theorum 0.1.4 → 0.1.6

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

@@ -0,0 +1,127 @@
+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, buffer = {
+    holdLate: false,
+    holdUserVisible: 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);
+        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;
+        }
+    }
+    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 holdUserVisible = Boolean(profile.guardrails.egress?.enforce);
+    const holdLate = Boolean(profile.outputs.validation) || holdUserVisible;
+    while (!isStepLimitReached(stepInAttempt, generation.maxSteps)) {
+        stepInAttempt++;
+        state.stepCount++;
+        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, gemini }, state, { holdLate, holdUserVisible });
+        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,70 @@
+import { publicError, 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;
+    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') {
+        const internal = event.errorInternal ?? event.error ?? '';
+        yield {
+            type: 'error',
+            error: publicError(event.error ?? internal),
+            ...(internal ? { errorInternal: internal } : {}),
+        };
+    }
+    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 toErrorEvent('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,192 @@
+import { toErrorEvent } 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 toErrorEvent(formatToolFinding(result));
+            return;
+        }
+        yield { type: 'done' };
+    }
+    catch (err) {
+        yield toErrorEvent(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(toErrorEvent(formatToolFinding(result)));
+        }
+        return events;
+    }
+    catch (err) {
+        return [toErrorEvent(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 [toErrorEvent(`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/{src/kernel/engine/runner.ts → esm/src/kernel/engine/runner.d.ts}

@@ -3,5 +3,4 @@
  *
  * @module
  */
-
-export { runTurn } from './runner/mod.ts';
+export { runTurn } from './runner/mod.js';

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

@@ -0,0 +1,6 @@
+/**
+ * Deterministic turn runner for THEORUM.
+ *
+ * @module
+ */
+export { runTurn } from './runner/mod.js';

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

@@ -0,0 +1,2 @@
+declare function mapStrings(value: unknown, map: (text: string) => string): unknown;
+export { mapStrings };

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

@@ -0,0 +1,17 @@
+function mapStrings(value, map) {
+    if (typeof value === 'string') {
+        return map(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => mapStrings(item, map));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            out[key] = mapStrings(nested, map);
+        }
+        return out;
+    }
+    return value;
+}
+export { mapStrings };

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

@@ -0,0 +1,18 @@
+/**
+ * Profile, turn, tool, provider, egress, and event contracts for THEORUM.
+ *
+ * This entrypoint is type-first. Host applications import from here when they
+ * want to declare profiles, tool schemas, provider adapters, turn requests, or
+ * trace-safe event handlers without importing provider implementations.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { runTurn } from './engine/runner.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export type { ProfileDefinition } from './registry/profiles.js';
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
+export { projectProfile, resolveTurn } from './registry/resolve.js';
+export { getStructured, registerStructured } from './registry/schemas.js';
+export { executeTool } from './registry/tools.js';
+export type * from './types.js';

package/esm/src/kernel/mod.js

@@ -0,0 +1,16 @@
+/**
+ * Profile, turn, tool, provider, egress, and event contracts for THEORUM.
+ *
+ * This entrypoint is type-first. Host applications import from here when they
+ * want to declare profiles, tool schemas, provider adapters, turn requests, or
+ * trace-safe event handlers without importing provider implementations.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { runTurn } from './engine/runner.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
+export { projectProfile, resolveTurn } from './registry/resolve.js';
+export { getStructured, registerStructured } from './registry/schemas.js';
+export { executeTool } from './registry/tools.js';

package/esm/src/kernel/registry/attachments.d.ts

@@ -0,0 +1,16 @@
+import type { MediaLimits, Profile, TurnBlob } from '../types.js';
+declare function tooManyFilesMessage(maxFiles: number): string;
+declare function fileTooLargeMessage(maxBytes: number): string;
+declare function turnTooLargeMessage(maxTurnBytes: number): string;
+declare function requireMediaLimits(profile: Profile): MediaLimits;
+declare function sanitizeCsvText(text: string): string;
+declare function assertAttachmentLimits(blobs: TurnBlob[], limits: MediaLimits): void;
+declare function sanitizeTurnBlobs(attachments: TurnBlob[] | undefined, voice: TurnBlob[] | undefined, limits: MediaLimits | undefined): {
+    attachments?: TurnBlob[];
+    voice?: TurnBlob[];
+};
+declare function sanitizeTurnBlobsForProfile(profileId: string, attachments: TurnBlob[] | undefined, voice: TurnBlob[] | undefined): {
+    attachments?: TurnBlob[];
+    voice?: TurnBlob[];
+};
+export { assertAttachmentLimits, fileTooLargeMessage, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };