{"_id":"@ai-agent-ledger/sdk","_rev":"5-9039fbe472d77271bb26ae8e635317f0","name":"@ai-agent-ledger/sdk","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@ai-agent-ledger/sdk","version":"0.1.0","keywords":["ai-agents","observability","audit","policy","governance","llm","langchain"],"license":"MIT","_id":"@ai-agent-ledger/sdk@0.1.0","maintainers":[{"name":"esammy","email":"egwusamuel2015@gmail.com"}],"homepage":"https://github.com/agentledger/agent-ledger-sdk#readme","bugs":{"url":"https://github.com/agentledger/agent-ledger-sdk/issues"},"dist":{"shasum":"7339a4e7f841171834bbcb0417c30fc35b2ff9fb","tarball":"https://registry.npmjs.org/@ai-agent-ledger/sdk/-/sdk-0.1.0.tgz","fileCount":16,"integrity":"sha512-2SSspvxjdV2KszLi1YDviBUGxl1UONxKz39NwM82ryx953+xdPMS8Rxh5ECV/qH0vZz0icatrbdE/pnq/usVrQ==","signatures":[{"sig":"MEUCIFZIH4nKlBENcaKDKU+9mGs55T+ZztMrrgIBcjgfiwiWAiEArX7VLeLpnrk2nRAE2eFWE8Gqb//1EpOmhP64XjTqGO4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":167614},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.mjs","require":"./dist/server.js"}},"scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","prepack":"npm run build","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"esammy","email":"egwusamuel2015@gmail.com"},"repository":{"url":"git+https://github.com/agentledger/agent-ledger-sdk.git","type":"git"},"_npmVersion":"10.5.0","description":"Runtime observability, policy enforcement, and audit trails for AI agents","directories":{},"_nodeVersion":"21.7.3","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.6.0","@types/ws":"^8.0.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"peerDependencies":{"ws":">=8.0.0"},"peerDependenciesMeta":{"ws":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1777812031742_0.2245610747106046","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@ai-agent-ledger/sdk","version":"0.1.1","keywords":["ai-agents","observability","audit","policy","governance","llm","langchain"],"license":"MIT","_id":"@ai-agent-ledger/sdk@0.1.1","maintainers":[{"name":"esammy","email":"egwusamuel2015@gmail.com"}],"homepage":"https://github.com/Esammy/AgentLedgerSDK#readme","bugs":{"url":"https://github.com/Esammy/AgentLedgerSDK/issues"},"dist":{"shasum":"1eb5f6f216b506dd24c0c284a6dfc50cea07be17","tarball":"https://registry.npmjs.org/@ai-agent-ledger/sdk/-/sdk-0.1.1.tgz","fileCount":16,"integrity":"sha512-Sp9hbzBrxcKXAnHKOL3EsELVZ4xtswRTT8KpcAPR0uECkrSFGTCcN1Th3k98x8/ckj+TvsocBnLkSLOTdAn0QQ==","signatures":[{"sig":"MEUCIG9jmAOV1jwRcyL5Qv/MuI9kIs2aYpwzOZiIA9UJ1aE/AiEAvR/o9ytFlzEQXoDD3irNAvsmna9o5aKjI32GqqYmm7k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":167635},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.mjs","require":"./dist/server.js"}},"gitHead":"d2d24b37cf6d5fd99629e93cdc346782add0b81f","scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","prepack":"npm run build","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"esammy","email":"egwusamuel2015@gmail.com"},"repository":{"url":"git+https://github.com/Esammy/AgentLedgerSDK.git","type":"git"},"_npmVersion":"10.5.0","description":"Runtime observability, policy enforcement, and audit trails for AI agents","directories":{},"_nodeVersion":"21.7.3","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.6.0","@types/ws":"^8.0.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"peerDependencies":{"ws":">=8.0.0"},"peerDependenciesMeta":{"ws":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.1_1777814936386_0.21971859049301634","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@ai-agent-ledger/sdk","version":"0.1.2","keywords":["ai-agents","observability","audit","policy","governance","llm","langchain"],"license":"MIT","_id":"@ai-agent-ledger/sdk@0.1.2","maintainers":[{"name":"esammy","email":"egwusamuel2015@gmail.com"}],"homepage":"https://github.com/Esammy/AgentLedgerSDK#readme","bugs":{"url":"https://github.com/Esammy/AgentLedgerSDK/issues"},"dist":{"shasum":"73c8858d1bb4c64da45af360245d1d0e66145773","tarball":"https://registry.npmjs.org/@ai-agent-ledger/sdk/-/sdk-0.1.2.tgz","fileCount":16,"integrity":"sha512-YIi/PNqfwXGAWw8EiVBukAyuaDfyk6APYHUcy4XnLlJDSV1UrbmcuAnOpmOXhkiBUWoaYjuqqW83XB7wviKPEA==","signatures":[{"sig":"MEQCIBo7FQCy8TPD+iTihMvA/3Qu2ieOO3h1irbXk4O0eAcGAiAxNT4Hqceozn+dGvi23BlHIV3YtIRAEYLRF5oDRshNHA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":167696},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.mjs","require":"./dist/server.js"}},"gitHead":"11e2be91440e8aae7cabd88f4eeedbebb71fa0a7","scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","prepack":"npm run build","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"esammy","email":"egwusamuel2015@gmail.com"},"repository":{"url":"git+https://github.com/Esammy/AgentLedgerSDK.git","type":"git"},"_npmVersion":"10.5.0","description":"Runtime observability, policy enforcement, and audit trails for AI agents","directories":{},"_nodeVersion":"21.7.3","dependencies":{"ws":"^8.18.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.6.0","@types/ws":"^8.0.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"peerDependencies":{"ws":">=8.0.0"},"peerDependenciesMeta":{"ws":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.2_1777841617205_0.7998215002965006","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@ai-agent-ledger/sdk","version":"0.2.0","keywords":["ai-agents","observability","audit","policy","governance","llm","langchain"],"license":"MIT","_id":"@ai-agent-ledger/sdk@0.2.0","maintainers":[{"name":"esammy","email":"egwusamuel2015@gmail.com"}],"homepage":"https://github.com/Esammy/AgentLedgerSDK#readme","bugs":{"url":"https://github.com/Esammy/AgentLedgerSDK/issues"},"dist":{"shasum":"1186bea12e6e9cbe4fff8f8a7e1ed96b0d55e6a6","tarball":"https://registry.npmjs.org/@ai-agent-ledger/sdk/-/sdk-0.2.0.tgz","fileCount":16,"integrity":"sha512-TquFyGCZ5uxv3OwB+WfL833Z7pnPzFz/i8jQmedy4yjOwX8jMAQ/3BAGHYkWmEQx79IfOUuDx53W1yOensuWoA==","signatures":[{"sig":"MEQCIBA+eOwPe0DTy43Kv4F03iiqqlJl3uRLxUP6AdnwZS8gAiB+d2fbfq72AA7l+j7e7T87BlZz0vDyC94nK6tEDYPRVQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":216814},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.mjs","require":"./dist/server.js"}},"gitHead":"d91efbbe770d3645066428573807a76bee882e70","scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","prepack":"npm run build","ci:local":"npm run typecheck && npm run typecheck:examples && npm run build && npm test","typecheck":"tsc --noEmit","test:watch":"vitest","typecheck:examples":"tsc --noEmit --project tsconfig.examples.json"},"_npmUser":{"name":"esammy","email":"egwusamuel2015@gmail.com"},"repository":{"url":"git+https://github.com/Esammy/AgentLedgerSDK.git","type":"git"},"_npmVersion":"10.5.0","description":"Runtime observability, policy enforcement, and audit trails for AI agents","directories":{},"_nodeVersion":"21.7.3","_hasShrinkwrap":false,"devDependencies":{"ws":"^8.18.0","tsup":"^8.0.0","vitest":"^1.6.0","@types/ws":"^8.0.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"peerDependencies":{"ws":">=8.0.0"},"peerDependenciesMeta":{"ws":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1779556196562_0.09014329510385433","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@ai-agent-ledger/sdk","version":"0.3.0","description":"Runtime observability, policy enforcement, and audit trails for AI agents","repository":{"type":"git","url":"git+https://github.com/Esammy/AgentLedgerSDK.git"},"bugs":{"url":"https://github.com/Esammy/AgentLedgerSDK/issues"},"homepage":"https://github.com/Esammy/AgentLedgerSDK#readme","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.mjs","require":"./dist/server.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","lint":"eslint src --ext .ts","ci:local":"npm run typecheck && npm run typecheck:examples && npm run build && npm test","typecheck":"tsc --noEmit","typecheck:examples":"tsc --noEmit --project tsconfig.examples.json","prepack":"npm run build"},"keywords":["ai-agents","observability","audit","policy","governance","llm","langchain","mcp","guardrails","ai-safety","kill-switch"],"license":"MIT","peerDependencies":{"ws":">=8.0.0"},"peerDependenciesMeta":{"ws":{"optional":true}},"devDependencies":{"@types/node":"^20.0.0","@types/ws":"^8.0.0","tsup":"^8.0.0","typescript":"^5.4.0","vitest":"^1.6.0","ws":"^8.18.0"},"engines":{"node":">=18.0.0"},"_id":"@ai-agent-ledger/sdk@0.3.0","gitHead":"5ba4a2362fb3b3ee06e96c575fd23db93fb92012","_nodeVersion":"21.7.3","_npmVersion":"10.5.0","dist":{"integrity":"sha512-KC/aMP/jIRQe6Co3Xnxn8sy25YHyXNUouh/HQ6COW2abIKF9ezP+uZafGjGuFEWyeR+vu7I5iY8WFF/emyxFQQ==","shasum":"42f66233c7f7ccf864e7a4a42a45015552d18bf8","tarball":"https://registry.npmjs.org/@ai-agent-ledger/sdk/-/sdk-0.3.0.tgz","fileCount":17,"unpackedSize":392316,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBQdI3sCk/f8e1U+GPVLGMuP1NtHO5whUjQeTjwlH4WyAiEAydnAVC+KcHfPh41TrYxOUepmJVTKBwRc0BC7hFCxra4="}]},"_npmUser":{"name":"esammy","email":"egwusamuel2015@gmail.com"},"directories":{},"maintainers":[{"name":"esammy","email":"egwusamuel2015@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.3.0_1783789630053_0.33085201625767824"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T12:40:31.689Z","modified":"2026-07-11T17:07:10.371Z","0.1.0":"2026-05-03T12:40:31.896Z","0.1.1":"2026-05-03T13:28:56.590Z","0.1.2":"2026-05-03T20:53:37.376Z","0.2.0":"2026-05-23T17:09:56.725Z","0.3.0":"2026-07-11T17:07:10.207Z"},"bugs":{"url":"https://github.com/Esammy/AgentLedgerSDK/issues"},"license":"MIT","homepage":"https://github.com/Esammy/AgentLedgerSDK#readme","keywords":["ai-agents","observability","audit","policy","governance","llm","langchain","mcp","guardrails","ai-safety","kill-switch"],"repository":{"type":"git","url":"git+https://github.com/Esammy/AgentLedgerSDK.git"},"description":"Runtime observability, policy enforcement, and audit trails for AI agents","maintainers":[{"name":"esammy","email":"egwusamuel2015@gmail.com"}],"readme":"# AgentLedger SDK 🛡️⛓️\r\n\r\n**Runtime kill switch, audit trail, and policy enforcement for AI agents. Add it in 3 lines.**\r\n\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\r\n[![NPM Version](https://img.shields.io/npm/v/@ai-agent-ledger/sdk)](https://www.npmjs.com/package/@ai-agent-ledger/sdk)\r\n[![TypeScript](https://img.shields.io/badge/Language-TypeScript-blue)](https://www.typescriptlang.org/)\r\n[![npm downloads](https://img.shields.io/npm/dm/@ai-agent-ledger/sdk)](https://www.npmjs.com/package/@ai-agent-ledger/sdk)\r\n\r\n---\r\n\r\n<p align=\"center\">\r\n  <img src=\"./assets/demo.svg\" alt=\"AgentLedger demo: allow a $250 payment, block a $12,500 payment by policy, kill switch halts further calls, then chain verifies tamper-evident\" width=\"820\" />\r\n</p>\r\n\r\n---\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install @ai-agent-ledger/sdk\r\n```\r\n\r\n```typescript\r\nimport { AgentLedger, POLICY_TEMPLATES } from '@ai-agent-ledger/sdk'\r\n\r\nconst ledger = new AgentLedger({ agent_id: 'my-agent', storage: { type: 'file', path: './audit.ndjson' }, policies: [POLICY_TEMPLATES.no_spend_over(500)] })\r\nconst agent = ledger.wrap(myExistingAgent) // every tool call is now governed\r\n```\r\n\r\n---\r\n\r\n## Why this exists\r\n\r\nHere is the scenario that made this necessary:\r\n\r\nAn AI agent, running unsupervised in a payment workflow, queued 47 transactions totalling $230,000 — none of them authorized. By the time anyone caught it, 12 had already executed. There was no kill switch. No audit trail. No way to explain to a board what the agent had been doing, or why it could not be stopped.\r\n\r\nThis is the pattern we kept hearing across AI engineering teams trying to ship to production. The agent works. It passes every test. Then it hits a real environment, and there is nothing between it and your production systems.\r\n\r\nWe went looking for the middleware layer that should exist — something you drop in front of any agent framework that intercepts tool calls before they execute, enforces policies, writes a tamper-evident log, and gives you a kill switch you can trigger in under 50ms. It did not exist. So we built it.\r\n\r\nAgentLedger is that layer. It wraps your agent's tools, evaluates policies synchronously before each call, appends every event to a SHA-256 hash chain you can verify later, and gives you a kill switch you can trigger in under 50ms from a dashboard API.\r\n\r\n---\r\n\r\n## Framework Integrations\r\n\r\n### LangChain\r\n\r\n```typescript\r\nimport { ChatOpenAI } from '@langchain/openai'\r\nimport { AgentLedger, POLICY_TEMPLATES } from '@ai-agent-ledger/sdk'\r\n\r\nconst ledger = new AgentLedger({\r\n  agent_id: 'langchain-agent',\r\n  storage: { type: 'file', path: './audit.ndjson' },\r\n  policies: [POLICY_TEMPLATES.no_delete(), POLICY_TEMPLATES.no_spend_over(1000)]\r\n})\r\n\r\n// Wrap your tools before passing them to the agent\r\nconst rawTools = [sendEmailTool, queryDatabaseTool, createPaymentTool]\r\nconst agent = ledger.wrap({ id: 'langchain-agent', tools: rawTools })\r\n\r\n// Now pass agent.tools to your LangChain executor as normal\r\n// Every call is intercepted, risk-scored, and hash-chained\r\n```\r\n\r\n> Full example: [`examples/langchain_integration.ts`](./examples/langchain_integration.ts)\r\n\r\n---\r\n\r\n### Anthropic (Claude Tool Use)\r\n\r\n```typescript\r\nimport Anthropic from '@anthropic-ai/sdk'\r\nimport { AgentLedger, POLICY_TEMPLATES, PolicyBlockError } from '@ai-agent-ledger/sdk'\r\n\r\nconst ledger = new AgentLedger({\r\n  agent_id: 'claude-agent',\r\n  storage: { type: 'memory' },\r\n  policies: [POLICY_TEMPLATES.no_delete()]\r\n})\r\n\r\nconst myTools = [{ name: 'query_db', description: 'Query the database', func: async (...args) => queryDb(...args) }]\r\nconst governed = ledger.wrap({ id: 'claude-agent', tools: myTools })\r\n\r\n// Use governed.tools as your Anthropic tool handlers\r\n```\r\n\r\n> Full example: [`examples/anthropic_integration.ts`](./examples/anthropic_integration.ts)\r\n\r\n---\r\n\r\n### Raw OpenAI (Function Calling)\r\n\r\n```typescript\r\nimport OpenAI from 'openai'\r\nimport { AgentLedger, POLICY_TEMPLATES } from '@ai-agent-ledger/sdk'\r\n\r\nconst ledger = new AgentLedger({\r\n  agent_id: 'openai-agent',\r\n  storage: { type: 'memory' },\r\n  policies: [POLICY_TEMPLATES.no_spend_over(500)]\r\n})\r\n\r\nconst myTools = [{ name: 'create_payment', description: 'Create a payment', func: async (...args) => processPayment(...args) }]\r\nconst governed = ledger.wrap({ id: 'openai-agent', tools: myTools })\r\n\r\n// Call governed.tools[0].func() — it runs your policy check first, then the real function\r\n```\r\n\r\n> Full example: [`examples/openai_integration.ts`](./examples/openai_integration.ts)\r\n\r\n---\r\n\r\n### CrewAI / AutoGen / Custom Agents\r\n\r\nAny object with a `tools` array works:\r\n\r\n```typescript\r\nconst myAgent = {\r\n  id: 'my-crew-agent',\r\n  tools: [\r\n    { name: 'send_report', description: 'Send a report email', func: async (...args) => sendEmail(...args) },\r\n    { name: 'write_file',  description: 'Write to disk',       func: async (...args) => writeFile(...args) }\r\n  ]\r\n}\r\n\r\nconst governed = ledger.wrap(myAgent)\r\n// governed.tools[*].func is now intercepted — policies run, entries are logged\r\n```\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n*   **🛡️ Policy Enforcement:** Block or gate tool calls with deterministic rules — no LLM in the enforcement path.\r\n*   **🧠 Natural-Language Policies:** Write policies in plain English; compiled once at startup (Claude, Gemini, OpenAI, Groq, …) into a deterministic rule AST.\r\n*   **⛓️ Tamper-Evident Ledger:** Every event is SHA-256 hash-chained. Edits, deletions, and reordering all break verification.\r\n*   **🛑 Kill Switch:** Call `ledger.killSwitch(run_id)` — the next tool invocation for that run throws immediately.\r\n*   **🔍 Risk Scoring:** Heuristic 0–100 scoring on tool names, arguments (PII/credential patterns), and payload size.\r\n*   **🧵 Request-Scoped Runs:** `ledger.run(cb, run_id)` uses `AsyncLocalStorage` to isolate audit context across concurrent async requests.\r\n*   **🤖 Framework Agnostic:** Works with LangChain, CrewAI, Anthropic, OpenAI, MCP servers (via the gateway), or any custom agent.\r\n\r\n---\r\n\r\n## Built-in Policy Templates\r\n\r\n```typescript\r\nPOLICY_TEMPLATES.no_spend_over(500)              // Block any payment tool where amount > $500\r\nPOLICY_TEMPLATES.no_delete()                     // Block tools matching deletion patterns\r\nPOLICY_TEMPLATES.external_email_gate('corp.com') // Require approval before emailing outside domain\r\nPOLICY_TEMPLATES.business_hours_only(9, 17)      // Block all tool calls outside 09:00–17:00 UTC\r\nPOLICY_TEMPLATES.pii_write_alert(['#sec-ops'])   // Alert channel when PII detected in DB writes\r\n```\r\n\r\n---\r\n\r\n## Approval Gates\r\n\r\n```typescript\r\nimport { PolicyBlockError, ApprovalDeniedError } from '@ai-agent-ledger/sdk'\r\n\r\ntry {\r\n  await governed.tools[0].func({ to: 'vendor@external.com', body: '...' })\r\n} catch (err) {\r\n  if (err instanceof PolicyBlockError) {\r\n    // Blocked outright — check err.policy_id for which rule fired\r\n  }\r\n  if (err instanceof ApprovalDeniedError) {\r\n    // A human reviewed and denied the approval gate\r\n  }\r\n}\r\n\r\n// In your approval handler (e.g. from a dashboard or Slack webhook):\r\nawait ledger.approveGate(token, 'alice@corp.com')\r\n// or\r\nawait ledger.denyGate(token, 'alice@corp.com')\r\n```\r\n\r\n---\r\n\r\n## Kill Switch\r\n\r\n```typescript\r\n// Halt a specific run\r\nawait ledger.killSwitch('run-abc-123')\r\n\r\n// Global halt — stops all future tool calls across all runs\r\nawait ledger.killSwitch()\r\n```\r\n\r\n---\r\n\r\n## Audit Dashboard\r\n\r\n```typescript\r\nimport { createDashboardServer } from '@ai-agent-ledger/sdk/server'\r\n\r\nconst server = createDashboardServer(ledger)\r\nawait server.listen({ port: 4000 })\r\n\r\n// REST API:\r\n// GET  /runs/:run_id          — list all entries for a run\r\n// GET  /runs/:run_id/verify   — re-compute SHA-256 chain, returns { valid, broken_at }\r\n// POST /runs/:run_id/kill     — kill switch via HTTP\r\n// GET  /export/:run_id        — download audit log as JSON or plain text\r\n// WebSocket /                 — live stream of entry, kill, and escalation events\r\n```\r\n\r\n---\r\n\r\n## 🧠 Natural-Language Policies\r\n\r\nWrite policies in plain English. They compile **once at startup** into a deterministic rule AST — zero LLM calls on the enforcement path, so runtime evaluation stays synchronous and sub-2ms.\r\n\r\n```typescript\r\nimport { AgentLedger, ClaudeCompiler, createGroqCompiler } from '@ai-agent-ledger/sdk'\r\n\r\nconst ledger = new AgentLedger({ agent_id: 'my-agent', storage: { type: 'memory' } })\r\n\r\n// Pick any provider: ClaudeCompiler, GeminiCompiler, createOpenAICompiler,\r\n// createGroqCompiler, createMistralCompiler, createDeepSeekCompiler, ...\r\nconst compiler = new ClaudeCompiler({ apiKey: process.env.ANTHROPIC_API_KEY! })\r\n\r\nawait ledger.policy.addPolicyAsync(\r\n  {\r\n    description: 'Never allow sending emails to addresses ending in @competitor.com',\r\n    action: 'block',\r\n    severity: 'high',\r\n  },\r\n  compiler\r\n)\r\n// From here on, enforcement is pure JS — the LLM is never called again.\r\n```\r\n\r\nSupported compile-time providers: **Anthropic (Claude), Google (Gemini), OpenAI, Groq, Mistral, xAI, Together, DeepSeek, Fireworks, Azure OpenAI** — plus any OpenAI-compatible endpoint via `ChatCompletionsCompiler`.\r\n\r\n> Full example: [`examples/policy_compilation.ts`](./examples/policy_compilation.ts)\r\n\r\n---\r\n\r\n## Verify the Chain\r\n\r\nEvery entry's `id` is a SHA-256 over the entry *including* its `prev_id`, and verification checks both per-entry integrity **and** link continuity — so editing, deleting, reordering, or truncating entries is detected:\r\n\r\n```typescript\r\nimport { verifyChain } from '@ai-agent-ledger/sdk'\r\n\r\nconst entries = await ledger.storage.query({ run_id: 'run-abc' })\r\nconst result = verifyChain(entries)\r\n// { valid: false, broken_at: 3, reason: 'link_broken', runs: [...] }\r\n// reason: 'hash_mismatch' → a field was edited\r\n//         'link_broken'   → an entry was deleted/reordered mid-run\r\n//         'bad_genesis'   → the start of the run was truncated\r\n```\r\n\r\n---\r\n\r\n<!--\r\n  Star History — bring this section back once the repo has ~200+ stars with visible momentum.\r\n  Below that threshold an empty chart actively hurts perception. Just uncomment when ready.\r\n\r\n  ## Star History\r\n\r\n  [![Star History Chart](https://api.star-history.com/svg?repos=Esammy/AgentLedgerSDK&type=Date)](https://star-history.com/#Esammy/AgentLedgerSDK&Date)\r\n\r\n  ---\r\n-->\r\n\r\n## Project Structure\r\n\r\n```\r\nsrc/\r\n  ledger/           — AgentLedger core, SHA-256 chain, run context (AsyncLocalStorage)\r\n  interceptor/      — Tool wrapping, policy evaluation, kill switch, approval gates\r\n  policy/           — PolicyEngine, rule evaluator, built-in templates\r\n  policy/compilers/ — Natural language → rule AST (Claude, Gemini, OpenAI-compatible)\r\n  risk/             — Heuristic risk scorer and PII/credential classifier\r\n  storage/          — Pluggable adapters: File (NDJSON), Memory, Cloud WebSocket\r\n  server/           — Lightweight Node http + WebSocket dashboard server\r\nexamples/\r\n  basic_usage.ts            — Quickstart: block + allow\r\n  policy_compilation.ts     — Natural-language policy → compiled rule\r\n  concurrency_and_runs.ts   — Request-scoped run isolation\r\n  langchain_integration.ts  — LangChain tool wrapping\r\n  anthropic_integration.ts  — Anthropic Claude tool use\r\n  openai_integration.ts     — Raw OpenAI function calling\r\n```\r\n\r\n> **S3 storage** requires the separate `@ai-agent-ledger/s3` package.\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup, test commands, and how to propose new policy templates.\r\n\r\n## License\r\n\r\nMIT © [AgentLedger](https://github.com/Esammy/AgentLedgerSDK)\r\n","readmeFilename":"README.md"}