@relayplane/ledger

Learning Ledger — the immutable event store for agent operations.

Overview

The Ledger is the foundation of RelayPlane Agent Ops, capturing every run with full context including:

• Auth tracking: auth_type, execution_mode, auth_risk, policy_override, compliance_mode
• Metrics: latency_ms, ttft_ms, input_tokens, output_tokens, cost_usd
• Decision audit: Policy decisions, routing decisions, error details
• Event log: Append-only event stream for each run

Installation

pnpm add @relayplane/ledger

Quick Start

import { createLedger } from '@relayplane/ledger';

const ledger = createLedger();

// Start a run
const runId = await ledger.startRun({
  workspace_id: 'ws_123',
  agent_id: 'agent_456',
  provider: 'anthropic',
  model: 'claude-3-5-sonnet',
  auth_type: 'api',
  execution_mode: 'interactive',
  compliance_mode: 'recommended',
});

// Complete the run with metrics
await ledger.completeRun(runId, {
  status: 'completed',
  input_tokens: 1000,
  output_tokens: 500,
  total_tokens: 1500,
  cost_usd: 0.015,
  latency_ms: 2500,
  ttft_ms: 150,
});

// Query runs
const runs = await ledger.queryRuns({
  workspace_id: 'ws_123',
  auth_type: 'consumer',
  execution_mode: 'background',
});

// Get usage statistics
const stats = await ledger.getUsageStats('ws_123', '2024-01-01', '2024-12-31');
console.log(`Auth risk runs: ${stats.auth_risk_runs}`);

Auth Risk Tracking

The Ledger tracks auth risk for compliance monitoring:

| Field | Description | |-------|-------------| | auth_type | 'api' or 'consumer' | | execution_mode | 'interactive', 'background', or 'scheduled' | | auth_risk | true if consumer auth used in non-interactive mode | | policy_override | true if user explicitly overrode restrictions | | compliance_mode | 'recommended' or 'permissive' at time of run |

Event Types

The ledger captures these event types:

• run.started — Run initiated
• run.auth_validated — Auth check completed
• run.policy_evaluated — Policies evaluated
• run.routed — Provider/model selected
• run.provider_called — Request sent to provider
• run.completed — Run finished successfully
• run.failed — Run failed
• run.retried — Retry attempted
• run.cancelled — Run cancelled

Storage Backends

SQLite (default)

Local-first storage using SQLite with WAL mode:

import { createLedger, getDefaultLedgerPath } from '@relayplane/ledger';

// Default: ~/.relayplane/ledger.db
const ledger = createLedger();

// Custom path
const ledger = createLedger({ dbPath: '/path/to/ledger.db' });

Postgres (coming in Phase 2)

For cloud deployments with Supabase:

// Coming soon
import { createLedger, PostgresLedger } from '@relayplane/ledger';

const ledger = createLedger({
  storage: new PostgresLedger({ connectionString: '...' }),
});

API Reference

Ledger Class

Run Lifecycle

• startRun(options) — Start a new run, returns run_id
• completeRun(run_id, options) — Complete a run with metrics
• recordAuthValidation(run_id, payload) — Record auth check result
• recordPolicyEvaluation(run_id, decisions) — Record policy decisions
• recordRouting(run_id, decision) — Record routing decision
• recordProviderCall(run_id, payload) — Record provider call timing
• recordRetry(run_id, payload) — Record retry attempt

Queries

• getRun(run_id) — Get single run by ID
• queryRuns(options) — Query runs with filters
• countRuns(options) — Count matching runs
• getRunEvents(run_id) — Get all events for a run
• queryEvents(options) — Query events with filters
• getUsageStats(workspace_id, from, to) — Get usage statistics

License

MIT