agentledger 0.3.0

package/README.md

@@ -0,0 +1,176 @@
+# AgentLedger
+
+**See everything your AI agents do.** Track actions, monitor costs, and kill agents when things go wrong.
+
+Your agents send emails, create tickets, charge credit cards, and call APIs. AgentLedger logs every action, tracks every cost, and lets you kill agents instantly when things go sideways.
+
+## Install
+
+```bash
+npm install agentledger
+```
+
+## Quick Start
+
+```typescript
+import { AgentLedger } from 'agentledger';
+
+const ledger = new AgentLedger({
+  apiKey: process.env.AGENTLEDGER_KEY, // Get this from agentledger.co
+});
+
+// Wrap any async function — it's logged, timed, and budget-checked
+const result = await ledger.track({
+  agent: 'support-bot',
+  service: 'slack',
+  action: 'send_message',
+}, async () => {
+  return await slack.chat.postMessage({ channel: '#support', text: 'Hello!' });
+});
+```
+
+Open your dashboard at [agentledger.co](https://agentledger.co) and watch your agents in real-time.
+
+## Features
+
+- **Zero dependencies** — just this package, nothing else
+- **Fail-open by default** — if AgentLedger is down, your agents keep running
+- **Pre-flight checks** — block actions before they happen if agent is over budget
+- **Kill switches** — pause or kill any agent instantly
+- **Cost tracking** — know exactly what each agent costs
+- **5ms overhead** — async logging, doesn't slow your agents down
+
+## API
+
+### `new AgentLedger(config)`
+
+```typescript
+const ledger = new AgentLedger({
+  apiKey: 'al_...',           // Required. Get from agentledger.co
+  baseUrl: 'https://...',     // Optional. Default: https://agentledger.co
+  failOpen: true,             // Optional. If true, agents run even if AgentLedger is unreachable
+  timeout: 5000,              // Optional. API timeout in ms
+  onError: (err) => {},       // Optional. Called on communication errors
+});
+```
+
+### `ledger.track(options, fn)`
+
+Wrap an async function. Runs a pre-flight budget check, executes the function, logs the result.
+
+```typescript
+const { result, allowed, durationMs } = await ledger.track({
+  agent: 'my-bot',
+  service: 'stripe',
+  action: 'charge',
+  costCents: 50,
+  metadata: { customerId: '123' },
+}, async () => {
+  return await stripe.charges.create({ amount: 5000 });
+});
+```
+
+### `ledger.check(options)`
+
+Pre-flight check without executing. Use before expensive operations.
+
+```typescript
+const { allowed, blockReason } = await ledger.check({
+  agent: 'my-bot',
+  service: 'openai',
+  action: 'completion',
+});
+
+if (!allowed) {
+  console.log(`Blocked: ${blockReason}`);
+}
+```
+
+### `ledger.log(options)`
+
+Manual logging without wrapping a function.
+
+```typescript
+await ledger.log({
+  agent: 'my-bot',
+  service: 'sendgrid',
+  action: 'send_email',
+  costCents: 1,
+  durationMs: 340,
+});
+```
+
+### `ledger.pauseAgent(name)` / `resumeAgent(name)` / `killAgent(name)`
+
+Control agents programmatically.
+
+```typescript
+await ledger.pauseAgent('runaway-bot');  // All future actions blocked
+await ledger.resumeAgent('runaway-bot'); // Back in action
+await ledger.killAgent('runaway-bot');   // Permanently stopped
+```
+
+## Framework Integrations
+
+### LangChain
+
+```typescript
+import { AgentLedger } from 'agentledger';
+import { AgentLedgerCallbackHandler } from 'agentledger/integrations/langchain';
+
+const handler = new AgentLedgerCallbackHandler(ledger, {
+  agent: 'research-bot',
+  serviceMap: { 'tavily_search': { service: 'tavily', action: 'search' } },
+});
+
+const agent = createReactAgent({ llm, tools, callbacks: [handler] });
+```
+
+### OpenAI
+
+```typescript
+import { createToolExecutor } from 'agentledger/integrations/openai';
+
+const execute = createToolExecutor(ledger, 'my-agent', tools, serviceMap);
+```
+
+### MCP Servers
+
+```typescript
+import { wrapMCPServer } from 'agentledger/integrations/mcp';
+
+wrapMCPServer(ledger, server, { agent: 'my-mcp-server' });
+```
+
+### Express
+
+```typescript
+import { agentLedgerMiddleware } from 'agentledger/integrations/express';
+
+app.post('/api/action', agentLedgerMiddleware(ledger, {
+  agent: 'api-bot', service: 'internal', action: 'process',
+}), handler);
+```
+
+## Self-Hosting
+
+AgentLedger is open source. You can self-host the dashboard:
+
+```bash
+git clone https://github.com/mnoonan/agentledger.git
+cd agentledger
+npm install && npm run dev
+```
+
+Point your SDK to your own instance:
+
+```typescript
+const ledger = new AgentLedger({
+  apiKey: 'al_...',
+  baseUrl: 'https://your-instance.com',
+});
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+export interface AgentLedgerConfig {
+    /** Your AgentLedger API key (starts with al_) */
+    apiKey: string;
+    /** Base URL for the AgentLedger API. Default: https://agentledger.co */
+    baseUrl?: string;
+    /** If true, actions proceed even if AgentLedger is unreachable. Default: true */
+    failOpen?: boolean;
+    /** Timeout in ms for API calls. Default: 5000 */
+    timeout?: number;
+    /** Called when an error occurs communicating with AgentLedger */
+    onError?: (error: Error) => void;
+}
+export interface TrackOptions {
+    /** Name of the agent performing the action */
+    agent: string;
+    /** Service being called (e.g. 'slack', 'stripe', 'openai') */
+    service: string;
+    /** Action being performed (e.g. 'send_message', 'charge', 'completion') */
+    action: string;
+    /** Estimated cost in cents. Auto-calculated from duration if not provided. */
+    costCents?: number;
+    /** Additional metadata to log with the action */
+    metadata?: Record<string, unknown>;
+}
+export interface TrackResult<T> {
+    /** The return value of the wrapped function */
+    result: T;
+    /** Whether AgentLedger allowed the action */
+    allowed: boolean;
+    /** Duration of the action in milliseconds */
+    durationMs: number;
+    /** The logged action ID */
+    actionId?: string;
+}
+export interface CheckResult {
+    allowed: boolean;
+    blockReason?: string;
+    remainingBudget?: {
+        actions?: number;
+        costCents?: number;
+    };
+}
+export declare class AgentLedger {
+    private apiKey;
+    private baseUrl;
+    private failOpen;
+    private timeout;
+    private onError?;
+    constructor(config: AgentLedgerConfig);
+    /**
+     * Track an agent action. Wraps an async function with logging and budget checks.
+     *
+     * @example
+     * const result = await ledger.track({
+     *   agent: 'support-bot',
+     *   service: 'slack',
+     *   action: 'send_message',
+     * }, async () => {
+     *   return await slack.chat.postMessage({ channel: '#support', text: 'Hello!' });
+     * });
+     */
+    track<T>(options: TrackOptions, fn: () => Promise<T>): Promise<TrackResult<T>>;
+    /**
+     * Check if an action is allowed without executing it.
+     * Useful for pre-flight checks before expensive operations.
+     */
+    check(options: Pick<TrackOptions, 'agent' | 'service' | 'action'>): Promise<CheckResult>;
+    /**
+     * Log an action directly without wrapping a function.
+     * Useful when you want manual control over timing.
+     */
+    log(options: TrackOptions & {
+        status?: string;
+        durationMs?: number;
+    }): Promise<{
+        id?: string;
+    }>;
+    /**
+     * Pause an agent. All future actions will be blocked until resumed.
+     */
+    pauseAgent(name: string): Promise<void>;
+    /**
+     * Resume a paused agent.
+     */
+    resumeAgent(name: string): Promise<void>;
+    /**
+     * Kill an agent permanently. All future actions will be blocked.
+     */
+    killAgent(name: string): Promise<void>;
+    private logAction;
+    private fetch;
+    private handleError;
+}
+export default AgentLedger;

package/dist/index.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentLedger = void 0;
+class AgentLedger {
+    constructor(config) {
+        if (!config.apiKey || !config.apiKey.startsWith('al_')) {
+            throw new Error('AgentLedger: Invalid API key. Keys start with "al_".');
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl || 'https://agentledger.co').replace(/\/$/, '');
+        this.failOpen = config.failOpen !== false; // default true
+        this.timeout = config.timeout || 5000;
+        this.onError = config.onError;
+    }
+    /**
+     * Track an agent action. Wraps an async function with logging and budget checks.
+     *
+     * @example
+     * const result = await ledger.track({
+     *   agent: 'support-bot',
+     *   service: 'slack',
+     *   action: 'send_message',
+     * }, async () => {
+     *   return await slack.chat.postMessage({ channel: '#support', text: 'Hello!' });
+     * });
+     */
+    async track(options, fn) {
+        // Pre-flight check
+        let allowed = true;
+        try {
+            const check = await this.check(options);
+            allowed = check.allowed;
+            if (!allowed) {
+                throw new Error(`AgentLedger: Action blocked - ${check.blockReason || 'budget exceeded'}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.startsWith('AgentLedger: Action blocked')) {
+                throw err;
+            }
+            // Communication error — fail open or closed
+            if (!this.failOpen) {
+                throw new Error('AgentLedger: Cannot verify action (fail-closed mode)');
+            }
+            this.handleError(err);
+        }
+        // Execute the action
+        const start = Date.now();
+        let status = 'success';
+        let result;
+        try {
+            result = await fn();
+        }
+        catch (err) {
+            status = 'error';
+            const durationMs = Date.now() - start;
+            // Log the error, then re-throw
+            this.logAction(options, status, durationMs).catch(this.handleError.bind(this));
+            throw err;
+        }
+        const durationMs = Date.now() - start;
+        // Log the action (fire and forget for speed, unless we need the ID)
+        let actionId;
+        try {
+            const logResult = await this.logAction(options, status, durationMs);
+            actionId = logResult?.id;
+        }
+        catch (err) {
+            this.handleError(err);
+        }
+        return { result, allowed, durationMs, actionId };
+    }
+    /**
+     * Check if an action is allowed without executing it.
+     * Useful for pre-flight checks before expensive operations.
+     */
+    async check(options) {
+        const res = await this.fetch('/api/v1/check', {
+            method: 'POST',
+            body: JSON.stringify({
+                agent: options.agent,
+                service: options.service,
+                action: options.action,
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`AgentLedger: Check failed (${res.status})`);
+        }
+        return res.json();
+    }
+    /**
+     * Log an action directly without wrapping a function.
+     * Useful when you want manual control over timing.
+     */
+    async log(options) {
+        return this.logAction(options, options.status || 'success', options.durationMs || 0);
+    }
+    /**
+     * Pause an agent. All future actions will be blocked until resumed.
+     */
+    async pauseAgent(name) {
+        const res = await this.fetch(`/api/v1/agents/${encodeURIComponent(name)}/pause`, {
+            method: 'POST',
+        });
+        if (!res.ok)
+            throw new Error(`AgentLedger: Failed to pause agent (${res.status})`);
+    }
+    /**
+     * Resume a paused agent.
+     */
+    async resumeAgent(name) {
+        const res = await this.fetch(`/api/v1/agents/${encodeURIComponent(name)}/resume`, {
+            method: 'POST',
+        });
+        if (!res.ok)
+            throw new Error(`AgentLedger: Failed to resume agent (${res.status})`);
+    }
+    /**
+     * Kill an agent permanently. All future actions will be blocked.
+     */
+    async killAgent(name) {
+        const res = await this.fetch(`/api/v1/agents/${encodeURIComponent(name)}/kill`, {
+            method: 'POST',
+        });
+        if (!res.ok)
+            throw new Error(`AgentLedger: Failed to kill agent (${res.status})`);
+    }
+    // Internal: log action to API
+    async logAction(options, status, durationMs) {
+        const res = await this.fetch('/api/v1/actions', {
+            method: 'POST',
+            body: JSON.stringify({
+                agent: options.agent,
+                service: options.service,
+                action: options.action,
+                status,
+                cost_cents: options.costCents || 0,
+                duration_ms: durationMs,
+                metadata: options.metadata || {},
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`AgentLedger: Failed to log action (${res.status})`);
+        }
+        const data = await res.json();
+        return { id: data.id };
+    }
+    // Internal: fetch with timeout and auth
+    async fetch(path, init = {}) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            return await fetch(`${this.baseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                    ...(init.headers || {}),
+                },
+            });
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    handleError(err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (this.onError) {
+            this.onError(error);
+        }
+    }
+}
+exports.AgentLedger = AgentLedger;
+exports.default = AgentLedger;

package/dist/integrations/express.d.ts

@@ -0,0 +1,69 @@
+/**
+ * AgentLedger Express middleware and generic HTTP integration.
+ *
+ * Usage with Express:
+ *   import { AgentLedger } from '@agentledger/sdk';
+ *   import { agentLedgerMiddleware } from '@agentledger/sdk/integrations/express';
+ *
+ *   const ledger = new AgentLedger({ apiKey: 'al_...' });
+ *
+ *   // Track all requests to a specific route
+ *   app.post('/api/agent/send-email', agentLedgerMiddleware(ledger, {
+ *     agent: 'email-bot',
+ *     service: 'sendgrid',
+ *     action: 'send_email',
+ *   }), (req, res) => {
+ *     // your handler
+ *   });
+ *
+ *   // Or track all routes with auto-detection
+ *   app.use('/api/agent', agentLedgerMiddleware(ledger, {
+ *     agent: 'my-agent',
+ *     autoDetect: true, // uses req.path as action, req.method as metadata
+ *   }));
+ */
+import type { AgentLedger, TrackOptions } from '../index';
+export interface MiddlewareConfig {
+    /** Agent name */
+    agent: string;
+    /** Service name. If autoDetect is true, can be omitted */
+    service?: string;
+    /** Action name. If autoDetect is true, uses req.path */
+    action?: string;
+    /** Auto-detect service/action from request path */
+    autoDetect?: boolean;
+    /** Custom cost extractor from request/response */
+    costExtractor?: (req: unknown, res: unknown) => number;
+}
+/**
+ * Express-compatible middleware that tracks requests as agent actions.
+ */
+export declare function agentLedgerMiddleware(ledger: AgentLedger, config: MiddlewareConfig): (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => Promise<void>;
+/**
+ * Simple wrapper for any async function — no Express dependency needed.
+ * Wraps a function with AgentLedger tracking and returns a new function
+ * with the same signature.
+ *
+ * Usage:
+ *   const trackedFn = trackFunction(ledger, {
+ *     agent: 'my-bot',
+ *     service: 'slack',
+ *     action: 'send_message',
+ *   }, slackSendMessage);
+ *
+ *   await trackedFn('#general', 'Hello!');
+ */
+export declare function trackFunction<TArgs extends unknown[], TResult>(ledger: AgentLedger, options: Pick<TrackOptions, 'agent' | 'service' | 'action'>, fn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
+interface ExpressRequest {
+    method: string;
+    path?: string;
+    url?: string;
+    [key: string]: unknown;
+}
+interface ExpressResponse {
+    statusCode: number;
+    end: (...args: unknown[]) => ExpressResponse;
+    [key: string]: unknown;
+}
+type NextFunction = (err?: unknown) => void;
+export {};

package/dist/integrations/express.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * AgentLedger Express middleware and generic HTTP integration.
+ *
+ * Usage with Express:
+ *   import { AgentLedger } from '@agentledger/sdk';
+ *   import { agentLedgerMiddleware } from '@agentledger/sdk/integrations/express';
+ *
+ *   const ledger = new AgentLedger({ apiKey: 'al_...' });
+ *
+ *   // Track all requests to a specific route
+ *   app.post('/api/agent/send-email', agentLedgerMiddleware(ledger, {
+ *     agent: 'email-bot',
+ *     service: 'sendgrid',
+ *     action: 'send_email',
+ *   }), (req, res) => {
+ *     // your handler
+ *   });
+ *
+ *   // Or track all routes with auto-detection
+ *   app.use('/api/agent', agentLedgerMiddleware(ledger, {
+ *     agent: 'my-agent',
+ *     autoDetect: true, // uses req.path as action, req.method as metadata
+ *   }));
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentLedgerMiddleware = agentLedgerMiddleware;
+exports.trackFunction = trackFunction;
+/**
+ * Express-compatible middleware that tracks requests as agent actions.
+ */
+function agentLedgerMiddleware(ledger, config) {
+    return async (req, res, next) => {
+        const start = Date.now();
+        // Determine service/action
+        let service = config.service || 'http';
+        let action = config.action || 'request';
+        if (config.autoDetect) {
+            // /api/agent/send-email → service: 'agent', action: 'send-email'
+            const pathParts = (req.path || req.url || '').split('/').filter(Boolean);
+            if (pathParts.length >= 2) {
+                service = pathParts[pathParts.length - 2] || service;
+                action = pathParts[pathParts.length - 1] || action;
+            }
+            else if (pathParts.length === 1) {
+                action = pathParts[0] || action;
+            }
+        }
+        // Hook into response finish to log with timing
+        const originalEnd = res.end.bind(res);
+        let logged = false;
+        res.end = function (...args) {
+            if (!logged) {
+                logged = true;
+                const durationMs = Date.now() - start;
+                const status = res.statusCode >= 400 ? 'error' : 'success';
+                const costCents = config.costExtractor ? config.costExtractor(req, res) : 0;
+                // Fire and forget — don't block the response
+                ledger.log({
+                    agent: config.agent,
+                    service,
+                    action,
+                    status,
+                    durationMs,
+                    costCents,
+                    metadata: {
+                        source: 'express',
+                        method: req.method,
+                        path: req.path || req.url,
+                        statusCode: res.statusCode,
+                    },
+                }).catch(() => { }); // fail-open
+            }
+            return originalEnd(...args);
+        };
+        next();
+    };
+}
+/**
+ * Simple wrapper for any async function — no Express dependency needed.
+ * Wraps a function with AgentLedger tracking and returns a new function
+ * with the same signature.
+ *
+ * Usage:
+ *   const trackedFn = trackFunction(ledger, {
+ *     agent: 'my-bot',
+ *     service: 'slack',
+ *     action: 'send_message',
+ *   }, slackSendMessage);
+ *
+ *   await trackedFn('#general', 'Hello!');
+ */
+function trackFunction(ledger, options, fn) {
+    return async (...args) => {
+        const { result } = await ledger.track({
+            agent: options.agent,
+            service: options.service,
+            action: options.action,
+            metadata: { source: 'tracked-function' },
+        }, () => fn(...args));
+        return result;
+    };
+}

package/dist/integrations/index.d.ts

@@ -0,0 +1,7 @@
+export { AgentLedgerCallbackHandler } from './langchain';
+export type { AgentLedgerCallbackConfig } from './langchain';
+export { withAgentLedger, createToolExecutor, wrapOpenAICompletion } from './openai';
+export { wrapMCPServer, wrapMCPTool } from './mcp';
+export type { MCPWrapConfig } from './mcp';
+export { agentLedgerMiddleware, trackFunction } from './express';
+export type { MiddlewareConfig } from './express';

package/dist/integrations/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackFunction = exports.agentLedgerMiddleware = exports.wrapMCPTool = exports.wrapMCPServer = exports.wrapOpenAICompletion = exports.createToolExecutor = exports.withAgentLedger = exports.AgentLedgerCallbackHandler = void 0;
+var langchain_1 = require("./langchain");
+Object.defineProperty(exports, "AgentLedgerCallbackHandler", { enumerable: true, get: function () { return langchain_1.AgentLedgerCallbackHandler; } });
+var openai_1 = require("./openai");
+Object.defineProperty(exports, "withAgentLedger", { enumerable: true, get: function () { return openai_1.withAgentLedger; } });
+Object.defineProperty(exports, "createToolExecutor", { enumerable: true, get: function () { return openai_1.createToolExecutor; } });
+Object.defineProperty(exports, "wrapOpenAICompletion", { enumerable: true, get: function () { return openai_1.wrapOpenAICompletion; } });
+var mcp_1 = require("./mcp");
+Object.defineProperty(exports, "wrapMCPServer", { enumerable: true, get: function () { return mcp_1.wrapMCPServer; } });
+Object.defineProperty(exports, "wrapMCPTool", { enumerable: true, get: function () { return mcp_1.wrapMCPTool; } });
+var express_1 = require("./express");
+Object.defineProperty(exports, "agentLedgerMiddleware", { enumerable: true, get: function () { return express_1.agentLedgerMiddleware; } });
+Object.defineProperty(exports, "trackFunction", { enumerable: true, get: function () { return express_1.trackFunction; } });

package/dist/integrations/langchain.d.ts

@@ -0,0 +1,54 @@
+/**
+ * AgentLedger integration for LangChain.
+ *
+ * Usage:
+ *   import { AgentLedger } from '@agentledger/sdk';
+ *   import { AgentLedgerCallbackHandler } from '@agentledger/sdk/integrations/langchain';
+ *
+ *   const ledger = new AgentLedger({ apiKey: 'al_...' });
+ *   const handler = new AgentLedgerCallbackHandler(ledger, { agent: 'my-agent' });
+ *
+ *   const chain = new ChatOpenAI({ callbacks: [handler] });
+ *   // or
+ *   await agent.invoke({ input: '...' }, { callbacks: [handler] });
+ */
+import type { AgentLedger } from '../index';
+interface Serialized {
+    id?: string[];
+    name?: string;
+    [key: string]: unknown;
+}
+export interface AgentLedgerCallbackConfig {
+    /** Name of the agent in AgentLedger */
+    agent: string;
+    /** Map LangChain tool names to AgentLedger services. Default: tool name becomes both service and action */
+    serviceMap?: Record<string, {
+        service: string;
+        action?: string;
+    }>;
+    /** Whether to track LLM calls (tokens/cost). Default: true */
+    trackLLM?: boolean;
+    /** Whether to track tool calls. Default: true */
+    trackTools?: boolean;
+    /** Whether to track chain/agent runs. Default: false */
+    trackChains?: boolean;
+}
+export declare class AgentLedgerCallbackHandler {
+    name: string;
+    private ledger;
+    private config;
+    private runTimers;
+    constructor(ledger: AgentLedger, config: AgentLedgerCallbackConfig);
+    handleToolStart(tool: Serialized, input: string, runId: string): Promise<void>;
+    handleToolEnd(output: string, runId: string): Promise<void>;
+    handleToolError(err: Error, runId: string): Promise<void>;
+    handleLLMStart(llm: Serialized, prompts: string[], runId: string): Promise<void>;
+    handleLLMEnd(output: unknown, runId: string): Promise<void>;
+    handleLLMError(err: Error, runId: string): Promise<void>;
+    handleChainStart(chain: Serialized, inputs: Record<string, unknown>, runId: string): Promise<void>;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void>;
+    handleChainError(err: Error, runId: string): Promise<void>;
+    private toolNameStore;
+    private extractToolName;
+}
+export {};

package/dist/integrations/langchain.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * AgentLedger integration for LangChain.
+ *
+ * Usage:
+ *   import { AgentLedger } from '@agentledger/sdk';
+ *   import { AgentLedgerCallbackHandler } from '@agentledger/sdk/integrations/langchain';
+ *
+ *   const ledger = new AgentLedger({ apiKey: 'al_...' });
+ *   const handler = new AgentLedgerCallbackHandler(ledger, { agent: 'my-agent' });
+ *
+ *   const chain = new ChatOpenAI({ callbacks: [handler] });
+ *   // or
+ *   await agent.invoke({ input: '...' }, { callbacks: [handler] });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentLedgerCallbackHandler = void 0;
+class AgentLedgerCallbackHandler {
+    constructor(ledger, config) {
+        this.name = 'AgentLedgerCallbackHandler';
+        this.runTimers = new Map();
+        // ==================== HELPERS ====================
+        this.toolNameStore = new Map();
+        this.ledger = ledger;
+        this.config = {
+            trackLLM: true,
+            trackTools: true,
+            trackChains: false,
+            ...config,
+        };
+    }
+    // ==================== TOOL CALLS ====================
+    async handleToolStart(tool, input, runId) {
+        if (!this.config.trackTools)
+            return;
+        this.runTimers.set(runId, Date.now());
+    }
+    async handleToolEnd(output, runId) {
+        if (!this.config.trackTools)
+            return;
+        const startTime = this.runTimers.get(runId);
+        const durationMs = startTime ? Date.now() - startTime : 0;
+        this.runTimers.delete(runId);
+        // Extract tool name from runId context (stored during handleToolStart)
+        const toolName = this.extractToolName(runId) || 'unknown_tool';
+        const mapped = this.config.serviceMap?.[toolName];
+        await this.ledger.log({
+            agent: this.config.agent,
+            service: mapped?.service || toolName,
+            action: mapped?.action || 'invoke',
+            durationMs,
+            metadata: { source: 'langchain', runId, outputLength: output?.length },
+        }).catch(() => { }); // fail-open
+    }
+    async handleToolError(err, runId) {
+        if (!this.config.trackTools)
+            return;
+        const startTime = this.runTimers.get(runId);
+        const durationMs = startTime ? Date.now() - startTime : 0;
+        this.runTimers.delete(runId);
+        const toolName = this.extractToolName(runId) || 'unknown_tool';
+        const mapped = this.config.serviceMap?.[toolName];
+        await this.ledger.log({
+            agent: this.config.agent,
+            service: mapped?.service || toolName,
+            action: mapped?.action || 'invoke',
+            status: 'error',
+            durationMs,
+            metadata: { source: 'langchain', runId, error: err.message },
+        }).catch(() => { });
+    }
+    // ==================== LLM CALLS ====================
+    async handleLLMStart(llm, prompts, runId) {
+        if (!this.config.trackLLM)
+            return;
+        this.runTimers.set(runId, Date.now());
+    }
+    async handleLLMEnd(output, runId) {
+        if (!this.config.trackLLM)
+            return;
+        const startTime = this.runTimers.get(runId);
+        const durationMs = startTime ? Date.now() - startTime : 0;
+        this.runTimers.delete(runId);
+        // Try to extract token usage and model info
+        const llmOutput = output;
+        const tokenUsage = llmOutput?.llmOutput?.tokenUsage;
+        const model = llmOutput?.llmOutput?.modelName;
+        // Estimate cost from tokens (rough: $0.01 per 1K tokens for GPT-4 class)
+        const totalTokens = tokenUsage?.totalTokens || 0;
+        const estimatedCostCents = Math.ceil(totalTokens * 0.001);
+        await this.ledger.log({
+            agent: this.config.agent,
+            service: model?.includes('claude') ? 'anthropic' : model?.includes('gpt') ? 'openai' : 'llm',
+            action: 'completion',
+            costCents: estimatedCostCents,
+            durationMs,
+            metadata: { source: 'langchain', runId, model, tokenUsage },
+        }).catch(() => { });
+    }
+    async handleLLMError(err, runId) {
+        if (!this.config.trackLLM)
+            return;
+        const startTime = this.runTimers.get(runId);
+        const durationMs = startTime ? Date.now() - startTime : 0;
+        this.runTimers.delete(runId);
+        await this.ledger.log({
+            agent: this.config.agent,
+            service: 'llm',
+            action: 'completion',
+            status: 'error',
+            durationMs,
+            metadata: { source: 'langchain', runId, error: err.message },
+        }).catch(() => { });
+    }
+    // ==================== CHAIN/AGENT RUNS ====================
+    async handleChainStart(chain, inputs, runId) {
+        if (!this.config.trackChains)
+            return;
+        this.runTimers.set(runId, Date.now());
+    }
+    async handleChainEnd(outputs, runId) {
+        if (!this.config.trackChains)
+            return;
+        const startTime = this.runTimers.get(runId);
+        const durationMs = startTime ? Date.now() - startTime : 0;
+        this.runTimers.delete(runId);
+        await this.ledger.log({
+            agent: this.config.agent,
+            service: 'langchain',
+            action: 'chain_run',
+            durationMs,
+            metadata: { source: 'langchain', runId },
+        }).catch(() => { });
+    }
+    async handleChainError(err, runId) {
+        if (!this.config.trackChains)
+            return;
+        const startTime = this.runTimers.get(runId);
+        const durationMs = startTime ? Date.now() - startTime : 0;
+        this.runTimers.delete(runId);
+        await this.ledger.log({
+            agent: this.config.agent,
+            service: 'langchain',
+            action: 'chain_run',
+            status: 'error',
+            durationMs,
+            metadata: { source: 'langchain', runId, error: err.message },
+        }).catch(() => { });
+    }
+    extractToolName(runId) {
+        return this.toolNameStore.get(runId);
+    }
+}
+exports.AgentLedgerCallbackHandler = AgentLedgerCallbackHandler;

package/dist/integrations/mcp.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AgentLedger integration for MCP (Model Context Protocol) servers.
+ *
+ * Wraps MCP tool handlers so every tool invocation is logged.
+ *
+ * Usage with @modelcontextprotocol/sdk:
+ *
+ *   import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+ *   import { AgentLedger } from '@agentledger/sdk';
+ *   import { wrapMCPServer } from '@agentledger/sdk/integrations/mcp';
+ *
+ *   const ledger = new AgentLedger({ apiKey: 'al_...' });
+ *   const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+ *
+ *   // Register tools normally
+ *   server.tool('send_email', { to: z.string(), body: z.string() }, async (args) => {
+ *     return await sendEmail(args.to, args.body);
+ *   });
+ *
+ *   // Wrap the server — all tool calls are now logged
+ *   wrapMCPServer(ledger, server, { agent: 'my-mcp-server' });
+ */
+import type { AgentLedger } from '../index';
+export interface MCPWrapConfig {
+    /** Agent name in AgentLedger */
+    agent: string;
+    /** Map tool names to AgentLedger service/action. Default: tool name as service, 'invoke' as action */
+    serviceMap?: Record<string, {
+        service: string;
+        action?: string;
+    }>;
+}
+/**
+ * Wraps an MCP server instance to log all tool invocations.
+ * Works by monkey-patching the tool registration method.
+ *
+ * Compatible with @modelcontextprotocol/sdk McpServer.
+ */
+export declare function wrapMCPServer(ledger: AgentLedger, server: MCPServerLike, config: MCPWrapConfig): void;
+/**
+ * Alternative: wrap a single MCP tool handler function directly.
+ *
+ * Usage:
+ *   server.tool('send_email', schema, wrapMCPTool(ledger, {
+ *     agent: 'my-server',
+ *     service: 'sendgrid',
+ *     action: 'send_email',
+ *   }, async (args) => {
+ *     return await sendEmail(args.to, args.body);
+ *   }));
+ */
+export declare function wrapMCPTool<TArgs, TResult>(ledger: AgentLedger, options: {
+    agent: string;
+    service: string;
+    action: string;
+}, handler: (args: TArgs) => Promise<TResult>): (args: TArgs) => Promise<TResult>;
+/**
+ * Minimal interface for MCP server compatibility.
+ * We don't import @modelcontextprotocol/sdk to keep zero dependencies.
+ */
+interface MCPServerLike {
+    tool: (name: string, ...args: unknown[]) => unknown;
+}
+export {};

package/dist/integrations/mcp.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * AgentLedger integration for MCP (Model Context Protocol) servers.
+ *
+ * Wraps MCP tool handlers so every tool invocation is logged.
+ *
+ * Usage with @modelcontextprotocol/sdk:
+ *
+ *   import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+ *   import { AgentLedger } from '@agentledger/sdk';
+ *   import { wrapMCPServer } from '@agentledger/sdk/integrations/mcp';
+ *
+ *   const ledger = new AgentLedger({ apiKey: 'al_...' });
+ *   const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+ *
+ *   // Register tools normally
+ *   server.tool('send_email', { to: z.string(), body: z.string() }, async (args) => {
+ *     return await sendEmail(args.to, args.body);
+ *   });
+ *
+ *   // Wrap the server — all tool calls are now logged
+ *   wrapMCPServer(ledger, server, { agent: 'my-mcp-server' });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapMCPServer = wrapMCPServer;
+exports.wrapMCPTool = wrapMCPTool;
+/**
+ * Wraps an MCP server instance to log all tool invocations.
+ * Works by monkey-patching the tool registration method.
+ *
+ * Compatible with @modelcontextprotocol/sdk McpServer.
+ */
+function wrapMCPServer(ledger, server, config) {
+    const originalTool = server.tool.bind(server);
+    server.tool = function wrappedTool(name, ...rest) {
+        // tool(name, schema, handler) or tool(name, description, schema, handler)
+        // The handler is always the last argument
+        const handler = rest[rest.length - 1];
+        const otherArgs = rest.slice(0, -1);
+        const wrappedHandler = async (...handlerArgs) => {
+            const mapped = config.serviceMap?.[name];
+            const { result } = await ledger.track({
+                agent: config.agent,
+                service: mapped?.service || name,
+                action: mapped?.action || 'invoke',
+                metadata: {
+                    source: 'mcp',
+                    toolName: name,
+                    argsPreview: JSON.stringify(handlerArgs[0]).slice(0, 500),
+                },
+            }, () => handler(...handlerArgs));
+            return result;
+        };
+        return originalTool(name, ...otherArgs, wrappedHandler);
+    };
+}
+/**
+ * Alternative: wrap a single MCP tool handler function directly.
+ *
+ * Usage:
+ *   server.tool('send_email', schema, wrapMCPTool(ledger, {
+ *     agent: 'my-server',
+ *     service: 'sendgrid',
+ *     action: 'send_email',
+ *   }, async (args) => {
+ *     return await sendEmail(args.to, args.body);
+ *   }));
+ */
+function wrapMCPTool(ledger, options, handler) {
+    return async (args) => {
+        const { result } = await ledger.track({
+            agent: options.agent,
+            service: options.service,
+            action: options.action,
+            metadata: {
+                source: 'mcp',
+                argsPreview: JSON.stringify(args).slice(0, 500),
+            },
+        }, () => handler(args));
+        return result;
+    };
+}

package/dist/integrations/openai.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AgentLedger integration for the OpenAI Agents SDK.
+ *
+ * Wraps tool functions so every tool invocation is automatically logged.
+ *
+ * Usage:
+ *   import { AgentLedger } from '@agentledger/sdk';
+ *   import { withAgentLedger } from '@agentledger/sdk/integrations/openai';
+ *
+ *   const ledger = new AgentLedger({ apiKey: 'al_...' });
+ *
+ *   // Wrap individual tool functions
+ *   const trackedSendEmail = withAgentLedger(ledger, {
+ *     agent: 'support-bot',
+ *     service: 'sendgrid',
+ *     action: 'send_email',
+ *   }, sendEmail);
+ *
+ *   // Or wrap an entire tools array
+ *   const tools = wrapOpenAITools(ledger, 'my-agent', [
+ *     { type: 'function', function: { name: 'send_email', ... } }
+ *   ]);
+ */
+import type { AgentLedger, TrackOptions } from '../index';
+/**
+ * Wraps a single async function with AgentLedger tracking.
+ * The function signature is preserved — drop-in replacement.
+ */
+export declare function withAgentLedger<TArgs extends unknown[], TResult>(ledger: AgentLedger, options: Pick<TrackOptions, 'agent' | 'service' | 'action'>, fn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
+/**
+ * Map of tool names to their handler functions.
+ */
+type ToolHandlers = Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
+/**
+ * Service mapping: how to categorize each tool for AgentLedger tracking.
+ * If a tool isn't in the map, its name is used as both service and action.
+ */
+type ServiceMap = Record<string, {
+    service: string;
+    action?: string;
+}>;
+/**
+ * Creates a tool execution wrapper that logs all tool calls to AgentLedger.
+ *
+ * Usage:
+ *   const executeTools = createToolExecutor(ledger, 'my-agent', {
+ *     send_email: sendEmailFn,
+ *     create_ticket: createTicketFn,
+ *   }, {
+ *     send_email: { service: 'sendgrid', action: 'send' },
+ *     create_ticket: { service: 'jira', action: 'create_issue' },
+ *   });
+ *
+ *   // In your OpenAI agent loop:
+ *   for (const toolCall of message.tool_calls) {
+ *     const result = await executeTools(toolCall.function.name, JSON.parse(toolCall.function.arguments));
+ *   }
+ */
+export declare function createToolExecutor(ledger: AgentLedger, agent: string, handlers: ToolHandlers, serviceMap?: ServiceMap): (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Convenience: wraps the OpenAI chat.completions.create call itself to track LLM usage.
+ */
+export declare function wrapOpenAICompletion<TArgs extends unknown[], TResult>(ledger: AgentLedger, agent: string, createFn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
+export {};

package/dist/integrations/openai.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * AgentLedger integration for the OpenAI Agents SDK.
+ *
+ * Wraps tool functions so every tool invocation is automatically logged.
+ *
+ * Usage:
+ *   import { AgentLedger } from '@agentledger/sdk';
+ *   import { withAgentLedger } from '@agentledger/sdk/integrations/openai';
+ *
+ *   const ledger = new AgentLedger({ apiKey: 'al_...' });
+ *
+ *   // Wrap individual tool functions
+ *   const trackedSendEmail = withAgentLedger(ledger, {
+ *     agent: 'support-bot',
+ *     service: 'sendgrid',
+ *     action: 'send_email',
+ *   }, sendEmail);
+ *
+ *   // Or wrap an entire tools array
+ *   const tools = wrapOpenAITools(ledger, 'my-agent', [
+ *     { type: 'function', function: { name: 'send_email', ... } }
+ *   ]);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAgentLedger = withAgentLedger;
+exports.createToolExecutor = createToolExecutor;
+exports.wrapOpenAICompletion = wrapOpenAICompletion;
+/**
+ * Wraps a single async function with AgentLedger tracking.
+ * The function signature is preserved — drop-in replacement.
+ */
+function withAgentLedger(ledger, options, fn) {
+    return async (...args) => {
+        const { result } = await ledger.track({
+            agent: options.agent,
+            service: options.service,
+            action: options.action,
+            metadata: {
+                source: 'openai-agents',
+                argsPreview: JSON.stringify(args).slice(0, 500),
+            },
+        }, () => fn(...args));
+        return result;
+    };
+}
+/**
+ * Creates a tool execution wrapper that logs all tool calls to AgentLedger.
+ *
+ * Usage:
+ *   const executeTools = createToolExecutor(ledger, 'my-agent', {
+ *     send_email: sendEmailFn,
+ *     create_ticket: createTicketFn,
+ *   }, {
+ *     send_email: { service: 'sendgrid', action: 'send' },
+ *     create_ticket: { service: 'jira', action: 'create_issue' },
+ *   });
+ *
+ *   // In your OpenAI agent loop:
+ *   for (const toolCall of message.tool_calls) {
+ *     const result = await executeTools(toolCall.function.name, JSON.parse(toolCall.function.arguments));
+ *   }
+ */
+function createToolExecutor(ledger, agent, handlers, serviceMap) {
+    return async (toolName, args) => {
+        const handler = handlers[toolName];
+        if (!handler) {
+            throw new Error(`Unknown tool: ${toolName}`);
+        }
+        const mapped = serviceMap?.[toolName];
+        const { result } = await ledger.track({
+            agent,
+            service: mapped?.service || toolName,
+            action: mapped?.action || 'invoke',
+            metadata: {
+                source: 'openai-agents',
+                toolName,
+                argsPreview: JSON.stringify(args).slice(0, 500),
+            },
+        }, () => handler(args));
+        return result;
+    };
+}
+/**
+ * Convenience: wraps the OpenAI chat.completions.create call itself to track LLM usage.
+ */
+function wrapOpenAICompletion(ledger, agent, createFn) {
+    return withAgentLedger(ledger, { agent, service: 'openai', action: 'completion' }, createFn);
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "agentledger",
+  "version": "0.3.0",
+  "description": "Track, monitor, and control AI agent actions. The missing observability layer for AI agents. Zero dependencies.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./integrations/langchain": {
+      "import": "./dist/integrations/langchain.js",
+      "types": "./dist/integrations/langchain.d.ts"
+    },
+    "./integrations/openai": {
+      "import": "./dist/integrations/openai.js",
+      "types": "./dist/integrations/openai.d.ts"
+    },
+    "./integrations/mcp": {
+      "import": "./dist/integrations/mcp.js",
+      "types": "./dist/integrations/mcp.d.ts"
+    },
+    "./integrations/express": {
+      "import": "./dist/integrations/express.js",
+      "types": "./dist/integrations/express.d.ts"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai", "agents", "monitoring", "observability", "langchain", "openai",
+    "mcp", "safety", "llm", "ai-agents", "kill-switch", "budget",
+    "cost-tracking", "anthropic", "claude"
+  ],
+  "author": "AgentLedger",
+  "license": "MIT",
+  "homepage": "https://agentledger.co",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mnoonan/agentledger"
+  },
+  "bugs": {
+    "url": "https://github.com/mnoonan/agentledger/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}