@fgv/ts-extras 5.1.0-4 → 5.1.0-40

package/lib/packlets/ai-assist/model.d.ts

@@ -3,6 +3,50 @@
  * @packageDocumentation
  */
 import { type Result } from '@fgv/ts-utils';
+import { type JsonObject, type JsonSchema } from '@fgv/ts-json-base';
+/**
+ * Universal image representation used for both image input (vision prompts)
+ * and image output (generation responses).
+ *
+ * @remarks
+ * The base64 string is raw — no `data:` URL prefix. Use {@link AiAssist.toDataUrl} to
+ * format it for browser-display contexts.
+ *
+ * @public
+ */
+export interface IAiImageData {
+    /** MIME type, e.g. `'image/png'`, `'image/jpeg'`, `'image/webp'`. */
+    readonly mimeType: string;
+    /** Base64-encoded image bytes (no `data:` prefix). */
+    readonly base64: string;
+}
+/**
+ * Formats an {@link IAiImageData} as a `data:` URL suitable for browser display.
+ * @param image - The image to format
+ * @returns A `data:<mime>;base64,<data>` URL string
+ * @public
+ */
+export declare function toDataUrl(image: IAiImageData): string;
+/**
+ * Image attachment for a vision (image-input) prompt.
+ *
+ * @remarks
+ * Extends {@link IAiImageData} with an OpenAI-specific `detail` hint that is
+ * silently ignored by Anthropic, Gemini, and other providers.
+ *
+ * @public
+ */
+export interface IAiImageAttachment extends IAiImageData {
+    /**
+     * OpenAI vision detail hint:
+     * - `'low'`: faster, cheaper, lower fidelity
+     * - `'high'`: slower, more expensive, higher fidelity
+     * - `'auto'` (default): provider chooses
+     *
+     * Ignored by providers other than OpenAI.
+     */
+    readonly detail?: 'low' | 'high' | 'auto';
+}
 /**
  * A structured AI prompt with system/user split for direct API calls,
  * and a lazily-constructed combined version for copy/paste workflows.
@@ -13,9 +57,28 @@ export declare class AiPrompt {
     readonly system: string;
     /** User request: the specific entity generation request. */
     readonly user: string;
-    constructor(user: string, system: string);
-    /** Combined single-string version (user + system joined) for copy/paste. */
+    /**
+     * Optional image attachments. When present, vision-capable providers will
+     * include them in the user message; non-vision providers will reject the
+     * call up front (see {@link AiAssist.IAiProviderDescriptor.acceptsImageInput}).
+     */
+    readonly attachments: ReadonlyArray<IAiImageAttachment>;
+    constructor(user: string, system: string, attachments?: ReadonlyArray<IAiImageAttachment>);
+    /**
+     * Combined single-string version (user + system joined) for copy/paste.
+     * When attachments are present, includes a sentinel noting they aren't
+     * part of the copied text.
+     */
     get combined(): string;
+    /**
+     * Lowers this prompt to the unified {@link AiAssist.IChatRequest} shape consumed
+     * by the turn entry points (`callProviderCompletion`,
+     * `callProviderCompletionStream`, `generateJsonCompletion`,
+     * `executeClientToolTurn`). The prompt becomes a single current `user` turn
+     * (carrying any attachments) with the system instructions in the distinct
+     * `system` field.
+     */
+    toRequest(): IChatRequest;
 }
 /**
  * A single chat message in OpenAI format.
@@ -26,6 +89,40 @@ export interface IChatMessage {
     readonly role: 'system' | 'user' | 'assistant';
     /** Message content */
     readonly content: string;
+    /**
+     * Optional image attachments. Only honoured on the **current turn** (the last
+     * message of an {@link AiAssist.IChatRequest}); vision-capable providers include
+     * them in that user message, non-vision providers reject the call up front (see
+     * {@link AiAssist.IAiProviderDescriptor.acceptsImageInput}). Attachments on
+     * history (non-final) messages are ignored.
+     */
+    readonly attachments?: ReadonlyArray<IAiImageAttachment>;
+}
+/**
+ * An ordered chat request: optional system instructions plus the conversation
+ * turns. The **last** entry in `messages` is the current turn (always a `user`
+ * turn); everything before it is prior conversation history.
+ *
+ * @remarks
+ * This is the unified shape accepted by every turn entry point. Both the
+ * completion path and the client-tool turn path linearize it identically:
+ * `[system, ...history, current user turn, ...continuation]`. Keeping `system`
+ * as a distinct field (rather than a `system`-role message) matches how the
+ * per-provider request builders already separate system from the turn list
+ * (Anthropic top-level `system`, Gemini `systemInstruction`, OpenAI a leading
+ * `system`-role message). `messages` should therefore carry only `user` /
+ * `assistant` turns.
+ *
+ * @public
+ */
+export interface IChatRequest {
+    /** System instructions (schema docs, format rules, general guidance). */
+    readonly system?: string;
+    /**
+     * The ordered conversation turns. Must be non-empty; the last entry is the
+     * current `user` turn and the preceding entries are history.
+     */
+    readonly messages: ReadonlyArray<IChatMessage>;
 }
 /**
  * Built-in server-side tool types supported across providers.
@@ -69,11 +166,230 @@ export interface IAiToolEnablement {
     /** Optional tool-specific configuration. */
     readonly config?: AiServerToolConfig;
 }
