@urun-sh/openai 0.5.4 → 0.5.6

package/dist/proxy/index.d.cts

@@ -1,5 +1,547 @@
-export { O as OpenAIProxyOptions, P as ProxyClients, a as ProxyIdentity, b as ProxyVideoOutLane, c as createOpenAIProxy } from '../server-wmUnMewW.cjs';
-export { h as GEMINI_LIVE_PATH, V as VIDEO_OUT_SETUP_KEY } from '../translator-CcDBEfvm.cjs';
-import 'node:http';
-import '../video-out-D20UuJ8G.cjs';
+import { Server, IncomingMessage } from 'node:http';
+import { f as ProxyHandlerOptions, P as ProxyClients } from '../responses-turn-tNUHq5b0.cjs';
+export { D as DialObserver, a as DialReport, g as ProxyIdentity, h as ProxyVideoOutLane, S as SessionGoneError, U as UnknownModelError } from '../responses-turn-tNUHq5b0.cjs';
+export { h as GEMINI_LIVE_PATH, V as VIDEO_OUT_SETUP_KEY } from '../translator-Bh0Bp_Ie.cjs';
+import { WebSocket } from 'ws';
+import '../models-DUdx_Y6X.cjs';
+import '../video-out-CCksIcj8.cjs';
 import '../types-lsVTbNcH.cjs';
