@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/kernel/engine/live-ingress.d.ts

@@ -0,0 +1,15 @@
+import type { LiveIngressSpec, Profile } from '../types.js';
+/** A channel a live session can take input on: audio, video, or text. */
+export type LiveIngressChannel = keyof LiveIngressSpec;
+/** Default when `live.ingress.<channel>` is omitted — mic and camera on, typed text off. */
+export declare function liveIngressChannelDefault(channel: LiveIngressChannel): boolean;
+/** True when the ingress spec enables the channel. */
+export declare function liveIngressEnabledFromSpec(ingress: LiveIngressSpec | undefined, channel: LiveIngressChannel): boolean;
+/** True when the live profile enables the channel. */
+export declare function liveIngressEnabled(profile: Profile, channel: LiveIngressChannel): boolean;
+/** True when the live profile enables at least one channel. */
+export declare function hasAnyLiveIngress(profile: Profile): boolean;
+/** Throws when the live profile enables no input channel. */
+export declare function assertLiveIngressConfigured(profile: Profile): void;
+/** Throws when the live profile does not enable the channel. */
+export declare function assertLiveIngress(profile: Profile, channel: LiveIngressChannel): void;

package/esm/src/kernel/engine/live-ingress.js

@@ -0,0 +1,42 @@
+import { TheoremError } from '../../guardrails/error.js';
+const LIVE_INGRESS_CHANNELS = ['audio', 'video', 'text'];
+function assertLiveProfile(profile) {
+    if (profile.type !== 'live') {
+        throw new TheoremError('request', `Profile '${profile.id}' is not type 'live'`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return profile;
+}
+/** Default when `live.ingress.<channel>` is omitted — mic and camera on, typed text off. */
+export function liveIngressChannelDefault(channel) {
+    return channel !== 'text';
+}
+/** True when the ingress spec enables the channel. */
+export function liveIngressEnabledFromSpec(ingress, channel) {
+    const value = ingress?.[channel];
+    if (value === undefined)
+        return liveIngressChannelDefault(channel);
+    return value;
+}
+/** True when the live profile enables the channel. */
+export function liveIngressEnabled(profile, channel) {
+    const live = assertLiveProfile(profile);
+    return liveIngressEnabledFromSpec(live.live.ingress, channel);
+}
+/** True when the live profile enables at least one channel. */
+export function hasAnyLiveIngress(profile) {
+    const live = assertLiveProfile(profile);
+    return LIVE_INGRESS_CHANNELS.some((channel) => liveIngressEnabledFromSpec(live.live.ingress, channel));
+}
+/** Throws when the live profile enables no input channel. */
+export function assertLiveIngressConfigured(profile) {
+    const live = assertLiveProfile(profile);
+    if (hasAnyLiveIngress(live))
+        return;
+    throw new TheoremError('config', `Profile '${live.id}': at least one live.ingress channel (audio, video, text) must be enabled`);
+}
+/** Throws when the live profile does not enable the channel. */
+export function assertLiveIngress(profile, channel) {
+    if (liveIngressEnabled(profile, channel))
+        return;
+    throw new TheoremError('request', `Profile '${profile.id}' live.ingress.${channel} is disabled — cannot send on this channel`);
+}

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 { labelText } from '../../guardrails/labels.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, labels) {
+    if (messages.length === 0) {
+        return '';
+    }
+    const lines = messages.map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`);
+    const heading = labelText('repair.history_heading', { count: messages.length }, labels);
+    return `${heading}\n${lines.join('\n')}\n\n`;
+}
+function synthesizeRepairPrompt(args) {
+    const { profile, repair, history } = args;
+    const guidance = repair.guidance || labelText('repair.default_guidance', {}, profile.labels);
+    const historyBlock = formatHistoryBlock(scopeHistory(history), profile.labels);
+    let prompt = `${labelText('repair.prompt_header', {}, profile.labels)}\n\n`;
+    prompt += `${labelText('repair.prompt_intro', {}, profile.labels)}\n\n`;
+    prompt += `${labelText('repair.section_previous_output', {}, profile.labels)}\n\`\`\`\n${repair.previousOutput.trim()}\n\`\`\`\n\n`;
+    prompt += `${labelText('repair.section_validator_rejection', {}, profile.labels)}\n${repair.rejection.trim()}\n\n`;
+    if (guidance.trim()) {
+        prompt += `${labelText('repair.section_repair_guidance', {}, profile.labels)}\n${guidance.trim()}\n\n`;
+    }
+    if (historyBlock) {
+        prompt += historyBlock;
+    }
+    prompt += `${labelText('repair.section_instructions', {}, profile.labels)}\n`;
+    prompt += labelText('repair.prompt_instructions', {}, profile.labels);
+    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 { Profile, ResolvedGeneration, TurnEvent, TurnModel, TurnRequest } from '../../types.js';
+import { type StepExecutionState } from './state.js';
+declare function runAttemptsWithValidation(safe: TurnRequest, profile: Profile, generation: ResolvedGeneration, system: BoundSystem, provider: TurnModel, state: StepExecutionState): AsyncGenerator<TurnEvent>;
+export { runAttemptsWithValidation };

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

@@ -0,0 +1,508 @@
+import { scopeOf } from '../../../guardrails/detect-at.js';
+import { readReply, refusalAfter, replyAfter, standingBlock, TURN_REPLY, } from '../../../guardrails/detect-reply.js';
+import { WITHHELD_REASON } from '../../../guardrails/egress.js';
+import { TheoremError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
+import { guardrailFromHits, guardrailTurnEvent } from '../../../guardrails/events.js';
+import { retryRejection } from '../../../guardrails/hints.js';
+import { labelText } from '../../../guardrails/labels.js';
+import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
+import { replyIsJudged } from '../../../guardrails/progressive-yield.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 { collectItemFailures, collectValidationFailures, formatValidationFailures, itemSchemaAt, valueAt, withListAt, } from './schema-validation.js';
+import { applyTurnStage } from './stages.js';
+import { appendUserInput, } from './state.js';
+import { executeAttempt } from './steps.js';
+import { isWithheldOnBlock, shownToHost } 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('');
+}
+// why: 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,
+            },
+        },
+    };
+}
+/** The verdict on an attempt's reply, as `guardrails.detect` reads it whole. */
+function evaluateEgressOutcome(args) {
+    const { attemptEvents, request, profile, canRetry, promptLeaks } = args;
+    const { detect, blockedReply } = args.policy;
+    const written = projectOutbound(attemptEvents);
+    const scope = scopeOf(args.policy, {
+        canary: args.generation.canary,
+        canaryGiven: args.canaryGiven,
+        privateSystem: args.privateSystem,
+        givenUrls: args.givenUrls,
+        ...(args.ownTools ? { ownTools: args.ownTools } : {}),
+        ...(profile.labels ? { labels: profile.labels } : {}),
+    });
+    const read = readReply(written, detect, {
+        boundary: 'reply',
+        ...(args.withheld ? { reportedTo: args.released.length } : {}),
+        scope,
+    });
+    const { payload } = read;
+    /** Text that takes the written reply's place, as the host receives it. */
+    const replacement = (text) => ({
+        action: 'refusal',
+        event: { type: 'text', text },
+    });
+    const stopped = standingBlock(read, promptLeaks);
+    // why: A detector's block is reported by its own event, which names the boundary.
+    const judged = stopped && stopped !== read.blocked
+        ? guardrailFromHits('output_final', 'untrusted', stopped, 'block')
+        : undefined;
+    const guardrails = [...read.events.map(guardrailTurnEvent), ...(judged ? [judged] : [])];
+    if (!stopped) {
+        if (read.rewritten) {
+            // why: Text the stream could not replace as it went: the reply goes out replaced, whole.
+            return { outcome: replacement(replyAfter(args.shown, payload.text)), guardrails };
+        }
+        const replaced = payload.structured !== written.structured;
+        return {
+            outcome: { action: 'pass' },
+            guardrails,
+            ...(replaced ? { structured: payload.structured } : {}),
+        };
+    }
+    if (blockedReply.onBlock === 'refuse') {
+        return { outcome: replacement(refusalAfter(args.shown, profile.labels)), guardrails };
+    }
+    if (canRetry) {
+        const nextRequest = buildRepairRequest(request, payload.text, retryRejection(stopped, detect, profile.labels), labelText('egress.default_repair_guidance', {}, profile.labels));
+        return { outcome: { action: 'retry', nextRequest }, guardrails };
+    }
+    return {
+        outcome: {
+            action: 'withhold',
+            event: toErrorEvent(new TheoremError('safety', WITHHELD_REASON.egress)),
+        },
+        guardrails,
+    };
+}
+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' };
+    if (!canRetry)
+        return { action: 'pass', failed: failures };
+    const nextRequest = buildRepairRequest(request, latestStructured, formatValidationFailures(failures));
+    return { action: 'retry', nextRequest };
+}
+function* yieldBufferedAttemptEvents(events, alreadyStreamedUserVisible, generation) {
+    for (const ev of events) {
+        if (ev.type === 'tokens') {
+            continue;
+        }
+        // why: Thoughts always streamed live; text and media did unless the attempt withheld them.
+        if (ev.type === 'thought' || (alreadyStreamedUserVisible && isWithheldOnBlock(ev))) {
+            continue;
+        }
+        // why: A held structured reply was judged whole; its drafts are the JSON before that check, so the `structured` event alone shows it.
+        const shown = shownToHost(ev, { ...generation, stream: false });
+        if (shown)
+            yield shown;
+    }
+}
+/**
+ * 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') {
+        // why: The conversation is already in turn history: the repair is its next user message.
+        const before = state.currentHistory.length;
+        appendUserInput(state, resolveInputParts(profile, { ...safe, input: { repair: safe.input?.repair } }));
+        for (const message of state.currentHistory.slice(before))
+            quotesOwnReply(state, message);
+    }
+    else {
+        // why: An image or speech call reads only its input: the repair replaces the prompt.
+        const input = resolveInputParts(profile, safe);
+        quotesOwnReply(state, input);
+        flow.currentGen = { ...flow.currentGen, input };
+    }
+    const event = { type: 'attempt', attempt: flow.currentAttempt, reason };
+    state.allEmittedEvents.push(event);
+    return event;
+}
+/**
+ * A repair hands the stopped reply back, and the model wrote that reply. What
+ * carries it gives the model nothing: a canary or a URL in it is still a leak
+ * on the next attempt.
+ */
+function quotesOwnReply(state, carrier) {
+    state.canaryScanned.add(carrier);
+    state.givenUrls.own.add(carrier);
+}
+/** Whether an attempt holds its reply text to its end: one validated and not streamed. */
+function holdsVisible(profile, generation) {
+    return profileTurnOutputs(profile)?.validation !== undefined && generation.stream === false;
+}
+async function* handleEgressGate(policy, flow, state, profile, privateSystem) {
+    const canRetry = flow.currentAttempt < policy.blockedReply.maxRetries;
+    const checkStart = performance.now();
+    const { outcome, guardrails, structured } = await evaluateEgressOutcome({
+        policy,
+        attemptEvents: state.attemptEvents,
+        withheld: state.withheldVisible === true,
+        released: state.released,
+        shown: holdsVisible(profile, flow.currentGen) ? '' : state.released,
+        generation: flow.currentGen,
+        request: flow.currentReq,
+        profile,
+        canRetry,
+        ...(state.promptLeaks ? { promptLeaks: state.promptLeaks } : {}),
+        givenUrls: state.givenUrls,
+        canaryGiven: state.canaryGiven,
+        privateSystem,
+        ...(state.ownTools ? { ownTools: state.ownTools } : {}),
+    });
+    state.trace.root.event('theorem.guardrail', guardrailCheckAttributes('egress', performance.now() - checkStart, guardrails.at(-1)?.guardrail, {
+        stage: 'output_final',
+        trust: 'untrusted',
+    }));
+    for (const guardrail of guardrails) {
+        state.allEmittedEvents.push(guardrail);
+        yield guardrail;
+    }
+    if (structured !== undefined) {
+        // why: What validation reads and the host receives is the structured output as replaced.
+        const held = findLast(state.attemptEvents, (event) => event.type === 'structured');
+        if (held)
+            state.attemptEvents[state.attemptEvents.indexOf(held)] = { ...held, structured };
+    }
+    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') {
+        yield updateFlowForRetry(flow, state, profile, outcome.nextRequest, 'egress');
+        return 'continue';
+    }
+    return 'pass';
+}
+/** The refused items of each list, in the reply's own shape and order. */
+function refusedLists(refused) {
+    let lists = {};
+    for (const path of new Set(refused.map((failure) => failure.path))) {
+        const items = refused.filter((failure) => failure.path === path).map(({ item }) => item);
+        lists = withListAt(lists, path, items);
+    }
+    return lists;
+}
+/**
+ * The schema a rewrite of refused items answers under: the reply's shape, holding
+ * only the lists that had a refused item.
+ *
+ * why: Under the reply's own schema the model would write the whole reply again to change one item.
+ */
+function fixSchemaFor(jsonSchema, paths) {
+    const root = { type: 'object', properties: {}, required: [] };
+    // why: An item schema may point into the reply schema's definitions.
+    if (jsonSchema.$defs !== undefined)
+        root.$defs = jsonSchema.$defs;
+    for (const path of paths) {
+        const items = itemSchemaAt(jsonSchema, path);
+        if (!items)
+            continue;
+        const keys = path.split('.');
+        let node = root;
+        for (const [depth, key] of keys.entries()) {
+            if (!node.required.includes(key))
+                node.required.push(key);
+            if (depth === keys.length - 1) {
+                node.properties[key] = { type: 'array', items };
+                break;
+            }
+            const next = node.properties[key];
+            const child = next?.type === 'object' ? next : { type: 'object', properties: {}, required: [] };
+            node.properties[key] = child;
+            node = child;
+        }
+    }
+    return root;
+}
+/** `fix.reply` with each refused item replaced by its rewrite, matched by position; one with no rewrite stays as it was. */
+function withRewrittenItems(fix, rewrite) {
+    let reply = fix.reply;
+    for (const path of new Set(fix.refused.map((failure) => failure.path))) {
+        const list = valueAt(reply, path);
+        const rewritten = valueAt(rewrite, path);
+        if (!Array.isArray(list) || !Array.isArray(rewritten))
+            continue;
+        const next = [...list];
+        const refusedHere = fix.refused.filter((failure) => failure.path === path);
+        for (const [position, failure] of refusedHere.entries()) {
+            if (position < rewritten.length)
+                next[failure.index] = rewritten[position];
+        }
+        reply = withListAt(reply, path, next);
+    }
+    return reply;
+}
+/** `reply` without its refused items. */
+function withoutItems(reply, refused) {
+    let next = reply;
+    for (const path of new Set(refused.map((failure) => failure.path))) {
+        const list = valueAt(next, path);
+        if (!Array.isArray(list))
+            continue;
+        const gone = new Set(refused.filter((failure) => failure.path === path).map(({ index }) => index));
+        next = withListAt(next, path, list.filter((_, index) => !gone.has(index)));
+    }
+    return next;
+}
+/**
+ * Makes `reply` the attempt's structured output, with what the item rules removed.
+ *
+ * why: The buffered text is the model's own JSON, which no longer matches; held text goes out as the reply that is kept, and streamed text is skipped at release as it always is.
+ */
+function holdReply(state, reply, removed, failed) {
+    const event = {
+        type: 'structured',
+        structured: reply,
+        ...(removed.length
+            ? { removed: removed.map(({ path, reason, item }) => ({ path, reason, item })) }
+            : {}),
+        ...(failed ? { failed } : {}),
+    };
+    state.attemptEvents = [
+        ...state.attemptEvents.filter((held) => held.type !== 'structured' && held.type !== 'text'),
+        { type: 'text', text: JSON.stringify(reply) },
+        event,
+    ];
+}
+/** The next attempt rewrites only the refused items, under a schema that holds only their lists. */
+function startItemFix(args) {
+    const { flow, state, profile, reply, refused, structured } = args;
+    const positions = new Map();
+    const rejection = refused
+        .map(({ path, reason }) => {
+        const position = positions.get(path) ?? 0;
+        positions.set(path, position + 1);
+        return `${path}[${position}]: ${reason}`;
+    })
+        .join('\n');
+    const nextRequest = buildRepairRequest(flow.currentReq, refusedLists(refused), rejection, labelText('repair.items_guidance', {}, profile.labels));
+    flow.pendingItemFix = { reply, refused, structured };
+    const attempt = updateFlowForRetry(flow, state, profile, nextRequest, 'validation');
+    flow.currentGen = {
+        ...flow.currentGen,
+        structured: {
+            id: structured.id,
+            jsonSchema: fixSchemaFor(structured.jsonSchema, refused.map(({ path }) => path)),
+        },
+    };
+    return attempt;
+}
+async function handleValidationGate(validation, flow, state, profile, latestStructured) {
+    const canRetry = flow.currentAttempt < (validation.maxRetries ?? 0);
+    const fix = flow.pendingItemFix;
+    let reply = latestStructured;
+    if (fix) {
+        // why: The attempt that just ended answered under the fix schema; the reply is the one the items were refused in, with the rewrites put back.
+        flow.pendingItemFix = undefined;
+        flow.currentGen = { ...flow.currentGen, structured: fix.structured };
+        reply = withRewrittenItems(fix, latestStructured);
+        holdReply(state, reply, []);
+    }
+    const outcome = await evaluateValidationOutcome({
+        validation,
+        generation: flow.currentGen,
+        latestStructured: reply,
+        request: flow.currentReq,
+        canRetry,
+    });
+    if (outcome.action === 'retry') {
+        return updateFlowForRetry(flow, state, profile, outcome.nextRequest, 'validation');
+    }
+    if (reply === undefined)
+        return 'pass';
+    if (outcome.failed)
+        markFailed(state, outcome.failed);
+    const slots = flow.currentReq.input?.slots;
+    const refused = await collectItemFailures(reply, validation.items, {
+        ...(slots ? { slots } : {}),
+        toolResults: state.toolResults,
+    });
+    if (refused.length === 0)
+        return 'pass';
+    const fixable = refused.filter((failure) => failure.onFail === 'fix');
+    const structured = flow.currentGen.structured;
+    // invariant: Refused items get one rewrite. Refused again, they are removed.
+    if (fixable.length > 0 && canRetry && !fix && structured) {
+        return startItemFix({ flow, state, profile, reply, refused: fixable, structured });
+    }
+    holdReply(state, withoutItems(reply, refused), refused, outcome.failed);
+    return 'pass';
+}
+/** Puts on the attempt's structured output the fields that still failed. */
+function markFailed(state, failed) {
+    const held = findLast(state.attemptEvents, (event) => event.type === 'structured');
+    if (held)
+        state.attemptEvents[state.attemptEvents.indexOf(held)] = { ...held, failed };
+}
+function gateStatusToAction(status) {
+    if (status === 'terminal') {
+        return { status: 'terminal' };
+    }
+    if (status === 'continue') {
+        return { status: 'continue' };
+    }
+    return null;
+}
+async function* executeSingleAttemptCycle(args) {
+    const { flow, state, profile, system, provider } = args;
+    const validation = profileTurnOutputs(profile)?.validation;
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const judged = replyIsJudged(policy, TURN_REPLY);
+    // invariant: 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;
+    for (;;) {
+        state.attemptEvents = [];
+        state.released = '';
+        state.withheldVisible = false;
+        state.promptLeaks = undefined;
+        const attempt = yield* executeAttempt({
+            safe: flow.currentReq,
+            profile,
+            generation: flow.currentGen,
+            system,
+            provider,
+            state,
+        });
+        latestStructured = attempt.latestStructured;
+        // why: Tool / gate suspension, or no answer to check — do not before_end; finalize with that stop.
+        if (state.lastStop?.kind === 'tool' ||
+            state.lastStop?.kind === 'gate' ||
+            state.lastStop?.kind === 'step_limit') {
+            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) {
+            continue;
+        }
+        break;
+    }
+    if (judged) {
+        const status = yield* handleEgressGate(policy, flow, state, profile, system.private);
+        const action = gateStatusToAction(status);
+        if (action) {
+            return action;
+        }
+        latestStructured = projectOutbound(state.attemptEvents).structured ?? latestStructured;
+    }
+    if (validation) {
+        const status = await handleValidationGate(validation, flow, state, profile, latestStructured);
+        if (status !== 'pass') {
+            yield status;
+            return { status: 'continue' };
+        }
+    }
+    if (validation || judged) {
+        // why: 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.
+        const heldVisible = state.withheldVisible || holdsVisible(profile, flow.currentGen);
+        yield* yieldBufferedAttemptEvents(state.attemptEvents, !heldVisible, flow.currentGen);
+    }
+    return { status: 'success' };
+}
+async function* runAttemptsWithValidation(safe, profile, generation, system, provider, state) {
+    const { blockedReply } = resolveGuardrailPolicy(profile.guardrails);
+    // why: Each gate counts the attempts against its own cap; the turn runs while either has one left.
+    const maxRetries = Math.max(profileTurnOutputs(profile)?.validation?.maxRetries ?? 0, blockedReply.onBlock === 'retry' ? blockedReply.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,
+        });
+        if (step.status === 'terminal' || step.status === 'success') {
+            break;
+        }
+    }
+}
+export { runAttemptsWithValidation };

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

