@fractaal/pi-ai 0.85.3 → 0.86.1

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { TelemetryContext } from "@earendil-works/pi-telemetry";
 import type { AnthropicOptions } from "./api/anthropic-messages.ts";
 import type { AzureOpenAIResponsesOptions } from "./api/azure-openai-responses.ts";
 import type { BedrockOptions } from "./api/bedrock-converse-stream.ts";
@@ -13,19 +14,24 @@ import type { AssistantMessageEventStream } from "./utils/event-stream.ts";
 export type { AssistantMessageEventStream } from "./utils/event-stream.ts";
 export type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "pi-messages";
 export type Api = KnownApi | (string & {});
-export type KnownImagesApi = "openrouter-images";
-export type ImagesApi = KnownImagesApi | (string & {});
-export type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "radius" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "opencode" | "opencode-go" | "kimi-coding" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
+export type KnownImageApi = "openrouter-images";
+export type ImageApi = KnownImageApi | (string & {});
+export type KnownClassifierApi = "typesafe-system-one" | "cloudflare-workers-ai-system-one" | "llama-cpp-classify";
+export type ClassifierApi = KnownClassifierApi | (string & {});
+export type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure" | "openai-codex" | "radius" | "typesafe" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
 export type ProviderId = KnownProvider | string;
-export type KnownImagesProvider = "openrouter";
-export type ImagesProviderId = KnownImagesProvider | string;
+export type ToolChoice = "auto" | "none";
 export type ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export type ModelThinkingLevel = "off" | ThinkingLevel;
 export type ThinkingLevelMap = Partial<Record<ModelThinkingLevel, string | null>>;
+export type SamplingParams = Record<string, unknown>;
+export type SamplingParamsByThinkingLevel = Partial<Record<ModelThinkingLevel, SamplingParams>>;
 export type ChatTemplateKwargValue = string | number | boolean | null | {
-    $var: "thinking.enabled" | "thinking.effort";
+    $var: "thinking.enabled" | "thinking.effort" | "thinking.budget";
     omitWhenOff?: boolean;
 };
