theorum 0.1.4 → 0.1.5

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

@@ -0,0 +1,9 @@
+const HEX_PAD = 2;
+const HEX_RADIX = 16;
+function hexSha256(bytes) {
+    return [...bytes].map((b) => b.toString(HEX_RADIX).padStart(HEX_PAD, '0')).join('');
+}
+export async function sha256(text) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return hexSha256(new Uint8Array(buf));
+}

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

@@ -0,0 +1,2 @@
+declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export { asRecord };

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

@@ -0,0 +1,7 @@
+function asRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+export { asRecord };

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

@@ -0,0 +1,7 @@
+import type { Profile, TurnHistoryMessage, TurnRepairRequest } from '../types.js';
+declare function synthesizeRepairPrompt(args: {
+    profile: Profile;
+    repair: TurnRepairRequest;
+    history?: TurnHistoryMessage[];
+}): string;
+export { synthesizeRepairPrompt };

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

@@ -0,0 +1,38 @@
+const MAX_REPAIR_HISTORY_EXCHANGES = 2;
+const MAX_REPAIR_HISTORY_MESSAGES = MAX_REPAIR_HISTORY_EXCHANGES * 2;
+function scopeHistory(history) {
+    if (!history || history.length === 0) {
+        return [];
+    }
+    return history.slice(-MAX_REPAIR_HISTORY_MESSAGES);
+}
+function formatHistoryBlock(messages) {
+    if (messages.length === 0) {
+        return '';
+    }
+    const lines = messages.map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`);
+    return `### RECENT CONVERSATION CONTEXT (LAST ${messages.length} TURNS)\n${lines.join('\n')}\n\n`;
+}
+function synthesizeRepairPrompt(args) {
+    const { profile, repair, history } = args;
+    const guidance = repair.guidance ||
+        profile.outputs.validation?.repairGuidance ||
+        'Revise the previous output so it satisfies the validator rejection. Preserve the intended user-facing substance unless the guidance says otherwise.';
+    const historyBlock = formatHistoryBlock(scopeHistory(history));
+    let prompt = `## OUTPUT REPAIR REQUEST\n\n`;
+    prompt += `The previous assistant output was rejected by a host validator and must be revised.\n\n`;
+    prompt += `### PREVIOUS OUTPUT\n\`\`\`\n${repair.previousOutput.trim()}\n\`\`\`\n\n`;
+    prompt += `### VALIDATOR REJECTION\n${repair.rejection.trim()}\n\n`;
+    if (guidance.trim()) {
+        prompt += `### REPAIR GUIDANCE\n${guidance.trim()}\n\n`;
+    }
+    if (historyBlock) {
+        prompt += historyBlock;
+    }
+    prompt += `### INSTRUCTIONS\n`;
+    prompt += `1. Inspect the previous output and validator rejection.\n`;
+    prompt += `2. Apply the repair guidance without inventing unsupported facts.\n`;
+    prompt += `3. Return only the corrected assistant output required by the active profile.`;
+    return prompt;
+}
+export { synthesizeRepairPrompt };

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

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

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

@@ -0,0 +1,203 @@
+import { toErrorEvent } from '../../../guardrails/error.js';
+import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { resolveTurn } from '../../registry/resolve.js';
+import { executeAttempt } from './steps.js';
+function collectAttemptText(events) {
+    return events
+        .filter((e) => e.type === 'text' && e.text)
+        .map((e) => e.text)
+        .join('');
+}
+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: toErrorEvent('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;
+        }
+    }
+}
+export { runAttemptsWithValidation };

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,109 @@
+/**
+ * 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 (event.type === 'error') {
+                const detail = event.errorInternal ?? event.error;
+                if (detail) {
+                    console.error(`[theorum] turn error (${req.profile}): ${detail}`);
+                }
+            }
+            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,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 };