@aryee337/aery-ai 0.1.148 → 0.2.10

package/dist/types/types.d.ts

@@ -0,0 +1,801 @@
+import type { ZodType, z } from "zod/v4";
+import type { BedrockOptions } from "./providers/amazon-bedrock";
+import type { AnthropicOptions } from "./providers/anthropic";
+import type { AzureOpenAIResponsesOptions } from "./providers/azure-openai-responses";
+import type { CursorOptions } from "./providers/cursor";
+import type { DeleteArgs, DeleteResult, DiagnosticsArgs, DiagnosticsResult, GrepArgs, GrepResult, LsArgs, LsResult, McpResult, ReadArgs, ReadResult, ShellArgs, ShellResult, WriteArgs, WriteResult } from "./providers/cursor/gen/agent_pb";
+import type { GoogleOptions } from "./providers/google";
+import type { GoogleGeminiCliOptions } from "./providers/google-gemini-cli";
+import type { GoogleVertexOptions } from "./providers/google-vertex";
+import type { OllamaChatOptions } from "./providers/ollama";
+import type { OpenAICodexResponsesOptions } from "./providers/openai-codex-responses";
+import type { OpenAICompletionsOptions } from "./providers/openai-completions";
+import type { OpenAIResponsesOptions } from "./providers/openai-responses";
+import type { AssistantMessageEventStream } from "./utils/event-stream";
+export type { AssistantMessageEventStream } from "./utils/event-stream";
+export type KnownApi = "openai-completions" | "openai-responses" | "openai-codex-responses" | "azure-openai-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-gemini-cli" | "google-vertex" | "ollama-chat" | "cursor-agent";
+export type Api = KnownApi | (string & {});
+export interface ApiOptionsMap {
+    "anthropic-messages": AnthropicOptions;
+    "bedrock-converse-stream": BedrockOptions;
+    "openai-completions": OpenAICompletionsOptions;
+    "openai-responses": OpenAIResponsesOptions;
+    "openai-codex-responses": OpenAICodexResponsesOptions;
+    "azure-openai-responses": AzureOpenAIResponsesOptions;
+    "google-generative-ai": GoogleOptions;
+    "google-gemini-cli": GoogleGeminiCliOptions;
+    "google-vertex": GoogleVertexOptions;
+    "ollama-chat": OllamaChatOptions;
+    "cursor-agent": CursorOptions;
+}
+export type OptionsForApi<TApi extends Api> = StreamOptions | (TApi extends keyof ApiOptionsMap ? ApiOptionsMap[TApi] : never);
+/** Canonical thinking transport used by a model. */
+export type ThinkingControlMode = "effort" | "budget" | "google-level" | "anthropic-adaptive" | "anthropic-budget-effort";
+/** Per-model thinking capabilities used to clamp and map user-facing effort levels. */
+export interface ThinkingConfig {
+    /** Least intensive supported user-facing effort level. */
+    minLevel: Effort;
+    /** Most intensive supported user-facing effort level. */
+    maxLevel: Effort;
+    /**
+     * Optional explicit list of supported levels. When present, takes precedence over
+     * the `minLevel`..`maxLevel` range — used to encode discrete sets with gaps
+     * (e.g. Gemini 3 Pro supports `low` and `high` but not `medium`).
+     */
+    levels?: readonly Effort[];
+    /** Optional default effort applied when this model is selected. Falls back to global default if absent. */
+    defaultLevel?: Effort;
+    /** Provider-specific transport used to encode the selected effort. */
+    mode: ThinkingControlMode;
+}
+export type KnownProvider = "alibaba-coding-plan" | "amazon-bedrock" | "anthropic" | "google" | "google-gemini-cli" | "google-antigravity" | "google-vertex" | "openai" | "openai-codex" | "kimi-code" | "minimax-code" | "minimax-code-cn" | "github-copilot" | "fireworks" | "firepass" | "gitlab-duo" | "cursor" | "deepseek" | "xai" | "xai-oauth" | "groq" | "cerebras" | "openrouter" | "kilo" | "vercel-ai-gateway" | "zai" | "zhipu-coding-plan" | "mistral" | "minimax" | "opencode-go" | "opencode-zen" | "synthetic" | "cloudflare-ai-gateway" | "huggingface" | "litellm" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "qianfan" | "qwen-portal" | "together" | "venice" | "vllm" | "xiaomi" | "wafer-pass" | "wafer-serverless" | "zenmux" | "lm-studio";
+export type Provider = KnownProvider | string;
+import type { Effort } from "./model-thinking";
+/** Token budgets for each thinking level (token-based providers only) */
+export type ThinkingBudgets = {
+    [key in Effort]?: number;
+};
+export interface TokenTaskBudget {
+    type: "tokens";
+    total: number;
+    remaining?: number;
+}
+export type MessageAttribution = "user" | "agent";
+export type ToolChoice = "auto" | "none" | "any" | "required" | {
+    type: "function";
+    name: string;
+} | {
+    type: "function";
+    function: {
+        name: string;
+    };
+} | {
+    type: "tool";
+    name: string;
+};
+export type CacheRetention = "none" | "short" | "long";
+/**
+ * Service tier hint for processing priority / cost control.
+ *
+ * The unscoped values (`"auto"`, `"default"`, `"flex"`, `"scale"`,
+ * `"priority"`) are passed through to providers that understand them
+ * (OpenAI's `service_tier` field directly; Anthropic translates
+ * `"priority"` into `speed: "fast"` on supported Opus models).
+ *
+ * The scoped values target a specific provider family and behave as the
+ * unscoped value on the matching provider, or `undefined` everywhere else.
+ * They let users opt into priority on one family without paying premium
+ * costs on the other when switching models mid-session.
+ *
+ * - `"openai-only"` → `"priority"` on `openai` and `openai-codex`; ignored elsewhere.
+ * - `"claude-only"` → `"priority"` on direct `anthropic` (not Bedrock/Vertex Claude).
+ */
+export type ServiceTier = "auto" | "default" | "flex" | "scale" | "priority" | "openai-only" | "claude-only";
+/** Resolved tier — one of the values that providers actually consume on the wire. */
+export type ResolvedServiceTier = Exclude<ServiceTier, "openai-only" | "claude-only">;
+/**
+ * Resolves a possibly scoped `ServiceTier` to the effective tier for the
+ * given provider. Scoped values match their target family and otherwise
+ * collapse to `undefined`; unscoped values pass through unchanged.
+ */
+export declare function resolveServiceTier(serviceTier: ServiceTier | null | undefined, provider: Provider | undefined): ResolvedServiceTier | undefined;
+/**
+ * True when the (possibly scoped) tier should be sent as OpenAI's
+ * `service_tier` request field for the given provider. Non-OpenAI
+ * providers, unsupported tiers (`"auto"`, `"default"`), and scope
+ * mismatches all return false.
+ */
+export declare function shouldSendServiceTier(serviceTier: ServiceTier | null | undefined, provider: Provider | undefined): boolean;
+/**
+ * Premium-request weight contributed by sending priority to a provider
+ * that supports it. Mirrors GitHub Copilot's `premiumRequests` accounting
+ * so the "premium requests" stat aggregates priority traffic across the
+ * OpenAI family and Anthropic fast-mode realizations.
+ *
+ * Returns 1 per resolved priority request, 0 otherwise.
+ */
+export declare function getPriorityPremiumRequests(serviceTier: ServiceTier | null | undefined, provider: Provider | undefined): number;
+export interface ProviderSessionState {
+    close(): void;
+}
+export interface ProviderResponseMetadata {
+    status: number;
+    headers: Record<string, string>;
+    requestId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface RawSseEvent {
+    event: string | null;
+    data: string;
+    raw: string[];
+}
+/**
+ * `fetch`-compatible function. Accepts any callable matching the standard
+ * fetch signature; `preconnect` is optional because non-Bun runtimes (browsers,
+ * test mocks) won't expose it.
+ */
+export type FetchImpl = ((input: string | URL | Request, init?: RequestInit) => Promise<Response>) & {
+    preconnect?: typeof globalThis.fetch.preconnect;
+};
+export interface StreamOptions {
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    minP?: number;
+    presencePenalty?: number;
+    repetitionPenalty?: number;
+    /**
+     * Stop sequences. Anthropic encodes as `stop_sequences` (array, max 4);
+     * OpenAI chat-completions encodes as `stop` (string or array of up to 4);
+     * OpenAI Responses API has no `stop` field today (silently dropped by the
+     * provider when present).
+     */
+    stopSequences?: string[];
+    /**
+     * Frequency penalty (OpenAI). Penalizes new tokens based on existing frequency
+     * in the text so far. Range -2.0 to 2.0. Parallel to {@link presencePenalty}.
+     */
+    frequencyPenalty?: number;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    apiKey?: string;
+    /**
+     * Called when a provider returns 401 before any replay-unsafe assistant
+     * event has been emitted. Returning a different key retries the provider
+     * request once.
+     */
+    onAuthError?: (provider: string, apiKey: string, error: unknown) => Promise<string | undefined>;
+    cacheRetention?: CacheRetention;
+    /**
+     * Additional headers to include in provider requests.
+     * These are merged on top of model-defined headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional explicit request attribution override for providers that support it.
+     */
+    initiatorOverride?: MessageAttribution;
+    /**
+     * 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>;
+    /**
+     * Advisory token budget for a full agentic loop. Anthropic encodes this as
+     * `output_config.task_budget` with the `task-budgets-2026-03-13` beta header.
+     */
+    taskBudget?: TokenTaskBudget;
+    /**
+     * Optional session identifier for providers that support session-based
+     * routing, request affinity, or transport reuse. Providers may also use this
+     * as the prompt-cache key when `promptCacheKey` is not set.
+     */
+    sessionId?: string;
+    /**
+     * Optional prompt-cache identity. When set, OpenAI Responses-compatible
+     * providers use this for `prompt_cache_key` while keeping `sessionId` for
+     * provider routing / conversation headers.
+     */
+    promptCacheKey?: string;
+    /**
+     * Provider-scoped mutable state store for this agent session.
+     * Providers can use this to persist transport/session state between turns.
+     */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /**
+     * Optional callback for inspecting or replacing provider payloads before sending.
+     * Return undefined to keep the payload unchanged.
+     */
+    onPayload?: (payload: unknown, model?: Model<Api>) => unknown | undefined | Promise<unknown | undefined>;
+    /**
+     * Optional callback for provider response metadata after headers are received.
+     */
+    onResponse?: (response: ProviderResponseMetadata, model?: Model<Api>) => void | Promise<void>;
+    /**
+     * Optional callback for raw Server-Sent Events as they arrive from HTTP streaming providers,
+     * plus synthesized SSE-shaped frames for the Codex WebSocket transport (one synthetic frame
+     * per JSON request/response message). WebSocket frames are tagged with a leading
+     * `: ws → <type>` (outbound) or `: ws ← <type>` (inbound) comment line in `RawSseEvent.raw`.
+     *
+     * Diagnostic only: provider implementations must ignore callback failures and must not
+     * let observers alter stream contents.
+     */
+    onSseEvent?: (event: RawSseEvent, model?: Model<Api>) => void;
+    /**
+     * Optional override for the first-event watchdog in milliseconds. Built-in
+     * providers apply this budget twice when they can: once to the underlying
+     * SDK/request while waiting for the HTTP stream object to exist, then again
+     * in the iterator while waiting for the first semantic stream event. Set to
+     * `0` to disable both layers for this request. After the first semantic
+     * event arrives, `streamIdleTimeoutMs` governs inter-event stalls. Falls
+     * back to `PI_STREAM_FIRST_EVENT_TIMEOUT_MS` and then to a 100s default.
+     * OpenAI-family transports additionally honor
+     * `PI_OPENAI_STREAM_FIRST_EVENT_TIMEOUT_MS` as the most-specific override and
+     * floor the first-event budget at the resolved idle (per-call
+     * `streamIdleTimeoutMs` or `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS`) so slow local
+     * OpenAI-compatible servers are not undercut during prompt processing.
+     *
+     * Iterator-level honored by: every built-in provider (via the lazy-stream
+     * forwarder in `register-builtins`). SDK-request honored by:
+     * `openai-completions`, `openai-responses`, `azure-openai-responses`,
+     * `anthropic-messages`.
+     */
+    streamFirstEventTimeoutMs?: number;
+    /**
+     * Optional override for the maximum idle gap between streamed events in
+     * milliseconds. Once the first event arrives, this guards against silent
+     * mid-stream stalls (broker dies, half-open socket, model produces no real
+     * progress for too long). Set to `0` to disable. Falls back to
+     * `PI_STREAM_IDLE_TIMEOUT_MS` (alias: `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS`)
+     * and then to a 120s default.
+     */
+    streamIdleTimeoutMs?: number;
+    /**
+     * Optional retry delay hook for tests and transports that need custom scheduling.
+     */
+    providerRetryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * Optional `fetch` implementation override. Providers route every HTTP
+     * request — direct calls, SDK clients, and retry helpers — through this
+     * implementation when set. Defaults to `globalThis.fetch`. Providers that
+     * do not use `fetch` (Bedrock's AWS SDK transport, Cursor's HTTP/2
+     * channel) silently ignore the override.
+     */
+    fetch?: FetchImpl;
+    /** Cursor exec/MCP tool handlers (cursor-agent only). */
+    execHandlers?: CursorExecHandlers;
+}
+export interface SimpleStreamOptions extends StreamOptions {
+    reasoning?: Effort;
+    /**
+     * Force-disable reasoning for the request even when the model supports it.
+     * Takes precedence over `reasoning`. Useful for fast utility calls
+     * (e.g. title generation) where the model would otherwise burn the entire
+     * output budget on internal thinking. Provider support is format-specific:
+     * some transports can disable reasoning directly, while generic
+     * effort-based OpenAI-compatible endpoints use the lowest supported effort.
+     */
+    disableReasoning?: boolean;
+    /**
+     * If true, request that the provider omit thinking/reasoning summaries
+     * from the response (e.g. Anthropic `thinking.display = "omitted"`,
+     * OpenAI Responses `reasoning.summary` left unset). The model still
+     * reasons internally; only the human-readable summary stream is dropped.
+     * Useful when the UI hides thinking blocks anyway and the summary is wasted bandwidth.
+     */
+    hideThinkingSummary?: boolean;
+    /** Custom token budgets for thinking levels (token-based providers only) */
+    thinkingBudgets?: ThinkingBudgets;
+    /** Cursor exec handlers for local tool execution */
+    cursorExecHandlers?: CursorExecHandlers;
+    /** Hook to handle tool results from Cursor exec */
+    cursorOnToolResult?: CursorToolResultHandler;
+    /** Optional tool choice override for compatible providers */
+    toolChoice?: ToolChoice;
+    /** OpenAI service tier for processing priority/cost control. Ignored by non-OpenAI providers. */
+    serviceTier?: ServiceTier;
+    /** API format for Kimi Code provider: "openai" or "anthropic" (default: "anthropic") */
+    kimiApiFormat?: "openai" | "anthropic";
+    /** API format for Synthetic provider: "openai" or "anthropic" (default: "openai") */
+    syntheticApiFormat?: "openai" | "anthropic";
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
+    /**
+     * OpenRouter routing-variant suffix automatically appended to model IDs when
+     * the request targets OpenRouter (`model.provider === "openrouter"`). Common
+     * values: `"nitro"` (throughput), `"floor"` (cheapest), `"online"` (web
+     * search plugin), `"exacto"` (cherry-picked high-quality providers, only
+     * defined for some models). Ignored when the resolved model id already
+     * contains a `:<variant>` suffix (e.g. the user typed `:nitro` explicitly
+     * or the catalog entry already names the variant).
+     */
+    openrouterVariant?: string;
+}
+export type StreamFunction<TApi extends Api> = (model: Model<TApi>, context: Context, options: OptionsForApi<TApi>) => AssistantMessageEventStream;
+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;
+    itemId?: string;
+}
+export interface RedactedThinkingContent {
+    type: "redactedThinking";
+    data: string;
+}
+export interface ImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export interface ToolCall {
+    type: "toolCall";
+    id: string;
+    name: string;
+    arguments: Record<string, any>;
+    thoughtSignature?: string;
+    intent?: string;
+    /**
+     * Original wire-level name when the tool was invoked via OpenAI's custom-tool
+     * mechanism (e.g., `apply_patch`). Set by `openai-responses` on receive so
+     * the history-replay path can re-emit the call as `custom_tool_call` with
+     * its paired tool-result as `custom_tool_call_output`. Absent for regular
+     * JSON function tools.
+     */
+    customWireName?: string;
+}
+export interface Usage {
+    /** Non-cached input tokens (matches the bucket the provider bills as new input). */
+    input: number;
+    /** Total output tokens for the turn, including thinking, assistant text, and tool-call argument tokens. */
+    output: number;
+    /** Tokens read from the prompt cache. */
+    cacheRead: number;
+    /** Tokens written to the prompt cache (cache creation). */
+    cacheWrite: number;
+    /** Sum of input + output + cacheRead + cacheWrite. */
+    totalTokens: number;
+    /** Copilot premium-request counter, when applicable. */
+    premiumRequests?: number;
+    /**
+     * Reasoning/thinking tokens included in `output`, when the provider reports them
+     * (OpenAI `output_tokens_details.reasoning_tokens`, Google `thoughtsTokenCount`).
+     * Always a subset of `output` — non-reasoning output is `output - reasoningTokens`.
+     *
+     * Providers that don't expose this leave it undefined rather than guessing;
+     * `undefined` means unknown, NOT zero.
+     */
+    reasoningTokens?: number;
+    /**
+     * Cache-write TTL breakdown (Anthropic only). When set, the components sum to
+     * `cacheWrite`. Absent providers do not populate this.
+     */
+    cttl?: {
+        ephemeral5m?: number;
+        ephemeral1h?: number;
+    };
+    /**
+     * Server-side tool invocations made during this turn (Anthropic web_search /
+     * web_fetch, OpenAI built-in tools when reported). Counts requests, not tokens.
+     */
+    server?: {
+        webSearch?: number;
+        webFetch?: number;
+    };
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+export interface OpenAIResponsesHistoryPayload {
+    type: "openaiResponsesHistory";
+    provider?: string;
+    dt?: boolean;
+    items: Array<Record<string, unknown>>;
+}
+export type ProviderPayload = OpenAIResponsesHistoryPayload;
+export interface UserMessage {
+    role: "user";
+    content: string | (TextContent | ImageContent)[];
+    /** True if the message was injected by the system (e.g., auto-continue). */
+    synthetic?: boolean;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    /** Provider-specific opaque payload used to reconstruct transport-native history. */
+    providerPayload?: ProviderPayload;
+    timestamp: number;
+}
+export interface DeveloperMessage {
+    role: "developer";
+    content: string | (TextContent | ImageContent)[];
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    /** Provider-specific opaque payload used to reconstruct transport-native history. */
+    providerPayload?: ProviderPayload;
+    timestamp: number;
+}
+export interface AssistantMessage {
+    role: "assistant";
+    content: (TextContent | ThinkingContent | RedactedThinkingContent | ToolCall)[];
+    api: Api;
+    provider: Provider;
+    model: string;
+    responseId?: string;
+    usage: Usage;
+    stopReason: StopReason;
+    errorMessage?: string;
+    /** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
+    errorStatus?: number;
+    /**
+     * Stable identifiers for request features the provider silently dropped
+     * during this turn (e.g. `"priority"`). Set when a server-side rejection
+     * triggered an in-provider fallback retry that succeeded without the
+     * feature. Callers can use this to sync user-facing toggles back to the
+     * server's actual state.
+     */
+    disabledFeatures?: string[];
+    /** Provider-specific opaque payload used to reconstruct transport-native history. */
+    providerPayload?: ProviderPayload;
+    timestamp: number;
+    duration?: number;
+    ttft?: number;
+}
+export interface ToolResultMessage<TDetails = any> {
+    role: "toolResult";
+    toolCallId: string;
+    toolName: string;
+    content: (TextContent | ImageContent)[];
+    details?: TDetails;
+    isError: boolean;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    /** Timestamp when output was pruned (ms since epoch). Undefined if unpruned. */
+    prunedAt?: number;
+    timestamp: number;
+}
+export type Message = UserMessage | DeveloperMessage | AssistantMessage | ToolResultMessage;
+export type CursorExecHandlerResult<T> = {
+    result: T;
+    toolResult?: ToolResultMessage;
+} | T | ToolResultMessage;
+export type CursorToolResultHandler = (result: ToolResultMessage) => ToolResultMessage | undefined | Promise<ToolResultMessage | undefined>;
+export interface CursorMcpCall {
+    name: string;
+    providerIdentifier: string;
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+    rawArgs: Record<string, Uint8Array>;
+}
+export interface CursorShellStreamCallbacks {
+    onStdout(data: string): void;
+    onStderr(data: string): void;
+}
+export interface CursorExecHandlers {
+    read?: (args: ReadArgs) => Promise<CursorExecHandlerResult<ReadResult>>;
+    ls?: (args: LsArgs) => Promise<CursorExecHandlerResult<LsResult>>;
+    grep?: (args: GrepArgs) => Promise<CursorExecHandlerResult<GrepResult>>;
+    write?: (args: WriteArgs) => Promise<CursorExecHandlerResult<WriteResult>>;
+    delete?: (args: DeleteArgs) => Promise<CursorExecHandlerResult<DeleteResult>>;
+    shell?: (args: ShellArgs) => Promise<CursorExecHandlerResult<ShellResult>>;
+    shellStream?: (args: ShellArgs, callbacks: CursorShellStreamCallbacks) => Promise<CursorExecHandlerResult<ShellResult>>;
+    diagnostics?: (args: DiagnosticsArgs) => Promise<CursorExecHandlerResult<DiagnosticsResult>>;
+    mcp?: (call: CursorMcpCall) => Promise<CursorExecHandlerResult<McpResult>>;
+    onToolResult?: CursorToolResultHandler;
+}
+/**
+ * Plain JSON Schema document used by extension-authored tools (legacy TypeBox
+ * emits this shape). Distinguished from Zod at runtime via {@link isZodSchema}.
+ */
+export type TJsonSchema = Record<string, unknown>;
+/**
+ * Schema type accepted by the {@link Tool} interface.
+ *
+ * Canonical authoring uses Zod. Extension compat may supply a JSON Schema
+ * object (including TypeBox static schema objects).
+ */
+export type TSchema = ZodType | TJsonSchema;
+/** Resolve parameter types for tool execution / handlers. */
+export type Static<S> = S extends ZodType ? z.infer<S> : S extends {
+    static: infer T;
+} ? T : unknown;
+export interface Tool<TParameters extends TSchema = TSchema> {
+    name: string;
+    description: string;
+    parameters: TParameters;
+    /** If true, tool is strictly typed and validated against the parameters schema before execution */
+    strict?: boolean;
+    /**
+     * Optional grammar constraint for OpenAI custom-tool emission.
+     * When set, providers that support grammar-constrained tools (currently only
+     * `openai-responses` against models with the right capability flag) may emit
+     * this tool as `{type: "custom", format: {type: "grammar", …}}` instead of a
+     * JSON function tool. Other providers ignore the field.
+     */
+    customFormat?: {
+        syntax: "lark" | "regex";
+        definition: string;
+    };
+    /**
+     * Optional wire-level name used when this tool is emitted as a custom tool
+     * (e.g. OpenAI's `{type: "custom"}` shape). Models trained on specific tool
+     * names — like GPT-5 on `apply_patch` — need to see that exact name on the
+     * wire, but it may differ from the harness-internal `name`. The agent-loop
+     * dispatcher matches both `name` and `customWireName` so returned tool
+     * calls route correctly. Absent for regular JSON function tools.
+     */
+    customWireName?: string;
+}
+export interface Context {
+    systemPrompt?: string[];
+    messages: Message[];
+    tools?: Tool[];
+}
+export type AssistantMessageEvent = {
+    type: "start";
+    contentIndex?: undefined;
+    partial: AssistantMessage;
+} | {
+    type: "text_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "text_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "text_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    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;
+} | {
+    type: "toolcall_end";
+    contentIndex: number;
+    toolCall: ToolCall;
+    partial: AssistantMessage;
+} | {
+    type: "done";
+    contentIndex?: undefined;
+    reason: Extract<StopReason, "stop" | "length" | "toolUse">;
+    message: AssistantMessage;
+} | {
+    type: "error";
+    contentIndex?: undefined;
+    reason: Extract<StopReason, "aborted" | "error">;
+    error: AssistantMessage;
+};
+/**
+ * Compatibility settings for openai-completions API.
+ * Use this to override URL-based auto-detection for custom providers.
+ */
+export interface OpenAICompat {
+    /** 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's chat-completions endpoint accepts multiple
+     * leading `system`/`developer` messages. When false, ordered system
+     * prompts are coalesced into a single message joined by `\n\n` so
+     * strict chat templates (e.g. Qwen-served via vLLM, MiniMax) accept
+     * the request. Default: detected per provider/baseUrl. Canonical
+     * OpenAI/Azure/OpenRouter/Cerebras/Together/Fireworks/Groq/DeepSeek/
+     * Mistral/xAI/Z.ai/GitHub Copilot/Zenmux are treated as `true`;
+     * unknown or strict-template hosts default to `false`. Setting this
+     * to `true` preserves separate blocks, which is preferred for
+     * KV-cache reuse when the trailing prompt changes between calls.
+     */
+    supportsMultipleSystemMessages?: boolean;
+    /** Whether the provider supports `reasoning_effort`. Default: auto-detected from URL. */
+    supportsReasoningEffort?: boolean;
+    /** Optional mapping from aery-ai reasoning levels to provider/model-specific `reasoning_effort` values. */
+    reasoningEffortMap?: Partial<Record<Effort, string>>;
+    /** 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: auto-detected from URL. */
+    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 tool call IDs must be normalized to Mistral format (exactly 9 alphanumeric chars). Default: auto-detected from URL. */
+    requiresMistralToolIds?: boolean;
+    /** Format for reasoning/thinking parameter. "openai" uses reasoning_effort, "openrouter" uses reasoning: { effort }, "zai" uses thinking: { type: "enabled" | "disabled" } (also used by Moonshot Kimi), "qwen" uses top-level enable_thinking, and "qwen-chat-template" uses chat_template_kwargs.enable_thinking. Default: "openai". */
+    thinkingFormat?: "openai" | "openrouter" | "zai" | "qwen" | "qwen-chat-template";
+    /** Which reasoning content field to emit on assistant messages. Default: auto-detected. */
+    reasoningContentField?: "reasoning_content" | "reasoning" | "reasoning_text";
+    /** Whether assistant tool-call messages must include reasoning content. Default: false. */
+    requiresReasoningContentForToolCalls?: boolean;
+    /** Whether the provider accepts a synthetic placeholder (e.g. ".") for missing reasoning_content on tool-call turns. Default: true. Set to false for providers like DeepSeek that validate the exact reasoning_content value. */
+    allowsSyntheticReasoningContentForToolCalls?: boolean;
+    /** Whether assistant tool-call messages must include non-empty content. Default: false. */
+    requiresAssistantContentForToolCalls?: boolean;
+    /** Whether the provider supports the `tool_choice` parameter. Default: true. */
+    supportsToolChoice?: boolean;
+    /**
+     * Drop reasoning fields (`reasoning_effort`, OpenRouter `reasoning`) for
+     * the request when `tool_choice` forces a tool call. Mirrors the Anthropic
+     * `disableThinkingIfToolChoiceForced` rule for backends like Kimi that
+     * 400 with `tool_choice 'specified' is incompatible with thinking
+     * enabled` whenever both are present. Default: auto-detected (Kimi).
+     */
+    disableReasoningOnForcedToolChoice?: boolean;
+    /**
+     * Drop reasoning fields (`reasoning_effort`, OpenRouter `reasoning`) for
+     * any request that sends `tool_choice`. Use for providers/models that accept
+     * tools and `tool_choice`, but reject `tool_choice` while thinking is enabled.
+     * Default: auto-detected (DeepSeek reasoning models).
+     */
+    disableReasoningOnToolChoice?: boolean;
+    /** 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;
+    /** Extra fields to include in request body (e.g. gateway routing hints for OpenClaw-style proxies). */
+    extraBody?: Record<string, unknown>;
+    /** Whether the provider supports the `strict` field in tool definitions. Default: auto-detected per provider/baseUrl (conservative for unknown providers). */
+    supportsStrictMode?: boolean;
+    /** Whether tool schemas must be sent either all strict or all non-strict. Undefined keeps the existing per-tool mixed behavior. */
+    toolStrictMode?: "all_strict" | "none";
+}
+/**
+ * Compatibility settings for anthropic-messages API.
+ * Use this to disable features that strict-by-default Anthropic accepts but
+ * that proxy gateways (Vertex AI, AWS Bedrock-style fronts, etc.) reject.
+ */
+export interface AnthropicCompat {
+    /**
+     * Drop the top-level `strict: true` field on tool definitions. Vertex AI's
+     * Anthropic-compatible endpoint rejects unknown tool fields with
+     * `tools.<n>.custom.strict: Extra inputs are not permitted`.
+     */
+    disableStrictTools?: boolean;
+    /**
+     * Map adaptive thinking (`thinking: { type: "adaptive" }`) to
+     * `{ type: "enabled", budget_tokens }`. Vertex AI rejects the `adaptive`
+     * tag with `Input tag 'adaptive' ... does not match any of the expected
+     * tags: 'disabled', 'enabled'`.
+     */
+    disableAdaptiveThinking?: boolean;
+    /** Whether tools may include Anthropic's per-tool eager_input_streaming flag. Default: true. */
+    supportsEagerToolInputStreaming?: boolean;
+    /** Whether long prompt-cache retention (`ttl: "1h"`) is supported. Default: true for canonical Anthropic API. */
+    supportsLongCacheRetention?: boolean;
+    /**
+     * Whether mid-conversation `role: "system"` messages are accepted in the
+     * `messages` array (Claude Opus 4.8+ on the first-party Claude API and
+     * Claude Platform on AWS). When unset, auto-detected from the model id and
+     * base URL. Not available on Bedrock, Vertex AI, or Microsoft Foundry.
+     */
+    supportsMidConversationSystem?: boolean;
+}
+/**
+ * OpenRouter provider routing preferences.
+ * Controls which upstream providers OpenRouter routes requests to.
+ * @see https://openrouter.ai/docs/provider-routing
+ */
+export interface OpenRouterRouting {
+    /** List of provider slugs to exclusively use for this request (e.g., ["amazon-bedrock", "anthropic"]). */
+    only?: string[];
+    /** List of provider slugs to try in order (e.g., ["anthropic", "openai"]). */
+    order?: string[];
+}
+/**
+ * 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 = any> {
+    id: string;
+    name: string;
+    api: TApi;
+    provider: Provider;
+    baseUrl: string;
+    reasoning: boolean;
+    input: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    /** Premium Copilot requests charged per user-initiated request (defaults to 1). */
+    premiumMultiplier?: number;
+    contextWindow: number;
+    maxTokens: number;
+    headers?: Record<string, string>;
+    /**
+     * Streaming transport override. When `"aery-native"`, `streamSimple` routes
+     * the request to the model's `baseUrl` via the auth-gateway's
+     * `POST /v1/aery/stream` endpoint instead of dispatching the per-API
+     * provider client. The `baseUrl` must point at an `aery auth-gateway`
+     * (or compatible) host; `headers.Authorization` (or `apiKey` resolved by
+     * the registry) carries the gateway bearer.
+     *
+     * Used by containerized aery installs (e.g. robomp slots) to route every
+     * LLM call through a sidecar gateway that holds the real provider
+     * credentials. The model's other metadata (pricing, context window,
+     * thinking config, …) still resolves locally; only the streaming
+     * dispatch is redirected.
+     */
+    transport?: "aery-native";
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
+    /** Preferred model to switch to when context promotion is triggered (model id or provider/id). */
+    contextPromotionTarget?: string;
+    /** Provider-assigned priority value (lower = higher priority). */
+    priority?: number;
+    /** Canonical thinking capability metadata for this model. */
+    thinking?: ThinkingConfig;
+    /** Compatibility overrides per API. If not set, auto-detected from baseUrl. */
+    compat?: TApi extends "openai-completions" | "openai-responses" ? OpenAICompat : TApi extends "anthropic-messages" ? AnthropicCompat : never;
+    /**
+     * Which shape to use when exposing the Codex `apply_patch` tool to this model.
+     * Generated catalog policy sets `"freeform"` for first-party GPT-5 Responses
+     * models that support OpenAI custom tools with a Lark grammar. The freeform
+     * variant sends a raw patch string with no JSON envelope.
+     * - `"function"` or undefined: JSON function-tool with `{input: string}` (spec §1.2).
+     */
+    applyPatchToolType?: "freeform" | "function";
+    /**
+     * Force OAuth-style request shaping for providers whose API key prefix doesn't
+     * match an OAuth token (e.g. routing Anthropic traffic through a proxy that
+     * expects Claude Code framing). When true, the streaming layer sets
+     * `options.isOAuth = true` for the underlying provider call.
+     */
+    isOAuth?: boolean;
+}