@theoremjs/agents 0.3.0 → 0.3.1

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

@@ -1,20 +1,27 @@
 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 { InvokeToolRequest } from './tools/types.js';
-import type { CompactHistoryRequest, CompactionResult, DecisionRequest, DecisionResult, LiveSession, ModelProvider, ProjectedProfile, SessionRequest, TurnEvent, TurnRequest } from './types.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, provider: ModelProvider, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+    runTurn(req: TurnRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
     runSession(req: SessionRequest, options: RunSessionOptions, sinkOverride?: TraceSink): Promise<LiveSession>;
-    compactHistory(req: CompactHistoryRequest, provider: ModelProvider, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
+    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>;
 }
-/** 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;

package/esm/src/kernel/scope.js

@@ -1,23 +1,43 @@
 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 } from './tools/invoke.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, provider, sinkOverride) => runTurnInRegistry(registry, req, provider, sinkOverride),
+        runTurn: (req, options = {}, sinkOverride) => runTurnInRegistry(registry, req, selectedTurnProvider(registry, req, options), sinkOverride),
         runSession: (req, options, sinkOverride) => runSessionInRegistry(registry, req, options, sinkOverride),
-        compactHistory: (req, provider, sinkOverride) => compactHistoryInRegistry(registry, req, provider, 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. */

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

