@arnilo/prism 0.8.0 → 0.10.0

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

package/dist/contracts-protocol.d.ts

@@ -1,4 +1,6 @@
-import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, RetryOptions, RunLimitBreach, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, TurnPolicyOptions, Usage } from "./contracts-core.js";
+import type { CacheUsageReport } from "./cache-helpers.js";
+import type { CheckpointRestoreAudit } from "./checkpoint-restore.js";
+import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, BudgetAxisUsage, BudgetConsumedCounters, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, ProviderStopReason, RetryOptions, RunLimitBreach, RunLimitName, RunLimits, Skill, StopHook, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, ToolCallSummary, TurnBudgets, TurnPolicyOptions, Usage } from "./contracts-core.js";
 import type { AgentRunInterruption, AgentRunStateOptions } from "./contracts-run-state.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { ToolValidator } from "./tools.js";
@@ -28,6 +30,7 @@ export type ProviderEvent = {
 } | {
     readonly type: "done";
     readonly usage?: Usage;
+    readonly stopReason?: ProviderStopReason;
 } | {
     readonly type: "error";
     readonly error: ErrorInfo;
@@ -108,6 +111,10 @@ export interface RunOptions {
     readonly toolNames?: readonly string[];
     /** 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;
+    /** Per-turn restrictive allow-list over the run grant. Overrides `AgentConfig.toolNarrowing`. */
+    readonly toolNarrowing?: import("./contracts-core/agent.js").ToolNarrowing;
+    /** Opt-in: tools hidden this turn stay callable by name (default off). Overrides agent config. */
+    readonly allowHiddenToolCalls?: true;
     readonly toolsSearch?: import("./tool-search.js").ToolsSearchOptions;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
@@ -130,6 +137,8 @@ export interface RunOptions {
      * evaluated before every provider request. Omitted → no callback runs.
      */
     readonly turnPolicy?: TurnPolicyOptions;
+    /** Appended to agent-level stop hooks for this run (plan 106 R1). */
+    readonly stopHooks?: readonly StopHook[];
 }
 export interface ProviderTurnMetadata {
     readonly providerId: string;
@@ -140,6 +149,17 @@ export interface ProviderTurnMetadata {
     readonly httpStatus?: number;
     readonly rateLimitRemaining?: number;
     readonly rateLimitResetMs?: number;
+    /** Why the provider turn stopped (plan 087 T1); present on `provider_turn_finished` only. */
+    readonly stopReason?: ProviderStopReason;
+    /** Effective budget state at turn end (plan 087 T1); present on `provider_turn_finished` only. */
+    readonly budgets?: TurnBudgets;
+    /** Provider-reported cache usage and derived hit rate; absent when cache usage is unknown. */
+    readonly cache?: CacheUsageReport;
+    /** Effective tool menu this turn. Names hashed in request order; never includes args. */
+    readonly tools?: {
+        readonly count: number;
+        readonly idsHash: string;
+    };
 }
 export interface ToolExecutionMetadata {
     readonly durationMs: number;
@@ -175,9 +195,20 @@ export interface DelegatedAgentStep {
         readonly label?: string;
     };
 }
-/** Why a run stopped cleanly. `host_policy` is a `RunOptions.turnPolicy` stop; the rest are loop ceilings (F4). */
-export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal" | "host_policy";
-export type AgentEvent = {
+/** Why a run stopped cleanly. `host_policy` is a `RunOptions.turnPolicy` stop, `hook_limit` a stop-hook continuation cap; the rest are loop ceilings (F4). */
+export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal" | "host_policy" | "hook_limit";
+/**
+ * Origin of an agent event forwarded from a delegated child (supervisor child-event passthrough).
+ * Present only on child events routed onto a parent stream; absent on a session's own events.
+ */
+export interface ChildEventOrigin {
+    readonly childId: string;
+    readonly delegationId: string;
+    /** Delegation depth: 1 is a direct child of the hosting supervisor. */
+    readonly depth: number;
+}
+/** Payload union of every agent event; the exported `AgentEvent` adds the optional child origin tag. */
+type AgentEventPayload = {
     readonly type: "agent_started";
     readonly sessionId: string;
     readonly runId: string;
@@ -186,7 +217,7 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly usage?: Usage;
-    /** Why the loop stopped, when a limit/ceiling or a host turn policy ended the run cleanly (F4). Absent = natural end. */
+    /** Why the loop stopped, when a limit/ceiling, a host turn policy, or a stop-hook continuation cap ended the run cleanly (F4). Absent = natural end. */
     readonly finishReason?: AgentFinishReason;
     /** Host stop detail from `TurnPolicyOptions.stop` (≤256 bytes, redacted). Present only with `finishReason: "host_policy"`. */
     readonly stopDetail?: string;
@@ -201,6 +232,8 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly version: number;
+    /** Plan 094 Task 3: audit of the external-state restore hooks that ran before this claim. */
+    readonly restore?: CheckpointRestoreAudit;
 } | {
     readonly type: "agent_denied";
     readonly sessionId: string;
@@ -217,6 +250,17 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly turn: number;
+} | {
+    /**
+     * Host middleware completed this turn without a provider request (plan 096). No `usage` field:
+     * a deterministic turn has no provider cost, so accounting must never zero-fill one.
+     */
+    readonly type: "deterministic_turn";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    /** Answering middleware id (provenance); ids only, never free host code. */
+    readonly middleware: string;
 } | {
     readonly type: "provider_turn_started";
     readonly sessionId: string;
@@ -281,6 +325,13 @@ export type AgentEvent = {
     readonly reason: string;
     readonly error: ErrorInfo;
     readonly metadata: ToolExecutionMetadata;
+} | {
+    /** Host `toolNarrowing` asked for names outside the run grant; those names were dropped. */
+    readonly type: "tool_narrowing_clamped";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly dropped: readonly string[];
 } | {
     readonly type: "guardrail_decision";
     readonly sessionId: string;
@@ -293,6 +344,16 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly breach: RunLimitBreach;
+} | {
+    /** Terminal attribution for a run that died on a run limit (plan 087 T2): which axis fired,
+     *  counters at exhaustion, how close the other axes were, and hashes of recent tool calls. */
+    readonly type: "budget_exhausted";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly limit: RunLimitName;
+    readonly consumed: BudgetConsumedCounters;
+    readonly closestOtherAxes: readonly BudgetAxisUsage[];
+    readonly recentToolCalls: readonly ToolCallSummary[];
 } | {
     readonly type: "queue_updated";
     readonly sessionId: string;
@@ -383,6 +444,14 @@ export type AgentEvent = {
     readonly attempt: number;
     readonly result: ArtifactValidation;
 };
+/**
+ * One agent event. `child` is set only when the event was forwarded from a delegated child
+ * (e.g. supervisor `report: "stream"` passthrough), so hosts can route it onto a parent stream
+ * without per-event-type special cases. It never replaces the event's own `sessionId`/`runId`.
+ */
+export type AgentEvent = AgentEventPayload & {
+    readonly child?: ChildEventOrigin;
+};
 export type ToolEffectKind = "none" | "local_mutation" | "external_mutation";
 export type ToolEffectIdempotency = "none" | "optional" | "required" | "tool_managed" | "unsupported";
 /** Static or validated-argument classification of one tool call's side-effect behavior. */
@@ -688,4 +757,11 @@ export interface ProviderTurnResult {
     readonly messageId?: string;
     readonly started: boolean;
     readonly usage?: Usage;
+    /**
+     * Provenance for turns that did not come from the provider (plan 096):
+     * `{ deterministic: { middleware } }`. Copied onto the assistant `Message.metadata`, so it
+     * serializes with the transcript and survives replay. Absent for provider turns.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
+export {};

package/dist/contracts-run-state.d.ts

@@ -1,4 +1,5 @@
-import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ErrorInfo, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
+import type { CheckpointRestoreHook } from "./checkpoint-restore.js";
+import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointRecord, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ContextMeter, ErrorInfo, GuardrailPackRef, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
 import type { AgentEvent, AgentFinishReason, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
 export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
@@ -26,6 +27,16 @@ export interface PendingDecision {
     readonly reason: string;
     /** Typed payload contract for elicitation decisions. */
     readonly elicitationSchema?: JsonObject;
+    /**
+     * Plan 104 T3: pack `ask` rule that gated this call as `pack:<pack>/<rule>` (bounded by the
+     * compile-time id limits), present only when a pack rule raised the decision.
+     */
+    readonly guardrail?: string;
+    /** Plan 104 T3: machine-readable ids behind `guardrail`, so a host never parses the name. */
+    readonly guardrailRule?: {
+        readonly pack: string;
+        readonly rule: string;
+    };
     /** Delegation chain, root-first; core-written, never client-supplied. */
     readonly attribution?: {
         readonly path: readonly string[];
@@ -37,6 +48,8 @@ export interface AgentRunInterruption {
     readonly reason: string;
     readonly toolCallId?: string;
     readonly toolName?: string;
+    /** Plan 104 T3: the pack rule that raised this suspension (`pack:<pack>/<rule>`), when one did. */
+    readonly guardrail?: string;
     /** All unresolved approval requests of this suspension; absent for legacy single approvals. */
     readonly pendingDecisions?: readonly PendingDecision[];
 }
@@ -139,6 +152,15 @@ export declare const HARD_MAX_ACTION_CONSTRAINTS = 64;
 export declare const MAX_ATTRIBUTION_DEPTH = 8;
 export declare const MAX_ACTION_CONSTRAINT_BYTES: number;
 export declare const HARD_MAX_ACTION_CONSTRAINT_BYTES: number;
+/**
+ * Opaque host sidecar pinned to one checkpoint *record* (git commit, document version,
+ * workspace fingerprint) — never part of the run-state value, so it costs no `maxStateBytes`
+ * budget and is invisible to state parsing. Bounded to `MAX_AGENT_RUN_METADATA_BYTES` (4 KiB)
+ * and redacted like the state value at every write.
+ */
+export type AgentRunCheckpointMetadata = Readonly<Record<string, string>>;
+/** Host source for checkpoint sidecar metadata: a fixed map or a live provider resolved per write. */
+export type AgentRunCheckpointMetadataSource = AgentRunCheckpointMetadata | (() => AgentRunCheckpointMetadata | undefined);
 export interface AgentRunStateOptions {
     readonly checkpoints: CheckpointStore;
     /** Host-authored immutable revision required for durable runs. */
@@ -156,6 +178,12 @@ export interface AgentRunStateOptions {
     readonly checkpointPolicy?: "decision" | "every-turn";
     /** Suspend every tool call before its side effect. */
     readonly interruptBeforeTool?: boolean;
+    /**
+     * Sidecar metadata written with every checkpoint of this run (and carried into a resumed
+     * run). A provider is resolved at each checkpoint write, so a host closure can pin state
+     * that moves mid-run (e.g. the current git commit). Absent = records stay byte-identical.
+     */
+    readonly checkpointMetadata?: AgentRunCheckpointMetadataSource;
     readonly maxStateBytes?: number;
     readonly fencingToken?: number;
     /** Enables sticky auto-apply when a nested suspension first surfaces during this run. */
@@ -204,6 +232,23 @@ export interface AgentRunResume {
     /** Batch decision path; exactly one of decision/decisions. Applied as one atomic CAS transition. */
     readonly decisions?: readonly RunDecision[];
 }
+/**
+ * Checkpoint handed to a restore hook (plan 094 Task 3). `checkpoint.value` is the raw stored
+ * run-state value; `metadata` is the redacted, bounded sidecar map hosts write via
+ * `AgentRunStateOptions.checkpointMetadata`.
+ */
+export interface AgentCheckpointRestoreContext {
+    readonly runId: string;
+    readonly sessionId: string;
+    /** Version of the checkpoint being claimed; a hook may pass it to an external system's own CAS. */
+    readonly version: number;
+    /** State being claimed: `running` for crash recovery, `suspended` for a decision resume. */
+    readonly status: AgentRunStatus | "running";
+    readonly metadata?: AgentRunCheckpointMetadata;
+    readonly checkpoint: CheckpointRecord;
+}
+/** Host code restoring one external layer before a durable resume applies. */
+export type AgentCheckpointRestoreHook = CheckpointRestoreHook<AgentCheckpointRestoreContext>;
 export interface AgentRunResumeOptions {
     readonly checkpoints: CheckpointStore;
     /** Current host-authored revision; must exactly match the checkpoint. */
@@ -224,6 +269,20 @@ export interface AgentRunResumeOptions {
     readonly persistSessionState?: boolean;
     /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies (requires `persistSessionState` too). */
     readonly includeSkillBodies?: boolean;
+    /**
+     * Checkpoint sidecar metadata for the claim write (and the resumed run's later checkpoints).
+     * Absent = the record's existing metadata is preserved unchanged.
+     */
+    readonly checkpointMetadata?: AgentRunCheckpointMetadataSource;
+    /**
+     * Plan 094 Task 3: external-state restore hooks. Every hook must succeed (sequentially, each
+     * within `restoreHookTimeoutMs`) before the claim write and the conversation restore apply;
+     * the first failure throws `CheckpointRestoreError` naming the hook and leaves the checkpoint
+     * suspended. Hosts that register hooks on the lifecycle instead pass them once there.
+     */
+    readonly restoreHooks?: readonly AgentCheckpointRestoreHook[];
+    /** Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
+    readonly restoreHookTimeoutMs?: number;
 }
 /** Bounded live-event options for `resumeAgentRunStream()`; `signal` is inherited from the base resume options. */
 export interface AgentRunResumeStreamOptions extends AgentRunResumeOptions, SubscribeOptions {
@@ -235,6 +294,8 @@ export interface AgentRunRef {
 export interface AgentRunStatusResult {
     readonly state: AgentRunState;
     readonly version: number;
+    /** Checkpoint sidecar metadata; absent when the record carries none (or carries only malformed entries). */
+    readonly metadata?: AgentRunCheckpointMetadata;
 }
 export declare class AgentRunStateError extends Error {
     readonly code = "ERR_PRISM_AGENT_RUN_STATE";
@@ -301,6 +362,12 @@ export interface SteerOptions {
 }
 export interface AgentSession {
     readonly id: string;
+    /**
+     * Plan 104 Task 2: guardrail pack refs this session enforces (the restored rows after a durable
+     * resume); `undefined` when it enforces none. Pass to `snapshotRunBundle({ packs })` for the
+     * recorded identity that matches enforcement.
+     */
+    readonly guardrailPackRefs?: readonly GuardrailPackRef[];
     /** Current branch leaf entry id; advances on every append/run and is re-pointed by `checkout`.
      *  Undefined until the first entry lands (a fresh session with no history). */
     readonly leafId: string | undefined;
@@ -312,13 +379,35 @@ export interface AgentSession {
      * Fails closed when no run is active or the pending queue exceeds caps.
      */
     steer(input: string | Message | readonly Message[], options?: SteerOptions): void;
-    /** Subscribe first, then start exactly one run and yield only that run's events until it terminates. */
+    /**
+     * Subscribe first, then start exactly one run and yield only that run's events until it terminates.
+     * This subscription belongs to `stream()`: it is closed when the owned run settles (so a pre-flight
+     * rejection unblocks the consumer instead of parking it behind a run that never emits).
+     */
     stream(input: string | Message | readonly Message[], options?: RunOptions & SubscribeOptions): AsyncIterable<AgentEvent>;
     compact(options?: CompactionOptions): Promise<CompactionResult>;
+    /**
+     * Subscribe to this session's live events. A run-scoped subscriber (default) is closed when the run
+     * ends, suspends, or is denied; `SubscribeOptions.acrossRuns: true` keeps it open across runs until
+     * `subscription.close()`, `closeSubscribers()`, or a queue overflow closes it.
+     */
     subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
+    /**
+     * Plan 106 R2: session teardown. Dispatches `session_shutdown` middleware once (idempotent), then
+     * closes every subscriber (`acrossRuns` included); calling it twice is a no-op. Call after the
+     * active run settles. Subscriber-only teardown stays `break`ing the `for await` (or calling the
+     * iterator's `return()`). See [Agent/session runtime](agent-session-runtime.md).
+     */
+    close(): Promise<void>;
     abort(reason?: unknown): void;
     entries(): Promise<readonly SessionEntry[]>;
     checkout(leafId?: string): Promise<void>;
+    /**
+     * Context-fill read (plan 091 T2): latest provider turn's input tokens
+     * (reported or labeled estimate) plus the resolved per-request cap, run input
+     * budget, and used ratio. Before any provider turn it estimates stored history.
+     */
+    contextMeter(): ContextMeter;
     fork(options?: AgentSessionForkOptions): AgentSession;
     clone(options?: AgentSessionCloneOptions): Promise<AgentSession>;
 }

package/dist/contributions.d.ts

@@ -1,4 +1,4 @@
-import type { AgentDefinition, AuthMethod, CommandDefinition, CompactionStrategy, ContextProvider, CredentialResolver, DiscoveredContribution, InputBuilder, InstructionInjector, PromptBuilder, ProviderPackage, ProviderRequestPolicy, ResourceLoader, RetryPolicy, SettingsProvider, Skill, StoreFactory, SystemPromptContribution, ToolDefinition } from "./contracts.js";
+import type { AgentDefinition, AuthMethod, CommandDefinition, CompactionStrategy, ContextProvider, CredentialResolver, DiscoveredContribution, InputBuilder, InstructionInjector, PromptBuilder, ProviderPackage, ProviderRequestPolicy, ResourceLoader, RetryPolicy, SettingsProvider, Skill, StopHook, StoreFactory, SystemPromptContribution, ToolDefinition } from "./contracts.js";
 import { type ModelRegistry } from "./models.js";
 import { type ProviderRegistry } from "./providers.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
@@ -35,6 +35,7 @@ export interface ContributionRegistries {
     readonly providerRequestPolicies: ContributionRegistry<ProviderRequestPolicy>;
     readonly systemPromptContributions: ContributionRegistry<SystemPromptContribution>;
     readonly instructionInjectors: ContributionRegistry<InstructionInjector>;
+    readonly stopHooks: ContributionRegistry<StopHook>;
 }
 export interface ContributionRegistriesOptions extends DuplicateRegistrationOptions {
 }

package/dist/contributions.js

@@ -49,6 +49,7 @@ export function createContributionRegistries(options = {}) {
         providerRequestPolicies: createContributionRegistry(registryOptions("provider request policy")),
         systemPromptContributions: createContributionRegistry(registryOptions("system prompt contribution")),
         instructionInjectors: createContributionRegistry(registryOptions("instruction injector")),
+        stopHooks: createContributionRegistry(registryOptions("stop hook")),
     };
 }
 /** Register discovered contributions into the given registries. Inert: skill

package/dist/extensions.d.ts

@@ -1,4 +1,4 @@
-import type { CommandDefinition, ContextProvider, Extension, ExtensionEvent, ExtensionLifecycleEventName, InstructionInjector, Skill, ToolDefinition } from "./contracts.js";
+import type { AgentEvent, CommandDefinition, ContextProvider, Extension, ExtensionEvent, ExtensionLifecycleEventName, InstructionInjector, Skill, StopHook, ToolDefinition } from "./contracts.js";
 import { type ContributionRegistries } from "./contributions.js";
 import { type MiddlewareRegistry } from "./middleware.js";
 import { type PermissionPolicy } from "./security.js";
@@ -40,6 +40,18 @@ export interface ExtensionKernel {
 }
 export declare function createExtensionEventBus(options?: Pick<ExtensionKernelOptions, "errorPolicy" | "secrets">): ExtensionEventBus;
 export declare function createExtensionKernel(options?: ExtensionKernelOptions): ExtensionKernel;
+export interface AgentEventBridgeOptions {
+    /** Bridge-side failure (a source error, or a bus listener that throws under `errorPolicy: "throw"`).
+     *  Never rethrown — the bridge must not fail the run it is observing. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Forward an `AgentEvent` iterable onto the extension bus, one mapped lifecycle event at a time
+ * (plan 106 R2). Handlers run in event order and never in the run's path, so a slow or throwing
+ * listener cannot stall or fail the observed run. Returns an unsubscribe that stops forwarding and
+ * releases the source iterator.
+ */
+export declare function forwardAgentEvents(source: AsyncIterable<AgentEvent>, events: Pick<ExtensionEventBus, "emit">, options?: AgentEventBridgeOptions): () => void;
 /** Host-owned activation: copy contributed entries into the `createAgent()`
  *  fields that accept plain arrays. Contributions stay inert until the host
  *  passes the returned fields into runtime config. Array slots only —
@@ -51,6 +63,8 @@ export interface ActivatedKernelConfig {
     readonly skills: readonly Skill[];
     readonly instructionInjectors: readonly InstructionInjector[];
     readonly context: readonly ContextProvider[];
+    /** Run-end stop hooks (plan 106 R1); pass to `createAgent({ stopHooks })`. */
+    readonly stopHooks: readonly StopHook[];
     /** For host command surfaces (CLI/RPC/UI); not part of `AgentConfig`. */
     readonly commands: readonly CommandDefinition[];
     /** The kernel middleware registry itself; runs only when passed to runtime config. */

package/dist/extensions.js

@@ -143,6 +143,10 @@ export function createExtensionKernel(options = {}) {
             registries.instructionInjectors.register(injector.name, injector);
             track?.(() => registries.instructionInjectors.unregister(injector.name));
         },
+        registerStopHook(hook) {
+            registries.stopHooks.register(hook.name, hook);
+            track?.(() => registries.stopHooks.unregister(hook.name));
+        },
     });
     const unwind = (undo) => {
         for (const fn of undo.reverse()) {
@@ -190,12 +194,76 @@ export function createExtensionKernel(options = {}) {
         },
     };
 }
+/**
+ * Lifecycle hook each forwarded `AgentEvent` maps onto (plan 106 R2). Notification only: the bus
+ * receives the original event as `payload` and nothing is transformed. Events not listed here are
+ * ignored — notably `agent_finished` stays an AgentEvent and is not re-emitted as a bus event.
+ */
+const AGENT_EVENT_BRIDGE = {
+    agent_started: "before_agent_start",
+    turn_started: "turn",
+    turn_finished: "turn",
+    tool_execution_started: "tool_call",
+    tool_execution_finished: "tool_result",
+};
+/**
+ * Forward an `AgentEvent` iterable onto the extension bus, one mapped lifecycle event at a time
+ * (plan 106 R2). Handlers run in event order and never in the run's path, so a slow or throwing
+ * listener cannot stall or fail the observed run. Returns an unsubscribe that stops forwarding and
+ * releases the source iterator.
+ */
+export function forwardAgentEvents(source, events, options = {}) {
+    const iterator = source[Symbol.asyncIterator]();
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A throwing error callback must not become an unhandled rejection.
+        }
+    };
+    let stopped = false;
+    // Serially chained so a listener that awaits keeps event order; the run never awaits this chain.
+    let pending = Promise.resolve();
+    void (async () => {
+        try {
+            while (!stopped) {
+                const { value, done } = await iterator.next();
+                if (done || stopped)
+                    return;
+                const type = AGENT_EVENT_BRIDGE[value.type];
+                if (type === undefined)
+                    continue;
+                const event = { type, payload: value };
+                pending = pending.then(() => events.emit(event)).catch(report);
+            }
+        }
+        catch (error) {
+            if (!stopped)
+                report(error);
+        }
+    })();
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        void (async () => {
+            try {
+                await iterator.return?.();
+            }
+            catch (error) {
+                report(error);
+            }
+        })();
+    };
+}
 export function activateKernel(kernel) {
     return {
         tools: kernel.registries.tools.list(),
         skills: kernel.registries.skills.list(),
         instructionInjectors: kernel.registries.instructionInjectors.list(),
         context: kernel.registries.contextProviders.list(),
+        stopHooks: kernel.registries.stopHooks.list(),
         commands: kernel.registries.commands.list(),
         middleware: kernel.middleware,
     };

package/dist/guardrail-packs/coding-standard.d.ts

@@ -0,0 +1,3 @@
+import type { GuardrailPackDefinition } from "./types.js";
+/** Canned coding hygiene: file mutations confined to configured roots, test files read-only. */
+export declare const codingStandardPack: GuardrailPackDefinition;