+/**
+ * Behavior annotations for a client-defined tool.
+ *
+ * @remarks
+ * These are **host-advisory-only hints** describing a tool's side-effect profile.
+ * They are consumed by the host's tool loop (e.g. a before-execute gate) and are
+ * **never serialized to the model** — the provider wire tool-schemas whitelist
+ * `{name, description, parameters}` and ignore this field.
+ *
+ * Field names mirror MCP's `ToolAnnotations` (`@modelcontextprotocol/sdk`) 1:1 so
+ * an MCP tool's annotations pass through unchanged. Per the MCP spec, all fields
+ * are hints — a host should never make tool-use decisions based on annotations
+ * received from an untrusted server without its own validation.
+ *
+ * @public
+ */
+export interface IAiToolAnnotations {
+    /** Optional human-readable display title for the tool. */
+    readonly title?: string;
+    /** Hint: the tool does not modify its environment (read-only). */
+    readonly readOnlyHint?: boolean;
+    /** Hint: the tool may perform destructive updates (only meaningful when not read-only). */
+    readonly destructiveHint?: boolean;
+    /** Hint: repeated calls with the same arguments have no additional effect. */
+    readonly idempotentHint?: boolean;
+    /** Hint: the tool interacts with an open world of external entities. */
+    readonly openWorldHint?: boolean;
+}
+/**
+ * Configuration for a client-defined (harness-supplied) tool.
+ *
+ * @remarks
+ * The `parametersSchema` is the single source of truth for both the wire-format
+ * JSON Schema sent to the provider (via `.toJson()`) and the runtime argument
+ * validation (via `.validate(rawArgs)`). Use `JsonSchema.object(...)` from
+ * `@fgv/ts-json-base` to author the schema as a const (e.g. `const mySchema = JsonSchema.object({...})`);
+ * the static type `TParams` is then derived via `JsonSchema.Static<typeof mySchema>` —
+ * no drift between wire schema and runtime validation.
+ *
+ * @public
+ */
+export interface IAiClientToolConfig<TParams = unknown> {
+    /** Discriminator — always `'client_tool'`. */
+    readonly type: 'client_tool';
+    /** Tool name sent to the model (must be unique within a call). */
+    readonly name: string;
+    /** Human-readable description of what the tool does, shown to the model. */
+    readonly description: string;
+    /**
+     * JSON Schema validator for the tool's parameters. Emits wire format via
+     * `.toJson()` and validates model-returned args via `.validate(rawArgs)`.
+     */
+    readonly parametersSchema: JsonSchema.ISchemaValidator<TParams>;
+    /**
+     * Optional host-advisory behavior annotations (read-only / destructive /
+     * idempotent / open-world hints + display title). Consumed by the host's
+     * tool loop; never serialized to the model. See {@link IAiToolAnnotations}.
+     */
+    readonly annotations?: IAiToolAnnotations;
+}
+/**
+ * A client-defined tool: configuration + execution callback pair.
+ *
+ * @remarks
+ * The `execute` callback receives typed `TParams` (already validated by
+ * `config.parametersSchema.validate()`) and returns a `Promise<Result<unknown>>`.
+ * Thrown errors are caught via `captureAsyncResult` in the round-trip helper.
+ *
+ * @public
+ */
+export interface IAiClientTool<TParams = unknown> {
+    /** The tool's configuration (name, description, parameters schema). */
+    readonly config: IAiClientToolConfig<TParams>;
+    /**
+     * Execute the tool with validated parameters.
+     * @param args - Typed arguments, already validated against `config.parametersSchema`.
+     * @returns A `Promise<Result<unknown>>` — the result is stringified and sent back to the model.
+     */
+    readonly execute: (args: TParams) => Promise<Result<unknown>>;
+}
+/**
+ * Union of all tool configurations: server-side or client-defined.
+ * Discriminated on `type`.
+ * @public
+ */
+export type AiToolConfig = AiServerToolConfig | IAiClientToolConfig;
+/**
+ * Emitted when a client-defined tool call begins streaming. Carries the tool name
+ * and optional provider-assigned call ID (Anthropic / OpenAI Responses API; absent
+ * for Gemini which does not assign call IDs).
+ * @public
+ */
+export interface IAiStreamToolUseStart {
+    readonly type: 'client-tool-call-start';
+    /** The name of the client tool being called. */
+    readonly toolName: string;
+    /**
+     * Provider-assigned call identifier (Anthropic: `toolu_*`; OpenAI: `call_*`).
+     * Absent for Gemini (correlation by name).
+     */
+    readonly callId?: string;
+}
+/**
+ * Emitted when a client-defined tool call is complete and its arguments are fully
+ * accumulated. The `args` object is the fully parsed JSON object — no further
+ * streaming deltas follow for this call.
+ * @public
+ */
+export interface IAiStreamToolUseDelta {
+    readonly type: 'client-tool-call-done';
+    /** The name of the client tool being called. */
+    readonly toolName: string;
+    /**
+     * Provider-assigned call identifier. Absent for Gemini.
+     */
+    readonly callId?: string;
+    /** The fully accumulated and parsed tool arguments. */
+    readonly args: JsonObject;
+}
+/**
+ * Emitted after a client-defined tool has been executed and the result is ready
+ * to be fed back to the model in the round-trip continuation.
+ * @public
+ */
+export interface IAiStreamToolUseComplete {
+    readonly type: 'client-tool-result';
+    /** The name of the client tool that was executed. */
+    readonly toolName: string;
+    /**
+     * Provider-assigned call identifier. Absent for Gemini.
+     */
+    readonly callId?: string;
+    /** The stringified result returned by the tool's execute callback. */
+    readonly result: string;
+    /** Whether the tool execution failed (schema validation failure, execute error, or unknown tool). */
+    readonly isError: boolean;
+}
+/**
+ * Summary of a single client tool call within a turn: the tool name, call ID,
+ * raw arguments, execution result, and whether the execution was an error.
+ * @public
+ */
+export interface IAiClientToolCallSummary {
+    /** The name of the tool that was called. */
+    readonly toolName: string;
+    /** Provider-assigned call identifier (absent for Gemini). */
+    readonly callId?: string;
+    /** The fully accumulated raw arguments object as parsed JSON. */
+    readonly args: JsonObject;
+    /** The stringified result (success value or error message). */
+    readonly result: string;
+    /** Whether execution failed (schema validation failure, execute error, or unknown tool). */
+    readonly isError: boolean;
+}
+/**
+ * The provider-specific continuation data needed to build the follow-up request
+ * for the next round of the conversation.
+ *
+ * @remarks
+ * `messages` are provider-native request objects (Anthropic: content-block arrays,
+ * OpenAI Responses API: input items, Gemini: content parts). The continuation
+ * builder in `clientToolContinuationBuilder.ts` populates this.
+ *
+ * @public
+ */
+export interface IAiClientToolContinuation {
+    /**
+     * **Cumulative** provider-native wire-format message objects covering all
+     * tool rounds so far. On each turn, `executeClientToolTurn` prepends the
+     * inbound `continuationMessages` so that this array always contains the
+     * complete wire tail from round 1 through the current round.
+     *
+     * To drive a multi-round loop, simply **replace** `continuationMessages`
+     * with this value — do not manually concatenate:
+     *
+     * ```ts
+     * let tail: JsonObject[] | undefined;
+     * while (true) {
+     *   const { events, nextTurn } = executeClientToolTurn({
+     *     ..., continuationMessages: tail
+     *   }).orThrow();
+     *   for await (const e of events) { /* observe *\/ }
+     *   const outcome = (await nextTurn).orThrow();
+     *   if (!outcome.continuation) break;
+     *   tail = [...outcome.continuation.messages]; // replace — already cumulative
+     * }
+     * ```
+     *
+     * The exact shape is provider-native and may include provider-specific
+     * blocks (e.g. Anthropic thinking/redacted_thinking/tool_use, OpenAI
+     * function_call/function_call_output items, Gemini functionCall/functionResponse
+     * parts). These are NOT `IChatMessage[]` and must NOT be placed in the
+     * `messages` parameter — the normalized-message path strips provider-native
+     * fields (thinking signatures, redacted_thinking data) that the server
+     * requires for continuation validation.
+     *
+     * `toolCallsSummary` is per-round only (the calls executed in the current
+     * turn). Only `messages` is cumulative.
+     */
+    readonly messages: ReadonlyArray<JsonObject>;
+    /** Summary of each tool call executed in this turn (per-round, not cumulative). */
+    readonly toolCallsSummary: ReadonlyArray<IAiClientToolCallSummary>;
+}
+/**
+ * The result of a single client-tool turn: the optional continuation for the next
+ * call (absent when no tool calls occurred) and whether the stream was truncated.
+ * @public
+ */
+export interface IAiClientToolTurnResult {
+    /**
+     * The continuation data for the next round-trip. `undefined` when the model
+     * completed without invoking any client tools.
+     */
+    readonly continuation: IAiClientToolContinuation | undefined;
+    /** Whether the stream was truncated (token limit or stop reason). */
+    readonly truncated: boolean;
+    /** The full concatenated text from all `text-delta` events in this turn. */
+    readonly fullText: string;
+}
 /**
  * Known context keys for model specification maps.
  * @public
  */
