@kuralle-syrinx/core 2.1.0

package/src/idle-timeout.ts

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Idle Timeout Manager
+//
+// Tracks user silence and escalates: inject message → inject warning → disconnect.
+// Configurable duration, escalation messages, and consecutive backoff.
+//
+// Design decision (per RFC Q4 resolution): idle messages are injected as
+// synthetic LlmDeltaPacket + LlmDonePacket through the normal TTS path.
+// This keeps voice style, logging, interruption, and abort semantics consistent.
+
+import type { PipelineBus } from "./pipeline-bus.js";
+import { Route } from "./pipeline-bus.js";
+import type {
+  StartIdleTimeoutPacket,
+  StopIdleTimeoutPacket,
+  InjectMessagePacket,
+  DisconnectRequestedPacket,
+} from "./packets.js";
+import { TimerScheduler, type Scheduler } from "./scheduler.js";
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+export interface IdleTimeoutConfig {
+  /** Base duration before triggering idle behavior (ms). Default: 15000 */
+  durationMs: number;
+  /**
+   * Number of consecutive timeouts before disconnecting.
+   * 0 = never disconnect (just inject messages repeatedly).
+   * Default: 3
+   */
+  maxConsecutive: number;
+  /**
+   * Messages to inject at each consecutive idle.
+   * Index 0 = first timeout, index 1 = second timeout, etc.
+   * If more timeouts occur than messages, the last message repeats.
+   * Default: ["Are you still there?", "I'll end this call soon."]
+   */
+  escalationMessages: string[];
+  /**
+   * Whether to disconnect the session after maxConsecutive is reached.
+   * If false, the maxConsecutive counter stops incrementing and the
+   * last escalation message repeats indefinitely.
+   * Default: true
+   */
+  disconnectAfterMax: boolean;
+}
+
+export const DEFAULT_IDLE_TIMEOUT_CONFIG: IdleTimeoutConfig = {
+  durationMs: 15_000,
+  maxConsecutive: 3,
+  escalationMessages: ["Are you still there?", "I'll end this call soon."],
+  disconnectAfterMax: true,
+};
+
+// =============================================================================
+// Manager
+// =============================================================================
+
+export class IdleTimeoutManager {
+  private timerScheduled = false;
+  private count = 0;
+  private readonly config: IdleTimeoutConfig;
+  private readonly bus: PipelineBus;
+  private currentContextId: string;
+  private readonly scheduler: Scheduler;
+
+  constructor(
+    bus: PipelineBus,
+    config?: Partial<IdleTimeoutConfig>,
+    scheduler?: Scheduler,
+  ) {
+    this.bus = bus;
+    this.config = { ...DEFAULT_IDLE_TIMEOUT_CONFIG, ...config };
+    this.currentContextId = "";
+    this.scheduler = scheduler ?? new TimerScheduler();
+  }
+
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+
+  /** Set the current turn context ID (used for injected message context). */
+  setContextId(id: string): void {
+    this.currentContextId = id;
+  }
+
+  /** Start (or restart) the idle timeout timer. */
+  start(): void {
+    this.clearTimer();
+    if (this.config.durationMs <= 0) return;
+
+    this.timerScheduled = true;
+    this.scheduler.schedule("voice.idle_timeout", this.config.durationMs, () => {
+      this.timerScheduled = false;
+      this.onTimeout();
+    });
+  }
+
+  /**
+   * Stop the idle timeout timer.
+   * @param resetCount — If true, resets the consecutive idle counter.
+   *   Use true when the user actively engages (speaks or types).
+   *   Use false for system-driven stops (e.g., TTS still playing).
+   */
+  stop(resetCount: boolean): void {
+    this.clearTimer();
+    if (resetCount) {
+      this.count = 0;
+    }
+  }
+
+  /**
+   * Extend the current timer by a duration (e.g., TTS audio playback time).
+   * Stops the current timer and restarts with the remaining time + extension.
+   */
+  extend(ms: number): void {
+    this.clearTimer();
+    this.timerScheduled = true;
+    this.scheduler.schedule("voice.idle_timeout", this.config.durationMs + ms, () => {
+      this.timerScheduled = false;
+      this.onTimeout();
+    });
+  }
+
+  /** Clean up — stop timer without side effects. */
+  dispose(): void {
+    this.clearTimer();
+  }
+
+  // -------------------------------------------------------------------------
+  // Private
+  // -------------------------------------------------------------------------
+
+  private clearTimer(): void {
+    if (!this.timerScheduled) return;
+    this.scheduler.cancel("voice.idle_timeout");
+    this.timerScheduled = false;
+  }
+
+  /**
+   * Resolve a non-empty context id for injected idle turns. If no turn context has been seen yet
+   * (e.g. the idle timer fired before the first user turn completed), synthesize a stable one —
+   * an empty contextId propagates downstream and is rejected by providers that validate it
+   * (e.g. Cartesia TTS: "context_id must be alphanumeric/_/-").
+   */
+  private ensureContextId(): string {
+    if (this.currentContextId === "") {
+      this.currentContextId = `idle-${String(Date.now())}`;
+    }
+    return this.currentContextId;
+  }
+
+  private onTimeout(): void {
+    this.count++;
+    const contextId = this.ensureContextId();
+
+    // Check if we should disconnect
+    if (
+      this.config.maxConsecutive > 0 &&
+      this.count >= this.config.maxConsecutive &&
+      this.config.disconnectAfterMax
+    ) {
+      const disconnect: DisconnectRequestedPacket = {
+        kind: "session.disconnect",
+        contextId,
+        timestampMs: Date.now(),
+        reason: `idle_timeout: ${this.count} consecutive`,
+      };
+      this.bus.push(Route.Critical, disconnect);
+      return;
+    }
+
+    // Inject escalation message
+    const msgIdx = Math.min(
+      this.count - 1,
+      this.config.escalationMessages.length - 1,
+    );
+    const message = this.config.escalationMessages[msgIdx];
+    if (message) {
+      const inject: InjectMessagePacket = {
+        kind: "inject.message",
+        contextId,
+        timestampMs: Date.now(),
+        text: message,
+      };
+      this.bus.push(Route.Main, inject);
+    }
+
+    // Restart timer for next escalation
+    this.start();
+  }
+
+  // -------------------------------------------------------------------------
+  // Bus packet handlers (for integration with VoiceAgentSession)
+  // -------------------------------------------------------------------------
+
+  /** Handle a StartIdleTimeoutPacket from the bus. */
+  handleStart(pkt: StartIdleTimeoutPacket): void {
+    if (pkt.contextId) this.setContextId(pkt.contextId);
+    this.start();
+  }
+
+  /** Handle a StopIdleTimeoutPacket from the bus. */
+  handleStop(pkt: StopIdleTimeoutPacket): void {
+    this.stop(pkt.resetCount);
+  }
+}

