theorum 0.1.15 → 1.1.3

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

@@ -1,29 +1,57 @@
 import { throwIfAborted } from '../../../guardrails/error.js';
+import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
+import { recordTaint } from '../../../guardrails/tool-result.js';
+import { wireInteractionPart } from '../../interaction-parts.js';
+import { profileTurnOutputs } from '../../registry/profile-outputs.js';
+import { injectWouldExceedMaxSteps } from '../../stages.js';
+import { profileAllowsInject } from '../../stop.js';
+import { executeRegisteredTool, formatToolFailureForModel, formatToolResult, newCallId, } from '../../tools/execute.js';
+import { applyStageInjects } from './stages.js';
 import { recordStepEvent } from './state.js';
 import { yieldProviderEvents } from './stream.js';
-import { executeDynamicDeclaration, findDynamicDeclaration, formatToolFinding, isActionableDynamicDeclaration, } from './tools.js';
 function isStepLimitReached(step, maxSteps) {
-    if (maxSteps <= 0) {
+    if (maxSteps === undefined || maxSteps <= 0) {
         return false;
     }
     return step >= maxSteps;
 }
+function generationForProviderStep(generation, state) {
+    if (state.interactionsContinuation) {
+        const { previousInteractionId, input } = state.interactionsContinuation;
+        state.interactionsContinuation = undefined;
+        return {
+            ...generation,
+            history: [],
+            input: [],
+            previousInteractionId,
+            interactionOnlyInput: input,
+        };
+    }
+    return { ...generation, history: state.currentHistory };
+}
+function captureInteractionId(event, state) {
+    if (event.interactionId) {
+        state.lastInteractionId = event.interactionId;
+    }
+}
 async function* executeAutonomousStep(args, state, buffer = {
     holdLate: false,
-    holdUserVisible: false,
 }) {
-    const { profile, generation, system, provider, gemini, signal } = args;
-    const genForStep = { ...generation, history: state.currentHistory };
+    const { generation, system, provider, upstream, signal } = args;
+    const genForStep = generationForProviderStep(generation, state);
     const pendingTools = [];
     let latestStructured;
+    const control = { withholdVisible: false };
     for await (const event of yieldProviderEvents({
-        profile,
+        profile: args.profile,
         generation: genForStep,
         system,
         provider,
-        gemini,
+        upstream,
         signal,
+        control,
     })) {
+        captureInteractionId(event, state);
         if (event.type === 'structured') {
             latestStructured = event.structured;
         }
@@ -38,22 +66,41 @@ async function* executeAutonomousStep(args, state, buffer = {
             continue;
         }
         recordStepEvent(event, state);
-        const isUserVisible = event.type === 'thought' || event.type === 'text';
-        // Egress must not stream user-visible text before the gate runs.
-        // Validation-only may stream thought/text live and only hold structured.
-        const streamNow = !buffer.holdLate || event.type === 'tokens' || (isUserVisible && !buffer.holdUserVisible);
+        const isUserVisible = event.type === 'thought' || event.type === 'text' || event.type === 'media';
+        if (control.withholdVisible && isUserVisible) {
+            // Progressive-yield blocked this attempt — keep events for egress/repair only.
+            // Record the decision so the attempt gate knows nothing reached the host.
+            state.withheldVisible = true;
+            continue;
+        }
+        // Progressive-yield streams text/thought live under egress; holdLate only
+        // buffers non-visible events (e.g. structured) for validation.
+        const streamNow = !buffer.holdLate || event.type === 'tokens' || isUserVisible;
         if (streamNow) {
             yield event;
         }
     }
     return { pendingTools, latestStructured };
 }
-function appendToolTurnToHistory(history, toolEv, res) {
+function appendInteractionsToolResultToHistory(history, toolEv, result) {
     const tool = toolEv.tool;
     if (!tool) {
         return;
     }
-    const callId = tool.id ?? `call_${tool.name}_${String(Date.now())}`;
+    history.push({
+        role: 'tool',
+        tool_call_id: tool.id ?? tool.callId ?? `call_${tool.name}`,
+        name: tool.name,
+        content: formatToolResult(result),
+        ...(result.parts && result.parts.length > 0 ? { parts: result.parts } : {}),
+    });
+}
+function appendToolTurnToHistory(history, toolEv, result) {
+    const tool = toolEv.tool;
+    if (!tool) {
+        return;
+    }
+    const callId = tool.id ?? tool.callId ?? newCallId(tool.name);
     history.push({
         role: 'assistant',
         tool_calls: [
@@ -71,51 +118,205 @@ function appendToolTurnToHistory(history, toolEv, res) {
         role: 'tool',
         tool_call_id: callId,
         name: tool.name,
-        content: formatToolFinding(res),
+        content: formatToolResult(result),
+        ...(result.parts && result.parts.length > 0 ? { parts: result.parts } : {}),
     });
 }
-async function* handlePendingDynamicTools(pendingTools, generation, profile, state) {
-    let hasRunnableHandler = false;
+function queueInteractionsToolContinuation(state, toolEv, result, fallbackInteractionId) {
+    const tool = toolEv.tool;
+    if (!tool) {
+        return;
+    }
+    const previousInteractionId = state.lastInteractionId ?? fallbackInteractionId;
+    if (!previousInteractionId) {
+        return;
+    }
+    const step = {
+        type: 'function_result',
+        name: tool.name,
+        call_id: tool.id ?? tool.callId ?? `call_${tool.name}`,
+        result: result.parts && result.parts.length > 0
+            ? result.parts.map(wireInteractionPart)
+            : [{ type: 'text', text: formatToolResult(result) }],
+    };
+    if (state.interactionsContinuation &&
+        state.interactionsContinuation.previousInteractionId === previousInteractionId) {
+        state.interactionsContinuation.input.push(step);
+        return;
+    }
+    state.interactionsContinuation = {
+        previousInteractionId,
+        input: [step],
+    };
+}
+function recordToolModelResult(state, toolEv, modelResult, generation, useInteractionsContinuation) {
+    if (useInteractionsContinuation) {
+        queueInteractionsToolContinuation(state, toolEv, modelResult, generation.previousInteractionId);
+        if (!state.interactionsContinuation) {
+            appendInteractionsToolResultToHistory(state.currentHistory, toolEv, modelResult);
+        }
+        return;
+    }
+    appendToolTurnToHistory(state.currentHistory, toolEv, modelResult);
+}
+function enrichToolEvent(tool, callId, patch) {
+    return {
+        type: 'tool',
+        tool: {
+            ...tool,
+            ...patch,
+            callId,
+            id: tool.id ?? callId,
+        },
+    };
+}
+async function* drainToolExecEvents(exec, tool, callId, state) {
+    let next = await exec.next();
+    let sawGate = false;
+    while (!next.done) {
+        const event = next.value;
+        if (event.type === 'tool') {
+            const enriched = enrichToolEvent(tool, callId, event.tool);
+            state.allEmittedEvents.push(enriched);
+            yield enriched;
+            if (event.tool?.phase === 'gate')
+                sawGate = true;
+        }
+        else {
+            state.allEmittedEvents.push(event);
+            yield event;
+        }
+        next = await exec.next();
+    }
+    return { settlement: next.value, sawGate };
+}
+function recordProviderToolFailure(state, toolEv, tool, callId, failure, generation, useInteractionsContinuation, patch) {
+    const enriched = enrichToolEvent(tool, callId, {
+        phase: 'error',
+        failure,
+        ...patch,
+    });
+    state.allEmittedEvents.push(enriched);
+    recordToolModelResult(state, toolEv, formatToolFailureForModel(failure), generation, useInteractionsContinuation);
+    return enriched;
+}
+function applyToolSettlement(settlement, state, toolEv, generation, useInteractionsContinuation) {
+    if (settlement.aborted) {
+        state.lastStop = {
+            kind: 'cancelled',
+            ...(typeof settlement.aborted === 'object' && settlement.aborted.reason
+                ? { native: settlement.aborted.reason }
+                : {}),
+        };
+        return 'stop_cancelled';
+    }
+    if (settlement.gated) {
+        state.toolSnapshot = generation.tools;
+        return 'gated';
+    }
+    if (settlement.modelResult?.provenance) {
+        state.taint = recordTaint(state.taint, settlement.modelResult.provenance, settlement.modelResult.suspicious);
+    }
+    if (!settlement.modelResult)
+        return 'continue';
+    recordToolModelResult(state, toolEv, settlement.modelResult, generation, useInteractionsContinuation);
+    if (settlement.pendingInject?.length) {
+        applyStageInjects(state, settlement.pendingInject);
+    }
+    return 'continue';
+}
+async function* handlePendingTools(pendingTools, generation, profile, state, safe) {
+    let executed = false;
+    let sawGate = false;
+    const useInteractionsContinuation = generation.transport === 'interactions';
     for (const toolEv of pendingTools) {
+        if (sawGate)
+            break;
         const tool = toolEv.tool;
-        if (!tool) {
+        if (!tool)
+            continue;
+        executed = true;
+        const callId = tool.id ?? tool.callId ?? newCallId(tool.name || 'unknown');
+        if (tool.phase === 'cancel') {
+            const enriched = enrichToolEvent(tool, callId);
+            state.allEmittedEvents.push(enriched);
+            yield enriched;
             continue;
         }
-        const decl = findDynamicDeclaration(generation.dynamicTools, tool.name);
-        if (!isActionableDynamicDeclaration(decl)) {
-            state.allEmittedEvents.push(toolEv);
-            yield toolEv;
+        if (tool.phase === 'error' && tool.failure) {
+            const enriched = enrichToolEvent(tool, callId);
+            state.allEmittedEvents.push(enriched);
+            yield enriched;
+            recordToolModelResult(state, toolEv, formatToolFailureForModel(tool.failure), generation, useInteractionsContinuation);
             continue;
         }
-        hasRunnableHandler = true;
-        const finalResult = await executeDynamicDeclaration({
-            decl,
-            toolArgs: tool.arguments ?? {},
+        if (!tool.name) {
+            yield recordProviderToolFailure(state, toolEv, tool, callId, {
+                code: 'malformed_arguments',
+                message: 'Provider tool call is missing a function name', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }, generation, useInteractionsContinuation, { name: '' });
+            continue;
+        }
+        const stages = {
+            handlers: safe?.onStage ? [safe.onStage] : [],
             profile,
-            generation,
-        });
-        const enrichedEvent = {
-            type: 'tool',
-            tool: { ...tool, result: finalResult },
+            step: state.stepCount,
+            history: () => state.currentHistory,
+            injectAllowed: profileAllowsInject(profile),
+            injectWouldExceedMaxSteps: injectWouldExceedMaxSteps(state.stepCount, generation.maxSteps),
+            host: generation.host,
+            signal: safe?.signal,
         };
-        state.allEmittedEvents.push(enrichedEvent);
-        yield enrichedEvent;
-        appendToolTurnToHistory(state.currentHistory, toolEv, finalResult);
+        const drained = yield* drainToolExecEvents(executeRegisteredTool({
+            profile,
+            name: tool.name,
+            input: tool.arguments ?? {},
+            callId,
+            ctx: {
+                sessionPermissions: generation.sessionPermissions,
+                path: generation.tools.path,
+                turn: { step: state.stepCount, taint: state.taint },
+                credentials: safe?.credentials,
+                host: generation.host,
+                resume: undefined,
+                signal: safe?.signal,
+            },
+            snapshot: generation.tools,
+            stages,
+        }), tool, callId, state);
+        if (drained.sawGate)
+            sawGate = true;
+        const outcome = applyToolSettlement(drained.settlement, state, toolEv, generation, useInteractionsContinuation);
+        if (outcome === 'stop_cancelled')
+            return false;
+        if (outcome === 'gated' || sawGate) {
+            sawGate = true;
+        }
+    }
+    if (sawGate) {
+        state.lastStop = { kind: 'gate' };
+        return false;
     }
-    return hasRunnableHandler;
+    return executed;
 }
 async function* executeAttempt(args) {
-    const { profile, generation, system, provider, gemini, state } = args;
+    const { profile, generation, system, provider, upstream, state } = args;
     let latestStructured;
     let pendingTools = [];
-    let stepInAttempt = 0;
-    const holdUserVisible = Boolean(profile.guardrails.egress?.enforce);
-    const holdLate = Boolean(profile.outputs.validation) || holdUserVisible;
-    while (!isStepLimitReached(stepInAttempt, generation.maxSteps)) {
+    // Text/thought stream via progressive-yield under egress; validation and egress
+    // both hold non-visible events (structured) until the attempt gate, so a policy
+    // sees the structured payload before any of it reaches the host.
+    const holdLate = Boolean(profileTurnOutputs(profile)?.validation ||
+        resolveGuardrailPolicy(profile.guardrails).egress?.enforce);
+    // Ceiling is cumulative `state.stepCount` across before_end inject re-entries
+    // within this attempt. Validation/egress repair resets stepCount at the start
+    // of each attempt cycle (see gates.ts).
+    while (!isStepLimitReached(state.stepCount, generation.maxSteps ?? 0)) {
         throwIfAborted(args.safe.signal);
-        stepInAttempt++;
         state.stepCount++;
-        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, gemini, signal: args.safe.signal }, state, { holdLate, holdUserVisible });
+        // Mid-loop inject lives on `post_tool` (after tools). Opening inject is `pre_turn`
+        // outside this loop.
+        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, upstream, signal: args.safe.signal }, state, { holdLate });
         if (stepResult.latestStructured !== undefined) {
             latestStructured = stepResult.latestStructured;
         }
@@ -123,8 +324,8 @@ async function* executeAttempt(args) {
         if (pendingTools.length === 0) {
             break;
         }
-        const hasRunnableHandler = yield* handlePendingDynamicTools(pendingTools, generation, profile, state);
-        if (!hasRunnableHandler) {
+        const executed = yield* handlePendingTools(pendingTools, generation, profile, state, args.safe);
+        if (!executed) {
             break;
         }
     }

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

@@ -1,12 +1,18 @@
 import type { ModelProvider, Profile, ResolvedGeneration, TurnEvent } from '../../types.js';
-declare function systemFromProfile(profile: Profile, role: string): string;
+/** Mutable control flags shared with the step runner during one provider stream. */
+interface OutboundStreamControl {
+    /** Stop releasing text/thought/media to the host; keep recording for egress. */
+    withholdVisible: boolean;
+}
 declare function shouldSkipStreamEvent(event: TurnEvent, profile: Profile): boolean;
 declare function yieldProviderEvents(args: {
     profile: Profile;
     generation: ResolvedGeneration;
     system: string;
     provider: ModelProvider;
-    gemini: Record<string, unknown>[];
+    upstream: Record<string, unknown>[];
     signal?: AbortSignal;
+    control?: OutboundStreamControl;
 }): AsyncGenerator<TurnEvent>;
-export { shouldSkipStreamEvent, systemFromProfile, yieldProviderEvents };
+export type { OutboundStreamControl };
+export { shouldSkipStreamEvent, yieldProviderEvents };

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

@@ -1,44 +1,16 @@
+import { eventHasCanary, isStreamedCanaryEvent, redactCanary } from '../../../guardrails/canary.js';
+import { EGRESS_RULES } from '../../../guardrails/egress.js';
 import { publicError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
+import { guardrailFromHits } from '../../../guardrails/events.js';
+import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
+import { createOutboundProgressiveGate, } from '../../../guardrails/progressive-yield.js';
+import { profileTurnOutputs } from '../../registry/profile-outputs.js';
 import { providerCompleteRequest } from '../../registry/provider-request.js';
-import { eventHasCanary, redactCanary } from '../boundary.js';
-import { dispatchModelTool } from './tools.js';
-function systemFromProfile(profile, role) {
-    const { identity } = profile;
-    const { systemByRole, system } = identity;
-    if (systemByRole) {
-        const byRole = systemByRole[role];
-        if (byRole) {
-            return byRole;
-        }
-    }
-    if (system) {
-        return system;
-    }
-    return '';
-}
-function* interceptProviderTool(event, profile, generation) {
-    const tool = event.tool;
-    if (!tool) {
-        return;
-    }
-    const isDynamic = generation.dynamicTools?.some((d) => d.name === tool.name);
-    if (isDynamic) {
-        yield event;
-    }
-    else {
-        for (const item of dispatchModelTool(profile, event, generation.custom)) {
-            yield item;
-        }
-    }
-}
 function shouldSkipStreamEvent(event, profile) {
-    return event.type === 'thought' && profile.outputs.streaming?.streamThoughts === false;
+    return (event.type === 'thought' && profileTurnOutputs(profile)?.streaming?.streamThoughts === false);
 }
-function* processNormalEvent(event, profile, generation) {
-    if (event.type === 'tool') {
-        yield* interceptProviderTool(event, profile, generation);
-    }
-    else if (event.type === 'error') {
+function* processNormalEvent(event) {
+    if (event.type === 'error') {
         const internal = event.errorInternal ?? event.error ?? '';
         yield {
             type: 'error',
@@ -50,24 +22,148 @@ function* processNormalEvent(event, profile, generation) {
         yield event;
     }
 }
+function* yieldCanaryLeak(canary, event) {
+    const guardrail = guardrailFromHits('output_delta', 'untrusted', [{ rule: EGRESS_RULES.canary, severity: 'high', match: '[canary]' }], 'block');
+    if (guardrail) {
+        yield guardrail;
+    }
+    yield redactCanary(event, canary);
+    yield toErrorEvent('canary leaked');
+}
+function* yieldDeltaBlock(hits) {
+    const guardrail = guardrailFromHits('output_delta', 'untrusted', hits, 'block');
+    if (guardrail) {
+        yield guardrail;
+    }
+}
+function isHostVisible(event) {
+    return event.type === 'text' || event.type === 'thought' || event.type === 'media';
+}
+function canaryOnlyImmediateStop(policy) {
+    return !policy.egress?.enforce;
+}
+function hasCanaryHit(hits) {
+    return hits.some((hit) => hit.rule === EGRESS_RULES.canary);
+}
 async function* yieldProviderEvents(args) {
-    const { profile, generation, system, provider, gemini, signal } = args;
+    const { profile, generation, system, provider, upstream, signal, control } = args;
     const { canary } = generation;
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const context = {
+        stage: 'output_final',
+        trust: 'untrusted',
+        profileId: profile.id,
+        ...(canary ? { canary } : {}),
+    };
+    const gate = createOutboundProgressiveGate(policy, context);
+    let lastStreamType;
+    let withholdVisible = false;
+    function armWithhold() {
+        withholdVisible = true;
+        if (control)
+            control.withholdVisible = true;
+    }
+    function withholding() {
+        return withholdVisible;
+    }
+    async function* drainBlockedDelta(hits) {
+        yield* yieldDeltaBlock(hits);
+        // Arm withhold before recording the unreleased tail so the step runner
+        // does not forward that text to the host.
+        armWithhold();
+        const tail = gate?.drainUnreleased();
+        if (tail)
+            yield { type: 'text', text: tail };
+    }
+    async function* flushGate() {
+        if (!gate || !lastStreamType) {
+            return 'pass';
+        }
+        const emitType = lastStreamType;
+        const result = await gate.flush();
+        lastStreamType = undefined;
+        if (result.blocked) {
+            if (hasCanaryHit(result.hits) && canary && canaryOnlyImmediateStop(policy)) {
+                yield* yieldCanaryLeak(canary, { type: emitType, text: gate.accumulated() });
+                return 'stop';
+            }
+            yield* drainBlockedDelta(result.hits);
+            return 'pass';
+        }
+        if (result.emit) {
+            yield* processNormalEvent({ type: emitType, text: result.emit });
+        }
+        return 'pass';
+    }
+    async function* gateStreamEvent(event) {
+        if (!gate) {
+            yield* processNormalEvent(event);
+            return 'continue';
+        }
+        if (withholding()) {
+            // Keep recording ungated fragments for egress context; host will not see them.
+            yield { type: event.type, text: event.text ?? '' };
+            return 'continue';
+        }
+        if (lastStreamType && lastStreamType !== event.type) {
+            const flushed = yield* flushGate();
+            if (flushed === 'stop') {
+                return 'stop';
+            }
+        }
+        lastStreamType = event.type;
+        const result = await gate.process(event.text ?? '');
+        if (result.blocked) {
+            if (hasCanaryHit(result.hits) && canary && canaryOnlyImmediateStop(policy)) {
+                yield* yieldCanaryLeak(canary, event);
+                return 'stop';
+            }
+            yield* drainBlockedDelta(result.hits);
+            return 'continue';
+        }
+        if (result.emit) {
+            yield* processNormalEvent({ ...event, text: result.emit });
+        }
+        return 'continue';
+    }
     throwIfAborted(signal);
     for await (const event of provider.complete({
         ...providerCompleteRequest(generation, system),
         signal,
-        tapGemini: (row) => {
-            gemini.push(row);
+        tapUpstream: (row) => {
+            upstream.push(row);
         },
     })) {
         throwIfAborted(signal);
+        if (isStreamedCanaryEvent(event)) {
+            const status = yield* gateStreamEvent(event);
+            if (status === 'stop') {
+                return;
+            }
+            continue;
+        }
+        if (gate && lastStreamType) {
+            const flushed = yield* flushGate();
+            if (flushed === 'stop') {
+                return;
+            }
+        }
         if (canary && eventHasCanary(event, canary)) {
-            yield redactCanary(event, canary);
-            yield toErrorEvent('canary leaked');
+            yield* yieldCanaryLeak(canary, event);
+            return;
+        }
+        if (withholding() && isHostVisible(event)) {
+            // Record for attempt egress / repair; step runner withholds from host.
+            yield event;
+            continue;
+        }
+        yield* processNormalEvent(event);
+    }
+    if (gate && lastStreamType) {
+        const flushed = yield* flushGate();
+        if (flushed === 'stop') {
             return;
         }
-        yield* processNormalEvent(event, profile, generation);
     }
 }
-export { shouldSkipStreamEvent, systemFromProfile, yieldProviderEvents };
+export { shouldSkipStreamEvent, yieldProviderEvents };

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

@@ -0,0 +1,25 @@
+/**
+ * `runSession` — long-lived live profile execution.
+ *
+ * Shares resolve / tools / canary / system / outbound gate with `runTurn`.
+ * Does not use `ModelProvider.complete()` — live is a session, not one turn.
+ *
+ * Stages: `docs/contracts/stages.md` (cycle map + `executeTool`).
+ *
+ * @module
+ */
+import type { GeminiTransport } from '../../../providers/google/keys.js';
+import type { LiveSession, SessionRequest } from '../../types.js';
+export type { LiveSession, SessionRequest };
+export interface RunSessionOptions {
+    gemini: GeminiTransport;
+    /** Override socket open (Cloudflare fetch-upgrade, tests). Default: `new WebSocket(url)`. */
+    openWebSocket?: (url: string) => Promise<WebSocket>;
+}
+/**
+ * Open a gated Gemini Live session for a `type: 'live'` profile.
+ *
+ * Hosts bridge browser sockets and tool dispatch; THEORUM owns Gemini WS,
+ * framing, inbound prep, outbound canary/egress gates, and live stages.
+ */
+export declare function runSession(req: SessionRequest, options: RunSessionOptions): Promise<LiveSession>;