zidane 5.13.26 → 5.14.0

package/dist/{agent-DQIL5BFk.d.ts → agent-BAgOgS37.d.ts}

@@ -1,5 +1,7 @@
 import { c as ExecutionContext, h as TaskExitInfo, l as ExecutionHandle } from "./types-Bs2oY7Ux.js";
+import { c as ClassifiedError } from "./errors-CkTvg97v.js";
 import { Hookable } from "hookable";
+import { Message } from "@earendil-works/pi-ai";
 import { OAuthCredentials } from "@earendil-works/pi-ai/oauth";
 import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -226,207 +228,6 @@ interface ContextSnapshot {
  */
 declare function buildContextBreakdown(snapshot: ContextSnapshot): ContextBreakdown;
 //#endregion
-//#region src/errors.d.ts
-/**
- * Typed error classes for agent runs.
- *
- * Providers classify native errors into one of these so downstream consumers
- * can react without string-sniffing messages.
- *
- * Provider authors: implement `Provider.classifyError` to map native errors
- * (SDK exceptions, HTTP responses) to a `ClassifiedError`. The loop wraps
- * unclassified errors in `AgentProviderError` automatically.
- */
-/** Kind of classified provider error */
-type ClassifiedErrorKind = 'context_exceeded' | 'provider_error' | 'aborted' | 'tool_pairing_corruption';
-/** Structured classification returned by `Provider.classifyError` */
-interface ClassifiedError {
-  kind: ClassifiedErrorKind;
-  /** Upstream error code as surfaced by the provider (e.g. `context_length_exceeded`). Optional. */
-  providerCode?: string;
-  /** Optional human-readable message override. Falls back to the underlying error's message. */
-  message?: string;
-  /**
-   * Hint that the error is transient and a retry with backoff is reasonable
-   * (e.g. 429, 5xx, truncated stream). Omitted when the provider can't decide;
-   * callers should default to "do not retry" when absent to avoid hammering
-   * terminal failures (auth, invalid request).
-   */
-  retryable?: boolean;
-}
-interface TypedErrorOptions {
-  /** Provider name, always set (e.g. `anthropic`, `openrouter`) */
-  provider: string;
-  /** Optional upstream error code */
-  providerCode?: string;
-  /** Original error from the provider SDK/HTTP layer */
-  cause?: unknown;
-  /** See {@link ClassifiedError.retryable}. */
-  retryable?: boolean;
-}
-/**
- * Thrown when the model or provider signals that the context window was exceeded.
- * Downstream consumers should catch this, prune history, and retry.
- */
-declare class AgentContextExceededError extends Error {
-  readonly code: "context_exceeded";
-  readonly provider: string;
-  readonly providerCode?: string;
-  constructor(message: string, options: TypedErrorOptions);
-}
-/**
- * Thrown when the provider returns a non-context error (auth, rate limit, server error, etc.).
- * Catch-all for unclassified provider failures.
- */
-declare class AgentProviderError extends Error {
-  readonly code: "provider_error";
-  readonly provider: string;
-  readonly providerCode?: string;
-  /**
-   * Whether a retry with backoff is likely to succeed. See
-   * {@link ClassifiedError.retryable}. Absent when the provider did not
-   * classify the error — callers should treat absent as "don't retry".
-   */
-  readonly retryable?: boolean;
-  constructor(message: string, options: TypedErrorOptions);
-}
-/**
- * Thrown when a run is aborted by the consumer via `agent.abort()` or an external `AbortSignal`.
- */
-declare class AgentAbortedError extends Error {
-  readonly code: "aborted";
-  constructor(message?: string, options?: {
-    cause?: unknown;
-  });
-}
-/**
- * Thrown by the loop when a run's cumulative cost, token consumption, or
- * wall-clock elapsed time crosses a ceiling configured on
- * {@link AgentBehavior.maxCostUsd} / {@link AgentBehavior.maxTotalTokens} /
- * {@link AgentBehavior.maxWallMs}. Acts as a programmable circuit
- * breaker for unattended runs — without this, the only built-in safety net
- * is {@link AgentBehavior.maxTurns}, which doesn't bound a single very
- * expensive turn (large context, deep reasoning).
- *
- * The breach is checked **after** each turn completes (post-`turn:after`),
- * so the run may exceed the budget by one turn's worth of usage before
- * tripping. Callers wanting a tighter pre-turn estimate should layer their
- * own check on top of the `usage` hook.
- *
- * The harness treats this the same way as {@link AgentAbortedError}: the
- * session run is finalized as `'aborted'`, persisted stats reflect what
- * was actually consumed, and the parent agent re-throws so a caller's
- * `try`/`catch` can branch on `err instanceof AgentBudgetExceededError`
- * without string-sniffing.
- */
-declare class AgentBudgetExceededError extends Error {
-  readonly code: "budget_exceeded";
-  /** Which ceiling tripped. `'cost'` → `maxCostUsd`, `'tokens'` → `maxTotalTokens`, `'wallClock'` → `maxWallMs`. */
-  readonly limit: 'cost' | 'tokens' | 'wallClock';
-  /** The configured cap (USD for `cost`, total tokens for `tokens`, ms for `wallClock`). */
-  readonly limitValue: number;
-  /** Actual consumed value at the moment the cap was crossed (same units as `limitValue`). */
-  readonly actualValue: number;
-  constructor(options: {
-    limit: 'cost' | 'tokens' | 'wallClock';
-    limitValue: number;
-    actualValue: number;
-    cause?: unknown;
-  });
-}
-/**
- * Thrown by the pre-send pairing repair when {@link AgentBehavior.strictToolPairing}
- * is `true` and {@link ensureToolResultPairing} would otherwise patch over
- * corruption. Strict mode opts into fail-fast for training-data collectors and
- * any consumer that prefers to bail out rather than ship a transcript carrying
- * a {@link SYNTHETIC_TOOL_RESULT_PLACEHOLDER}.
- *
- * The `repairs` field carries every repair the loop would have made — useful
- * for postmortems and for surfacing exactly which transcripts were rejected.
- *
- * Note: callers consuming the chat layer (TUI/SDK presets) typically leave
- * `strictToolPairing` off so user-facing sessions auto-heal instead of
- * crashing.
- */
-declare class AgentToolPairingError extends Error {
-  readonly code: "tool_pairing_corruption";
-  /** Provider whose wire format the corruption would have hit. */
-  readonly provider?: string;
-  /** Upstream error code when the corruption was detected from a 400 response. */
-  readonly providerCode?: string;
-  /**
-   * Repairs the harness would have performed had strict mode been off.
-   * Preserves the full diagnostic so consumers can route to telemetry,
-   * `/rewind` flows, or training-data quarantine without re-walking the
-   * transcript.
-   */
-  readonly repairs: ReadonlyArray<{
-    mode: string;
-    callId?: string;
-    messageIndex: number;
-  }>;
-  constructor(options: {
-    message: string;
-    provider?: string;
-    providerCode?: string;
-    repairs: ReadonlyArray<{
-      mode: string;
-      callId?: string;
-      messageIndex: number;
-    }>;
-    cause?: unknown;
-  });
-}
-/**
- * Thrown (well — constructed; attach via the `tool:gate` block signal) when the
- * union of `allowed-tools` across active skills does not permit a tool call.
- *
- * Produced by the allowed-tools middleware registered on `tool:gate` /
- * `mcp:tool:gate`. The gate's `block = true` + `reason` carry the same message
- * so consumers that don't look at this typed error still get a useful string.
- */
-declare class AgentToolNotAllowedError extends Error {
-  readonly code: "tool_not_allowed";
-  /** Canonical tool name the agent tried to call. */
-  readonly toolName: string;
-  /** Aliased / wire name the LLM saw. */
-  readonly displayName: string;
-  /** Flattened union of `allowedTools` patterns across active skills. */
-  readonly allowedUnion: readonly string[];
-  /** Names of the skills currently active when the block fired. */
-  readonly activeSkills: readonly string[];
-  constructor(options: {
-    toolName: string;
-    displayName: string;
-    allowedUnion: readonly string[];
-    activeSkills: readonly string[];
-    cause?: unknown;
-  });
-}
-/**
- * Regex patterns matching common "context window exceeded" messages across providers.
- *
- * Use {@link matchesContextExceeded} to test a free-form error message against them.
- * Provider authors can also compose these into their own `classifyError` fallbacks.
- */
-declare const CONTEXT_EXCEEDED_MESSAGE_PATTERNS: readonly RegExp[];
-/**
- * Return true when `message` matches any of the known "context window exceeded"
- * phrasings. Safe for `''` / non-strings (returns false).
- */
-declare function matchesContextExceeded(message: unknown): boolean;
-/**
- * Extract a printable message from an unknown thrown value.
- *
- * Standardizes the `err instanceof Error ? err.message : String(err)` idiom
- * that every `catch (err)` block was reaching for.
- */
-declare function errorMessage(err: unknown): string;
-/**
- * Convert a `ClassifiedError` + underlying cause into the matching typed error instance.
- */
-declare function toTypedError(classification: ClassifiedError, provider: string, cause: unknown): AgentContextExceededError | AgentProviderError | AgentAbortedError | AgentToolPairingError;
-//#endregion
 //#region src/types.d.ts
 /**
  * Thinking / extended-reasoning configuration.
@@ -701,6 +502,11 @@ interface RetryConfig {
  * `dedupTools` for the full contract.
  */
 type DedupHasher = (input: Record<string, unknown>) => string | undefined;
+type ProgressNudgeKind = 'readOnlyTurns' | 'failedMutations' | 'noopMutations' | 'validationRejects' | 'toolErrors';
+type ProgressNudgeMessage = string | ((ctx: {
+  kind: ProgressNudgeKind;
+  count: number;
+}) => string);
 /**
  * Per-tool dedup configuration. Two equivalent forms:
  *
@@ -1061,6 +867,15 @@ interface AgentBehavior {
    * historic behavior).
    */
   maxTurnsWarning?: number;
+  /**
+   * Optional custom message for {@link maxTurnsWarning}. When unset, the loop
+   * uses its built-in wrap-up warning. String form is sent verbatim; function
+   * form receives the remaining/maximum turn counts and can tailor the nudge.
+   */
+  maxTurnsWarningMessage?: string | ((ctx: {
+    remaining: number;
+    maxTurns: number;
+  }) => string);
   /**
    * Run-level cost ceiling, expressed in USD. After each turn, the sum of
    * `TurnUsage.cost` across the run is compared against this value; if the
@@ -1231,6 +1046,16 @@ interface AgentBehavior {
   maxTokens?: number;
   /** Thinking token budget — overrides the level-based default when set */
   thinkingBudget?: number;
+  /**
+   * When a provider streams more thinking text than expected, optionally nudge
+   * the next continuing turn toward concrete progress. This is advisory and
+   * non-interrupting: same-turn tool calls are still allowed to finish.
+   */
+  thinkingOverrunPolicy?: 'off' | 'steer-next-turn' | {
+    mode?: 'off' | 'steer-next-turn';
+    thresholdTokens?: number;
+    message?: string;
+  };
   /**
    * Default model-specific options applied to every run, keyed by option id
    * (e.g. `{ fast: true }`). A per-run {@link AgentRunOptions.modelOptions}
@@ -1295,6 +1120,15 @@ interface AgentBehavior {
    * list — see `src/chat/agents.ts`.
    */
   toolOutputBudgetExcludeTools?: readonly string[];
+  /**
+   * Default `read_file` slice limits for calls that omit `limit` / `maxBytes`.
+   * Explicit tool-call arguments still win. SDK default remains the tool's
+   * built-in defaults; hosts can tighten these for context-sensitive profiles.
+   */
+  readFileDefaults?: {
+    limit?: number;
+    maxBytes?: number;
+  };
   /**
    * Deduplicate identical re-reads of the same file in `read_file`. When the
    * model re-reads a file with the same slice and the bytes haven't changed
@@ -1331,6 +1165,54 @@ interface AgentBehavior {
     factor: number;
     floor: number;
   } | ((runTurn: number, baseBudget: number) => number);
+  /**
+   * Policy for full-file writes to paths that already exist. The guard is a
+   * `tool:gate` refusal that points the model toward `read_file` + `edit` /
+   * `multi_edit`.
+   */
+  writeFileExistingPolicy?: 'allow' | 'block-with-edit-recipe' | {
+    mode?: 'allow' | 'block-with-edit-recipe';
+    allowPaths?: readonly string[];
+    denyPaths?: readonly string[];
+  };
+  /**
+   * Steer when a model emits a textual tool call instead of a provider-native
+   * tool call. Execution of parsed text calls is intentionally not part of this
+   * public contract.
+   */
+  textToolCallRescue?: false | {
+    mode?: 'steer';
+  };
+  /**
+   * Steer when the model calls a tool name that is not registered. The unknown
+   * tool result remains an error; this only queues a bounded follow-up nudge
+   * with closest advertised tool-name suggestions.
+   */
+  unknownToolRecovery?: false | {
+    mode?: 'steer';
+    maxSuggestions?: number;
+    maxNudges?: number;
+    message?: string | ((ctx: {
+      called: string;
+      suggestions: readonly string[];
+    }) => string);
+  };
+  /**
+   * Advisory progress nudges for broad stalls that exact repeat guards do not
+   * cover: several read-only turns, failed/no-op mutations, validation rejects,
+   * or tool errors. All nudges are non-interrupting and off by default.
+   */
+  progressNudges?: false | {
+    mode?: 'steer';
+    readOnlyTurns?: number | false;
+    failedMutations?: number | false;
+    noopMutations?: number | false;
+    validationRejects?: number | false;
+    toolErrors?: number | false;
+    readOnlyTools?: readonly string[];
+    maxNudges?: number;
+    messages?: Partial<Record<ProgressNudgeKind, ProgressNudgeMessage>>;
+  };
   /**
    * Per-tool soft call budget for this run. Keyed by **canonical** tool name.
    * On the first call after the run-cumulative dispatched count for that tool
@@ -2913,6 +2795,65 @@ interface AnthropicParams extends OAuthParams {
    */
   extraHeaders?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
 }
