@kuralle-syrinx/kuralle 4.4.0 → 4.5.0

package/dist/from-kuralle.d.ts

@@ -0,0 +1,100 @@
+import type { Reasoner, ReasonerTurn, ReasoningPart } from "@kuralle-syrinx/core";
+export interface KuralleStreamPart {
+    readonly [key: string]: unknown;
+    readonly type: string;
+    readonly delta?: string;
+    readonly toolName?: string;
+    readonly args?: unknown;
+    readonly toolCallId?: string;
+    readonly result?: unknown;
+    readonly error?: string;
+    readonly waitingFor?: string;
+    readonly nodeId?: string;
+    readonly options?: unknown;
+    readonly prompt?: string;
+    readonly sessionId?: string;
+    readonly userFacingMessage?: string;
+    readonly payload?: unknown;
+}
+export interface KuralleMessageLike {
+    readonly role: string;
+    content: unknown;
+}
+export interface KuralleStoredSession {
+    readonly id: string;
+    messages: KuralleMessageLike[];
+    /**
+     * Durable-run bookkeeping the bridge reads for flow-resume. Optional and unknown-typed
+     * because kuralle owns its shape.
+     *
+     * This was a `[key: string]: unknown` catch-all, which made the interface unsatisfiable
+     * by any concrete type: a real `Session` has no index signature, so it could never be
+     * assigned here. Nothing caught that, because nothing type-checked the bridge against
+     * the real Runtime — see `real-runtime.compile-check.ts`. Only this one key is read.
+     */
+    durableRuns?: unknown;
+    /** Working-memory blob the bridge inspects on resume. Kuralle owns its shape. */
+    workingMemory?: unknown;
+}
+export interface KuralleSessionStoreLike {
+    get(id: string): Promise<KuralleStoredSession | null>;
+    save(session: KuralleStoredSession): Promise<void>;
+}
+export interface KuralleTurnHandle {
+    readonly events: AsyncIterable<KuralleStreamPart>;
+    then?: PromiseLike<unknown>["then"];
+}
+export interface KuralleRunOptions {
+    readonly input?: string;
+    readonly sessionId?: string;
+    readonly userId?: string;
+    readonly agentId?: string;
+    readonly abortSignal?: AbortSignal;
+    /**
+     * Prior turns seeded into an empty kuralle session (G4 resume-by-seed).
+     *
+     * Deliberately narrower than it looks: the real `Runtime.run` takes `ModelMessage[]`,
+     * whose `role` is a union, so a `string` role here would be too wide to assign — and a
+     * mutable array, so `ReadonlyArray` would not assign either. The producer
+     * (`buildHistoryDeltaSeed`) already filters to user/assistant, so this only makes the
+     * declaration honest about what the code was doing.
+     *
+     * `real-runtime.compile-check.ts` pins this against the actual Runtime type.
+     */
+    historyDelta?: Array<{
+        role: "user" | "assistant";
+        content: string;
+    }>;
+}
+/**
+ * The slice of kuralle's `Runtime` this bridge calls, as a loose structural shape.
+ *
+ * Deliberately hand-written rather than `Pick<Runtime, ...>`. Deriving was tried and is
+ * strictly worse here: it drags in `TurnHandle`, `HarnessStreamPart`, `Session` and
+ * `RunOptions` wholesale, so every test fake and adapter would have to construct
+ * full-fidelity kuralle objects to call a bridge whose whole point is loose coupling.
+ *
+ * The drift that freedom costs is contained by `real-runtime.compile-check.ts`, which
+ * asserts the REAL `Runtime` still satisfies this shape. That check is what was missing —
+ * not stricter types. It is the same pattern `cf-agents` uses for the agents SDK.
+ */
+export interface KuralleRuntimeLike {
+    run(opts: KuralleRunOptions): KuralleTurnHandle;
+    getSession?(sessionId: string): Promise<KuralleStoredSession | null>;
+    getSessionStore?(): KuralleSessionStoreLike;
+}
+export interface FromKuralleRuntimeOptions {
+    readonly sessionId: string;
+    readonly userId?: string;
+    readonly agentId?: string;
+}
+export declare function fromKuralleRuntime(runtime: KuralleRuntimeLike, opts: FromKuralleRuntimeOptions): Reasoner;
+export declare function buildKuralleTurnRunOptions(runtime: KuralleRuntimeLike, params: FromKuralleRuntimeOptions & {
+    readonly userText: string;
+    readonly signal?: AbortSignal;
+}): Promise<KuralleRunOptions>;
+export declare function runKuralleTurn(runtime: KuralleRuntimeLike, runOpts: KuralleRunOptions): KuralleTurnHandle;
+export declare function awaitKuralleTurn(handle: KuralleTurnHandle): Promise<void>;
+export declare function streamFromKuralle(runtime: KuralleRuntimeLike, turn: ReasonerTurn, opts: FromKuralleRuntimeOptions): AsyncGenerator<ReasoningPart>;
+export declare function reconcileSpokenPrefix(runtime: KuralleRuntimeLike, sessionId: string, spokenPrefix: string): Promise<void>;
+export declare function rewriteLastAssistant(messages: ReadonlyArray<KuralleMessageLike>, spokenPrefix: string): KuralleMessageLike[];

