theorum 1.0.0 → 1.1.3

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

@@ -1,5 +1,12 @@
 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';
 function isStepLimitReached(step, maxSteps) {
@@ -29,18 +36,20 @@ function captureInteractionId(event, state) {
 }
 async function* executeAutonomousStep(args, state, buffer = {
     holdLate: false,
-    holdUserVisible: false,
 }) {
     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: args.profile,
         generation: genForStep,
         system,
         provider,
         upstream,
         signal,
+        control,
     })) {
         captureInteractionId(event, state);
         if (event.type === 'structured') {
@@ -57,8 +66,16 @@ async function* executeAutonomousStep(args, state, buffer = {
             continue;
         }
         recordStepEvent(event, state);
-        const isUserVisible = event.type === 'thought' || event.type === 'text';
-        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;
         }
@@ -75,6 +92,7 @@ function appendInteractionsToolResultToHistory(history, toolEv, result) {
         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) {
@@ -101,6 +119,7 @@ function appendToolTurnToHistory(history, toolEv, result) {
         tool_call_id: callId,
         name: tool.name,
         content: formatToolResult(result),
+        ...(result.parts && result.parts.length > 0 ? { parts: result.parts } : {}),
     });
 }
 function queueInteractionsToolContinuation(state, toolEv, result, fallbackInteractionId) {
@@ -116,7 +135,9 @@ function queueInteractionsToolContinuation(state, toolEv, result, fallbackIntera
         type: 'function_result',
         name: tool.name,
         call_id: tool.id ?? tool.callId ?? `call_${tool.name}`,
-        result: [{ type: 'text', text: formatToolResult(result) }],
+        result: result.parts && result.parts.length > 0
+            ? result.parts.map(wireInteractionPart)
+            : [{ type: 'text', text: formatToolResult(result) }],
     };
     if (state.interactionsContinuation &&
         state.interactionsContinuation.previousInteractionId === previousInteractionId) {
@@ -149,25 +170,79 @@ function enrichToolEvent(tool, callId, patch) {
         },
     };
 }
-async function* handlePendingTools(pendingTools, generation, profile, state) {
+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 sawPause = 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');
-        // Provider cancelled an in-flight call (e.g. live barge-in). Do not execute.
         if (tool.phase === 'cancel') {
             const enriched = enrichToolEvent(tool, callId);
             state.allEmittedEvents.push(enriched);
             yield enriched;
             continue;
         }
-        // Provider already failed this call (e.g. malformed arguments JSON).
         if (tool.phase === 'error' && tool.failure) {
             const enriched = enrichToolEvent(tool, callId);
             state.allEmittedEvents.push(enriched);
@@ -175,25 +250,24 @@ async function* handlePendingTools(pendingTools, generation, profile, state) {
             recordToolModelResult(state, toolEv, formatToolFailureForModel(tool.failure), generation, useInteractionsContinuation);
             continue;
         }
-        // Empty name is a protocol defect — never route through the registry as unknown_tool.
         if (!tool.name) {
-            const failure = {
+            yield recordProviderToolFailure(state, toolEv, tool, callId, {
                 code: 'malformed_arguments',
-                message: 'Provider tool call is missing a function name',
-            };
-            const enriched = enrichToolEvent(tool, callId, {
-                phase: 'error',
-                failure,
-                name: '',
-            });
-            state.allEmittedEvents.push(enriched);
-            yield enriched;
-            recordToolModelResult(state, toolEv, formatToolFailureForModel(failure), generation, useInteractionsContinuation);
+                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;
         }
-        let modelResult;
-        let paused = false;
-        const exec = executeRegisteredTool({
+        const stages = {
+            handlers: safe?.onStage ? [safe.onStage] : [],
+            profile,
+            step: state.stepCount,
+            history: () => state.currentHistory,
+            injectAllowed: profileAllowsInject(profile),
+            injectWouldExceedMaxSteps: injectWouldExceedMaxSteps(state.stepCount, generation.maxSteps),
+            host: generation.host,
+            signal: safe?.signal,
+        };
+        const drained = yield* drainToolExecEvents(executeRegisteredTool({
             profile,
             name: tool.name,
             input: tool.arguments ?? {},
@@ -201,39 +275,26 @@ async function* handlePendingTools(pendingTools, generation, profile, state) {
             ctx: {
                 sessionPermissions: generation.sessionPermissions,
                 path: generation.tools.path,
-                turn: { step: state.stepCount },
+                turn: { step: state.stepCount, taint: state.taint },
+                credentials: safe?.credentials,
+                host: generation.host,
+                resume: undefined,
+                signal: safe?.signal,
             },
             snapshot: generation.tools,
-        });
-        let next = await exec.next();
-        while (!next.done) {
-            const event = next.value;
-            const enriched = enrichToolEvent(tool, callId, event.tool);
-            state.allEmittedEvents.push(enriched);
-            yield enriched;
-            if (event.tool?.phase === 'error' && event.tool.failure) {
-                modelResult = formatToolFailureForModel(event.tool.failure);
-            }
-            if (event.tool?.phase === 'pause') {
-                modelResult = undefined;
-                paused = true;
-            }
-            next = await exec.next();
-        }
-        if (next.value !== undefined) {
-            modelResult = next.value;
-        }
-        if (paused) {
-            sawPause = true;
-            continue;
-        }
-        if (!modelResult) {
-            continue;
+            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;
         }
-        recordToolModelResult(state, toolEv, modelResult, generation, useInteractionsContinuation);
     }
-    if (sawPause) {
-        state.lastStop = { kind: 'tool' };
+    if (sawGate) {
+        state.lastStop = { kind: 'gate' };
         return false;
     }
     return executed;
@@ -242,14 +303,20 @@ async function* executeAttempt(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 ?? 0)) {
+    // 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, upstream, 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;
         }
@@ -257,7 +324,7 @@ async function* executeAttempt(args) {
         if (pendingTools.length === 0) {
             break;
         }
-        const executed = yield* handlePendingTools(pendingTools, generation, profile, state);
+        const executed = yield* handlePendingTools(pendingTools, generation, profile, state, args.safe);
         if (!executed) {
             break;
         }

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

@@ -1,11 +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;
     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,22 +1,13 @@
-import { createCanaryStreamGate, eventHasCanary, isStreamedCanaryEvent, redactCanary, } from '../../../guardrails/canary.js';
+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';
-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 shouldSkipStreamEvent(event, profile) {
-    return event.type === 'thought' && profile.outputs?.streaming?.streamThoughts === false;
+    return (event.type === 'thought' && profileTurnOutputs(profile)?.streaming?.streamThoughts === false);
 }
 function* processNormalEvent(event) {
     if (event.type === 'error') {
@@ -32,38 +23,109 @@ function* processNormalEvent(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* yieldGatedStreamEvent(event, gate, canary) {
-    const fragment = event.text ?? '';
-    const result = gate.process(fragment);
-    if (result.leak) {
-        yield* yieldCanaryLeak(canary, event);
-        return 'stop';
-    }
-    if (result.emit) {
-        yield* processNormalEvent({ ...event, text: result.emit });
+function* yieldDeltaBlock(hits) {
+    const guardrail = guardrailFromHits('output_delta', 'untrusted', hits, 'block');
+    if (guardrail) {
+        yield guardrail;
     }
-    return 'continue';
 }
-function* flushCanaryGate(gate, _canary, lastType) {
-    const result = gate.flush();
-    if (result.leak) {
-        yield toErrorEvent('canary leaked');
-        return 'stop';
-    }
-    if (result.emit) {
-        const emitType = lastType ?? 'text';
-        yield* processNormalEvent({ type: emitType, text: result.emit });
-    }
-    return 'pass';
+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 { generation, system, provider, upstream, signal } = args;
+    const { profile, generation, system, provider, upstream, signal, control } = args;
     const { canary } = generation;
-    const gate = canary ? createCanaryStreamGate(canary) : null;
+    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),
@@ -73,38 +135,35 @@ async function* yieldProviderEvents(args) {
         },
     })) {
         throwIfAborted(signal);
-        if (gate && isStreamedCanaryEvent(event)) {
-            if (lastStreamType && lastStreamType !== event.type) {
-                const status = yield* flushCanaryGate(gate, canary, lastStreamType);
-                if (status === 'stop') {
-                    return;
-                }
-            }
-            lastStreamType = event.type;
-            const status = yield* yieldGatedStreamEvent(event, gate, canary);
+        if (isStreamedCanaryEvent(event)) {
+            const status = yield* gateStreamEvent(event);
             if (status === 'stop') {
                 return;
             }
             continue;
         }
         if (gate && lastStreamType) {
-            const status = yield* flushCanaryGate(gate, canary, lastStreamType);
-            if (status === 'stop') {
+            const flushed = yield* flushGate();
+            if (flushed === 'stop') {
                 return;
             }
-            lastStreamType = undefined;
         }
         if (canary && eventHasCanary(event, canary)) {
             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) {
-        const status = yield* flushCanaryGate(gate, canary, lastStreamType);
-        if (status === 'stop') {
+    if (gate && lastStreamType) {
+        const flushed = yield* flushGate();
+        if (flushed === 'stop') {
             return;
         }
     }
 }
-export { shouldSkipStreamEvent, systemFromProfile, yieldProviderEvents };
+export { shouldSkipStreamEvent, yieldProviderEvents };

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

@@ -4,6 +4,8 @@
  * 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';
@@ -18,6 +20,6 @@ export interface RunSessionOptions {
  * 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, and outbound canary/egress gates.
+ * framing, inbound prep, outbound canary/egress gates, and live stages.
  */
 export declare function runSession(req: SessionRequest, options: RunSessionOptions): Promise<LiveSession>;