@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -1,29 +1,47 @@
-import { canaryNote, userDataNote } from '../../../guardrails/canary.js';
+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, withPublicWording, } from '../../../guardrails/error.js';
+import { describeError, errorKind, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, } from '../../../guardrails/error.js';
 import { projectGuardrailTurnEvent } from '../../../guardrails/events.js';
-import { lexiconText } from '../../../guardrails/lexicon.js';
+import { labelText } from '../../../guardrails/labels.js';
 import { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from '../../../guardrails/live-outbound-gate.js';
-import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { sanitizeTurnRequestWithEvents } from '../../../guardrails/sanitize.js';
+import { recordTaint } from '../../../guardrails/tool-result.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 { 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 { failureEvent } from '../../tools/events.js';
-import { executeRegisteredTool, lapsedGateFailure, } from '../../tools/execute.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 { prepareLiveInboundText } from '../live-inbound.js';
+import { prepareLiveContext, prepareLiveInboundText } from '../live-inbound.js';
 import { assertLiveIngress } from '../live-ingress.js';
-import { mediaTokenFamily } from '../token-estimate.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;
 }
@@ -35,14 +53,14 @@ function isSettledPhase(tool) {
  * 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) {
+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: lexiconText('live.session_ended', {}, lexicon),
+            message: labelText('live.session_ended', {}, labels),
             ended: {
                 cause: 'go_away',
                 code: closed.code,
@@ -84,7 +102,7 @@ function sessionSnapshotWithinAllow(profile, snapshot) {
         }
     }
     if (outside.size > 0) {
-        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        // 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}`);
     }
@@ -93,20 +111,39 @@ function sessionSnapshotWithinAllow(profile, snapshot) {
 function toTurnRequest(req) {
     return {
         profile: req.profile,
+        providerState: req.providerState,
         system: req.system,
+        builtInArgs: req.builtInArgs,
         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,
+            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;
@@ -128,33 +165,42 @@ function applyInitialInput(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);
+        return [
+            ...(batch.events ?? []).filter((event) => !isTurnComplete(event) && event.type !== 'provider_checkpoint'),
+            toErrorEvent(batch.error),
+        ];
     }
-    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' } });
+    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 out;
+    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
@@ -172,7 +218,7 @@ function liveReadBack(s) {
     const output = liveToolOutput(s);
     return output === undefined
         ? undefined
-        : { text: JSON.stringify(liveFunctionResponsePayload(output)) };
+        : { text: liveToolReadBack(output), parts: s.modelResult?.parts };
 }
 /**
  * A provider batch as the host receives it: a call's `done` becomes the
@@ -180,7 +226,7 @@ function liveReadBack(s) {
  */
 function hostEventsOf(events, snapshot) {
     return events.flatMap((ev) => {
-        if (ev.type === 'response')
+        if (ev.type === 'response' || ev.type === 'reasoning')
             return [];
         if (ev.type !== 'done')
             return [ev];
@@ -203,20 +249,75 @@ function boundaryDoneEvents(doneBatch, turnPhase, interrupted) {
     }
     return [{ type: 'done', stop: { kind: 'completed' } }];
 }
-function* yieldLiveNonDoneEvents(gated, includeMatch, recordAssistantText) {
+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;
-        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;
+    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. */
@@ -225,12 +326,14 @@ function buildLiveSession(args) {
     let closed = false;
     let withholdClose = false;
     const pendingHostEvents = [];
-    /** Wakes the host's stream when the session queues an event while Gemini is silent. */
+    /** 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)
         : [];
@@ -242,19 +345,19 @@ function buildLiveSession(args) {
             return;
         history.push({ role: 'user', content: trimmed });
         addSeenUrls(givenUrls.request, trimmed);
+        addGivenDestinations(destinations, trimmed);
     };
     const recordAssistantText = (text) => {
-        const trimmed = text.trim();
-        if (!trimmed)
+        if (!text)
             return;
         const last = history.at(-1);
         if (last?.role === 'assistant' && typeof last.content === 'string' && !last.tool_calls) {
-            last.content = `${last.content}${trimmed}`;
+            last.content = `${last.content}${text}`;
             return;
         }
-        history.push({ role: 'assistant', content: trimmed });
+        history.push({ role: 'assistant', content: text });
     };
-    const recordToolSettle = (tool, readBack) => {
+    const recordToolSettle = (tool, readBack, parts) => {
         history.push({
             role: 'assistant',
             tool_calls: [
@@ -272,6 +375,7 @@ function buildLiveSession(args) {
             tool_call_id: tool.callId,
             name: tool.name,
             content: readBack,
+            ...(parts?.length ? { parts } : {}),
         });
         addSeenUrls(givenUrls.tools, readBack);
     };
@@ -281,6 +385,8 @@ function buildLiveSession(args) {
         wakeHost = undefined;
         wake?.();
     };
+    for (const ev of args.requestEvents)
+        enqueuePending(ev);
     const hostEventQueued = () => pendingHostEvents.length > 0
         ? Promise.resolve('queued')
         : new Promise((resolve) => {
@@ -288,31 +394,40 @@ function buildLiveSession(args) {
         });
     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)
+            throw new TheoremError('request', 'Live session is closed'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
     };
-    const sendJson = (payload) => {
+    const sendInput = (input) => {
         assertOpen();
-        connection.send(payload);
+        connection.sendInput(input);
     };
-    const answerModel = (callId, held, readBack) => {
-        recordToolSettle({ name: held.name, callId, arguments: held.arguments }, readBack);
-        sendJson(buildGeminiLiveToolResponse(callId, held.name, readBack));
+    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) => {
+    const settleHeld = (callId, held, readBack, parts) => {
         clearTimeout(held.lapse);
         calls.delete(callId);
-        answerModel(callId, held, readBack);
+        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.lexicon);
-        const readBack = formatToolResult(formatToolFailureForModel(failure));
-        enqueuePending(failureEvent({ name: held.name, callId }, failure, readBack));
-        settleHeld(callId, held, readBack);
+        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 = () => {
@@ -346,7 +461,12 @@ function buildLiveSession(args) {
                 continue;
             const tool = ev.tool;
             if (tool.phase === undefined) {
-                calls.set(tool.callId, { name: tool.name, arguments: tool.arguments, state: 'open' });
+                calls.set(tool.callId, {
+                    name: tool.name,
+                    arguments: tool.arguments,
+                    operationId: tool.operationId ?? crypto.randomUUID(),
+                    state: 'open',
+                });
                 continue;
             }
             const held = calls.get(tool.callId);
@@ -355,7 +475,9 @@ function buildLiveSession(args) {
             if (tool.phase === 'error' && tool.readBack !== undefined) {
                 settleHeld(tool.callId, held, tool.readBack);
             }
-            else if (tool.phase === 'cancel' && held.state !== 'running') {
+            else if (tool.phase === 'cancel' &&
+                held.state !== 'running' &&
+                held.state !== 'uncertain') {
                 calls.delete(tool.callId);
             }
         }
@@ -394,14 +516,36 @@ function buildLiveSession(args) {
             inject: result.value.inject,
         };
     };
-    const ingestPreparedLiveText = (text) => {
+    /** 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);
-        recordUserText(prepared.text);
-        sendJson(buildGeminiLiveRealtimeInput({ type: 'text', text: prepared.text }));
+        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),
@@ -419,7 +563,7 @@ function buildLiveSession(args) {
                         {
                             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)
+                            message: 'live ingress takes plain-text inject messages only; inject refused', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                         },
                     ],
                 });
@@ -438,7 +582,7 @@ function buildLiveSession(args) {
     /** 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.
+        // 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 });
@@ -448,6 +592,8 @@ function buildLiveSession(args) {
             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);
@@ -480,7 +626,11 @@ function buildLiveSession(args) {
         cycle = 'idle';
     };
     const withIngress = (fn) => {
-        const next = ingressChain.then(fn, fn);
+        const flush = async () => {
+            await fn();
+            await connection.flush?.();
+        };
+        const next = ingressChain.then(flush, flush);
         ingressChain = next.then(() => undefined, () => undefined);
         return next;
     };
@@ -488,19 +638,26 @@ function buildLiveSession(args) {
      * 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 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,
@@ -508,7 +665,10 @@ function buildLiveSession(args) {
                 signal,
                 resume,
                 host,
-                turn: { step: Math.max(1, cycleStep) },
+                // 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: {
@@ -520,6 +680,7 @@ function buildLiveSession(args) {
                 host,
                 signal,
             },
+            scope: gate.context,
             openSpan: record.open,
             readBack: liveReadBack,
         });
@@ -535,8 +696,14 @@ function buildLiveSession(args) {
             }
         }
         catch (err) {
-            // It did not settle: it waits as it did, to be run again.
-            held.state = waiting;
+            // 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 {
@@ -549,26 +716,24 @@ function buildLiveSession(args) {
             return { gated: s.gated };
         }
         if (s.aborted) {
-            // A stage stopped the call. The model still reads an answer, or it
+            // 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: lexiconText('session.tool_aborted', { tool: held.name }, profile.lexicon),
+                    message: labelText('session.tool_aborted', { tool: held.name }, profile.labels),
                 }
                 : s.failure;
             if (s.callNotStarted && failure) {
-                const readBack = formatToolResult(formatToolFailureForModel(failure));
-                enqueuePending(failureEvent({ name: held.name, callId }, failure, readBack));
-                settleHeld(callId, held, readBack);
+                settleHeldFailure(callId, held, failure);
             }
             else {
                 const output = liveToolOutput(s);
                 if (output === undefined)
                     calls.delete(callId);
                 else
-                    settleHeld(callId, held, output);
+                    settleHeld(callId, held, output, s.modelResult?.parts);
             }
             const { aborted } = s;
             await withIngress(async () => {
@@ -582,6 +747,10 @@ function buildLiveSession(args) {
                 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 () => {
@@ -595,7 +764,7 @@ function buildLiveSession(args) {
         if (output === undefined)
             calls.delete(callId);
         else
-            settleHeld(callId, held, output);
+            settleHeld(callId, held, output, s.modelResult?.parts);
         return {
             outputRaw: s.outputRaw,
             outputModel: s.modelResult,
@@ -603,8 +772,13 @@ function buildLiveSession(args) {
             awaiting: s.awaiting,
         };
     };
+    const runHeld = async (...input) => {
+        const result = await runHeldCore(...input);
+        await connection.flush?.();
+        return result;
+    };
     const gateExpiredError = (callId) => 
-    // lexicon-exempt: developer contract / internal diagnostic — the user reads session.gate_expired
+    // labels-exempt: developer contract / internal diagnostic — the user reads session.gate_expired
     new TheoremError('request', `gate ${callId} expired`, {
         copy: { key: 'session.gate_expired' },
     });
@@ -614,11 +788,20 @@ function buildLiveSession(args) {
      * `gateTtlMs` is settled (a held one as abandoned, a released one as lapsed;
      * the model reads that), then refused.
      */
-    const takeHeld = async (callId) => {
+    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`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            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);
@@ -628,28 +811,58 @@ function buildLiveSession(args) {
         }
         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) {
-        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 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;
         });
-        // An abort only drops what the gate held; there is no check to time.
+        // 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);
         }
-        const doneBatch = yield* yieldLiveNonDoneEvents(gated, includeMatch, recordAssistantText);
+        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;
-        // Boundary batches (`interactionStatus: IDLE`, or bare `turnComplete` when the
+        // 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);
@@ -665,16 +878,16 @@ function buildLiveSession(args) {
         }
     };
     const streamToHost = async function* () {
-        // Who closes the socket when the loop ends: the host, unless THEOREM stops it.
+        // why: 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.
+        // why: 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
+                // 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);
@@ -690,7 +903,7 @@ function buildLiveSession(args) {
                 yield* drainPendingHostEvents(pendingHostEvents);
                 if (item.type === 'closed') {
                     if (item.goAway)
-                        yield sessionEndedEvent(item, item.goAway, profile.lexicon);
+                        yield sessionEndedEvent(item, item.goAway, profile.labels);
                     else if (item.error)
                         yield toErrorEvent(item.error);
                     break;
@@ -722,7 +935,7 @@ function buildLiveSession(args) {
                 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.
+            // why: The socket is closed, so a batch still awaited resolves and the provider can finish.
             await provider.return(undefined);
             await trace.close({ thrown });
         }
@@ -732,7 +945,7 @@ function buildLiveSession(args) {
         canary,
         async *events() {
             for await (const raw of streamToHost()) {
-                const event = withPublicWording(raw, profile.lexicon);
+                const event = withPublicLabels(raw, profile.labels);
                 trace.delivered(event);
                 yield event;
             }
@@ -745,11 +958,7 @@ function buildLiveSession(args) {
                 const opened = await openCycleIfNeeded();
                 if (opened.aborted)
                     return;
-                sendJson(buildGeminiLiveRealtimeInput({
-                    type: 'audio',
-                    mimeType: audio.mimeType,
-                    data: audio.data,
-                }));
+                sendInput({ type: 'audio', mimeType: audio.mimeType, data: audio.data });
             });
         },
         sendVideo(video) {
@@ -758,11 +967,7 @@ function buildLiveSession(args) {
                 const opened = await openCycleIfNeeded();
                 if (opened.aborted)
                     return;
-                sendJson(buildGeminiLiveRealtimeInput({
-                    type: 'video',
-                    mimeType: video.mimeType,
-                    data: video.data,
-                }));
+                sendInput({ type: 'video', mimeType: video.mimeType, data: video.data });
             });
         },
         sendText(text) {
@@ -774,35 +979,30 @@ function buildLiveSession(args) {
                 ingestPreparedLiveText(text);
             });
         },
-        sendContext(text) {
+        sendContext(context) {
             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));
+                landContext(context);
                 return Promise.resolve();
             });
         },
-        async executeTool({ callId, decision, input, secret, credentials, host, }) {
+        async executeTool({ callId, operationId, decision, input, secret, credentials, host, page, }) {
             assertOpen();
-            const held = await takeHeld(callId);
+            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`);
+                    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 });
+                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: held.arguments,
+                arguments: gate.preparedArguments ?? held.arguments,
                 permission: gate.permission,
+                gateKind: gate.kind,
                 ...(gate.kind === 'auth' ? { auth: gate.authChallenge } : {}),
             }, sessionPermissions ?? []);
             if (answered.typed) {
@@ -812,13 +1012,14 @@ function buildLiveSession(args) {
             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`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                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);
@@ -831,11 +1032,16 @@ function buildLiveSession(args) {
                 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`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                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) {
@@ -850,7 +1056,7 @@ function buildLiveSession(args) {
             }
             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)
+                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);
@@ -858,19 +1064,28 @@ function buildLiveSession(args) {
                 ? { outputRaw: settled.output, ...(settled.awaiting ? { awaiting: true } : {}) }
                 : { failure: settled.failure };
         },
-        close(reason = 'session-closed') {
+        async 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.
+            // why: The session record is sealed here; frames the host reads after closing are not in it.
+            await connection.flush?.();
             return trace.close({});
         },
     };
-    if (args.openInitialCycle) {
+    const { initialContext, opening } = args;
+    if (args.openInitialCycle || initialContext || opening) {
         void withIngress(async () => {
-            await openCycleIfNeeded();
+            if (initialContext)
+                landContext(initialContext);
+            if (!args.openInitialCycle && !opening)
+                return;
+            const opened = await openCycleIfNeeded();
+            if (opening && !opened.aborted) {
+                sendInput({ type: 'text', text: opening });
+            }
         });
     }
     return session;
@@ -880,7 +1095,7 @@ function buildLiveSession(args) {
  * 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);
+    const trace = startLiveTrace(req, registry.profiles.find(req.profile), sinkOverride);
     try {
         return await openTracedSession(registry, req, options, trace);
     }
@@ -892,10 +1107,14 @@ export async function runSessionInRegistry(registry, req, options, sinkOverride)
 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));
+    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);
     }
@@ -904,8 +1123,9 @@ async function openTracedSession(registry, req, options, trace) {
     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),
+        canaryNote(generation.canary, profile.labels),
+        userDataNote(profile.labels),
+        profile.inputs?.context ? contextNote(profile.labels) : '',
     ]);
     const completeReq = {
         ...providerCompleteRequest(registry.tools, generation, system.text),
@@ -917,23 +1137,30 @@ async function openTracedSession(registry, req, options, trace) {
         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);
+    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,
@@ -944,7 +1171,11 @@ async function openTracedSession(registry, req, options, trace) {
         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',
     });