@lucascouts/claude-agent-tui 0.1.0

package/dist/diff-enriched-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-enriched-reader.d.ts","sourceRoot":"","sources":["../src/diff-enriched-reader.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzE;AAED,mGAAmG;AACnG,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IACjD;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,WAAW,EACjB,IAAI,GAAE,yBAA8B,GACnC,WAAW,CAoCb"}

package/dist/diff-enriched-reader.js

@@ -0,0 +1,106 @@
+// Story 043 / Task 1.1 (R1.1, R1.2, R1.3, R4.2) — the diff-enriched reduced-shape reader.
+//
+// PROBLEM. `getSessionMessages` returns the REDUCED shape (6 fields; see the
+// getsessionmessages-reduced-shape follow-up): it does NOT carry the per-type `toolUseResult` that the
+// story-021/026 Edit/Write diff block reads off `turn.message.toolUseResult` (acp-agent.ts:1461). With
+// the PTY engine the PostToolUse hook that once produced diffs is GONE, so a live pump over the reduced
+// shape renders no diff — the diff silently no-ops.
+//
+// SOLUTION (REUSE-faithful, billing-free). WRAP the base reader and HYDRATE each returned message's
+// `toolUseResult` from the raw JSONL transcript, matched by `uuid`:
+//   - ordering / identity stay the base reader's (the SDK is the single parser; we add ONE key);
+//   - the raw read is a pure `fs` read of the transcript located via `findTranscript(sessionId)` — NO
+//     SDK call, so NO token billing (R4.2);
+//   - a message whose raw record has no `toolUseResult` is returned UNCHANGED — we NEVER fabricate a
+//     patch (R1.2 / R4.2);
+//   - any failure to locate / read / parse the transcript falls back to the plain reduced messages so
+//     the diff degrades to the existing graceful no-op and the pump NEVER crashes (R1.3).
+//
+// DEVIATION (recorded in .draft/deviations.yaml, task 1.1/2.2). design.md sketched
+// `createDiffEnrichedReader(session.transcriptPath, base)`, but `session.transcriptPath` does not exist
+// (neither SessionState nor StartedEngine expose it) and `this.getMessages` is AGENT-level (shared
+// across sessions). So the reader derives the path itself from the `sessionId` it already receives via
+// `findTranscript(sessionId)[0]` — keeping the wiring agent-level (one `this.getMessages` covers both
+// pumpUpdates and replaySessionHistory), multi-session safe, and correct on the story-028 fresh path
+// (the path resolves at use-time, when the transcript already exists).
+//
+// node: builtins + the in-fork jsonl glob only — no new runtime dep, no lib.ts export (frozen surface).
+import { readFileSync } from "node:fs";
+import { findTranscript as defaultFindTranscript } from "./jsonl.js";
+/**
+ * Build a `uuid → toolUseResult` index from raw JSONL transcript lines.
+ *
+ * Only records that ARE plain objects carrying BOTH a string `uuid` AND a defined `toolUseResult`
+ * enter the map — a record without a `toolUseResult` is intentionally absent so the matching message is
+ * returned unchanged (R1.2). Empty/whitespace lines and malformed JSON are skipped silently (robustness:
+ * a torn or partially-written final line must never throw and abort the hydration).
+ *
+ * @param rawLines the transcript's newline-split lines (READ-ONLY; never mutated).
+ * @returns a map from message uuid to its raw `toolUseResult` value (possibly empty).
+ */
+export function toolUseResultMap(rawLines) {
+    const map = new Map();
+    for (const line of rawLines) {
+        if (line.trim() === "")
+            continue; // skip blank lines (e.g. the trailing newline split)
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue; // malformed / partially-written line — skip silently, never throw
+        }
+        if (rec === null || typeof rec !== "object")
+            continue;
+        const { uuid, toolUseResult } = rec;
+        if (typeof uuid === "string" && toolUseResult !== undefined) {
+            map.set(uuid, toolUseResult);
+        }
+    }
+    return map;
+}
+/**
+ * Wrap a base `getSessionMessages`-shaped reader so each returned message gains its `toolUseResult`
+ * from the raw transcript, matched by `uuid`. This is PURE hydration: ordering and identity come from
+ * `base`; only the top-level `toolUseResult` key is added (exactly where the diff block reads it,
+ * `turn.message.toolUseResult`). Billing-free — the only extra cost is one `fs` read of the transcript
+ * located from the `sessionId` (R4.2). On ANY locate/read/parse failure, or when no record carries a
+ * `toolUseResult`, the plain reduced messages are returned unchanged (R1.3) and NO patch is fabricated.
+ *
+ * @param base the underlying reader (the SDK `getSessionMessages`, or an injected stub).
+ * @param opts injectable {@link DiffEnrichedReaderOptions} seams (defaults are production behaviour).
+ * @returns a {@link GetMessages} that yields the base messages with `toolUseResult` hydrated by uuid.
+ */
+export function createDiffEnrichedReader(base, opts = {}) {
+    const findTranscript = opts.findTranscript ?? defaultFindTranscript;
+    const readRawLines = opts.readRawLines ?? ((path) => readFileSync(path, "utf8").split("\n"));
+    return async (sessionId, readerOpts) => {
+        // base is the single source of order/identity (and the only billed reader) — invoked exactly once.
+        const reduced = await base(sessionId, readerOpts);
+        // Locate the transcript from the sessionId. A throw OR an empty glob → no raw source: return the
+        // reduced messages unchanged (R1.3; no fabrication, R4.2).
+        let path;
+        try {
+            path = findTranscript(sessionId)[0];
+        }
+        catch {
+            return reduced;
+        }
+        if (!path)
+            return reduced;
+        // Read the raw transcript. A read failure must NEVER crash the pump → fall back to reduced (R1.3).
+        let raw;
+        try {
+            raw = readRawLines(path);
+        }
+        catch {
+            return reduced;
+        }
+        const map = toolUseResultMap(raw);
+        if (map.size === 0)
+            return reduced; // nothing to hydrate → reduced unchanged
+        // Attach the matched toolUseResult as a top-level key; unmatched messages pass through UNCHANGED
+        // (they never gain a `toolUseResult` key — R1.2 / R4.2).
+        return reduced.map((m) => typeof m.uuid === "string" && map.has(m.uuid) ? { ...m, toolUseResult: map.get(m.uuid) } : m);
+    };
+}

