@kuralle-syrinx/aisdk 4.2.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/aisdk",
-  "version": "4.2.0",
+  "version": "4.4.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": [
@@ -28,11 +28,11 @@
     "@ai-sdk/openai": "^3.0.67",
     "ai": "^6.0.0",
     "zod": "^4.1.8",
-    "@kuralle-syrinx/core": "4.2.0"
+    "@kuralle-syrinx/core": "4.4.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

@@ -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: {
@@ -127,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;
     } = {},
@@ -136,6 +155,12 @@ 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) => {
@@ -188,6 +213,7 @@ export class ReasoningBridge implements VoicePlugin {
         ) {
           this.iuLedger.commit(draft.id);
           this.speculativeDraft = null;
+          this.metric(eos.contextId, "speculative.draft_promoted");
           for (const flush of draft.hold.buffered.splice(0)) flush();
           return;
         }
@@ -259,6 +285,7 @@ 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();
@@ -291,11 +318,22 @@ export class ReasoningBridge implements VoicePlugin {
     this.speculativeDraft = null;
     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(
     userText: string,
     contextId: string,
@@ -340,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
@@ -355,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.
@@ -374,6 +435,7 @@ export class ReasoningBridge implements VoicePlugin {
               case "text-delta":
                 reply += part.text;
                 emittedDelta = true;
+                recordPassTtft();
                 push(Route.Main, {
                   kind: "llm.delta",
                   contextId,
@@ -382,6 +444,7 @@ export class ReasoningBridge implements VoicePlugin {
                 });
                 break;
               case "tool-call":
+                recordPassTtft();
                 push(Route.Main, {
                   kind: "llm.tool_call",
                   contextId,
@@ -401,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":
@@ -412,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": {
@@ -556,6 +688,7 @@ export class ReasoningBridge implements VoicePlugin {
     this.assistantMsgByContext.clear();
     this.wordTimestampsByContext.clear();
     this.playedOutMsByContext.clear();
+    this.transientContextMessages.clear();
     this.bus = null;
   }
 
@@ -574,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 {
@@ -654,6 +794,9 @@ 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 {

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

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