zidane 5.6.15 → 5.7.4

package/dist/{agent-CkJp_ZOR.d.ts → agent-BNS2nx_T.d.ts}

@@ -1,9 +1,231 @@
-import { a as ExecutionContext, o as ExecutionHandle } from "./types-2PMY5Rlc.js";
+import { a as ExecutionContext, o as ExecutionHandle } from "./types-CEAMIUXw.js";
 import { Hookable } from "hookable";
+import { OAuthCredentials, getOAuthApiKey } from "@earendil-works/pi-ai/oauth";
 import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import Anthropic from "@anthropic-ai/sdk";
 
+//#region src/chat/context-breakdown.d.ts
+/**
+ * Context-usage breakdown — pure transforms.
+ *
+ * Turns a {@link ContextSnapshot} (the raw pieces the agent assembled for a
+ * run: system prompt, wire tools, deferred tools, MCP tools/instructions,
+ * skills catalog, ...) plus the real last-turn token total into a categorized
+ * {@link ContextBreakdown} the TUI panel / GUI popover render.
+ *
+ * No React, no node — a browser-context renderer imports these via
+ * `zidane/chat/pure`. The snapshot is captured main-side (TUI direct, GUI in
+ * `main/chat`) because building it reads provider/agent state; only the pure
+ * shaping lives here.
+ *
+ * Accuracy: per-category counts are estimates when no provider `countTokens`
+ * is available — the heuristic ({@link estimateTokens}, ~4 bytes/token) sizes
+ * each static segment and the bar is reconciled so it always sums to the real
+ * last-turn total (`conversation = realTotal - sum(static)`). When a provider
+ * exposes exact counts (Anthropic, OpenAI), the caller passes them in via
+ * {@link ContextSnapshot.exact} and the corresponding categories drop their
+ * `estimated` flag. Exact buckets (free space, autocompact buffer) are never
+ * estimated.
+ */
+/**
+ * Stable identifiers for each breakdown category. Drives swatch color +
+ * ordering in both UIs. `*Deferred` buckets are tools/MCP that exist but are
+ * NOT currently on the wire (lazy disclosure); `autocompactBuffer` is the
+ * reserved output headroom; `freeSpace` is the remaining window.
+ */
+type ContextCategoryId = 'systemPrompt' | 'rules' | 'tools' | 'mcpTools' | 'mcpInstructions' | 'skills' | 'subagentDefs' | 'conversation' | 'mcpToolsDeferred' | 'toolsDeferred' | 'autocompactBuffer' | 'freeSpace';
+/**
+ * Exact last-turn token usage split (provider-reported — always exact). Drives
+ * the cache breakdown shown below the categories. `cacheRead + cacheCreation +
+ * input` equals the live context total (`used`).
+ */
+interface ContextUsageSplit {
+  /** Fresh, uncached input tokens this turn. */
+  input: number;
+  /** Tokens served from the prompt cache (the cached prefix). */
+  cacheRead: number;
+  /** Tokens written to the cache this turn. */
+  cacheCreation: number;
+  /** Assistant output tokens (not part of the input window; informational). */
+  output: number;
+}
+/** One expandable child row under a category (e.g. a single MCP tool / memory file). */
+interface ContextItem {
+  /** Stable-ish key for rendering (tool name, file path). */
+  id: string;
+  /** Display label. */
+  label: string;
+  /** Token count for this item. */
+  tokens: number;
+  /** True when `tokens` came from the heuristic rather than an exact count. */
+  estimated: boolean;
+}
+/** One category row in the breakdown. */
+interface ContextCategory {
+  id: ContextCategoryId;
+  /** Display label (e.g. "Tool definitions"). */
+  label: string;
+  /** Token count for the category. */
+  tokens: number;
+  /** True when `tokens` came from the heuristic rather than an exact count. */
+  estimated: boolean;
+  /**
+   * True for buckets that are NOT counted against the live window total
+   * (deferred tools, free space, autocompact buffer) — the UI renders these
+   * dimmed / below a divider, mirroring Claude Code's layout.
+   */
+  deferred?: boolean;
+  /** Optional expandable child rows (per MCP tool, per memory file, ...). */
+  items?: ContextItem[];
+}
+/** The shaped, render-ready breakdown. */
+interface ContextBreakdown {
+  /** Model id the snapshot was built for. */
+  modelId: string;
+  /**
+   * Real last-turn context size (provider-reported `input + cacheRead +
+   * cacheCreation`) — the SAME number the footer/orb shows. The non-deferred
+   * categories always sum to this.
+   */
+  used: number;
+  /** Effective window (raw - output reserve), the bar's denominator. */
+  effectiveWindow: number;
+  /** `used / effectiveWindow`, clamped to [0, 1]. */
+  fraction: number;
+  /** Live categories (sum to `used`) followed by deferred + free-space buckets. */
+  categories: ContextCategory[];
+  /** True when ANY live category is estimated (drives the panel's footnote). */
+  hasEstimates: boolean;
+  /**
+   * Exact last-turn usage split (cache read / write / fresh input / output),
+   * when the host supplied it. Always exact — rendered as an informational
+   * section below the categories. Absent when no usage is available yet.
+   */
+  usage?: ContextUsageSplit;
+  /**
+   * Names of currently-active skills. Informational — an activated skill's body
+   * lands in the conversation (tool-results), so its tokens are already counted
+   * under Conversation; this just surfaces "which skills are loaded". Empty/absent
+   * when none are active.
+   */
+  activeSkills?: string[];
+}
+/** Host-supplied options for `agent.getContextBreakdown`. */
+interface ContextBreakdownOptions {
+  /**
+   * Effective context window (`rawWindow - outputReserve`) for the active
+   * model, resolved by the host via the chat model registry. Drives free-space
+   * + fraction. When omitted, defaults to `used` (no headroom shown).
+   */
+  effectiveWindow?: number;
+  /**
+   * Active model id — used for the exact `countTokens` call + the header label.
+   * Only consulted on the PRE-RUN path (no snapshot yet); once a run has fired,
+   * the snapshot's own model wins. When omitted, the provider default is used.
+   */
+  model?: string;
+  /** Tokens reserved for output (autocompact buffer). Defaults to 0. */
+  autocompactBuffer?: number;
+  /**
+   * Auto-compact threshold as a fraction of the window (0–1), when enabled.
+   * When set, the "Autocompact buffer" bucket represents the ENTIRE tail from
+   * the threshold to the end of the window (`(1 − threshold) × window`) rather
+   * than just the reserved-output tokens — so the bar/row show exactly where
+   * compaction fires. When omitted, `autocompactBuffer` is used as-is.
+   */
+  compactThreshold?: number;
+  /** Abort signal forwarded to the provider's `countTokens`. */
+  signal?: AbortSignal;
+}
+/** Tools grouped by MCP server, for the expandable per-server rows. */
+interface ContextMcpGroup {
+  server: string;
+  /** Wire tool specs for this server (their JSON size is measured). */
+  tools: {
+    name: string;
+    json: string;
+  }[];
+}
+/**
+ * Exact per-segment counts from a provider's `countTokens`, when available.
+ * Each field is the count of the cumulative payload up to and including that
+ * segment, so categories are derived by differencing (see
+ * {@link buildContextBreakdown}). Any subset may be present; missing fields
+ * fall back to the heuristic for that category.
+ */
+interface ContextExactCounts {
+  /** Tokens for system prompt alone. */
+  system?: number;
+  /** Tokens for system + tools (so tools = systemAndTools - system). */
+  systemAndTools?: number;
+  /** Tokens for the full payload (system + tools + messages) = the real total. */
+  full?: number;
+}
+/**
+ * Raw inputs captured at agent prompt-assembly time. Everything here is what
+ * actually went on (or was withheld from) the wire for the last run.
+ */
+interface ContextSnapshot {
+  modelId: string;
+  /** Full rendered system prompt (marker-stripped, as sent). */
+  system: string;
+  /**
+   * Host-composed base system BEFORE the agent appended skills / searchable /
+   * MCP-instructions catalogs. Includes the rules block. The "System prompt"
+   * (base doctrine) bucket = base − rules − env-noise. Defaults to `system`
+   * when not provided (back-compat).
+   */
+  baseSystem?: string;
+  /** Rendered AGENTS.md/CLAUDE.md rules block (a substring of `baseSystem`). */
+  rulesBlock?: string;
+  /** Source files behind the rules block, for per-file rows. */
+  rulesFiles?: {
+    path: string;
+    source: string;
+  }[];
+  /** Wire tool specs currently disclosed to the model, as JSON strings. */
+  toolsJson: string[];
+  /** Lazy tool entries NOT currently disclosed (deferred), as JSON strings. */
+  deferredToolsJson: string[];
+  /** MCP tools grouped by server (disclosed ones). */
+  mcpGroups: ContextMcpGroup[];
+  /** Deferred (undisclosed) MCP tools grouped by server. */
+  deferredMcpGroups: ContextMcpGroup[];
+  /** Rendered MCP instructions block, if any. */
+  mcpInstructions?: string;
+  /** Rendered skills catalog text, if any. */
+  skillsCatalog?: string;
+  /** Searchable / subagent (spawn) tool definitions text, if any. */
+  subagentDefs?: string;
+  /** Memory / rules files in context. */
+  /** Real last-turn total (input + cacheRead + cacheCreation). */
+  used: number;
+  /** Effective window (raw - output reserve). */
+  effectiveWindow: number;
+  /** Tokens reserved for output (autocompact buffer). */
+  autocompactBuffer: number;
+  /** Exact per-segment counts from the provider, when available. */
+  exact?: ContextExactCounts;
+  /** Exact last-turn usage split, when available (passed straight through). */
+  usage?: ContextUsageSplit;
+  /** Names of currently-active skills (passed straight through). */
+  activeSkills?: string[];
+}
+/**
+ * Shape a {@link ContextSnapshot} into a render-ready {@link ContextBreakdown}.
+ *
+ * Live categories (system prompt, tools, MCP tools/instructions, skills,
+ * memory, subagent defs, conversation) sum to `snapshot.used` — `conversation`
+ * absorbs the remainder so the bar matches the provider-reported total exactly.
+ * Deferred + autocompact + free-space buckets follow.
+ *
+ * When `snapshot.exact` carries provider counts, the matching categories use
+ * them (system, tools) and drop their `estimated` flag; everything else stays
+ * on the heuristic.
+ */
+declare function buildContextBreakdown(snapshot: ContextSnapshot): ContextBreakdown;
+//#endregion
 //#region src/errors.d.ts
 /**
  * Typed error classes for agent runs.
@@ -629,6 +851,12 @@ interface AgentBehavior {
   maxTokens?: number;
   /** Thinking token budget — overrides the level-based default when set */
   thinkingBudget?: number;
