@sema-ai/core 1.275.1

package/dist/engine/llm/types.d.ts

@@ -0,0 +1,753 @@
+export type { AssistantMessageDiagnostic, DiagnosticErrorInfo } from "./diagnostics.js";
+import type { AssistantMessageDiagnostic } from "./diagnostics.js";
+import type { RepetitionEvent } from "../../brain/repetition.js";
+export type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-chatgpt-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex";
+export type Api = KnownApi | (string & {});
+export type KnownImagesApi = "openrouter-images";
+export type ImagesApi = KnownImagesApi | (string & {});
+export type Provider = string;
+export type KnownImagesProvider = "openrouter";
+export type ImagesProvider = string;
+/**
+ * Effort/intensity TIERS (no "off" — this is the value a provider effort field takes). ⚠ Name clash
+ * by history with the loop-layer `ThinkingLevel` (engine/loop/types.ts), which is the SEVEN-value
+ * on/off+tier knob ("off" | these six). Rule of thumb: harness/task config uses the loop's 7-tier
+ * type; provider compat fields (`reasoningEffortLevels`/`effortLevels`) use this 6-tier one.
+ */
+export type ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type ModelThinkingLevel = "off" | ThinkingLevel;
+export type ThinkingLevelMap = Partial<Record<ModelThinkingLevel, string | null>>;
+export type CacheRetention = "none" | "short" | "long";
+export type Transport = "sse" | "websocket" | "websocket-cached" | "auto";
+export type MaybePromise<T> = T | Promise<T>;
+export interface ProviderResponse {
+    status: number;
+    headers: Record<string, string>;
+}
+/**
+ * design/131 — per-task resilience overrides (intent flags, NOT decorator config). A bench/eval or
+ * critical task can say "fail rather than fall back" without any new global switch; the deployment's
+ * decorator stack stays the single topology owner. All default to today's behavior when absent.
+ */
+export interface ResilienceOptions {
+    /** false = this task forbids reactive model DEGRADE (the degrading brain passes the failure through). */
+    allowDegrade?: boolean;
+    /** false = this task forbids cross-gateway FAILOVER (only the primary brain is tried). */
+    allowFailover?: boolean;
+    /** true = this task ignores an OPEN circuit breaker's fast-fail (the probe goes through; outcomes
+     *  are STILL recorded so shared observation is undiminished). Operator-facing — an open breaker
+     *  exists to protect the provider; bypass only where true failure shape matters (benchmarks). */
+    bypassBreaker?: boolean;
+}
+export interface StreamOptions {
+    temperature?: number;
+    maxTokens?: number;
+    /**
+     * Stop sequences forwarded to providers that support them. Providers map this
+     * to their native request field, such as OpenAI `stop` or Anthropic
+     * `stop_sequences`.
+     */
+    stop?: string[];
+    signal?: AbortSignal;
+    apiKey?: string;
+    /**
+     * Preferred transport for providers that support multiple transports.
+     * Providers that do not support this option ignore it.
+     */
+    transport?: Transport;
+    /**
+     * Prompt cache retention preference. Providers map this to their supported values.
+     * Default: "short".
+     */
+    cacheRetention?: CacheRetention;
+    /**
+     * Optional session identifier for providers that support session-based caching.
+     * Providers can use this to enable prompt caching, request routing, or other
+     * session-aware features. Ignored by providers that don't support it.
+     */
+    sessionId?: string;
+    /**
+     * Optional provider prompt-cache affinity key, distinct from transcript/session identity.
+     * Providers that do not support separate cache affinity ignore it.
+     */
+    promptCacheKey?: string;
+    /**
+     * Optional callback for inspecting or replacing provider payloads before sending.
+     * Return undefined to keep the payload unchanged.
+     */
+    onPayload?: (payload: unknown, model: Model) => MaybePromise<unknown>;
+    /**
+     * Optional callback invoked after an HTTP response is received and before
+     * its body stream is consumed.
+     */
+    onResponse?: (response: ProviderResponse, model: Model) => void | Promise<void>;
+    /**
+     * Optional custom HTTP headers to include in API requests.
+     * Merged with provider defaults; can override default headers.
+     * Not supported by all providers (e.g., AWS Bedrock uses SDK auth).
+     */
+    headers?: Record<string, string>;
+    /**
+     * HTTP request timeout in milliseconds for providers/SDKs that support it.
+     * For example, OpenAI and Anthropic SDK clients default to 10 minutes.
+     */
+    timeoutMs?: number;
+    /**
+     * service [405] P0 — true when `maxTokens` on THIS call was DYNAMICALLY SHRUNK by the wall-clock
+     * cap (design/130 P1), not statically configured. A provider hitting max_tokens with ONLY
+     * reasoning output should then finish as a RECOVERABLE `length` stop (the loop's truncated-output
+     * continue picks it up; the next call is cap-exempt via the runtime reasoning observation) instead
+     * of the static-config fail-loud error — under a dynamic cap the truncation is the ENGINE's doing,
+     * not a deployment mistake.
+     */
+    maxTokensDynamic?: boolean;
+    /**
+     * Blackboard [477] — the STATIC leg of the [405] dynamicCut family. True = the caller (the agent
+     * loop) is prepared to recover a `length` stop, so a provider hitting the STATIC max_tokens with
+     * ONLY reasoning output (a budget-ignoring thinking model — e.g. a Qwen gateway that ignores the
+     * thinking control plane and eats the whole static budget in one thought) may finish as a
+     * RECOVERABLE `length` stop tagged `staticReasoningCut` instead of the fail-loud config error.
+     * The loop grants this only while its per-run stop-loss budget lasts (2 downgrades), then stops
+     * passing it — the third truncation fails loud again (no infinite truncate/continue burn).
+     * Absent/false ⇒ today's behavior: reasoning-only static max_tokens is a fail-loud error (a
+     * genuine misconfiguration must stay loud — e.g. the compaction summarizer relies on the
+     * `length_empty` errorKind to escalate its budget).
+     */
+    staticReasoningCutDowngrade?: boolean;
+    /**
+     * design/131 (service [404] 拍) — per-task resilience INTENT flags, threaded per call so the
+     * resilience decorator stack (degrading / failover / circuit-breaker) can stand aside for THIS
+     * task. Intent-only: no decorator topology rides the wire; each layer reads the flag it owns and
+     * defaults to today's behavior when absent. See design/131-per-task-resilience-overrides.md.
+     */
+    resilience?: ResilienceOptions;
+    /**
+     * design/130 P2b — absolute soft wall-clock deadline (ms epoch) for THIS call. A provider that
+     * observes `Date.now()` crossing it SHOULD cancel the stream deliberately, salvage the prefix
+     * streamed so far, and end the turn `error` with the shared walltime-cutoff sentinel message
+     * (see src/brain/walltime.ts) — the loop then drives a bounded write-out turn instead of the
+     * generation riding into the runner's hard abort. Best-effort contract: a provider that ignores
+     * it is still safe (the runner's hard-abort backstop remains the outer bound).
+     */
+    callDeadlineMs?: number;
+    /**
+     * Maximum retry attempts for providers/SDKs that support client-side retries.
+     * For example, OpenAI and Anthropic SDK clients default to 2.
+     */
+    maxRetries?: number;
+    /**
+     * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
+     * If the server's requested delay exceeds this value, the request fails immediately
+     * with an error containing the requested delay, allowing higher-level retry logic
+     * to handle it with user visibility.
+     * Default: 60000 (60 seconds). Set to 0 to disable the cap.
+     */
+    maxRetryDelayMs?: number;
+    /**
+     * Optional metadata to include in API requests.
+     * Providers extract the fields they understand and ignore the rest.
+     * For example, Anthropic uses `user_id` for abuse tracking and rate limiting.
+     */
+    metadata?: Record<string, unknown>;
+}
+export type ProviderStreamOptions = StreamOptions & Record<string, unknown>;
+export interface ImagesOptions {
+    signal?: AbortSignal;
+    apiKey?: string;
+    /**
+     * Optional callback for inspecting or replacing provider payloads before sending.
+     * Return undefined to keep the payload unchanged.
+     */
+    onPayload?: (payload: unknown, model: ImagesModel) => MaybePromise<unknown>;
+    /**
+     * Optional callback invoked after an HTTP response is received.
+     */
+    onResponse?: (response: ProviderResponse, model: ImagesModel) => void | Promise<void>;
+    /**
+     * Optional custom HTTP headers to include in API requests.
+     * Merged with provider defaults; can override default headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * HTTP request timeout in milliseconds for providers/SDKs that support it.
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum retry attempts for providers/SDKs that support client-side retries.
+     */
+    maxRetries?: number;
+    /**
+     * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
+     * If the server's requested delay exceeds this value, the request fails immediately
+     * with an error containing the requested delay, allowing higher-level retry logic
+     * to handle it with user visibility.
+     * Default: 60000 (60 seconds). Set to 0 to disable the cap.
+     */
+    maxRetryDelayMs?: number;
+    /**
+     * Optional metadata to include in API requests.
+     * Providers extract the fields they understand and ignore the rest.
+     */
+    metadata?: Record<string, unknown>;
+}
+export type ProviderImagesOptions = ImagesOptions & Record<string, unknown>;
+export interface SimpleStreamOptions extends StreamOptions {
+    reasoning?: ThinkingLevel;
+}
+export type StreamFunction<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = (model: Model<TApi>, context: Context, options?: TOptions) => AssistantMessageEventStreamContract;
+export type ImagesFunction<TApi extends ImagesApi = ImagesApi, TOptions extends ImagesOptions = ImagesOptions> = (model: ImagesModel<TApi>, context: ImagesContext, options?: TOptions) => Promise<AssistantImages>;
+export interface TextSignatureV1 {
+    v: 1;
+    id: string;
+    phase?: "commentary" | "final_answer";
+}
+export interface TextContent {
+    type: "text";
+    text: string;
+    textSignature?: string;
+}
+export interface ThinkingContent {
+    type: "thinking";
+    thinking: string;
+    thinkingSignature?: string;
+    /** When true, the thinking content was redacted by safety filters. The opaque
+     *  encrypted payload is stored in `thinkingSignature` so it can be passed back
+     *  to the API for multi-turn continuity. */
+    redacted?: boolean;
+}
+export interface ImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+/** A binary document payload (today: PDF only — `application/pdf`). Produced by the Read tool's PDF
+ *  branch (CC FileReadTool parity: the file is sent to the model as a native `document` content block
+ *  so an Anthropic-family model reads the text layer directly). Provider support is uneven: the
+ *  anthropic brain forwards it as `{type:"document",source:{type:"base64",…}}`; the openai brain has
+ *  no equivalent block and substitutes an honest text placeholder (never a silent drop). */
+export interface DocumentContent {
+    type: "document";
+    data: string;
+    mimeType: string;
+}
+export interface ToolCall {
+    type: "toolCall";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    thoughtSignature?: string;
+    executionMode?: "sequential" | "parallel";
+}
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+export interface UserMessage {
+    role: "user";
+    content: string | (TextContent | ImageContent)[];
+    timestamp: number;
+}
+export interface AssistantMessage {
+    role: "assistant";
+    content: (TextContent | ThinkingContent | ToolCall)[];
+    api: Api;
+    provider: Provider;
+    model: string;
+    responseModel?: string;
+    responseId?: string;
+    diagnostics?: AssistantMessageDiagnostic[];
+    usage: Usage;
+    /** TB 尸检 T1-5 (codex 1.238 复审 F3): the provider never delivered a usage frame for this message (e.g. a
+     *  degenerate-repetition cutoff cancelled the stream first) — `usage` above is a zero-synthesized shell.
+     *  Consumers must treat the numbers as UNKNOWN, not zero. Absent ⇒ usage is provider-reported. */
+    usageMissing?: true;
+    stopReason: StopReason;
+    errorMessage?: string;
+    /** Structured cause for `stopReason:"error"` a caller can react to programmatically (errorMessage is
+     *  human-facing prose and NOT a contract). `"length_empty"` = a max_tokens cut that produced reasoning/
+     *  scratch but NO answer text (both brains surface that as an error, not a "length" stop) — the compaction
+     *  summary path escalates its token budget on it. Extend the union as new recoverable causes are classified. */
+    errorKind?: "length_empty";
+    /**
+     * design/124 tier A: this final message was PARTIALLY FINALIZED after a mid-stream connection
+     * loss/stall — the substantive streamed prefix (text and/or completed tool calls) was promoted to
+     * final content instead of failing the turn (CC 198 queryModelStreaming parity: avoid re-billing +
+     * keep the displayed content consistent with the result). `stopReason` is synthesized from the
+     * content ("toolUse" when a completed tool call streamed, else "stop"); `errorMessage` carries the
+     * CC-verbatim warning ("Response stalled mid-stream." / "Connection closed mid-response."), visible
+     * to the model in the transcript. Downstream semantics (agent-loop): `partialFinalized &&
+     * stopReason==="stop"` gets a BOUNDED continue nudge (an autonomous run must not book the cut as an
+     * incomplete success); `partialFinalized && stopReason==="toolUse"` executes normally (a truncated
+     * trailing call was already dropped by the finalize malformed path). Additive — absent everywhere else.
+     */
+    partialFinalized?: true;
+    /**
+     * Degenerate-repetition telemetry for THIS call (clay 2026-07-10: counts + detected segment, not just
+     * a boolean). `cut` = the event that cancelled the stream (always paired with the DEGENERATE_MESSAGE
+     * errorMessage); `spared` = repetitions that landed in a detection window but were exempted by a
+     * 2e1c161 structural allowance (code-line shape / divider run) — deduped per stream by rule+segment.
+     * The RSI raw material for judging whether the allowance is too wide or too narrow. Additive —
+     * absent when the detector never hit anything.
+     */
+    repetition?: {
+        cut?: RepetitionEvent;
+        spared?: RepetitionEvent[];
+    };
+    /**
+     * Blackboard [477]: this `length` stop is a DOWNGRADED reasoning-only STATIC max_tokens hit — the
+     * model spent the entire static output budget on thinking (budget-ignoring gateway shape) and the
+     * brain, granted `StreamOptions.staticReasoningCutDowngrade`, finished the turn as a recoverable
+     * `length` instead of the fail-loud config error. The agent loop counts these per run to enforce
+     * the 2-downgrade stop-loss. Additive — absent everywhere else (incl. the dynamicCut shape).
+     */
+    staticReasoningCut?: true;
+    timestamp: number;
+}
+export interface ToolResultMessage<TDetails = unknown> {
+    role: "toolResult";
+    toolCallId: string;
+    toolName: string;
+    content: (TextContent | ImageContent | DocumentContent)[];
+    details?: TDetails;
+    isError: boolean;
+    timestamp: number;
+}
+export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+export type ImagesInputContent = TextContent | ImageContent;
+export type ImagesOutputContent = TextContent | ImageContent;
+export interface ImagesContext {
+    input: ImagesInputContent[];
+}
+export type ImagesStopReason = "stop" | "error" | "aborted";
+export interface AssistantImages {
+    api: ImagesApi;
+    provider: ImagesProvider;
+    model: string;
+    output: ImagesOutputContent[];
+    responseId?: string;
+    usage?: Usage;
+    stopReason: ImagesStopReason;
+    errorMessage?: string;
+    timestamp: number;
+}
+import type { TSchema } from "typebox";
+export interface Tool<TParameters extends TSchema = TSchema> {
+    name: string;
+    /** VENDORED EDIT (design/115 P0): canonical tool renames keep old model/SDK wire names as aliases. */
+    aliases?: string[];
+    description: string;
+    parameters: TParameters;
+}
+export interface Context {
+    systemPrompt?: string;
+    messages: Message[];
+    tools?: Tool[];
+}
+/**
+ * Event protocol for AssistantMessageEventStream.
+ *
+ * Streams should emit `start` before partial updates, then terminate with either:
+ * - `done` carrying the final successful AssistantMessage, or
+ * - `error` carrying the final AssistantMessage with stopReason "error" or "aborted"
+ *   and errorMessage.
+ */
+export type AssistantMessageEvent = {
+    type: "start";
+    partial: AssistantMessage;
+} | {
+    type: "text_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+}
+/**
+ * VENDORED EDIT (upstream cherry-pick 6fcc945702, monthly diff 2026-06-13): plain text deltas may
+ * omit `partial` to avoid retaining one full assistant snapshot per token; consumers replay
+ * `delta` from the latest start/end partial checkpoint (agent-loop reconstructs).
+ */
+ | {
+    type: "text_delta";
+    contentIndex: number;
+    delta: string;
+    partial?: AssistantMessage;
+} | {
+    type: "text_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+}
+/**
+ * design/124 tier B contract note: after a mid-stream failure with only thinking streamed, the
+ * brain seals the block (`thinking_end`) and RE-SENDS the whole turn WITHOUT a second `start` —
+ * the retry attempt may then legally reopen a thinking block at the SAME contentIndex (the openai
+ * parser hardcodes thinking at index 0; the anthropic wire restarts block indexing per attempt).
+ * Consumers that render by `partial` snapshot are naturally correct (each retry event carries a
+ * fresh snapshot that REPLACES the previous attempt's content — CC's "drop the thinking" semantics);
+ * a consumer keying blocks by index gets exactly the intended replacement.
+ */
+ | {
+    type: "thinking_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+}
+/**
+ * design/120 P2.0 provider contract — `toolcall_end` may trigger IN-STREAM TOOL EXECUTION
+ * (agent-loop P2), so its emission carries real semantics, not just UI progress:
+ * - Emit it only when the call's input is COMPLETE and parsed to a valid JSON object (`toolCall`
+ *   is executable as-is). A malformed/truncated accumulation must emit nothing (fail-closed: the
+ *   call then never executes in-stream; the brain's finalize surfaces it via its malformed path).
+ * - Emit AT MOST ONCE per call, and every emitted call MUST appear — same `id`, same `arguments`
+ *   object identity not required but same values — in the terminal `done` message's content.
+ *   (One-directional: content may carry calls that never emitted `toolcall_end`, e.g. trailing
+ *   calls closed at finalize or text-repaired calls; those simply run on the post-stream batch
+ *   path.) An `error` terminal is allowed to lack the block; the loop's error-final reconciliation
+ *   merges executor-held calls back into the persisted content (design/120 §5.4).
+ */
+ | {
+    type: "toolcall_end";
+    contentIndex: number;
+    toolCall: ToolCall;
+    partial: AssistantMessage;
+} | {
+    type: "done";
+    reason: Extract<StopReason, "stop" | "length" | "toolUse">;
+    message: AssistantMessage;
+} | {
+    type: "error";
+    reason: Extract<StopReason, "aborted" | "error">;
+    error: AssistantMessage;
+};
+export interface AssistantMessageEventStreamContract extends AsyncIterable<AssistantMessageEvent> {
+    push(event: AssistantMessageEvent): void;
+    end(result?: AssistantMessage): void;
+    result(): Promise<AssistantMessage>;
+}
+export interface AssistantMessageEventStreamLike extends AsyncIterable<AssistantMessageEvent> {
+    result(): Promise<AssistantMessage>;
+}
+/**
+ * Compatibility settings for OpenAI-compatible completions APIs.
+ * Use this to override URL-based auto-detection for custom providers.
+ */
+export interface OpenAICompletionsCompat {
+    /** Whether the provider supports the `store` field. Default: auto-detected from URL. */
+    supportsStore?: boolean;
+    /** Whether the provider supports the `developer` role (vs `system`). Default: auto-detected from URL. */
+    supportsDeveloperRole?: boolean;
+    /** Whether the provider supports `reasoning_effort`. Default: auto-detected from URL. */
+    supportsReasoningEffort?: boolean;
+    /**
+     * Which `reasoning_effort` tiers this endpoint accepts. Absent → the conservative default
+     * (`minimal | low | medium | high`), so a higher requested tier (`xhigh`/`max`) clamps down to `high`
+     * rather than 422'ing a stock OpenAI endpoint. Declare a higher tier here when the provider genuinely
+     * takes it (e.g. `["minimal","low","medium","high","xhigh"]`). See sema-core design/96 S5.
+     */
+    reasoningEffortLevels?: ThinkingLevel[];
+    /** Whether the provider supports `stream_options: { include_usage: true }` for token usage in streaming responses. Default: true. */
+    supportsUsageInStreaming?: boolean;
+    /** Which field to use for max tokens. Default: `"max_tokens"` (no URL auto-detection — declare
+     *  `"max_completion_tokens"` for newer stock-OpenAI models that require it; design/119 #3). */
+    maxTokensField?: "max_completion_tokens" | "max_tokens";
+    /** Whether tool results require the `name` field. Default: auto-detected from URL. */
+    requiresToolResultName?: boolean;
+    /** Whether a user message after tool results requires an assistant message in between. Default: auto-detected from URL. */
+    requiresAssistantAfterToolResult?: boolean;
+    /** Whether thinking blocks must be converted to text blocks with <thinking> delimiters. Default: auto-detected from URL. */
+    requiresThinkingAsText?: boolean;
+    /** Whether all replayed assistant messages must include an empty reasoning_content field when reasoning is enabled. Default: auto-detected from URL. */
+    requiresReasoningContentOnAssistantMessages?: boolean;
+    /** Format for reasoning/thinking parameter. "openai" uses reasoning_effort, "openrouter" uses reasoning: { effort }, "deepseek" uses thinking: { type } plus reasoning_effort, "together" uses reasoning: { enabled } plus reasoning_effort when supported, "zai" uses top-level enable_thinking: boolean, "qwen" uses top-level enable_thinking: boolean, and "qwen-chat-template" uses chat_template_kwargs.enable_thinking. Default: "openai". */
+    thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "zai" | "qwen" | "qwen-chat-template";
+    /** OpenRouter-specific routing preferences. Only used when baseUrl points to OpenRouter. */
+    openRouterRouting?: OpenRouterRouting;
+    /** Vercel AI Gateway routing preferences. Only used when baseUrl points to Vercel AI Gateway. */
+    vercelGatewayRouting?: VercelGatewayRouting;
+    /** Whether z.ai supports top-level `tool_stream: true` for streaming tool call deltas. Default: false. */
+    zaiToolStream?: boolean;
+    /** Whether the provider supports the `strict` field in tool definitions. Default: true. */
+    supportsStrictMode?: boolean;
+    /** Cache control convention for prompt caching. "anthropic" applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user/assistant text content. */
+    cacheControlFormat?: "anthropic";
+    /** Whether to send known session-affinity headers (`session_id`, `x-client-request-id`, `x-session-affinity`) from `options.sessionId` when caching is enabled. Default: false. */
+    sendSessionAffinityHeaders?: boolean;
+    /** Whether the provider supports long prompt cache retention (`prompt_cache_retention: "24h"` or Anthropic-style `cache_control.ttl: "1h"`, depending on format). Default: true. */
+    supportsLongCacheRetention?: boolean;
+}
+/** Compatibility settings for OpenAI Responses APIs. */
+export interface OpenAIResponsesCompat {
+    /** Whether to send the OpenAI `session_id` cache-affinity header from `options.sessionId` when caching is enabled. Default: true. */
+    sendSessionIdHeader?: boolean;
+    /** Whether the provider supports `prompt_cache_retention: "24h"`. Default: true. */
+    supportsLongCacheRetention?: boolean;
+}
+/** Compatibility settings for Anthropic Messages-compatible APIs. */
+export interface AnthropicMessagesCompat {
+    /**
+     * How this endpoint takes extended thinking (CC 2.1.198 parity, design/119).
+     * - `"budget"` (default, pre-Fable models): `thinking: { type: "enabled", budget_tokens }`.
+     * - `"adaptive"` (Fable 5 / Opus 4.8/4.7 class): `thinking: { type: "adaptive" }` — NO
+     *   `budget_tokens` (these models 400 on a budget), no max_tokens bump; the intensity is carried
+     *   by `output_config.effort` instead (see {@link effortLevels}). `off` omits the field entirely
+     *   (these models also reject `{type:"disabled"}`).
+     */
+    thinkingMode?: "budget" | "adaptive";
+    /**
+     * Effort tiers this endpoint accepts via `output_config.effort` (CC 2.1.198 `effort` /
+     * `xhigh_effort` / `max_effort` capability bits collapsed into one declared set, matching the
+     * `reasoningEffortLevels` pattern on {@link OpenAICompletionsCompat}). Present ⇒ the brain sends
+     * `output_config: { effort }` plus the `effort-2025-11-24` beta header, clamping the requested
+     * tier DOWN into this set (e.g. Fable 5 = `["low","medium","high","xhigh","max"]`; a model without
+     * `xhigh_effort` declares up to `"high"` and higher requests clamp). Absent ⇒ no `output_config`
+     * is ever sent (pre-effort models unchanged).
+     */
+    effortLevels?: ThinkingLevel[];
+    /**
+     * Whether the endpoint accepts `temperature` at all. CC 2.1.198 sends temperature only to a
+     * legacy allowlist — Fable-5-class models NEVER receive it (400 risk), independent of thinking
+     * state. Default true (existing models unchanged); `false` drops a caller temperature
+     * unconditionally, not just under extended thinking.
+     */
+    supportsTemperature?: boolean;
+    /**
+     * design/119 S4 (CC 2.1.198 `context_management` capability): when thinking is enabled, send
+     * `context_management: { edits: [{ type: "clear_thinking_20251015", keep: "all" }] }` plus the
+     * `context-management-2025-06-27` beta — an explicit opt-OUT of the server's default
+     * thinking-clearing, preserving cross-turn reasoning continuity (what CC sends on first-party
+     * endpoints). Declare only on endpoints that accept the beta (real Anthropic); an
+     * Anthropic-COMPATIBLE gateway (e.g. DeepSeek's anthropic endpoint) must leave it off.
+     */
+    contextManagement?: boolean;
+    /**
+     * design/119 S4 (CC 2.1.198): attach the `interleaved-thinking-2025-05-14` beta on tool-enabled
+     * requests with thinking on (thinking blocks may interleave with tool_use). Declare per endpoint;
+     * absent = no beta (pre-119 behavior; a deployment could already do this via static `headers`).
+     */
+    interleavedThinking?: boolean;
+    /**
+     * Whether the provider accepts per-tool `eager_input_streaming`.
+     * When false, the Anthropic provider omits `tools[].eager_input_streaming`
+     * and sends the legacy `fine-grained-tool-streaming-2025-05-14` beta header
+     * for tool-enabled requests.
+     * Default: true.
+     */
+    supportsEagerToolInputStreaming?: boolean;
+    /** Whether the provider supports Anthropic long cache retention (`cache_control.ttl: "1h"`). Default: true. */
+    supportsLongCacheRetention?: boolean;
+    /**
+     * Whether to send the `x-session-affinity` header from `options.sessionId`
+     * when caching is enabled. Required for providers like Fireworks that use
+     * session affinity for prompt cache routing (requests to the same replica
+     * maximize cache hits).
+     * Default: false.
+     */
+    sendSessionAffinityHeaders?: boolean;
+    /**
+     * Whether the provider supports Anthropic-style `cache_control` markers on
+     * tool definitions. When false, `cache_control` is omitted from tool params.
+     * Some Anthropic-compatible providers (e.g., Fireworks) do not support this
+     * field on tools and may reject or ignore it.
+     * Default: true.
+     */
+    supportsCacheControlOnTools?: boolean;
+}
+/**
+ * OpenRouter provider routing preferences.
+ * Controls which upstream providers OpenRouter routes requests to.
+ * Sent as the `provider` field in the OpenRouter API request body.
+ * @see https://openrouter.ai/docs/guides/routing/provider-selection
+ */
+export interface OpenRouterRouting {
+    /** Whether to allow backup providers to serve requests. Default: true. */
+    allow_fallbacks?: boolean;
+    /** Whether to filter providers to only those that support all parameters in the request. Default: false. */
+    require_parameters?: boolean;
+    /** Data collection setting. "allow" (default): allow providers that may store/train on data. "deny": only use providers that don't collect user data. */
+    data_collection?: "deny" | "allow";
+    /** Whether to restrict routing to only ZDR (Zero Data Retention) endpoints. */
+    zdr?: boolean;
+    /** Whether to restrict routing to only models that allow text distillation. */
+    enforce_distillable_text?: boolean;
+    /** An ordered list of provider names/slugs to try in sequence, falling back to the next if unavailable. */
+    order?: string[];
+    /** List of provider names/slugs to exclusively allow for this request. */
+    only?: string[];
+    /** List of provider names/slugs to skip for this request. */
+    ignore?: string[];
+    /** A list of quantization levels to filter providers by (e.g., ["fp16", "bf16", "fp8", "fp6", "int8", "int4", "fp4", "fp32"]). */
+    quantizations?: string[];
+    /** Sorting strategy. Can be a string (e.g., "price", "throughput", "latency") or an object with `by` and `partition`. */
+    sort?: string | {
+        /** The sorting metric: "price", "throughput", "latency". */
+        by?: string;
+        /** Partitioning strategy: "model" (default) or "none". */
+        partition?: string | null;
+    };
+    /** Maximum price per million tokens (USD). */
+    max_price?: {
+        /** Price per million prompt tokens. */
+        prompt?: number | string;
+        /** Price per million completion tokens. */
+        completion?: number | string;
+        /** Price per image. */
+        image?: number | string;
+        /** Price per audio unit. */
+        audio?: number | string;
+        /** Price per request. */
+        request?: number | string;
+    };
+    /** Preferred minimum throughput (tokens/second). Can be a number (applies to p50) or an object with percentile-specific cutoffs. */
+    preferred_min_throughput?: number | {
+        /** Minimum tokens/second at the 50th percentile. */
+        p50?: number;
+        /** Minimum tokens/second at the 75th percentile. */
+        p75?: number;
+        /** Minimum tokens/second at the 90th percentile. */
+        p90?: number;
+        /** Minimum tokens/second at the 99th percentile. */
+        p99?: number;
+    };
+    /** Preferred maximum latency (seconds). Can be a number (applies to p50) or an object with percentile-specific cutoffs. */
+    preferred_max_latency?: number | {
+        /** Maximum latency in seconds at the 50th percentile. */
+        p50?: number;
+        /** Maximum latency in seconds at the 75th percentile. */
+        p75?: number;
+        /** Maximum latency in seconds at the 90th percentile. */
+        p90?: number;
+        /** Maximum latency in seconds at the 99th percentile. */
+        p99?: number;
+    };
+}
+/**
+ * Vercel AI Gateway routing preferences.
+ * Controls which upstream providers the gateway routes requests to.
+ * @see https://vercel.com/docs/ai-gateway/models-and-providers/provider-options
+ */
+export interface VercelGatewayRouting {
+    /** List of provider slugs to exclusively use for this request (e.g., ["bedrock", "anthropic"]). */
+    only?: string[];
+    /** List of provider slugs to try in order (e.g., ["anthropic", "openai"]). */
+    order?: string[];
+}
+export interface Model<TApi extends Api = Api> {
+    id: string;
+    name: string;
+    api: TApi;
+    provider: Provider;
+    baseUrl: string;
+    reasoning: boolean;
+    /**
+     * design/111 — this model's DEFAULT thinking level (per-model preset). The thinking-resolution chain is
+     * `spec.thinking ?? role.thinking ?? model.defaultThinking` (prepare-task) — a caller/role still overrides, but
+     * a model that should "think by default" (e.g. an Anthropic reasoning model defaulting to `medium`) declares it
+     * here instead of every task/role re-specifying. Absent ⇒ no model-level default (chain falls to `undefined` =
+     * thinking off unless a caller/role asks). It is the REQUESTED tier; the per-endpoint clamp (`resolveReasoning`/
+     * `reasoningEffortLevels`) still bounds it — a stock-OpenAI endpoint clamps `max`→`high`, while an
+     * `anthropic-messages` budget endpoint honors the full range up to `max` unclamped.
+     */
+    defaultThinking?: ThinkingLevel;
+    /**
+     * Maps OpenClaw thinking levels to provider/model-specific values.
+     * Missing keys use provider defaults. null marks a level as unsupported.
+     */
+    thinkingLevelMap?: ThinkingLevelMap;
+    input: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    /**
+     * Optional effective runtime cap used for compaction/session budgeting.
+     * Keeps provider/native contextWindow metadata intact while allowing a
+     * smaller practical window.
+     */
+    contextTokens?: number;
+    /**
+     * design/123 D2 — structural token-estimate coefficient: how many CHARACTERS ≈ one token for this
+     * model's tokenizer. Used by every structural (non-usage-anchored) token estimate in the engine:
+     * the compaction trigger's anchor-less fallback, the request-layer defenses (clearStaleToolResults /
+     * trimToBudget), cut-point accounting, the prompt-overhead term, and the summarization input guard.
+     * API-agnostic model property (NOT a wire knob), hence top-level and not `compat`.
+     *
+     * Default **4** (byte-compatible with the historical chars/4 heuristic; CC 198's legacy-family
+     * value — claude-3.x / opus·sonnet-4-x / haiku-4-5). Newer families tokenize denser (CC 198 uses
+     * **3** for the sonnet-5/fable-5 class). CJK-heavy deployments should consider **2–3**: chars/4
+     * underestimates Chinese by 60–75%, which lets the defenses pass over-window requests.
+     */
+    charsPerToken?: number;
+    maxTokens: number;
+    /** Provider-specific request/runtime parameters passed through to provider plugins. */
+    params?: Record<string, unknown>;
+    /**
+     * Extra request-BODY params merged into the provider call (design/40): official provider knobs core
+     * doesn't model as first-class — OpenAI `frequency_penalty`/`presence_penalty`/`top_p`/`seed`/`logit_bias`,
+     * Anthropic `top_k`/`top_p`/`stop_sequences`, etc. Keys core owns (messages/tools/temperature/…) are
+     * stripped (core wins). **Anchored on the Model and stable across turns** — reuse the SAME Model object
+     * (stable key-insertion order) for every turn sharing a cache namespace, or the serialized body bytes
+     * change and the prefix cache breaks (design/9/31). Not for per-turn variation.
+     */
+    extraBody?: Record<string, unknown>;
+    /** Extra request HEADERS merged into the provider call. Cannot override auth / content-type / version. */
+    headers?: Record<string, string>;
+    /**
+     * design/119 S3 (CC 2.1.198 parity): model-declared system-prompt guidance sections, appended to
+     * the assembled system prompt. This is the declarative home for per-model behavioral patches (CC
+     * ships Fable-5 "mitigations" baked behind model-name checks; sema keeps the MECHANISM generic —
+     * any Model can carry guidance — and the CONTENT as preset data, zero model-name matching in core).
+     * Each entry is one section; joined with blank lines.
+     */
+    promptGuidance?: string[];
+    /** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
+    compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : never;
+    /** Provider-documented media input limits used by attachment preprocessing. */
+    mediaInput?: {
+        image?: {
+            maxBytes?: number;
+            maxPixels?: number;
+            maxSidePx?: number;
+            preferredSidePx?: number;
+            tokenMode?: "tile" | "detail" | "provider";
+        };
+    };
+}
+export interface ImagesModel<TApi extends ImagesApi = ImagesApi> extends Omit<Model, "api" | "provider" | "reasoning" | "contextWindow" | "maxTokens" | "compat"> {
+    api: TApi;
+    provider: ImagesProvider;
+    output: ("text" | "image")[];
+}
+export type StreamFn = (model: Model, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStreamLike | Promise<AssistantMessageEventStreamLike>;
+export type CompleteSimpleFn = (model: Model, context: Pick<Context, "systemPrompt" | "messages">, options?: SimpleStreamOptions) => Promise<AssistantMessage>;
+export type ValidateToolArgumentsFn = (tool: Tool, toolCall: ToolCall) => unknown;
+//# sourceMappingURL=types.d.ts.map