@@ -0,0 +1,29 @@
+import type { TraceSink } from '../../../observability/trace-sink.js';
+import type { ProviderHostOptions } from '../../protocols/runtime.js';
+import type { KernelRegistry } from '../../registry/kernel-registry.js';
+import type { AgentCaller } from '../../tools/agent.js';
+import type { InvokeToolRequest } from '../../tools/types.js';
+import type { CompactHistoryRequest, CompactionResult, SessionRequest, TurnEvent, TurnModel, 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: TurnModel, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/**
+ * A host's own call's agent tools: the host's provider, or the one `onAgentCall`
+ * returns, runs each. Its nested turns bind their canaries into `canaries`.
+ */
+declare function invokeAgentCaller(registry: KernelRegistry, request: InvokeToolRequest, canaries: string[]): AgentCaller;
+/**
+ * A live session's agent tools: the session's own provider options, or those
+ * `onAgentCall` returns, run each. Its nested turns bind their canaries into
+ * `canaries`.
+ */
+declare function sessionAgentCaller(registry: KernelRegistry, req: Pick<SessionRequest, 'onAgentCall' | 'metadata'>, options: ProviderHostOptions & Pick<TurnRequest, 'execution'>, canaries: string[]): AgentCaller;
+/**
+ * `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: TurnModel, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
+export { compactHistoryInRegistry, invokeAgentCaller, runTurnInRegistry, sessionAgentCaller };