package/dist/diff-source.d.ts

@@ -0,0 +1,104 @@
+import type { ToolCallContent } from "@agentclientprotocol/sdk";
+/** A single diff hunk — the unit the reused `toolUpdateFromDiffToolResponse` reads `lines` from. */
+export interface Hunk {
+    readonly oldStart: number;
+    readonly oldLines: number;
+    readonly newStart: number;
+    readonly newLines: number;
+    readonly lines: readonly string[];
+}
+/**
+ * The classification of a `toolUseResult` as a diff source, discriminated by `kind`.
+ *
+ * - `not-a-diff-source` — the payload carries none of the diff-source fields and cannot
+ *   reconstruct a diff (Task 1.1; e.g. a `file-history-snapshot`).
+ * - `edit` — an Edit (`type:update`): carries `filePath`, the pre-edit `originalFile`, and the
+ *   `structuredPatch` hunks fed VERBATIM to the reused translator.
+ * - `write` — a Write (`type:create`): carries `filePath` and the new-file `content` (its
+ *   structuredPatch is empty; the renderable hunk is synthesised in {@link toDiffToolResponse}).
+ * - `unsupported` — a diff-bearing payload whose shape could not be verified (skip-and-logged).
+ */
+export type DiffSource = {
+    readonly kind: "not-a-diff-source";
+} | {
+    readonly kind: "edit";
+    readonly filePath: string;
+    readonly originalFile: string;
+    readonly structuredPatch: readonly Hunk[];
+} | {
+    readonly kind: "write";
+    readonly filePath: string;
+    readonly content: string;
+} | {
+    readonly kind: "unsupported";
+    readonly tool?: string;
+};
+/** The source shape consumed by the reused `toolUpdateFromDiffToolResponse` (tools.ts). */
+export interface DiffToolResponseInput {
+    readonly filePath: string;
+    readonly structuredPatch: readonly Hunk[];
+}
+/**
+ * Classify a `user` event's `toolUseResult` as a diff source.
+ *
+ * Returns, in order: `not-a-diff-source` when `toolUseResult` is not a non-null object, or holds NONE
+ * of the diff-source fields (`structuredPatch` array / `content` / `originalFile`) AND its tool name
+ * is not diff-bearing (Task 1.1; e.g. a `file-history-snapshot`, name `undefined`); `unsupported`
+ * (skip-and-logged) when a diff-bearing tool name (Task 3.2 — `MultiEdit`/`NotebookEdit`/`mcp__…`)
+ * carries an unmappable shape; `edit` for an Edit (`name === "Edit"`, or a non-empty `structuredPatch`
+ * paired with a string `originalFile` — so a recognised MultiEdit shape maps here too), carrying
+ * `{filePath, originalFile, structuredPatch}`; `write` for a Write (`name === "Write"`, or an EMPTY
+ * `structuredPatch` paired with a string `content`), carrying `{filePath, content}`; and `unsupported`
+ * (skip-and-logged) for a diff-bearing payload whose required field is missing or the wrong type.
+ * NEVER throws; NEVER emits a half-built edit/write with an undefined field; NEVER aborts the pipeline.
+ *
+ * @param name - The originating tool name (`Edit`, `Write`, …), or `undefined` when unknown.
+ * @param toolUseResult - The raw `toolUseResult` value to inspect (READ-ONLY, never mutated).
+ * @returns A {@link DiffSource}.
+ */
+export declare function classifyDiffSource(name: string | undefined, toolUseResult: unknown): DiffSource;
+/**
+ * Assemble the `{filePath, structuredPatch}` input consumed by the reused
+ * `toolUpdateFromDiffToolResponse` (tools.ts) — the only thing this module produces for rendering.
+ *
+ * - `edit` — pass the hunks through VERBATIM (same array reference): `{filePath, structuredPatch}`.
+ * - `write` — normalise to a single synthetic all-additions hunk (see {@link syntheticAdditionHunk})
+ *   so the reused translator emits `oldText:null` / newText=`content`.
+ * - `unsupported` / `not-a-diff-source` — not renderable; returns `null`.
+ *
+ * This module does NOT call `toolUpdateFromDiffToolResponse` and does NOT hand-build diff content —
+ * the caller (the tests now; story 023 later) feeds this input to the reused translator.
+ *
+ * @param source - A {@link DiffSource} from {@link classifyDiffSource}.
+ * @returns The reused translator's input, or `null` when `source` is not renderable.
+ */
+export declare function toDiffToolResponse(source: DiffSource): DiffToolResponseInput | null;
+/**
+ * The §7 `tool_call_update` envelope carrying rendered diff content, attached to an OPEN tool call.
+ *
+ * It updates an already-open tool call (the story 019 seam keyed by `toolCallId`); it does NOT open a
+ * new one. `content` is the diff content rendered by the reused `toolUpdateFromDiffToolResponse`.
+ */
+export interface DiffToolCallUpdate {
+    readonly sessionUpdate: "tool_call_update";
+    readonly toolCallId: string;
+    readonly content: ToolCallContent[];
+}
+/**
+ * Render a classified diff source into a §7 `tool_call_update` (Task 3.1, R4.1/R4.2).
+ *
+ * Feeds {@link toDiffToolResponse}'s `{filePath, structuredPatch}` input to the REUSED, unmodified
+ * `toolUpdateFromDiffToolResponse` (tools.ts §3) — the ONLY place this module calls the reused
+ * translator — and wraps the rendered hunks in the envelope attached to the OPEN `toolCallId` (story
+ * 019 seam; this does not open a new tool call). The reused translator dictates oldText/newText
+ * (Decision A): for an Edit the JSONL `structuredPatch` is fed VERBATIM (shim: none); for a Write the
+ * synthetic all-additions hunk is supplied by {@link toDiffToolResponse} (the empty structuredPatch is
+ * not accepted verbatim), so the new file renders with `oldText:null`.
+ *
+ * @param source - A {@link DiffSource} from {@link classifyDiffSource}.
+ * @param toolCallId - The OPEN tool call id the diff content attaches to.
+ * @returns The `tool_call_update` envelope, or `null` when `source` is not renderable or yields no
+ *   diff content (an unsupported/not-a-diff-source source, or a translation with no `content`).
+ */
+export declare function diffToolCallUpdate(source: DiffSource, toolCallId: string): DiffToolCallUpdate | null;
+//# sourceMappingURL=diff-source.d.ts.map

