@kuralle-syrinx/aisdk 2.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,53 @@
+# @kuralle-syrinx/aisdk
+
+The LLM stage of the Syrinx cascade as a bus-native `VoicePlugin` — **`ReasoningBridge`** — plus the AI SDK adapters that turn a Vercel AI SDK backend into the normalized [`Reasoner`](../core/README.md#the-reasoner-seam) seam it drives.
+
+`ReasoningBridge` consumes `eos.turn_complete`, drives one `reasoner.stream(turn)` per turn, and emits `llm.delta` / `llm.tool_call` / `llm.tool_result` / `llm.done` (or `llm.error` → retry) packets. It owns conversation history, the word-timestamp **spoken-prefix barge-in**, retry, finish-reason validation, and turn-superseding — none of which change when you swap the backend.
+
+## Adapters
+
+```ts
+import { fromAiSdkAgent, fromStreamText, fromStreamFactory } from "@kuralle-syrinx/aisdk";
+
+fromAiSdkAgent(agent)        // wraps (await agent.stream({messages, abortSignal})).fullStream
+fromStreamText(config)       // raw `streamText` config as a Reasoner
+fromStreamFactory(factory)   // an AISDKStreamFactory (async generator of TextStreamPart) — the test seam
+```
+
+All three map the full `ai@6` `TextStreamPart` union → `ReasoningPart` through one no-buffering generator: `text-delta`/`tool-call`/`tool-result` pass through; `error`/`tool-error`/`abort` and `finish-step`/`finish` with abnormal reasons become a terminal `error` part (driving the bridge's retry/`llm.error` path); everything else is dropped. No buffering — each part is yielded the instant the backend produces it (the §7a latency invariant).
+
+## Usage
+
+```ts
+import { createOpenAI } from "@ai-sdk/openai";
+import { stepCountIs } from "ai";
+import { ReasoningBridge, fromStreamText } from "@kuralle-syrinx/aisdk";
+
+const bridge = new ReasoningBridge(fromStreamText({
+  model: createOpenAI({ apiKey })("gpt-4.1-mini"),
+  system: "You are a helpful voice assistant.",
+  temperature: 0.4,
+  maxOutputTokens: 256,
+  maxRetries: 0,
+  timeout: 30_000,
+  stopWhen: stepCountIs(1),
+}));
+session.registerPlugin("bridge", bridge);
+```
+
+The constructor takes a **`Reasoner` only** — wrap your backend explicitly with the matching adapter. There is **no auto-wrap / `.stream()`-probe**. Provider config (model, system, temperature, tools, …) lives in the adapter; the plugin config holds only `timeout_ms` / `max_history_turns` / retry.
+
+## Suspend/resume (optional)
+
+```ts
+new ReasoningBridge(reasoner, { runStore, onResumeConflict: "restart" });
+```
+
+- `runStore?: RunStore` — a `{ save(contextId, runId), takePending(contextId), discard(contextId) }` pointer store ("which conversation has a pending suspended run"). Without it, suspend/resume is inert.
+- `onResumeConflict` (default `"restart"`) — on barge-in over a pending run, the pointer is discarded and the question is re-asked fresh (never resume a checkpoint that diverged from the corrected spoken-prefix history). `"replay"` is reserved (throws "not yet supported").
+
+A `RunStore` implementation is provided by `@kuralle-syrinx/server-workers-mastra` (`DurableObjectRunStore`, SQL on `ctx.storage.sql`).
+
+## Gotcha
+
+The bridge is the single source of truth for history (the backend is stateless-per-turn) — this is what makes spoken-prefix barge-in correct. Don't give the backend its own conversation memory; pass `turn.messages`.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@kuralle-syrinx/aisdk",
+  "version": "2.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.67",
+    "ai": "^6.0.0",
+    "zod": "^4.1.8",
+    "@kuralle-syrinx/core": "2.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/from-ai-sdk.test.ts

@@ -0,0 +1,276 @@
+// 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, 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,
+};
+
+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>;
+}
+
+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." },
+    ]);
+  });
+
+  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 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("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" },
+    ]);
+  });
+
+  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" },
+    ]);
+  });
+
+  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" },
+    ]);
+  });
+});

