@arnilo/prism 0.9.0 → 0.11.0

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 { PendingToolCall, PersistedGuardrailPacks } from "../../agent-run-state.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 { Agent, AgentEvent, AgentFinishReason, AgentLoopStrategy, AgentRunResult, AIProvider, ErrorInfo, Guardrails, LoopContext, Message, ModelConfig, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunLedger, RunOptions, SessionEntry, SessionStore, Skill, StopHook, 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";
@@ -35,6 +35,12 @@ export type SessionHost = {
     activeGuardrails?: Guardrails;
     /** Plan 092 Task 2: packs compiled once at session construction; read-only for phases. */
     readonly packGuardrails?: Guardrails;
+    /** Plan 104 T3: `ask` rules as the durable charge-time gate (`interrupt` records) and as plain
+     *  blocks for a run that cannot suspend. */
+    readonly packAskGate?: Guardrails;
+    readonly packAskBlocks?: Guardrails;
+    /** Plan 104 T2: pack refs + live pack-owned state for a durable checkpoint. */
+    serializedGuardrailPackState(): PersistedGuardrailPacks | undefined;
     activeMetadata?: Readonly<Record<string, unknown>>;
     activePromptVersion?: PromptVersionRef;
     activeLimits?: RunLimitTracker;
@@ -83,6 +89,8 @@ export type SessionHost = {
     emit(event: AgentEvent): void;
     rebuildHistory(): Promise<void>;
     resolveRunSkills(options: RunOptions, tools: readonly ToolDefinition[]): readonly Skill[];
+    /** Redacted, cap-checked steer queue push (plan 106 R1 uses it for stop-hook continuations). */
+    steer(input: AgentInput): void;
     appendEntry(entry: SessionEntry): Promise<void>;
     redact<T>(value: T): T;
     appendMessage(message: Message, runId: string): Promise<void>;
@@ -99,12 +107,21 @@ export type SessionHost = {
         readonly status: AgentRunResult["status"];
         readonly usage?: Usage;
         readonly limit?: import("../../contracts.js").RunLimitBreach;
+        readonly attribution?: import("../../run-limits.js").BudgetExhaustionAttribution;
         readonly error?: ErrorInfo;
         readonly abortReason?: string;
         readonly runState?: import("../../contracts.js").AgentRunState;
         readonly interruption?: import("../../contracts.js").AgentRunInterruption;
     }): AgentRunResult;
+    /**
+     * Plan 106 R2: dispatch `session_start` middleware once per session (first run start), awaited by
+     * the run assembler after the `agent_started`/`agent_resumed` emits. No-op on every later call.
+     */
+    openSession(runId: string): Promise<void>;
+    /** Session teardown: close every subscriber, run-scoped and `acrossRuns` alike. */
     closeSubscribers(): void;
+    /** Run end (finish, suspend, or deny): close only the subscribers that do not opt into `acrossRuns`. */
+    closeRunSubscribers(): void;
     snapshot(): Promise<SessionContextSnapshot>;
 };
 export declare function asSessionHost(session: unknown): SessionHost;
@@ -151,6 +168,8 @@ export type RoundContext = {
     toolResults: ToolResult[];
     /** Set when a `RunOptions.turnPolicy` stop ended the loop (plan 084 Task 2). */
     runStop?: RunStopInfo;
+    /** Merged agent + run stop hooks, in invocation order (plan 106 R1). Empty = wrapper skipped. */
+    stopHooks: readonly StopHook[];
     runUsage: {
         add(usage: Usage): void;
         value(): Usage | undefined;

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, ActiveDurableRunExtras } from "../agent-approval.js";
-import type { PendingToolCall, StoredAgentRunState } from "../agent-run-state.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, Guardrails, Message, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunDecision, RunOptions, SessionEntry, Skill, SteerOptions, SubscribeOptions, ToolCallSummary, ToolDefinition, ToolEffectStore, Usage } from "../contracts.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?;
@@ -31,9 +35,15 @@ export declare class RuntimeAgentSession implements AgentSession {
     private activeIdempotencyKey?;
     private activeGuardrails?;
     /** Plan 092 Task 2: guardrail packs compiled once in the constructor; merged into every run's `activeGuardrails`. */
-    readonly packGuardrails?: Guardrails;
+    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 readonly guardrailPackRefs?;
+    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;
@@ -95,11 +105,28 @@ 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;
     });
