@arnilo/prism 0.6.0 → 0.8.0

package/dist/contracts-core/attention.d.ts

@@ -0,0 +1,66 @@
+/** Attention Compiler contracts (plan 074 Tasks 2–5). Opt-in per-turn gate that measures the
+ *  assembled input and mutates a history clone only after a host ratio of the model input
+ *  cap. `resolveRunAttentionCompiler` turns the agent setting plus an optional run overlay
+ *  into the frozen handle the session hands to assembly; nothing declared here runs on its
+ *  own, and omitting the option keeps today's request bytes. */
+import type { CompactionTrigger } from "./compaction.js";
+import type { ModelConfig } from "./content.js";
+/** Input-cap resolution inputs shared by the compiler and `input_ratio` compaction triggers. */
+export interface AttentionInputCapOptions {
+    /** Host cap; when set it wins over `model.limits.contextWindow` (C2). */
+    readonly maxInputTokens?: number;
+    /** Output + next-turn headroom subtracted from the window (default 1024). */
+    readonly reserveTokens?: number;
+}
+export interface AttentionCompilerOptions extends AttentionInputCapOptions {
+    /** Fraction of `inputCap` that triggers mutation; in `(0, 1)` (default 0.75). */
+    readonly triggerRatio?: number;
+    /** Where compaction should fire relative to `triggerRatio`; must exceed it (default 0.9). */
+    readonly compactRatio?: number;
+    /** Newest thinking-bearing assistant turns kept intact (default 1). */
+    readonly thinkingKeepTurns?: number;
+    /** Newest tool results kept full (default 3). */
+    readonly keepLast?: number;
+    /** Tool names whose results are never stubbed, whatever the ratio. */
+    readonly excludeTools?: readonly string[];
+}
+/** Where the compiler is switched on: `true` uses the defaults, an object tunes them, `false`
+ *  (or omitted) leaves requests byte-for-byte as they are without the compiler. On
+ *  `RunOptions` the same shape is an overlay: `false` disables, `true` is a no-op, and an
+ *  object may only *relax* the agent setting (see `resolveRunAttentionCompiler`). */
+export type AttentionCompilerSetting = boolean | AttentionCompilerOptions;
+export interface AttentionCompilerContext {
+    /** Model limits used to resolve the input cap; ignored when `maxInputTokens` is set. */
+    readonly model?: Pick<ModelConfig, "limits">;
+    /** Validated at create so an unknown trigger type fails at config time, not on turn one. */
+    readonly compactionTrigger?: CompactionTrigger;
+}
+/** Validated, frozen configuration returned by `createAttentionCompiler`. */
+export interface AttentionCompiler {
+    readonly inputCap: number;
+    readonly reserveTokens: number;
+    readonly triggerRatio: number;
+    readonly compactRatio: number;
+    readonly thinkingKeepTurns: number;
+    readonly keepLast: number;
+    readonly excludeTools: readonly string[];
+}
+/** One mutated turn. Under-ratio turns emit nothing and produce no report (C14). */
+export interface AttentionReport {
+    /** Estimated tokens measured before this turn's mutation — the value compared to the ratio. */
+    readonly used: number;
+    /** Estimated tokens of the same request after this turn's mutation: the cost curve is `used` → `usedAfter`. */
+    readonly usedAfter: number;
+    readonly inputCap: number;
+    readonly triggerRatio: number;
+    /** Thinking turns absent from this request; rows re-applied from the sticky frontier count again. */
+    readonly droppedThinkingTurns: number;
+    /** Tool results stubbed in this request; rows re-applied from the sticky frontier count again. */
+    readonly stubbedToolResults: number;
+    /** Payload bytes the stubs took out of this request (never the stub text itself). */
+    readonly stubbedBytes: number;
+    /** True when the gate stopped with eligible rows left: the sticky frontier is partial. */
+    readonly truncated: boolean;
+    readonly runId?: string;
+    readonly sessionId?: string;
+}

