@arnilo/prism 0.7.0 → 0.9.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));

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

@@ -10,6 +10,7 @@ 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 { GuardrailPackRef } from "./guardrail-packs.js";
 import type { AgentLoopOptions, AgentLoopStrategy } from "./loop.js";
 import type { OwnershipScope } from "./persistence.js";
 import type { AIProvider, ProviderRequestOptions, ProviderResolver } from "./provider.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,21 @@ 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 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.
+     */
+    readonly usageEstimation?: "fallback" | "off";
     readonly inputBuilder?: InputBuilder;
     readonly promptBuilder?: PromptBuilder;
     readonly middleware?: MiddlewareRegistry;
@@ -134,6 +156,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
@@ -277,6 +305,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,15 +2,19 @@
  * 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 {
     readonly [key: string]: JsonValue;
 }
+export type ProviderFailureClass = "quota" | "auth" | "rate_limited" | "transient" | "permanent" | "unknown";
 export interface ErrorInfo {
     readonly name?: string;
     readonly message: string;
     readonly code?: string | number;
+    /** Advisory classification stamped only for provider failures; it never changes retry behavior. */
+    readonly failureClass?: ProviderFailureClass;
     /** Provider backpressure hint (e.g. from a `Retry-After` header); retry policies
      *  honor it capped at their own `maxDelayMs`. */
     readonly retryAfterMs?: number;
@@ -102,6 +106,8 @@ export interface ModelCapabilities {
     readonly output?: readonly string[];
     readonly reasoning?: boolean;
     readonly tools?: boolean;
+    /** Advisory, conformance-derived tool-call behavior. Absent means unknown; it never changes runtime tool validation. */
+    readonly toolCallStrictness?: "strict" | "lenient" | "legacy";
     readonly streaming?: boolean;
     /** Native JSON-schema structured output support for this model. */
     readonly structuredOutput?: boolean | "json_schema";
@@ -172,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/guardrail-packs.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+import type { JsonObject } from "./content.js";
+export type GuardrailRuleAction = "deny" | "tripwire";
+/** 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` has no deterministic seam (plan 092 Task 1). */
+    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

@@ -4,6 +4,48 @@ import type { AgentEvent, AgentFinishReason, ProviderTurnResult, ToolResult } fr
 import type { AgentInput } from "../input.js";
 import type { JsonValue, Message, ToolCallContent, Usage } from "./content.js";
 import type { ProviderRequest, StructuredOutputOptions } from "./provider.js";
+/**
+ * Metadata-only view of a run at a provider-turn boundary (plan 084 Task 2). Hosts branch on
+ * counters, never content: tool arguments, prompts, and tool results are not fields.
+ */
+export interface TurnBoundaryContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    /** 1-based index of the provider turn this boundary precedes. */
+    readonly turn: number;
+    /** Provider turns already completed in this run (`turn - 1`; 0 at the first boundary). */
+    readonly turns: number;
+    /** Host tool calls dispatched so far in this run. */
+    readonly toolCalls: number;
+    /** Run-total usage so far, when the provider reported any. */
+    readonly usage?: Usage;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+/** Synchronous decision at a turn boundary. `stop` ends the run cleanly; `continue` runs the turn. */
+export type TurnStopDecision = {
+    readonly action: "continue";
+} | {
+    readonly action: "stop";
+    readonly reason: string;
+};
+/**
+ * Host turn policy (plan 084 Task 2). Evaluated before every provider request, at the same
+ * boundary a `checkpointPolicy: "every-turn"` checkpoint is written. Omit it and the run keeps
+ * its exact 0.8.x turn structure (no callback, no reads).
+ */
+export interface TurnPolicyOptions {
+    /**
+     * Clean turn cap. Reaching it stops the run (`stopReason: "turn_limit"`) instead of failing it
+     * with a limit breach. A run overlay may only narrow `limits.maxTurns`; widening throws.
+     */
+    readonly maxTurns?: number;
+    /**
+     * Consulted before every provider request. Returning `stop` ends the run cleanly with
+     * `stopReason: "host_policy"` and a resumable checkpoint (`decision: "continue"` resumes it).
+     * Must be synchronous and must not throw; a throw fails the run with `ERR_PRISM_TURN_POLICY`.
+     */
+    readonly stop?: (context: TurnBoundaryContext) => TurnStopDecision;
+}
 export interface LoopContext {
     readonly sessionId: string;
     readonly runId: string;

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

@@ -62,6 +62,31 @@ 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 {
+    /** Provider-reported input tokens for this turn; absent when the provider reported none. */
+    readonly inputTokens?: number;
+    /** 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

@@ -60,6 +60,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;
@@ -70,6 +89,8 @@ export interface GuardrailContext<S extends GuardrailStage> {
     readonly runId: string;
     readonly toolCallId?: string;
     readonly toolName?: string;
+    /** Same-run completed host tool results, available only at the output stage. */
+    readonly toolResults?: S extends "output" ? readonly ToolResult[] : never;
     readonly metadata: Readonly<Record<string, unknown>>;
     readonly signal: AbortSignal;
 }

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);

package/dist/contracts-core/session.js

@@ -56,7 +56,26 @@ export function resolveSessionSearchQuery(query) {
     assertSearchStringBytes(query.userId, "userId", HARD_MAX_SESSION_SEARCH_QUERY_BYTES);
     assertSearchStringBytes(query.fromUpdatedAt, "fromUpdatedAt", HARD_MAX_SESSION_SEARCH_QUERY_BYTES);
     assertSearchStringBytes(query.toUpdatedAt, "toUpdatedAt", HARD_MAX_SESSION_SEARCH_QUERY_BYTES);
-    return { ...query, limit, order };
+    return { ...query, limit, order, kind: resolveSessionSearchKinds(query.kind) };
+}
+/** Normalize `kind` to concrete entry kinds (`undefined` = any). Unknown or mixed `"any"` fails closed. */
+function resolveSessionSearchKinds(kind) {
+    if (kind === undefined || kind === "any")
+        return undefined;
+    const values = typeof kind === "string" ? [kind] : kind;
+    const kinds = [];
+    for (const value of values) {
+        if (value === "any")
+            throw new TypeError('SessionSearchQuery.kind cannot mix "any" with entry kinds');
+        if (!isSessionEntryKind(value)) {
+            throw new TypeError(`SessionSearchQuery.kind must be a session entry kind or "any"; got ${JSON.stringify(value)}`);
+        }
+        if (!kinds.includes(value))
+            kinds.push(value);
+    }
+    if (kinds.length === 0)
+        throw new TypeError("SessionSearchQuery.kind must name at least one entry kind");
+    return kinds;
 }
 function assertSearchStringBytes(value, name, hardMax) {
     if (value === undefined)
@@ -71,7 +90,7 @@ function assertSearchStringBytes(value, name, hardMax) {
     }
 }
 export 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 class SessionSearchUnsupportedError extends Error {
     code = SESSION_SEARCH_UNSUPPORTED_CODE;
     constructor(message = "session search is unsupported by this store") {

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

@@ -0,0 +1,40 @@
+/** Contracts-core usage family (plan 091 Task 1): labeled token-estimation types.
+ *
+ * Estimation exists for the "missing usage is never zero usage" accounting rule:
+ * when a provider reports no usage, a host may show a labeled approximation. An
+ * estimate is never provider truth — reported usage always wins and is never
+ * overwritten by one of these. */
+/** Model families with a chars/token table (`MODEL_FAMILY_TOKENS`). `unknown`
+ *  is the conservative fallback used when a model id/name matches no family. */
+export type ModelFamily = "anthropic" | "openai" | "google" | "deepseek" | "openrouter-generic" | "mistral" | "unknown";
+/** Confidence label on an estimated token count. `high` is reserved for a real
+ *  tokenizer (Prism ships none); the calibrated family tables are `medium`, and
+ *  the unknown-family fallback is `low`. */
+export type TokenEstimateConfidence = "high" | "medium" | "low";
+/** Labeled token estimate. Never conflate with `Usage`: estimates are
+ *  approximations for context metering and labeling, reported usage is provider
+ *  truth for billing. */
+export interface TokenEstimate {
+    readonly tokens: number;
+    readonly confidence: TokenEstimateConfidence;
+    /** Coarse `confidence === "low"` flag for UI badges and host-side labeling. */
+    readonly lowConfidence: boolean;
+}
+/**
+ * Context-fill read for hosts (plan 091 Task 2): the latest provider turn's input
+ * tokens with their provenance, plus the cap/budget resolved the same way the
+ * turn-budget snapshot resolves them. `source: "reported"` means the provider
+ * reported those tokens; `"estimated"` means they are a labeled approximation
+ * (never billing, never conflated with reported usage). Cap/budget/ratio are
+ * absent when the model or run cannot derive them.
+ */
+export interface ContextMeter {
+    readonly inputTokens: number;
+    readonly source: "reported" | "estimated";
+    /** Per-request input cap from the model window and `attentionCompiler` reserve. */
+    readonly inputCap?: number;
+    /** Cumulative run input budget (`RunLimits.maxInputTokens`); absent without run limits. */
+    readonly runInputBudget?: number;
+    /** `inputTokens / inputCap`; absent when no cap is derivable. */
+    readonly usedRatio?: number;
+}

package/dist/contracts-core/usage.js

@@ -0,0 +1,8 @@
+/** Contracts-core usage family (plan 091 Task 1): labeled token-estimation types.
+ *
+ * Estimation exists for the "missing usage is never zero usage" accounting rule:
+ * when a provider reports no usage, a host may show a labeled approximation. An
+ * estimate is never provider truth — reported usage always wins and is never
+ * overwritten by one of these. */
+export {};
+//# sourceMappingURL=usage.js.map

package/dist/contracts-core.d.ts

@@ -9,6 +9,7 @@ export * from "./contracts-core/compaction.js";
 export * from "./contracts-core/content.js";
 export * from "./contracts-core/embeddings.js";
 export * from "./contracts-core/extensions.js";
+export * from "./contracts-core/guardrail-packs.js";
 export * from "./contracts-core/images.js";
 export * from "./contracts-core/loop.js";
 export * from "./contracts-core/moderation.js";
@@ -19,4 +20,5 @@ export * from "./contracts-core/run-limits.js";
 export * from "./contracts-core/session.js";
 export * from "./contracts-core/speech.js";
 export * from "./contracts-core/transcription.js";
+export * from "./contracts-core/usage.js";
 export * from "./contracts-core/video.js";

package/dist/contracts-core.js

@@ -5,6 +5,7 @@ export * from "./contracts-core/compaction.js";
 export * from "./contracts-core/content.js";
 export * from "./contracts-core/embeddings.js";
 export * from "./contracts-core/extensions.js";
+export * from "./contracts-core/guardrail-packs.js";
 export * from "./contracts-core/images.js";
 export * from "./contracts-core/loop.js";
 export * from "./contracts-core/moderation.js";
@@ -15,5 +16,6 @@ export * from "./contracts-core/run-limits.js";
 export * from "./contracts-core/session.js";
 export * from "./contracts-core/speech.js";
 export * from "./contracts-core/transcription.js";
+export * from "./contracts-core/usage.js";
 export * from "./contracts-core/video.js";
 //# sourceMappingURL=contracts-core.js.map