+
+/**
+ * The local OpenAI-compatible proxy — `npx @urun-sh/openai proxy`.
+ *
+ * A loopback HTTP server speaking the OpenAI REST surface (`/v1/models`,
+ * `/v1/responses`, `/v1/chat/completions`, SSE streaming included), so any
+ * OpenAI-env-var tool — coding agents first — integrates with uRun with ZERO
+ * code changes: point `OPENAI_BASE_URL` at it and keep making plain, local,
+ * "inefficient" HTTP requests. The proxy backhauls each request over the uRun
+ * session transport (the `@urun-sh/openai` Responses client → session doc
+ * lanes + streams — no public OpenAI-style HTTP leaves the machine), which is
+ * also where the delta-sync chat-state doc lane (urun-python
+ * `urun/serve/chat_state.py`) plugs in as the transport evolves.
+ *
+ * Local-trust model: binds 127.0.0.1 by default; `apiKey` (when set) must
+ * match the agent's `Authorization: Bearer` — otherwise any local bearer is
+ * accepted (the key the agent sends is NEVER forwarded upstream; uRun auth is
+ * the session's own).
+ */
+
+/** The proxy server's own options: a FIXED backhaul (the local CLI lane). */
+interface OpenAIProxyOptions extends ProxyHandlerOptions {
+    clients: ProxyClients;
+}
+/** Build (not listen) the proxy server — the caller owns listen/close. */
+declare function createOpenAIProxy(options: OpenAIProxyOptions): Server;
+
+/**
+ * The Gemini Live WS surface: a minimal `ws` upgrade hook on the proxy's
+ * node:http server plus one per-connection protocol driver. ALL session
+ * plumbing is the proxy's existing seam — `ProxyClients` (lazily-opened
+ * pooled per-app uRun sessions behind ModelRouter) — the driver holds ONLY
+ * protocol translation state: the conversation transcript the Live API keeps
+ * server-side (Live clients never re-send history, so the driver accumulates
+ * Responses input items and sends the full transcript per turn; the
+ * backhaul's delta-sync chat-state lane makes the re-send cheap).
+ *
+ * SESSION RESUMPTION (`setup.sessionResumption`) rides the session-identity
+ * seam (ProxyClients.sessionHandle / onSessionEnd → ModelRouter.handleFor /
+ * sessionForHandle): a resumption handle snapshots the Live conversation
+ * PLUS the opaque handle of the pooled uRun session serving it, so resuming
+ * reattaches the SAME session (session-affine slot + doc state — the
+ * platform's native resume, urun-python#1556/#1582). A handle whose session
+ * is gone fails LOUD (1008) — a fresh session is never silently sold as a
+ * resume.
+ *
+ * HOSTED MULTI-TENANT MODE: `attachGeminiLive` either rides a FIXED local
+ * backhaul (the `urun compat proxy` lane: `clients` + optional `apiKey`) or
+ * resolves PER REQUEST through `authenticate` (the hosted lane), which runs
+ * to completion BEFORE `ws.handleUpgrade` — a refused credential never
+ * becomes a Live session. Header credentials (`x-goog-api-key` or
+ * `Authorization: Bearer`) and the browser `?key=` channel are
+ * distinguished; contradictory distinct credentials are refused, and the
+ * hosted lane refuses `?key=` outright (origin policy: long-lived org keys
+ * must never ride browser query strings) as well as missing auth.
+ * Resumption snapshots are bound to the verified caller's scope — another
+ * key/org cannot recover a transcript even holding the handle (loud 1008,
+ * identical to an unknown handle, so handle existence never leaks).
+ *
+ * COMPOSITION: the attach claims ONLY the BidiGenerateContent upgrade path
+ * and leaves every other upgrade untouched for the next `upgrade` listener
+ * (the /v1/responses acceptor, then — registered LAST by the embedder — the
+ * final refusal of unclaimed upgrades). It returns an async close handle
+ * (ws-native lifecycle: graceful close frame to every live socket, then
+ * `wss.close()`) for drain to run BEFORE HTTP-server closure.
+ *
+ * goAway: wired to core's NATIVE terminal phase signal via
+ * ProxyClients.onSessionEnd. MISSING PRIMITIVE (surfaced in the PR): core
+ * exposes `endsAt` but no PRE-expiry notice event, so goAway is emitted AT
+ * the moment of loss (timeLeft ≈ 0s) — per the no-invented-timers rule.
+ *
+ * Loud-failure contract (no silent degradation):
+ *   1007  protocol violations / declared-follow-up inputs (automatic
+ *         server-side VAD…)
+ *   1008  unknown model (sendUnknownModel's WS mirror) / resumption handle
+ *         whose session is gone (CLOSE_SESSION_GONE)
+ *   1011  upstream failures (error event, stream without response.completed,
+ *         pooled session terminal loss — preceded by goAway)
+ *
+ * Manual VAD/activity + barge-in: with
+ * `setup.realtimeInputConfig.automaticActivityDetection.disabled: true` the
+ * client marks its own activity windows (`realtimeInput.activityStart` /
+ * `activityEnd`). An activityStart while a generation is in flight is a
+ * BARGE-IN (activityHandling START_OF_ACTIVITY_INTERRUPTS, the default): the
+ * turn loop breaks out of its for-await, which calls `return()` on the
+ * upstream async iterator — the async-iterator-native cancel the /v1/messages
+ * lane uses for client disconnects (server.ts), no bespoke abort plumbing —
+ * then emits the golden `serverContent.interrupted: true` and DROPS the
+ * partial turn (no generationComplete/turnComplete, no transcript adoption).
+ * Cancellation lands at the next upstream event, same as the HTTP lane.
+ */
+
+/**
+ * The upstream seams the Live lane uses: the pooled-session Responses call,
+ * the pooled session's NATIVE audio lanes (`openAudio` — the same
+ * enableSessionAudio/AudioBridge machinery RealtimeClient.enableAudio
+ * rides), the NATIVE video frame lane (`openVideo` — enableSessionVideo's
+ * rt-video-in named-DATA frame path), and the session-identity seam
+ * (sessionHandle/onSessionEnd → ModelRouter.handleFor/sessionForHandle)
+ * sessionResumption rides.
+ */
+type GeminiLiveClients = Pick<ProxyClients, 'createResponse' | 'openAudio' | 'openVideo' | 'openVideoOut' | 'sessionHandle' | 'onSessionEnd'>;
+interface LiveSnapshot {
+    model: string;
+    /** The session-identity seam's opaque handle for the pooled uRun session. */
+    proxyHandle: string;
+    /** The Live conversation at snapshot time, as Responses input items. */
+    transcript: Array<Record<string, unknown>>;
+}
+/**
+ * One registry per attached proxy server (created in {@link attachGeminiLive}).
+ *
+ * Snapshots are keyed by CALLER SCOPE + handle: a handle minted for one
+ * verified caller is unreachable to every other caller — handle in hand or
+ * not, the lookup is exactly the unknown-handle loud 1008, so handle
+ * existence is never leaked across tenants. The scope is the authorized
+ * caller's identity (LOCAL_SCOPE on the local lane, the hosted lane's
+ * verified-caller subject); the conversation dimension lives in the handle
+ * itself, which names one conversation's snapshot. Multiattach is normal:
+ * concurrent connections of the SAME caller may resume the SAME handle.
+ *
+ * HONEST SCOPE (not HA): this registry is per-process, per-attach. A replica
+ * restart loses every handle (loud 1008, never a silent restart), and no
+ * other replica can serve one. Cross-replica / persistent resumption needs a
+ * shared persistence plane for snapshots + session identity — a reported
+ * platform requirement, never silently claimed here.
+ */
+declare class ResumptionRegistry {
+    private readonly snapshots;
+    store(scope: string, handle: string, snapshot: LiveSnapshot): void;
+    get(scope: string, handle: string): LiveSnapshot | undefined;
+}
+/**
+ * One authorized Live call: the backhaul to ride and the tenant scope its
+ * resumption snapshots bind to.
+ */
+interface GeminiLiveCall {
+    clients: GeminiLiveClients;
+    /**
+     * The verified caller's scope (hosted: derived from the verified org API
+     * key — e.g. TenantRegistry's non-secret `tenantSubject`). A resumption
+     * handle minted under one scope is UNREACHABLE under any other, and the
+     * failed lookup is the ordinary unknown-handle loud 1008 — never a
+     * "wrong tenant" error that would confirm the handle exists.
+     */
+    scope: string;
+    /**
+     * HOSTED conversation binding (optional): the lane calls it with every
+     * resume handle it mints, so the embedder can index handle → the private
+     * conversation backhaul that will serve a resume of it. Absent on the
+     * local lane (fixed clients).
+     */
+    onBindResumeHandle?: (handle: string) => void;
+    /**
+     * HOSTED (optional): resolve the backhaul a minted resume handle belongs
+     * to. Runs at resume setup BEFORE any seam call — the resumed connection
+     * reattaches the SAME private conversation (same native session identity,
+     * owner binding enforced); a throw is the loud session-gone close (1008).
+     * Absent on the local lane.
+     */
+    clientsForResume?: (resumeHandle: string) => Promise<GeminiLiveClients>;
+    /**
+     * HOSTED per-attachment release (optional): called ONCE when this
+     * connection's socket closes, so the embedder can drop THIS attachment's
+     * claim on the private conversation backhaul (native detach at the last
+     * attachment — no resource keepalive merely to preserve local resume).
+     * Fire-and-forget from the lane; must be idempotent. Absent on the local
+     * lane.
+     */
+    release?: () => Promise<void>;
+}
+/**
+ * HOSTED per-request auth: verify the single Gemini credential the client
+ * presented (already policy-checked — no missing auth, no `?key=`, no
+ * contradictory inputs) and resolve THAT caller's own backhaul + tenant
+ * scope. Runs to completion BEFORE `ws.handleUpgrade`; a throw refuses the
+ * upgrade with the error's own `status` (e.g. ProxyAuthError's 401) or 502
+ * when the error carries none.
+ */
+type GeminiLiveAuthenticate = (credential: string, req: IncomingMessage) => Promise<GeminiLiveCall>;
+interface GeminiLiveOptions {
+    /** The FIXED backhaul (local CLI lane). Required unless `authenticate`. */
+    clients?: GeminiLiveClients;
+    /**
+     * The proxy's local bearer (OpenAIProxyOptions.apiKey). Gemini Live clients
+     * authenticate with `?key=…` or `x-goog-api-key`; both are accepted here
+     * (never forwarded upstream — uRun auth is the session's own). Omitted ⇒
+     * the local lane is open (a loopback embedder's choice).
+     */
+    apiKey?: string;
+    /**
+     * HOSTED per-request resolution; mutually exclusive with a fixed
+     * `clients`/`apiKey` lane (throw at attach). Sets the HOSTED credential
+     * policy: missing auth refused, `?key=` refused (origin policy — long-lived
+     * org keys must never appear in browser query strings), contradictory
+     * distinct credentials refused.
+     */
+    authenticate?: GeminiLiveAuthenticate;
+}
+/**
+ * Attach the Gemini Live BidiGenerateContent WS endpoint to an HTTP server.
+ *
+ * COMPOSITION: this attach claims ONLY the BidiGenerateContent upgrade path.
+ * Upgrades on any other path are left untouched for the NEXT `upgrade`
+ * listener (the /v1/responses acceptor, and — registered LAST by the
+ * embedder — the final refusal of unclaimed upgrades). On the claimed path
+ * auth happens BEFORE `ws.handleUpgrade`: the local fixed bearer 401s, and
+ * the hosted lane runs `authenticate` to completion (401 on a
+ * refused/missing credential, the error's own status for a resolver
+ * rejection, 502 when the error carries none — never an open pass).
+ *
+ * Returns the lane's close handle — `await close()` runs the ws-native
+ * lifecycle: a graceful close() to every live socket (close frames, sends
+ * flushed), then `wss.close()` resolving when the last socket is gone.
+ * Disconnects are DETACHES: closing never ends a pooled session. The handle
+ * is idempotent.
+ */
+declare function attachGeminiLive(server: Server, options: GeminiLiveOptions): () => Promise<void>;
+/**
+ * Drive ONE already-authenticated Gemini Live socket — the per-connection
+ * driver underneath {@link attachGeminiLive}, for surfaces that own the
+ * upgrade + auth themselves (e.g. a destination-side SFU route that
+ * pre-authenticates and hands the live `WebSocket` over).
+ *
+ * Runs the full protocol loop (setup → setupComplete, clientContent /
+ * realtimeInput / toolResponse → turns, native audio/video lanes, session
+ * resumption, goAway) against `call`'s seams, and detaches cleanly when the
+ * socket closes: `call.release?.()` fires once (per-attachment release —
+ * native detach at the last attachment), sessions are never ended by a
+ * socket closing.
+ *
+ * `registry` collects this driver's resumption snapshots. Omit it for a
+ * private per-socket registry (handles then live exactly as long as the
+ * socket); pass a shared one to let several sockets resume each other's
+ * handles — always scoped by `call.scope`, never across callers.
+ */
+declare function serveGeminiLiveSocket(ws: WebSocket, call: GeminiLiveCall, registry?: ResumptionRegistry): void;
+
+/**
+ * `attachOpenAIRealtime(server, options)` — the WS upgrade hook for the OpenAI
+ * Realtime surface (GA protocol subset; see protocol.ts for the event subset).
+ *
+ * Contract (Main-owned composition; this lane claims ONLY `/v1/realtime`):
+ *   - Upgrades on any other path are passed through UNTOUCHED — a plain
+ *     `next()` listener, so sibling lanes (Gemini Live, Responses WS) and the
+ *     hosted composition keep their own upgrade hooks.
+ *   - Clients are resolved/authenticated ASYNCHRONOUSLY BEFORE the upgrade is
+ *     accepted: no 101 is written until `resolver.resolve(req)` settles. A
+ *     thrown error maps `err.status` (default 502) to the HTTP reject;
+ *     401/403 keep their status.
+ *   - The resolved binding carries a PRIVATE native uRun session (fresh or
+ *     explicitly-resumed) and, iff voice, a PRIVATE audio bridge — never the
+ *     pooled tenant lane. The connection's cross-caller claim is invariant
+ *     validation, not capacity policy.
+ *   - Returns an async close function: waits for every touched socket to
+ *     settle, then closes the internal WebSocketServer. It does NOT end the
+ *     native uRun sessions (detach ≠ session death — resume is Main-owned;
+ *     the binding seam decides lifetime).
+ */
+
+declare const OPENAI_REALTIME_PATH = "/v1/realtime";
+/**
+ * The resolver seam — the ONLY credential, modality, and session-allocation
+ * authority this adapter recognizes. Implemented by Main's composition (and
+ * by tests with an injected fake). Accepted in EITHER form: a bare
+ * `(req) => Promise<binding>` (the {@link ProxyClientsFor}-style convention)
+ * or a `{ resolve(req) }` object.
+ */
+type OpenAIRealtimeResolver<S = unknown> = ((req: IncomingMessage) => Promise<RealtimeBinding<S>>) | {
+    resolve(req: IncomingMessage): Promise<RealtimeBinding<S>>;
+};
+interface RealtimeBinding<S = unknown> {
+    /**
+     * The PRIVATE native uRun session serving this conversation (the shared
+     * per-conversation factory in hosted/tenants.ts allocates it; reuse/multi-
+     * attach is sanctioned ONLY for the SAME authorized conversation on an
+     * explicit resume — two different conversations MUST NOT receive one
+     * session). The upstream turn seam is EITHER form:
+     *   - `session.sendResponseCreate(params, input, requestId)` (the direct
+     *     SdkTransport-style seam), or
+     *   - `clients.createResponse(params)` — the canonical ProxyClients seam
+     *     the conversation factory hands out (`input` rides inside `params`).
+     * A binding with neither is rejected at upgrade time, LOUD.
+     */
+    session?: S & {
+        sendResponseCreate?(params: unknown, input: unknown[], requestId: string): AsyncIterable<unknown>;
+    };
+    clients?: Pick<ProxyClients, 'createResponse'>;
+    /**
+     * Authoritative modality verdict from the resolver. A function NAME proves
+     * nothing — without `voice: true`, audio events are refused and no audio
+     * primitive is ever opened on the session.
+     */
+    voice: boolean;
+    /** The PRIVATE audio bridge for THIS conversation (required iff `voice`). */
+    audioSession?: {
+        audio: {
+            appendInputAudio(base64Pcm16: string): void;
+            onOutputAudio(handler: (b64: string) => void): () => void;
+        };
+        /** Cross-caller reuse registry (invariant validation; see connection.ts). */
+        openaiRealtimeClaims?: Set<RealtimeBinding['audioSession']>;
+    };
+    /** `model` the binding names for this conversation (overrides session config default). */
+    model?: string;
+    /** True when `session` is a resumed authorized session (vs a fresh private one). */
+    resumed?: boolean;
+    /**
+     * The backend's OWN turn/transcript lane — the §5 `stt` named stream
+     * (urun.serve.transcribe_bridge wire shape: `t` = delta/final/turn_start/
+     * turn_end/turn_eager_end/turn_resumed, `delta` text, additive `start_ms`
+     * and semantic-VAD `confidence`). The resolver maps `session.stream('stt')
+     * .messages()` onto this. Its `turn_end` IS the native commit and
+     * `turn_start` IS the native barge-in — the adapter drives server-VAD
+     * emulation, real transcription events, and model-visible committed audio
+     * from it. Absent = the backend wired no turn lane: manual mode only.
+     */
+    turns?: () => AsyncIterable<{
+        kind: 'delta' | 'final' | 'turn_start' | 'turn_end' | 'turn_eager_end' | 'turn_resumed';
+        text?: string;
+        confidence?: number;
+        startMs?: number;
+    }>;
+    /**
+     * Release THIS attachment when the socket closes (the hosted
+     * conversation-factory seam — the twin of the Gemini Live binding's
+     * `release`): per-attachment release, native detach underneath, the named
+     * session itself stays live. Absent (the local fixed-clients lane) = the
+     * pooled sessions are the process's own and outlive the socket.
+     */
+    release?: () => Promise<void> | void;
+}
+interface OpenAIRealtimeOptions<S = unknown> {
+    resolver: OpenAIRealtimeResolver<S>;
+}
+/**
+ * Attach the OpenAI Realtime WS endpoint to `server`. Upgrades on any other
+ * path pass through untouched. Returns an async close function.
+ */
+declare function attachOpenAIRealtime<S = unknown>(server: Server, options: OpenAIRealtimeOptions<S>): () => Promise<void>;
+
+/**
+ * One authenticated OpenAI Realtime WS connection — the adapter's core.
+ *
+ * OWNERSHIP MODEL (Main's contract, 2026-09-08): the binding seam hands this
+ * connection an EXCLUSIVE, connection-private native uRun session (and, when
+ * the resolver authoritatively binds voice, a PRIVATE audio bridge). The
+ * pooled tenant `openAudio` lane is NEVER used here — `binding.audioSession`
+ * comes from the resolver's own per-conversation acquisition, and
+ * {@link claimVoiceBinding} is the INVARIANT VALIDATION that an accidental
+ * cross-caller reuse of one bridge fails LOUD (it is not a capacity policy).
+ * Multi-attach on the SAME authorized session (explicit resume) is the one
+ * sanctioned shared form: one bridge owner at a time, validated by claim.
+ *
+ * NO-OP POLICY: every unsupported client event or backend gap renders as a
+ * LOUD `error` server event (or a close) — never a silently ignored frame.
+ */
+
+declare class OpenAIRealtimeConnection<S = unknown> {
+    readonly id: string;
+    private readonly ws;
+    private readonly binding;
+    private readonly onClosed?;
+    private config;
+    private readonly sessionId;
+    private readonly conversationId;
+    private readonly items;
+    /** Uncommitted input audio (base64 PCM16 chunks) held locally until commit. */
+    private pendingAudioBytes;
+    private pendingAudioTotalBytes;
+    /** Committed audio of the frozen turn, dispatched at response.create. */
+    private frozenAudio;
+    private inFlight;
+    private activeResponseId;
+    /** Output events already flowed for the active response (post-flush faults → error event, pre-flush → response.failed). */
+    private responseFlushed;
+    private cancelled;
+    private voiceClaimed;
+    private audioLaneOwner;
+    private audioUnsubscribe;
+    private outOfTurnAudioWarned;
+    private audioOnlyTranscriptGapWarned;
+    private closed;
+    /** The backend's turn/transcript lane consumer (binding.turns), if wired. */
+    private turnLaneAbort;
+    /** Accumulated transcript of the OPEN user turn (delta/final events). */
+    private turnTranscript;
+    /** Transcript of the LAST committed turn (the model-visible commit). */
+    private lastCommittedTranscript;
+    constructor(opts: {
+        ws: WebSocket;
+        binding: RealtimeBinding<S>;
+        onClosed?: (conn: OpenAIRealtimeConnection<S>) => void;
+    });
+    /**
+     * Consume the backend's OWN turn/transcript lane (§5 stt stream): the
+     * semantic-VAD boundary events drive REAL protocol semantics — turn_start
+     * is the native barge-in, turn_end is the native commit, deltas/finals are
+     * the REAL input transcription. This is the server-VAD primitive, not an
+     * emulation gap: the voice engine itself decides turn boundaries.
+     */
+    private startTurnLane;
+    /** One backend turn/transcript event → REAL GA protocol events. */
+    private onTurnEvent;
+    /** The committed turn's transcript, consumed once (null = none). */
+    private takeTurnTranscript;
+    private onMessage;
+    private handle;
+    /** Refuse loudly when a text-only-resolved session is asked to carry audio. */
+    private ensureVoice;
+    /**
+     * Cross-caller reuse guard — the INVARIANT check, not capacity policy. The
+     * resolver must hand every independent conversation its OWN bridge; if two
+     * connections ever hold one, the second fails LOUD instead of mixing audio.
+     */
+    private claimVoiceBinding;
+    private releaseVoiceBinding;
+    private warnAudioOnlyTranscriptGap;
+    /**
+     * The upstream turn seam, normalized: a binding carries EITHER
+     * `session.sendResponseCreate(params, input, requestId)` (direct
+     * SdkTransport-style) OR `clients.createResponse(params)` (the canonical
+     * ProxyClients seam the shared conversation factory hands out). A binding
+     * with neither was already rejected at upgrade time; this is the loud
+     * backstop. The ProxyClients seam is PROMISE-VALUED
+     * (`rehomingCreateResponse` dials inside an async function — its
+     * private-backhaul cold wake can park the promise for seconds), so it is
+     * awaited here; awaiting the SdkTransport generator is a no-op. The cast
+     * states the seam's REAL union: typing it sync-iterable is what let the
+     * unawaited promise reach `for await` as "R is not async iterable" (the
+     * prod-usw2 speak-turn kill, 2026-09-14).
+     */
+    private upstreamStream;
+    private startResponse;
+    /**
+     * Bridge voice OUT frame → `response.output_audio.delta` on the open turn.
+     *
+     * OUT-OF-TURN frames split by CONTENT, per the platform's own liveness
+     * model (urun-python #1812/#1827): the runtime's egress holds a DECLARED
+     * quiet track — `CtxMediaTransport`'s silence keepalive emits Opus silence
+     * whenever the app is silent, including before the first response.create —
+     * so an all-quiet frame with no open turn is that muted egress, not voice.
+     * It is dropped quietly (the same reading as a negotiated muted WebRTC
+     * track). A NON-quiet frame with no open turn is real voice the adapter
+     * cannot attribute — still the loud, once-per-connection
+     * `out_of_turn_audio` error that caught the speak-lane bug class.
+     */
+    private onOutputAudioFrame;
+    /** One assistant message item per turn (text and audio parts share it). */
+    private messageItemAdded;
+    /** true when an audio delta opened the message item this turn. */
+    private messageItemOpenForAudio;
+    private beginMessageItem;
+    private beginAudioMessageItem;
+    /**
+     * Close every item the turn opened, in first-open order, adopt them into
+     * the transcript, and emit their `done` events.
+     */
+    private closeOpenItems;
+    private responseObject;
+    private failedResponse;
+    /**
+     * `response.done` — REAL usage only: the serve runtime emits
+     * `{input_tokens, output_tokens, total_tokens}` on terminal bodies; when it
+     * sent none, `usage: null` is delivered (never zeros dressed as counts).
+     */
+    private doneResponse;
+    private upstreamErrorBody;
+    private emitUpstreamFault;
+    /**
+     * Cancel the in-flight response. The upstream iterator is stopped through
+     * the for-await `break` protocol (its `return()` runs — no bespoke cancel
+     * machinery); the turn stops at the NEXT upstream event and the partial
+     * output is NEVER adopted into the transcript (see closeOpenItems being
+     * skipped on the cancelled path).
+     */
+    private cancelResponse;
+    private pushItem;
+    private itemToProtocol;
+    private send;
+    private fail;
+    /**
+     * Socket-level teardown ONLY (never session death): the native uRun session
+     * behind this conversation stays alive — resume semantics are Main-owned.
+     */
+    private teardown;
+}
+
+/**
+ * THE REALTIME BINDING COMPOSITION — the ONE seam every composition rides to
+ * turn an upgraded `/v1/realtime` request into a {@link RealtimeBinding}.
+ *
+ * The modality is read from the CATALOG (`task` stt | tts, invariant across
+ * placements) through the SAME router-backed gate seam the Images lane uses
+ * (`ProxyClients.supportsAudio` — `ModelRouter.supportsAudio`). A non-audio
+ * model is refused LOUDLY with a 404 before anything is opened; a voice
+ * binding acquires its PRIVATE audio bridge from `ProxyClients.openAudio`
+ * (the pooled session's native `audio` lane at 24 kHz — the ONE canonical
+ * session-audio wiring, `transport/media.ts` AUDIO_STREAM). There is no env-var
+ * switch and no chat-default fall-through: an absent model resolves through
+ * the router exactly like every other lane, and a chat default is refused
+ * exactly like an explicitly named chat model.
+ *
+ * Used by BOTH compositions — the local `urun compat proxy` (fixed clients,
+ * optional fixed apiKey) and the hosted multi-tenant endpoint (per-request
+ * org resolution + per-conversation private backhauls) — so there is exactly
+ * ONE binding implementation and no copy-pasted second handler.
+ */
+
+/**
+ * The realtime lane's model name — the GA `?model=` query parameter
+ * (`wss://…/v1/realtime?model=…`). Absent = the router's configured default
+ * resolves it (locally the startup app; hosted, a loud 404 — there IS no
+ * default app on the hosted lane).
+ */
+declare function realtimeModelOf(req: IncomingMessage): string | undefined;
+/**
+ * Build the binding for `model` against `clients`:
+ *   - NO `supportsAudio` seam ⇒ 501 (loud, never a silent allow-all).
+ *   - {@link UnknownModelError} ⇒ 404 with the router's own loud message.
+ *   - A non-audio verdict ⇒ 404 — the realtime lane never falls through to
+ *     the chat lane, in either direction.
+ *   - A voice verdict with no `openAudio` seam ⇒ 501 (a voice binding cannot
+ *     be served without its bridge; a voiceless downgrade is never silent).
+ */
+declare function realtimeBindingFor(clients: Pick<ProxyClients, 'createResponse'> & Partial<Pick<ProxyClients, 'supportsAudio' | 'openAudio'>>, model: string | undefined): Promise<RealtimeBinding<ProxyClients>>;
+/**
+ * The LOCAL lane resolver: fixed pooled clients, optional fixed apiKey (the
+ * same shared-secret rule the local Gemini Live lane applies — a mismatched
+ * or missing Bearer is a 401; with no configured key the header is not
+ * consulted). The HOSTED lane builds its own resolver per request (org
+ * resolution + per-conversation private backhaul) and reuses
+ * {@link realtimeBindingFor} for the binding itself.
+ */
+declare function fixedClientsResolver(clients: ProxyClients, apiKey?: string): {
+    resolve(req: IncomingMessage): Promise<RealtimeBinding<ProxyClients>>;
+};
+
+export { type GeminiLiveCall, type GeminiLiveClients, OPENAI_REALTIME_PATH, type OpenAIProxyOptions, OpenAIRealtimeConnection, type OpenAIRealtimeOptions, type OpenAIRealtimeResolver, ProxyClients, type RealtimeBinding, ResumptionRegistry, attachGeminiLive, attachOpenAIRealtime, createOpenAIProxy, fixedClientsResolver, realtimeBindingFor, realtimeModelOf, serveGeminiLiveSocket };