package/dist/contracts-core/attention.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attention.js.map

package/dist/contracts-core/compaction.d.ts

@@ -21,15 +21,74 @@ export interface CompactionResult {
     readonly entries?: readonly SessionEntry[];
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+/** Inputs a compaction trigger decides on. Estimates and ids only — never raw payloads. */
+export interface CompactionTriggerContext {
+    readonly sessionId: string;
+    readonly entryCount: number;
+    readonly estimatedInputTokens: number;
+    readonly inputCapTokens: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+/** Host-programmable compact-when gate (plan 074 C11). Omitted → `thresholdEntries` only. */
+export type CompactionTrigger = {
+    readonly type: "threshold_entries";
+    readonly entries: number;
+} | {
+    readonly type: "input_ratio";
+    readonly ratio: number;
+} | {
+    readonly type: "custom";
+    readonly shouldCompact: (context: CompactionTriggerContext) => boolean | Promise<boolean>;
+};
+/** Validate a host trigger at config time, so an unknown `type` fails at create (C11). */
+export declare function assertCompactionTrigger(trigger: CompactionTrigger): CompactionTrigger;
 export interface CompactionOptions {
     readonly strategy?: CompactionStrategy;
     readonly thresholdEntries?: number;
+    /** Replaces the `thresholdEntries` gate when set; omitted keeps today's entry-count gate. */
+    readonly trigger?: CompactionTrigger;
     readonly keepRecentEntries?: number;
     readonly maxSummaryChars?: number;
     readonly secrets?: readonly (string | undefined)[];
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly signal?: AbortSignal;
 }
+/** Legacy gates a compaction decision can fall back to when no `trigger` is configured. */
+export interface ResolveShouldCompactOptions {
+    /** Host trigger; when set it replaces the legacy gates below. */
+    readonly trigger?: CompactionTrigger;
+    /** Session gate: compact when the branch holds more than this many entries. */
+    readonly thresholdEntries?: number;
+    /** Attach-loop gate: compact when the estimated input is at or above this many tokens. */
+    readonly compactAfterTokens?: number;
+}
+/** Everything a compaction decision reads. Estimates only — never raw payloads. */
+export interface ResolveShouldCompactInput {
+    readonly sessionId: string;
+    readonly entryCount: number;
+    /** Estimated tokens of the would-be input; called at most once, and only when a ratio or custom trigger reads it. */
+    readonly estimateInputTokens: () => number;
+    /** Resolved input cap (the attention compiler's `resolveInputCap`); called at most once, and only when a ratio or custom trigger reads it. */
+    readonly resolveInputCapTokens: () => number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+    /** Receives the failure behind a fail-closed `false`. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * The single compact-when decision used by `autoCompact` and by host attach loops that gate their
+ * own post-run compaction (plan 074 C11).
+ *
+ * Precedence: an explicit `trigger` replaces the legacy gates. Only the token gates below a `trigger`
+ * replace are lazy — a `threshold_entries` trigger, or a `custom` callback that only reads counts,
+ * never pays for the token estimate or the input cap.
+ *
+ * Failure policy: a malformed trigger throws (`assertCompactionTrigger`, config error), while a
+ * throwing `custom.shouldCompact` — including a callback that reads an unresolvable cap — decides
+ * `false` and reports through `onError`, so a host bug can never compact on a guess.
+ */
+export declare function resolveShouldCompact(options: ResolveShouldCompactOptions, input: ResolveShouldCompactInput): Promise<boolean>;
 export interface CompactionMiddlewarePayload {
     readonly context: CompactionContext;
     readonly result: CompactionResult;

package/dist/contracts-core/compaction.js

@@ -1,2 +1,78 @@
-export {};
+/** Validate a host trigger at config time, so an unknown `type` fails at create (C11). */
+export function assertCompactionTrigger(trigger) {
+    if (typeof trigger !== "object" || trigger === null) {
+        throw new TypeError("compaction trigger must be an object");
+    }
+    switch (trigger.type) {
+        case "threshold_entries":
+            if (!Number.isSafeInteger(trigger.entries) || trigger.entries < 1) {
+                throw new TypeError("compaction trigger threshold_entries.entries must be a positive safe integer");
+            }
+            return trigger;
+        case "input_ratio":
+            if (!Number.isFinite(trigger.ratio) || trigger.ratio <= 0 || trigger.ratio >= 1) {
+                throw new TypeError("compaction trigger input_ratio.ratio must be a number in (0, 1)");
+            }
+            return trigger;
+        case "custom":
+            if (typeof trigger.shouldCompact !== "function") {
+                throw new TypeError("compaction trigger custom.shouldCompact must be a function");
+            }
+            return trigger;
+        default:
+            throw new TypeError(`unknown compaction trigger type: ${String(trigger.type)}`);
+    }
+}
+/**
+ * The single compact-when decision used by `autoCompact` and by host attach loops that gate their
+ * own post-run compaction (plan 074 C11).
+ *
+ * Precedence: an explicit `trigger` replaces the legacy gates. Only the token gates below a `trigger`
+ * replace are lazy — a `threshold_entries` trigger, or a `custom` callback that only reads counts,
+ * never pays for the token estimate or the input cap.
+ *
+ * Failure policy: a malformed trigger throws (`assertCompactionTrigger`, config error), while a
+ * throwing `custom.shouldCompact` — including a callback that reads an unresolvable cap — decides
+ * `false` and reports through `onError`, so a host bug can never compact on a guess.
+ */
+export async function resolveShouldCompact(options, input) {
+    let estimated;
+    let cap;
+    const estimateOnce = () => (estimated ??= input.estimateInputTokens());
+    const capOnce = () => (cap ??= input.resolveInputCapTokens());
+    const trigger = options.trigger;
+    if (trigger === undefined) {
+        if (options.thresholdEntries !== undefined)
+            return input.entryCount > options.thresholdEntries;
+        if (options.compactAfterTokens !== undefined)
+            return estimateOnce() >= options.compactAfterTokens;
+        return false;
+    }
+    assertCompactionTrigger(trigger);
+    if (trigger.type === "threshold_entries")
+        return input.entryCount > trigger.entries;
+    if (trigger.type === "input_ratio")
+        return estimateOnce() >= trigger.ratio * capOnce();
+    // Getter-backed so a callback that only reads counts never forces cap resolution, which throws
+    // when the active model declares no context window.
+    const context = {
+        sessionId: input.sessionId,
+        entryCount: input.entryCount,
+        get estimatedInputTokens() {
+            return estimateOnce();
+        },
+        get inputCapTokens() {
+            return capOnce();
+        },
+        ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    };
+    try {
+        return (await trigger.shouldCompact(context)) === true;
+    }
+    catch (error) {
+        input.onError?.(error);
+        return false;
+    }
+}
 //# sourceMappingURL=compaction.js.map

package/dist/contracts-core/content.d.ts

@@ -7,10 +7,13 @@ export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 export interface JsonObject {
     readonly [key: string]: JsonValue;
 }
+export type ProviderFailureClass = "quota" | "auth" | "rate_limited" | "transient" | "permanent" | "unknown";
 export interface ErrorInfo {
     readonly name?: string;
     readonly message: string;
     readonly code?: string | number;
+    /** Advisory classification stamped only for provider failures; it never changes retry behavior. */
+    readonly failureClass?: ProviderFailureClass;
     /** Provider backpressure hint (e.g. from a `Retry-After` header); retry policies
      *  honor it capped at their own `maxDelayMs`. */
     readonly retryAfterMs?: number;
@@ -102,6 +105,8 @@ export interface ModelCapabilities {
     readonly output?: readonly string[];
     readonly reasoning?: boolean;
     readonly tools?: boolean;
+    /** Advisory, conformance-derived tool-call behavior. Absent means unknown; it never changes runtime tool validation. */
+    readonly toolCallStrictness?: "strict" | "lenient" | "legacy";
     readonly streaming?: boolean;
     /** Native JSON-schema structured output support for this model. */
     readonly structuredOutput?: boolean | "json_schema";

package/dist/contracts-core/loop.d.ts

@@ -4,6 +4,48 @@ import type { AgentEvent, AgentFinishReason, ProviderTurnResult, ToolResult } fr
 import type { AgentInput } from "../input.js";
 import type { JsonValue, Message, ToolCallContent, Usage } from "./content.js";
 import type { ProviderRequest, StructuredOutputOptions } from "./provider.js";
+/**
+ * Metadata-only view of a run at a provider-turn boundary (plan 084 Task 2). Hosts branch on
+ * counters, never content: tool arguments, prompts, and tool results are not fields.
+ */
+export interface TurnBoundaryContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    /** 1-based index of the provider turn this boundary precedes. */
+    readonly turn: number;
+    /** Provider turns already completed in this run (`turn - 1`; 0 at the first boundary). */
+    readonly turns: number;
+    /** Host tool calls dispatched so far in this run. */
+    readonly toolCalls: number;
+    /** Run-total usage so far, when the provider reported any. */
+    readonly usage?: Usage;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+/** Synchronous decision at a turn boundary. `stop` ends the run cleanly; `continue` runs the turn. */
+export type TurnStopDecision = {
+    readonly action: "continue";
+} | {
+    readonly action: "stop";
+    readonly reason: string;
+};
+/**
+ * Host turn policy (plan 084 Task 2). Evaluated before every provider request, at the same
+ * boundary a `checkpointPolicy: "every-turn"` checkpoint is written. Omit it and the run keeps
+ * its exact 0.8.x turn structure (no callback, no reads).
+ */
+export interface TurnPolicyOptions {
+    /**
+     * Clean turn cap. Reaching it stops the run (`stopReason: "turn_limit"`) instead of failing it
+     * with a limit breach. A run overlay may only narrow `limits.maxTurns`; widening throws.
+     */
+    readonly maxTurns?: number;
+    /**
+     * Consulted before every provider request. Returning `stop` ends the run cleanly with
+     * `stopReason: "host_policy"` and a resumable checkpoint (`decision: "continue"` resumes it).
+     * Must be synchronous and must not throw; a throw fails the run with `ERR_PRISM_TURN_POLICY`.
+     */
+    readonly stop?: (context: TurnBoundaryContext) => TurnStopDecision;
+}
 export interface LoopContext {
     readonly sessionId: string;
     readonly runId: string;

package/dist/contracts-core/provider.d.ts

@@ -83,6 +83,10 @@ export interface RealtimeSession {
     close(reason?: string, options?: {
         readonly signal?: AbortSignal;
     }): Promise<void>;
+    /** Return a host-dispatched tool result. Omitted on transports that cannot complete tools. */
+    completeTool?(callId: string, output: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
 }
 /** Factory a provider exposes for realtime sessions; not part of `AIProvider`. */
 export type RealtimeSessionFactory = (options: RealtimeSessionOptions) => RealtimeSession;

package/dist/contracts-core/run-limits.d.ts

@@ -70,6 +70,8 @@ export interface GuardrailContext<S extends GuardrailStage> {
     readonly runId: string;
     readonly toolCallId?: string;
     readonly toolName?: string;
+    /** Same-run completed host tool results, available only at the output stage. */
+    readonly toolResults?: S extends "output" ? readonly ToolResult[] : never;
     readonly metadata: Readonly<Record<string, unknown>>;
     readonly signal: AbortSignal;
 }

package/dist/contracts-core.d.ts

@@ -3,6 +3,7 @@
  * of `./contracts-core.js` is unchanged (0.1.4 barrel precedent). */
 export type { AudioContent, DocumentContent, FileContent } from "./content.js";
 export * from "./contracts-core/agent.js";
+export * from "./contracts-core/attention.js";
 export * from "./contracts-core/batch.js";
 export * from "./contracts-core/compaction.js";
 export * from "./contracts-core/content.js";

package/dist/contracts-core.js

@@ -1,4 +1,5 @@
 export * from "./contracts-core/agent.js";
+export * from "./contracts-core/attention.js";
 export * from "./contracts-core/batch.js";
 export * from "./contracts-core/compaction.js";
 export * from "./contracts-core/content.js";

package/dist/contracts-protocol.d.ts

@@ -1,4 +1,4 @@
-import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, RetryOptions, RunLimitBreach, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, Usage } from "./contracts-core.js";
+import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, RetryOptions, RunLimitBreach, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, TurnPolicyOptions, Usage } from "./contracts-core.js";
 import type { AgentRunInterruption, AgentRunStateOptions } from "./contracts-run-state.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { ToolValidator } from "./tools.js";
@@ -45,6 +45,9 @@ export type RealtimeEvent = {
 } | {
     readonly type: "tool_call";
     readonly call: ToolCallContent;
+} | {
+    readonly type: "usage";
+    readonly usage: Usage;
 } | {
     readonly type: "interrupted";
 } | {
@@ -97,11 +100,22 @@ export interface RunOptions {
     readonly activateAllSkills?: true;
     /** Progressive: catalog (name+description) unless loaded; eager: full instructions every turn. Default progressive. */
     readonly skillsDisclosure?: import("./skill-disclosure.js").SkillsDisclosure;
+    /**
+     * Optional per-run allow-list of registered tool names. Omitted → every registered tool (legacy).
+     * Empty → no tools this run. Unknown names fail closed. Cannot widen the agent registry or a
+     * checkpointed grant; resume intersects this list with current authority.
+     */
+    readonly toolNames?: readonly string[];
     /** Tools disclosure: "all" (default) sends every active tool schema; "search" sends top-k + the generated `search_tools` tool. */
     readonly toolsDisclosure?: import("./tool-search.js").ToolsDisclosure;
     readonly toolsSearch?: import("./tool-search.js").ToolsSearchOptions;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
+    /** Per-run overlay for `AgentConfig.attentionCompiler` (plan 074 C12): `false` disables the
+     *  compiler for this run, `true` is a no-op, an object may only relax the agent setting
+     *  (gate ratios up, `keepLast`/`thinkingKeepTurns` down, `excludeTools` extended). Enabling
+     *  the compiler where the agent config left it off throws before the first provider turn. */
+    readonly attentionCompiler?: import("./contracts-core/attention.js").AttentionCompilerSetting;
     readonly instructionInjectors?: readonly InstructionInjector[];
     readonly inputLayout?: InputAssemblyLayout;
     readonly loop?: AgentLoopStrategy | AgentLoopOptions;
@@ -111,6 +125,11 @@ export interface RunOptions {
     readonly runState?: AgentRunStateOptions;
     /** Prompt provenance: copied verbatim onto this run's start and finish ledger records. */
     readonly promptVersion?: PromptVersionRef;
+    /**
+     * Host turn policy (plan 084 Task 2): a clean turn cap and/or a synchronous stop callback
+     * evaluated before every provider request. Omitted → no callback runs.
+     */
+    readonly turnPolicy?: TurnPolicyOptions;
 }
 export interface ProviderTurnMetadata {
     readonly providerId: string;
@@ -156,7 +175,8 @@ export interface DelegatedAgentStep {
         readonly label?: string;
     };
 }
-export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal";
+/** Why a run stopped cleanly. `host_policy` is a `RunOptions.turnPolicy` stop; the rest are loop ceilings (F4). */
+export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal" | "host_policy";
 export type AgentEvent = {
     readonly type: "agent_started";
     readonly sessionId: string;
@@ -166,8 +186,10 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly usage?: Usage;
-    /** Why the loop stopped, when a limit/ceiling ended the run cleanly (F4). Absent = natural end. */
+    /** Why the loop stopped, when a limit/ceiling or a host turn policy ended the run cleanly (F4). Absent = natural end. */
     readonly finishReason?: AgentFinishReason;
+    /** Host stop detail from `TurnPolicyOptions.stop` (≤256 bytes, redacted). Present only with `finishReason: "host_policy"`. */
+    readonly stopDetail?: string;
 } | {
     readonly type: "agent_suspended";
     readonly sessionId: string;
@@ -299,6 +321,21 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId?: string;
     readonly summary: string;
+} | {
+    /** One attention-compiler mutation (plan 074 R15/T6): measured counts only, never message text. */
+    readonly type: "attention_compiled";
+    readonly sessionId: string;
+    readonly runId?: string;
+    readonly used: number;
+    /** Estimated tokens of the same request after this turn's mutation. */
+    readonly usedAfter: number;
+    readonly inputCap: number;
+    readonly triggerRatio: number;
+    readonly droppedThinkingTurns: number;
+    readonly stubbedToolResults: number;
+    /** Payload bytes the tool stubs took out of this request. */
+    readonly stubbedBytes: number;
+    readonly truncated: boolean;
 } | {
     readonly type: "retry_scheduled";
     readonly sessionId: string;
@@ -509,6 +546,10 @@ export interface RunRecord extends OwnershipScope {
     readonly startedAt: string;
     readonly finishedAt?: string;
     readonly abortReason?: string;
+    /** Present when the loop stopped on a ceiling or host policy instead of a natural end. */
+    readonly stopReason?: AgentFinishReason;
+    /** Host stop detail from `TurnPolicyOptions.stop` (≤256 bytes, redacted). */
+    readonly stopDetail?: string;
     readonly error?: ErrorInfo;
     readonly metadata?: Readonly<Record<string, unknown>>;
     /** Provenance ref copied from `RunOptions.promptVersion` when the host supplied one. */

package/dist/contracts-run-state.d.ts

@@ -1,5 +1,5 @@
 import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ErrorInfo, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
-import type { AgentEvent, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
+import type { AgentEvent, AgentFinishReason, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
 export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
 export type ApprovalOutcome = "allow_once" | "allow_for_run" | "reject_once" | "reject_for_run";
@@ -143,6 +143,17 @@ export interface AgentRunStateOptions {
     readonly checkpoints: CheckpointStore;
     /** Host-authored immutable revision required for durable runs. */
     readonly definitionRevision: string;
+    /**
+     * Durable checkpoint cadence (plan 084 Task 1). `"decision"` (default) persists only on
+     * suspension and terminal status. `"every-turn"` additionally persists a running-state
+     * checkpoint at each provider-turn boundary — after the previous turn's tool results are in
+     * the session store, before the next provider request — so a host process that dies mid-run
+     * can `resumeAgentRun(..., { decision: "continue" })` from the last turn instead of re-running
+     * the investigation. Costs one bounded, redacted checkpoint write per provider turn; the
+     * policy is recorded in the checkpoint, so a later resume keeps checkpointing without the host
+     * repeating the option.
+     */
+    readonly checkpointPolicy?: "decision" | "every-turn";
     /** Suspend every tool call before its side effect. */
     readonly interruptBeforeTool?: boolean;
     readonly maxStateBytes?: number;
@@ -183,8 +194,13 @@ export interface AgentRunState {
 }
 export interface AgentRunResume {
     readonly expectedVersion: number;
-    /** Legacy single-approval path; `approve` allows all pending once, `deny` terminates the run denied. */
-    readonly decision?: "approve" | "deny";
+    /**
+     * Legacy decision path. `approve` allows all pending decisions once; `deny` terminates the run
+     * as `denied`; `continue` resumes a running-state `"every-turn"` checkpoint that has no pending
+     * decisions (crash recovery). A suspended run still requires `approve`/`deny` or a decision
+     * batch — `continue` never bypasses an approval gate and is a host-API-only action.
+     */
+    readonly decision?: "approve" | "deny" | "continue";
     /** Batch decision path; exactly one of decision/decisions. Applied as one atomic CAS transition. */
     readonly decisions?: readonly RunDecision[];
 }
@@ -194,16 +210,23 @@ export interface AgentRunResumeOptions {
     readonly definitionRevision: string;
     readonly ownership?: OwnershipScope;
     readonly fencingToken?: number;
+    /** Host abort for the resume: checked between steps and threaded into the resumed provider/tool turn. */
+    readonly signal?: AbortSignal;
     /** Routes root decisions for nested-run approvals back to the child (e.g. supervisor). */
     readonly resumeNestedRun?: ResumeNestedRun;
+    /**
+     * Opt-in (plan 078 Task 7): receives the reconstructed session before the resumed run
+     * starts, so an observer (e.g. the supervisor's child-event pump) can subscribe while the
+     * run is still live. The session is valid only for the duration of this resume.
+     */
+    readonly onSession?: (session: AgentSession) => void;
     /** Opt-in (plan 015 Task 4): restore persisted loaded-skill names into the resumed session catalog. */
     readonly persistSessionState?: boolean;
     /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies (requires `persistSessionState` too). */
     readonly includeSkillBodies?: boolean;
 }
-/** Bounded, abortable options for `resumeAgentRunStream()`. */
+/** Bounded live-event options for `resumeAgentRunStream()`; `signal` is inherited from the base resume options. */
 export interface AgentRunResumeStreamOptions extends AgentRunResumeOptions, SubscribeOptions {
-    readonly signal?: AbortSignal;
 }
 export interface AgentRunRef {
     readonly runId: string;
@@ -245,6 +268,10 @@ export interface AgentRunResult {
     readonly error?: ErrorInfo;
     /** String form of the abort reason when `status` is `"aborted"`. */
     readonly abortReason?: string;
+    /** Present when the loop stopped on a ceiling or host turn policy instead of a natural end. */
+    readonly stopReason?: AgentFinishReason;
+    /** Host stop detail from `TurnPolicyOptions.stop` (≤256 bytes, redacted). */
+    readonly stopDetail?: string;
     /** Present for durable suspended/terminal runs. Payload is redacted and bounded. */
     readonly runState?: AgentRunState;
     /** Present only while awaiting an operator decision. */

package/dist/evidence-grounding.d.ts

@@ -0,0 +1,29 @@
+import type { Guardrail, ToolResult } from "./contracts.js";
+export interface ClaimGroundingEvidence {
+    readonly value: number;
+    /** Refer to this governed figure as `[evidence:<ref>]` immediately after a claim. */
+    readonly ref?: string;
+}
+export interface ClaimGroundingEvidenceExtractorContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly toolResults: readonly ToolResult[];
+}
+/** Supplies host-governed figures without coupling this primitive to a host store or package. */
+export type ClaimGroundingEvidenceExtractor = (context: ClaimGroundingEvidenceExtractorContext) => readonly ClaimGroundingEvidence[];
+export interface ClaimGroundingGuardrailOptions {
+    /** False makes the returned guardrail a no-op. */
+    readonly requireEvidenceForNumbers: boolean;
+    /** Defaults to same-run tool results. A host extractor may return its own governed figures. */
+    readonly evidenceSources?: "tool_results" | ClaimGroundingEvidenceExtractor;
+    /** Defaults to block. Flag emits an allow record with `metadata.violation: true`. */
+    readonly onViolation?: "block" | "flag";
+    /** Exact numeric equality by default; rounded accepts half the final printed unit. */
+    readonly tolerance?: "exact" | "rounded";
+}
+/**
+ * Deterministic output guardrail for figures that must be grounded in same-run tool results
+ * or host-governed evidence. It never calls a provider, store, or extractor asynchronously.
+ */
+export declare function createClaimGroundingGuardrail(options: ClaimGroundingGuardrailOptions): Guardrail<"output">;