Timing-aware recording and replay with --replay-speed multiplier (#223)

## Summary

Records per-frame arrival timestamps during proxy recording and replays
them at configurable speed. Requested by Atai.

- **Recording:** SSE frame parser captures per-frame timestamps. NDJSON
uses `\n` delimiter. Bedrock binary EventStream uses 4-byte
length-prefix frame detection. Stores `recordedTimings { ttftMs,
interChunkDelaysMs, totalDurationMs }` on fixtures.
- **Replay:** `calculateDelay` extended with `recordedTimings` +
`replaySpeed` params. Precedence: streamingProfile > recordedTimings >
global latency. Speed multiplier divides all delays.
- **CLI:** `--replay-speed 2.0` (2x faster). Per-fixture `replaySpeed`
override.
- **Coverage:** All 11 streaming paths — 8 SSE/NDJSON/EventStream
writers + 3 WebSocket handlers. All providers including Bedrock.
- **Validation:** Per-fixture `replaySpeed <= 0` stripped with warning.
NaN/negative values in `recordedTimings` sanitized.

Approximate timing reproduction based on recorded TTFT and inter-frame
cadence. Replay chunk count may differ from recording — TTFT and average
pace are preserved, not per-token fidelity.

**Spec:** https://www.notion.so/3643aa38185281328fe6ddf27407c6ed

## Test plan

- [x] 3097 tests pass (9 new across 2 test files)
- [x] TypeScript clean
- [x] Lint + format + build clean
- [x] CR Round 1: 1 finding fixed (Bedrock/Ollama defaults fallback)
- [x] CR Round 2: 7/7 confirmed 0 findings
- [x] CR Round 3 adversarial: 6 findings — fixed eventIndex reset, NaN
validation, Bedrock capture, docs language
- [x] Positive control tests for precedence and replaySpeed
- [x] Backward compat verified

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: jpr5

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "source": {
         "source": "npm",
         "package": "@copilotkit/aimock",
-        "version": "^1.25.0"
+        "version": "^1.26.0"
       },
       "description": "Fixture authoring skill for @copilotkit/aimock — LLM, multimedia (image/TTS/transcription/video), MCP, A2A, AG-UI, vector, embeddings, structured output, sequential responses, streaming physics, record/replay, agent loop patterns, and debugging"
     }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aimock",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "Fixture authoring guidance for @copilotkit/aimock — LLM, multimedia, MCP, A2A, AG-UI, vector, and service mocking",
   "author": {
     "name": "CopilotKit"

CHANGELOG.md

@@ -4,6 +4,15 @@
 
 ### Added
 
+- **Timing-aware recording and replay** — proxy recording captures per-frame
+  arrival timestamps as `recordedTimings` on fixtures. Replay uses recorded
+  timings for approximate timing reproduction based on recorded TTFT and
+  inter-frame cadence instead of the synthetic model. Replay chunk count may
+  differ from recording chunk count — TTFT and average pace are preserved,
+  not per-token fidelity. `--replay-speed N` multiplier applies to all delay
+  sources (recorded timings, streaming profiles, global latency). Per-fixture
+  `replaySpeed` override. Covers SSE, NDJSON, Bedrock EventStream, and
+  WebSocket protocols.
 - **Gemini `embedContent` endpoint** — `POST /v1beta/models/{model}:embedContent`
   with deterministic fallback embeddings and fixture matching
 - **`/v1/images/edit` and `/v1/images/variations` endpoints** — multipart

README.md

@@ -49,6 +49,7 @@ Run them all on one port with `npx @copilotkit/aimock --config aimock.json`, or
 ## Features
 
 - **[Record & Replay](https://aimock.copilotkit.dev/record-replay)** — Proxy real APIs, save as fixtures, replay deterministically forever
+- **Timing-aware recording and replay** — Recorded fixtures capture per-frame arrival timestamps; replay uses recorded timings for approximate timing reproduction based on recorded TTFT and inter-frame cadence (replay chunk count may differ from recording — TTFT and average pace are preserved, not per-token fidelity) with configurable `--replay-speed` multiplier
 - **[Multi-turn Conversations](https://aimock.copilotkit.dev/multi-turn)** — Record and replay multi-turn traces with tool rounds; match distinct turns via `turnIndex`, `hasToolResult`, `toolCallId`, `sequenceIndex`, `systemMessage` (gate on host-supplied agent context), or custom predicates
 - **[14 LLM Providers](https://aimock.copilotkit.dev/docs)** — OpenAI Chat, OpenAI Responses, OpenAI Realtime (GA + Beta shim), Claude, Gemini (REST + embedContent), Gemini Live, Gemini Interactions, Azure, Bedrock, Vertex AI, Ollama (chat + embeddings), Cohere (chat + embed), ElevenLabs TTS — full streaming support
 - **Multimedia APIs** — [image generation](https://aimock.copilotkit.dev/images) (DALL-E, Imagen), [image editing](https://aimock.copilotkit.dev/images) (/v1/images/edit), [text-to-speech](https://aimock.copilotkit.dev/speech) (OpenAI + ElevenLabs), [audio transcription](https://aimock.copilotkit.dev/transcription), [audio translation](https://aimock.copilotkit.dev/transcription) (/v1/audio/translations), [video generation](https://aimock.copilotkit.dev/video), [fal.ai](https://aimock.copilotkit.dev/fal-ai) (image / video / audio with queue lifecycle)
@@ -101,6 +102,9 @@ npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.c
 npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.com \
   --body-timeout-ms 180000
 
+# Replay recorded fixtures at 2× speed
+npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures --replay-speed 2
+
 # Convert fixtures from other tools
 npx @copilotkit/aimock convert vidaimock ./templates/ ./fixtures/
 npx @copilotkit/aimock convert mockllm ./config.yaml ./fixtures/

charts/aimock/Chart.yaml

@@ -3,4 +3,4 @@ name: aimock
 description: Mock infrastructure for AI application testing (OpenAI, Anthropic, Gemini, MCP, A2A, vector)
 type: application
 version: 0.1.0
-appVersion: "1.25.0"
+appVersion: "1.26.0"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/aimock",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "Mock infrastructure for AI application testing — LLM APIs, image generation, text-to-speech, transcription, audio generation, video generation, MCP tools, A2A agents, AG-UI event streams, vector databases, search, rerank, and moderation. One package, one port, zero dependencies.",
   "license": "MIT",
   "keywords": [