+  /**
+   * Default model-specific options applied to every run, keyed by option id
+   * (e.g. `{ fast: true }`). A per-run {@link AgentRunOptions.modelOptions}
+   * takes precedence when set. See `StreamOptions.modelOptions`.
+   */
+  modelOptions?: Record<string, boolean>;
   /** JSON Schema for structured output enforcement */
   schema?: Record<string, unknown>;
   /**
@@ -1146,6 +1374,40 @@ interface AgentBehavior {
    * Default: `false`.
    */
   strictToolPairing?: boolean;
+  /**
+   * Egress allowlist for the web tools (`fetch_url`, `web_search`). When set
+   * to a non-empty list, those tools refuse any request whose target host
+   * isn't covered — on `fetch_url` this is checked for the initial URL AND
+   * every redirect hop (alongside the SSRF blocklist); on `web_search` it
+   * gates the keyless DuckDuckGo / Tavily / Brave backends so a sandboxed or
+   * compliance-bound host can pin egress to approved domains.
+   *
+   * Matching is host-suffix based and case-insensitive: an entry `example.com`
+   * matches `example.com` and any subdomain (`docs.example.com`), but not
+   * `notexample.com`. Ports are ignored (match on hostname only). Leading
+   * dots are tolerated (`.example.com` ≡ `example.com`).
+   *
+   * Default: `undefined` (no allowlist — every public host is reachable,
+   * subject to the SSRF blocklist). An empty array is treated the same as
+   * `undefined` so a host can't accidentally lock itself out with `[]`.
+   */
+  fetchUrlAllowHosts?: readonly string[];
+  /**
+   * Enable an in-process response cache for the `fetch_url` tool, with this
+   * TTL in milliseconds. Keyed on the requested URL string. When a fan-out
+   * re-fetches the same page within the window (e.g. spidering a docs site
+   * across parallel tool calls), the cached body is returned without a second
+   * network round-trip.
+   *
+   * The cache is bounded by entry count and total bytes (fixed internal caps)
+   * and is **process-local** — it never persists across restarts and is not
+   * shared between agents. Only successful `2xx` text responses are cached;
+   * redirects, errors, and aborts are not.
+   *
+   * Default: `undefined` / `0` → caching disabled (every call is a fresh
+   * fetch — the stateless default). Set e.g. `900_000` (15 min) to enable.
+   */
+  fetchUrlCacheTtlMs?: number;
 }
 /**
  * One block of a multimodal user prompt.
@@ -1289,6 +1551,32 @@ type SessionContentBlock = {
    * embedded signatures, so the sender drops the block on mismatch.
    */
   model?: string;
