@arnilo/prism 0.8.0 → 0.10.0

package/dist/context-budget.js

@@ -1,4 +1,5 @@
 import { capSkillCatalog, selectSkillsForPrompt, skillHasRenderableBody, skillPromptText, } from "./skill-disclosure.js";
+import { estimateTextTokensForFamily, MODEL_FAMILY_TOKENS, resolveModelFamily } from "./usage-estimation.js";
 export const CONTEXT_BUDGET_REPORT_METADATA_KEY = "contextBudgetReport";
 export const HARD_MAX_CONTEXT_BUDGET_TOKENS = 2_000_000;
 export const HARD_MAX_CONTEXT_BUDGET_BYTES = 32 * 1024 * 1024;
@@ -22,8 +23,29 @@ export function estimateTextTokens(text) {
 export function estimateTextBytes(text) {
     return Buffer.byteLength(text, "utf8");
 }
-export function estimateMessageTokens(message, estimateTokens = estimateTextTokens) {
-    return estimateTokens(messageText(message));
+/**
+ * Single message → flattened text → estimator (budget accounting, never billing).
+ *
+ * Plan 091 Task 1 overload: a message array plus a model id, provider id, or
+ * family name returns a labeled {@link TokenEstimate}. It reuses this same
+ * per-message flattening and adds the family's per-message chat-template
+ * overhead; `unknown` families fall back to the conservative table with
+ * `lowConfidence: true`.
+ */
+export function estimateMessageTokens(input, estimatorOrFamily) {
+    if (isMessageArray(input)) {
+        const family = resolveModelFamily(estimatorOrFamily);
+        const table = MODEL_FAMILY_TOKENS[family];
+        let tokens = table.perMessageOverhead * input.length;
+        for (const message of input)
+            tokens += estimateTextTokensForFamily(messageText(message), family);
+        return { tokens, confidence: table.confidence, lowConfidence: table.confidence === "low" };
+    }
+    const estimateTokens = typeof estimatorOrFamily === "function" ? estimatorOrFamily : estimateTextTokens;
+    return estimateTokens(messageText(input));
+}
+function isMessageArray(value) {
+    return Array.isArray(value);
 }
 export function estimateMessageBytes(message) {
     return estimateTextBytes(messageText(message));
@@ -224,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);
     }
@@ -234,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;
@@ -320,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

@@ -10,7 +10,8 @@ import type { ToolValidator } from "../tools.js";
 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 { AgentLoopOptions, AgentLoopStrategy } from "./loop.js";
+import type { GuardrailPackRef } from "./guardrail-packs.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";
@@ -47,6 +48,17 @@ export interface AgentDefinitionResolutionContext {
     readonly activateAllCapabilities?: true;
     readonly overrides?: Partial<AgentConfig>;
 }
+/** Per-turn tool menu. Called at `loopCtx.assemble` before each provider request. */
+export interface ToolNarrowingContext {
+    /** 1-based provider turn this assemble precedes. */
+    readonly turn: number;
+    /** Text of the latest assistant message, when any. */
+    readonly lastAssistantText?: string;
+    /** Run-grant tool names (R11 snapshot, including generated `search_tools` when disclosure is search). */
+    readonly toolIds: readonly string[];
+}
+/** Host callback: return a subset of `toolIds`. Superset names are clamped; throw fails the turn. */
+export type ToolNarrowing = (ctx: ToolNarrowingContext) => readonly string[] | Promise<readonly string[]>;
 export interface AgentConfig {
     readonly id?: string;
     readonly name?: string;
@@ -64,11 +76,34 @@ export interface AgentConfig {
     /** Tools disclosure: "all" (default) sends every active tool schema; "search" sends top-k + the generated `search_tools` tool. */
     readonly toolsDisclosure?: import("../tool-search.js").ToolsDisclosure;
     readonly toolsSearch?: import("../tool-search.js").ToolsSearchOptions;
+    /** Per-turn restrictive allow-list over the run grant. RunOptions override. */
+    readonly toolNarrowing?: ToolNarrowing;
+    /** Opt-in: tools hidden this turn stay callable by name (default off). */
+    readonly allowHiddenToolCalls?: true;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("../tool-result-fold.js").ToolResultFoldOptions;
     /** Opt-in attention compiler (plan 074): `true` for defaults, an object to tune ratios/depth.
      *  Omitted keeps today's request bytes; per-run options may only relax this setting. */
     readonly attentionCompiler?: import("./attention.js").AttentionCompilerSetting;
+    /**
+     * 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" | "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;
@@ -102,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. */
@@ -134,6 +171,12 @@ export interface AgentSessionConfig {
     readonly store?: SessionStore;
     readonly leafId?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * Restrictive-only guardrail packs compiled once per session onto the existing tool interception
+     * seams (plan 092). Built-in ids are versioned; an input object with `rules` is an inline pack.
+     * Compiled rules can only deny or tripwire — they never grant permissions.
+     */
+    readonly guardrailPacks?: readonly GuardrailPackRef[];
     /**
      * TTL of the in-memory `session.snapshot()` branch cache in milliseconds.
      * Default `DEFAULT_SNAPSHOT_CACHE_TTL_MS`; `0` disables the cache (every snapshot read
@@ -155,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`. */
@@ -277,6 +326,8 @@ export interface PromptBuildRequest {
     readonly skills?: readonly Skill[];
     readonly skillsDisclosure?: import("../skill-disclosure.js").SkillsDisclosure;
     readonly loadedSkills?: import("../skill-disclosure.js").LoadedSkillSet;
+    /** Loaded skill bodies already appended to `messages` by the session tail allocator; render catalog entries only. */
+    readonly tailSkillBodies?: boolean;
     /** Tools disclosure: "all" (default) sends every active tool schema; "search" sends top-k + the generated `search_tools` tool. */
     readonly toolsDisclosure?: import("../tool-search.js").ToolsDisclosure;
     readonly toolsSearch?: import("../tool-search.js").ToolsSearchOptions;

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

@@ -12,9 +12,75 @@ export interface AttentionInputCapOptions {
     /** Output + next-turn headroom subtracted from the window (default 1024). */
     readonly reserveTokens?: number;
 }
+/** Fold axes (plan 086 T2). `input_ratio` is the legacy `triggerRatio` axis; the rest are new. */
+export type AttentionTriggerKind = "input_ratio" | "run_input_ratio" | "token_floor" | "predicate";
+/** Per-turn inputs an axis reads. Frozen before a `predicate` sees it; estimates and ids only. */
+export interface AttentionTriggerState {
+    /** Estimated tokens of the request this turn will send — what the ratio axes compare. */
+    readonly estimatedInputTokens: number;
+    /** Resolved per-request input cap (`resolveInputCap`). */
+    readonly inputCapTokens: number;
+    /** Cumulative run input budget when the run limits declare one; absent falls back to `inputCapTokens`. */
+    readonly runInputBudgetTokens?: number;
+    /** Run input tokens already charged by provider usage this run (0 when unknown). */
+    readonly runInputTokens: number;
+    /** 1-based provider turn index. */
+    readonly turn: number;
+}
+/** Host predicate axis. Runs host-supplied code under the same trust as `CompactionTrigger.custom`. */
+export type AttentionTriggerFunction = (state: AttentionTriggerState) => boolean;
+/** One fold gate. An array is any-of; the first axis that fires is the one attributed. */
+export type AttentionTrigger = 
+/** Legacy axis: fires when the assembled request reaches `ratio` of the per-request input cap. */
+{
+    readonly kind: "input_ratio";
+    readonly ratio: number;
+}
+/** Cumulative axis: fires when `runInputTokens + estimatedInputTokens` reaches `ratio` of the run
+ *  input budget, so a run capped below the window folds before the cap kills it. Falls back to
+ *  the `input_ratio` comparison when the run limits declare no input budget. */
+ | {
+    readonly kind: "run_input_ratio";
+    readonly ratio: number;
+}
+/** Absolute axis: fires when the assembled request reaches `tokens`, whatever the cap. */
+ | {
+    readonly kind: "token_floor";
+    readonly tokens: number;
+}
+/** Host axis: fires when `shouldFold` returns `true`. Called once per turn; must be synchronous. */
+ | {
+    readonly kind: "predicate";
+    readonly shouldFold: AttentionTriggerFunction;
+};
+/** Accepted `trigger` value: one axis, one predicate, or an any-of array of either. */
+export type AttentionTriggerInput = AttentionTrigger | AttentionTriggerFunction | readonly (AttentionTrigger | AttentionTriggerFunction)[];
+/** Result of evaluating the axes once against one turn's state. */
+export interface AttentionTriggerDecision {
+    readonly shouldFold: boolean;
+    /** First axis that fired, in configured order (plan 087 attribution). */
+    readonly firedAxis?: AttentionTriggerKind;
+    /** Estimated-token target the sticky stages fold to; absent = fold every eligible row. */
+    readonly targetTokens?: number;
+    /** `true` when folding this request can settle the fired axis, so a still-firing axis after every
+     *  eligible row throws `AttentionBudgetError`. Cumulative `run_input_ratio` axes are `false`: the
+     *  spend is already booked, folding only slows the counter, and the run limit owns the cap. */
+    readonly failsClosed: boolean;
+}
 export interface AttentionCompilerOptions extends AttentionInputCapOptions {
     /** Fraction of `inputCap` that triggers mutation; in `(0, 1)` (default 0.75). */
     readonly triggerRatio?: number;
+    /**
+     * Fold axes (plan 086 T2). Omitted keeps the `triggerRatio` axis alone, so requests gate
+     * exactly as before. Given, it **replaces** the `triggerRatio` axis: the gate is the any-of of
+     * the listed axes, and `triggerRatio` stays the input-ratio reference for `compactRatio` and
+     * the report. A run overlay may not set it (the gate is agent-config only).
+     *
+     * Predicate axes execute host-supplied code, trusted exactly like `CompactionTrigger.custom`:
+     * the function runs once per turn with a frozen `AttentionTriggerState` and must return a
+     * boolean synchronously (a `Promise` return fails closed with a `TypeError`).
+     */
+    readonly trigger?: AttentionTriggerInput;
     /** Where compaction should fire relative to `triggerRatio`; must exceed it (default 0.9). */
     readonly compactRatio?: number;
     /** Newest thinking-bearing assistant turns kept intact (default 1). */
@@ -23,6 +89,17 @@ export interface AttentionCompilerOptions extends AttentionInputCapOptions {
     readonly keepLast?: number;
     /** Tool names whose results are never stubbed, whatever the ratio. */
     readonly excludeTools?: readonly string[];
+    /**
+     * Durable folding (plan 086 T3): persist the fold ledger and its sticky frontier into the
+     * run's checkpoint at each fold, and restore them before the first turn after a resume.
+     * Requires a durable run (`runState` with a checkpoint store); independent of
+     * `persistSessionState`, which governs skill/tool session state instead.
+     *
+     * Off by default: durable folding costs one extra checkpoint write per fold (never per turn)
+     * and stores the folded bodies — already redacted, capped by `maxSummaryBytes` — so a resumed
+     * request carries the same folded rows a live run would. A run overlay may not set it.
+     */
+    readonly durable?: boolean;
 }
 /** Where the compiler is switched on: `true` uses the defaults, an object tunes them, `false`
  *  (or omitted) leaves requests byte-for-byte as they are without the compiler. On
@@ -34,6 +111,10 @@ export interface AttentionCompilerContext {
     readonly model?: Pick<ModelConfig, "limits">;
     /** Validated at create so an unknown trigger type fails at config time, not on turn one. */
     readonly compactionTrigger?: CompactionTrigger;
+    /** Cumulative run input budget the `run_input_ratio` axis folds against (the resolved
+     *  `RunLimits.maxInputTokens`); `null`/omitted means no run budget, so that axis falls back to
+     *  the per-request input cap. Distinct from `maxInputTokens`, which caps one request. */
+    readonly runInputBudget?: number | null;
 }
 /** Validated, frozen configuration returned by `createAttentionCompiler`. */
 export interface AttentionCompiler {
@@ -44,6 +125,14 @@ export interface AttentionCompiler {
     readonly thinkingKeepTurns: number;
     readonly keepLast: number;
     readonly excludeTools: readonly string[];
+    /** Normalized, frozen fold axes in evaluation order: the `input_ratio` default when no
+     *  `trigger` was configured, otherwise exactly the configured axes. */
+    readonly trigger: readonly AttentionTrigger[];
+    /** Run input budget resolved at create; absent when the run limits declare none. */
+    readonly runInputBudget?: number;
+    /** Durable folding resolved at create (plan 086 T3); `true` opts the run's fold state into
+     *  checkpoint persistence, so `assembleProviderInput` callers should pass the ledger. */
+    readonly durable: boolean;
 }
 /** One mutated turn. Under-ratio turns emit nothing and produce no report (C14). */
 export interface AttentionReport {
@@ -53,12 +142,18 @@ export interface AttentionReport {
     readonly usedAfter: number;
     readonly inputCap: number;
     readonly triggerRatio: number;
+    /** Axis that opened the gate on this turn, when one did (plan 087 attribution). */
+    readonly firedAxis?: AttentionTriggerKind;
     /** Thinking turns absent from this request; rows re-applied from the sticky frontier count again. */
     readonly droppedThinkingTurns: number;
     /** Tool results stubbed in this request; rows re-applied from the sticky frontier count again. */
     readonly stubbedToolResults: number;
     /** Payload bytes the stubs took out of this request (never the stub text itself). */
     readonly stubbedBytes: number;
+    /** Folded bodies this turn added to the ledger — the summarize calls a cache saved, and the
+     *  signal that a durable fold has new state to checkpoint (plan 086 T3). Zero on a turn that
+     *  only re-applied bodies the ledger already held. */
+    readonly newFoldedBodies: number;
     /** True when the gate stopped with eligible rows left: the sticky frontier is partial. */
     readonly truncated: boolean;
     readonly runId?: string;

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

@@ -2,6 +2,7 @@
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
 import type { AudioContent, DocumentContent, FileContent } from "../content.js";
 import type { ModelCacheCapabilities } from "./provider.js";
+import type { TokenEstimateConfidence } from "./usage.js";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 export interface JsonObject {
@@ -177,6 +178,15 @@ export interface Usage {
     readonly cacheWriteTokens?: number;
     readonly cost?: number;
     readonly currency?: string;
+    /**
+     * True when these token counts are a harness estimate, never provider truth
+     * (plan 091 T2). Estimated usage is never priced, and every accounting export
+     * (ledger rows, run totals, turn events) keeps this flag so a billing surface
+     * can always tell an estimate from a report. Absent means reported.
+     */
+    readonly estimated?: boolean;
+    /** Confidence label of an estimated usage; absent on reported usage. */
+    readonly confidence?: TokenEstimateConfidence;
 }
 /**
  * Host-supplied pricing adapter (plan 062): quotes cost rates per model id. Core

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

@@ -0,0 +1,46 @@
+/**
+ * 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, 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" | "ask";
+/** Read-only identity view handed to a pack rule predicate (never carries a raw argument echo). */
+export interface GuardrailRuleContext {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /** Pack-local state shared with the pack's result observer; treat as read-only. */
+    readonly state: Readonly<Record<string, unknown>>;
+}
+export interface GuardrailRule {
+    readonly id: string;
+    /** Tool names this rule applies to; omitted matches every tool. */
+    readonly tool?: string | readonly string[];
+    /** Regex source, compiled once; tested against matched argument strings. Exactly one of `pattern` / `deny`. */
+    readonly pattern?: string | RegExp;
+    /** Dot path(s) of arguments to test (e.g. `command`, `["from", "to"]`); omitted deep-scans argument strings. */
+    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` 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;
+}
+/** Built-in pack selection by `id` (optional `options`), or an inline pack when `rules` is present. */
+export interface GuardrailPackInput {
+    readonly id: string;
+    readonly version?: number;
+    readonly options?: Readonly<Record<string, unknown>>;
+    readonly rules?: readonly GuardrailRule[];
+}
+/** A session's `guardrailPacks` entry: built-in pack id, or an inline/built-in pack input object. */
+export type GuardrailPackRef = string | GuardrailPackInput;

package/dist/contracts-core/guardrail-packs.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=guardrail-packs.js.map

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

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

@@ -62,6 +62,36 @@ export interface AIProvider {
     readonly id: string;
     generate(request: ProviderRequest): AsyncIterable<ProviderEvent>;
 }
+/**
+ * Closed taxonomy for why a provider turn stopped (plan 087 T1). Adapters map native wire
+ * reasons (`finish_reason`, `stop_reason`, `finishReason`, Converse `stopReason`) through the
+ * shared `mapProviderStopReason` table; `unknown` is the escape hatch for a new wire value.
+ */
+export type ProviderStopReason = "end_turn" | "tool_calls" | "max_output_tokens" | "content_filter" | "abort" | "provider_error" | "unknown";
+/**
+ * Effective budget snapshot at provider-turn end (plan 087 T1): current-turn input tokens
+ * against the per-request input cap, cumulative run input against its budget, and the turn
+ * axis, so a host can see which limit was closest without instrumenting the session.
+ */
+export interface TurnBudgets {
+    /** Input tokens charged for this turn: provider-reported, or a labeled fallback estimate when the
+     *  provider reported none; absent when neither exists. See `inputTokensSource`. */
+    readonly inputTokens?: number;
+    /** Provenance of `inputTokens`: `"reported"` from the provider, `"estimated"` from the
+     *  `usageEstimation: "fallback"` seam. Absent together with `inputTokens`; `usage.estimated` stays
+     *  the authoritative label for the turn's usage. */
+    readonly inputTokensSource?: "reported" | "estimated";
+    /** Resolved per-request input cap (attention compiler when enabled); absent when no cap derivable. */
+    readonly inputCap?: number;
+    /** Cumulative run input budget (`RunLimits.maxInputTokens`); absent when the axis is disabled. */
+    readonly runInputBudget?: number;
+    /** Cumulative input tokens charged this run (all provider turns). */
+    readonly runInputUsed: number;
+    /** Provider turns started this run (1-based current turn at turn end). */
+    readonly turns: number;
+    /** Resolved clean turn cap; `null` when disabled. */
+    readonly maxTurns: number | null;
+}
 export type ProviderResolver = (model: ModelConfig) => AIProvider | undefined;
 /** Realtime audio/session event. Realtime is a bidirectional session, not a request/response
  *  stream, so it is a separate neutral seam from `AIProvider.generate()`. Credentials are

package/dist/contracts-core/run-limits.d.ts

@@ -22,6 +22,12 @@ export interface RunLimits {
         readonly amount: number;
         readonly currency: string;
     };
+    /**
+     * Clean cap on stop-hook continuations in one run (plan 106 R1). Default 3; `0` observes stop
+     * hooks but never continues; `null` disables the cap. Layers narrow by min like every other
+     * policy axis, and the cap ends the run with `stopReason: "hook_limit"` (no limit breach).
+     */
+    readonly maxStopContinuations?: number | null;
 }
 /** Fully resolved limits after `resolveRunLimits`: every policy axis is a finite cap or `null` (disabled). */
 export interface ResolvedRunLimits {
@@ -39,8 +45,11 @@ export interface ResolvedRunLimits {
         readonly amount: number;
         readonly currency: string;
     };
+    /** Stop-hook continuation cap (plan 106 R1); not a run-limit counter axis. */
+    readonly maxStopContinuations: number | null;
 }
-export type RunLimitName = keyof Required<RunLimits>;
+/** Counter-backed limit axes; `maxStopContinuations` caps a clean stop instead of a breach. */
+export type RunLimitName = Exclude<keyof Required<RunLimits>, "maxStopContinuations">;
 export interface RunLimitCounters {
     readonly turns: number;
     readonly providerAttempts: number;
@@ -60,6 +69,25 @@ export interface RunLimitBreach {
     readonly observed: number;
     readonly currency?: string;
 }
+/** One dispatched host tool call, bounded to id + name + argument hash (plan 087 T2). */
+export interface ToolCallSummary {
+    readonly id: string;
+    readonly name: string;
+    /** `sha256:<64 hex>` over the canonicalized arguments; raw arguments never enter events. */
+    readonly argHash: string;
+}
+/** One run-limit axis and how close it came to its cap: `used / cap` in [0, 1] (plan 087 T2). */
+export interface BudgetAxisUsage {
+    readonly axis: RunLimitName;
+    readonly usedRatio: number;
+}
+/** Run counters at exhaustion (plan 087 T2): the axes a host reads first when attributing a death. */
+export interface BudgetConsumedCounters {
+    readonly turns: number;
+    readonly inputTokens: number;
+    readonly providerAttempts: number;
+    readonly requestBytes: number;
+}
 export type GuardrailStage = "input" | "output" | "tool_input" | "tool_output";
 export type GuardrailAction = "allow" | "block" | "tripwire" | "interrupt";
 export type GuardrailValue<S extends GuardrailStage> = S extends "input" ? readonly Message[] : S extends "output" ? ProviderTurnResult : S extends "tool_input" ? ToolCallContent : ToolResult;

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

@@ -35,8 +35,8 @@ export interface SessionStore {
     /**
      * Optional bounded session search. Prefer implementing this **or** returning a companion
      * `SessionIndex` from the adapter factory — hosts must not need both. Call
-     * `resolveSessionSearchQuery` before scan/query. Memory defaults to capped linear
-     * search (`sessionSearchMode: "unsupported"` throws). JSONL throws unsupported.
+     * `resolveSessionSearchQuery` before scan/query. Memory and JSONL default to capped linear
+     * search (memory `sessionSearchMode: "unsupported"` throws); DB adapters index.
      */
     searchSessions?(query: SessionSearchQuery): Promise<PersistencePage<SessionSearchHit>>;
 }
@@ -58,11 +58,18 @@ export declare const DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES: number;
 export declare const HARD_MAX_SESSION_SEARCH_LINEAR_BYTES: number;
 export declare const DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES = 1000;
 export declare const HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES = 5000;
+/** Entry-kind filter for `SessionSearchQuery.kind`; `"any"` (the default) matches every kind. */
+export type SessionSearchKind = SessionEntryKind | "any";
 /** Bounded session search filters. Workspace matches host-written `metadata.workspaceRoot`. */
 export interface SessionSearchQuery extends PersistenceQuery, OwnershipScope {
     readonly workspaceRoot?: string;
     /** Optional full-text / message+summary query (adapter-defined matching). */
     readonly query?: string;
+    /**
+     * Restrict the text `query` to entries of these kinds (one kind or a list). Omitted or `"any"`
+     * matches every kind. Annotation search is `kind: ["label", "summary", "metadata", "custom"]`.
+     */
+    readonly kind?: SessionSearchKind | readonly SessionSearchKind[];
     readonly provider?: string;
     readonly model?: string;
     readonly label?: string;
@@ -73,11 +80,20 @@ export interface SessionSearchQuery extends PersistenceQuery, OwnershipScope {
 }
 /**
  * Safe search hit for resume/checkout. Never includes credentials or raw full transcripts.
- * `leafId` is the branch tip for `session.checkout` when known.
+ * `leafId` is the branch tip for `session.checkout` when known; when a text `query` matched,
+ * `entryId`/`runId`/`turn`/`score` point at the matched entry and `snippet` is its matched text.
  */
 export interface SessionSearchHit {
     readonly sessionId: string;
     readonly leafId?: string;
+    /** Transcript entry that matched the text `query` (absent for filter-only searches). */
+    readonly entryId?: string;
+    /** Run that wrote the matched entry. */
+    readonly runId?: string;
+    /** 1-based position of the matched entry in the session transcript (`(timestamp, id)` order). */
+    readonly turn?: number;
+    /** Matched-entry relevance from the store's full-text index; higher is better (0 is a valid score). */
+    readonly score?: number;
     readonly updatedAt?: string;
     readonly label?: string;
     readonly summary?: string;
@@ -89,10 +105,12 @@ export interface SessionSearchHit {
 export interface SessionIndex {
     search(query: SessionSearchQuery): Promise<PersistencePage<SessionSearchHit>>;
 }
-/** Validated search query with finite `limit` / `order` filled in. */
+/** Validated search query with finite `limit` / `order` filled in and `kind` normalized. */
 export interface ResolvedSessionSearchQuery extends SessionSearchQuery {
     readonly limit: number;
     readonly order: "asc" | "desc";
+    /** Concrete kinds to match, or `undefined` for "any". */
+    readonly kind?: readonly SessionEntryKind[];
 }
 /**
  * O(1) validation before any scan/query. Applies default page limit; rejects NaN,
@@ -100,7 +118,7 @@ export interface ResolvedSessionSearchQuery extends SessionSearchQuery {
  */
 export declare function resolveSessionSearchQuery(query: SessionSearchQuery): ResolvedSessionSearchQuery;
 export declare const SESSION_SEARCH_UNSUPPORTED_CODE: "session_search_unsupported";
-/** Thrown when a store opts out of `searchSessions` (memory `unsupported`, JSONL). */
+/** Thrown when a store opts out of `searchSessions` (memory `sessionSearchMode: "unsupported"`). */
 export declare class SessionSearchUnsupportedError extends Error {
     readonly code: "session_search_unsupported";
     constructor(message?: string);