ADR-0017: Application traces compose upstream replay

Status: Accepted
Date: 2026-07-11

Context

AgentsKit Chat already emits deterministic-route and capability-policy decisions. Developers need one committed fixture explaining application outcomes and comparing them across native renderers. AgentsKit already owns adapter recording, cassettes, playback, time travel, and eval reporting.

Decision

@agentskit/chat-devtools captures application-only records in causal append order. Records have a monotonic sequence, optional prior parent, category, timestamp, and bounded JSON detail. Configured field names are recursively redacted before storage. Returned snapshots and reports are deeply immutable.

A versioned replay fixture stores these records beside an upstream Cassette. Cassette serialization and validation delegate to @agentskit/eval/replay; model requests and chunks are never independently recorded here. Semantic renderer parity compares ordered outcomes by turn identity and reports missing or different values without comparing pixels or framework internals.

Alternatives considered

1. Build a second recording adapter — rejected because AgentsKit owns replay.
2. Add traces to the turn wire protocol — rejected because developer fixtures are not client/server state.
3. Snapshot native markup — rejected because DOM, mobile, and terminal layouts are intentionally different.

Consequences

• Hosts connect existing route/policy callbacks to one capture without changing execution.
• Redaction covers application trace detail only; upstream cassettes may contain prompts and require separate handling.
• A fixture can be committed and replayed without live model access.
• Renderer diagnostics prove semantic equivalence, not visual identity.

Upstream adoption

Inspected AgentsKit revision 978ce3d77be7bbf76094b5919d240e50091bc824 and @agentskit/eval@0.4.17. Reused createRecordingAdapter, createReplayAdapter, Cassette, serializeCassette, and parseCassette from @agentskit/eval/replay. No upstream source or behavior is copied and no upstream gap blocks this application-only composition.