package/dist/from-kuralle.js

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: MIT
+import { categorizeLlmError, isRecoverable } from "@kuralle-syrinx/core";
+const DURABLE_RUNS_KEY = "durableRuns";
+export function fromKuralleRuntime(runtime, opts) {
+    return { stream: (turn) => streamFromKuralle(runtime, turn, opts) };
+}
+async function buildKuralleRunOptions(runtime, turn, opts) {
+    const base = {
+        sessionId: opts.sessionId,
+        userId: opts.userId,
+        agentId: opts.agentId,
+        abortSignal: turn.signal,
+    };
+    if (!turn.userText)
+        return base;
+    if (!runtime.getSession) {
+        return { ...base, input: turn.userText };
+    }
+    const session = await runtime.getSession(opts.sessionId);
+    const runState = readActiveRunState(session, opts.sessionId);
+    if (runState?.activeFlow) {
+        const appended = await appendFlowResumeUserMessage(runtime, opts.sessionId, turn.userText);
+        if (appended)
+            return base;
+    }
+    // G4 resume-by-seed: the BRIDGE owns history (reasoner seam §4.5). When the kuralle
+    // session is empty (fresh isolate / post-eviction) and the turn carries prior context,
+    // seed it once via historyDelta — kuralle appends it to the (empty) session, so the
+    // runtime resumes with the same context instead of restarting amnesiac. Never seeded
+    // into a non-empty session (that would double-apply history).
+    return { ...base, input: turn.userText, ...seedHistoryDelta(session, turn.messages) };
+}
+function seedHistoryDelta(session, messages) {
+    if (session && session.messages.length > 0)
+        return {};
+    const delta = messages
+        .filter((message) => message.role === "user" || message.role === "assistant")
+        .map((message) => ({ role: message.role, content: message.content }));
+    return delta.length > 0 ? { historyDelta: delta } : {};
+}
+export async function buildKuralleTurnRunOptions(runtime, params) {
+    const turn = {
+        userText: params.userText,
+        messages: [],
+        signal: params.signal ?? new AbortController().signal,
+    };
+    return buildKuralleRunOptions(runtime, turn, params);
+}
+export function runKuralleTurn(runtime, runOpts) {
+    return runtime.run(runOpts);
+}
+export async function awaitKuralleTurn(handle) {
+    await new Promise((resolve, reject) => {
+        if (typeof handle.then === "function") {
+            handle.then(() => resolve(), reject);
+            return;
+        }
+        resolve();
+    });
+}
+function readActiveRunState(session, sessionId) {
+    if (!session)
+        return undefined;
+    const runs = session[DURABLE_RUNS_KEY];
+    if (!runs || typeof runs !== "object" || Array.isArray(runs))
+        return undefined;
+    const persisted = runs[sessionId];
+    if (!persisted || typeof persisted !== "object")
+        return undefined;
+    const runState = persisted.runState;
+    return runState;
+}
+async function appendFlowResumeUserMessage(runtime, sessionId, userText) {
+    const store = runtime.getSessionStore?.();
+    if (!store)
+        return false;
+    const session = await store.get(sessionId);
+    if (!session)
+        return false;
+    const userMessage = { role: "user", content: userText };
+    session.messages = [...session.messages, userMessage];
+    const wm = session.workingMemory;
+    if (wm && typeof wm === "object" && !Array.isArray(wm)) {
+        delete wm["__v2_pendingUserInput"];
+    }
+    const runs = session[DURABLE_RUNS_KEY];
+    if (runs && typeof runs === "object" && !Array.isArray(runs)) {
+        const persisted = runs[sessionId];
+        if (persisted && typeof persisted === "object") {
+            const runState = persisted.runState;
+            if (runState) {
+                runState.messages = [...(runState.messages ?? []), userMessage];
+            }
+        }
+    }
+    await store.save(session);
+    return true;
+}
+export async function* streamFromKuralle(runtime, turn, opts) {
+    const runOpts = await buildKuralleRunOptions(runtime, turn, opts);
+    const handle = runtime.run(runOpts);
+    let acc = "";
+    let aborted = false;
+    try {
+        for await (const part of handle.events) {
+            if (turn.signal.aborted) {
+                aborted = true;
+                break;
+            }
+            switch (part.type) {
+                case "text-delta": {
+                    const t = String(part.delta ?? "");
+                    acc += t;
+                    yield { type: "text-delta", text: t };
+                    if (turn.signal.aborted) {
+                        aborted = true;
+                    }
+                    break;
+                }
+                case "tool-call":
+                    yield {
+                        type: "tool-call",
+                        toolId: String(part.toolCallId ?? ""),
+                        toolName: String(part.toolName ?? ""),
+                        args: toRecord(part.args),
+                    };
+                    break;
+                case "tool-result":
+                    yield {
+                        type: "tool-result",
+                        toolId: String(part.toolCallId ?? ""),
+                        toolName: String(part.toolName ?? ""),
+                        result: stringifyResult(part.result),
+                    };
+                    break;
+                case "error":
+                    yield toErrorPart(new Error(String(part.error ?? "Kuralle error")));
+                    return;
+                case "paused":
+                    yield {
+                        type: "suspended",
+                        runId: opts.sessionId,
+                        prompt: typeof part.waitingFor === "string" ? part.waitingFor : undefined,
+                        payload: part,
+                    };
+                    return;
+                case "interactive":
+                    yield {
+                        type: "suspended",
+                        runId: opts.sessionId,
+                        prompt: typeof part.prompt === "string" ? part.prompt : undefined,
+                        payload: part,
+                    };
+                    return;
+                case "safety-blocked":
+                    yield {
+                        type: "blocked",
+                        userFacingMessage: String(part.userFacingMessage ?? "This request cannot be completed."),
+                        payload: part,
+                    };
+                    return;
+                case "done":
+                    yield { type: "finish", reason: "stop", text: acc };
+                    return;
+                default:
+                    yield { type: "control", name: part.type, payload: part };
+                    break;
+            }
+            if (aborted)
+                break;
+        }
+    }
+    finally {
+        await awaitKuralleTurn(handle).catch(() => undefined);
+        if (aborted && acc.length > 0) {
+            await reconcileSpokenPrefix(runtime, opts.sessionId, acc);
+        }
+    }
+    if (aborted)
+        return;
+    yield toErrorPart(new Error("Kuralle stream ended without a done part"));
+}
+export async function reconcileSpokenPrefix(runtime, sessionId, spokenPrefix) {
+    const store = runtime.getSessionStore?.();
+    if (!store)
+        return;
+    const session = await store.get(sessionId);
+    if (!session)
+        return;
+    let changed = false;
+    const topLevel = rewriteLastAssistant(session.messages, spokenPrefix);
+    if (topLevel !== session.messages) {
+        session.messages = topLevel;
+        changed = true;
+    }
+    const runs = session[DURABLE_RUNS_KEY];
+    if (runs && typeof runs === "object" && !Array.isArray(runs)) {
+        for (const persisted of Object.values(runs)) {
+            if (!persisted || typeof persisted !== "object")
+                continue;
+            const runState = persisted.runState;
+            if (!runState?.messages)
+                continue;
+            const rewritten = rewriteLastAssistant(runState.messages, spokenPrefix);
+            if (rewritten !== runState.messages) {
+                runState.messages = rewritten;
+                changed = true;
+            }
+        }
+    }
+    if (changed)
+        await store.save(session);
+}
+export function rewriteLastAssistant(messages, spokenPrefix) {
+    if (messages.length === 0)
+        return [...messages];
+    const last = messages[messages.length - 1];
+    if (!last || last.role !== "assistant")
+        return [...messages];
+    const full = assistantText(last);
+    if (spokenPrefix.length >= full.length)
+        return [...messages];
+    return [...messages.slice(0, -1), { role: "assistant", content: spokenPrefix }];
+}
+function assistantText(message) {
+    if (typeof message.content === "string")
+        return message.content;
+    if (Array.isArray(message.content)) {
+        return message.content
+            .map((part) => {
+            if (typeof part === "string")
+                return part;
+            if (part && typeof part === "object" && "text" in part)
+                return String(part.text);
+            return "";
+        })
+            .join("");
+    }
+    return String(message.content ?? "");
+}
+function toErrorPart(error) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    return { type: "error", cause, recoverable: isRecoverable(categorizeLlmError(cause)) };
+}
+function stringifyResult(r) {
+    return typeof r === "string" ? r : JSON.stringify(r);
+}
+function toRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return {};
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { fromKuralleRuntime, runKuralleTurn, awaitKuralleTurn, buildKuralleTurnRunOptions, reconcileSpokenPrefix, rewriteLastAssistant, type KuralleRuntimeLike, type KuralleRunOptions, type KuralleStreamPart, type KuralleSessionStoreLike, type KuralleStoredSession, type KuralleMessageLike, type FromKuralleRuntimeOptions, } from "./from-kuralle.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: MIT
+export { fromKuralleRuntime, runKuralleTurn, awaitKuralleTurn, buildKuralleTurnRunOptions, reconcileSpokenPrefix, rewriteLastAssistant, } from "./from-kuralle.js";

