xo-harness 0.2.0 → 0.3.0

package/dist/internal/harness/runtime-limits.d.ts

@@ -0,0 +1,18 @@
+/** Opt-in per-session limits. Omitted fields preserve full replay and unlimited storage waits. */
+export interface SessionRuntimeLimits {
+    /** Oldest events are evicted together; lagging readers receive EventReplayUnavailableError. */
+    maxReplayEvents?: number;
+    /** PCM bytes retained in the shared replay window, independent of the EventStore's retention. */
+    maxReplayAudioBytes?: number;
+    /** Maximum underlying appends in flight. Overflow fails the session instead of dropping records. */
+    maxPendingAppends?: number;
+    /** PCM bytes held by underlying appends, independent of chunk size. */
+    maxPendingAudioBytes?: number;
+    /** Deadline for each store operation. A timeout does not cancel an underlying external write. */
+    persistenceTimeoutMs?: number;
+}
+export declare class SessionPersistenceError extends Error {
+    readonly code: "persistence_failed" | "persistence_timeout" | "pending_appends_exceeded" | "pending_audio_bytes_exceeded";
+    constructor(code: "persistence_failed" | "persistence_timeout" | "pending_appends_exceeded" | "pending_audio_bytes_exceeded", message: string, options?: ErrorOptions);
+}
+export declare function validateRuntimeLimits(limits?: SessionRuntimeLimits): Readonly<SessionRuntimeLimits>;

package/dist/internal/harness/runtime-limits.js

