@arnilo/prism 0.8.0 → 0.10.0

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 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 { ActiveDurableRun, ActiveDurableRunExtras } from "../agent-approval.js";
+import type { PendingToolCall, PersistedGuardrailPacks, StoredAgentRunState } from "../agent-run-state.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, GuardrailPackRef, 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";
@@ -14,6 +14,10 @@ export declare class RuntimeAgentSession implements AgentSession {
     private readonly metadata?;
     private readonly store;
     private readonly subscribers;
+    /** Plan 106 R2: `session_start` is dispatched at the first run start, once per runtime session. */
+    private sessionOpened;
+    /** Plan 106 R2: `close()` dispatches `session_shutdown` and closes subscribers exactly once. */
+    private closed;
     private currentLeafId?;
     private history;
     private activeRun?;
@@ -30,9 +34,27 @@ 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`. */
+    packGuardrails?: Guardrails;
+    /** Plan 104 Task 3: `ask` rules as the durable charge-time gate (a match records `interrupt`). */
+    packAskGate?: Guardrails;
+    /** Plan 104 Task 3: the same `ask` rules as plain blocks for a run that cannot suspend. */
+    packAskBlocks?: Guardrails;
+    /** Original pack refs, carried into `fork()`/`clone()` so a branch cannot silently lose its policy. */
+    private packRefs?;
+    /** Plan 104 Task 2: compiled refs + live pack state, replaced by `restoreGuardrailPacks` on resume. */
+    private compiledGuardrailPacks?;
     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 +65,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 +86,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). */
@@ -70,22 +105,77 @@ export declare class RuntimeAgentSession implements AgentSession {
     clearActivatedTools(): void;
     /** Plan 018 Task 6: restore persisted loaded-skill bodies (already validated fail-closed at load). */
     restoreLoadedSkillBodies(bodies: readonly LoadedSkillBodiesEntry[]): void;
+    /** Plan 104 T2: the refs this session actually enforces (restored ones after a resume). */
+    get guardrailPackRefs(): readonly GuardrailPackRef[] | undefined;
+    /** Plan 104 T2: pack refs + live pack-owned state for a durable checkpoint (opt-in with `persistSessionState`). */
+    serializedGuardrailPackState(): PersistedGuardrailPacks | undefined;
+    /**
+     * Plan 104 T2: recompile checkpoint packs before the resumed run's first turn. `state` present
+     * (even empty) marks a restore, so unknown ids, version mismatches, and codec-less state fail
+     * closed as `AgentRunStateError` — never a session that silently enforces less than it did.
+     */
+    restoreGuardrailPacks(refs: readonly GuardrailPackRef[], state?: Readonly<Record<string, unknown>>): void;
     private ledgerChain;
     private ledgerFailure;
     private snapshotGeneration;
     private snapshotCache?;
     private readonly snapshotCacheTtlMs;
+    /**
+     * Plan 103 T4: identity-keyed meter cache. Holds only the last public meter value
+     * plus the identity of everything the cold read consumed (`snapshotGeneration`,
+     * leaf, active meter/limits, and the history array reference + length, which catches
+     * in-place `history.push` during a run) — never history content, never an estimator.
+     */
+    private meterCache?;
     constructor(config: AgentSessionConfig & {
         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.
+     *
+     * Plan 103 T4: reads are cached until the history generation, leaf, history
+     * length, or active-run identity changes, so a per-frame poll pays one estimate
+     * per mutation instead of one per read. The cached value is frozen and is
+     * identical (`===`) to the previous read while nothing changed.
+     */
+    contextMeter(): ContextMeter;
+    /** Cold path of `contextMeter()`: one estimate over stored history plus cap/budget resolution. */
+    private measureContextMeter;
+    /**
+     * Live events for this session. A run-scoped subscriber (the default) is closed when the run ends,
+     * suspends, or is denied; `SubscribeOptions.acrossRuns: true` keeps one subscriber open across runs
+     * of the same session until the host closes it, the session tears it down, or its bounded queue
+     * overflows under the default policy. Subscribe before `run()`; the consumer loop and `run()` must
+     * run concurrently, since events are only emitted during a live run.
+     */
     subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
+    private createSubscriber;
     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;
+    /**
+     * Plan 106 R2: dispatch `session_start` once per session, at its first run start (including the
+     * first run of a session rebuilt from a durable checkpoint). The run assembler awaits it right
+     * after `agent_started`/`agent_resumed`, so session-scoped provisioning is done before the first
+     * turn while the runtime's synchronous emit burst stays intact. Middleware error policy decides
+     * whether a failure surfaces or becomes an `extension_error` event.
+     */
+    openSession(runId: string): Promise<void>;
+    /**
+     * Plan 106 R2: session teardown. Dispatches `session_shutdown` middleware once (idempotent) and
+     * then closes every subscriber, run-scoped and `acrossRuns` alike. Call it after the active run
+     * settles; `closeSubscribers()` remains the subscriber-only seam.
+     */
+    close(): Promise<void>;
     prompt(input: string, options?: RunOptions): Promise<AgentRunResult>;
     stream(input: AgentInput, options?: RunOptions & SubscribeOptions): AsyncGenerator<AgentEvent>;
     buildRunResult(input: {
@@ -115,6 +205,11 @@ export declare class RuntimeAgentSession implements AgentSession {
     resolveRunProvider(options: RunOptions): void;
     resolveRunSkills(options: RunOptions, tools: readonly ToolDefinition[]): readonly Skill[];
     emit(event: AgentEvent): void;
+    /**
+     * Run end (finish, suspension, or denial): closes the run-scoped subscribers only. Subscribers that
+     * opted into `SubscribeOptions.acrossRuns` stay open for the next run of this session.
+     */
+    closeRunSubscribers(): void;
     closeSubscribers(): void;
     drainLedger(): Promise<void>;
     applyPendingSteers(runId: string, metadata: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<boolean>;

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 { 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 { estimateAssemblyTokens, estimateMessageTokens, estimateTextTokens } from "../context-budget.js";
+import { AgentRunStateError, 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 { compileGuardrailPacksWithState, GuardrailError, GuardrailPackError, 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";
@@ -23,6 +23,10 @@ export class RuntimeAgentSession {
     metadata;
     store;
     subscribers = new Set();
+    /** Plan 106 R2: `session_start` is dispatched at the first run start, once per runtime session. */
+    sessionOpened = false;
+    /** Plan 106 R2: `close()` dispatches `session_shutdown` and closes subscribers exactly once. */
+    closed = false;
     currentLeafId;
     history = [];
     activeRun;
@@ -39,9 +43,24 @@ export class RuntimeAgentSession {
     activeIdentity;
     activeIdempotencyKey;
     activeGuardrails;
+    /** Plan 092 Task 2: guardrail packs compiled once in the constructor; merged into every run's `activeGuardrails`. */
+    packGuardrails;
+    /** Plan 104 Task 3: `ask` rules as the durable charge-time gate (a match records `interrupt`). */
+    packAskGate;
+    /** Plan 104 Task 3: the same `ask` rules as plain blocks for a run that cannot suspend. */
+    packAskBlocks;
+    /** Original pack refs, carried into `fork()`/`clone()` so a branch cannot silently lose its policy. */
+    packRefs;
+    /** Plan 104 Task 2: compiled refs + live pack state, replaced by `restoreGuardrailPacks` on resume. */
+    compiledGuardrailPacks;
     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 +68,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 +98,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)
@@ -98,11 +137,51 @@ export class RuntimeAgentSession {
         for (const entry of bodies)
             this.loadedSkills.add(entry.name);
     }
+    /** Plan 104 T2: the refs this session actually enforces (restored ones after a resume). */
+    get guardrailPackRefs() {
+        return this.packRefs;
+    }
+    /** Plan 104 T2: pack refs + live pack-owned state for a durable checkpoint (opt-in with `persistSessionState`). */
+    serializedGuardrailPackState() {
+        const compiled = this.compiledGuardrailPacks;
+        if (!compiled || compiled.packs.length === 0)
+            return undefined;
+        const state = compiled.snapshotState();
+        return { packs: compiled.packs, ...(state ? { state } : {}) };
+    }
+    /**
+     * Plan 104 T2: recompile checkpoint packs before the resumed run's first turn. `state` present
+     * (even empty) marks a restore, so unknown ids, version mismatches, and codec-less state fail
+     * closed as `AgentRunStateError` — never a session that silently enforces less than it did.
+     */
+    restoreGuardrailPacks(refs, state) {
+        let compiled;
+        try {
+            compiled = compileGuardrailPacksWithState(refs, undefined, state ?? {});
+        }
+        catch (error) {
+            if (error instanceof GuardrailPackError)
+                throw new AgentRunStateError(`Cannot restore guardrail packs: ${error.message}`);
+            throw error;
+        }
+        this.compiledGuardrailPacks = compiled;
+        this.packGuardrails = compiled.guardrails;
+        this.packAskGate = compiled.askGate;
+        this.packAskBlocks = compiled.askBlocks;
+        this.packRefs = refs;
+    }
     ledgerChain = Promise.resolve();
     ledgerFailure;
     snapshotGeneration = 0;
     snapshotCache;
     snapshotCacheTtlMs;
+    /**
+     * Plan 103 T4: identity-keyed meter cache. Holds only the last public meter value
+     * plus the identity of everything the cold read consumed (`snapshotGeneration`,
+     * leaf, active meter/limits, and the history array reference + length, which catches
+     * in-place `history.push` during a run) — never history content, never an estimator.
+     */
+    meterCache;
     constructor(config) {
         this.id = config.id ?? randomId("session");
         this.agent = config.agent;
@@ -110,11 +189,89 @@ export class RuntimeAgentSession {
         this.store = config.store ?? config.agent.config.store ?? createMemorySessionStore();
         this.currentLeafId = config.leafId;
         this.snapshotCacheTtlMs = resolveSnapshotCacheTtlMs(config.snapshotCacheTtlMs);
+        this.compiledGuardrailPacks = compileGuardrailPacksWithState(config.guardrailPacks);
+        this.packGuardrails = this.compiledGuardrailPacks.guardrails;
+        this.packAskGate = this.compiledGuardrailPacks.askGate;
+        this.packAskBlocks = this.compiledGuardrailPacks.askBlocks;
+        this.packRefs = config.guardrailPacks;
+        const usageEstimation = config.agent.config.usageEstimation;
+        if (usageEstimation !== undefined && usageEstimation !== "fallback" && usageEstimation !== "off" && usageEstimation !== "strict") {
+            throw new TypeError('usageEstimation must be "fallback", "off", or "strict"');
+        }
     }
     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.
+     *
+     * Plan 103 T4: reads are cached until the history generation, leaf, history
+     * length, or active-run identity changes, so a per-frame poll pays one estimate
+     * per mutation instead of one per read. The cached value is frozen and is
+     * identical (`===`) to the previous read while nothing changed.
+     */
+    contextMeter() {
+        const cached = this.meterCache;
+        if (cached &&
+            cached.leafId === this.currentLeafId &&
+            cached.generation === this.snapshotGeneration &&
+            cached.meter === this.activeInputMeter &&
+            cached.limits === this.activeLimits &&
+            cached.history === this.history &&
+            cached.historyLength === this.history.length) {
+            return cached.value;
+        }
+        const value = Object.freeze(this.measureContextMeter());
+        this.meterCache = {
+            leafId: this.currentLeafId,
+            generation: this.snapshotGeneration,
+            meter: this.activeInputMeter,
+            limits: this.activeLimits,
+            history: this.history,
+            historyLength: this.history.length,
+            value,
+        };
+        return value;
+    }
+    /** Cold path of `contextMeter()`: one estimate over stored history plus cap/budget resolution. */
+    measureContextMeter() {
+        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 }),
+        };
+    }
+    /**
+     * Live events for this session. A run-scoped subscriber (the default) is closed when the run ends,
+     * suspends, or is denied; `SubscribeOptions.acrossRuns: true` keeps one subscriber open across runs
+     * of the same session until the host closes it, the session tears it down, or its bounded queue
+     * overflows under the default policy. Subscribe before `run()`; the consumer loop and `run()` must
+     * run concurrently, since events are only emitted during a live run.
+     */
     subscribe(options = {}) {
+        return this.createSubscriber(options);
+    }
+    createSubscriber(options) {
         const subscriber = new EventSubscriber(this.id, options, () => this.subscribers.delete(subscriber));
         this.subscribers.add(subscriber);
         return subscriber;
@@ -147,12 +304,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) {
@@ -167,7 +325,7 @@ export class RuntimeAgentSession {
             this.activeLedger = undefined;
             this.activeOwnership = undefined;
             this.activeRedactor = undefined;
-            this.closeSubscribers();
+            this.closeRunSubscribers();
         }
     }
     async recordDurableDenial(runId, interruption, version, ownership) {
@@ -182,25 +340,58 @@ export class RuntimeAgentSession {
             this.activeLedger = undefined;
             this.activeOwnership = undefined;
             this.activeRedactor = undefined;
-            this.closeSubscribers();
+            this.closeRunSubscribers();
         }
     }
     async runInternal(input, options, runId, resumed) {
         return executeRun(asSessionHost(this), input, options, runId, resumed);
     }
+    /**
+     * Plan 106 R2: dispatch `session_start` once per session, at its first run start (including the
+     * first run of a session rebuilt from a durable checkpoint). The run assembler awaits it right
+     * after `agent_started`/`agent_resumed`, so session-scoped provisioning is done before the first
+     * turn while the runtime's synchronous emit burst stays intact. Middleware error policy decides
+     * whether a failure surfaces or becomes an `extension_error` event.
+     */
+    async openSession(runId) {
+        if (this.sessionOpened)
+            return;
+        this.sessionOpened = true;
+        await this.agent.config.middleware?.run("session_start", { sessionId: this.id, runId });
+    }
+    /**
+     * Plan 106 R2: session teardown. Dispatches `session_shutdown` middleware once (idempotent) and
+     * then closes every subscriber, run-scoped and `acrossRuns` alike. Call it after the active run
+     * settles; `closeSubscribers()` remains the subscriber-only seam.
+     */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            await this.agent.config.middleware?.run("session_shutdown", { sessionId: this.id });
+        }
+        finally {
+            this.closeSubscribers();
+        }
+    }
     prompt(input, options) {
         return this.run(input, options);
     }
     async *stream(input, options = {}) {
         const { maxQueuedEvents, overflow, ...runOptions } = options;
-        const subscription = this.subscribe({ maxQueuedEvents, overflow });
+        const subscriber = this.createSubscriber({ maxQueuedEvents, overflow });
         let runOwnedId;
         let settled = false;
+        // This subscription is stream()'s own, so it does not depend on the run-end close: settling the
+        // run closes it too, which also unblocks the consumer loop when the run fails before it ever
+        // emits (a pre-flight validation rejection returns before run-end cleanup).
         const runPromise = this.run(input, runOptions).finally(() => {
             settled = true;
+            subscriber.close();
         });
         try {
-            for await (const event of subscription) {
+            for await (const event of subscriber) {
                 if ("runId" in event && typeof event.runId === "string") {
                     if (runOwnedId === undefined && event.type === "agent_started")
                         runOwnedId = event.runId;
@@ -212,6 +403,7 @@ export class RuntimeAgentSession {
             await runPromise;
         }
         finally {
+            subscriber.close();
             if (!settled) {
                 this.abort(new Error("stream consumer closed"));
                 await runPromise.catch(() => undefined);
@@ -241,7 +433,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 +459,7 @@ export class RuntimeAgentSession {
             store: this.store,
             leafId: options.leafId ?? this.currentLeafId,
             metadata: this.metadata,
+            ...(this.packRefs ? { guardrailPacks: this.packRefs } : {}),
         });
     }
     async clone(options = {}) {
@@ -286,6 +482,7 @@ export class RuntimeAgentSession {
             store: this.store,
             leafId: branch.length ? remap.get(branch[branch.length - 1].id) : undefined,
             metadata: this.metadata,
+            ...(this.packRefs ? { guardrailPacks: this.packRefs } : {}),
         });
     }
     branchReader() {
@@ -347,6 +544,15 @@ export class RuntimeAgentSession {
             });
         }
     }
+    /**
+     * Run end (finish, suspension, or denial): closes the run-scoped subscribers only. Subscribers that
+     * opted into `SubscribeOptions.acrossRuns` stay open for the next run of this session.
+     */
+    closeRunSubscribers() {
+        for (const subscriber of this.subscribers)
+            if (!subscriber.acrossRuns)
+                subscriber.close();
+    }
     closeSubscribers() {
         for (const subscriber of this.subscribers)
             subscriber.close();
@@ -457,10 +663,15 @@ export class RuntimeAgentSession {
             signal,
         };
         this.emit({ type: "compaction_started", sessionId: this.id, runId });
-        let result = await strategy.compact(context);
+        // Plan 106 R3: pre-compaction seam — the strategy compacts exactly the context this returns.
+        const requested = (await this.agent.config.middleware?.run("compaction_request", context)) ?? context;
+        let result = await strategy.compact(requested);
         result = { ...result, summary: redactSecrets(result.summary, secrets) };
-        const payload = (await this.agent.config.middleware?.run("compaction", { context, result })) ?? {
-            context,
+        const payload = (await this.agent.config.middleware?.run("compaction", {
+            context: requested,
+            result,
+        })) ?? {
+            context: requested,
             result,
         };
         result = { ...payload.result, summary: redactSecrets(payload.result.summary, secrets) };

package/dist/attention-compiler.d.ts

@@ -5,7 +5,7 @@
  *  frozen prefix. The assembly branch lives in `input.ts`; opt-in agent wiring (Task 5) is not
  *  part of this module. */
 import { type ContextBudgetMessageGroups } from "./context-budget.js";
-import type { AttentionCompiler, AttentionCompilerContext, AttentionCompilerOptions, AttentionCompilerSetting, AttentionInputCapOptions, AttentionReport, ContextBlock, Skill, ToolDefinition } from "./contracts.js";
+import type { AttentionCompiler, AttentionCompilerContext, AttentionCompilerOptions, AttentionCompilerSetting, AttentionInputCapOptions, AttentionReport, AttentionTrigger, AttentionTriggerDecision, AttentionTriggerState, ContextBlock, Skill, ToolDefinition } from "./contracts.js";
 import { type CompactionTrigger } from "./contracts-core/compaction.js";
 import type { SecretRedactor } from "./redaction.js";
 import { type ResolvedToolResultFoldOptions } from "./tool-result-fold.js";
@@ -25,13 +25,29 @@ export declare function resolveAttentionReserveTokens(value: unknown): number;
 /** C2: host `maxInputTokens` wins; otherwise `contextWindow - (maxOutputTokens ?? 0) - reserve`.
  *  Shared with the `input_ratio` compaction trigger (Task 4). Throws when no cap can be derived. */
 export declare function resolveInputCap(options?: AttentionInputCapOptions, model?: AttentionCompilerContext["model"]): number;
+/**
+ * Build the frozen per-turn state the axes read: the compiler supplies the cap and the run budget
+ * (so a caller cannot silently drop the budget and fall back to the input cap), the caller
+ * supplies what only the turn knows.
+ */
+export declare function attentionTriggerState(compiler: Pick<AttentionCompiler, "inputCap" | "runInputBudget">, turn: {
+    readonly estimatedInputTokens: number;
+    readonly runInputTokens?: number;
+    readonly turn?: number;
+}): AttentionTriggerState;
+/**
+ * Evaluate the fold axes in order against one turn's state; the first axis that fires wins, and
+ * its `targetTokens` (when it has one) is what the stages fold to. Called at most twice per turn —
+ * once at turn start, once after the stages — so a host predicate never runs per row.
+ */
+export declare function evaluateAttentionTrigger(axes: readonly AttentionTrigger[], state: AttentionTriggerState): AttentionTriggerDecision;
 /** Validate compiler options + resolve the input cap. No provider I/O; unknown or
  *  unresolvable input throws here rather than on the first turn. */
 export declare function createAttentionCompiler(options?: AttentionCompilerOptions, context?: AttentionCompilerContext): AttentionCompiler;
 /** Resolve the run's compiler from the agent setting plus an optional run overlay, validating
  *  both eagerly (no provider I/O) so a typo fails at run start, not on some later turn (C12).
  *  Returns `undefined` when the compiler is off — the assembly path then allocates nothing. */
-export declare function resolveRunAttentionCompiler(agent: AttentionCompilerSetting | undefined, run: AttentionCompilerSetting | undefined, model: AttentionCompilerContext["model"]): AttentionCompiler | undefined;
+export declare function resolveRunAttentionCompiler(agent: AttentionCompilerSetting | undefined, run: AttentionCompilerSetting | undefined, model: AttentionCompilerContext["model"], runInputBudget?: number | null): AttentionCompiler | undefined;
 /** Caller-owned sticky frontier: what this session leaf already mutated (C10). Mutations are
  *  monotonic, so a stubbed call stays stubbed and stripped thinking stays stripped even on a
  *  later under-ratio turn — restoring either would rewrite the prompt-cache prefix. */
@@ -53,9 +69,15 @@ export interface AttentionCompileOptions {
      *  decide fold-eligibility. Omitted → the deterministic stub and `keepLast` alone. */
     readonly fold?: ResolvedToolResultFoldOptions;
     readonly frontier?: AttentionStickyFrontier;
+    /** Session-owned folded bodies (plan 086 T3): a body stored here is re-applied instead of
+     *  re-summarized, so a sticky row stays byte-identical and the host `summarize` runs once per
+     *  row instead of once per turn. Omit for one-shot assemblies. */
+    readonly attentionFold?: AttentionFoldLedger;
     readonly redactor?: SecretRedactor;
     readonly signal?: AbortSignal;
     readonly turn?: number;
+    /** Run input tokens already charged this run; the `run_input_ratio` axis projects onto it. */
+    readonly runInputTokens?: number;
     readonly sessionId?: string;
     readonly runId?: string;
 }
@@ -90,6 +112,33 @@ export declare function serializeAttentionStickyFrontier(frontier: AttentionStic
 export declare function parseAttentionStickyFrontier(value: unknown): PersistedAttentionStickyFrontier | undefined;
 /** Rebuild a frontier from a restored snapshot; callers hold the session that owns it. */
 export declare function restoreAttentionStickyFrontier(persisted: PersistedAttentionStickyFrontier): AttentionStickyFrontier;
+/** Session-owned folded bodies, keyed by tool call id. A row is summarized once: every later
+ *  turn re-applies the stored body, so a sticky row stays byte-identical for the provider cache
+ *  and the host `summarize` is not called again for it. Bodies are already redacted and capped by
+ *  the fold that produced them, so nothing here needs redaction at persistence time. */
+export interface AttentionFoldLedger {
+    /** toolCallId → stub body (never the payload); insertion order is fold order, oldest first. */
+    readonly bodies: Map<string, string>;
+}
+export declare function createAttentionFoldLedger(): AttentionFoldLedger;
+/** Serialized fold ledger (plan 086 T3). Stub bodies only — no payload, and every entry was
+ *  already capped and redacted when it was folded, so a durable resume restores it verbatim. */
+export interface PersistedAttentionFoldLedger {
+    readonly v: 1;
+    /** Oldest-first, so a restored ledger is the tail of the folds the session made. */
+    readonly bodies: readonly {
+        readonly id: string;
+        readonly body: string;
+    }[];
+}
+/** Bounded snapshot of a live ledger; caller-owned (the runtime persists it, the compiler never
+ *  writes anywhere). */
+export declare function serializeAttentionFoldLedger(ledger: AttentionFoldLedger): PersistedAttentionFoldLedger;
+/** Validate a persisted ledger from an untrusted store (plan 086 T3). Malformed *entries* are
+ *  dropped one by one — a body the compiler cannot trust simply re-summarizes on the next turn —
+ *  while a malformed *shape* yields `undefined` so the caller starts from an empty ledger.
+ *  Never throws: a resume must not fail because a checkpoint was hand-edited. */
+export declare function restoreAttentionFoldLedger(value: unknown): AttentionFoldLedger | undefined;
 /** Consecutive `truncated` turns that arm compaction by default. */
 export declare const DEFAULT_ATTENTION_TRUNCATION_THRESHOLD = 2;
 export interface AttentionTruncationTriggerOptions {