package/src/index.ts

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Public API
+//
+// Everything a consumer needs to build voice agents with the new kernel.
+
+// Core types
+export {
+  type AudioFormat,
+  type VoicePacket,
+  type AsyncPacket,
+  type VoiceErrorPacket,
+  ErrorCategory,
+  SessionState,
+  InitStage,
+  type InitStepCompletedPacket,
+  type InitializationFailedPacket,
+  type InitializationCompletedPacket,
+} from "./packets.js";
+
+// Pipeline packets — input
+export {
+  type UserAudioReceivedPacket,
+  type UserTextReceivedPacket,
+  type DenoiseAudioPacket,
+  type DenoisedAudioPacket,
+  type VadAudioPacket,
+  type VadSpeechStartedPacket,
+  type VadSpeechEndedPacket,
+  type VadSpeechActivityPacket,
+  type SpeechToTextAudioPacket,
+  type SttInterimPacket,
+  type SttResultPacket,
+  type FinalizeSttPacket,
+  type SttErrorPacket,
+  type EndOfSpeechAudioPacket,
+  type EndOfSpeechPacket,
+  type InterimEndOfSpeechPacket,
+  type UserInputPacket,
+} from "./packets.js";
+
+// Pipeline packets — interruption
+export {
+  type InterruptionDetectedPacket,
+  type InterruptTtsPacket,
+  type InterruptLlmPacket,
+  type InterruptSttPacket,
+  type TurnChangePacket,
+} from "./packets.js";
+
+// Pipeline packets — LLM
+export {
+  type LlmDeltaPacket,
+  type LlmResponseDonePacket,
+  type LlmErrorPacket,
+  type LlmToolCallPacket,
+  type LlmToolResultPacket,
+} from "./packets.js";
+
+// Pipeline packets — reasoning (suspend/resume)
+export {
+  type ReasoningSuspendedPacket,
+  type ReasoningResumePacket,
+} from "./packets.js";
+
+// Pipeline packets — TTS
+export {
+  type TextToSpeechTextPacket,
+  type TextToSpeechDonePacket,
+  type TextToSpeechAudioPacket,
+  type TextToSpeechEndPacket,
+  type TextToSpeechPlayoutStartedPacket,
+  type TextToSpeechPlayoutProgressPacket,
+  type TextToSpeechWordTimestampsPacket,
+  type TtsWordTimestamp,
+  type TtsErrorPacket,
+} from "./packets.js";
+
+// Pipeline packets — behavior
+export {
+  type RecordAssistantAudioDataPacket,
+  type RecordAssistantAudioPacket,
+  type RecordAssistantAudioTruncatePacket,
+  type RecordUserAudioPacket,
+  type StartIdleTimeoutPacket,
+  type StopIdleTimeoutPacket,
+  type InjectMessagePacket,
+  type DisconnectRequestedPacket,
+} from "./packets.js";
+
+// Pipeline packets — mode
+export {
+  type ModeSwitchRequestedPacket,
+  type ModeSwitchCompletedPacket,
+} from "./packets.js";
+
+// Pipeline packets — persistence
+export {
+  type MessageCreatePacket,
+  type ConversationMetricPacket,
+  type TurnBoundaryKind,
+  type TurnBoundaryEventPacket,
+  type ObservabilityPacket,
+  type PipelineErrorPacket,
+} from "./packets.js";
+
+// Observability backbone (VE-07)
+export {
+  monotonicNowMs,
+  type MetricTags,
+  type SpanHandle,
+  type MetricsExporter,
+  noopMetricsExporter,
+  InMemoryMetricsExporter,
+  reconstructTurnTimeline,
+  type TurnTimelineStep,
+} from "./observability.js";
+
+export {
+  ObservabilityObserver,
+  type ObservabilityObserverDeps,
+  type ObservabilityDims,
+} from "./observability-observer.js";
+
+// PipelineBus
+export { PipelineBusImpl, Route, type PipelineBus, type PipelineBusConfig, type PacketHandler } from "./pipeline-bus.js";
+
+// Init chain
+export { runInitChain, runFinalizeChain, type InitStep, InitializationError } from "./init-chain.js";
+
+// Plugin contract
+export {
+  type VoicePlugin,
+  type PluginConfig,
+  type EndpointingOwner,
+  type EndpointingCapability,
+  requireStringConfig,
+  optionalStringConfig,
+} from "./plugin-contract.js";
+
+// Error handler
+export { categorizeSttError, categorizeTtsError, categorizeLlmError, isRecoverable, isFatalError } from "./error-handler.js";
+
+// Retry helpers
+export { DEFAULT_RETRY_CONFIG, VOICE_PROVIDER_RETRY_CONFIG, VOICE_PROVIDER_OUTAGE_RETRY_CONFIG, readRetryConfig, readProviderRetryConfig, retryDelayMs, waitForRetryDelay, type RetryConfig } from "./retry.js";
+
+// Provider fallback/degradation
+export { ProviderFallback, type FallbackProvider, type ProviderFallbackOptions } from "./provider-fallback.js";
+
+// Runtime scheduler seam
+export { TimerScheduler, type Scheduler, type ScheduledCallback } from "./scheduler.js";
+
+// Idle timeout
+export { IdleTimeoutManager, type IdleTimeoutConfig, DEFAULT_IDLE_TIMEOUT_CONFIG } from "./idle-timeout.js";
+
+// Mode switcher
+export { ModeSwitcher, type ModeSwitchHandlers } from "./mode-switcher.js";
+
+// Conversation events
+export { type ConversationEvent, createConversationEventStream } from "./conversation-event.js";
+
+// Websocket audio envelope
+export {
+  SYRINX_AUDIO_ENVELOPE_NAME,
+  SYRINX_AUDIO_ENVELOPE_MAGIC,
+  assertAudioFormat,
+  assertAudioPayload,
+  encodeSyrinxAudioEnvelope,
+  decodeSyrinxAudioEnvelope,
+  hasSyrinxAudioEnvelope,
+  type SyrinxAudioEnvelope,
+  type SyrinxAudioEnvelopeHeader,
+} from "./audio-envelope.js";
+
+// VoiceAgentSession
+export { VoiceAgentSession, type VoiceAgentSessionConfig, type VoiceAgentSessionEvents } from "./voice-agent-session.js";
+
+// Primary-speaker barge-in gate (VE-02)
+export {
+  PrimarySpeakerGate,
+  extractSpeakerFingerprint,
+  fingerprintSimilarity,
+  type SpeakerFingerprint,
+  type PrimarySpeakerGateConfig,
+} from "./primary-speaker-gate.js";
+export {
+  synthesizeTonePcm16,
+  mixPcm16,
+  PRIMARY_SPEAKER_TONE_HZ,
+  BYSTANDER_SPEAKER_TONE_HZ,
+  ASSISTANT_ECHO_TONE_HZ,
+} from "./primary-speaker-fixtures.js";
+
+// Latency-hiding filler track (VE-03)
+export {
+  LatencyFillerController,
+  selectLatencyFillerConnective,
+  stripRedundantFillerPrefix,
+  LATENCY_FILLER_CONNECTIVES,
+  type LatencyFillerConfig,
+  type LatencyFillerState,
+  type LatencyFillerConnective,
+} from "./latency-filler.js";
+export {
+  LATENCY_FILLER_FIXTURES,
+  type LatencyFillerFixture,
+} from "./latency-filler-fixtures.js";
+
+// Reasoner seam (RFC §4.2)
+export {
+  type Reasoner,
+  type ReasonerTurn,
+  type ReasonerMessage,
+  type ReasoningPart,
+} from "./reasoner.js";

