Agent Black Box

Agent Black Box gives agent and CLI developers a local, tamper-evident account of what ran and when without retaining prompts, arguments, stdout, or stderr. It is useful when you need a reviewable execution timeline, incident-recovery trail, or OpenTelemetry-compatible handoff but cannot send sensitive content to a hosted tracing service.

Published on npm as @shakebenn/agent-black-box under the MIT License. It has no runtime dependencies and performs no network export.

Shortest path

The packaged CLI supports Node.js 20 or newer and has no runtime dependencies.

pnpm add --global @shakebenn/agent-black-box
abb capture --trace ./trace.jsonl -- git status --short
abb timeline --trace ./trace.jsonl

npm install --global @shakebenn/agent-black-box is the npm equivalent.

Repository development requires Node.js 22.13 or newer because the pinned pnpm 11.0.8 toolchain has that higher engine floor. If corepack is unavailable but pnpm 11.0.8 is already installed, skip the corepack enable line.

git clone https://github.com/Kota-Ohno/agent-black-box-oss.git
cd agent-black-box-oss
corepack enable
pnpm install --frozen-lockfile --ignore-scripts
pnpm abb capture --trace ./source-trace.jsonl -- git status --short
pnpm abb timeline --trace ./source-trace.jsonl

The capture records bounded metadata and hashes, not the command arguments or output. The trace remains on your machine.

Everyday workflows

# Repair only an interrupted final record, then verify the intact chain.
abb recover --trace ./trace.jsonl

# Preview a replay plan. This never executes the captured command.
abb replay --trace ./trace.jsonl

# Anchor the current head and create a local OTLP JSON projection.
cp ./trace.jsonl.head.json ./trusted-head.json
abb export-otlp --trace ./trace.jsonl --trusted-head ./trusted-head.json --output ./otlp.json

# Fingerprint an existing JSONL stream without retaining its content.
abb ingest --trace ./trace.jsonl ./source.jsonl

Move the copied head to an independent protected channel before relying on it as a future anchor. Re-copying a head from a trace already under investigation does not establish that the trace is authentic.

Role in the ecosystem

Agent Black Box is the execution-observation layer. It emits a privacy-bounded hash chain that Sol Ledger Protocol can validate. Evidence Forge is the separate evidence-promotion layer; a trace event is not verified Evidence. The Ecosystem Acceptance Kit checks the pinned products together. See ecosystem compatibility.

Safety limits

• Hashes prove consistency against a separately retained trusted head; they do not prove that the original event was truthful or independently timestamped.
• abb recover is for interrupted tails, not arbitrary history repair.
• Replay is deliberately dry-run only, and OTLP export never sends data over the network.
• Protect trace files and trusted heads as local private data. Review the full privacy decision and recovery guide.

The package allowlist contains the CLI, runtime library, README, and MIT license; it excludes test fixtures, captured traces, and build output. See the roadmap for delivery status.

Principles

• Raw prompts, tool arguments, tool results, argv, stdout, and stderr are never stored.
• The only supported content modes are metadata_only and hash_only; there is no raw-content opt-in.
• Trace files are append-only JSONL hash chains.
• Writers are serialized by an ownership-tracked lock; durable head receipts are replaced atomically.
• abb recover truncates only an interrupted final record after verifying the intact prefix.
• Replay is a dry run and never executes commands.
• Trace and span identifiers are OpenTelemetry-compatible.
• OTLP export only writes local JSON and a receipt; it contains no SDK or network transport.

This privacy boundary is the completed product policy, not a temporary default. See the privacy decision for its guarantees and change gate.

Security

Run pnpm audit:secrets with Gitleaks installed before preparing a release. Report suspected vulnerabilities privately as described in SECURITY.md; do not attach real prompts, tool output, traces, or credentials.

Contributions are welcome under the privacy and verification requirements in CONTRIBUTING.md.

License

MIT