+/**
+ * Build the `anthropic-beta` header value — OAuth defaults plus caller-supplied
+ * extras, de-duped while preserving order. Returns `undefined` when no betas
+ * apply (non-OAuth, no extras).
+ */
+declare function resolveAnthropicBetas(isOAuth: boolean, extraBetas?: readonly string[]): string | undefined;
+/**
+ * Description of the Anthropic-side thinking configuration derived from a
+ * ThinkingLevel. `null` means no thinking-related field should be set on the
+ * request.
+ *
+ * Two shapes:
+ * - `adaptive` — `thinking.type='adaptive'`. The model self-budgets per turn.
+ *   When `effort` is set, also emits `output_config.effort` to hint at the
+ *   level of reasoning the caller wants. This is the post-Claude-4.6 default
+ *   for level-based control and avoids the `thinking.type='enabled'`
+ *   deprecation warning. When `maxTokensCap` is set, the request builder
+ *   reduces `max_tokens` to `min(max_tokens, maxTokensCap)` — adaptive thinks
+ *   and replies inside one envelope, so capping the envelope soft-bounds the
+ *   thinking too.
+ * - `enabled` — explicit-budget path: `thinking.type='enabled'` with an
+ *   explicit `budget_tokens`. `maxTokensBump` is added to the request's
+ *   `max_tokens` so the budget sits on top of the response cap. The only
+ *   way to pin a precise token budget; Anthropic emits a deprecation
+ *   warning for this shape on opus 4.6+, so we only route here when the
+ *   caller explicitly sets `behavior.thinkingBudget`.
+ *
+ * In both shapes Anthropic requires `temperature` to be `1`.
+ */
+type AnthropicThinkingPlan = {
+  kind: 'enabled';
+  budgetTokens: number;
+  maxTokensBump: number;
+} | {
+  kind: 'adaptive';
+  effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  maxTokensCap?: number;
+};
+/**
+ * Decide how to translate a `ThinkingLevel` into Anthropic's request shape.
+ * Pure / synchronous — exported so tests can assert routing without standing
+ * up the SDK.
+ *
+ * Routing rules:
+ * - `'off'` → `null` (no thinking field, no effort hint).
+ * - `'adaptive'` → adaptive thinking with no effort hint (model decides
+ *   everything). When `customBudget` is set, it is carried as `maxTokensCap`
+ *   so the request builder caps `max_tokens` accordingly — adaptive has no
+ *   native budget knob, but capping the response envelope soft-bounds the
+ *   thinking that lives inside it.
+ * - Budgeted levels → adaptive thinking with an `effort` hint, unless
+ *   `customBudget` is provided.
+ * - Any level + `customBudget` → explicit-budget `enabled` path. The caller
+ *   has opted into precise budget control and accepts the Anthropic
+ *   deprecation warning that comes with it on opus 4.6+. `'adaptive'` is the
+ *   sole exception: it never falls back to enabled, since adaptive is the
+ *   current Anthropic API surface for self-budgeted thinking.
+ */
+declare function planAnthropicThinking(level: ThinkingLevel, customBudget?: number): AnthropicThinkingPlan | null;
 /**
  * Mutate an Anthropic request in place to add cache breakpoints on the three
  * stable prefixes:
@@ -2938,6 +2879,26 @@ interface AnthropicParams extends OAuthParams {
  *   breakpoint placement.
  */
 declare function applyAnthropicCacheBreakpoints(params: Anthropic.MessageCreateParamsStreaming, originalSystem?: string): void;