@@ -111,15 +138,44 @@ export declare class RuntimeAgentSession implements AgentSession {
      * `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>, 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: {
@@ -127,6 +183,7 @@ export declare class RuntimeAgentSession implements AgentSession {
         readonly status: AgentRunResult["status"];
         readonly usage?: Usage;
         readonly limit?: import("../contracts.js").RunLimitBreach;
+        readonly attribution?: import("../run-limits.js").BudgetExhaustionAttribution;
         readonly error?: ErrorInfo;
         readonly abortReason?: string;
         readonly stopReason?: import("../contracts.js").AgentFinishReason;
@@ -149,6 +206,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

@@ -3,8 +3,8 @@ import { policyList } from "../agent-tool-dispatch.js";
 import { createAttentionFoldLedger, createAttentionStickyFrontier, resolveInputCap, restoreAttentionStickyFrontier, serializeAttentionFoldLedger, serializeAttentionStickyFrontier, } from "../attention-compiler.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "../compaction.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 { compileGuardrailPacks, GuardrailError, runGuardrails } from "../guardrails.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;
@@ -41,8 +45,14 @@ export class RuntimeAgentSession {
     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. */
-    guardrailPackRefs;
+    packRefs;
+    /** Plan 104 Task 2: compiled refs + live pack state, replaced by `restoreGuardrailPacks` on resume. */
+    compiledGuardrailPacks;
     activeMetadata;
     activePromptVersion;
     activeLimits;
@@ -127,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;
@@ -139,11 +189,14 @@ 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;
+        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") {
-            throw new TypeError('usageEstimation must be "fallback" or "off"');
+        if (usageEstimation !== undefined && usageEstimation !== "fallback" && usageEstimation !== "off" && usageEstimation !== "strict") {
+            throw new TypeError('usageEstimation must be "fallback", "off", or "strict"');
         }
     }
     get leafId() {
@@ -156,8 +209,37 @@ export class RuntimeAgentSession {
      * `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";
@@ -179,7 +261,17 @@ export class RuntimeAgentSession {
             ...(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;
@@ -233,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) {
@@ -248,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;
@@ -278,6 +403,7 @@ export class RuntimeAgentSession {
             await runPromise;
         }
         finally {
+            subscriber.close();
             if (!settled) {
                 this.abort(new Error("stream consumer closed"));
                 await runPromise.catch(() => undefined);
@@ -296,6 +422,7 @@ export class RuntimeAgentSession {
             message: final.message,
             usage: input.usage,
             limit: input.limit,
+            attribution: input.attribution,
             error: input.error,
             abortReason: input.abortReason,
             stopReason: input.stopReason,
@@ -333,7 +460,7 @@ export class RuntimeAgentSession {
             store: this.store,
             leafId: options.leafId ?? this.currentLeafId,
             metadata: this.metadata,
-            ...(this.guardrailPackRefs ? { guardrailPacks: this.guardrailPackRefs } : {}),
+            ...(this.packRefs ? { guardrailPacks: this.packRefs } : {}),
         });
     }
     async clone(options = {}) {
@@ -356,12 +483,12 @@ 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 } : {}),
+            ...(this.packRefs ? { guardrailPacks: this.packRefs } : {}),
         });
     }
     branchReader() {
-        // ponytail: prefer the store's readBranchPath (one ancestor-chain query) when present so a
-        // DB-backed store never loads the full session; else fall back to list() + in-memory walk.
+        // ponytail: prefer readBranchPath when present (memory, SQLite, Postgres) so snapshot does
+        // not list() the whole session. JSONL and other omitters fall back to list() + in-memory walk.
         const read = this.store.readBranchPath;
         return read ? (query) => read.call(this.store, query) : undefined;
     }
@@ -418,6 +545,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();
@@ -528,10 +664,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/checkpoint-restore.d.ts

@@ -1,12 +1,17 @@
 /**
- * Checkpoint restore hooks (plan 094 Task 3). A hook restores one external layer (git commit,
- * document version, workspace fingerprint) recorded in a checkpoint's sidecar metadata.
+ * Checkpoint restore hooks (plan 094 Task 3; reverse compensation plan 109 Task 2). A hook restores
+ * one external layer (git commit, document version, workspace fingerprint) recorded in a
+ * checkpoint's sidecar metadata.
  *
- * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails
- * or times out aborts the resume with `CheckpointRestoreError` naming that hook, so the
- * conversation restore never applies on top of a half-restored external world. Hosts that need
- * every layer back where they were re-run the whole restore after fixing the failing layer.
+ * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails or
+ * times out aborts the resume with `CheckpointRestoreError` naming that hook, so the conversation
+ * restore never applies on top of a half-restored external world. A handler may also declare a
+ * `compensate` direction: on failure the applied layers — including the failing one, which may be
+ * half-applied — are undone in reverse order and the error carries a best-effort
+ * `CheckpointRestoreCompensation` report. Compensation never runs after the caller aborted, never
+ * masks the original failure, and the checkpoint stays resumable either way.
  */
