@arnilo/prism 0.9.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, 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: {
@@ -149,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

@@ -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);
@@ -333,7 +459,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,7 +482,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 } : {}),
+            ...(this.packRefs ? { guardrailPacks: this.packRefs } : {}),
         });
     }
     branchReader() {
@@ -418,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();
@@ -528,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/context-budget.d.ts

@@ -96,3 +96,14 @@ export declare function measureInputCost(options: MeasureInputCostOptions): {
     tokens: number;
     bytes: number;
 };
+/** Plan 103 T6: the host's `contextBudget.tokenEstimator`, validated exactly like the budget pass
+ * validates it (a non-function, or a non-finite/negative count, fails closed with `TypeError`).
+ * `undefined` when no host estimator is configured, so callers can fall through to the built-in
+ * heuristic. Exported for the usage seam (`provider-round.ts`) — deliberately not re-exported by
+ * `src/index.ts`, so the public surface is unchanged. */
+export declare function resolveHostTokenEstimator(budget: ContextBudget | undefined): TokenEstimator | undefined;
+/** Plan 103 T6: tool declarations and context blocks projected with the assembler's own
+ * `measureAll` text shapes, so the usage-fallback estimate and the budget pass cannot drift
+ * (never `JSON.stringify` of the raw schemas). Exported for the usage seam — deliberately not
+ * re-exported by `src/index.ts`. */
+export declare function estimateRequestExtrasTokens(tools: readonly ToolDefinition[] | undefined, context: readonly ContextBlock[] | undefined, estimateTokens: TokenEstimator): number;

package/dist/context-budget.js

@@ -246,7 +246,7 @@ function measureAll(groups, context, skills, tools, skillContext, demotedBodies,
     for (const message of groups.toolResults)
         addMessage(message);
     for (const block of context) {
-        const text = `${block.title ? `${block.title}:\n` : "Context:\n"}${contextBlockText(block)}`;
+        const text = contextBlockMeasureText(block);
         tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
@@ -256,12 +256,35 @@ function measureAll(groups, context, skills, tools, skillContext, demotedBodies,
         bytes += estimateTextBytes(text);
     }
     if (tools?.length) {
-        const text = `Available tools:\n${tools.map((tool) => `- ${tool.name}${tool.description ? `: ${tool.description}` : ""}`).join("\n")}`;
+        const text = toolsMeasureText(tools);
         tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
     return { tokens, bytes };
 }
+/** Plan 103 T6: the host's `contextBudget.tokenEstimator`, validated exactly like the budget pass
+ * validates it (a non-function, or a non-finite/negative count, fails closed with `TypeError`).
+ * `undefined` when no host estimator is configured, so callers can fall through to the built-in
+ * heuristic. Exported for the usage seam (`provider-round.ts`) — deliberately not re-exported by
+ * `src/index.ts`, so the public surface is unchanged. */
+export function resolveHostTokenEstimator(budget) {
+    if (budget?.tokenEstimator === undefined)
+        return undefined;
+    return resolveTokenEstimator(budget);
+}
+/** Plan 103 T6: tool declarations and context blocks projected with the assembler's own
+ * `measureAll` text shapes, so the usage-fallback estimate and the budget pass cannot drift
+ * (never `JSON.stringify` of the raw schemas). Exported for the usage seam — deliberately not
+ * re-exported by `src/index.ts`. */
+export function estimateRequestExtrasTokens(tools, context, estimateTokens) {
+    let tokens = 0;
+    if (context?.length)
+        for (const block of context)
+            tokens += estimateTokens(contextBlockMeasureText(block));
+    if (tools?.length)
+        tokens += estimateTokens(toolsMeasureText(tools));
+    return tokens;
+}
 function overBudget(cost, budget) {
     if (budget.maxInputTokens !== undefined && cost.tokens > budget.maxInputTokens)
         return true;
@@ -342,4 +365,12 @@ function contextBlockText(block) {
     })
         .join("\n");
 }
+/** The context block exactly as `measureAll` measures it (plan 103 T6 shares this shape with the usage seam). */
+function contextBlockMeasureText(block) {
+    return `${block.title ? `${block.title}:\n` : "Context:\n"}${contextBlockText(block)}`;
+}
+/** The tool list exactly as `measureAll` measures it (plan 103 T6 shares this shape with the usage seam). */
+function toolsMeasureText(tools) {
+    return `Available tools:\n${tools.map((tool) => `- ${tool.name}${tool.description ? `: ${tool.description}` : ""}`).join("\n")}`;
+}
 //# sourceMappingURL=context-budget.js.map

package/dist/contracts-core/agent.d.ts

@@ -11,7 +11,7 @@ import type { CompactionOptions, RetryOptions } from "./compaction.js";
 import type { ContentBlock, ErrorInfo, JsonObject, Message, ModelConfig } from "./content.js";
 import type { ProviderRequestPolicy, SystemPromptConfig } from "./extensions.js";
 import type { GuardrailPackRef } from "./guardrail-packs.js";
-import type { AgentLoopOptions, AgentLoopStrategy } from "./loop.js";
+import type { AgentLoopOptions, AgentLoopStrategy, StopHook } from "./loop.js";
 import type { OwnershipScope } from "./persistence.js";
 import type { AIProvider, ProviderRequestOptions, ProviderResolver } from "./provider.js";
 import type { ResourceLoader } from "./resources.js";
@@ -86,11 +86,24 @@ export interface AgentConfig {
      *  Omitted keeps today's request bytes; per-run options may only relax this setting. */
     readonly attentionCompiler?: import("./attention.js").AttentionCompilerSetting;
     /**
-     * Missing-usage fallback (plan 091 T2): `"fallback"` (default) records a labeled
-     * estimate when a provider turn reports no usage; `"off"` leaves usage absent —
-     * never zero. Estimates are marked `Usage.estimated` and are never priced.
+     * Missing-usage handling (plan 091 T2, plan 103 T5): `"fallback"` (default) records a labeled
+     * estimate when a provider turn reports no usage; `"off"` leaves usage absent — never zero;
+     * `"strict"` refuses a usage-less turn instead, failing the run with `code: "usage_missing"`
+     * (`name: "UsageMissingError"`) so a host whose cost gates cannot tolerate approximations never
+     * runs on an estimate. A refusal is a harness decision, not a provider failure, so it carries no
+     * `failureClass` and is never retried. Estimates are marked `Usage.estimated` and never priced.
      */
-    readonly usageEstimation?: "fallback" | "off";
+    readonly usageEstimation?: "fallback" | "off" | "strict";
+    /**
+     * Session-turn context budget (plan 103 T6): forwarded to every `assembleProviderInput`
+     * call this agent's sessions make, so a session gets the same eviction, `tokenEstimator`,
+     * and `reportOmissions` semantics as a direct assembler caller. Mutually exclusive with
+     * `attentionCompiler` (rejected at assembly). With `usageEstimation: "fallback"`, the
+     * missing-usage estimate prefers this budget's own measurement: the request's
+     * `ContextBudgetReport.keptTokens` when `reportOmissions` is on, else the `tokenEstimator`
+     * projection — see [Runs and usage](../../docs/runs-and-usage.md).
+     */
+    readonly contextBudget?: import("../context-budget.js").ContextBudget;
     readonly inputBuilder?: InputBuilder;
     readonly promptBuilder?: PromptBuilder;
     readonly middleware?: MiddlewareRegistry;
@@ -124,6 +137,8 @@ export interface AgentConfig {
     readonly inputLayout?: InputAssemblyLayout;
     readonly loop?: AgentLoopStrategy | AgentLoopOptions;
     readonly guardrails?: Guardrails;
+    /** Run-end stop hooks (plan 106 R1); `RunOptions.stopHooks` appends to this list. */
+    readonly stopHooks?: readonly StopHook[];
     /** Opt-in durable interruption/checkpointing default for this agent. */
     readonly runState?: AgentRunStateOptions;
     /** Internal marker set by createSecureAgent(); makes security defaults immutable per run. */
@@ -183,6 +198,12 @@ export interface AgentSessionCloneOptions {
 }
 export type SubscriberOverflowPolicy = "close" | "drop_oldest" | "drop_newest";
 export interface SubscribeOptions {
+    /**
+     * Plan 104 T5: `true` keeps this subscriber open across runs of the same session; it is then
+     * closed only by the host (`subscription.close()` / `session.closeSubscribers()`) or by an
+     * overflow under the default `close` policy. Default `false` (closed at run end).
+     */
+    readonly acrossRuns?: boolean;
     /** Maximum queued events for a subscriber that is not actively awaiting `next()`. Defaults to 1024. */
     readonly maxQueuedEvents?: number;
     /** What to do when `maxQueuedEvents` is reached. Defaults to `close`. */

package/dist/contracts-core/extensions.d.ts

@@ -7,6 +7,7 @@ import type { Middleware, MiddlewareHookName, MiddlewareRegistry } from "../midd
 import type { AgentDefinition, CommandDefinition, ContextProvider, InputBuilder, InstructionInjector, PromptBuilder, Skill } from "./agent.js";
 import type { CompactionStrategy, RetryPolicy } from "./compaction.js";
 import type { ErrorInfo, ModelConfig } from "./content.js";
+import type { StopHook } from "./loop.js";
 import type { StoreFactory } from "./persistence.js";
 import type { AIProvider, ProviderRequest } from "./provider.js";
 import type { Credential, CredentialResolver, ResourceLoader, SettingsProvider } from "./resources.js";
@@ -160,4 +161,6 @@ export interface ExtensionAPI {
     registerProviderRequestPolicy(policy: ProviderRequestPolicy): void;
     registerSystemPromptContribution(contribution: SystemPromptContribution): void;
     registerInstructionInjector(injector: InstructionInjector): void;
+    /** Contributes an inert run-end stop hook; activate it via `activateKernel()` → `AgentConfig.stopHooks` (plan 106 R1). */
+    registerStopHook(hook: StopHook): void;
 }

package/dist/contracts-core/guardrail-packs.d.ts

@@ -1,10 +1,10 @@
 /**
  * Guardrail packs (plan 092 Task 2): config-declared, restrictive-only rule sets compiled once per
  * session onto the existing tool interception seams (`tool_input` / `tool_output`). Packs can only
- * deny or tripwire — they never grant permissions, widen arguments, or add a stage.
+ * deny, tripwire, or ask for approval — they never grant permissions, widen arguments, or add a stage.
  */
 import type { JsonObject } from "./content.js";
-export type GuardrailRuleAction = "deny" | "tripwire";
+export type GuardrailRuleAction = "deny" | "tripwire" | "ask";
 /** Read-only identity view handed to a pack rule predicate (never carries a raw argument echo). */
 export interface GuardrailRuleContext {
     readonly toolName: string;
@@ -25,7 +25,12 @@ export interface GuardrailRule {
     readonly argPath?: string | readonly string[];
     /** Typed predicate escape hatch (host-trusted like all host code); deny when it returns true. Exactly one of `pattern` / `deny`. */
     readonly deny?: (args: JsonObject, context: GuardrailRuleContext) => boolean;
-    /** Defaults to `deny`; `tripwire` also rejects the enclosing run. `ask` has no deterministic seam (plan 092 Task 1). */
+    /**
+     * Defaults to `deny`. `tripwire` also rejects the enclosing run. `ask` suspends a durable run
+     * before the call dispatches (the pending decision names this rule) and blocks the call in a run
+     * that cannot suspend; it requires `pattern` — an opaque predicate cannot raise an approval
+     * (plan 104 Task 3).
+     */
     readonly action?: GuardrailRuleAction;
     /** Bounded, redacted record reason; defaults to the pack/rule id. */
     readonly reason?: string;

package/dist/contracts-core/loop.d.ts

@@ -46,6 +46,36 @@ export interface TurnPolicyOptions {
      */
     readonly stop?: (context: TurnBoundaryContext) => TurnStopDecision;
 }
+/**
+ * Run-end stop-hook contract (plan 106 R1). Stop hooks run at a natural loop end — never after a
+ * loop ceiling, a host turn-policy stop, or an artifact failure — and decide whether the run is
+ * done. The first `continue` queues `reason` (plus optional `steer`) through the same steer path a
+ * host would use and re-enters the loop; `stop` (or no hook continuing) ends the run normally.
+ */
+export interface StopHookContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    /** Provider turns already assembled in this run (resumption continues the run's counter). */
+    readonly turn: number;
+    /** Live transcript at loop end; hooks read it, never mutate it. */
+    readonly history: readonly Message[];
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly signal: AbortSignal;
+    /** True on every invocation after the first continuation in this run (Claude Code `stop_hook_active`). */
+    readonly stopHookActive: boolean;
+}
+/** `continue` re-enters the loop with `reason` queued as a steer (optional extra `steer` message follows it). */
+export type StopHookDecision = {
+    readonly action: "stop";
+} | {
+    readonly action: "continue";
+    readonly reason: string;
+    readonly steer?: string | Message;
+};
+export interface StopHook {
+    readonly name: string;
+    decide(context: StopHookContext): StopHookDecision | Promise<StopHookDecision>;
+}
 export interface LoopContext {
     readonly sessionId: string;
     readonly runId: string;
@@ -54,6 +84,12 @@ export interface LoopContext {
     readonly history: Message[];
     readonly input: AgentInput;
     readonly inputMessages: readonly Message[];
+    /**
+     * True when this `run()` call is a stop-hook continuation re-entry (plan 106 R1): `input` and
+     * `inputMessages` are empty because the continuation message is already in `history`. Custom
+     * strategies must not replay run-start input when this is set.
+     */
+    readonly continuation?: boolean;
     readonly maxToolRounds: number;
     /**
      * Why the loop stopped, when a limit/ceiling ends the run cleanly (F4). Strategies set