package/src/init-chain.ts

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Init Chain
+//
+// Serial initialization of pipeline components with ordered teardown on failure.
+// Each step runs synchronously in order. On failure, already-initialized steps
+// are torn down in reverse order.
+
+import type { PipelineBus } from "./pipeline-bus.js";
+import { Route } from "./pipeline-bus.js";
+import type {
+  InitStage,
+  InitStepCompletedPacket,
+  InitializationFailedPacket,
+  InitializationCompletedPacket,
+} from "./packets.js";
+import { ErrorCategory } from "./packets.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface InitStep {
+  /** Human-readable name for logging and error messages. */
+  readonly name: string;
+  /** Which initialization stage this step represents. */
+  readonly stage: InitStage;
+  /** Run the initialization. Throws on failure. */
+  run(): Promise<void>;
+  /** Clean up resources. Called during teardown (on failure) or finalize chain. */
+  cleanup?(): Promise<void>;
+}
+
+// =============================================================================
+// Error
+// =============================================================================
+
+export class InitializationError extends Error {
+  constructor(
+    public readonly stage: InitStage,
+    public readonly component: string,
+    cause: Error,
+  ) {
+    super(`Initialization failed at ${stage}/${component}: ${cause.message}`);
+    this.name = "InitializationError";
+  }
+}
+
+// =============================================================================
+// Core
+// =============================================================================
+
+/**
+ * Run a serial init chain. Each step runs in order. On failure:
+ * 1. Emits InitializationFailedPacket through the bus.
+ * 2. Tears down already-initialized steps in reverse order.
+ * 3. Throws InitializationError.
+ *
+ * On success:
+ * 1. Emits InitStepCompletedPacket for each step (with initMs).
+ * 2. Emits InitializationCompletedPacket.
+ */
+export async function runInitChain(
+  bus: PipelineBus,
+  steps: readonly InitStep[],
+): Promise<void> {
+  const initialized: InitStep[] = [];
+
+  for (const step of steps) {
+    const startMs = performance.now();
+    try {
+      await step.run();
+      const initMs = performance.now() - startMs;
+
+      const completed: InitStepCompletedPacket = {
+        kind: "init.step_completed",
+        contextId: "",
+        timestampMs: Date.now(),
+        stage: step.stage,
+        component: step.name,
+        initMs,
+      };
+      bus.push(Route.Main, completed);
+      initialized.push(step);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+
+      const failed: InitializationFailedPacket = {
+        kind: "init.failed",
+        contextId: "",
+        timestampMs: Date.now(),
+        stage: step.stage,
+        component: step.name,
+        category: ErrorCategory.InternalFault,
+        cause: error,
+        isRecoverable: false,
+      };
+      bus.push(Route.Main, failed);
+
+      // Reverse teardown of already-initialized steps
+      for (const done of [...initialized].reverse()) {
+        try {
+          await done.cleanup?.();
+        } catch (cleanupErr) {
+          // Log but don't throw — cleanup failures shouldn't mask the init error
+          // In production, this goes to the bus as a warning
+        }
+      }
+
+      throw new InitializationError(step.stage, step.name, error);
+    }
+  }
+
+  const completed: InitializationCompletedPacket = {
+    kind: "init.completed",
+    contextId: "",
+    timestampMs: Date.now(),
+  };
+  bus.push(Route.Main, completed);
+}
+
+/**
+ * Run a reverse finalize chain. Steps are torn down in reverse order.
+ * Errors during teardown are logged but do not stop the chain.
+ * All steps get their cleanup called regardless of earlier failures.
+ */
+export async function runFinalizeChain(
+  steps: readonly InitStep[],
+): Promise<void> {
+  for (const step of [...steps].reverse()) {
+    try {
+      await step.cleanup?.();
+    } catch {
+      // Log but continue — finalize must complete
+    }
+  }
+}