+import type { SecretRedactor } from "./redaction.js";
 /** Per-hook ceiling for a restore (plan 094 Task 3 default). */
 export declare const DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS = 10000;
 /** One hook that completed during a restore. */
@@ -20,26 +25,57 @@ export interface CheckpointRestoreAudit {
     readonly durationMs: number;
 }
 /**
- * Host code restoring one external layer. `signal` aborts on the per-hook timeout and on the
- * caller's abort, so a hook that talks to a remote system can cancel instead of dangling.
+ * Host code restoring or compensating one external layer. `signal` aborts on the per-hook timeout
+ * and on the caller's abort, so a hook that talks to a remote system can cancel instead of dangling.
  */
 export type CheckpointRestoreHook<Context> = (checkpoint: Context, signal: AbortSignal) => void | Promise<void>;
+/** Object form of a restore handler: an identity plus the layer's undo direction (plan 109 Task 2). */
+interface CheckpointRestoreHandlerObject<Context> {
+    /** Stable name reported in the audit and in `CheckpointRestoreError.compensation`; defaults to the restore hook's name, then `hook[i]`. */
+    readonly id?: string;
+    readonly restore: CheckpointRestoreHook<Context>;
+    /** Undo for this layer, run when a later hook — or this one — fails. Absent = the layer has no undo. */
+    readonly compensate?: CheckpointRestoreHook<Context>;
+}
+/**
+ * A restore handler: today's bare function, or `{ id?, restore, compensate? }` to declare an undo
+ * direction. Bare functions behave exactly as in plan 094 and are never compensated.
+ */
+export type CheckpointRestoreHandler<Context> = CheckpointRestoreHook<Context> | CheckpointRestoreHandlerObject<Context>;
+/** Best-effort record of the reverse compensation pass after a failed restore (plan 109 Task 2). */
+export interface CheckpointRestoreCompensation {
+    /** Names of the hooks whose `compensate` ran, most recently applied layer first. */
+    readonly ran: readonly string[];
+    /** First compensation that failed; the pass still continues with the remaining layers. */
+    readonly failed?: {
+        readonly hook: string;
+        readonly reason: string;
+    };
+}
 /** Thrown when a restore hook fails or times out; the checkpoint and conversation are untouched. */
 export declare class CheckpointRestoreError extends Error {
     readonly code = "ERR_PRISM_CHECKPOINT_RESTORE";
-    /** Name of the failing hook (`fn.name` or `hook[i]`). */
+    /** Name of the failing hook (`id`, `hook.name`, or `hook[i]`). */
     readonly hook: string;
-    constructor(hook: string, cause: unknown);
+    /** Present only when at least one `compensate` ran; omitted otherwise, as in plan 094. */
+    readonly compensation?: CheckpointRestoreCompensation;
+    constructor(hook: string, cause: unknown, compensation?: CheckpointRestoreCompensation);
 }
 export interface RunCheckpointRestoreHooksOptions {
     /** Per-hook timeout; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
     readonly timeoutMs?: number;
     /** Caller abort: checked between hooks and combined into each hook's signal. */
     readonly signal?: AbortSignal;
+    /** Applied to the bounded compensation reason; absent = the message is reported as-is (still capped). */
+    readonly redactor?: SecretRedactor;
 }
 /**
- * Run restore hooks sequentially and report the audit. A hook failure throws
- * `CheckpointRestoreError` immediately (later hooks do not run); an already-aborted caller signal
- * throws its own abort reason so the resume reads as cancelled rather than as a restore failure.
+ * Run restore handlers sequentially and report the audit. A handler failure throws
+ * `CheckpointRestoreError` immediately (later handlers do not run) after a best-effort reverse
+ * compensation pass over the applied layers; with no `compensate` declared anywhere, the failure
+ * shape is exactly plan 094's. An already-aborted caller signal throws its own abort reason so the
+ * resume reads as cancelled rather than as a restore failure, and a caller abort during the pass
+ * stops it before the next handler runs.
  */
-export declare function runCheckpointRestoreHooks<Context>(hooks: readonly CheckpointRestoreHook<Context>[], context: Context, options?: RunCheckpointRestoreHooksOptions): Promise<CheckpointRestoreAudit>;
+export declare function runCheckpointRestoreHooks<Context>(hooks: readonly CheckpointRestoreHandler<Context>[], context: Context, options?: RunCheckpointRestoreHooksOptions): Promise<CheckpointRestoreAudit>;
+export {};