+/**
+ * Classify an Anthropic SDK / HTTP error for typed-error wrapping.
+ *
+ * - `prompt is too long` (400 invalid_request_error) → `context_exceeded`.
+ * - `'tool_use' ids were found without 'tool_result' blocks` /
+ *   `'tool_result must be preceded by a tool_call'` (400) →
+ *   `tool_pairing_corruption`. The local repair pass should have caught
+ *   this — the typed error tells consumers their pre-send pipeline is
+ *   shipping orphaned blocks somehow (custom `context:transform` hook,
+ *   bypassed loop, mid-stream session edit) so they can patch the root
+ *   cause instead of chasing 400s.
+ * - Any other Anthropic `APIError`-shaped value → `provider_error` with the
+ *   native status/type code.
+ * - Unknown errors → `null` (loop wraps in `AgentProviderError` generically).
+ *
+ * Anthropic's wire error shape is `{ type: 'error', error: { type, message } }` — the
+ * SDK stores the parsed body on `err.error`. We walk both levels so callers see the
+ * most specific `providerCode` we can find.
+ */
+declare function classifyAnthropicError(err: unknown): ClassifiedError | null;
 declare function anthropic(anthropicParams?: AnthropicParams): Provider;
 //#endregion
 //#region src/providers/arcee.d.ts
