Audit & Replay Logger

Type: Local Logger / API / MCP / Dashboard

Value: Records explicitly logged agent decisions, tool calls, state changes, messages, and errors so teams can replay and debug what happened locally.

Current Status

Complete as a local SDK / MCP / HTTP logger slice. It persists explicitly logged events, supports replay/export, and provides local tamper-evidence through event and bundle hashes.

Shipped Local Scope

• SDK logger for sessions, decisions, tool calls, tool results, state changes, messages, errors, and session end events
• Durable local JSON audit store with configurable path
• Event sequence numbers, timestamps, causal links, event hashes, and hash-chain continuity
• Redaction for common sensitive fields such as tokens, secrets, passwords, credentials, authorization headers, and API keys
• Replay filtering by sequence range, event type, and actor
• Causal-chain lookup by event id
• Exportable replay bundle with event hashes, causal chains, and bundle hash
• Local HTTP API plus lightweight dashboard page
• MCP tools for logging, replay, causal-chain lookup, export, and session listing
• Package bins and subpath exports for SDK, MCP, and HTTP usage

Install And Run

npm install
npm test
npm run mcp
npm run serve

After build, the package exposes:

audit-replay-mcp
audit-replay-api

Local Store

By default, the logger writes to:

.audit-replay-logger/audit-log.json

Override with either:

AUDIT_REPLAY_LOGGER_STORE_PATH=/path/to/audit-log.json
AUDIT_REPLAY_LOGGER_STORE=/path/to/audit-log.json

Pass storePath: null to createAuditLogger only when you intentionally want an in-memory logger.

MCP bundle exports are confined to a local export directory. By default that is:

.audit-replay-logger/exports

Override with:

AUDIT_REPLAY_LOGGER_EXPORT_DIR=/path/to/exports

SDK Surface

import { createAuditLogger } from '@blair/audit-replay-logger';

const audit = createAuditLogger({ storePath: './audit-log.json' });
const session = audit.startSession({ actor: 'agent', metadata: { task: 'refund-review' } });

const decision = audit.logDecision(session.id, {
  actor: 'agent',
  decision: 'request human review',
  reasoning: 'confidence gate returned review'
});

audit.logToolCall(session.id, {
  actor: 'agent',
  tool: 'confidence_gate',
  input: { action: 'refund customer', token: 'will be redacted' },
  causedBy: decision.id
});

const timeline = audit.replay(session.id);

HTTP API

GET  /dashboard
GET  /health
POST /api/sessions
GET  /api/sessions
GET  /api/sessions/:id
POST /api/sessions/:id/events
GET  /api/sessions/:id/replay
GET  /api/sessions/:id/causal-chain/:eventId
GET  /api/sessions/:id/bundle

The server binds locally by default when run through:

npm run serve

MCP Tools

• start_session
• end_session
• log_event
• log_decision
• log_tool_call
• log_tool_result
• log_state_change
• replay_session
• causal_chain
• list_sessions
• export_bundle

Current Limits

• This is a local product slice, not hosted SaaS.
• The logger records events explicitly sent through the SDK, MCP tools, or local HTTP API; it does not automatically observe every agent action.
• Hashes and bundle hashes provide local tamper evidence, not a notarized compliance ledger.
• There is no public npm publication, live checkout, user auth, team workspace, hosted retention policy, signed export, WORM storage, or compliance certification yet.
• The dashboard is a lightweight local API landing page, not a full visual replay timeline UI.

Verification

Fresh suite verification on 2026-05-28:

• npm test passed, 25/25 SDK, persistence, redaction, MCP, HTTP, and package contract tests.
• npm run build passes.
• Package dry-run verifies only runtime artifacts and README are included.