Package Exports

@relayplane/ledger
@relayplane/ledger/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@relayplane/ledger) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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