-export type ModelSpecKey = 'base' | 'tools' | 'image';
+export type ModelSpecKey = 'base' | 'advanced' | 'frontier' | 'image' | 'embedding';
 /**
  * All valid {@link ModelSpecKey} values.
  * @public
@@ -91,18 +407,18 @@ export declare const MODEL_SPEC_BASE_KEY: ModelSpecKey;
  * @remarks
  * A bare string is equivalent to `{ base: string }`. This keeps the simple
  * case simple while allowing context-aware model selection (e.g. different
- * models for tool-augmented vs. base completions).
+ * models for different quality tiers).
  *
  * @example
  * ```typescript
  * // Simple — same model for all contexts:
- * const simple: ModelSpec = 'grok-4-1-fast';
+ * const simple: ModelSpec = 'grok-4.3';
  *
- * // Context-aware — reasoning model when tools are active:
- * const split: ModelSpec = { base: 'grok-4-1-fast', tools: 'grok-4-1-fast-reasoning' };
+ * // Context-aware — different model per quality tier:
+ * const split: ModelSpec = { base: 'gpt-5.4-mini', advanced: 'gpt-5.5', frontier: 'gpt-5.5-pro' };
  *
- * // Future nested — per-tool model selection:
- * const nested: ModelSpec = { base: 'grok-fast', tools: { base: 'grok-r', image: 'grok-v' } };
+ * // Nested — a tier branch is itself a spec:
+ * const nested: ModelSpec = { base: 'grok-fast', advanced: { base: 'grok-r', image: 'grok-v' } };
  * ```
  * @public
  */
@@ -119,26 +435,147 @@ export type ModelSpec = string | IModelSpecMap;
  * @remarks
  * Resolution rules:
  * 1. If the spec is a string, return it directly (context is irrelevant).
- * 2. If the spec is an object and the context key exists, recurse into that branch.
+ * 2. If the spec is an object, walk the ordered candidate keys for the context:
+ *    a quality-tier context (`advanced`/`frontier`) cascades through the
+ *    tier-fallback table (`frontier → advanced → base`, `advanced → base`);
+ *    every other context resolves flat (`[context]`); `undefined` resolves to
+ *    the shared `base` fallback. The first present key wins.
  * 3. Otherwise, fall back to the {@link MODEL_SPEC_BASE_KEY | 'base'} key.
  * 4. If neither context nor `'base'` exists, use the first available value.
  *
  * @param spec - The model specification to resolve
- * @param context - Optional context key (e.g. `'tools'`)
+ * @param context - Optional context key (e.g. `'advanced'`)
  * @returns The resolved model string
  * @public
  */
 export declare function resolveModel(spec: ModelSpec, context?: string): string;
+/**
+ * Canonical fgv alias → concrete provider model map.
+ *
+ * @remarks
+ * Keys are full fgv aliases (`@<providerId>:<role>`, e.g. `@google-gemini:flash`);
+ * values are the current concrete provider model id (or a provider-native alias,
+ * which is resolved with one further indirection hop). Additive; absence of an
+ * `aliases` field on a descriptor means "this provider defines no aliases" and
+ * every model string passes through verbatim.
+ * @public
+ */
+export interface IModelAliasMap {
+    readonly [alias: string]: string;
+}
+/**
+ * Marker prefix for an fgv model alias.
+ *
+ * @remarks
+ * A model string is an fgv alias **iff** it begins with this sigil. Everything
+ * else is a raw provider model id and passes through {@link resolveModelAlias}
+ * untouched — this is what keeps the alias layer back-compatible (no current
+ * `defaultModel`, `modelOverride`, or self-hosted `model:tag` id starts with `@`).
+ * @public
+ */
+export declare const MODEL_ALIAS_SIGIL: '@';
+/**
+ * Resolves a single (possibly-aliased) model string against a provider descriptor.
+ *
+ * @remarks
+ * Resolution rules:
+ * 1. No leading {@link MODEL_ALIAS_SIGIL} → raw provider id, returned verbatim.
+ * 2. Leading sigil + registered in `descriptor.aliases` → the registered target,
+ *    which is itself resolved — so a chain of `@` aliases is followed until a
+ *    non-`@` (concrete provider) id is reached. The canonical case is a single
+ *    hop (an fgv alias targeting a provider-native alias), but longer chains
+ *    resolve too.
+ * 3. Leading sigil + unregistered → fails loudly, naming the provider and alias.
+ *
+ * An `@`→`@` cycle is guarded by a visited-set and fails rather than exhausting
+ * the stack.
+ *
+ * @param descriptor - The provider descriptor whose `aliases` map is consulted.
+ * @param model - The (possibly-aliased) model string to resolve.
+ * @returns `Result` with the concrete provider model id, or a failure.
+ * @public
+ */
+export declare function resolveModelAlias(descriptor: IAiProviderDescriptor, model: string): Result<string>;
+/**
+ * The full provider model-resolution chokepoint: the {@link ModelSpecKey} walk
+ * (via {@link resolveModel}) THEN {@link resolveModelAlias}.
+ *
+ * @remarks
+ * Replaces the bare `resolveModel(modelOverride ?? descriptor.defaultModel, context)`
+ * call plus the duplicated empty-result check at each call-time chokepoint. The
+ * `ModelSpec` branch is selected first; the resulting string — which may itself
+ * be an fgv alias — is then resolved to a concrete id.
+ *
+ * @param descriptor - The provider descriptor (supplies `defaultModel` and `aliases`).
+ * @param modelOverride - An optional caller-supplied `ModelSpec` that takes precedence
+ * over `descriptor.defaultModel`. May itself contain or be an alias.
+ * @param context - Optional {@link ModelSpecKey} selecting the spec branch.
+ * @returns `Result` with the concrete provider model id, or a failure.
+ * @public
+ */
+export declare function resolveProviderModel(descriptor: IAiProviderDescriptor, modelOverride: ModelSpec | undefined, context?: ModelSpecKey): Result<string>;
+/**
+ * Determines whether a concrete (already-resolved) model id must be invoked via
+ * the OpenAI Responses API rather than chat completions.
+ *
+ * @remarks
+ * Matches `modelId` against the descriptor's
+ * {@link IAiProviderDescriptor.responsesOnlyModelPrefixes} by prefix. A provider
+ * that declares no list (the common case) always returns `false`. Consulted by
+ * both the completion (`callProviderCompletion`) and streaming
+ * (`callProviderCompletionStream`) OpenAI dispatch branches so a Responses-only
+ * model (e.g. `gpt-5.5-pro`) routes correctly even with no tools requested.
+ *
+ * @param descriptor - The provider descriptor supplying the prefix list.
+ * @param modelId - The resolved concrete model id to test.
+ * @returns `true` when `modelId` starts with any declared Responses-only prefix.
+ * @public
+ */
+export declare function isResponsesOnlyModel(descriptor: IAiProviderDescriptor, modelId: string): boolean;
 /**
  * All known AI provider identifiers.
  * @public
  */
