@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/kernel/engine/session/mod.js

@@ -0,0 +1,951 @@
+import { canaryNote, userDataNote } from '../../../guardrails/canary.js';
+import { addHistoryUrls, addRequestUrls, addSeenUrls, givenUrlSets, } from '../../../guardrails/egress-urls.js';
+import { describeError, errorKind, TheoremError, throwIfAborted, toErrorEvent, withPublicWording, } from '../../../guardrails/error.js';
+import { projectGuardrailTurnEvent } from '../../../guardrails/events.js';
+import { lexiconText } from '../../../guardrails/lexicon.js';
+import { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from '../../../guardrails/live-outbound-gate.js';
+import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { resolveObservabilityPolicy } from '../../../observability/resolve-policy.js';
+import { buildGeminiLiveContext, buildGeminiLiveRealtimeInput, buildGeminiLiveToolResponse, liveFunctionResponsePayload, } from '../../../providers/google/live/framing.js';
+import { openGoogleLiveSession } from '../../../providers/google/live/session.js';
+import { memoryCredentialSource } from '../../auth/credential-source.js';
+import { providerCompleteRequest } from '../../registry/provider-request.js';
+import { resolveTurnInRegistry } from '../../registry/resolve.js';
+import { injectedStageEvent, runStage, stageEventFields, } from '../../stages.js';
+import { profileAllowsInject, stageAbortStop } from '../../stop.js';
+import { bindSystem } from '../../system-parts.js';
+import { failureEvent } from '../../tools/events.js';
+import { executeRegisteredTool, lapsedGateFailure, } from '../../tools/execute.js';
+import { answerGatedCall, gateExpired, resolveGateTtlMs, resumeForAnswer, } from '../../tools/gate-answer.js';
+import { formatToolFailureForModel, formatToolResult } from '../../tools/model-text.js';
+import { cloneTurnToolSnapshot } from '../../tools/resolve.js';
+import { turnDoneOf } from '../../turn-events.js';
+import { prepareLiveInboundText } from '../live-inbound.js';
+import { assertLiveIngress } from '../live-ingress.js';
+import { mediaTokenFamily } from '../token-estimate.js';
+import { startLiveTrace } from './session-trace.js';
+function isReleased(held) {
+    return typeof held.state === 'object' && held.state.released === true;
+}
+function isSettledPhase(tool) {
+    return tool.phase === 'complete' || tool.phase === 'error' || tool.phase === 'gate';
+}
+/**
+ * The provider's close after it warned of it (`goAway`): the session's last
+ * event, not a failure. Every close fact rides along for the builder; the raw
+ * close text is `errorInternal`, which `forClient` strips.
+ */
+function sessionEndedEvent(closed, goAway, lexicon) {
+    const internal = closed.error ? describeError(closed.error) : closed.reason;
+    return {
+        type: 'session',
+        session: {
+            kind: 'ended',
+            ...(goAway.timeLeftMs !== undefined ? { timeLeftMs: goAway.timeLeftMs } : {}),
+            message: lexiconText('live.session_ended', {}, lexicon),
+            ended: {
+                cause: 'go_away',
+                code: closed.code,
+                closedAfterMs: goAway.closedAfterMs,
+                ...(closed.error ? { errorKind: errorKind(closed.error) } : {}),
+            },
+        },
+        ...(internal ? { errorInternal: internal } : {}),
+    };
+}
+/** Live ingress takes text: an inject's texts, or `undefined` when any message is not plain text. */
+function liveInjectTexts(messages) {
+    const texts = [];
+    for (const msg of messages) {
+        const text = msg.role === 'tool' || msg.parts?.length ? undefined : msg.content?.trim();
+        if (!text)
+            return undefined;
+        texts.push(text);
+    }
+    return texts;
+}
+function assertLiveProfile(profile) {
+    if (profile.type !== 'live') {
+        throw new TheoremError('request', `runSession requires profile.type 'live' (got '${profile.type}' for ${profile.id})`);
+    }
+}
+/**
+ * Accept a registry-resolved snapshot from the process that owns the tool
+ * registry. The profile's `tools.allow` stays the ceiling: a custom tool id
+ * outside it is refused rather than declared.
+ */
+function sessionSnapshotWithinAllow(profile, snapshot) {
+    const allow = new Set(profile.tools.allow);
+    const builtins = new Set(snapshot.builtins);
+    const outside = new Set();
+    for (const id of [...snapshot.gated, ...snapshot.visible, ...snapshot.executable]) {
+        if (!allow.has(id) && !builtins.has(id)) {
+            outside.add(id);
+        }
+    }
+    if (outside.size > 0) {
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        const detail = `session snapshot declares tools outside tools.allow: ${[...outside].join(', ')}`;
+        throw new TheoremError('config', `Profile ${profile.id}: ${detail}`);
+    }
+    return cloneTurnToolSnapshot(snapshot);
+}
+function toTurnRequest(req) {
+    return {
+        profile: req.profile,
+        system: req.system,
+        path: req.path,
+        sessionPermissions: req.sessionPermissions,
+        sessionResumptionHandle: req.sessionResumptionHandle,
+        signal: req.signal,
+        metadata: req.metadata,
+        host: req.host,
+        input: {
+            text: '',
+            history: req.history,
+            sessionResumptionHandle: req.sessionResumptionHandle,
+        },
+    };
+}
+function applyVoiceOverride(generation, voice) {
+    if (!voice || !generation.live) {
+        return generation;
+    }
+    return {
+        ...generation,
+        live: {
+            ...generation.live,
+            voice,
+        },
+    };
+}
+function applyInitialInput(generation, input) {
+    if (!input || input.length === 0) {
+        return generation;
+    }
+    return { ...generation, input };
+}
+async function applyOutbound(gate, events, turnPhase, onWithhold) {
+    if (turnPhase === 'abort') {
+        abortLiveOutboundTurn(gate);
+        // Keep tool calls + interrupted marker; drop buffered speech via abortLiveOutboundTurn.
+        return events.filter((ev) => ev.type === 'tool' ||
+            ev.type === 'session' ||
+            (ev.type === 'done' && ev.interrupted === true));
+    }
+    const batch = await processLiveOutboundBatch(gate, events);
+    const out = [];
+    if (batch.action === 'withhold') {
+        onWithhold();
+        return [...(batch.events ?? []), toErrorEvent(batch.error)];
+    }
+    if (batch.action === 'emit') {
+        out.push(...batch.events);
+    }
+    if (turnPhase === 'complete') {
+        const finalized = await finalizeLiveOutboundTurn(gate);
+        if (finalized.action === 'withhold') {
+            onWithhold();
+            return [...out, toErrorEvent(finalized.error)];
+        }
+        if (finalized.action === 'emit') {
+            out.push(...finalized.events);
+        }
+        // Conversational turn boundary — session stays open.
+        out.push({ type: 'done', stop: { kind: 'completed' } });
+    }
+    return out;
+}
+/**
+ * The output a settled Live call sends upstream, or `undefined` when nothing
+ * is sent (a held gate, or no result). The model reads it as the `functionResponse`:
+ * the same guarded text a turn sends, never the tool's raw output.
+ */
+function liveToolOutput(s) {
+    if (s.gated)
+        return undefined;
+    const result = s.modelResult ?? (s.failure ? formatToolFailureForModel(s.failure) : undefined);
+    return result ? formatToolResult(result) : undefined;
+}
+/** What the model reads back from a Live call: the `functionResponse.response` sent. */
+function liveReadBack(s) {
+    const output = liveToolOutput(s);
+    return output === undefined
+        ? undefined
+        : { text: JSON.stringify(liveFunctionResponsePayload(output)) };
+}
+/**
+ * A provider batch as the host receives it: a call's `done` becomes the
+ * host's (`turnDoneOf`); `response` stays with the trace, which read the batch.
+ */
+function hostEventsOf(events, snapshot) {
+    return events.flatMap((ev) => {
+        if (ev.type === 'response')
+            return [];
+        if (ev.type !== 'done')
+            return [ev];
+        const { type: _done, ...done } = ev;
+        return [turnDoneOf(done, snapshot)];
+    });
+}
+function* drainPendingHostEvents(pendingHostEvents) {
+    while (pendingHostEvents.length > 0) {
+        const pending = pendingHostEvents.shift();
+        if (pending)
+            yield pending;
+    }
+}
+function boundaryDoneEvents(doneBatch, turnPhase, interrupted) {
+    if (doneBatch.length > 0)
+        return doneBatch;
+    if (turnPhase === 'abort' || interrupted) {
+        return [{ type: 'done', stop: { kind: 'interrupted' }, interrupted: true }];
+    }
+    return [{ type: 'done', stop: { kind: 'completed' } }];
+}
+function* yieldLiveNonDoneEvents(gated, includeMatch, recordAssistantText) {
+    const doneBatch = gated.filter((ev) => ev.type === 'done');
+    for (const ev of gated) {
+        if (ev.type === 'done')
+            continue;
+        if (ev.type === 'text' && typeof ev.text === 'string') {
+            recordAssistantText(ev.text);
+        }
+        yield projectGuardrailTurnEvent(ev, includeMatch ?? false);
+    }
+    return doneBatch;
+}
+function buildLiveSession(args) {
+    const { profile, canary, connection, gate, givenUrls, signal, onStage, host: sessionHost, resolveHost, path, snapshot, trace, gateTtlMs, signInGate, } = args;
+    /** Grows as the user approves `session_consent` tools. */
+    let sessionPermissions = args.sessionPermissions;
+    /** Where keys typed at sign-in gates go when a call brings no source of its own. */
+    const sessionCredentials = args.credentials ?? memoryCredentialSource();
+    const calls = new Map();
+    let closed = false;
+    let withholdClose = false;
+    const pendingHostEvents = [];
+    /** Wakes the host's stream when the session queues an event while Gemini is silent. */
+    let wakeHost;
+    const includeMatch = resolveObservabilityPolicy(profile.observability).include
+        .guardrailMatchPreview;
+    let cycle = 'idle';
+    let cycleStep = 0;
+    const history = args.historySeed?.length
+        ? structuredClone(args.historySeed)
+        : [];
+    /** Serialize stage + ingress so concurrent send* cannot interleave cycles. */
+    let ingressChain = Promise.resolve();
+    const recordUserText = (text) => {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        history.push({ role: 'user', content: trimmed });
+        addSeenUrls(givenUrls.request, trimmed);
+    };
+    const recordAssistantText = (text) => {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        const last = history.at(-1);
+        if (last?.role === 'assistant' && typeof last.content === 'string' && !last.tool_calls) {
+            last.content = `${last.content}${trimmed}`;
+            return;
+        }
+        history.push({ role: 'assistant', content: trimmed });
+    };
+    const recordToolSettle = (tool, readBack) => {
+        history.push({
+            role: 'assistant',
+            tool_calls: [
+                {
+                    id: tool.callId,
+                    type: 'function',
+                    function: {
+                        name: tool.name,
+                        arguments: JSON.stringify(tool.arguments),
+                    },
+                },
+            ],
+        }, {
+            role: 'tool',
+            tool_call_id: tool.callId,
+            name: tool.name,
+            content: readBack,
+        });
+        addSeenUrls(givenUrls.tools, readBack);
+    };
+    const enqueuePending = (ev) => {
+        pendingHostEvents.push(projectGuardrailTurnEvent(ev, includeMatch));
+        const wake = wakeHost;
+        wakeHost = undefined;
+        wake?.();
+    };
+    const hostEventQueued = () => pendingHostEvents.length > 0
+        ? Promise.resolve('queued')
+        : new Promise((resolve) => {
+            wakeHost = () => resolve('queued');
+        });
+    const assertOpen = () => {
+        if (closed) {
+            throw new TheoremError('request', 'Live session is closed'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    };
+    const sendJson = (payload) => {
+        assertOpen();
+        connection.send(payload);
+    };
+    const answerModel = (callId, held, readBack) => {
+        recordToolSettle({ name: held.name, callId, arguments: held.arguments }, readBack);
+        sendJson(buildGeminiLiveToolResponse(callId, held.name, readBack));
+    };
+    const settleHeld = (callId, held, readBack) => {
+        clearTimeout(held.lapse);
+        calls.delete(callId);
+        answerModel(callId, held, readBack);
+    };
+    /** A released call nobody answered in time: the model reads that its sign-in expired. */
+    const lapseReleased = (callId, held) => {
+        if (closed || calls.get(callId) !== held || typeof held.state !== 'object')
+            return;
+        const { gate } = held.state;
+        const failure = lapsedGateFailure(held.name, gate.kind === 'auth' ? gate.authChallenge.service : undefined, profile.lexicon);
+        const readBack = formatToolResult(formatToolFailureForModel(failure));
+        enqueuePending(failureEvent({ name: held.name, callId }, failure, readBack));
+        settleHeld(callId, held, readBack);
+    };
+    /** A closed session answers nothing more. */
+    const stopLapses = () => {
+        for (const held of calls.values())
+            clearTimeout(held.lapse);
+    };
+    /**
+     * A call that ran into `gate`. A sign-in gate this session answers at once tells the model its
+     * pending note and releases the call; a call already released stays released. Either waits
+     * `gateTtlMs` for its outcome. False: the call is not released, and the caller holds it.
+     */
+    const releaseGated = (callId, held, wasReleased, gate, readBack) => {
+        const answersNow = signInGate === 'answer' && gate.kind === 'auth' && readBack !== undefined;
+        if (!answersNow && !wasReleased)
+            return false;
+        if (answersNow)
+            answerModel(callId, held, readBack);
+        clearTimeout(held.lapse);
+        held.state = { gate, createdAt: Date.now(), released: true };
+        held.lapse = setTimeout(() => lapseReleased(callId, held), gateTtlMs);
+        return true;
+    };
+    /**
+     * Hold each call the model makes. A call the provider already failed
+     * (malformed arguments) is settled here: the model reads its failure. A
+     * provider cancel lets go of a call that is not running.
+     */
+    const holdCalls = (events) => {
+        for (const ev of events) {
+            if (ev.type !== 'tool')
+                continue;
+            const tool = ev.tool;
+            if (tool.phase === undefined) {
+                calls.set(tool.callId, { name: tool.name, arguments: tool.arguments, state: 'open' });
+                continue;
+            }
+            const held = calls.get(tool.callId);
+            if (!held)
+                continue;
+            if (tool.phase === 'error' && tool.readBack !== undefined) {
+                settleHeld(tool.callId, held, tool.readBack);
+            }
+            else if (tool.phase === 'cancel' && held.state !== 'running') {
+                calls.delete(tool.callId);
+            }
+        }
+    };
+    const closeSocket = (code, reason, initiator) => {
+        trace.socketClosed(code, reason, initiator);
+        connection.close(code, reason);
+    };
+    /** A `done` names the response span it ends. */
+    const stampDone = (ev) => {
+        if (ev.type !== 'done')
+            return ev;
+        const traceparent = trace.responseTraceparent();
+        return traceparent ? { ...ev, traceparent } : ev;
+    };
+    const runCycleStage = async (stage, extra) => {
+        const gen = runStage({
+            ...extra,
+            stage,
+            step: Math.max(1, cycleStep),
+            history,
+            handlers: onStage ? [onStage] : [],
+            guardrails: profile.guardrails,
+            injectAllowed: profileAllowsInject(profile),
+            host: sessionHost,
+            signal,
+            span: trace.root,
+        });
+        let result = await gen.next();
+        while (!result.done) {
+            enqueuePending(result.value);
+            result = await gen.next();
+        }
+        return {
+            abort: result.value.abort,
+            inject: result.value.inject,
+        };
+    };
+    const ingestPreparedLiveText = (text) => {
+        const start = performance.now();
+        const prepared = prepareLiveInboundText(profile, text);
+        trace.inboundCheck(performance.now() - start, prepared.guardrail);
+        if (prepared.guardrail)
+            enqueuePending(prepared.guardrail);
+        recordUserText(prepared.text);
+        sendJson(buildGeminiLiveRealtimeInput({ type: 'text', text: prepared.text }));
+    };
+    /**
+     * Write each inject whole into the open cycle (no re-entry into pre_turn),
+     * then record the named ones that landed. An inject live cannot write as
+     * text is refused whole with a stage warning, never written in part.
+     */
+    const landInject = (stage, units, extra) => {
+        const landed = [];
+        for (const unit of units) {
+            const texts = liveInjectTexts(unit.messages);
+            if (!texts) {
+                enqueuePending({
+                    ...stageEventFields(stage, extra),
+                    stageWarnings: [
+                        {
+                            code: 'inject_invalid_messages',
+                            field: 'inject',
+                            message: 'live ingress takes plain-text inject messages only; inject refused', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                        },
+                    ],
+                });
+                continue;
+            }
+            for (const text of texts) {
+                assertLiveIngress(profile, 'text');
+                ingestPreparedLiveText(text);
+            }
+            landed.push(unit);
+        }
+        const event = injectedStageEvent(stage, landed, extra);
+        if (event)
+            enqueuePending(event);
+    };
+    /** A stage's `abort` ends the open cycle: a cancelled `done`, then `post_turn`. */
+    const cancelCycle = async (abort) => {
+        const stop = stageAbortStop(abort);
+        // Idle first, so a boundary Gemini sends meanwhile does not end the cycle again.
+        cycle = 'idle';
+        enqueuePending({ type: 'done', stop, interrupted: true });
+        await runCycleStage('post_turn', { stop });
+    };
+    const openCycleIfNeeded = async () => {
+        if (cycle === 'open')
+            return { aborted: false };
+        cycle = 'open';
+        cycleStep += 1;
+        const pre = await runCycleStage('pre_turn');
+        if (pre.abort) {
+            await cancelCycle(pre.abort);
+            return { aborted: true };
+        }
+        landInject('pre_turn', pre.inject);
+        return { aborted: false };
+    };
+    const endCycleAroundDone = async function* (doneEvents) {
+        if (cycle !== 'open') {
+            for (const ev of doneEvents)
+                yield ev;
+            return;
+        }
+        const before = await runCycleStage('before_end', {
+            stop: doneEvents.find((e) => e.type === 'done')?.stop,
+        });
+        if (before.abort) {
+            yield { type: 'done', stop: { kind: 'cancelled' }, interrupted: true };
+            await runCycleStage('post_turn', { stop: { kind: 'cancelled' } });
+            cycle = 'idle';
+            return;
+        }
+        landInject('before_end', before.inject);
+        for (const ev of doneEvents) {
+            yield ev;
+        }
+        const terminal = doneEvents.find((e) => e.type === 'done');
+        await runCycleStage('post_turn', { stop: terminal?.stop });
+        cycle = 'idle';
+    };
+    const withIngress = (fn) => {
+        const next = ingressChain.then(fn, fn);
+        ingressChain = next.then(() => undefined, () => undefined);
+        return next;
+    };
+    /**
+     * Run a held call through the registry, with stages. A gate holds it for its
+     * decision; any other settlement answers the model and lets it go.
+     */
+    const runHeld = async (callId, held, input, resume, per) => {
+        const waiting = held.state;
+        const wasReleased = isReleased(held);
+        held.state = 'running';
+        const host = per.host ?? sessionHost;
+        const record = trace.toolRecord(callId);
+        const exec = executeRegisteredTool({
+            tools: args.tools,
+            profile,
+            name: held.name,
+            input,
+            callId,
+            ctx: {
+                sessionPermissions,
+                credentials: per.credentials ?? sessionCredentials,
+                resolveHost,
+                path,
+                signal,
+                resume,
+                host,
+                turn: { step: Math.max(1, cycleStep) },
+            },
+            snapshot,
+            stages: {
+                handlers: onStage ? [onStage] : [],
+                profile,
+                step: Math.max(1, cycleStep),
+                history: () => history,
+                injectAllowed: profileAllowsInject(profile),
+                host,
+                signal,
+            },
+            openSpan: record.open,
+            readBack: liveReadBack,
+        });
+        let s;
+        try {
+            while (true) {
+                const next = await exec.next();
+                if (next.done) {
+                    s = next.value;
+                    break;
+                }
+                enqueuePending(next.value);
+            }
+        }
+        catch (err) {
+            // It did not settle: it waits as it did, to be run again.
+            held.state = waiting;
+            throw err;
+        }
+        finally {
+            record.finish();
+        }
+        if (s.gated) {
+            if (!releaseGated(callId, held, wasReleased, s.gated, s.gateReadBack)) {
+                held.state = { gate: s.gated, createdAt: Date.now() };
+            }
+            return { gated: s.gated };
+        }
+        if (s.aborted) {
+            // A stage stopped the call. The model still reads an answer, or it
+            // waits for one; then the open cycle ends cancelled, as a turn does.
+            const failure = s.callNotStarted
+                ? {
+                    code: 'cancelled',
+                    kind: 'cancelled',
+                    message: lexiconText('session.tool_aborted', { tool: held.name }, profile.lexicon),
+                }
+                : s.failure;
+            if (s.callNotStarted && failure) {
+                const readBack = formatToolResult(formatToolFailureForModel(failure));
+                enqueuePending(failureEvent({ name: held.name, callId }, failure, readBack));
+                settleHeld(callId, held, readBack);
+            }
+            else {
+                const output = liveToolOutput(s);
+                if (output === undefined)
+                    calls.delete(callId);
+                else
+                    settleHeld(callId, held, output);
+            }
+            const { aborted } = s;
+            await withIngress(async () => {
+                if (cycle === 'open')
+                    await cancelCycle(aborted);
+            });
+            return {
+                outputRaw: s.outputRaw,
+                outputModel: s.modelResult,
+                failure,
+                awaiting: s.awaiting,
+            };
+        }
+        const { pendingInject } = s;
+        if (pendingInject) {
+            await withIngress(async () => {
+                const opened = await openCycleIfNeeded();
+                if (opened.aborted)
+                    return;
+                landInject('post_tool', pendingInject, { callId, toolName: held.name });
+            });
+        }
+        const output = liveToolOutput(s);
+        if (output === undefined)
+            calls.delete(callId);
+        else
+            settleHeld(callId, held, output);
+        return {
+            outputRaw: s.outputRaw,
+            outputModel: s.modelResult,
+            failure: s.failure,
+            awaiting: s.awaiting,
+        };
+    };
+    const gateExpiredError = (callId) => 
+    // lexicon-exempt: developer contract / internal diagnostic — the user reads session.gate_expired
+    new TheoremError('request', `gate ${callId} expired`, {
+        copy: { key: 'session.gate_expired' },
+    });
+    const gateLapsed = (held) => typeof held.state === 'object' && gateExpired(held.state.createdAt, Date.now(), gateTtlMs);
+    /**
+     * The held call `callId`, when it can run now. A gate that waited past
+     * `gateTtlMs` is settled (a held one as abandoned, a released one as lapsed;
+     * the model reads that), then refused.
+     */
+    const takeHeld = async (callId) => {
+        const held = calls.get(callId);
+        if (!held || held.state === 'running') {
+            throw new TheoremError('request', `call ${callId} is not waiting to run`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        if (gateLapsed(held)) {
+            if (isReleased(held))
+                lapseReleased(callId, held);
+            else
+                await runHeld(callId, held, held.arguments, resumeForAnswer({ decision: 'abandon' }), {});
+            throw gateExpiredError(callId);
+        }
+        return held;
+    };
+    const deliverBatch = async function* (item) {
+        holdCalls(item.events);
+        // Usage is held per response and emitted once, reported or estimated, by `settle`.
+        const hostEvents = hostEventsOf(item.events.filter((ev) => ev.type !== 'tokens'), snapshot);
+        const gateStart = performance.now();
+        const gated = await applyOutbound(gate, hostEvents, item.turnPhase, () => {
+            withholdClose = true;
+        });
+        // An abort only drops what the gate held; there is no check to time.
+        if (item.turnPhase !== 'abort')
+            trace.outboundTime(performance.now() - gateStart);
+        for (const ev of gated) {
+            if (ev.type === 'guardrail')
+                trace.outbound(ev);
+        }
+        const doneBatch = yield* yieldLiveNonDoneEvents(gated, includeMatch, recordAssistantText);
+        const tokens = await trace.settle();
+        if (tokens)
+            yield tokens;
+        const interrupted = doneBatch.some((ev) => ev.type === 'done' && ev.interrupted);
+        const completeBoundary = item.turnPhase === 'complete' || item.turnPhase === 'abort' || doneBatch.length > 0;
+        // Boundary batches (`interactionStatus: IDLE`, or bare `turnComplete` when the
+        // provider sends no status) often have no folded `done` — still end the cycle.
+        if (completeBoundary && cycle === 'open') {
+            const boundaryDone = boundaryDoneEvents(doneBatch, item.turnPhase, interrupted);
+            for await (const ev of endCycleAroundDone(boundaryDone)) {
+                yield projectGuardrailTurnEvent(stampDone(ev), includeMatch);
+            }
+            yield* drainPendingHostEvents(pendingHostEvents);
+        }
+        else if (doneBatch.length > 0) {
+            for (const ev of doneBatch) {
+                yield projectGuardrailTurnEvent(stampDone(ev), includeMatch);
+            }
+        }
+    };
+    const streamToHost = async function* () {
+        // Who closes the socket when the loop ends: the host, unless THEOREM stops it.
+        let closer = 'host';
+        let thrown;
+        const provider = connection.batches();
+        // The batch being awaited; it stays pending across wakes, so no frame is read twice.
+        let nextBatch;
+        try {
+            while (true) {
+                nextBatch ??= provider.next();
+                // A tool the host ran, or a stage the session fired, reaches the host
+                // now: a model waiting on a call's result sends nothing meanwhile.
+                const woke = await Promise.race([nextBatch, hostEventQueued()]);
+                throwIfAborted(signal);
+                if (woke === 'queued') {
+                    yield* drainPendingHostEvents(pendingHostEvents);
+                    continue;
+                }
+                nextBatch = undefined;
+                if (woke.done)
+                    break;
+                const item = woke.value;
+                trace.receive(item);
+                yield* drainPendingHostEvents(pendingHostEvents);
+                if (item.type === 'closed') {
+                    if (item.goAway)
+                        yield sessionEndedEvent(item, item.goAway, profile.lexicon);
+                    else if (item.error)
+                        yield toErrorEvent(item.error);
+                    break;
+                }
+                if (item.type === 'error') {
+                    closer = 'theorem';
+                    yield toErrorEvent(item.error);
+                    break;
+                }
+                if (item.type === 'row') {
+                    continue;
+                }
+                yield* deliverBatch(item);
+                if (withholdClose) {
+                    closer = 'theorem';
+                    break;
+                }
+            }
+            yield* drainPendingHostEvents(pendingHostEvents);
+        }
+        catch (err) {
+            thrown = err;
+            throw err;
+        }
+        finally {
+            closed = true;
+            stopLapses();
+            if (withholdClose)
+                closeSocket(1011, 'guardrail withheld', closer);
+            else
+                closeSocket(1000, 'session-closed', closer);
+            // The socket is closed, so a batch still awaited resolves and the provider can finish.
+            await provider.return(undefined);
+            await trace.close({ thrown });
+        }
+    };
+    const session = {
+        profileId: profile.id,
+        canary,
+        async *events() {
+            for await (const raw of streamToHost()) {
+                const event = withPublicWording(raw, profile.lexicon);
+                trace.delivered(event);
+                yield event;
+            }
+        },
+        sendAudio(audio) {
+            return withIngress(async () => {
+                if (!audio.data)
+                    return;
+                assertLiveIngress(profile, 'audio');
+                const opened = await openCycleIfNeeded();
+                if (opened.aborted)
+                    return;
+                sendJson(buildGeminiLiveRealtimeInput({
+                    type: 'audio',
+                    mimeType: audio.mimeType,
+                    data: audio.data,
+                }));
+            });
+        },
+        sendVideo(video) {
+            return withIngress(async () => {
+                assertLiveIngress(profile, 'video');
+                const opened = await openCycleIfNeeded();
+                if (opened.aborted)
+                    return;
+                sendJson(buildGeminiLiveRealtimeInput({
+                    type: 'video',
+                    mimeType: video.mimeType,
+                    data: video.data,
+                }));
+            });
+        },
+        sendText(text) {
+            return withIngress(async () => {
+                assertLiveIngress(profile, 'text');
+                const opened = await openCycleIfNeeded();
+                if (opened.aborted)
+                    return;
+                ingestPreparedLiveText(text);
+            });
+        },
+        sendContext(text) {
+            return withIngress(() => {
+                assertLiveIngress(profile, 'text');
+                const start = performance.now();
+                const prepared = prepareLiveInboundText(profile, text);
+                trace.inboundCheck(performance.now() - start, prepared.guardrail);
+                if (prepared.guardrail)
+                    enqueuePending(prepared.guardrail);
+                sendJson(buildGeminiLiveContext(prepared.text));
+                return Promise.resolve();
+            });
+        },
+        async executeTool({ callId, decision, input, secret, credentials, host, }) {
+            assertOpen();
+            const held = await takeHeld(callId);
+            const gate = typeof held.state === 'object' ? held.state.gate : undefined;
+            if (!gate) {
+                if (decision !== undefined || input !== undefined || secret !== undefined) {
+                    throw new TheoremError('request', `call ${callId} is not waiting on a gate; it takes no decision, input or secret`);
+                }
+                return await runHeld(callId, held, held.arguments, undefined, { credentials, host });
+            }
+            if (decision === undefined) {
+                throw new TheoremError('request', `call ${callId} is waiting on a gate; answer it with a decision`);
+            }
+            const answered = answerGatedCall({ callId, decision, input, secret }, {
+                name: held.name,
+                arguments: held.arguments,
+                permission: gate.permission,
+                ...(gate.kind === 'auth' ? { auth: gate.authChallenge } : {}),
+            }, sessionPermissions ?? []);
+            if (answered.typed) {
+                await (credentials ?? sessionCredentials).set(answered.typed.slot, answered.typed.credential);
+            }
+            sessionPermissions = answered.sessionPermissions;
+            return await runHeld(callId, held, answered.input, answered.resume, {
+                credentials,
+                host,
+            });
+        },
+        answerToolCall({ callId, events }) {
+            assertOpen();
+            const held = calls.get(callId);
+            if (!held || (held.state !== 'open' && !isReleased(held))) {
+                throw new TheoremError('request', `call ${callId} is not waiting for an answer`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            if (gateLapsed(held)) {
+                lapseReleased(callId, held);
+                throw gateExpiredError(callId);
+            }
+            let settled;
+            for (const ev of events) {
+                if (ev.type !== 'tool')
+                    continue;
+                if (ev.tool.phase === undefined || ev.tool.callId !== callId) {
+                    throw new TheoremError('request', `the run answering call ${callId} carries a call of its own (${ev.tool.callId})`);
+                }
+                if (isSettledPhase(ev.tool))
+                    settled = ev.tool;
+            }
+            if (!settled) {
+                throw new TheoremError('request', `the run answering call ${callId} settled nothing`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            const forward = () => {
+                for (const ev of events) {
+                    if (ev.type !== 'done')
+                        enqueuePending(ev);
+                }
+            };
+            if (settled.phase === 'gate') {
+                forward();
+                releaseGated(callId, held, isReleased(held), settled.gate, settled.readBack);
+                return { gated: settled.gate };
+            }
+            const { readBack } = settled;
+            if (readBack === undefined) {
+                throw new TheoremError('request', `the run answering call ${callId} carries no readBack`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            forward();
+            settleHeld(callId, held, readBack);
+            return settled.phase === 'complete'
+                ? { outputRaw: settled.output, ...(settled.awaiting ? { awaiting: true } : {}) }
+                : { failure: settled.failure };
+        },
+        close(reason = 'session-closed') {
+            if (!closed) {
+                closed = true;
+                stopLapses();
+                closeSocket(1000, reason, 'host');
+            }
+            // The session record is sealed here; frames the host reads after closing are not in it.
+            return trace.close({});
+        },
+    };
+    if (args.openInitialCycle) {
+        void withIngress(async () => {
+            await openCycleIfNeeded();
+        });
+    }
+    return session;
+}
+/**
+ * The session record is written however the session ends, including when opening fails. An unknown
+ * profile fails to open and is recorded under the standard observability policy.
+ */
+export async function runSessionInRegistry(registry, req, options, sinkOverride) {
+    const trace = startLiveTrace(req, registry.profiles.find(req.profile)?.observability, sinkOverride);
+    try {
+        return await openTracedSession(registry, req, options, trace);
+    }
+    catch (err) {
+        await trace.close({ thrown: err });
+        throw err;
+    }
+}
+async function openTracedSession(registry, req, options, trace) {
+    const gateTtlMs = resolveGateTtlMs('runSession', options.gateTtlMs);
+    const turnReq = toTurnRequest(req);
+    const safe = sanitizeTurnRequest(turnReq, registry.profiles.get(turnReq.profile));
+    throwIfAborted(safe.signal);
+    const { profile, generation: gen0 } = resolveTurnInRegistry(registry, safe);
+    assertLiveProfile(profile);
+    if (req.snapshot) {
+        gen0.tools = sessionSnapshotWithinAllow(profile, req.snapshot);
+    }
+    gen0.builtins = gen0.tools.builtins;
+    let generation = applyVoiceOverride(gen0, req.voice);
+    const hasInitialInput = Boolean(req.input && req.input.length > 0);
+    generation = applyInitialInput(generation, req.input);
+    const system = bindSystem(generation.resolvedSystem, [
+        canaryNote(generation.canary, profile.lexicon),
+        userDataNote(profile.lexicon),
+    ]);
+    const completeReq = {
+        ...providerCompleteRequest(registry.tools, generation, system.text),
+        signal: safe.signal,
+        tapUpstream: trace.sent,
+    };
+    const binding = profile.models[generation.model];
+    trace.bind({
+        request: completeReq,
+        generation,
+        binding,
+        family: binding ? mediaTokenFamily(binding) : undefined,
+        system: system.text,
+        canary: generation.canary,
+    });
+    const givenUrls = givenUrlSets();
+    addRequestUrls(givenUrls, completeReq);
+    addHistoryUrls(givenUrls, req.history ?? []);
+    const gate = createLiveOutboundGateSession(profile, generation.canary || undefined, system.private, givenUrls);
+    const connection = await openGoogleLiveSession(completeReq, { ...options.gemini, vault: options.vault }, options.openWebSocket);
+    trace.setup(connection.setup);
+    return buildLiveSession({
+        tools: registry.tools,
+        profile,
+        canary: generation.canary,
+        connection,
+        gate,
+        givenUrls,
+        signal: safe.signal,
+        onStage: req.onStage,
+        host: req.host,
+        credentials: req.credentials,
+        resolveHost: req.resolveHost,
+        sessionPermissions: req.sessionPermissions,
+        path: req.path,
+        snapshot: gen0.tools,
+        historySeed: req.history,
+        openInitialCycle: hasInitialInput,
+        trace,
+        gateTtlMs,
+        signInGate: options.signInGate ?? 'hold',
+    });
+}