@kuralle-syrinx/stt-core 4.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,84 @@
+# @kuralle-syrinx/stt-core
+
+The shared streaming-STT lifecycle engine for Syrinx STT adapters — the STT counterpart of
+`@kuralle-syrinx/tts-core`. A provider becomes a Syrinx STT plugin by implementing one small,
+socket-free port (`SttWireProtocol`); this package owns everything else: the
+`@kuralle-syrinx/ws` `WebSocketConnection`, `stt.interim` / `stt.result` emission, the
+smart-turn-safe final-transcript funnel, `usage.recorded{stage:"stt", audioSeconds}`
+delta-billing, and finalize/reconfigure/reset plumbing.
+
+## The `SttWireProtocol` port
+
+```ts
+export interface SttWireProtocol {
+  encodeFinalize(contextId: string): readonly SocketData[];
+  decode(data: SocketData, isBinary: boolean): readonly SttEvent[];
+  encodeClose?(): readonly SocketData[];
+  encodeAudio?(audio: Uint8Array): readonly SocketData[];   // default: raw PCM frame
+  onOpen?(): readonly SocketData[];                          // handshake/config on (re)connect
+  encodeReconfigure?(partial: SttReconfigurePartial): readonly SocketData[];
+  isReady?(): boolean;                                       // gate outbound audio pre-handshake
+  onConnectionLost?(): void;
+  attach?(host: SttProtocolHost): void;                      // async-emit seam (timers, etc.)
+  onFinalizeSent?(contextId: string): void;
+}
+```
+
+A provider implements only wire encode/decode. The engine owns context tracking, outbound
+audio send + finalize, the interim/final funnel, delta-billing, and (optional) `eos.turn_complete`.
+
+## `startStreamingSttSession`
+
+```typescript
+import { startStreamingSttSession, defaultNodeSocketFactory } from "@kuralle-syrinx/stt-core";
+
+const session = await startStreamingSttSession(bus, {
+  protocol: new MyProviderWireProtocol(),
+  provider: { name: "my-provider", model: "my-model" },
+  url: () => "wss://api.example.com/stt",
+  headers: { Authorization: `Bearer ${apiKey}` },
+  retry: readProviderRetryConfig(config),
+  socketFactory: await defaultNodeSocketFactory(),
+  emitEosOnFinal: true, // eos.turn_complete on speechFinal:true results
+});
+
+// session.dispose(): Promise<void>
+// session.reconfigure(partial: SttReconfigurePartial): void  — mid-turn keyterms/language/etc.
+// session.reset(): void                                       — force a transport reconnect
+```
+
+Wires the standard `PipelineBus` plumbing: `stt.audio` → `engine.onAudio` (the **canonical STT
+ingress** — plugins subscribe to `stt.audio` only, never `user.audio_received`, to avoid
+double-sending/double-billing every frame), `stt.finalize` → `encodeFinalize`, `turn.change` /
+`interrupt.stt` → context bookkeeping.
+
+## Extension seams (wave 1 + wave 2)
+
+- **`encodeAudio` / `onOpen` / `encodeReconfigure`** — optional wire hooks for providers whose
+  audio framing, connect-time handshake, or reconfigure protocol differs from the raw-PCM default.
+- **Richer `SttEvent` vocabulary** — `speech_started`, `partial`, `eos_interim`, `eos_retracted`,
+  in addition to `interim` / `final` / `error` / `turn_complete` / `ignore`.
+- **Pre-handshake audio buffering** — audio that races ahead of a provider handshake (e.g. Grok's
+  `transcript.created`) is buffered (capped) and flushed on the ready transition instead of dropped.
+- **Sent-bytes billing fallback** — when a final has no provider duration, usage bills off sent PCM
+  bytes; a later duration-bearing final advances the byte marker so it can't double-bill.
+- **`SttProtocolHost` (`attach`/`emit`/`reset`), `onFinalizeSent`, `Transport.reset`,
+  `SttEvent.turn_complete`** (wave 2) — async-emit seams for providers with their own
+  finalize-timeout/fallback/reconnect state machine (e.g. Deepgram nova's Finalize handshake).
+
+## Providers built on it
+
+Grok, ElevenLabs, Google, and Deepgram Flux STT are behavior-preserving migrations onto this
+base. Deepgram nova STT also builds on it, using the wave-2 async-emit seams for its
+Finalize-timeout state machine (multi-segment accumulation, `speech_final`/`from_finalize`
+gating, UtteranceEnd backstop) — provider-boundary logic stays in the wire protocol; the
+socket/reconnect/billing/buffer funnel is shared.
+
+See `@kuralle-syrinx/grok`'s `GrokSTTPlugin` (`src/stt.ts`) or `@kuralle-syrinx/elevenlabs`'s
+`ElevenLabsSTTPlugin` for a minimal real implementation.
+
+## Deploy on Cloudflare Workers
+
+Socket-free and transport-injectable like the rest of the Syrinx kernel: pass
+`createWorkersSocket` (`@kuralle-syrinx/ws/workers`) as the `socketFactory` instead of
+`defaultNodeSocketFactory()` to dial outbound provider WebSockets through the fetch-upgrade path.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kuralle-syrinx/stt-core",
+  "version": "4.3.0",
+  "private": false,
+  "description": "Shared streaming-STT lifecycle engine for Syrinx STT adapters — connection, transcript funnel, usage delta-billing",
+  "keywords": [
+    "voice",
+    "voice-agent",
+    "speech",
+    "syrinx",
+    "speech-to-text",
+    "streaming"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/kuralle/syrinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/syrinx.git",
+    "directory": "packages/stt-core"
+  },
+  "bugs": {
+    "url": "https://github.com/kuralle/syrinx/issues"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@kuralle-syrinx/core": "4.3.0",
+    "@kuralle-syrinx/ws": "4.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.6"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,394 @@
+// SPDX-License-Identifier: MIT
+//
+// The streaming-STT deep module. Owns the lifecycle adapters used to re-implement:
+// context tracking, outbound audio send + finalize, transcript funnel (interim/final),
+// usage delta-billing at finals, and optional eos.turn_complete. Socket-free: depends
+// only on injected ports so the funnel is unit-testable without a real WebSocket.
+
+import {
+  Route,
+  assertAudioPayload,
+  categorizeSttError,
+  isRecoverable,
+  type AudioFormat,
+  type SttErrorPacket,
+  type SttInterimPacket,
+  type SttResultPacket,
+} from "@kuralle-syrinx/core";
+import type { SocketData } from "@kuralle-syrinx/ws";
+
+import type { PacketSink, SttEvent, SttWireProtocol, Transport } from "./types.js";
+
+export interface SttEngineDeps {
+  readonly protocol: SttWireProtocol;
+  readonly transport: Transport;
+  readonly sink: PacketSink;
+  readonly provider: { readonly name: string; readonly model: string; readonly region?: string };
+  /** When true, emit `eos.turn_complete` for finals with `speechFinal: true`. */
+  readonly emitEosOnFinal: boolean;
+  /** Default language stamped on `stt.result` when the event omits one. */
+  readonly language: string;
+  /** When set, outbound audio is validated with `assertAudioPayload` before send. */
+  readonly format?: AudioFormat;
+  readonly now?: () => number;
+}
+
+export interface SttEngine {
+  onAudio(audio: Uint8Array, contextId?: string): Promise<boolean>;
+  onFinalize(contextId?: string): Promise<void>;
+  onTurnChange(contextId: string): void;
+  onInterrupt(): void;
+  onMessage(data: SocketData, isBinary: boolean): void;
+  onConnectionLost(error: Error): void;
+  close(): Promise<void>;
+  readonly currentContextId: string;
+}
+
+export function createSttEngine(deps: SttEngineDeps): SttEngine {
+  return new SttEngineImpl(deps);
+}
+
+/** Cap the pre-handshake audio buffer so a never-ready session cannot grow it unbounded. */
+const MAX_PENDING_AUDIO_FRAMES = 256;
+
+class SttEngineImpl implements SttEngine {
+  private contextId = "";
+  /** Cumulative billed audio-seconds per context (provider duration is often cumulative). */
+  private readonly billedDurationByContextId = new Map<string, number>();
+  /** Sent PCM byte totals per context (for providers without a duration signal). */
+  private readonly sentBytesByContextId = new Map<string, number>();
+  /** Already-billed PCM byte totals per context (kept in sync with duration billing). */
+  private readonly billedBytesByContextId = new Map<string, number>();
+  /** Audio that arrived before the provider handshake (isReady()) — flushed on the ready transition. */
+  private readonly pendingAudio: Uint8Array[] = [];
+  private readonly now: () => number;
+
+  constructor(private readonly deps: SttEngineDeps) {
+    this.now = deps.now ?? (() => Date.now());
+    this.deps.protocol.attach?.({
+      emit: (event) => this.dispatch(event),
+      reset: () => {
+        this.deps.transport.reset?.();
+      },
+    });
+  }
+
+  get currentContextId(): string {
+    return this.contextId;
+  }
+
+  async onAudio(audio: Uint8Array, contextId?: string): Promise<boolean> {
+    if (contextId) this.contextId = contextId;
+    if (audio.byteLength === 0) return true;
+    try {
+      if (this.deps.format) assertAudioPayload(this.deps.format, audio);
+      await this.deps.transport.ensureReady();
+      // Buffer (don't drop) audio that races ahead of the provider handshake (e.g. Grok's
+      // transcript.created); the pending frames flush on the isReady() transition in onMessage.
+      // Prevents losing the start of speech and the pre-handshake send/receive race.
+      if (this.deps.protocol.isReady && !this.deps.protocol.isReady()) {
+        this.pendingAudio.push(audio);
+        if (this.pendingAudio.length > MAX_PENDING_AUDIO_FRAMES) this.pendingAudio.shift();
+        this.recordSentBytes(this.contextId, audio.byteLength);
+        return true;
+      }
+      this.flushPendingAudioIfReady(); // drain anything buffered before the handshake, in order
+      this.sendEncodedAudio(audio);
+      this.recordSentBytes(this.contextId, audio.byteLength);
+      return true;
+    } catch (err) {
+      this.emitError(this.contextId, err instanceof Error ? err : new Error(String(err)));
+      return false;
+    }
+  }
+
+  async onFinalize(contextId?: string): Promise<void> {
+    const ctx = contextId ?? this.contextId;
+    try {
+      await this.deps.transport.ensureReady();
+      if (this.deps.transport.isReady === false) return;
+      for (const frame of this.deps.protocol.encodeFinalize(ctx)) {
+        this.deps.transport.send(frame);
+      }
+      this.deps.protocol.onFinalizeSent?.(ctx);
+    } catch (err) {
+      this.emitError(ctx, err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+
+  onTurnChange(nextContextId: string): void {
+    // Do NOT retire the prior context's billing here: a provider's finalize tail (e.g. nova's
+    // `from_finalize` final under smart-turn) can arrive AFTER turn.change rotates the context.
+    // Clearing on rotation would bill that trailing audio against a wiped counter (0s = under-bill).
+    // Billing is retired on true turn completion instead (speechFinal final / turn_complete / interrupt).
+    this.contextId = nextContextId;
+  }
+
+  onInterrupt(): void {
+    // Barge-in abandons the current turn — retire its billing (no trailing final will be billed).
+    if (this.contextId) this.clearContextBilling(this.contextId);
+    this.contextId = "";
+  }
+
+  onMessage(data: SocketData, isBinary: boolean): void {
+    let events: readonly SttEvent[];
+    try {
+      events = this.deps.protocol.decode(data, isBinary);
+    } catch (err) {
+      this.emitError(this.contextId, err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    for (const event of events) this.dispatch(event);
+    this.flushPendingAudioIfReady();
+  }
+
+  private flushPendingAudioIfReady(): void {
+    if (this.pendingAudio.length === 0) return;
+    if (this.deps.protocol.isReady && !this.deps.protocol.isReady()) return;
+    const frames = this.pendingAudio.splice(0);
+    try {
+      for (const audio of frames) this.sendEncodedAudio(audio);
+    } catch (err) {
+      this.emitError(this.contextId, err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+
+  private sendEncodedAudio(audio: Uint8Array): void {
+    const frames = this.deps.protocol.encodeAudio?.(audio) ?? [audio];
+    for (const frame of frames) this.deps.transport.send(frame);
+  }
+
+  private recordSentBytes(contextId: string, byteLength: number): void {
+    if (!contextId || byteLength <= 0) return;
+    this.sentBytesByContextId.set(contextId, (this.sentBytesByContextId.get(contextId) ?? 0) + byteLength);
+  }
+
+  private clearContextBilling(contextId: string): void {
+    this.billedDurationByContextId.delete(contextId);
+    this.sentBytesByContextId.delete(contextId);
+    this.billedBytesByContextId.delete(contextId);
+  }
+
+  onConnectionLost(error: Error): void {
+    this.deps.protocol.onConnectionLost?.();
+    this.emitError(this.contextId, error);
+  }
+
+  async close(): Promise<void> {
+    this.billedDurationByContextId.clear();
+    this.sentBytesByContextId.clear();
+    this.billedBytesByContextId.clear();
+    this.pendingAudio.length = 0;
+    try {
+      const frames = this.deps.protocol.encodeClose?.() ?? [];
+      if (frames.length > 0) {
+        await this.deps.transport.ensureReady();
+        if (this.deps.transport.isReady !== false) {
+          for (const frame of frames) this.deps.transport.send(frame);
+        }
+      }
+    } catch {
+      // Best-effort session shutdown.
+    }
+    await this.deps.transport.close();
+  }
+
+  private dispatch(event: SttEvent): void {
+    switch (event.type) {
+      case "interim":
+        this.handleInterim(event);
+        return;
+      case "final":
+        this.handleFinal(event);
+        return;
+      case "speech_started":
+        this.handleSpeechStarted(event);
+        return;
+      case "partial":
+        this.handlePartial(event);
+        return;
+      case "eos_interim":
+        this.handleEosInterim(event);
+        return;
+      case "eos_retracted":
+        this.handleEosRetracted(event);
+        return;
+      case "turn_complete":
+        this.handleTurnComplete(event);
+        return;
+      case "error":
+        this.emitError(event.contextId || this.contextId, event.error);
+        return;
+      case "ignore":
+        return;
+    }
+  }
+
+  /** Eos-only: result + usage already emitted on per-segment `final` events. */
+  private handleTurnComplete(event: Extract<SttEvent, { type: "turn_complete" }>): void {
+    const text = event.text.trim();
+    if (!text) return;
+    const contextId = event.contextId || this.contextId;
+    this.deps.sink.push(Route.Main, {
+      kind: "eos.turn_complete",
+      contextId,
+      timestampMs: this.now(),
+      text,
+      transcripts: [],
+    });
+    // Turn committed (per-segment results already billed) — retire billing.
+    this.clearContextBilling(contextId);
+  }
+
+  private handleInterim(event: Extract<SttEvent, { type: "interim" }>): void {
+    const text = event.text.trim();
+    if (!text) return;
+    const contextId = event.contextId || this.contextId;
+    const packet: SttInterimPacket = {
+      kind: "stt.interim",
+      contextId,
+      timestampMs: this.now(),
+      text,
+    };
+    this.deps.sink.push(Route.Main, packet);
+  }
+
+  private handlePartial(event: Extract<SttEvent, { type: "partial" }>): void {
+    const text = event.text.trim();
+    if (!text) return;
+    const contextId = event.contextId || this.contextId;
+    const packet: Record<string, unknown> = {
+      kind: "stt.partial",
+      contextId,
+      timestampMs: this.now(),
+      text,
+    };
+    if (event.wordTimings !== undefined) packet["wordTimings"] = event.wordTimings;
+    this.deps.sink.push(Route.Main, packet);
+  }
+
+  private handleSpeechStarted(event: Extract<SttEvent, { type: "speech_started" }>): void {
+    const contextId = event.contextId || this.contextId;
+    this.deps.sink.push(Route.Main, {
+      kind: "vad.speech_started",
+      contextId,
+      timestampMs: this.now(),
+      confidence: 1,
+    });
+  }
+
+  private handleEosInterim(event: Extract<SttEvent, { type: "eos_interim" }>): void {
+    const text = event.text.trim();
+    if (!text) return;
+    const contextId = event.contextId || this.contextId;
+    this.deps.sink.push(Route.Main, {
+      kind: "eos.interim",
+      contextId,
+      timestampMs: this.now(),
+      text,
+    });
+  }
+
+  private handleEosRetracted(event: Extract<SttEvent, { type: "eos_retracted" }>): void {
+    const contextId = event.contextId || this.contextId;
+    this.deps.sink.push(Route.Main, {
+      kind: "eos.retracted",
+      contextId,
+      timestampMs: this.now(),
+    });
+  }
+
+  private handleFinal(event: Extract<SttEvent, { type: "final" }>): void {
+    const text = event.text.trim();
+    if (!text) return;
+    const contextId = event.contextId || this.contextId;
+    const providerBase = {
+      name: this.deps.provider.name,
+      model: this.deps.provider.model,
+      region: this.deps.provider.region ?? "global",
+    };
+    const packet: SttResultPacket = {
+      kind: "stt.result",
+      contextId,
+      timestampMs: this.now(),
+      text,
+      confidence: event.confidence ?? 0,
+      language: event.language ?? this.deps.language,
+      provider: event.provider ? { ...providerBase, ...event.provider } : providerBase,
+    };
+    this.deps.sink.push(Route.Main, packet);
+    // Bill at the final-result funnel so usage fires under smart-turn endpointing too.
+    this.emitSttUsage(contextId, event.audioSeconds);
+    if (event.speechFinal) {
+      if (this.deps.emitEosOnFinal) {
+        this.deps.sink.push(Route.Main, {
+          kind: "eos.turn_complete",
+          contextId,
+          timestampMs: this.now(),
+          text,
+          transcripts: [],
+        });
+      }
+      // Turn completed via a speech-final result (usage already billed above) — retire billing.
+      this.clearContextBilling(contextId);
+    }
+  }
+
+  /**
+   * Prefer provider duration when present (Grok duration / Google resultEndOffset); otherwise
+   * bill unbilled PCM bytes as audio-seconds. Duration path also advances the byte marker so a
+   * later no-duration final cannot double-bill the same audio.
+   */
+  private emitSttUsage(contextId: string, duration: number | undefined): void {
+    if (typeof duration === "number" && Number.isFinite(duration) && duration > 0) {
+      const billed = this.billedDurationByContextId.get(contextId) ?? 0;
+      const audioSeconds = duration - billed;
+      if (audioSeconds <= 0) return;
+      this.billedDurationByContextId.set(contextId, duration);
+      // Keep byte marker in sync so a later final without offset does not double-bill.
+      this.billedBytesByContextId.set(contextId, this.sentBytesByContextId.get(contextId) ?? 0);
+      this.deps.sink.push(Route.Background, {
+        kind: "usage.recorded",
+        contextId,
+        timestampMs: this.now(),
+        stage: "stt",
+        provider: this.deps.provider.name,
+        model: this.deps.provider.model,
+        audioSeconds,
+      });
+      return;
+    }
+
+    const sampleRate = this.deps.format?.sampleRateHz;
+    if (!sampleRate || sampleRate <= 0) return;
+    const sent = this.sentBytesByContextId.get(contextId) ?? 0;
+    const billedBytes = this.billedBytesByContextId.get(contextId) ?? 0;
+    const newBytes = sent - billedBytes;
+    if (newBytes <= 0) return;
+    this.billedBytesByContextId.set(contextId, sent);
+    const audioSeconds = newBytes / 2 / sampleRate;
+    this.deps.sink.push(Route.Background, {
+      kind: "usage.recorded",
+      contextId,
+      timestampMs: this.now(),
+      stage: "stt",
+      provider: this.deps.provider.name,
+      model: this.deps.provider.model,
+      audioSeconds,
+    });
+  }
+
+  private emitError(contextId: string, err: Error): void {
+    const category = categorizeSttError(err);
+    const packet: SttErrorPacket = {
+      kind: "stt.error",
+      contextId,
+      timestampMs: this.now(),
+      component: "stt",
+      category,
+      cause: err,
+      isRecoverable: isRecoverable(category),
+    };
+    this.deps.sink.push(Route.Critical, packet);
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+
+export { createSttEngine, type SttEngine, type SttEngineDeps } from "./engine.js";
+export {
+  startStreamingSttSession,
+  defaultNodeSocketFactory,
+  type StreamingSttSpec,
+  type StreamingSttSession,
+} from "./session.js";
+export type {
+  SttEvent,
+  SttProtocolHost,
+  SttWireProtocol,
+  Transport,
+  PacketSink,
+} from "./types.js";

package/src/session.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: MIT
+//
+// Ergonomic factory: wires a provider `SttWireProtocol` into a running streaming-STT
+// session over a `WebSocketConnection`-backed transport, with standard PipelineBus wiring
+// (stt.audio → send, stt.finalize → encodeFinalize, turn.change / interrupt.stt context
+// bookkeeping). A provider's published `*STTPlugin` class delegates `initialize`/`close`
+// to this — its public surface is unchanged.
+
+import {
+  Route,
+  type AudioFormat,
+  type PipelineBus,
+  type RetryConfig,
+  type SttReconfigurePartial,
+} from "@kuralle-syrinx/core";
+import { WebSocketConnection, type SocketData, type SocketFactory } from "@kuralle-syrinx/ws";
+
+import { createSttEngine } from "./engine.js";
+import type { SttWireProtocol } from "./types.js";
+
+export interface StreamingSttSpec {
+  readonly protocol: SttWireProtocol;
+  readonly provider: { readonly name: string; readonly model: string; readonly region?: string };
+  readonly url: () => string;
+  readonly headers?: Record<string, string>;
+  readonly retry: RetryConfig;
+  readonly socketFactory: SocketFactory;
+  readonly emitEosOnFinal?: boolean;
+  readonly language?: string;
+  readonly format?: AudioFormat;
+  readonly maxReconnectAttempts?: number;
+  readonly connectTimeoutMs?: number;
+  readonly replayBufferSize?: number;
+  readonly keepAliveIntervalMs?: number;
+  readonly keepAliveMessage?: () => SocketData;
+  readonly metricPrefix?: string;
+}
+
+export interface StreamingSttSession {
+  dispose(): Promise<void>;
+  reconfigure(partial: SttReconfigurePartial): void;
+  reset(): void;
+}
+
+/** Open the provider socket, wire the bus, and return a handle whose `dispose()` tears it all down. */
+export async function startStreamingSttSession(
+  bus: PipelineBus,
+  spec: StreamingSttSpec,
+): Promise<StreamingSttSession> {
+  let conn: WebSocketConnection;
+  const metricPrefix = spec.metricPrefix ?? "stt";
+  const protocol = spec.protocol;
+  const engine = createSttEngine({
+    protocol,
+    transport: {
+      ensureReady: () => conn.ensureReady(),
+      send: (frame) => conn.send(frame),
+      close: () => conn.close(),
+      get isReady() {
+        return conn.isReady;
+      },
+      reset: () => {
+        conn.reset();
+      },
+    },
+    sink: { push: (route, packet) => bus.push(route, packet as Parameters<PipelineBus["push"]>[1]) },
+    provider: spec.provider,
+    emitEosOnFinal: spec.emitEosOnFinal ?? true,
+    language: spec.language ?? "en",
+    format: spec.format,
+  });
+
+  conn = new WebSocketConnection({
+    url: spec.url,
+    headers: spec.headers,
+    socketFactory: spec.socketFactory,
+    retry: spec.retry,
+    maxReconnectAttempts: spec.maxReconnectAttempts,
+    connectTimeoutMs: spec.connectTimeoutMs,
+    replayBufferSize: spec.replayBufferSize,
+    keepAliveIntervalMs: spec.keepAliveIntervalMs,
+    keepAliveMessage: spec.keepAliveMessage,
+    onMessage: (data, isBinary) => engine.onMessage(data, isBinary),
+    onConnectionLost: (err) => engine.onConnectionLost(err),
+    onUnrecoverable: (err) => engine.onConnectionLost(err),
+    onReadyBeforeReplay: () => {
+      for (const frame of protocol.onOpen?.() ?? []) conn.send(frame);
+    },
+    onReplay: (event, count) =>
+      bus.push(Route.Background, {
+        kind: "metric.conversation",
+        contextId: "",
+        timestampMs: Date.now(),
+        name: `${metricPrefix}.reconnect_replay_${event}`,
+        value: String(count),
+      }),
+  });
+  await conn.connect();
+
+  const disposers: Array<() => void> = [
+    // STT plugins consume `stt.audio` only — the canonical STT ingress. VoiceAgentSession
+    // fans `user.audio_received` out to `stt.audio` (handleUserAudio), so subscribing to both
+    // would double-send + double-bill every frame in a real session.
+    bus.on("stt.audio", (pkt: unknown) => {
+      const audioPkt = pkt as { audio: Uint8Array; contextId?: string };
+      void engine.onAudio(audioPkt.audio, audioPkt.contextId);
+    }),
+    bus.on("stt.finalize", (pkt: unknown) => {
+      const finalizePkt = pkt as { contextId?: string };
+      void engine.onFinalize(finalizePkt.contextId);
+    }),
+    bus.on("turn.change", (pkt: unknown) => {
+      engine.onTurnChange((pkt as { contextId: string }).contextId);
+    }),
+    bus.on("interrupt.stt", () => {
+      engine.onInterrupt();
+    }),
+  ];
+
+  return {
+    dispose: async () => {
+      for (const dispose of disposers.splice(0)) dispose();
+      await engine.close();
+    },
+    reconfigure: (partial: SttReconfigurePartial) => {
+      const frames = protocol.encodeReconfigure?.(partial) ?? [];
+      if (frames.length === 0) return;
+      for (const frame of frames) conn.send(frame);
+    },
+    reset: () => {
+      conn.reset();
+    },
+  };
+}
+
+/** Default Node socket factory — lazily imported so the heavy `ws` dep only loads when used. */
+export async function defaultNodeSocketFactory(): Promise<SocketFactory> {
+  const mod = await import("@kuralle-syrinx/ws/node");
+  return mod.createNodeWsSocket;
+}

package/src/types.ts

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: MIT
+//
+// Ports for the shared streaming-STT deep module. Provider adapters implement only
+// `SttWireProtocol`; the session owns the socket, bus wiring, and usage delta-billing.
+
+import type { Route, SttReconfigurePartial } from "@kuralle-syrinx/core";
+import type { SocketData } from "@kuralle-syrinx/ws";
+
+/**
+ * Decoded result of one inbound provider frame — a list, because a single frame can
+ * carry several aspects (or none).
+ *
+ * `audioSeconds` is the provider's per-turn (often cumulative-from-stream-start) duration
+ * signal used for billing at the final funnel; optional when the provider has no duration.
+ */
+export type SttEvent =
+  | {
+      readonly type: "interim";
+      readonly contextId: string;
+      readonly text: string;
+      readonly confidence?: number;
+      readonly wordTimings?: unknown;
+      readonly audioSeconds?: number;
+    }
+  | {
+      readonly type: "final";
+      readonly contextId: string;
+      readonly text: string;
+      readonly confidence?: number;
+      readonly wordTimings?: unknown;
+      readonly audioSeconds?: number;
+      /** When true with `emitEosOnFinal`, the session emits `eos.turn_complete`. */
+      readonly speechFinal?: boolean;
+      readonly language?: string;
+      /** Provider-specific fields merged into `stt.result.provider`. */
+      readonly provider?: Record<string, unknown>;
+    }
+  | {
+      readonly type: "speech_started";
+      readonly contextId?: string;
+    }
+  | {
+      readonly type: "partial";
+      readonly contextId?: string;
+      readonly text: string;
+      readonly wordTimings?: unknown;
+    }
+  | {
+      readonly type: "eos_interim";
+      readonly contextId?: string;
+      readonly text: string;
+    }
+  | {
+      readonly type: "eos_retracted";
+      readonly contextId?: string;
+    }
+  | {
+      readonly type: "error";
+      readonly contextId?: string;
+      readonly error: Error;
+    }
+  | {
+      /** Eos-only commit after per-segment `final` results (e.g. Deepgram nova turn complete). */
+      readonly type: "turn_complete";
+      readonly contextId?: string;
+      readonly text: string;
+    }
+  | { readonly type: "ignore" };
+
+/** Host the engine injects so a protocol can emit events or force reconnect outside decode. */
+export interface SttProtocolHost {
+  /** Routes through engine.dispatch (same funnel as a decoded event: billing/eos/etc.). */
+  emit(event: SttEvent): void;
+  /** Force a transport reconnect (e.g. after repeated finalize timeouts). */
+  reset(): void;
+}
+
+/**
+ * DRIVEN PORT — provider wire protocol. Pure of sockets and the bus. This is the only
+ * surface a provider implements; connection lifecycle + funnel live in the session.
+ */
+export interface SttWireProtocol {
+  /** Encode the "no more audio for this turn" frame(s). `[]` if the provider has none. */
+  encodeFinalize(contextId: string): readonly SocketData[];
+  /** Optional session-teardown frame(s) sent best-effort on dispose. */
+  encodeClose?(): readonly SocketData[];
+  /**
+   * Optional wire encoding for outbound PCM. Default when unset: send raw `[audio]`
+   * (Grok / Deepgram / Google / Flux). ElevenLabs JSON-wraps each chunk.
+   */
+  encodeAudio?(audio: Uint8Array): readonly SocketData[];
+  /** Optional config/handshake frame(s) sent on every (re)connect before replay. */
+  onOpen?(): readonly SocketData[];
+  /** Optional mid-stream reconfigure frame(s) (e.g. Flux Configure). */
+  encodeReconfigure?(partial: SttReconfigurePartial): readonly SocketData[];
+  /** Decode one inbound socket frame into domain events (0+). Throwing is treated as fatal. */
+  decode(data: SocketData, isBinary: boolean): readonly SttEvent[];
+  /**
+   * When false, outbound audio is dropped without error (e.g. awaiting provider handshake
+   * like Grok's `transcript.created`). Default true when omitted.
+   */
+  isReady?(): boolean;
+  /** Optional: provider handshake state that must reset on socket drop (e.g. clear ready). */
+  onConnectionLost?(): void;
+  /**
+   * Optional host injection at engine construction. Protocols with async timers (e.g. nova
+   * Finalize timeout → fallback final / reconnect) use `host.emit` / `host.reset`.
+   */
+  attach?(host: SttProtocolHost): void;
+  /**
+   * Optional: called after encodeFinalize frames were sent (transport ready). Nova starts
+   * its provider-finalize timeout here.
+   */
+  onFinalizeSent?(contextId: string): void;
+}
+
+/** DRIVEN PORT — transport. Production wraps a `WebSocketConnection`; tests pass a fake. */
+export interface Transport {
+  ensureReady(): Promise<void>;
+  send(frame: SocketData): void;
+  close(): Promise<void>;
+  readonly isReady?: boolean;
+  /** Optional force-reconnect (session wires `conn.reset`). */
+  reset?(): void;
+}
+
+/** The bus, narrowed to the one method the engine needs. Injectable for socket-free tests. */
+export interface PacketSink {
+  push(route: Route, packet: unknown): void;
+}