@kuralle-syrinx/aisdk 4.4.0 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/aisdk",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "private": false,
   "description": "Vercel AI SDK bridge for Syrinx — drive any ai@6 model or agent as the voice pipeline's reasoner, with opt-in speculative generation",
   "keywords": [
@@ -22,20 +22,27 @@
     "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": {
     "@ai-sdk/openai": "^3.0.67",
     "ai": "^6.0.0",
     "zod": "^4.1.8",
-    "@kuralle-syrinx/core": "4.4.0"
+    "@kuralle-syrinx/core": "4.5.0"
   },
   "devDependencies": {
+    "@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-ai-sdk.test.ts

@@ -0,0 +1,315 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import type { FinishReason, TextStreamPart, ToolSet } from "ai";
+import type { Reasoner, ReasonerTurn, ReasoningPart } from "@kuralle-syrinx/core";
+import { fromAiSdkAgent, fromStreamFactory, modelIdentity, type AiSdkAgentLike } from "./from-ai-sdk.js";
+
+const ZERO_USAGE = {
+  inputTokens: 0,
+  inputTokenDetails: {
+    noCacheTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+  },
+  outputTokens: 0,
+  outputTokenDetails: {
+    textTokens: 0,
+    reasoningTokens: 0,
+  },
+  totalTokens: 0,
+};
+
+// What the finish ReasoningPart now carries, forwarded from totalUsage. Nested
+// detail fields (cache/reasoning) are not surfaced, so only the three top-level counts appear.
+const FINISH_USAGE = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+
+function baseTurn(): ReasonerTurn {
+  return {
+    userText: "Hi",
+    messages: [{ role: "system", content: "test" }],
+    signal: new AbortController().signal,
+  };
+}
+
+function textDelta(text: string): TextStreamPart<ToolSet> {
+  return { type: "text-delta", id: "0", text, providerMetadata: undefined } as TextStreamPart<ToolSet>;
+}
+
+function finish(finishReason: FinishReason, rawFinishReason?: string): TextStreamPart<ToolSet> {
+  return {
+    type: "finish",
+    finishReason,
+    rawFinishReason,
+    totalUsage: ZERO_USAGE,
+    usage: ZERO_USAGE,
+    providerMetadata: undefined,
+    response: {},
+  } as TextStreamPart<ToolSet>;
+}
+
+function finishStep(finishReason: FinishReason, rawFinishReason?: string): TextStreamPart<ToolSet> {
+  return {
+    type: "finish-step",
+    finishReason,
+    rawFinishReason,
+    usage: ZERO_USAGE,
+    providerMetadata: undefined,
+    response: {},
+  } 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 errorPart(error: unknown): TextStreamPart<ToolSet> {
+  return { type: "error", error } as TextStreamPart<ToolSet>;
+}
+
+function toolErrorPart(toolCallId: string, toolName: string, error: unknown): TextStreamPart<ToolSet> {
+  return {
+    type: "tool-error",
+    toolCallId,
+    toolName,
+    input: {},
+    error,
+  } as TextStreamPart<ToolSet>;
+}
+
+function abortPart(reason: string): TextStreamPart<ToolSet> {
+  return { type: "abort", reason } as TextStreamPart<ToolSet>;
+}
+
+async function collectParts(reasoner: Reasoner, turn: ReasonerTurn): Promise<ReasoningPart[]> {
+  const parts: ReasoningPart[] = [];
+  for await (const part of reasoner.stream(turn)) {
+    parts.push(part);
+  }
+  return parts;
+}
+
+describe("from-ai-sdk adapters", () => {
+  it("maps happy path: deltas, tool-call, tool-result, finish:stop", async () => {
+    const reasoner = fromStreamFactory(async function* () {
+      yield textDelta("Hello ");
+      yield textDelta("world.");
+      yield toolCall("tc-1", "get_weather", { city: "NYC" });
+      yield toolResult("tc-1", "get_weather", { temp: 72 });
+      yield finish("stop");
+    });
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "Hello " },
+      { type: "text-delta", text: "world." },
+      {
+        type: "tool-call",
+        toolId: "tc-1",
+        toolName: "get_weather",
+        args: { city: "NYC" },
+      },
+      {
+        type: "tool-result",
+        toolId: "tc-1",
+        toolName: "get_weather",
+        result: JSON.stringify({ temp: 72 }),
+      },
+      { type: "finish", reason: "stop", text: "Hello world.", usage: FINISH_USAGE },
+    ]);
+  });
+
+  it("maps error part to terminal error", async () => {
+    const reasoner = fromStreamFactory(async function* () {
+      yield textDelta("partial");
+      yield errorPart(new Error("provider failed"));
+    });
+
+    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("provider failed");
+      expect(parts[1].recoverable).toBe(false);
+    }
+  });
+
+  it("maps an abort part to an AbortError-named cause so downstream isAbortError guards swallow it", async () => {
+    // Regression: a barge-in aborts the reasoner mid-delegate → the AI SDK emits an `abort`
+    // stream part. If the cause isn't named "AbortError", the realtime-bridge's isAbortError
+    // guard misses it and surfaces a fatal bridge.error/internal_fault (the native multi-turn crash).
+    const reasoner = fromStreamFactory(async function* () {
+      yield textDelta("partial");
+      yield abortPart("This operation was aborted");
+    });
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts[1]?.type).toBe("error");
+    if (parts[1]?.type === "error") {
+      expect(parts[1].cause.name).toBe("AbortError");
+      // The web/Node abort convention: err.name === "AbortError".
+      const isAbortError = (err: unknown): boolean => err instanceof Error && err.name === "AbortError";
+      expect(isAbortError(parts[1].cause)).toBe(true);
+    }
+  });
+
+  it("maps tool-error part to terminal error", async () => {
+    const reasoner = fromStreamFactory(async function* () {
+      yield toolErrorPart("tc-1", "broken_tool", new Error("tool exploded"));
+    });
+
+    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("tool exploded");
+    }
+  });
+
+  it("maps finish-step(error) to terminal error", async () => {
+    const reasoner = fromStreamFactory(async function* () {
+      yield finishStep("error", "MALFORMED_FUNCTION_CALL");
+    });
+
+    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(
+        "AI SDK provider step failed: error (MALFORMED_FUNCTION_CALL)",
+      );
+      expect(parts[0].recoverable).toBe(true);
+    }
+  });
+
+  it("extracts provider/model for cost attribution from a model object and a bare id", () => {
+    // Regression: the bridge emitted usage with EMPTY provider/model in production while a
+    // session-layer test that hand-supplied them stayed green. modelIdentity is the real
+    // extraction the bridge threads onto finish usage, so usage counters carry a model tag.
+    const objectModel = { provider: "openai", modelId: "gpt-4.1-mini" } as never;
+    expect(modelIdentity(objectModel)).toEqual({ provider: "openai", model: "gpt-4.1-mini" });
+
+    // A bare id string: the id IS the model; provider is unknown, so it's omitted (not "").
+    expect(modelIdentity("openai/gpt-4.1-mini" as never)).toEqual({ model: "openai/gpt-4.1-mini" });
+  });
+
+  it("maps finish(length) to finish with accumulated text", async () => {
+    const reasoner = fromStreamFactory(async function* () {
+      yield textDelta("truncated");
+      yield finish("length", "MAX_TOKENS");
+    });
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "truncated" },
+      { type: "finish", reason: "length", text: "truncated", usage: FINISH_USAGE },
+    ]);
+  });
+
+  it("drops reasoning-delta and tool-input-start parts", async () => {
+    const reasoner = fromStreamFactory(async function* () {
+      yield {
+        type: "reasoning-delta",
+        id: "r1",
+        text: "thinking...",
+        providerMetadata: undefined,
+      } as TextStreamPart<ToolSet>;
+      yield {
+        type: "tool-input-start",
+        id: "t1",
+        toolName: "search",
+        providerMetadata: undefined,
+      } as TextStreamPart<ToolSet>;
+      yield textDelta("answer");
+      yield finish("stop");
+    });
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "answer" },
+      { type: "finish", reason: "stop", text: "answer", usage: FINISH_USAGE },
+    ]);
+  });
+
+  it("yields first text-delta before source stream completes (no buffering)", async () => {
+    let resolveGate: (() => void) | undefined;
+    const gate = new Promise<void>((resolve) => {
+      resolveGate = resolve;
+    });
+
+    const reasoner = fromStreamFactory(async function* () {
+      yield textDelta("immediate");
+      await gate;
+    });
+
+    const iterator = reasoner.stream(baseTurn())[Symbol.asyncIterator]();
+    const first = await iterator.next();
+
+    expect(first.done).toBe(false);
+    expect(first.value).toEqual({ type: "text-delta", text: "immediate" });
+    resolveGate?.();
+  });
+
+  it("maps stream ending without finish to terminal error", async () => {
+    const reasoner = fromStreamFactory(async function* () {
+      yield textDelta("no finish");
+    });
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toHaveLength(2);
+    expect(parts[1]?.type).toBe("error");
+    if (parts[1]?.type === "error") {
+      expect(parts[1].cause.message).toBe("AI SDK stream ended without a provider finish reason");
+    }
+  });
+
+  it("fromAiSdkAgent maps agent fullStream through the same table", async () => {
+    const agent: AiSdkAgentLike = {
+      async stream() {
+        return {
+          fullStream: (async function* () {
+            yield textDelta("From ");
+            yield textDelta("agent");
+            yield finish("stop");
+          })(),
+        };
+      },
+    };
+
+    const parts = await collectParts(fromAiSdkAgent(agent), baseTurn());
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "From " },
+      { type: "text-delta", text: "agent" },
+      { type: "finish", reason: "stop", text: "From agent", usage: FINISH_USAGE },
+    ]);
+  });
+});