-export type AiProviderId = 'copy-paste' | 'xai-grok' | 'openai' | 'anthropic' | 'google-gemini' | 'groq' | 'mistral';
+export type AiProviderId = 'copy-paste' | 'xai-grok' | 'openai' | 'openai-compat' | 'anthropic' | 'google-gemini' | 'groq' | 'mistral' | 'ollama';
 /**
  * API format categories for provider routing.
  * @public
  */
 export type AiApiFormat = 'openai' | 'anthropic' | 'gemini';
+/**
+ * API format categories for image-generation provider routing.
+ *
+ * @remarks
+ * - `'openai-images'` — OpenAI Images API. Routes to `/images/generations`
+ *   (text-only) or `/images/edits` (when reference images are present).
+ * - `'xai-images'` — xAI Images API. Text-only JSON generation request.
+ * - `'xai-images-edits'` — xAI Images API for Grok Imagine models. Uses JSON
+ *   body with `{ type: "image_url" }` objects (not multipart).
+ * - `'gemini-image-out'` — Google Gemini chat-style `:generateContent`
+ *   endpoint that returns image parts (Gemini Flash Image / "Nano
+ *   Banana"). Accepts reference images.
+ *
+ * @public
+ */
+export type AiImageApiFormat = 'openai-images' | 'xai-images' | 'xai-images-edits' | 'gemini-image-out';
+/**
+ * API format categories for embedding provider routing.
+ *
+ * @remarks
+ * - `'openai-embeddings'` — OpenAI `/v1/embeddings` shape. Serves OpenAI,
+ *   Ollama (via `/v1`), openai-compat self-hosted servers (vLLM, LM Studio,
+ *   llama.cpp's openai-server), and Mistral (`mistral-embed`) — all of which
+ *   speak the same request/response shape.
+ * - `'gemini-embeddings'` — Google Gemini `:batchEmbedContents` endpoint. A
+ *   genuinely divergent shape (different route, auth header, request body, and
+ *   the `taskType` retrieval-asymmetry knob that has no OpenAI analog).
+ *
+ * Named with the `ApiFormat` suffix for symmetry with `AiApiFormat` and
+ * `AiImageApiFormat`.
+ *
+ * @public
+ */
+export type AiEmbeddingApiFormat = 'openai-embeddings' | 'gemini-embeddings';
 /**
  * Result of an AI provider completion call.
  * @public
@@ -149,6 +586,87 @@ export interface IAiCompletionResponse {
     /** Whether the response was truncated due to token limits */
     readonly truncated: boolean;
 }
+/**
+ * A text-content delta arriving during a streaming completion.
+ * @public
+ */
+export interface IAiStreamTextDelta {
+    readonly type: 'text-delta';
+    /** The newly arrived text fragment. */
+    readonly delta: string;
+}
+/**
+ * A server-side tool progress event arriving during a streaming completion.
+ * Surfaced for providers that emit explicit tool-progress markers (OpenAI
+ * Responses API, Anthropic). Gemini's grounding doesn't emit these.
+ * @public
+ */
+export interface IAiStreamToolEvent {
+    readonly type: 'tool-event';
+    /** Which server-side tool this event describes. */
+    readonly toolType: AiServerToolType;
+    /** Tool lifecycle phase. */
+    readonly phase: 'started' | 'completed';
+    /**
+     * Optional provider-specific detail. For web_search this is typically the
+     * search query when available; format varies by provider.
+     */
+    readonly detail?: string;
+}
+/**
+ * Terminal success event for a streaming completion. Carries the aggregated
+ * full text and truncation status for callers that want both the progressive
+ * UI and the complete result.
+ * @public
+ */
+export interface IAiStreamDone {
+    readonly type: 'done';
+    /** Whether the response was truncated due to token limits. */
+    readonly truncated: boolean;
+    /** The full concatenated text from all `text-delta` events. */
+    readonly fullText: string;
+    /**
+     * Provider-reported reason a truncated response was cut short (e.g.
+     * `'max_output_tokens'`, `'content_filter'`), when the provider supplies one.
+     * Currently populated only by the OpenAI / xAI Responses adapter, from the
+     * completed payload's `incomplete_details.reason`. Meaningful only when
+     * `truncated === true`; `undefined` otherwise (and whenever the provider
+     * reports truncation without a reason).
+     */
+    readonly incompleteReason?: string;
+}
+/**
+ * Terminal failure event for a streaming completion. After this event no
+ * further events are emitted.
+ *
+ * @remarks
+ * Connection-time failures (auth, network, pre-flight CORS rejection) are
+ * surfaced via the outer `Result.fail` returned by
+ * `callProviderCompletionStream` rather than as an `error` event, so callers
+ * can distinguish "didn't start" from "started but errored mid-stream."
+ *
+ * @public
+ */
+export interface IAiStreamError {
+    readonly type: 'error';
+    readonly message: string;
+}
+/**
+ * Discriminated union of events emitted by a streaming completion.
+ *
+ * @remarks
+ * **Exhaustive-switch consumers must handle all variants.** The three
+ * `client-tool-*` variants were added when client-tool support shipped;
+ * update every exhaustive switch over this union in lockstep.
+ *
+ * @public
+ */
+export type IAiStreamEvent = IAiStreamTextDelta | IAiStreamToolEvent | IAiStreamToolUseStart | IAiStreamToolUseDelta | IAiStreamToolUseComplete | IAiStreamDone | IAiStreamError;
+/**
+ * Thinking/reasoning mode support for a provider.
+ * @public
+ */
+export type AiThinkingMode = 'optional' | 'required' | 'unsupported';
 /**
  * Describes a single AI provider — single source of truth for all metadata.
  * @public
@@ -168,10 +686,674 @@ export interface IAiProviderDescriptor {
     readonly baseUrl: string;
     /** Default model specification — string or context-aware map. */
     readonly defaultModel: ModelSpec;
+    /**
+     * Canonical fgv alias → concrete model map for this provider. Absent means the
+     * provider defines no aliases and every model string passes through verbatim.
+     *
+     * @remarks
+     * Keys are full fgv aliases (`@<providerId>:<role>`); values are the current
+     * concrete model id (or a provider-native alias). Consulted by
+     * {@link resolveModelAlias} / {@link resolveProviderModel} at each call-time
+     * resolution chokepoint, downstream of the {@link ModelSpecKey} walk. Additive
+     * and optional — composes with the existing per-descriptor `imageGeneration` /
+     * `embedding` capability arrays.
+     */
+    readonly aliases?: IModelAliasMap;
     /** Which server-side tools this provider supports (empty = none). */
     readonly supportedTools: ReadonlyArray<AiServerToolType>;
     /** Whether this provider's API enforces CORS restrictions that prevent direct browser calls. */
     readonly corsRestricted: boolean;
