zidane 5.0.6 → 5.1.0

package/dist/index-CFxhms_B.d.ts

@@ -0,0 +1,1303 @@
+import { a as ExecutionHandle, i as ExecutionContext } from "./types-OtrV6LJT.js";
+import { D as Session, Ot as SessionTurn, Pt as ToolResultContent, Rt as TurnUsage, W as Provider, gt as McpServerConfig, ht as ChildRunStats, i as AgentOptions, jt as ThinkingLevel, l as SkillActivationState, mt as AgentStats, r as AgentHooks, s as ActiveSkill, v as ToolContext, x as SkillConfig, y as ToolDef } from "./agent-B0vrSTQ9.js";
+import { Hookable } from "hookable";
+import { OAuthClientProvider, OAuthDiscoveryState } from "@modelcontextprotocol/sdk/client/auth.js";
+import { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+
+//#region src/compact/messages.d.ts
+/**
+ * What to summarize and what to preserve verbatim.
+ *
+ * - `'full'`         — summarize everything, no preserved tail.
+ * - `'tail'`         — summarize everything before the last `keepTurns` turns.
+ * - `{ kind: 'from',  turnId }` — summarize from the anchor turn onward.
+ * - `{ kind: 'up_to', turnId }` — summarize up to (and including) the anchor.
+ */
+type CompactScope = 'full' | 'tail' | {
+  kind: 'from';
+  turnId: string;
+} | {
+  kind: 'up_to';
+  turnId: string;
+};
+interface CompactionSlice {
+  /** The portion of the conversation that will be summarized. */
+  toSummarize: readonly SessionTurn[];
+  /** The portion that stays verbatim in the post-compact history. */
+  preserved: readonly SessionTurn[];
+}
+/**
+ * Partition `turns` into `(toSummarize, preserved)` according to `scope`.
+ *
+ * Throws {@link CompactInvalidInputError} on degenerate inputs so the
+ * caller doesn't pay for a doomed provider call:
+ *   - empty `turns`
+ *   - `scope: 'tail'` with `keepTurns >= turns.length` (nothing to summarize)
+ *   - `scope: { from | up_to }` with an anchor id that isn't in `turns`
+ *   - the resulting `toSummarize` slice contains no text-bearing content
+ *     (only system turns or empty content)
+ *
+ * Pure. Returns references to the original `SessionTurn` objects — the
+ * caller can compare by identity (=== Object.is) to confirm.
+ */
+declare function sliceForCompaction(turns: readonly SessionTurn[], scope: CompactScope, keepTurns: number): CompactionSlice;
+/**
+ * Replace every image block in `turns` with a `[image]` text marker.
+ *
+ * Covers two shapes:
+ *   - Top-level `{ type: 'image', ... }` content blocks on user turns.
+ *   - Image entries inside `tool_result.output` array form (multimodal
+ *     tool results — e.g. an MCP browser screenshot).
+ *
+ * Unconditional by design: even on vision-capable models, the summary
+ * call doesn't benefit from raw image bytes (the model can't refer to
+ * them after the summary lands), and stripping uniformly avoids
+ * `prompt_too_long` on image-heavy sessions.
+ *
+ * Returns a fresh array; input turns / blocks are never mutated.
+ */
+declare function stripImagesFromTurns(turns: readonly SessionTurn[]): SessionTurn[];
+/**
+ * Drop the oldest "round" from `turns` and return a fresh array. Used by
+ * the PTL retry path to shrink the prompt one round at a time.
+ *
+ * A round is a contiguous `[user, assistant?, tool_results?]` group. The
+ * function walks forward from index 0, advances through the user turn
+ * and any trailing assistant + tool-result turns belonging to the same
+ * exchange, and returns the remainder.
+ *
+ * Adjacency-safe: when the oldest user turn carries `tool_result` blocks
+ * answering an assistant turn ahead of it (rare — happens during
+ * resume), the function keeps walking until the next clean boundary so
+ * the resulting array still respects every provider's `tool_use ↔
+ * tool_result` adjacency rule.
+ *
+ * Returns `turns` unchanged when only one round (or less) remains — the
+ * caller is expected to interpret that as "cannot shrink further" and
+ * give up the retry loop.
+ */
+declare function truncateHeadForPtlRetry(turns: readonly SessionTurn[]): SessionTurn[];
+/**
+ * Maximum length of an anchor turn's textual preview, in characters. Long
+ * enough to give the model recognizable context (the first paragraph of
+ * a typical user message), short enough that it doesn't blow the
+ * cache-stability invariant for the prompt prefix.
+ */
+declare const ANCHOR_PREVIEW_MAX_CHARS = 200;
+/**
+ * Extract the first ~200 chars of text-bearing content from a turn — the
+ * preview surfaced in `from` / `up_to` direction prompts so the model
+ * knows where the slice begins.
+ */
+declare function anchorPreviewFor(turn: SessionTurn): string;
+/**
+ * Input shape for {@link summaryToTurn}. Designed to align with the
+ * fields of `CompactResult` so a caller can spread the runner's output
+ * with a single `replacesTurnIds` rename — no field-by-field unpacking
+ * required.
+ *
+ * Primitive shape (no `CompactResult` import) keeps this module free of
+ * dependencies on the runner — `compact.ts` imports from here, not the
+ * other way around.
+ */
+interface SummaryToTurnInput {
+  /** Summary text — typically `CompactResult.summary`. */
+  summary: string;
+  /** Turn ids being replaced — typically `CompactResult.summarizedTurnIds`. */
+  replacesTurnIds: readonly string[];
+  /** Model id that produced the summary. */
+  model: string;
+  /** Token usage from the summary call. */
+  usage: TurnUsage;
+  /** Defaults to `Date.now()` when omitted. */
+  compactedAt?: number;
+}
+/**
+ * Build a synthetic `SessionTurn` carrying a single `compact-summary`
+ * block, ready to append to a session.
+ *
+ * The turn's role is `'user'` so it sits at a conversational boundary
+ * the way the model expects. The caller is responsible for
+ * `session.appendTurns([turn])`. The id is freshly generated via
+ * `crypto.randomUUID()` so collisions are statistically impossible.
+ *
+ * Typical use after running `compactConversation`:
+ *
+ * ```ts
+ * const result = await compactConversation({ provider, turns })
+ * const turn = summaryToTurn({
+ *   summary: result.summary,
+ *   replacesTurnIds: result.summarizedTurnIds,
+ *   model: result.model,
+ *   usage: result.usage,
+ * })
+ * await session.appendTurns([turn])
+ * ```
+ */
+declare function summaryToTurn(input: SummaryToTurnInput): SessionTurn;
+//#endregion
+//#region src/compact/prompt.d.ts
+/**
+ * Pure prompt builders for conversation compaction.
+ *
+ * The builders produce the **system prompt** for a no-tools summary call.
+ * They are total functions of `(direction, anchorPreview?)` and produce
+ * byte-stable output for the same inputs — that's load-bearing for the
+ * provider's prompt cache: repeated compactions in the same host process
+ * share the same prefix and read cache instead of writing it.
+ *
+ * Inspired by Claude Code's `services/compact/prompt.ts` — same 9-section
+ * scaffold, same `<analysis> + <summary>` envelope, same no-tools
+ * preamble. Adapted to zidane-specific wording (no "Claude" references)
+ * and trimmed of the bits that don't apply (no `marble_origami`-style
+ * query sources, no compaction-fingerprint header).
+ */
+/** Identifier for the section of the conversation being summarized. */
+type CompactDirection = 'full' | 'tail' | 'from' | 'up_to';
+interface CompactPromptOptions {
+  direction: CompactDirection;
+  /**
+   * Short preview of the anchor turn's text — only used by `'from'` and
+   * `'up_to'`. Pass the last ~200 chars of the anchor turn so the model
+   * has a recognizable handle on where the slice begins / ends. Empty /
+   * undefined for `'full'` and `'tail'`.
+   */
+  anchorPreview?: string;
+}
+/**
+ * Function shape for callers that want to swap in a domain-specific
+ * summary prompt (security review handoff, support-ticket continuation,
+ * etc.) without touching the runner. Default: {@link buildCompactPrompt}.
+ */
+type CompactPromptBuilder = (opts: CompactPromptOptions) => string;
+/**
+ * No-tools guard. The runner sends `tools: []` to the provider already,
+ * but some models still hallucinate tool-call intent on a long
+ * conversation. The prose guard is cheap insurance.
+ */
+declare const NO_TOOLS_PREAMBLE = "CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.\n\n- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.\n- You already have all the context you need in the conversation above.\n- Tool calls will be REJECTED and will waste your only turn \u2014 you will fail the task.\n- Your entire response must be plain text: an <analysis> block followed by a <summary> block.";
+/**
+ * Body shared by every direction. Lays out the 9-section scaffold,
+ * mirrors Claude Code's `BASE_COMPACT_PROMPT` so a model already trained
+ * on the layout produces the same shape.
+ */
+declare const BASE_INSTRUCTIONS = "Your task is to create a detailed summary of the conversation so far, paying close attention to the user's explicit requests and your previous actions.\n\nThis summary should be thorough in capturing technical details, code patterns, and architectural decisions that would be essential for continuing development work without losing context.\n\nBefore providing your final summary, wrap your analysis in <analysis> tags to organize your thoughts and ensure you've covered all necessary points. In your analysis process:\n\n1. Chronologically analyze each message and section of the conversation. For each section thoroughly identify:\n   - The user's explicit requests and intents\n   - Your approach to addressing the user's requests\n   - Key decisions, technical concepts and code patterns\n   - Specific details like file names, full code snippets, function signatures, file edits\n   - Errors that you ran into and how you fixed them\n   - Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.\n2. Double-check for technical accuracy and completeness.\n\nYour summary, wrapped in <summary> tags, must include the following sections:\n\n1. Primary Request and Intent\n2. Key Technical Concepts\n3. Files and Code Sections (with paths; include code snippets only when load-bearing)\n4. Errors and fixes\n5. Problem Solving\n6. All user messages (list ALL non-tool user messages, verbatim)\n7. Pending Tasks\n8. Current Work\n9. Optional Next Step (include direct quotes from the most recent conversation when relevant)";
+/** Trailer prompting the model to begin. Same on every direction. */
+declare const TRAILER = "Provide your <analysis> and <summary> now.";
+declare function buildFullCompactPrompt(): string;
+declare function buildTailCompactPrompt(): string;
+declare function buildFromCompactPrompt(anchorPreview: string): string;
+declare function buildUpToCompactPrompt(anchorPreview: string): string;
+/**
+ * Default public builder. Dispatches by direction to the four named
+ * builders. Throws when `from` / `up_to` are passed without an
+ * `anchorPreview` — those scopes only make sense with an anchor and a
+ * silent fallback would produce a prompt that doesn't tell the model
+ * where the slice begins.
+ */
+declare const buildCompactPrompt: CompactPromptBuilder;
+//#endregion
+//#region src/compact/errors.d.ts
+/**
+ * Typed errors thrown by the compaction helper.
+ *
+ * Lives in its own file so both the runner and the pure messages module
+ * can import without circular dependencies.
+ */
+/**
+ * Raised when the caller's inputs make compaction meaningless before any
+ * API call is attempted. Common cases:
+ *   - empty `turns`
+ *   - `keepTurns >= turns.length` (no older content to summarize)
+ *   - `'from'` / `'up_to'` anchor id not found in `turns`
+ *   - the resolved `toSummarize` slice has no text-bearing content
+ *
+ * Synchronous — thrown from `compactConversation()` before the provider
+ * call so the caller can recover without a network round-trip.
+ */
+declare class CompactInvalidInputError extends Error {
+  constructor(message: string);
+}
+/**
+ * Raised when the provider rejects the compaction request with
+ * `prompt_too_long` (or an equivalent) and the head-truncation retry
+ * budget has been exhausted. Callers can inspect `ptlRetries` to log
+ * how far the retry loop got before giving up.
+ */
+declare class CompactPromptTooLongError extends Error {
+  readonly ptlRetries: number;
+  constructor(message: string, ptlRetries: number);
+}
+//#endregion
+//#region src/compact/compact.d.ts
+interface CompactOptions {
+  /** Provider used for the summary call. Called with empty tools list. */
+  provider: Provider;
+  /** Conversation to compact, in chronological order. */
+  turns: readonly SessionTurn[];
+  /**
+   * What to summarize. Default: `'tail'` — summarize everything before
+   * the last `keepTurns` turns. See {@link CompactScope}.
+   */
+  scope?: CompactScope;
+  /**
+   * Trailing turns left untouched when `scope: 'tail'`. Default: 4.
+   * Matches `AgentBehavior.compactKeepTurns` so a host that uses both
+   * mechanisms shares one knob.
+   */
+  keepTurns?: number;
+  /** Model id used for the summary call. Default: `provider.meta.defaultModel`. */
+  model?: string;
+  /**
+   * Maximum tokens the summary itself can occupy. Default: 20_000 — the
+   * p99.99 of summary output size in Claude Code's `COMPACT_MAX_OUTPUT`.
+   * Reasonable for any model with a 200k+ window.
+   */
+  maxOutputTokens?: number;
+  /** Optional reasoning level. Default: `'off'` — summarization rarely benefits from thinking. */
+  thinking?: ThinkingLevel;
+  /** Optional cancellation signal forwarded to `provider.stream()`. */
+  signal?: AbortSignal;
+  /**
+   * Retries with head-truncation when the provider reports
+   * `prompt_too_long`. Each retry drops the oldest conversational round
+   * before re-issuing the call. Default: 3. Set 0 to fail-fast.
+   */
+  maxPtlRetries?: number;
+  /**
+   * Optional builder override. The default builder dispatches by
+   * direction to the named builders in `./prompt.ts`; pass a custom
+   * function to swap in a domain-specific summary prompt.
+   */
+  prompt?: CompactPromptBuilder;
+  /**
+   * Lifecycle hook for observability. Fires once per provider call,
+   * including retries. The `kind` field tells you whether the call is
+   * the initial attempt, a head-truncated retry, or a transient-error
+   * retry — useful for surfacing progress in a UI spinner.
+   */
+  onAttempt?: (event: {
+    attempt: number;
+    kind: 'initial' | 'ptl-retry' | 'transient-retry';
+  }) => void;
+}
+interface CompactResult {
+  /** The summary text, with any `<analysis>` block stripped. */
+  summary: string;
+  /** Token usage from the (last successful) summary call. */
+  usage: TurnUsage;
+  /** Model id used to produce the summary. */
+  model: string;
+  /** Number of `prompt_too_long` retries that fired before success. 0 on first-try success. */
+  ptlRetries: number;
+  /**
+   * Turn ids actually covered by the summary — i.e., the ids of turns
+   * that made it to the provider. **PTL-retry safe**: when head-truncation
+   * shrank the scope, only the surviving (post-truncation) turn ids
+   * appear here. Drives `summaryToTurn`'s `replacesTurnIds`; the wire-
+   * level cutoff in `applyCompactSummaryCutoff` reads the same field
+   * from the persisted marker.
+   */
+  summarizedTurnIds: readonly string[];
+  /**
+   * Turn ids dropped by PTL head-truncation before reaching the
+   * provider. **Empty on first-try success.** These turns are NOT
+   * covered by the summary — callers should either leave them in the
+   * conversation history (they stay visible to the model verbatim,
+   * since the id-based cutoff only elides ids the marker explicitly
+   * claims) or surface a "compaction lost N turns of context" warning.
+   *
+   * The harness keeps these in the wire-level conversation by default;
+   * the safety contract is "the summary describes exactly what's in
+   * `summarizedTurnIds` — nothing more, nothing less".
+   */
+  droppedDueToPtl: readonly string[];
+  /** Turns left untouched (the preserved tail / verbatim slice). */
+  preservedTurns: readonly SessionTurn[];
+  /** Byte length of turns actually summarized (post-PTL-truncation). */
+  beforeBytes: number;
+  /** UTF-8 byte length of the summary text (rough "after" measure). */
+  afterBytes: number;
+}
+declare function compactConversation(opts: CompactOptions): Promise<CompactResult>;
+//#endregion
+//#region src/compact/restore.d.ts
+/** One file selected for restoration, with its last-read timestamp for ranking. */
+interface RecentFile {
+  /** Path relative to the execution context's `handle.cwd`. */
+  path: string;
+  /** Wall-clock when the file was last read, in ms. Drives recency ranking. */
+  mtimeMs: number;
+}
+interface PostCompactRestoreOptions {
+  /**
+   * Files to consider for restoration, ranked by recency. Typically derived
+   * via {@link selectFilesFromReadState} from `getReadState(session)`.
+   * The helper takes the top {@link PostCompactRestoreOptions.maxFilesToRestore}
+   * by `mtimeMs` descending, fetches their current content, and synthesizes
+   * `read_file` tool_call/tool_result pairs.
+   */
+  recentFiles?: readonly RecentFile[];
+  /**
+   * Active skills to re-inject. Typically `agent.activeSkills`. Each entry
+   * yields a synthetic `skills_use` tool_call/tool_result pair carrying the
+   * skill's instructions (possibly truncated to the per-skill budget).
+   */
+  activeSkills?: readonly ActiveSkill[];
+  /**
+   * Execution context used to fetch file content. **Required for file
+   * restoration.** Skills come pre-loaded (instructions live on the
+   * `SkillConfig`), so they don't need the context.
+   */
+  execution?: ExecutionContext;
+  handle?: ExecutionHandle;
+  /**
+   * Canonical name of the file-read tool. Defaults to `read_file`. Aliases
+   * (e.g. `Read`) are NOT specified here — the agent loop's
+   * `rewriteMessagesToWire` handles wire conversion automatically.
+   *
+   * Override only when a host registered file-read under a different
+   * canonical name (not just an alias).
+   */
+  readFileToolName?: string;
+  /**
+   * Canonical name of the skill-activation tool. Defaults to `skills_use`.
+   * Same aliasing semantics as `readFileToolName`.
+   */
+  skillsUseToolName?: string;
+  /** Total token budget for file restoration. Default: 50_000. */
+  fileTokenBudget?: number;
+  /** Per-file token cap. Default: 5_000. */
+  fileTokenPerFileCap?: number;
+  /** Maximum file count. Default: 5. */
+  maxFilesToRestore?: number;
+  /** Total token budget for skill restoration. Default: 25_000. */
+  skillTokenBudget?: number;
+  /** Per-skill token cap. Default: 5_000. */
+  skillTokenPerSkillCap?: number;
+  /**
+   * Paths to skip — typically the file paths already covered by the
+   * compaction result's `preservedTurns`. Avoids double-injection when the
+   * recent reads sit in the preserved tail.
+   */
+  excludePaths?: readonly string[];
+  /**
+   * Optional `runId` to tag the synthetic turns with — useful for hosts
+   * that want the restoration turns to roll up under the same run as the
+   * compaction marker. Defaults to undefined (orphan turns).
+   */
+  runId?: string;
+}
+/**
+ * Envelope returned by {@link buildPostCompactAttachments}. The caller
+ * spreads `turns` into `session.appendTurns([summaryTurn, ...turns])`.
+ * Count fields drive UI banners ("restored 5 files + 2 skills").
+ */
+interface PostCompactAttachments {
+  /**
+   * Two synthetic turns when at least one item was restored, otherwise
+   * an empty array. The pair is `[assistant_with_tool_calls,
+   * user_with_tool_results]` — adjacent and well-formed for every
+   * provider's `tool_use ↔ tool_result` invariant.
+   */
+  turns: readonly SessionTurn[];
+  /** Count of files actually restored (post-budget). */
+  restoredFiles: number;
+  /** Count of skills actually restored (post-budget). */
+  restoredSkills: number;
+  /** Rough total token cost of the restoration payload (sum of all content). */
+  estimatedTokens: number;
+}
+/**
+ * Convert a raw read-state map into a deduped, path-ranked list ready for
+ * restoration. Multiple entries for the same path (different
+ * `(offset, limit, maxBytes)` slices) collapse to one — keeping the most
+ * recent `mtimeMs`.
+ *
+ * Filters out entries whose key doesn't share the given `cwd` prefix:
+ * those came from a different execution context and can't be read back
+ * through this agent's handle.
+ *
+ * Pure. Most callers want {@link selectFilesFromSession}, which wraps
+ * `getReadState(session)` + this function in one call so the host
+ * doesn't have to reach into the tools layer.
+ */
+declare function selectFilesFromReadState(readState: ReadonlyMap<string, {
+  mtimeMs: number;
+}>, cwd: string): RecentFile[];
+/**
+ * Session-aware convenience: extract recently-read files directly from
+ * a {@link Session} via its per-session read-state map.
+ *
+ * Hosts (TUI / SDK consumers) typically have a `Session` and a `cwd`
+ * (the active agent's `handle.cwd`) on hand — this wrapper saves them
+ * from reaching into `src/tools/read-state.ts` directly. Returns an
+ * empty list when no read state has been recorded yet (fresh session,
+ * or `behavior.dedupReads === false`).
+ *
+ * Equivalent to:
+ *
+ * ```ts
+ * const state = getReadState(session)
+ * return state ? selectFilesFromReadState(state, cwd) : []
+ * ```
+ */
+declare function selectFilesFromSession(session: Session, cwd: string): RecentFile[];
+/**
+ * Pick the top `maxFiles` from `files` (descending by `mtimeMs`),
+ * dropping any whose path appears in `excludePaths`.
+ *
+ * Stable for equal mtimes — files with the same timestamp retain their
+ * input order. Pure.
+ */
+declare function selectRecentFiles(files: readonly RecentFile[], opts: {
+  maxFiles: number;
+  excludePaths?: readonly string[];
+}): RecentFile[];
+/** UTF-8 byte length, matching `Buffer.byteLength(text, 'utf-8')`. */
+/**
+ * Build the synthetic turns to append after a `compact-summary` marker.
+ *
+ * Returns a `PostCompactAttachments` envelope; the caller is responsible
+ * for `session.appendTurns([summaryTurn, ...result.turns])`. The two
+ * synthetic turns are always emitted together (or both omitted when
+ * nothing was restored) so the `tool_use ↔ tool_result` adjacency
+ * invariant holds regardless of caller code path.
+ *
+ * Failure isolation: a single file's read failure never blocks the rest
+ * of restoration — that file is skipped silently and processing
+ * continues. The returned `restoredFiles` count reflects what actually
+ * landed in the synthesized turns.
+ */
+declare function buildPostCompactAttachments(opts: PostCompactRestoreOptions): Promise<PostCompactAttachments>;
+//#endregion
+//#region src/compact/utils.d.ts
+/**
+ * Shared utilities for the compact module — extracted so the runner
+ * (`compact.ts`) and the restoration helper (`restore.ts`) don't carry
+ * redundant copies of the same low-level math.
+ *
+ * Kept zero-dependency by design: no Node/Bun imports, no zidane types
+ * either. Both `utf8ByteLength` and `estimateTokens` are total
+ * functions of a single `string` argument, so they're trivially
+ * portable to a worker/browser context if the compact module ever
+ * needs to render outside Node.
+ */
+/**
+ * UTF-8 byte length, matching `Buffer.byteLength(text, 'utf-8')` but
+ * without pulling `node:buffer` for a one-liner. Stable for surrogate
+ * pairs — a high+low surrogate pair counts as a single 4-byte sequence
+ * (not 2 × 3-byte). Cheap to call in hot loops.
+ *
+ * Pure. Identical bytes for identical input across every JS runtime.
+ */
+declare function utf8ByteLength(text: string): number;
+/** Same constant Claude Code's `CONTEXT_MANAGEMENT.md` documents. */
+declare const BYTES_PER_TOKEN = 4;
+/**
+ * Approximate token count for `text`. Mirrors Claude Code's
+ * `BYTES_PER_TOKEN = 4` heuristic — acceptable for budget arithmetic
+ * (sizing summarization scopes, enforcing per-file caps in restoration).
+ *
+ * Accurate to ~10% on English + code. Use a real tokenizer when exact
+ * counts matter (cost reporting, hard caps); this is for budget gates
+ * where being off by 10% is fine.
+ *
+ * Pure. Exported so callers (TUI, SDK consumers) can do their own
+ * pre-budgeting against the same heuristic the harness uses internally.
+ */
+declare function estimateTokens(text: string): number;
+//#endregion
+//#region src/loop-persistence.d.ts
+/**
+ * Bytes of head content included in the inline preview block. 2 KiB matches
+ * Claude Code's `PREVIEW_SIZE_BYTES` — enough for the model to identify the
+ * content class (error output / structured data / log shape) and decide
+ * whether to call `read_file` on the persisted path for the full payload.
+ *
+ * Tail-priority preview (matching `shell`'s truncation strategy) was
+ * considered but rejected: most "what is this?" decisions get made from
+ * the head, and the path is in the stub for the rare case where the tail
+ * matters.
+ */
+declare const PERSISTENCE_PREVIEW_BYTES: number;
+/**
+ * Byte-stable prefix every {@link buildPersistedStub} output starts with.
+ * Exported so wire-level passes (tail compaction, future stale-output
+ * elision) can recognize a persisted stub and preserve its path attribute
+ * rather than replacing the stub with their own — losing the pointer to
+ * the on-disk blob.
+ *
+ * Bound to the literal opening of the XML tag; changing the stub format
+ * requires updating this constant in lockstep (and shipping a migration
+ * for in-flight sessions).
+ */
+declare const PERSISTED_STUB_PREFIX = "<persisted-output tool=\"";
+/**
+ * Resolve the per-session persistence directory under `<userDir>/tool-results/<sessionId>/`.
+ *
+ * The chat layer calls this at session activation and forwards the result
+ * via `behavior.persistDir`. Exposed as a public helper so SDK consumers
+ * pick the same layout — single source of truth for "where do blobs live".
+ */
+declare function resolvePersistDir(opts: {
+  userDir: string;
+  sessionId: string;
+}): string;
+/**
+ * Inputs to {@link maybePersistToolResult}. Kept as a struct so the loop's
+ * call site stays readable and additional optional knobs (compression,
+ * mime detection, …) land without re-threading every call site.
+ */
+interface PersistInput {
+  /** Canonical tool name — checked against `excludeTools`. */
+  toolName: string;
+  /** `tool_use` id from the assistant turn. Used as the filename. */
+  callId: string;
+  /** Result returned by the tool (post-`tool:transform`). */
+  output: string | ToolResultContent[];
+  /** Byte threshold; outputs at or below stay inline. */
+  threshold: number;
+  /** Canonical tool names that bypass persistence. */
+  excludeTools?: readonly string[];
+  /** Persistence root directory. Created on first write. */
+  persistDir: string;
+}
+type PersistOutcome = {
+  kind: 'skip';
+  reason: 'disabled' | 'excluded' | 'under-threshold' | 'unsupported-shape' | 'unsafe-call-id' | 'invalid-persist-dir';
+} | {
+  kind: 'persisted';
+  output: string;
+  originalBytes: number;
+  persistedPath: string;
+} | {
+  kind: 'error';
+  reason: 'write-failed';
+  error: Error;
+};
+/**
+ * Decide-and-persist for a single tool result. Pure decision + filesystem
+ * side-effect; returns the new wire-level `output` string when substitution
+ * happened, otherwise tells the caller to leave the result alone.
+ *
+ * Atomicity: writes go through `<path>.tmp` + `rename` so a concurrent
+ * read (or a crash mid-write) never sees a half-written blob.
+ *
+ * `ToolResultContent[]` results (images, structured blocks) currently bypass
+ * persistence — the inline image bytes are the point of the call, and a
+ * mixed text/image array isn't representable as a single `.txt` file. We
+ * may revisit if a tool starts returning very large text-only arrays.
+ */
+declare function maybePersistToolResult(input: PersistInput): Promise<PersistOutcome>;
+interface BuildStubInput {
+  toolName: string;
+  originalBytes: number;
+  persistedPath: string;
+  output: string;
+}
+/**
+ * Render the byte-stable `<persisted-output>` stub the model sees in place
+ * of the original `tool_result`.
+ *
+ * Format choices:
+ *  - XML wrapper because models reliably parse it as structural.
+ *  - Byte count + path in attributes so the model can decide whether to
+ *    `read_file` the persisted blob without scanning the preview.
+ *  - Preview always shows the head — `shell`'s tail-priority truncation is
+ *    irrelevant here because the model has the full path if it needs the
+ *    tail.
+ *  - No timestamps, no random UUIDs inside the stub: every byte must be
+ *    reproducible from the inputs, otherwise re-emission on subsequent
+ *    turns would bust the prompt cache.
+ *
+ * Exported for tests (asserting the byte-stable contract) and for SDK
+ * consumers wiring their own persistence middleware against the same
+ * surface.
+ */
+declare function buildPersistedStub(input: BuildStubInput): string;
+/**
+ * Remove every persisted blob belonging to a session. Called by the chat
+ * layer from its session-delete path so closing a session frees the disk
+ * footprint alongside the SQLite row.
+ *
+ * Idempotent — missing directory (session never persisted anything) is a
+ * no-op, not an error. Wraps the `rm -rf` so a permissions blip on one
+ * blob doesn't propagate to the caller; the chat layer can't usefully
+ * recover from "couldn't unlink a result file" mid-delete.
+ */
+declare function cleanupPersistedSession(persistRoot: string): Promise<void>;
+//#endregion
+//#region src/mcp/oauth-provider.d.ts
+/**
+ * Per-server persisted state. Subfields are optional so a partial save
+ * (e.g. `saveCodeVerifier` arriving before `saveTokens`) doesn't blow away
+ * earlier subfields — the provider always patches, never replaces.
+ */
+interface McpCredentialEntry {
+  tokens?: OAuthTokens;
+  clientInformation?: OAuthClientInformationMixed;
+  discoveryState?: OAuthDiscoveryState;
+}
+interface McpCredentialStore {
+  load: (name: string) => McpCredentialEntry | undefined;
+  save: (name: string, entry: McpCredentialEntry) => void;
+  delete: (name: string) => void;
+}
+/**
+ * In-memory store — primarily for tests, but valid as a no-persistence option
+ * (tokens evaporate on process exit, the user re-auths every cold start).
+ */
+declare function createMemoryMcpCredentialStore(seed?: Record<string, McpCredentialEntry>): McpCredentialStore;
+interface McpOAuthProviderOptions {
+  /** Server name — used as the storage key. */
+  name: string;
+  /** Persistence backend. */
+  store: McpCredentialStore;
+  /**
+   * Loopback callback URI. Pass `undefined` for bootstrap (non-interactive
+   * mode — stored tokens + refresh only, never opens a browser).
+   */
+  redirectUri?: string;
+  /**
+   * Invoked when the SDK wants the user agent to navigate to the authorization
+   * URL. Typically the host opens the browser AND emits a hook so the TUI can
+   * render the URL in a status row. No-op in non-interactive mode (the SDK
+   * still calls this before throwing `UnauthorizedError` from connect).
+   */
+  onAuthorizationUrl?: (url: URL) => void | Promise<void>;
+  /**
+   * `client_name` used in dynamic client registration. Defaults to `'zidane'`.
+   * Some servers display this string to the user on the consent screen.
+   */
+  clientName?: string;
+  /**
+   * Override the requested OAuth scope. Default: unset (the SDK negotiates
+   * via the server's metadata).
+   */
+  scope?: string;
+}
+declare class McpOAuthProvider implements OAuthClientProvider {
+  private readonly name;
+  private readonly store;
+  private readonly _redirectUri?;
+  private readonly onAuthorizationUrl?;
+  private readonly clientName;
+  private readonly _scope?;
+  private codeVerifierValue;
+  constructor(opts: McpOAuthProviderOptions);
+  get redirectUrl(): string | URL | undefined;
+  get clientMetadata(): OAuthClientMetadata;
+  tokens(): OAuthTokens | undefined;
+  saveTokens(tokens: OAuthTokens): void;
+  clientInformation(): OAuthClientInformationMixed | undefined;
+  saveClientInformation(info: OAuthClientInformationMixed): void;
+  discoveryState(): OAuthDiscoveryState | undefined;
+  saveDiscoveryState(state: OAuthDiscoveryState): void;
+  saveCodeVerifier(verifier: string): void;
+  codeVerifier(): string;
+  redirectToAuthorization(url: URL): Promise<void>;
+  /**
+   * Wipe stored credentials when the server reports the cached state is no
+   * longer valid. The SDK calls this with a scope hint:
+   *   - `'tokens'`  → access/refresh revoked, keep client registration
+   *   - `'client'`  → client registration invalidated, reset everything
+   *   - `'verifier'`→ PKCE state stale (e.g. mismatched state param)
+   *   - `'discovery'` → discovery metadata stale (servers re-keyed)
+   *   - `'all'`     → full reset
+   */
+  invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
+  private patch;
+}
+/**
+ * True when an HTTP transport's auth headers already include an explicit
+ * Authorization. Used by the bootstrap escape-hatch: a user who provided
+ * their own bearer token shouldn't be auto-promoted to OAuth on a 401.
+ *
+ * Case-insensitive — Node normalizes outgoing headers to lowercase but
+ * users hand-write `Authorization` in configs.
+ */
+declare function hasAuthorizationHeader(headers: Record<string, string> | undefined): boolean;
+//#endregion
+//#region src/mcp/login.d.ts
+interface LoginMcpServerOptions {
+  /** Persistence — same store the bootstrap path reads from. */
+  store: McpCredentialStore;
+  /**
+   * Invoked with the authorization URL once it's ready. Hosts typically
+   * (a) emit `mcp:auth:url` for the TUI, and (b) call `tryOpenBrowser`.
+   * The URL is identical to the one passed to the `mcp:auth:url` hook
+   * fired automatically — this callback is a synchronous hook for callers
+   * that don't want to wire the agent hook machinery.
+   */
+  onAuthorizationUrl?: (url: URL) => void | Promise<void>;
+  /** Cancels the flow (esc / close modal / SIGINT). */
+  signal?: AbortSignal;
+  /** Agent hooks. The flow emits `mcp:auth:url`/`success`/`error` when wired. */
+  hooks?: Hookable<AgentHooks>;
+  /** Override `client_name` shown on consent screens. Default: 'zidane'. */
+  clientName?: string;
+  /** Override the requested OAuth scope. */
+  scope?: string;
+  /**
+   * Override the loopback callback path. Default: `/callback`. Useful only
+   * for servers that pinned a different path during registration.
+   */
+  callbackPath?: string;
+  /**
+   * Maximum time to wait for the user to complete the browser flow, in ms.
+   * The user can also cancel via `signal`. Default: 5 minutes.
+   */
+  timeoutMs?: number;
+}
+interface LoginMcpServerResult {
+  /** Stored OAuth tokens after a successful exchange. */
+  tokens: NonNullable<ReturnType<McpOAuthProvider['tokens']>>;
+  /**
+   * Upstream tool descriptors discovered after re-connecting with the new
+   * tokens. Already filtered by the server's `enabledTools` / `disabledTools`
+   * is NOT applied here — that's a bootstrap concern. Hosts that want filtering
+   * should pass the result through `connectMcpServers` rebuild on the next
+   * session activation rather than reusing this list verbatim.
+   */
+  tools: Array<{
+    name: string;
+    description?: string | null;
+    inputSchema?: unknown;
+  }>;
+}
+/**
+ * Run the full interactive OAuth flow for `config`. Only supports `sse` and
+ * `streamable-http` transports — `stdio` MCP servers don't speak OAuth.
+ *
+ * Throws on:
+ *   - Wrong transport.
+ *   - Abort signal.
+ *   - Browser-side error (user denied, server rejected, etc.).
+ *   - Code exchange failure.
+ *   - Post-exchange connect failure.
+ *
+ * Always closes the loopback callback server before returning, success or
+ * failure.
+ */
+declare function loginMcpServer(config: McpServerConfig, options: LoginMcpServerOptions): Promise<LoginMcpServerResult>;
+//#endregion
+//#region src/mcp/oauth-callback.d.ts
+/**
+ * Local loopback HTTP callback for OAuth 2.0 authorization code flows.
+ *
+ * Stands up a one-shot server on `127.0.0.1:<random>` that captures the
+ * `?code=...` redirect from a browser-driven OAuth flow and resolves a
+ * promise with the code. Used as the `redirectUrl` half of the MCP SDK's
+ * `OAuthClientProvider` (the persistence half lives separately).
+ *
+ * Design:
+ *   - Loopback-only (`127.0.0.1`) — the OAuth spec treats `http://127.0.0.1:<port>`
+ *     as a public-client redirect URI per RFC 8252 §7.3. Browsers do NOT block it,
+ *     and Anthropic / OpenAI / Linear / GitHub all accept it.
+ *   - Random port (`port = 0`) — the OS picks an unused one. We read the actual
+ *     port back from `server.address()` after `listen()`.
+ *   - Single-shot — the first GET to `path` with a `code` (or `error`) wins;
+ *     subsequent requests get 404. The server keeps listening (in case the user
+ *     hits "back" and re-authorizes), so callers must `close()` once they have
+ *     the code or have given up.
+ *   - Abort-aware — wiring an external `AbortSignal` rejects the promise and
+ *     closes the server immediately. Required for the TUI's "esc cancels login"
+ *     UX.
+ *   - No HTML framework — a single inline `<html>` string keeps this isolated
+ *     from any UI dependency.
+ */
+/**
+ * Result of a successful callback. `state` is forwarded verbatim from the
+ * query string — callers verify it against their pre-flight value to defend
+ * against CSRF (the MCP SDK does this internally when it controls `state`).
+ */
+interface OAuthCallbackResult {
+  code: string;
+  state?: string;
+}
+interface OAuthCallbackHandle {
+  /**
+   * Full URI to register with the authorization server, e.g.
+   * `http://127.0.0.1:51823/callback`. Stable for the lifetime of the
+   * handle.
+   */
+  redirectUri: string;
+  /**
+   * Resolves with `{ code, state }` on a successful callback. Rejects with:
+   *   - The OAuth-spec `error` field (`access_denied`, `server_error`, ...)
+   *     when the authorization server redirects with `?error=...`.
+   *   - `'OAuth callback aborted'` when the external `AbortSignal` fires.
+   *   - `'OAuth callback server closed'` when `close()` is called before any
+   *     callback arrives.
+   *
+   * Single-shot — only the first matching request resolves the promise.
+   */
+  promise: Promise<OAuthCallbackResult>;
+  /**
+   * Idempotent shutdown. Safe to call from a `finally` block whether the
+   * flow succeeded, failed, or was aborted. Resolves once the server stops
+   * accepting connections.
+   */
+  close: () => Promise<void>;
+}
+interface OAuthCallbackOptions {
+  /** Cancels the flow — rejects `promise` and closes the server. */
+  signal?: AbortSignal;
+  /**
+   * Path component the authorization server should redirect to. Defaults
+   * to `/callback`. Useful when matching a pre-registered URI that uses a
+   * different path.
+   */
+  path?: string;
+  /**
+   * Override the loopback host. Defaults to `127.0.0.1`. Don't bind to
+   * `0.0.0.0` here — the OAuth code is a one-time secret and the server
+   * would otherwise accept it from any host on the LAN.
+   */
+  host?: string;
+  /**
+   * Override the port. Defaults to `0` (OS-assigned). Pin to a fixed port
+   * only when the authorization server requires a pre-registered redirect
+   * URI; the random-port path is preferred so concurrent flows don't clash.
+   */
+  port?: number;
+}
+/**
+ * Start a one-shot OAuth callback server. The returned handle's `redirectUri`
+ * should be passed to the authorization server as the `redirect_uri` query
+ * parameter; `promise` resolves once the user finishes the browser flow.
+ *
+ * Always `await handle.close()` in a `finally` block — even on success, the
+ * server stays open until told to shut down (so it can serve the
+ * "you can close this tab" page).
+ */
+declare function startOAuthCallback(opts?: OAuthCallbackOptions): Promise<OAuthCallbackHandle>;
+//#endregion
+//#region src/stats.d.ts
+/**
+ * Per-model usage rollup produced by {@link statsByModel}.
+ *
+ * `turns` counts the number of `TurnUsage` entries attributed to the model
+ * across the whole tree (parent loop + every recursively-spawned child).
+ * Cache and cost numbers are summed from the same set of turns.
+ */
+interface ModelUsage {
+  input: number;
+  output: number;
+  cost: number;
+  cacheRead: number;
+  cacheCreation: number;
+  turns: number;
+}
+/**
+ * Depth-first walk over the stats tree, returning every `TurnUsage` entry
+ * — parent loop first, then each child subtree in completion order.
+ *
+ * Closes the cache-token aggregation gap: `TurnUsage.cacheRead` /
+ * `cacheCreation` live only on per-turn entries, and the top-level
+ * `AgentStats` deliberately doesn't carry cumulative forms (one source of
+ * truth, no risk of drift). Anything that needs a tree-wide sum walks
+ * through this.
+ */
+declare function flattenTurns(stats: AgentStats): TurnUsage[];
+/**
+ * Group cumulative usage by `TurnUsage.modelId`. Each entry sums the input,
+ * output, cache, cost, and turn-count across every turn the tree attributed
+ * to that model — naturally handling cross-model runs (vision-fallback,
+ * model-shifted subagents, mixed-provider workflows).
+ *
+ * Turns missing `modelId` (mock providers, providers that don't echo a model
+ * id) are bucketed under the literal string `'(unknown)'`.
+ */
+declare function statsByModel(stats: AgentStats): Map<string, ModelUsage>;
+//#endregion
+//#region src/tools/edit.d.ts
+/**
+ * Surgical edit — replace `old_string` with `new_string` in a single file.
+ *
+ * Mirrors Claude Code's `Edit` semantics so models post-trained on Anthropic's
+ * tool surface need no relearning. Fails clearly when `old_string` isn't unique
+ * (unless `replace_all: true`) and when not found, with a nearest-match preview
+ * so the model can recover without a separate `read_file` round-trip.
+ */
+declare const edit: ToolDef;
+//#endregion
+//#region src/tools/glob.d.ts
+declare const glob: ToolDef;
+//#endregion
+//#region src/tools/grep.d.ts
+declare const grep: ToolDef;
+//#endregion
+//#region src/tools/interaction.d.ts
+interface InteractionToolOptions {
+  /** JSON Schema for the request payload the model sends */
+  schema: Record<string, unknown>;
+  /** Tool name (default: 'interaction') */
+  name?: string;
+  /** Tool description shown to the model */
+  description?: string;
+  /** Called when the model invokes this tool. Receives the validated payload and tool context, returns data for the model. */
+  onRequest: (payload: Record<string, unknown>, ctx: ToolContext) => Promise<Record<string, unknown> | string>;
+}
+/**
+ * Create an interaction tool that lets the agent request structured input.
+ *
+ * The model calls this tool with a payload matching the schema.
+ * `onRequest` is called with the payload and should return the response
+ * (string or object) that gets sent back to the model as the tool result.
+ */
+declare function createInteractionTool(options: InteractionToolOptions): ToolDef;
+//#endregion
+//#region src/tools/list-files.d.ts
+declare const listFiles: ToolDef;
+//#endregion
+//#region src/tools/multi-edit.d.ts
+declare const multiEdit: ToolDef;
+//#endregion
+//#region src/tools/read-file.d.ts
+declare const readFile: ToolDef;
+//#endregion
+//#region src/tools/shell.d.ts
+declare const shell: ToolDef;
+//#endregion
+//#region src/tools/skills-read.d.ts
+interface SkillsReadToolOptions {
+  catalog: readonly SkillConfig[];
+  state: SkillActivationState;
+}
+declare function createSkillsReadTool(options: SkillsReadToolOptions): ToolDef;
+//#endregion
+//#region src/tools/skills-run-script.d.ts
+interface SkillsRunScriptToolOptions {
+  catalog: readonly SkillConfig[];
+  state: SkillActivationState;
+  /** Script timeout in milliseconds. Default 60000. */
+  scriptTimeoutMs?: number;
+}
+declare function createSkillsRunScriptTool(options: SkillsRunScriptToolOptions): ToolDef;
+//#endregion
+//#region src/tools/skills-use.d.ts
+interface SkillsUseToolOptions {
+  /** Resolved skills catalog for this run. */
+  catalog: readonly SkillConfig[];
+  /** Per-agent activation state the tool mutates. */
+  state: SkillActivationState;
+  /** Agent hooks — used to fire `skills:activate` on first activation. */
+  hooks: Hookable<AgentHooks>;
+}
+/**
+ * Factory for `skills_use`. Auto-injected into the agent's tool set by the
+ * agent runtime when a non-empty skills catalog is available (unless
+ * `SkillsConfig.tool === false`).
+ *
+ * The tool schema's `name` property is `enum`-constrained to the resolved
+ * catalog so the LLM cannot hallucinate a skill that doesn't exist.
+ */
+declare function createSkillsUseTool(options: SkillsUseToolOptions): ToolDef;
+//#endregion
+//#region src/tools/spawn.d.ts
+interface ChildAgent {
+  id: string;
+  task: string;
+  startedAt: number;
+  /** Subagent depth — 1 for a direct child of a top-level agent. */
+  depth: number;
+}
+interface SpawnToolState {
+  /** Currently running children. */
+  readonly children: ReadonlyMap<string, ChildAgent>;
+  /**
+   * Cumulative stats across every completed direct child of this spawn-tool
+   * instance (returns a copy). Each child's contribution is the cumulative
+   * `AgentStats` returned by its `agent.run()` — so
+   * `totalIn`/`totalOut`/`totalCacheRead`/`totalCacheCreation` cover the
+   * entire subtree (children + grandchildren + …), while `turns` and
+   * `elapsed` stay parent-loop-only per child and are summed across direct
+   * children. `elapsed` over-counts when children ran in parallel.
+   *
+   * Lives across multiple parent runs that share this instance.
+   */
+  readonly totalChildStats: Readonly<AgentStats>;
+}
+interface SpawnToolOptions {
+  /** Maximum concurrent sub-agents (default: 3). */
+  maxConcurrent?: number;
+  /**
+   * Maximum subagent depth. 0 disables spawning entirely; 1 allows top-level
+   * spawns but forbids grandchildren; 3 (default) allows three levels of
+   * recursion — enough for most orchestration patterns, a sharp ceiling
+   * against runaway loops.
+   */
+  maxDepth?: number;
+  /** Child model override. */
+  model?: string;
+  /** Child system prompt override. Per-spawn `input.system` takes precedence. */
+  system?: string;
+  /** Child thinking level. */
+  thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high';
+  /** Preset override for children. Shallow-merged over the parent's preset (parent fields still win for anything left unset). */
+  preset?: Preset;
+  /**
+   * Per-child timeout, in milliseconds. When the child exceeds it the spawn
+   * tool returns a timeout marker, fires `spawn:error`, and destroys the
+   * child agent. Default: none.
+   */
+  timeoutMs?: number;
+  /**
+   * When `true` and the parent has a session, the child reuses the parent's
+   * session — child turns are appended with the child's own `runId`, and the
+   * resulting `SessionRun` carries `parentRunId` so the tree is
+   * reconstructible. Default: `false` (child is in-memory only).
+   */
+  persist?: boolean;
+  /**
+   * Forward a curated subset of child hook events (`stream:*`, `tool:*`,
+   * `turn:after`) onto the parent's hook bus as `child:*` events. Default:
+   * `true`. Grandchildren bubble through their child transparently.
+   */
+  forwardHooks?: boolean;
+  /** Called when a child agent starts. */
+  onSpawn?: (child: ChildAgent) => void;
+  /** Called when a child agent completes (success, abort, timeout, or error). */
+  onComplete?: (child: ChildAgent, stats: AgentStats, status: NonNullable<ChildRunStats['status']>) => void;
+}
+/**
+ * Create a configured spawn tool.
+ *
+ * State (`children`, `totalChildStats`, counters, active count) is scoped to
+ * the returned instance. Multiple parent agents using the same instance will
+ * share counters + stats + concurrency slots — call `createSpawnTool()` per
+ * agent (or use the stateless default `spawn`) to keep them isolated.
+ */
+declare function createSpawnTool(options?: SpawnToolOptions): ToolDef & SpawnToolState;
+//#endregion
+//#region src/tools/tool-search.d.ts
+interface LazyToolEntry {
+  /**
+   * Wire name (after `toolAliases` rewrite). What the model sees in the
+   * catalog, what `tool_search` matches against, and what the provider's
+   * tool list will carry once the entry is unlocked.
+   */
+  name: string;
+  /**
+   * Canonical (registry-key) name used for unlock-set membership and for the
+   * loop's `ctx.tools[name]` dispatch lookup. Equal to `name` when no alias
+   * is configured for this tool.
+   */
+  canonicalName: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  /** Source MCP server, when applicable. Used for `server`-bulk unlock. */
+  server?: string;
+}
+interface ToolSearchToolOptions {
+  /**
+   * Snapshot of every lazy tool the model can discover. Built once per run by
+   * the agent — the tool closes over this array and never mutates it.
+   */
+  catalog: readonly LazyToolEntry[];
+  /**
+   * Mutable per-run set of unlocked **canonical** tool names. The tool adds
+   * matches in place; the loop reads the set when rebuilding the wire-level
+   * tool list. Keyed by canonical (not wire) so dispatch lookups stay
+   * alias-stable.
+   */
+  unlocked: Set<string>;
+  /** Default cap on returned matches when the model omits `limit`. */
+  defaultLimit?: number;
+}
+/**
+ * Factory for `tool_search`. Auto-injected by the agent when
+ * `behavior.toolDisclosure === 'lazy'` and at least one MCP tool is in the
+ * registry. Opt out via `behavior.toolSearch.tool === false`.
+ */
+declare function createToolSearchTool(options: ToolSearchToolOptions): ToolDef;
+//#endregion
+//#region src/tools/validation.d.ts
+/**
+ * Tool argument validation against JSON Schema-style inputSchema.
+ *
+ * Two passes:
+ *   1. Required-field presence. Missing or null/undefined required fields fail.
+ *   2. Top-level type checks with **best-effort coercion**. Small/OSS models
+ *      routinely send `"true"` for a `boolean` field or `"42"` for a `number`,
+ *      and rejecting outright forces a confusing retry. Instead, we auto-heal
+ *      coerce when the conversion is unambiguous, fail only when the value
+ *      cannot be reasonably normalized to any of the declared types.
+ *
+ * Nested validation is intentionally out of scope — keep it cheap and let the
+ * tool's `execute` body assert deeper invariants.
+ */
+interface ValidationResult {
+  valid: boolean;
+  /** Human-readable reason. Present on failure only. */
+  error?: string;
+  /**
+   * Possibly-coerced input. Present iff `valid: true`. Tools should call
+   * `execute(coercedInput, ctx)` so auto-healed values reach the tool body.
+   * When no coercion was applied, this is reference-equal to the input.
+   */
+  coercedInput?: Record<string, unknown>;
+  /**
+   * Names of fields whose values were coerced. Empty when nothing changed.
+   * Useful for telemetry (`validation:reject` on failure already carries the
+   * reason; this is the success-path equivalent).
+   */
+  coercions?: readonly string[];
+}
+declare function validateToolArgs(input: Record<string, unknown>, schema: Record<string, unknown>): ValidationResult;
+//#endregion
+//#region src/tools/write-file.d.ts
+/**
+ * Write a file, with an idempotency signal when the content is unchanged.
+ *
+ * Three return shapes — chosen so the model can recognize a no-op without a
+ * separate read:
+ *   - `Created path (N bytes)` — file did not exist
+ *   - `Updated path (N bytes)` — content differed from on-disk
+ *   - `No change needed: path already at target state (N bytes)` — equal
+ *
+ * Race window: in non-process execution contexts (docker, sandbox) shared by
+ * multiple agents, another writer can mutate the file between our read and
+ * our write. Local process context is single-writer per agent so the race is
+ * a non-issue there. Documented rather than locked because the cost of
+ * cross-context locking outweighs the cost of a stale "No change" message.
+ */
+declare const writeFile: ToolDef;
+//#endregion
+//#region src/tracing.d.ts
+/** Minimal span shape — any tracer that provides these two methods is compatible. */
+interface Span {
+  /** Close the span. Called exactly once per span. */
+  end: () => void;
+  /** Optional: attach additional attributes after the span is started (ignored if unsupported). */
+  setAttributes?: (attrs: Record<string, unknown>) => void;
+}
+/** Function that opens a span. Caller-provided so we stay tracer-agnostic. */
+type StartSpan = (name: string, attrs?: Record<string, unknown>) => Span;
+interface TracingHooksOptions {
+  /** Tracer seam. Receives a span name + attributes; must return a `Span`. */
+  startSpan: StartSpan;
+  /**
+   * Optional attribute namespace. Prepended to every span name (e.g. `"agent"` →
+   * span names like `agent/turn:0`, `agent/tool:Bash`).
+   */
+  namespace?: string;
+}
+/** Value returned by {@link createTracingHooks} — install entrypoint. */
+interface TracingHookSet {
+  /**
+   * Attach every hook handler to the given agent hooks instance.
+   *
+   * @returns an `uninstall` function that detaches every handler and closes any
+   * still-open spans. Safe to call multiple times.
+   */
+  install: (hooks: Hookable<AgentHooks>) => () => void;
+}
+/**
+ * Build a set of tracing hook handlers that can be installed on an agent.
+ *
+ * @example Sentry
+ * ```ts
+ * const tracing = createTracingHooks({
+ *   startSpan: (name, attrs) => Sentry.startInactiveSpan({ name, attributes: attrs }),
+ * })
+ * const uninstall = tracing.install(agent.hooks)
+ * try { await agent.run({ prompt }) }
+ * finally { uninstall() }
+ * ```
+ */
+declare function createTracingHooks(options: TracingHooksOptions): TracingHookSet;
+//#endregion
+//#region src/zod.d.ts
+/**
+ * Zod v4 integration helper.
+ *
+ * Normalizes the output of z.toJsonSchema() for use as ToolSpec.inputSchema.
+ * Zod is an optional peer dependency — consumers call z.toJsonSchema() themselves.
+ *
+ * Usage:
+ *   import { z } from 'zod'
+ *   import { zodToJsonSchema } from 'zidane'
+ *   const schema = zodToJsonSchema(z.toJsonSchema(z.object({ name: z.string() })))
+ */
+/**
+ * Normalize a JSON Schema (e.g. from zod v4's z.toJsonSchema()) for use
+ * as a ToolSpec.inputSchema.
+ *
+ * Strips the $schema key that some providers reject.
+ */
+declare function zodToJsonSchema(jsonSchema: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+//#region src/presets/basic.d.ts
+/**
+ * Core tools available in every basic preset (without spawn).
+ *
+ * `edit` and `multi_edit` ship in the basic set because surgical edits are the
+ * default modality for production agents — `write_file` is for full overwrites.
+ * `glob` and `grep` are exported but opt-in: not every agent needs codebase
+ * search, and shipping them by default would force `tool:gate` work onto
+ * consumers that prefer the model to use `shell` + classic Unix tools.
+ */
+declare const basicTools: {
+  shell: ToolDef;
+  readFile: ToolDef;
+  writeFile: ToolDef;
+  listFiles: ToolDef;
+  edit: ToolDef;
+  multiEdit: ToolDef;
+};
+declare const _default: Preset;
+//#endregion
+//#region src/presets/index.d.ts
+/**
+ * A preset is a reusable slice of `AgentOptions` — spread it into `createAgent()`
+ * to configure tools, a default system prompt, aliases, behavior defaults, and
+ * agent-lifetime hooks.
+ *
+ * `provider`, `execution`, `session`, and internal fields are excluded so presets
+ * remain shareable and composable.
+ *
+ * ```ts
+ * import { basic } from 'zidane/presets'
+ * createAgent({ ...basic, provider })
+ * ```
+ *
+ * ### Composing multiple presets
+ *
+ * Bare `...spread` is shallow — `{ ...a, ...b }` overwrites every key `b`
+ * defines, including `hooks`. Use {@link composePresets} when you want
+ * field-aware merging (per-event hook concat, tools shallow-merge, etc.):
+ *
+ * ```ts
+ * createAgent({ ...composePresets(basic, telemetry, mine), provider })
+ * ```
+ */
+type Preset = Omit<Partial<AgentOptions>, 'provider' | 'execution' | 'session' | 'mcpConnector'>;
+/**
+ * Identity helper for type inference when defining a preset.
+ */
+declare function definePreset(config: Preset): Preset;
+/**
+ * Field-aware composition of presets. Right-most preset wins for scalar fields;
+ * objects shallow-merge; arrays and hook handler lists concatenate. Designed so
+ * stacking presets does the obvious thing without the spread-collision footgun:
+ *
+ * - `name`, `system`, `eager`, `skills`           → last-defined wins
+ * - `tools`, `toolAliases`, `behavior`            → shallow-merge (later keys override)
+ * - `mcpServers`                                  → concat with last-wins on `name` collision
+ * - `hooks`                                       → per-event concat; every handler fires
+ *
+ * `hooks` always emerges as `event → handler[]` so downstream registration
+ * (in `createAgent`) sees a uniform shape. Order of handlers within an event
+ * follows preset order: earlier presets register first.
+ *
+ * `mcpServers` is deduped by `name` because shipping two servers with the same
+ * name would trip the connector at runtime — a later preset overriding an
+ * earlier preset's `github` server is the practical intent.
+ */
+declare function composePresets(...presets: Preset[]): Preset;
+//#endregion
+export { PERSISTENCE_PREVIEW_BYTES as $, listFiles as A, buildTailCompactPrompt as At, OAuthCallbackOptions as B, truncateHeadForPtlRetry as Bt, SkillsRunScriptToolOptions as C, CompactPromptBuilder as Ct, shell as D, buildCompactPrompt as Dt, createSkillsReadTool as E, TRAILER as Et, edit as F, SummaryToTurnInput as Ft, loginMcpServer as G, startOAuthCallback as H, ModelUsage as I, anchorPreviewFor as It, McpOAuthProvider as J, McpCredentialEntry as K, flattenTurns as L, sliceForCompaction as Lt, createInteractionTool as M, ANCHOR_PREVIEW_MAX_CHARS as Mt, grep as N, CompactScope as Nt, readFile as O, buildFromCompactPrompt as Ot, glob as P, CompactionSlice as Pt, PERSISTED_STUB_PREFIX as Q, statsByModel as R, stripImagesFromTurns as Rt, createSkillsUseTool as S, CompactDirection as St, SkillsReadToolOptions as T, NO_TOOLS_PREAMBLE as Tt, LoginMcpServerOptions as U, OAuthCallbackResult as V, LoginMcpServerResult as W, createMemoryMcpCredentialStore as X, McpOAuthProviderOptions as Y, hasAuthorizationHeader as Z, ChildAgent as _, CompactResult as _t, basicTools as a, resolvePersistDir as at, createSpawnTool as b, CompactPromptTooLongError as bt, TracingHookSet as c, utf8ByteLength as ct, writeFile as d, RecentFile as dt, PersistInput as et, ValidationResult as f, buildPostCompactAttachments as ft, createToolSearchTool as g, CompactOptions as gt, ToolSearchToolOptions as h, selectRecentFiles as ht, _default as i, maybePersistToolResult as it, InteractionToolOptions as j, buildUpToCompactPrompt as jt, multiEdit as k, buildFullCompactPrompt as kt, TracingHooksOptions as l, PostCompactAttachments as lt, LazyToolEntry as m, selectFilesFromSession as mt, composePresets as n, buildPersistedStub as nt, zodToJsonSchema as o, BYTES_PER_TOKEN as ot, validateToolArgs as p, selectFilesFromReadState as pt, McpCredentialStore as q, definePreset as r, cleanupPersistedSession as rt, Span as s, estimateTokens as st, Preset as t, PersistOutcome as tt, createTracingHooks as u, PostCompactRestoreOptions as ut, SpawnToolOptions as v, compactConversation as vt, createSkillsRunScriptTool as w, CompactPromptOptions as wt, SkillsUseToolOptions as x, BASE_INSTRUCTIONS as xt, SpawnToolState as y, CompactInvalidInputError as yt, OAuthCallbackHandle as z, summaryToTurn as zt };
+//# sourceMappingURL=index-CFxhms_B.d.ts.map