@@ -3156,9 +3117,207 @@ interface OpenAIParams extends OAuthParams {
    */
   extraHeaders?: Record<string, string>;
 }
+declare function toPiMessages(messages: SessionMessage[], modelId: string): Message[];
+/**
+ * Map pi-ai's `StopReason` to the zidane `TurnFinishReason` union — the same
+ * native-stop-reason fidelity anthropic's `mapStopReason` / openai-compat's
+ * `mapOAIFinishReason` provide. Notably `length` (max-token truncation) is no
+ * longer misreported as a clean `stop`. `hasToolCalls` is the fallback for
+ * messages whose stop reason is missing or doesn't carry the tool-call signal.
+ */
+declare function mapCodexStopReason(stopReason: string | undefined, hasToolCalls: boolean): TurnFinishReason;
+/**
+ * Classify an OpenAI Codex error. pi-ai surfaces errors either as thrown `Error`s
+ * (wrapping `event.error.errorMessage`) or via stream event types.
+ *
+ * Retryable hint is set when pi-ai's own retry budget is exhausted on a
+ * transient failure — pattern-matched against `message` since pi-ai strips
+ * structured fields on plain-Error throws. Set `behavior.retry.maxAttempts: 1`
+ * to disable the loop-level retry.
+ */
+declare function classifyOpenAIError(err: unknown): ClassifiedError | null;
 declare function openai(params?: OpenAIParams): Provider;
 //#endregion
 //#region src/providers/openai-compat.d.ts