+/** Top-level request field used to cap reasoning tokens on OpenAI-compatible servers. */
+export type ThinkingTokenBudgetField = "thinking_token_budget" | "thinking_budget" | "thinking_budget_tokens";
 /** Token budgets for each thinking level (token-based providers only) */
 export interface ThinkingBudgets {
     minimal?: number;
@@ -34,6 +40,11 @@ export interface ThinkingBudgets {
     high?: number;
 }
 export type CacheRetention = "none" | "short" | "long";
+/**
+ * Best-effort prompt cache lifetime in seconds for each retention tier a request can ask for.
+ * A missing tier means the lifetime is unknown; pi does not warm such caches.
+ */
+export type ModelPromptCache = Partial<Record<Exclude<CacheRetention, "none">, number>>;
 export type Transport = "sse" | "websocket" | "websocket-cached" | "auto";
 /** Provider-scoped environment overrides. Values take precedence over process.env. */
 export type ProviderEnv = Record<string, string>;
@@ -44,10 +55,11 @@ export interface ProviderResponse {
     status: number;
     headers: Record<string, string>;
 }
-export interface StreamOptions {
-    temperature?: number;
-    maxTokens?: number;
+/** Authentication, HTTP transport, and lifecycle callbacks shared by provider requests. */
+export interface ProviderRequestOptions<TModel = Model<Api>> {
     signal?: AbortSignal;
+    /** Explicit parent context for telemetry produced by this logical request. */
+    telemetryContext?: TelemetryContext;
     apiKey?: string;
     /**
      * Optional fetch implementation for provider HTTP requests.
@@ -56,31 +68,20 @@ export interface StreamOptions {
      */
     fetch?: FetchFunction;
     /**
-     * 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.
+     * Provider-scoped environment values. These take precedence over process.env for
+     * provider configuration such as regional settings, endpoint placeholders, and
+     * proxy variables.
      */
-    sessionId?: string;
+    env?: ProviderEnv;
     /**
      * 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>;
+    onPayload?: (payload: unknown, model: TModel) => unknown | undefined | Promise<unknown | undefined>;
     /**
-     * Optional callback invoked after an HTTP response is received and before
-     * its body stream is consumed.
+     * Optional callback invoked after an HTTP response is received.
      */
-    onResponse?: (response: ProviderResponse, model: Model<Api>) => void | Promise<void>;
+    onResponse?: (response: ProviderResponse, model: TModel) => void | Promise<void>;
     /**
      * Optional custom HTTP headers to include in API requests.
      * Merged with provider defaults; caller values override default headers.
@@ -95,12 +96,6 @@ export interface StreamOptions {
      * For example, OpenAI and Anthropic SDK clients default to 10 minutes.
      */
     timeoutMs?: number;
-    /**
-     * WebSocket connect timeout in milliseconds for providers that support
-     * WebSocket transports. This covers the connection/open handshake only;
-     * stream idleness after connection uses timeoutMs.
-     */
-    websocketConnectTimeoutMs?: number;
     /**
      * Maximum retry attempts for providers/SDKs that support client-side retries.
      * For example, OpenAI and Anthropic SDK clients default to 2.
@@ -114,20 +109,68 @@ export interface StreamOptions {
      * Default: 60000 (60 seconds). Set to 0 to disable the cap.
      */
     maxRetryDelayMs?: number;
+}
+export interface StreamOptions extends ProviderRequestOptions<Model<Api>> {
+    /**
+     * Optional callback invoked after an HTTP response is received and before
+     * its body stream is consumed.
+     */
+    onResponse?: (response: ProviderResponse, model: Model<Api>) => void | Promise<void>;
+    /**
+     * Optional observer for each parsed provider stream event before Pi normalization.
+     * Event data is adapter-owned and must be treated as read-only.
+     * Adapter support is explicit; unsupported adapters do not invoke it.
+     */
+    onProviderStreamEvent?: (data: unknown, model: Model<Api>) => void | Promise<void>;
+    temperature?: number;
+    /**
+     * Arbitrary sampling parameters merged into the request body as-is, after the named request
+     * fields, so keys here override them. Lets custom OpenAI-compatible servers (llama.cpp, vLLM,
+     * SGLang, ...) receive parameters pi does not model, e.g. `top_p`, `top_k`, `min_p`,
+     * `repetition_penalty`. Merged over `Model.samplingParams` per key. Only applied by
+     * OpenAI-compatible adapters (completions, responses, Azure responses); other APIs ignore it.
+     */
+    samplingParams?: SamplingParams;
+    maxTokens?: number;
+    /**
+     * 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;
+    /**
+     * WebSocket connect timeout in milliseconds for providers that support
+     * WebSocket transports. This covers the connection/open handshake only;
+     * stream idleness after connection uses timeoutMs.
+     */
+    websocketConnectTimeoutMs?: 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 DeferredFetchOptions extends ProviderRequestOptions<Model<Api>> {
     /**
-     * Provider-scoped environment values. These take precedence over process.env for
-     * provider configuration such as regional settings, endpoint placeholders, and
-     * proxy variables.
+     * Maximum provider long-poll duration in milliseconds.
+     * Defaults to 0, which performs one status check.
      */
-    env?: ProviderEnv;
+    wait?: number;
 }
-export type ProviderStreamOptions = StreamOptions & Record<string, unknown>;
+/** Request options for best-effort deferred-response cancellation. */
+export type DeferredCancelOptions = ProviderRequestOptions<Model<Api>>;
 /**
  * Maps known APIs to their full provider-specific stream option types.
  * Type-only imports from API implementation modules are erased at emit, so
@@ -152,66 +195,40 @@ export interface ApiOptionsMap {
 export type ApiStreamOptions<TApi extends Api> = TApi extends keyof ApiOptionsMap ? ApiOptionsMap[TApi] : StreamOptions & Record<string, unknown>;
 /**
  * The uniform stream contract of an API implementation module: every module
- * under `src/api/` exports exactly `stream` and `streamSimple`, so the module
- * itself satisfies this interface. Lazy wrappers (`lazyApi()`) and provider
+ * under `src/api/` exports `stream` and `streamSimple`; capable modules may also
+ * export deferred-response methods. Lazy wrappers (`lazyApi()`) and provider
  * factories pass these around as values. This is the untyped dispatch shape;
  * per-API option typing lives on the implementation modules themselves and on
  * `Provider.stream()` via `ApiStreamOptions`.
  */
 export interface ProviderStreams {
-    stream(model: Model<Api>, context: Context, options?: StreamOptions): AssistantMessageEventStream;
-    streamSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+    stream(model: Model<Api>, context: TranscriptContext, options?: StreamOptions): AssistantMessageEventStream;
+    streamSimple(model: Model<Api>, context: TranscriptContext, options?: SimpleStreamOptions): AssistantMessageEventStream;
+    fetchDeferred?(model: Model<Api>, handle: DeferredHandle, options?: DeferredFetchOptions): AssistantMessageEventStream;
+    cancelDeferred?(model: Model<Api>, handle: DeferredHandle, options?: DeferredCancelOptions): Promise<void>;
 }
 /**
  * The uniform contract of an image-generation API implementation module:
  * every image API module under `src/api/` exports exactly `generateImages`,
- * so the module itself satisfies this interface. Lazy wrappers and image
- * provider factories pass these around as values.
+ * so the module itself satisfies this interface. Lazy wrappers and
+ * `createProvider({ images })` pass these around as values.
  */
 export interface ProviderImages {
-    generateImages(model: ImagesModel<ImagesApi>, context: ImagesContext, options?: ImagesOptions): Promise<AssistantImages>;
+    generateImages(model: ImageModel<ImageApi>, context: ImagesContext, options?: ImagesOptions): Promise<AssistantImages>;
 }
-export interface ImagesOptions {
-    signal?: AbortSignal;
-    apiKey?: string;
-    /** Optional fetch implementation for provider HTTP requests. Defaults to `globalThis.fetch`. */
-    fetch?: FetchFunction;
-    /**
-     * Provider-scoped environment values. These take precedence over process.env for
-     * provider configuration such as endpoint placeholders and proxy variables.
-     */
-    env?: ProviderEnv;
-    /**
-     * Optional callback for inspecting or replacing provider payloads before sending.
-     * Return undefined to keep the payload unchanged.
-     */
-    onPayload?: (payload: unknown, model: ImagesModel<ImagesApi>) => unknown | undefined | Promise<unknown | undefined>;
-    /**
-     * Optional callback invoked after an HTTP response is received.
-     */
-    onResponse?: (response: ProviderResponse, model: ImagesModel<ImagesApi>) => void | Promise<void>;
-    /**
-     * Optional custom HTTP headers to include in API requests.
-     * Merged with provider defaults; can override default headers.
-     * A null value suppresses a provider/API default header with the same name.
-     */
-    headers?: ProviderHeaders;
-    /**
-     * 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;
+/** The uniform contract implemented by classifier API modules. */
+export interface ProviderClassifier {
+    classify(model: ClassifierModel<ClassifierApi>, context: ClassifierContext, options?: ClassifierOptions): Promise<ClassifierResult>;
+}
+export interface ClassifierOptions extends ProviderRequestOptions<ClassifierModel<ClassifierApi>> {
     /**
-     * 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.
+     * Divides the answer logits by this value before they are normalized into probabilities.
+     * Values above 1 soften the distribution; values below 1 sharpen it. Must be positive.
+     * APIs that cannot apply it ignore it.
      */
-    maxRetryDelayMs?: number;
+    temperature?: number;
+}
+export interface ImagesOptions extends ProviderRequestOptions<ImageModel<ImageApi>> {
     /**
      * Optional metadata to include in API requests.
      * Providers extract the fields they understand and ignore the rest.
@@ -219,13 +236,25 @@ export interface ImagesOptions {
     metadata?: Record<string, unknown>;
 }
 export type ProviderImagesOptions = ImagesOptions & Record<string, unknown>;
+export interface AnthropicAllowedFallbackModel {
+    provider: ProviderId;
+    model: string;
+    cost: ModelCost;
+}
 export interface SimpleStreamOptions extends StreamOptions {
+    /** Provider-neutral tool selection for simple requests. When omitted, adapters use provider-specific behavior. */
+    toolChoice?: ToolChoice;
     reasoning?: ThinkingLevel;
+    /** Ask a capable provider to return a durable handle and continue the request asynchronously. */
+    deferred?: boolean | {
+        window?: "15m" | "1h" | "24h";
+    };
     /** Custom token budgets for thinking levels (token-based providers only) */
     thinkingBudgets?: ThinkingBudgets;
 }
-export type StreamFunction<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = (model: Model<TApi>, context: Context, options?: TOptions) => AssistantMessageEventStream;
-export type ImagesFunction<TApi extends ImagesApi = ImagesApi, TOptions extends ImagesOptions = ImagesOptions> = (model: ImagesModel<TApi>, context: ImagesContext, options?: TOptions) => Promise<AssistantImages>;
+export type StreamFunction<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = (model: Model<TApi>, context: TranscriptContext, options?: TOptions) => AssistantMessageEventStream;
+export type ImagesFunction<TOptions extends ImagesOptions = ImagesOptions> = (model: ImageModel<ImageApi>, context: ImagesContext, options?: TOptions) => Promise<AssistantImages>;
+export type ClassifierFunction<TOptions extends ClassifierOptions = ClassifierOptions> = (model: ClassifierModel<ClassifierApi>, context: ClassifierContext, options?: TOptions) => Promise<ClassifierResult>;
 export interface TextSignatureV1 {
     v: 1;
     id: string;
@@ -254,8 +283,10 @@ export interface ToolCall {
     type: "toolCall";
     id: string;
     name: string;
-    arguments: Record<string, any>;
+    arguments: JsonObject;
     thoughtSignature?: string;
+    /** OpenAI Responses namespace for calls to dynamically loaded or namespaced tools. */
+    namespace?: string;
 }
 export interface Usage {
     input: number;
@@ -279,7 +310,62 @@ export interface Usage {
         total: number;
     };
 }
-export type StopReason = "pending" | "stop" | "length" | "toolUse" | "error" | "aborted";
+export type StopReason = "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject;
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type IsExactlyJsonValue<T> = [T] extends [JsonValue] ? ([JsonValue] extends [T] ? true : false) : false;
+type IsJsonProperty<T> = IsAny<T> extends true ? false : unknown extends T ? false : [Exclude<T, undefined>] extends [never] ? true : IsJsonCompatible<Exclude<T, undefined>>;
+type InvalidJsonKeys<T extends object> = {
+    [TKey in keyof T]-?: TKey extends string | number ? (IsJsonProperty<T[TKey]> extends true ? never : TKey) : TKey;
+}[keyof T];
+type IsJsonCompatible<T> = IsAny<T> extends true ? false : unknown extends T ? false : IsExactlyJsonValue<T> extends true ? true : T extends null | boolean | number | string ? true : T extends undefined ? false : T extends readonly (infer TItem)[] ? IsJsonCompatible<TItem> : T extends (...args: never[]) => unknown ? false : T extends object ? [InvalidJsonKeys<T>] extends [never] ? true : false : false;
+/** The JSON representation of a typed in-memory value. Optional object properties remain optional. */
+export type JsonRepresentation<T> = IsAny<T> extends true ? JsonValue : unknown extends T ? JsonValue : [T] extends [JsonValue] ? T : T extends readonly unknown[] ? {
+    [TKey in keyof T]: JsonRepresentation<Exclude<T[TKey], undefined>>;
+} : T extends object ? {
+    [TKey in keyof T]: JsonRepresentation<Exclude<T[TKey], undefined>>;
+} : never;
+export interface DeferredHandle {
+    provider: string;
+    modelId: string;
+    api: string;
+    /** Provider token, such as a response id or batch id plus row id. */
+    id: string;
+    expiresAt?: number;
+    pollAfterMs?: number;
+    /** Provider conversion data required to reconstruct the final assistant message. */
+    data?: JsonValue;
+}
+/**
+ * System instructions and tool declarations at one point in the transcript.
+ *
+ * The leading system message is the system prompt. Later system messages change it:
+ * `content` adds instructions from that point on, `sections` replace or remove named
+ * prompt sections, and `toolsAdded`/`toolsRemoved` change the tool set. Replaying
+ * every system message in order yields the current prompt and tools. Providers that
+ * accept system messages mid-conversation send each one in place; other providers
+ * rebuild the leading system message from the replayed state.
+ */
+export interface SystemMessage {
+    role: "system";
+    /** Instruction text. On the leading message this is the base prompt; later, additional instructions. */
+    content: string | TextContent[];
+    /**
+     * Named, ordered prompt sections rendered verbatim after `content`. The leading message
+     * declares them; later messages replace sections by name, and `null` removes one. Keep
+     * each section self-delimiting (a tag, a heading) so the model can relate an update to
+     * the original. Avoid integer-like names; JSON objects reorder those.
+     */
+    sections?: Record<string, string | null>;
+    /** Complete definitions of tools that become available at this point. */
+    toolsAdded?: Tool[];
+    /** Tools that stop being available at this point. */
+    toolsRemoved?: ToolReference[];
+    timestamp: number;
+}
 export interface UserMessage {
     role: "user";
     content: string | (TextContent | ImageContent)[];
@@ -293,31 +379,57 @@ export interface AssistantMessage {
     model: string;
     responseModel?: string;
     responseId?: string;
+    /** Exact provider-native effort level used for this response. Absent for legacy or unmanaged responses. */
+    providerThinkingLevel?: string;
+    /** Pi thinking level the agent loop requested for this response. Absent outside the agent loop and for legacy responses. */
+    thinkingLevel?: ModelThinkingLevel;
     diagnostics?: AssistantMessageDiagnostic[];
     usage: Usage;
     stopReason: StopReason;
+    deferred?: DeferredHandle;
     errorMessage?: string;
     rawStopReason?: string;
+    /**
+     * Provider indication of whether the model explicitly ended its turn.
+     * Preserved for debugging and does not currently affect agent control flow.
+     */
+    endTurn?: boolean;
     timestamp: number;
 }
-export interface ToolResultMessage<TDetails = any> {
+/** A tool call that another tool made while it ran, for example from a codemode script. */
+export interface NestedToolCallRecord {
+    id: string;
+    name: string;
+    /** Omitted when over the size limits; `argumentsBytes` then gives their size. */
+    arguments?: JsonObject;
+    /** UTF-8 size of the arguments as JSON, set when `arguments` is omitted. */
+    argumentsBytes?: number;
+    /** `unfinished`: the call was still running when the calling tool finished. */
+    status: "ok" | "error" | "unfinished";
+    durationMs?: number;
+    /** Error text, truncated. */
+    error?: string;
+}
+/** Bounded record of the nested calls a tool made. Results are not recorded. */
+export interface NestedToolCalls {
+    calls: NestedToolCallRecord[];
+    /** False when calls were dropped, arguments omitted, or calls had not finished. */
+    complete: boolean;
+}
+export type ToolResultMessage<TDetails = JsonValue> = IsJsonCompatible<TDetails> extends true ? {
     role: "toolResult";
     toolCallId: string;
     toolName: string;
     content: (TextContent | ImageContent)[];
-    details?: TDetails;
+    details?: JsonRepresentation<TDetails>;
     /** Usage from the tool execution itself, if available. Not part of main LLM context accounting. */
     usage?: Usage;
-    /**
-     * Names from `Context.tools` that became available after this result.
-     * Providers with native deferred tool loading use this as the load point;
-     * other providers ignore it and use `Context.tools` normally.
-     */
-    addedToolNames?: string[];
+    /** Calls this tool made to other tools. Kept for the session record; not sent to the model. */
+    nestedCalls?: NestedToolCalls;
     isError: boolean;
     timestamp: number;
-}
-export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+} : never;
+export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
 export type ImagesInputContent = TextContent | ImageContent;
 export type ImagesOutputContent = TextContent | ImageContent;
 export interface ImagesContext {
@@ -325,8 +437,8 @@ export interface ImagesContext {
 }
 export type ImagesStopReason = "stop" | "error" | "aborted";
 export interface AssistantImages {
-    api: ImagesApi;
-    provider: ImagesProviderId;
+    api: ImageApi;
+    provider: ProviderId;
     model: string;
     output: ImagesOutputContent[];
     responseId?: string;
@@ -335,6 +447,57 @@ export interface AssistantImages {
     errorMessage?: string;
     timestamp: number;
 }
+export interface ClassifierChoiceQuestion {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+}
+export interface ClassifierScoreQuestion {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+}
+export interface ClassifierBoolQuestion {
+    type: "bool";
+    instructions: string;
+    criteria: {
+        true: string;
+        false: string;
+    };
+}
+export type ClassifierQuestion = ClassifierChoiceQuestion | ClassifierScoreQuestion | ClassifierBoolQuestion;
+export interface ClassifierContext {
+    state: JsonObject;
+    questions: Record<string, ClassifierQuestion>;
+}
+export interface ClassifierChoiceAnswer {
+    type: "choice";
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence: number;
+}
+export interface ClassifierScoreAnswer {
+    type: "score";
+    score: number;
+    confidence: number;
+}
+export interface ClassifierBoolAnswer {
+    type: "bool";
+    probability: number;
+}
+export type ClassifierAnswer = ClassifierChoiceAnswer | ClassifierScoreAnswer | ClassifierBoolAnswer;
+export type ClassifierStopReason = "stop" | "error" | "aborted";
+export interface ClassifierResult {
+    api: ClassifierApi;
+    provider: ProviderId;
+    model: string;
+    answers: Record<string, ClassifierAnswer>;
+    /** Token usage and its cost at the model's catalog price, when the service reports token counts. */
+    usage?: Usage;
+    stopReason: ClassifierStopReason;
+    errorMessage?: string;
+    timestamp: number;
+}
 import type { TSchema } from "typebox";
 /** OpenAI grammar variants for constrained sampling. */
 export type GrammarFormat = "openai_lark" | "openai_regex";
@@ -359,18 +522,46 @@ export interface Tool<TParameters extends TSchema = TSchema> {
     parameters: TParameters;
     constrainedSampling?: false | ConstrainedSamplingConfig;
 }
+export interface ToolReference {
+    name: string;
+}
+/**
+ * Request input accepted by the public stream entry points (`Models.stream()`,
+ * `streamSimple()`, ...). `systemPrompt` and `tools` are shorthand for a leading
+ * system message; `normalizeContext()` folds them into one before the request
+ * reaches a provider.
+ */
 export interface Context {
     systemPrompt?: string;
     messages: Message[];
     tools?: Tool[];
 }
+declare const transcriptContextBrand: unique symbol;
+/**
+ * Normalized request context passed to providers and API implementations. The
+ * prompt and tool declarations are carried by the transcript's system messages.
+ * Only `normalizeContext()` produces this type, so a raw `Context` cannot reach
+ * provider code by accident.
+ */
+export type TranscriptContext = {
+    messages: Message[];
+    readonly [transcriptContextBrand]: true;
+};
 /**
  * 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.
+ * Successful streams emit `start` before partial updates and terminate with
+ * `done`. A stream may terminate directly with `error` when request setup fails
+ * before generation starts; after `start`, failures also terminate with `error`.
+ * Direct `streamSimple()` calls throw synchronously when request auth is missing.
+ * Updates and `done` must never appear before `start`.
+ *
+ * `partial` is the shared live response-so-far helper, not an event-time
+ * snapshot. Text and thinking blocks are empty when their `*_start` event is
+ * emitted and grow only through their corresponding `*_delta` events until the
+ * authoritative `*_end`. Redacted thinking may be complete at start and emit no
+ * deltas. Tool-call arguments at `toolcall_start` are provider-specific;
+ * `toolcall_delta` carries subsequent JSON updates.
  */
 export type AssistantMessageEvent = {
     type: "start";
@@ -419,7 +610,7 @@ export type AssistantMessageEvent = {
     partial: AssistantMessage;
 } | {
     type: "done";
-    reason: Extract<StopReason, "stop" | "length" | "toolUse">;
+    reason: Extract<StopReason, "stop" | "length" | "toolUse" | "deferred">;
     message: AssistantMessage;
 } | {
     type: "error";
@@ -439,6 +630,8 @@ export interface OpenAICompletionsCompat {
     supportsReasoningEffort?: boolean;
     /** Whether the provider supports `stream_options: { include_usage: true }` for token usage in streaming responses. Default: true. */
     supportsUsageInStreaming?: boolean;
+    /** Whether streamed responses include `finish_reason`. When false, pi infers `stop` or `toolUse` when the stream ends. Default: true. */
+    supportsFinishReason?: 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. */
@@ -449,35 +642,58 @@ export interface OpenAICompletionsCompat {
     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 when supported, "together" uses reasoning: { enabled } plus reasoning_effort when supported, "zai" uses thinking: { type }, "qwen" uses top-level enable_thinking: boolean, "qwen-chat-template" uses chat_template_kwargs.enable_thinking and preserve_thinking, "chat-template" uses configurable chat_template_kwargs, "string-thinking" uses top-level thinking: string, and "ant-ling" uses reasoning: { effort } only when the mapped effort is non-null. Default: "openai". */
-    thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling";
-    /** Kwargs to send as `chat_template_kwargs` when `thinkingFormat` is `chat-template`. Use `{ "$var": "thinking.enabled" }` or `{ "$var": "thinking.effort" }` for pi-controlled thinking values. */
+    /** Format for reasoning/thinking parameter. "openai" uses reasoning_effort, "openrouter" uses reasoning: { effort }, "deepseek" uses thinking: { type } plus reasoning_effort when supported, "together" uses reasoning: { enabled } plus reasoning_effort when supported, "baseten" uses configurable chat_template_args plus reasoning_effort when supported, "zai" uses thinking: { type }, "qwen" uses top-level enable_thinking: boolean, "qwen-chat-template" uses chat_template_kwargs.enable_thinking and preserve_thinking, "chat-template" uses configurable chat_template_kwargs, "string-thinking" uses top-level thinking: string, and "ant-ling" uses reasoning: { effort } only when the mapped effort is non-null. Default: "openai". */
+    thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "baseten" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling";
+    /** Kwargs to send as `chat_template_kwargs` when `thinkingFormat` is `chat-template`. Use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values. */
     chatTemplateKwargs?: Record<string, ChatTemplateKwargValue>;
+    /** Arguments to send as `chat_template_args` when `thinkingFormat` is `baseten`. Use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values. */
+    chatTemplateArgs?: Record<string, ChatTemplateKwargValue>;
     /** OpenRouter-compatible routing preferences sent as the `provider` request field. */
     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;
+    /**
+     * Top-level request field used to cap reasoning tokens from `thinkingBudgets`.
+     * Reasoning and the answer share `max_tokens` on these endpoints, so without a budget a
+     * reasoning-heavy turn can consume the whole response and emit no answer.
+     * `"thinking_token_budget"` is vLLM, `"thinking_budget"` is Qwen/DashScope/SGLang,
+     * `"thinking_budget_tokens"` is llama.cpp. Off by default; not set on the generated catalog.
+     */
+    thinkingTokenBudgetField?: ThinkingTokenBudgetField;
+    /** Alias for `thinkingTokenBudgetField: "thinking_token_budget"` (vLLM). Prefer `thinkingTokenBudgetField`. Default: false. */
+    supportsThinkingTokenBudget?: boolean;
     /** Whether the provider supports OpenAI custom tools with Lark/regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. Default: false; the generated model catalog enables it for capable models. */
     supportsOpenAIGrammarTools?: boolean;
-    /** Whether the provider supports the `strict` field in tool definitions. Default: true. */
+    /** Whether the exact model accepts system or developer messages after the conversation has started. When false, later system messages are folded into the leading system message. Default: false; the generated model catalog enables it for verified models. */
+    supportsMidConvoSystemMessages?: boolean;
+    /** Whether system messages can introduce additional tools mid-conversation. Requires `supportsMidConvoSystemMessages`. Default: false; the generated model catalog enables it for capable models. */
+    supportsMidConvoToolAdditions?: boolean;
+    /** Whether the provider supports the `strict` field in tool definitions. Default: false; generated capable models enable it explicitly. */
     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, or tool-result text content. */
     cacheControlFormat?: "anthropic";
-    /** Whether to send session-affinity data from `options.sessionId`. Default: false. */
+    /** Whether to send session-affinity data from `options.sessionId`. Default: true for OpenRouter endpoints, false otherwise. */
     sendSessionAffinityHeaders?: boolean;
-    /** Provider-specific deferred tool serialization mode. */
-    deferredToolsMode?: "kimi";
     /** Session-affinity header format: `openai` sends `session_id`, `x-client-request-id`, and `x-session-affinity`; `openai-nosession` sends `x-client-request-id` and `x-session-affinity`; `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param, which is governed by cache retention. Default: auto-detected. */
     sessionAffinityFormat?: SessionAffinityFormat;
     /** 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;
+    /**
+     * vLLM scheduler priority sent as the top-level `priority` request field (lower values are
+     * handled earlier; server default 0). Only meaningful when vLLM runs with
+     * `--scheduling-policy priority`; useful for keeping background/batch work from stalling
+     * interactive sessions. Off by default; not set on the generated catalog.
+     */
+    vllmPriority?: number;
 }
 /** Compatibility settings for OpenAI Responses APIs. */
 export interface OpenAIResponsesCompat {
     /** Whether the provider supports the `developer` role (vs `system`). Default: true. */
     supportsDeveloperRole?: boolean;
+    /** Whether the exact model accepts developer or system messages after the conversation has started. When false, later system messages are folded into the leading system message. Default: false; the generated model catalog enables it for verified models. */
+    supportsMidConvoSystemMessages?: boolean;
     /** Session-affinity header format: `openai` sends `session_id` and `x-client-request-id`; `openai-nosession` sends `x-client-request-id`; `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param, which is governed by cache retention. Default: auto-detected. */
     sessionAffinityFormat?: SessionAffinityFormat;
     /** Whether the provider supports long prompt cache retention. This uses `prompt_cache_options.ttl: "30m"` on GPT-5.6+ and `prompt_cache_retention: "24h"` on earlier models. Default: true. */
@@ -486,10 +702,14 @@ export interface OpenAIResponsesCompat {
     supportsStrictMode?: boolean;
     /** Whether to emit OpenAI custom tools with Lark/regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. Default: false; the generated model catalog enables it for capable models. */
     supportsOpenAIGrammarTools?: boolean;
-    /** Whether the model supports client-executed tool search for deferred tools. Default: false. */
+    /** Whether the model supports message-anchored `additional_tools` input items. Default: false. */
+    supportsAdditionalTools?: boolean;
+    /** Whether the model supports client-executed tool search for transcript-anchored additions. Default: false. */
     supportsToolSearch?: boolean;
-    /** Whether the model accepts `prompt_cache_options` (OpenAI GPT-5.6+ prompt caching). Older models reject the parameter. Default: false. */
+    /** Whether the model accepts `prompt_cache_options` (OpenAI GPT-5.6+ prompt caching). Older OpenAI models reject the parameter. Default: false. */
     supportsExplicitPromptCacheMode?: boolean;
+    /** Whether the provider accepts the `max_output_tokens` parameter. Some Codex-protocol gateways reject it. Default: true. */
+    supportsMaxOutputTokens?: boolean;
 }
 /** Compatibility settings for Anthropic Messages-compatible APIs. */
 export interface AnthropicMessagesCompat {
@@ -511,6 +731,8 @@ export interface AnthropicMessagesCompat {
      * Default: false.
      */
     sendSessionAffinityHeaders?: boolean;
+    /** Session-affinity format. `"openrouter"` sends `x-session-id`; when unset, sends `x-session-affinity`. */
+    sessionAffinityFormat?: "openrouter";
     /**
      * Whether the provider supports Anthropic-style `cache_control` markers on
      * tool definitions. When false, `cache_control` is omitted from tool params.
@@ -539,18 +761,30 @@ export interface AnthropicMessagesCompat {
     allowEmptySignature?: boolean;
     /** Whether the provider supports Anthropic strict tool schemas. Default: false; generated Anthropic models enable it explicitly. */
     supportsStrictTools?: boolean;
+    /** Whether the exact model transport supports effort-only system messages and thinking binding controls. Default: false. */
+    supportsMidConvoEffort?: boolean;
+    /** Whether the exact model accepts system-role messages inside the conversation. When false, later system messages are folded into the top-level system prompt. Default: false. */
+    supportsMidConvoSystemMessages?: boolean;
+    /** Whether the exact model accepts mid-conversation `tool_addition` blocks with inline tool definitions (`inline-tools-2026-09-15`) and `tool_removal` blocks. Requires `supportsMidConvoSystemMessages`. Default: false. */
+    supportsMidConvoToolChanges?: boolean;
     /**
-     * Whether the provider supports deferred tools loaded by `tool_reference`
-     * blocks in tool results. Default: true for first-party Anthropic models
-     * except Haiku and models older than Claude 4.5; false for other providers.
+     * Models Anthropic accepts in `fallbacks` for server-side refusal fallback,
+     * with local pricing metadata for returned fallback responses. When absent or
+     * empty, callers must omit `fallbacks`; Anthropic rejects the field for models
+     * with no permitted fallback targets.
      */
-    supportsToolReferences?: boolean;
+    allowedFallbackModels?: AnthropicAllowedFallbackModel[];
 }
 /** Compatibility settings for Amazon Bedrock models. */
 export interface BedrockCompat {
     /** Whether the model supports Bedrock strict tool schemas. Default: false. */
     supportsStrictMode?: boolean;
 }
+/** Compatibility settings for the Mistral chat API. */
+export interface MistralConversationsCompat {
+    /** Whether the exact model accepts system messages after the conversation has started. When false, later system messages are folded into the leading system message. Default: false. */
+    supportsMidConvoSystemMessages?: boolean;
+}
 /**
  * OpenRouter provider routing preferences.
  * Controls which upstream providers OpenRouter routes requests to.
@@ -644,29 +878,86 @@ export interface ModelCost extends ModelCostRates {
     /** Request-wide pricing tiers. The highest matching input threshold applies to the full request. */
     tiers?: ModelCostTier[];
 }
-export interface Model<TApi extends Api> {
+export interface ModelImageResizeOptions {
+    maxWidth?: number;
+    maxHeight?: number;
+    /** Maximum base64-encoded payload size in bytes. */
+    maxBytes?: number;
+    jpegQuality?: number;
+}
+export interface ModelImageInputLimits {
+    /** Cache-safe resize profile applied before a new image enters conversation history. */
+    resize?: ModelImageResizeOptions;
+    /** Maximum images accepted in one provider message. */
+    maxPerMessage?: number;
+    /** Maximum images accepted across one provider request. */
+    maxPerRequest?: number;
+}
+export interface ModelInputLimits {
+    /** Maximum serialized provider request size in bytes. */
+    maxRequestBytes?: number;
+    images?: ModelImageInputLimits;
+}
+/** Fields shared by every catalog entry, regardless of what you can do with it. */
+export interface BaseModel<TApi extends string> {
     id: string;
     name: string;
     api: TApi;
     provider: ProviderId;
     baseUrl: string;
+    input: ("text" | "image")[];
+    /** Provider input limits and cache-safe preprocessing metadata. */
+    inputLimits?: ModelInputLimits;
+    cost: ModelCost;
+    headers?: Record<string, string>;
+}
+/** Chat model: usable with `stream()` and friends. */
+export interface Model<TApi extends Api> extends BaseModel<TApi> {
+    /**
+     * Optional: chat is the default model type, so models without `type` are chat
+     * models. Narrow mixed model lists with `isModelType()` instead of comparing
+     * `type` directly.
+     */
+    type?: "chat";
     reasoning: boolean;
     /**
      * Maps pi thinking levels to provider/model-specific values.
      * Missing keys use provider defaults. null marks a level as unsupported.
      */
     thinkingLevelMap?: ThinkingLevelMap;
-    input: ("text" | "image")[];
-    cost: ModelCost;
+    /** Prompt cache lifetimes per retention tier. Unset when the provider's cache behavior is unknown. */
+    promptCache?: ModelPromptCache;
+    /** Default context budget. A larger provider-supported opt-in limit may be advertised separately. */
     contextWindow: number;
+    /** Provider-supported context ceiling; does not automatically change the default budget. */
+    maxContextWindow?: number;
     maxTokens: number;
-    headers?: Record<string, string>;
+    /** Default sampling parameters for this model. See {@link StreamOptions.samplingParams}; per-request keys override these. */
+    samplingParams?: SamplingParams;
+    /** Sampling parameter overrides selected by the effective pi thinking level. */
+    samplingParamsByThinkingLevel?: SamplingParamsByThinkingLevel;
     /** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
-    compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" | "azure-openai-responses" | "openai-codex-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : TApi extends "bedrock-converse-stream" ? BedrockCompat : never;
+    compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" | "azure-openai-responses" | "openai-codex-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : TApi extends "bedrock-converse-stream" ? BedrockCompat : TApi extends "mistral-conversations" ? MistralConversationsCompat : never;
 }
-export interface ImagesModel<TApi extends ImagesApi> extends Omit<Model<Api>, "api" | "provider" | "reasoning" | "contextWindow" | "maxTokens" | "compat"> {
-    api: TApi;
-    provider: ImagesProviderId;
+/** Image-generation model: usable with `generateImages()` only. */
+export interface ImageModel<TApi extends ImageApi> extends BaseModel<TApi> {
+    type: "image";
+    /** Output modalities. Always includes `"image"`; `"text"` means the model can also return text blocks. */
     output: ("text" | "image")[];
 }
+/** Structured classifier model: usable with `classify()` only. */
+export interface ClassifierModel<TApi extends ClassifierApi> extends BaseModel<TApi> {
+    type: "classifier";
+    contextWindow: number;
+}
+/** Model shape for each model type. */
+export interface ModelTypeMap {
+    chat: Model<Api>;
+    image: ImageModel<ImageApi>;
+    classifier: ClassifierModel<ClassifierApi>;
+}
+/** What a catalog entry is for. Decides which `Models` operation accepts it. */
+export type ModelType = keyof ModelTypeMap;
+/** Anything a provider can list. Narrow with `isModelType()`. */
+export type AnyModel = ModelTypeMap[ModelType];
 //# sourceMappingURL=types.d.ts.map