+    /**
+     * Whether this provider's streaming completion endpoint requires a proxy
+     * for direct browser calls. Some providers gate streaming separately from
+     * non-streaming (rare), so this is tracked independently from
+     * {@link IAiProviderDescriptor.corsRestricted}.
+     *
+     * @remarks
+     * When `true`, `callProviderCompletionStream` rejects up front unless the
+     * call is being routed through a proxy.
+     */
+    readonly streamingCorsRestricted: boolean;
+    /**
+     * Whether this provider's chat completions API accepts image input
+     * (i.e. supports vision prompts). When false, calls with
+     * `prompt.attachments` are rejected up front.
+     */
+    readonly acceptsImageInput: boolean;
+    /**
+     * Whether this provider supports thinking/reasoning mode.
+     * - 'optional': thinking can be enabled but is not required
+     * - 'required': thinking is always active (e.g. o-series models)
+     * - 'unsupported': thinking is not supported
+     */
+    readonly thinkingMode: AiThinkingMode;
+    /**
+     * Image-generation capabilities, scoped to model id prefixes. Empty or
+     * undefined means the provider does not support image generation.
+     *
+     * @remarks
+     * The dispatcher matches the resolved model id against each rule's
+     * `modelPrefix` and selects the longest match (see
+     * {@link AiAssist.resolveImageCapability}). An empty `modelPrefix` is the
+     * catch-all and matches every model id.
+     *
+     * Multiple entries support providers that host more than one image-API
+     * surface under one baseUrl. The dispatcher selects the longest-matching
+     * prefix, so a provider can list a specific-prefix surface alongside an
+     * empty-prefix catch-all and the right model routes to the right API.
+     *
+     * Image-model selection reuses the existing `image` {@link ModelSpecKey}.
+     * Providers that declare `imageGeneration` should declare a model in
+     * `defaultModel.image`, e.g. `{ base: '@openai:mini', image: '@openai:image' }`.
+     */
+    readonly imageGeneration?: ReadonlyArray<IAiImageModelCapability>;
+    /**
+     * Embedding capabilities, scoped to model id prefixes. Empty or undefined
+     * means the provider does not support embeddings.
+     *
+     * @remarks
+     * The dispatcher matches the resolved embedding model id against each rule's
+     * `modelPrefix` and selects the longest match (see
+     * {@link AiAssist.resolveEmbeddingCapability}). An empty `modelPrefix` is the
+     * catch-all and matches every model id.
+     *
+     * Embedding-model selection uses the `embedding` {@link ModelSpecKey}.
+     * Providers that declare `embedding` should declare a model in
+     * `defaultModel.embedding`, e.g. `{ base: '@openai:mini', embedding: '@openai:embedding' }`.
+     * Self-hosted providers (`ollama`, `openai-compat`) leave it unset — the
+     * caller supplies the embedding model via `modelOverride`.
+     */
+    readonly embedding?: ReadonlyArray<IAiEmbeddingModelCapability>;
+    /**
+     * Concrete model ids (prefix-matched) that must be invoked via the OpenAI
+     * Responses API rather than chat completions — e.g. `gpt-5.5-pro`. Non-OpenAI
+     * `apiFormat`s ignore this.
+     *
+     * @remarks
+     * Some current-generation OpenAI models (the `-pro` tier) are Responses-API-only
+     * and 400 on `/chat/completions`. The completion and streaming dispatch consult
+     * this list (via the sibling predicate {@link AiAssist.isResponsesOnlyModel})
+     * and route a matching model to the Responses path
+     * even when no tools are requested. Mirrors the prefix-matching shape of the
+     * `imageGeneration` / `embedding` capability arrays; adding a new Responses-only
+     * line is a one-entry descriptor edit. Empty or undefined means no model is
+     * Responses-only.
+     */
+    readonly responsesOnlyModelPrefixes?: ReadonlyArray<string>;
+}
+/**
+ * Image-generation capability for a model family within a provider. Used as
+ * an entry in {@link IAiProviderDescriptor.imageGeneration}.
+ *
+ * @public
+ */
+export interface IAiImageModelCapability {
+    /**
+     * Prefix matched against the resolved image model id. The empty string is
+     * the catch-all and matches every model. When multiple rules' prefixes
+     * match a model id, the longest prefix wins; ties are broken by
+     * first-encountered.
+     */
+    readonly modelPrefix: string;
+    /** API format used to dispatch requests for matching models. */
+    readonly format: AiImageApiFormat;
+    /**
+     * Whether matching models accept reference images via
+     * {@link AiAssist.IAiImageGenerationParams.referenceImages}. When false or
+     * undefined, calls that include reference images are rejected up front.
+     */
+    readonly acceptsImageReferenceInput?: boolean;
+    /** Accepted size strings. When present, dispatcher pre-validates. */
+    readonly acceptedSizes?: ReadonlyArray<string>;
+    /** When true, quality param is sent. When false/undefined, don't send quality. */
+    readonly supportsQualityParam?: boolean;
+    /** Accepted quality values when supportsQualityParam is true. */
+    readonly acceptedQualities?: ReadonlyArray<string>;
+    /** Maximum count (n). When present, dispatcher pre-validates. */
+    readonly maxCount?: number;
+    /**
+     * How to encode the output format on the wire:
+     * - 'response-format': send response_format: 'b64_json' (openai-images catch-all)
+     * - 'output-format': send output_format (gpt-image-1)
+     * - 'none': send neither (Gemini Flash)
+     */
+    readonly outputParamStyle?: 'response-format' | 'output-format' | 'none';
+    /** Default MIME type for response images. */
+    readonly defaultOutputMimeType?: string;
+}
+/**
+ * Embedding capability for a model family within a provider. Used as an entry
+ * in {@link IAiProviderDescriptor.embedding}.
+ *
+ * @public
+ */
+export interface IAiEmbeddingModelCapability {
+    /**
+     * Prefix matched against the resolved embedding model id. The empty string is
+     * the catch-all and matches every model. When multiple rules' prefixes match
+     * a model id, the longest prefix wins; ties are broken by first-encountered.
+     */
+    readonly modelPrefix: string;
+    /** API format used to dispatch requests for matching models. */
+    readonly format: AiEmbeddingApiFormat;
+    /**
+     * Whether matching models honor a requested output `dimensions`
+     * (OpenAI `text-embedding-3-*`, Gemini `gemini-embedding-001` via MRL
+     * truncation). When false/undefined, a caller-supplied `dimensions` is a
+     * no-op (logged, not failed — see {@link AiAssist.IAiEmbeddingParams}).
+     */
+    readonly supportsDimensions?: boolean;
+    /**
+     * Whether matching models honor a `taskType` hint (Gemini only today). When
+     * false/undefined, a caller-supplied `taskType` is a no-op (logged, not
+     * failed).
+     */
+    readonly supportsTaskType?: boolean;
+    /** Native fixed output dimension, when the model has one (metadata only). */
+    readonly defaultDimensions?: number;
+    /**
+     * Maximum number of inputs accepted per request. When present, the dispatcher
+     * rejects batches larger than this up front (no auto-chunking in v1).
+     */
+    readonly maxBatchSize?: number;
+}
+/**
+ * A single embedding task-type hint (Gemini-style). Cross-provider; providers
+ * that don't support task typing ignore it (logged, not failed). Open string
+ * union so new Gemini task types don't force a churn, with the known set
+ * enumerated for ergonomics.
+ *
+ * @remarks
+ * Values are the kebab-case cross-provider form; the Gemini adapter maps them to
+ * `SCREAMING_SNAKE_CASE` on the wire (e.g. `'retrieval-document'` →
+ * `RETRIEVAL_DOCUMENT`).
+ *
+ * @public
+ */
+export type AiEmbeddingTaskType = 'retrieval-query' | 'retrieval-document' | 'semantic-similarity' | 'classification' | 'clustering' | 'code-retrieval-query' | 'question-answering' | 'fact-verification' | (string & {});
+/**
+ * Parameters for an embedding request. Batch is the norm: `input` accepts a
+ * single string or an array; the result always exposes a vector array aligned
+ * by index to the input.
+ *
+ * @public
+ */
+export interface IAiEmbeddingParams {
+    /** One or more input strings. A bare string is treated as a single-element batch. */
+    readonly input: string | ReadonlyArray<string>;
+    /**
+     * Requested output dimensionality. Honored only by models whose capability
+     * declares `supportsDimensions` (OpenAI `text-embedding-3-*`, Gemini
+     * `gemini-embedding-001` via MRL truncation). Ignored — with a `logger.info`
+     * note — by models that don't.
+     */
+    readonly dimensions?: number;
+    /**
+     * Task-type hint. Mapped to Gemini `taskType`; a no-op (with a `logger.info`
+     * note) on OpenAI/Ollama/compat/Mistral. Preserves Gemini's
+     * query-vs-document retrieval asymmetry.
+     */
+    readonly taskType?: AiEmbeddingTaskType;
+}
+/**
+ * Token-usage accounting for an embedding call, when the provider reports it.
+ * @public
+ */
+export interface IAiEmbeddingUsage {
+    /** Tokens consumed by the input(s). */
+    readonly promptTokens?: number;
+    /** Total tokens billed. */
+    readonly totalTokens?: number;
+}
+/**
+ * Result of an embedding call. `vectors[i]` is the embedding for `input[i]`,
+ * in request order.
+ *
+ * @remarks
+ * Vectors are plain `number[]` (not `Float32Array`) for JSON-wire fidelity and
+ * validator-friendliness — consumers who want a typed array call
+ * `Float32Array.from(vector)` at the vector-store / WebGPU boundary. The
+ * library does not L2-normalize; Gemini's MRL truncation (when
+ * `dimensions < native`) returns un-normalized vectors that the consumer should
+ * normalize if their similarity metric requires it.
+ *
+ * @public
+ */
+export interface IAiEmbeddingResult {
+    /** One vector per input, aligned by index to the request order. */
+    readonly vectors: ReadonlyArray<ReadonlyArray<number>>;
+    /** The resolved provider-native model id that produced the vectors. */
+    readonly model: string;
+    /** Dimensionality of each returned vector (`vectors[0].length`; `0` for empty input). */
+    readonly dimensions: number;
+    /** Token usage, when the provider reports it (OpenAI-format; absent for Gemini). */
+    readonly usage?: IAiEmbeddingUsage;
+}
+/** Pixel dimension sizes accepted by gpt-image-1. @public */
+export type GptImageSize = '1024x1024' | '1536x1024' | '1024x1536' | 'auto';
+/** All accepted image size strings across all providers. @public */
+export type AiImageSize = GptImageSize;
+/** Quality values for gpt-image-1. @public */
+export type GptImageQuality = 'low' | 'medium' | 'high' | 'auto';
+/** All accepted quality strings across all providers. @public */
+export type AiImageQuality = GptImageQuality;
+/** Model names in the GPT Image family. @public */
+export type GptImageModelNames = 'gpt-image-1' | 'gpt-image-1.5';
+/** Model names in the xAI Grok Imagine family. @public */
+export type GrokImagineModelNames = 'grok-imagine-image' | 'grok-imagine-image-quality';
+/** Model names in the Gemini Flash Image family. @public */
+export type GeminiFlashImageModelNames = 'gemini-3.1-flash-image-preview';
+/**
+ * Provider-specific config for gpt-image-1.
+ * @public
+ */
+export interface IGptImageGenerationConfig {
+    /** Image dimensions. */
+    readonly size?: GptImageSize;
+    /** Quality tier. */
+    readonly quality?: GptImageQuality;
+    /** Output format (replaces response_format for this model). */
+    readonly outputFormat?: 'png' | 'jpeg' | 'webp';
+    /** JPEG/WebP compression level 0–100. */
+    readonly outputCompression?: number;
+    /** Background transparency control. */
+    readonly background?: 'transparent' | 'opaque' | 'auto';
+    /** Content moderation strictness. */
+    readonly moderation?: 'low' | 'auto';
+}
+/**
+ * Provider-specific config for xAI Grok Imagine models.
+ * @public
+ */
+export interface IGrokImagineImageGenerationConfig {
+    /** Aspect ratio string (xAI uses aspect ratios, not pixel dimensions). */
+    readonly aspectRatio?: string;
+    /** Resolution hint. */
+    readonly resolution?: string;
+}
+/**
+ * Provider-specific config for Gemini Flash Image.
+ * @public
+ */
+export interface IGeminiFlashImageGenerationConfig {
+    /** Aspect ratio string. */
+    readonly aspectRatio?: string;
+}
+/**
+ * Base shape shared by all named family option blocks.
+ * Provides a typed `models` field for applicability filtering without unsafe casts.
+ * @internal
+ */
+export interface INamedModelFamilyConfig {
+    readonly models?: readonly string[];
+}
+/**
+ * Options block scoped to GPT Image family models.
+ * @public
+ */
+export interface IGptImageModelOptions extends INamedModelFamilyConfig {
+    readonly provider: 'openai';
+    readonly family: 'gpt-image';
+    readonly models?: GptImageModelNames[];
+    readonly config: IGptImageGenerationConfig;
+}
+/**
+ * Options block scoped to xAI Grok Imagine family models.
+ * @public
+ */
+export interface IGrokImagineModelOptions extends INamedModelFamilyConfig {
+    readonly provider: 'xai';
+    readonly family: 'grok-imagine';
+    readonly models?: GrokImagineModelNames[];
+    readonly config: IGrokImagineImageGenerationConfig;
+}
+/**
+ * Options block scoped to Gemini Flash Image models.
+ * @public
+ */
+export interface IGeminiFlashImageModelOptions extends INamedModelFamilyConfig {
+    readonly provider: 'google';
+    readonly family: 'gemini-flash-image';
+    readonly models?: GeminiFlashImageModelNames[];
+    readonly config: IGeminiFlashImageGenerationConfig;
+}
+/**
+ * Escape-hatch options block for models not covered by a named family.
+ * @remarks
+ * `models` is required — there is no implicit "all" for unknown model families.
+ * `config` is `JsonObject` — passed verbatim to the wire request with no validation.
+ * This is the "trust me, I know what I'm doing" path for callers who need to send
+ * wire params our typed configs don't yet expose.
+ * @public
+ */
+export interface IOtherModelOptions {
+    readonly provider: 'other';
+    readonly models: string[];
+    readonly config: JsonObject;
+}
+/**
+ * Discriminated union of all model-family option blocks.
+ * Discriminated on `provider` + `family` fields.
+ * @public
+ */
+export type IModelFamilyConfig = IGptImageModelOptions | IGrokImagineModelOptions | IGeminiFlashImageModelOptions | IOtherModelOptions;
+/**
+ * Options for image generation requests.
+ *
+ * @remarks
+ * Uses a layered architecture:
+ * 1. Generic top-level options (size, count, quality, seed) apply across providers
+ *    via the resolved model's registry mapping.
+ * 2. Optional `models` array contains model-family-scoped blocks; the resolver
+ *    picks applicable blocks based on the resolved model and applies them in
+ *    declaration order.
+ *
+ * **Merge precedence (later wins):**
+ * 1. Generic top-level options (lowest precedence)
+ * 2. Family-generic blocks (matching family, models field omitted)
+ * 3. Model-specific blocks (models array includes resolved model name)
+ * 4. Other blocks (provider: 'other', models array includes resolved model name)
+ *
+ * Provider-mismatch: blocks whose provider doesn't match the dispatcher's
+ * provider lineage are silently skipped.
+ *
+ * @public
+ */
+export interface IAiImageGenerationOptions {
+    /**
+     * Image dimensions for OpenAI models (mapped to `size` field).
+     * For xAI or Gemini Flash aspect ratio, use the corresponding `models` family block.
+     */
+    readonly size?: AiImageSize;
+    /** Number of images. Default 1. Some models enforce a maximum. */
+    readonly count?: number;
+    /**
+     * Quality tier. Accepted values differ per model:
+     * - gpt-image-1: 'low' | 'medium' | 'high' | 'auto'
+     * Other models ignore this field.
+     */
+    readonly quality?: AiImageQuality;
+    /** Reproducibility seed, where supported. */
+    readonly seed?: number;
+    /**
+     * Optional precision via model-family-scoped blocks. The resolver picks
+     * applicable blocks dynamically based on the resolved model.
+     */
+    readonly models?: ReadonlyArray<IModelFamilyConfig>;
+}
+/**
+ * Parameters for an image-generation request.
+ * @public
+ */
+export interface IAiImageGenerationParams {
+    /** The text prompt describing the desired image. */
+    readonly prompt: string;
+    /** Optional generation options. */
+    readonly options?: IAiImageGenerationOptions;
+    /**
+     * Optional reference images. When present, the provider will use them as
+     * visual context (e.g. to preserve a character's appearance across multiple
+     * generations). The dispatcher resolves the
+     * {@link AiAssist.IAiImageModelCapability} for the requested model and
+     * rejects the call up front if `acceptsImageReferenceInput` is not set on
+     * the matching capability. An empty array is treated identically to
+     * `undefined`.
+     */
+    readonly referenceImages?: ReadonlyArray<IAiImageAttachment>;
+}
+/**
+ * A single generated image.
+ * @public
+ */
+export interface IAiGeneratedImage extends IAiImageData {
+    /**
+     * The prompt as rewritten by the provider, if any. OpenAI's image models
+     * commonly rewrite prompts; other providers do not.
+     */
+    readonly revisedPrompt?: string;
+}
+/**
+ * Capability vocabulary used to describe what a model can do. Used as both
+ * a filter and as a tag in {@link AiAssist.IAiModelInfo.capabilities}.
+ *
+ * @remarks
+ * Adding a new capability is cheap; adding the *first* one after consumers
+ * already exist forces churn. The initial vocabulary is intentionally broad
+ * even though only `image-generation` is fully exercised today.
+ *
+ * @public
+ */
+export type AiModelCapability = 'chat' | 'tools' | 'vision' | 'image-generation' | 'thinking' | 'embedding';
+/**
+ * All valid `AiModelCapability` values — the single source of truth for
+ * the capability vocabulary (used by validators and capability filters).
+ * @public
+ */
+export declare const allModelCapabilities: ReadonlyArray<AiModelCapability>;
+/**
+ * Information about a single model returned by a provider's list endpoint,
+ * with capabilities already resolved (native + config rules).
+ * @public
+ */
+export interface IAiModelInfo {
+    /** Provider-native model identifier. */
+    readonly id: string;
+    /** Resolved capability set — union of native declarations and config rules. */
+    readonly capabilities: ReadonlySet<AiModelCapability>;
+    /** Friendly name for display, when known. */
+    readonly displayName?: string;
+}
+/**
+ * One rule in an {@link IAiModelCapabilityConfig}. Multiple rules can match
+ * a single model — their capability arrays are unioned.
+ * @public
+ */
+export interface IAiModelCapabilityRule {
+    /** RegExp tested against the model id (using `.test`). */
+    readonly idPattern: RegExp;
+    /** Capabilities this rule attributes to matching models. */
+    readonly capabilities: ReadonlyArray<AiModelCapability>;
+    /**
+     * Friendly display-name override for matching models. The function form
+     * lets one rule format many ids (e.g. `(id) => id.toUpperCase()`).
+     * If multiple matching rules supply `displayName`, the first match wins.
+     */
+    readonly displayName?: string | ((id: string) => string);
+}
+/**
+ * Configuration that maps model id patterns to capabilities. Used to
+ * augment (or, where the provider supplies no capability info, fully
+ * derive) the capability set for each listed model.
+ * @public
+ */
+export interface IAiModelCapabilityConfig {
+    /** Per-provider rules. Tried before {@link AiAssist.IAiModelCapabilityConfig.global}. */
+    readonly perProvider?: {
+        readonly [P in AiProviderId]?: ReadonlyArray<IAiModelCapabilityRule>;
+    };
+    /** Cross-provider fallback rules. */
+    readonly global?: ReadonlyArray<IAiModelCapabilityRule>;
+}
+/**
+ * Result of an image-generation call.
+ * @public
+ */
+export interface IAiImageGenerationResponse {
+    /** The generated images, in provider-returned order. */
+    readonly images: ReadonlyArray<IAiGeneratedImage>;
+}
+/**
+ * Model IDs for Anthropic thinking-capable models.
+ *
+ * @remarks
+ * Only thinking-capable lines are listed. The non-tier `@anthropic:haiku` / `@anthropic:fable`
+ * aliases (reachable via `modelOverride` only) are deliberately omitted — they are not
+ * documented as thinking-capable, so naming them in a thinking-model filter would be misleading.
+ * @public
+ */
+export type AnthropicThinkingModelNames = 'claude-sonnet-4-5' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-opus-4-6' | 'claude-opus-4-7' | 'claude-opus-4-8';
+/**
+ * Model IDs for OpenAI thinking-capable models.
+ * @public
+ */
+export type OpenAiThinkingModelNames = 'o3' | 'o4-mini' | 'o3-deep-research' | 'o4-mini-deep-research' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4-mini' | 'gpt-5.5' | 'gpt-5.5-pro' | 'gpt-5-pro';
+/**
+ * Model IDs for Google Gemini thinking-capable models.
+ * @public
+ */
+export type GeminiThinkingModelNames = 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3.1-flash-lite';
+/**
+ * Model IDs for xAI thinking-capable models.
+ * @public
+ */
+export type XAiThinkingModelNames = 'grok-3-mini' | 'grok-4.3' | 'grok-4';
+/**
+ * Anthropic-specific thinking configuration.
+ * @public
+ */
+export interface IAnthropicThinkingConfig {
+    /**
+     * Anthropic effort level. The emit-site converts to `thinking.budget_tokens`
+     * (the integer budget the Anthropic API requires). Mapping policy: low = 2048,
+     * medium = 8192, high = 24000, max = 32000.
+     * - 'low' | 'medium' | 'high': all thinking-capable models
+     * - 'max': Opus 4.6 only
+     */
+    readonly effort?: 'low' | 'medium' | 'high' | 'max';
+}
+/**
+ * OpenAI-specific thinking configuration.
+ * @remarks
+ * Maps to `reasoning_effort` (Chat Completions path) or `reasoning.effort`
+ * (Responses API path) on the wire. The adapter selects the correct field.
+ * @public
+ */
+export interface IOpenAiThinkingConfig {
+    /**
+     * OpenAI reasoning effort. Maps 1:1 to the wire field.
+     * - 'none': disables reasoning (gpt-5.x only; rejected by o-series)
+     * - 'minimal': fastest (gpt-5.x)
+     * - 'low' | 'medium' | 'high': standard tiers
+     * - 'xhigh': highest (select gpt-5.x models only)
+     *
+     * @remarks
+     * When effective effort is 'none', reasoning is disabled and temperature is
+     * accepted by gpt-5.x models. This is the only case where temperature and
+     * thinking config co-exist without a Result.fail.
+     */
+    readonly effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+}
+/**
+ * Google Gemini-specific thinking configuration.
+ * @public
+ */
+export interface IGeminiThinkingConfig {
+    /**
+     * Token budget for thinking. Maps 1:1 to `thinkingBudget` on the wire.
+     * - 0: disable thinking (Flash and Flash-Lite only; error on Pro)
+     * - positive integer: soft token cap
+     * - -1: dynamic
+     * - omitted: model default
+     */
+    readonly thinkingBudget?: number;
+    /**
+     * Whether to include thought summaries in the response.
+     * @remarks
+     * INERT in phase B. Adapters never send `includeThoughts: true`.
+     * Wired up by the followup stream `ai-assist-thinking-events`.
+     */
+    readonly includeThoughts?: boolean;
+}
+/**
+ * xAI-specific thinking configuration.
+ * @public
+ */
+export interface IXAiThinkingConfig {
+    /**
+     * xAI reasoning effort. Maps 1:1 to `reasoning_effort` on the wire.
+     * For grok-4, the adapter omits this field (grok-4 always reasons and
+     * rejects the parameter).
+     */
+    readonly effort?: 'none' | 'low' | 'medium' | 'high';
+}
+/**
+ * Anthropic-specific thinking options block.
+ * @public
+ */
+export interface IAnthropicThinkingOptions {
+    readonly provider: 'anthropic';
+    readonly models?: ReadonlyArray<AnthropicThinkingModelNames>;
+    readonly config: IAnthropicThinkingConfig;
+}
+/**
+ * OpenAI-specific thinking options block.
+ * @public
+ */
+export interface IOpenAiThinkingOptions {
+    readonly provider: 'openai';
+    readonly models?: ReadonlyArray<OpenAiThinkingModelNames>;
+    readonly config: IOpenAiThinkingConfig;
+}
+/**
+ * Google Gemini-specific thinking options block.
+ * @public
+ */
+export interface IGeminiThinkingOptions {
+    readonly provider: 'google';
+    readonly models?: ReadonlyArray<GeminiThinkingModelNames>;
+    readonly config: IGeminiThinkingConfig;
+}
+/**
+ * xAI-specific thinking options block.
+ * @public
+ */
+export interface IXAiThinkingOptions {
+    readonly provider: 'xai';
+    readonly models?: ReadonlyArray<XAiThinkingModelNames>;
+    readonly config: IXAiThinkingConfig;
+}
+/**
+ * Escape-hatch options block for providers not covered by typed configs.
+ * @remarks
+ * `models` is required — no implicit "all" for unknown providers.
+ * `config` fields are merged verbatim into the wire request.
+ * @public
+ */
+export interface IOtherThinkingOptions {
+    readonly provider: 'other';
+    readonly models: ReadonlyArray<string>;
+    readonly config: JsonObject;
+}
+/**
+ * Discriminated union of per-provider thinking config blocks.
+ * @public
+ */
+export type IThinkingProviderConfig = IAnthropicThinkingOptions | IOpenAiThinkingOptions | IGeminiThinkingOptions | IXAiThinkingOptions | IOtherThinkingOptions;
+/**
+ * Thinking/reasoning mode configuration for a completion request.
+ *
+ * @remarks
+ * The generic `effort` field covers the common-subset cross-provider vocabulary.
+ * For provider-specific precision (Anthropic 'max', OpenAI 'xhigh', Gemini token
+ * budgets, xAI effort-level tuning), use the `providers` array.
+ *
+ * Absence (or undefined) means "no thinking mode" — existing callers are unaffected.
+ *
+ * @public
+ */
+export interface IThinkingConfig {
+    /**
+     * Cross-provider effort level. Common-subset mapping:
+     * - 'low': Anthropic effort:low | OpenAI effort:low | Gemini thinkingBudget:1024 | xAI reasoning_effort:low
+     * - 'medium': effort:medium | effort:medium | thinkingBudget:4096 | reasoning_effort:medium
+     * - 'high': effort:high | effort:high | thinkingBudget:8192 | reasoning_effort:high
+     */
+    readonly effort?: 'low' | 'medium' | 'high';
+    /**
+     * Optional per-provider precision blocks. Blocks for providers that don't
+     * match the resolved model's provider are silently skipped.
+     */
+    readonly providers?: ReadonlyArray<IThinkingProviderConfig>;
 }
 /**
  * Configuration for a single AI assist provider.
@@ -186,6 +1368,14 @@ export interface IAiAssistProviderConfig {
     readonly model?: ModelSpec;
     /** Tool enablement/configuration. Tools are disabled unless explicitly enabled. */
     readonly tools?: ReadonlyArray<IAiToolEnablement>;
+    /**
+     * Optional caller-supplied endpoint URL (http/https). Overrides
+     * `descriptor.baseUrl` for this provider. Used to point a provider at a
+     * self-hosted server (Ollama, LM Studio, llama.cpp's openai-server) or a
+     * local proxy. Validation lives in `@fgv/ts-extras` — query strings,
+     * fragments, and userinfo are rejected.
+     */
+    readonly endpoint?: string;
 }
 /**
  * AI assist settings — which providers are enabled and their configuration.