package/dist/real-runtime.compile-check.d.ts

@@ -0,0 +1 @@
+export declare const reasonerFromRealRuntime: import("@kuralle-syrinx/core").Reasoner;

package/dist/real-runtime.compile-check.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+//
+// Compile-only proof that the REAL `@kuralle-agents/core` Runtime satisfies the
+// structural `KuralleRuntimeLike` this bridge consumes. Type-checked by
+// `tsc --noEmit`; never executed.
+//
+// Why this file exists: the bridge deliberately types against a structural interface
+// rather than importing kuralle's types, so a consumer can supply any runtime-shaped
+// object. The cost of that freedom is that nothing was verifying the real Runtime
+// still fits — the package pinned `^0.8.5` in devDeps while npm shipped 0.13.0, five
+// minors and a package-folder rename later, and no check would have failed. If kuralle
+// changes `run` / `getSession` / `getSessionStore`, this file stops compiling.
+//
+// Mirrors the same pattern as `packages/cf-agents/src/real-agent.compile-check.ts`.
+import { fromKuralleRuntime } from "./from-kuralle.js";
+const asBridgeRuntime = realRuntime;
+// And the real thing composes into the seam the voice pipeline consumes.
+export const reasonerFromRealRuntime = fromKuralleRuntime(asBridgeRuntime, {
+    sessionId: "compile-check-session",
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/kuralle",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "private": false,
   "description": "kuralle-agents bridge for Syrinx — run a kuralle runtime as the voice pipeline's reasoner",
   "keywords": [
@@ -21,21 +21,28 @@
     "url": "https://github.com/kuralle/syrinx/issues"
   },
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "dependencies": {
-    "@kuralle-syrinx/core": "4.4.0"
+    "@kuralle-syrinx/core": "4.5.0"
   },
   "peerDependencies": {
     "@kuralle-agents/core": ">=0.13.0 <1"
   },
   "devDependencies": {
     "@kuralle-agents/core": "^0.13.0",
+    "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6"
   },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
   }
 }

