@arnilo/prism 0.8.0 → 0.10.0

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,15 +17,26 @@ 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 { checkpointDurableTurn, 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
@@ -45,6 +56,104 @@ class TurnPolicyError extends Error {
         this.name = "TurnPolicyError";
     }
 }
+/** Stop-hook misuse: a throwing or malformed hook fails the run closed (plan 106 R1). */
+class StopHookError extends Error {
+    code = "ERR_PRISM_STOP_HOOK";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "StopHookError";
+    }
+}
+/** Validate the merged stop-hook list once per run, before any provider turn (plan 106 R1). */
+function assertStopHooks(hooks) {
+    for (const hook of hooks) {
+        if (typeof hook !== "object" ||
+            hook === null ||
+            typeof hook.name !== "string" ||
+            hook.name.length === 0 ||
+            typeof hook.decide !== "function") {
+            throw new TypeError("stopHooks entries must be StopHook objects with a non-empty name and a decide function");
+        }
+    }
+}
+/**
+ * Run stop hooks in order at a natural loop end (plan 106 R1). The first `continue` wins; every
+ * `stop` (or no hook continuing) leaves the run finished. Hook context is metadata plus the live
+ * transcript — tool arguments, prompts, and results are never reshaped by core.
+ */
+async function evaluateStopHooks(ctx, stopHookActive) {
+    const context = {
+        sessionId: ctx.session.id,
+        runId: ctx.runId,
+        turn: ctx.limits.snapshot().turns,
+        history: ctx.loopCtx.history,
+        metadata: ctx.metadata,
+        signal: ctx.controller.signal,
+        stopHookActive,
+    };
+    for (const hook of ctx.stopHooks) {
+        let decision;
+        try {
+            decision = await hook.decide(context);
+        }
+        catch (error) {
+            throw new StopHookError(`Stop hook "${hook.name}" threw`, { cause: error });
+        }
+        if (decision === null || typeof decision !== "object") {
+            throw new StopHookError(`Stop hook "${hook.name}" must return a StopHookDecision`);
+        }
+        const action = decision.action;
+        if (action === "stop")
+            continue;
+        if (action !== "continue") {
+            throw new StopHookError(`Stop hook "${hook.name}" decision action must be "stop" or "continue"`);
+        }
+        const reason = decision.reason;
+        if (typeof reason !== "string" || reason.length === 0) {
+            throw new StopHookError(`Stop hook "${hook.name}" continue decision requires a non-empty reason string`);
+        }
+        const steer = decision.steer;
+        if (!isStopHookSteer(steer)) {
+            throw new StopHookError(`Stop hook "${hook.name}" steer must be a string or Message`);
+        }
+        return steer === undefined ? { reason } : { reason, steer };
+    }
+    return undefined;
+}
+function isStopHookSteer(value) {
+    if (value === undefined || typeof value === "string")
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const message = value;
+    return typeof message.role === "string" && Array.isArray(message.content);
+}
+/**
+ * Queue a continuation through the host steer path (plan 106 R1): same redaction, same 8-message /
+ * 64 KiB caps, and the same input-guardrail re-check when the loop drains it. A queue failure fails
+ * the run closed — the hook asked for something the run cannot deliver.
+ */
+function queueStopHookContinuation(ctx, decision) {
+    const messages = [{ role: "user", content: [{ type: "text", text: decision.reason }] }];
+    if (decision.steer !== undefined) {
+        messages.push(typeof decision.steer === "string" ? { role: "user", content: [{ type: "text", text: decision.steer }] } : decision.steer);
+    }
+    try {
+        ctx.session.steer(messages);
+    }
+    catch (error) {
+        throw new StopHookError("Stop hook continuation could not be queued", { cause: error });
+    }
+}
+/** The generate-validate-revise loop promises a validated artifact; a bare return is a failure. */
+function assertArtifactOutcome(ctx) {
+    if (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",
+        });
+    }
+}
 /** Validate `RunOptions.turnPolicy` once, before any provider turn (plan 084 Task 2). */
 function assertTurnPolicy(policy, resolvedLimits) {
     if (policy === undefined)
@@ -135,12 +244,21 @@ function assertPromptVersionRef(ref) {
     return ref;
 }
 async function assembleRoundContext(params) {
-    const { session, input, options, runId, resumed, controller, model, startedAt, promptVersion, metadata, limits, runUsage } = params;
+    const { session, input, options, runId, resumed, controller, model, startedAt, promptVersion, metadata, limits, runUsage, stopHooks } = params;
     session.resolveRunProvider(options);
     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 } : {}),