package/src/init-stage-order.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Init Stage Ordering
+//
+// Pure mapping from plugin name → init stage, and the deterministic order in
+// which stages initialize (and, reversed, finalize). Extracted from
+// VoiceAgentSession so the orchestrator owns chain assembly, not the ordering
+// policy.
+
+import { InitStage } from "./packets.js";
+
+export function pluginStage(name: string): InitStage {
+  switch (name) {
+    case "stt":
+    case "deepgram":
+      return InitStage.STT;
+    case "tts":
+    case "cartesia":
+    case "elevenlabs":
+      return InitStage.TTS;
+    case "vad":
+    case "silero":
+      return InitStage.VAD;
+    case "eos":
+    case "pipecat":
+      return InitStage.EOS;
+    case "denoiser":
+    case "rnnoise":
+      return InitStage.Denoiser;
+    case "bridge":
+    case "aisdk":
+      return InitStage.Assistant;
+    case "recorder":
+      return InitStage.Recorder;
+    case "auth":
+      return InitStage.Auth;
+    default:
+      return InitStage.Assistant;
+  }
+}
+
+export function stageOrder(stage: InitStage): number {
+  switch (stage) {
+    case InitStage.Assistant:
+      return 10;
+    case InitStage.Conversation:
+      return 20;
+    case InitStage.Recorder:
+      return 30;
+    case InitStage.Normalizer:
+      return 40;
+    case InitStage.Auth:
+      return 50;
+    case InitStage.STT:
+      return 60;
+    case InitStage.TTS:
+      return 70;
+    case InitStage.VAD:
+      return 80;
+    case InitStage.EOS:
+      return 90;
+    case InitStage.Denoiser:
+      return 100;
+    case InitStage.Behavior:
+      return 110;
+    case InitStage.Telemetry:
+      return 120;
+  }
+}
+
+export function isAudioStage(stage: InitStage): boolean {
+  return (
+    stage === InitStage.STT ||
+    stage === InitStage.TTS ||
+    stage === InitStage.VAD ||
+    stage === InitStage.EOS ||
+    stage === InitStage.Denoiser
+  );
+}

package/src/latency-filler-fixtures.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+//
+// Labeled utterances for latency-filler connective selection tests.
+
+export interface LatencyFillerFixture {
+  readonly id: string;
+  readonly userText: string;
+  readonly expectedConnective: string;
+}
+
+export const LATENCY_FILLER_FIXTURES: readonly LatencyFillerFixture[] = [
+  { id: "question", userText: "Can I still add Biology 101?", expectedConnective: "Well," },
+  { id: "thanks", userText: "Thanks for checking that.", expectedConnective: "Right," },
+  { id: "statement-0", userText: "I need the late add form.", expectedConnective: "So," },
+  { id: "statement-1", userText: "My hold is blocking registration.", expectedConnective: "Well," },
+] as const;