Metadata-Version: 2.4
Name: agentboundary
Version: 0.2.0a1
Summary: Open spec and conformance suite for proving AI-initiated production actions
Project-URL: Homepage, https://github.com/jamjet-labs/agentboundary
Project-URL: Repository, https://github.com/jamjet-labs/agentboundary
Project-URL: Issues, https://github.com/jamjet-labs/agentboundary/issues
Author-email: JamJet Labs <sunil@jamjet.dev>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: action-receipts,agent,agent-action-control,agentboundary,ai-governance,ai-safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: jsonschema[format-nongpl]<5.0,>=4.21
Requires-Dist: pyyaml>=6.0
Requires-Dist: rfc8785>=0.1.4
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# AgentBoundary

> An open spec and conformance suite for proving AI-initiated production actions.

![AgentBoundary v0.1 conformance suite — 40 scenarios frozen (W10)](docs/assets/conformance-matrix.svg)

```bash
npx agentboundary run scenarios/
# or
uvx agentboundary run scenarios/
```

40 scenarios, 60 seconds, no signup, no Docker.

**v0.1** is the stable spec. **v0.2-alpha** (draft) adds three optional fields — `provenance`, `completeness_score`, `prior_receipt` — for self-honest emission reporting and singly-linked chain-of-custody. See [`docs/spec/v0.2-alpha.md`](docs/spec/v0.2-alpha.md).

## The problem AgentBoundary solves

Every agent framework can tell you *what an agent did*. None of them lets a third party — auditor, regulator, insurer, the team in the next building — verify *what the agent was allowed to do, by whom, against which policy, with which arguments, with what outcome*, without trusting the framework or model provider.

AgentBoundary defines an **Action Receipt**: a portable, tamper-evident JSON document emitted at the production action boundary (the moment an agent calls a tool that touches reality — merging a PR, refunding a charge, mutating a service). Receipts are content-addressed (`receipt_hash = sha256(canonical_json(receipt))`), bound to the arguments the agent actually executed against (`arguments_hash`), and reference the policy decision (allow / require-approval / deny / escalate) that authorized the action.

The conformance suite in this repo runs 40 deterministic scenarios — *every test is named for the failure it prevents* — and grades the receipts they emit against the v0.1 spec at Levels 1 through 4.

## What's in the receipt

```json
{
  "version": "agentboundary/v0.1",
  "receipt_id": "0192c8d0-1f2a-7c3e-bf2a-1a4d3f5e6c7b",
  "issued_at": "2026-06-15T14:23:08Z",
  "actor":  { "type": "agent", "id": "agent:claude-code:session/789abc", "display_name": "Claude Code" },
  "agent":  { "framework": "claude-code", "framework_version": "2.4.1", "model": "claude-opus-4-7", "model_version": "20260101" },
  "tool":   { "name": "github-mcp", "version": "0.7.0", "capability": "github.merge" },
  "target": { "system": "github.com/jamjet-labs/agentboundary", "environment": "prod", "resource_id": "pull/14" },
  "arguments_hash": "9698adaf2dca5f26a4f9644a8d0f4f34b5558bce09961f94e810fe3aaa9071aa",
  "policy": { "name": "agentboundary.repo.merges", "version": "2", "decision": "allow" },
  "execution": { "status": "success", "completed_at": "2026-06-15T14:23:09Z", "result_ref": "sha:b1c2d3e4f5a6" },
  "receipt_hash": "4d905d5dbc9faa4dafcb2155da9c4d5e1052cb23c680f3754d4ebc5800a4bae7"
}
```

This is `docs/receipts/github-merge.json` verbatim. The `receipt_hash` is the canonical SHA-256 of the body with `receipt_hash` excluded — recompute it yourself and the value matches.

## What's here today