+        });
+    // Plan 106 R2: first run start of this session opens it. Awaited after the two emits above so the
+    // run's synchronous announce burst stays intact; middleware error policy owns failures.
+    await session.openSession(runId);
     const startRecord = {
         id: runId,
         sessionId: session.id,
@@ -176,6 +294,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,
@@ -215,24 +334,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;
@@ -269,9 +405,12 @@ async function assembleRoundContext(params) {
         artifactFailedInfo: undefined,
         toolCalls: 0,
         toolResults: [],
+        stopHooks,
         runUsage,
         loopCtx: undefined,
     };
+    const toolNarrowing = options.toolNarrowing ?? session.agent.config.toolNarrowing;
+    let narrowedForTurn;
     const loopCtx = {
         sessionId: session.id,
         runId,
@@ -285,6 +424,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,
@@ -304,13 +475,21 @@ async function assembleRoundContext(params) {
                 toolsSearch: session.agent.config.toolsSearch,
                 activatedTools: session.activatedTools,
                 toolResultFold: resolveToolResultFold(options.toolResultFold, session.agent.config.toolResultFold),
+                contextBudget: session.agent.config.contextBudget,
                 attentionCompiler,
                 // 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,
@@ -323,6 +502,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),
@@ -345,10 +531,15 @@ async function assembleRoundContext(params) {
             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), ctx.toolResults);
+                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)) {
@@ -381,6 +572,50 @@ async function assembleRoundContext(params) {
     ctx.loopCtx = loopCtx;
     return ctx;
 }
+/**
+ * Run the loop to settlement, then apply stop hooks at the natural loop end (plan 106 R1). Each
+ * `continue` queues its reason through the steer path and re-enters the loop with a continuation
+ * context whose `input`/`inputMessages` are empty — the continuation message is already in
+ * `history`, and replaying run-start input would duplicate it. A loop ceiling, a host turn-policy
+ * stop, or an artifact failure is not a natural end: hooks never run there, and a continuation leg
+ * that hits a ceiling ends the run instead of asking again. `limits.maxStopContinuations`
+ * (default 3; `0` observes only; `null` uncapped) bounds continuations as a clean `hook_limit` stop.
+ */
+async function runLoopWithStopHooks(ctx) {
+    let usage = await runLoopUntilSettled(ctx);
+    assertArtifactOutcome(ctx);
+    // Zero overhead when nothing is configured: no wrapper state, no reads.
+    if (ctx.stopHooks.length === 0)
+        return usage;
+    const cap = ctx.limits.limits.maxStopContinuations;
+    let continuations = 0;
+    let stopHookActive = false;
+    for (;;) {
+        if (ctx.runStop !== undefined || ctx.loopCtx.finishReason !== undefined)
+            return usage;
+        const decision = await evaluateStopHooks(ctx, stopHookActive);
+        if (!decision)
+            return usage;
+        if (cap !== null && continuations >= cap) {
+            ctx.loopCtx.finishReason = "hook_limit";
+            return usage;
+        }
+        continuations += 1;
+        stopHookActive = true;
+        queueStopHookContinuation(ctx, decision);
+        const continuationCtx = { ...ctx.loopCtx, input: [], inputMessages: [], continuation: true };
+        try {
+            usage = await runLoopUntilSettled({ ...ctx, loopCtx: continuationCtx });
+        }
+        finally {
+            // The loops set `finishReason` on the context they receive; carry it back so the ceiling
+            // survives onto the result, the finish record, and `persistSucceeded`.
+            if (continuationCtx.finishReason !== undefined)
+                ctx.loopCtx.finishReason = continuationCtx.finishReason;
+        }
+        assertArtifactOutcome(ctx);
+    }
+}
 export async function executeRun(session, input, options, runId, resumed) {
     const legacyMaxToolRounds = options.maxToolRounds;
     if (legacyMaxToolRounds !== undefined) {
@@ -398,6 +633,8 @@ 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 stopHooks = [...(session.agent.config.stopHooks ?? []), ...(options.stopHooks ?? [])];
+    assertStopHooks(stopHooks);
     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");
@@ -431,8 +668,14 @@ 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.activeDurable = resumed ?? (durableOptions ? { options: durableOptions, version: 0 } : undefined);
+    // Plan 104 T3: an `ask` rule is gated at charge time when the run can suspend; a run that cannot
+    // suspend enforces the same rule as a plain block, so it joins the ordinary stage guardrails.
+    const packGuardrails = session.activeDurable ? session.packGuardrails : mergeGuardrails(session.packGuardrails, session.packAskBlocks);
+    session.activeGuardrails = mergeGuardrails(mergeGuardrails(session.agent.config.guardrails, packGuardrails), options.guardrails);
+    // 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();
@@ -462,6 +705,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 {
@@ -478,6 +722,7 @@ export async function executeRun(session, input, options, runId, resumed) {
             metadata,
             limits,
             runUsage,
+            stopHooks,
         });
         await replayDurableNestedAndPending(ctx);
         const resumedLoopState = resumed?.state?.loopState;
@@ -487,7 +732,7 @@ export async function executeRun(session, input, options, runId, resumed) {
             }
             ctx.loop.restore?.(resumedLoopState.snapshot);
         }
-        const loopUsage = await runLoopUntilSettled(ctx).catch((error) => {
+        const loopUsage = await runLoopWithStopHooks(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)
@@ -496,12 +741,6 @@ export async function executeRun(session, input, options, runId, resumed) {
         });
         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",
-            });
-        }
         usage = runUsage.value() ?? loopUsage;
         return await persistSucceeded(ctx, loopUsage);
     }