package/src/from-ai-sdk.ts

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — AI SDK → Reasoner adapters
+//
+// Normalizes ai@6 TextStreamPart streams into the Reasoner/ReasoningPart seam.
+// See RFC §4.3 and Sprint 0 PLAN §6.
+
+import {
+  streamText,
+  type FinishReason,
+  type ModelMessage,
+  type TextStreamPart,
+  type ToolChoice,
+  type ToolSet,
+} from "ai";
+import {
+  categorizeLlmError,
+  isRecoverable,
+  type Reasoner,
+  type ReasonerMessage,
+  type ReasonerTurn,
+  type ReasoningPart,
+} from "@kuralle-syrinx/core";
+import type { AISDKStreamFactory } from "./index.js";
+
+export interface AiSdkAgentLike {
+  stream(opts: {
+    messages: ModelMessage[];
+    abortSignal: AbortSignal;
+  }): Promise<{ fullStream: AsyncIterable<TextStreamPart<ToolSet>> }>;
+}
+
+export type StreamTextConfig = {
+  model: Parameters<typeof streamText>[0]["model"];
+  system?: string;
+  tools?: ToolSet;
+  toolChoice?: ToolChoice<ToolSet>;
+  temperature?: number;
+  maxOutputTokens?: number;
+  maxRetries?: number;
+  timeout?: number;
+  stopWhen?: Parameters<typeof streamText>[0]["stopWhen"];
+};
+
+export function fromAiSdkAgent(agent: AiSdkAgentLike): Reasoner {
+  return {
+    stream(turn: ReasonerTurn): AsyncIterable<ReasoningPart> {
+      return streamFromAgent(agent, turn);
+    },
+  };
+}
+
+export function fromStreamText(config: StreamTextConfig): Reasoner {
+  return {
+    stream(turn: ReasonerTurn): AsyncIterable<ReasoningPart> {
+      return streamFromStreamText(config, turn);
+    },
+  };
+}
+
+export function fromStreamFactory(factory: AISDKStreamFactory): Reasoner {
+  return {
+    stream(turn: ReasonerTurn): AsyncIterable<ReasoningPart> {
+      return streamFromFactory(factory, turn);
+    },
+  };
+}
+
+async function* streamFromAgent(agent: AiSdkAgentLike, turn: ReasonerTurn): AsyncGenerator<ReasoningPart> {
+  const messages = buildMessagesForTurn(turn);
+  const result = await agent.stream({ messages, abortSignal: turn.signal });
+  yield* mapTextStreamParts(result.fullStream);
+}
+
+async function* streamFromStreamText(config: StreamTextConfig, turn: ReasonerTurn): AsyncGenerator<ReasoningPart> {
+  const messages = buildMessagesForTurn(turn);
+  const result = streamText({
+    ...config,
+    messages,
+    abortSignal: turn.signal,
+  });
+  yield* mapTextStreamParts(result.fullStream);
+}
+
+async function* streamFromFactory(factory: AISDKStreamFactory, turn: ReasonerTurn): AsyncGenerator<ReasoningPart> {
+  const messages = buildMessagesForTurn(turn);
+  yield* mapTextStreamParts(factory({ userText: turn.userText, signal: turn.signal, messages }));
+}
+
+function buildMessagesForTurn(turn: ReasonerTurn): ModelMessage[] {
+  return [...mapMessages(turn.messages), { role: "user", content: turn.userText }];
+}
+
+function mapMessages(messages: readonly ReasonerMessage[]): ModelMessage[] {
+  return messages.map((message) => {
+    if (message.role === "tool") {
+      return {
+        role: "tool",
+        content: [
+          {
+            type: "tool-result",
+            toolCallId: message.toolCallId ?? "",
+            toolName: "",
+            output: { type: "text", value: message.content },
+          },
+        ],
+      };
+    }
+    return { role: message.role, content: message.content };
+  });
+}
+
+async function* mapTextStreamParts(
+  source: AsyncIterable<TextStreamPart<ToolSet>>,
+): AsyncGenerator<ReasoningPart> {
+  let accumulatedText = "";
+  let sawFinish = false;
+
+  for await (const part of source) {
+    switch (part.type) {
+      case "text-delta":
+        accumulatedText += part.text;
+        yield { type: "text-delta", text: part.text };
+        break;
+      case "tool-call":
+        yield {
+          type: "tool-call",
+          toolId: part.toolCallId,
+          toolName: part.toolName,
+          args: toRecord(part.input),
+        };
+        break;
+      case "tool-result":
+        yield {
+          type: "tool-result",
+          toolId: part.toolCallId,
+          toolName: part.toolName,
+          result: stringifyToolOutput(part.output),
+        };
+        break;
+      case "error": {
+        const cause = part.error instanceof Error ? part.error : new Error(String(part.error));
+        yield toErrorPart(cause);
+        return;
+      }
+      case "tool-error": {
+        const cause =
+          part.error instanceof Error ? part.error : new Error(`Tool ${part.toolName} failed`);
+        yield toErrorPart(cause);
+        return;
+      }
+      case "abort": {
+        const cause = new Error(part.reason ?? "AI SDK stream aborted");
+        yield toErrorPart(cause);
+        return;
+      }
+      case "finish-step":
+        if (part.finishReason === "error" || part.finishReason === "content-filter") {
+          yield toErrorPart(
+            new Error(
+              `AI SDK provider step failed: ${formatFinishReason(part.finishReason, part.rawFinishReason)}`,
+            ),
+          );
+          return;
+        }
+        break;
+      case "finish":
+        sawFinish = true;
+        if (part.finishReason === "stop" || part.finishReason === "tool-calls" || part.finishReason === "length") {
+          yield {
+            type: "finish",
+            reason: mapFinishReason(part.finishReason),
+            text: accumulatedText,
+          };
+          return;
+        }
+        if (
+          part.finishReason === "error" ||
+          part.finishReason === "content-filter" ||
+          part.finishReason === "other" ||
+          part.finishReason === "unknown"
+        ) {
+          yield toErrorPart(
+            new Error(
+              `AI SDK provider did not complete normally: ${formatFinishReason(part.finishReason, part.rawFinishReason)}`,
+            ),
+          );
+          return;
+        }
+        break;
+      default:
+        break;
+    }
+  }
+
+  if (!sawFinish) {
+    yield toErrorPart(new Error("AI SDK stream ended without a provider finish reason"));
+  }
+}
+
+function mapFinishReason(finishReason: FinishReason): "stop" | "tool" | "length" {
+  if (finishReason === "tool-calls") return "tool";
+  if (finishReason === "length") return "length";
+  return "stop";
+}
+
+function toErrorPart(cause: Error): ReasoningPart {
+  return {
+    type: "error",
+    cause,
+    recoverable: isRecoverable(categorizeLlmError(cause)),
+  };
+}
+
+function formatFinishReason(finishReason: FinishReason, rawFinishReason: string | undefined): string {
+  return rawFinishReason ? `${finishReason} (${rawFinishReason})` : finishReason;
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+function stringifyToolOutput(output: unknown): string {
+  return typeof output === "string" ? output : JSON.stringify(output);
+}