signed-agent-receipts 0.1.0

Local agent run receipts with signed JSONL records and Markdown review artifacts.

signed-agent-receipts

signed-agent-receipts is a small local POC for signed Agent Run Ledger receipts plus a Computer-Use QA Pack. It scans local agent runtime traces when present, normalizes them into versioned JSONL records, signs them with Ed25519, and renders Markdown receipts that a human can review without reading a full transcript.

Durable generated outputs default to a neutral local config path:

~/.config/signed-agent-receipts/output

Commands

Requires Python 3.10+.

Install locally:

python -m pip install .
# or
pipx install .

Packaging note: the PyPI distribution and installed CLI command are signed-agent-receipts; the Python import package remains agent_receipts for stable module imports.

Normalize recent local runs:

signed-agent-receipts normalize --limit 10

Render Markdown receipts:

signed-agent-receipts render --jsonl ~/.config/signed-agent-receipts/output/agent_run.jsonl

Run the end-to-end POC:

signed-agent-receipts dogfood --limit 10

Verify signed JSONL receipts:

signed-agent-receipts verify --jsonl ~/.config/signed-agent-receipts/output/agent_run.jsonl

Run tests:

python -m unittest

What It Scans

The normalizers are heuristic and defensive. Missing or unreadable sources are skipped or represented as warning records instead of crashing.

• Hermes: ~/.hermes, including readable SQLite, JSON/JSONL, and log/text files.
• Codex: ~/.codex.
• Claude Code: ~/.claude/projects.

For tests or local fixture runs, set:

AGENT_RECEIPTS_HOME=/tmp/fixture-home
AGENT_RECEIPTS_WORKSPACE=/tmp/fixture-workspace

Analytics

The CLI is instrument-ready for PostHog without adding a runtime dependency. Set a project-scoped key to enable capture; leave it unset for a complete no-op:

POSTHOG_KEY=phc_... python -m agent_receipts dogfood
# Optional; defaults to https://us.i.posthog.com
POSTHOG_HOST=https://us.i.posthog.com

Emitted events currently include agent_receipts_cli_started, agent_receipts_normalized, agent_receipts_rendered, and agent_receipts_dogfood_completed.

Signing

Every JSONL receipt written by the CLI is signed with Ed25519 over canonical JSON: UTF-8 JSON with sorted keys and compact separators, excluding the signature field itself. Markdown receipts include the same signature metadata in a Signature section.

The default private key path is:

~/.config/signed-agent-receipts/ed25519_private.pem

The key is created automatically with 0600 permissions on first use. Override the path with either --signing-key /path/to/ed25519_private.pem or AGENT_RECEIPTS_SIGNING_KEY=/path/to/ed25519_private.pem. Local private-key filenames are gitignored by default; do not commit private keys.

Schema Summary

Records are JSONL objects using schema_version: agent-run-ledger.v1. The schema lives at schema/agent_run.schema.json and includes:

• identity: run ID, runtime, source path, actor, profile, session, title
• timing: started, ended, duration
• normalized content: inputs, tool calls, file diffs, URLs
• QA support: evidence with local file hashes when available, costs, policy flags
• traceability: receipt path and raw source references
• signature: Ed25519 public key, key ID, canonicalization, and signature value

Evidence

The POC discovers recent local image files only from causally scoped roots such as the workspace and output directory, computes SHA-256 for local evidence, and records provenance for every evidence item. Shared caches such as ~/.hermes/cache/screenshots are not backfilled into unrelated runs; time-window matches are marked as heuristic.

Current Limitations

• Source formats are inferred, not runtime-specific contracts.
• SQLite support samples likely session/run/log tables but does not understand every vendor schema.
• Cost and token data are only populated when present in source traces.
• Markdown receipts are static review artifacts; they do not provide approval workflow state.
• JSON Schema validation is documented but not enforced at runtime.