@kuralle-syrinx/aisdk 4.1.0 → 4.3.0

package/package.json

@@ -1,20 +1,38 @@
 {
   "name": "@kuralle-syrinx/aisdk",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "private": false,
-  "type": "module",
+  "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": [
+    "voice",
+    "voice-agent",
+    "speech",
+    "syrinx",
+    "ai-sdk",
+    "vercel-ai"
+  ],
   "license": "MIT",
+  "homepage": "https://github.com/kuralle/syrinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/syrinx.git",
+    "directory": "packages/aisdk"
+  },
+  "bugs": {
+    "url": "https://github.com/kuralle/syrinx/issues"
+  },
+  "type": "module",
   "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": "4.1.0"
+    "@kuralle-syrinx/core": "4.3.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0"
+    "vitest": "^3.2.6"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/from-ai-sdk.ts

@@ -8,6 +8,7 @@
 import {
   streamText,
   type FinishReason,
+  type LanguageModelUsage,
   type ModelMessage,
   type TextStreamPart,
   type ToolChoice,
@@ -19,6 +20,7 @@ import {
   type Reasoner,
   type ReasonerMessage,
   type ReasonerTurn,
+  type ReasonerUsage,
   type ReasoningPart,
 } from "@kuralle-syrinx/core";
 import type { AISDKStreamFactory } from "./index.js";
@@ -79,7 +81,7 @@ async function* streamFromStreamText(config: StreamTextConfig, turn: ReasonerTur
     messages,
     abortSignal: turn.signal,
   });
