@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/kernel/engine/runner/stream.d.ts

@@ -1,9 +1,11 @@
 import type { GivenUrls } from '../../../guardrails/egress-urls.js';
+import type { OwnTools } from '../../../guardrails/tool-leak.js';
 import type { GuardrailHit } from '../../../guardrails/types.js';
-import type { ModelProvider, Profile, ProviderCompleteRequest, ProviderEvent, ResolvedGeneration } from '../../types.js';
+import type { ToolRegistry } from '../../tools/registry.js';
+import type { ModelEvent, ModelRequest, Profile, ResolvedGeneration, TurnEvent, TurnModel } from '../../types.js';
 import type { CallTrace } from '../turn-trace.js';
 /** What the stream yields to the step runner: every provider event but `response`, which only the trace reads. */
-export type StreamEvent = Exclude<ProviderEvent, {
+export type StreamEvent = Exclude<ModelEvent, {
     type: 'response';
 }>;
 interface OutboundStreamControl {
@@ -19,22 +21,51 @@ interface OutboundStreamControl {
     /** What the turn's thoughts so far ended on (`ThoughtGuard.carryOut`): read in front of this call's, and replaced. */
     thoughtCarry?: string;
 }
-declare function shouldSkipStreamEvent(event: ProviderEvent, profile: Profile): boolean;
+declare function shouldSkipStreamEvent(event: ModelEvent, profile: Profile): boolean;
 /** Host-visible output a mid-stream block withholds. A thought is never withheld, only omitted from. */
-declare function isWithheldOnBlock(event: ProviderEvent): boolean;
-declare function yieldProviderEvents(args: {
+declare function isWithheldOnBlock(event: ModelEvent): boolean;
+/**
+ * An event as the host gets it, or nothing. The text of a call that asked for structured output is
+ * that output's JSON: under `sse` it goes out as `structured_draft`, and under `buffered` not at all,
+ * since the `structured` event is the reply whole. The turn keeps it as text, which its checks,
+ * repairs and history read.
+ */
+declare function shownToHost(event: TurnEvent, generation: Pick<ResolvedGeneration, 'structured' | 'stream'>): TurnEvent | undefined;
+/**
+ * A step's events as the host gets them (`shownToHost`), with a structured reply's drafts read
+ * first at `reply_structured`, where the whole is read. The reply's text has already passed the
+ * `reply` gate; a match at `reply_structured` stops the drafts, and the `structured` event still
+ * arrives as that check leaves it. The held tail is read and released when the step's stream ends.
+ */
+declare class StructuredDrafts {
+    private readonly drafts;
+    private readonly generation;
+    /** Reads the stream's own checks off what the step knows of the turn. */
+    constructor(seen: Pick<StreamArgs, 'profile' | 'generation' | 'privateSystem' | 'givenUrls' | 'canaryGiven' | 'ownTools'>);
+    show(event: TurnEvent): AsyncGenerator<TurnEvent>;
+    /** The drafts' tail the gate still holds, once the step's stream has ended. */
+    end(): Generator<TurnEvent>;
+}
+interface StreamArgs {
     profile: Profile;
     generation: ResolvedGeneration;
-    request: ProviderCompleteRequest;
+    request: ModelRequest;
     /** The private stretches of `request.system` (`BoundSystem.private`). */
     privateSystem: readonly string[];
-    provider: ModelProvider;
+    provider: TurnModel;
     /** This call's recorder: sees every tap row and every provider event before any gate. */
-    call: Pick<CallTrace, 'tap' | 'observe'> & Partial<Pick<CallTrace, 'guardTime'>>;
+    call: Pick<CallTrace, 'tap' | 'observe'> & Partial<Pick<CallTrace, 'guardTime' | 'guardrail'>>;
     signal?: AbortSignal;
     control?: OutboundStreamControl;
     /** Every URL the model has been given this turn. */
     givenUrls: GivenUrls;
-}): AsyncGenerator<StreamEvent>;
-export type { OutboundStreamControl };
-export { isWithheldOnBlock, shouldSkipStreamEvent, yieldProviderEvents };
+    /** Whether the model has been given the canary this turn. */
+    canaryGiven?: boolean;
+    /** The names of the profile's tools and of their parameters. */
+    ownTools?: OwnTools;
+    /** The turn's tools: a draft is read at the boundary its tool's calls are. */
+    tools: ToolRegistry;
+}
+declare function yieldProviderEvents(args: StreamArgs): AsyncGenerator<StreamEvent>;
+export type { OutboundStreamControl, StreamArgs };
+export { isWithheldOnBlock, StructuredDrafts, shouldSkipStreamEvent, shownToHost, yieldProviderEvents, };

package/esm/src/kernel/engine/runner/stream.js

@@ -1,20 +1,31 @@
 import { isStreamedCanaryEvent } from '../../../guardrails/canary.js';
-import { CANARY_HIT, eventPromptLeakHits, isPromptLeakHit, promptLeakReason, WITHHELD_REASON, } from '../../../guardrails/egress.js';
+import { detectEvent, leakScopeOf } from '../../../guardrails/detect-at.js';
+import { eventLeak, isPromptLeakHit, promptLeakReason, WITHHELD_REASON, } from '../../../guardrails/egress.js';
 import { TheoremError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
-import { guardrailFromHits } from '../../../guardrails/events.js';
+import { guardrailFromHits, guardrailTurnEvent } from '../../../guardrails/events.js';
 import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
-import { createOutboundProgressiveGate, } from '../../../guardrails/progressive-yield.js';
+import { createDraftGate, createOutboundProgressiveGate, DraftReader, } from '../../../guardrails/progressive-yield.js';
+import { EGRESS_RULES } from '../../../guardrails/rules.js';
 import { thoughtGuardFor, } from '../../../guardrails/thought-guard.js';
 import { profileTurnOutputs } from '../../registry/profile-outputs.js';
+import { toolArgumentsBoundary } from '../../tools/execute.js';
 function shouldSkipStreamEvent(event, profile) {
     return (event.type === 'thought' && profileTurnOutputs(profile)?.streaming?.streamThoughts === false);
 }
-/** The offending text never reaches the host: redaction cannot cover a partial or encoded token. */
-function* yieldCanaryLeak(hits = [CANARY_HIT]) {
-    yield* yieldDeltaBlock(hits);
+/**
+ * A leak in an event that is not the reply's text ends the turn there: the
+ * event never reaches the host, and it has no text to replace.
+ */
+function* yieldLeakStop(hits) {
+    if (hits.some((hit) => hit.rule === EGRESS_RULES.providerToolLeak)) {
+        yield* yieldDeltaBlock(hits);
+    }
+    else {
+        yield* yieldDetected('reply', { action: 'block', hits });
+    }
     const reason = promptLeakReason(hits);
     yield toErrorEvent(new TheoremError('safety', reason));
-    // The turn ends because our guardrail blocked the output, not because the model finished.
+    // why: The turn ends because our guardrail blocked the output, not because the model finished.
     const native = reason === WITHHELD_REASON.canary
         ? 'canary'
         : reason === WITHHELD_REASON.promptEcho
@@ -28,8 +39,17 @@ function* yieldDeltaBlock(hits) {
         yield guardrail;
     }
 }
-/** What the guard released, after the event saying what it omitted from it. */
-function* yieldThought({ text, hits }, event) {
+/** What `guardrails.detect` found at `boundary` in text released as it streamed. */
+function* yieldDetected(boundary, found) {
+    const event = found && detectEvent(boundary, found, undefined, STREAMED_STAGE[boundary]);
+    if (event)
+        yield guardrailTurnEvent(event);
+}
+/** The stage a boundary reports under while its text streams, where that is not its own. */
+const STREAMED_STAGE = { reply: 'output_delta' };
+/** What the guard released, after the events saying what was found in it and omitted from it. */
+function* yieldThought({ text, hits, found }, event) {
+    yield* yieldDetected('thought', found);
     const guardrail = guardrailFromHits('thought', 'untrusted', hits, 'redact');
     if (guardrail)
         yield guardrail;
@@ -48,11 +68,139 @@ function* flushThoughts(thoughts, control) {
 function isWithheldOnBlock(event) {
     return event.type === 'text' || event.type === 'media';
 }
-function canaryOnlyImmediateStop(policy) {
-    return !policy.egress?.enforce;
+/**
+ * An event as the host gets it, or nothing. The text of a call that asked for structured output is
+ * that output's JSON: under `sse` it goes out as `structured_draft`, and under `buffered` not at all,
+ * since the `structured` event is the reply whole. The turn keeps it as text, which its checks,
+ * repairs and history read.
+ */
+function shownToHost(event, generation) {
+    if (!generation.structured || event.type !== 'text')
+        return event;
+    return generation.stream === false ? undefined : { type: 'structured_draft', text: event.text };
+}
+/**
+ * A step's events as the host gets them (`shownToHost`), with a structured reply's drafts read
+ * first at `reply_structured`, where the whole is read. The reply's text has already passed the
+ * `reply` gate; a match at `reply_structured` stops the drafts, and the `structured` event still
+ * arrives as that check leaves it. The held tail is read and released when the step's stream ends.
+ */
+class StructuredDrafts {
+    drafts;
+    generation;
+    /** Reads the stream's own checks off what the step knows of the turn. */
+    constructor(seen) {
+        const policy = resolveGuardrailPolicy(seen.profile.guardrails);
+        const context = streamContext(seen, policy);
+        this.drafts = new DraftReader(() => createDraftGate(policy, context, 'reply_structured'));
+        this.generation = seen.generation;
+    }
+    async *show(event) {
+        const shown = shownToHost(event, this.generation);
+        if (shown?.type !== 'structured_draft') {
+            if (shown)
+                yield shown;
+            return;
+        }
+        const text = await this.drafts.read(shown.text);
+        if (text)
+            yield { ...shown, text };
+    }
+    /** The drafts' tail the gate still holds, once the step's stream has ended. */
+    *end() {
+        const text = this.drafts.end();
+        if (text)
+            yield { type: 'structured_draft', text };
+    }
+}
+/**
+ * Events read at a boundary of their own, not with the reply's text: the
+ * model's tool call at its `tool_arguments` boundary, and the structured
+ * output at `reply_structured`.
+ */
+function isReadElsewhere(event) {
+    return event.type === 'structured' || event.type === 'tool';
+}
+/**
+ * The tool calls the model is drafting, each through a gate of its own at the boundary its call is
+ * read at (`createDraftGate`). A draft is a preview: one its gate stops, or whose tool's name
+ * changes, shows nothing more, and the call itself is still read whole. A draft's gate closes when
+ * its call arrives; its held tail is not released, because the call shows all of it.
+ */
+class ToolDrafts {
+    policy;
+    context;
+    tools;
+    drafts = new Map();
+    constructor(policy, context, tools) {
+        this.policy = policy;
+        this.context = context;
+        this.tools = tools;
+    }
+    /**
+     * Shows `event` when it is a draft and says whether it was; any other event closes its call's
+     * draft. Nothing shows while the reply is `withheld`.
+     */
+    async *take(event, withheld, timed) {
+        if (event.type !== 'tool_draft') {
+            this.close(event);
+            return false;
+        }
+        // why: A withheld reply is judged whole when its attempt ends; nothing more of it previews before then.
+        if (!withheld)
+            yield* this.release(event, timed);
+        return true;
+    }
+    async *release(event, timed) {
+        const draft = this.drafts.get(event.callId) ?? (await this.open(event));
+        if (draft === 'stopped')
+            return;
+        if (draft.name !== event.name) {
+            this.drafts.set(event.callId, 'stopped');
+            return;
+        }
+        if (!draft.gate) {
+            yield event;
+            return;
+        }
+        const { gate } = draft;
+        // why: What the gate finds is reported once, by the check on the whole call.
+        const result = await timed('tool_draft', () => gate.process(event.text));
+        if (result.blocked) {
+            this.drafts.set(event.callId, 'stopped');
+            return;
+        }
+        if (result.emit)
+            yield { ...event, text: result.emit };
+    }
+    close(event) {
+        if (event.type === 'tool')
+            this.drafts.delete(event.tool.callId);
+    }
+    async open(event) {
+        const boundary = toolArgumentsBoundary(this.tools, event.name);
+        const gate = boundary ? await createDraftGate(this.policy, this.context, boundary) : null;
+        const draft = { name: event.name, gate };
+        this.drafts.set(event.callId, draft);
+        return draft;
+    }
+}
+/** What the stream's checks know of the turn. */
+function streamContext(args, policy) {
+    const { profile, privateSystem, canaryGiven } = args;
+    const { canary } = args.generation;
+    return {
+        stage: 'output_final',
+        trust: 'untrusted',
+        profileId: profile.id,
+        ...(profile.labels ? { labels: profile.labels } : {}),
+        ...leakScopeOf(policy.detect, { canary, canaryGiven, privateSystem }),
+        givenUrls: args.givenUrls,
+        ...(args.ownTools ? { ownTools: args.ownTools } : {}),
+    };
 }
 async function* yieldProviderEvents(args) {
-    const { profile, generation, request, privateSystem, provider, call, signal, control, givenUrls, } = args;
+    const { profile, request, provider, call, signal, control } = args;
     /** Runs one stream check and adds the run to the call's record of that check. */
     async function timed(check, run) {
         const start = performance.now();
@@ -63,27 +211,18 @@ async function* yieldProviderEvents(args) {
             call.guardTime?.(check, performance.now() - start);
         }
     }
-    const { canary } = generation;
     const policy = resolveGuardrailPolicy(profile.guardrails);
-    const context = {
-        stage: 'output_final',
-        trust: 'untrusted',
-        profileId: profile.id,
-        ...(profile.lexicon ? { lexicon: profile.lexicon } : {}),
-        ...(canary ? { canary } : {}),
-        // The system prompt is guarded against echo alongside the canary that binds it.
-        ...(canary && policy.promptEcho && privateSystem.length > 0 ? { privateSystem } : {}),
-        givenUrls,
-    };
+    const context = streamContext(args, policy);
     const { canaryCarry, thoughtCarry } = control ?? {};
-    const gate = createOutboundProgressiveGate(policy, context, canaryCarry);
-    const thoughts = thoughtGuardFor(policy.egress?.enforce, context, thoughtCarry);
+    const gate = await createOutboundProgressiveGate(policy, context, 'reply', canaryCarry);
+    const thoughts = await thoughtGuardFor(policy, context, thoughtCarry);
+    const drafts = new ToolDrafts(policy, context, args.tools);
     /** The streamed event whose reply sits in the gate's lookback; released tails keep its shape. */
     let pendingStream = null;
     let withholdVisible = false;
     /**
-     * Under a host policy a withheld system-prompt leak goes to the
-     * end-of-attempt verdict, which it pins to block: no verdict may release it.
+     * A leak the gate stopped on goes to the end-of-attempt verdict, which reads
+     * the whole reply for it: one that reading misses still blocks.
      */
     function recordPromptLeak(hits) {
         const leaks = hits.filter(isPromptLeakHit);
@@ -100,7 +239,7 @@ async function* yieldProviderEvents(args) {
     }
     async function* drainBlockedDelta(hits, template) {
         yield* yieldDeltaBlock(hits);
-        // Arm withhold before recording the unreleased tail so the step runner
+        // why: Arm withhold before recording the unreleased tail so the step runner
         // does not forward that text to the host.
         armWithhold();
         const tail = gate?.drainUnreleased();
@@ -117,19 +256,22 @@ async function* yieldProviderEvents(args) {
         return (yield* releaseOrBlock(result, template)) === 'stop' ? 'stop' : 'pass';
     }
     /**
-     * Act on one gate step: release what it cleared, or block — stopping the turn
-     * when no host policy decides later, otherwise withholding for its verdict.
+     * Act on one gate step: release what it cleared, or withhold the rest of the
+     * reply for the verdict on the whole of it.
      */
     async function* releaseOrBlock(result, template) {
         if (result.blocked) {
-            if (canary && canaryOnlyImmediateStop(policy)) {
-                yield* yieldCanaryLeak(result.hits);
-                return 'stop';
-            }
             recordPromptLeak(result.hits);
-            yield* drainBlockedDelta(result.hits, template);
+            // why: A detector's stop is reported once, by the verdict on the whole reply. The trace
+            // still records that this check is the one that stopped it.
+            const stopped = result.boundary &&
+                detectEvent(result.boundary, { action: 'block', hits: result.hits }, undefined, 'output_delta');
+            if (stopped)
+                call.guardrail?.(stopped);
+            yield* drainBlockedDelta(result.boundary ? [] : result.hits, template);
             return 'go';
         }
+        yield* yieldDetected('reply', result.found);
         if (result.emit) {
             yield { ...template, text: result.emit };
         }
@@ -141,7 +283,7 @@ async function* yieldProviderEvents(args) {
             return 'continue';
         }
         if (withholding()) {
-            // Keep recording ungated fragments for egress context; host will not see them.
+            // why: Keep recording ungated fragments for egress context; host will not see them.
             yield { ...event, text: event.text ?? '' };
             return 'continue';
         }
@@ -172,7 +314,12 @@ async function* yieldProviderEvents(args) {
         call.observe(event);
         throwIfAborted(signal);
         if (event.type === 'response') {
-            // Identity is the trace's alone; the call span already recorded it.
+            // why: Identity is the trace's alone; the call span already recorded it.
+            continue;
+        }
+        if (event.type === 'reasoning') {
+            // why: Signed reasoning goes back to the model as it came; no one reads it in between.
+            yield event;
             continue;
         }
         if (yield* guardThought(event))
@@ -185,20 +332,24 @@ async function* yieldProviderEvents(args) {
             }
             continue;
         }
-        // Release held reply text first so the host sees events in order.
+        // why: Release held reply text first so the host sees events in order.
         const flushed = yield* flushGate();
         if (flushed === 'stop') {
             return;
         }
-        const leaks = canary
-            ? await timed('stream_canary', () => eventPromptLeakHits(event, canary, context.privateSystem))
-            : [];
-        if (leaks.length > 0) {
-            yield* yieldCanaryLeak(leaks);
+        if (yield* drafts.take(event, withholding(), timed))
+            continue;
+        const leak = isReadElsewhere(event)
+            ? undefined
+            : await timed('stream_canary', () => eventLeak(event, context, policy.detect, 'reply'));
+        if (leak?.stop) {
+            yield* yieldLeakStop(leak.hits);
             return;
         }
+        if (leak)
+            yield* yieldDetected('reply', { action: 'flag', hits: leak.hits });
         if (withholding() && isWithheldOnBlock(event)) {
-            // Record for attempt egress / repair; step runner withholds from host.
+            // why: Record for attempt egress / repair; step runner withholds from host.
             yield event;
             continue;
         }
@@ -218,8 +369,8 @@ async function* yieldProviderEvents(args) {
         control.canaryCarry = gate.carryOut();
     }
     if (providerFailed) {
-        // An error from the provider outranks any `done` it sent: the call's output is not whole.
+        // why: An error from the provider outranks any `done` it sent: the call's output is not whole.
         yield { type: 'done', stop: { kind: 'provider_error' } };
     }
 }
-export { isWithheldOnBlock, shouldSkipStreamEvent, yieldProviderEvents };
+export { isWithheldOnBlock, StructuredDrafts, shouldSkipStreamEvent, shownToHost, yieldProviderEvents, };

package/esm/src/kernel/engine/runner/usage.d.ts

@@ -1,6 +1,6 @@
 import type { ToolCallRequest } from '../../tools/types.js';
-import type { InteractionPart, ProviderEvent, ResolvedGeneration, TurnEventOf, TurnHistoryMessage, TurnTokens } from '../../types.js';
-import { type MediaTokenFamily, type TokenCount } from '../token-estimate.js';
+import type { InteractionPart, ModelEvent, ResolvedGeneration, TurnEventOf, TurnHistoryMessage, TurnTokens } from '../../types.js';
+import { type TokenCount } from '../token-estimate.js';
 type CallConversation = {
     history: TurnHistoryMessage[];
     input: InteractionPart[];
@@ -29,17 +29,17 @@ declare function startCallUsage(system: string, conversation: CallConversation,
  * Record one provider event. Returns true for a `tokens` event, which the
  * runner holds instead of streaming; `callTokensEvent` emits it at call end.
  */
-declare function observeCallEvent(usage: CallUsage, event: ProviderEvent): boolean;
+declare function observeCallEvent(usage: CallUsage, event: ModelEvent): boolean;
 /**
  * What the provider holds once `usage`'s call has ended: what it held before,
  * what was sent for the call, and the call's output (not thoughts), counted
  * as a continuation replays it.
  */
-declare function heldAfter(usage: CallUsage, family: MediaTokenFamily | undefined): Promise<TokenCount>;
+declare function heldAfter(usage: CallUsage): Promise<TokenCount>;
 /**
  * `undefined` when the call failed with no usage: what was billed is unknown, and an estimate would
  * claim a completed read.
  */
-declare function callTokensEvent(usage: CallUsage, generation: ResolvedGeneration, family: MediaTokenFamily | undefined): Promise<TurnEventOf<'tokens'> | undefined>;
+declare function callTokensEvent(usage: CallUsage, generation: ResolvedGeneration): Promise<TurnEventOf<'tokens'> | undefined>;
 export type { CallConversation, CallUsage };
 export { callTokensEvent, heldAfter, observeCallEvent, startCallUsage };

package/esm/src/kernel/engine/runner/usage.js

@@ -23,7 +23,7 @@ function observeCallEvent(usage, event) {
             usage.failed = true;
             return false;
         case 'tool':
-            // The model wrote its call; a provider's phase event about it (a malformed call's failure) it did not.
+            // why: The model wrote its call; a provider's phase event about it (a malformed call's failure) it did not.
             if (event.tool.phase === undefined)
                 usage.output.push({ type: 'tool', tool: event.tool });
             return false;
@@ -80,17 +80,17 @@ async function countOutput(usage, thoughts) {
     }
     return count;
 }
-async function countConversation(usage, family) {
+async function countConversation(usage) {
     const estimator = await loadTokenEstimator();
     const { conversation } = usage;
     if ('previous' in conversation) {
-        const earlier = await countConversation(conversation.previous, family);
+        const earlier = await countConversation(conversation.previous);
         const replayed = await countOutput(conversation.previous, false);
-        const continuation = await estimator.messages(conversation.continuation, family);
+        const continuation = estimator.messages(conversation.continuation);
         return addCounts(addCounts(earlier, replayed), continuation);
     }
-    const history = await estimator.messages(conversation.history, family);
-    const sent = addCounts(history, await estimator.parts(conversation.input, family));
+    const history = estimator.messages(conversation.history);
+    const sent = addCounts(history, estimator.parts(conversation.input));
     return usage.held ? addCounts(usage.held, sent) : sent;
 }
 /**
@@ -98,17 +98,17 @@ async function countConversation(usage, family) {
  * what was sent for the call, and the call's output (not thoughts), counted
  * as a continuation replays it.
  */
-async function heldAfter(usage, family) {
-    return addCounts(await countConversation(usage, family), await countOutput(usage, false));
+async function heldAfter(usage) {
+    return addCounts(await countConversation(usage), await countOutput(usage, false));
 }
-async function countPrompt(usage, generation, family) {
+async function countPrompt(usage, generation) {
     const estimator = await loadTokenEstimator();
     const wire = generation.tools.wire;
     const tools = wire.length > 0 ? estimator.text(JSON.stringify(wire)) : 0;
     const schema = generation.structured
         ? estimator.text(JSON.stringify(generation.structured.jsonSchema))
         : 0;
-    const conversation = await countConversation(usage, family);
+    const conversation = await countConversation(usage);
     return {
         tokens: estimator.text(usage.system) + tools + schema + conversation.tokens,
         unknownMedia: conversation.unknownMedia,
@@ -118,16 +118,14 @@ async function countPrompt(usage, generation, family) {
  * `undefined` when the call failed with no usage: what was billed is unknown, and an estimate would
  * claim a completed read.
  */
-async function callTokensEvent(usage, generation, family) {
+async function callTokensEvent(usage, generation) {
     const reported = usage.reported;
     if (!reported && usage.failed)
         return undefined;
     const estimated = reported ? (reported.estimated ?? []) : ['input', 'output'];
     if (reported && estimated.length === 0)
         return { type: 'tokens', tokens: reported };
-    const prompt = estimated.includes('input')
-        ? await countPrompt(usage, generation, family)
-        : undefined;
+    const prompt = estimated.includes('input') ? await countPrompt(usage, generation) : undefined;
     const written = estimated.includes('output') ? await countOutput(usage, true) : undefined;
     const input = prompt?.tokens ?? reported?.input ?? 0;
     const output = written?.tokens ?? reported?.output ?? 0;

package/esm/src/kernel/engine/session/mod.d.ts

@@ -1,14 +1,15 @@
 import type { TraceSink } from '../../../observability/trace-sink.js';
-import type { GeminiOptions } from '../../../providers/google/keys.js';
+import type { ProviderHostOptions } from '../../protocols/runtime.js';
 import type { KernelRegistry } from '../../registry/kernel-registry.js';
+import type { PageToolExecution, ToolExecutionCoordinator } from '../../tools/operation.js';
 import type { KeyVault, LiveSession, SessionRequest } from '../../types.js';
 export type { LiveSession, SessionRequest };
-export interface RunSessionOptions {
+/** Options for opening a live session: the key vault, a provider's own settings, a WebSocket opener, how long a gated call waits for its decision, and the sign-in gate policy. */
+export interface RunSessionOptions extends ProviderHostOptions {
+    execution?: ToolExecutionCoordinator;
+    pageExecution?: PageToolExecution;
     /** The host's keys by slot; the session uses the slots its profile names. */
-    vault: KeyVault;
-    gemini?: GeminiOptions;
-    /** Override socket open (Cloudflare fetch-upgrade, tests). Default: `new WebSocket(url)`. */
-    openWebSocket?: (url: string) => Promise<WebSocket>;
+    vault?: KeyVault;
     /**
      * Milliseconds a gated call waits for its decision (default 30 minutes). A later decision is
      * refused (`session.gate_expired`), and the model reads the call as abandoned.
@@ -23,6 +24,7 @@ export interface RunSessionOptions {
      */
     signInGate?: SignInGatePolicy;
 }
+/** How a sign-in gate behaves in a live session: `hold` waits for the decision, `answer` tells the model the sign-in is pending and releases the call. */
 export type SignInGatePolicy = 'hold' | 'answer';
 /**
  * The session record is written however the session ends, including when opening fails. An unknown