@kuralle-syrinx/core 4.4.0 → 4.5.0

package/dist/retry.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+export const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    baseDelayMs: 250,
+    maxDelayMs: 2000,
+};
+/**
+ * Retry profile for long-lived voice-provider WebSockets (STT/TTS).
+ *
+ * Keeps the SAME fast first reconnect as the default (~125-250 ms) so a transient
+ * blip during a live call recovers without dead air, but raises the backoff cap to
+ * 10 s and allows more attempts so a persistent provider failure (rate limit /
+ * outage) is retried patiently instead of giving up after ~2 s. This intentionally
+ * does NOT use a multi-second *floor* (a 4 s first-retry would mean seconds of dead
+ * air on a live call); "every 10 ms matters" applies to the first reconnect, patient
+ * backoff applies only after repeated failures.
+ */
+export const VOICE_PROVIDER_RETRY_CONFIG = {
+    maxAttempts: 6,
+    baseDelayMs: 250,
+    maxDelayMs: 10_000,
+};
+export const VOICE_PROVIDER_OUTAGE_RETRY_CONFIG = {
+    maxAttempts: 4,
+    baseDelayMs: 4_000,
+    maxDelayMs: 10_000,
+};
+export function readRetryConfig(config) {
+    return readRetryConfigWithDefaults(config, DEFAULT_RETRY_CONFIG);
+}
+/** Read retry config for a voice-provider WebSocket; defaults to the patient-backoff profile. */
+export function readProviderRetryConfig(config) {
+    const profile = typeof config["retry_profile"] === "string" ? config["retry_profile"] : "";
+    return readRetryConfigWithDefaults(config, profile === "provider_outage" ? VOICE_PROVIDER_OUTAGE_RETRY_CONFIG : VOICE_PROVIDER_RETRY_CONFIG);
+}
+function readRetryConfigWithDefaults(config, defaults) {
+    return {
+        maxAttempts: readPositiveInteger(config["retry_max_attempts"], defaults.maxAttempts),
+        baseDelayMs: readPositiveInteger(config["retry_base_delay_ms"], defaults.baseDelayMs),
+        maxDelayMs: readPositiveInteger(config["retry_max_delay_ms"], defaults.maxDelayMs),
+    };
+}
+export function retryDelayMs(attemptIndex, config) {
+    const exponential = config.baseDelayMs * 2 ** Math.max(0, attemptIndex - 1);
+    return Math.min(config.maxDelayMs, exponential);
+}
+/**
+ * Equal-jitter backoff: half the deterministic exponential delay plus a random half.
+ * Spreads out retries so many sessions hitting the same provider rate/concurrency limit
+ * at once don't reconnect in lockstep (thundering herd). `rng` is injectable for tests.
+ */
+export function retryDelayWithJitterMs(attemptIndex, config, rng = Math.random) {
+    const base = retryDelayMs(attemptIndex, config);
+    const half = base / 2;
+    return Math.round(half + rng() * half);
+}
+export async function waitForRetryDelay(attemptIndex, config, signal) {
+    const delayMs = retryDelayWithJitterMs(attemptIndex, config);
+    await new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        const timeout = setTimeout(resolve, delayMs);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(abortError());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function abortError() {
+    const err = new Error("Retry aborted");
+    err.name = "AbortError";
+    return err;
+}
+function readPositiveInteger(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    const integer = Math.floor(value);
+    return integer > 0 ? integer : fallback;
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/scheduler.d.ts

@@ -0,0 +1,11 @@
+export type ScheduledCallback = () => void | Promise<void>;
+export interface Scheduler {
+    schedule(key: string, delayMs: number, cb: ScheduledCallback): void;
+    cancel(key: string): void;
+}
+export declare class TimerScheduler implements Scheduler {
+    private readonly timers;
+    schedule(key: string, delayMs: number, cb: ScheduledCallback): void;
+    cancel(key: string): void;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoD;IAE3E,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,iBAAiB,GAAG,IAAI;IASnE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAM1B"}

package/dist/scheduler.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+export class TimerScheduler {
+    timers = new Map();
+    schedule(key, delayMs, cb) {
+        this.cancel(key);
+        const timer = setTimeout(() => {
+            this.timers.delete(key);
+            void cb();
+        }, Math.max(0, delayMs));
+        this.timers.set(key, timer);
+    }
+    cancel(key) {
+        const timer = this.timers.get(key);
+        if (!timer)
+            return;
+        clearTimeout(timer);
+        this.timers.delete(key);
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAS/B,MAAM,OAAO,cAAc;IACR,MAAM,GAAG,IAAI,GAAG,EAAyC,CAAC;IAE3E,QAAQ,CAAC,GAAW,EAAE,OAAe,EAAE,EAAqB;QAC1D,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,KAAK,EAAE,EAAE,CAAC;QACZ,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/spend-cap.d.ts

@@ -0,0 +1,27 @@
+import type { UsageRecordedPacket } from "./packets.js";
+import { type PriceCatalog } from "./pricing.js";
+export interface SpendCapConfig {
+    readonly maxUsd: number;
+    readonly catalog?: PriceCatalog;
+}
+export interface SpendCapCheck {
+    readonly exceeded: boolean;
+    readonly spentUsd: number;
+}
+/**
+ * Accumulates priced `usage.recorded` into session spend and reports whether a
+ * configured USD cap has been breached. Does not call providers; the session
+ * layer decides refuse/fallback from `check()`.
+ */
+export declare class SpendCapGuard {
+    private readonly maxUsd;
+    private readonly catalog;
+    private spentUsd;
+    private exceeded;
+    constructor(cfg: SpendCapConfig);
+    /** Observe one usage packet. Unpriced usage does not change spentUsd. */
+    record(usage: UsageRecordedPacket): void;
+    /** Read-only policy view — never mutates spend. */
+    check(): SpendCapCheck;
+}
+//# sourceMappingURL=spend-cap.d.ts.map

package/dist/spend-cap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-cap.d.ts","sourceRoot":"","sources":["../src/spend-cap.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEhF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAS;gBAEb,GAAG,EAAE,cAAc;IAQ/B,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;IASxC,mDAAmD;IACnD,KAAK,IAAI,aAAa;CAGvB"}

package/dist/spend-cap.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+//
+// Pure spend accumulator + policy. Observe (record) and control (check) are
+// separated so the same usage packet is never double-counted by the guard.
+import { costOf, DEFAULT_PRICE_CATALOG } from "./pricing.js";
+/**
+ * Accumulates priced `usage.recorded` into session spend and reports whether a
+ * configured USD cap has been breached. Does not call providers; the session
+ * layer decides refuse/fallback from `check()`.
+ */
+export class SpendCapGuard {
+    maxUsd;
+    catalog;
+    spentUsd = 0;
+    exceeded = false;
+    constructor(cfg) {
+        if (!Number.isFinite(cfg.maxUsd) || cfg.maxUsd < 0) {
+            throw new Error(`SpendCapGuard maxUsd must be a non-negative finite number, got ${String(cfg.maxUsd)}`);
+        }
+        this.maxUsd = cfg.maxUsd;
+        this.catalog = cfg.catalog ?? DEFAULT_PRICE_CATALOG;
+    }
+    /** Observe one usage packet. Unpriced usage does not change spentUsd. */
+    record(usage) {
+        const result = costOf(usage, this.catalog);
+        if (result.usd === null)
+            return;
+        this.spentUsd += result.usd;
+        if (this.spentUsd > this.maxUsd) {
+            this.exceeded = true;
+        }
+    }
+    /** Read-only policy view — never mutates spend. */
+    check() {
+        return { exceeded: this.exceeded, spentUsd: this.spentUsd };
+    }
+}
+//# sourceMappingURL=spend-cap.js.map

package/dist/spend-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-cap.js","sourceRoot":"","sources":["../src/spend-cap.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAG3E,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAqB,MAAM,cAAc,CAAC;AAYhF;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACP,MAAM,CAAS;IACf,OAAO,CAAe;IAC/B,QAAQ,GAAG,CAAC,CAAC;IACb,QAAQ,GAAG,KAAK,CAAC;IAEzB,YAAY,GAAmB;QAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,kEAAkE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC1G,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,qBAAqB,CAAC;IACtD,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,KAA0B;QAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,MAAM,CAAC,GAAG,KAAK,IAAI;YAAE,OAAO;QAChC,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC;QAC5B,IAAI,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED,mDAAmD;IACnD,KAAK;QACH,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC9D,CAAC;CACF"}

package/dist/tts-playout-clock.d.ts

@@ -0,0 +1,43 @@
+import { type Scheduler } from "./scheduler.js";
+export declare class TtsPlayoutClock {
+    private readonly scheduler;
+    private readonly active;
+    private readonly playoutEndMs;
+    private readonly releaseTimers;
+    private readonly realPlayoutContexts;
+    private readonly playedOutMsByContext;
+    constructor(scheduler?: Scheduler);
+    /**
+     * A TTS audio chunk arrived: mark the context active and advance its playout
+     * cursor by the chunk's realtime duration, anchored to `nowMs` if the previous
+     * estimate already lapsed (a gap in delivery).
+     */
+    noteAudio(contextId: string, audioDurationMs: number, nowMs: number): void;
+    /**
+     * Generation finished (tts.end). Keep the context interruptible until its
+     * playout estimate elapses, then release it. Releases immediately if the
+     * estimate has already passed.
+     */
+    scheduleRelease(contextId: string, nowMs: number): void;
+    /**
+     * Transport reported realtime playout progress for a context. Real playout is
+     * authoritative once seen; release the context when it reports complete.
+     */
+    noteProgress(contextId: string, complete: boolean, playedOutMs?: number): void;
+    positionMs(contextId: string): number | undefined;
+    release(contextId: string): void;
+    isActive(contextId: string): boolean;
+    /** All still-active contexts, insertion order (oldest first). */
+    activeContexts(): string[];
+    /**
+     * Wall-clock estimate of when this context's audio finishes playing out, or
+     * undefined if unknown. Anchors the idle timer to real playout end rather than
+     * chunk-arrival (TTS streams faster than realtime).
+     */
+    playoutEnd(contextId: string): number | undefined;
+    /** The most-recently-added still-active context (insertion order), or "" if none. */
+    latestActive(): string;
+    clear(): void;
+    private cancelRelease;
+}
+//# sourceMappingURL=tts-playout-clock.d.ts.map

package/dist/tts-playout-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-playout-clock.d.ts","sourceRoot":"","sources":["../src/tts-playout-clock.ts"],"names":[],"mappings":"AAYA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhE,qBAAa,eAAe;IAYd,OAAO,CAAC,QAAQ,CAAC,SAAS;IAXtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAE5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IAKnD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;gBAErC,SAAS,GAAE,SAAgC;IAExE;;;;OAIG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAO1E;;;;OAIG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAoBvD;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAM9E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIjD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQhC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIpC,iEAAiE;IACjE,cAAc,IAAI,MAAM,EAAE;IAI1B;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIjD,qFAAqF;IACrF,YAAY,IAAI,MAAM;IAMtB,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,aAAa;CAKtB"}

package/dist/tts-playout-clock.js

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — TTS Playout Clock
+//
+// Tracks when each context's streamed TTS audio finishes *playing out* (not just
+// generating). TTS streams faster than realtime, so generation (tts.end) ends
+// well before playout; turn-taking keys on these estimates so the assistant
+// stays interruptible until it is actually done being heard.
+//
+// Pure state + timers — no bus, no other session coupling. The orchestrator owns
+// wiring; this owns the playout bookkeeping.
+import { TimerScheduler } from "./scheduler.js";
+export class TtsPlayoutClock {
+    scheduler;
+    active = new Set();
+    // Wall-clock estimate of when each context's audio finishes playing out.
+    playoutEndMs = new Map();
+    releaseTimers = new Set();
+    // Contexts for which the output transport has reported real playout progress.
+    // When present, the transport's `complete` signal is authoritative and the
+    // sample-duration estimate defers to it (it is only a fallback for transports
+    // without a paced-playout layer, e.g. headless).
+    realPlayoutContexts = new Set();
+    playedOutMsByContext = new Map();
+    constructor(scheduler = new TimerScheduler()) {
+        this.scheduler = scheduler;
+    }
+    /**
+     * A TTS audio chunk arrived: mark the context active and advance its playout
+     * cursor by the chunk's realtime duration, anchored to `nowMs` if the previous
+     * estimate already lapsed (a gap in delivery).
+     */
+    noteAudio(contextId, audioDurationMs, nowMs) {
+        this.cancelRelease(contextId);
+        this.active.add(contextId);
+        const base = Math.max(nowMs, this.playoutEndMs.get(contextId) ?? nowMs);
+        this.playoutEndMs.set(contextId, base + audioDurationMs);
+    }
+    /**
+     * Generation finished (tts.end). Keep the context interruptible until its
+     * playout estimate elapses, then release it. Releases immediately if the
+     * estimate has already passed.
+     */
+    scheduleRelease(contextId, nowMs) {
+        const playoutEndMs = this.playoutEndMs.get(contextId);
+        const remainingMs = playoutEndMs === undefined ? 0 : playoutEndMs - nowMs;
+        if (remainingMs <= 0) {
+            this.release(contextId);
+            return;
+        }
+        this.cancelRelease(contextId);
+        this.releaseTimers.add(contextId);
+        this.scheduler.schedule(releaseKey(contextId), remainingMs, () => {
+            this.releaseTimers.delete(contextId);
+            // If a paced transport is reporting real playout for this context, it
+            // owns the release via noteProgress({complete}) — the estimate must not
+            // pre-empt it (real playout can run past the audio length under
+            // send-buffer backpressure). Session close() is the backstop.
+            if (this.realPlayoutContexts.has(contextId))
+                return;
+            this.release(contextId);
+        });
+    }
+    /**
+     * Transport reported realtime playout progress for a context. Real playout is
+     * authoritative once seen; release the context when it reports complete.
+     */
+    noteProgress(contextId, complete, playedOutMs) {
+        this.realPlayoutContexts.add(contextId);
+        if (playedOutMs !== undefined)
+            this.playedOutMsByContext.set(contextId, playedOutMs);
+        if (complete)
+            this.release(contextId);
+    }
+    positionMs(contextId) {
+        return this.playedOutMsByContext.get(contextId);
+    }
+    release(contextId) {
+        this.cancelRelease(contextId);
+        this.active.delete(contextId);
+        this.playoutEndMs.delete(contextId);
+        this.realPlayoutContexts.delete(contextId);
+        this.playedOutMsByContext.delete(contextId);
+    }
+    isActive(contextId) {
+        return this.active.has(contextId);
+    }
+    /** All still-active contexts, insertion order (oldest first). */
+    activeContexts() {
+        return [...this.active];
+    }
+    /**
+     * Wall-clock estimate of when this context's audio finishes playing out, or
+     * undefined if unknown. Anchors the idle timer to real playout end rather than
+     * chunk-arrival (TTS streams faster than realtime).
+     */
+    playoutEnd(contextId) {
+        return this.playoutEndMs.get(contextId);
+    }
+    /** The most-recently-added still-active context (insertion order), or "" if none. */
+    latestActive() {
+        let latest = "";
+        for (const contextId of this.active)
+            latest = contextId;
+        return latest;
+    }
+    clear() {
+        for (const contextId of [...this.releaseTimers])
+            this.cancelRelease(contextId);
+        this.active.clear();
+        this.playoutEndMs.clear();
+        this.realPlayoutContexts.clear();
+        this.playedOutMsByContext.clear();
+    }
+    cancelRelease(contextId) {
+        if (!this.releaseTimers.has(contextId))
+            return;
+        this.scheduler.cancel(releaseKey(contextId));
+        this.releaseTimers.delete(contextId);
+    }
+}
+function releaseKey(contextId) {
+    return `voice.tts_playout.release:${contextId}`;
+}
+//# sourceMappingURL=tts-playout-clock.js.map

package/dist/tts-playout-clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-playout-clock.js","sourceRoot":"","sources":["../src/tts-playout-clock.ts"],"names":[],"mappings":"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"}

package/dist/turn-arbiter.d.ts

@@ -0,0 +1,41 @@
+import { type PipelineBus } from "./pipeline-bus.js";
+import type { VadAudioPacket, VadSpeechActivityPacket, VadSpeechEndedPacket, VadSpeechStartedPacket } from "./packets.js";
+import { PrimarySpeakerGate } from "./primary-speaker-gate.js";
+import { TtsPlayoutClock } from "./tts-playout-clock.js";
+export declare function isBackchannel(text: string): boolean;
+export declare function isAcknowledgement(text: string, phrases: readonly string[]): boolean;
+export interface TurnArbiterDeps {
+    readonly bus: PipelineBus;
+    readonly primarySpeakerGate: PrimarySpeakerGate;
+    readonly ttsPlayout: TtsPlayoutClock;
+    readonly minInterruptionMs: number;
+    readonly onInterrupt?: (interruptedContextId: string, source: "vad") => void;
+    /** When true, emit `interaction.duck` while evaluating a barge-in during active TTS,
+     *  and `interaction.resume` if the pending window resolves without an interrupt. */
+    readonly pauseThenResolveBargeIn?: boolean;
+}
+export declare class TurnArbiter {
+    private readonly deps;
+    private turnInterruption;
+    private latestInterimText;
+    private latestInterimConfidence;
+    private ducked;
+    constructor(deps: TurnArbiterDeps);
+    noteInterimEvidence(text: string, confidence?: number): void;
+    onSpeechStarted(pkt: VadSpeechStartedPacket, interruptedContextId: string): void;
+    onSpeechActivity(pkt: VadSpeechActivityPacket): void;
+    onProviderSttEvidence(userContextId: string, timestampMs: number, interruptedContextId: string): void;
+    onSpeechEnded(pkt: VadSpeechEndedPacket, hasActiveTts: boolean): void;
+    observeBargeInAudio(pkt: VadAudioPacket): boolean;
+    emitInterruptDetected(interruptedContextId: string): void;
+    commitClientInterrupt(interruptedContextId: string): void;
+    clear(): void;
+    private pendingFor;
+    private transitionToPending;
+    private setAwaitingAudio;
+    private shouldDeferImmediateBargeInForSpeakerGate;
+    private tryCommit;
+    private decideInterrupt;
+    private suppress;
+}
+//# sourceMappingURL=turn-arbiter.d.ts.map

package/dist/turn-arbiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-arbiter.d.ts","sourceRoot":"","sources":["../src/turn-arbiter.ts"],"names":[],"mappings":"AAIA,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EACV,cAAc,EACd,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAuCzD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQnD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAenF;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,oBAAoB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,KAAK,IAAI,CAAC;IAC7E;wFACoF;IACpF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAC5C;AAED,qBAAa,WAAW;IAMV,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,gBAAgB,CAA2C;IACnE,OAAO,CAAC,iBAAiB,CAAM;IAC/B,OAAO,CAAC,uBAAuB,CAAuB;IACtD,OAAO,CAAC,MAAM,CAAS;gBAEM,IAAI,EAAE,eAAe;IAElD,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAK5D,eAAe,CAAC,GAAG,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,GAAG,IAAI;IAqBhF,gBAAgB,CAAC,GAAG,EAAE,uBAAuB,GAAG,IAAI;IAYpD,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,IAAI;IAUrG,aAAa,CAAC,GAAG,EAAE,oBAAoB,EAAE,YAAY,EAAE,OAAO,GAAG,IAAI;IAyBrE,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO;IAYjD,qBAAqB,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI;IAIzD,qBAAqB,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI;IAWzD,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,mBAAmB;IAwB3B,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,yCAAyC;IAKjD,OAAO,CAAC,SAAS;IA+CjB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,QAAQ;CAuBjB"}