@kuralle-syrinx/core 4.2.0 → 4.3.0

package/src/observability-observer.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 
 import { Route, type PipelineBus } from "./pipeline-bus.js";
-import { monotonicNowMs, type MetricsExporter } from "./observability.js";
+import { monotonicNowMs, type MetricsExporter, type ObservabilityLayer } from "./observability.js";
 import type {
   TurnBoundaryKind,
   VadSpeechStartedPacket,
@@ -17,6 +17,7 @@ export interface ObservabilityDims {
   readonly provider: string;
   readonly model: string;
   readonly region: string;
+  readonly layer?: ObservabilityLayer;
 }
 
 export interface ObservabilityObserverDeps {
@@ -124,12 +125,11 @@ export class ObservabilityObserver {
 
     const dims = this.dimsFor(speechId, cancelled);
     const tags = {
-      sessionId: this.deps.sessionId,
-      speechId,
       provider: dims.provider,
       model: dims.model,
       region: dims.region,
       cancelled: dims.cancelled ? "true" : "false",
+      layer: dims.layer ?? "conversation",
     };
 
     if (boundary === "agent_started_speaking") {
@@ -179,12 +179,16 @@ export class ObservabilityObserver {
     });
   }
 
-  private dimsFor(speechId: string, cancelled: boolean): Required<ObservabilityDims> & { cancelled: boolean } {
+  private dimsFor(
+    speechId: string,
+    cancelled: boolean,
+  ): Required<ObservabilityDims> & { cancelled: boolean } {
     const stage = this.stageDims.get(speechId) ?? {};
     return {
       provider: stage.provider ?? this.deps.dims.provider,
       model: stage.model ?? this.deps.dims.model,
       region: stage.region ?? this.deps.dims.region,
+      layer: stage.layer ?? this.deps.dims.layer ?? "conversation",
       cancelled: cancelled || stage.cancelled === true,
     };
   }

package/src/observability.ts

@@ -7,6 +7,21 @@ export function monotonicNowMs(): number {
   return performance.timeOrigin + performance.now();
 }
 
+export type ObservabilityLayer = "infrastructure" | "conversation";
+
+export type TurnLocalizationVerdict = ObservabilityLayer | "none";
+
+export interface TurnLocalizationSignals {
+  readonly infrastructureBreached: boolean;
+  readonly conversationFlagged: boolean;
+}
+
+export function localizeTurn(signals: TurnLocalizationSignals): TurnLocalizationVerdict {
+  if (signals.infrastructureBreached) return "infrastructure";
+  if (signals.conversationFlagged) return "conversation";
+  return "none";
+}
+
 /** One step of a reconstructed turn timeline, with elapsed ms since the prior boundary. */
 export interface TurnTimelineStep {
   readonly boundary: TurnBoundaryEventPacket["boundary"];
@@ -46,7 +61,8 @@ export function reconstructTurnTimeline(
 }
 
 export interface MetricTags {
-  readonly [key: string]: string;
+  readonly [key: string]: string | undefined;
+  readonly layer?: ObservabilityLayer;
 }
 
 export interface SpanHandle {
@@ -56,12 +72,20 @@ export interface SpanHandle {
 /** Export seam — implementations (Prometheus/OTel) live in optional packages, NOT here. */
 export interface MetricsExporter {
   observeHistogram(name: string, valueMs: number, tags: MetricTags): void;
+  /**
+   * A monotonic count (tokens, characters, audio-seconds). Counters, not histograms:
+   * usage sums to a bill, latency distributes to a percentile — different instruments.
+   * Optional so an existing exporter that predates it still satisfies the interface;
+   * producers call it as `exporter.observeCounter?.(...)`.
+   */
+  observeCounter?(name: string, value: number, tags: MetricTags): void;
   startSpan(name: string, tags: MetricTags): SpanHandle;
 }
 
 /** Default no-op exporter (core never depends on a backend). */
 export const noopMetricsExporter: MetricsExporter = {
   observeHistogram() {},
+  observeCounter() {},
   startSpan() {
     return { end() {} };
   },
@@ -70,12 +94,17 @@ export const noopMetricsExporter: MetricsExporter = {
 /** In-memory exporter for tests + incident reconstruction. */
 export class InMemoryMetricsExporter implements MetricsExporter {
   readonly histograms: Array<{ name: string; valueMs: number; tags: MetricTags }> = [];
+  readonly counters: Array<{ name: string; value: number; tags: MetricTags }> = [];
   readonly spans: Array<{ name: string; tags: MetricTags; durationMs?: number }> = [];
 
   observeHistogram(name: string, valueMs: number, tags: MetricTags): void {
     this.histograms.push({ name, valueMs, tags });
   }
 
+  observeCounter(name: string, value: number, tags: MetricTags): void {
+    this.counters.push({ name, value, tags });
+  }
+
   startSpan(name: string, tags: MetricTags): SpanHandle {
     const startMs = monotonicNowMs();
     const spanIndex = this.spans.length;

package/src/packet-factories.ts

@@ -10,11 +10,18 @@
 import type { WordTiming } from "./interaction-policy.js";
 import { ErrorCategory } from "./packets.js";
 import type {
+  UsageRecordedPacket,
   ConversationMetricPacket,
+  AcousticSignalPacket,
+  AcousticSignal,
+  TurnLocalizationPacket,
   TurnBoundaryKind,
   TurnBoundaryEventPacket,
   DtmfDigit,
   DtmfReceivedPacket,
+  DtmfSendPacket,
+  CallTransferPacket,
+  CallTransferMode,
   RecordUserAudioPacket,
   RecordAssistantAudioDataPacket,
   RecordAssistantAudioTruncatePacket,
@@ -35,6 +42,7 @@ import type {
   InterruptLlmPacket,
   InterruptSttPacket,
   InjectMessagePacket,
+  SttReconfigurePacket,
   LlmDeltaPacket,
   LlmResponseDonePacket,
   ReasoningSuspendedPacket,
@@ -43,7 +51,10 @@ import type {
   StopIdleTimeoutPacket,
   ModeSwitchRequestedPacket,
   InteractionBackchannelPacket,
+  InteractionDuckPacket,
+  InteractionResumePacket,
 } from "./packets.js";
+import type { SttReconfigurePartial } from "./plugin-contract.js";
 
 const DTMF_DIGITS = new Set<DtmfDigit>(["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#"]);
 
@@ -63,6 +74,36 @@ export function dtmfReceived(
   return { kind: "dtmf.received", contextId, timestampMs, digit, provider, rawDigit };
 }
 
+const DTMF_SEND_CHARS = /^[0-9*#wW]+$/;
+
+/** Validate + build a `dtmf.send` packet. Throws on empty/invalid digit strings. */
+export function dtmfSend(contextId: string, timestampMs: number, digits: string): DtmfSendPacket {
+  if (!digits || !DTMF_SEND_CHARS.test(digits)) {
+    throw new Error(`Invalid dtmf.send digits: ${JSON.stringify(digits)} (expected [0-9*#wW]+)`);
+  }
+  return { kind: "dtmf.send", contextId, timestampMs, digits };
+}
+
+/** Build a `call.transfer` packet. */
+export function callTransfer(
+  contextId: string,
+  timestampMs: number,
+  mode: CallTransferMode,
+  target: string,
+  summary?: string,
+): CallTransferPacket {
+  const trimmed = target.trim();
+  if (!trimmed) throw new Error("call.transfer target must be a non-empty E.164 / SIP URI");
+  return {
+    kind: "call.transfer",
+    contextId,
+    timestampMs,
+    mode,
+    target: trimmed,
+    ...(summary !== undefined ? { summary } : {}),
+  };
+}
+
 export function metric(
   contextId: string,
   name: string,
@@ -72,6 +113,46 @@ export function metric(
   return { kind: "metric.conversation", contextId, timestampMs, name, value };
 }
 
+export function acousticSignal(
+  contextId: string,
+  timestampMs: number,
+  signal: AcousticSignal,
+  payload?: Readonly<Record<string, unknown>>,
+): AcousticSignalPacket {
+  return {
+    kind: "acoustic.signal",
+    contextId,
+    timestampMs,
+    signal,
+    ...(payload ? { payload } : {}),
+  };
+}
+
+export function turnLocalization(
+  contextId: string,
+  timestampMs: number,
+  value: TurnLocalizationPacket["value"],
+  infrastructureBreached: boolean,
+  conversationFlagged: boolean,
+): TurnLocalizationPacket {
+  return {
+    kind: "turn.localization",
+    contextId,
+    timestampMs,
+    value,
+    infrastructureBreached,
+    conversationFlagged,
+  };
+}
+
+export function usageRecorded(
+  contextId: string,
+  fields: Omit<UsageRecordedPacket, "kind" | "contextId" | "timestampMs">,
+  timestampMs: number = Date.now(),
+): UsageRecordedPacket {
+  return { kind: "usage.recorded", contextId, timestampMs, ...fields };
+}
+
 export function turnBoundary(
   contextId: string,
   timestampMs: number,
@@ -210,8 +291,21 @@ export function ttsError(
   return { kind: "tts.error", contextId, timestampMs, component: "tts", category, cause, isRecoverable };
 }
 
-export function injectMessage(contextId: string, timestampMs: number, text: string): InjectMessagePacket {
-  return { kind: "inject.message", contextId, timestampMs, text };
+export function injectMessage(
+  contextId: string,
+  timestampMs: number,
+  text: string,
+  mode?: InjectMessagePacket["mode"],
+): InjectMessagePacket {
+  return { kind: "inject.message", contextId, timestampMs, text, ...(mode ? { mode } : {}) };
+}
+
+export function sttReconfigure(
+  contextId: string,
+  timestampMs: number,
+  partial: SttReconfigurePartial,
+): SttReconfigurePacket {
+  return { kind: "stt.reconfigure", contextId, timestampMs, partial };
 }
 
 export function llmDelta(contextId: string, timestampMs: number, text: string): LlmDeltaPacket {
@@ -268,3 +362,17 @@ export function interactionBackchannel(
 ): InteractionBackchannelPacket {
   return { kind: "interaction.backchannel", contextId, timestampMs, cue };
 }
+
+export function interactionDuck(
+  contextId: string,
+  timestampMs: number,
+): InteractionDuckPacket {
+  return { kind: "interaction.duck", contextId, timestampMs };
+}
+
+export function interactionResume(
+  contextId: string,
+  timestampMs: number,
+): InteractionResumePacket {
+  return { kind: "interaction.resume", contextId, timestampMs };
+}

package/src/packets.ts

@@ -10,6 +10,7 @@
 //   Lifecycle:              InitStepCompleted, InitFailed, InitCompleted
 
 import type { WordTiming } from "./interaction-policy.js";
+import type { SttReconfigurePartial } from "./plugin-contract.js";
 
 // =============================================================================
 // Base Types
@@ -199,6 +200,16 @@ export interface FinalizeSttPacket extends VoicePacket {
   readonly kind: "stt.finalize";
 }
 
+/**
+ * Per-turn STT reconfigure actuation. Session routes to the stt plugin's
+ * `sttReconfigure` seam when present (warn-and-no-op otherwise).
+ * Call at a turn boundary so reconnect-based STTs do not drop mid-utterance audio.
+ */
+export interface SttReconfigurePacket extends VoicePacket {
+  readonly kind: "stt.reconfigure";
+  readonly partial: SttReconfigurePartial;
+}
+
 export interface SttErrorPacket extends VoicePacket, VoiceErrorPacket {
   readonly kind: "stt.error";
   readonly component: "stt";
@@ -280,6 +291,32 @@ export interface DtmfReceivedPacket extends VoicePacket {
   readonly rawDigit: string;
 }
 
+/**
+ * Outbound DTMF request (IVR navigation). Digits may include pause syntax
+ * `w` (0.5s) / `W` (1s). Mechanism unit-tested; live carrier decode unverified.
+ */
+export interface DtmfSendPacket extends VoicePacket {
+  readonly kind: "dtmf.send";
+  /** Digits in `[0-9*#wW]+`. */
+  readonly digits: string;
+}
+
+export type CallTransferMode = "warm" | "cold" | "sip_refer";
+
+/**
+ * Outbound call transfer. Prefer Call-Control transfer over SIP REFER where
+ * answer-rate matters (REFER drops STIR/SHAKEN attestation). Mechanism
+ * unit-tested; live transfer bridge unverified against a carrier.
+ */
+export interface CallTransferPacket extends VoicePacket {
+  readonly kind: "call.transfer";
+  readonly mode: CallTransferMode;
+  /** E.164 number or SIP URI. */
+  readonly target: string;
+  /** Warm-handoff context for the receiving agent/human (mode `"warm"`). */
+  readonly summary?: string;
+}
+
 // =============================================================================
 // LLM Pipeline Packets
 // =============================================================================
@@ -354,6 +391,14 @@ export interface DelegateResultPacket extends VoicePacket {
   readonly grounded: boolean;
   readonly toolId?: string;
   readonly toolName?: string;
+  readonly control?: {
+    readonly name: string;
+    readonly payload: unknown;
+  };
+  readonly blocked?: {
+    readonly userFacingMessage: string;
+    readonly payload?: unknown;
+  };
 }
 
 export interface ReasoningResumePacket extends VoicePacket {
@@ -480,6 +525,16 @@ export interface InteractionBackchannelPacket extends VoicePacket {
   readonly cue: string;
 }
 
+/** Signal to attenuate active TTS while a barge-in is being evaluated (pending window). */
+export interface InteractionDuckPacket extends VoicePacket {
+  readonly kind: "interaction.duck";
+}
+
+/** Signal to restore attenuated TTS when the pending window resolved without an interrupt. */
+export interface InteractionResumePacket extends VoicePacket {
+  readonly kind: "interaction.resume";
+}
+
 // =============================================================================
 // Behavior Packets
 // =============================================================================
@@ -496,6 +551,8 @@ export interface StopIdleTimeoutPacket extends VoicePacket {
 export interface InjectMessagePacket extends VoicePacket {
   readonly kind: "inject.message";
   readonly text: string;
+  /** Defaults to speak for compatibility with existing inject.message producers. */
+  readonly mode?: "speak" | "context";
 }
 
 export interface DisconnectRequestedPacket extends VoicePacket {
@@ -537,6 +594,58 @@ export interface ConversationMetricPacket extends VoicePacket {
   readonly value: string;
 }
 
+export type AcousticSignal =
+  | "prosody"
+  | "backchannel"
+  | "interruption"
+  | "primary_speaker"
+  | "echo_rejected"
+  | "cadence";
+
+export interface AcousticSignalPacket extends VoicePacket {
+  readonly kind: "acoustic.signal";
+  readonly signal: AcousticSignal;
+  readonly payload?: Readonly<Record<string, unknown>>;
+}
+
+export type TurnLocalizationVerdict = "infrastructure" | "conversation" | "none";
+
+export interface TurnLocalizationPacket extends VoicePacket {
+  readonly kind: "turn.localization";
+  readonly value: TurnLocalizationVerdict;
+  readonly infrastructureBreached: boolean;
+  readonly conversationFlagged: boolean;
+}
+
+/** The pipeline stage that consumed resources. Billing planes group cost by this. */
+export type UsageStage = "llm" | "stt" | "tts";
+
+/**
+ * One unit of billable resource consumption, recorded where it happens.
+ *
+ * The full shape is defined up front — LLM tokens, STT audio-seconds, TTS characters —
+ * so a producer added later needs no schema change; only the LLM producer is wired today
+ * (the AI SDK finish part carries usage the bridge had been dropping). `VoiceAgentSession`
+ * accumulates these into an end-of-session `session.usage` manifest and exports them as
+ * counters — the load-bearing seam for metering, spend caps, and eventual per-tenant billing.
+ * Fields not applicable to a stage are simply absent (tokens on STT/TTS, seconds on LLM).
+ */
+export interface UsageRecordedPacket extends VoicePacket {
+  readonly kind: "usage.recorded";
+  readonly stage: UsageStage;
+  readonly provider?: string;
+  readonly model?: string;
+  // LLM
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly totalTokens?: number;
+  readonly cachedInputTokens?: number;
+  readonly reasoningTokens?: number;
+  // STT / TTS
+  readonly audioSeconds?: number;
+  readonly characters?: number;
+}
+
 export type TurnBoundaryKind =
   | "user_started_speaking"
   | "user_stopped_speaking"
@@ -583,6 +692,7 @@ export type InputPacket =
   | SttPartialPacket
   | SttResultPacket
   | FinalizeSttPacket
+  | SttReconfigurePacket
   | SttErrorPacket
   | EndOfSpeechAudioPacket
   | EndOfSpeechPacket
@@ -628,7 +738,12 @@ export type AnyErrorPacket =
   | InitializationFailedPacket;
 
 /** Observability packets (Background route). */
-export type ObservabilityPacket = ConversationMetricPacket | TurnBoundaryEventPacket;
+export type ObservabilityPacket =
+  | ConversationMetricPacket
+  | TurnBoundaryEventPacket
+  | UsageRecordedPacket
+  | AcousticSignalPacket
+  | TurnLocalizationPacket;
 
 /** Delegate (Responder-Thinker) lifecycle packets (Background route). */
 export type DelegatePacket = DelegateQueryPacket | DelegateResultPacket;

package/src/plugin-contract.ts

@@ -22,9 +22,43 @@ export interface EndpointingCapability {
   readonly disableConfig?: PluginConfig;
 }
 
+/**
+ * Vendor-agnostic mid-stream STT reconfiguration. Per-turn reconfigure is a COMMODITY STT capability
+ * (Deepgram Flux `Configure`, AssemblyAI `UpdateConfiguration`, Speechmatics `SetRecognitionConfig`) —
+ * the value of THIS seam is normalizing those differing wire shapes behind one interface so an
+ * InteractionPolicy can actuate any STT without vendor-specific plumbing. All fields optional; a plugin
+ * applies what it supports and ignores the rest (best-effort — e.g. Deepgram ignores `contextText`).
+ */
+export interface SttReconfigurePartial {
+  readonly keyterms?: readonly string[];
+  readonly eotThreshold?: number;
+  readonly eagerEotThreshold?: number;
+  readonly eotTimeoutMs?: number;
+  /** Silence-based endpointing (ms). Nova-style; Flux may ignore (it uses eotTimeoutMs). */
+  readonly endpointingMs?: number;
+  readonly vadThreshold?: number;
+  readonly languageHints?: readonly string[];
+  /**
+   * Hard recognition-language switch (e.g. "en-US" → "es-ES", or Nova-3 "multi" for code-switch).
+   * Distinct from `languageHints` (soft bias): this changes the recognizer's language. Providers
+   * that carry language in the connection URL (Nova) reconnect to apply it; model-fixed providers
+   * (Flux, `flux-general-en`) ignore it and rely on `languageHints`.
+   */
+  readonly language?: string;
+  /** AssemblyAI-style agent-context biasing (the agent's own prior reply). Ignored where unsupported. */
+  readonly contextText?: string;
+}
+
+export interface SttReconfigure {
+  reconfigure(partial: SttReconfigurePartial): void;
+}
+
 export interface VoicePlugin {
   readonly endpointingCapability?: EndpointingCapability;
 
+  /** Present when the STT supports mid-stream reconfiguration (see {@link SttReconfigure}). */
+  readonly sttReconfigure?: SttReconfigure;
+
   /**
    * Initialize the plugin. Called during the init chain.
    * Connect to provider, start streams, register bus handlers if needed.
@@ -34,6 +68,13 @@ export interface VoicePlugin {
    */
   initialize(bus: PipelineBus, config: PluginConfig): Promise<void>;
 
+  /**
+   * Best-effort warm of remote/expensive resources (open connections, wake a scaled-to-zero
+   * endpoint). Called AFTER initialize, before the first turn. Must not throw fatally — swallow
+   * errors internally. Optional; plugins with nothing to warm omit it.
+   */
+  prewarm?(): Promise<void>;
+
   /**
    * Tear down the plugin. Called during the finalize chain (reverse order).
    * Close connections, flush buffers, release resources.

package/src/policies/rule-based.ts

@@ -11,11 +11,19 @@ export interface RuleBasedInteractionPolicyDeps {
   readonly primarySpeakerGate: PrimarySpeakerGate;
   readonly ttsPlayout: TtsPlayoutClock;
   readonly minInterruptionMs: number;
+  /** When true, the underlying TurnArbiter emits duck/resume signals during barge-in evaluation. */
+  readonly pauseThenResolveBargeIn?: boolean;
+  /** Tenant-level backchannel knobs. Default (undefined) = current behavior (`mm_hmm`). */
+  readonly backchannel?: {
+    readonly enabled?: boolean;
+    readonly cues?: readonly string[];
+  };
 }
 
 export class RuleBasedInteractionPolicy implements InteractionPolicy {
   readonly arbiter: TurnArbiter;
   private readonly ttsPlayout: TtsPlayoutClock;
+  private readonly backchannelConfig: RuleBasedInteractionPolicyDeps["backchannel"];
   private pending: InteractionDecision[] = [];
   private bargeInAudioConsumed = false;
   private delegateGapOpen = false;
@@ -24,8 +32,13 @@ export class RuleBasedInteractionPolicy implements InteractionPolicy {
 
   constructor(deps: RuleBasedInteractionPolicyDeps) {
     this.ttsPlayout = deps.ttsPlayout;
+    this.backchannelConfig = deps.backchannel;
     this.arbiter = new TurnArbiter({
-      ...deps,
+      bus: deps.bus,
+      primarySpeakerGate: deps.primarySpeakerGate,
+      ttsPlayout: deps.ttsPlayout,
+      minInterruptionMs: deps.minInterruptionMs,
+      pauseThenResolveBargeIn: deps.pauseThenResolveBargeIn,
       onInterrupt: (id) => this.pending.push({ kind: "interrupt", interruptedContextId: id }),
     });
   }
@@ -109,7 +122,9 @@ export class RuleBasedInteractionPolicy implements InteractionPolicy {
         if (this.depsTtsActive()) return [];
         if (this.userSpeaking) return [];
         this.delegateCuePlayed = true;
-        return [{ kind: "backchannel", cue: "mm_hmm" }];
+        if (this.backchannelConfig?.enabled === false) return [];
+        const cue = this.backchannelConfig?.cues?.[0] ?? "mm_hmm";
+        return [{ kind: "backchannel", cue }];
       }
       case "complete":
       case "failed":