@kuralle-syrinx/core 4.1.0 → 4.3.0

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

@@ -7,13 +7,21 @@
 // definition and call sites need no `as` assertion — illegal packet shapes are
 // unrepresentable at construction instead of asserted-valid by a cast (CR-05).
 
+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,
@@ -21,7 +29,9 @@ import type {
   SpeechToTextAudioPacket,
   EndOfSpeechAudioPacket,
   EndOfSpeechPacket,
+  SttPartialPacket,
   SttResultPacket,
+  FinalizeSttPacket,
   UserInputPacket,
   TextToSpeechTextPacket,
   TextToSpeechDonePacket,
@@ -32,6 +42,7 @@ import type {
   InterruptLlmPacket,
   InterruptSttPacket,
   InjectMessagePacket,
+  SttReconfigurePacket,
   LlmDeltaPacket,
   LlmResponseDonePacket,
   ReasoningSuspendedPacket,
@@ -39,7 +50,11 @@ import type {
   StartIdleTimeoutPacket,
   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", "*", "#"]);
 
@@ -59,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,
@@ -68,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,
@@ -115,6 +200,17 @@ export function sttAudio(contextId: string, timestampMs: number, audio: Uint8Arr
   return { kind: "stt.audio", contextId, timestampMs, audio };
 }
 
+export function sttPartial(
+  contextId: string,
+  timestampMs: number,
+  text: string,
+  wordTimings?: readonly WordTiming[],
+): SttPartialPacket {
+  return wordTimings
+    ? { kind: "stt.partial", contextId, timestampMs, text, wordTimings }
+    : { kind: "stt.partial", contextId, timestampMs, text };
+}
+
 export function eosAudio(contextId: string, timestampMs: number, audio: Uint8Array): EndOfSpeechAudioPacket {
   return { kind: "eos.audio", contextId, timestampMs, audio };
 }
@@ -128,6 +224,10 @@ export function eosTurnComplete(
   return { kind: "eos.turn_complete", contextId, timestampMs, text, transcripts };
 }
 
+export function finalizeStt(contextId: string, timestampMs: number): FinalizeSttPacket {
+  return { kind: "stt.finalize", contextId, timestampMs };
+}
+
 export function userInput(
   contextId: string,
   timestampMs: number,
@@ -191,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 {
@@ -241,3 +354,25 @@ export function modeSwitchRequested(
 ): ModeSwitchRequestedPacket {
   return { kind: "mode.switch_requested", contextId, timestampMs, mode };
 }
+
+export function interactionBackchannel(
+  contextId: string,
+  timestampMs: number,
+  cue: string,
+): 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

@@ -9,6 +9,9 @@
 //   Errors:                 SttError, TtsError, LlmError
 //   Lifecycle:              InitStepCompleted, InitFailed, InitCompleted
 
+import type { WordTiming } from "./interaction-policy.js";
+import type { SttReconfigurePartial } from "./plugin-contract.js";
+
 // =============================================================================
 // Base Types
 // =============================================================================
@@ -44,7 +47,7 @@ export enum ErrorCategory {
 
 export interface VoiceErrorPacket extends VoicePacket {
   /** Which component emitted the error. */
-  readonly component: "stt" | "tts" | "vad" | "eos" | "denoiser" | "llm" | "bridge" | "pipeline";
+  readonly component: "stt" | "tts" | "vad" | "eos" | "denoiser" | "llm" | "bridge" | "pipeline" | "iu_ledger";
   /** Machine-readable error category. */
   readonly category: ErrorCategory;
   /** Original error. May contain provider-specific details. */
@@ -120,8 +123,10 @@ export interface AudioFormat {
 
 export interface UserAudioReceivedPacket extends VoicePacket {
   readonly kind: "user.audio_received";
-  /** Raw PCM audio (16-bit, mono, 16kHz). */
+  /** Raw PCM audio (16-bit, mono). Rate given by `sampleRateHz` (defaults to 16kHz). */
   readonly audio: Uint8Array;
+  /** Sample rate of `audio` in Hz. Omitted means 16000 (the legacy default). */
+  readonly sampleRateHz?: number;
 }
 
 export interface UserTextReceivedPacket extends VoicePacket {
@@ -176,6 +181,12 @@ export interface SttInterimPacket extends VoicePacket {
   readonly text: string;
 }
 
+export interface SttPartialPacket extends VoicePacket {
+  readonly kind: "stt.partial";
+  readonly text: string;
+  readonly wordTimings?: readonly WordTiming[];
+}
+
 export interface SttResultPacket extends VoicePacket {
   readonly kind: "stt.result";
   readonly text: string;
@@ -189,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";
@@ -270,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
 // =============================================================================
@@ -286,7 +333,7 @@ export interface LlmResponseDonePacket extends VoicePacket {
 
 export interface LlmErrorPacket extends VoicePacket, VoiceErrorPacket {
   readonly kind: "llm.error";
-  readonly component: "llm" | "bridge";
+  readonly component: "llm" | "bridge" | "iu_ledger";
 }
 
 export interface LlmToolCallPacket extends VoicePacket {
@@ -344,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 {
@@ -460,6 +515,26 @@ export interface RecordAssistantAudioTruncatePacket extends VoicePacket {
 
 export type RecordAssistantAudioPacket = RecordAssistantAudioDataPacket | RecordAssistantAudioTruncatePacket;
 
+// =============================================================================
+// Interaction Policy Packets
+// =============================================================================
+
+/** Pre-cached backchannel cue id rendered by the outbound mixer (IP-C3). */
+export interface InteractionBackchannelPacket extends VoicePacket {
+  readonly kind: "interaction.backchannel";
+  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
 // =============================================================================
@@ -476,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 {
@@ -517,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"
@@ -560,8 +689,10 @@ export type InputPacket =
   | VadSpeechActivityPacket
   | SpeechToTextAudioPacket
   | SttInterimPacket
+  | SttPartialPacket
   | SttResultPacket
   | FinalizeSttPacket
+  | SttReconfigurePacket
   | SttErrorPacket
   | EndOfSpeechAudioPacket
   | EndOfSpeechPacket
@@ -607,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/defer.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+
+import type { InteractionDecision, InteractionObservation, InteractionPolicy } from "../interaction-policy.js";
+
+/**
+ * The front owns full-duplex interaction (turn-taking, barge-in, backchannels). This policy takes no
+ * action — it observes only, so the coordinator drives nothing and the front's own decisions (surfaced
+ * by its adapter/bridge as interrupt.detected / eos.turn_complete) stand. RFC InteractionPolicy REQ-4.
+ */
+export class DeferInteractionPolicy implements InteractionPolicy {
+  observe(_obs: InteractionObservation): readonly InteractionDecision[] {
+    return [];
+  }
+  reset(_contextId: string): void {}
+}