package/src/from-kuralle.test.ts

@@ -0,0 +1,421 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import type { Reasoner, ReasonerTurn, ReasoningPart } from "@kuralle-syrinx/core";
+import {
+  buildKuralleTurnRunOptions,
+  fromKuralleRuntime,
+  reconcileSpokenPrefix,
+  rewriteLastAssistant,
+  type KuralleMessageLike,
+  type KuralleRunOptions,
+  type KuralleRuntimeLike,
+  type KuralleSessionStoreLike,
+  type KuralleStoredSession,
+  type KuralleStreamPart,
+} from "./from-kuralle.js";
+
+function baseTurn(): ReasonerTurn {
+  return {
+    userText: "Hi",
+    messages: [{ role: "system", content: "test" }],
+    signal: new AbortController().signal,
+  };
+}
+
+function textDelta(delta: string): KuralleStreamPart {
+  return { type: "text-delta", delta };
+}
+
+function toolCall(toolCallId: string, toolName: string, args: Record<string, unknown>): KuralleStreamPart {
+  return { type: "tool-call", toolCallId, toolName, args };
+}
+
+function toolResult(toolCallId: string, toolName: string, result: unknown): KuralleStreamPart {
+  return { type: "tool-result", toolCallId, toolName, result };
+}
+
+function errorPart(error: string): KuralleStreamPart {
+  return { type: "error", error };
+}
+
+function done(sessionId?: string): KuralleStreamPart {
+  return { type: "done", sessionId };
+}
+
+function safetyBlocked(userFacingMessage: string): KuralleStreamPart {
+  return { type: "safety-blocked", userFacingMessage };
+}
+
+async function* partsToEvents(parts: KuralleStreamPart[]): AsyncIterable<KuralleStreamPart> {
+  for (const p of parts) yield p;
+}
+
+function fakeRuntime(
+  parts: KuralleStreamPart[],
+  spy?: {
+    runOpts?: {
+      input?: string;
+      sessionId?: string;
+      userId?: string;
+      agentId?: string;
+      abortSignal?: AbortSignal;
+    };
+  },
+): KuralleRuntimeLike {
+  return {
+    run(opts) {
+      if (spy) spy.runOpts = opts;
+      return { events: partsToEvents(parts) };
+    },
+  };
+}
+
+async function collectParts(reasoner: Reasoner, turn: ReasonerTurn): Promise<ReasoningPart[]> {
+  const collected: ReasoningPart[] = [];
+  for await (const part of reasoner.stream(turn)) {
+    collected.push(part);
+  }
+  return collected;
+}
+
+describe("fromKuralleRuntime G4 resume-by-seed (historyDelta)", () => {
+  const turnWithContext = (): ReasonerTurn => ({
+    userText: "Second question",
+    messages: [
+      { role: "system", content: "sys" },
+      { role: "user", content: "First question" },
+      { role: "assistant", content: "First answer" },
+    ],
+    signal: new AbortController().signal,
+  });
+
+  it("seeds prior turn.messages into an EMPTY kuralle session (fresh isolate resume)", async () => {
+    const spy: { runOpts?: KuralleRunOptions } = {};
+    const runtime: KuralleRuntimeLike = {
+      run(opts) {
+        spy.runOpts = opts;
+        return { events: partsToEvents([textDelta("ok"), done()]) };
+      },
+      getSession: async () => null,
+    };
+    const reasoner = fromKuralleRuntime(runtime, { sessionId: "sess-1" });
+
+    await collectParts(reasoner, turnWithContext());
+
+    expect(spy.runOpts?.input).toBe("Second question");
+    expect(spy.runOpts?.historyDelta).toEqual([
+      { role: "user", content: "First question" },
+      { role: "assistant", content: "First answer" },
+    ]);
+  });
+
+  it("does NOT seed into a non-empty session (no double-applied history, R6)", async () => {
+    const spy: { runOpts?: KuralleRunOptions } = {};
+    const runtime: KuralleRuntimeLike = {
+      run(opts) {
+        spy.runOpts = opts;
+        return { events: partsToEvents([textDelta("ok"), done()]) };
+      },
+      getSession: async () => ({
+        id: "sess-1",
+        messages: [{ role: "user", content: "already there" }],
+      }),
+    };
+    const reasoner = fromKuralleRuntime(runtime, { sessionId: "sess-1" });
+
+    await collectParts(reasoner, turnWithContext());
+
+    expect(spy.runOpts?.input).toBe("Second question");
+    expect(spy.runOpts?.historyDelta).toBeUndefined();
+  });
+});
+
+describe("fromKuralleRuntime", () => {
+  it("maps happy path: text deltas and done to finish:stop", async () => {
+    const reasoner = fromKuralleRuntime(
+      fakeRuntime([textDelta("Hi"), textDelta(" there"), done("sess-1")]),
+      { sessionId: "sess-1" },
+    );
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "Hi" },
+      { type: "text-delta", text: " there" },
+      { type: "finish", reason: "stop", text: "Hi there" },
+    ]);
+  });
+
+  it("speaks a kuralle per-tool interim: it arrives as text-delta before the tool result", async () => {
+    // Kuralle's `Tool.interim` / `interimAfterMs` is the tool-level equivalent of a spoken
+    // preamble — "Let me pull up your record" while a slow tool runs. It is NOT a distinct
+    // stream part: `ToolExecutor` fires an `onInterim` callback, and kuralle's `Runtime`
+    // converts it to `text-start` / `text-delta` / `text-end` on the run stream
+    // (Runtime.js — `onInterim: (message) => { emit({type:'text-delta', delta: message}) }`).
+    //
+    // So it reaches Syrinx as an ordinary text-delta and flows llm.delta -> bufferTtsText ->
+    // tts.text -> spoken audio, with no bridge change needed. This test pins that path so a
+    // future refactor of the text-delta case cannot silently mute every tool interim.
+    const reasoner = fromKuralleRuntime(
+      fakeRuntime([
+        toolCall("call-1", "studentRelationsLookup", { requestType: "late_add" }),
+        // The interim, as the runtime actually emits it — bare text-delta, mid-tool.
+        textDelta("Let me pull up your registration record."),
+        toolResult("call-1", "studentRelationsLookup", { addDeadline: "2027-02-05" }),
+        textDelta("Your late add deadline was February 5th."),
+        done("sess-interim"),
+      ]),
+      { sessionId: "sess-interim" },
+    );
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    const firstSpoken = parts.find((p) => p.type === "text-delta");
+    expect(firstSpoken).toEqual({
+      type: "text-delta",
+      text: "Let me pull up your registration record.",
+    });
+    // And it precedes the tool result, so the user hears it while the tool is still running.
+    const interimIdx = parts.findIndex((p) => p.type === "text-delta");
+    const resultIdx = parts.findIndex((p) => p.type === "tool-result");
+    expect(interimIdx).toBeLessThan(resultIdx);
+  });
+
+  it("maps tool-call and tool-result with toolId from toolCallId", async () => {
+    const reasoner = fromKuralleRuntime(
+      fakeRuntime([
+        toolCall("tc-1", "lookup", { id: "123" }),
+        toolResult("tc-1", "lookup", { found: true }),
+        done(),
+      ]),
+      { sessionId: "sess-1" },
+    );
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      {
+        type: "tool-call",
+        toolId: "tc-1",
+        toolName: "lookup",
+        args: { id: "123" },
+      },
+      {
+        type: "tool-result",
+        toolId: "tc-1",
+        toolName: "lookup",
+        result: JSON.stringify({ found: true }),
+      },
+      { type: "finish", reason: "stop", text: "" },
+    ]);
+  });
+
+  it("maps error part to terminal error", async () => {
+    const reasoner = fromKuralleRuntime(fakeRuntime([errorPart("boom")]), { sessionId: "sess-1" });
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toHaveLength(1);
+    expect(parts[0]?.type).toBe("error");
+    if (parts[0]?.type === "error") {
+      expect(parts[0].cause.message).toBe("boom");
+      expect(parts[0].recoverable).toBe(false);
+    }
+  });
+
+  it("maps safety-blocked to a terminal blocked part without the missing-done error", async () => {
+    const reasoner = fromKuralleRuntime(
+      fakeRuntime([safetyBlocked("I cannot help with that request.")]),
+      { sessionId: "sess-safety" },
+    );
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      {
+        type: "blocked",
+        userFacingMessage: "I cannot help with that request.",
+        payload: { type: "safety-blocked", userFacingMessage: "I cannot help with that request." },
+      },
+    ]);
+    expect(parts.some((part) => part.type === "error")).toBe(false);
+  });
+
+  it("preserves orchestration parts as opaque control parts", async () => {
+    const handoff = { type: "handoff", targetAgent: "billing", reason: "account question" } satisfies KuralleStreamPart;
+    const outcome = { type: "conversation-outcome", outcome: { taskSuccess: true, satisfaction: false } } satisfies KuralleStreamPart;
+    const reasoner = fromKuralleRuntime(fakeRuntime([handoff, outcome, done()]), { sessionId: "sess-control" });
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      { type: "control", name: "handoff", payload: handoff },
+      { type: "control", name: "conversation-outcome", payload: outcome },
+      { type: "finish", reason: "stop", text: "" },
+    ]);
+  });
+
+  it("yields terminal error when stream ends without done", async () => {
+    const reasoner = fromKuralleRuntime(fakeRuntime([textDelta("partial")]), { sessionId: "sess-1" });
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toHaveLength(2);
+    expect(parts[0]).toEqual({ type: "text-delta", text: "partial" });
+    expect(parts[1]?.type).toBe("error");
+    if (parts[1]?.type === "error") {
+      expect(parts[1].cause.message).toBe("Kuralle stream ended without a done part");
+      expect(parts[1].recoverable).toBe(false);
+    }
+  });
+
+  it("returns without yielding when turn.signal is already aborted", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const turn: ReasonerTurn = { ...baseTurn(), signal: controller.signal };
+
+    const reasoner = fromKuralleRuntime(
+      fakeRuntime([textDelta("should not appear"), done()]),
+      { sessionId: "sess-1" },
+    );
+
+    const parts = await collectParts(reasoner, turn);
+
+    expect(parts).toEqual([]);
+  });
+
+  it("passes only userText to run, not turn.messages", async () => {
+    const spy: { runOpts?: { input?: string; sessionId?: string } } = {};
+    const reasoner = fromKuralleRuntime(fakeRuntime([done()], spy), { sessionId: "sess-42" });
+
+    const turn: ReasonerTurn = {
+      userText: "What is my name?",
+      messages: [
+        { role: "system", content: "ignored" },
+        { role: "user", content: "also ignored" },
+      ],
+      signal: new AbortController().signal,
+    };
+    await collectParts(reasoner, turn);
+
+    expect(spy.runOpts?.input).toBe("What is my name?");
+    expect(spy.runOpts?.sessionId).toBe("sess-42");
+  });
+
+  it("flow resume pre-appends user message and omits input", async () => {
+    const sessionId = "sess-flow";
+    const store = createMockSessionStore(sessionId, [{ role: "assistant", content: "What is your name?" }]);
+    const session = (await store.get(sessionId))!;
+    session.durableRuns = {
+      [sessionId]: {
+        runState: {
+          activeFlow: "book-advisor-appointment",
+          messages: [{ role: "assistant", content: "What is your name?" }],
+        },
+        steps: [],
+      },
+    };
+    await store.save(session);
+
+    const runtime: KuralleRuntimeLike = {
+      run: () => ({ events: partsToEvents([done()]) }),
+      getSession: (id) => store.get(id),
+      getSessionStore: () => store,
+    };
+
+    const opts = await buildKuralleTurnRunOptions(runtime, {
+      sessionId,
+      userText: "Priya, CS masters, Friday",
+    });
+
+    expect(opts.input).toBeUndefined();
+    expect(opts.historyDelta).toBeUndefined();
+    const saved = await store.get(sessionId);
+    expect(saved?.messages.at(-1)).toEqual({ role: "user", content: "Priya, CS masters, Friday" });
+    const runMessages = (
+      saved?.durableRuns as Record<string, { runState: { messages: KuralleMessageLike[] } }>
+    )[sessionId]?.runState.messages;
+    expect(runMessages?.at(-1)).toEqual({ role: "user", content: "Priya, CS masters, Friday" });
+  });
+
+  it("rewriteLastAssistant truncates only when spoken prefix is shorter", () => {
+    const messages: KuralleMessageLike[] = [
+      { role: "user", content: "Hi" },
+      { role: "assistant", content: "Hello there friend" },
+    ];
+    expect(rewriteLastAssistant(messages, "Hello")).toEqual([
+      { role: "user", content: "Hi" },
+      { role: "assistant", content: "Hello" },
+    ]);
+    expect(rewriteLastAssistant(messages, "Hello there friend")).toStrictEqual(messages);
+  });
+
+  it("after barge-in abort, reconciles persisted assistant message to spoken prefix", async () => {
+    const fullText = "Hello there friend";
+    const spokenPrefix = "Hello";
+    const sessionId = "sess-barge";
+    const store = createMockSessionStore(sessionId, []);
+
+    await reconcileSpokenPrefix(
+      { run: () => ({ events: partsToEvents([]) }), getSessionStore: () => store },
+      sessionId,
+      spokenPrefix,
+    );
+    let session = await store.get(sessionId);
+    expect(session?.messages).toEqual([]);
+
+    session = (await store.get(sessionId)) ?? { id: sessionId, messages: [] };
+    session.messages = [{ role: "assistant", content: fullText }];
+    await store.save(session);
+
+    await reconcileSpokenPrefix(
+      { run: () => ({ events: partsToEvents([]) }), getSessionStore: () => store },
+      sessionId,
+      spokenPrefix,
+    );
+    session = await store.get(sessionId);
+    expect(session?.messages.at(-1)).toEqual({ role: "assistant", content: spokenPrefix });
+  });
+
+  it("reconcileSpokenPrefix rewrites durable run messages", async () => {
+    const sessionId = "sess-durable";
+    const store = createMockSessionStore(sessionId, []);
+    const session = (await store.get(sessionId))!;
+    session.messages = [{ role: "assistant", content: "full reply text" }];
+    session.durableRuns = {
+      [sessionId]: {
+        runState: { messages: [{ role: "assistant", content: "full reply text" }] },
+        steps: [],
+      },
+    };
+    await store.save(session);
+
+    await reconcileSpokenPrefix(
+      { run: () => ({ events: partsToEvents([]) }), getSessionStore: () => store },
+      sessionId,
+      "full",
+    );
+
+    const saved = await store.get(sessionId);
+    expect(saved?.messages.at(-1)).toEqual({ role: "assistant", content: "full" });
+    const runState = (saved?.durableRuns as Record<string, { runState: { messages: KuralleMessageLike[] } }>)[sessionId]
+      ?.runState;
+    expect(runState?.messages.at(-1)).toEqual({ role: "assistant", content: "full" });
+  });
+});
+
+function createMockSessionStore(sessionId: string, messages: KuralleMessageLike[]): KuralleSessionStoreLike {
+  const sessions = new Map<string, KuralleStoredSession>([
+    [sessionId, { id: sessionId, messages: [...messages] }],
+  ]);
+  return {
+    async get(id) {
+      const session = sessions.get(id);
+      return session ? structuredClone(session) : null;
+    },
+    async save(session) {
+      sessions.set(session.id, structuredClone(session));
+    },
+  };
+}