+} | {
+  /**
+   * Anthropic server-side tool invocation block (currently `web_search`).
+   * Captured opaquely so the model's reasoning chain stays intact across
+   * turns — Anthropic's docs require `encrypted_content` and
+   * `encrypted_index` to be passed back on follow-up turns or citation
+   * context is lost. Dropped on cross-provider sends.
+   */
+  type: 'server_tool_use';
+  producer: 'anthropic';
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+} | {
+  /**
+   * Anthropic server-side tool result block. Pairs with `server_tool_use`
+   * and carries the search hits Anthropic injected into the assistant
+   * message. The full content array is preserved as `unknown[]` so
+   * `encrypted_content` / `encrypted_index` survive a session round-trip
+   * verbatim.
+   */
+  type: 'server_tool_result';
+  producer: 'anthropic';
+  toolUseId: string;
+  toolName: string;
+  content: unknown;
 } | {
   /**
    * Compaction marker. Inserted by `compactConversation()` to replace a
@@ -1344,7 +1632,28 @@ interface AgentRunOptions {
    */
   prompt?: string | PromptPart[];
   system?: string;
+  /**
+   * Optional metadata describing which named sections the host baked into
+   * `system` (e.g. the rendered AGENTS.md/CLAUDE.md "Rules" block). Purely
+   * informational — used by `agent.getContextBreakdown()` to attribute system-
+   * prompt tokens to a "Rules" bucket the agent can't otherwise isolate from
+   * the opaque base string. Does not affect what's sent to the model.
+   */
+  contextSections?: {
+    /** Rendered user-instructions / rules block text (a substring of `system`). */rulesBlock?: string; /** Source files behind the rules block, for per-file breakdown rows. */
+    rulesFiles?: {
+      path: string;
+      source: string;
+    }[];
+  };
   thinking?: ThinkingLevel;
+  /**
+   * Enabled model-specific options for this run, keyed by option id (e.g.
+   * `{ fast: true }` for Anthropic's fast mode). Options the active model
+   * doesn't declare are silently ignored by the provider. Overrides
+   * {@link AgentBehavior.modelOptions} when both are set.
+   */
+  modelOptions?: Record<string, boolean>;
   /** Abort signal — when triggered, the agent stops after the current turn */
   signal?: AbortSignal;
   /** Behavior overrides for this run (overrides agent defaults) */
@@ -1663,6 +1972,14 @@ interface OAuthRefreshHookContext {
 }
 type SessionEndStatus = 'completed' | 'aborted' | 'error';
 //#endregion
+//#region src/providers/oauth.d.ts
+interface OAuthParams {
+  apiKey?: string;
+  access?: string;
+  refresh?: string;
+  expires?: number;
+}
+//#endregion
 //#region src/providers/anthropic.d.ts
 /**
  * Server-side context-management config — the body of `context_management` on
@@ -1676,11 +1993,7 @@ interface AnthropicContextManagement {
   edits?: Array<Record<string, unknown>>;
   [key: string]: unknown;
 }
-interface AnthropicParams {
-  apiKey?: string;
-  access?: string;
-  refresh?: string;
-  expires?: number;
+interface AnthropicParams extends OAuthParams {
   defaultModel?: string;
   /**
    * Optional override for the Anthropic SDK base URL. Honored end-to-end — headers and
@@ -1784,14 +2097,82 @@ interface CerebrasParams {
  */
 declare function cerebras(params?: CerebrasParams): Provider;
 //#endregion
-//#region src/providers/openai.d.ts
-interface OpenAIParams {
-  /** OpenAI Codex OAuth access token. Falls back to OPENAI_CODEX_API_KEY and .credentials.json. */
+//#region src/providers/cursor.d.ts
+/**
+ * Cursor provider (OAuth).
+ *
+ * Auth is fully wired: `bun run auth --cursor` (or the TUI wizard) logs in via
+ * Cursor's poll-based PKCE flow and persists credentials; this provider resolves
+ * + refreshes the OAuth token on every turn via {@link resolveOAuthApiKey}.
+ *
+ * Inference is **not** wired yet. Cursor does not expose an OpenAI-compatible
+ * HTTP endpoint — it speaks a protobuf/Connect agent protocol over HTTP/2 to
+ * `api2.cursor.sh`. Implementing `stream()` requires porting that transport
+ * (generated protobuf schemas + an HTTP/2 streaming client) in-process, which
+ * is intentionally left as a follow-up. Until then `stream()` resolves the
+ * token (proving auth works) and then throws a clear, actionable error.
+ *
+ * The `openaiCompat` base supplies the message-format helpers (`formatTools`,
+ * `userMessage`, `toolResultsMessage`, …) so the provider satisfies the full
+ * `Provider` contract and slots into the registry; only `stream` is overridden.
+ */
+interface CursorParams {
+  /** Bypass OAuth resolution with an explicit token (mainly for tests). */
   apiKey?: string;
-  /** Alias for apiKey, matching the OAuth credential field. */
-  access?: string;
-  refresh?: string;
-  expires?: number;
+  defaultModel?: string;
+}
+declare function cursor(params?: CursorParams): Provider;
+//#endregion
+//#region src/providers/local.d.ts
+interface LocalParams {
+  /**
+   * Base URL of the local OpenAI-compatible server. `/chat/completions` is
+   * appended. Examples:
+   *   - Ollama:    `http://localhost:11434/v1`
+   *   - vLLM:      `http://localhost:8000/v1`
+   *   - LM Studio: `http://localhost:1234/v1`
+   *   - Lemonade:  `http://localhost:8000/api/v1`
+   *   - llama.cpp: `http://localhost:8080/v1`
+   *
+   * Resolution order: explicit `params.baseURL` > `LOCAL_LLM_BASE_URL` env >
+   * throw.
+   */
+  baseURL?: string;
+  /**
+   * Optional bearer key. Most local servers don't authenticate; some (vLLM
+   * with `--api-key`, gateway proxies, llama.cpp with `--api-key`) do.
+   * Falls back to `LOCAL_LLM_API_KEY`, then to a placeholder string accepted
+   * by unauthenticated endpoints.
+   */
+  apiKey?: string;
+  /**
+   * Default model id. Local runtimes have no fixed catalogue — whatever the
+   * user has loaded (e.g. `llama3.1:8b`, `qwen2.5-coder`, a HF repo path).
+   * Falls back to `LOCAL_LLM_DEFAULT_MODEL`.
+   */
+  defaultModel?: string;
+  /**
+   * Provider capability flags. Defaults to text-only — typical OSS local
+   * deployment. Override when pointing at a vision-capable runtime (e.g.
+   * Ollama serving a multimodal model, vLLM with a VLM).
+   */
+  capabilities?: ProviderCapabilities;
+}
+/**
+ * Local OpenAI-compatible LLM provider.
+ *
+ * Thin wrapper around {@link openaiCompat} for self-hosted runtimes that
+ * speak the standard `POST /chat/completions` + SSE dialect: Ollama, vLLM,
+ * LM Studio, Lemonade, llama.cpp's server, text-generation-webui, etc.
+ *
+ * Caching and reasoning are left off — local runtimes typically strict-
+ * validate the request schema and would 400 on the extra fields. Override
+ * `capabilities` when pointing at a vision-capable deployment.
+ */
+declare function local(params?: LocalParams): Provider;
+//#endregion
+//#region src/providers/openai.d.ts
+interface OpenAIParams extends OAuthParams {
   accountId?: string;
   defaultModel?: string;
   transport?: 'sse' | 'websocket' | 'auto';
@@ -2112,11 +2493,51 @@ interface ProviderCapabilities {
    * URLs in user messages.
    */
   imageInToolResult?: boolean;
+  /**
+   * Provider executes web search server-side as a "server tool" — the model
+   * issues searches and receives results without a `tool_use` / `tool_result`
+   * round-trip on our wire. When set, the provider's `formatTools` recognizes
+   * a canonical tool named `web_search` and rewrites it to the provider's
+   * native server-tool shape (e.g. Anthropic's `web_search_20250305`),
+   * dropping the client-side `ToolDef` from the function-tools list so the
+   * model uses the server-side path instead.
+   *
+   * The client-side `web_search` `ToolDef` remains the cross-provider
+   * fallback for providers that don't set this flag.
+   */
+  nativeWebSearch?: {
+    /** Cap on server-side search invocations per turn. Provider-specific default when omitted. */maxUses?: number;
+  };
 }
 interface StreamCallbacks {
   onText: (delta: string) => void;
   onThinking?: (delta: string) => void;
   onOAuthRefresh?: (ctx: OAuthRefreshHookContext) => void | Promise<void>;
+  /**
+   * Fires mid-stream when a provider that executes tools server-side closes
+   * a server-tool-invocation content block (currently: Anthropic's
+   * `web_search_20250305`). Lets the loop surface the call into the
+   * transcript at the moment the model issued it — without waiting for the
+   * full assistant message to finalize. Shape is intentionally generic so
+   * future server tools (web_fetch, code_execution) reuse the same wire.
+   */
+  onServerToolUse?: (block: {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+  }) => void;
+  /**
+   * Pairs with {@link onServerToolUse} — fires when the provider closes the
+   * matching server-tool-result block (e.g. Anthropic's
+   * `web_search_tool_result`). `content` is the raw block payload
+   * (either an error object or an array of result entries); consumers
+   * format it for display.
+   */
+  onServerToolResult?: (block: {
+    toolUseId: string;
+    toolName: string;
+    content: unknown;
+  }) => void;
 }
 interface TurnResult {
   /** Full assistant turn as a SessionMessage */
@@ -2129,6 +2550,19 @@ interface TurnResult {
   done: boolean;
   usage: TurnUsage;
 }
+/**
+ * Payload for {@link Provider.countTokens} — the input half of a request whose
+ * token footprint we want measured WITHOUT running inference. Mirrors the
+ * subset of {@link StreamOptions} that contributes to input tokens.
+ */
+interface TokenCountPayload {
+  model: string;
+  /** System prompt as passed to `stream` (provider re-renders for the wire). */
+  system: string;
+  /** Wire-formatted tool specs (already through `provider.formatTools`). */
+  tools: unknown[];
+  messages: SessionMessage[];
+}
 interface StreamOptions {
   model: string;
   system: string;
@@ -2139,6 +2573,13 @@ interface StreamOptions {
   thinking?: ThinkingLevel;
   /** Exact thinking token budget — overrides the level-based default when set */
   thinkingBudget?: number;
+  /**
+   * Enabled model-specific options (the `id`s of {@link ModelInfo.options} the
+   * user toggled on), e.g. `{ fast: true }` for Anthropic's fast mode. Each
+   * provider interprets the keys it recognizes and ignores the rest; an option
+   * the active model doesn't declare is a silent no-op.
+   */
+  modelOptions?: Record<string, boolean>;
   /** Force tool selection behavior */
   toolChoice?: {
     type: 'auto' | 'required' | 'tool';
@@ -2188,6 +2629,18 @@ interface Provider {
    * route it to one of the typed error classes.
    */
   classifyError?: (err: unknown) => ClassifiedError | null;
+  /**
+   * Exact input-token count for a payload, WITHOUT running inference — backs
+   * the context-usage breakdown's exact mode. Implemented by providers with a
+   * free server-side count endpoint (Anthropic `messages.countTokens`, OpenAI
+   * `responses.input_tokens.count`).
+   *
+   * Returns the token count, or `null` when counting is unavailable/unreachable
+   * under the active auth (e.g. an OAuth backend that doesn't expose the
+   * endpoint) — callers fall back to the heuristic in that case. Absent on
+   * providers with no count endpoint (Cerebras, OpenRouter).
+   */
+  countTokens?: (payload: TokenCountPayload, signal?: AbortSignal) => Promise<number | null>;
 }
 //#endregion
 //#region src/session/messages.d.ts
@@ -3393,6 +3846,37 @@ interface AgentHooks {
     delta: string;
     thinking: string;
   }) => void;
+  /**
+   * Fires mid-stream when a provider that executes a tool server-side
+   * (currently: Anthropic's `web_search_20250305`) closes the
+   * server-tool-invocation content block. Symmetric with `tool:before` for
+   * function tools — surface the call into the transcript at the moment the
+   * model issued it, without waiting for the assistant message to finalize.
+   *
+   * Shape is intentionally generic so future server tools reuse the same
+   * hook. `id` is the block's tool-use id (echoed back to the provider on
+   * follow-up turns); pair with `stream:server_tool_result` via that id.
+   *
+   * Observational — handlers cannot block or substitute, since the call
+   * has already executed server-side by the time we see it.
+   */
+  'stream:server_tool_use': (ctx: StreamHookContext & {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+  }) => void;
+  /**
+   * Pairs with {@link AgentHooks['stream:server_tool_use']} — fires when the
+   * provider closes the matching server-tool-result block. `content` is the
+   * raw block payload (either an error object or an array of result entries
+   * carrying `encrypted_content` / `encrypted_index`); consumers format it
+   * for display.
+   */
+  'stream:server_tool_result': (ctx: StreamHookContext & {
+    toolUseId: string;
+    toolName: string;
+    content: unknown;
+  }) => void;
   /**
    * Fires when the provider's stream rejects BEFORE `stream:end` — provider
    * errors, network blips, malformed `tools` payloads (400 invalid_request_error).
@@ -3725,6 +4209,22 @@ interface AgentHooks {
     childId: string;
     depth: number;
   }) => void;
+  /** Bubbled `stream:server_tool_use` from a subagent. See {@link AgentHooks['stream:server_tool_use']}. */
+  'child:stream:server_tool_use': (ctx: StreamHookContext & {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    childId: string;
+    depth: number;
+  }) => void;
+  /** Bubbled `stream:server_tool_result` from a subagent. See {@link AgentHooks['stream:server_tool_result']}. */
+  'child:stream:server_tool_result': (ctx: StreamHookContext & {
+    toolUseId: string;
+    toolName: string;
+    content: unknown;
+    childId: string;
+    depth: number;
+  }) => void;
   /** Bubbled `stream:error` from a subagent's turn. See {@link AgentHooks['stream:error']}. */
   'child:stream:error': (ctx: StreamHookContext & {
     err: unknown;
@@ -4440,6 +4940,26 @@ interface Agent {
    * model / capability defaults, construct a new provider.
    */
   readonly meta: Readonly<Record<string, unknown>>;
+  /**
+   * Categorized context-window usage — system prompt, rules, skills, MCP
+   * tools/instructions, subagent defs, tool definitions, conversation, deferred
+   * buckets, autocompact buffer, and free space. Computed on demand (the host
+   * opens a panel / popover). Available even before the first run: when no run
+   * snapshot exists yet it assembles a skills-only pre-run view (no MCP connect),
+   * so it never returns `null` for a live agent — only after `destroy()`.
+   *
+   * Per-category counts are heuristic estimates reconciled so the live
+   * categories sum to the real last-turn total; when the provider exposes
+   * {@link Provider.countTokens} (Anthropic, OpenAI), the system/tools buckets
+   * use exact counts and drop their `estimated` flag. One network round-trip
+   * on the exact path; the host decides when to call it.
+   *
+   * The host supplies `effectiveWindow` (the model's `rawWindow -
+   * outputReserve`, resolved via the chat model registry which the agent core
+   * deliberately doesn't depend on). When omitted, free-space / fraction are
+   * computed against `used` only (bar still renders, just without headroom).
+   */
+  getContextBreakdown: (opts?: ContextBreakdownOptions) => Promise<ContextBreakdown | null>;
   /**
    * TC39 explicit-resource-management `await using` sink — alias for
    * {@link Agent.destroy}. Lets hosts write:
@@ -4474,5 +4994,5 @@ declare function createAgent({
   clock: agentClock
 }: AgentOptions): Agent;
 //#endregion
-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-CkJp_ZOR.d.ts.map
+export { autoDetectAndConvert as $, McpToolSchema as $t, SkillSource as A, ClassifiedError as An, openaiCompat as At, createRemoteStore as B, ContextItem as Bn, anthropic as Bt, getReadState as C, AgentAbortedError as Cn, OpenRouterParams as Ct, SkillConfig as D, AgentToolNotAllowedError as Dn, OpenAICompatParams as Dt, resolveReadStateMap as E, AgentProviderError as En, OpenAICompatHttpError as Et, SessionRun as F, ContextBreakdown as Fn, CursorParams as Ft, EnsureToolResultPairingOptions as G, AgentStats as Gt, FileMapAdapter as H, ContextSnapshot as Hn, AgentBehavior as Ht, SessionStore as I, ContextBreakdownOptions as In, cursor as It, PairingRepairMode as J, DEFAULT_AGENT_CLOCK as Jt, ORPHANED_TOOL_RESULT_MARKER as K, ChildRunStats as Kt, createSession as L, ContextCategory as Ln, CerebrasParams as Lt, CreateSessionOptions as M, errorMessage as Mn, openai as Mt, Session as N, matchesContextExceeded as Nn, LocalParams as Nt, SkillDiagnostic as O, AgentToolPairingError as On, classifyOpenAICompatError as Ot, SessionData as P, toTypedError as Pn, local as Pt, TurnInterruptionState as Q, McpToolHookContext as Qt, loadSession as R, ContextCategoryId as Rn, cerebras as Rt, ReadStateMap as S, toolResultToText as Sn, sanitizeToolSpecs as St, readStateKey as T, AgentContextExceededError as Tn, OpenAICompatAuthHeader as Tt, FileMapStoreOptions as U, ContextUsageSplit as Un, AgentClock as Ut, createMemoryStore as V, ContextMcpGroup as Vn, applyAnthropicCacheBreakpoints as Vt, createFileMapStore as W, buildContextBreakdown as Wn, AgentRunOptions as Wt, TOOL_USE_INTERRUPTED_MARKER as X, DedupToolConfig as Xt, SYNTHETIC_TOOL_RESULT_PLACEHOLDER as Y, DedupHasher as Yt, ToWireMessagesOptions as Z, McpServerConfig as Zt, resultToString as _, ToolResultImageContent as _n, TurnResult as _t, createAgent as a, RetryConfig as an, fromOpenAI as at, ToolMap as b, TurnUsage as bn, SchemaSanitizeResult as bt, DeactivationReason as c, SessionEndStatus as cn, toWireMessages as ct, createSkillActivationState as d, SessionTurn as dn, StreamCallbacks as dt, OAuthRefreshHookContext as en, detectTurnInterruption as et, ConnectMcpServersOptions as f, SpawnHookContext as fn, StreamOptions as ft, normalizeMcpServers as g, ToolResultContent as gn, ToolSpec as gt, normalizeMcpBlocks as h, ToolHookContext as hn, ToolResult as ht, AgentOptions as i, PromptTextPart as in, fromAnthropic as it, SkillsConfig as j, ClassifiedErrorKind as jn, OpenAIParams as jt, SkillResource as k, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as kn, mapOAIFinishReason as kt, SkillActivationState as l, SessionHookContext as ln, Provider as lt, connectMcpServers as m, ThinkingLevel as mn, ToolCall as mt, AgentHookMap as n, PromptImagePart as nn, ensureToolResultPairing as nt, ActivationVia as o, RunHookMap as on, toAnthropic as ot, McpConnection as p, StreamHookContext as pn, TokenCountPayload as pt, PairingRepair as q, CompactFunction as qt, AgentHooks as r, PromptPart as rn, filterUnresolvedToolUses as rt, ActiveSkill as s, SessionContentBlock as sn, toOpenAI as st, Agent as t, PromptDocumentPart as tn, ensureEndsWithUserMessage as tt, SkillActivationStateOptions as u, SessionMessage as un, ProviderCapabilities as ut, ToolContext as v, ToolResultTextContent as vn, SchemaSanitizeOptions as vt, hashContent as w, AgentBudgetExceededError as wn, openrouter as wt, ReadStateEntry as x, toolOutputByteLength as xn, sanitizeToolSchema as xt, ToolDef as y, TurnFinishReason as yn, SchemaSanitizeProfile as yt, RemoteStoreOptions as z, ContextExactCounts as zn, AnthropicParams as zt };
+//# sourceMappingURL=agent-BNS2nx_T.d.ts.map