package/dist/diff-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-source.d.ts","sourceRoot":"","sources":["../src/diff-source.ts"],"names":[],"mappings":"AAgEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAGhE,oGAAoG;AACpG,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GACtC;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,SAAS,IAAI,EAAE,CAAC;CAC3C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,2FAA2F;AAC3F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,SAAS,IAAI,EAAE,CAAC;CAC3C;AAsCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,aAAa,EAAE,OAAO,GAAG,UAAU,CAiD/F;AAoBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,qBAAqB,GAAG,IAAI,CAanF;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,GACjB,kBAAkB,GAAG,IAAI,CAU3B"}

package/dist/diff-source.js

@@ -0,0 +1,164 @@
+import { toolUpdateFromDiffToolResponse } from "./tools.js";
+/** The not-a-diff-source result is a singleton — it carries no payload, so it can be shared. */
+const NOT_A_DIFF_SOURCE = { kind: "not-a-diff-source" };
+/** True when `value` is a non-null object (the only shape that can hold diff-source fields). */
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/** True when `value` is a string — the type both `originalFile` and `content` must have to be usable. */
+function isString(value) {
+    return typeof value === "string";
+}
+/** The explicit diff-producing tool names (besides the `mcp__` prefix, handled in {@link isDiffBearingName}). */
+const DIFF_BEARING_NAMES = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+/**
+ * True when `name` denotes a diff-producing tool (Task 3.2). A contentless payload from such a tool is
+ * skip-and-logged drift telemetry (`unsupported`), whereas a contentless payload with NO diff-bearing
+ * name (e.g. a `file-history-snapshot`, name `undefined`) stays the silent `not-a-diff-source` (Task
+ * 1.1). The set is {@link DIFF_BEARING_NAMES} plus any MCP tool (`mcp__…`); never assume a fixed set.
+ */
+function isDiffBearingName(name) {
+    return name !== undefined && (DIFF_BEARING_NAMES.has(name) || name.startsWith("mcp__"));
+}
+/**
+ * Skip-and-log seam (§6, consistent with event-switch.ts): a diff-bearing payload whose shape could
+ * not be verified is logged to STDERR — NEVER stdout, which carries the ACP stream — and degraded to
+ * `unsupported`. Returning the discriminated result keeps every caller a single tolerant expression.
+ */
+function skipAndLog(name, reason) {
+    console.error(`[diff-source] skipping ${name ?? "<unknown tool>"}: ${reason}`);
+    return { kind: "unsupported", tool: name };
+}
+/**
+ * Classify a `user` event's `toolUseResult` as a diff source.
+ *
+ * Returns, in order: `not-a-diff-source` when `toolUseResult` is not a non-null object, or holds NONE
+ * of the diff-source fields (`structuredPatch` array / `content` / `originalFile`) AND its tool name
+ * is not diff-bearing (Task 1.1; e.g. a `file-history-snapshot`, name `undefined`); `unsupported`
+ * (skip-and-logged) when a diff-bearing tool name (Task 3.2 — `MultiEdit`/`NotebookEdit`/`mcp__…`)
+ * carries an unmappable shape; `edit` for an Edit (`name === "Edit"`, or a non-empty `structuredPatch`
+ * paired with a string `originalFile` — so a recognised MultiEdit shape maps here too), carrying
+ * `{filePath, originalFile, structuredPatch}`; `write` for a Write (`name === "Write"`, or an EMPTY
+ * `structuredPatch` paired with a string `content`), carrying `{filePath, content}`; and `unsupported`
+ * (skip-and-logged) for a diff-bearing payload whose required field is missing or the wrong type.
+ * NEVER throws; NEVER emits a half-built edit/write with an undefined field; NEVER aborts the pipeline.
+ *
+ * @param name - The originating tool name (`Edit`, `Write`, …), or `undefined` when unknown.
+ * @param toolUseResult - The raw `toolUseResult` value to inspect (READ-ONLY, never mutated).
+ * @returns A {@link DiffSource}.
+ */
+export function classifyDiffSource(name, toolUseResult) {
+    if (!isObject(toolUseResult)) {
+        return NOT_A_DIFF_SOURCE;
+    }
+    const structuredPatch = toolUseResult.structuredPatch;
+    const hasStructuredPatch = Array.isArray(structuredPatch);
+    const hasContent = "content" in toolUseResult;
+    const hasOriginalFile = "originalFile" in toolUseResult;
+    // No diff-source field is present. A diff-bearing tool name (Task 3.2 — MultiEdit/NotebookEdit/MCP)
+    // means a tool that SHOULD have produced a patch shipped one we cannot map: detect + log it as drift
+    // telemetry and degrade to `unsupported`. A payload with no diff-bearing name (e.g. a
+    // `file-history-snapshot`, name `undefined`) is the silent `not-a-diff-source` (Task 1.1).
+    if (!hasStructuredPatch && !hasContent && !hasOriginalFile) {
+        return isDiffBearingName(name)
+            ? skipAndLog(name, "diff-bearing tool produced no usable structuredPatch/originalFile/content")
+            : NOT_A_DIFF_SOURCE;
+    }
+    const filePath = toolUseResult.filePath;
+    const originalFile = toolUseResult.originalFile;
+    const content = toolUseResult.content;
+    // Edit (`type:update`): an explicit Edit name, OR a non-empty structuredPatch alongside a string
+    // `originalFile`. The hunks reconstruct the diff; without `originalFile` (or without a usable
+    // filePath/patch) the Edit shape is unverified and skipped — never a half-built edit.
+    const looksLikeEdit = name === "Edit" || (hasStructuredPatch && structuredPatch.length > 0 && isString(originalFile));
+    if (looksLikeEdit) {
+        if (!isString(filePath) || !isString(originalFile) || !hasStructuredPatch) {
+            return skipAndLog(name, "Edit is missing filePath, originalFile, or structuredPatch");
+        }
+        return { kind: "edit", filePath, originalFile, structuredPatch: structuredPatch };
+    }
+    // Write (`type:create`): an explicit Write name, OR an EMPTY structuredPatch alongside a string
+    // `content`. The new-file body lives in `content`; without it there is nothing to render — skip.
+    const looksLikeWrite = name === "Write" || (hasStructuredPatch && structuredPatch.length === 0 && isString(content));
+    if (looksLikeWrite) {
+        if (!isString(filePath) || !isString(content)) {
+            return skipAndLog(name, "Write is missing filePath or content");
+        }
+        return { kind: "write", filePath, content };
+    }
+    // A diff-source field IS present but the shape matched neither a verifiable Edit nor Write.
+    return skipAndLog(name, "diff-bearing payload of an unverified shape");
+}
+/**
+ * Build one synthetic all-additions hunk from a new file's `content` (Decision A, D3).
+ *
+ * Every line of `content` is prefixed `+`, so the reused translator — which reads only the hunk
+ * `lines` — collects NO `-`/context lines and therefore yields `oldText:null` (literal null) and
+ * newText=`content`. The hunk header marks the whole body as added: oldStart/oldLines 0/0, newStart 1.
+ */
+function syntheticAdditionHunk(content) {
+    const lines = content.split("\n");
+    return {
+        oldStart: 0,
+        oldLines: 0,
+        newStart: 1,
+        newLines: lines.length,
+        lines: lines.map((line) => "+" + line),
+    };
+}
+/**
+ * Assemble the `{filePath, structuredPatch}` input consumed by the reused
+ * `toolUpdateFromDiffToolResponse` (tools.ts) — the only thing this module produces for rendering.
+ *
+ * - `edit` — pass the hunks through VERBATIM (same array reference): `{filePath, structuredPatch}`.
+ * - `write` — normalise to a single synthetic all-additions hunk (see {@link syntheticAdditionHunk})
+ *   so the reused translator emits `oldText:null` / newText=`content`.
+ * - `unsupported` / `not-a-diff-source` — not renderable; returns `null`.
+ *
+ * This module does NOT call `toolUpdateFromDiffToolResponse` and does NOT hand-build diff content —
+ * the caller (the tests now; story 023 later) feeds this input to the reused translator.
+ *
+ * @param source - A {@link DiffSource} from {@link classifyDiffSource}.
+ * @returns The reused translator's input, or `null` when `source` is not renderable.
+ */
+export function toDiffToolResponse(source) {
+    switch (source.kind) {
+        case "edit":
+            return { filePath: source.filePath, structuredPatch: source.structuredPatch };
+        case "write":
+            return {
+                filePath: source.filePath,
+                structuredPatch: [syntheticAdditionHunk(source.content)],
+            };
+        case "unsupported":
+        case "not-a-diff-source":
+            return null;
+    }
+}
+/**
+ * Render a classified diff source into a §7 `tool_call_update` (Task 3.1, R4.1/R4.2).
+ *
+ * Feeds {@link toDiffToolResponse}'s `{filePath, structuredPatch}` input to the REUSED, unmodified
+ * `toolUpdateFromDiffToolResponse` (tools.ts §3) — the ONLY place this module calls the reused
+ * translator — and wraps the rendered hunks in the envelope attached to the OPEN `toolCallId` (story
+ * 019 seam; this does not open a new tool call). The reused translator dictates oldText/newText
+ * (Decision A): for an Edit the JSONL `structuredPatch` is fed VERBATIM (shim: none); for a Write the
+ * synthetic all-additions hunk is supplied by {@link toDiffToolResponse} (the empty structuredPatch is
+ * not accepted verbatim), so the new file renders with `oldText:null`.
+ *
+ * @param source - A {@link DiffSource} from {@link classifyDiffSource}.
+ * @param toolCallId - The OPEN tool call id the diff content attaches to.
+ * @returns The `tool_call_update` envelope, or `null` when `source` is not renderable or yields no
+ *   diff content (an unsupported/not-a-diff-source source, or a translation with no `content`).
+ */
+export function diffToolCallUpdate(source, toolCallId) {
+    const input = toDiffToolResponse(source);
+    if (input === null) {
+        return null;
+    }
+    const { content } = toolUpdateFromDiffToolResponse(input);
+    if (content === undefined || content.length === 0) {
+        return null;
+    }
+    return { sessionUpdate: "tool_call_update", toolCallId, content };
+}

