OpenWorkProof

# OpenWorkProof

> OpenWorkProof is an open protocol for AI agent work contracts and verifiable execution. It answers the question MCP and A2A leave open: under what authority does an agent work, and on what evidence is its result accepted?

## How It Works

Four signed protocol objects bound into a single verifiable history:

- **WorkOrder** — frozen work contract (target paths, tools, quotas, acceptance conditions)
- **CapabilityGrant** — attenuating authority: child grants can only shrink, never expand (No-Cloning Authority)
- **ActionReceipt** — per-action signed evidence with bound authorization decision, quota delta, and evidence references
- **AcceptanceReceipt** — final acceptance or rejection, one of two mutually exclusive terminal states

Six roles (each with independent Ed25519 keys): Maintainer, Manager, Developer, Verifier, Sidecar, Acceptor. The Acceptor role's key is bound in the WorkOrder and can be assigned to the Owner or any authorized party — no mandatory independent natural person.

State machine: `running → locally_verified → proof_ready → awaiting_human → accepted | rejected`

Core principles: Proof-Carrying Work, No-Cloning Authority, Multi-Scale Proof Composition, Fail Closed, and offline third-party audit via `validate_grant_chain`.

## Current Status

**v0.1.0 in active development. 2,283 tests passed, 0 failed, 7 skipped.**

What's implemented and verified:
- Four protocol object models with strict RFC 8785 JCS normalization and Ed25519 signing
- SQLite authoritative ledger with atomic grant issuance/revocation, quota replay, and crash recovery
- Pure pre-authorization: tool call / human decision / rollback three PolicyDecision paths
- Causality replay layer + policy replay layer + five-input offline acceptance bundle verifier
- Atomic acceptance and rejection (mutually exclusive terminal states, tamper-evident)
- `produce_deny_receipt` — immutable audit record for denied requests
- CLI (`owp status / run-tests / repo-read`), MCP stdio transport server, AgentTeams TCP network client
- Docker production executor with STARTED_UNCONFIRMED crash recovery
- Supply-chain verifiable build pipeline (docker + OCI archives, candidate inventory)

Two end-to-end demos across the full nine-step five-role evidence chain, each verified with real external Acceptor subprocess TCP signing + offline bundle verification:

1. **M2 — Rich #4196** (developer tool): NBSP line-breaking bug in Textualize/rich, fixed at commit `9d8f9a3`
2. **M3 — Dify #33013** (AI application platform): TypeError crash in QuestionClassifierNode when `structured_output_schema` was not updated for v1.14.0-rc1 API change, fixed at commit `9f7bea37`

Key remaining: other ToolCall handler closures with evidence publication, competition submission.

OpenWorkProof does not make agents smarter; it gives them the accountability structure needed for deployment in production — work that can be authorized, constrained, verified, accepted, and rejected when evidence is insufficient.

## Documentation

- [README](https://github.com/dengyier/OpenWorkProof/blob/main/README.md): Full overview with usage guide (CLI / MCP / Python API / external Acceptor / AgentTeams), value proposition, and implementation status
- [Protocol Schemas](https://github.com/dengyier/OpenWorkProof/tree/main/specs/v0.1): Authoritative JSON Schemas for WorkOrder, CapabilityGrant, ActionReceipt, and AcceptanceReceipt
- [Offline Verification](https://github.com/dengyier/OpenWorkProof/blob/main/docs/offline-verification.md): How third parties verify the full signed authorization history without connecting to either party's systems
- [Status](https://github.com/dengyier/OpenWorkProof/blob/main/docs/status.md): Detailed implementation checklist and boundary declarations
- [Rich #4196 Demo Log](https://github.com/dengyier/OpenWorkProof/blob/main/docs/superpowers/2026-08-07-rich-4196-demo-log.md)
- [Dify #33013 Demo Log](https://github.com/dengyier/OpenWorkProof/blob/main/docs/superpowers/2026-08-07-dify-33013-demo-log.md)
- [Competition Materials](https://github.com/dengyier/OpenWorkProof/tree/main/docs/competition): Agent identity, skill list, and intro for World AI Open Source Competition (Agent Infra track)

## Source

- [models.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/models.py): Four protocol object models with strict JSON/byte-boundary validation and frozen immutability
- [policy.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/policy.py): Policy replay and pure pre-authorization (authorize_tool_call, validate_human_decision, validate_rollback, validate_grant_chain)
- [evidence.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/evidence.py): SQLite authoritative ledger, atomic grant issuance/revocation, evidence staging and publication with crash recovery
- [composition.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/composition.py): Causality replay layer reconstructing immutable causal snapshots per receipt
- [acceptance.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/acceptance.py): Terminal acceptance/rejection transactions and offline acceptance bundle verifier
- [mcp_server.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/mcp_server.py): Coordinator — complete_receipt_publication, compose_proof, execute_repo_read, produce_deny_receipt
- [signing.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/signing.py): Ed25519 signing with RFC 8785 JCS canonical JSON normalization
- [predicates.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/predicates.py): Predicate registry — path_allowed, tool_allowed, quota_remaining, and select_required_predicates
- [repo_tools.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/repo_tools.py): Repository pipeline tools (CandidateReadRequest, resolve/render workspace)
- [cli.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/cli.py): CLI transport — `owp status`, `owp run-tests`, `owp repo-read`
- [mcp_transport.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/mcp_transport.py): MCP stdio transport server (tools: owp_status, owp_run_tests, owp_repo_read)
- [execution_adapter.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/execution_adapter.py): AgentTeams execution adapter with team-to-developer task dispatch loop
- [team_network_client.py](https://github.com/dengyier/OpenWorkProof/blob/main/src/openworkproof/team_network_client.py): TCP network client implementing AgentTeamClient protocol with auth, retry, and reconnect

## Optional

- [pyproject.toml](https://github.com/dengyier/OpenWorkProof/blob/main/pyproject.toml): Packaging metadata and dependencies (Python >=3.12, <3.13)
- [tests](https://github.com/dengyier/OpenWorkProof/tree/main/tests): 2,283-test conformance suite covering protocol models, policy replay, receipt chains, acceptance, sandbox recovery, supply chain, and end-to-end demos (M1/M2/M3)
- [supply-chain](https://github.com/dengyier/OpenWorkProof/tree/main/supply-chain): Verifiable build images (docker + OCI) and candidate inventory for reproducible execution