Forensics & Replay: Full SDK + MCP + Dashboard Coverage

2026-03-10

What We Built

Full developer surface coverage for BrainstormRouter's forensics and replay subsystems. The API routes for routing replay (/v1/replays/decisions, /v1/replays/simulate, /v1/replays/compare) and forensic snapshots (/v1/mesh/forensics, /auth/mesh/forensics) already existed — this phase normalizes the auth-route forensic response (structured details + lossless _raw) and wires them into every developer surface: TypeScript SDK, Python SDK, MCP tools, dashboard, and documentation.

The TypeScript SDK gains a client.replays resource with decisions(), simulate(), and compare() methods. The Python SDK mirrors this with both sync and async variants. Two new MCP tools (br_replay_decisions, br_forensic_snapshots) let agents inspect routing history and termination records programmatically. The dashboard's forensic snapshot detail view includes an Export JSON button for case archival.

Why It Matters

Forensics and replay are critical for AI governance — teams need to answer "what happened?" after incidents and "what would have happened?" before strategy changes. Until now, these capabilities were API-only with no SDK methods and no MCP tools. This means developers had to craft raw HTTP calls and agents had no way to self-inspect routing history. The dashboard's security center had a basic forensic view, but no governance-tab integration or JSON export for case archival.

How It Works

Routing Replay records every routing decision (model, provider, strategy, cost, latency) in the usage_events table. The simulate endpoint applies strategy multipliers to actual traffic to estimate alternative costs. Compare aggregates by strategy with percentile latency calculations.

// Simulate: "what would last week cost with price strategy?"
const sim = await client.replays.simulate({ strategy: "price" });
console.log(`Savings: $${sim.simulated.cost_savings_vs_actual}`);

Forensic Snapshots capture agent state at termination: anomaly score (0.0-1.0), violated security rules, blast radius (affected agents and impact score), and active mesh connections. The dashboard's Governance > Forensic Snapshots tab renders these in a table with click-to-expand detail views. Each snapshot includes a lossless _raw field containing the complete stored record, and the Export JSON button downloads this full payload for case archival and compliance handoff.

The Numbers

• 6 new SDK methods across TypeScript and Python (3 each, plus async variants in Python)
• 2 new MCP tools registered in the tool manifest and agents.json
• 1 new dashboard tab with table view and drill-down detail
• 4 new test files covering SDK methods and MCP tool registration

Competitive Edge

No competing AI gateway (Portkey, OpenRouter, Lasso) offers routing replay simulation — the ability to answer "what would this week have cost with a different routing strategy?" against real traffic. Combined with forensic snapshots that capture proof-of-death records on agent termination, BrainstormRouter provides the only complete post-incident analysis toolkit for AI workloads.

Lockstep Checklist

> _You MUST check these boxes [x] and verify the corresponding files are updated BEFORE committing this log._

• [x] API Routes: Pre-existing — no changes needed.
• [x] TS SDK: packages/sdk-ts — Replays resource with 3 methods, tests, wired into client.
• [x] Python SDK: packages/sdk-py — Replays + AsyncReplays resources, tests, wired into client.
• [x] MCP Schemas: br_replay_decisions and br_forensic_snapshots in tool-manifest.ts, server.ts, agents.json.
• [x] Master Record: Reflected via agents.json tool listing.