package/dist/end-of-turn.d.ts

@@ -0,0 +1,172 @@
+import type { PromptResponse } from "@agentclientprotocol/sdk";
+import { TURN_WATCHDOG_MS } from "./linearize.js";
+import { FILE_DISCOVERY_WATCHDOG_MS } from "./jsonl.js";
+import { type StopReasonLogger } from "./stop-reason-map.js";
+export { TURN_WATCHDOG_MS, FILE_DISCOVERY_WATCHDOG_MS };
+/**
+ * Default STALL window (ms): the watchdog trips only after this much transcript silence while a
+ * turn is in flight. Generous on purpose — a long text block or tool run writes nothing for tens of
+ * seconds; the watchdog exists to fail a DEAD turn loudly (R5.2), not to cap a slow one.
+ */
+export declare const TURN_STALL_WATCHDOG_MS = 120000;
+/** Env var overriding the default stall window per process (positive integer ms). */
+export declare const TURN_WATCHDOG_ENV = "FORK_TURN_WATCHDOG_MS";
+/**
+ * The TERMINAL `message.stop_reason` values (E3 augmented predicate, Binding decision 2). An
+ * `assistant` event whose stop_reason is one of these is an end-of-turn boundary CANDIDATE; a
+ * `tool_use` pause (or `null`) is mid-turn and NOT a boundary. Typed `ReadonlySet` so the set
+ * cannot drift at a call site.
+ */
+export declare const TERMINAL_STOP_REASONS: ReadonlySet<string>;
+/**
+ * The minimal structural shape the predicate reads off a story-015/016 typed `JsonlEvent` (only
+ * `.type` and `.message` are inspected). Kept structural — and every field `unknown` — so the
+ * predicate stays defensive: it never assumes a fixed `.type` set and never throws on a string-or-
+ * array `message.content` (§6 tolerant parser, R1.2/R3 forward-compat).
+ */
+export interface StopReasonEvent {
+    readonly type?: unknown;
+    readonly message?: unknown;
+    /** Sidechain (subagent) back-pointer, SDK snake_case — non-null marks a sidechain row (R4.1). */
+    readonly parent_tool_use_id?: unknown;
+    /** Sidechain back-pointer, story-015 typed alias — read alongside the snake_case form (R4.1). */
+    readonly parentToolUseId?: unknown;
+}
+/**
+ * The E3 augmented predicate (Binding decision 2): is `event` an `assistant` event whose
+ * `message.stop_reason` is a TERMINAL value? Reads everything defensively — a non-`assistant`
+ * `.type`, a missing/string `message`, or a `null`/`undefined`/`tool_use` stop_reason all yield
+ * `false`. Pure and total: never throws.
+ *
+ * Story 041 (R4.1): a SIDECHAIN row (non-null `parent_tool_use_id`) is EXCLUDED — its terminal stop
+ * is the subagent's own turn ending and must never end the parent turn.
+ */
+export declare function isTerminalStop(event: StopReasonEvent | null | undefined): boolean;
+/**
+ * The LAST event in `events` satisfying {@link isTerminalStop} — the single per-turn boundary
+ * candidate (E3 picks the LAST terminal `assistant`, so a turn that streamed several assistant
+ * blocks collapses to one boundary). Returns `undefined` when no event is terminal (e.g. a
+ * `tool_use`-only turn still in flight). Pure; never throws on an unknown `.type` or string content.
+ */
+export declare function findTerminalCandidate<E extends StopReasonEvent>(events: readonly E[]): E | undefined;
+/**
+ * The Δt quiescence window (ms) — E3 binding decision 2: the SMALLEST zero-false-positive window
+ * (Δt sweep, experiments/DECISION.md). A terminal candidate is confirmed only after Δt of silence
+ * with no further user/assistant write. Consumed VERBATIM from E3 — NOT re-derived here.
+ */
+export declare const DELTA_T_MS = 200;
+/**
+ * Injectable timer seam: schedule `fn` after `ms`, returning a cancel function. The detector takes
+ * it as an option so tests drive a deterministic fake clock (mirrors `bindEndOfTurnReparse`); the
+ * default wraps `setTimeout`/`clearTimeout`.
+ */
+export type DetectorSchedule = (fn: () => void, ms: number) => () => void;
+/** Diagnostics carried by a {@link TurnTimeoutError} — the last-seen event and the elapsed window. */
+export interface TurnTimeoutDiagnostics {
+    /** The turn-watchdog window that elapsed (ms). */
+    readonly elapsedMs: number;
+    /** The `.type` of the last event the detector saw before the watchdog tripped, if any. */
+    readonly lastEventType?: string;
+    /** The `message.stop_reason` of that last event, if any. */
+    readonly lastStopReason?: string;
+    /** The session whose turn stalled, if known. */
+    readonly sessionId?: string;
+}
+/**
+ * Typed error surfaced when no end-of-turn is detected within the 5583 ms turn watchdog (R5.2). It
+ * carries the elapsed window plus last-seen-event diagnostics so the §5 stall is observable for R2
+ * runtime telemetry instead of hanging the ACP protocol silently.
+ */
+export declare class TurnTimeoutError extends Error {
+    readonly elapsedMs: number;
+    readonly lastEventType?: string;
+    readonly lastStopReason?: string;
+    readonly sessionId?: string;
+    constructor(diag: TurnTimeoutDiagnostics);
+}
+/** Options for {@link createEndOfTurnDetector}. */
+export interface EndOfTurnDetectorOptions {
+    /** Invoked exactly once per confirmed turn boundary, with the terminal candidate event. */
+    onEndOfTurn: (boundary: StopReasonEvent) => void;
+    /** Invoked when the turn watchdog trips before any end-of-turn (R5.2). */
+    onTurnTimeout?: (error: TurnTimeoutError) => void;
+    /** Timer seam (default wraps setTimeout). */
+    schedule?: DetectorSchedule;
+    /** Δt quiescence window (ms); defaults to {@link DELTA_T_MS}. */
+    deltaTMs?: number;
+    /**
+     * STALL window (ms): silence tolerated between observed events while a turn is in flight.
+     * Defaults to the {@link TURN_WATCHDOG_ENV} env override when valid, else
+     * {@link TURN_STALL_WATCHDOG_MS}. Pass {@link TURN_WATCHDOG_MS} explicitly for the E3 cap.
+     */
+    watchdogMs?: number;
+    /** The session whose turns this detector watches — carried in {@link TurnTimeoutError}. */
+    sessionId?: string;
+    /** Telemetry sink for a stalled turn (R2). The timeout is also surfaced via `onTurnTimeout`. */
+    logger?: {
+        error: (...args: unknown[]) => void;
+    };
+}
+/** Handle returned by {@link createEndOfTurnDetector}. */
+export interface EndOfTurnDetector {
+    /** Arm the turn watchdog — call when a turn becomes in-flight (the prompt loop, story 023). */
+    beginTurn(): void;
+    /** Feed the next watched event, in arrival order. */
+    observe(event: StopReasonEvent): void;
+    /**
+     * Liveness-only kick (story 044, Option B): re-arm the stall watchdog iff a turn is in flight (the
+     * watchdog is armed). Registers NO event, touches NO boundary/openTaskIds/diagnostics state — it is
+     * purely "the turn is still alive". Called by the sub-agent watcher on observed sub-agent progress
+     * so a silent main chain with an active sub-agent never trips the watchdog (R1.2). No-op when
+     * stopped, cancelled, or not armed (replay/load never starts a stall clock).
+     */
+    noteActivity(): void;
+    /**
+     * Cancel seam (the Degrau-2 story 030 calls this): set the single-resolution latch and clear both
+     * the Δt timer and the turn watchdog, so the detector cannot also fire an end-of-turn for this turn
+     * (no double-resolve, R3.4). Read-only — it does NOT resolve the ACP session/prompt here.
+     */
+    markCancelled(): void;
+    /** Tear down: cancel any armed timer and suppress further signals. Idempotent. */
+    stop(): void;
+}
+/**
+ * The end-of-turn detector: feed it the linearized turn events via {@link EndOfTurnDetector.observe}
+ * and it emits exactly one end-of-turn per turn. A terminal candidate (Task 1) arms a Δt timer; the
+ * boundary is confirmed on Δt quiescence (here) or immediately on a queued follow-up write (Task 2.2).
+ * A `fired` latch keyed on the boundary uuid prevents the same terminal event from firing twice.
+ */
+export declare function createEndOfTurnDetector(opts: EndOfTurnDetectorOptions): EndOfTurnDetector;
+/** Options for {@link createTurnResolver} — forwarded to the underlying detector. */
+export interface TurnResolverOptions {
+    schedule?: DetectorSchedule;
+    sessionId?: string;
+    logger?: StopReasonLogger;
+    deltaTMs?: number;
+    watchdogMs?: number;
+}
+/** A detector paired with the awaitable {@link PromptResponse} the prompt() loop returns. */
+export interface TurnResolver {
+    /** Feed events here (and arm the turn via `beginTurn`). */
+    detector: EndOfTurnDetector;
+    /** Settles once: resolves with the mapped PromptResponse, or rejects with a TurnTimeoutError. */
+    promise: Promise<PromptResponse>;
+    /**
+     * Story 031 (R2.1, R2.2, R3.1) — claim the story-024 single-resolution latch to resolve the
+     * prompt as `{ stopReason: "cancelled" }`, then call `detector.markCancelled()` to clear its Δt +
+     * watchdog. A no-op if the turn already settled (the latch is the arbiter): a racing detector
+     * boundary, a watchdog trip, or a second `cancel()` cannot produce a second resolution. This is
+     * story-031 wiring that CALLS the latch — it does NOT re-implement it.
+     */
+    cancel(): void;
+}
+/**
+ * Wrap the end-of-turn detector in the awaitable the rewritten `prompt()` loop (story 023) returns
+ * (R2). The promise stays pending across every mid-turn event and settles EXACTLY ONCE — resolving
+ * with `{ stopReason: mapStopReason(boundary.message.stop_reason) }` on the confirmed boundary, or
+ * rejecting with the surfaced {@link TurnTimeoutError} on a watchdog trip. A single-resolution latch
+ * makes a detector/watchdog/cancel race settle the prompt exactly once (and stops the detector so a
+ * late boundary cannot produce a second settlement).
+ */
+export declare function createTurnResolver(opts?: TurnResolverOptions): TurnResolver;
+//# sourceMappingURL=end-of-turn.d.ts.map

package/dist/end-of-turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"end-of-turn.d.ts","sourceRoot":"","sources":["../src/end-of-turn.ts"],"names":[],"mappings":"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"}