zidane 5.6.11 → 5.6.13

package/dist/{agent-C9AKTU_V.d.ts → agent-ClkpElCZ.d.ts}

@@ -2,6 +2,8 @@ import { a as ExecutionContext, o as ExecutionHandle } from "./types-KukEp-mi.js
 import { Hookable } from "hookable";
 import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import Anthropic from "@anthropic-ai/sdk";
+
 //#region src/errors.d.ts
 /**
  * Typed error classes for agent runs.
@@ -422,6 +424,131 @@ interface McpServerConfig {
    */
   lazyConnect?: boolean;
 }
+/**
+ * Configuration for the loop's retry-with-backoff policy around
+ * `provider.stream()`. See {@link AgentBehavior.retry}.
+ */
+interface RetryConfig {
+  /**
+   * Maximum number of attempts including the initial call. `1` disables retry.
+   * Values below `1`, non-finite, or non-integer fall back to the default.
+   *
+   * Default: `3`.
+   */
+  maxAttempts?: number;
+  /**
+   * Initial backoff delay in milliseconds. Subsequent delays double
+   * (exponential) before jitter is applied and the cap enforced.
+   *
+   * Default: `1000`.
+   */
+  initialDelayMs?: number;
+  /**
+   * Upper bound on any single backoff delay in milliseconds. Caps both the
+   * exponential schedule and any `retry-after` header the server returns.
+   *
+   * Default: `30_000`.
+   */
+  maxDelayMs?: number;
+}
+/**
+ * Per-tool argument hasher used by {@link AgentBehavior.dedupTools}.
+ *
+ * Returning a non-empty string activates dedup with that string as the
+ * cache key. Returning `undefined` (or `''` / non-string) opts THIS call
+ * out — the tool runs normally and no state is recorded. See
+ * `dedupTools` for the full contract.
+ */
+type DedupHasher = (input: Record<string, unknown>) => string | undefined;
+/**
+ * Per-tool dedup configuration. Two equivalent forms:
+ *
+ * - **Hasher only** (legacy form): a bare function. The framework runs
+ *   in `'replay'` mode — identical re-calls replay the prior result.
+ *   Existing consumers that pass a function continue working unchanged.
+ * - **Config object**: explicit `hasher` plus a `mode`:
+ *   - `'replay'` (default) — replay the cached result on identical re-
+ *     calls. Cheap loop, but doesn't BREAK the loop — the model keeps
+ *     seeing the same tool_result and keeps trying.
+ *   - `'block-after'` — replay for the first `threshold` identical calls,
+ *     then refuse with `Blocked: <reason>` via `tool:gate`. Designed to
+ *     break tight loops where the model fixates on a single failing
+ *     call. The block lands on the Nth identical call (i.e. once the
+ *     total count reaches `threshold`); the cap is sticky — every
+ *     subsequent identical call also blocks until a different input
+ *     resets the counter.
+ *
+ * `reason` is the model-visible refusal text. The framework formats the
+ * final tool_result as `Blocked: <reason>` (see `tool:gate` docs).
+ * Strings are used verbatim; the callback form receives the input and
+ * the (now-blocking) repeat count so it can produce per-invocation
+ * messaging like `Blocked: 4 identical "shell" calls — try a different
+ * approach`. Default reason is generic but actionable.
+ */
+/**
+ * Pluggable client-side context compactor — see
+ * {@link AgentBehavior.compactStrategy}. The loop invokes this in place
+ * of the built-in tail elision when `compactStrategy` is a function.
+ *
+ * Contract:
+ * - Operates on the wire-level message list — the post-alias / post-
+ *   sanitize / post-`context:transform` view the provider will see.
+ *   The framework treats the returned array as the new wire payload;
+ *   `ctx.session` / `ctx.turns` are never modified.
+ * - Must preserve `tool_use ↔ tool_result` adjacency. Stranding a
+ *   `tool_use` without its matching `tool_result` (or vice versa) will
+ *   trip the loop's pair-repair pass and either repair the violation
+ *   or throw (`strictToolPairing`).
+ * - The trailing user message must remain — providers reject
+ *   assistant-tail wire payloads. If unsure, leave the last user turn
+ *   intact and operate on the prefix only.
+ * - May return the input verbatim (e.g. when the total stays under the
+ *   host's threshold).
+ * - Sync or async. The loop awaits the result, so a long-running LLM
+ *   summarizer will block the next turn — keep latency in mind.
+ *
+ * `ctx.threshold` and `ctx.keepTurns` are forwarded from
+ * `behavior.compactThreshold` / `behavior.compactKeepTurns` so hosts
+ * can reuse the same knobs the built-in tail mode uses.
+ * `ctx.totalBytes` is the pre-compaction total — the same number the
+ * tail mode uses to gate its threshold check, exposed so the function
+ * can short-circuit on under-threshold inputs without recomputing.
+ */
+type CompactFunction = (messages: SessionMessage[], ctx: {
+  /** Resolved `behavior.compactThreshold` (default `131_072` when unset). */threshold: number; /** Resolved `behavior.compactKeepTurns` (default `4` when unset). */
+  keepTurns: number;
+  /**
+   * Pre-compaction sum of `tool_result` output bytes across `messages`
+   * — the same heuristic the built-in tail mode uses to decide
+   * whether to act. Forwarded so the function can `return messages`
+   * verbatim on a quick under-threshold check.
+   */
+  totalBytes: number;
+}) => SessionMessage[] | Promise<SessionMessage[]>;
+type DedupToolConfig = DedupHasher | {
+  hasher: DedupHasher;
+  mode?: 'replay' | 'block-after';
+  /**
+   * For `mode: 'block-after'` only — total count of identical calls
+   * (including the first dispatch) at which the gate switches from
+   * replay to block. Threshold `4` blocks the 4th identical call;
+   * the first 3 (one dispatch + two replays) still go through.
+   *
+   * Ignored for `mode: 'replay'`. Default: `4`. Values `<= 1` are
+   * clamped to `2` (anything less would block the very first replay,
+   * which would behave the same as not having a hasher at all).
+   */
+  threshold?: number;
+  /**
+   * Refusal text rendered into the model-visible tool_result as
+   * `Blocked: <reason>`. Either a literal string or a callback that
+   * receives the call's input and the repeat count (1-indexed total
+   * of identical calls so far, including this blocking one).
+   *
+   * Default: a generic "identical call repeated N times" message.
+   */
+  reason?: string | ((input: Record<string, unknown>, count: number) => string);
+};
 interface AgentBehavior {
   /**
    * Maximum number of tools that may be in flight concurrently within a
@@ -476,6 +603,28 @@ interface AgentBehavior {
    * Default: unbounded. Set `0` to disable explicitly.
    */
   maxTotalTokens?: number;
+  /**
+   * Bounded retry-with-backoff policy applied around `provider.stream()`.
+   *
+   * Triggers only on errors the provider classifies as `retryable: true`
+   * (typically 429 / 5xx HTTP responses and mid-stream SSE errors like
+   * Anthropic's `overloaded_error`). Terminal failures (auth, invalid
+   * request, context exceeded, aborts) skip retry and propagate.
+   *
+   * Skipped when any output has already streamed to the user this turn —
+   * replaying over partial text would produce a confusing transcript.
+   * Mid-stream continuation (replaying with the partial assistant response
+   * appended for the model to continue from) is a separate, larger change.
+   *
+   * The Anthropic SDK already retries pre-stream errors up to twice
+   * internally; this loop-level retry catches mid-stream failures and
+   * other providers that don't ship an SDK-side retry.
+   *
+   * Default: 3 attempts, 1s → 2s → 4s exponential with full jitter,
+   * capped at 30s per delay, with `retry-after` / `retry-after-ms`
+   * headers honored when present. Set `maxAttempts: 1` to disable.
+   */
+  retry?: RetryConfig;
   /** Max tokens per LLM response (default: 16384) */
   maxTokens?: number;
   /** Thinking token budget — overrides the level-based default when set */
@@ -671,7 +820,7 @@ interface AgentBehavior {
    *
    * Default: `undefined` (no per-tool dedup).
    */
-  dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>;
+  dedupTools?: Record<string, DedupToolConfig>;
   /**
    * Require `read_file` before `edit` / `multi_edit` on the same path, and
    * reject edits when the file has changed on disk since the last read in
@@ -698,10 +847,18 @@ interface AgentBehavior {
    *   short stub, keeping the newest `compactKeepTurns` turns intact. The
    *   compaction is applied to the wire-level message list only; the
    *   underlying session turns are not modified.
+   * - **Function** ({@link CompactFunction}) — a pluggable replacement
+   *   that the loop calls instead of the built-in tail elision. The
+   *   function receives the post-`context:transform` wire messages and
+   *   returns the compacted view (sync or async). Use this to plug in
+   *   an LLM summarizer ("`<analysis>` / `<summary>`" style), a custom
+   *   semantic-aware compactor, or anything else hosts need beyond the
+   *   built-ins. The framework never modifies session turns — the same
+   *   wire-only contract as `'tail'` applies.
    *
    * Default: `'off'`.
    */
-  compactStrategy?: 'off' | 'tail';
+  compactStrategy?: 'off' | 'tail' | CompactFunction;
   /**
    * Soft byte threshold that triggers tail compaction when
    * `compactStrategy === 'tail'`. Counts the post-`context:transform` bytes
@@ -766,12 +923,17 @@ interface AgentBehavior {
    * - Auto-injects a `tool_search` native tool (opt out via
    *   {@link AgentBehavior.toolSearch}) the model uses to load schemas on
    *   demand. Surfaced tools persist for the rest of the run.
-   * - Rebuilds the wire-level tool list each turn, appending newly-unlocked
-   *   tools at the end so the prefix-cache breakpoint advances cleanly.
-   *
-   * Trade-off: every `tool_search` invocation expands the tool list and
-   * invalidates the tool-list cache breakpoint for one turn. With many
-   * MCP servers, the savings on cold turns (fewer schemas in context) are
+   * - Rebuilds the wire-level tool list each turn in two phases: every
+   *   initially-eager tool in registry order (the cache-stable prefix),
+   *   then every dynamically-unlocked tool in **unlock order** at the
+   *   tail. Newly-unlocked tools never get inserted into the prefix, so
+   *   the provider tool-list cache (Anthropic ephemeral) only invalidates
+   *   the suffix from the first new schema onwards — not the full array.
+   *
+   * Trade-off: every `tool_search` invocation extends the tool list and
+   * invalidates the tool-list cache breakpoint for the appended tail on
+   * one turn. The eager-prefix portion stays cache-hit. With many MCP
+   * servers, the savings on cold turns (fewer schemas in context) are
    * substantial; with one tiny MCP server, the overhead may not pay back.
    *
    * Default: `'eager'`.
@@ -804,6 +966,57 @@ interface AgentBehavior {
     tool?: false;
     limit?: number;
   };
+  /**
+   * Render the per-server `instructions` payload from the MCP `initialize`
+   * handshake as a `# MCP Server Instructions` section appended to the
+   * system prompt. Each server may return free-form guidance (e.g. "the
+   * database is already provisioned, use `apply_migration` directly")
+   * that materially changes how the model uses the server's tools.
+   *
+   * Matches the Claude Code SDK's default. Without this, models often
+   * try to bootstrap state the server already advertises as ready —
+   * e.g. running `npx supabase init` in a loop when the MCP server's
+   * instructions would have said "skip the init, use `apply_migration`".
+   *
+   * The section is built once per run and embedded into the system
+   * prompt next to the skills + searchable-tools catalogs, so it rides
+   * the same system-prompt cache breakpoint. Server insertion order
+   * matches `mcpServers` config order for byte-stable output.
+   *
+   * Only eager-connect servers contribute. `lazyConnect: true` servers
+   * are excluded by design — pulling their instructions would force the
+   * connection the host asked to defer. Empty / whitespace-only payloads
+   * are normalized to "no instructions" so a server that returns `""`
+   * doesn't produce a stub heading.
+   *
+   * Default: `true`. Set `false` for paranoid embedders that want full
+   * control of the system prompt or need to avoid leaking server
+   * advisories into untrusted contexts.
+   */
+  surfaceMcpInstructions?: boolean;
+  /**
+   * Hard cap on consecutive Anthropic `pause_turn` recoveries within a
+   * single run. Anthropic 4.6+ may return `stop_reason: 'pause_turn'`
+   * mid-turn for server-side reasons; the loop injects a "Please continue."
+   * user message and re-enters. With some 4.6 streaming edge cases the
+   * model returns empty pauses indefinitely, which without this cap spins
+   * forever burning tokens (the host's only escape was an external abort).
+   *
+   * When the consecutive-empty-pause counter reaches this value, the loop
+   * exits cleanly. The last turn's `TurnUsage.finishReason` stays
+   * `'pause'` so consumers can detect pause exhaustion from `stats`. The
+   * `agent:abort` hook does NOT fire — this is graceful termination, not
+   * user cancel.
+   *
+   * Only turns with no tool calls, no text, AND no thinking count toward
+   * the cap (the case Claude Code's v2 SDK collapses to `stop` outright).
+   * A pause turn with text resets the counter — productive turns are
+   * never penalised.
+   *
+   * Set `0` to disable (loop will continue indefinitely on pauses; useful
+   * only for tests). Default: `5`.
+   */
+  maxConsecutivePauseTurns?: number;
   /**
    * Persist large `tool_result` outputs to disk and replace the in-message
    * content with a `<persisted-output>` stub (preview + filesystem path).
@@ -1525,6 +1738,31 @@ interface AnthropicParams {
    */
   extraBodyParams?: Record<string, unknown>;
 }
+/**
+ * Mutate an Anthropic request in place to add cache breakpoints on the three
+ * stable prefixes:
+ *  1. System prompt — `cache_control` on the static prefix only (see below).
+ *  2. Tool definitions — last tool.
+ *  3. Conversation — last content block of the last message.
+ *
+ * Each breakpoint tells Anthropic to cache the prefix ending at that block;
+ * subsequent turns reuse the cached prefix and pay only for the delta. Safe
+ * no-op when any prefix is empty (no tools, empty system, etc.).
+ *
+ * System-prompt boundary handling (`SYSTEM_PROMPT_BOUNDARY`):
+ *
+ * - When `originalSystem` is provided AND carries the marker, the system
+ *   block is rewritten as a 2-block array: static (cached) then dynamic
+ *   (uncached). The caller is expected to have already stripped the marker
+ *   from `params.system` via {@link renderSystemForWire} — this helper
+ *   only re-splits to apply `cache_control` cleanly.
+ * - When `originalSystem` is omitted or marker-free, the existing single-
+ *   block treatment applies: `cache_control` on the whole system string.
+ * - Array system prompts: existing semantics — `cache_control` lands on the
+ *   last block. Callers building their own multi-block layout own the
+ *   breakpoint placement.
+ */
+declare function applyAnthropicCacheBreakpoints(params: Anthropic.MessageCreateParamsStreaming, originalSystem?: string): void;
 declare function anthropic(anthropicParams?: AnthropicParams): Provider;
 //#endregion
 //#region src/providers/cerebras.d.ts
@@ -1952,42 +2190,6 @@ interface Provider {
   classifyError?: (err: unknown) => ClassifiedError | null;
 }
 //#endregion
-//#region src/session/file-map.d.ts
-/**
- * Host-provided file-map adapter. Three methods exchanging `Record<string, string>`
- * payloads — the whole persistence surface the wrapper needs.
- */
-interface FileMapAdapter {
-  /** Load the current file map. Returns an empty `files` record when nothing is persisted. */
-  get: () => Promise<{
-    files: Record<string, string>;
-  }>;
-  /** Replace the persisted file map. Full-rewrite semantics. */
-  save: (files: Record<string, string>) => Promise<void>;
-  /** Delete all persisted state. */
-  delete: () => Promise<void>;
-}
-interface FileMapStoreOptions {
-  /** Filename for the JSONL turns log. Default: `turns.jsonl`. */
-  turnsFile?: string;
-  /** Filename for the metadata JSON. Default: `meta.json`. */
-  metaFile?: string;
-}
-/**
- * Create a single-session `SessionStore` backed by a file-map adapter.
- *
- * @example
- * ```ts
- * const session = await createSession({
- *   store: createFileMapStore(hostSessionStore),
- * })
- * ```
- */
-declare function createFileMapStore(adapter: FileMapAdapter, options?: FileMapStoreOptions): SessionStore;
-//#endregion
-//#region src/session/memory.d.ts
-declare function createMemoryStore(): SessionStore;
-//#endregion
 //#region src/session/messages.d.ts
 declare function fromAnthropic(msg: {
   role: string;
@@ -2150,11 +2352,139 @@ declare function detectTurnInterruption<T extends {
   role: string;
   content: SessionContentBlock[];
 }>(turns: T[]): TurnInterruptionState;
+/**
+ * Guarantee a message list ends with a `role: 'user'` message, appending a
+ * synthetic directive when it doesn't.
+ *
+ * Why: Anthropic's API (and several OpenAI-compat reasoning models — opus
+ * 4.7, the o-series translation layers on Bedrock/Vertex) rejects requests
+ * whose final message is `role: 'assistant'` with
+ * "This model does not support assistant message prefill. The conversation
+ * must end with a user message."
+ *
+ * Triggers in zidane:
+ *   - Compaction over a session whose last turn is the agent's response
+ *     (the common case — autocompact fires right after `agent.run()`).
+ *   - Schema enforcement after an assistant text turn (no `tool_use`, so
+ *     `ensureToolResultPairing` doesn't synthesize a user tail).
+ *   - `context:transform` hooks that strip the trailing user turn.
+ *
+ * The pair-repair pass {@link ensureToolResultPairing} already covers the
+ * orphan-`tool_use` case via mode 2; this helper closes the plain-text
+ * assistant-tail case. They compose: run pair-repair first, then this
+ * pass, so an assistant turn with orphan tool_uses gets its synthetic
+ * `tool_result` user turn AND this pass is a no-op (the synthetic turn
+ * is already user-role).
+ *
+ * Empty input passes through unchanged — the caller's "nothing to send"
+ * guard is responsible for that case; we don't materialize a conversation
+ * out of an empty list.
+ *
+ * Idempotent: returns the input reference unchanged when the list is
+ * already user-terminated (or empty).
+ *
+ * @param messages   Wire-ready message list.
+ * @param provider   Provider whose `userMessage()` shape we use so the
+ *                   synthetic turn matches the wire format the rest of
+ *                   the list already follows.
+ * @param directive  Text to put in the synthetic user message. Defaults
+ *                   to {@link DEFAULT_USER_TAIL_DIRECTIVE} ("Continue.").
+ *                   Compaction overrides this with a summary-specific cue.
+ */
+declare function ensureEndsWithUserMessage(messages: SessionMessage[], provider: Provider, directive?: string): SessionMessage[];
+interface ToWireMessagesOptions {
+  /**
+   * Pairing-repair telemetry. Fires once per repair the underlying
+   * {@link ensureToolResultPairing} pass performs. Mirrors the
+   * `pairing:repair` hook surface so consumers can wire structured logging
+   * without an agent instance.
+   */
+  onRepair?: (repair: PairingRepair) => void;
+  /**
+   * When set, also runs {@link ensureEndsWithUserMessage} so the result is
+   * safe for assistant-prefill-rejecting models (opus 4.7, o-series
+   * translation layers). Omit to skip — pure pairing repair only.
+   */
+  provider?: Provider;
+  /**
+   * Override for the synthetic user-tail directive. Only consulted when
+   * `provider` is set. Defaults to {@link DEFAULT_USER_TAIL_DIRECTIVE}.
+   */
+  userTailDirective?: string;
+}
+/**
+ * Build a wire-ready `SessionMessage[]` from raw persisted `SessionTurn[]`.
+ *
+ * **The canonical "I want to send these to a provider" projection.** Use
+ * this — not raw `session.turns` / `store.getTurns()` — when constructing a
+ * provider request outside `agent.run()`. The agent's own wire pipeline
+ * (`executeTurn` in `src/loop.ts`) applies the same repair just-in-time;
+ * downstream consumers that bypass the loop hit `tool_result must be
+ * preceded by a tool_call` 400s precisely because they shipped raw turns.
+ *
+ * Pipeline:
+ *   1. Filter `system`-role turns (the wire only carries user/assistant).
+ *   2. {@link ensureToolResultPairing} — repairs all six orphan / dup
+ *      corruption modes by inserting synthetic placeholders rather than
+ *      dropping (preserves the model's tool_use shape).
+ *   3. {@link ensureEndsWithUserMessage} when `options.provider` is set —
+ *      guards against assistant-tail prefill rejection (opus 4.7, o-series).
+ *
+ * Pure + idempotent. Does not mutate the input turns. Re-running on the
+ * output is a no-op.
+ *
+ * **Do not feed the result back into `session.setTurns` / `appendTurns`.**
+ * The repair can insert `SYNTHETIC_TOOL_RESULT_PLACEHOLDER` / `[Orphaned
+ * tool result removed …]` markers; round-tripping those into persisted
+ * state contaminates the session's reasoning history and defeats the
+ * "don't rewrite the past" invariant the wire-only repair was designed
+ * around.
+ */
+declare function toWireMessages(turns: readonly {
+  role: 'user' | 'assistant' | 'system';
+  content: SessionContentBlock[];
+}[], options?: ToWireMessagesOptions): SessionMessage[];
 declare function autoDetectAndConvert(msg: {
   role: string;
   content: unknown;
 }): SessionMessage;
 //#endregion
+//#region src/session/file-map.d.ts
+/**
+ * Host-provided file-map adapter. Three methods exchanging `Record<string, string>`
+ * payloads — the whole persistence surface the wrapper needs.
+ */
+interface FileMapAdapter {
+  /** Load the current file map. Returns an empty `files` record when nothing is persisted. */
+  get: () => Promise<{
+    files: Record<string, string>;
+  }>;
+  /** Replace the persisted file map. Full-rewrite semantics. */
+  save: (files: Record<string, string>) => Promise<void>;
+  /** Delete all persisted state. */
+  delete: () => Promise<void>;
+}
+interface FileMapStoreOptions {
+  /** Filename for the JSONL turns log. Default: `turns.jsonl`. */
+  turnsFile?: string;
+  /** Filename for the metadata JSON. Default: `meta.json`. */
+  metaFile?: string;
+}
+/**
+ * Create a single-session `SessionStore` backed by a file-map adapter.
+ *
+ * @example
+ * ```ts
+ * const session = await createSession({
+ *   store: createFileMapStore(hostSessionStore),
+ * })
+ * ```
+ */
+declare function createFileMapStore(adapter: FileMapAdapter, options?: FileMapStoreOptions): SessionStore;
+//#endregion
+//#region src/session/memory.d.ts
+declare function createMemoryStore(): SessionStore;
+//#endregion
 //#region src/session/remote.d.ts
 interface RemoteStoreOptions {
   /** Base URL of the session API */
@@ -2279,7 +2609,22 @@ interface Session {
    * Set once on creation; surfaces here for read-only inspection.
    */
   readonly projectRoot?: string;
-  /** Current turn history */
+  /**
+   * Raw persisted turn history — kept pristine for fidelity (the model's
+   * reasoning chain stays intact across reloads).
+   *
+   * **DO NOT pass this directly to a provider request.** Mid-pair
+   * persistence (interrupted runs, partial-result writes, compaction
+   * boundaries) leaves orphan `tool_use` / `tool_result` blocks here that
+   * every provider 400s on (`tool_result must be preceded by a tool_call
+   * with the same toolCallId`). The agent's own loop repairs these
+   * just-in-time at wire-send time and never writes the repair back to
+   * `turns`.
+   *
+   * For provider requests built outside `agent.run()`, use
+   * {@link Session.toMessages} — it applies the same defensive pairing
+   * repair and returns a guaranteed-safe `SessionMessage[]`.
+   */
   readonly turns: SessionTurn[];
   /**
    * True when this session has no turns yet.
@@ -2360,6 +2705,27 @@ interface Session {
   setMeta: (key: string, value: unknown) => void;
   /** Persist the full session document to the store */
   save: () => Promise<void>;
+  /**
+   * Project the session's persisted turns into a wire-ready
+   * `SessionMessage[]` safe to hand to any provider.
+   *
+   * The canonical answer to "I need to send these turns to Anthropic /
+   * OpenAI from outside `agent.run()`" (sub-agent classifier, side-channel
+   * summarizer, replay worker, …). Runs the same defensive pairing repair
+   * the agent loop applies just-in-time at wire-send time
+   * ({@link ensureToolResultPairing}), so orphan `tool_use` blocks and
+   * dangling `tool_result`s never reach the provider as the 400
+   * "tool_result must be preceded by a tool_call with the same toolCallId".
+   *
+   * Pass `provider` to also enforce the user-tail invariant
+   * ({@link ensureEndsWithUserMessage}) — required for opus 4.7 / o-series
+   * style models that reject assistant-prefill.
+   *
+   * Pure + idempotent. Does NOT mutate `session.turns`. **Do not write the
+   * result back via `setTurns` / `appendTurns`** — synthetic placeholders
+   * inserted by the repair will contaminate persisted history.
+   */
+  toMessages: (options?: ToWireMessagesOptions) => SessionMessage[];
   /** Serialize to SessionData */
   toJSON: () => SessionData;
 }
@@ -2721,6 +3087,29 @@ type ToolMap = Map<string, ToolDef>;
 //#region src/mcp/index.d.ts
 interface McpConnection {
   tools: Record<string, ToolDef>;
+  /**
+   * Per-server `instructions` payload from the MCP `initialize` handshake,
+   * keyed by server name. Each server may return free-form guidance the
+   * model is meant to read alongside the tool catalog — typical content
+   * is "the database is already provisioned, use `apply_migration`
+   * directly" or "always wrap SELECTs in a transaction". The agent
+   * renders these into a system-prompt section when
+   * `behavior.surfaceMcpInstructions` is on (default).
+   *
+   * Servers that omit the field, return an empty string, or fail to
+   * connect contribute no entry. Lazy-connected servers contribute an
+   * entry only once their first connect resolves — until then the model
+   * never sees their instructions, matching the schema-loading semantics
+   * of `lazyConnect`.
+   *
+   * Map (not Record) so insertion order matches server config order and
+   * the rendered section is byte-stable for the cache breakpoint.
+   *
+   * Optional so custom `mcpConnector` implementations from before this
+   * field existed still type-check; the framework's own
+   * `connectMcpServers` always returns a Map (possibly empty).
+   */
+  instructions?: Map<string, string>;
   close: () => Promise<void>;
 }
 /**
@@ -2895,6 +3284,18 @@ interface AgentHooks {
     startedAt: number;
     tracingContext?: Readonly<Record<string, string>>;
   }) => void;
+  /**
+   * Fires immediately before each turn's `provider.stream()` call, after
+   * `context:transform` + pairing repair + `system:transform`. The
+   * `options` object IS mutable as a last-mile escape hatch (per-turn
+   * reminders, dynamic tags, audit wrapping), but prefer
+   * {@link AgentHooks['context:transform']} for any mutation that touches
+   * `messages` — it runs upstream of the defensive pairing pass and stays
+   * cheaper. Loop re-runs `ensureToolResultPairing` + `ensureEndsWithUserMessage`
+   * after this hook so a `messages` mutation here can't leak a
+   * `tool_result must be preceded by a tool_call` 400 to the wire, but you
+   * pay one extra walk for the privilege.
+   */
   'turn:before': (ctx: {
     turn: number;
     turnId: string;
@@ -3020,14 +3421,61 @@ interface AgentHooks {
     statusCode?: number;
     requestId?: string;
   }) => void;
+  /**
+   * Fires when the loop catches a `retryable` provider error and is about
+   * to sleep before re-issuing `provider.stream()`. Does NOT fire on the
+   * terminal failure (the attempt the loop gives up on) — that lands on
+   * `stream:error` instead, same as today.
+   *
+   * Use this hook to surface "Anthropic overloaded — retrying in Ns" in
+   * the TUI, count retries in observability, or short-circuit further
+   * retry logic from an outer harness.
+   *
+   * - `attempt` — 1-indexed number of the attempt that just failed.
+   * - `nextAttempt` — `attempt + 1`, the attempt that will run after the sleep.
+   * - `delayMs` — the wait the loop is about to take. Already accounts for
+   *   any `retry-after` / `retry-after-ms` header the server returned and
+   *   the configured `maxDelayMs` cap.
+   * - `err` — the raw thrown value (same as `stream:error.err`).
+   * - `statusCode` / `requestId` — extracted via the same helper as
+   *   `stream:error` when available.
+   *
+   * Observational — handlers cannot cancel the retry. To disable retry,
+   * set `behavior.retry.maxAttempts: 1`.
+   */
+  'stream:retry': (ctx: StreamHookContext & {
+    attempt: number;
+    nextAttempt: number;
+    delayMs: number;
+    err: unknown;
+    statusCode?: number;
+    requestId?: string;
+  }) => void;
   'oauth:refresh': (ctx: OAuthRefreshHookContext) => void;
   /**
    * Fires before validation, `tool:before`, and `execute`. Two ways to
    * intercept:
    *
    * - Set `block = true` (with a `reason`) to refuse the call. The model
-   *   sees a `Blocked: <reason>` tool result; `tool:before` / `tool:after`
-   *   do **not** fire.
+   *   sees a `tool_result` block with `content` = `Blocked: <reason>` and
+   *   `is_error: true`. `tool:before` / `tool:after` do **not** fire;
+   *   `tool:dispatched` does (with `outcome: 'gate-block'`) so trace /
+   *   audit consumers see the refusal. The exact wire payload is:
+   *
+   *   ```jsonc
+   *   {
+   *     "type": "tool_result",
+   *     "tool_use_id": "<call id>",
+   *     "content": "Blocked: <reason>",   // verbatim, no wrapping XML
+   *     "is_error": true
+   *   }
+   *   ```
+   *
+   *   The `Blocked: ` prefix is fixed (single space, no colon variations);
+   *   the `<reason>` is whatever string the gate handler assigned to
+   *   `ctx.reason` (defaults to `'Tool execution was blocked'` if no
+   *   handler set it). Pinned by `test/dedup-tools.test.ts` so SDK
+   *   consumers can safely string-match for telemetry / eval scoring.
    * - Set `result` to substitute a successful tool_result and skip
    *   execution. The model sees the substitute as a normal tool_result;
    *   `tool:before` does not fire, but `tool:after` and `tool:transform`
@@ -3068,6 +3516,26 @@ interface AgentHooks {
      * for `write_file` on a fresh-create.
      */
     priorContent?: string;
+    /**
+     * `true` when the call's name has no matching registered tool — the
+     * model invented it (hallucination) or referenced a tool whose
+     * registration is gone (an MCP server dropped, an alias removed).
+     *
+     * Fires immediately BEFORE the `tool:unknown` substitute path so UI
+     * consumers using `tool:before` to render a tool card still see
+     * the model's attempt — otherwise the call was silently swallowed
+     * and the model's intent never surfaced in the transcript.
+     *
+     * Pairing contract for `unknown: true` events:
+     *   - `tool:after` does NOT fire (the body never executed).
+     *   - `tool:error` fires next (unless the `tool:unknown` handler
+     *     sets `suppressError`).
+     *   - `tool:dispatched` fires with `outcome: 'unknown'`.
+     *
+     * Mutations to `ctx.input` / `ctx.coercions` on this path are
+     * observational only — there's no body to dispatch them into.
+     */
+    unknown?: boolean;
   }) => void;
   /**
    * Symmetric notification fired ONCE per call the model dispatched,
@@ -3076,12 +3544,14 @@ interface AgentHooks {
    * get a guaranteed `tool` ↔ `tool-result` event pairing for downstream
    * consumers reconstructing message history from live events.
    *
-   * Distinct from `tool:before`: `tool:before` only fires when the tool
-   * body is about to execute (the legacy "I'm running this tool" notification),
-   * skipping gate-block / gate-substitute / unknown-tool / validation-reject
-   * paths. `tool:dispatched` fires on all five paths with an `outcome`
-   * discriminator so live consumers never see a `tool:after` whose
-   * matching dispatch event was suppressed.
+   * Distinct from `tool:before`: `tool:before` fires when a tool's body
+   * is about to execute (the legacy "I'm running this tool" notification)
+   * OR — as a special case — once with `unknown: true` for hallucinated
+   * tool names, so UI consumers rendering tool cards still see the
+   * model's attempt. It still skips gate-block / gate-substitute /
+   * validation-reject paths. `tool:dispatched` fires on all five paths
+   * with an `outcome` discriminator so live consumers never see a
+   * `tool:after` whose matching dispatch event was suppressed.
    *
    * Strict ordering: `tool:dispatched` fires AFTER `tool:gate` /
    * `validation:reject` / `tool:unknown` so the resolved `outcome` is
@@ -3970,6 +4440,21 @@ interface Agent {
    * model / capability defaults, construct a new provider.
    */
   readonly meta: Readonly<Record<string, unknown>>;
+  /**
+   * TC39 explicit-resource-management `await using` sink — alias for
+   * {@link Agent.destroy}. Lets hosts write:
+   *
+   * ```ts
+   * await using agent = createAgent({ ... })
+   * await agent.run({ prompt: 'go' })
+   * // agent.destroy() runs automatically at scope exit
+   * ```
+   *
+   * Requires Node 20+ (or any runtime that ships the TC39
+   * explicit-resource-management proposal). Older runtimes simply ignore
+   * the symbol; nothing breaks. Idempotent because `destroy()` is.
+   */
+  [Symbol.asyncDispose]: () => Promise<void>;
 }
 declare function createAgent({
   provider,
@@ -3989,5 +4474,5 @@ declare function createAgent({
   clock: agentClock
 }: AgentOptions): Agent;
 //#endregion
-export { fromOpenAI as $, SpawnHookContext as $t, SkillSource as A, cerebras as At, createRemoteStore as B, McpToolHookContext as Bt, getReadState as C, OpenAICompatParams as Ct, SkillConfig as D, OpenAIParams as Dt, resolveReadStateMap as E, openaiCompat as Et, SessionRun as F, AgentRunOptions as Ft, SYNTHETIC_TOOL_RESULT_PLACEHOLDER as G, PromptPart as Gt, ORPHANED_TOOL_RESULT_MARKER as H, OAuthRefreshHookContext as Ht, SessionStore as I, AgentStats as It, autoDetectAndConvert as J, SessionContentBlock as Jt, TOOL_USE_INTERRUPTED_MARKER as K, PromptTextPart as Kt, createSession as L, ChildRunStats as Lt, CreateSessionOptions as M, anthropic as Mt, Session as N, AgentBehavior as Nt, SkillDiagnostic as O, openai as Ot, SessionData as P, AgentClock as Pt, fromAnthropic as Q, SessionTurn as Qt, loadSession as R, DEFAULT_AGENT_CLOCK as Rt, ReadStateMap as S, OpenAICompatHttpError as St, readStateKey as T, mapOAIFinishReason as Tt, PairingRepair as U, PromptDocumentPart as Ut, EnsureToolResultPairingOptions as V, McpToolSchema as Vt, PairingRepairMode as W, PromptImagePart as Wt, ensureToolResultPairing as X, SessionHookContext as Xt, detectTurnInterruption as Y, SessionEndStatus as Yt, filterUnresolvedToolUses as Z, SessionMessage as Zt, resultToString as _, ClassifiedError as _n, sanitizeToolSchema as _t, createAgent as a, ToolResultTextContent as an, createFileMapStore as at, ToolMap as b, matchesContextExceeded as bn, openrouter as bt, DeactivationReason as c, toolOutputByteLength as cn, StreamCallbacks as ct, createSkillActivationState as d, AgentBudgetExceededError as dn, ToolResult as dt, StreamHookContext as en, toAnthropic as et, ConnectMcpServersOptions as f, AgentContextExceededError as fn, ToolSpec as ft, normalizeMcpServers as g, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as gn, SchemaSanitizeResult as gt, normalizeMcpBlocks as h, AgentToolPairingError as hn, SchemaSanitizeProfile as ht, AgentOptions as i, ToolResultImageContent as in, FileMapStoreOptions as it, SkillsConfig as j, AnthropicParams as jt, SkillResource as k, CerebrasParams as kt, SkillActivationState as l, toolResultToText as ln, StreamOptions as lt, connectMcpServers as m, AgentToolNotAllowedError as mn, SchemaSanitizeOptions as mt, AgentHookMap as n, ToolHookContext as nn, createMemoryStore as nt, ActivationVia as o, TurnFinishReason as on, Provider as ot, McpConnection as p, AgentProviderError as pn, TurnResult as pt, TurnInterruptionState as q, RunHookMap as qt, AgentHooks as r, ToolResultContent as rn, FileMapAdapter as rt, ActiveSkill as s, TurnUsage as sn, ProviderCapabilities as st, Agent as t, ThinkingLevel as tn, toOpenAI as tt, SkillActivationStateOptions as u, AgentAbortedError as un, ToolCall as ut, ToolContext as v, ClassifiedErrorKind as vn, sanitizeToolSpecs as vt, hashContent as w, classifyOpenAICompatError as wt, ReadStateEntry as x, toTypedError as xn, OpenAICompatAuthHeader as xt, ToolDef as y, errorMessage as yn, OpenRouterParams as yt, RemoteStoreOptions as z, McpServerConfig as zt };
-//# sourceMappingURL=agent-C9AKTU_V.d.ts.map
+export { autoDetectAndConvert as $, PromptTextPart as $t, SkillSource as A, OpenAIParams as At, createRemoteStore as B, AgentStats as Bt, getReadState as C, AgentToolPairingError as Cn, openrouter as Ct, SkillConfig as D, errorMessage as Dn, classifyOpenAICompatError as Dt, resolveReadStateMap as E, ClassifiedErrorKind as En, OpenAICompatParams as Et, SessionRun as F, anthropic as Ft, EnsureToolResultPairingOptions as G, DedupToolConfig as Gt, FileMapAdapter as H, CompactFunction as Ht, SessionStore as I, applyAnthropicCacheBreakpoints as It, PairingRepairMode as J, McpToolSchema as Jt, ORPHANED_TOOL_RESULT_MARKER as K, McpServerConfig as Kt, createSession as L, AgentBehavior as Lt, CreateSessionOptions as M, CerebrasParams as Mt, Session as N, cerebras as Nt, SkillDiagnostic as O, matchesContextExceeded as On, mapOAIFinishReason as Ot, SessionData as P, AnthropicParams as Pt, TurnInterruptionState as Q, PromptPart as Qt, loadSession as R, AgentClock as Rt, ReadStateMap as S, AgentToolNotAllowedError as Sn, OpenRouterParams as St, readStateKey as T, ClassifiedError as Tn, OpenAICompatHttpError as Tt, FileMapStoreOptions as U, DEFAULT_AGENT_CLOCK as Ut, createMemoryStore as V, ChildRunStats as Vt, createFileMapStore as W, DedupHasher as Wt, TOOL_USE_INTERRUPTED_MARKER as X, PromptDocumentPart as Xt, SYNTHETIC_TOOL_RESULT_PLACEHOLDER as Y, OAuthRefreshHookContext as Yt, ToWireMessagesOptions as Z, PromptImagePart as Zt, resultToString as _, toolResultToText as _n, SchemaSanitizeOptions as _t, createAgent as a, SessionMessage as an, fromOpenAI as at, ToolMap as b, AgentContextExceededError as bn, sanitizeToolSchema as bt, DeactivationReason as c, StreamHookContext as cn, toWireMessages as ct, createSkillActivationState as d, ToolResultContent as dn, StreamCallbacks as dt, RetryConfig as en, detectTurnInterruption as et, ConnectMcpServersOptions as f, ToolResultImageContent as fn, StreamOptions as ft, normalizeMcpServers as g, toolOutputByteLength as gn, TurnResult as gt, normalizeMcpBlocks as h, TurnUsage as hn, ToolSpec as ht, AgentOptions as i, SessionHookContext as in, fromAnthropic as it, SkillsConfig as j, openai as jt, SkillResource as k, toTypedError as kn, openaiCompat as kt, SkillActivationState as l, ThinkingLevel as ln, Provider as lt, connectMcpServers as m, TurnFinishReason as mn, ToolResult as mt, AgentHookMap as n, SessionContentBlock as nn, ensureToolResultPairing as nt, ActivationVia as o, SessionTurn as on, toAnthropic as ot, McpConnection as p, ToolResultTextContent as pn, ToolCall as pt, PairingRepair as q, McpToolHookContext as qt, AgentHooks as r, SessionEndStatus as rn, filterUnresolvedToolUses as rt, ActiveSkill as s, SpawnHookContext as sn, toOpenAI as st, Agent as t, RunHookMap as tn, ensureEndsWithUserMessage as tt, SkillActivationStateOptions as u, ToolHookContext as un, ProviderCapabilities as ut, ToolContext as v, AgentAbortedError as vn, SchemaSanitizeProfile as vt, hashContent as w, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as wn, OpenAICompatAuthHeader as wt, ReadStateEntry as x, AgentProviderError as xn, sanitizeToolSpecs as xt, ToolDef as y, AgentBudgetExceededError as yn, SchemaSanitizeResult as yt, RemoteStoreOptions as z, AgentRunOptions as zt };
+//# sourceMappingURL=agent-ClkpElCZ.d.ts.map