@arnilo/prism 0.7.0 → 0.9.0

package/dist/agent-run-state.js

@@ -1,12 +1,14 @@
 import { createHash } from "node:crypto";
+import { parseAttentionStickyFrontier, restoreAttentionFoldLedger, } from "./attention-compiler.js";
 import { AgentLoopStateError, AgentRunStateError } from "./contracts.js";
-import { parseAttentionStickyFrontier } from "./attention-compiler.js";
 import { validateLoadedSkillBodies } from "./skill-load.js";
 import { HARD_RUN_TOOL_NAMES } from "./tools.js";
 export const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
 export const AGENT_RUN_STATE_SCHEMA_VERSION = 1;
 export const DEFAULT_MAX_AGENT_RUN_STATE_BYTES = 256 * 1024;
 export const HARD_MAX_AGENT_RUN_STATE_BYTES = 1024 * 1024;
+/** Sidecar metadata ceiling per checkpoint record (not the run-state value). */
+export const MAX_AGENT_RUN_METADATA_BYTES = 4 * 1024;
 const MAX_DEPTH = 32;
 const MAX_PROPERTIES = 256;
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
@@ -102,6 +104,9 @@ export function validateRunStateOptions(options) {
     if (!Number.isSafeInteger(bytes) || bytes < 1 || bytes > HARD_MAX_AGENT_RUN_STATE_BYTES) {
         throw new AgentRunStateError(`maxStateBytes must be a positive safe integer at most ${HARD_MAX_AGENT_RUN_STATE_BYTES}`);
     }
+    if (options.checkpointPolicy !== undefined && options.checkpointPolicy !== "decision" && options.checkpointPolicy !== "every-turn") {
+        throw new AgentRunStateError('checkpointPolicy must be "decision" or "every-turn"');
+    }
 }
 export async function loadAgentRunState(checkpoints, ref, ownership) {
     const record = await checkpoints.loadCheckpoint({ namespace: AGENT_RUN_STATE_NAMESPACE, key: ref.runId, ...ownership });
@@ -113,10 +118,55 @@ export async function loadAgentRunState(checkpoints, ref, ownership) {
         record.value.sessionId !== ref.sessionId) {
         throw new AgentRunStateError("Agent run session mismatch");
     }
-    return { record, state: parseAgentRunState(record.value, record.version) };
+    const metadata = readCheckpointMetadata(record.metadata);
+    return { record, state: parseAgentRunState(record.value, record.version), ...(metadata ? { metadata } : {}) };
+}
+/** Resolve a host metadata source. A throwing provider fails the checkpoint write (fail closed). */
+export function resolveCheckpointMetadata(source) {
+    return typeof source === "function" ? source() : source;
+}
+function checkpointMetadataBytes(metadata) {
+    return Buffer.byteLength(JSON.stringify(metadata), "utf8");
+}
+/**
+ * Redact + bound a sidecar metadata map for a checkpoint write. Values must be strings;
+ * redaction runs first so a replacement marker is still charged against the 4 KiB ceiling.
+ */
+export function boundCheckpointMetadata(metadata, redactor) {
+    const redacted = redactor?.redact(metadata) ?? metadata;
+    if (!redacted || typeof redacted !== "object" || Array.isArray(redacted)) {
+        throw new AgentRunStateError("Checkpoint metadata must be an object");
+    }
+    const bounded = {};
+    for (const [key, value] of Object.entries(redacted)) {
+        if (typeof value !== "string")
+            throw new AgentRunStateError(`Checkpoint metadata value for ${key} must be a string`);
+        bounded[key] = value;
+    }
+    if (checkpointMetadataBytes(bounded) > MAX_AGENT_RUN_METADATA_BYTES) {
+        throw new AgentRunStateError(`Checkpoint metadata exceeds ${MAX_AGENT_RUN_METADATA_BYTES} bytes`);
+    }
+    return Object.freeze(bounded);
+}
+/**
+ * Read-side normalization (legacy tolerance): absent, oversize, or non-string entries are
+ * dropped, never thrown — a malformed sidecar must not block a resume.
+ */
+export function readCheckpointMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return undefined;
+    const bounded = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (typeof value === "string")
+            bounded[key] = value;
+    }
+    if (Object.keys(bounded).length === 0 || checkpointMetadataBytes(bounded) > MAX_AGENT_RUN_METADATA_BYTES)
+        return undefined;
+    return Object.freeze(bounded);
 }
 export async function saveAgentRunState(input) {
     const bounded = boundState(input.redactor?.redact(input.state) ?? input.state, input.maxStateBytes ?? DEFAULT_MAX_AGENT_RUN_STATE_BYTES);
+    const metadata = input.metadata === undefined ? undefined : boundCheckpointMetadata(input.metadata, input.redactor);
     const record = await input.checkpoints.saveCheckpoint({
         namespace: AGENT_RUN_STATE_NAMESPACE,
         key: bounded.runId,
@@ -125,12 +175,13 @@ export async function saveAgentRunState(input) {
         fencingToken: input.fencingToken,
         value: bounded,
         category: "agent-run",
+        ...(metadata ? { metadata } : {}),
         ...input.ownership,
     });
     return { record, state: { ...bounded, version: record.version } };
 }
 export function publicState(state) {
-    const { input: _input, pending: _pending, pendingCalls: _pendingCalls, nestedRuns: _nestedRuns, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, toolNames: _toolNames, ...publicValue } = state;
+    const { input: _input, pending: _pending, pendingCalls: _pendingCalls, nestedRuns: _nestedRuns, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, toolNames: _toolNames, checkpointPolicy: _checkpointPolicy, stopReason: _stopReason, ...publicValue } = state;
     return publicValue;
 }
 export function initialAgentRunState(input) {
@@ -152,6 +203,7 @@ export function initialAgentRunState(input) {
         interruptBeforeTool: input.interruptBeforeTool,
         counters: input.counters,
         deadlineAt: input.deadlineAt,
+        ...(input.options.checkpointPolicy === "every-turn" ? { checkpointPolicy: "every-turn" } : {}),
     };
 }
 export function parseAgentRunState(value, version) {
@@ -215,6 +267,12 @@ export function parseAgentRunState(value, version) {
             }
         }
     }
