theorum 1.0.0 → 1.1.3

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

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import type { TurnStopKind } from './schema.js';
+import { type ContinueStopKind, type TurnStopKind } from './schema.js';
 /** Normalized stop attached to terminal `done` events and host continue requests. */
 export interface TurnStop {
     kind: TurnStopKind;
@@ -14,35 +14,65 @@ export interface TurnStop {
     native?: string;
 }
 /**
- * Fixed continue instruction for resumeable stops.
- * Hosts should not invent per-app continue prompts.
+ * Default continue instruction for resumeable stops — the registered lexicon
+ * default (`continue.instruction`). It rarely needs replacing, but hosts may
+ * override it per profile via `turnBehaviour.resumption.continueInstruction`
+ * or process-wide via `overrideLexicon`.
  */
-export declare const CONTINUE_INSTRUCTION = "Continue and finish the incomplete output from the previous turn. Do not restart from scratch; preserve what was already generated and complete it.";
+export declare const CONTINUE_INSTRUCTION: string;
+/** Default kinds hosts may offer Continue for (= full ContinueStopKind set). */
+export declare const DEFAULT_ALLOW_CONTINUE: readonly ContinueStopKind[];
 /**
  * Default kinds for one silent auto-continue (hosts wait briefly, then resume once).
- * User `cancelled` is never included.
+ * Never includes kinds outside ContinueStopKind (e.g. cancelled / tool / gate / completed).
  */
-export declare const DEFAULT_AUTO_CONTINUE: readonly TurnStopKind[];
+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;
-/** Profile turn-continuation policy under top-level `turnResumption`. */
+/** Profile turn-continuation policy under `turnBehaviour.resumption`. */
 export interface ProfileTurnResumptionSpec {
     /**
      * Kinds eligible for a Continue / continueFrom turn.
      * When omitted, length / stream_incomplete / provider_error are eligible.
+     * Only `ContinueStopKind` values are valid — not tool / cancelled / completed / …
      */
-    allowContinue?: TurnStopKind[];
+    allowContinue?: ContinueStopKind[];
     /**
      * Kinds the host may auto-continue without a CTA.
      * Kernel does not loop; hosts call continueFrom and pass `continuation`.
      */
-    autoContinue?: TurnStopKind[];
+    autoContinue?: ContinueStopKind[];
     /**
      * Max continueFrom rounds the kernel will accept for this profile.
      * Compared against `TurnRequest.continuation` (1-based continue attempt).
      * When omitted, only kind allowlists apply (no count cap).
      */
     maxContinues?: number;
+    /**
+     * Host replacement for the continue instruction appended on continueFrom
+     * turns. Omitted means the registered default (`CONTINUE_INSTRUCTION`).
+     */
+    continueInstruction?: string;
+}
+/** True when `kind` may appear in allowContinue / autoContinue. */
+export declare function isContinueStopKind(kind: string): kind is ContinueStopKind;
+/**
+ * Mid-turn + resume policy for text / image / speech profiles.
+ *
+ * - `resumption` — continueFrom after a non-user stop (all three types).
+ * - `allowSteering` — stage **inject** gate on text and live (default true).
+ *   Image / speech must omit. Stage events always emit when the runner uses stages.
+ *
+ * Stop / AbortSignal is not a profile knob — composer interfaces always
+ * project `canStop: true` because `TurnRequest.signal` is already wired.
+ */
+export interface ProfileTurnBehaviourSpec {
+    resumption?: ProfileTurnResumptionSpec;
+    /**
+     * When true (default on text/live), host `onStage` inject affordances are applied
+     * (`profileAllowsInject`). Does not hide stage emission.
+     */
+    allowSteering?: boolean;
 }
 /** Partial state passed when continuing a resumeable stop. */
 export interface TurnContinueFrom {
@@ -52,11 +82,35 @@ export interface TurnContinueFrom {
     partialArtifact?: string;
 }
 /** True when this stop may be continued (profile allow list or default). */
-export declare function isResumeableStop(stop: TurnStop | undefined, allowContinue?: readonly TurnStopKind[]): boolean;
+export declare function isResumeableStop(stop: TurnStop | undefined, allowContinue?: readonly ContinueStopKind[]): boolean;
 /** True when the host aborted (user Stop). */
 export declare function isUserCancelledStop(stop: TurnStop | undefined): boolean;
 /** True when profile policy allows one silent auto-continue for this stop. */
-export declare function shouldAutoContinue(stop: TurnStop | undefined, autoContinue?: readonly TurnStopKind[] | undefined): boolean;
+export declare function shouldAutoContinue(stop: TurnStop | undefined, autoContinue?: readonly ContinueStopKind[] | undefined): boolean;
+/** Read nested `turnBehaviour.resumption` from a non-live profile. */
+export declare function profileTurnResumption(profile: {
+    type: string;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
+}): ProfileTurnResumptionSpec | undefined;
+/**
+ * Text profiles may inject at stages unless `allowSteering: false`.
+ * Image / speech / host: use `profileAllowsInject` for the target matrix;
+ * this helper remains text-only for interface `allowSteering` projection.
+ */
+export declare function profileAllowsSteering(profile: {
+    type: string;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
+}): boolean;
+/**
+ * Whether stage **inject** affordances may be applied (`docs/contracts/stages.md`).
+ * Gates inject only — never stage emission or tool stages.
+ *
+ * Text + live when `allowSteering !== false`; never image / speech / host.
+ */
+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`. */

package/esm/src/kernel/stop.js

@@ -6,29 +6,36 @@
  *
  * @module
  */
+import { lexiconDefault } from '../guardrails/lexicon.js';
+import { CONTINUE_STOP_KINDS } from './schema.js';
 /**
- * Fixed continue instruction for resumeable stops.
- * Hosts should not invent per-app continue prompts.
+ * Default continue instruction for resumeable stops — the registered lexicon
+ * default (`continue.instruction`). It rarely needs replacing, but hosts may
+ * override it per profile via `turnBehaviour.resumption.continueInstruction`
+ * or process-wide via `overrideLexicon`.
  */
-export const CONTINUE_INSTRUCTION = 'Continue and finish the incomplete output from the previous turn. Do not restart from scratch; preserve what was already generated and complete it.';
-/** Default kinds hosts may offer Continue for. */
-const DEFAULT_ALLOW_CONTINUE = [
-    'length',
-    'stream_incomplete',
-    'provider_error',
-];
+export const CONTINUE_INSTRUCTION = lexiconDefault('continue.instruction');
+/** Default kinds hosts may offer Continue for (= full ContinueStopKind set). */
+export const DEFAULT_ALLOW_CONTINUE = CONTINUE_STOP_KINDS;
 /**
  * Default kinds for one silent auto-continue (hosts wait briefly, then resume once).
- * User `cancelled` is never included.
+ * Never includes kinds outside ContinueStopKind (e.g. cancelled / tool / gate / completed).
  */
 export const DEFAULT_AUTO_CONTINUE = ['length', 'stream_incomplete'];
 /** Pause before the one-shot auto-continue 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 `kind` may appear in allowContinue / autoContinue. */
+export function isContinueStopKind(kind) {
+    return CONTINUE_KIND_SET.has(kind);
+}
 const RESUMEABLE_DEFAULT = new Set(DEFAULT_ALLOW_CONTINUE);
 /** True when this stop may be continued (profile allow list or default). */
 export function isResumeableStop(stop, allowContinue) {
     if (!stop)
         return false;
+    if (!isContinueStopKind(stop.kind))
+        return false;
     const allow = allowContinue?.length ? new Set(allowContinue) : RESUMEABLE_DEFAULT;
     return allow.has(stop.kind);
 }
@@ -38,13 +45,41 @@ export function isUserCancelledStop(stop) {
 }
 /** True when profile policy allows one silent auto-continue for this stop. */
 export function shouldAutoContinue(stop, autoContinue = DEFAULT_AUTO_CONTINUE) {
-    if (!stop)
+    if (!stop || !isContinueStopKind(stop.kind))
         return false;
     const list = autoContinue ?? DEFAULT_AUTO_CONTINUE;
     if (list.length === 0)
         return false;
     return list.includes(stop.kind) && isResumeableStop(stop);
 }
+/** Read nested `turnBehaviour.resumption` from a non-live profile. */
+export function profileTurnResumption(profile) {
+    if (profile.type === 'live')
+        return undefined;
+    return profile.turnBehaviour?.resumption;
+}
+/**
+ * Text profiles may inject at stages unless `allowSteering: false`.
+ * Image / speech / host: use `profileAllowsInject` for the target matrix;
+ * this helper remains text-only for interface `allowSteering` projection.
+ */
+export function profileAllowsSteering(profile) {
+    if (profile.type !== 'text')
+        return false;
+    return profile.turnBehaviour?.allowSteering !== false;
+}
+/**
+ * Whether stage **inject** affordances may be applied (`docs/contracts/stages.md`).
+ * Gates inject only — never stage emission or tool stages.
+ *
+ * Text + live when `allowSteering !== false`; never image / speech / host.
+ */
+export function profileAllowsInject(profile) {
+    if (profile.type === 'text' || profile.type === 'live') {
+        return profile.turnBehaviour?.allowSteering !== false;
+    }
+    return false;
+}
 /** OpenAI-compatible normalized `finish_reason` (+ optional `native_finish_reason`). */
 export function turnStopFromOpenAiFinishReason(finishReason, nativeFinishReason) {
     const native = nativeFinishReason?.trim() || finishReason?.trim() || undefined;

package/esm/src/kernel/tools/events.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tool event shapes and the preamble every executable tool path shares.
+ *
+ * Function, declarative HTTP, and remote MCP tools all announce themselves,
+ * validate their input, and — for the remote kinds — clear their target against
+ * the profile's SSRF policy. Keeping that here means the three paths cannot drift,
+ * and it holds the event constructors both `execute.ts` and `remote.ts` need
+ * without either importing the other.
+ *
+ * @module
+ */
+import type { z } from 'zod';
+import type { TurnEvent } from '../types.js';
+import type { ToolCallEvent, ToolContext, ToolFailure } from './types.js';
+/** Identifying fields repeated on every event for one tool call. */
+export type ToolCallBase = Pick<ToolCallEvent, 'name' | 'callId' | 'arguments'>;
+export declare function toolEvent(base: ToolCallBase, patch: Partial<ToolCallEvent>): TurnEvent;
+export declare function failureEvent(base: ToolCallBase, failure: ToolFailure): TurnEvent;
+/** Failure text for a thrown value, without leaking a stack. */
+export declare function messageOf(err: unknown): string;
+/**
+ * Announce the call and validate its input.
+ *
+ * Returns `{ ok: false }` after emitting the failure event, so callers bail
+ * without re-deciding what an invalid input means.
+ */
+export declare function startToolExecution<T>(tool: {
+    input: z.ZodType<T>;
+}, rawInput: unknown, ctx: ToolContext, base: ToolCallBase): Generator<TurnEvent, {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+}>;
+/**
+ * Clear a remote target against the profile's network policy.
+ *
+ * Returns `undefined` after emitting the failure event when the target is
+ * blocked, so HTTP and MCP cannot diverge on what SSRF enforcement means.
+ */
+export declare function guardToolTarget(url: string, ctx: ToolContext, base: ToolCallBase): Generator<TurnEvent, URL | undefined>;

package/esm/src/kernel/tools/events.js

@@ -0,0 +1,71 @@
+/**
+ * Tool event shapes and the preamble every executable tool path shares.
+ *
+ * Function, declarative HTTP, and remote MCP tools all announce themselves,
+ * validate their input, and — for the remote kinds — clear their target against
+ * the profile's SSRF policy. Keeping that here means the three paths cannot drift,
+ * and it holds the event constructors both `execute.ts` and `remote.ts` need
+ * without either importing the other.
+ *
+ * @module
+ */
+import { throwIfAborted } from '../../guardrails/error.js';
+import { assertSafeUrl } from '../../guardrails/network.js';
+import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
+export function toolEvent(base, patch) {
+    return {
+        type: 'tool',
+        tool: { ...base, ...patch },
+    };
+}
+export function failureEvent(base, failure) {
+    return toolEvent(base, { phase: 'error', failure });
+}
+/** Failure text for a thrown value, without leaking a stack. */
+export function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Announce the call and validate its input.
+ *
+ * Returns `{ ok: false }` after emitting the failure event, so callers bail
+ * without re-deciding what an invalid input means.
+ */
+export function* startToolExecution(tool, rawInput, ctx, base) {
+    yield toolEvent(base, { phase: 'running' });
+    throwIfAborted(ctx.signal);
+    const parsed = tool.input.safeParse(rawInput);
+    if (!parsed.success) {
+        yield failureEvent(base, {
+            code: 'invalid_input',
+            message: 'Tool input validation failed', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            details: parsed.error.flatten(),
+        });
+        return { ok: false };
+    }
+    return { ok: true, data: parsed.data };
+}
+/**
+ * Clear a remote target against the profile's network policy.
+ *
+ * Returns `undefined` after emitting the failure event when the target is
+ * blocked, so HTTP and MCP cannot diverge on what SSRF enforcement means.
+ */
+export function* guardToolTarget(url, ctx, base) {
+    try {
+        return assertSafeUrl(url, resolveGuardrailPolicy(ctx.profile.guardrails).network);
+    }
+    catch (err) {
+        yield {
+            type: 'guardrail',
+            guardrail: {
+                stage: 'network',
+                trust: 'untrusted',
+                action: 'block',
+                hits: [{ rule: 'network.blocked', severity: 'high' }],
+            },
+        };
+        yield failureEvent(base, { code: 'network_blocked', message: messageOf(err) });
+        return undefined;
+    }
+}

package/esm/src/kernel/tools/execute.d.ts

@@ -3,37 +3,73 @@
  *
  * @module
  */
-import type { z } from 'zod';
-import type { Profile, TurnEvent } from '../types.js';
-import type { FunctionToolDef, InvokeToolResume, ModelToolResult, ToolCallEvent, ToolContext, ToolFailure, ToolPause, ToolPermission, ToolStreamEvent, TurnToolSnapshot } from './types.js';
-export declare function isResumeContinuation(resume?: InvokeToolResume): boolean;
-export declare function isToolPause(value: ToolFailure | ToolPause): value is ToolPause;
+import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import type { Provenance } from '../../guardrails/types.js';
+import type { InteractionPart, Profile, TurnEvent, TurnHistoryMessage } from '../types.js';
+import { startToolExecution } from './events.js';
+import { type ToolStageSupport } from './stage-run.js';
+import type { FunctionToolDef, ModelToolResult, ToolCallEvent, ToolContext, ToolFailure, ToolGate, ToolStreamEvent, TurnToolSnapshot } from './types.js';
+export { checkPermission, isGateResumeGranted, isResumeContinuation, permissionGranted, } from './permission.js';
+/** Validate host-emitted InteractionPart shapes; drop invalid entries. */
+export declare function coerceToolResultParts(raw: unknown): InteractionPart[] | undefined;
+/** Copy tool output for model `data`, omitting media `parts`. */
+export declare function leanToolResultData(output: unknown): unknown;
+/** @deprecated Gates use `ToolGate` / `phase: 'gate'`. Kept for type narrowing during migration. */
+export declare function isToolPause(value: ToolFailure | {
+    kind: string;
+}): value is {
+    kind: 'interactive' | 'confirmation' | 'permission' | 'auth';
+};
 export declare function yieldHandlerSideEvent(base: Pick<ToolCallEvent, 'name' | 'callId' | 'arguments'>, event: Exclude<ToolStreamEvent, {
     kind: 'complete';
 }>): Generator<TurnEvent>;
-export declare function permissionGranted(toolName: string, sessionPermissions?: string[]): boolean;
-export declare function checkPermission(toolName: string, permission: ToolPermission, sessionPermissions?: string[], resume?: InvokeToolResume): ToolPause | null;
 export declare function projectForModel(tool: FunctionToolDef, output: unknown): ModelToolResult;
-/** Format model-facing tool output for provider history continuation. */
+/**
+ * Format model-facing tool output for provider history continuation.
+ *
+ * Text projection only — never embeds `parts[].data`; media travels on
+ * `TurnHistoryMessage.parts` and adapters wire it from there.
+ *
+ * `executeRegisteredTool` guards at the boundary and leaves `modelText` behind, so
+ * the common path returns already-fenced text. A result recorded elsewhere — a
+ * host replaying a transcript — is guarded here instead, under full detection.
+ */
 export declare function formatToolResult(result: ModelToolResult): string;
-/** Format a tool failure for provider history — structured so the model (or host) sees the code. */
-export declare function formatToolFailureForModel(failure: ToolFailure): ModelToolResult;
-export declare function startToolExecution<T>(tool: {
-    input: z.ZodType<T>;
-}, rawInput: unknown, ctx: ToolContext, base: Pick<ToolCallEvent, 'name' | 'callId' | 'arguments'>): Generator<TurnEvent, {
-    ok: true;
-    data: T;
-} | {
-    ok: false;
-}>;
-export declare function executeFunction(tool: FunctionToolDef, rawInput: unknown, ctx: ToolContext, base: Pick<ToolCallEvent, 'name' | 'callId' | 'arguments'>, snapshot?: TurnToolSnapshot): AsyncGenerator<TurnEvent, ModelToolResult | undefined>;
-export declare function notLoadedMessage(tool: FunctionToolDef): string;
+/**
+ * Format a tool failure for provider history — structured so the model (or host)
+ * sees the code.
+ *
+ * The message is remote-authored on HTTP and MCP tools, so it is redacted before
+ * the kernel frames it as a system report.
+ */
+export declare function formatToolFailureForModel(failure: ToolFailure, provenance?: Provenance, policy?: ReturnType<typeof resolveGuardrailPolicy>): ModelToolResult;
+/** Settlement returned from `executeRegisteredTool` / function execute. */
+export type ToolExecuteSettlement = {
+    modelResult?: ModelToolResult;
+    gated?: ToolGate;
+    aborted?: boolean | {
+        reason?: string;
+    };
+    callNotStarted?: boolean;
+    awaiting?: boolean;
+    failure?: ToolFailure;
+    /** Raw tool output when the body completed (incl. awaiting). */
+    outputRaw?: unknown;
+    /**
+     * post_tool inject messages — apply after recording the provider tool result
+     * so Interactions continuation exists.
+     */
+    pendingInject?: TurnHistoryMessage[];
+};
+export declare function executeFunction(tool: FunctionToolDef, rawInput: unknown, ctx: ToolContext, base: Pick<ToolCallEvent, 'name' | 'callId' | 'arguments'>, snapshot?: TurnToolSnapshot, stages?: ToolStageSupport): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
+export declare function notLoadedMessage(tool: {
+    name: string;
+    loadTier?: string;
+}): string;
 export declare function extractLoadedIds(output: unknown): string[] | undefined;
-/** Strip prototype-pollution keys from provider/host tool args before validation. */
-export declare function plainToolInput(input: unknown): unknown;
 export declare function executeBuiltin(tool: {
     name: string;
-}, ctx: ToolContext, base: Pick<ToolCallEvent, 'name' | 'callId' | 'arguments'>, snapshot: TurnToolSnapshot): AsyncGenerator<TurnEvent, ModelToolResult | undefined>;
+}, ctx: ToolContext, base: Pick<ToolCallEvent, 'name' | 'callId' | 'arguments'>, snapshot: TurnToolSnapshot): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
 export declare function executeRegisteredTool(args: {
     profile: Profile;
     name: string;
@@ -41,5 +77,8 @@ export declare function executeRegisteredTool(args: {
     callId: string;
     ctx: Omit<ToolContext, 'callId' | 'profile'>;
     snapshot?: TurnToolSnapshot;
-}): AsyncGenerator<TurnEvent, ModelToolResult | undefined>;
+    stages?: ToolStageSupport;
+}): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
+export type { ToolStageSupport };
+export { startToolExecution };
 export declare function newCallId(name: string): string;