@kuralle-syrinx/aisdk 3.0.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/aisdk",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -10,7 +10,7 @@
     "@ai-sdk/openai": "^3.0.67",
     "ai": "^6.0.0",
     "zod": "^4.1.8",
-    "@kuralle-syrinx/core": "3.0.0"
+    "@kuralle-syrinx/core": "4.0.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",

package/src/index.test.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 
 import { describe, expect, it } from "vitest";
-import { PipelineBusImpl, Route } from "@kuralle-syrinx/core";
+import { InMemoryReasonerSessionStore, PipelineBusImpl, Route } from "@kuralle-syrinx/core";
 import type {
   EndOfSpeechPacket,
   InterruptLlmPacket,
@@ -72,7 +72,75 @@ describe("ReasoningBridge", () => {
     });
   });
 
-  it("emits llm.error instead of llm.done when provider reaches token limit", async () => {
+  it("G2/WBS-1: cascade turn emits delegate.query then delegate.result on the Background route", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const plugin = new ReasoningBridge(fromStreamFactory(async function* () {
+      yield toolCall("rag-1", "retrieve", { q: "deadline" });
+      yield toolResult("rag-1", "retrieve", "chunk");
+      yield textDelta("The deadline is March 31.");
+      yield finish("stop");
+    }));
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+
+    await plugin.initialize(bus, baseConfig());
+    bus.push(Route.Main, turnComplete("turn-1", "When is the deadline?"));
+
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "delegate.result"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    const delegatePackets = packets.filter(({ packet }) =>
+      String((packet as { kind?: string }).kind).startsWith("delegate."),
+    );
+    expect(delegatePackets.map(({ route }) => route)).toEqual([Route.Background, Route.Background]);
+    expect(delegatePackets[0]!.packet).toMatchObject({
+      kind: "delegate.query",
+      contextId: "turn-1",
+      query: "When is the deadline?",
+    });
+    expect((delegatePackets[0]!.packet as { toolName?: string }).toolName).toBeUndefined();
+    expect(delegatePackets[1]!.packet).toMatchObject({
+      kind: "delegate.result",
+      contextId: "turn-1",
+      query: "When is the deadline?",
+      answer: "The deadline is March 31.",
+      grounded: true,
+    });
+    expect((delegatePackets[1]!.packet as { durationMs: number }).durationMs).toBeGreaterThanOrEqual(0);
+    // delegate.query precedes the reasoner's first output.
+    const queryIndex = packets.findIndex(({ packet }) => (packet as { kind?: string }).kind === "delegate.query");
+    const firstDeltaIndex = packets.findIndex(({ packet }) => (packet as { kind?: string }).kind === "llm.delta");
+    expect(queryIndex).toBeGreaterThanOrEqual(0);
+    expect(queryIndex).toBeLessThan(firstDeltaIndex);
+  });
+
+  it("G2/WBS-1: cascade delegate.result grounded=false without tool use; none on error", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const plugin = new ReasoningBridge(fromStreamFactory(async function* () {
+      yield textDelta("From memory.");
+      yield finish("stop");
+    }));
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+
+    await plugin.initialize(bus, baseConfig());
+    bus.push(Route.Main, turnComplete("turn-1", "Hi"));
+
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "delegate.result"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    const result = packets.find(({ packet }) => (packet as { kind?: string }).kind === "delegate.result")!;
+    expect(result.packet).toMatchObject({ grounded: false, answer: "From memory." });
+  });
+
+  it("accepts the truncated reply on token-limit finish (fails the turn, never the call)", async () => {
+    // A `length` finish means the model hit the token cap: the streamed reply is
+    // truncated but usable. It must be spoken and the call kept up (L2) — never
+    // escalated to a session-killing llm.error.
     const packets: Array<{ route: Route; packet: unknown }> = [];
     const plugin = new ReasoningBridge(fromStreamFactory(async function* () {
       yield textDelta("This answer is incomplete");
@@ -84,20 +152,48 @@ describe("ReasoningBridge", () => {
     await plugin.initialize(bus, baseConfig());
     bus.push(Route.Main, turnComplete("turn-1", "Hi"));
 
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    // The partial reply is committed as a normal turn completion.
+    expect(packets).toContainEqual({
+      route: Route.Main,
+      packet: expect.objectContaining({ kind: "llm.done", contextId: "turn-1", text: "This answer is incomplete" }),
+    });
+    // No session-killing error was emitted.
+    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.error")).toBe(false);
+    // The truncation is observable for telemetry.
+    expect(packets.some(({ packet }) => (packet as { kind?: string; name?: string }).name === "llm.finish_length_truncated")).toBe(true);
+  });
+
+  it("fails the turn recoverably (not the call) on an unfinished tool-loop finish", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const plugin = new ReasoningBridge(fromStreamFactory(async function* () {
+      yield textDelta("partial");
+      yield finish("tool-calls");
+    }));
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+
+    await plugin.initialize(bus, baseConfig());
+    bus.push(Route.Main, turnComplete("turn-1", "Hi"));
+
     await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.error"));
     bus.stop();
     await drain;
     await plugin.close();
 
-    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done")).toBe(false);
     expect(packets).toContainEqual({
       route: Route.Critical,
       packet: expect.objectContaining({
         kind: "llm.error",
         contextId: "turn-1",
-        isRecoverable: false,
+        isRecoverable: true, // recoverable → fallback spoken, session stays open
       } satisfies Partial<LlmErrorPacket>),
     });
+    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done")).toBe(false);
   });
 
   it("emits llm.error when the stream ends without finish metadata", async () => {
@@ -394,6 +490,110 @@ describe("ReasoningBridge", () => {
   });
 });
 
+describe("ReasoningBridge durable session (G4/WBS-4)", () => {
+  it("re-seeds context from the session store after a simulated eviction; no double-answer", async () => {
+    const store = new InMemoryReasonerSessionStore();
+
+    // First lifetime: one committed turn, then the host is evicted (bridge closed).
+    const first = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Answer one.");
+        yield finish("stop");
+      }),
+      { sessionStore: store, sessionId: "s1" },
+    );
+    const firstPackets: Array<{ packet: unknown }> = [];
+    const firstBus = new PipelineBusImpl({ onPacket: (_route, packet) => firstPackets.push({ packet }) });
+    const firstDrain = firstBus.start();
+    await first.initialize(firstBus, baseConfig());
+    firstBus.push(Route.Main, turnComplete("turn-1", "First question"));
+    await waitFor(() => firstPackets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done"));
+    firstBus.stop();
+    await firstDrain;
+    await first.close();
+
+    // Second lifetime: a fresh bridge over the same store must hand the reasoner
+    // the prior turn as context — and must not re-answer it.
+    const seenMessages: Array<ReasonerTurn["messages"]> = [];
+    const secondReasoner: Reasoner = {
+      stream: (turn) => {
+        seenMessages.push([...turn.messages]);
+        return (async function* (): AsyncGenerator<ReasoningPart> {
+          yield { type: "text-delta", text: "Answer two." };
+          yield { type: "finish", reason: "stop", text: "Answer two." };
+        })();
+      },
+    };
+    const second = new ReasoningBridge(secondReasoner, { sessionStore: store, sessionId: "s1" });
+    const packets: Array<{ packet: unknown }> = [];
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await second.initialize(bus, baseConfig());
+    // Nothing speaks spontaneously on resume (no double-answer).
+    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done")).toBe(false);
+
+    bus.push(Route.Main, turnComplete("turn-2", "Second question"));
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done"));
+    bus.stop();
+    await drain;
+    await second.close();
+
+    expect(seenMessages[0]).toEqual([
+      { role: "user", content: "First question" },
+      { role: "assistant", content: "Answer one." },
+    ]);
+    // The store now carries both turns for the next resume.
+    expect(store.load("s1")).toEqual([
+      { role: "user", content: "First question" },
+      { role: "assistant", content: "Answer one." },
+      { role: "user", content: "Second question" },
+      { role: "assistant", content: "Answer two." },
+    ]);
+  });
+
+  it("persists the interrupted turn's history as the heard prefix", async () => {
+    const store = new InMemoryReasonerSessionStore();
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Full generated reply that was cut off.");
+        yield finish("stop");
+      }),
+      { sessionStore: store, sessionId: "s1" },
+    );
+    const packets: Array<{ packet: unknown }> = [];
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+
+    bus.push(Route.Main, turnComplete("turn-1", "Hi"));
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done"));
+    // What actually reached TTS before the barge-in.
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      text: "Full generated",
+    } satisfies TextToSpeechTextPacket);
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "tts.text"));
+    bus.push(Route.Critical, {
+      kind: "interrupt.llm",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+    } satisfies InterruptLlmPacket);
+    await waitFor(() =>
+      packets.some(({ packet }) => (packet as { name?: string }).name === "llm.history_truncated_to_spoken"),
+    );
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    expect(store.load("s1")).toEqual([
+      { role: "user", content: "Hi" },
+      { role: "assistant", content: "Full generated" },
+    ]);
+  });
+});
+
 describe("ReasoningBridge suspend/resume", () => {
   it("clean suspend → resume: saves pointer, resumes with userText, discards on finish", async () => {
     const packets: Array<{ route: Route; packet: unknown }> = [];
@@ -617,6 +817,14 @@ function textDelta(text: string): TextStreamPart<ToolSet> {
   return { type: "text-delta", id: "0", text, providerMetadata: undefined } as TextStreamPart<ToolSet>;
 }
 
+function toolCall(toolCallId: string, toolName: string, input: Record<string, unknown>): TextStreamPart<ToolSet> {
+  return { type: "tool-call", toolCallId, toolName, input } as TextStreamPart<ToolSet>;
+}
+
+function toolResult(toolCallId: string, toolName: string, output: unknown): TextStreamPart<ToolSet> {
+  return { type: "tool-result", toolCallId, toolName, input: {}, output } as TextStreamPart<ToolSet>;
+}
+
 function finish(finishReason: FinishReason, rawFinishReason?: string): TextStreamPart<ToolSet> {
   return {
     type: "finish",

package/src/index.ts

@@ -17,12 +17,14 @@ import {
   type VoicePlugin,
   type PluginConfig,
   type Reasoner,
+  type ReasonerSessionStore,
   type ReasonerTurn,
   type TtsWordTimestamp,
   categorizeLlmError,
   isRecoverable,
   readRetryConfig,
   waitForRetryDelay,
+  ErrorCategory,
   type RetryConfig,
 } from "@kuralle-syrinx/core";
 
@@ -82,7 +84,18 @@ export class ReasoningBridge implements VoicePlugin {
 
   constructor(
     private readonly reasoner: Reasoner,
-    private readonly opts: { runStore?: RunStore; onResumeConflict?: "restart" | "replay" } = {},
+    private readonly opts: {
+      runStore?: RunStore;
+      onResumeConflict?: "restart" | "replay";
+      /**
+       * G4 durable session (RFC bimodel-delegate-seam): when set with `sessionId`, the
+       * bridge loads its conversation history from the store on initialize and persists
+       * the bounded snapshot after every committed (or interrupted-truncated) turn — a
+       * bridge re-created after host eviction resumes with the same context.
+       */
+      sessionStore?: ReasonerSessionStore;
+      sessionId?: string;
+    } = {},
   ) {
     if (this.opts.onResumeConflict === "replay") {
       throw new Error("onResumeConflict 'replay' not yet supported — use 'restart'");
@@ -95,6 +108,13 @@ export class ReasoningBridge implements VoicePlugin {
     this.maxHistoryTurns = readPositiveIntegerConfig(config["max_history_turns"], 12);
     this.retryConfig = readRetryConfig(config);
 
+    // G4: resume from durable history — the reasoner's next turn sees the same
+    // context as before the eviction/reconnect (R6). Load-only: nothing is spoken.
+    if (this.opts.sessionStore && this.opts.sessionId) {
+      const stored = await this.opts.sessionStore.load(this.opts.sessionId);
+      this.history = stored.map((message) => ({ ...message }));
+    }
+
     // Listen for EOS turn completions
     this.disposers.push(
       // Concurrent producer: a turn's LLM generation streams its own packets over
@@ -166,9 +186,22 @@ export class ReasoningBridge implements VoicePlugin {
     let reply = "";
     let emittedDelta = false;
     let committed = false;
+    let grounded = false;
+
+    // G2 observability: the turn's query is on its way to the reasoner (Background
+    // route, droppable — RFC bimodel-delegate-seam R4). Cascade turns have no
+    // front-model tool call, so toolId/toolName are absent.
+    const queryStartedMs = Date.now();
+    this.bus.push(Route.Background, {
+      kind: "delegate.query",
+      contextId,
+      timestampMs: queryStartedMs,
+      query: userText,
+    });
 
     try {
       for (let attempt = 1; attempt <= this.retryConfig.maxAttempts; attempt += 1) {
+        grounded = false;
         try {
           const pending = this.opts.runStore
             ? await Promise.resolve(this.opts.runStore.takePending(contextId))
@@ -204,6 +237,7 @@ export class ReasoningBridge implements VoicePlugin {
                 });
                 break;
               case "tool-result":
+                grounded = true;
                 this.bus.push(Route.Main, {
                   kind: "llm.tool_result",
                   contextId,
@@ -254,18 +288,56 @@ export class ReasoningBridge implements VoicePlugin {
             }
           }
 
-          validateFinalFinishReason(finishReason);
+          // A non-"stop" finish must fail the TURN, never the call (L2). Killing the
+          // session on a token-cap or unfinished-tool-loop hangs up the caller
+          // mid-conversation. `length` = token cap: the streamed reply is truncated
+          // but usable, so accept it and continue (fall through to llm.done). Any
+          // other non-"stop" reason (tool loop ended, null) = fail the turn
+          // recoverably — the caller hears the graceful fallback, the call stays up.
+          if (finishReason !== "stop" && finishReason !== "length") {
+            if (signal.aborted) return;
+            this.bus.push(Route.Critical, {
+              kind: "llm.error",
+              contextId,
+              timestampMs: Date.now(),
+              component: "bridge" as const,
+              category: ErrorCategory.InternalFault,
+              cause: new Error(`AI SDK turn ended on finishReason "${finishReason ?? "null"}"`),
+              isRecoverable: true,
+            });
+            return;
+          }
+          if (finishReason === "length") {
+            this.bus.push(Route.Background, {
+              kind: "metric.conversation",
+              contextId,
+              timestampMs: Date.now(),
+              name: "llm.finish_length_truncated",
+              value: "1",
+            });
+          }
 
           // Interrupted as generation finished — the interrupt handler owns the history
           // for this turn (spoken prefix); don't commit the full reply or emit llm.done.
           if (signal.aborted) return;
 
+          const answeredMs = Date.now();
           this.bus.push(Route.Main, {
             kind: "llm.done",
             contextId,
-            timestampMs: Date.now(),
+            timestampMs: answeredMs,
             text: reply,
           });
+          // G2 observability: the reasoner produced the turn's final answer.
+          this.bus.push(Route.Background, {
+            kind: "delegate.result",
+            contextId,
+            timestampMs: answeredMs,
+            query: userText,
+            answer: reply,
+            durationMs: answeredMs - queryStartedMs,
+            grounded,
+          });
           this.rememberTurn(userText, reply, contextId);
           if (this.opts.runStore && resuming) {
             await Promise.resolve(this.opts.runStore.discard(contextId));
@@ -338,6 +410,21 @@ export class ReasoningBridge implements VoicePlugin {
     this.history.push({ role: "user", content: userText }, assistantMsg);
     this.assistantMsgByContext.set(contextId, assistantMsg);
     this.trimHistory();
+    this.persistHistory();
+  }
+
+  /** G4: persist the bounded history snapshot, best-effort off the hot path. */
+  private persistHistory(): void {
+    const store = this.opts.sessionStore;
+    const sessionId = this.opts.sessionId;
+    if (!store || !sessionId) return;
+    try {
+      void Promise.resolve(store.save(sessionId, this.history.map((message) => ({ ...message })))).catch(
+        () => undefined,
+      );
+    } catch {
+      /* persistence must never fail the turn */
+    }
   }
 
   /**
@@ -390,6 +477,7 @@ export class ReasoningBridge implements VoicePlugin {
       name: "llm.history_truncated_to_spoken",
       value: String(spoken.length),
     });
+    this.persistHistory(); // G4: the durable snapshot reflects the heard prefix
     this.clearTurnState(contextId);
   }
 
@@ -413,17 +501,6 @@ export class ReasoningBridge implements VoicePlugin {
   }
 }
 
-function validateFinalFinishReason(finishReason: "stop" | "tool" | "length" | null): void {
-  if (finishReason === null) {
-    throw new Error("AI SDK stream ended without a provider finish reason");
-  }
-  if (finishReason === "length") {
-    throw new Error("AI SDK provider reached token limit before completing");
-  }
-  if (finishReason !== "stop") {
-    throw new Error("AI SDK provider did not complete normally");
-  }
-}
 
 function readPositiveIntegerConfig(value: unknown, fallback: number): number {
   if (typeof value !== "number" || !Number.isFinite(value)) return fallback;