theorum 0.1.2 → 0.1.3

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

@@ -0,0 +1,14 @@
+/**
+ * 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 { type TraceSink } from '../../../observability/trace.js';
+import type { ModelProvider, TurnEvent, TurnRequest } from '../../types.js';
+/** Execute one host turn against a provider adapter. */
+declare function runTurn(req: TurnRequest, provider: ModelProvider, sink?: TraceSink): AsyncGenerator<TurnEvent>;
+export { runTurn };

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

@@ -0,0 +1,103 @@
+/**
+ * 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 { 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 { bindCanary } from '../boundary.js';
+import { runAttemptsWithValidation } from './gates.js';
+import { shouldSkipStreamEvent, systemFromProfile } from './stream.js';
+import { calculateFallbackTokens } from './tokens.js';
+import { invokeFromUi } from './tools.js';
+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 };

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

@@ -0,0 +1,16 @@
+import type { ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnRequest } from '../../types.js';
+interface StepExecutionState {
+    currentHistory: TurnHistoryMessage[];
+    stepCount: number;
+    sawTokensEvent: boolean;
+    allEmittedEvents: TurnEvent[];
+    attemptEvents: TurnEvent[];
+}
+interface AttemptFlowState {
+    currentAttempt: number;
+    currentReq: TurnRequest;
+    currentGen: ResolvedGeneration;
+}
+declare function recordStepEvent(event: TurnEvent, state: StepExecutionState): void;
+export type { AttemptFlowState, StepExecutionState };
+export { recordStepEvent };

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

@@ -0,0 +1,8 @@
+function recordStepEvent(event, state) {
+    if (event.type === 'tokens') {
+        state.sawTokensEvent = true;
+    }
+    state.allEmittedEvents.push(event);
+    state.attemptEvents.push(event);
+}
+export { recordStepEvent };

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

@@ -0,0 +1,15 @@
+import type { ModelProvider, Profile, ResolvedGeneration, TurnEvent, TurnRequest } from '../../types.js';
+import { type StepExecutionState } from './state.js';
+declare function executeAttempt(args: {
+    safe: TurnRequest;
+    profile: Profile;
+    generation: ResolvedGeneration;
+    system: string;
+    provider: ModelProvider;
+    gemini: Record<string, unknown>[];
+    state: StepExecutionState;
+}): AsyncGenerator<TurnEvent, {
+    pendingTools: TurnEvent[];
+    latestStructured?: unknown;
+}>;
+export { executeAttempt };

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

@@ -0,0 +1,119 @@
+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) {
+        return false;
+    }
+    return step >= maxSteps;
+}
+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),
+    });
+}
+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 };
+}
+export { executeAttempt };

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

@@ -0,0 +1,11 @@
+import type { ModelProvider, Profile, ResolvedGeneration, TurnEvent } from '../../types.js';
+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>[];
+}): AsyncGenerator<TurnEvent>;
+export { shouldSkipStreamEvent, systemFromProfile, yieldProviderEvents };

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

@@ -0,0 +1,65 @@
+import { publicError } 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;
+    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({
+        ...providerCompleteRequest(generation, system),
+        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);
+    }
+}
+export { shouldSkipStreamEvent, systemFromProfile, yieldProviderEvents };

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

@@ -0,0 +1,3 @@
+import type { TurnEvent, TurnRequest } from '../../types.js';
+declare function calculateFallbackTokens(safe: TurnRequest, system: string, events: TurnEvent[]): Generator<TurnEvent>;
+export { calculateFallbackTokens };

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

@@ -0,0 +1,38 @@
+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,
+        },
+    };
+}
+export { calculateFallbackTokens };

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

@@ -0,0 +1,13 @@
+import type { CustomToolId, DynamicToolDeclaration, Profile, ResolvedGeneration, ToolEnvelope, TurnEvent, TurnRequest } from '../../types.js';
+declare function formatToolFinding(res: ToolEnvelope): string;
+declare function invokeFromUi(profile: Profile, req: TurnRequest): Generator<TurnEvent>;
+declare function dispatchModelTool(profile: Profile, event: TurnEvent, gated: CustomToolId[]): TurnEvent[];
+declare function findDynamicDeclaration(tools: DynamicToolDeclaration[] | undefined, name: string): DynamicToolDeclaration | undefined;
+declare function isActionableDynamicDeclaration(decl: DynamicToolDeclaration | undefined): decl is DynamicToolDeclaration;
+declare function executeDynamicDeclaration(args: {
+    decl: DynamicToolDeclaration;
+    toolArgs: Record<string, unknown>;
+    profile: Profile;
+    generation: ResolvedGeneration;
+}): Promise<ToolEnvelope>;
+export { dispatchModelTool, executeDynamicDeclaration, findDynamicDeclaration, formatToolFinding, invokeFromUi, isActionableDynamicDeclaration, };

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

@@ -0,0 +1,197 @@
+import { publicError } from '../../../guardrails/error.js';
+import { CATALOG } from '../../registry/catalog.js';
+import { executeTool } from '../../registry/tools.js';
+function formatToolFinding(res) {
+    if (res.finding) {
+        return res.finding;
+    }
+    if (res.data) {
+        return JSON.stringify(res.data);
+    }
+    return 'ok';
+}
+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 findDynamicDeclaration(tools, name) {
+    return tools?.find((t) => t.name === name);
+}
+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;
+}
+export { dispatchModelTool, executeDynamicDeclaration, findDynamicDeclaration, formatToolFinding, invokeFromUi, isActionableDynamicDeclaration, };

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

@@ -1,14 +1,6 @@
 /**
  * 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 { type TraceSink } from '../../observability/trace.js';
-import type { ModelProvider, TurnEvent, TurnRequest } from '../types.js';
-/** Execute one host turn against a provider adapter. */
-declare function runTurn(req: TurnRequest, provider: ModelProvider, sink?: TraceSink): AsyncGenerator<TurnEvent>;
-export { runTurn };
+export { runTurn } from './runner/mod.js';