@@ -0,0 +1,19 @@
+export class SessionPersistenceError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "SessionPersistenceError";
+    }
+}
+export function validateRuntimeLimits(limits = {}) {
+    for (const [key, value] of Object.entries(limits)) {
+        if (value === undefined)
+            continue;
+        const minimum = key.endsWith("Bytes") || key === "maxReplayEvents" ? 0 : 1;
+        const maximum = key === "persistenceTimeoutMs" ? 2_147_483_647 : Number.MAX_SAFE_INTEGER;
+        if (!Number.isSafeInteger(value) || value < minimum || value > maximum)
+            throw new Error(`${key} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return Object.freeze({ ...limits });
+}

package/dist/internal/harness/session-persistence.d.ts

@@ -0,0 +1,16 @@
+import type { HarnessEvent, HarnessRecord, UnsequencedHarnessEvent } from "../protocol/index.js";
+import type { EventStore } from "../storage/index.js";
+import { SessionPersistenceError, type SessionRuntimeLimits } from "./runtime-limits.js";
+/** Session-local admission/deadlines around the host store; never bypasses durable publication. */
+export declare class SessionPersistence implements EventStore {
+    #private;
+    onFailure: ((error: SessionPersistenceError) => void) | undefined;
+    constructor(store: EventStore, limits: Readonly<SessionRuntimeLimits>);
+    stats(): {
+        pendingAppends: number;
+        pendingAppendAudioBytes: number;
+    };
+    append(event: UnsequencedHarnessEvent): Promise<HarnessEvent>;
+    flush(sessionId: string): Promise<void>;
+    list(sessionId: string): Promise<readonly HarnessRecord[]>;
+}

package/dist/internal/harness/session-persistence.js

@@ -0,0 +1,106 @@
+import { SessionPersistenceError } from "./runtime-limits.js";
+/** Session-local admission/deadlines around the host store; never bypasses durable publication. */
+export class SessionPersistence {
+    #store;
+    #limits;
+    #pendingAppends = 0;
+    #pendingAudioBytes = 0;
+    #failure;
+    #failureWaiters = new Set();
+    onFailure;
+    constructor(store, limits) {
+        this.#store = store;
+        this.#limits = limits;
+    }
+    stats() {
+        return { pendingAppends: this.#pendingAppends, pendingAppendAudioBytes: this.#pendingAudioBytes };
+    }
+    append(event) {
+        if (this.#failure)
+            return Promise.reject(this.#failure);
+        if (this.#pendingAppends >= (this.#limits.maxPendingAppends ?? Infinity))
+            return Promise.reject(this.#fail(new SessionPersistenceError("pending_appends_exceeded", `Pending event appends exceeded ${this.#limits.maxPendingAppends}; session recording is incomplete`)));
+        const bytes = event.type === "audio.input" || event.type === "audio.output" ? event.chunk.data.byteLength : 0;
+        if (this.#pendingAudioBytes + bytes > (this.#limits.maxPendingAudioBytes ?? Infinity))
+            return Promise.reject(this.#fail(new SessionPersistenceError("pending_audio_bytes_exceeded", `Pending audio appends exceeded ${this.#limits.maxPendingAudioBytes} bytes; session recording is incomplete`)));
+        this.#pendingAppends++;
+        this.#pendingAudioBytes += bytes;
+        // Invoke synchronously: the store reserves ordering before any provider forwarding.
+        let append;
+        try {
+            append = this.#store.append(event);
+        }
+        catch (error) {
+            append = Promise.reject(this.#operationFailed(error, "append"));
+        }
+        const settled = append.finally(() => {
+            // Counts underlying writes, including writes still outstanding after a deadline.
+            this.#pendingAppends--;
+            this.#pendingAudioBytes -= bytes;
+        });
+        return this.#observe(settled, "append");
+    }
+    flush(sessionId) {
+        return this.#call(() => this.#store.flush(sessionId), "flush");
+    }
+    list(sessionId) {
+        return this.#call(() => this.#store.list(sessionId), "list");
+    }
+    #call(operation, label) {
+        if (this.#failure)
+            return Promise.reject(this.#failure);
+        try {
+            return this.#observe(operation(), label);
+        }
+        catch (error) {
+            return Promise.reject(this.#operationFailed(error, label));
+        }
+    }
+    async #observe(operation, label) {
+        let timer;
+        let rejectFailure;
+        try {
+            const timeout = this.#limits.persistenceTimeoutMs;
+            const pending = [operation];
+            pending.push(new Promise((_resolve, reject) => {
+                if (this.#failure)
+                    reject(this.#failure);
+                else {
+                    rejectFailure = reject;
+                    this.#failureWaiters.add(reject);
+                }
+            }));
+            if (timeout !== undefined)
+                pending.push(new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(this.#fail(new SessionPersistenceError("persistence_timeout", `EventStore ${label} exceeded ${timeout} ms; persistence remains unconfirmed`))), timeout);
+                }));
+            const value = await Promise.race(pending);
+            if (this.#failure)
+                throw this.#failure;
+            return value;
+        }
+        catch (error) {
+            throw this.#operationFailed(error, label);
+        }
+        finally {
+            clearTimeout(timer);
+            if (rejectFailure)
+                this.#failureWaiters.delete(rejectFailure);
+        }
+    }
+    #operationFailed(error, label) {
+        return this.#fail(error instanceof SessionPersistenceError
+            ? error
+            : new SessionPersistenceError("persistence_failed", `EventStore ${label} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error }));
+    }
+    #fail(error) {
+        if (!this.#failure) {
+            this.#failure = error;
+            for (const reject of this.#failureWaiters)
+                reject(error);
+            this.#failureWaiters.clear();
+            this.onFailure?.(error);
+        }
+        return this.#failure;
+    }
+}

package/dist/internal/harness/shadow.d.ts

@@ -1,4 +1,4 @@
-import type { HarnessEvent } from "../protocol/index.js";
+import { type HarnessRecord } from "../protocol/index.js";
 import type { VoiceProvider } from "../provider/index.js";
 import { type EventStore } from "../storage/memory.js";
 import { type SessionReport } from "./report.js";
@@ -6,7 +6,7 @@ import type { ToolPolicy } from "./tool-policy.js";
 import type { VoiceTool } from "./tools.js";
 export interface ShadowRunOptions {
     /** The recorded session whose microphone audio is re-driven. */
-    events: readonly HarnessEvent[];
+    events: readonly HarnessRecord[];
     /** The provider to shadow-test with the recorded input. */
     provider: VoiceProvider;
     /** Tools to execute during the shadow run; use substitutes when side effects are unwanted. */
@@ -20,7 +20,7 @@ export interface ShadowRunOptions {
     sessionId?: string;
     /** Defaults to the recorded session's instructions. */
     instructions?: string;
-    /** The run settles once the provider has produced audio and then stayed quiet this long. */
+    /** Waits this long after meaningful output, with no pending backend, tool, or task work. */
     quietMs?: number;
     timeoutMs?: number;
 }
@@ -29,7 +29,7 @@ export interface ShadowRunOptions {
  * provider and returns the resulting session report for comparison with the original.
  * The shadow run executes supplied tools and applies only the policy provided here;
  * a recording's denials do not establish permissions for a new session.
- * Input is sent as fast as the provider accepts it; server-side VAD sees the recorded
- * speech and trailing silence exactly as the original session did.
+ * Continuous-input providers receive paced PCM and silence through settlement.
+ * Other providers retain the existing push-input behavior.
  */
 export declare function runShadowSession(options: ShadowRunOptions): Promise<SessionReport>;

package/dist/internal/harness/shadow.js

@@ -1,22 +1,35 @@
+import { PacedAudioInput, requireRecordedAudioHistory, } from "../protocol/index.js";
 import { MemoryEventStore } from "../storage/memory.js";
 import { summarizeSession } from "./report.js";
+import { ToolCallTracker } from "./tool-calls.js";
 import { XO } from "./xo.js";
 /**
  * The silent-test primitive: re-drives a recorded session's input audio against another
  * provider and returns the resulting session report for comparison with the original.
  * The shadow run executes supplied tools and applies only the policy provided here;
  * a recording's denials do not establish permissions for a new session.
- * Input is sent as fast as the provider accepts it; server-side VAD sees the recorded
- * speech and trailing silence exactly as the original session did.
+ * Continuous-input providers receive paced PCM and silence through settlement.
+ * Other providers retain the existing push-input behavior.
  */
 export async function runShadowSession(options) {
     const recordedStart = options.events.find((event) => event.type === "session.started");
-    const inputs = options.events.filter((event) => event.type === "audio.input");
-    if (inputs.length === 0)
+    // Validate every required input before opening a provider or executing tools.
+    const inputs = requireRecordedAudioHistory(options.events.filter((event) => event.type === "audio.input")).filter((event) => event.type === "audio.input");
+    const firstInput = inputs[0];
+    if (!firstInput)
         throw new Error("Recorded session has no input audio to re-drive");
     const instructions = options.instructions ?? recordedStart?.instructions;
     const quietMs = options.quietMs ?? 3_000;
     const timeoutMs = options.timeoutMs ?? 60_000;
+    if (!Number.isFinite(quietMs) || quietMs < 0 || !Number.isFinite(timeoutMs) || timeoutMs < 1) {
+        throw new Error("Shadow quietMs must be nonnegative and timeoutMs must be positive and finite");
+    }
+    const continuousInput = options.provider.capabilities.inputCadence === "continuous";
+    const continuousOutput = options.provider.capabilities.outputLifecycle === "continuous";
+    if (continuousInput &&
+        inputs.some((input) => input.chunk.channels !== 1 || input.chunk.sampleRate !== firstInput.chunk.sampleRate)) {
+        throw new Error("Continuous shadow input requires one consistent mono PCM sample rate");
+    }
     const harness = new XO({
         store: options.store ?? new MemoryEventStore(),
         ...(options.tools === undefined ? {} : { tools: options.tools }),
@@ -29,18 +42,130 @@ export async function runShadowSession(options) {
         ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
         ...(instructions === undefined ? {} : { instructions }),
     });
+    const deadline = performance.now() + timeoutMs;
+    const inputController = new AbortController();
+    let pacedInput;
+    let closeReason = "shadow_complete";
+    const inputDeadline = setTimeout(() => {
+        closeReason = "shadow_timeout";
+        inputController.abort(new Error("Shadow input exceeded the run deadline"));
+    }, timeoutMs);
     try {
-        await waitForReady(session, timeoutMs);
-        for (const input of inputs) {
-            await session.sendAudio(input.chunk);
+        await waitOrAbort(session.waitUntilReady(), inputController.signal);
+        if (continuousInput) {
+            const sampleRate = firstInput.chunk.sampleRate;
+            let sequence = 0;
+            let startSample = 0;
+            let frameSubmitted = Promise.withResolvers();
+            pacedInput = new PacedAudioInput({
+                sampleRate,
+                signal: inputController.signal,
+                send: async (data, syntheticSilence) => {
+                    const chunk = {
+                        streamId: "shadow-input",
+                        sequence: sequence++,
+                        encoding: "pcm_s16le",
+                        sampleRate,
+                        channels: 1,
+                        startSample,
+                        data: Uint8Array.from(data),
+                    };
+                    await session.sendAudio(chunk, { syntheticSilence });
+                    startSample += data.byteLength / 2;
+                    const submitted = frameSubmitted;
+                    frameSubmitted = Promise.withResolvers();
+                    submitted.resolve();
+                },
+            });
+            // A rejected input clock must not become an unhandled rejection while the
+            // recording is waiting for its next source timestamp.
+            void pacedInput.done.catch((error) => inputController.abort(error));
+            await driveContinuousInput(inputs, pacedInput, deadline, recordedStart?.capabilities.inputCadence !== "continuous", async (targetSample) => {
+                while (startSample < targetSample)
+                    await waitOrAbort(frameSubmitted.promise, inputController.signal);
+            });
         }
-        await settleAfterOutput(session, quietMs, timeoutMs);
+        else {
+            for (const input of inputs)
+                await session.sendAudio(input.chunk);
+        }
+        const settlement = settleAfterOutput(session, quietMs, deadline, continuousOutput);
+        const result = await (pacedInput
+            ? Promise.race([settlement, pacedInput.done.then(() => "closed")])
+            : settlement);
+        if (result === "timeout")
+            closeReason = "shadow_timeout";
     }
     finally {
-        await session.close("shadow_complete");
+        clearTimeout(inputDeadline);
+        inputController.abort("shadow_complete");
+        await pacedInput?.done.catch(() => undefined);
+        await session.close(closeReason);
     }
     return summarizeSession(await session.history());
 }
+async function driveContinuousInput(inputs, pacedInput, deadline, preserveCapturePauses, waitUntilSample) {
+    const first = inputs[0];
+    if (!first)
+        return;
+    const sourceStart = first.sessionTimeMs - (first.chunk.data.byteLength / 2 / first.chunk.sampleRate) * 1000;
+    const frameSamples = Math.round(first.chunk.sampleRate / 10);
+    const streams = new Map();
+    let frame = new Uint8Array(frameSamples * 2);
+    let filled = 0;
+    let position = 0;
+    let hasSourceAudio = false;
+    const flushFrame = async () => {
+        if (performance.now() >= deadline)
+            throw new Error("Shadow input exceeds the run deadline");
+        if (hasSourceAudio)
+            await pacedInput.write(frame);
+        else
+            await waitUntilSample(position);
+        frame = new Uint8Array(frameSamples * 2);
+        filled = 0;
+        hasSourceAudio = false;
+    };
+    const appendSamples = async (count, data) => {
+        let consumed = 0;
+        while (consumed < count) {
+            const take = Math.min(frameSamples - filled, count - consumed);
+            if (data) {
+                frame.set(data.subarray(consumed * 2, (consumed + take) * 2), filled * 2);
+                hasSourceAudio = true;
+            }
+            filled += take;
+            consumed += take;
+            position += take;
+            if (filled === frameSamples)
+                await flushFrame();
+        }
+    };
+    for (const input of inputs) {
+        const { chunk } = input;
+        const observedOffsetMs = input.sessionTimeMs - (chunk.data.byteLength / 2 / chunk.sampleRate) * 1000 - sourceStart;
+        let origin = streams.get(chunk.streamId);
+        if (!origin) {
+            origin = { sample: chunk.startSample, offsetMs: observedOffsetMs };
+            streams.set(chunk.streamId, origin);
+        }
+        let offsetMs = Math.max(0, origin.offsetMs + ((chunk.startSample - origin.sample) / chunk.sampleRate) * 1_000);
+        if (preserveCapturePauses && observedOffsetMs - offsetMs > 250) {
+            // On-demand capture can stop while its sample counter stays contiguous. Preserve
+            // that pause; continuous recordings keep their sample clock despite receipt jitter.
+            offsetMs = observedOffsetMs;
+            streams.set(chunk.streamId, { sample: chunk.startSample, offsetMs });
+        }
+        // Coalesce source packets before awaiting the clock: a 20 ms packet must not
+        // acquire 80 ms of padding merely because the transport uses 100 ms frames.
+        // Sample positions preserve gaps, including silence inside a transport frame.
+        const targetSample = Math.round((offsetMs * chunk.sampleRate) / 1_000);
+        await appendSamples(Math.max(0, targetSample - position));
+        await appendSamples(chunk.data.byteLength / 2, input.syntheticSilence ? undefined : chunk.data);
+    }
+    if (filled)
+        await flushFrame();
+}
 function createEventCursor(session) {
     const iterator = session.events()[Symbol.asyncIterator]();
     // A raced-and-lost next() must be reused, not abandoned: an abandoned call would
@@ -49,7 +174,13 @@ function createEventCursor(session) {
     return {
         async next(timeoutMs) {
             pendingNext ??= iterator.next();
-            const result = await Promise.race([pendingNext, delay(timeoutMs).then(() => "timeout")]);
+            let timer;
+            const result = await Promise.race([
+                pendingNext,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve("timeout"), timeoutMs);
+                }),
+            ]).finally(() => clearTimeout(timer));
             if (result === "timeout")
                 return "timeout";
             pendingNext = undefined;
@@ -62,54 +193,72 @@ function createEventCursor(session) {
         },
     };
 }
-async function waitForReady(session, timeoutMs) {
+async function settleAfterOutput(session, quietMs, deadline, continuousOutput) {
     const cursor = createEventCursor(session);
-    const deadline = Date.now() + timeoutMs;
+    let lastActivity = performance.now();
+    let sawOutputSinceWork = false;
+    let responseIdle = true;
+    const toolCalls = new ToolCallTracker();
+    const backends = new Set();
+    const hostedTools = new Set();
     try {
         while (true) {
-            const remaining = deadline - Date.now();
-            if (remaining <= 0)
-                throw new Error("Shadow provider did not become ready in time");
-            const event = await cursor.next(remaining);
-            if (event === "timeout")
-                throw new Error("Shadow provider did not become ready in time");
-            if (event === "done")
-                throw new Error("Shadow session ended before the provider was ready");
-            if (event.type === "provider.ready")
-                return;
-        }
-    }
-    finally {
-        cursor.dispose();
-    }
-}
-async function settleAfterOutput(session, quietMs, timeoutMs) {
-    const cursor = createEventCursor(session);
-    const deadline = Date.now() + timeoutMs;
-    let lastActivity = Date.now();
-    let sawOutput = false;
-    try {
-        while (true) {
-            const untilDeadline = deadline - Date.now();
+            const untilDeadline = deadline - performance.now();
             if (untilDeadline <= 0)
-                return;
-            const untilQuiet = quietMs - (Date.now() - lastActivity);
-            if (sawOutput && untilQuiet <= 0)
-                return;
-            const wait = Math.max(10, sawOutput ? Math.min(untilQuiet, untilDeadline) : untilDeadline);
+                return "timeout";
+            const untilQuiet = quietMs - (performance.now() - lastActivity);
+            const canSettle = sawOutputSinceWork &&
+                responseIdle &&
+                !toolCalls.hasPending() &&
+                backends.size + hostedTools.size === 0;
+            const wait = Math.max(0, canSettle ? Math.min(untilQuiet, untilDeadline) : untilDeadline);
             const event = await cursor.next(wait);
-            if (event === "timeout")
+            if (event === "timeout") {
+                if (canSettle && performance.now() - lastActivity >= quietMs)
+                    return "quiet";
                 continue;
+            }
             if (event === "done")
-                return;
+                return "closed";
             const type = event.type;
-            if (type === "audio.output" ||
-                type === "transcript" ||
-                type === "tool.requested" ||
-                type === "tool.completed") {
-                lastActivity = Date.now();
-                if (type === "audio.output")
-                    sawOutput = true;
+            const previousToolCall = "callId" in event && event.callId !== undefined ? toolCalls.get(event.callId) : undefined;
+            const toolCall = toolCalls.apply(event);
+            // Only a new execution result requires another answer. Retransmissions and
+            // delivery diagnostics must not erase an answer already observed.
+            let workSettled = toolCall?.status === "result_ready" && toolCall.state !== previousToolCall?.state;
+            if (type === "backend.response") {
+                // Voice may announce a result before the backend emits its trailing terminal.
+                // That terminal releases the pending gate; it does not require another answer.
+                if (event.phase === "completed")
+                    backends.delete(event.responseId);
+                else
+                    backends.add(event.responseId);
+            }
+            if (type === "backend.tool") {
+                const key = JSON.stringify([event.responseId, event.toolId]);
+                if (event.phase === "started")
+                    hostedTools.add(key);
+                else
+                    workSettled = hostedTools.delete(key);
+            }
+            if (type === "delegation.created" && event.target === "responses" && event.responseId)
+                backends.add(event.responseId);
+            if (type === "response.state")
+                responseIdle = event.state === "idle";
+            if (workSettled)
+                sawOutputSinceWork = false;
+            const spokenAudio = type === "audio.output" && (!continuousOutput || hasAudibleSamples(event.chunk.data));
+            const assistantText = (type === "transcript" || type === "transcript.delta" || type === "transcript.fragment") &&
+                event.role === "assistant";
+            if (spokenAudio || assistantText)
+                sawOutputSinceWork = true;
+            if (spokenAudio ||
+                assistantText ||
+                type === "response.state" ||
+                type.startsWith("tool.") ||
+                type.startsWith("task.") ||
+                type.startsWith("backend.")) {
+                lastActivity = performance.now();
             }
         }
     }
@@ -117,6 +266,19 @@ async function settleAfterOutput(session, quietMs, timeoutMs) {
         cursor.dispose();
     }
 }
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function hasAudibleSamples(data) {
+    const samples = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    let squares = 0;
+    for (let offset = 0; offset < data.byteLength; offset += 2)
+        squares += (samples.getInt16(offset, true) / 32_768) ** 2;
+    return Math.sqrt(squares / Math.max(1, data.byteLength / 2)) >= 0.003;
+}
+function waitOrAbort(promise, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+        void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
 }

package/dist/internal/harness/socket-bridge.d.ts

@@ -4,7 +4,7 @@ import type { VoiceSession } from "./voice-session.js";
 /**
  * The client wire protocol every XO transport speaks:
  * - text frames are JSON control messages (start / playout / stop up; started / event /
- *   error / closed down),
+ *   interrupt / error / closed down),
  * - binary frames are PCM16 mono audio (microphone up; length-prefixed model audio down:
  *   u32le header length, JSON header, PCM bytes).
  *
@@ -30,6 +30,15 @@ export declare const VoiceClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObj
     type: z.ZodLiteral<"playout">;
     streamId: z.ZodString;
     playedThroughSample: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    streamId: z.ZodString;
+    startSample: z.ZodInt;
+    endSample: z.ZodInt;
+    status: z.ZodEnum<{
+        discarded: "discarded";
+        played: "played";
+    }>;
+    type: z.ZodLiteral<"playout.range">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"stop">;
     reason: z.ZodOptional<z.ZodString>;
@@ -40,13 +49,41 @@ export type VoiceStartRequest = Omit<Extract<VoiceClientMessage, {
     type: "start";
 }>, "type">;
 export interface VoiceBridgeSocket {
+    /** Throw if the frame cannot be accepted locally; returning does not confirm client receipt. */
     sendText(text: string): void;
     sendBinary(frame: ArrayBuffer): void;
 }
+export interface VoiceBridgeStartupContext {
+    /** Aborted on disconnect only until the factory returns; safe to pass to XO.startSession. */
+    startupSignal: AbortSignal;
+}
+export interface VoiceBridgeStartedContext {
+    /** Cancels opening work on close, independently of the provider's owner signal. */
+    signal: AbortSignal;
+}
+export interface VoiceBridgeCloseResult {
+    /** Whether pending creation/late cleanup settled before the bridge's deadline, not provider finalization. */
+    readonly startup: "settled" | "unconfirmed";
+}
 export interface VoiceSocketBridgeOptions {
     socket: VoiceBridgeSocket;
     /** Owns provider resolution and XO construction; the bridge owns only the wire. */
-    startSession(start: VoiceStartRequest): Promise<VoiceSession>;
+    startSession(start: VoiceStartRequest, context: VoiceBridgeStartupContext): Promise<VoiceSession>;
+    /**
+     * Runs after media is enabled and started is submitted locally; its promise never gates media.
+     * The started control frame precedes the provider.ready event frame. Earlier startup events may precede it.
+     */
+    onStarted?(session: VoiceSession, context: VoiceBridgeStartedContext): void | Promise<void>;
+    /**
+     * Synchronous visibility policy for JSON event frames. Default: send every event.
+     * Does not filter playback configuration/interruption controls, binary audio, stored history, or server observers.
+     * Inspect without mutating the event; throwing closes the bridge with a generic client error.
+     */
+    shouldSendEvent?(event: HarnessEvent): boolean;
+    /** Observes command/hook errors and socket send failures, including when wire reporting is impossible. */
+    onError?(error: Error): void;
+    /** Bounds waiting for pending creation on close. Integer 1–2147483647 ms; default: 5 seconds. */
+    startupCloseTimeoutMs?: number;
     inputSampleRate?: number;
 }
 export declare const VOICE_BRIDGE_INPUT_SAMPLE_RATE = 24000;
@@ -57,8 +94,12 @@ export declare class VoiceSocketBridge {
     handleText(text: string): Promise<void>;
     /** Feed every binary frame from the client socket here. */
     handleBinary(data: Uint8Array): Promise<void>;
-    /** Call when the client socket closes; settles the session. */
-    handleClose(reason?: string): Promise<void>;
+    /**
+     * Closes an attached session gracefully, or cancels pending creation and waits up to
+     * startupCloseTimeoutMs. Repeated calls share one result. Unconfirmed startup is still
+     * cleaned up if it returns later; this result never claims provider finalization.
+     */
+    handleClose(reason?: string): Promise<VoiceBridgeCloseResult>;
 }
 export declare function encodeVoiceAudioFrame(chunk: AudioChunk): ArrayBuffer;
 /** Event payload for clients: audio chunks shrink to metadata, bytes stay server-side. */