@arnilo/prism 0.8.0 → 0.9.0

package/dist/agent-session/session/provider-round.js

@@ -1,9 +1,14 @@
 /** Provider-round phase of runInternal (plan 059). */
+import { resolveInputCap } from "../../attention-compiler.js";
+import { cacheUsageReport } from "../../cache-helpers.js";
+import { estimateMessageTokens } from "../../context-budget.js";
 import { assertGuardrailsAllowed, GuardrailError, runGuardrails } from "../../guardrails.js";
+import { validateDeterministicTurnAnswer } from "../../middleware.js";
 import { createProviderTurnMetadata, readProviderHttpStatus } from "../../observability.js";
 import { providerError, providerToolCallDeltaContent } from "../../provider-events.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "../../redaction.js";
 import { createDefaultRetryPolicy, waitForRetry } from "../../retry.js";
+import { estimateTextTokensForFamily } from "../../usage-estimation.js";
 import { bridgeAbort, errorFromInfo, isSteerSoftInterrupt, jsonBytes, mergeRetry, ProviderTurnFailure, providerContent, randomId, reconstructMissingToolCalls, SteerSoftInterrupt, throwIfAborted, } from "../helpers.js";
 function pushCoalescedContent(content, block) {
     const last = content.at(-1);
@@ -21,6 +26,49 @@ function pushCoalescedContent(content, block) {
     }
     content.push(block);
 }