package/src/heard-prefix-commit.test.ts

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import {
+  PipelineBusImpl,
+  Route,
+  type EndOfSpeechPacket,
+  type InMemoryIuLedger,
+  type IncrementalUnitId,
+  type InterruptLlmPacket,
+  type TextToSpeechPlayoutProgressPacket,
+  type TextToSpeechTextPacket,
+  type TextToSpeechWordTimestampsPacket,
+  type TtsWordTimestamp,
+} from "@kuralle-syrinx/core";
+import type { FinishReason, TextStreamPart, ToolSet } from "ai";
+import { fromStreamFactory } from "./from-ai-sdk.js";
+import { ReasoningBridge } from "./index.js";
+
+const ZERO_USAGE = {
+  inputTokens: 0,
+  inputTokenDetails: { noCacheTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
+  outputTokens: 0,
+  outputTokenDetails: { textTokens: 0, reasoningTokens: 0 },
+  totalTokens: 0,
+};
+
+type BridgeLedgerAccess = {
+  iuLedger: InMemoryIuLedger;
+};
+
+function bridgeLedger(plugin: ReasoningBridge): BridgeLedgerAccess {
+  return plugin as unknown as BridgeLedgerAccess;
+}
+
+function assistantId(contextId: string, epoch = 1): IncrementalUnitId {
+  return { contextId, iuId: `${contextId}#assistant`, epoch };
+}
+
+function userTurnId(contextId: string, epoch = 1): IncrementalUnitId {
+  return { contextId, iuId: contextId, epoch };
+}
+
+describe("ReasoningBridge heard-prefix commit (S2-01)", () => {
+  it("commits assistant IU with word-boundary prefix on barge-in during playback", async () => {
+    const packets: Array<{ packet: unknown }> = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Hello world foo bar.");
+        yield finish("stop");
+      }),
+    );
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-word";
+
+    bus.push(Route.Main, turnComplete(ctx, "first question"));
+    await waitFor(() => hasPacket(packets, "llm.done", ctx));
+
+    bus.push(Route.Main, wordTimestamps(ctx, [
+      { word: "Hello", startMs: 0, endMs: 200 },
+      { word: "world", startMs: 220, endMs: 400 },
+      { word: "foo", startMs: 420, endMs: 600 },
+      { word: "bar.", startMs: 620, endMs: 800 },
+    ]));
+    bus.push(Route.Main, playoutProgress(ctx, 450));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    bus.push(Route.Critical, interruptLlm(ctx));
+    await waitFor(() => hasMetric(packets, "llm.history_truncated_to_spoken"));
+
+    const spoken = "Hello world";
+    const iu = ledger.iuLedger.get(assistantId(ctx))!;
+    expect(iu.state).toBe("committed");
+    expect(iu.committedPrefix?.chars).toBe(spoken.length);
+    expect(iu.committedPrefix?.ms).toBe(450);
+    expect(iu.committedPrefix?.chars).toBeLessThan("Hello world foo bar.".length);
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("commits assistant IU with spokenByContext prefix when word timestamps are absent", async () => {
+    const packets: Array<{ packet: unknown }> = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Sentence one. Sentence two.");
+        yield finish("stop");
+      }),
+    );
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-fallback";
+
+    bus.push(Route.Main, turnComplete(ctx, "first question"));
+    await waitFor(() => hasPacket(packets, "llm.done", ctx));
+
+    bus.push(Route.Main, ttsText(ctx, "Sentence one."));
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    bus.push(Route.Critical, interruptLlm(ctx));
+    await waitFor(() => hasMetric(packets, "llm.history_truncated_to_spoken"));
+
+    const spoken = "Sentence one.";
+    const iu = ledger.iuLedger.get(assistantId(ctx))!;
+    expect(iu.state).toBe("committed");
+    expect(iu.committedPrefix?.chars).toBe(spoken.length);
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("commits heard prefix on mid-stream interrupt without losing streamed packets", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* ({ signal }) {
+        yield textDelta("Hello");
+        await new Promise<void>((resolve) => {
+          if (signal.aborted) {
+            resolve();
+            return;
+          }
+          signal.addEventListener("abort", () => resolve(), { once: true });
+        });
+      }),
+    );
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-mid";
+
+    bus.push(Route.Main, turnComplete(ctx, "first question"));
+    await waitFor(() =>
+      packets.some(
+        ({ packet }) =>
+          (packet as { kind?: string }).kind === "llm.delta" &&
+          (packet as { text?: string }).text === "Hello",
+      ),
+    );
+
+    bus.push(Route.Main, ttsText(ctx, "Hello"));
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    bus.push(Route.Critical, interruptLlm(ctx));
+    await waitFor(() => hasMetric(packets, "llm.history_truncated_to_spoken"));
+
+    const iu = ledger.iuLedger.get(assistantId(ctx))!;
+    expect(iu.state).toBe("committed");
+    expect(iu.committedPrefix?.chars).toBe("Hello".length);
+
+    expect(packets).toContainEqual({
+      route: Route.Main,
+      packet: expect.objectContaining({ kind: "llm.delta", contextId: ctx, text: "Hello" }),
+    });
+    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done")).toBe(false);
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("commits assistant IU fully on clean completion without a truncated prefix", async () => {
+    const packets: Array<{ packet: unknown }> = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Clean answer.");
+        yield finish("stop");
+      }),
+    );
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-clean";
+
+    bus.push(Route.Main, turnComplete(ctx, "question"));
+    await waitFor(() => hasPacket(packets, "llm.done", ctx));
+
+    const iu = ledger.iuLedger.get(assistantId(ctx))!;
+    expect(iu.state).toBe("committed");
+    expect(iu.committedPrefix).toBeUndefined();
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("keeps distinct assistant and user-turn IUs in the ledger for one contextId", async () => {
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Answer.");
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: () => {} });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-dual";
+
+    bus.push(Route.Main, eosInterim(ctx, "hello"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    const userIu = ledger.iuLedger.get(userTurnId(ctx));
+    const assistantIu = ledger.iuLedger.get(assistantId(ctx));
+    expect(userIu?.kind).toBe("user_turn");
+    expect(assistantIu?.kind).toBe("assistant_response");
+    expect(userIu?.id.iuId).toBe(ctx);
+    expect(assistantIu?.id.iuId).toBe(`${ctx}#assistant`);
+    expect(userIu?.id.epoch).toBe(assistantIu?.id.epoch);
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+});
+
+function baseConfig(): Record<string, unknown> {
+  return {
+    api_key: "test-key",
+    model: "gpt-test",
+    system_prompt: "test",
+    retry_max_attempts: 1,
+    timeout_ms: 1000,
+  };
+}
+
+function turnComplete(contextId: string, text: string): EndOfSpeechPacket {
+  return { kind: "eos.turn_complete", contextId, timestampMs: Date.now(), text, transcripts: [] };
+}
+
+function eosInterim(contextId: string, text: string): { kind: "eos.interim"; contextId: string; timestampMs: number; text: string } {
+  return { kind: "eos.interim", contextId, timestampMs: Date.now(), text };
+}
+
+function ttsText(contextId: string, text: string): TextToSpeechTextPacket {
+  return { kind: "tts.text", contextId, timestampMs: Date.now(), text };
+}
+
+function wordTimestamps(contextId: string, words: TtsWordTimestamp[]): TextToSpeechWordTimestampsPacket {
+  return { kind: "tts.word_timestamps", contextId, timestampMs: Date.now(), words };
+}
+
+function playoutProgress(contextId: string, playedOutMs: number): TextToSpeechPlayoutProgressPacket {
+  return { kind: "tts.playout_progress", contextId, timestampMs: Date.now(), playedOutMs, complete: false };
+}
+
+function interruptLlm(contextId: string): InterruptLlmPacket {
+  return { kind: "interrupt.llm", contextId, timestampMs: Date.now() };
+}
+
+function textDelta(text: string): TextStreamPart<ToolSet> {
+  return { type: "text-delta", id: "0", text, providerMetadata: undefined } as TextStreamPart<ToolSet>;
+}
+
+function finish(finishReason: FinishReason): TextStreamPart<ToolSet> {
+  return {
+    type: "finish",
+    finishReason,
+    totalUsage: ZERO_USAGE,
+    usage: ZERO_USAGE,
+    providerMetadata: undefined,
+    response: {},
+  } as unknown as TextStreamPart<ToolSet>;
+}
+
+function hasPacket(packets: Array<{ packet: unknown }>, kind: string, contextId: string): boolean {
+  return packets.some(
+    ({ packet }) =>
+      (packet as { kind?: string }).kind === kind &&
+      (packet as { contextId?: string }).contextId === contextId,
+  );
+}
+
+function hasMetric(packets: Array<{ packet: unknown }>, name: string): boolean {
+  return packets.some(({ packet }) => (packet as { name?: string }).name === name);
+}
+
+async function waitFor(predicate: () => boolean): Promise<void> {
+  const started = Date.now();
+  while (!predicate()) {
+    if (Date.now() - started > 2000) throw new Error("Timed out waiting for condition");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}