@kuralle-syrinx/core 4.2.0 → 4.4.0

package/src/pricing.ts

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: MIT
+//
+// Versioned price catalog: usage.recorded quantities → USD.
+// Unknown provider/model keys yield unpriced (never silent 0 for real providers).
+// Declared local/self-hosted models are explicitly zero-cost.
+
+import type { UsageRecordedPacket } from "./packets.js";
+
+export interface SttPrice {
+  readonly usdPerAudioSecond: number;
+}
+
+export interface LlmPrice {
+  readonly usdPer1MInputTokens: number;
+  readonly usdPer1MOutputTokens: number;
+  readonly usdPer1MCachedInputTokens?: number;
+}
+
+export interface TtsPrice {
+  readonly usdPer1MCharacters: number;
+}
+
+export interface PriceCatalog {
+  readonly source: string;
+  readonly version: string;
+  /** Keys: `provider/model` (e.g. `deepgram/nova-3`). */
+  readonly stt: Readonly<Record<string, SttPrice>>;
+  readonly llm: Readonly<Record<string, LlmPrice>>;
+  readonly tts: Readonly<Record<string, TtsPrice>>;
+}
+
+export type CostResult =
+  | { readonly usd: number; readonly unpriced?: undefined }
+  | { readonly usd: null; readonly unpriced: true };
+
+function catalogKey(provider: string | undefined, model: string | undefined): string | null {
+  if (!provider || !model) return null;
+  return `${provider}/${model}`;
+}
+
+/**
+ * Public list prices stamped into DEFAULT_PRICE_CATALOG.source.
+ * STT $/audio-second from $/min ÷ 60. TTS is $/1M characters. LLM is $/1M tokens.
+ */
+export const DEFAULT_PRICE_CATALOG: PriceCatalog = {
+  source:
+    "voice-prices@3 | deepgram.com/pricing PAYG Nova-3 streaming monolingual $0.0077/min → $0.000128333/s; " +
+    "deepgram.com/pricing Aura-2 TTS $0.030/1k chars → $30/1M; " +
+    "cartesia.ai/pricing + docs.cartesia.ai/pricing ~1 credit/char, PAYG ~$50/1M chars (cloudtalk.io cartesia-pricing 2026); " +
+    "openai tts-1 $15/1M chars (openai.com api pricing); gpt-4o-mini-tts text $0.60/1M (community/azure listed text input rate); " +
+    "openai GPT-4.1-mini $0.40/$1.60 per 1M in/out (developers.openai.com/api/docs/pricing; Azure GPT-4.1-mini-2025-04-14 Global); " +
+    "cloud.google.com/speech-to-text/pricing V2 standard recognition $0.016/min → $0.000266667/s (latest_long); " +
+    "ai.google.dev/pricing Gemini 2.5 Flash TTS preview text $0.50/1M chars (Gemini API TTS text input rate, 2026); " +
+    "elevenlabs.io/pricing/api Flash/Turbo TTS $0.05/1k chars → $50/1M; Multilingual v2/v3 $0.10/1k → $100/1M; " +
+    "Scribe v2 Realtime $0.39/hour → $0.000108333/s; " +
+    "grok/stt + grok/* TTS + epsilon/epsilon-tts intentionally ABSENT (no public list price → costOf unpriced, never silent $0)",
+  version: "3",
+  stt: {
+    "deepgram/nova-3": { usdPerAudioSecond: 0.0077 / 60 },
+    "deepgram/nova-2": { usdPerAudioSecond: 0.0077 / 60 },
+    "deepgram/flux-general-en": { usdPerAudioSecond: 0.0077 / 60 },
+    // Google Cloud Speech-to-Text V2 standard streaming recognition list rate.
+    "google/latest_long": { usdPerAudioSecond: 0.016 / 60 },
+    "google/latest_short": { usdPerAudioSecond: 0.016 / 60 },
+    "google/chirp_2": { usdPerAudioSecond: 0.016 / 60 },
+    // ElevenLabs Scribe v2 Realtime — public list $0.39/hour.
+    "elevenlabs/scribe_v2_realtime": { usdPerAudioSecond: 0.39 / 3600 },
+    "local/whisper": { usdPerAudioSecond: 0 },
+    // grok/stt: no public list price — omit so costOf → unpriced
+  },
+  llm: {
+    "openai/gpt-4.1-mini": {
+      usdPer1MInputTokens: 0.4,
+      usdPer1MOutputTokens: 1.6,
+      usdPer1MCachedInputTokens: 0.1,
+    },
+    "local/llm": {
+      usdPer1MInputTokens: 0,
+      usdPer1MOutputTokens: 0,
+    },
+  },
+  tts: {
+    "cartesia/sonic-3": { usdPer1MCharacters: 50 },
+    "openai/gpt-4o-mini-tts": { usdPer1MCharacters: 0.6 },
+    "openai/tts-1": { usdPer1MCharacters: 15 },
+    "deepgram/aura-2-thalia-en": { usdPer1MCharacters: 30 },
+    // Gemini TTS preview models — Gemini API TTS text input list rate.
+    "gemini/gemini-3.1-flash-tts-preview": { usdPer1MCharacters: 0.5 },
+    "gemini/gemini-2.5-flash-preview-tts": { usdPer1MCharacters: 0.5 },
+    "gemini/gemini-2.5-pro-preview-tts": { usdPer1MCharacters: 0.5 },
+    // ElevenLabs public list — Flash/Turbo $0.05/1k, Multilingual $0.10/1k.
+    "elevenlabs/eleven_flash_v2_5": { usdPer1MCharacters: 50 },
+    "elevenlabs/eleven_flash_v2": { usdPer1MCharacters: 50 },
+    "elevenlabs/eleven_turbo_v2_5": { usdPer1MCharacters: 50 },
+    "elevenlabs/eleven_turbo_v2": { usdPer1MCharacters: 50 },
+    "elevenlabs/eleven_multilingual_v2": { usdPer1MCharacters: 100 },
+    "local/tts": { usdPer1MCharacters: 0 },
+    // grok/* voice keys + epsilon/epsilon-tts: no public list — omit → unpriced
+  },
+};
+
+export function costOf(usage: UsageRecordedPacket, catalog: PriceCatalog): CostResult {
+  const key = catalogKey(usage.provider, usage.model);
+  if (!key) return { usd: null, unpriced: true };
+
+  switch (usage.stage) {
+    case "stt": {
+      const price = catalog.stt[key];
+      if (!price) return { usd: null, unpriced: true };
+      const seconds = usage.audioSeconds ?? 0;
+      return { usd: seconds * price.usdPerAudioSecond };
+    }
+    case "tts": {
+      const price = catalog.tts[key];
+      if (!price) return { usd: null, unpriced: true };
+      const characters = usage.characters ?? 0;
+      return { usd: (characters / 1_000_000) * price.usdPer1MCharacters };
+    }
+    case "llm": {
+      const price = catalog.llm[key];
+      if (!price) return { usd: null, unpriced: true };
+      const input = usage.inputTokens ?? 0;
+      const output = usage.outputTokens ?? 0;
+      const cached = usage.cachedInputTokens ?? 0;
+      const cachedRate = price.usdPer1MCachedInputTokens ?? price.usdPer1MInputTokens;
+      // Prefer charging cached tokens at the cached rate when present; non-cached input is the remainder.
+      const nonCachedInput = Math.max(0, input - cached);
+      const usd =
+        (nonCachedInput / 1_000_000) * price.usdPer1MInputTokens +
+        (cached / 1_000_000) * cachedRate +
+        (output / 1_000_000) * price.usdPer1MOutputTokens;
+      return { usd };
+    }
+    default:
+      return { usd: null, unpriced: true };
+  }
+}

