@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,29 @@
+import type { TraceSink } from '../observability/trace-sink.js';
+import { type RunDecisionOptions } from './engine/decision.js';
+import { type RunEmbeddingOptions } from './engine/embedding.js';
+import { type RunSessionOptions } from './engine/session/mod.js';
+import type { ProviderHostOptions } from './protocols/runtime.js';
+import { type KernelRegistry } from './registry/kernel-registry.js';
+import { resolveTurnInRegistry } from './registry/resolve.js';
+import { type ToolCallResult, type ToolStepCallResult } from './tools/run.js';
+import type { InvokeToolRequest, InvokeToolStepRequest } from './tools/types.js';
+import type { CompactHistoryRequest, CompactionResult, DecisionRequest, DecisionResult, EmbeddingRequest, EmbeddingResult, LiveSession, ProjectedProfile, SessionRequest, TurnEvent, TurnRequest } from './types.js';
+/** A kernel scope: its registries and the operations that run against them (turns, live sessions, history compaction, tool invocation, turn resolution, profile projection, and decisions). */
+interface KernelScope extends KernelRegistry {
+    runTurn(req: TurnRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+    runSession(req: SessionRequest, options: RunSessionOptions, sinkOverride?: TraceSink): Promise<LiveSession>;
+    compactHistory(req: CompactHistoryRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
+    invokeTool(request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+    invokeToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+    runTool(request: InvokeToolRequest, sinkOverride?: TraceSink): Promise<ToolCallResult>;
+    runToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<ToolStepCallResult>;
+    resolveTurn(req: TurnRequest): ReturnType<typeof resolveTurnInRegistry>;
+    projectProfile(id: string): ProjectedProfile;
+    runDecision(request: DecisionRequest, options: RunDecisionOptions): Promise<DecisionResult>;
+    runEmbedding(request: EmbeddingRequest, options?: RunEmbeddingOptions): Promise<EmbeddingResult>;
+}
+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,45 @@
+import { runDecisionInRegistry } from './engine/decision.js';
+import { runEmbeddingInRegistry } from './engine/embedding.js';
+import { compactHistoryInRegistry, runTurnInRegistry } from './engine/runner/mod.js';
+import { runSessionInRegistry } from './engine/session/mod.js';
+import { resolveRegisteredTurnModel } from './provider-dispatch.js';
+import { createKernelRegistry } from './registry/kernel-registry.js';
+import { projectProfileInRegistry, resolveTurnInRegistry } from './registry/resolve.js';
+import { invokeTool, invokeToolStep, startInvoke, startInvokeStep } from './tools/invoke.js';
+import { settledCall, settledCalls, } from './tools/run.js';
+/** Isolated from every other scope: a host that registers per request gives each its own. */
+function selectedTurnProvider(registry, req, options) {
+    try {
+        return resolveRegisteredTurnModel(registry, req.profile, req.model, options, req);
+    }
+    catch (error) {
+        return {
+            complete() {
+                throw error;
+            },
+        };
+    }
+}
+function createKernelScope() {
+    const registry = createKernelRegistry();
+    return {
+        providers: registry.providers,
+        tools: registry.tools,
+        profiles: registry.profiles,
+        schemas: registry.schemas,
+        runTurn: (req, options = {}, sinkOverride) => runTurnInRegistry(registry, req, selectedTurnProvider(registry, req, options), sinkOverride),
+        runSession: (req, options, sinkOverride) => runSessionInRegistry(registry, req, options, sinkOverride),
+        compactHistory: (req, options = {}, sinkOverride) => compactHistoryInRegistry(registry, req, resolveRegisteredTurnModel(registry, req.profile, req.model, options), sinkOverride),
+        invokeTool: (request, sinkOverride) => invokeTool(registry, request, sinkOverride),
+        invokeToolStep: (request, sinkOverride) => invokeToolStep(registry, request, sinkOverride),
+        runTool: (request, sinkOverride) => settledCall(startInvoke(registry, request, sinkOverride)),
+        runToolStep: (request, sinkOverride) => settledCalls(startInvokeStep(registry, request, sinkOverride)),
+        resolveTurn: (req) => resolveTurnInRegistry(registry, req),
+        projectProfile: (id) => projectProfileInRegistry(registry, id),
+        runDecision: (request, options) => runDecisionInRegistry(registry, request, options),
+        runEmbedding: (request, options = {}) => runEmbeddingInRegistry(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,176 @@
+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, StageApplyWarning, TurnEventOf } from './turn-events.js';
+import type { Profile, TurnEvent, TurnHistoryMessage } from './types.js';
+export type { AwaitingUserInput, ToolGate };
+/**
+ * What a stage handler can ask for: inject messages, abort, deny a tool call, ask for
+ * confirmation, mutate it, label it failed, or have it wait for other calls in its step.
+ */
+export declare const STAGE_AFFORDANCES: readonly ["inject", "abort", "deny", "confirm", "mutate", "labelFailed", "waitFor"];
+/** One of {@linkcode STAGE_AFFORDANCES}. */
+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[]>>;
+/** A call the model made in this step, as the host was shown it. */
+export interface StepCall {
+    callId: string;
+    tool: string;
+    input: unknown;
+}
+export type StageCallBag = {
+    callId?: string;
+    tool?: string;
+    input?: unknown;
+    /** `pre_tool` in a turn's step: every call the model made in the step, in the order it made them. */
+    stepCalls?: readonly StepCall[];
+    callNotStarted?: boolean;
+    outputRaw?: unknown;
+    outputModel?: ModelToolResult;
+    /** `post_tool`: the tool's past activity label, filled from the input and `outputRaw`. */
+    activityPast?: string;
+    /** `post_tool`: the tool's failed activity label, filled from the input. */
+    activityFailed?: string;
+    failure?: ToolFailure;
+    awaiting?: boolean;
+    stop?: TurnStop;
+    gate?: ToolGate;
+};
+/** What a stage handler is given: the stage, the step, and what has happened so far. */
+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;
+}
+/** What a stage handler returns: what it asks the turn to do. */
+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;
+    /**
+     * `post_tool` only: the call completed, but show its failed label (`activityFailed`) on the
+     * terminal `tool` event. The result and the phase stay as they are.
+     */
+    labelFailed?: true;
+    /**
+     * `pre_tool` only: the call ids in `stepCalls` whose calls must settle before this call's body
+     * starts. A call held for confirmation is held at once and does not wait.
+     */
+    waitFor?: string[];
+}
+/** A rewrite of a tool call's input or output. */
+export type StageMutate = {
+    input: unknown;
+} | {
+    output: unknown;
+};
+/** A host function the turn calls at each stage. */
+export type StageHandler = (ctx: StageContext) => StageResult | undefined | Promise<StageResult | undefined>;
+export type { StageApplyWarning, StageApplyWarningCode };
+/** A stage handler's result and the stage it came from, to be applied. */
+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[];
+}
+/** A stage handler's result after validation: the parts the turn will act on. */
+export interface StageApplyOutput {
+    inject?: InjectUnit;
+    abort?: boolean | {
+        reason?: string;
+    };
+    deny?: {
+        code: string;
+        message: string;
+    };
+    confirm?: {
+        summary?: string;
+    };
+    mutate?: StageMutate;
+    labelFailed?: true;
+    waitFor?: string[];
+    warnings: StageApplyWarning[];
+}
+/** True when the affordance is physically allowed at `stage` (ignores inject gate). */
+export declare function stageAllowsAffordance(stage: TurnStage, affordance: StageAffordance): boolean;
+/** Never throws: invalid fields become warnings and are dropped. */
+export declare function applyStageResult(input: StageApplyInput): StageApplyOutput;
+/** What a `stage` event records beside the stage: the tool call, its gate, and any injected messages. */
+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,431 @@
+import { boundaryReader, detectEvent } from '../guardrails/detect-at.js';
+import { throwIfAborted } from '../guardrails/error.js';
+import { guardrailTurnEvent } from '../guardrails/events.js';
+import { resolveGuardrailPolicy } from '../guardrails/policy.js';
+import { requestRefused, sanitizeHistory } from '../guardrails/sanitize.js';
+import { guardrailAttributes } from './engine/turn-trace.js';
+import { isRecord } from './util/record.js';
+/**
+ * What a stage handler can ask for: inject messages, abort, deny a tool call, ask for
+ * confirmation, mutate it, label it failed, or have it wait for other calls in its step.
+ */
+export const STAGE_AFFORDANCES = [
+    'inject',
+    'abort',
+    'deny',
+    'confirm',
+    'mutate',
+    'labelFailed',
+    'waitFor',
+];
+/** 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', 'waitFor']),
+    post_tool: Object.freeze(['inject', 'abort', 'deny', 'mutate', 'labelFailed']),
+    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 });
+}
+/** 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'); // labels-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'); // labels-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'); // labels-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'); // labels-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'); // labels-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 }'); // labels-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}`); // labels-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'); // labels-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'; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        out.deny = { code, message };
+    }
+}
+function applyLabelFailedField(result, stage, out) {
+    if (!('labelFailed' in result) || result.labelFailed === undefined)
+        return;
+    if (!stageAllowsAffordance(stage, 'labelFailed')) {
+        warn(out.warnings, 'affordance_not_allowed', 'labelFailed', `labelFailed is not allowed at stage ${stage}`);
+    }
+    else if (result.labelFailed === true) {
+        out.labelFailed = true;
+    }
+    else if (result.labelFailed !== false) {
+        warn(out.warnings, 'label_failed_invalid', 'labelFailed', 'labelFailed must be true'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+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 }');
+    }
+}
+function applyWaitForField(result, stage, out) {
+    if (!('waitFor' in result) || result.waitFor === undefined)
+        return;
+    if (!stageAllowsAffordance(stage, 'waitFor')) {
+        warn(out.warnings, 'affordance_not_allowed', 'waitFor', `waitFor is not allowed at stage ${stage}`);
+    }
+    else if (!Array.isArray(result.waitFor) ||
+        !result.waitFor.every((id) => typeof id === 'string' && id.trim() !== '')) {
+        warn(out.warnings, 'wait_for_invalid', 'waitFor', 'waitFor must be an array of call ids');
+    }
+    else if (result.waitFor.length > 0) {
+        out.waitFor = [...new Set(result.waitFor)];
+    }
+}
+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) {
+        // why: Matrix allows mutate but no subject is mapped: a kernel drift, surfaced not swallowed.
+        warn(out.warnings, 'mutate_invalid', 'mutate', 
+        // labels-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', 
+        // labels-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', 
+        // labels-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'); // labels-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`); // labels-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);
+    applyLabelFailedField(result, stage, out);
+    applyWaitForField(result, stage, out);
+    if (out.deny && out.confirm) {
+        warn(warnings, 'confirm_invalid', 'confirm', 'confirm ignored because deny is set'); // labels-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, `waitFor` ids join, 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.labelFailed)
+            out.labelFailed = true;
+        if (part.waitFor)
+            out.waitFor = [...new Set([...(out.waitFor ?? []), ...part.waitFor])];
+        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'); // labels-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);
+    // why: 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 reader = boundaryReader('injected', resolveGuardrailPolicy(guardrails).detect);
+    const sanitized = applied.inject.map((unit) => ({
+        ...unit,
+        messages: sanitizeHistory(unit.messages, reader),
+    }));
+    const found = reader.found();
+    const event = detectEvent('injected', found);
+    if (event) {
+        span?.event('theorem.guardrail', guardrailAttributes(event));
+        yield guardrailTurnEvent(event);
+    }
+    if (found.action === 'block')
+        throw requestRefused('injected');
+    return { ...applied, inject: sanitized };
+}