+/** 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 function resolveTurnInputCap(session, model) {
+    const setting = session.agent.config.attentionCompiler;
+    const options = typeof setting === "object" && setting !== null ? setting : undefined;
+    try {
+        return resolveInputCap(options ? { maxInputTokens: options.maxInputTokens, reserveTokens: options.reserveTokens } : {}, model);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Effective budget snapshot at turn end (plan 087 T1): O(1) from the run limit tracker. */
+function turnBudgets(session, model, usage) {
+    const tracker = session.activeLimits;
+    if (!tracker)
+        return undefined;
+    const snapshot = tracker.snapshot();
+    const inputCap = resolveTurnInputCap(session, model);
+    const runInputBudget = tracker.limits.maxInputTokens;
+    return {
+        ...(usage?.inputTokens === undefined ? {} : { inputTokens: usage.inputTokens }),
+        ...(inputCap === undefined ? {} : { inputCap }),
+        ...(runInputBudget === null ? {} : { runInputBudget }),
+        runInputUsed: snapshot.inputTokens,
+        turns: snapshot.turns,
+        maxTurns: tracker.limits.maxTurns,
+    };
+}
+function cacheMetadata(usage) {
+    const cache = cacheUsageReport(usage);
+    return cache === undefined ? {} : { cache };
+}
+/** Native reason wins, except a generic `end_turn` on a turn that produced tool calls: protocols
+ *  with one generic completion value (Google `STOP`) are tool-call turns by content (plan 087 T1). */
+function normalizeTurnStopReason(native, calls) {
+    if (native === undefined)
+        return calls.length > 0 ? "tool_calls" : "end_turn";
+    if (native === "end_turn" && calls.length > 0)
+        return "tool_calls";
+    return native;
+}
 /**
  * Plan 062: price usage through the host's {@link CostCatalog} when the provider
  * did not report a cost itself. Stale/unknown quotes, catalog failures, or
@@ -46,17 +94,22 @@ async function withCatalogCost(catalog, model, usage, signal) {
         return usage; // catalog failure degrades to usage-only
     }
 }
-export async function recordProviderUsage(ctx, turnUsage, turn, attempt) {
+export async function recordProviderUsage(ctx, turnUsage, turn, attempt, request) {
     const { session, limits, runUsage, runId } = ctx;
-    const usage = turnUsage
-        ? await withCatalogCost(session.agent.config.costCatalog, ctx.model, turnUsage, ctx.controller.signal)
-        : undefined;
-    limits.recordUsage(usage);
-    if (!usage)
-        return;
-    runUsage.add(usage);
+    const usage = turnUsage ?? estimateTurnUsage(session, ctx.model, request);
+    // An estimate is never priced: a catalog quote on estimated tokens would invent billing.
+    const effective = usage && usage.estimated !== true
+        ? await withCatalogCost(session.agent.config.costCatalog, ctx.model, usage, ctx.controller.signal)
+        : usage;
+    limits.recordUsage(effective);
+    if (!effective)
+        return undefined;
+    if (effective.inputTokens !== undefined) {
+        session.activeInputMeter = { tokens: effective.inputTokens, source: effective.estimated === true ? "estimated" : "reported" };
+    }
+    runUsage.add(effective);
     if (!session.activeLedger)
-        return;
+        return effective;
     const usageRecord = {
         id: randomId("usage"),
         sessionId: session.id,
@@ -64,11 +117,103 @@ export async function recordProviderUsage(ctx, turnUsage, turn, attempt) {
         scope: "provider_turn",
         turn,
         attempt,
-        usage,
+        usage: effective,
         recordedAt: new Date().toISOString(),
         ...session.activeOwnership,
     };
     await session.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, session.activeRedactor));
+    return effective;
+}
+/**
+ * Plan 091 T2 missing-usage fallback: when the provider reported nothing and the
+ * agent did not turn estimation off, label an estimate of the turn's own request
+ * (messages + tool declarations + context blocks). Returns `undefined` when
+ * estimation is off or the request is unavailable — absent stays absent.
+ */
+function estimateTurnUsage(session, model, request) {
+    if (!request || session.agent.config.usageEstimation === "off")
+        return undefined;
+    const estimate = estimateMessageTokens(request.messages, model.model);
+    const extras = request.tools?.length || request.context?.length ? JSON.stringify({ tools: request.tools, context: request.context }) : undefined;
+    return {
+        inputTokens: estimate.tokens + (extras === undefined ? 0 : estimateTextTokensForFamily(extras, model.model)),
+        estimated: true,
+        confidence: estimate.confidence,
+    };
+}
+/** Latest user-role text in the assembled request; steered messages included. */
+function lastUserText(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message?.role !== "user")
+            continue;
+        return message.content.map((block) => (block.type === "text" ? block.text : "")).join("");
+    }
+    return "";
+}
+/**
+ * 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 async function resolveDeterministicTurn(session, request, runId, turn, signal, toolResults = []) {
+    const middleware = session.agent.config.middleware;
+    if (!middleware)
+        return undefined;
+    const payload = await middleware.run("beforeProviderTurn", {
+        sessionId: session.id,
+        runId,
+        turn,
+        userText: lastUserText(request.messages),
+    });
+    const answer = payload?.answer;
+    if (answer === undefined)
+        return undefined;
+    const validated = validateDeterministicTurnAnswer(answer);
+    throwIfAborted(signal);
+    const messageId = randomId("msg");
+    // Same response-byte axis as provider output: a host answer must not bypass a run ceiling.
+    session.activeLimits?.charge("maxResponseBytes", jsonBytes(validated.content));
+    if (session.activeGuardrails?.output?.length) {
+        assertGuardrailsAllowed(await runGuardrails({
+            stage: "output",
+            guardrails: session.activeGuardrails,
+            value: { content: validated.content, calls: [], messageId, started: true, usage: undefined },
+            context: {
+                sessionId: session.id,
+                runId,
+                metadata: session.activeMetadata ?? {},
+                signal,
+                toolResults,
+            },
+            redactor: session.activeRedactor,
+            emit: (event) => session.emit(event),
+        }));
+    }
+    session.emit({
+        type: "deterministic_turn",
+        sessionId: session.id,
+        runId,
+        turn,
+        middleware: validated.provenance.middleware,
+    });
+    session.emit({
+        type: "message_started",
+        sessionId: session.id,
+        runId,
+        message: { id: messageId, role: "assistant", content: [] },
+    });
+    for (const block of validated.content)
+        session.emit({ type: "message_delta", sessionId: session.id, runId, content: block });
+    // Provenance rides the message into the store (plan 096 Task 2): the transcript alone proves no model ran.
+    return {
+        content: validated.content,
+        calls: [],
+        messageId,
+        started: true,
+        usage: undefined,
+        metadata: { deterministic: validated.provenance },
+    };
 }
 export async function generateWithRetry(session, request, runId, options, signal, requestSecrets = [], turn = 1, recordUsage, toolResults = []) {
     const retry = mergeRetry(session.agent.config.retry, options.retry);
@@ -119,7 +264,9 @@ export async function generateProviderTurn(session, request, runId, signal, secr
     let messageId;
     let started = false;
     let usage;
+    let nativeStopReason;
     let usageRecorded = false;
+    let effectiveUsage;
     const bufferedOutput = [];
     const bufferOutput = Boolean(session.activeGuardrails?.output?.length || session.activeLimitOutputBuffer);
     const emitOutput = (event) => {
@@ -130,9 +277,11 @@ export async function generateProviderTurn(session, request, runId, signal, secr
     };
     const recordTurnUsage = async () => {
         if (usageRecorded)
-            return;
+            return effectiveUsage;
         usageRecorded = true;
-        await recordUsage?.(usage, turn, attempt);
+        // The seam may return a labeled estimate (plan 091 T2); without a callback the reported value stands.
+        effectiveUsage = (await recordUsage?.(usage, turn, attempt)) ?? usage;
+        return effectiveUsage;
     };
     const turnAbort = new AbortController();
     const cleanupTurn = bridgeAbort(signal, turnAbort);
@@ -153,6 +302,7 @@ export async function generateProviderTurn(session, request, runId, signal, secr
                 usage = event.usage;
             if (event.type === "done") {
                 usage = event.usage ?? usage;
+                nativeStopReason = event.stopReason;
                 break;
             }
             if (event.type === "message_start") {
@@ -209,10 +359,15 @@ export async function generateProviderTurn(session, request, runId, signal, secr
             sessionId: session.id,
             runId,
             turn,
-            metadata: buildMetadata({ latencyMs }),
-            usage,
+            metadata: buildMetadata({
+                latencyMs,
+                stopReason: normalizeTurnStopReason(nativeStopReason, calls),
+                budgets: turnBudgets(session, request.model, effectiveUsage),
+                ...cacheMetadata(effectiveUsage),
+            }),
+            usage: effectiveUsage,
         });
-        return { content, calls, messageId, started, usage };
+        return { content, calls, messageId, started, usage: effectiveUsage };
     }
     catch (error) {
         if (isSteerSoftInterrupt(error) || isSteerSoftInterrupt(turnAbort.signal.reason)) {
@@ -223,8 +378,13 @@ export async function generateProviderTurn(session, request, runId, signal, secr
                 sessionId: session.id,
                 runId,
                 turn,
-                metadata: buildMetadata({ latencyMs }),
-                usage,
+                metadata: buildMetadata({
+                    latencyMs,
+                    stopReason: "abort",
+                    budgets: turnBudgets(session, request.model, effectiveUsage),
+                    ...cacheMetadata(effectiveUsage),
+                }),
+                usage: effectiveUsage,
             });
             throw new SteerSoftInterrupt();
         }
@@ -236,8 +396,14 @@ export async function generateProviderTurn(session, request, runId, signal, secr
             sessionId: session.id,
             runId,
             turn,
-            metadata: buildMetadata({ latencyMs, httpStatus: readProviderHttpStatus(info) }),
-            usage,
+            metadata: buildMetadata({
+                latencyMs,
+                httpStatus: readProviderHttpStatus(info),
+                stopReason: signal.aborted || turnAbort.signal.aborted ? "abort" : "provider_error",
+                budgets: turnBudgets(session, request.model, effectiveUsage),
+                ...cacheMetadata(effectiveUsage),
+            }),
+            usage: effectiveUsage,
             error: info,
         });
         if (error instanceof GuardrailError || error instanceof ProviderTurnFailure)

package/dist/agent-session/session/tool-round.js

@@ -238,6 +238,24 @@ export function bindChargeToolRound(ctx) {
         }
     };
 }
+/** Last-N dispatched tool calls kept for `budget_exhausted` attribution (plan 087 T2); the hash
+ *  is the same canonical arguments hash the effect store uses, so raw args never enter events. */
+const RECENT_TOOL_CALL_LIMIT = 10;
+function recordRecentToolCall(session, call) {
+    const recent = (session.activeRecentToolCalls ??= []);
+    recent.push({ id: call.id, name: call.name, argHash: `sha256:${toolEffectArgumentsHash(call.arguments)}` });
+    if (recent.length > RECENT_TOOL_CALL_LIMIT)
+        recent.shift();
+}
+function dispatchFilter(ctx) {
+    const hiddenOk = ctx.options.allowHiddenToolCalls ?? ctx.session.agent.config.allowHiddenToolCalls;
+    if (hiddenOk || ctx.turnAllow === undefined) {
+        return ctx.tools.length > 0 ? { filter: { allow: ctx.tools.map((tool) => tool.name) } } : {};
+    }
+    if (ctx.turnAllow.length > 0)
+        return { filter: { allow: ctx.turnAllow } };
+    return ctx.tools.length > 0 ? { filter: { deny: ctx.tools.map((tool) => tool.name) } } : {};
+}
 export function bindDispatchToolCall(ctx) {
     return async (call) => {
         const sticky = matchStickyDecision(ctx.session, call, ctx.registry);
@@ -252,6 +270,7 @@ export function bindDispatchToolCall(ctx) {
             return { toolCallId: call.id, name: call.name, metadata: { approvalPending: true } };
         }
         ctx.toolCalls += 1;
+        recordRecentToolCall(ctx.session, call);
         try {
             const result = await dispatchToolCall({
                 call,
@@ -279,7 +298,7 @@ export function bindDispatchToolCall(ctx) {
                 ownership: ctx.session.activeOwnership,
                 identity: ctx.session.activeIdentity,
                 guardrails: ctx.session.activeGuardrails,
-                ...(ctx.tools.length > 0 ? { filter: { allow: ctx.tools.map((tool) => tool.name) } } : {}),
+                ...dispatchFilter(ctx),
                 limitTracker: ctx.limits,
                 beforeExecute: async (mediatedCall) => {
                     const durable = ctx.session.activeDurable;

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

@@ -1,8 +1,8 @@
 /** Shared host/round types for runInternal phase split (plan 059). Internal only. */
 import type { ActiveDurableRun } from "../../agent-approval.js";
 import type { PendingToolCall } from "../../agent-run-state.js";
-import type { AttentionStickyFrontier, PersistedAttentionStickyFrontier } from "../../attention-compiler.js";
-import type { Agent, AgentEvent, AgentFinishReason, AgentLoopStrategy, AgentRunResult, AIProvider, ErrorInfo, Guardrails, LoopContext, Message, ModelConfig, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunLedger, RunOptions, SessionEntry, SessionStore, Skill, ToolDefinition, ToolEffectStore, ToolRegistry, ToolResult, Usage } from "../../contracts.js";
+import type { AttentionFoldLedger, AttentionStickyFrontier, PersistedAttentionFoldLedger, PersistedAttentionStickyFrontier } from "../../attention-compiler.js";
+import type { Agent, AgentEvent, AgentFinishReason, AgentLoopStrategy, AgentRunResult, AIProvider, ErrorInfo, Guardrails, LoopContext, Message, ModelConfig, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunLedger, RunOptions, SessionEntry, SessionStore, Skill, ToolCallSummary, ToolDefinition, ToolEffectStore, ToolRegistry, ToolResult, Usage } from "../../contracts.js";
 import type { AgentIdentity } from "../../identity.js";
 import type { AgentInput } from "../../input.js";
 import type { SecretRedactor } from "../../redaction.js";
@@ -33,9 +33,19 @@ export type SessionHost = {
     activeIdentity?: AgentIdentity;
     activeIdempotencyKey?: string;
     activeGuardrails?: Guardrails;
+    /** Plan 092 Task 2: packs compiled once at session construction; read-only for phases. */
+    readonly packGuardrails?: Guardrails;
     activeMetadata?: Readonly<Record<string, unknown>>;
     activePromptVersion?: PromptVersionRef;
     activeLimits?: RunLimitTracker;
+    /** Plan 091 T2: input tokens of the latest provider turn plus whether the
+     *  provider reported them. Set by the usage seam; read by `contextMeter()`. */
+    activeInputMeter?: {
+        readonly tokens: number;
+        readonly source: "reported" | "estimated";
+    };
+    /** Bounded last-N tool-call summaries of the active run (plan 087 T2): ids, names, arg hashes. */
+    activeRecentToolCalls?: ToolCallSummary[];
     activeLimitOutputBuffer: boolean;
     activeDurable?: ActiveDurableRun;
     activeLoop?: AgentLoopStrategy;
@@ -45,6 +55,8 @@ export type SessionHost = {
     }>;
     activeLoopTurn: number;
     readonly loadedSkills: LoadedSkillSet;
+    /** Run-owned monotonic prompt tail; cleared before each new run. */
+    readonly tailSegments: Map<string, Message>;
     readonly activatedTools: ActiveToolSet;
     restoredSkillBodies: readonly LoadedSkillBodiesEntry[];
     activeRunSkills: readonly Skill[];
@@ -57,6 +69,15 @@ export type SessionHost = {
     serializedAttentionSticky(): PersistedAttentionStickyFrontier | undefined;
     /** Plan 074 P3: restore a frontier that was validated when the checkpoint was loaded. */
     restoreAttentionSticky(persisted: PersistedAttentionStickyFrontier): void;
+    /** Folded bodies for this session (plan 086 T3); session-owned so a resumed fold re-applies
+     *  the same stub bytes instead of calling the host `summarize` again. Lazily created. */
+    attentionFoldFor(): AttentionFoldLedger;
+    /** Plan 086 T3: bounded ledger snapshot for a durable checkpoint (undefined before any fold). */
+    serializedAttentionFold(): PersistedAttentionFoldLedger | undefined;
+    /** Plan 086 T3: adopt a ledger validated when the checkpoint was loaded. */
+    restoreAttentionFold(ledger: AttentionFoldLedger): void;
+    /** Plan 086 T3: `attention.compiler.durable` for the current run; set by the run assembler. */
+    attentionDurable: boolean;
     invalidateSnapshot(): void;
     resolveRunProvider(options: RunOptions): void;
     emit(event: AgentEvent): void;
@@ -116,6 +137,8 @@ export type RoundContext = {
     loop: AgentLoopStrategy;
     toolConcurrency: number;
     toolsDisclosure: import("../../tool-search.js").ToolsDisclosure;
+    /** Per-turn dispatch overlay; undefined when `toolNarrowing` is unset. */
+    turnAllow?: readonly string[];
     assembledTurn: boolean;
     artifactFinished: boolean;
     artifactFailedInfo: {

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

@@ -1,8 +1,8 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
-import { ActiveDurableRun } from "../agent-approval.js";
+import { ActiveDurableRun, ActiveDurableRunExtras } from "../agent-approval.js";
 import type { PendingToolCall, StoredAgentRunState } from "../agent-run-state.js";
-import { type AttentionStickyFrontier, type PersistedAttentionStickyFrontier } from "../attention-compiler.js";
-import type { Agent, AgentEvent, AgentRunResult, AgentRunState, AgentRunStateOptions, AgentSession, AgentSessionConfig, AIProvider, CompactionOptions, CompactionResult, ErrorInfo, Message, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunDecision, RunOptions, SessionEntry, Skill, SteerOptions, SubscribeOptions, ToolDefinition, ToolEffectStore, Usage } from "../contracts.js";
+import { type AttentionFoldLedger, type AttentionStickyFrontier, type PersistedAttentionFoldLedger, type PersistedAttentionStickyFrontier } from "../attention-compiler.js";
+import type { Agent, AgentEvent, AgentRunResult, AgentRunState, AgentRunStateOptions, AgentSession, AgentSessionConfig, AIProvider, CompactionOptions, CompactionResult, ContextMeter, ErrorInfo, Guardrails, Message, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunDecision, RunOptions, SessionEntry, Skill, SteerOptions, SubscribeOptions, ToolCallSummary, ToolDefinition, ToolEffectStore, Usage } from "../contracts.js";
 import type { AgentIdentity } from "../identity.js";
 import type { AgentInput } from "../input.js";
 import type { RunLimitTracker } from "../run-limits.js";
@@ -30,9 +30,21 @@ export declare class RuntimeAgentSession implements AgentSession {
     activeIdentity?: AgentIdentity;
     private activeIdempotencyKey?;
     private activeGuardrails?;
+    /** Plan 092 Task 2: guardrail packs compiled once in the constructor; merged into every run's `activeGuardrails`. */
+    readonly packGuardrails?: Guardrails;
+    /** Original pack refs, carried into `fork()`/`clone()` so a branch cannot silently lose its policy. */
+    private readonly guardrailPackRefs?;
     activeMetadata?: Readonly<Record<string, unknown>>;
     activePromptVersion?: PromptVersionRef;
     activeLimits?: RunLimitTracker;
+    /** Plan 091 T2: input tokens of the latest provider turn plus whether the provider reported
+     *  them; set by the usage seam, read by `contextMeter()`. */
+    activeInputMeter?: {
+        readonly tokens: number;
+        readonly source: "reported" | "estimated";
+    };
+    /** Bounded last-N tool-call summaries of the active run (plan 087 T2): ids, names, arg hashes. */
+    activeRecentToolCalls?: ToolCallSummary[];
     activeLimitOutputBuffer: boolean;
     activeDurable?: ActiveDurableRun;
     activeLoop?: import("../contracts.js").AgentLoopStrategy;
@@ -43,6 +55,8 @@ export declare class RuntimeAgentSession implements AgentSession {
     }>;
     activeLoopTurn: number;
     private readonly loadedSkills;
+    /** Run-owned only: loaded bodies and URI resources retain first insertion order within one provider loop. */
+    readonly tailSegments: Map<string, Message>;
     /** Tools activated via `search_tools` this session (plan 041); names-only in persistence. */
     readonly activatedTools: import("../tool-search.js").ActiveToolSet;
     /** Plan 018 Task 6 (closeout `checkpoint-bodies`): persisted exact instructions, registry-independent. */
@@ -62,6 +76,17 @@ export declare class RuntimeAgentSession implements AgentSession {
     /** Plan 074 P3: restore a frontier validated at checkpoint load, so a resumed run keeps its
      *  stubs instead of re-deciding its first turn from the ratio. */
     restoreAttentionSticky(persisted: PersistedAttentionStickyFrontier): void;
+    /** Session-owned folded bodies (plan 086 T3); created on first use like the frontier, so a
+     *  compiler-off session allocates nothing. */
+    private attentionFold?;
+    /** Set per run from the resolved compiler: `durable: true` opts the fold ledger and its
+     *  frontier into checkpoints even when `persistSessionState` is off. */
+    attentionDurable: boolean;
+    attentionFoldFor(): AttentionFoldLedger;
+    /** Plan 086 T3: bounded ledger snapshot for a durable checkpoint; `undefined` before any fold. */
+    serializedAttentionFold(): PersistedAttentionFoldLedger | undefined;
+    /** Plan 086 T3: adopt a ledger validated at checkpoint load, so a resumed fold is byte-identical. */
+    restoreAttentionFold(ledger: AttentionFoldLedger): void;
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names: readonly string[]): void;
     /** Plan 041: re-add persisted activated-tool names (names only; inert for absent tools). */
@@ -79,10 +104,19 @@ export declare class RuntimeAgentSession implements AgentSession {
         readonly agent: Agent;
     });
     get leafId(): string | undefined;
+    /**
+     * Context-fill read (plan 091 T2): the latest provider turn's input tokens —
+     * provider-reported when it reported, else a labeled estimate — plus the
+     * per-request cap and cumulative run input budget, resolved exactly as
+     * `provider_turn_finished.budgets` resolves them. Before any provider turn in
+     * this session it estimates stored history, so a non-reporting model still
+     * shows a working meter instead of zero. Never billing; estimates are labeled.
+     */
+    contextMeter(): ContextMeter;
     subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
     run(input: AgentInput, options?: RunOptions): Promise<AgentRunResult>;
     steer(input: AgentInput, options?: SteerOptions): void;
-    resumeDurable(state: StoredAgentRunState, runState: AgentRunStateOptions, ownership?: OwnershipScope, signal?: AbortSignal, decisions?: ReadonlyMap<string, RunDecision>): Promise<AgentRunResult>;
+    resumeDurable(state: StoredAgentRunState, runState: AgentRunStateOptions, ownership?: OwnershipScope, signal?: AbortSignal, decisions?: ReadonlyMap<string, RunDecision>, extras?: ActiveDurableRunExtras): Promise<AgentRunResult>;
     recordDurableResumption(runId: string, interruption: import("../contracts.js").AgentRunInterruption, version: number, ownership?: OwnershipScope): Promise<void>;
     recordDurableDenial(runId: string, interruption: import("../contracts.js").AgentRunInterruption, version: number, ownership?: OwnershipScope): Promise<void>;
     private runInternal;

package/dist/agent-session/session.js

@@ -1,10 +1,10 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
 import { policyList } from "../agent-tool-dispatch.js";
-import { createAttentionStickyFrontier, resolveInputCap, restoreAttentionStickyFrontier, serializeAttentionStickyFrontier, } from "../attention-compiler.js";
+import { createAttentionFoldLedger, createAttentionStickyFrontier, resolveInputCap, restoreAttentionStickyFrontier, serializeAttentionFoldLedger, serializeAttentionStickyFrontier, } from "../attention-compiler.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "../compaction.js";
-import { estimateAssemblyTokens, estimateTextTokens } from "../context-budget.js";
+import { estimateAssemblyTokens, estimateMessageTokens, estimateTextTokens } from "../context-budget.js";
 import { DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, resolveShouldCompact, } from "../contracts.js";
-import { GuardrailError, runGuardrails } from "../guardrails.js";
+import { compileGuardrailPacks, GuardrailError, runGuardrails } from "../guardrails.js";
 import { applyDefaultProviderRequestOptions, createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult, } from "../provider-request-policy.js";
 import { redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "../redaction.js";
 import { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, rebuildSessionContext } from "../session-stores.js";
@@ -39,9 +39,18 @@ export class RuntimeAgentSession {
     activeIdentity;
     activeIdempotencyKey;
     activeGuardrails;
+    /** Plan 092 Task 2: guardrail packs compiled once in the constructor; merged into every run's `activeGuardrails`. */
+    packGuardrails;
+    /** Original pack refs, carried into `fork()`/`clone()` so a branch cannot silently lose its policy. */
+    guardrailPackRefs;
     activeMetadata;
     activePromptVersion;
     activeLimits;
+    /** Plan 091 T2: input tokens of the latest provider turn plus whether the provider reported
+     *  them; set by the usage seam, read by `contextMeter()`. */
+    activeInputMeter;
+    /** Bounded last-N tool-call summaries of the active run (plan 087 T2): ids, names, arg hashes. */
+    activeRecentToolCalls;
     activeLimitOutputBuffer = false;
     activeDurable;
     activeLoop;
@@ -49,6 +58,8 @@ export class RuntimeAgentSession {
     activeGatedRound;
     activeLoopTurn = 1;
     loadedSkills = createLoadedSkillSet();
+    /** Run-owned only: loaded bodies and URI resources retain first insertion order within one provider loop. */
+    tailSegments = new Map();
     /** Tools activated via `search_tools` this session (plan 041); names-only in persistence. */
     activatedTools = createActiveToolSet();
     /** Plan 018 Task 6 (closeout `checkpoint-bodies`): persisted exact instructions, registry-independent. */
@@ -77,6 +88,24 @@ export class RuntimeAgentSession {
     restoreAttentionSticky(persisted) {
         this.attentionSticky = restoreAttentionStickyFrontier(persisted);
     }
+    /** Session-owned folded bodies (plan 086 T3); created on first use like the frontier, so a
+     *  compiler-off session allocates nothing. */
+    attentionFold;
+    /** Set per run from the resolved compiler: `durable: true` opts the fold ledger and its
+     *  frontier into checkpoints even when `persistSessionState` is off. */
+    attentionDurable = false;
+    attentionFoldFor() {
+        this.attentionFold ??= createAttentionFoldLedger();
+        return this.attentionFold;
+    }
+    /** Plan 086 T3: bounded ledger snapshot for a durable checkpoint; `undefined` before any fold. */
+    serializedAttentionFold() {
+        return this.attentionFold && this.attentionFold.bodies.size > 0 ? serializeAttentionFoldLedger(this.attentionFold) : undefined;
+    }
+    /** Plan 086 T3: adopt a ledger validated at checkpoint load, so a resumed fold is byte-identical. */
+    restoreAttentionFold(ledger) {
+        this.attentionFold = ledger;
+    }
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names) {
         for (const name of names)
@@ -110,10 +139,46 @@ export class RuntimeAgentSession {
         this.store = config.store ?? config.agent.config.store ?? createMemorySessionStore();
         this.currentLeafId = config.leafId;
         this.snapshotCacheTtlMs = resolveSnapshotCacheTtlMs(config.snapshotCacheTtlMs);
+        this.packGuardrails = compileGuardrailPacks(config.guardrailPacks);
+        this.guardrailPackRefs = config.guardrailPacks;
+        const usageEstimation = config.agent.config.usageEstimation;
+        if (usageEstimation !== undefined && usageEstimation !== "fallback" && usageEstimation !== "off") {
+            throw new TypeError('usageEstimation must be "fallback" or "off"');
+        }
     }
     get leafId() {
         return this.currentLeafId;
     }
+    /**
+     * Context-fill read (plan 091 T2): the latest provider turn's input tokens —
+     * provider-reported when it reported, else a labeled estimate — plus the
+     * per-request cap and cumulative run input budget, resolved exactly as
+     * `provider_turn_finished.budgets` resolves them. Before any provider turn in
+     * this session it estimates stored history, so a non-reporting model still
+     * shows a working meter instead of zero. Never billing; estimates are labeled.
+     */
+    contextMeter() {
+        const model = this.agent.config.model;
+        const inputTokens = this.activeInputMeter?.tokens ?? estimateMessageTokens(this.history, model.model).tokens;
+        const source = this.activeInputMeter?.source ?? "estimated";
+        let inputCap;
+        try {
+            const setting = this.agent.config.attentionCompiler;
+            const options = typeof setting === "object" && setting !== null ? setting : undefined;
+            inputCap = resolveInputCap(options ? { maxInputTokens: options.maxInputTokens, reserveTokens: options.reserveTokens } : {}, model);
+        }
+        catch {
+            inputCap = undefined; // undialed model: omit instead of throwing a state read
+        }
+        const runInputBudget = this.activeLimits?.limits.maxInputTokens ?? undefined;
+        return {
+            inputTokens,
+            source,
+            ...(inputCap === undefined ? {} : { inputCap }),
+            ...(runInputBudget == null ? {} : { runInputBudget }),
+            ...(inputCap === undefined ? {} : { usedRatio: inputTokens / inputCap }),
+        };
+    }
     subscribe(options = {}) {
         const subscriber = new EventSubscriber(this.id, options, () => this.subscribers.delete(subscriber));
         this.subscribers.add(subscriber);
@@ -147,12 +212,13 @@ export class RuntimeAgentSession {
                 this.pendingSoftInterrupt = true;
         }
     }
-    async resumeDurable(state, runState, ownership, signal, decisions) {
+    async resumeDurable(state, runState, ownership, signal, decisions, extras) {
         return this.runInternal(state.input ?? [], { runState, ownership, signal }, state.runId, {
             options: runState,
             state,
             version: state.version,
             decisions,
+            ...extras,
         });
     }
     async recordDurableResumption(runId, interruption, version, ownership) {
@@ -241,7 +307,10 @@ export class RuntimeAgentSession {
     async compact(options = {}) {
         if (this.activeRun)
             throw new Error("Agent session already has an active run");
-        return this.compactBranch(options, undefined, options.signal, "manual");
+        const result = await this.compactBranch(options, undefined, options.signal, "manual");
+        // Plan 091 T2: history changed, so a pre-compaction meter reading would overstate the context.
+        this.activeInputMeter = undefined;
+        return result;
     }
     abort(reason) {
         this.activeRun?.abort(reason);
@@ -264,6 +333,7 @@ export class RuntimeAgentSession {
             store: this.store,
             leafId: options.leafId ?? this.currentLeafId,
             metadata: this.metadata,
+            ...(this.guardrailPackRefs ? { guardrailPacks: this.guardrailPackRefs } : {}),
         });
     }
     async clone(options = {}) {
@@ -286,6 +356,7 @@ export class RuntimeAgentSession {
             store: this.store,
             leafId: branch.length ? remap.get(branch[branch.length - 1].id) : undefined,
             metadata: this.metadata,
+            ...(this.guardrailPackRefs ? { guardrailPacks: this.guardrailPackRefs } : {}),
         });
     }
     branchReader() {