theorum 0.1.14 → 1.0.0

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

@@ -150,9 +150,9 @@ function gateStatusToAction(status, terminalStatus = 'terminal') {
     return null;
 }
 async function* executeSingleAttemptCycle(args) {
-    const { flow, state, profile, system, provider, gemini, maxRetries } = args;
-    const validation = profile.outputs.validation;
-    const egress = profile.guardrails.egress;
+    const { flow, state, profile, system, provider, upstream, maxRetries } = args;
+    const validation = profile.outputs?.validation;
+    const egress = profile.guardrails?.egress;
     state.attemptEvents = [];
     const { latestStructured } = yield* executeAttempt({
         safe: flow.currentReq,
@@ -160,7 +160,7 @@ async function* executeSingleAttemptCycle(args) {
         generation: flow.currentGen,
         system,
         provider,
-        gemini,
+        upstream,
         state,
     });
     if (egress?.enforce) {
@@ -183,8 +183,8 @@ async function* executeSingleAttemptCycle(args) {
     }
     return { status: 'success' };
 }
-async function* runAttemptsWithValidation(safe, profile, generation, system, provider, gemini, state) {
-    const maxRetries = Math.max(profile.outputs.validation?.maxRetries ?? 0, profile.guardrails.egress?.maxRetries ?? 2);
+async function* runAttemptsWithValidation(safe, profile, generation, system, provider, upstream, state) {
+    const maxRetries = Math.max(profile.outputs?.validation?.maxRetries ?? 0, profile.guardrails?.egress?.maxRetries ?? 0);
     const flow = {
         currentAttempt: 0,
         currentGen: generation,
@@ -198,7 +198,7 @@ async function* runAttemptsWithValidation(safe, profile, generation, system, pro
             profile,
             system,
             provider,
-            gemini,
+            upstream,
             maxRetries,
         });
         if (step.status === 'terminal' || step.status === 'success') {

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

@@ -7,18 +7,18 @@
  *
  * @module
  */
+import { bindCanary } from '../../../guardrails/canary.js';
 import { throwIfAborted } from '../../../guardrails/error.js';
 import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
 import { noopSink, writeTrace } from '../../../observability/trace.js';
 import { buildRecord } from '../../../observability/trace-record.js';
 import { pickSystemRole, resolveTurn } from '../../registry/resolve.js';
 import { CONTINUE_INSTRUCTION } from '../../stop.js';
-import { bindCanary } from '../boundary.js';
+import { expandT1Policy } from '../../tools/resolve.js';
 import { resolveCompactionTokens, shouldCompact, splitForCompaction } from '../compaction.js';
 import { runAttemptsWithValidation } from './gates.js';
 import { shouldSkipStreamEvent, systemFromProfile } from './stream.js';
 import { calculateFallbackTokens } from './tokens.js';
-import { invokeFromUi } from './tools.js';
 function getCompactionSpec(profile, modelId) {
     return profile.model.config[modelId]?.compaction;
 }
@@ -94,11 +94,7 @@ async function attachAfterCompaction(event, args) {
     return { ...event, compaction: signal };
 }
 async function* emitTurn(args) {
-    const { safe, profile, generation, system, provider, gemini } = args;
-    if (safe.toolInvoke) {
-        yield* invokeFromUi(profile, safe);
-        return;
-    }
+    const { safe, profile, generation, system, provider, upstream } = args;
     const state = {
         currentHistory: [...(generation.history ?? [])],
         stepCount: 0,
@@ -106,7 +102,7 @@ async function* emitTurn(args) {
         allEmittedEvents: [],
         attemptEvents: [],
     };
-    yield* runAttemptsWithValidation(safe, profile, generation, system, provider, gemini, state);
+    yield* runAttemptsWithValidation(safe, profile, generation, system, provider, upstream, state);
     if (!state.sawTokensEvent) {
         yield* calculateFallbackTokens(safe, system, state.allEmittedEvents);
     }
@@ -121,12 +117,13 @@ async function flushTurnTrace(sink, ctx) {
         events: ctx.seen,
         started: ctx.started,
         model: ctx.model,
-        bucket: ctx.bucket,
+        keySlot: ctx.keySlot,
         thrown: ctx.thrown,
-        gemini: ctx.gemini,
+        upstreamLog: ctx.upstream,
         canary: ctx.canary,
         system: ctx.system,
         generation: ctx.generation,
+        protocol: ctx.protocol,
         sanitizedReq: ctx.safe,
     }));
 }
@@ -137,7 +134,7 @@ async function* runTurn(req, provider, sink = noopSink()) {
         seen: [],
         started: Date.now(),
         canary: '',
-        gemini: [],
+        upstream: [],
     };
     try {
         yield* runTurnBody(ctx, provider);
@@ -152,10 +149,13 @@ async function* runTurnBody(ctx, provider) {
     ctx.safe = sanitizeTurnRequest(ctx.req);
     throwIfAborted(ctx.safe.signal);
     const { profile, generation: gen } = resolveTurn(ctx.safe);
+    await expandT1Policy(gen.tools, profile, ctx.safe);
+    gen.builtins = gen.tools.builtins;
     ctx.generation = gen;
     ctx.model = gen.model;
-    ctx.bucket = gen.geminiBucket;
+    ctx.keySlot = gen.keySlot;
     ctx.canary = gen.canary;
+    ctx.protocol = profile.model.protocol;
     const isCompacting = ctx.req.metadata?._compacting === true;
     const compactionSpec = isCompacting ? undefined : getCompactionSpec(profile, gen.model);
     await maybeCompactBefore(ctx, gen, compactionSpec, provider);
@@ -188,7 +188,7 @@ async function* streamTurnEvents(ctx, profile, gen, provider, compactionSpec, is
         generation: gen,
         system: ctx.system,
         provider,
-        gemini: ctx.gemini,
+        upstream: ctx.upstream,
     })) {
         const out = await maybeAttachAfter(event, ctx, gen, compactionSpec, isCompacting);
         ctx.seen.push(out);

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

@@ -7,6 +7,13 @@ interface StepExecutionState {
     attemptEvents: TurnEvent[];
     /** Last provider stop from a discarded provider `done` event. */
     lastStop?: TurnStop;
+    /** Latest Google Interactions id observed on the current provider stream. */
+    lastInteractionId?: string;
+    /** Pending Interactions `function_result` continuation for the next provider step. */
+    interactionsContinuation?: {
+        previousInteractionId: string;
+        input: Record<string, unknown>[];
+    };
 }
 interface AttemptFlowState {
     currentAttempt: number;

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

@@ -6,7 +6,7 @@ declare function executeAttempt(args: {
     generation: ResolvedGeneration;
     system: string;
     provider: ModelProvider;
-    gemini: Record<string, unknown>[];
+    upstream: Record<string, unknown>[];
     state: StepExecutionState;
 }): AsyncGenerator<TurnEvent, {
     pendingTools: TurnEvent[];

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

@@ -1,29 +1,48 @@
 import { throwIfAborted } from '../../../guardrails/error.js';
+import { executeRegisteredTool, formatToolFailureForModel, formatToolResult, newCallId, } from '../../tools/execute.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;
     for await (const event of yieldProviderEvents({
-        profile,
         generation: genForStep,
         system,
         provider,
-        gemini,
+        upstream,
         signal,
     })) {
+        captureInteractionId(event, state);
         if (event.type === 'structured') {
             latestStructured = event.structured;
         }
@@ -39,8 +58,6 @@ async function* executeAutonomousStep(args, state, buffer = {
         }
         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);
         if (streamNow) {
             yield event;
@@ -48,12 +65,24 @@ async function* executeAutonomousStep(args, state, buffer = {
     }
     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),
+    });
+}
+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 +100,156 @@ function appendToolTurnToHistory(history, toolEv, res) {
         role: 'tool',
         tool_call_id: callId,
         name: tool.name,
-        content: formatToolFinding(res),
+        content: formatToolResult(result),
     });
 }
-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: [{ 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* handlePendingTools(pendingTools, generation, profile, state) {
+    let executed = false;
+    let sawPause = false;
+    const useInteractionsContinuation = generation.transport === 'interactions';
     for (const toolEv of pendingTools) {
         const tool = toolEv.tool;
         if (!tool) {
             continue;
         }
-        const decl = findDynamicDeclaration(generation.dynamicTools, tool.name);
-        if (!isActionableDynamicDeclaration(decl)) {
-            state.allEmittedEvents.push(toolEv);
-            yield toolEv;
+        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;
         }
-        hasRunnableHandler = true;
-        const finalResult = await executeDynamicDeclaration({
-            decl,
-            toolArgs: tool.arguments ?? {},
+        // 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);
+            yield enriched;
+            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 = {
+                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);
+            continue;
+        }
+        let modelResult;
+        let paused = false;
+        const exec = executeRegisteredTool({
             profile,
-            generation,
+            name: tool.name,
+            input: tool.arguments ?? {},
+            callId,
+            ctx: {
+                sessionPermissions: generation.sessionPermissions,
+                path: generation.tools.path,
+                turn: { step: state.stepCount },
+            },
+            snapshot: generation.tools,
         });
-        const enrichedEvent = {
-            type: 'tool',
-            tool: { ...tool, result: finalResult },
-        };
-        state.allEmittedEvents.push(enrichedEvent);
-        yield enrichedEvent;
-        appendToolTurnToHistory(state.currentHistory, toolEv, finalResult);
+        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;
+        }
+        recordToolModelResult(state, toolEv, modelResult, generation, useInteractionsContinuation);
+    }
+    if (sawPause) {
+        state.lastStop = { kind: 'tool' };
+        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)) {
+    const holdUserVisible = Boolean(profile.guardrails?.egress?.enforce);
+    const holdLate = Boolean(profile.outputs?.validation) || holdUserVisible;
+    while (!isStepLimitReached(stepInAttempt, 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 });
+        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, upstream, signal: args.safe.signal }, state, { holdLate, holdUserVisible });
         if (stepResult.latestStructured !== undefined) {
             latestStructured = stepResult.latestStructured;
         }
@@ -123,8 +257,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);
+        if (!executed) {
             break;
         }
     }

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

@@ -2,11 +2,10 @@ import type { ModelProvider, Profile, ResolvedGeneration, TurnEvent } from '../.
 declare function systemFromProfile(profile: Profile, role: string): string;
 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;
 }): AsyncGenerator<TurnEvent>;
 export { shouldSkipStreamEvent, systemFromProfile, yieldProviderEvents };

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

@@ -1,7 +1,6 @@
+import { createCanaryStreamGate, eventHasCanary, isStreamedCanaryEvent, redactCanary, } from '../../../guardrails/canary.js';
 import { publicError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.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;
@@ -16,29 +15,11 @@ function systemFromProfile(profile, role) {
     }
     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' && profile.outputs?.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 +31,80 @@ function* processNormalEvent(event, profile, generation) {
         yield event;
     }
 }
