@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/kernel/engine/media-probe/video.d.ts

@@ -0,0 +1,15 @@
+export interface VideoInfo {
+    /** Presented length of the first video track. */
+    seconds: number;
+    /** Coded frame size of the first video track. */
+    width: number;
+    height: number;
+    /** `0` when there is no audio track; `undefined` when its length cannot be read exactly. */
+    audioSeconds: number | undefined;
+}
+/**
+ * Identified by the bytes, not the declared MIME type. MP4 video length is the edit-list-aware
+ * header duration; Matroska video ends one frame after its latest block, else at the segment's
+ * stated `Duration`, and Matroska audio is known only when it is unlaced Opus.
+ */
+export declare function videoInfo(bytes: Uint8Array): VideoInfo | undefined;

package/esm/src/kernel/engine/media-probe/video.js

@@ -0,0 +1,49 @@
+import { MKV_AUDIO_TRACK, MKV_VIDEO_TRACK, matroska, opusSamplesFromNs, } from './matroska.js';
+import { MP4_SOUND, MP4_VIDEO, mp4Tracks } from './mp4.js';
+import { OPUS_RATE } from './opus.js';
+const NS_PER_SECOND = 1e9;
+function mp4Video(bytes) {
+    const tracks = mp4Tracks(bytes);
+    const video = tracks?.find((t) => t.handler === MP4_VIDEO);
+    if (!tracks || !video?.seconds || !video.width || !video.height)
+        return undefined;
+    const audio = tracks.find((t) => t.handler === MP4_SOUND);
+    return {
+        seconds: video.seconds,
+        width: video.width,
+        height: video.height,
+        audioSeconds: audio ? audio.decodedSeconds : 0,
+    };
+}
+/** End of the last frame: latest block timestamp plus one frame. */
+function matroskaVideoSeconds(track) {
+    if (track.lastNs === undefined)
+        return undefined;
+    const frameNs = track.defaultDurationNs ??
+        (track.previousNs === undefined ? undefined : track.lastNs - track.previousNs);
+    return frameNs === undefined ? undefined : (track.lastNs + frameNs) / NS_PER_SECOND;
+}
+function matroskaVideo(bytes) {
+    const file = matroska(bytes);
+    const video = file?.tracks.find((t) => t.type === MKV_VIDEO_TRACK);
+    if (!file || !video?.pixelWidth || !video.pixelHeight)
+        return undefined;
+    const seconds = (file.complete ? matroskaVideoSeconds(video) : undefined) ?? file.durationSeconds;
+    if (!seconds || seconds <= 0)
+        return undefined;
+    const audio = file.tracks.find((t) => t.type === MKV_AUDIO_TRACK);
+    const audioSeconds = !audio
+        ? 0
+        : file.complete && audio.opusSamples !== undefined
+            ? Math.max(0, audio.opusSamples - opusSamplesFromNs(audio.codecDelayNs)) / OPUS_RATE
+            : undefined;
+    return { seconds, width: video.pixelWidth, height: video.pixelHeight, audioSeconds };
+}
+/**
+ * Identified by the bytes, not the declared MIME type. MP4 video length is the edit-list-aware
+ * header duration; Matroska video ends one frame after its latest block, else at the segment's
+ * stated `Duration`, and Matroska audio is known only when it is unlaced Opus.
+ */
+export function videoInfo(bytes) {
+    return mp4Video(bytes) ?? matroskaVideo(bytes);
+}

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

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

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

@@ -0,0 +1,11 @@
+import { isRecord } from '../util/record.js';
+function asRecord(value) {
+    return isRecord(value) ? value : undefined;
+}
+function nonEmptyString(value) {
+    if (typeof value === 'string' && value.trim()) {
+        return value;
+    }
+    return undefined;
+}
+export { asRecord, nonEmptyString };

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,36 @@
+import { lexiconText } from '../../guardrails/lexicon.js';
+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, lexicon) {
+    if (messages.length === 0) {
+        return '';
+    }
+    const lines = messages.map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`);
+    const heading = lexiconText('repair.history_heading', { count: messages.length }, lexicon);
+    return `${heading}\n${lines.join('\n')}\n\n`;
+}
+function synthesizeRepairPrompt(args) {
+    const { profile, repair, history } = args;
+    const guidance = repair.guidance || lexiconText('repair.default_guidance', {}, profile.lexicon);
+    const historyBlock = formatHistoryBlock(scopeHistory(history), profile.lexicon);
+    let prompt = `${lexiconText('repair.prompt_header', {}, profile.lexicon)}\n\n`;
+    prompt += `${lexiconText('repair.prompt_intro', {}, profile.lexicon)}\n\n`;
+    prompt += `${lexiconText('repair.section_previous_output', {}, profile.lexicon)}\n\`\`\`\n${repair.previousOutput.trim()}\n\`\`\`\n\n`;
+    prompt += `${lexiconText('repair.section_validator_rejection', {}, profile.lexicon)}\n${repair.rejection.trim()}\n\n`;
+    if (guidance.trim()) {
+        prompt += `${lexiconText('repair.section_repair_guidance', {}, profile.lexicon)}\n${guidance.trim()}\n\n`;
+    }
+    if (historyBlock) {
+        prompt += historyBlock;
+    }
+    prompt += `${lexiconText('repair.section_instructions', {}, profile.lexicon)}\n`;
+    prompt += lexiconText('repair.prompt_instructions', {}, profile.lexicon);
+    return prompt;
+}
+export { synthesizeRepairPrompt };

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