- [`docs/spec/v0.1.md`](docs/spec/v0.1.md) — the v0.1 specification (definitions, lifecycle, receipt requirements, conformance levels, versioning)
- [`docs/spec/threat-model.md`](docs/spec/threat-model.md) — adversaries, threats, mitigations, and conformance-level mapping
- [`docs/spec/owasp-mapping.md`](docs/spec/owasp-mapping.md) — OWASP LLM Top 10 risks mapped to AgentBoundary conformance levels
- [`docs/schemas/action-receipt-v0.1.json`](docs/schemas/action-receipt-v0.1.json) — Action Receipt JSON Schema (normative source for receipt syntax)
- [`docs/schemas/action-receipt-v0.2-alpha.json`](docs/schemas/action-receipt-v0.2-alpha.json) — draft v0.2-alpha schema with optional `provenance` + `completeness_score` + `prior_receipt` fields
- [`docs/receipts/`](docs/receipts/README.md) — three worked example receipts (GitHub merge, Spring service mutation, Stripe refund); each one's `receipt_hash` verifies under the spec
- [`scenarios/`](scenarios/) — 40 deterministic conformance scenarios driven by `agentboundary run` (v0.1 spec freeze: lifecycle + adversarial + positive boundaries + v0.2-alpha extensions + canonical-JSON + environment + honest-failure paths)
- [`docs/spec/v0.2-alpha.md`](docs/spec/v0.2-alpha.md) — draft v0.2 delta: optional `provenance` + `completeness_score` + `prior_receipt` fields for self-honest emission reporting and singly-linked chain-of-custody
- [`adapters/`](adapters/) — translation layers from existing agent-governance products to AgentBoundary v0.2-alpha receipts (Microsoft AGT, Anthropic permission_policy, LangSmith Gateway, Cloudflare HITL); each adapter ships its own `mapping.md`, `results.md`, and smoke tests
- [`src/agentboundary/`](src/agentboundary/) — Python reference implementation (validator, hashing, runtime, CLI)
- [`npm/`](npm/) — thin Node wrapper that dispatches to `uvx`, `pipx`, or `python3 -m agentboundary`

## Comparison with other agent-governance products

![Cross-vendor conformance matrix — 40 scenarios × JamJet reference + Microsoft AGT, Anthropic permission_policy, LangSmith Gateway, Cloudflare HITL](docs/assets/comparative-matrix.svg)

Each vendor adapter in [`adapters/`](adapters/) translates that vendor's normative artifact (or, where there isn't one, the documented-recommended capture shape) into an AgentBoundary v0.2-alpha receipt, runs all 40 scenarios against the result, and records what survives. Per-vendor `results.md` files document every PASS / PARTIAL / DOCS-ONLY / NOT COVERED with structural reasoning. The data table that drives the matrix lives in [`scripts/generate-comparative-matrix.py`](scripts/generate-comparative-matrix.py); the SVG above is a deterministic function of that table.

The framing in the comparative report is that AGT and AgentBoundary are *closest peers* (both artifact formats); Cloudflare HITL is a workflow primitive (durable approval gates), not an emitted-artifact format; LangSmith is the richest observability platform but deliberately leaves the audit schema to team convention; Anthropic ships the most layered runtime permission primitive but does not publish a portable audit-log schema. Comparison reveals that none of the four exposes a single-artifact verification pattern a third party can run without trusting the vendor's runtime — which is the gap this spec fills.

**Read the full report:**
- [`jamjet.dev/blog/agent-action-control-40-tests`](https://jamjet.dev/blog/agent-action-control-40-tests/) — long-form write-up
- [`agentboundary.jamjet.dev/reports/2026-05-comparative`](https://agentboundary.jamjet.dev/reports/2026-05-comparative/) — canonical report archive

## Run the tests

```bash
pip install hatch
hatch test
```

155 fast tests cover the schema loader, validator, hashing, conformance checks (Levels 1-4 including v0.2-alpha completeness + chain integrity), runtime, scenarios loader, and CLI. 8 additional slow tests verify the published wheel behaves correctly under a clean install.

## License

Apache 2.0 — see [LICENSE](LICENSE).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). All commits require DCO sign-off (`git commit -s`).

The spec is open. Implementations welcome.
