@kuralle-syrinx/core 4.1.0 → 4.3.0

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,17 +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) {}
 
@@ -92,7 +114,7 @@ export class TurnArbiter {
         return;
       }
       bus.push(Route.Background, make.metric(interruptedContextId, "vaqi.interruption", "1"));
-      this.emitInterruptDetected(interruptedContextId);
+      this.decideInterrupt(interruptedContextId);
       return;
     }
 
@@ -129,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 {
@@ -165,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"));
@@ -176,6 +199,7 @@ export class TurnArbiter {
     this.turnInterruption = { kind: "idle" };
     this.latestInterimText = "";
     this.latestInterimConfidence = null;
+    this.ducked = false;
   }
 
   private pendingFor(userContextId: string): PendingTurnInterruption | null {
@@ -202,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 {
@@ -221,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;
     }
@@ -237,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)) {
@@ -256,11 +285,19 @@ export class TurnArbiter {
       Route.Background,
       make.metric(pending.interruptedContextId, "interrupt.latency_ms", String(sustainedMs)),
     );
-    this.emitInterruptDetected(pending.interruptedContextId);
+    this.decideInterrupt(pending.interruptedContextId);
     this.latestInterimText = "";
     this.latestInterimConfidence = null;
   }
 
+  private decideInterrupt(interruptedContextId: string): void {
+    if (this.deps.onInterrupt) {
+      this.deps.onInterrupt(interruptedContextId, "vad");
+      return;
+    }
+    this.emitInterruptDetected(interruptedContextId);
+  }
+
   private suppress(
     pending: PendingTurnInterruption,
     metricName: string,
@@ -272,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,