package/src/primary-speaker-gate.ts

@@ -19,12 +19,23 @@ export interface PrimarySpeakerGateConfig {
   readonly enabled?: boolean;
   readonly similarityThreshold?: number;
   readonly echoDominanceMargin?: number;
+  readonly onDecision?: (decision: PrimarySpeakerGateDecision) => void;
+}
+
+export interface PrimarySpeakerGateDecision {
+  readonly contextId: string;
+  readonly signal: "primary_speaker" | "echo_rejected";
+  readonly accepted: boolean;
+  readonly frameCount: number;
+  readonly primaryHits: number;
+  readonly echoRejectedFrames: number;
 }
 
 export class PrimarySpeakerGate {
   private readonly enabled: boolean;
   private readonly similarityThreshold: number;
   private readonly echoDominanceMargin: number;
+  private readonly onDecision?: PrimarySpeakerGateConfig["onDecision"];
   private profile: SpeakerFingerprint | null = null;
   private enrollFrames: SpeakerFingerprint[] = [];
   private bargeInFrames: SpeakerFingerprint[] = [];
@@ -34,6 +45,7 @@ export class PrimarySpeakerGate {
     this.enabled = config.enabled !== false;
     this.similarityThreshold = config.similarityThreshold ?? 0.72;
     this.echoDominanceMargin = config.echoDominanceMargin ?? 0.12;
+    this.onDecision = config.onDecision;
   }
 
   isEnabled(): boolean {
@@ -73,22 +85,30 @@ export class PrimarySpeakerGate {
     this.assistantProfile = frame;
   }
 
-  shouldCommitBargeIn(): boolean {
+  shouldCommitBargeIn(contextId = ""): boolean {
     if (!this.enabled || this.profile === null) return true;
     if (this.bargeInFrames.length === 0) return false;
 
     let primaryHits = 0;
+    let echoRejectedFrames = 0;
     for (const frame of this.bargeInFrames) {
       const primarySim = fingerprintSimilarity(frame, this.profile);
       if (this.assistantProfile !== null) {
         const echoSim = fingerprintSimilarity(frame, this.assistantProfile);
-        if (echoSim >= primarySim + this.echoDominanceMargin) continue;
+        if (echoSim >= primarySim + this.echoDominanceMargin) {
+          echoRejectedFrames += 1;
+          continue;
+        }
       }
       if (primarySim >= this.similarityThreshold) primaryHits += 1;
     }
 
     const required = Math.max(1, Math.ceil(this.bargeInFrames.length * 0.45));
-    return primaryHits >= required;
+    const accepted = primaryHits >= required;
+    const decision = { contextId, accepted, frameCount: this.bargeInFrames.length, primaryHits, echoRejectedFrames };
+    if (echoRejectedFrames > 0) this.onDecision?.({ signal: "echo_rejected", ...decision });
+    this.onDecision?.({ signal: "primary_speaker", ...decision });
+    return accepted;
   }
 
   resetBargeInWindow(): void {

package/src/reasoner.ts

@@ -8,6 +8,9 @@
 
 /** A reasoning backend reduced to one normalized pull-stream per turn. */
 export interface Reasoner {
+  /** Add transient steering context consumed by the next turn, when supported. */
+  injectContext?(text: string): void;
+
   /**
    * Drive one reasoning turn. The returned async-iterable IS the response.
    * Cancellation (barge-in) is via `turn.signal` (abort) — the adapter forwards
@@ -50,11 +53,35 @@ export type ReasoningPart =
   | { readonly type: "text-delta"; readonly text: string }
   | { readonly type: "tool-call"; readonly toolId: string; readonly toolName: string; readonly args: Record<string, unknown> }
   | { readonly type: "tool-result"; readonly toolId: string; readonly toolName: string; readonly result: string }
+  | { readonly type: "control"; readonly name: string; readonly payload: unknown }
+  | { readonly type: "blocked"; readonly userFacingMessage: string; readonly payload?: unknown }
   // Human-in-the-loop pause (step 3). ALWAYS the terminal part for the turn.
   | { readonly type: "suspended"; readonly runId: string; readonly toolId?: string; readonly prompt?: string; readonly payload: unknown }
   // (B1) Error/abort the backend surfaced. The bridge treats `error` like today's
   // thrown TextStreamPart `error`/`tool-error`/`finish-step(error)`: it drives the
   // retry/`llm.error` path. `recoverable` mirrors `categorizeLlmError`. ALWAYS terminal.
   | { readonly type: "error"; readonly cause: Error; readonly recoverable: boolean }
-  | { readonly type: "finish"; readonly reason: "stop" | "tool" | "length"; readonly text: string };
+  | {
+      readonly type: "finish";
+      readonly reason: "stop" | "tool" | "length";
+      readonly text: string;
+      /**
+       * Billable token usage for this turn, when the backend reports it. Optional —
+       * a reasoner that cannot report usage omits it, and the metering path treats a
+       * missing field as "unknown", never zero. Consumed into `usage.recorded`.
+       */
+      readonly usage?: ReasonerUsage;
+    };
 
+/** Token usage a reasoner may attach to its terminal `finish` part. */
+export interface ReasonerUsage {
+  /** Provider slug (e.g. "openai"), for low-cardinality cost attribution. */
+  readonly provider?: string;
+  /** Model id (e.g. "gpt-4.1-mini"). Without this, spend cannot be attributed to a model. */
+  readonly model?: string;
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly totalTokens?: number;
+  readonly cachedInputTokens?: number;
+  readonly reasoningTokens?: number;
+}

package/src/spend-cap.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+//
+// Pure spend accumulator + policy. Observe (record) and control (check) are
+// separated so the same usage packet is never double-counted by the guard.
+
+import type { UsageRecordedPacket } from "./packets.js";
+import { costOf, DEFAULT_PRICE_CATALOG, type PriceCatalog } from "./pricing.js";
+
+export interface SpendCapConfig {
+  readonly maxUsd: number;
+  readonly catalog?: PriceCatalog;
+}
+
+export interface SpendCapCheck {
+  readonly exceeded: boolean;
+  readonly spentUsd: number;
+}
+
+/**
+ * Accumulates priced `usage.recorded` into session spend and reports whether a
+ * configured USD cap has been breached. Does not call providers; the session
+ * layer decides refuse/fallback from `check()`.
+ */
+export class SpendCapGuard {
+  private readonly maxUsd: number;
+  private readonly catalog: PriceCatalog;
+  private spentUsd = 0;
+  private exceeded = false;
+
+  constructor(cfg: SpendCapConfig) {
+    if (!Number.isFinite(cfg.maxUsd) || cfg.maxUsd < 0) {
+      throw new Error(`SpendCapGuard maxUsd must be a non-negative finite number, got ${String(cfg.maxUsd)}`);
+    }
+    this.maxUsd = cfg.maxUsd;
+    this.catalog = cfg.catalog ?? DEFAULT_PRICE_CATALOG;
+  }
+
+  /** Observe one usage packet. Unpriced usage does not change spentUsd. */
+  record(usage: UsageRecordedPacket): void {
+    const result = costOf(usage, this.catalog);
+    if (result.usd === null) return;
+    this.spentUsd += result.usd;
+    if (this.spentUsd > this.maxUsd) {
+      this.exceeded = true;
+    }
+  }
+
+  /** Read-only policy view — never mutates spend. */
+  check(): SpendCapCheck {
+    return { exceeded: this.exceeded, spentUsd: this.spentUsd };
+  }
+}

package/src/turn-arbiter.ts

@@ -59,18 +59,39 @@ export function isBackchannel(text: string): boolean {
   return BACKCHANNELS.has(norm);
 }
 
+export function isAcknowledgement(text: string, phrases: readonly string[]): boolean {
+  const norm = text
+    .toLowerCase()
+    .replace(/[^a-z\s'-]/g, "")
+    .trim()
+    .replace(/\s+/g, " ");
+  if (!norm) return false;
+  return phrases.some((p) => {
+    const pNorm = p
+      .toLowerCase()
+      .replace(/[^a-z\s'-]/g, "")
+      .trim()
+      .replace(/\s+/g, " ");
+    return pNorm === norm;
+  });
+}
+
 export interface TurnArbiterDeps {
   readonly bus: PipelineBus;
   readonly primarySpeakerGate: PrimarySpeakerGate;
   readonly ttsPlayout: TtsPlayoutClock;
   readonly minInterruptionMs: number;
   readonly onInterrupt?: (interruptedContextId: string, source: "vad") => void;
+  /** When true, emit `interaction.duck` while evaluating a barge-in during active TTS,
+   *  and `interaction.resume` if the pending window resolves without an interrupt. */
+  readonly pauseThenResolveBargeIn?: boolean;
 }
 
 export class TurnArbiter {
   private turnInterruption: TurnInterruptionState = { kind: "idle" };
   private latestInterimText = "";
   private latestInterimConfidence: number | null = null;
+  private ducked = false;
 
   constructor(private readonly deps: TurnArbiterDeps) {}
 
@@ -130,7 +151,7 @@ export class TurnArbiter {
         if (
           this.deps.primarySpeakerGate.isEnabled() &&
           this.deps.primarySpeakerGate.hasProfile() &&
-          !this.deps.primarySpeakerGate.shouldCommitBargeIn()
+          !this.deps.primarySpeakerGate.shouldCommitBargeIn(pending.userContextId)
         ) {
           this.suppress(pending, "interrupt.suppressed_non_primary", durationMs);
         } else {
@@ -166,6 +187,7 @@ export class TurnArbiter {
   commitClientInterrupt(interruptedContextId: string): void {
     if (!this.deps.ttsPlayout.isActive(interruptedContextId)) return;
     this.turnInterruption = { kind: "idle" };
+    this.ducked = false;
     this.deps.primarySpeakerGate.resetBargeInWindow();
     this.deps.bus.push(Route.Background, make.metric(interruptedContextId, "interrupt.committed_after_ms", "0"));
     this.deps.bus.push(Route.Background, make.metric(interruptedContextId, "vaqi.interruption", "1"));
@@ -177,6 +199,7 @@ export class TurnArbiter {
     this.turnInterruption = { kind: "idle" };
     this.latestInterimText = "";
     this.latestInterimConfidence = null;
+    this.ducked = false;
   }
 
   private pendingFor(userContextId: string): PendingTurnInterruption | null {
@@ -203,6 +226,10 @@ export class TurnArbiter {
       firstSpeechMs: pkt.timestampMs,
       awaitingAudio,
     };
+    if (this.deps.pauseThenResolveBargeIn && this.deps.ttsPlayout.isActive(interruptedContextId) && !this.ducked) {
+      this.deps.bus.push(Route.Main, make.interactionDuck(interruptedContextId, pkt.timestampMs));
+      this.ducked = true;
+    }
   }
 
   private setAwaitingAudio(awaitingAudio: boolean): void {
@@ -222,7 +249,7 @@ export class TurnArbiter {
     if (nowMs - pending.firstSpeechMs < this.deps.minInterruptionMs) return;
 
     const gate = this.deps.primarySpeakerGate;
-    if (gate.isEnabled() && gate.hasProfile() && !gate.shouldCommitBargeIn()) {
+    if (gate.isEnabled() && gate.hasProfile() && !gate.shouldCommitBargeIn(pending.userContextId)) {
       this.suppress(pending, "interrupt.suppressed_non_primary", nowMs - pending.firstSpeechMs);
       return;
     }
@@ -238,6 +265,7 @@ export class TurnArbiter {
     }
     this.turnInterruption = { kind: "idle" };
     gate.resetBargeInWindow();
+    this.ducked = false;
 
     const { bus, ttsPlayout } = this.deps;
     if (!ttsPlayout.isActive(pending.interruptedContextId)) {
@@ -281,6 +309,10 @@ export class TurnArbiter {
     } else {
       this.turnInterruption = { kind: "idle" };
       this.deps.primarySpeakerGate.resetBargeInWindow();
+      if (this.ducked) {
+        this.deps.bus.push(Route.Main, make.interactionResume(pending.interruptedContextId, Date.now()));
+        this.ducked = false;
+      }
     }
     this.deps.bus.push(
       Route.Background,

package/src/voice-agent-session-util.ts

@@ -81,6 +81,8 @@ export class VoiceSessionWatchdogs {
   private readonly scheduler: Scheduler;
   private sttForceFinalizeScheduled = false;
   private pendingSttContextId = "";
+  /** Contexts whose STT the force-finalize watchdog has already fired on this turn. */
+  private readonly forceFinalizedContexts = new Set<string>();
   private vaqiMissedResponseScheduled = false;
   private vaqiMissedResponseContextId = "";
   private vaqiMissedResponseStartMs = 0;
@@ -98,6 +100,7 @@ export class VoiceSessionWatchdogs {
     this.clearVaqiMissedResponseTimer();
     this.clearTtsStallTimer();
     this.clearInputCadenceWatchdog();
+    this.forceFinalizedContexts.clear();
   }
 
   scheduleSttForceFinalize(contextId: string): void {
@@ -109,11 +112,26 @@ export class VoiceSessionWatchdogs {
     this.sttForceFinalizeScheduled = true;
     this.scheduler.schedule("voice.watchdog.stt_force_finalize", this.deps.sttForceFinalizeTimeoutMs, () => {
       this.sttForceFinalizeScheduled = false;
+      this.forceFinalizedContexts.add(contextId);
+      // Broadcast the decision on the bus: the completing eos may come from the STT
+      // plugin (which cannot know the watchdog fired), so the metrics tracker reads
+      // this mark to label the turn rather than each emitter re-deriving it.
+      this.deps.bus.push(Route.Background, make.metric(contextId, "stt.force_finalized", "1"));
       const plugin = findForceFinalizableSttPlugin(this.deps.plugins);
       plugin?.forceFinalize(contextId);
     });
   }
 
+  /** True when the force-finalize watchdog has already fired for this context this turn. */
+  wasForceFinalized(contextId: string): boolean {
+    return this.forceFinalizedContexts.has(contextId);
+  }
+
+  /** Retire the flag once the turn has completed (read by the emitter + metrics tracker). */
+  clearForceFinalized(contextId: string): void {
+    this.forceFinalizedContexts.delete(contextId);
+  }
+
   clearSttForceFinalizeIfContext(contextId: string): void {
     if (this.pendingSttContextId === contextId) {
       this.clearSttForceFinalizeTimer();