+    if (state.checkpointPolicy !== undefined && state.checkpointPolicy !== "every-turn") {
+        throw new AgentRunStateError("Malformed agent run checkpoint policy");
+    }
+    if (state.stopReason !== undefined && state.stopReason !== "host_policy") {
+        throw new AgentRunStateError("Malformed agent run stop reason");
+    }
     // Load bounds against the hard cap, not the default: the configured maxStateBytes is a
     // save-side policy knob, while the load-side bound is only a DoS ceiling. States saved
     // with a raised maxStateBytes must remain resumable.
@@ -284,12 +342,16 @@ function validateSessionState(sessionState) {
         }
     }
     const attention = sessionState.attentionSticky;
-    if (attention === undefined)
-        return;
     // Both arrays are capped by the parser, and a malformed frontier is dropped rather than
     // failing the resume: re-deciding a mutation is safe, refusing to resume is not.
-    if (parseAttentionStickyFrontier(attention) === undefined) {
+    if (attention !== undefined && parseAttentionStickyFrontier(attention) === undefined) {
         throw new AgentRunStateError("Malformed agent run attention frontier");
     }
+    // Plan 086 T3: the fold ledger gets the same treatment — malformed entries are dropped by the
+    // parser, a malformed shape fails the load rather than the first provider turn.
+    const fold = sessionState.attentionFold;
+    if (fold !== undefined && restoreAttentionFoldLedger(fold) === undefined) {
+        throw new AgentRunStateError("Malformed agent run attention fold ledger");
+    }
 }
 //# sourceMappingURL=agent-run-state.js.map

package/dist/agent-session/helpers.js

