@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,1182 @@
+import { canaryNote, contextNote, USER_CLOSE, USER_OPEN, userDataNote, } from '../../../guardrails/canary.js';
+import { addGivenDestinations, addHistoryDestinations, addRequestDestinations, addResultDestinations, turnDestinations, } from '../../../guardrails/destinations.js';
+import { addHistoryUrls, addRequestUrls, addSeenUrls, givenUrlSets, } from '../../../guardrails/egress-urls.js';
+import { describeError, errorKind, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, } from '../../../guardrails/error.js';
+import { projectGuardrailTurnEvent } from '../../../guardrails/events.js';
+import { labelText } from '../../../guardrails/labels.js';
+import { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from '../../../guardrails/live-outbound-gate.js';
+import { sanitizeTurnRequestWithEvents } from '../../../guardrails/sanitize.js';
+import { recordTaint } from '../../../guardrails/tool-result.js';
+import { resolveObservabilityPolicy } from '../../../observability/resolve-policy.js';
+import { liveToolReadBack } from '../../../providers/live.js';
+import { memoryCredentialSource } from '../../auth/credential-source.js';
+import { historyHash } from '../../checkpoint.js';
+import { openRegisteredLiveSession } from '../../provider-live.js';
+import { assertHistoryKept } from '../../provider-runtime.js';
+import { assertTurnContext } from '../../registry/ingress.js';
+import { providerCompleteRequest } from '../../registry/provider-request.js';
+import { resolveTurnInRegistry } from '../../registry/resolve.js';
+import { fillSlots } from '../../registry/slot-fill.js';
+import { DEFAULT_RESUMED_AFTER_MS } from '../../schema.js';
+import { injectedStageEvent, runStage, stageEventFields, } from '../../stages.js';
+import { profileAllowsInject, stageAbortStop } from '../../stop.js';
+import { bindSystem } from '../../system-parts.js';
+import { failedActivity, failureEvent } from '../../tools/events.js';
+import { executeRegisteredTool, lapsedGateFailure, shownToolArguments, } from '../../tools/execute.js';
+import { answerGatedCall, gateExpired, resolveGateTtlMs, resumeForAnswer, } from '../../tools/gate-answer.js';
+import { formatToolFailureForModel, formatToolResult } from '../../tools/model-text.js';
+import { ownToolsOf } from '../../tools/project.js';
+import { cloneTurnToolSnapshot } from '../../tools/resolve.js';
+import { turnDoneOf } from '../../turn-events.js';
+import { prepareLiveContext, prepareLiveInboundText } from '../live-inbound.js';
+import { assertLiveIngress } from '../live-ingress.js';
+import { sessionAgentCaller } from '../runner/mod.js';
+import { startLiveTrace } from './session-trace.js';
+function pageAnswerForLiveRequest(page, execution) {
+    return page ?? (execution ? undefined : { unanswered: true });
+}
+function isUnresolvedOperationError(error) {
+    if (!(error instanceof TheoremError) || !error.copy)
+        return false;
+    return 'key' in error.copy
+        ? error.copy.key === 'tool.execution_uncertain'
+        : error.copy.some((copy) => copy.key === 'tool.execution_uncertain');
+}
+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, labels) {
+    const internal = closed.error ? describeError(closed.error) : closed.reason;
+    return {
+        type: 'session',
+        session: {
+            kind: 'ended',
+            ...(goAway.timeLeftMs !== undefined ? { timeLeftMs: goAway.timeLeftMs } : {}),
+            message: labelText('live.session_ended', {}, labels),
+            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) {
+        // labels-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,
+        providerState: req.providerState,
+        system: req.system,
+        builtInArgs: req.builtInArgs,
+        path: req.path,
+        sessionPermissions: req.sessionPermissions,
+        signal: req.signal,
+        metadata: req.metadata,
+        host: req.host,
+        input: {
+            text: '',
+            history: req.history,
+            slots: req.slots,
+        },
+    };
+}
+/**
+ * The prompt the session opens with: the greeting on a new call, the resume prompt when the
+ * caller was away long enough to notice. It is the profile's own copy, so no boundary reads it.
+ */
+function openingPrompt(profile, req, slots) {
+    const { greeting, resumed } = profile.live;
+    if (!req.providerState && !req.history?.length) {
+        return greeting ? fillSlots(profile, greeting, slots, 'live.greeting') : undefined;
+    }
+    if (!resumed || (req.awayMs ?? 0) < (resumed.afterMs ?? DEFAULT_RESUMED_AFTER_MS)) {
+        return undefined;
+    }
+    return fillSlots(profile, resumed.prompt, slots, 'live.resumed.prompt');
+}
+/** Refuses context the profile's `inputs.context` does not take. */
+function assertSessionContext(profile, context) {
+    assertTurnContext(profile, { profile: profile.id, input: { context } });
+}
+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);
+        return events.filter((ev) => ev.type === 'tool' ||
+            ev.type === 'session' ||
+            (ev.type === 'done' && ev.interrupted === true));
+    }
+    const batch = await processLiveOutboundBatch(gate, events);
+    if (batch.action === 'withhold') {
+        onWithhold();
+        return [
+            ...(batch.events ?? []).filter((event) => !isTurnComplete(event) && event.type !== 'provider_checkpoint'),
+            toErrorEvent(batch.error),
+        ];
+    }
+    const out = batch.action === 'emit' ? batch.events : [];
+    if (turnPhase !== 'complete')
+        return out;
+    // why: The response is whole only once its verdict is in: `turn_complete` follows what the
+    // verdict released, and a withheld response ends on its error.
+    const said = out.filter((event) => !isTurnComplete(event));
+    const finalized = await finalizeLiveOutboundTurn(gate);
+    if (finalized.action === 'withhold') {
+        onWithhold();
+        return [
+            ...said.filter((event) => event.type !== 'provider_checkpoint'),
+            ...(finalized.events ?? []),
+            toErrorEvent(finalized.error),
+        ];
+    }
+    return [
+        ...said,
+        ...(finalized.action === 'emit' ? finalized.events : []),
+        ...out.filter(isTurnComplete),
+        { type: 'done', stop: { kind: 'completed' } },
+    ];
+}
+function isTurnComplete(event) {
+    return event.type === 'session' && event.session.kind === 'turn_complete';
+}
+/**
+ * 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: liveToolReadBack(output), parts: s.modelResult?.parts };
+}
+/**
+ * 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' || ev.type === 'reasoning')
+            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 recordLiveHistory(events, recordUserText, recordAssistantText) {
+    for (const event of events) {
+        if (event.type === 'text')
+            recordAssistantText(event.text);
+        if (event.type === 'evidence' &&
+            event.text &&
+            (event.evidence.kind === 'input_transcription' ||
+                event.evidence.kind === 'output_transcription') &&
+            !event.evidence.interim) {
+            if (event.evidence.kind === 'input_transcription')
+                recordUserText(event.text);
+            if (event.evidence.kind === 'output_transcription' &&
+                !events.some((item) => item.type === 'text'))
+                recordAssistantText(event.text);
+        }
+    }
+}
+async function sealLiveCheckpoints(events, history, calls, keepsHistory) {
+    const sealed = [];
+    for (const event of events) {
+        if (!keepsHistory && event.type === 'provider_checkpoint')
+            continue;
+        if (!keepsHistory && event.type === 'done') {
+            const { providerState: _dropped, ...standsAlone } = event;
+            sealed.push(standsAlone);
+            continue;
+        }
+        if ((event.type === 'provider_checkpoint' || event.type === 'done') && event.providerState) {
+            const covered = [...history];
+            for (const [callId, held] of calls) {
+                if (covered.some((message) => message.tool_calls?.some((call) => call.id === callId)))
+                    continue;
+                covered.push({
+                    role: 'assistant',
+                    tool_calls: [
+                        {
+                            id: callId,
+                            type: 'function',
+                            function: { name: held.name, arguments: JSON.stringify(held.arguments) },
+                        },
+                    ],
+                });
+            }
+            sealed.push({
+                ...event,
+                ...(event.type === 'provider_checkpoint' ? { history: structuredClone(covered) } : {}),
+                providerState: {
+                    ...event.providerState,
+                    coveredHistoryLength: covered.length,
+                    coveredHistoryHash: await historyHash(covered),
+                },
+            });
+        }
+        else
+            sealed.push(event);
+    }
+    return sealed;
+}
+function* yieldLiveNonDoneEvents(gated, includeMatch) {
+    const doneBatch = gated.filter((ev) => ev.type === 'done');
+    for (const ev of gated) {
+        if (ev.type === 'done')
+            continue;
+        yield projectGuardrailTurnEvent(ev, includeMatch ?? false);
+    }
+    return doneBatch;
+}
+function buildLiveSession(args) {
+    const { profile, canary, connection, gate, givenUrls, destinations, 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 the model is silent. */
+    let wakeHost;
+    const includeMatch = resolveObservabilityPolicy(profile.observability).include
+        .guardrailMatchPreview;
+    let cycle = 'idle';
+    let cycleStep = 0;
+    /** What this cycle's tool results read from outside the host; a cycle starts clean, as a turn does. */
+    let cycleTaint;
+    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);
+        addGivenDestinations(destinations, trimmed);
+    };
+    const recordAssistantText = (text) => {
+        if (!text)
+            return;
+        const last = history.at(-1);
+        if (last?.role === 'assistant' && typeof last.content === 'string' && !last.tool_calls) {
+            last.content = `${last.content}${text}`;
+            return;
+        }
+        history.push({ role: 'assistant', content: text });
+    };
+    const recordToolSettle = (tool, readBack, parts) => {
+        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,
+            ...(parts?.length ? { parts } : {}),
+        });
+        addSeenUrls(givenUrls.tools, readBack);
+    };
+    const enqueuePending = (ev) => {
+        pendingHostEvents.push(projectGuardrailTurnEvent(ev, includeMatch));
+        const wake = wakeHost;
+        wakeHost = undefined;
+        wake?.();
+    };
+    for (const ev of args.requestEvents)
+        enqueuePending(ev);
+    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'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    };
+    const sendInput = (input) => {
+        assertOpen();
+        connection.sendInput(input);
+    };
+    const answerModel = (callId, held, readBack, parts) => {
+        recordToolSettle({ name: held.name, callId, arguments: held.arguments }, readBack, parts);
+        assertOpen();
+        connection.sendToolResponse(callId, held.name, readBack, parts);
+    };
+    const settleHeld = (callId, held, readBack, parts) => {
+        clearTimeout(held.lapse);
+        calls.delete(callId);
+        answerModel(callId, held, readBack, parts);
+    };
+    const settleHeldFailure = (callId, held, failure) => {
+        const readBack = formatToolResult(formatToolFailureForModel(failure));
+        enqueuePending(failureEvent({
+            name: held.name,
+            callId,
+            operationId: held.operationId,
+            activityFailed: failedActivity(held.name, profile.labels),
+        }, failure, readBack));
+        settleHeld(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.labels);
+        settleHeldFailure(callId, held, failure);
+    };
+    /** 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,
+                    operationId: tool.operationId ?? crypto.randomUUID(),
+                    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' &&
+                held.state !== 'uncertain') {
+                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,
+        };
+    };
+    /** The text to send, or `undefined` when a match blocks it: the message does not reach the model. */
+    const readLiveText = (text) => {
+        const start = performance.now();
+        const prepared = prepareLiveInboundText(profile, text);
+        trace.inboundCheck(performance.now() - start, prepared.guardrail);
+        if (prepared.guardrail)
+            enqueuePending(prepared.guardrail);
+        return prepared.text;
+    };
+    /** Context is background: it joins no history and opens no cycle, and its addresses count as given. */
+    const landContext = (context) => {
+        assertSessionContext(profile, context);
+        const start = performance.now();
+        const prepared = prepareLiveContext(profile, context);
+        trace.inboundCheck(performance.now() - start, prepared.guardrails[0]);
+        for (const guardrail of prepared.guardrails)
+            enqueuePending(guardrail);
+        for (const text of prepared.texts) {
+            addSeenUrls(givenUrls.request, text);
+            addGivenDestinations(destinations, text);
+            assertOpen();
+            connection.sendContext(text);
+        }
+    };
+    const ingestPreparedLiveText = (text) => {
+        const safe = readLiveText(text);
+        if (safe === undefined)
+            return;
+        recordUserText(safe.slice(USER_OPEN.length + 1, -(USER_CLOSE.length + 1)));
+        sendInput({ type: 'text', text: safe });
+    };
+    /**
+     * 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', // labels-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);
+        // why: Idle first, so a boundary the provider 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;
+        cycleTaint = undefined;
+        destinations.remote.clear();
+        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 flush = async () => {
+            await fn();
+            await connection.flush?.();
+        };
+        const next = ingressChain.then(flush, flush);
+        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 runHeldCore = 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);
+        let dispatched = false;
+        const exec = executeRegisteredTool({
+            onDispatch: () => {
+                dispatched = true;
+            },
+            tools: args.tools,
+            agents: args.agents,
+            execution: args.execution,
+            profile,
+            name: held.name,
+            input,
+            callId,
+            ctx: {
+                operationId: held.operationId,
+                sessionPermissions,
+                credentials: per.credentials ?? sessionCredentials,
+                resolveHost,
+                path,
+                signal,
+                resume,
+                host,
+                // why: A call opens no second line to the page, so a call the page did not answer is not held for it.
+                page: pageAnswerForLiveRequest(per.page, args.pageExecution),
+                pageExecution: args.pageExecution,
+                turn: { step: Math.max(1, cycleStep), taint: cycleTaint, destinations },
+            },
+            snapshot,
+            stages: {
+                handlers: onStage ? [onStage] : [],
+                profile,
+                step: Math.max(1, cycleStep),
+                history: () => history,
+                injectAllowed: profileAllowsInject(profile),
+                host,
+                signal,
+            },
+            scope: gate.context,
+            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) {
+            // invariant: A dispatched call with no outcome cannot regain approval authority.
+            const unresolved = dispatched || isUnresolvedOperationError(err);
+            held.state = unresolved ? 'uncertain' : waiting;
+            if (unresolved)
+                throw new TheoremError('unavailable', labelText('tool.execution_uncertain', {}, profile.labels), {
+                    copy: { key: 'tool.execution_uncertain' },
+                    cause: err,
+                });
+            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) {
+            // why: 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: labelText('session.tool_aborted', { tool: held.name }, profile.labels),
+                }
+                : s.failure;
+            if (s.callNotStarted && failure) {
+                settleHeldFailure(callId, held, failure);
+            }
+            else {
+                const output = liveToolOutput(s);
+                if (output === undefined)
+                    calls.delete(callId);
+                else
+                    settleHeld(callId, held, output, s.modelResult?.parts);
+            }
+            const { aborted } = s;
+            await withIngress(async () => {
+                if (cycle === 'open')
+                    await cancelCycle(aborted);
+            });
+            return {
+                outputRaw: s.outputRaw,
+                outputModel: s.modelResult,
+                failure,
+                awaiting: s.awaiting,
+            };
+        }
+        if (s.modelResult?.provenance) {
+            cycleTaint = recordTaint(cycleTaint, s.modelResult.provenance, s.modelResult.suspicious);
+            addResultDestinations(destinations, s.modelResult, s.modelResult.provenance);
+        }
+        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, s.modelResult?.parts);
+        return {
+            outputRaw: s.outputRaw,
+            outputModel: s.modelResult,
+            failure: s.failure,
+            awaiting: s.awaiting,
+        };
+    };
+    const runHeld = async (...input) => {
+        const result = await runHeldCore(...input);
+        await connection.flush?.();
+        return result;
+    };
+    const gateExpiredError = (callId) => 
+    // labels-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, operationId) => {
+        const held = calls.get(callId);
+        if (!held || held.state === 'running') {
+            throw new TheoremError('request', `call ${callId} is not waiting to run`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        if (operationId !== undefined && operationId !== held.operationId) {
+            throw new TheoremError('request', labelText('session.gate_expired', {}, profile.labels), {
+                copy: { key: 'session.gate_expired' },
+            });
+        }
+        if (held.state === 'uncertain')
+            throw new TheoremError('unavailable', labelText('tool.execution_uncertain', {}, profile.labels), {
+                copy: { key: 'tool.execution_uncertain' },
+            });
+        if (gateLapsed(held)) {
+            if (isReleased(held))
+                lapseReleased(callId, held);
+            else
+                await runHeld(callId, held, held.arguments, resumeForAnswer({ decision: 'abandon' }), {});
+            throw gateExpiredError(callId);
+        }
+        return held;
+    };
+    /** The model's call as the host is shown it: its arguments as the tool gets them. */
+    const asToolGetsIt = (event) => {
+        if (event.type !== 'tool' || event.tool.phase !== undefined)
+            return event;
+        const { name, arguments: input } = event.tool;
+        const shown = shownToolArguments({
+            tools: args.tools,
+            profile,
+            name,
+            input,
+            scope: gate.context,
+        });
+        return { ...event, tool: { ...event.tool, arguments: shown } };
+    };
+    const deliverBatch = async function* (item) {
+        const identities = new Map();
+        const events = item.events.map((event) => {
+            if (event.type !== 'tool')
+                return event;
+            const { tool } = event;
+            if (tool.phase === undefined) {
+                if (calls.has(tool.callId) || identities.has(tool.callId)) {
+                    throw new TheoremError('bad_response', labelText('provider.duplicate_call', {}, profile.labels), { cause: { code: 'duplicate_pending_call' } });
+                }
+                identities.set(tool.callId, crypto.randomUUID());
+            }
+            const operationId = identities.get(tool.callId) ?? calls.get(tool.callId)?.operationId;
+            return { ...event, tool: { ...tool, operationId } };
+        });
+        holdCalls(events);
+        // why: Usage is held per response and emitted once, reported or estimated, by `settle`.
+        const hostEvents = hostEventsOf(events.filter((ev) => ev.type !== 'tokens'), snapshot).map(asToolGetsIt);
+        const gateStart = performance.now();
+        const gated = await applyOutbound(gate, hostEvents, item.turnPhase, () => {
+            withholdClose = true;
+        });
+        // why: 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);
+        }
+        recordLiveHistory(gated, recordUserText, recordAssistantText);
+        const sealed = await sealLiveCheckpoints(gated, history, calls, profile.providerContinuation?.history !== 'stateless');
+        const doneBatch = yield* yieldLiveNonDoneEvents(sealed, includeMatch);
+        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;
+        // why: 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* () {
+        // why: Who closes the socket when the loop ends: the host, unless THEOREM stops it.
+        let closer = 'host';
+        let thrown;
+        const provider = connection.batches();
+        // why: The batch being awaited; it stays pending across wakes, so no frame is read twice.
+        let nextBatch;
+        try {
+            while (true) {
+                nextBatch ??= provider.next();
+                // why: 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.labels);
+                    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);
+            // why: 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 = withPublicLabels(raw, profile.labels);
+                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;
+                sendInput({ type: 'audio', mimeType: audio.mimeType, data: audio.data });
+            });
+        },
+        sendVideo(video) {
+            return withIngress(async () => {
+                assertLiveIngress(profile, 'video');
+                const opened = await openCycleIfNeeded();
+                if (opened.aborted)
+                    return;
+                sendInput({ 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(context) {
+            return withIngress(() => {
+                landContext(context);
+                return Promise.resolve();
+            });
+        },
+        async executeTool({ callId, operationId, decision, input, secret, credentials, host, page, }) {
+            assertOpen();
+            const held = await takeHeld(callId, operationId);
+            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, page });
+            }
+            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: gate.preparedArguments ?? held.arguments,
+                permission: gate.permission,
+                gateKind: gate.kind,
+                ...(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,
+                page,
+            });
+        },
+        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`); // labels-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 (ev.tool.operationId !== held.operationId || ev.tool.name !== held.name) {
+                    throw new TheoremError('request', labelText('session.gate_expired', {}, profile.labels), {
+                        copy: { key: 'session.gate_expired' },
+                    });
+                }
+                if (isSettledPhase(ev.tool))
+                    settled = ev.tool;
+            }
+            if (!settled) {
+                throw new TheoremError('request', `the run answering call ${callId} settled nothing`); // labels-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`); // labels-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 };
+        },
+        async close(reason = 'session-closed') {
+            if (!closed) {
+                closed = true;
+                stopLapses();
+                closeSocket(1000, reason, 'host');
+            }
+            // why: The session record is sealed here; frames the host reads after closing are not in it.
+            await connection.flush?.();
+            return trace.close({});
+        },
+    };
+    const { initialContext, opening } = args;
+    if (args.openInitialCycle || initialContext || opening) {
+        void withIngress(async () => {
+            if (initialContext)
+                landContext(initialContext);
+            if (!args.openInitialCycle && !opening)
+                return;
+            const opened = await openCycleIfNeeded();
+            if (opening && !opened.aborted) {
+                sendInput({ type: 'text', text: opening });
+            }
+        });
+    }
+    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), 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 { request: safe, events: requestEvents, refusal, } = sanitizeTurnRequestWithEvents(turnReq, registry.profiles.get(turnReq.profile));
+    if (refusal)
+        throw refusal;
+    throwIfAborted(safe.signal);
+    const { profile, generation: gen0 } = resolveTurnInRegistry(registry, safe);
+    assertLiveProfile(profile);
+    if (req.context)
+        assertSessionContext(profile, req.context);
+    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.labels),
+        userDataNote(profile.labels),
+        profile.inputs?.context ? contextNote(profile.labels) : '',
+    ]);
+    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,
+        system: system.text,
+        canary: generation.canary,
+    });
+    const givenUrls = givenUrlSets();
+    addRequestUrls(givenUrls, completeReq);
+    addHistoryUrls(givenUrls, req.history ?? []);
+    const destinations = turnDestinations();
+    addRequestDestinations(destinations, completeReq, givenUrls.own);
+    addHistoryDestinations(destinations, req.history ?? [], givenUrls.own);
+    const gate = await createLiveOutboundGateSession(profile, generation.canary || undefined, system.private, givenUrls, ownToolsOf(registry.tools, profile));
+    assertHistoryKept(profile.providerContinuation, req.providerState, req.history);
+    const definition = registry.providers.require(binding.provider, binding.apiId);
+    const connection = await openRegisteredLiveSession(definition, { ...binding }, completeReq, options, req.providerState, profile.providerContinuation);
+    trace.setup(connection.setup);
+    return buildLiveSession({
+        execution: options.execution,
+        pageExecution: options.pageExecution,
+        tools: registry.tools,
+        profile,
+        canary: generation.canary,
+        connection,
+        gate,
+        givenUrls,
+        destinations,
+        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,
+        requestEvents,
+        initialContext: req.context,
+        opening: hasInitialInput ? undefined : openingPrompt(profile, req, safe.input?.slots),
+        trace,
+        agents: sessionAgentCaller(registry, req, options, trace.agentCanaries),
+        gateTtlMs,
+        signInGate: options.signInGate ?? 'hold',
+    });
+}