@@ -0,0 +1,5 @@
+import type { BoundSystem } from '../../system-parts.js';
+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: BoundSystem, provider: ModelProvider, state: StepExecutionState): AsyncGenerator<TurnEvent>;
+export { runAttemptsWithValidation };

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

@@ -0,0 +1,322 @@
+import { hitRules, runEnforcer, WITHHELD_REASON } from '../../../guardrails/egress.js';
+import { TheoremError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
+import { guardrailFromVerdict } from '../../../guardrails/events.js';
+import { lexiconText } from '../../../guardrails/lexicon.js';
+import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
+import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { resolveInputParts } from '../../registry/ingress.js';
+import { profileTurnOutputs } from '../../registry/profile-outputs.js';
+import { injectWouldExceedMaxSteps } from '../../stages.js';
+import { findLast } from '../../util/find-last.js';
+import { guardrailCheckAttributes } from '../turn-trace.js';
+import { collectValidationFailures, formatValidationFailures } from './schema-validation.js';
+import { applyTurnStage } from './stages.js';
+import { appendUserInput } from './state.js';
+import { executeAttempt } from './steps.js';
+import { isWithheldOnBlock } from './stream.js';
+/** A turn whose final output the egress check blocked (withheld or replaced by policy copy). */
+const EGRESS_FILTERED_STOP = { kind: 'filtered', native: 'egress' };
+/** Reply text only: thoughts are not guarded output (`isGuardedOutput`). */
+function collectAttemptText(events) {
+    const parts = [];
+    for (const event of events) {
+        if (event.type === 'text' && event.text) {
+            parts.push(event.text);
+        }
+    }
+    return parts.join('');
+}
+// Structured output travels with the text so `outputs.structured` meets egress rather than passing unexamined.
+function projectOutbound(events) {
+    const structured = findLast(events, (e) => e.type === 'structured')?.structured;
+    return {
+        text: collectAttemptText(events),
+        ...(structured !== undefined ? { structured } : {}),
+    };
+}
+function buildRepairRequest(safe, previousOutput, rejection, repairGuidance) {
+    return {
+        ...safe,
+        input: {
+            ...safe.input,
+            repair: {
+                previousOutput: typeof previousOutput === 'string' ? previousOutput : JSON.stringify(previousOutput),
+                rejection,
+                guidance: repairGuidance,
+            },
+        },
+    };
+}
+async function evaluateEgressOutcome(args) {
+    const { egress, attemptEvents, generation, request, profile, canRetry, promptLeaks, givenUrls } = args;
+    const payload = projectOutbound(attemptEvents);
+    const context = {
+        stage: 'output_final',
+        trust: 'untrusted',
+        profileId: profile.id,
+        ...(profile.lexicon ? { lexicon: profile.lexicon } : {}),
+        ...(generation.canary ? { canary: generation.canary } : {}),
+        ...(request.input?.slots ? { slots: request.input.slots } : {}),
+        ...(request.input?.role ? { role: request.input.role } : {}),
+        givenUrls,
+    };
+    // The host policy adds checks; it never releases a system-prompt leak.
+    const verdict = promptLeaks?.length
+        ? {
+            action: 'block',
+            hits: promptLeaks,
+            rejection: lexiconText('egress.rejection', { rules: hitRules(promptLeaks).join(', ') }, profile.lexicon),
+        }
+        : await runEnforcer(egress.enforce, payload, context);
+    const guardrail = guardrailFromVerdict('output_final', 'untrusted', verdict);
+    // `flag` is advisory: the hit is recorded, the turn still releases.
+    if (verdict.action === 'allow' || verdict.action === 'flag') {
+        return { outcome: { action: 'pass' }, guardrail };
+    }
+    // The policy supplied safe replacement prose — release that instead.
+    if (verdict.action === 'redact') {
+        return {
+            outcome: {
+                action: 'refusal',
+                event: { type: 'text', text: verdict.text },
+            },
+            guardrail,
+        };
+    }
+    if (egress.onBlock === 'refuse_to_user') {
+        const text = lexiconText('egress.refusal', {}, profile.lexicon);
+        return { outcome: { action: 'refusal', event: { type: 'text', text } }, guardrail };
+    }
+    if (canRetry) {
+        const nextRequest = buildRepairRequest(request, payload.text, verdict.rejection, lexiconText('egress.default_repair_guidance', {}, profile.lexicon));
+        return { outcome: { action: 'retry', nextRequest }, guardrail };
+    }
+    return {
+        outcome: {
+            action: 'withhold',
+            event: toErrorEvent(new TheoremError('safety', WITHHELD_REASON.egress)),
+        },
+        guardrail,
+    };
+}
+async function evaluateValidationOutcome(args) {
+    const { validation, generation, latestStructured, request, canRetry } = args;
+    if (latestStructured === undefined) {
+        return { action: 'pass' };
+    }
+    const structured = generation.structured;
+    if (!structured) {
+        throw new TheoremError('config', 'outputs.validation requires outputs.structured with a JSON Schema');
+    }
+    const failures = await collectValidationFailures(structured.jsonSchema, latestStructured, validation.fields, request.input?.slots);
+    if (failures.length === 0) {
+        return { action: 'pass' };
+    }
+    const error = formatValidationFailures(failures);
+    if (canRetry) {
+        const nextRequest = buildRepairRequest(request, latestStructured, error);
+        return { action: 'retry', nextRequest };
+    }
+    return {
+        action: 'accept',
+        event: { type: 'structured', structured: latestStructured },
+    };
+}
+function* yieldBufferedAttemptEvents(events, alreadyStreamedUserVisible) {
+    for (const ev of events) {
+        if (ev.type === 'tokens') {
+            continue;
+        }
+        // Thoughts always streamed live; text and media did unless the attempt withheld them.
+        if (ev.type === 'thought' || (alreadyStreamedUserVisible && isWithheldOnBlock(ev))) {
+            continue;
+        }
+        yield ev;
+    }
+}
+/**
+ * Start the next attempt with the repair added. The turn is not resolved again:
+ * the retry keeps attempt 1's canary, tools and system prompt, and only the
+ * repair prompt is new.
+ */
+function updateFlowForRetry(flow, state, profile, nextReq, reason) {
+    flow.currentAttempt++;
+    state.trace.attempt = flow.currentAttempt;
+    state.trace.root.event('theorem.attempt.retry', { attempt: flow.currentAttempt, reason });
+    flow.currentReq = nextReq;
+    const safe = sanitizeTurnRequest(nextReq, profile);
+    if (profile.type === 'text') {
+        // The conversation is already in turn history: the repair is its next user message.
+        appendUserInput(state, resolveInputParts(profile, { ...safe, input: { repair: safe.input?.repair } }));
+        return;
+    }
+    // An image or speech call reads only its input: the repair replaces the prompt.
+    flow.currentGen = { ...flow.currentGen, input: resolveInputParts(profile, safe) };
+}
+async function* handleEgressGate(egress, flow, state, profile, maxRetries) {
+    const canRetry = flow.currentAttempt < maxRetries;
+    const checkStart = performance.now();
+    const { outcome, guardrail } = await evaluateEgressOutcome({
+        egress,
+        attemptEvents: state.attemptEvents,
+        generation: flow.currentGen,
+        request: flow.currentReq,
+        profile,
+        canRetry,
+        ...(state.promptLeaks ? { promptLeaks: state.promptLeaks } : {}),
+        givenUrls: state.givenUrls,
+    });
+    state.trace.root.event('theorem.guardrail', guardrailCheckAttributes('egress', performance.now() - checkStart, guardrail?.guardrail, {
+        stage: 'output_final',
+        trust: 'untrusted',
+    }));
+    if (guardrail) {
+        state.allEmittedEvents.push(guardrail);
+        yield guardrail;
+    }
+    if (outcome.action === 'refusal') {
+        state.lastStop = EGRESS_FILTERED_STOP;
+        state.allEmittedEvents.push(outcome.event);
+        yield outcome.event;
+        return 'terminal';
+    }
+    if (outcome.action === 'withhold') {
+        state.lastStop = EGRESS_FILTERED_STOP;
+        yield outcome.event;
+        return 'terminal';
+    }
+    if (outcome.action === 'retry') {
+        updateFlowForRetry(flow, state, profile, outcome.nextRequest, 'egress');
+        return 'continue';
+    }
+    return 'pass';
+}
+async function* handleValidationGate(validation, flow, state, profile, latestStructured, maxRetries) {
+    const canRetry = flow.currentAttempt < maxRetries;
+    const outcome = await evaluateValidationOutcome({
+        validation,
+        generation: flow.currentGen,
+        latestStructured,
+        request: flow.currentReq,
+        canRetry,
+    });
+    if (outcome.action === 'retry') {
+        updateFlowForRetry(flow, state, profile, outcome.nextRequest, 'validation');
+        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, maxRetries } = args;
+    const validation = profileTurnOutputs(profile)?.validation;
+    const egress = resolveGuardrailPolicy(profile.guardrails).egress;
+    // Fresh maxSteps budget per validation/egress attempt. before_end inject
+    // re-entry inside this cycle still accumulates stepCount (do not reset there).
+    state.stepCount = 0;
+    let latestStructured;
+    // before_end may inject and re-enter the step loop under maxSteps.
+    for (;;) {
+        state.attemptEvents = [];
+        state.withheldVisible = false;
+        state.promptLeaks = undefined;
+        const attempt = yield* executeAttempt({
+            safe: flow.currentReq,
+            profile,
+            generation: flow.currentGen,
+            system,
+            provider,
+            state,
+        });
+        latestStructured = attempt.latestStructured;
+        // Tool / gate suspension — do not before_end; finalize with that stop.
+        if (state.lastStop?.kind === 'tool' || state.lastStop?.kind === 'gate') {
+            break;
+        }
+        if (state.lastStop?.kind === 'cancelled') {
+            return { status: 'terminal' };
+        }
+        const beforeEnd = yield* applyTurnStage({
+            profile,
+            generation: flow.currentGen,
+            state,
+            stage: 'before_end',
+            step: Math.max(state.stepCount, 1),
+            onStage: flow.currentReq.onStage,
+            signal: flow.currentReq.signal,
+            host: flow.currentGen.host,
+            injectWouldExceedMaxSteps: injectWouldExceedMaxSteps(state.stepCount, flow.currentGen.maxSteps),
+        });
+        if (beforeEnd.abort) {
+            state.lastStop = {
+                kind: 'cancelled',
+                ...(typeof beforeEnd.abort === 'object' && beforeEnd.abort.reason
+                    ? { native: beforeEnd.abort.reason }
+                    : {}),
+            };
+            return { status: 'terminal' };
+        }
+        if (beforeEnd.injectCount > 0) {
+            // Host extended the turn — another provider step under maxSteps.
+            continue;
+        }
+        break;
+    }
+    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, profile, latestStructured, maxRetries);
+        const action = gateStatusToAction(status, 'success');
+        if (action) {
+            return action;
+        }
+    }
+    if (validation || egress?.enforce) {
+        // Progressive-yield already released text and media live under egress — unless it
+        // withheld them mid-stream. A passing final verdict on the full text supersedes
+        // that partial-window decision, so the buffer is released instead of dropped.
+        yield* yieldBufferedAttemptEvents(state.attemptEvents, !state.withheldVisible);
+    }
+    return { status: 'success' };
+}
+async function* runAttemptsWithValidation(safe, profile, generation, system, provider, state) {
+    const maxRetries = Math.max(profileTurnOutputs(profile)?.validation?.maxRetries ?? 0, resolveGuardrailPolicy(profile.guardrails).egress?.maxRetries ?? 0);
+    const flow = {
+        currentAttempt: 0,
+        currentGen: generation,
+        currentReq: safe,
+    };
+    while (flow.currentAttempt <= maxRetries) {
+        throwIfAborted(safe.signal);
+        const step = yield* executeSingleAttemptCycle({
+            flow,
+            state,
+            profile,
+            system,
+            provider,
+            maxRetries,
+        });
+        if (step.status === 'terminal' || step.status === 'success') {
+            break;
+        }
+    }
+}
+export { runAttemptsWithValidation };

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

@@ -0,0 +1,15 @@
+import type { TraceSink } from '../../../observability/trace-sink.js';
+import type { KernelRegistry } from '../../registry/kernel-registry.js';
+import type { CompactHistoryRequest, CompactionResult, ModelProvider, TurnEvent, TurnRequest } from '../../types.js';
+/**
+ * The trace record is written however the turn ends, including when the host stops reading early;
+ * spans still open then close as `ERROR` / `unclosed`.
+ */
+declare function runTurnInRegistry(registry: KernelRegistry, req: TurnRequest, provider: ModelProvider, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/**
+ * `timing: 'after'`: run the compactor on the history `done.compaction` carried,
+ * with the same split, failure rules and trace as `before`. `provider` runs the
+ * compactor. `undefined` when the split leaves nothing to compact.
+ */
+declare function compactHistoryInRegistry(registry: KernelRegistry, req: CompactHistoryRequest, provider: ModelProvider, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
+export { compactHistoryInRegistry, runTurnInRegistry };