@deepseek-ai/dsh-llm-replay 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/support/llm-replay/README.md
+README.md: ae7cb5414a28bcf33f9878f6f02220861df9a0d5
+README.zh.md: 2acc0ff8e8c011126452ba3458aaeb0800d9d8f3

package/README.md

@@ -0,0 +1,80 @@
+# @deepseek-ai/dsh-llm-replay
+
+English | [中文](README.zh.md)
+
+A replay LLM plugin for keyless snapshot tests. It yields model streams reconstructed from a recorded **session JSONL** fixture, so a test can boot the real agent against a fixed model transcript with no API key. With `providers` configured it registers a replay-only adapter whose catalog is available to scenarios that exercise model discovery; without `providers` it installs the catch-all `llm/stream` waterfall used by tests that do not need discovery.
+
+Its consumers are the ACP and headless `stream-json` snapshot suites plus the Web browser e2e lane. Loader-driven suites mount this plugin in place of a real LLM adapter; the Web lane installs it directly to retain the teardown consumption handle.
+
+## How the fixture works
+
+The fixture IS the persisted session log (`<scenario>/session.jsonl`). Its `assistant/chunk` events carry every `StreamChunk`, so grouping them by `(turn, step)` reconstructs each agent-loop `stream()` call's chunk sequence. A successful compaction summarizer is logged differently: when `compact/summary` carries `llmStreamCall: true` and its complete `rawOutput`, replay reconstructs a canonical successful stream at that event's position using one `block-start`/`block-end` pair per block, the recorded usage when present, and a terminal `stop`. Exact provider delta partitioning is not part of the durable compaction result. `rawOutput` without the marker does not imply a local LLM call because template and remote summarizers may retain complete output without using this context's adapter.
+
+Recording is therefore "run the real agent once and harvest the `.jsonl`", done by the snapshot harness — this plugin does not record. A fixture may carry its `request/header` content tokenized to `{{system}}`/`{{tools}}` (the harness pins that content in one scenario and scrubs the rest); replay is indifferent — derivation reads only `assistant/chunk` and `compact/summary` events plus the line-0 session header.
+
+Two failure modes are not reconstructable from `assistant/chunk` alone — a pure throw before any chunk (e.g. an HTTP 401, where the log holds only a `turn/end {error}` and no chunks) and a cancel/hang (timing, not chunk content). A scenario that needs those supplies an optional sidecar (`<scenario>/replay.override.json`) that either replaces the derived script (a bare `ReplayEntry[]`) or augments it (`{ patches: [{ at, entry }] }`: keep every JSONL-derived call and swap the named 0-based call indexes; `at` equal to the derived length appends the retry attempt after an injected transient throw). Patch indexes must be unique. The override document, each patch and entry, and every chunk discriminant are validated when the file loads. A `hang` entry may name `readyFile`; replay writes that empty marker after its prefix chunks reach the loop and before it waits for cancellation, so an external driver can cancel deterministically without observing a presentation update.
+
+A scripted string may embed `{{fromRequest:<regex>}}` to fill a value no static sidecar can know — for example a randomly minted goal id the model must echo back into `update_goal`. At stream time every placeholder resolves against the live request: the corpus is every string leaf of the request messages joined by newlines, the pattern's LAST corpus match wins, and its first capture group (or the whole match without one) substitutes in place. A pattern that matches nothing, an invalid pattern, and an unterminated placeholder each fail loud. The last two braces of a consecutive `}` run terminate the placeholder, so a pattern may end with a brace quantifier (`[0-9a-f]{4}`) but cannot contain `}}` followed by further pattern content. Resolution applies to every scripted entry, including ones derived from the recorded JSONL — a recorded fixture whose text legitimately contains the literal marker must be expressed through a sidecar without it.
+
+## Nested agents: per-session keying
+
+A scenario where a parent agent delegates to in-process subagents records more than one log: the parent (`session.jsonl`) plus one per child (`session.1.jsonl`, …). Each agent runs as its own `Session` on the same context, so replay must serve each one its own script.
+
+Replay keys every call by its calling session id (`GenerateOptions.sessionId`, stamped by the agent loop). Live session ids are freshly random each run and never equal the recorded ones, so a live session binds to a recorded script by **first-call order**: scripts are ordered by header `createdAt` (parent first — it streams before it can delegate), and the first live session to make any call claims the first script, the next new session the next, and so on. Each session then advances its own cursor. A call with no `sessionId` is one anonymous session bound to the primary script. More distinct live sessions than recorded scripts fails loud.
+
+## Config
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `file` | string | `$DSH_SNAPSHOT_FILE` | Path to the primary (parent) `session.jsonl` fixture. Required (config or env). |
+| `overrideFile` | string | `$DSH_SNAPSHOT_OVERRIDE` | Optional `ReplayOverrideDoc` sidecar for the primary session: a bare `ReplayEntry[]` replaces its derived script, while `{ patches }` augments it by call index. |
+| `childFiles` | string[] | `$DSH_SNAPSHOT_CHILD_FILES` (path-delimited) | Recorded subagent child-session logs for a nested scenario; empty for a single-session scenario. |
+| `providers` | `ReplayProviderConfig[]` | — | Optional replay-only provider and model catalog. Each provider may set `retryPolicy`, and each model may publish `contextWindow`; configured routes dispatch through the replay adapter and never perform provider I/O. |
+| `paceMs` | number | — (burst) | Optional per-chunk delay in ms so downstream transports (e.g. the web SSE mux observed by a real browser) see genuinely incremental delivery. A realism knob only — tests must not depend on it for correctness. Non-negative integer; abort during a pace wait cancels the stream promptly. |
+
+```yaml
+- id: llm-replay
+  name: '@deepseek-ai/dsh-llm-replay'
+  config:
+    providers:
+      - id: deepseek-official
+        name: DeepSeek
+        retryPolicy:
+          mode: normal
+          backoff:
+            initialDelayMs: 1
+            maxDelayMs: 1
+            jitterRatio: 0
+        models:
+          - id: deepseek-v4-flash
+            contextWindow: 128000
+          - id: deepseek-v4-pro
+  # file/overrideFile/childFiles default to $DSH_SNAPSHOT_FILE /
+  # $DSH_SNAPSHOT_OVERRIDE / $DSH_SNAPSHOT_CHILD_FILES, set by the snapshot
+  # harness per scenario.
+```
+
+## Exports
+
+- `installLlmReplay(ctx, config)` — install the configured replay adapter or catch-all `llm/stream` listener; returns a `ReplayHandle` (`dispose()` for HMR safety plus `assertConsumed()`, the teardown check that every recorded script bound to a live session and every bound cursor drained — turning a scenario that silently drove fewer model calls than recorded into a crisp diagnostic). Use this in tests to drive replay without the Loader or env vars.
+- `loadSessionScripts(config)` — resolve the ordered `SessionScript[]` (primary + children) for a scenario, ready to bind to live sessions in first-call order.
+- `loadReplayScript(config)` — resolve the `ReplayEntry[]` for the primary session only (validated sidecar replacement/patches if present, else derived from the JSONL; fail-loud if the fixture is missing).
+- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)` — the pure helpers that turn ordinary loop chunks and explicitly marked local compaction outputs in a recorded session log into a script, read its header `id`/`createdAt`, and resolve `{{fromRequest:...}}` placeholders against one live request. A derived assistant group must end in a `finish` chunk; a group without one is the fingerprint of a thrown `stream()` and must instead be expressed via an override sidecar.
+- Types `ReplayEntry` / `ReplayOverrideDoc` / `ReplayOverridePatch` / `SessionScript` / `ReplayConfig` / `ReplayProviderConfig` / `ReplayModelConfig` / `ReplayHandle` / `Config`.
+
+## Plugin export shape
+
+Named `name` / `inject` / `Config` / `apply`, with **no default export**: the cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray default would collapse the module to the bare function and drop the `inject` namespace (see [docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)).
+
+## Model Experience
+
+None, as this keyless test adapter sends no request to a provider model; it only replays recorded assistant chunks into the test loop.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **First-call-order script binding assumes sequential delegation** — a cut that runs sibling subagents concurrently would bind live sessions to recorded scripts non-deterministically; a stronger keying is deferred until such a scenario exists (`XXX(concurrent-subagents)`).
+- **Only ordinary loop chunks and marked local compaction outputs are derivable** — a pure pre-chunk throw, a cancel/hang, or an unmarked external summarizer call needs the `replay.override.json` sidecar. Replacement and patch forms affect only the primary session; child scripts still derive from their logs.

package/README.zh.md

@@ -0,0 +1,80 @@
+# @deepseek-ai/dsh-llm-replay
+
+[English](README.md) | 中文
+
+用于无密钥快照测试的 LLM（大语言模型）回放插件。它根据已记录的**会话 JSONL** fixture（测试前置数据）重建模型流，使测试无需 API 密钥即可针对固定的模型 transcript（文本记录）启动真实 agent（智能体）。配置 `providers` 后，它会注册仅用于回放的适配器，其模型目录可供测试模型发现功能的场景使用；未配置 `providers` 时，它会安装无需模型发现功能的测试所用 catch-all `llm/stream` waterfall（瀑布式事件）。
+
+其消费方包括 ACP（Agent Client Protocol）与 headless `stream-json` 快照套件，以及 Web 浏览器 e2e 流水线。Loader 驱动的套件使用此插件替代真实 LLM 适配器；Web 流水线直接安装它，以保留清理阶段的消费检查句柄。
+
+## fixture 的工作方式
+
+fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 agent loop（智能体循环）的 `stream()` 调用的分片序列。压缩（compaction）摘要器成功时，日志记录方式有所不同：当 `compact/summary` 携带 `llmStreamCall: true` 和完整的 `rawOutput` 时，回放会在该事件的位置重建一条规范成功流，其中每个块各使用一对 `block-start`/`block-end`，带上已记录的用量（如有），并以 `stop` 终止。提供方增量的精确切分不属于持久压缩结果。不带该标记的 `rawOutput` 并不意味着发生了本地 LLM 调用，因为模板摘要器和远程摘要器即使未使用此上下文的适配器，也可能保留完整输出。
+
+因此，录制就是「运行一次真实 agent 并收集 `.jsonl`」，由快照 harness 完成；该插件本身不录制。fixture 的 `request/header` 内容可能被标记化为 `{{system}}`/`{{tools}}`（harness 会在一个场景中固定该内容，并清除其余场景中的内容）；回放不受影响，因为派生过程只读取 `assistant/chunk` 和 `compact/summary` 事件以及第 0 行的会话 header。
+
+有两种失败模式无法仅根据 `assistant/chunk` 重建：在产生任何分片前直接抛出异常（例如 HTTP 401，此时日志只有 `turn/end {error}` 而没有分片），以及取消或挂起（差异在时序，而非分片内容）。需要这些行为的场景可提供伴随文件（`<scenario>/replay.override.json`）：它可以替换派生脚本（裸 `ReplayEntry[]`），也可以增补派生脚本（`{ patches: [{ at, entry }] }`：保留所有从 JSONL 派生的调用，只替换指定的从 0 开始计数的调用索引；当 `at` 等于派生长度时，则在注入瞬态异常后的重试位置追加一次调用）。补丁索引不得重复。文件加载时会校验覆写文档、每个补丁和条目，以及每个分片的判别标签。`hang` 条目可以指定 `readyFile`；当前缀分片到达循环后、开始等待取消前，回放会写入这个空标记，使外部驱动程序无需观察展示层更新即可确定性地取消。
+
+脚本字符串可以内嵌 `{{fromRequest:<regex>}}`，用来填入静态伴随文件不可能预知的值——例如模型必须原样回填到 `update_goal` 的随机生成 goal id。回放时每个占位符针对实时请求解析：语料是请求消息的所有字符串叶子按换行拼接的结果，取该模式在语料中的最后一次匹配，用其第一个捕获组（无捕获组时用整个匹配）原位替换。模式匹配不到内容、模式非法、占位符未闭合都会明确报错。连续右花括号串的最后两个花括号才是占位符结束符，因此模式可以以花括号量词收尾（如 `[0-9a-f]{4}`），但不能在 `}}` 之后还有后续模式内容。解析作用于所有脚本条目，包括从已记录 JSONL 派生的条目——若录制文本本身合法地含有该字面量标记，需改用不含标记的伴随文件表达。
+
+## 嵌套 agent：每会话键控
+
+父 agent 委托给进程内 subagent 的场景会记录多个日志：父会话使用 `session.jsonl`，每个子会话各使用一个日志（`session.1.jsonl` 等）。每个 agent 都在同一上下文中作为独立的 `Session` 运行，因此回放必须为每个 agent 提供各自的脚本。
+
+回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop 写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话。不同实时会话的数量超过已记录脚本数时会明确报错。
+
+## 配置
+
+| 键 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `file` | string | `$DSH_SNAPSHOT_FILE` | 主（父）`session.jsonl` fixture 的路径。必需（配置或 env）。 |
+| `overrideFile` | string | `$DSH_SNAPSHOT_OVERRIDE` | 主会话的可选 `ReplayOverrideDoc` 伴随文件：裸 `ReplayEntry[]` 替换其派生脚本，`{ patches }` 则按调用索引增补该脚本。 |
+| `childFiles` | string[] | `$DSH_SNAPSHOT_CHILD_FILES`（以路径分隔符分隔） | 嵌套场景中已记录的 subagent 子会话日志；单会话场景为空。 |
+| `providers` | `ReplayProviderConfig[]` | 无 | 可选的仅回放提供方和模型目录。每个提供方可以设置 `retryPolicy`，每个模型可以发布 `contextWindow`；已配置路由通过回放适配器分派，绝不执行提供方 I/O。 |
+| `paceMs` | number | 无（突发） | 可选的每分片毫秒延迟，使下游传输（例如真实浏览器观察到的 Web SSE（Server-Sent Events）多路复用器）看到真正的增量传递。它只是仿真开关，测试不得依赖它保证正确性。值必须是非负整数；pace 等待期间中止会迅速取消流。 |
+
+```yaml
+- id: llm-replay
+  name: '@deepseek-ai/dsh-llm-replay'
+  config:
+    providers:
+      - id: deepseek-official
+        name: DeepSeek
+        retryPolicy:
+          mode: normal
+          backoff:
+            initialDelayMs: 1
+            maxDelayMs: 1
+            jitterRatio: 0
+        models:
+          - id: deepseek-v4-flash
+            contextWindow: 128000
+          - id: deepseek-v4-pro
+  # file/overrideFile/childFiles default to $DSH_SNAPSHOT_FILE /
+  # $DSH_SNAPSHOT_OVERRIDE / $DSH_SNAPSHOT_CHILD_FILES, set by the snapshot
+  # harness per scenario.
+```
+
+## 导出项
+
+- `installLlmReplay(ctx, config)`：安装已配置回放适配器或 catch-all `llm/stream` 监听器；返回 `ReplayHandle`（包含用于保证 HMR（热模块替换）安全的 `dispose()`，以及清理阶段执行的 `assertConsumed()` 检查；后者确保每个已记录脚本都绑定到实时会话，且每个已绑定游标都已耗尽，从而将场景静默驱动的模型调用少于记录数转换为明确诊断）。在测试中使用它，可以不通过 Loader 或 env var 驱动回放。
+- `loadSessionScripts(config)`：解析场景中有序的 `SessionScript[]`（主会话 + 子会话），准备按首次调用顺序绑定到实时会话。
+- `loadReplayScript(config)`：只解析主会话的 `ReplayEntry[]`（如果伴随文件存在，则使用经校验的替换或补丁；否则从 JSONL 派生；fixture 缺失时明确报错）。
+- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)`：将已记录会话日志中的普通 loop 分片和显式标记的本地压缩输出转换为脚本、读取其 header `id`/`createdAt`、并针对单次实时请求解析 `{{fromRequest:...}}` 占位符的纯辅助工具。派生的 assistant 分组必须以 `finish` 分片结束；没有该分片的分组是 `stream()` 抛出异常的指纹，必须改用 override 伴随文件表达。
+- 类型 `ReplayEntry` / `ReplayOverrideDoc` / `ReplayOverridePatch` / `SessionScript` / `ReplayConfig` / `ReplayProviderConfig` / `ReplayModelConfig` / `ReplayHandle` / `Config`。
+
+## 插件导出形态
+
+命名导出 `name` / `inject` / `Config` / `apply`，且**没有默认导出**：Cordis Loader 的 `unwrapExports` 执行 `exports.default ?? exports`，因此意外的默认导出会将模块折叠为纯函数，并丢弃 `inject` 命名空间（见 [docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）。
+
+## 模型体验
+
+无。该无密钥测试适配器不向提供方模型发送请求，只将已记录 assistant 分片回放到测试 loop 中。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **首次调用顺序脚本绑定假设串行委托**：并发运行同级 subagent 的 cut 会非确定性地将实时会话绑定到已记录脚本；在这种场景出现前暂不实现更强的键控（`XXX(concurrent-subagents)`）。
+- **只有普通 loop 分片和带标记的本地压缩输出才能派生**：在产生分片前直接抛出异常、取消/挂起，或未标记的外部摘要器调用场景需要 `replay.override.json` 伴随文件。替换和补丁两种形式都只影响主会话；子会话脚本仍从各自日志派生。

package/lib/index.js

@@ -0,0 +1,536 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter } from "node:path";
+import { decodeStorageRecord } from "@deepseek-ai/dsh-session";
+import { LlmAdapter, LlmError, ReasoningEffortId, assertNever, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+//#region lib/types/index.js
+/**
+* Keyless snapshot-test LLM replay. It derives one model-call script per
+* recorded session from `assistant/chunk` events and explicitly marked local
+* compaction calls, then binds fresh live sessions to parent/child scripts by
+* first-call order. Throw and hang cases require an explicit override because
+* a session log cannot reconstruct them alone.
+* @module @deepseek-ai/dsh-llm-replay
+*/
+/**
+* Parse a session `.jsonl` buffer into its event list. Line 0 is the session
+* header (a `{type:'session',…}` record), every subsequent non-empty line is a
+* {@link SessionEvent} or a packed chunk row (expanded back into its events, so
+* a fixture recorded with `packChunks` on derives the same script). The header
+* is skipped; malformed lines fail loud.
+* @param text - the raw `.jsonl` file contents.
+* @returns every event after the header, in log order.
+*/
+function parseSessionLog(text) {
+	const lines = text.split("\n").filter((line) => line.trim().length > 0);
+	const events = [];
+	for (let i = 1; i < lines.length; i++) events.push(...decodeStorageRecord(JSON.parse(lines[i])));
+	return events;
+}
+/**
+* Read replay identity, ordering, and fork-seed facts from the JSONL header.
+*
+* @param text - the raw `.jsonl` file contents (only the header line is read).
+* @returns the header's `id`, `createdAt`, and `seedLength`, defaulted when absent.
+*/
+function parseSessionHeader(text) {
+	const firstLine = text.split("\n").find((line) => line.trim().length > 0) ?? "{}";
+	const parsed = JSON.parse(firstLine);
+	return {
+		id: typeof parsed.id === "string" ? parsed.id : "",
+		createdAt: typeof parsed.createdAt === "number" ? parsed.createdAt : 0,
+		seedLength: typeof parsed.seedLength === "number" ? parsed.seedLength : 0
+	};
+}
+/**
+* Reconstruct the per-`stream()` replay script from a recorded session log.
+*
+* Splits `assistant/chunk` events at every `finish`, using turn and step changes
+* to detect an unterminated prior call. A `compact/summary` explicitly marked
+* as one local LLM-stream call becomes a canonical successful stream from its
+* complete `rawOutput` at the summary's log position. A
+* missing assistant terminator means the live stream threw, so derivation
+* rejects and the scenario must provide an explicit override. Multiple calls
+* may share one turn and step when the loop retries.
+* @param events - the recorded session's events.
+* @returns one `chunks` entry per recorded model call, in call order.
+*/
+function deriveReplayScript(events) {
+	const script = [];
+	let currentKey;
+	let current = [];
+	const close = (key, chunks) => {
+		if (chunks.length === 0) return;
+		if (chunks[chunks.length - 1]?.type !== "finish") throw new Error(`llm-replay: model call ${key} ended without a finish chunk (a thrown stream); this scenario needs a replay.override.json sidecar`);
+		script.push({
+			kind: "chunks",
+			chunks
+		});
+	};
+	for (const event of events) {
+		if (event.type === "compact/summary") {
+			close(currentKey, current);
+			currentKey = void 0;
+			current = [];
+			const persisted = event.data;
+			if (persisted.llmStreamCall === true) {
+				if (persisted.rawOutput === void 0) throw new Error("llm-replay: compact/summary marks an LLM stream call without rawOutput");
+				const chunks = [];
+				for (const [index, block] of persisted.rawOutput.entries()) {
+					chunks.push({
+						type: "block-start",
+						index,
+						blockType: block.type
+					});
+					chunks.push({
+						type: "block-end",
+						index,
+						block
+					});
+				}
+				if (persisted.usage !== void 0) chunks.push({
+					type: "usage",
+					usage: persisted.usage
+				});
+				chunks.push({
+					type: "finish",
+					reason: { kind: "stop" }
+				});
+				script.push({
+					kind: "chunks",
+					chunks
+				});
+			}
+			continue;
+		}
+		if (event.type !== "assistant/chunk") continue;
+		const { turn, step, chunk } = event.data;
+		const key = `${turn}/${step}`;
+		if (current.length > 0 && key !== currentKey) close(currentKey, current);
+		if (current.length === 0) currentKey = key;
+		current.push(chunk);
+		if (chunk.type === "finish") {
+			close(currentKey, current);
+			currentKey = void 0;
+			current = [];
+		}
+	}
+	close(currentKey, current);
+	return script;
+}
+const REPLAY_CHUNK_TYPES = new Set([
+	"block-start",
+	"text-delta",
+	"reasoning-delta",
+	"tool-call-delta",
+	"block-end",
+	"usage",
+	"finish"
+]);
+const FROM_REQUEST_OPEN = "{{fromRequest:";
+const FROM_REQUEST_CLOSE = "}}";
+/** Collect every string leaf of one JSON-compatible value, in traversal order. */
+function collectStrings(value, out) {
+	if (typeof value === "string") {
+		out.push(value);
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) collectStrings(item, out);
+		return;
+	}
+	if (value !== null && typeof value === "object") for (const item of Object.values(value)) collectStrings(item, out);
+}
+/** Resolve one placeholder pattern against the request corpus; the LAST match wins. */
+function resolveFromRequest(pattern, corpus) {
+	let regex;
+	try {
+		regex = new RegExp(pattern, "g");
+	} catch (error) {
+		throw new Error(`llm-replay: fromRequest has an invalid pattern ${JSON.stringify(pattern)}: ${String(error)}`);
+	}
+	let last;
+	for (const match of corpus.matchAll(regex)) last = match;
+	if (last === void 0) throw new Error(`llm-replay: fromRequest pattern ${JSON.stringify(pattern)} matched nothing in the request`);
+	return last[1] ?? last[0];
+}
+/** Replace every `{{fromRequest:<pattern>}}` occurrence in one scripted string. */
+function substituteString(text, corpus) {
+	let result = "";
+	let cursor = 0;
+	while (true) {
+		const open = text.indexOf(FROM_REQUEST_OPEN, cursor);
+		if (open === -1) return result + text.slice(cursor);
+		let close = text.indexOf(FROM_REQUEST_CLOSE, open + 14);
+		if (close === -1) throw new Error(`llm-replay: fromRequest placeholder is unterminated in ${JSON.stringify(text)}`);
+		while (text[close + 2] === "}") close += 1;
+		const pattern = text.slice(open + 14, close);
+		result += text.slice(cursor, open) + resolveFromRequest(pattern, corpus);
+		cursor = close + 2;
+	}
+}
+/** Deep-copy one JSON-compatible value with scripted placeholders resolved. */
+function substituteValue(value, corpus) {
+	if (typeof value === "string") return value.includes(FROM_REQUEST_OPEN) ? substituteString(value, corpus) : value;
+	if (Array.isArray(value)) return value.map((item) => substituteValue(item, corpus));
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteValue(item, corpus)]));
+	return value;
+}
+/**
+* Resolve every `{{fromRequest:<regex>}}` placeholder in one scripted entry
+* against the live request. The corpus is every string leaf of the request
+* messages joined by newlines; the pattern's LAST corpus match wins and its
+* first capture group (or, without one, the whole match) substitutes in place.
+* Scenario sidecars use this to script arguments no static file can know,
+* such as a randomly minted goal id the model must echo back. A pattern that
+* matches nothing, an invalid pattern, and an unterminated placeholder each
+* fail loud. The last two braces of a consecutive `}` run terminate the
+* placeholder, so a pattern may end with a brace quantifier but cannot
+* contain `}}` followed by further pattern content. Derived entries pass
+* through the same resolution as sidecar entries.
+* @param entry - the scripted entry about to replay.
+* @param messages - the live request messages searched by the placeholders.
+* @returns the entry itself when no placeholder appears, else a resolved deep copy.
+*/
+function resolveScriptedEntry(entry, messages) {
+	if (!JSON.stringify(entry).includes(FROM_REQUEST_OPEN)) return entry;
+	const leaves = [];
+	collectStrings(messages, leaves);
+	return substituteValue(entry, leaves.join("\n"));
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+	return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function invalidOverride(file, location, detail) {
+	throw new Error(`llm-replay: invalid override ${file}: ${location} ${detail}`);
+}
+function readChunks(value, file, location) {
+	if (!Array.isArray(value)) invalidOverride(file, location, "chunks must be an array");
+	for (const [index, chunk] of value.entries()) if (!isRecord(chunk) || typeof chunk["type"] !== "string" || !REPLAY_CHUNK_TYPES.has(chunk["type"])) invalidOverride(file, `${location}.chunks[${index}]`, "must have a known StreamChunk type");
+	return value;
+}
+function readReplayEntry(value, file, location) {
+	if (!isRecord(value)) invalidOverride(file, location, "must be an object");
+	switch (value["kind"]) {
+		case "chunks":
+			if (!hasExactKeys(value, ["kind", "chunks"])) invalidOverride(file, location, "has invalid chunks-entry fields");
+			return {
+				kind: "chunks",
+				chunks: readChunks(value["chunks"], file, location)
+			};
+		case "throw":
+			if (!hasExactKeys(value, [
+				"kind",
+				"chunks",
+				"message",
+				"code"
+			])) invalidOverride(file, location, "has invalid throw-entry fields");
+			if (typeof value["message"] !== "string" || value["message"].length === 0) invalidOverride(file, location, "message must be a non-empty string");
+			if (typeof value["code"] !== "string" || value["code"].length === 0) invalidOverride(file, location, "code must be a non-empty string");
+			return {
+				kind: "throw",
+				chunks: readChunks(value["chunks"], file, location),
+				message: value["message"],
+				code: value["code"]
+			};
+		case "hang": {
+			const readyFile = value["readyFile"];
+			if (!hasExactKeys(value, readyFile === void 0 ? ["kind"] : ["kind", "readyFile"])) invalidOverride(file, location, "has invalid hang-entry fields");
+			if (readyFile !== void 0 && (typeof readyFile !== "string" || readyFile.length === 0)) invalidOverride(file, location, "readyFile must be a non-empty string");
+			return {
+				kind: "hang",
+				...readyFile === void 0 ? {} : { readyFile }
+			};
+		}
+		default: return invalidOverride(file, location, `has unknown kind ${JSON.stringify(value["kind"])}`);
+	}
+}
+function readOverrideDoc(value, file) {
+	if (Array.isArray(value)) return value.map((entry, index) => readReplayEntry(entry, file, `entry ${index}`));
+	if (!isRecord(value) || !hasExactKeys(value, ["patches"]) || !Array.isArray(value["patches"])) return invalidOverride(file, "document", "must be a ReplayEntry[] or { patches: [...] }");
+	return { patches: value["patches"].map((value, index) => {
+		const location = `patch ${index}`;
+		if (!isRecord(value) || !hasExactKeys(value, ["at", "entry"])) return invalidOverride(file, location, "must contain exactly at and entry");
+		const at = value["at"];
+		if (typeof at !== "number" || !Number.isSafeInteger(at) || at < 0) return invalidOverride(file, location, "at must be a non-negative safe integer");
+		return {
+			at,
+			entry: readReplayEntry(value["entry"], file, `${location}.entry`)
+		};
+	}) };
+}
+/**
+* Load the PRIMARY session's replay script: the sidecar override when present
+* (whole-script replacement or `{ patches }` augmentation over the derived
+* script), else the script derived from the session JSONL (fail-loud when the
+* fixture is missing).
+* @param config - the fixture paths; only `file` and `overrideFile` are consulted.
+* @returns the resolved primary-session script.
+*/
+function loadReplayScript(config) {
+	if (config.overrideFile !== void 0 && existsSync(config.overrideFile)) {
+		const doc = readOverrideDoc(JSON.parse(readFileSync(config.overrideFile, "utf8")), config.overrideFile);
+		if (Array.isArray(doc)) return doc;
+		const script = deriveScriptFromFile(config.file);
+		const derivedLength = script.length;
+		const seenIndexes = /* @__PURE__ */ new Set();
+		for (const patch of doc.patches) {
+			if (patch.at > derivedLength) throw new Error(`llm-replay: override patch index ${String(patch.at)} out of range (derived script has ${derivedLength} call(s); == length appends): ${config.overrideFile}`);
+			if (seenIndexes.has(patch.at)) throw new Error(`llm-replay: duplicate override patch index ${patch.at}: ${config.overrideFile}`);
+			seenIndexes.add(patch.at);
+			script[patch.at] = patch.entry;
+		}
+		return script;
+	}
+	return deriveScriptFromFile(config.file);
+}
+/** Derive the primary script from the session JSONL, failing loud on a missing fixture. */
+function deriveScriptFromFile(file) {
+	if (!existsSync(file)) throw new Error(`llm-replay: fixture not found: ${file} — run \`pnpm run test:snapshot:record\` first`);
+	return deriveReplayScript(parseSessionLog(readFileSync(file, "utf8")));
+}
+/**
+* Load the primary and child scripts in bind order. Child derivation begins at
+* `seedLength` so inherited parent chunks are never replayed as child calls.
+*
+* @param config - the fixture paths: the primary log plus any recorded child logs.
+* @returns the primary script first, then the child scripts in bind order.
+*/
+function loadSessionScripts(config) {
+	const primaryEntries = loadReplayScript(config);
+	const primaryHeader = existsSync(config.file) ? parseSessionHeader(readFileSync(config.file, "utf8")) : {
+		id: "",
+		createdAt: 0
+	};
+	const primary = {
+		recordedId: primaryHeader.id,
+		createdAt: primaryHeader.createdAt,
+		entries: primaryEntries,
+		primary: true
+	};
+	const children = [];
+	for (const childFile of config.childFiles ?? []) {
+		if (!existsSync(childFile)) throw new Error(`llm-replay: child fixture not found: ${childFile} — re-record the scenario`);
+		const text = readFileSync(childFile, "utf8");
+		const header = parseSessionHeader(text);
+		const ownEvents = parseSessionLog(text).slice(header.seedLength);
+		children.push({
+			recordedId: header.id,
+			createdAt: header.createdAt,
+			entries: deriveReplayScript(ownEvents),
+			primary: false
+		});
+	}
+	children.sort((a, b) => a.createdAt - b.createdAt || a.recordedId.localeCompare(b.recordedId));
+	return [primary, ...children];
+}
+/** Replay adapter that makes a configured provider catalog discoverable without provider I/O. */
+var ReplayAdapter = class extends LlmAdapter {
+	replay;
+	providers;
+	constructor(providers, replay) {
+		super();
+		this.replay = replay;
+		this.providers = new Map(providers.map((provider) => [provider.id, provider]));
+	}
+	providerInfo(provider) {
+		const configured = this.providers.get(provider);
+		/* v8 ignore next -- LlmService only asks about routes registered from this same map. */
+		if (configured === void 0) return super.providerInfo(provider);
+		return {
+			id: provider,
+			name: configured.name ?? provider
+		};
+	}
+	providerRetryPolicy(provider) {
+		const configured = this.providers.get(provider);
+		/* v8 ignore next -- LlmService only asks about routes registered from this same map. */
+		if (configured === void 0) return super.providerRetryPolicy(provider);
+		return configured.retryPolicy === void 0 ? void 0 : resolveRetryPolicy(configured.retryPolicy, `llm-replay: provider "${provider}" retryPolicy`);
+	}
+	listModels(provider) {
+		const configured = this.providers.get(provider);
+		/* v8 ignore next -- LlmService only asks about routes registered from this same map. */
+		if (configured === void 0) return Promise.resolve([]);
+		return Promise.resolve((configured.models ?? []).map((model) => ({
+			provider,
+			id: model.id,
+			name: model.name ?? model.id,
+			...model.description === void 0 ? {} : { description: model.description }
+		})));
+	}
+	resolveModel(provider, model) {
+		const configured = this.providers.get(provider);
+		/* v8 ignore next -- LlmService only asks about routes registered from this same map. */
+		if (configured === void 0) return Promise.resolve({
+			provider,
+			id: model,
+			name: model
+		});
+		const configuredModel = configured.models?.find((candidate) => candidate.id === model);
+		return Promise.resolve({
+			provider,
+			id: model,
+			name: configuredModel?.name ?? model,
+			...configuredModel?.description === void 0 ? {} : { description: configuredModel.description },
+			...configuredModel?.contextWindow === void 0 ? {} : { context: { contextWindow: configuredModel.contextWindow } },
+			...configuredModel?.defaultMaxTokens === void 0 ? {} : { defaultMaxTokens: configuredModel.defaultMaxTokens },
+			...configuredModel?.reasoningEfforts === void 0 ? {} : { reasoning: {
+				efforts: configuredModel.reasoningEfforts.map((id) => ({
+					id: ReasoningEffortId(id),
+					name: id
+				})),
+				...configuredModel.defaultReasoningEffort === void 0 ? {} : { defaultEffort: ReasoningEffortId(configuredModel.defaultReasoningEffort) }
+			} }
+		});
+	}
+	stream(options) {
+		return this.replay(options);
+	}
+};
+/**
+* Wait `paceMs` between chunk yields, aborting the wait (and the stream) the
+* moment the signal fires — a paced replay must cancel as promptly as a burst
+* one.
+*/
+function paceDelay(paceMs, signal) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, paceMs);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error("aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** Yield a recorded stream back, honoring abort like a real adapter. */
+async function* replayEntry(entry, signal, paceMs) {
+	switch (entry.kind) {
+		case "chunks":
+			for (const chunk of entry.chunks) {
+				if (signal?.aborted) throw new Error("aborted");
+				if (paceMs > 0) await paceDelay(paceMs, signal);
+				yield chunk;
+			}
+			return;
+		case "throw":
+			for (const chunk of entry.chunks) {
+				if (signal?.aborted) throw new Error("aborted");
+				if (paceMs > 0) await paceDelay(paceMs, signal);
+				yield chunk;
+			}
+			throw new LlmError(entry.message, entry.code);
+		case "hang":
+			yield {
+				type: "block-start",
+				index: 0,
+				blockType: "text"
+			};
+			yield {
+				type: "text-delta",
+				index: 0,
+				text: "partial"
+			};
+			if (entry.readyFile !== void 0) writeFileSync(entry.readyFile, "");
+			await new Promise((_resolve, reject) => {
+				if (signal?.aborted) {
+					reject(/* @__PURE__ */ new Error("aborted"));
+					return;
+				}
+				signal?.addEventListener("abort", () => {
+					reject(/* @__PURE__ */ new Error("aborted"));
+				}, { once: true });
+			});
+			/* v8 ignore next -- unreachable: the hang promise only ever rejects (on abort), never resolves; control never reaches here */
+			return;
+		/* v8 ignore next -- sidecar entries are validated before they reach the closed local union. */
+		default: return assertNever(entry, "llm-replay replay entry");
+	}
+}
+/**
+* Install per-session positional replay. A newly seen live session takes the
+* next ordered recorded script, then advances its own cursor synchronously at
+* invocation time; calls without `sessionId` share one anonymous session. A
+* non-empty provider catalog registers a routed replay adapter; otherwise a
+* catch-all waterfall intercepts requests.
+*
+* @param ctx - the context whose LLM service receives the replay route or waterfall.
+* @param config - the resolved fixture paths (env-var defaulting is `apply`'s job).
+* @returns the {@link ReplayHandle} carrying the disposer and the teardown consumption check.
+*/
+function installLlmReplay(ctx, config) {
+	const paceMs = config.paceMs ?? 0;
+	if (!Number.isInteger(paceMs) || paceMs < 0) throw new Error(`llm-replay: paceMs must be a non-negative integer, got ${String(config.paceMs)}`);
+	const scripts = loadSessionScripts(config);
+	const bound = /* @__PURE__ */ new Map();
+	let nextScript = 0;
+	const ANON = "\0anon\0";
+	const replay = (options) => {
+		const key = options.sessionId ?? ANON;
+		let state = bound.get(key);
+		let unrecorded = false;
+		if (state === void 0) {
+			const script = scripts[nextScript];
+			if (script === void 0) {
+				unrecorded = true;
+				state = {
+					entries: [],
+					cursor: 0
+				};
+			} else {
+				nextScript++;
+				state = {
+					entries: script.entries,
+					cursor: 0
+				};
+				bound.set(key, state);
+			}
+		}
+		const boundState = state;
+		const seenSessions = nextScript;
+		const totalScripts = scripts.length;
+		const index = boundState.cursor++;
+		const entry = boundState.entries[index];
+		return (async function* () {
+			if (unrecorded) throw new Error(`llm-replay: a model call arrived from an unrecorded session (#${seenSessions + 1}); the scenario recorded only ${totalScripts} session(s) — re-record it`);
+			if (entry === void 0) throw new Error(`llm-replay: script exhausted — session requested model call #${index + 1} but its script has only ${boundState.entries.length}; re-record the scenario`);
+			yield* replayEntry(resolveScriptedEntry(entry, options.messages), options.signal, paceMs);
+		})();
+	};
+	const providers = config.providers ?? [];
+	return {
+		dispose: providers.length > 0 ? ctx.llm.registerAdapter(providers.map((provider) => provider.id), new ReplayAdapter(providers, replay)) : ctx.on("llm/stream", (options, _next) => replay(options)),
+		assertConsumed() {
+			const problems = [];
+			if (nextScript < scripts.length) problems.push(`${scripts.length - nextScript} recorded script(s) never bound to a live session`);
+			for (const [key, state] of bound) if (state.cursor < state.entries.length) {
+				const who = key === ANON ? "the anonymous session" : `session ${key}`;
+				problems.push(`${who} consumed ${state.cursor}/${state.entries.length} recorded call(s)`);
+			}
+			if (problems.length > 0) throw new Error(`llm-replay: fixture not fully consumed — ${problems.join("; ")}; the scenario drove fewer model calls than recorded`);
+		}
+	};
+}
+const name = "llm-replay";
+const inject = ["llm"];
+function apply(ctx, config = {}) {
+	const file = config.file ?? process.env.DSH_SNAPSHOT_FILE;
+	if (file === void 0 || file.length === 0) throw new Error("llm-replay: a fixture path is required (Config.file or $DSH_SNAPSHOT_FILE)");
+	const overrideFile = config.overrideFile ?? process.env.DSH_SNAPSHOT_OVERRIDE;
+	const childEnv = process.env.DSH_SNAPSHOT_CHILD_FILES;
+	const childFiles = config.childFiles ?? (childEnv !== void 0 && childEnv.length > 0 ? childEnv.split(delimiter) : []);
+	installLlmReplay(ctx, {
+		file,
+		...overrideFile !== void 0 && overrideFile.length > 0 ? { overrideFile } : {},
+		...childFiles.length > 0 ? { childFiles } : {},
+		...config.providers !== void 0 ? { providers: config.providers } : {},
+		...config.paceMs !== void 0 ? { paceMs: config.paceMs } : {}
+	});
+}
+//#endregion
+export { apply, deriveReplayScript, inject, installLlmReplay, loadReplayScript, loadSessionScripts, name, parseSessionHeader, parseSessionLog, resolveScriptedEntry };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-llm-replay`.
+* @module @deepseek-ai/dsh-llm-replay/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-llm-replay";
+/** Cordis companion plugin name. */
+const name = "llm-replay-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this test-only adapter consumes a fixed replay script; its stream grammar
+* is checked by the LLM companion and fixture derivation tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Keyless snapshot-test LLM replay. It derives one model-call script per
+ * recorded session from `assistant/chunk` events and explicitly marked local
+ * compaction calls, then binds fresh live sessions to parent/child scripts by
+ * first-call order. Throw and hang cases require an explicit override because
+ * a session log cannot reconstruct them alone.
+ * @module @deepseek-ai/dsh-llm-replay
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { GenerateOptions, RetryPolicyConfig, StreamChunk } from '@deepseek-ai/dsh-llm';
+/**
+ * One recorded model call. `throw` may replay prefix chunks before failing;
+ * `hang` models cancellation. Derived chunk entries come from ordinary model
+ * streams and complete outputs of explicitly marked local compaction calls;
+ * an override sidecar can supply any variant.
+ */
+export type ReplayEntry = {
+    kind: 'chunks';
+    chunks: StreamChunk[];
+} | {
+    kind: 'throw';
+    chunks: StreamChunk[];
+    message: string;
+    code: string;
+} | {
+    kind: 'hang';
+    /** Optional marker written after the prefix chunks are consumed and before the stream waits for cancellation. */
+    readyFile?: string;
+};
+/** One model exposed by a replay-only provider catalog. */
+export interface ReplayModelConfig {
+    /** Model id used for replay requests. */
+    id: string;
+    /** Selector label; defaults to {@link id}. */
+    name?: string;
+    /** Optional selector description. */
+    description?: string;
+    /** Optional positive integer context capacity published by the replay adapter. */
+    contextWindow?: number;
+    /**
+     * Optional per-request output cap the replay route materializes when callers
+     * omit one, so replay reconstructs the request header a live catalog produced.
+     */
+    defaultMaxTokens?: number;
+    /** Optional reasoning-effort ids the replay route accepts, in display order. */
+    reasoningEfforts?: string[];
+    /**
+     * Optional effort materialized when callers omit one; must appear in
+     * {@link reasoningEfforts} or call resolution rejects the route.
+     */
+    defaultReasoningEffort?: string;
+}
+/** One provider route exposed by the replay adapter. */
+export interface ReplayProviderConfig {
+    /** Provider route used for replay requests. */
+    id: string;
+    /** Selector label; defaults to {@link id}. */
+    name?: string;
+    /** Advisory models exposed to replay scenarios that exercise discovery. */
+    models?: ReplayModelConfig[];
+    /** Optional provider-owned retry policy used by assembled recovery snapshots. */
+    retryPolicy?: RetryPolicyConfig;
+}
+/** Resolved plugin configuration. */
+export interface ReplayConfig {
+    /**
+     * Path to the PRIMARY (parent) `session.jsonl` fixture. For a single-session
+     * scenario this is the only log; for a nested-agent scenario it is the parent,
+     * and the child logs ride in {@link childFiles}.
+     */
+    file: string;
+    /**
+     * Optional sidecar for the PRIMARY session: a bare `ReplayEntry[]` replaces
+     * the derived script; `{ patches }` keeps it and swaps the named call
+     * indexes ({@link ReplayOverrideDoc}). Used by single-session scenarios not
+     * expressible as `assistant/chunk` (throw-before-chunk, cancel/hang,
+     * injected transient failures). Absent for normal and nested scenarios.
+     */
+    overrideFile?: string;
+    /**
+     * Additional recorded child-session logs (a nested-agent scenario's subagent
+     * sessions). Each is derived independently; the full set is ordered by
+     * `createdAt` so the parent (earliest) binds to the first live session. Empty
+     * for a single-session scenario.
+     */
+    childFiles?: string[];
+    /**
+     * Optional provider catalog. When non-empty, replay registers an adapter for
+     * these routes; when absent or empty, it retains the catch-all waterfall used
+     * by tests that do not need discovery.
+     */
+    providers?: ReplayProviderConfig[];
+    /**
+     * Optional per-chunk pacing delay in milliseconds: each replayed chunk waits
+     * this long before yielding, so a downstream transport (e.g. the web SSE
+     * mux observed by a browser) sees genuinely incremental delivery. A realism
+     * knob only — correctness must never depend on it. Absent or `0` keeps
+     * today's synchronous burst yield. Must be a non-negative finite integer;
+     * aborting mid-wait cancels the stream like any other abort.
+     */
+    paceMs?: number;
+}
+/**
+ * Handle returned by {@link installLlmReplay}: removal plus the end-of-run
+ * consumption check that turns silent fixture underruns (a scenario that
+ * issued fewer calls than recorded, or never bound a recorded child script)
+ * into a crisp diagnostic at teardown.
+ */
+export interface ReplayHandle {
+    /** Remove the registered adapter or waterfall listener (HMR safety). Freestanding closure — safe to destructure. */
+    dispose(this: void): void;
+    /**
+     * Throw unless every recorded script was bound to a live session and every
+     * bound cursor consumed its full entry list. Call at scenario teardown.
+     * Freestanding closure — safe to destructure.
+     */
+    assertConsumed(this: void): void;
+}
+/**
+ * Recorded calls plus header facts used to order parent and child scripts.
+ * Recorded ids are diagnostic; fresh live ids bind by ordered first use.
+ */
+export interface SessionScript {
+    /** The recorded session id (diagnostics only — the live id differs). */
+    recordedId: string;
+    /** Session creation time; the deterministic ordering key (parent < child). */
+    createdAt: number;
+    /** The per-`stream()`-call replay entries, in recorded call order. */
+    entries: ReplayEntry[];
+    /**
+     * Whether this is the PRIMARY (parent) session. Breaks a `createdAt` tie in
+     * favor of the parent, which always issues the first model call.
+     */
+    primary: boolean;
+}
+/**
+ * Parse a session `.jsonl` buffer into its event list. Line 0 is the session
+ * header (a `{type:'session',…}` record), every subsequent non-empty line is a
+ * {@link SessionEvent} or a packed chunk row (expanded back into its events, so
+ * a fixture recorded with `packChunks` on derives the same script). The header
+ * is skipped; malformed lines fail loud.
+ * @param text - the raw `.jsonl` file contents.
+ * @returns every event after the header, in log order.
+ */
+export declare function parseSessionLog(text: string): SessionEvent[];
+/**
+ * Read replay identity, ordering, and fork-seed facts from the JSONL header.
+ *
+ * @param text - the raw `.jsonl` file contents (only the header line is read).
+ * @returns the header's `id`, `createdAt`, and `seedLength`, defaulted when absent.
+ */
+export declare function parseSessionHeader(text: string): {
+    id: string;
+    createdAt: number;
+    seedLength: number;
+};
+/**
+ * Reconstruct the per-`stream()` replay script from a recorded session log.
+ *
+ * Splits `assistant/chunk` events at every `finish`, using turn and step changes
+ * to detect an unterminated prior call. A `compact/summary` explicitly marked
+ * as one local LLM-stream call becomes a canonical successful stream from its
+ * complete `rawOutput` at the summary's log position. A
+ * missing assistant terminator means the live stream threw, so derivation
+ * rejects and the scenario must provide an explicit override. Multiple calls
+ * may share one turn and step when the loop retries.
+ * @param events - the recorded session's events.
+ * @returns one `chunks` entry per recorded model call, in call order.
+ */
+export declare function deriveReplayScript(events: SessionEvent[]): ReplayEntry[];
+/**
+ * One positional patch in an augmentation sidecar: replaces the derived
+ * entry at call index `at` (0-based) with `entry`, or appends when `at`
+ * equals the derived length (an extra recorded-after-the-fact call, e.g. the
+ * retry attempt following an injected transient throw).
+ */
+export interface ReplayOverridePatch {
+    /** 0-based call index into the derived script; == length appends. */
+    at: number;
+    /** The replacement (or appended) entry at that call position. */
+    entry: ReplayEntry;
+}
+/**
+ * Override sidecar document: either a whole-script replacement (a
+ * bare `ReplayEntry[]`) or the augmentation form `{ patches }`, which keeps
+ * the JSONL-derived script and swaps only the named call indexes — the shape
+ * for "turn N errors, everything else replays as recorded".
+ */
+export type ReplayOverrideDoc = ReplayEntry[] | {
+    patches: ReplayOverridePatch[];
+};
+/**
+ * Resolve every `{{fromRequest:<regex>}}` placeholder in one scripted entry
+ * against the live request. The corpus is every string leaf of the request
+ * messages joined by newlines; the pattern's LAST corpus match wins and its
+ * first capture group (or, without one, the whole match) substitutes in place.
+ * Scenario sidecars use this to script arguments no static file can know,
+ * such as a randomly minted goal id the model must echo back. A pattern that
+ * matches nothing, an invalid pattern, and an unterminated placeholder each
+ * fail loud. The last two braces of a consecutive `}` run terminate the
+ * placeholder, so a pattern may end with a brace quantifier but cannot
+ * contain `}}` followed by further pattern content. Derived entries pass
+ * through the same resolution as sidecar entries.
+ * @param entry - the scripted entry about to replay.
+ * @param messages - the live request messages searched by the placeholders.
+ * @returns the entry itself when no placeholder appears, else a resolved deep copy.
+ */
+export declare function resolveScriptedEntry(entry: ReplayEntry, messages: GenerateOptions['messages']): ReplayEntry;
+/**
+ * Load the PRIMARY session's replay script: the sidecar override when present
+ * (whole-script replacement or `{ patches }` augmentation over the derived
+ * script), else the script derived from the session JSONL (fail-loud when the
+ * fixture is missing).
+ * @param config - the fixture paths; only `file` and `overrideFile` are consulted.
+ * @returns the resolved primary-session script.
+ */
+export declare function loadReplayScript(config: ReplayConfig): ReplayEntry[];
+/**
+ * Load the primary and child scripts in bind order. Child derivation begins at
+ * `seedLength` so inherited parent chunks are never replayed as child calls.
+ *
+ * @param config - the fixture paths: the primary log plus any recorded child logs.
+ * @returns the primary script first, then the child scripts in bind order.
+ */
+export declare function loadSessionScripts(config: ReplayConfig): SessionScript[];
+/**
+ * Install per-session positional replay. A newly seen live session takes the
+ * next ordered recorded script, then advances its own cursor synchronously at
+ * invocation time; calls without `sessionId` share one anonymous session. A
+ * non-empty provider catalog registers a routed replay adapter; otherwise a
+ * catch-all waterfall intercepts requests.
+ *
+ * @param ctx - the context whose LLM service receives the replay route or waterfall.
+ * @param config - the resolved fixture paths (env-var defaulting is `apply`'s job).
+ * @returns the {@link ReplayHandle} carrying the disposer and the teardown consumption check.
+ */
+export declare function installLlmReplay(ctx: Context, config: ReplayConfig): ReplayHandle;
+export declare const name = "llm-replay";
+export declare const inject: string[];
+/** Plugin config: the {@link ReplayConfig} inputs, each defaulting to its `DSH_SNAPSHOT_*` env var in `apply`. */
+export interface Config {
+    /** Override the fixture path; defaults to `$DSH_SNAPSHOT_FILE`. */
+    file?: string;
+    /** Override the sidecar path; defaults to `$DSH_SNAPSHOT_OVERRIDE`. */
+    overrideFile?: string;
+    /**
+     * Override the child-log paths; defaults to `$DSH_SNAPSHOT_CHILD_FILES` (a
+     * path-separator-delimited list). Each is a recorded subagent session log for
+     * a nested-agent scenario; absent/empty for a single-session scenario.
+     */
+    childFiles?: string[];
+    /** Optional replay-only provider catalog; absent or empty selects catch-all waterfall replay. */
+    providers?: ReplayProviderConfig[];
+    /** Optional per-chunk pacing delay in ms (see {@link ReplayConfig.paceMs}); absent keeps burst yield. */
+    paceMs?: number;
+}
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-llm-replay`.
+ * @module @deepseek-ai/dsh-llm-replay/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "llm-replay-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@deepseek-ai/dsh-llm-replay",
+  "description": "Replay LLM plugin: short-circuits llm/stream with model chunks reconstructed from a recorded session JSONL (keyless snapshot tests)",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/support/llm-replay"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-compact": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-compact": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}