-  yield* mapTextStreamParts(result.fullStream);
+  yield* mapTextStreamParts(result.fullStream, modelIdentity(config.model));
 }
 
 async function* streamFromFactory(factory: AISDKStreamFactory, turn: ReasonerTurn): AsyncGenerator<ReasoningPart> {
@@ -112,6 +114,7 @@ function mapMessages(messages: readonly ReasonerMessage[]): ModelMessage[] {
 
 async function* mapTextStreamParts(
   source: AsyncIterable<TextStreamPart<ToolSet>>,
+  identity: { provider?: string; model?: string } = {},
 ): AsyncGenerator<ReasoningPart> {
   let accumulatedText = "";
   let sawFinish = false;
@@ -150,7 +153,12 @@ async function* mapTextStreamParts(
         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;
       }
@@ -171,6 +179,11 @@ async function* mapTextStreamParts(
             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;
         }
@@ -198,6 +211,32 @@ async function* mapTextStreamParts(
   }
 }
 
+/**
+ * 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: StreamTextConfig["model"]): { provider?: string; model?: string } {
+  if (typeof model === "string") return { model };
+  const m = model as { provider?: unknown; modelId?: unknown };
+  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: LanguageModelUsage): ReasonerUsage {
+  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: FinishReason): "stop" | "tool" | "length" {
   if (finishReason === "tool-calls") return "tool";
   if (finishReason === "length") return "length";

package/src/index.ts

@@ -20,12 +20,14 @@ import {
   type ReasonerSessionStore,
   type ReasonerTurn,
   type TtsWordTimestamp,
+  type IncrementalUnitId,
   categorizeLlmError,
   isRecoverable,
   readRetryConfig,
   waitForRetryDelay,
   ErrorCategory,
   type RetryConfig,
+  InMemoryIuLedger,
 } from "@kuralle-syrinx/core";
 
 export {
@@ -60,8 +62,6 @@ export interface RunStore {
  * simply dropped — the generation was never observable.
  */
 interface SpeculativeHold {
-  promoted: boolean;
-  failed: boolean;
   buffered: Array<() => void>;
 }
 
@@ -70,6 +70,10 @@ export class ReasoningBridge implements VoicePlugin {
   private timeoutMs: number = 30_000;
   private maxHistoryTurns: number = 12;
   private history: Array<{ role: "system" | "user" | "assistant" | "tool"; content: string; toolCallId?: string }> = [];
+  private readonly transientContextMessages = new Set<{
+    role: "system";
+    content: string;
+  }>();
   private activeGeneration: { contextId: string; controller: AbortController } | null = null;
   // At most one speculative draft at a time; `hold` gates its side effects.
   private speculativeDraft: {
@@ -77,7 +81,11 @@ export class ReasoningBridge implements VoicePlugin {
     userText: string;
     controller: AbortController;
     hold: SpeculativeHold;
+    id: IncrementalUnitId;
   } | null = null;
+  private iuLedger!: InMemoryIuLedger;
+  private readonly epochByContext = new Map<string, number>();
+  private turnEpochCounter = 0;
   private retryConfig: RetryConfig = readRetryConfig({});
   private disposers: Array<() => void> = [];
   // G2/G25: per-turn state so a barged-in turn is remembered as what the user HEARD,
@@ -123,6 +131,21 @@ export class ReasoningBridge implements VoicePlugin {
        * 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;
     } = {},
@@ -132,8 +155,29 @@ export class ReasoningBridge implements VoicePlugin {
     }
   }
 
+  injectContext(text: string): void {
+    const message = { role: "system" as const, content: text };
+    this.history.push(message);
+    this.transientContextMessages.add(message);
+  }
+
   async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
     this.bus = bus;
+    this.iuLedger = new InMemoryIuLedger((a) => {
+      const detail =
+        a.kind === "terminal_op"
+          ? `${a.op} on ${a.state} IU`
+          : `${a.op} on unknown IU`;
+      this.bus?.push(Route.Background, {
+        kind: "llm.error",
+        contextId: a.id.contextId,
+        timestampMs: Date.now(),
+        component: "iu_ledger",
+        category: ErrorCategory.InternalFault,
+        cause: new Error(`iu_ledger anomaly: ${a.kind} ${detail}`),
+        isRecoverable: true,
+      });
+    });
     this.timeoutMs = readPositiveIntegerConfig(config["timeout_ms"], 30_000);
     this.maxHistoryTurns = readPositiveIntegerConfig(config["max_history_turns"], 12);
     this.retryConfig = readRetryConfig(config);
@@ -165,10 +209,11 @@ export class ReasoningBridge implements VoicePlugin {
           draft.contextId === eos.contextId &&
           draft.userText === eos.text &&
           !draft.controller.signal.aborted &&
-          !draft.hold.failed
+          this.iuLedger.get(draft.id)?.state === "hypothesized"
         ) {
+          this.iuLedger.commit(draft.id);
           this.speculativeDraft = null;
-          draft.hold.promoted = true;
+          this.metric(eos.contextId, "speculative.draft_promoted");
           for (const flush of draft.hold.buffered.splice(0)) flush();
           return;
         }
@@ -240,17 +285,53 @@ export class ReasoningBridge implements VoicePlugin {
   /** Start (or restart, if a newer eager endpoint supersedes) the speculative draft. */
   private async runDraft(userText: string, contextId: string): Promise<void> {
     this.discardDraft();
+    this.metric(contextId, "speculative.draft_started");
+    const id = this.iuIdFor(contextId);
+    this.iuLedger.add({ id, kind: "user_turn", state: "hypothesized" });
     const controller = new AbortController();
-    const hold: SpeculativeHold = { promoted: false, failed: false, buffered: [] };
-    this.speculativeDraft = { contextId, userText, controller, hold };
-    await this.processTurn(userText, contextId, hold, controller);
+    const hold: SpeculativeHold = { buffered: [] };
+    this.speculativeDraft = { contextId, userText, controller, hold, id };
+    await this.processTurn(userText, contextId, hold, controller, id);
+  }
+
+  private iuIdFor(contextId: string): IncrementalUnitId {
+    let epoch = this.epochByContext.get(contextId);
+    if (epoch === undefined) {
+      epoch = ++this.turnEpochCounter;
+      this.epochByContext.set(contextId, epoch);
+    }
+    return { contextId, iuId: contextId, epoch };
+  }
+
+  private assistantIuIdFor(contextId: string): IncrementalUnitId {
+    let epoch = this.epochByContext.get(contextId);
+    if (epoch === undefined) {
+      epoch = ++this.turnEpochCounter;
+      this.epochByContext.set(contextId, epoch);
+    }
+    return { contextId, iuId: `${contextId}#assistant`, epoch };
   }
 
   private discardDraft(): void {
     const draft = this.speculativeDraft;
     if (!draft) return;
     this.speculativeDraft = null;
-    if (!draft.hold.promoted) draft.controller.abort();
+    const committed = this.iuLedger.get(draft.id)?.state === "committed";
+    if (!committed) {
+      this.metric(draft.contextId, "speculative.draft_discarded");
+      this.iuLedger.revoke(draft.id);
+      draft.controller.abort();
+    }
+  }
+
+  private metric(contextId: string, name: string, value = "1"): void {
+    this.bus?.push(Route.Background, {
+      kind: "metric.conversation",
+      contextId,
+      timestampMs: Date.now(),
+      name,
+      value,
+    });
   }
 
   private async processTurn(
@@ -258,6 +339,7 @@ export class ReasoningBridge implements VoicePlugin {
     contextId: string,
     hold?: SpeculativeHold,
     presetController?: AbortController,
+    iuId?: IncrementalUnitId,
   ): Promise<void> {
     if (!this.bus) return;
 
@@ -268,21 +350,27 @@ export class ReasoningBridge implements VoicePlugin {
     this.activeGeneration?.controller.abort();
     const controller = presetController ?? new AbortController();
     this.activeGeneration = { contextId, controller };
+    const aid = this.assistantIuIdFor(contextId);
+    this.iuLedger.add({ id: aid, kind: "assistant_response", state: "hypothesized" });
     const signal = controller.signal;
 
     // R2: while a speculative hold is unpromoted, every push/mutation buffers.
     // Packets are constructed eagerly (their timestamps are event time); only
     // delivery is deferred. Promotion replays in order, then later effects run live.
+    const isBuffering = (): boolean =>
+      hold !== undefined &&
+      iuId !== undefined &&
+      this.iuLedger.get(iuId)?.state !== "committed";
     const push = <T extends Parameters<PipelineBus["push"]>[1]>(route: Route, packet: T): void => {
-      if (hold && !hold.promoted) {
-        if ((packet as { kind?: string }).kind === "llm.error") hold.failed = true;
-        hold.buffered.push(() => this.bus?.push(route, packet));
+      if (isBuffering()) {
+        if ((packet as { kind?: string }).kind === "llm.error" && iuId) this.iuLedger.revoke(iuId);
+        hold!.buffered.push(() => this.bus?.push(route, packet));
         return;
       }
       this.bus?.push(route, packet);
     };
     const defer = (fn: () => void): void => {
-      if (hold && !hold.promoted) hold.buffered.push(fn);
+      if (isBuffering()) hold!.buffered.push(fn);
       else fn();
     };
 
@@ -290,6 +378,20 @@ export class ReasoningBridge implements VoicePlugin {
     let emittedDelta = false;
     let committed = false;
     let grounded = false;
+    let passStartedMs = 0;
+    let passTtftRecorded = false;
+    const recordPassTtft = (): void => {
+      if (passTtftRecorded) return;
+      passTtftRecorded = true;
+      const firstOutputMs = Date.now();
+      push(Route.Main, {
+        kind: "metric.conversation",
+        contextId,
+        timestampMs: firstOutputMs,
+        name: "llm.pass_ttft_ms",
+        value: String(firstOutputMs - passStartedMs),
+      });
+    };
 
     // 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
@@ -305,6 +407,15 @@ export class ReasoningBridge implements VoicePlugin {
     try {
       for (let attempt = 1; attempt <= this.retryConfig.maxAttempts; attempt += 1) {
         grounded = false;
+        passStartedMs = Date.now();
+        passTtftRecorded = false;
+        push(Route.Main, {
+          kind: "metric.conversation",
+          contextId,
+          timestampMs: passStartedMs,
+          name: "llm.call_started",
+          value: "1",
+        });
         try {
           // Drafts never consume a suspended-run pointer: takePending mutates the
           // store, and a retracted draft would silently lose the resume.
@@ -324,6 +435,7 @@ export class ReasoningBridge implements VoicePlugin {
               case "text-delta":
                 reply += part.text;
                 emittedDelta = true;
+                recordPassTtft();
                 push(Route.Main, {
                   kind: "llm.delta",
                   contextId,
@@ -332,6 +444,7 @@ export class ReasoningBridge implements VoicePlugin {
                 });
                 break;
               case "tool-call":
+                recordPassTtft();
                 push(Route.Main, {
                   kind: "llm.tool_call",
                   contextId,
@@ -351,7 +464,64 @@ export class ReasoningBridge implements VoicePlugin {
                   toolName: part.toolName,
                   result: part.result,
                 });
+                passStartedMs = Date.now();
+                passTtftRecorded = false;
+                push(Route.Main, {
+                  kind: "metric.conversation",
+                  contextId,
+                  timestampMs: passStartedMs,
+                  name: "llm.call_started",
+                  value: "1",
+                });
                 break;
+              case "control":
+                push(Route.Background, {
+                  kind: "delegate.result",
+                  contextId,
+                  timestampMs: Date.now(),
+                  query: userText,
+                  answer: reply,
+                  durationMs: Date.now() - queryStartedMs,
+                  grounded,
+                  control: {
+                    name: part.name,
+                    payload: part.payload,
+                  },
+                });
+                break;
+              case "blocked": {
+                if (signal.aborted) return;
+                const safeMessage = part.userFacingMessage;
+                const blockedMs = Date.now();
+                push(Route.Main, {
+                  kind: "llm.delta",
+                  contextId,
+                  timestampMs: blockedMs,
+                  text: safeMessage,
+                });
+                push(Route.Main, {
+                  kind: "llm.done",
+                  contextId,
+                  timestampMs: blockedMs,
+                  text: safeMessage,
+                });
+                push(Route.Background, {
+                  kind: "delegate.result",
+                  contextId,
+                  timestampMs: blockedMs,
+                  query: userText,
+                  answer: safeMessage,
+                  durationMs: blockedMs - queryStartedMs,
+                  grounded,
+                  blocked: {
+                    userFacingMessage: safeMessage,
+                    payload: part.payload,
+                  },
+                });
+                defer(() => this.rememberTurn(userText, safeMessage, contextId));
+                committed = true;
+                return;
+              }
               case "error":
                 throw part.cause;
               case "finish":
@@ -362,6 +532,18 @@ export class ReasoningBridge implements VoicePlugin {
                   name: "llm.finish_reason",
                   value: part.reason,
                 });
+                // Record billable token usage — the field the bridge used to drop.
+                // A turn with tool calls produces several finish parts; the session
+                // accumulator sums them, so emit per-finish rather than once per turn.
+                if (part.usage) {
+                  push(Route.Background, {
+                    kind: "usage.recorded",
+                    contextId,
+                    timestampMs: Date.now(),
+                    stage: "llm",
+                    ...part.usage,
+                  });
+                }
                 finishReason = part.reason;
                 break;
               case "suspended": {
@@ -393,8 +575,8 @@ export class ReasoningBridge implements VoicePlugin {
                 if (this.opts.runStore) {
                   const store = this.opts.runStore;
                   const runId = part.runId;
-                  if (hold && !hold.promoted) {
-                    hold.buffered.push(() => void Promise.resolve(store.save(contextId, runId)).catch(() => undefined));
+                  if (isBuffering()) {
+                    hold!.buffered.push(() => void Promise.resolve(store.save(contextId, runId)).catch(() => undefined));
                   } else {
                     await Promise.resolve(store.save(contextId, runId));
                   }
@@ -506,6 +688,7 @@ export class ReasoningBridge implements VoicePlugin {
     this.assistantMsgByContext.clear();
     this.wordTimestampsByContext.clear();
     this.playedOutMsByContext.clear();
+    this.transientContextMessages.clear();
     this.bus = null;
   }
 
@@ -513,6 +696,7 @@ export class ReasoningBridge implements VoicePlugin {
     const assistantMsg = { role: "assistant" as const, content: assistantText };
     this.history.push({ role: "user", content: userText }, assistantMsg);
     this.assistantMsgByContext.set(contextId, assistantMsg);
+    this.iuLedger.commit(this.assistantIuIdFor(contextId));
     this.trimHistory();
     this.persistHistory();
   }
@@ -523,7 +707,14 @@ export class ReasoningBridge implements VoicePlugin {
     const sessionId = this.opts.sessionId;
     if (!store || !sessionId) return;
     try {
-      void Promise.resolve(store.save(sessionId, this.history.map((message) => ({ ...message })))).catch(
+      void Promise.resolve(
+        store.save(
+          sessionId,
+          this.history
+            .filter((message) => !this.transientContextMessages.has(message as { role: "system"; content: string }))
+            .map((message) => ({ ...message })),
+        ),
+      ).catch(
         () => undefined,
       );
     } catch {
@@ -558,6 +749,15 @@ export class ReasoningBridge implements VoicePlugin {
    */
   private commitInterruptedHistory(contextId: string): void {
     const spoken = this.computeSpokenPrefix(contextId);
+    const aid = this.assistantIuIdFor(contextId);
+    const ms = this.playedOutMsByContext.get(contextId);
+    const prefix = { chars: spoken.length, ms };
+    const assistantIu = this.iuLedger.get(aid);
+    if (assistantIu?.state === "hypothesized") {
+      this.iuLedger.commit(aid, prefix);
+    } else if (assistantIu?.state === "committed") {
+      assistantIu.committedPrefix = prefix;
+    }
     const existing = this.assistantMsgByContext.get(contextId);
     if (existing) {
       if (spoken) {
@@ -594,9 +794,16 @@ export class ReasoningBridge implements VoicePlugin {
     for (const [ctx, msg] of this.assistantMsgByContext) {
       if (!this.history.includes(msg)) this.clearTurnState(ctx);
     }
+    for (const message of this.transientContextMessages) {
+      if (!this.history.includes(message)) this.transientContextMessages.delete(message);
+    }
   }
 
   private clearTurnState(contextId: string): void {
+    const aid = this.assistantIuIdFor(contextId);
+    if (this.iuLedger.get(aid)?.state === "hypothesized") {
+      this.iuLedger.revoke(aid);
+    }
     this.spokenByContext.delete(contextId);
     this.turnUserText.delete(contextId);
     this.assistantMsgByContext.delete(contextId);