+interface OAIMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content?: unknown;
+  tool_calls?: {
+    id: string;
+    type: 'function';
+    function: {
+      name: string;
+      arguments: string;
+    };
+  }[];
+  tool_call_id?: string;
+  /**
+   * OpenRouter normalized reasoning envelope. Echoed back unmodified on assistant
+   * messages so the gateway can resume an extended-reasoning chain on the
+   * upstream route. Ignored by hosts that don't speak the envelope.
+   */
+  reasoning_details?: unknown[];
+  /**
+   * Plain reasoning string echoed back on assistant messages for vLLM-style
+   * reasoning models (Arcee Trinity-Thinking, DeepSeek-R1). Arcee's API accepts
+   * `reasoning_content`; some self-hosted vLLM versions read `reasoning`.
+   */
+  reasoning_content?: string;
+  reasoning?: string;
+}
+interface OAITool {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+declare const TOOL_RESULTS_TAG = "__zidane_tool_results__";
+declare const ASSISTANT_TOOL_CALLS_TAG = "__zidane_assistant_tc__";
+declare class OpenAICompatStreamError extends Error {
+  constructor(message: string);
+}
+interface OpenAICompatUsage {
+  input: number;
+  output: number;
+  cost?: number;
+  cacheRead?: number;
+  cacheCreation?: number;
+}
+declare function consumeSSE(response: Response, callbacks: StreamCallbacks, signal?: AbortSignal): Promise<{
+  text: string;
+  thinking: string;
+  toolCalls: {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+  }[];
+  finishReason: string;
+  usage: OpenAICompatUsage;
+  reasoningDetails: Record<string, unknown>[];
+}>;
+/**
+ * Options that influence OpenAI-compat message shaping.
+ *
+ * `imageInToolResult` defaults to `false`: the loop routes images via a companion
+ * user message emitted immediately after the `tool` message. Providers with
+ * genuine multi-part tool support can set it to `true` to emit a single
+ * multi-part `tool` message instead.
+ */
+interface ToOAIOptions {
+  imageInToolResult?: boolean;
+  /**
+   * Route accepts audio input (`input_audio` content parts). When false,
+   * audio blocks throw rather than silently dropping bytes a non-audio model
+   * would 400 on.
+   */
+  audio?: boolean;
+  /**
+   * Route accepts video input (`video_url` content parts, base64 data-URL).
+   * Currently Gemini-on-OpenRouter. When false, video blocks throw.
+   */
+  video?: boolean;
+  /**
+   * Route accepts native document/PDF input (OpenAI `file` content part with
+   * base64 `file_data`). When false (default), base64 documents degrade to the
+   * `[document omitted: …]` text marker. Text-encoded documents are always
+   * inlined upstream regardless of this flag.
+   */
+  documents?: boolean;
+  /**
+   * Host accepts provider-bound reasoning state echoed back on assistant
+   * messages. The exact wire shape is selected by `reasoningMode`: OpenRouter's
+   * structured `reasoning_details[]` envelope, or vLLM/Arcee's plain
+   * `reasoning_content` / `reasoning` string. When `false` (default), stored reasoning blocks
+   * are silently dropped to avoid 400s on hosts that strict-validate the schema.
+   */
+  supportsReasoning?: boolean;
+  /**
+   * Reasoning round-trip shape. `'openrouter'` echoes structured
+   * `reasoning_details[]`; `'reasoning_content'` echoes the plain reasoning
+   * string (vLLM/Arcee). Only consulted when `supportsReasoning` is `true`.
+   * Default: `'openrouter'`.
+   */
+  reasoningMode?: 'openrouter' | 'reasoning_content';
+  /**
+   * Wire field used to echo plain reasoning in `'reasoning_content'` mode.
+   * Default: `'reasoning'` (broadest vLLM compatibility).
+   */
+  reasoningContentField?: 'reasoning_content' | 'reasoning';
+  /**
+   * Normalize `content: null` → `''` on assistant tool-call turns. Default off.
+   */
+  normalizeNullContent?: boolean;
+  /**
+   * Active model id. Used to gate `provider_reasoning` blocks — reasoning state
+   * is bound to the route that produced it, so a model switch invalidates the
+   * embedded signatures.
+   */
+  model?: string;
+}
+declare function toOAIMessages(system: string, messages: SessionMessage[], options?: ToOAIOptions): OAIMessage[];
+/**
+ * Add `cache_control: { type: 'ephemeral' }` breakpoints to the system message's
+ * last text part and the last message's final content part.
+ *
+ * Mutates `messages` in place. Converts plain-string content into a single-element
+ * content array so the cache marker can attach — this shape is accepted verbatim by
+ * OpenRouter's Anthropic and Gemini routes and ignored by routes with automatic
+ * caching (OpenAI, DeepSeek, Grok, Groq, Moonshot).
+ *
+ * Skip conditions (safe no-ops):
+ * - Empty messages array.
+ * - Assistant messages with no text (tool-call-only) — attaching a cache marker to a
+ *   `tool_calls` block has no defined semantics, so we skip and let the prior
+ *   system/tools breakpoints carry caching.
+ *
+ * System-prompt boundary handling: when `originalSystem` (the un-rendered
+ * system text passed to {@link toOAIMessages}) contains
+ * {@link SYSTEM_PROMPT_BOUNDARY}, the leading system message is rewritten as
+ * a two-part array — `cache_control` lands on the static prefix only, so
+ * per-turn churn in the dynamic suffix doesn't invalidate the cached
+ * doctrine above. `originalSystem` defaults to `undefined` for back-compat;
+ * omit it (or pass a marker-free string) for the single-block historic
+ * behavior.
+ */
+declare function applyOAICacheBreakpoints(messages: OAIMessage[], originalSystem?: string): void;
+/**
+ * Return a copy of `tools` with `cache_control` on the last entry.
+ *
+ * OpenRouter accepts the marker alongside the standard `type` + `function` fields
+ * and forwards it when routing to Anthropic/Gemini. Leaves the non-cached tools
+ * unchanged so the caller's reference is not mutated.
+ */
+declare function applyOAIToolCacheBreakpoint(tools: OAITool[]): OAITool[];
+declare function formatTools(tools: ToolSpec[]): OAITool[];
+declare function userMessage(content: string): SessionMessage;
+/**
+ * Build a user `SessionMessage` from multimodal prompt parts.
+ *
+ * Passes every kind (text/image/audio/video/document) through as a canonical
+ * block; the actual wire emission, capability gating, and unsupported-media
+ * throwing all happen later in {@link toOAIMessages}. Implementing this (rather
+ * than letting the agent fall back to `defaultPromptMessage`) is what lets
+ * openai-compat routes accept base64 documents/PDFs at all — the default
+ * builder throws on base64 documents.
+ */
+declare function openAICompatPromptMessage(parts: PromptPart[]): SessionMessage;
+declare function assistantMessage(content: string): SessionMessage;
+declare function toolResultsMessage(results: ToolResult[]): SessionMessage;
+declare function buildAssistantContent(text: string, toolCalls: {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}[], thinking?: string, reasoning?: {
+  details: unknown[];
+  producer: 'openrouter';
+  model?: string;
+} | {
+  reasoningText: string;
+  producer: 'vllm';
+  model?: string;
+}): SessionMessage;
 /**
  * HTTP error thrown when an OpenAI-compatible endpoint returns a non-OK response.
  *
@@ -3391,6 +3550,7 @@ interface OpenRouterParams {
    */
   pdfEngine?: 'native' | 'pdf-text' | 'mistral-ocr';
 }
