@prufs/sdk

Decision trail capture SDK for AI coding agents. Records the directive → interpretation → decision chain your agent follows, signs each event with Ed25519, and hash-chains the log so it is tamper-evident: altering any event invalidates its signature and breaks the chain for every event after it.

Install

npm install @prufs/sdk

Quick start

import { TrailRecorder } from "@prufs/sdk";

const trail = new TrailRecorder({
  project_id: "my-project",
  transport: "local",
  agent_id: "claude-code",
  model_id: "claude-sonnet-4-20250514",
});

await trail.startSession();

const d = await trail.directive("Add user search to admin panel");
const i = await trail.interpretation(d, "Implement search endpoint...");
const dec = await trail.decision(i, {
  chosen: "Elasticsearch",
  alternatives: [
    { description: "PostgreSQL FTS", rejection_reason: "No existing index" },
  ],
  rationale: "Elasticsearch index already exists and supports fuzzy matching",
  domain_tags: ["search", "database"],
});

await trail.endSession();

Signing keys

On first run the SDK generates an Ed25519 keypair at .prufs/signing-key.pem (private, 0600) and .prufs/signing-key.pub (public, shareable). Never commit the private key. The default .gitignore in this repo excludes .prufs/; keep it that way in your own project. Verification only needs the public key, so share .pub freely and keep .pem secret. Override the path with the signing_key_path option.

Verifying a trail

Verification is independent of the SDK — any tool with the public key can check the chain:

import { verifyChain, loadOrCreateKeyPair } from "@prufs/sdk";

Exports

TrailRecorder, LocalTransport, HttpTransport, CloudSync, SessionObserver, ClaudeCodeHook, and the signing primitives (loadOrCreateKeyPair, signEvent, verifyEvent, verifyChain, computeContentHash).

License

See LICENSE at the repository root.