@@ -53,7 +53,12 @@ export function finalAssistantMessage(history) {
     return { content: [], text: "" };
 }
 export function errorFromInfo(error) {
-    return Object.assign(new Error(error.message), { name: error.name ?? "Error", cause: error.cause, code: error.code });
+    return Object.assign(new Error(error.message), {
+        name: error.name ?? "Error",
+        cause: error.cause,
+        code: error.code,
+        failureClass: error.failureClass,
+    });
 }
 export class ProviderTurnFailure extends Error {
     info;
@@ -155,6 +160,8 @@ export function createUsageAccumulator() {
     const sums = new Map();
     let costCurrency;
     let costCompatible = true;
+    let estimated = false;
+    let confidence;
     return {
         add(usage) {
             for (const key of ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"]) {
@@ -176,6 +183,13 @@ export function createUsageAccumulator() {
                 if (costCompatible)
                     sums.set("cost", (sums.get("cost") ?? 0) + usage.cost);
             }
+            // Run totals keep estimate provenance (plan 091 T2): one estimated turn
+            // labels the total, and the weakest confidence wins.
+            if (usage.estimated === true) {
+                estimated = true;
+                if (usage.confidence !== undefined && (confidence === undefined || usage.confidence === "low"))
+                    confidence = usage.confidence;
+            }
         },
         value() {
             if (sums.size === 0)
@@ -187,6 +201,11 @@ export function createUsageAccumulator() {
             }
             if (costCompatible && sums.has("cost") && costCurrency !== undefined)
                 usage.currency = costCurrency;
+            if (estimated) {
+                usage.estimated = true;
+                if (confidence !== undefined)
+                    usage.confidence = confidence;
+            }
             return Object.keys(usage).length > 0 ? usage : undefined;
         },
     };

package/dist/agent-session/session/assemble.js

@@ -9,7 +9,7 @@ import { assertGuardrailsAllowed, runGuardrails } from "../../guardrails.js";
 import { identityTelemetryAttributes, ownershipFromIdentity, resolveRunIdentity } from "../../identity.js";
 import { assembleProviderInput } from "../../input.js";
 import { errorToErrorInfo, redactRunLedgerRecord } from "../../redaction.js";
-import { RunLimitError, RunLimitTracker, resolveRunLimits } from "../../run-limits.js";
+import { describeBudgetExhaustion, RunLimitError, RunLimitTracker, resolveRunLimits } from "../../run-limits.js";
 import { createSessionEntry } from "../../session-stores.js";
 import { resolveSkillsDisclosure } from "../../skill-disclosure.js";
 import { applyRestoredSkillBodies } from "../../skill-load.js";
@@ -17,13 +17,117 @@ import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } fro
 import { composeSystemPrompt, mergeSystemPromptConfig } from "../../system-prompts.js";
 import { resolveToolResultFold } from "../../tool-result-fold.js";
 import { createSearchToolsTool, createToolSearchState, resolveToolsDisclosure } from "../../tool-search.js";
-import { createToolRegistry, selectRunTools } from "../../tools.js";
+import { clampTurnToolNames, createToolRegistry, selectRunTools } from "../../tools.js";
 import { bridgeAbort, createUsageAccumulator, inputToMessages, isDurableLoop, isSteerSoftInterrupt, mergeGuardrails, throwIfAborted, } from "../helpers.js";
-import { cleanupRun, persistDurable, persistSucceeded, suspendDurable } from "./persist.js";
-import { generateWithRetry, recordProviderUsage } from "./provider-round.js";
+import { checkpointDurableFold, checkpointDurableTurn, cleanupRun, persistDurable, persistSucceeded, suspendDurable } from "./persist.js";
+import { generateWithRetry, recordProviderUsage, resolveDeterministicTurn } from "./provider-round.js";
 import { bindChargeToolRound, bindDispatchToolCall, replayDurableNestedAndPending, runLoopUntilSettled, suspendGatedRound, } from "./tool-round.js";
 const PROMPT_VERSION_MAX_NAME_BYTES = 256;
 const PROMPT_VERSION_HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/** Cap on the host stop detail that reaches the result, ledger, and timeline (plan 084 Task 2). */
+const TURN_STOP_DETAIL_MAX_BYTES = 256;
+function lastAssistantText(history) {
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+        const message = history[i];
+        if (message?.role !== "assistant")
+            continue;
+        const text = message.content.map((block) => (block.type === "text" ? block.text : "")).join("");
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+/**
+ * `RunOptions.turnPolicy` stopped the run at a turn boundary (plan 084 Task 2). Internal control
+ * signal: it unwinds any loop shape and `executeRun` turns it into a clean terminal success with
+ * `stopReason: "host_policy"` — never a run error.
+ */
+class AgentRunStopped extends Error {
+    constructor() {
+        super("Agent run stopped by host turn policy");
+        this.name = "AgentRunStopped";
+    }
+}
+/** Host turn-policy misuse: a throwing or malformed callback fails the run closed. */
+class TurnPolicyError extends Error {
+    code = "ERR_PRISM_TURN_POLICY";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "TurnPolicyError";
+    }
+}
+/** Validate `RunOptions.turnPolicy` once, before any provider turn (plan 084 Task 2). */
+function assertTurnPolicy(policy, resolvedLimits) {
+    if (policy === undefined)
+        return;
+    if (typeof policy !== "object" || policy === null)
+        throw new TypeError("RunOptions.turnPolicy must be an object");
+    if (policy.stop !== undefined && typeof policy.stop !== "function") {
+        throw new TypeError("RunOptions.turnPolicy.stop must be a function");
+    }
+    const maxTurns = policy.maxTurns;
+    if (maxTurns === undefined)
+        return;
+    if (!Number.isSafeInteger(maxTurns) || maxTurns < 1) {
+        throw new TypeError("RunOptions.turnPolicy.maxTurns must be a positive safe integer");
+    }
+    // Same narrowing law as `limits`: a run overlay may tighten the agent's cap, never widen it.
+    const configured = resolvedLimits.maxTurns;
+    if (configured !== null && maxTurns > configured) {
+        throw new TypeError(`RunOptions.turnPolicy.maxTurns (${maxTurns}) cannot widen limits.maxTurns (${configured})`);
+    }
+}
+/** Redact and bound a host stop reason; anything unusable fails the run closed. */
+function boundedStopDetail(session, reason) {
+    if (typeof reason !== "string" || reason.length === 0) {
+        throw new TurnPolicyError("RunOptions.turnPolicy.stop must return a non-empty reason string");
+    }
+    const redacted = session.redact(reason);
+    if (Buffer.byteLength(redacted, "utf8") > TURN_STOP_DETAIL_MAX_BYTES) {
+        throw new TurnPolicyError(`RunOptions.turnPolicy.stop reason must be at most ${TURN_STOP_DETAIL_MAX_BYTES} UTF-8 bytes`);
+    }
+    return redacted;
+}
+/**
+ * Evaluate the host turn policy at the current provider-turn boundary (plan 084 Task 2). Returns
+ * the stop to record, or `undefined` to run the turn. Omitted policy → nothing is read or called.
+ */
+function evaluateTurnStop(ctx) {
+    const policy = ctx.options.turnPolicy;
+    if (!policy)
+        return undefined;
+    const turn = Math.max(1, ctx.session.activeLoopTurn);
+    const turns = turn - 1;
+    if (policy.maxTurns !== undefined && turns >= policy.maxTurns)
+        return { reason: "turn_limit", detail: "maxTurns" };
+    if (!policy.stop)
+        return undefined;
+    const context = {
+        sessionId: ctx.session.id,
+        runId: ctx.runId,
+        turn,
+        turns,
+        toolCalls: ctx.toolCalls,
+        ...(ctx.runUsage.value() ? { usage: ctx.runUsage.value() } : {}),
+        metadata: ctx.metadata,
+    };
+    let decision;
+    try {
+        decision = policy.stop(context);
+    }
+    catch (error) {
+        throw new TurnPolicyError("RunOptions.turnPolicy.stop threw", { cause: error });
+    }
+    if (decision === null || typeof decision !== "object" || typeof decision.then === "function") {
+        throw new TurnPolicyError("RunOptions.turnPolicy.stop must synchronously return a TurnStopDecision");
+    }
+    const action = decision.action;
+    if (action === "continue")
+        return undefined;
+    if (action !== "stop")
+        throw new TurnPolicyError('RunOptions.turnPolicy.stop decision action must be "continue" or "stop"');
+    return { reason: "host_policy", detail: boundedStopDetail(ctx.session, decision.reason) };
+}
 function assertPromptVersionRef(ref) {
     if (ref === undefined)
         return undefined;
@@ -47,7 +151,13 @@ async function assembleRoundContext(params) {
     throwIfAborted(controller.signal);
     session.emit({ type: "agent_started", sessionId: session.id, runId });
     if (resumed)
-        session.emit({ type: "agent_resumed", sessionId: session.id, runId, version: resumed.version });
+        session.emit({
+            type: "agent_resumed",
+            sessionId: session.id,
+            runId,
+            version: resumed.version,
+            ...(resumed.restore ? { restore: resumed.restore } : {}),
+        });
     const startRecord = {
         id: runId,
         sessionId: session.id,
@@ -83,6 +193,7 @@ async function assembleRoundContext(params) {
     const tools = searchTool ? [...activeToolList, searchTool] : activeToolList;
     const activeSkills = session.resolveRunSkills(options, tools);
     session.activeRunSkills = activeSkills;
+    session.tailSegments.clear();
     if (options.model && JSON.stringify(options.model) !== JSON.stringify(session.agent.config.model)) {
         await session.appendEntry(createSessionEntry({
             sessionId: session.id,
@@ -122,24 +233,41 @@ async function assembleRoundContext(params) {
     assertStructuredOutputRequestSupported(options.model ?? session.agent.config.model, providerOptions);
     const validate = options.validate ?? session.agent.config.validator;
     // Resolved once per run, before any provider turn: a bad setting or a widening run overlay
-    // fails here rather than on the turn that happens to cross the ratio (plan 074 C12).
-    const attentionCompiler = resolveRunAttentionCompiler(session.agent.config.attentionCompiler, options.attentionCompiler, options.model ?? session.agent.config.model);
+    // fails here rather than on the turn that happens to cross the ratio (plan 074 C12). The
+    // resolved run input budget rides the handle so `run_input_ratio` folds against the same cap
+    // the run limit enforces (plan 086 T2); `null` (disabled) leaves that axis on the input cap.
+    const attentionCompiler = resolveRunAttentionCompiler(session.agent.config.attentionCompiler, options.attentionCompiler, options.model ?? session.agent.config.model, limits.limits.maxInputTokens);
+    // Plan 086 T3: durable folding writes the fold ledger to the run checkpoint, so it needs a
+    // durable run (the session's durable state is set before this call). Fail at run start, before
+    // any provider turn, rather than folding into memory only. The fold state rides that
+    // checkpoint independently of `persistSessionState`.
+    if (attentionCompiler?.durable && !session.activeDurable) {
+        throw new AgentRunStateError("attentionCompiler.durable requires a durable run: set AgentConfig or RunOptions runState with a checkpoint store");
+    }
+    session.attentionDurable = attentionCompiler?.durable === true;
     // Telemetry seam (plan 074 T6): one `attention_compiled` per mutated turn, counts and the
     // measured ratio inputs only. Under-ratio turns and compiler-off runs emit nothing.
+    // Plan 086 T3: a turn that folded new bodies is the fold-boundary durability signal, so it is
+    // remembered here (the callback is synchronous) and checkpointed by the assembler below.
+    let foldCheckpointPending = false;
     const onAttentionReport = attentionCompiler
-        ? (report) => session.emit({
-            type: "attention_compiled",
-            sessionId: session.id,
-            runId,
-            used: report.used,
-            usedAfter: report.usedAfter,
-            inputCap: report.inputCap,
-            triggerRatio: report.triggerRatio,
-            droppedThinkingTurns: report.droppedThinkingTurns,
-            stubbedToolResults: report.stubbedToolResults,
-            stubbedBytes: report.stubbedBytes,
-            truncated: report.truncated,
-        })
+        ? (report) => {
+            if (report.newFoldedBodies > 0)
+                foldCheckpointPending = true;
+            session.emit({
+                type: "attention_compiled",
+                sessionId: session.id,
+                runId,
+                used: report.used,
+                usedAfter: report.usedAfter,
+                inputCap: report.inputCap,
+                triggerRatio: report.triggerRatio,
+                droppedThinkingTurns: report.droppedThinkingTurns,
+                stubbedToolResults: report.stubbedToolResults,
+                stubbedBytes: report.stubbedBytes,
+                truncated: report.truncated,
+            });
+        }
         : undefined;
     const instructionInjectors = options.instructionInjectors ?? session.agent.config.instructionInjectors ?? [];
     const inputLayout = options.inputLayout ?? session.agent.config.inputLayout;
@@ -174,9 +302,13 @@ async function assembleRoundContext(params) {
         assembledTurn: false,
         artifactFinished: false,
         artifactFailedInfo: undefined,
+        toolCalls: 0,
+        toolResults: [],
         runUsage,
         loopCtx: undefined,
     };
+    const toolNarrowing = options.toolNarrowing ?? session.agent.config.toolNarrowing;
+    let narrowedForTurn;
     const loopCtx = {
         sessionId: session.id,
         runId,
@@ -190,6 +322,38 @@ async function assembleRoundContext(params) {
         restoredLoopState: resumed?.state?.loopState?.snapshot,
         assemble: async (nextInput, toolResults, turn) => {
             limits.charge("maxTurns");
+            const turnIndex = turn ?? 1;
+            let turnTools = tools;
+            if (toolNarrowing) {
+                if (typeof toolNarrowing !== "function")
+                    throw new TypeError("toolNarrowing must be a function");
+                if (narrowedForTurn?.turn === turnIndex) {
+                    turnTools = narrowedForTurn.tools;
+                }
+                else {
+                    const assistant = lastAssistantText(session.history);
+                    const requested = await toolNarrowing({
+                        turn: turnIndex,
+                        toolIds: tools.map((tool) => tool.name),
+                        ...(assistant !== undefined ? { lastAssistantText: assistant } : {}),
+                    });
+                    if (!Array.isArray(requested))
+                        throw new TypeError("toolNarrowing must return a string array");
+                    const clamped = clampTurnToolNames(tools, requested);
+                    if (clamped.dropped.length > 0) {
+                        session.emit({
+                            type: "tool_narrowing_clamped",
+                            sessionId: session.id,
+                            runId,
+                            turn: turnIndex,
+                            dropped: clamped.dropped,
+                        });
+                    }
+                    turnTools = clamped.tools;
+                    narrowedForTurn = { turn: turnIndex, tools: turnTools };
+                }
+                ctx.turnAllow = turnTools.map((tool) => tool.name);
+            }
             const request = await assembleProviderInput({
                 model: options.model ?? session.agent.config.model,
                 input: nextInput,
@@ -213,9 +377,16 @@ async function assembleRoundContext(params) {
                 // Session-owned: a stub made earlier stays applied even on a later under-ratio turn, so
                 // the prompt-cache prefix is not rewritten (C10). Undefined when the compiler is off.
                 attentionSticky: attentionCompiler ? session.attentionStickyFor() : undefined,
+                // Folded bodies (plan 086 T3): a row summarized once is re-applied, never re-summarized,
+                // so sticky rows stay byte-identical and a resumed run reuses the persisted bodies.
+                attentionFold: attentionCompiler ? session.attentionFoldFor() : undefined,
+                // Charge-so-far for the `run_input_ratio` axis: the counter only holds completed turns,
+                // so the axis projects this turn's estimate onto it.
+                runInputTokens: limits.snapshot().inputTokens,
                 onAttentionReport,
                 loadedSkills: session.loadedSkills,
-                tools,
+                tailSegments: session.tailSegments,
+                tools: turnTools,
                 resourceLoader: session.agent.config.resourceLoader,
                 permission: session.agent.config.permission,
                 trust: session.agent.config.trust,
@@ -228,6 +399,13 @@ async function assembleRoundContext(params) {
                 signal: controller.signal,
             });
             ctx.assembledTurn = true;
+            if (foldCheckpointPending) {
+                foldCheckpointPending = false;
+                // Fold-boundary durability (plan 086 T3): one write per turn that added folded bodies,
+                // after the request is assembled and before the provider sees it, so a crash during this
+                // turn resumes with the same ledger. No-op unless the compiler is durable.
+                await checkpointDurableFold(session, { runId, model, limits });
+            }
             return request;
         },
         chargeToolRound: bindChargeToolRound(ctx),
@@ -236,10 +414,29 @@ async function assembleRoundContext(params) {
             if (!ctx.assembledTurn)
                 limits.charge("maxTurns");
             ctx.assembledTurn = false;
+            // Host turn policy (plan 084 Task 2): evaluated at the same turn boundary as the
+            // crash-recovery checkpoint below, before any provider work. Throwing unwinds any loop
+            // shape; `executeRun` converts it into a clean terminal success with `stopReason`.
+            const stop = evaluateTurnStop(ctx);
+            if (stop) {
+                ctx.runStop = stop;
+                ctx.loopCtx.finishReason = stop.reason;
+                throw new AgentRunStopped();
+            }
+            // Crash-recovery boundary (plan 084 Task 1): after the previous turn's tool results are in
+            // the store and before this provider request. No-op unless `checkpointPolicy: "every-turn"`.
+            if (session.activeDurable?.options.checkpointPolicy === "every-turn") {
+                await checkpointDurableTurn(session, { runId, model, limits });
+            }
+            // Deterministic no-model turn (plan 096): host middleware answers at the provider boundary,
+            // before any provider-round work. No answer → provider path unchanged.
+            const deterministic = await resolveDeterministicTurn(session, request, runId, session.activeLoopTurn, controller.signal, ctx.toolResults);
+            if (deterministic)
+                return deterministic;
             const policyResult = await session.applyProviderRequestPolicies(request, runId, options, metadata, controller.signal);
             const middlewareRequest = (await session.agent.config.middleware?.run("provider_request", policyResult.request)) ?? policyResult.request;
             try {
-                return await generateWithRetry(session, session.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, session.activeLoopTurn, (turnUsage, turn, attempt) => recordProviderUsage(ctx, turnUsage, turn, attempt));
+                return await generateWithRetry(session, session.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, session.activeLoopTurn, (turnUsage, turn, attempt) => recordProviderUsage(ctx, turnUsage, turn, attempt, middlewareRequest), ctx.toolResults);
             }
             catch (error) {
                 if (isSteerSoftInterrupt(error)) {
@@ -288,6 +485,7 @@ export async function executeRun(session, input, options, runId, resumed) {
     }
     const requestedLimits = options.limits;
     const resolvedLimits = resolveRunLimits(session.agent.config.limits, requestedLimits);
+    assertTurnPolicy(options.turnPolicy, resolvedLimits);
     const durableOptions = options.runState ?? session.agent.config.runState;
     if (session.agent.config.runState && options.runState && session.agent.config.runState !== options.runState) {
         throw new AgentRunStateError("RunOptions cannot replace agent durable run-state configuration");
@@ -321,8 +519,11 @@ export async function executeRun(session, input, options, runId, resumed) {
     if (session.activeIdentity && !session.activeOwnership)
         session.activeOwnership = ownershipFromIdentity(session.activeIdentity);
     session.activeIdempotencyKey = options.idempotencyKey ?? session.agent.config.idempotencyKey;
-    session.activeGuardrails = mergeGuardrails(session.agent.config.guardrails, options.guardrails);
+    session.activeGuardrails = mergeGuardrails(mergeGuardrails(session.agent.config.guardrails, session.packGuardrails), options.guardrails);
     session.activeDurable = resumed ?? (durableOptions ? { options: durableOptions, version: 0 } : undefined);
+    // Plan 086 T3: reset here, so a suspension before the compiler is resolved (input guardrail)
+    // cannot inherit the previous run's durable-folding flag. `assembleRoundContext` sets it true.
+    session.attentionDurable = false;
     session.activeGatedRound = undefined;
     if (resumed)
         session.invalidateSnapshot();
@@ -330,6 +531,9 @@ export async function executeRun(session, input, options, runId, resumed) {
     const startedAt = new Date().toISOString();
     let runError;
     let runStatus = "succeeded";
+    // Set only on the clean-success path; the finish ledger record carries them (plan 084 Task 2).
+    let stopReason;
+    let stopDetail;
     const runUsage = createUsageAccumulator();
     let usage;
     const metadata = {
@@ -349,6 +553,7 @@ export async function executeRun(session, input, options, runId, resumed) {
         deadlineAt: resumed?.state?.deadlineAt,
     });
     session.activeLimits = limits;
+    session.activeRecentToolCalls = [];
     const hasFiniteTokenCap = (value) => typeof value === "number" && Number.isFinite(value);
     session.activeLimitOutputBuffer = [session.agent.config.limits, requestedLimits].some((value) => hasFiniteTokenCap(value?.maxOutputTokens) || hasFiniteTokenCap(value?.maxTotalTokens) || value?.maxCost !== undefined);
     try {
@@ -374,8 +579,16 @@ export async function executeRun(session, input, options, runId, resumed) {
             }
             ctx.loop.restore?.(resumedLoopState.snapshot);
         }
-        const loopUsage = await runLoopUntilSettled(ctx);
-        if (ctx.loop.name === "generate-validate-revise" && !ctx.artifactFinished) {
+        const loopUsage = await runLoopUntilSettled(ctx).catch((error) => {
+            // Host turn-policy stop (plan 084 Task 2): the loop was unwound on purpose at a turn
+            // boundary. Not an error — the run settles cleanly and stays resumable.
+            if (error instanceof AgentRunStopped)
+                return undefined;
+            throw error;
+        });
+        stopReason = ctx.runStop?.reason ?? ctx.loopCtx.finishReason;
+        stopDetail = ctx.runStop?.detail;
+        if (!ctx.runStop && ctx.loop.name === "generate-validate-revise" && !ctx.artifactFinished) {
             throw Object.assign(new Error(ctx.artifactFailedInfo?.message ?? "artifact loop ended without a validated artifact"), {
                 name: "ArtifactFailed",
                 code: ctx.artifactFailedInfo?.code ?? "artifact_failed",
@@ -392,8 +605,18 @@ export async function executeRun(session, input, options, runId, resumed) {
             return session.buildRunResult({ runId, status: "suspended", runState: error.state, interruption: error.interruption });
         }
         runError = errorToErrorInfo(error);
-        session.emit({ type: "error", sessionId: session.id, runId, error: runError });
         const breach = error instanceof RunLimitError ? error.breach : limits.breach;
+        // Terminal attribution before the terminal `error`/finish records, so a subscriber that stops
+        // at the first terminal event still sees why the run died (plan 087 T2).
+        if (breach) {
+            session.emit({
+                type: "budget_exhausted",
+                sessionId: session.id,
+                runId,
+                ...describeBudgetExhaustion(limits, breach, session.activeRecentToolCalls ?? []),
+            });
+        }
+        session.emit({ type: "error", sessionId: session.id, runId, error: runError });
         runStatus = breach ? "failed" : controller.signal.aborted ? "aborted" : "failed";
         const runState = session.activeDurable?.state
             ? await persistDurable(session, {
@@ -418,7 +641,7 @@ export async function executeRun(session, input, options, runId, resumed) {
         throw new AgentRunError(result, { cause: error });
     }
     finally {
-        await cleanupRun({ session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError });
+        await cleanupRun({ session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError, stopReason, stopDetail });
     }
 }
 //# sourceMappingURL=assemble.js.map

package/dist/agent-session/session/persist.d.ts

@@ -15,6 +15,30 @@ export declare function suspendDurable(session: SessionHost, input: {
     /** Full replacement when provided; otherwise the recorded nested runs are preserved. */
     readonly nestedRuns?: readonly NestedRunRef[];
 }): Promise<AgentRunState>;
+/**
+ * Turn-boundary crash-recovery checkpoint (plan 084 Task 1). Called before each provider
+ * request when `checkpointPolicy: "every-turn"`; a no-op otherwise, so default-policy runs keep
+ * the 0.8.x checkpoint shape and write count unchanged. Pending-decision markers are dropped:
+ * at a turn boundary every gated call has been resolved or the run already suspended, and a
+ * stale marker must never replay. The recorded `checkpointPolicy` makes the cadence survive
+ * into a resumed run, and loop-local state rides along exactly as it does at suspension.
+ */
+export declare function checkpointDurableTurn(session: SessionHost, input: {
+    readonly runId: string;
+    readonly model: ModelConfig;
+    readonly limits: RunLimitTracker;
+}): Promise<void>;
+/**
+ * Fold-boundary checkpoint (plan 086 T3). Called once per turn that added folded bodies — never
+ * per turn — when the resolved compiler is durable, so a crash after a fold resumes with the
+ * ledger and frontier already on disk. Independent of `checkpointPolicy`: the fold is the
+ * durability point that matters for a long single run, not the turn boundary.
+ */
+export declare function checkpointDurableFold(session: SessionHost, input: {
+    readonly runId: string;
+    readonly model: ModelConfig;
+    readonly limits: RunLimitTracker;
+}): Promise<void>;
 export declare function persistSucceeded(ctx: RoundContext, loopUsage: Usage | undefined): Promise<AgentRunResult>;
 export declare function cleanupRun(input: {
     session: SessionHost;
@@ -25,4 +49,7 @@ export declare function cleanupRun(input: {
     startedAt: string;
     runStatus: AgentRunResult["status"];
     runError: ErrorInfo | undefined;
+    /** Clean stop taxonomy for the finish record; only written for a succeeded run (plan 084 Task 2). */
+    stopReason?: import("../../contracts.js").AgentFinishReason;
+    stopDetail?: string;
 }): Promise<void>;