@peculis/provenance-sdk

Record your AI agent's decisions into a tamper-evident, externally-anchored evidence trail. The SDK is fail-open — it never blocks or fails your agent.

Early/WIP (0.x). Self-contained (only zod as a runtime dependency).

Install

pnpm add @peculis/provenance-sdk      # npm i / yarn add also fine

Use

import { init } from "@peculis/provenance-sdk";

const provenance = init({
  projectKey: process.env.PROVENANCE_PROJECT_KEY!,
  endpoint: "https://ingest.your-provenance.example",
});

const session = provenance.startSession({ agentId: "refund-agent" });

session.record("model_call", { model: "claude-sonnet-4-6", tokens: 412 });
session.gate("refund-policy", "permitted", "rule:refund-under-100");   // declared governance
session.accessed("crm.customers", "refund-eligibility", { recordCount: 1 });
session.humanApproval({ who: "alice@corp", what: { action: "refund", amount: 50 }, outcome: "approved" });

await session.end("ok");

Options: mode ("fail-open" default / "fail-closed"), captureMode ("payload" / "digest-only"), redaction ([{ path, action: "drop"|"mask"|"hash" }], applied before the digest).

What it proves

Anchored events are unaltered and omissions are visible as declared gaps — verifiable offline by anyone. It does not prove that everything the agent did was recorded, that an event reflects a real action, or exactly when it occurred.