@arnilo/prism 0.8.0 → 0.9.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
@@ -140,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,
@@ -176,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,
@@ -215,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;
@@ -272,6 +307,8 @@ async function assembleRoundContext(params) {
         runUsage,
         loopCtx: undefined,
     };
+    const toolNarrowing = options.toolNarrowing ?? session.agent.config.toolNarrowing;
+    let narrowedForTurn;
     const loopCtx = {
         sessionId: session.id,
         runId,
@@ -285,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,
@@ -308,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,
@@ -323,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),
@@ -345,10 +428,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)) {
@@ -431,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();
@@ -462,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 {
@@ -513,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, {

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,16 @@ 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;
+    const sessionState = {
+        ...(persistSessionState
+            ? {
                 loadedSkillNames: session.loadedSkills.list(),
-                ...(attentionSticky ? { attentionSticky } : {}),
                 ...(session.activatedTools.list().length ? { activatedToolNames: session.activatedTools.list() } : {}),
                 ...(durable.options.includeSkillBodies
                     ? {
@@ -25,9 +28,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 +43,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 +94,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;
@@ -216,6 +241,7 @@ 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;

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>;