v0.2.0: v2 hashing and verifyExportedSession

Published on npm: @vluthra/agent-ledger@0.2.0

npm install @vluthra/agent-ledger@0.2.0

What's new

v2 hashing (opt-in): record hashes now cover nested fields

In 0.1.x (v1), the record hash only covered top-level fields. A change inside a nested value, such as a tool argument (input.args.amount), did not change the hash. v2 fixes this:

• Canonical JSON (RFC 8785): every field at every depth is hashed, with keys sorted.
• Domain-separated record hash: sha256("agentledger/record-hash/v2\n" + canonical).
• RFC 6962-style Merkle tree: leaves and nodes are prefixed differently, and an odd node is carried up instead of duplicated.

Turn it on per session:

new AgentLedgerSession({ agentId: 'my-agent', canonicalization: 'v2' })

v1 stays the default, so existing sessions and hashes verify exactly as before. Exports say which version they use (canonicalization, merkle).

verifyExportedSession(doc)

Verifies a saved session file on its own, in any process, with no live session object. It checks:

• the hashing version;
• each record's hash and the links between records;
• that every record belongs to the session and none are missing;
• the Merkle root.

Records are isolated copies

record() stores a plain-JSON copy of what you pass in:

• toJSON is honored, so a Date is stored as its ISO string.
• Records you get back are copies, so changing them can't affect the ledger.
• Circular references and BigInt values raise an error that names the path, such as $.c.self.
• Under v2, NaN and Infinity are rejected rather than silently turned into null.

Other

• Package test in CI: the published package is installed into a fresh project and the README quick start compiles under strict TypeScript, with both CommonJS and ES modules checked.
• 118 tests.

Talk

This release accompanies "Prove What Your Agent Did", presented at AGNTCon + MCPCon North America, October 23, 2026. The slides are attached and in docs/talks/2026-10-23-agntcon-mcpcon/.

The PDF's SHA-256 was anchored on Arbitrum Sepolia before the talk:

PDF SHA-256	a6b3f64f71441c0c95a67d88a5bbe865f4cc73eea06cdf74cbffcaca87b2de5a
Transaction	0x381f1f21…84aa91
Block	321864447 (2026-10-22T22:49:12Z)
Contract	0xB07eB96033eE808928aFE66eFbE82c2F90AF9D63
Anchorer	0x2f5ab2b229c45017fEF9C8e6a136453F32cc546A

Package integrity

• npm dist.integrity: sha512-GQ+0FbzplTs4c4LjQl/te5om/QzrK+c3QaEAn1Q47t+qWngIxM++JtVUdHTngNdXUXE0SPNAT8ReJs6OimbFYQ==
• Git tag v0.2.0 → commit b41c7f7