@@ -2,25 +2,43 @@ 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 { AwaitingUserInput, StageApplyWarning, 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"];
+/**
+ * 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). */
@@ -29,6 +47,7 @@ export interface StageContext extends StageCallBag {
     /** 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[];
     /**
@@ -50,14 +69,27 @@ export interface StageResult {
     };
     /** `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;
@@ -74,6 +106,7 @@ 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 | {
@@ -87,13 +120,15 @@ export interface StageApplyOutput {
         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;
-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;
+/** What a `stage` event records beside the stage: the tool call, its gate, and any injected messages. */
 export type StageEventExtra = {
     callId?: string;
     toolName?: string;

package/esm/src/kernel/stages.js

@@ -1,16 +1,28 @@
+import { boundaryReader, detectEvent } from '../guardrails/detect-at.js';
 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 { 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 { awaitingUserInputSchema, } from './turn-events.js';
 import { isRecord } from './util/record.js';
-export const STAGE_AFFORDANCES = ['inject', 'abort', 'deny', 'confirm', 'mutate'];
+/**
+ * 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']),
-    post_tool: Object.freeze(['inject', 'abort', 'deny', 'mutate']),
+    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([]),
 });
@@ -22,13 +34,10 @@ export function stageAllowsAffordance(stage, 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)
+        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') {
@@ -63,14 +72,14 @@ function coerceInjectMessage(item, warnings) {
     }
     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)
+            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'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            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 };
@@ -109,7 +118,7 @@ function injectUnit(result, warnings) {
 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)
+            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;
     }
@@ -133,7 +142,7 @@ 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)
+        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;
@@ -145,17 +154,17 @@ function applyAbortField(result, stage, out) {
         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)
+        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}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        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'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        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()
@@ -163,10 +172,23 @@ function applyDenyField(result, stage, out) {
             : '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)
+            : '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;
@@ -186,6 +208,20 @@ function applyConfirmField(result, stage, out) {
         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;
@@ -200,21 +236,21 @@ function applyMutateField(result, input, out) {
     }
     const subject = mutateSubject(stage);
     if (!subject) {
-        // Matrix allows mutate but no subject is mapped: a kernel drift, surfaced not swallowed.
+        // why: 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)
+        // 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', 
-        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        // 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', 
-        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         `there is no ${subject} to replace at this ${stage} fire`);
         return;
     }
@@ -229,12 +265,12 @@ export function applyStageResult(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)
+        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`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            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);
@@ -242,9 +278,10 @@ export function applyStageResult(input) {
     applyDenyField(result, stage, out);
     applyConfirmField(result, stage, out);
     applyMutateField(result, input, out);
-    // confirm + deny together: deny wins
+    applyLabelFailedField(result, stage, out);
+    applyWaitForField(result, stage, out);
     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)
+        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;
@@ -294,8 +331,8 @@ function appliedAffordance(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.
+ * 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: [] };
@@ -308,11 +345,15 @@ function mergeApplied(parts) {
             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'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        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;
@@ -342,7 +383,7 @@ async function applyHandlers(handlers, ctx, apply, signal) {
 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
+    // 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,
@@ -373,16 +414,18 @@ export async function* runStage(args) {
     }
     if (applied.inject.length === 0)
         return applied;
-    const hits = [];
-    const detection = detectionForTrust(resolveGuardrailPolicy(guardrails), 'untrusted');
+    const reader = boundaryReader('injected', resolveGuardrailPolicy(guardrails).detect);
     const sanitized = applied.inject.map((unit) => ({
         ...unit,
-        messages: sanitizeHistory(unit.messages, detection, hits),
+        messages: sanitizeHistory(unit.messages, reader),
     }));
-    const redacted = guardrailFromHits('history', 'untrusted', hits, 'redact');
-    if (redacted?.guardrail)
-        span?.event('theorem.guardrail', guardrailAttributes(redacted.guardrail));
-    if (redacted)
-        yield redacted;
+    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 };
 }

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

@@ -1,4 +1,4 @@
-import { type ContinueStopKind, type ProfileType } from './schema.js';
+import { type ContinueStopKind, type ProfileType, type StepLimitMode } from './schema.js';
 import type { TurnStop } from './turn-events.js';
 export type { TurnStop };
 /**
@@ -6,11 +6,13 @@ export type { TurnStop };
  * speech continue by re-sending the host's request unchanged.
  */
 export declare const CONTINUE_INSTRUCTION_TYPES: readonly ProfileType[];
+/** The stop kinds that offer Continue when a profile names none. */
 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. */
+/** Pause before an auto-continue, the host's or the turn's own, so a flaky tunnel can settle. */
 export declare const AUTO_CONTINUE_DELAY_MS = 1500;
+/** Which stops a profile offers Continue for, and which the host continues on its own. */
 export interface ProfileTurnResumptionSpec {
     /**
      * The host's UI policy for offering Continue: the kernel does not refuse a `continueFrom`
@@ -19,13 +21,22 @@ export interface ProfileTurnResumptionSpec {
      */
     allowContinue?: ContinueStopKind[];
     /**
-     * Omit → length / stream_incomplete; `[]` = none. The kernel does not loop: the host
-     * sends the `continueFrom` turn with `continuation`.
+     * Omit → length / stream_incomplete; `[]` = none. Apart from `allowContinue`: a stop can be
+     * continued without Continue being offered for it. The host sends the `continueFrom` turn
+     * with `continuation`. A text turn also sends a failed model call (`provider_error`,
+     * `stream_incomplete`) again itself when this list is set and names that stop, and the
+     * call gave no reply and no tool call: the turn keeps its history, its step count and
+     * what it has read. A failure the same call would meet again (the provider refused the
+     * request) is not sent again. Omitted, a turn sends nothing again.
      */
     autoContinue?: ContinueStopKind[];
-    /** Compared against `TurnRequest.continuation`. Omit → no count cap. */
+    /**
+     * Compared against `TurnRequest.continuation`; omit → no count cap. Also how many model
+     * calls one text turn sends again itself; omit → one.
+     */
     maxContinues?: number;
 }
+/** True when the stop kind can be continued. */
 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:
@@ -35,6 +46,11 @@ export interface ProfileTurnBehaviourSpec {
     resumption?: ProfileTurnResumptionSpec;
     /** Default true on text / live. Gates injects only; stage events still emit. */
     allowSteering?: boolean;
+    /**
+     * Text only. What the last model call under `maxSteps` may do. Omit = `'stop'`: it may call
+     * tools, and if it does the turn stops as `step_limit`. `'answer'` sends it without tools.
+     */
+    atStepLimit?: StepLimitMode;
 }
 /**
  * Image / speech turn behaviour: resumption only. A continue re-sends the
@@ -52,15 +68,20 @@ export interface MediaTurnBehaviourSpec {
 export interface TurnContinueFrom {
     stop: TurnStop;
 }
+/** True when the stop can be continued under the allowed kinds. */
 export declare function isResumeableStop(stop: TurnStop | undefined, allowContinue?: readonly ContinueStopKind[]): boolean;
+/** True for a stop where the model call failed; the rest either finished or were stopped on purpose. */
+export declare function isFailedStopKind(kind: TurnStop['kind']): boolean;
 export declare function stageAbortStop(abort: true | {
     reason?: string;
 }): TurnStop & {
     kind: 'cancelled';
 };
+/** True when the user cancelled the turn. */
 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 shouldAutoContinue(stop: TurnStop | undefined, policy?: Pick<ProfileTurnResumptionSpec, 'autoContinue'>): boolean;
+/** The profile's resumption policy, or `undefined` for a live profile. */
 export declare function profileTurnResumption(profile: {
     type: string;
     turnBehaviour?: ProfileTurnBehaviourSpec;
@@ -85,9 +106,11 @@ export declare function turnStopFromClientStreamEnd(opts: {
     sawTerminal: boolean;
     hadPartial?: boolean;
 }): TurnStop | null;
+/** Thrown when a model call stops before it finishes, carrying the stop. */
 export declare class GenerationStopError extends Error {
     readonly name = "GenerationStopError";
     readonly stop: TurnStop;
     constructor(stop: TurnStop, message?: string);
 }
+/** True when the error is a `GenerationStopError`. */
 export declare function isGenerationStopError(err: unknown): err is GenerationStopError;

package/esm/src/kernel/stop.js

@@ -1,19 +1,22 @@
-import { CONTINUE_STOP_KINDS } from './schema.js';
+import { CONTINUE_STOP_KINDS, } from './schema.js';
 /**
  * Profile types whose continue turn sends the continue instruction. Image and
  * speech continue by re-sending the host's request unchanged.
  */
 export const CONTINUE_INSTRUCTION_TYPES = ['text'];
+/** The stop kinds that offer Continue when a profile names none. */
 export const DEFAULT_ALLOW_CONTINUE = CONTINUE_STOP_KINDS;
 /** Hosts wait briefly, then continue once on their own. */
 export const DEFAULT_AUTO_CONTINUE = ['length', 'stream_incomplete'];
-/** Pause before the one-shot auto-continue so a flaky tunnel can settle. */
+/** Pause before an auto-continue, the host's or the turn's own, so a flaky tunnel can settle. */
 export const AUTO_CONTINUE_DELAY_MS = 1_500;
 const CONTINUE_KIND_SET = new Set(CONTINUE_STOP_KINDS);
+/** True when the stop kind can be continued. */
 export function isContinueStopKind(kind) {
     return CONTINUE_KIND_SET.has(kind);
 }
 const RESUMEABLE_DEFAULT = new Set(DEFAULT_ALLOW_CONTINUE);
+/** True when the stop can be continued under the allowed kinds. */
 export function isResumeableStop(stop, allowContinue) {
     if (!stop)
         return false;
@@ -22,11 +25,17 @@ export function isResumeableStop(stop, allowContinue) {
     const allow = allowContinue ? new Set(allowContinue) : RESUMEABLE_DEFAULT;
     return allow.has(stop.kind);
 }
+const FAILED_STOP_KINDS = new Set(['provider_error', 'stream_incomplete']);
+/** True for a stop where the model call failed; the rest either finished or were stopped on purpose. */
+export function isFailedStopKind(kind) {
+    return FAILED_STOP_KINDS.has(kind);
+}
 export function stageAbortStop(abort) {
     return typeof abort === 'object' && abort.reason
         ? { kind: 'cancelled', native: abort.reason }
         : { kind: 'cancelled' };
 }
+/** True when the user cancelled the turn. */
 export function isUserCancelledStop(stop) {
     return stop?.kind === 'cancelled';
 }
@@ -34,9 +43,10 @@ export function isUserCancelledStop(stop) {
 export function shouldAutoContinue(stop, policy) {
     if (!stop || !isContinueStopKind(stop.kind))
         return false;
-    const auto = policy?.autoContinue ?? DEFAULT_AUTO_CONTINUE;
-    return auto.includes(stop.kind) && isResumeableStop(stop, policy?.allowContinue);
+    // why: Offering Continue (`allowContinue`) is the host's own choice, apart from this one.
+    return (policy?.autoContinue ?? DEFAULT_AUTO_CONTINUE).includes(stop.kind);
 }
+/** The profile's resumption policy, or `undefined` for a live profile. */
 export function profileTurnResumption(profile) {
     if (profile.type === 'live')
         return undefined;
@@ -112,6 +122,7 @@ export function turnStopFromClientStreamEnd(opts) {
         return { kind: 'cancelled' };
     return { kind: 'stream_incomplete' };
 }
+/** Thrown when a model call stops before it finishes, carrying the stop. */
 export class GenerationStopError extends Error {
     name = 'GenerationStopError';
     stop;
@@ -120,6 +131,7 @@ export class GenerationStopError extends Error {
         this.stop = stop;
     }
 }
+/** True when the error is a `GenerationStopError`. */
 export function isGenerationStopError(err) {
     return err instanceof GenerationStopError;
 }