Start a local audit session
Create a session with an actor and optional metadata. The logger writes to
.audit-replay-logger/audit-log.json
by default, or to a configured local store path.
Product 08 · Logger / API / MCP / Dashboard · Local Slice
Audit & Replay Logger
Agents make decisions, call tools, and change state. Audit & Replay Logger captures the events you explicitly send it, redacts sensitive payload fields, links causes together, and exports a local replay bundle so teams can understand what actually happened.
Local product slice — Hosted audit cloud is not live yet
The Problem
Agent work is hard to trust when the trail is missing.
A model can produce a useful final answer while leaving the team unsure which decision triggered which tool call, which payload was sent, whether sensitive fields were exposed, or how a failed state change affected the rest of the session.
Ordinary logs help with raw output, but agent systems need a clearer account: ordered events, causal links, redacted payloads, event hashes, and replay exports that can be reviewed without relying on a hosted service.
Audit & Replay Logger adds that local account. It records explicitly logged sessions, decisions, tool calls, tool results, state changes, messages, errors, and session-end events, then lets teams replay the sequence or inspect the causal chain behind one event.
How It Works
Record → Chain → Replay
Log events with causal links
Record decisions, tool calls, tool results, state changes, messages, and errors.
Each event gets a sequence number, timestamp, hash, and previous hash. Optional
causedBy links connect events.
Replay or export the evidence
Filter replay timelines by event type, sequence range, or actor. Trace one event's causal chain, or export a replay bundle containing event hashes, causal chains, and a bundle hash for local review.
The logger records what the SDK, MCP tools, or HTTP API explicitly receive. It does not automatically observe every agent action.
Hash-chain events provide local tamper evidence, not notarized compliance storage, WORM retention, legal review, or certification.
Audit Signals
What the audit record contains
The fields below match the local logger's event and bundle model: ordered events, redacted payloads, causal chains, and exportable replay bundles.
| Signal | Source field | Values | Description |
|---|---|---|---|
| Event type | type | decision / tool_call / tool_result / state_change / message / error | Classifies what happened in the session timeline. |
| Sequence | seq | integer | Orders session events from the session_start event onward. |
| Hash-chain audit trail | hash / previousHash | sha256 | Links each event to the previous event hash for local tamper-evidence. |
| Causal chains | causedBy | event id | Connects decisions to downstream tool calls, results, and state changes. |
| Redaction | payload | [REDACTED] | Common secret, token, credential, password, authorization, and API-key fields are redacted before storage. |
| Replay bundles | bundleHash | sha256 | Export bundles include the session, events, causal-chain map, and bundle hash. |
Replay filters currently support sequence range, event type, and actor. Bundle exports are confined to a configured local export directory by the MCP server.
Local Install
SDK, MCP server, and local HTTP API
Audit & Replay Logger ships as a local Node package with SDK exports, an MCP server, and a local HTTP API. Use the SDK in process, connect MCP-compatible tools to the server, or run the local API for dashboard and replay endpoints.
The local HTTP API defaults to
http://127.0.0.1:4319/dashboard
after running
npm run serve.
npm package
npm install -g @certaworks/audit-replay-logger
SDK usage
import { createAuditLogger } from '@certaworks/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: 'redacted' },
causedBy: decision.id
});
const timeline = audit.replay(session.id);
Claude Desktop config
{
"mcpServers": {
"audit-replay-logger": {
"command": "npx",
"args": ["-y", "-p", "@certaworks/audit-replay-logger", "audit-replay-mcp"]
}
}
}
MCP Interface
Available MCP tools
Audit & Replay Logger exposes these tools to any MCP-compatible agent runtime. Tool
names match the TOOLS array in
src/mcp/server.ts exactly.
Sessions
start_session
Start a new audit session. Returns the session ID to use for future event logging.
end_session
End an audit session and append a session_end event to the local timeline.
list_sessions
List local audit sessions with ID, timestamps, end status, and metadata.
Event Logging
log_event
Record an arbitrary audit event with redacted payload and hash-chain continuity.
log_decision
Record an agent decision with reasoning, alternatives, and optional causal parent event.
log_tool_call
Record a tool invocation, including redacted input payload and optional caused_by link.
log_tool_result
Record a tool result, duration, output payload, and causal link back to the call.
log_state_change
Record a before/after state transition under a named key.
Replay & Export
replay_session
Replay events with optional filters for sequence range, event type, and actor.
causal_chain
Trace the causal chain leading to a specific event ID.
export_bundle
Export a session replay bundle to a safe local path inside the configured export directory.
Dashboard & API
Local dashboard — prototype status
Audit & Replay Logger includes a local HTTP API and lightweight dashboard landing page. The dashboard lists the local replay endpoints and requires no cloud connection.
The API supports session creation, session listing, direct event logging, replay retrieval,
causal-chain lookup, and replay-bundle export through local endpoints such as
GET /api/sessions/:id/replay
and
GET /api/sessions/:id/bundle.
Roadmap — not currently built
Hosted SaaS audit cloud, team accounts, user auth, signed exports, managed retention, WORM storage, compliance certification, and a full visual replay timeline UI are roadmap items. They are not currently built or available. What is available today is the local SDK, MCP server, HTTP API, durable JSON store, and lightweight local dashboard page.
Scope
What Audit & Replay Logger does and does not do
Does
- Store durable local sessions with explicitly logged events and metadata
- Record event sequence numbers, timestamps, event hashes, and previous-hash links
- Redact common secret, password, token, authorization, credential, and API-key fields
- Replay sessions by sequence range, event type, or actor
- Return causal chains for specific event IDs
- Export replay bundles with event hashes, causal chains, and a bundle hash
Does Not
- Provide hosted SaaS audit storage, team accounts, user auth, or managed retention (roadmap)
- Automatically observe every agent action — events must be explicitly logged through SDK, MCP, or HTTP API
- Provide notarized compliance storage, WORM retention, legal certification, or signed exports yet
- Guarantee that every sensitive value is redacted; teams should review custom payload schemas
- Provide a full visual replay timeline UI; the dashboard is a lightweight local landing page
- Replace security, legal, compliance, or human review processes
Related Products
Hosted Beta
Get early access to hosted Audit & Replay
The local SDK, MCP server, and HTTP API are available now for private testing. Hosted beta with cloud audit history, shared team review, signed export workflows, and longer retention is in development. Leave your details and we will reach out when hosted access opens.