+declare function normalizeOpenRouterModelId(modelId: string): string;
 /**
  * OpenRouter provider.
  *
@@ -5444,11 +5604,10 @@ interface AgentHooks {
    */
   /**
    * Gate a tool call before it runs. Handlers share ONE mutable `ctx` and run
-   * sequentially in registration order (the order they were `hook()`-ed; the
-   * built-in guards — dedup, tool-budgets, repeat-guard — register at agent
-   * construction, so host handlers added later run after them). The framework
-   * reads the final state once all handlers (including async ones, which are
-   * awaited) have run.
+   * sequentially in registration order (the order they were `hook()`-ed). The
+   * framework reads the final state once all handlers (including async ones,
+   * which are awaited) have run. Built-in behavior gates install during run
+   * setup and self-defer when another gate already set `block` / `result`.
    *
    * Precedence across the resolved state:
    *   - `block` beats `result`: if any handler left `block === true`, the call
@@ -6751,5 +6910,5 @@ declare function createAgent({
   toolKill
 }: AgentOptions): Agent;
 //#endregion
-export { FileMapAdapter as $, ToolResultImageContent as $n, cerebras as $t, getReadState as A, PromptTextPart as An, TurnResult as At, SkillSource as B, SessionHookContext as Bn, OpenAICompatAuthHeader as Bt, wrapDiscoveredMcpTools as C, McpToolHookContext as Cn, ContextCategoryId as Cr, ProviderCapabilities as Ct, HydrateReadStateOptions as D, PromptDocumentPart as Dn, ContextSnapshot as Dr, ToolCall as Dt, ToolMap as E, PromptAudioPart as En, ContextMcpGroup as Er, TokenCountPayload as Et, resolveReadStateMap as F, ResolveContentRefBlock as Fn, SchemaSanitizeResult as Ft, SessionRun as G, ThinkingLevel as Gn, openaiCompat as Gt, CreateSessionOptions as H, SessionTurn as Hn, OpenAICompatParams as Ht, ShellInterpolationApproval as I, RetryConfig as In, sanitizeToolSchema as It, demoteStaleRunningStatus as J, ToolOutcome as Jn, LocalParams as Jt, SessionStore as K, ToolBatchExecutor as Kn, OpenAIParams as Kt, SkillConfig as L, RunHookMap as Ln, sanitizeToolSpecs as Lt, hydrateReadStateFromSession as M, RepeatGuardConfig as Mn, xai as Mt, hydrateReadStateFromSessionAsync as N, RepeatGuardToolMatcher as Nn, SchemaSanitizeOptions as Nt, ReadStateEntry as O, PromptImagePart as On, ContextUsageSplit as Or, ToolResult as Ot, readStateKey as P, ResolveContentRef as Pn, SchemaSanitizeProfile as Pt, createMemoryStore as Q, ToolResultDocumentRefContent as Qn, CerebrasParams as Qt, SkillDiagnostic as R, SessionContentBlock as Rn, OpenRouterParams as Rt, resultToString as S, McpServerConfig as Sn, ContextCategory as Sr, Provider as St, ToolDef as T, OAuthRefreshHookContext as Tn, ContextItem as Tr, StreamOptions as Tt, Session as U, SpawnHookContext as Un, classifyOpenAICompatError as Ut, SkillsConfig as V, SessionMessage as Vn, OpenAICompatHttpError as Vt, SessionData as W, StreamHookContext as Wn, mapOAIFinishReason as Wt, RemoteStoreOptions as X, ToolResultContent as Xn, CursorParams as Xt, loadSession as Y, ToolResultAudioContent as Yn, local as Yt, createRemoteStore as Z, ToolResultDocumentContent as Zn, cursor as Zt, attachStderrWarnPump as _, CompactHookContext as _n, errorMessage as _r, fromOpenAI as _t, McpConnector as a, AnthropicParams as an, toolOutputBudgetByteLength as ar, PairingRepairMode as at, normalizeMcpBlocks as b, DedupHasher as bn, ContextBreakdown as br, toOpenAI as bt, createAgent as c, AgentBehavior as cn, AgentAbortedError as cr, TOOL_USE_INTERRUPTED_MARKER as ct, DeactivationReason as d, AgentStats as dn, AgentProviderError as dr, autoDetectAndConvert as dt, BasetenParams as en, ToolResultImageRefContent as er, FileMapStoreOptions as et, SkillActivationState as f, AutoCompact as fn, AgentToolNotAllowedError as fr, detectTurnInterruption as ft, McpConnection as g, CompactFunction as gn, ClassifiedErrorKind as gr, fromAnthropic as gt, ConnectMcpServersOptions as h, CompactEndHookContext as hn, ClassifiedError as hr, filterUnresolvedToolUses as ht, AgentOptions as i, arcee as in, TurnUsage as ir, PairingRepair as it, hashContent as j, PromptVideoPart as jn, XaiParams as jt, ReadStateMap as k, PromptPart as kn, buildContextBreakdown as kr, ToolSpec as kt, ActivationVia as l, AgentClock as ln, AgentBudgetExceededError as lr, ToWireMessagesOptions as lt, createSkillActivationState as m, ChildRunStats as mn, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as mr, ensureToolResultPairing as mt, AgentHookMap as n, planBasetenReasoning as nn, ToolResultVideoContent as nr, EnsureToolResultPairingOptions as nt, McpToolMeta as o, anthropic as on, toolOutputByteLength as or, RemintResult as ot, SkillActivationStateOptions as p, AutoCompactConfig as pn, AgentToolPairingError as pr, ensureEndsWithUserMessage as pt, createSession as q, ToolHookContext as qn, openai as qt, AgentHooks as r, ArceeParams as rn, TurnFinishReason as rr, ORPHANED_TOOL_RESULT_MARKER as rt, McpToolWrap as s, applyAnthropicCacheBreakpoints as sn, toolResultToText as sr, SYNTHETIC_TOOL_RESULT_PLACEHOLDER as st, Agent as t, baseten as tn, ToolResultTextContent as tr, createFileMapStore as tt, ActiveSkill as u, AgentRunOptions as un, AgentContextExceededError as ur, TurnInterruptionState as ut, connectMcpServers as v, CompactStartHookContext as vn, matchesContextExceeded as vr, remintDuplicateToolCallIds as vt, ToolContext as w, McpToolSchema as wn, ContextExactCounts as wr, StreamCallbacks as wt, normalizeMcpServers as x, DedupToolConfig as xn, ContextBreakdownOptions as xr, toWireMessages as xt, deriveMcpToolMeta as y, DEFAULT_AGENT_CLOCK as yn, toTypedError as yr, toAnthropic as yt, SkillResource as z, SessionEndStatus as zn, openrouter as zt };
-//# sourceMappingURL=agent-DQIL5BFk.d.ts.map
+export { FileMapAdapter as $, PromptDocumentPart as $n, classifyOpenAICompatError as $t, getReadState as A, planAnthropicThinking as An, TurnUsage as Ar, TurnResult as At, SkillSource as B, CompactFunction as Bn, ContextMcpGroup as Br, openrouter as Bt, wrapDiscoveredMcpTools as C, arcee as Cn, ToolResultDocumentContent as Cr, ProviderCapabilities as Ct, HydrateReadStateOptions as D, anthropic as Dn, ToolResultTextContent as Dr, ToolCall as Dt, ToolMap as E, AnthropicThinkingPlan as En, ToolResultImageRefContent as Er, TokenCountPayload as Et, resolveReadStateMap as F, AgentStats as Fn, ContextBreakdownOptions as Fr, SchemaSanitizeResult as Ft, SessionRun as G, DedupToolConfig as Gn, OpenAICompatHttpError as Gt, CreateSessionOptions as H, CompactStartHookContext as Hn, ContextUsageSplit as Hr, OAIMessage as Ht, ShellInterpolationApproval as I, AutoCompact as In, ContextCategory as Ir, sanitizeToolSchema as It, demoteStaleRunningStatus as J, McpToolSchema as Jn, TOOL_RESULTS_TAG as Jt, SessionStore as K, McpServerConfig as Kn, OpenAICompatParams as Kt, SkillConfig as L, AutoCompactConfig as Ln, ContextCategoryId as Lr, sanitizeToolSpecs as Lt, hydrateReadStateFromSession as M, AgentBehavior as Mn, toolOutputByteLength as Mr, xai as Mt, hydrateReadStateFromSessionAsync as N, AgentClock as Nn, toolResultToText as Nr, SchemaSanitizeOptions as Nt, ReadStateEntry as O, applyAnthropicCacheBreakpoints as On, ToolResultVideoContent as Or, ToolResult as Ot, readStateKey as P, AgentRunOptions as Pn, ContextBreakdown as Pr, SchemaSanitizeProfile as Pt, createMemoryStore as Q, PromptAudioPart as Qn, buildAssistantContent as Qt, SkillDiagnostic as R, ChildRunStats as Rn, ContextExactCounts as Rr, OpenRouterParams as Rt, resultToString as S, ArceeParams as Sn, ToolResultContent as Sr, Provider as St, ToolDef as T, AnthropicParams as Tn, ToolResultImageContent as Tr, StreamOptions as Tt, Session as U, DEFAULT_AGENT_CLOCK as Un, buildContextBreakdown as Ur, OAITool as Ut, SkillsConfig as V, CompactHookContext as Vn, ContextSnapshot as Vr, ASSISTANT_TOOL_CALLS_TAG as Vt, SessionData as W, DedupHasher as Wn, OpenAICompatAuthHeader as Wt, RemoteStoreOptions as X, ProgressNudgeKind as Xn, applyOAIToolCacheBreakpoint as Xt, loadSession as Y, OAuthRefreshHookContext as Yn, applyOAICacheBreakpoints as Yt, createRemoteStore as Z, ProgressNudgeMessage as Zn, assistantMessage as Zt, attachStderrWarnPump as _, CerebrasParams as _n, ThinkingLevel as _r, fromOpenAI as _t, McpConnector as a, toOAIMessages as an, RepeatGuardToolMatcher as ar, PairingRepairMode as at, normalizeMcpBlocks as b, baseten as bn, ToolOutcome as br, toOpenAI as bt, createAgent as c, OpenAIParams as cn, RetryConfig as cr, TOOL_USE_INTERRUPTED_MARKER as ct, DeactivationReason as d, openai as dn, SessionEndStatus as dr, autoDetectAndConvert as dt, consumeSSE as en, PromptImagePart as er, FileMapStoreOptions as et, SkillActivationState as f, toPiMessages as fn, SessionHookContext as fr, detectTurnInterruption as ft, McpConnection as g, cursor as gn, StreamHookContext as gr, fromAnthropic as gt, ConnectMcpServersOptions as h, CursorParams as hn, SpawnHookContext as hr, filterUnresolvedToolUses as ht, AgentOptions as i, openaiCompat as in, RepeatGuardConfig as ir, PairingRepair as it, hashContent as j, resolveAnthropicBetas as jn, toolOutputBudgetByteLength as jr, XaiParams as jt, ReadStateMap as k, classifyAnthropicError as kn, TurnFinishReason as kr, ToolSpec as kt, ActivationVia as l, classifyOpenAIError as ln, RunHookMap as lr, ToWireMessagesOptions as lt, createSkillActivationState as m, local as mn, SessionTurn as mr, ensureToolResultPairing as mt, AgentHookMap as n, mapOAIFinishReason as nn, PromptTextPart as nr, EnsureToolResultPairingOptions as nt, McpToolMeta as o, toolResultsMessage as on, ResolveContentRef as or, RemintResult as ot, SkillActivationStateOptions as p, LocalParams as pn, SessionMessage as pr, ensureEndsWithUserMessage as pt, createSession as q, McpToolHookContext as qn, OpenAICompatStreamError as qt, AgentHooks as r, openAICompatPromptMessage as rn, PromptVideoPart as rr, ORPHANED_TOOL_RESULT_MARKER as rt, McpToolWrap as s, userMessage as sn, ResolveContentRefBlock as sr, SYNTHETIC_TOOL_RESULT_PLACEHOLDER as st, Agent as t, formatTools as tn, PromptPart as tr, createFileMapStore as tt, ActiveSkill as u, mapCodexStopReason as un, SessionContentBlock as ur, TurnInterruptionState as ut, connectMcpServers as v, cerebras as vn, ToolBatchExecutor as vr, remintDuplicateToolCallIds as vt, ToolContext as w, AnthropicContextManagement as wn, ToolResultDocumentRefContent as wr, StreamCallbacks as wt, normalizeMcpServers as x, planBasetenReasoning as xn, ToolResultAudioContent as xr, toWireMessages as xt, deriveMcpToolMeta as y, BasetenParams as yn, ToolHookContext as yr, toAnthropic as yt, SkillResource as z, CompactEndHookContext as zn, ContextItem as zr, normalizeOpenRouterModelId as zt };
+//# sourceMappingURL=agent-BAgOgS37.d.ts.map