@kuralle-syrinx/aisdk 4.4.1 → 4.5.0

package/dist/from-ai-sdk.d.ts

@@ -0,0 +1,35 @@
+import { streamText, type ModelMessage, type TextStreamPart, type ToolChoice, type ToolSet } from "ai";
+import { type Reasoner } 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 declare function fromAiSdkAgent(agent: AiSdkAgentLike): Reasoner;
+export declare function fromStreamText(config: StreamTextConfig): Reasoner;
+export declare function fromStreamFactory(factory: AISDKStreamFactory): Reasoner;
+/**
+ * Extract provider/model for cost attribution. The AI SDK model is either a bare id
+ * string (`"openai/gpt-4.1-mini"`) or a model object exposing `.provider` / `.modelId`.
+ * Without this, usage counters are tagged with empty provider/model and spend cannot be
+ * attributed to a model — the whole point of the low-cardinality tags.
+ */
+export declare function modelIdentity(model: StreamTextConfig["model"]): {
+    provider?: string;
+    model?: string;
+};

package/dist/from-ai-sdk.js

@@ -0,0 +1,200 @@
+// 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, } from "ai";
+import { categorizeLlmError, isRecoverable, } from "@kuralle-syrinx/core";
+export function fromAiSdkAgent(agent) {
+    return {
+        stream(turn) {
+            return streamFromAgent(agent, turn);
+        },
+    };
+}
+export function fromStreamText(config) {
+    return {
+        stream(turn) {
+            return streamFromStreamText(config, turn);
+        },
+    };
+}
+export function fromStreamFactory(factory) {
+    return {
+        stream(turn) {
+            return streamFromFactory(factory, turn);
+        },
+    };
+}
+async function* streamFromAgent(agent, turn) {
+    const messages = buildMessagesForTurn(turn);
+    const result = await agent.stream({ messages, abortSignal: turn.signal });
+    yield* mapTextStreamParts(result.fullStream);
+}
+async function* streamFromStreamText(config, turn) {
+    const messages = buildMessagesForTurn(turn);
+    const result = streamText({
+        ...config,
+        messages,
+        abortSignal: turn.signal,
+    });
+    yield* mapTextStreamParts(result.fullStream, modelIdentity(config.model));
+}
+async function* streamFromFactory(factory, turn) {
+    const messages = buildMessagesForTurn(turn);
+    yield* mapTextStreamParts(factory({ userText: turn.userText, signal: turn.signal, messages }));
+}
+function buildMessagesForTurn(turn) {
+    return [...mapMessages(turn.messages), { role: "user", content: turn.userText }];
+}
+function mapMessages(messages) {
+    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, identity = {}) {
+    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": {
+                // An abort is a benign cancellation (barge-in aborted the reasoner), NOT an error.
+                // Carry the web/Node standard `name === "AbortError"` so downstream `isAbortError`
+                // guards (realtime-bridge runDelegate, ReasoningBridge) swallow it instead of
+                // surfacing a fatal `bridge.error/internal_fault`.
+                const cause = new Error(part.reason ?? "AI SDK stream aborted");
+                cause.name = "AbortError";
+                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,
+                        // The AI SDK finish part carries totalUsage; forward it so the bridge can
+                        // record cost. Omit entirely when the provider reported nothing.
+                        ...(part.totalUsage
+                            ? { usage: { ...identity, ...toReasonerUsage(part.totalUsage) } }
+                            : {}),
+                    };
+                    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"));
+    }
+}
+/**
+ * Extract provider/model for cost attribution. The AI SDK model is either a bare id
+ * string (`"openai/gpt-4.1-mini"`) or a model object exposing `.provider` / `.modelId`.
+ * Without this, usage counters are tagged with empty provider/model and spend cannot be
+ * attributed to a model — the whole point of the low-cardinality tags.
+ */
+export function modelIdentity(model) {
+    if (typeof model === "string")
+        return { model };
+    const m = model;
+    return {
+        ...(typeof m.provider === "string" ? { provider: m.provider } : {}),
+        ...(typeof m.modelId === "string" ? { model: m.modelId } : {}),
+    };
+}
+/** Copy only the token fields the SDK actually populated (all are `number | undefined`). */
+function toReasonerUsage(u) {
+    return {
+        ...(u.inputTokens !== undefined ? { inputTokens: u.inputTokens } : {}),
+        ...(u.outputTokens !== undefined ? { outputTokens: u.outputTokens } : {}),
+        ...(u.totalTokens !== undefined ? { totalTokens: u.totalTokens } : {}),
+        ...(u.cachedInputTokens !== undefined ? { cachedInputTokens: u.cachedInputTokens } : {}),
+        ...(u.reasoningTokens !== undefined ? { reasoningTokens: u.reasoningTokens } : {}),
+    };
+}
+function mapFinishReason(finishReason) {
+    if (finishReason === "tool-calls")
+        return "tool";
+    if (finishReason === "length")
+        return "length";
+    return "stop";
+}
+function toErrorPart(cause) {
+    return {
+        type: "error",
+        cause,
+        recoverable: isRecoverable(categorizeLlmError(cause)),
+    };
+}
+function formatFinishReason(finishReason, rawFinishReason) {
+    return rawFinishReason ? `${finishReason} (${rawFinishReason})` : finishReason;
+}
+function toRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return {};
+    return value;
+}
+function stringifyToolOutput(output) {
+    return typeof output === "string" ? output : JSON.stringify(output);
+}

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import type { PipelineBus } from "@kuralle-syrinx/core";
+import { type ModelMessage, type TextStreamPart, type ToolSet } from "ai";
+import { type VoicePlugin, type PluginConfig, type Reasoner, type ReasonerSessionStore } from "@kuralle-syrinx/core";
+export { fromAiSdkAgent, fromStreamText, fromStreamFactory, type AiSdkAgentLike, type StreamTextConfig, } from "./from-ai-sdk.js";
+export type AISDKBridgeTools = ToolSet;
+export type AISDKStreamFactory = (request: {
+    userText: string;
+    signal: AbortSignal;
+    messages: ModelMessage[];
+}) => AsyncGenerator<TextStreamPart<ToolSet>>;
+export interface RunPointer {
+    readonly runId: string;
+}
+export interface RunStore {
+    save(contextId: string, runId: string): void | Promise<void>;
+    takePending(contextId: string): RunPointer | null | Promise<RunPointer | null>;
+    discard(contextId: string): void | Promise<void>;
+}
+export declare class ReasoningBridge implements VoicePlugin {
+    private readonly reasoner;
+    private readonly opts;
+    private bus;
+    private timeoutMs;
+    private maxHistoryTurns;
+    private history;
+    private readonly transientContextMessages;
+    private activeGeneration;
+    private speculativeDraft;
+    private iuLedger;
+    private readonly epochByContext;
+    private turnEpochCounter;
+    private retryConfig;
+    private disposers;
+    private spokenByContext;
+    private turnUserText;
+    private assistantMsgByContext;
+    private wordTimestampsByContext;
+    private playedOutMsByContext;
+    constructor(reasoner: Reasoner, 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;
+        /**
+         * Speculative generation (LiveKit preemptive-generation / Deepgram Flux
+         * eager-EOT semantics): start the LLM on `eos.interim` with every side effect
+         * held back; commit as-is when `eos.turn_complete` confirms the same
+         * transcript, regenerate when it differs, discard on `eos.retracted`.
+         * Parallelizes LLM TTFT with the endpoint-confirmation window. Opt-in:
+         * unconfirmed endpoints cost extra LLM calls (Deepgram measures +50–70% at
+         * eager thresholds 0.3–0.5). Drafts never consume a suspended-run pointer —
+         * `runStore` resume stays confirmed-turn-only.
+         *
+         * **Only enable this with a confidence-gated eager endpointer (Deepgram Flux).**
+         * Promotion requires `draft.userText === eos.text` — exact equality. Flux
+         * guarantees the EndOfTurn transcript matches the preceding EagerEndOfTurn when
+         * no TurnResumed intervened, so drafts promote. `PipecatEOSPlugin` instead pushes
+         * `eos.interim` on EVERY non-empty STT interim, and each interim discards the prior
+         * draft and starts a new call, so the surviving draft is built on an interim
+         * transcript that rarely matches the final one.
+         *
+         * Measured live on smart-turn, one turn, university fixture:
+         *   ON  — started 13, discarded 13, promoted 0; ttfa 1724ms, llmTtft 1269ms
+         *   OFF — started  0, discarded  0, promoted 0; ttfa 1302ms, llmTtft 1025ms
+         *
+         * Thirteen wasted LLM calls, zero promotions, and latency got *worse*. The lever
+         * is Flux-specific; on a per-interim endpointer it is pure cost.
+         */
+        speculative?: boolean;
+    });
+    injectContext(text: string): void;
+    initialize(bus: PipelineBus, config: PluginConfig): Promise<void>;
+    /** Start (or restart, if a newer eager endpoint supersedes) the speculative draft. */
+    private runDraft;
+    private iuIdFor;
+    private assistantIuIdFor;
+    private discardDraft;
+    private metric;
+    private processTurn;
+    close(): Promise<void>;
+    private rememberTurn;
+    /** G4: persist the bounded history snapshot, best-effort off the hot path. */
+    private persistHistory;
+    /**
+     * G25: compute the spoken prefix — the assistant text the user actually heard before
+     * the barge-in. Uses word timestamps + playout position when available (exact at word
+     * boundaries), otherwise falls back to the accumulated text sent to TTS (approximate).
+     */
+    private computeSpokenPrefix;
+    /**
+     * Barge-in: rewrite the interrupted turn's history to what the user actually HEARD,
+     * not the full generated reply. Precision ladder (G25):
+     *   1. Word timestamps + playout position → exact word-boundary prefix.
+     *   2. Fallback: text sent to TTS — approximate (may include unplayed audio since
+     *      TTS streams faster than realtime; headless/browser paths have no playout clock).
+     * If the turn was committed (generation done before barge-in), truncates in place.
+     * If mid-generation (not yet committed), records what was sent. Either way the user
+     * utterance is preserved: neither divergent nor amnesiac.
+     */
+    private commitInterruptedHistory;
+    private trimHistory;
+    private clearTurnState;
+}