@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,22 @@
+import type { TraceSink } from '../observability/trace-sink.js';
+import { type RunDecisionOptions } from './engine/decision.js';
+import { type RunSessionOptions } from './engine/session/mod.js';
+import { type KernelRegistry } from './registry/kernel-registry.js';
+import { resolveTurnInRegistry } from './registry/resolve.js';
+import type { InvokeToolRequest } from './tools/types.js';
+import type { CompactHistoryRequest, CompactionResult, DecisionRequest, DecisionResult, LiveSession, ModelProvider, ProjectedProfile, SessionRequest, TurnEvent, TurnRequest } from './types.js';
+interface KernelScope extends KernelRegistry {
+    runTurn(req: TurnRequest, provider: ModelProvider, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+    runSession(req: SessionRequest, options: RunSessionOptions, sinkOverride?: TraceSink): Promise<LiveSession>;
+    compactHistory(req: CompactHistoryRequest, provider: ModelProvider, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
+    invokeTool(request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+    resolveTurn(req: TurnRequest): ReturnType<typeof resolveTurnInRegistry>;
+    projectProfile(id: string): ProjectedProfile;
+    runDecision(request: DecisionRequest, options: RunDecisionOptions): Promise<DecisionResult>;
+}
+/** Isolated from every other scope: a host that registers per request gives each its own. */
+declare function createKernelScope(): KernelScope;
+/** The process-wide scope behind the package's global API. */
+declare const defaultKernelScope: KernelScope;
+export type { KernelScope };
+export { createKernelScope, defaultKernelScope };

package/esm/src/kernel/scope.js

@@ -0,0 +1,25 @@
+import { runDecisionInRegistry } from './engine/decision.js';
+import { compactHistoryInRegistry, runTurnInRegistry } from './engine/runner/mod.js';
+import { runSessionInRegistry } from './engine/session/mod.js';
+import { createKernelRegistry } from './registry/kernel-registry.js';
+import { projectProfileInRegistry, resolveTurnInRegistry } from './registry/resolve.js';
+import { invokeTool } from './tools/invoke.js';
+/** Isolated from every other scope: a host that registers per request gives each its own. */
+function createKernelScope() {
+    const registry = createKernelRegistry();
+    return {
+        tools: registry.tools,
+        profiles: registry.profiles,
+        schemas: registry.schemas,
+        runTurn: (req, provider, sinkOverride) => runTurnInRegistry(registry, req, provider, sinkOverride),
+        runSession: (req, options, sinkOverride) => runSessionInRegistry(registry, req, options, sinkOverride),
+        compactHistory: (req, provider, sinkOverride) => compactHistoryInRegistry(registry, req, provider, sinkOverride),
+        invokeTool: (request, sinkOverride) => invokeTool(registry, request, sinkOverride),
+        resolveTurn: (req) => resolveTurnInRegistry(registry, req),
+        projectProfile: (id) => projectProfileInRegistry(registry, id),
+        runDecision: (request, options) => runDecisionInRegistry(registry, request, options),
+    };
+}
+/** The process-wide scope behind the package's global API. */
+const defaultKernelScope = createKernelScope();
+export { createKernelScope, defaultKernelScope };

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

@@ -0,0 +1,141 @@
+import type { SpanHandle } from '../observability/trace-span.js';
+import type { StageApplyWarningCode, TurnStage } from './schema.js';
+import type { TurnStop } from './stop.js';
+import type { ModelToolResult, ToolFailure, ToolGate } from './tools/types.js';
+import { type AwaitingUserInput, type StageApplyWarning, type TurnEventOf } from './turn-events.js';
+import type { Profile, TurnEvent, TurnHistoryMessage } from './types.js';
+export type { AwaitingUserInput, ToolGate };
+export declare const STAGE_AFFORDANCES: readonly ["inject", "abort", "deny", "confirm", "mutate"];
+export type StageAffordance = (typeof STAGE_AFFORDANCES)[number];
+/** Inject still needs the inject gate at apply time. Empty = observe only. */
+export declare const STAGE_AFFORDANCE_MATRIX: Readonly<Record<TurnStage, readonly StageAffordance[]>>;
+export type StageCallBag = {
+    callId?: string;
+    tool?: string;
+    input?: unknown;
+    callNotStarted?: boolean;
+    outputRaw?: unknown;
+    outputModel?: ModelToolResult;
+    failure?: ToolFailure;
+    awaiting?: boolean;
+    stop?: TurnStop;
+    gate?: ToolGate;
+};
+export interface StageContext extends StageCallBag {
+    stage: TurnStage;
+    /** 1-based provider step (text) or utterance cycle index (live). */
+    step: number;
+    history: readonly TurnHistoryMessage[];
+    /** Opaque host slot — never traced or client-forwarded by the kernel. */
+    host?: unknown;
+}
+export interface StageResult {
+    inject?: TurnHistoryMessage[];
+    /**
+     * Names this `inject` in the `stage` event that records it landing. A blank or
+     * non-string id refuses the inject whole.
+     */
+    injectId?: string;
+    abort?: boolean | {
+        reason?: string;
+    };
+    /** `pre_tool`: refuse the call. `post_tool`: replace the result with this failure. */
+    deny?: {
+        code?: string;
+        message?: string;
+    };
+    /** `pre_tool` only — request a confirm/permission gate. */
+    confirm?: true | {
+        summary?: string;
+    };
+    /** `pre_tool`: replace the call input. `post_tool`: replace the raw output. Both re-validate. */
+    mutate?: StageMutate;
+}
+export type StageMutate = {
+    input: unknown;
+} | {
+    output: unknown;
+};
+export type StageHandler = (ctx: StageContext) => StageResult | undefined | Promise<StageResult | undefined>;
+export type { StageApplyWarning, StageApplyWarningCode };
+export interface StageApplyInput {
+    stage: TurnStage;
+    result: unknown;
+    injectAllowed: boolean;
+    injectWouldExceedMaxSteps?: boolean;
+    /**
+     * False when the stage's mutate subject is absent at this fire (a `post_tool`
+     * whose body never completed, or a tool whose output the kernel must own).
+     * `mutate` is then a `mutate_invalid` warning, never a silent no-op.
+     */
+    mutable?: boolean;
+}
+export interface InjectUnit {
+    id?: string;
+    messages: TurnHistoryMessage[];
+}
+export interface StageApplyOutput {
+    inject?: InjectUnit;
+    abort?: boolean | {
+        reason?: string;
+    };
+    deny?: {
+        code: string;
+        message: string;
+    };
+    confirm?: {
+        summary?: string;
+    };
+    mutate?: StageMutate;
+    warnings: StageApplyWarning[];
+}
+/** True when the affordance is physically allowed at `stage` (ignores inject gate). */
+export declare function stageAllowsAffordance(stage: TurnStage, affordance: StageAffordance): boolean;
+export declare function isAwaitingUserInput(output: unknown): output is AwaitingUserInput;
+/** Never throws: invalid fields become warnings and are dropped. */
+export declare function applyStageResult(input: StageApplyInput): StageApplyOutput;
+export type StageEventExtra = {
+    callId?: string;
+    toolName?: string;
+    callNotStarted?: boolean;
+    awaiting?: boolean;
+    gate?: ToolGate;
+    stop?: TurnStop;
+    injected?: {
+        id: string;
+    }[];
+};
+/** Build a stream `stage` event. Unknown extra keys are not copied. */
+export declare function stageEventFields(stage: TurnStage, extra?: Partial<StageEventExtra>): TurnEventOf<'stage'>;
+export declare function injectMessages(units: readonly InjectUnit[]): TurnHistoryMessage[];
+/**
+ * The `stage` event recording that `units` landed, naming the ones the host
+ * named; `undefined` when none was named. Emit it where the messages land,
+ * never before: an inject that never lands is never reported.
+ */
+export declare function injectedStageEvent(stage: TurnStage, units: readonly InjectUnit[], extra?: Pick<StageEventExtra, 'callId' | 'toolName'>): TurnEventOf<'stage'> | undefined;
+export declare function injectWouldExceedMaxSteps(stepCount: number, maxSteps: number | undefined): boolean;
+export interface RunStageArgs extends StageCallBag {
+    stage: TurnStage;
+    step: number;
+    history: readonly TurnHistoryMessage[];
+    /**
+     * Handlers in call order. Later scalars win, `inject` lists concatenate. A
+     * tool-local `preTool` result rides here as the first handler.
+     */
+    handlers: readonly StageHandler[];
+    /** Profile guardrails — every inject site runs the untrusted sanitize path. */
+    guardrails: Profile['guardrails'];
+    injectAllowed: boolean;
+    injectWouldExceedMaxSteps?: boolean;
+    mutable?: boolean;
+    host?: unknown;
+    signal?: AbortSignal;
+    span?: SpanHandle;
+}
+/** Applied stage output: every handler's inject, in call order, sanitized. */
+export interface RunStageOutput extends Omit<StageApplyOutput, 'inject'> {
+    inject: InjectUnit[];
+}
+/** Stage events always emit, even with no handlers. */
+export declare function runStage(args: RunStageArgs): AsyncGenerator<TurnEvent, RunStageOutput>;

package/esm/src/kernel/stages.js

@@ -0,0 +1,388 @@
+import { throwIfAborted } from '../guardrails/error.js';
+import { guardrailFromHits } from '../guardrails/events.js';
+import { detectionForTrust, resolveGuardrailPolicy } from '../guardrails/policy.js';
+import { sanitizeHistory } from '../guardrails/sanitize.js';
+import { guardrailAttributes } from './engine/turn-trace.js';
+import { awaitingUserInputSchema, } from './turn-events.js';
+import { isRecord } from './util/record.js';
+export const STAGE_AFFORDANCES = ['inject', 'abort', 'deny', 'confirm', 'mutate'];
+/** Inject still needs the inject gate at apply time. Empty = observe only. */
+export const STAGE_AFFORDANCE_MATRIX = Object.freeze({
+    pre_turn: Object.freeze(['inject', 'abort']),
+    pre_tool: Object.freeze(['abort', 'deny', 'confirm', 'mutate']),
+    post_tool: Object.freeze(['inject', 'abort', 'deny', 'mutate']),
+    before_end: Object.freeze(['inject', 'abort']),
+    post_turn: Object.freeze([]),
+});
+const STAGE_RESULT_KEYS = new Set([...STAGE_AFFORDANCES, 'injectId']);
+/** True when the affordance is physically allowed at `stage` (ignores inject gate). */
+export function stageAllowsAffordance(stage, affordance) {
+    return STAGE_AFFORDANCE_MATRIX[stage].includes(affordance);
+}
+function warn(warnings, code, field, message) {
+    warnings.push({ code, field, message });
+}
+export function isAwaitingUserInput(output) {
+    return awaitingUserInputSchema.safeParse(output).success;
+}
+/** Drops unknown keys and rejects `role: 'tool'`; sanitizeHistory runs at the inject site. */
+function coerceInjectMessage(item, warnings) {
+    if (!isRecord(item)) {
+        warn(warnings, 'inject_invalid_messages', 'inject', 'inject entry must be an object'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return undefined;
+    }
+    if (item.role === 'tool') {
+        warn(warnings, 'inject_invalid_messages', 'inject', 'inject messages with role "tool" are rejected');
+        return undefined;
+    }
+    if (item.role !== 'user' && item.role !== 'assistant' && item.role !== 'system') {
+        warn(warnings, 'inject_invalid_messages', 'inject', `inject role not allowed: ${String(item.role)}`);
+        return undefined;
+    }
+    const msg = { role: item.role };
+    if (item.content !== undefined) {
+        if (typeof item.content !== 'string') {
+            warn(warnings, 'inject_invalid_messages', 'inject', 'inject content must be a string when present');
+            return undefined;
+        }
+        msg.content = item.content;
+    }
+    if (item.parts !== undefined) {
+        if (!Array.isArray(item.parts)) {
+            warn(warnings, 'inject_invalid_messages', 'inject', 'inject parts must be an array when present');
+            return undefined;
+        }
+        msg.parts = item.parts;
+    }
+    if (item.tool_calls !== undefined) {
+        if (!Array.isArray(item.tool_calls)) {
+            warn(warnings, 'inject_invalid_messages', 'inject', 'inject tool_calls must be an array when present');
+            return undefined;
+        }
+        msg.tool_calls = item.tool_calls;
+    }
+    if (item.name !== undefined) {
+        if (typeof item.name !== 'string') {
+            warn(warnings, 'inject_invalid_messages', 'inject', 'inject name must be a string'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            return undefined;
+        }
+        msg.name = item.name;
+    }
+    if (item.metadata !== undefined) {
+        if (!isRecord(item.metadata)) {
+            warn(warnings, 'inject_invalid_messages', 'inject', 'inject metadata must be a plain object'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            return undefined;
+        }
+        msg.metadata = { ...item.metadata };
+    }
+    if (item.tool_call_id !== undefined) {
+        warn(warnings, 'inject_invalid_messages', 'inject', 'inject tool_call_id is rejected (not a tool-role message)');
+    }
+    return msg;
+}
+function coerceHistoryMessages(raw, warnings) {
+    if (!Array.isArray(raw)) {
+        warn(warnings, 'inject_invalid_messages', 'inject', 'inject must be an array of history messages');
+        return undefined;
+    }
+    const out = [];
+    for (const item of raw) {
+        const msg = coerceInjectMessage(item, warnings);
+        if (msg)
+            out.push(msg);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/** The inject's messages under its id; an unusable id refuses the inject whole. */
+function injectUnit(result, warnings) {
+    const messages = coerceHistoryMessages(result.inject, warnings);
+    if (!messages)
+        return undefined;
+    if (result.injectId === undefined)
+        return { messages };
+    if (typeof result.injectId === 'string' && result.injectId.trim()) {
+        return { id: result.injectId, messages };
+    }
+    warn(warnings, 'inject_id_invalid', 'injectId', 'injectId must be a non-empty string; inject refused');
+    return undefined;
+}
+function applyInjectField(result, input, out) {
+    if (!('inject' in result) || result.inject === undefined) {
+        if (result.injectId !== undefined) {
+            warn(out.warnings, 'inject_id_invalid', 'injectId', 'injectId without inject ignored'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        return;
+    }
+    const { stage, injectAllowed, injectWouldExceedMaxSteps } = input;
+    if (!stageAllowsAffordance(stage, 'inject')) {
+        warn(out.warnings, 'affordance_not_allowed', 'inject', `inject is not allowed at stage ${stage}`);
+    }
+    else if (!injectAllowed) {
+        warn(out.warnings, 'inject_not_allowed', 'inject', 'inject gate is closed for this profile/session');
+    }
+    else if (injectWouldExceedMaxSteps) {
+        warn(out.warnings, 'inject_rejected_max_steps', 'inject', 'inject rejected: another model step would exceed maxSteps');
+    }
+    else {
+        const unit = injectUnit(result, out.warnings);
+        if (unit)
+            out.inject = unit;
+    }
+}
+function applyAbortField(result, stage, out) {
+    if (!('abort' in result) || result.abort === undefined)
+        return;
+    if (!stageAllowsAffordance(stage, 'abort')) {
+        warn(out.warnings, 'affordance_not_allowed', 'abort', 'abort is not allowed at post_turn'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    else if (result.abort === true) {
+        out.abort = true;
+    }
+    else if (isRecord(result.abort)) {
+        const reason = typeof result.abort.reason === 'string' && result.abort.reason.trim()
+            ? result.abort.reason.trim()
+            : undefined;
+        out.abort = reason ? { reason } : true;
+    }
+    else if (result.abort !== false) {
+        warn(out.warnings, 'abort_invalid', 'abort', 'abort must be boolean or { reason?: string }'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+function applyDenyField(result, stage, out) {
+    if (!('deny' in result) || result.deny === undefined)
+        return;
+    if (!stageAllowsAffordance(stage, 'deny')) {
+        warn(out.warnings, 'affordance_not_allowed', 'deny', `deny is not allowed at stage ${stage}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    else if (!isRecord(result.deny)) {
+        warn(out.warnings, 'deny_invalid', 'deny', 'deny must be an object'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    else {
+        const code = typeof result.deny.code === 'string' && result.deny.code.trim()
+            ? result.deny.code.trim()
+            : 'not_authorized';
+        const message = typeof result.deny.message === 'string' && result.deny.message.trim()
+            ? result.deny.message.trim()
+            : 'Tool execution not authorized'; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        out.deny = { code, message };
+    }
+}
+function applyConfirmField(result, stage, out) {
+    if (!('confirm' in result) || result.confirm === undefined)
+        return;
+    if (!stageAllowsAffordance(stage, 'confirm')) {
+        warn(out.warnings, 'affordance_not_allowed', 'confirm', `confirm is not allowed at stage ${stage}`);
+    }
+    else if (result.confirm === true) {
+        out.confirm = {};
+    }
+    else if (isRecord(result.confirm)) {
+        const summary = typeof result.confirm.summary === 'string' && result.confirm.summary.trim()
+            ? result.confirm.summary.trim()
+            : undefined;
+        out.confirm = summary ? { summary } : {};
+    }
+    else {
+        warn(out.warnings, 'confirm_invalid', 'confirm', 'confirm must be true or { summary?: string }');
+    }
+}
+const MUTATE_SUBJECT = { pre_tool: 'input', post_tool: 'output' };
+function mutateSubject(stage) {
+    return stage in MUTATE_SUBJECT ? MUTATE_SUBJECT[stage] : undefined;
+}
+function applyMutateField(result, input, out) {
+    const { stage } = input;
+    if (!('mutate' in result) || result.mutate === undefined)
+        return;
+    if (!stageAllowsAffordance(stage, 'mutate')) {
+        warn(out.warnings, 'affordance_not_allowed', 'mutate', `mutate is not allowed at stage ${stage}`);
+        return;
+    }
+    const subject = mutateSubject(stage);
+    if (!subject) {
+        // Matrix allows mutate but no subject is mapped: a kernel drift, surfaced not swallowed.
+        warn(out.warnings, 'mutate_invalid', 'mutate', 
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        `no mutate subject is defined at stage ${stage}`);
+        return;
+    }
+    if (!isRecord(result.mutate) || result.mutate[subject] === undefined) {
+        warn(out.warnings, 'mutate_invalid', 'mutate', 
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        `mutate must be { ${subject}: unknown } at stage ${stage}`);
+        return;
+    }
+    if (input.mutable === false) {
+        warn(out.warnings, 'mutate_invalid', 'mutate', 
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        `there is no ${subject} to replace at this ${stage} fire`);
+        return;
+    }
+    out.mutate =
+        subject === 'input' ? { input: result.mutate.input } : { output: result.mutate.output };
+}
+/** Never throws: invalid fields become warnings and are dropped. */
+export function applyStageResult(input) {
+    const warnings = [];
+    const out = { warnings };
+    const { stage, result } = input;
+    if (result == null)
+        return out;
+    if (!isRecord(result)) {
+        warn(warnings, 'result_invalid', 'result', 'StageResult must be a plain object'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return out;
+    }
+    for (const key of Object.keys(result)) {
+        if (!STAGE_RESULT_KEYS.has(key)) {
+            warn(warnings, 'unknown_field', key, `unknown StageResult field "${key}" ignored`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+    applyInjectField(result, input, out);
+    applyAbortField(result, stage, out);
+    applyDenyField(result, stage, out);
+    applyConfirmField(result, stage, out);
+    applyMutateField(result, input, out);
+    // confirm + deny together: deny wins
+    if (out.deny && out.confirm) {
+        warn(warnings, 'confirm_invalid', 'confirm', 'confirm ignored because deny is set'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        delete out.confirm;
+    }
+    return out;
+}
+/** Build a stream `stage` event. Unknown extra keys are not copied. */
+export function stageEventFields(stage, extra) {
+    const event = { type: 'stage', stage };
+    if (!extra)
+        return event;
+    if (extra.callId !== undefined)
+        event.callId = extra.callId;
+    if (extra.toolName !== undefined)
+        event.toolName = extra.toolName;
+    if (extra.callNotStarted !== undefined)
+        event.callNotStarted = extra.callNotStarted;
+    if (extra.awaiting !== undefined)
+        event.awaiting = extra.awaiting;
+    if (extra.gate !== undefined)
+        event.gate = extra.gate;
+    if (extra.stop !== undefined)
+        event.stop = extra.stop;
+    if (extra.injected !== undefined)
+        event.injected = extra.injected;
+    return event;
+}
+export function injectMessages(units) {
+    return units.flatMap((unit) => unit.messages);
+}
+/**
+ * The `stage` event recording that `units` landed, naming the ones the host
+ * named; `undefined` when none was named. Emit it where the messages land,
+ * never before: an inject that never lands is never reported.
+ */
+export function injectedStageEvent(stage, units, extra) {
+    const injected = units.flatMap((unit) => (unit.id === undefined ? [] : [{ id: unit.id }]));
+    if (injected.length === 0)
+        return undefined;
+    return stageEventFields(stage, { ...extra, injected });
+}
+export function injectWouldExceedMaxSteps(stepCount, maxSteps) {
+    if (maxSteps === undefined || maxSteps <= 0)
+        return false;
+    return stepCount >= maxSteps;
+}
+function appliedAffordance(applied, key) {
+    return key === 'inject' ? applied.inject.length > 0 : Boolean(applied[key]);
+}
+/**
+ * Merge per-handler applied outputs in call order. Later scalars win, `inject`
+ * lists concatenate, warnings accumulate. `deny` beats `confirm` across handlers
+ * exactly as it does within one return.
+ */
+function mergeApplied(parts) {
+    const out = { warnings: parts.flatMap((part) => part.warnings), inject: [] };
+    for (const part of parts) {
+        if (part.abort !== undefined)
+            out.abort = part.abort;
+        if (part.deny)
+            out.deny = part.deny;
+        if (part.confirm)
+            out.confirm = part.confirm;
+        if (part.mutate)
+            out.mutate = part.mutate;
+        if (part.inject)
+            out.inject.push(part.inject);
+    }
+    if (out.deny && out.confirm) {
+        warn(out.warnings, 'confirm_invalid', 'confirm', 'confirm ignored because deny is set'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        delete out.confirm;
+    }
+    return out;
+}
+/**
+ * Await each handler in order and apply its return on its own, so one handler's
+ * junk is that handler's warning and cannot erase another's affordance. Each
+ * handler gets its own shallow context; abort wins over any handler error.
+ */
+async function applyHandlers(handlers, ctx, apply, signal) {
+    const parts = [];
+    for (const handler of handlers) {
+        let raw;
+        try {
+            raw = await handler({ ...ctx });
+        }
+        catch (err) {
+            throwIfAborted(signal);
+            throw err;
+        }
+        throwIfAborted(signal);
+        parts.push(applyStageResult({ ...apply, result: raw }));
+    }
+    return parts;
+}
+/** Stage events always emit, even with no handlers. */
+export async function* runStage(args) {
+    const { stage, step, history, handlers, guardrails, injectAllowed, injectWouldExceedMaxSteps, mutable, host, signal, span, ...bag } = args;
+    throwIfAborted(signal);
+    // Stream stage events stay lean (no outputRaw/failure). Hosts read those on
+    // StageContext via onStage; tool failures also ride tool events.
+    yield stageEventFields(stage, {
+        callId: bag.callId,
+        toolName: bag.tool,
+        callNotStarted: bag.callNotStarted,
+        awaiting: bag.awaiting,
+        gate: bag.gate,
+        stop: bag.stop,
+    });
+    if (handlers.length === 0) {
+        span?.event('theorem.stage', { stage, affordance: [] });
+        return { warnings: [], inject: [] };
+    }
+    const ctx = { stage, step, history, host, ...bag };
+    const startedMs = span?.msSinceStart();
+    const applied = mergeApplied(await applyHandlers(handlers, ctx, { stage, injectAllowed, injectWouldExceedMaxSteps, mutable }, signal));
+    span?.event('theorem.stage', {
+        stage,
+        ...(startedMs === undefined ? {} : { hook_ms: span.msSinceStart() - startedMs }),
+        affordance: STAGE_AFFORDANCES.filter((key) => appliedAffordance(applied, key)),
+        ...(applied.warnings.length > 0 ? { warnings: applied.warnings.map((w) => w.code) } : {}),
+    });
+    if (applied.warnings.length > 0) {
+        yield {
+            ...stageEventFields(stage, { callId: bag.callId, toolName: bag.tool }),
+            stageWarnings: applied.warnings,
+        };
+    }
+    if (applied.inject.length === 0)
+        return applied;
+    const hits = [];
+    const detection = detectionForTrust(resolveGuardrailPolicy(guardrails), 'untrusted');
+    const sanitized = applied.inject.map((unit) => ({
+        ...unit,
+        messages: sanitizeHistory(unit.messages, detection, hits),
+    }));
+    const redacted = guardrailFromHits('history', 'untrusted', hits, 'redact');
+    if (redacted?.guardrail)
+        span?.event('theorem.guardrail', guardrailAttributes(redacted.guardrail));
+    if (redacted)
+        yield redacted;
+    return { ...applied, inject: sanitized };
+}

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

@@ -0,0 +1,93 @@
+import { type ContinueStopKind, type ProfileType } from './schema.js';
+import type { TurnStop } from './turn-events.js';
+export type { TurnStop };
+/**
+ * Profile types whose continue turn sends the continue instruction. Image and
+ * speech continue by re-sending the host's request unchanged.
+ */
+export declare const CONTINUE_INSTRUCTION_TYPES: readonly ProfileType[];
+export declare const DEFAULT_ALLOW_CONTINUE: readonly ContinueStopKind[];
+/** Hosts wait briefly, then continue once on their own. */
+export declare const DEFAULT_AUTO_CONTINUE: readonly ContinueStopKind[];
+/** Pause before the one-shot auto-continue so a flaky tunnel can settle. */
+export declare const AUTO_CONTINUE_DELAY_MS = 1500;
+export interface ProfileTurnResumptionSpec {
+    /**
+     * The host's UI policy for offering Continue: the kernel does not refuse a `continueFrom`
+     * outside it, since a continue is one more turn the host could send as plain text anyway.
+     * Omit → length / stream_incomplete / provider_error; `[]` = none.
+     */
+    allowContinue?: ContinueStopKind[];
+    /**
+     * Omit → length / stream_incomplete; `[]` = none. The kernel does not loop: the host
+     * sends the `continueFrom` turn with `continuation`.
+     */
+    autoContinue?: ContinueStopKind[];
+    /** Compared against `TurnRequest.continuation`. Omit → no count cap. */
+    maxContinues?: number;
+}
+export declare function isContinueStopKind(kind: string): kind is ContinueStopKind;
+/**
+ * `allowSteering` is text / live only; image and speech omit it. Stop is not a profile knob:
+ * interfaces always project `canStop: true` because `TurnRequest.signal` is always wired.
+ */
+export interface ProfileTurnBehaviourSpec {
+    resumption?: ProfileTurnResumptionSpec;
+    /** Default true on text / live. Gates injects only; stage events still emit. */
+    allowSteering?: boolean;
+}
+/**
+ * Image / speech turn behaviour: resumption only. A continue re-sends the
+ * host's request unchanged, so there is no continue instruction, and there is
+ * no mid-turn inject to steer.
+ */
+export interface MediaTurnBehaviourSpec {
+    resumption?: ProfileTurnResumptionSpec;
+}
+/**
+ * The stop a continue turn resumes. The partial reply is not carried here: a
+ * text continue reads it as the last assistant message in `input.history`, and
+ * an image or speech continue re-sends the original request.
+ */
+export interface TurnContinueFrom {
+    stop: TurnStop;
+}
+export declare function isResumeableStop(stop: TurnStop | undefined, allowContinue?: readonly ContinueStopKind[]): boolean;
+export declare function stageAbortStop(abort: true | {
+    reason?: string;
+}): TurnStop & {
+    kind: 'cancelled';
+};
+export declare function isUserCancelledStop(stop: TurnStop | undefined): boolean;
+/** `policy` is the profile's `profileTurnResumption(profile)`. */
+export declare function shouldAutoContinue(stop: TurnStop | undefined, policy?: Pick<ProfileTurnResumptionSpec, 'allowContinue' | 'autoContinue'>): boolean;
+export declare function profileTurnResumption(profile: {
+    type: string;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
+}): ProfileTurnResumptionSpec | undefined;
+/** Text-only, for the interface `allowSteering` projection; `profileAllowsInject` adds live. */
+export declare function profileAllowsSteering(profile: {
+    type: string;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
+}): boolean;
+/** Gates injects only, never stage emission. */
+export declare function profileAllowsInject(profile: {
+    type: string;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
+}): boolean;
+/** OpenAI-compatible normalized `finish_reason` (+ optional `native_finish_reason`). */
+export declare function turnStopFromOpenAiFinishReason(finishReason: string | null | undefined, nativeFinishReason?: string | null): TurnStop;
+/** Gemini Interactions terminal `status`. */
+export declare function turnStopFromInteractionStatus(status: string | null | undefined): TurnStop;
+/** `null` when `sawTerminal`, so the host keeps the provider's stop. */
+export declare function turnStopFromClientStreamEnd(opts: {
+    abortedByUser: boolean;
+    sawTerminal: boolean;
+    hadPartial?: boolean;
+}): TurnStop | null;
+export declare class GenerationStopError extends Error {
+    readonly name = "GenerationStopError";
+    readonly stop: TurnStop;
+    constructor(stop: TurnStop, message?: string);
+}
+export declare function isGenerationStopError(err: unknown): err is GenerationStopError;