+function* yieldCanaryLeak(canary, event) {
+    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 });
+    }
+    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';
+}
 async function* yieldProviderEvents(args) {
-    const { profile, generation, system, provider, gemini, signal } = args;
+    const { generation, system, provider, upstream, signal } = args;
     const { canary } = generation;
+    const gate = canary ? createCanaryStreamGate(canary) : null;
+    let lastStreamType;
     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 (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 (status === 'stop') {
+                return;
+            }
+            continue;
+        }
+        if (gate && lastStreamType) {
+            const status = yield* flushCanaryGate(gate, canary, lastStreamType);
+            if (status === 'stop') {
+                return;
+            }
+            lastStreamType = undefined;
+        }
         if (canary && eventHasCanary(event, canary)) {
-            yield redactCanary(event, canary);
-            yield toErrorEvent('canary leaked');
+            yield* yieldCanaryLeak(canary, event);
+            return;
+        }
+        yield* processNormalEvent(event);
+    }
+    if (gate) {
+        const status = yield* flushCanaryGate(gate, canary, lastStreamType);
+        if (status === 'stop') {
             return;
         }
-        yield* processNormalEvent(event, profile, generation);
     }
 }
 export { shouldSkipStreamEvent, systemFromProfile, yieldProviderEvents };

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

@@ -0,0 +1,23 @@
+/**
+ * `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.
+ *
+ * @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, and outbound canary/egress gates.
+ */
+export declare function runSession(req: SessionRequest, options: RunSessionOptions): Promise<LiveSession>;