@@ -513,8 +752,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, {

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

@@ -28,6 +28,17 @@ export declare function checkpointDurableTurn(session: SessionHost, input: {
     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;

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

@@ -1,5 +1,5 @@
 /** Finalize/persist phase of runInternal (plan 059). */
-import { boundedLoopSnapshot, initialAgentRunState, publicState, saveAgentRunState } from "../../agent-run-state.js";
+import { boundedLoopSnapshot, initialAgentRunState, publicState, resolveCheckpointMetadata, saveAgentRunState, } from "../../agent-run-state.js";
 import { AgentRunStateError } from "../../contracts.js";
 import { redactRunLedgerRecord } from "../../redaction.js";
 import { isFlushableRunLedger } from "../../run-ledger.js";
@@ -10,13 +10,20 @@ export async function persistDurable(session, state) {
     if (!durable)
         throw new AgentRunStateError("Durable run state is not configured");
     const withGrant = session.activeToolNames !== undefined ? { ...state, toolNames: session.activeToolNames } : state;
-    const attentionSticky = session.serializedAttentionSticky();
-    const persisted = durable.options.persistSessionState
-        ? {
-            ...withGrant,
-            sessionState: {
+    const persistSessionState = durable.options.persistSessionState === true;
+    // Plan 086 T3: durable folding owns its two keys. A run that opted into `durable` writes the
+    // fold ledger and its frontier even when the broader session-state bag stays off; a run that
+    // did not keeps exactly today's bytes, where the frontier rides `persistSessionState`.
+    const attentionSticky = persistSessionState || session.attentionDurable ? session.serializedAttentionSticky() : undefined;
+    const attentionFold = session.attentionDurable ? session.serializedAttentionFold() : undefined;
+    // Plan 104 T2: pack refs and pack-owned state; the key only exists under the same opt-in, so a
+    // default checkpoint keeps exactly today's bytes.
+    const guardrailPacks = persistSessionState ? session.serializedGuardrailPackState() : undefined;
+    const sessionState = {
+        ...(persistSessionState
+            ? {
                 loadedSkillNames: session.loadedSkills.list(),
-                ...(attentionSticky ? { attentionSticky } : {}),
+                ...(guardrailPacks ? { guardrailPacks } : {}),
                 ...(session.activatedTools.list().length ? { activatedToolNames: session.activatedTools.list() } : {}),
                 ...(durable.options.includeSkillBodies
                     ? {
@@ -25,9 +32,13 @@ export async function persistDurable(session, state) {
                             : undefined),
                     }
                     : {}),
-            },
-        }
-        : withGrant;
+            }
+            : {}),
+        ...(attentionSticky ? { attentionSticky } : {}),
+        ...(attentionFold ? { attentionFold } : {}),
+    };
+    const persisted = Object.keys(sessionState).length > 0 ? { ...withGrant, sessionState } : withGrant;
+    const metadata = resolveCheckpointMetadata(durable.options.checkpointMetadata) ?? durable.checkpointMetadata;
     const saved = await saveAgentRunState({
         checkpoints: durable.options.checkpoints,
         state: persisted,
@@ -36,6 +47,7 @@ export async function persistDurable(session, state) {
         fencingToken: durable.options.fencingToken,
         redactor: session.activeRedactor,
         maxStateBytes: durable.options.maxStateBytes,
+        ...(metadata ? { metadata } : {}),
     });
     durable.state = saved.state;
     durable.version = saved.record.version;
@@ -86,8 +98,25 @@ export async function suspendDurable(session, input) {
  * into a resumed run, and loop-local state rides along exactly as it does at suspension.
  */
 export async function checkpointDurableTurn(session, input) {
+    if (session.activeDurable?.options.checkpointPolicy !== "every-turn")
+        return;
+    await writeRunningCheckpoint(session, input);
+}
+/**
+ * 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 async function checkpointDurableFold(session, input) {
+    if (!session.attentionDurable)
+        return;
+    await writeRunningCheckpoint(session, input);
+}
+/** Shared running-checkpoint write for the turn-boundary and fold-boundary triggers. */
+async function writeRunningCheckpoint(session, input) {
     const durable = session.activeDurable;
-    if (durable?.options.checkpointPolicy !== "every-turn")
+    if (!durable)
         return;
     const loop = session.activeLoop;
     const loopState = loop?.snapshot ? boundedLoopSnapshot(loop.name, loop.revision ?? "1", loop.snapshot()) : undefined;
@@ -135,19 +164,21 @@ export async function persistSucceeded(ctx, loopUsage) {
         await session.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, session.activeRedactor));
     }
     await session.drainLedger();
+    // Plan 084 Task 2 / plan 106 R1: a clean run-end stop keeps the frontier and marks the state
+    // continuable — a host turn-policy stop (`host_policy`) or a stop-hook continuation cap
+    // (`hook_limit`). Every other succeeded state drops its loop state and is final.
+    const continuableStop = stop ? "host_policy" : ctx.loopCtx.finishReason === "hook_limit" ? "hook_limit" : undefined;
     const runState = session.activeDurable?.state
         ? await persistDurable(session, {
             ...session.activeDurable.state,
             status: "succeeded",
-            // Plan 084 Task 2: a host-policy stop is terminal for the run but leaves the frontier
-            // intact — the loop state is kept and the state is marked continuable.
-            ...(stop ? { stopReason: "host_policy", leafId: session.currentLeafId } : {}),
+            ...(continuableStop ? { stopReason: continuableStop, leafId: session.currentLeafId } : {}),
             pending: undefined,
             pendingCalls: undefined,
             nestedRuns: undefined,
             stickyDecisions: undefined,
             interruption: undefined,
-            ...(stop ? {} : { loopState: undefined }),
+            ...(continuableStop ? {} : { loopState: undefined }),
         })
         : undefined;
     session.emit({
@@ -216,11 +247,12 @@ export async function cleanupRun(input) {
         session.activeLimits?.dispose();
         session.activeToolNames = undefined;
         session.activeLimits = undefined;
+        session.activeRecentToolCalls = undefined;
         session.activeLimitOutputBuffer = false;
         session.activeRedactor = undefined;
         session.activeProvider = undefined;
         cleanupSignal();
-        session.closeSubscribers();
+        session.closeRunSubscribers();
     }
 }
 //# sourceMappingURL=persist.js.map

package/dist/agent-session/session/provider-round.d.ts

@@ -1,6 +1,16 @@
 /** Provider-round phase of runInternal (plan 059). */
-import type { ProviderRequest, ProviderTurnResult, RunOptions, ToolResult, Usage } from "../../contracts.js";
+import type { ModelConfig, ProviderRequest, ProviderTurnResult, RunOptions, ToolResult, Usage } from "../../contracts.js";
 import type { RoundContext, SessionHost } from "./types.js";
-export declare function recordProviderUsage(ctx: RoundContext, turnUsage: Usage | undefined, turn: number, attempt: number): Promise<void>;
-export declare function generateWithRetry(session: SessionHost, request: ProviderRequest, runId: string, options: RunOptions, signal: AbortSignal, requestSecrets?: readonly (string | undefined)[], turn?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>, toolResults?: readonly ToolResult[]): Promise<ProviderTurnResult>;
-export declare function generateProviderTurn(session: SessionHost, request: ProviderRequest, runId: string, signal: AbortSignal, secrets?: readonly (string | undefined)[], turn?: number, attempt?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>, toolResults?: readonly ToolResult[]): Promise<ProviderTurnResult>;
+/** Resolve the per-request input cap for turn-budget metadata (plan 087 T1). A model without a
+ *  derivable cap (or a bad attention setting on an unrelated run) omits the field instead of
+ *  failing an emitting turn; the attention compiler, when enabled, is the cap authority. */
+export declare function resolveTurnInputCap(session: SessionHost, model: ModelConfig): number | undefined;
+export declare function recordProviderUsage(ctx: RoundContext, turnUsage: Usage | undefined, turn: number, attempt: number, request?: ProviderRequest): Promise<Usage | undefined>;
+/**
+ * Plan 096: host middleware may answer the turn deterministically at the `beforeProviderTurn` seam —
+ * no provider request, no usage, mandatory provenance. `undefined` sends the turn to the provider
+ * unchanged; a malformed answer fails the run closed instead of falling through to the provider.
+ */
+export declare function resolveDeterministicTurn(session: SessionHost, request: ProviderRequest, runId: string, turn: number, signal: AbortSignal, toolResults?: readonly ToolResult[]): Promise<ProviderTurnResult | undefined>;
+export declare function generateWithRetry(session: SessionHost, request: ProviderRequest, runId: string, options: RunOptions, signal: AbortSignal, requestSecrets?: readonly (string | undefined)[], turn?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<Usage | undefined>, toolResults?: readonly ToolResult[]): Promise<ProviderTurnResult>;
+export declare function generateProviderTurn(session: SessionHost, request: ProviderRequest, runId: string, signal: AbortSignal, secrets?: readonly (string | undefined)[], turn?: number, attempt?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<Usage | undefined>, toolResults?: readonly ToolResult[]): Promise<ProviderTurnResult>;