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. See RELEASING.md for the release workflow and PyPI Trusted Publisher setup.

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 ../vectors/capsule/pos-executed-confirmed/input.json
Agent Action Capsule — Class-1 payload verification: ../vectors/capsule/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 ../vectors/capsule/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:

The current AAC Producer Envelope is separate from an RFC 9943 Signed Statement: it signs the raw 32-byte Capsule ID with exactly three protected headers and does not carry RFC 9943's required CWT claims. Install agent-action-capsule[envelope] and call verify_producer_envelope(capsule_id, envelope_bytes) to verify that profile. The function returns the authenticated public key; it does not decide whether the key is authorized for an operator or developer.

from agent_action_capsule.producer_envelope import verify_producer_envelope

To verify an Evidence Bundle's interval coverage and per-record membership (agent_action_capsule.bundle.verify_bundle), install the bundle extra. It adds the public CLL reference that checks the MMR proofs:

pip install 'agent-action-capsule[bundle]'

Without it those two claims fail closed as completeness_verifier_unavailable. That finding means this installation could not check the proofs. It does not mean the certificate is invalid.

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>]

For an RFC 9943 Capsule-ID registration statement, this command authenticates and prints the raw Capsule ID. Class-1 verification of the Capsule JSON is a separate operation. For a JSON-bearing Signed Statement, it also runs Class-1 verification over the authenticated payload.

  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

../vectors/capsule/ 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-05", format_version="4",
    canonicalization_id="jcs",
    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

Cross-record references (references[], §5.5.5)

chain is exclusively a Capsule's own same-stream parent. references cites everything else — a different producer's Capsule, or any other artifact this action targeted or responded to. Absent and an explicit empty array are semantically the same ("no such citation") but are distinct bytes, so they produce different capsule_id digests — pass references=() only when that distinction matters to a caller:

from agent_action_capsule import Capsule, ReferenceEntry, LogCoordinates

capsule = Capsule(
    spec_version="draft-mih-scitt-agent-action-capsule-05", format_version="4",
    canonicalization_id="jcs",
    action_id="deny-42", action_type="decide", operator="ACME-CO", developer="agent@v1",
    timestamp="2026-09-08T00:00:00Z",
    references=(
        ReferenceEntry(
            type="agent-action-capsule", digest_alg="SHA-256",
            digest="b" * 64,                    # the cited Capsule's capsule_id
            citation_purpose="responds_to",      # or "acted_on"; §12 citation_purpose registry
        ),
        ReferenceEntry(
            type="foreign-artifact", digest_alg="future-hash", digest="opaque-digest",
            log_coordinates=LogCoordinates(log_id="example-log", leaf_index=3, inclusion_proof={...}),
        ),
    ),
).seal()

capsule["references"]  # [{"type": ..., "digest_alg": ..., "digest": ..., "citation_purpose": ...}, {...}]

A references entry MUST NOT duplicate chain.parent_capsule_id — citing the producer's own same-stream parent is stated once, in chain, never redundantly in references (Capsule(...) raises InvariantError if it does). Only the agent-action-capsule/SHA-256 self-identity context constrains digest to 64-lowercase-hex; every other type/digest_alg combination is CPB's to define and stays open. log_coordinates, when present, is an upgrade (not a second identity) and its inclusion_proof is never independently verified by Class 1.

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 ../vectors/capsule/ are replayed through verify() / verify_store(). The two-layer (--transparent) tests run only when the optional [transparent] extra is installed, and skip cleanly otherwise.