Forensics & Replay

Post-incident analysis, routing replay, and proof-of-death records for terminated agents.

Overview

BrainstormRouter records every routing decision and agent termination event, enabling post-incident forensic analysis and "what-if" strategy simulation.

Two subsystems power this:

• Routing Replay — records every model routing decision (model, provider, cost,

latency, strategy) and lets you simulate alternative strategies against real traffic.

• Forensic Snapshots — proof-of-death records captured when an agent is terminated,

including anomaly score, violated rules, blast radius, and active mesh connections.

Routing replay

Every request through BrainstormRouter records the routing decision: which model was selected, which provider served it, the strategy used, token counts, latency, and cost.

List decisions

Retrieve recent routing decisions for analysis:

const { decisions, count } = await client.replays.decisions({
  limit: 100,
  since: "2026-03-01T00:00:00Z",
});

for (const d of decisions) {
  console.log(`${d.model} via ${d.provider} — $${d.costUsd} in ${d.latencyMs}ms`);
}

Simulate alternative strategies

Answer "what would this week have cost with a different strategy?":

const result = await client.replays.simulate({
  strategy: "price",
  since: "2026-03-01T00:00:00Z",
});

console.log(`Actual cost: $${result.actual.total_cost_usd}`);
console.log(`Simulated cost: $${result.simulated.total_cost_usd}`);
console.log(`Savings: $${result.simulated.cost_savings_vs_actual}`);

Available strategies: quality, price, latency, throughput, cascade, priority.

Compare strategies

Compare all strategies used during a period side-by-side:

const { strategies } = await client.replays.compare({
  since: "2026-03-01T00:00:00Z",
});

for (const s of strategies) {
  console.log(
    `${s.strategy}: $${s.total_cost_usd}, ${s.avg_latency_ms}ms avg, p95 ${s.p95_latency_ms}ms`,
  );
}

Forensic snapshots

When an agent is terminated (via lifecycle transition, delegation reclaim, or anomaly detection), BrainstormRouter captures a forensic snapshot — a proof-of-death record containing the agent's state at the moment of termination.

Each snapshot includes:

Field	Description
agentId	The terminated agent's identifier
spiffeId	SPIFFE identity (if mTLS was active)
anomalyScore	Anomaly detection score at termination (0.0-1.0)
severity	Severity level: low, medium, high, critical
violatedRules	Security policy rules that were violated
blastRadius	Number of affected agents and impact score
activeConnections	Upstream and downstream mesh connections at termination
details	Additional context (triggering payload, principal claims)

Viewing snapshots

Via the SDK (requires a user JWT, not an API key):

const { snapshots } = await client.security.forensicSnapshots();

for (const snap of snapshots) {
  console.log(
    `${snap.agentId} terminated — severity: ${snap.severity}, score: ${snap.anomalyScore}`,
  );
  console.log(`  Rules violated: ${snap.violatedRules.join(", ")}`);
  console.log(`  Blast radius: ${snap.blastRadius.agentCount} agents`);
}

Via the dashboard: Governance > Forensic Snapshots tab shows a table of all snapshots with click-to-expand detail view including SPIFFE ID, active connections, and raw details payload. Each snapshot detail view includes an Export JSON button that downloads the full snapshot as a structured JSON file for case archival or compliance handoff.

MCP tools

Both subsystems are available as MCP tools for agent self-inspection:

• br_replay_decisions — list recent routing decisions (requires audit.read)
• br_forensic_snapshots — list forensic snapshots (requires security.read)

Use cases

• Cost optimization — simulate price strategy against last month's traffic to

quantify potential savings before switching.

• Post-incident analysis — review forensic snapshots to understand why an agent

was terminated, what rules it violated, and what blast radius resulted.

• Strategy validation — compare actual routing decisions against alternatives to

confirm the chosen strategy is optimal.

• Compliance auditing — forensic snapshots provide tamper-evident termination

records for regulatory compliance.

Case export

BrainstormRouter supports exporting forensic data for case management and compliance:

• Dashboard export — the Forensic Snapshots detail view includes an "Export JSON"

button that downloads the complete snapshot (agent ID, anomaly score, violated rules, blast radius, active connections, and raw details) as a structured JSON file.

• SDK export — retrieve snapshots programmatically via client.security.forensicSnapshots()

and serialize to your case management system.

• Replay export — combine client.replays.decisions() with forensic snapshots to

build a complete incident timeline: what routing decisions led up to the anomaly, what rules were violated, and what the blast radius was.

Today, case export is snapshot-based: each forensic snapshot is a self-contained proof-of-death record. Cross-referencing with replay decisions requires correlating timestamps manually. A future release will add a unified incident timeline API that joins replay decisions, memory mutations, and forensic snapshots into a single chronological view.