atrib
Verifiable agent actions. Every action becomes signed context for the next.
atrib signs agent actions as records that later agents, teams, and verifiers can check. A record can describe a tool call, browser click, desktop action, policy decision, handoff, transaction, or intentional note from the agent.
Agent work already crosses tools, memory, identity, authorization, observability, evals, handoffs, and payment rails. atrib does not replace those systems. It gives them a common record that carries the action, selected evidence, and graph links across sessions, agents, teams, organizations, and protocols.
Product teams can put atrib in the execution path. A harness can sign an allow, block, or escalate decision before a high-impact browser click, desktop action, support reply, admin change, deployment, or payment-impacting step. The outcome then becomes signed context for later recall, review, handoff, or verification.
Browser and computer-use agents make the product concrete. Follow-up work can cite the decision and outcome without exposing raw browser state, desktop state, private tool payloads, or full runtime logs in public records.
Shared memory and context systems still decide what an agent should remember. Observability tools still inspect live runs. Authorization systems still issue policy and credentials. atrib signs the action trail so those systems can carry forward the same verifiable facts without trusting the runtime that stored them.
What this enables
Everything below depends on one substrate property: an action is signed when it happens and remains verifiable later.
Substrate vs harness
atrib is the substrate underneath the action layer. Consuming it well (surfacing an agent's history at session start, exposing recall tools the agent can call, persisting signed records locally for replay, and putting policy gates around high-impact actions) is the job of an agent harness or runtime. atrib does not prescribe a harness. The substrate is independently useful to any harness (Claude Code, Cursor, custom agent products, in-house agent runtimes) that wants to give agents and teams contextual awareness, coordination, control, and proof over work the agent performs.
Hard boundary: the public Merkle log proves a commitment, but it is not enough context for a future agent to continue the work. A continuation agent needs Tier 2 and Tier 3 material: canonical record bodies or archive references, redacted evidence references, skill pack identities and hashes, the latest chain tail, parent dispatch anchors for subagent work, and provenance anchors. Without those, it can prove a record existed but still has to guess what happened.
One canonical harness pattern is signed diagnostic outcome + trace replay: sign the action, sign the diagnostic outcome that evaluates it with informed_by back to the action, then let the next repair step walk informed_by back from the diagnostic record with recall. This keeps "what happened" and "what it supersedes" in one verifiable path without requiring a whole-session transcript dump.
Derived evidence products sit above the protocol. A harness can build a prior-work packet, suspect report, or eval summary from signed records, body commitments, verifier checks, and inclusion proofs. Those products can decide which records are useful for a task, which stale records to avoid, and which risks remain open. They do not change the record format, the graph derivation rules, or the attest/recall verb surface.
Logs and traces
Logs and traces are primary integration inputs for atrib, but the word "trace" can point at several different objects. The boundary matters.
The short rule: observability tools inspect and debug live traces; runtime systems own logs that reconstruct or resume a run; atrib signs actions and verifies claims over selected windows. Those layers compose, but they should not collapse into one product.
Frameworks and host runtimes
The "any agent framework" claim is about tool-call middleware, not every host
runtime feature. It covers SDK and MCP surfaces where application code owns the
agent loop: raw MCP SDK, Claude Agent SDK, Cloudflare Agents, Vercel AI SDK,
LangChain JS, and similar SDKs. Those integrations live in
@atrib/agent,
@atrib/mcp, and
@atrib/mcp-wrap.
Host runtime adapters cover a different shell: Claude Code, Codex, OpenClaw,
Hermes, Cursor, Goose, hosted runtimes, or another harness that owns sessions,
lifecycle hooks, approvals, subagents, checkpoints, telemetry, and run logs.
Those adapters use @atrib/mcp-wrap for MCP
tool calls, host-specific signing code for native tool hooks,
@atrib/openinference for
OpenInference-shaped span intake,
@atrib/runtime-log for bounded run windows,
@atrib/action-gate for pre-action policy
gates, @atrib/verify for accepted handoff claims,
and atrib-attest-cli (or the forwarded atrib-emit-cli) or the local substrate for hook-class observations.
The implementation rule: one host event has one signing owner. If an MCP wrapper
already signs a tool call, the host adapter should correlate ids and skip a
second tool_call record. The private integration package pins this rule in
packages/integration/src/host-runtime-proof.ts
so future OpenClaw, Hermes, and other host proofs share the same vocabulary.
Stateless MCP attribution
Add verifiable records to a tool call without adopting a new agent runtime or
maintaining an atrib transport session. A native server can advertise
dev.atrib/attribution; an existing server can sit behind @atrib/mcp-wrap;
and the TypeScript and Python SDKs carry the complete request envelope
automatically. The tool result can include a signed receipt that a verifier
checks without trusting any single log operator.
The stateless MCP attribution guide shows the request, result, receipt, integration choices, runnable proofs, retry rules, and the boundary between proof of a signed claim and proof that the claim is true.
How it works
- Each record is signed by the actor's Ed25519 key and JCS-canonicalized
- A Merkle log stores commitments (hashes, not content) with RFC 6962 inclusion proofs and C2SP-canonical signed-note checkpoints
- Nine deterministic edge types connect actions into one graph with two reading
planes: chronology edges (
CHAIN_PRECEDES,SESSION_PRECEDES,SESSION_PARALLEL,CROSS_SESSION,CONVERGES_ON) and declared-relationship edges (INFORMED_BY,PROVENANCE_OF,ANNOTATES,REVISES) - The explorer's primary trace path composes
/v1/traceand/v1/chainfor readability without adding a new graph edge, validity rule, or settlement input (D118) - A pure-function calculation maps graph + policy to value distribution when commerce closes
- A public-key directory (§6) resolves opaque keys to identity claims; rotation and revocation are normative (§1.9); identity claims may declare capability envelopes (§6.7) that verifiers check records against
- Transaction records require cross-attestation: at least 2 distinct verified signer keys (agent + counterparty) per §1.7.6
- Cross-log replication (§2.11) lets consumers submit records to multiple independent logs and detect equivocation
- Privacy is configurable per record (§8 privacy postures): tool_name forms (verbatim, opaque, hashed), commitment schemes (plain, salted-sha256, hmac-sha256), timestamp granularity (ms through day)
- Adversarial threat model (§8.7) enumerates the 10-layer trust assessment stack the substrate provides
No custom cryptography. No content exposure unless the harness opts in. No trust required.
Try the demo
One command, no setup beyond cloning. Generates a fresh key, spins up an in-process Merkle log, fake merchant, and fake agent, runs two tool calls plus one transaction, and prints what landed in the log.
ATRIB_PRIVATE_KEY=$(node -e 'console.log(Buffer.from(crypto.randomBytes(32)).toString("base64url"))') \
pnpm --filter @atrib/integration demo
Expected output:
[demo] starting dev log...
[demo] dev log running at http://127.0.0.1:58958
[demo] starting merchant tool server (fake search API)...
[demo] starting agent client...
[demo] agent connected to merchant
[demo] step 1: agent calls 'search' for the first time (genesis)
[log] +tool_call ctx=7f71199d… chain=sha256:064692c27… idx=0
[demo] step 2: agent calls 'search' again (chained from step 1)
[log] +tool_call ctx=7f71199d… chain=sha256:381c22ac6… idx=1
[demo] step 3: agent observes a fake x402 payment receipt
[log] +transaction ctx=7f71199d… chain=sha256:96ac3e962… idx=2
[demo] final state
[demo] 3 records in the log
[demo] 2 tool_call records
[demo] 1 transaction record
[demo] chain length: 3
[demo] done.
The signatures, chain hashes, and transaction detection are production code. Only the surrounding environment (merchant, agent, network) is stubbed.
Quick start
Node.js consumers need Node 22 or newer. See the canonicalization compatibility notes when upgrading from canonicalize 4.
Now that you've seen the demo, pick the install path that matches what you're doing:
- Sign tool calls your MCP server handles:
@atrib/mcp(below) - Sign tool calls your agent makes:
@atrib/agent(below) - Gate high-impact actions before they run:
@atrib/action-gate - Attach signed records to an existing OpenInference span stream:
@atrib/openinference - Prove a bounded run window from a host-owned runtime log:
@atrib/runtime-log - Verify records someone else produced:
@atrib/verify(below)
Sign tool calls (your MCP server)
import { atrib } from '@atrib/mcp'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
const server = atrib(new McpServer({ name: 'my-tool', version: '1.0.0' }), {
creatorKey: process.env.ATRIB_PRIVATE_KEY,
serverUrl: 'https://my-tool.example.com',
})
One line. Every successful tool call emits a signed attribution record, propagates W3C trace context, and submits to the log asynchronously.
Sign tool calls (your agent)
@atrib/agent exports one interceptor plus a helper
per framework; side-by-side quick-starts live in its README. Every runnable
example and proof, one per framework or runtime surface, is cataloged in
Examples and proofs below.
Verify records (any third party)
import { AtribVerifier } from '@atrib/verify'
const verifier = new AtribVerifier({
merchantKey: process.env.ATRIB_MERCHANT_KEY,
})
const result = await verifier.verify(recommendationDoc)
// { valid: true, signatureOk: true, calcMatch: true, distribution: {...} }
Verification re-runs the payments profile §8 calculation locally and compares the result. No trust in any intermediary.
What atrib certifies, what it does not
atrib certifies five verifiable axes of agent activity: who acted (identity), what they did (event_type), when (timestamp), what came before what in the chronology plane, and what the signer claimed informed, anchored, annotated, or revised the action in the declared-relationship plane.
atrib does NOT certify that the agent's reasoning is truthful, that prior records actually influenced subsequent decisions, or that tool responses were real absent tool-side attestation. A signature proves who committed to a claim, never that the claim is true. The first two limits are intrinsic to signed claims. The third narrows when another party signs its own evidence: the tool signs its response, a counterparty co-signs a transaction, an evaluator signs a diagnostic, or a witness attests the outcome. Those signatures corroborate the action, not the agent's reasoning. The substrate is content-preserving (commitments, not content) and disclosure-configurable: harnesses pick how much each record reveals via the privacy postures in spec §8.
This positioning keeps the claim honest. See spec §3 "What atrib chains, what it does not" for the detailed enumeration and spec §7.6 for the outcome-verification patterns that close the tool-response gap.
Framework support
This table covers framework tool-call middleware, not full host runtime integration. Host runtime work has its own boundary in Architecture and in the OpenClaw/Hermes map.
Examples and proofs
Each row is a runnable example or a pinned proof artifact under
packages/integration/examples/ (proof
packets under proof-packets/). Start with the row matching
your stack.
Payment-related completion detection
atrib detects transaction events from six payment-related completion cases. It
does not implement payment methods, move money, or enforce transactions. The
per-surface hooks are defined by the atrib Payments Profile,
which versions independently of the core spec (D147);
core keeps the transaction event type, the cross-attestation rule, and the
evidence envelope. The public packages provide runtime observation and
verification of supplied evidence, not a payment client or protocol-wide
market measurement system.
x401 is intentionally not in this table. It is a 401 proof-requirement
protocol for credential-gated HTTP routes, so
@atrib/verify treats x401 artifacts as
authorization evidence rather than transaction signals. The current Proof
issue and PR map lives in docs/proof-x401-open-threads.md.
Packages
Current packages come first. The deprecated legacy packages follow: all are re-export shims whose tool names stay mounted as permanent aliases per D164. Private workspace packages that never publish close the list.
Current packages
Deprecated legacy packages
All five are deprecated on npm and remain installable. Their tool names stay mounted as permanent aliases, so existing configurations keep working and signed records are byte-identical either way.
Private workspace packages
Fixtures, test harnesses, and superseded local runtimes. Marked private: true; never published.
The twenty designed-public packages split fifteen current and five deprecated;
the public-package tables above are the canonical list. Private application and
test packages do not change that count. The python/
directory ships the atrib Python SDK (published on PyPI), the first
non-TypeScript implementation of the
§1 record layer, held
byte-identical to the TypeScript implementation by the shared conformance
corpora and a cross-implementation determinism harness.
Open-source operating graph
apps/operating-graph/ is a complete inspectable
application over the protocol. It verifies local mirror records and presents
named, bounded workspace, task, team, and agent views with body-aware search,
live decisions and outcomes, incoming handoffs that expose prior task state,
and explicit state conflicts. The reader verifies each private application body
against the signed record's args_hash before projection.
The application never chooses a conflict winner from time or signer preference.
A resolution is accepted only when its signed record cites every active head
through informed_by and its private body names the selected head. Local,
container, fresh-machine, and application-conformance instructions ship with
the client.
Its revision stream carries exact event IDs and reports missed local projection revisions as gaps that require a bounded-view reload. Full signed-body and opening disclosure is disabled by default. Operators can enable a separate bearer-protected route that re-verifies local or archived record bodies and tests available content, tool-name, argument, and result openings against the signed commitments.
The application also exposes signed runtime observations in a separate, bounded feed. The source-neutral D183 path verifies a portable batch and commits its complete artifact, signed observation, and authoritative cursor in one caller-owned journal update. The observation does not create accepted state or other semantic events. A later application event must cite the atrib-signature-verified observation and match its named scope before it enters an operating view.
The runnable open composition uses the Codex rollout profile, a separate host mapping, a bounded view receipt, paired SDK action records, signed D168 membership, and an independent selected-effect verdict. It is a deterministic local fixture, not evidence of a live external session or deployed product. Buzz runtime-window observations use the same non-semantic application lane. Their later reader verifies the atrib signature and body commitment; it cannot replay absent Buzz frames or manifests.
This is an application profile, not a new protocol surface. It demonstrates usable shared state while keeping names, values, and resolution policy outside the public record format.
Status
Four public services are deployed today: services/log-node/ (service README, https://log.atrib.dev/v1), services/graph-node/ (service README, https://graph.atrib.dev/v1), services/directory-node/ (service README, https://directory.atrib.dev/v6), and services/archive-node/ (https://archive.atrib.dev/v1). The public explorer at https://explore.atrib.dev/ composes their read APIs into a public reference surface, and a 13-gate end-to-end verifier runs daily in CI against the deployed log.
The record layer, transparency log, graph, key directory, payments profile, and
verifier evidence checks are implemented, deployed, and pinned by conformance
corpora. services/witness-node/ is an
external-operator-ready witness reference that verifies pinned log checkpoints,
detects historical rewrites, and publishes C2SP cosignatures. The deployment
kit includes an image publication workflow, Compose and Fly templates, offline
backup verification, scheduled monitoring, signed retirement, and an
endpoint-aware verifier that binds fetched cosignatures to caller-pinned
witness keys and endpoints. Its software path has been exercised locally
against log.atrib.dev; no independently operated witness is deployed yet. The
independent operator guide supplies the
deployment and acceptance contract. Multi-log replication also remains
undeployed. The full enumeration, with spec and decision references, is in
STATUS.md.
Key generation
node -e 'console.log(Buffer.from(crypto.randomBytes(32)).toString("base64url"))'
Store the output as ATRIB_PRIVATE_KEY. The public key is derived at runtime.
Specification
atrib-spec.md covers:
- §0: Foundations
- §1: Attribution record format, signing, propagation, transaction event boundary
- §1.9: Key rotation and revocation (D033)
- §2: Merkle log protocol (C2SP tlog-tiles, proofs, witnessing)
- §3: Graph query interface (nine edge types)
- §4: Position of the policy layer; the policy format, negotiation, and calculation live in the payments profile (D147)
- §5: SDK contract, automation, degradation guarantees
- §6: Public-key directory (AKD-based; D034)
- §7: Harness integration patterns (informative)
- §8: Privacy postures (D045; per-record disclosure dials)
- §9: Runtime integration patterns (informative; seven peer patterns per D069 and D102)
Design principles
- Provenance travels with the artifact. Embedded at creation, not inferred later.
- Accountability without content exposure. The log stores hashes, not content.
- Settlement is separate from attribution. The protocol records what happened. It does not move money.
- No central arbiter of value. Trust from math and open spec, not from trusting atrib.
- The protocol is open. Deployments are independent. The spec, signing libraries, calculation algorithm, service software, explorer, and reference clients are open. Anyone can run the public services or build an independent deployment. No hosted analytics or SaaS application is part of the protocol requirement.
Product design
DESIGN.md is the source of truth for atrib's public product surfaces: website, explorer, docs, package README patterns, share images, and user-facing reliability states. It records the current state, target direction, tokens, components, writing rules, and remaining design backlog.
More
- Policy templates and guide
- Product design system
- Architecture and trust model
- Prior art and standards map
- Decision log
atrib-log-pp-cli: a Printing-Press-generated Go CLI for the public log API (signed checkpoint, recent entries, lookups by hash / context / creator, Merkle tiles, local SQLite mirror). Complementary to theattest/recallMCP verbs: agents use the verbs, humans and scripts use the CLI.- Implementation status
- Contributing
License
Apache 2.0