theorum 0.1.2

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

@@ -0,0 +1,731 @@
+/**
+ * Deterministic turn runner for THEORUM.
+ *
+ * `runTurn` resolves a profile, sanitizes input, binds canary boundaries,
+ * streams provider events, executes allowed tools, applies validation and
+ * egress repair loops, writes traces, and emits one terminal `done` event.
+ *
+ * @module
+ */
+import { publicError } 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 { CATALOG } from '../registry/catalog.js';
+import { pickSystemRole, resolveTurn } from '../registry/resolve.js';
+import { executeTool } from '../registry/tools.js';
+import { bindCanary, eventHasCanary, redactCanary } from './boundary.js';
+function* invokeFromUi(profile, req) {
+    const invoke = req.toolInvoke;
+    if (!invoke) {
+        return;
+    }
+    try {
+        const result = executeTool(profile, invoke.name, invoke.arguments);
+        yield {
+            type: 'tool',
+            tool: { name: invoke.name, arguments: invoke.arguments, result },
+        };
+        if (result.status === 'error') {
+            yield { type: 'error', error: publicError(formatToolFinding(result)) };
+            return;
+        }
+        yield { type: 'done' };
+    }
+    catch (err) {
+        yield { type: 'error', error: publicError(err) };
+        yield { type: 'done' };
+    }
+}
+function executeCustomModelTool(profile, name, args) {
+    try {
+        const result = executeTool(profile, name, args);
+        const events = [
+            {
+                type: 'tool',
+                tool: { name, arguments: args, result },
+            },
+        ];
+        if (result.status === 'error') {
+            events.push({ type: 'error', error: publicError(formatToolFinding(result)) });
+        }
+        return events;
+    }
+    catch (err) {
+        return [{ type: 'error', error: publicError(err) }];
+    }
+}
+function dispatchModelTool(profile, event, gated) {
+    const { tool } = event;
+    if (!tool) {
+        return [];
+    }
+    const name = tool.name;
+    if (CATALOG.tools[name]?.kind === 'builtin') {
+        return [event];
+    }
+    if (!gated.includes(name)) {
+        return [
+            {
+                type: 'error',
+                error: publicError(`Tool '${name}' is not gated on this turn`),
+            },
+        ];
+    }
+    const args = tool.arguments ?? {};
+    return executeCustomModelTool(profile, name, args);
+}
+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;
+}
+function* processNormalEvent(event, profile, generation) {
+    if (event.type === 'tool') {
+        yield* interceptProviderTool(event, profile, generation);
+    }
+    else if (event.type === 'error') {
+        yield { type: 'error', error: publicError(event.error) };
+    }
+    else {
+        yield event;
+    }
+}
+async function* yieldProviderEvents(args) {
+    const { profile, generation, system, provider, gemini } = args;
+    const { canary } = generation;
+    for await (const event of provider.complete({
+        model: generation.model,
+        previousInteractionId: generation.previousInteractionId,
+        store: generation.store,
+        thinking: generation.thinking,
+        summaries: generation.summaries,
+        maxOutputTokens: generation.maxOutputTokens,
+        temperature: generation.temperature,
+        builtins: generation.builtins,
+        system,
+        input: generation.input,
+        history: generation.history,
+        dynamicTools: generation.dynamicTools,
+        dynamicToolLoader: generation.dynamicToolLoader,
+        structured: generation.structured,
+        image: generation.image,
+        voice: generation.voice,
+        geminiBucket: generation.geminiBucket,
+        tapGemini: (row) => {
+            gemini.push(row);
+        },
+    })) {
+        if (canary && eventHasCanary(event, canary)) {
+            yield redactCanary(event, canary);
+            yield { type: 'error', error: publicError('canary leaked') };
+            return;
+        }
+        yield* processNormalEvent(event, profile, generation);
+    }
+}
+function isStepLimitReached(step, maxSteps) {
+    if (maxSteps <= 0) {
+        return false;
+    }
+    return step >= maxSteps;
+}
+function findDynamicDeclaration(tools, name) {
+    return tools?.find((t) => t.name === name);
+}
+function formatToolFinding(res) {
+    if (res.finding) {
+        return res.finding;
+    }
+    if (res.data) {
+        return JSON.stringify(res.data);
+    }
+    return 'ok';
+}
+function collectAttemptText(events) {
+    return events
+        .filter((e) => e.type === 'text' && e.text)
+        .map((e) => e.text)
+        .join('');
+}
+async function checkDynamicAuthorization(decl, args, profile, sessionPermissions) {
+    if (!decl.canExecute) {
+        return null;
+    }
+    try {
+        const decision = await decl.canExecute({
+            args,
+            profile,
+            sessionPermissions,
+        });
+        if (typeof decision === 'boolean' && !decision) {
+            return {
+                status: 'error',
+                finding: `Tool '${decl.name}' execution not authorized.`,
+            };
+        }
+        if (typeof decision === 'object' && decision !== null) {
+            return decision;
+        }
+        return null;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            status: 'error',
+            finding: `Authorization error for '${decl.name}': ${msg}`,
+        };
+    }
+}
+function checkDynamicPermissionTier(decl, args, sessionPermissions) {
+    if (decl.permissionTier === 'session_consent' || decl.permissionTier === 'always_confirm') {
+        const isGranted = sessionPermissions?.includes(decl.name) || sessionPermissions?.includes('*');
+        if (!isGranted) {
+            return {
+                status: 'pause',
+                finding: `Tool '${decl.name}' requires ${decl.permissionTier} authorization.`,
+                data: { tool: decl.name, permissionTier: decl.permissionTier, args },
+            };
+        }
+    }
+    return null;
+}
+async function runDynamicHandler(decl, args) {
+    if (!decl.handler) {
+        return {
+            status: 'ok',
+            finding: `${decl.name} accepted (no handler)`,
+            data: args,
+        };
+    }
+    try {
+        return await decl.handler(args);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { status: 'error', finding: msg };
+    }
+}
+async function executeDynamicTool(decl, args, profile, sessionPermissions) {
+    const authEnvelope = await checkDynamicAuthorization(decl, args, profile, sessionPermissions);
+    if (authEnvelope) {
+        return authEnvelope;
+    }
+    const permissionEnvelope = checkDynamicPermissionTier(decl, args, sessionPermissions);
+    if (permissionEnvelope) {
+        return permissionEnvelope;
+    }
+    return runDynamicHandler(decl, args);
+}
+function mergeDynamicTools(current, loaded) {
+    const merged = [...(current ?? [])];
+    for (const tool of loaded) {
+        const existing = merged.findIndex((item) => item.name === tool.name);
+        if (existing >= 0) {
+            merged[existing] = tool;
+        }
+        else {
+            merged.push(tool);
+        }
+    }
+    return merged;
+}
+async function executeDynamicToolLoader(args) {
+    const { decl, toolArgs, profile, generation } = args;
+    const loader = generation.dynamicToolLoader;
+    if (!loader) {
+        return {
+            status: 'error',
+            finding: `Tool '${decl.name}' is marked as a loader but no loader is configured.`,
+        };
+    }
+    const loaded = await loader({
+        name: decl.name,
+        args: toolArgs,
+        profile,
+        currentTools: generation.dynamicTools ?? [],
+        sessionPermissions: generation.sessionPermissions,
+    });
+    generation.dynamicTools = mergeDynamicTools(generation.dynamicTools, loaded);
+    return {
+        status: 'ok',
+        finding: `Loaded ${String(loaded.length)} dynamic tool schema(s).`,
+        data: { loadedTools: loaded.map((tool) => tool.name) },
+    };
+}
+function isActionableDynamicDeclaration(decl) {
+    return Boolean(decl?.handler || decl?.canExecute || decl?.permissionTier || decl?.loadsDynamicTools);
+}
+async function executeDynamicDeclaration(args) {
+    const { decl, toolArgs, profile, generation } = args;
+    const res = await executeDynamicTool(decl, toolArgs, profile, generation.sessionPermissions);
+    if (res.status === 'ok' && decl.loadsDynamicTools) {
+        return await executeDynamicToolLoader({
+            decl,
+            toolArgs,
+            profile,
+            generation,
+        });
+    }
+    return res;
+}
+function recordStepEvent(event, state) {
+    if (event.type === 'tokens') {
+        state.sawTokensEvent = true;
+    }
+    state.allEmittedEvents.push(event);
+    state.attemptEvents.push(event);
+}
+async function* executeAutonomousStep(args, state, bufferOutputs = false) {
+    const { profile, generation, system, provider, gemini } = args;
+    const genForStep = { ...generation, history: state.currentHistory };
+    const pendingTools = [];
+    let latestStructured;
+    for await (const event of yieldProviderEvents({
+        profile,
+        generation: genForStep,
+        system,
+        provider,
+        gemini,
+    })) {
+        if (event.type === 'structured') {
+            latestStructured = event.structured;
+        }
+        if (event.type === 'done') {
+            continue;
+        }
+        if (event.type === 'tool' && event.tool) {
+            pendingTools.push(event);
+            continue;
+        }
+        recordStepEvent(event, state);
+        if (!bufferOutputs || event.type === 'tokens') {
+            yield event;
+        }
+    }
+    return { pendingTools, latestStructured };
+}
+function appendToolTurnToHistory(history, toolEv, res) {
+    const tool = toolEv.tool;
+    if (!tool) {
+        return;
+    }
+    const callId = tool.id ?? `call_${tool.name}_${String(Date.now())}`;
+    history.push({
+        role: 'assistant',
+        tool_calls: [
+            {
+                id: callId,
+                type: 'function',
+                function: {
+                    name: tool.name,
+                    arguments: JSON.stringify(tool.arguments ?? {}),
+                },
+            },
+        ],
+    });
+    history.push({
+        role: 'tool',
+        tool_call_id: callId,
+        name: tool.name,
+        content: formatToolFinding(res),
+    });
+}
+function calculateInputChars(safe, system) {
+    const input = safe.input ?? {};
+    return ((input.text?.length ?? 0) +
+        (input.repair?.previousOutput?.length ?? 0) +
+        (system?.length ?? 800));
+}
+function calculateOutputChars(events) {
+    let outputChars = 0;
+    let thinkingChars = 0;
+    for (const e of events) {
+        if (e.type === 'text' && e.text)
+            outputChars += e.text.length;
+        if (e.type === 'structured' && e.structured) {
+            outputChars += JSON.stringify(e.structured).length;
+        }
+        if (e.type === 'thought' && e.text)
+            thinkingChars += e.text.length;
+    }
+    return { outputChars, thinkingChars };
+}
+function* calculateFallbackTokens(safe, system, events) {
+    const inputChars = calculateInputChars(safe, system);
+    const { outputChars, thinkingChars } = calculateOutputChars(events);
+    const inputTokens = Math.max(1, Math.round(inputChars / 4));
+    const outputTokens = Math.max(1, Math.round(outputChars / 4));
+    const thinkingTokens = thinkingChars ? Math.round(thinkingChars / 4) : 0;
+    yield {
+        type: 'tokens',
+        tokens: {
+            input: inputTokens,
+            output: outputTokens,
+            thinking: thinkingTokens,
+            toolUse: 0,
+            total: inputTokens + outputTokens + thinkingTokens,
+        },
+    };
+}
+async function* handlePendingDynamicTools(pendingTools, generation, profile, state) {
+    let hasRunnableHandler = false;
+    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;
+            continue;
+        }
+        hasRunnableHandler = true;
+        const finalResult = await executeDynamicDeclaration({
+            decl,
+            toolArgs: tool.arguments ?? {},
+            profile,
+            generation,
+        });
+        const enrichedEvent = {
+            type: 'tool',
+            tool: { ...tool, result: finalResult },
+        };
+        state.allEmittedEvents.push(enrichedEvent);
+        yield enrichedEvent;
+        appendToolTurnToHistory(state.currentHistory, toolEv, finalResult);
+    }
+    return hasRunnableHandler;
+}
+async function* executeAttempt(args) {
+    const { profile, generation, system, provider, gemini, state } = args;
+    let latestStructured;
+    let pendingTools = [];
+    let stepInAttempt = 0;
+    const shouldBuffer = Boolean(profile.outputs.validation) || Boolean(profile.guardrails.egress?.enforce);
+    while (!isStepLimitReached(stepInAttempt, generation.maxSteps)) {
+        stepInAttempt++;
+        state.stepCount++;
+        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, gemini }, state, shouldBuffer);
+        if (stepResult.latestStructured !== undefined) {
+            latestStructured = stepResult.latestStructured;
+        }
+        pendingTools = stepResult.pendingTools;
+        if (pendingTools.length === 0) {
+            break;
+        }
+        const hasRunnableHandler = yield* handlePendingDynamicTools(pendingTools, generation, profile, state);
+        if (!hasRunnableHandler) {
+            break;
+        }
+    }
+    return { pendingTools, latestStructured };
+}
+function buildRepairRequest(safe, previousOutput, rejection, repairGuidance) {
+    return {
+        ...safe,
+        input: {
+            ...safe.input,
+            repair: {
+                previousOutput: typeof previousOutput === 'string' ? previousOutput : JSON.stringify(previousOutput),
+                rejection,
+                guidance: repairGuidance,
+            },
+        },
+    };
+}
+function hasValidatableOutput(validation, latestStructured) {
+    if (!validation || latestStructured === undefined) {
+        return false;
+    }
+    const candidateOutput = validation.extract?.(latestStructured) ?? latestStructured;
+    return candidateOutput !== undefined && candidateOutput !== null;
+}
+async function evaluateValidationAttempt(validation, latestStructured, slots) {
+    const candidateOutput = validation.extract?.(latestStructured) ?? latestStructured;
+    const check = await validation.validate(candidateOutput, slots);
+    const error = check.error || check.finding || 'Validation failed';
+    return { candidateOutput, isValid: Boolean(check.isValid), error };
+}
+async function evaluateEgressOutcome(args) {
+    const { egress, attemptEvents, generation, request, profile, canRetry } = args;
+    const attemptText = collectAttemptText(attemptEvents);
+    const result = await egress.enforce({
+        text: attemptText,
+        canary: generation.canary,
+        slots: request.input?.slots,
+        profile,
+        role: request.input?.role,
+    });
+    if (!result.blocked) {
+        return { action: 'pass' };
+    }
+    if (egress.onBlock === 'refuse_to_user') {
+        return { action: 'refusal', event: { type: 'text', text: result.text } };
+    }
+    if (canRetry) {
+        const rejectionMsg = result.rejectionMessage || 'Egress disclosure violation detected.';
+        const repairGuidance = egress.repairGuidance ||
+            'Rewrite the message as corrected user-visible prose only. Keep the same helpful substance; scrub all internal tool names, leak phrases, and disclosure markers.';
+        const nextRequest = buildRepairRequest(request, attemptText, rejectionMsg, repairGuidance);
+        return { action: 'retry', nextRequest };
+    }
+    return {
+        action: 'withhold',
+        event: {
+            type: 'error',
+            error: publicError('Turn withheld: egress disclosure violation'),
+        },
+    };
+}
+async function evaluateValidationOutcome(args) {
+    const { validation, latestStructured, request, canRetry } = args;
+    if (!hasValidatableOutput(validation, latestStructured)) {
+        return { action: 'pass' };
+    }
+    const { candidateOutput, isValid, error } = await evaluateValidationAttempt(validation, latestStructured, request.input?.slots);
+    if (isValid) {
+        return { action: 'pass' };
+    }
+    if (canRetry) {
+        const nextRequest = buildRepairRequest(request, candidateOutput, error, validation.repairGuidance);
+        return { action: 'retry', nextRequest };
+    }
+    return {
+        action: 'accept',
+        event: { type: 'structured', structured: latestStructured },
+    };
+}
+function* yieldBufferedAttemptEvents(events) {
+    for (const ev of events) {
+        if (ev.type !== 'tokens') {
+            yield ev;
+        }
+    }
+}
+function updateFlowForRetry(flow, nextReq) {
+    flow.currentAttempt++;
+    flow.currentReq = nextReq;
+    flow.currentGen = resolveTurn(sanitizeTurnRequest(nextReq)).generation;
+}
+async function* handleEgressGate(egress, flow, state, profile, maxRetries) {
+    const canRetry = flow.currentAttempt < maxRetries;
+    const outcome = await evaluateEgressOutcome({
+        egress,
+        attemptEvents: state.attemptEvents,
+        generation: flow.currentGen,
+        request: flow.currentReq,
+        profile,
+        canRetry,
+    });
+    if (outcome.action === 'refusal') {
+        state.allEmittedEvents.push(outcome.event);
+        yield outcome.event;
+        return 'terminal';
+    }
+    if (outcome.action === 'withhold') {
+        yield outcome.event;
+        return 'terminal';
+    }
+    if (outcome.action === 'retry') {
+        updateFlowForRetry(flow, outcome.nextRequest);
+        return 'continue';
+    }
+    return 'pass';
+}
+async function* handleValidationGate(validation, flow, state, latestStructured, maxRetries) {
+    const canRetry = flow.currentAttempt < maxRetries;
+    const outcome = await evaluateValidationOutcome({
+        validation,
+        latestStructured,
+        request: flow.currentReq,
+        canRetry,
+    });
+    if (outcome.action === 'retry') {
+        updateFlowForRetry(flow, outcome.nextRequest);
+        return 'continue';
+    }
+    if (outcome.action === 'accept') {
+        state.allEmittedEvents.push(outcome.event);
+        yield outcome.event;
+        return 'terminal';
+    }
+    return 'pass';
+}
+function gateStatusToAction(status, terminalStatus = 'terminal') {
+    if (status === 'terminal') {
+        return { status: terminalStatus };
+    }
+    if (status === 'continue') {
+        return { status: 'continue' };
+    }
+    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;
+    state.attemptEvents = [];
+    const { latestStructured } = yield* executeAttempt({
+        safe: flow.currentReq,
+        profile,
+        generation: flow.currentGen,
+        system,
+        provider,
+        gemini,
+        state,
+    });
+    if (egress?.enforce) {
+        const status = yield* handleEgressGate(egress, flow, state, profile, maxRetries);
+        const action = gateStatusToAction(status, 'terminal');
+        if (action) {
+            return action;
+        }
+    }
+    if (validation) {
+        const status = yield* handleValidationGate(validation, flow, state, latestStructured, maxRetries);
+        const action = gateStatusToAction(status, 'success');
+        if (action) {
+            return action;
+        }
+    }
+    if (validation || egress?.enforce) {
+        yield* yieldBufferedAttemptEvents(state.attemptEvents);
+    }
+    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);
+    const flow = {
+        currentAttempt: 0,
+        currentGen: generation,
+        currentReq: safe,
+    };
+    while (flow.currentAttempt <= maxRetries) {
+        const step = yield* executeSingleAttemptCycle({
+            flow,
+            state,
+            profile,
+            system,
+            provider,
+            gemini,
+            maxRetries,
+        });
+        if (step.status === 'terminal' || step.status === 'success') {
+            break;
+        }
+    }
+}
+async function* emitTurn(args) {
+    const { safe, profile, generation, system, provider, gemini } = args;
+    if (safe.toolInvoke) {
+        yield* invokeFromUi(profile, safe);
+        return;
+    }
+    const state = {
+        currentHistory: [...(generation.history ?? [])],
+        stepCount: 0,
+        sawTokensEvent: false,
+        allEmittedEvents: [],
+        attemptEvents: [],
+    };
+    yield* runAttemptsWithValidation(safe, profile, generation, system, provider, gemini, state);
+    if (!state.sawTokensEvent) {
+        yield* calculateFallbackTokens(safe, system, state.allEmittedEvents);
+    }
+    yield { type: 'done' };
+}
+/** Execute one host turn against a provider adapter. */
+async function* runTurn(req, provider, sink = noopSink()) {
+    const started = Date.now();
+    const seen = [];
+    const gemini = [];
+    let model;
+    let bucket;
+    let canary = '';
+    let system;
+    let generation;
+    try {
+        const safe = sanitizeTurnRequest(req);
+        const { profile, generation: gen } = resolveTurn(safe);
+        generation = gen;
+        const { model: resolvedModel, geminiBucket, canary: turnCanary } = gen;
+        model = resolvedModel;
+        bucket = geminiBucket;
+        canary = turnCanary;
+        const role = pickSystemRole(profile, safe.input?.role);
+        const profileSys = systemFromProfile(profile, role);
+        const combinedSys = [profileSys, safe.system].filter(Boolean).join('\n\n');
+        const bound = bindCanary(combinedSys, turnCanary);
+        system = bound;
+        for await (const event of emitTurn({
+            safe,
+            profile,
+            generation: gen,
+            system: bound,
+            provider,
+            gemini,
+        })) {
+            seen.push(event);
+            if (shouldSkipStreamEvent(event, profile)) {
+                continue;
+            }
+            yield event;
+        }
+    }
+    catch (err) {
+        await writeTrace(sink, buildRecord({
+            req,
+            events: seen,
+            started,
+            model,
+            bucket,
+            thrown: err,
+            gemini,
+            canary,
+            system,
+            generation,
+        }));
+        throw err;
+    }
+    await writeTrace(sink, buildRecord({
+        req,
+        events: seen,
+        started,
+        model,
+        bucket,
+        gemini,
+        canary,
+        system,
+        generation,
+    }));
+}
+export { runTurn };