agent-action-capsule (reference library)

The reference implementation of the Agent Action Capsule profile: parse and seal a Capsule, and run the Class 1 verifier defined in the Internet-Draft (../spec/). Published to PyPI as agent-action-capsule.

The spec (../spec/) is the source of truth. Where the draft says MUST / MUST NOT, the code and tests enforce it, section by section.

Quickstart (30 seconds)

Install the payload-only core (stdlib only — zero required dependencies):

pip install agent-action-capsule        # from a checkout: cd python && pip install .

Verify a conformant capsule — point at a shipped positive vector:

$ agent-action-capsule verify ../test-vectors/pos-executed-confirmed/input.json
Agent Action Capsule — Class-1 payload verification: ../test-vectors/pos-executed-confirmed/input.json
  ok: True
  capsule_id (recomputed): 5b7c4ff1bcf4364e0dd8c8b65eddddbb1d6102f27bed3ad1a3595cba51d3502a
  derived: effect_mode=confirmed attestation_mode=self_attested ledger_mode=standalone
  findings: none
# exit code 0

Verify a failing capsule — the finding is self-explaining, with its §6 check number:

$ agent-action-capsule verify ../test-vectors/neg-confirmed-without-response/input.json
  ok: False
  ...
  findings:
    - [error] (check 3) confirmed_without_response: effect.status 'confirmed' requires a 64-hex response_digest (§5.2)
# exit code 1  (0 = ok, 1 = not ok, 2 = could not run / malformed input)

Add --json for the raw VerificationResult, or --store <dir-or-ledger-file> for store-level chain checks (supersedes / concurrent-supersedes / open-items).

The two layers

Verification is two layers, and this package is honest about which it does:

To verify both layers of a SCITT Signed Statement, install the optional extra and pass --transparent:

pip install 'agent-action-capsule[transparent]'     # adds the public scitt-cose verifier

agent-action-capsule verify --transparent statement.cose --issuer-key issuer_pub.pem [--log-key log_pub.pem --leaf-entry-hex <hex>]

  substrate (SCITT/COSE, via scitt-cose):
    signature_verified : True
    receipt_verified   : True
    attestation_tier   : anchored        # 'anchored' ONLY when a receipt actually verified (§3.2)
  payload (Agent Action Capsule, Class-1):
  ok: True

Without a verified receipt the substrate tier is self_attested, never anchored. The optional extra is public (scitt-cose, deps cbor2 + cryptography); the default install pulls nothing extra.

Build → verify (producer side)

../examples/build_and_verify.py is the smallest honest round trip: construct a capsule with the typed builders, seal() it (compute capsule_id), then verify() it — an executed action and a blocked one, in ~40 lines.

Conformance vectors

../test-vectors/ is the frozen conformance suite a second implementer runs against their own verifier: each input.json plus its spec-anchored expected.json (ok, the §6 check numbers + severities, the derived modes, the recomputed capsule_id). See ../spec/section-map.md for the spec section map.

What it implements

from agent_action_capsule import verify, Capsule, EffectRecord, Disposition, AssuranceBlock

capsule = Capsule(
    spec_version="draft-mih-scitt-agent-action-capsule-00", format_version="2",
    action_id="po-12345", action_type="decide", operator="ACME-CO", developer="agent@v1",
    timestamp="2026-06-13T00:00:00Z",
    effect=EffectRecord(status="confirmed", type="write_order",
                        response_digest="a"*64, effect_attestation="gate_executed"),
    assurance=AssuranceBlock(attestation_mode="self_attested", effect_mode="confirmed",
                             ledger_mode="standalone"),
    disposition=Disposition(decision="accept", approver="human", human_disposed=True,
                            verdict_class="executed"),
).seal()

result = verify(capsule)        # never throws
assert result.ok               # a single `ok` gates trust in every other field

Scope boundary (deliberate)

Does — the Class 1 agent-profile surface (§6), performable from the Capsule's own bytes plus the registry contents (and, for chain checks, the producer's store of Capsules).

Does NOT —

• Substrate verification. The COSE_Sign1 signature, registration, and the Receipt's inclusion proof are the SCITT/COSE substrate's, by reference (scitt-cose). This package never derives anchored; a claimed anchored mode is reported as an unverifiable overclaim (§5.3).
• Class 2 / manifest-aware verification (§8.2). Constraint Records are represented as data (§8.1) but no manifest is fetched and no evidence-schema check is performed.

Develop / test

cd python
pip install -e ".[dev]"
python -m pytest -q        # positive + negative (MUST-reject) suite
python -m ruff check .

The test suite is the conformance contract: every MUST / MUST NOT in the implemented sections has a positive and a negative case, and the frozen byte-level vectors under ../test-vectors/ are replayed through verify() / verify_store(). The two-layer (--transparent) tests run only when the optional [transparent] extra is installed, and skip cleanly otherwise.