@fgv/ts-extras 5.1.0-34 → 5.1.0-36

package/dist/ts-extras.d.ts

@@ -27,6 +27,7 @@ declare namespace AiAssist {
     export {
         AiPrompt,
         AiModelCapability,
+        allModelCapabilities,
         AiProviderId,
         AiServerToolType,
         AiServerToolConfig,
@@ -40,8 +41,15 @@ declare namespace AiAssist {
         IAiToolEnablement,
         IAiCompletionResponse,
         IChatMessage,
+        IChatRequest,
         AiApiFormat,
         AiImageApiFormat,
+        AiEmbeddingApiFormat,
+        AiEmbeddingTaskType,
+        IAiEmbeddingModelCapability,
+        IAiEmbeddingParams,
+        IAiEmbeddingUsage,
+        IAiEmbeddingResult,
         IAiImageModelCapability,
         IAiProviderDescriptor,
         IAiAssistProviderConfig,
@@ -120,6 +128,8 @@ declare namespace AiAssist {
         getProviderDescriptor,
         resolveImageCapability,
         supportsImageGeneration,
+        resolveEmbeddingCapability,
+        supportsEmbedding,
         DEFAULT_MODEL_CAPABILITY_CONFIG,
         callProviderCompletion,
         callProxiedCompletion,
@@ -130,6 +140,9 @@ declare namespace AiAssist {
         IProviderCompletionParams,
         IProviderImageGenerationParams,
         IProviderListModelsParams,
+        callProviderEmbedding,
+        callProxiedEmbedding,
+        IProviderEmbeddingParams,
         callProviderCompletionStream,
         callProxiedCompletionStream,
         IProviderCompletionStreamParams,
@@ -184,6 +197,40 @@ declare const aiAssistSettings: Converter<IAiAssistSettings>;
  */
 declare const aiClientToolConfig: Converter<IAiClientToolConfig>;
 
+/**
+ * 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
+ */
+declare type AiEmbeddingApiFormat = 'openai-embeddings' | 'gemini-embeddings';
+
+/**
+ * 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
+ */
+declare type AiEmbeddingTaskType = 'retrieval-query' | 'retrieval-document' | 'semantic-similarity' | 'classification' | 'clustering' | 'code-retrieval-query' | 'question-answering' | 'fact-verification' | (string & {});
+
 /**
  * API format categories for image-generation provider routing.
  *
@@ -219,7 +266,7 @@ declare type AiImageSize = DallE2Size | DallE3Size | GptImageSize;
  *
  * @public
  */
-declare type AiModelCapability = 'chat' | 'tools' | 'vision' | 'image-generation' | 'thinking';
+declare type AiModelCapability = 'chat' | 'tools' | 'vision' | 'image-generation' | 'thinking' | 'embedding';
 
 /**
  * A structured AI prompt with system/user split for direct API calls,
@@ -244,6 +291,15 @@ declare class AiPrompt {
      * 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;
 }
 
 /**
@@ -331,6 +387,13 @@ declare const allKeyStoreSecretTypes: ReadonlyArray<KeyStoreSecretType>;
  */
 declare const allKeyStoreSymmetricSecretTypes: ReadonlyArray<KeyStoreSymmetricSecretType>;
 
+/**
+ * All valid `AiModelCapability` values — the single source of truth for
+ * the capability vocabulary (used by validators and capability filters).
+ * @public
+ */
+declare const allModelCapabilities: ReadonlyArray<AiModelCapability>;
+
 /**
  * All valid {@link ModelSpecKey} values.
  * @public
@@ -388,11 +451,9 @@ declare const argon2idKeyDerivationParams: Converter<IArgon2idKeyDerivationParam
 declare const base64String: Converter<string>;
 
 /**
- * Calls the appropriate chat completion API for a given provider.
- * Routes by `apiFormat`: `'openai'` (xAI/OpenAI/Groq/Mistral — switches to Responses API when
- * tools are set), `'anthropic'`, or `'gemini'`.
- * @param params - Request parameters including descriptor, API key, prompt, and optional tools
- * @returns The completion response with content and truncation status, or a failure
+ * Calls the appropriate chat completion API for a given provider. Routes by
+ * `apiFormat`: `'openai'` (xAI/OpenAI/Groq/Mistral — switches to Responses API
+ * when tools are set), `'anthropic'`, or `'gemini'`.
  * @public
  */
 declare function callProviderCompletion(params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
@@ -418,13 +479,32 @@ declare function callProviderCompletion(params: IProviderCompletionParams): Prom
 declare function callProviderCompletionStream(params: IProviderCompletionStreamParams): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
 
 /**
- * Calls the appropriate image-generation API for a given provider.
- * Routes by the `format` field of the resolved {@link IAiImageModelCapability}:
- * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, `'gemini-imagen'`,
- * or `'gemini-image-out'`. Rejects up front if `referenceImages` is set but the
+ * Calls the appropriate embedding API for a given provider. Routes by the
+ * `format` of the resolved {@link AiAssist.IAiEmbeddingModelCapability}:
+ * `'openai-embeddings'` or `'gemini-embeddings'`.
+ *
+ * @remarks
+ * - Rejects up front when the provider declares no embedding capability, when no
+ *   embedding model resolves, or when the batch exceeds the capability's
+ *   `maxBatchSize` (no auto-chunking).
+ * - An empty `input` array short-circuits to an empty result with no wire call
+ *   (most providers HTTP-400 on empty input).
+ * - Caller-supplied `dimensions`/`taskType` that the model doesn't support are a
+ *   no-op (logged), not a failure (design §7).
+ *
+ * @param params - Request parameters including descriptor, API key, and input.
+ * @returns The embedding vectors aligned to input order, or a failure.
+ * @public
+ */
+declare function callProviderEmbedding(params: IProviderEmbeddingParams): Promise<Result<IAiEmbeddingResult>>;
+
+/**
+ * Calls the appropriate image-generation API for a given provider. Routes by the
+ * `format` field of the resolved {@link IAiImageModelCapability}:
+ * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, `'gemini-imagen'`, or
+ * `'gemini-image-out'`. Rejects up front if `referenceImages` is set but the
  * capability does not declare `acceptsImageReferenceInput`.
  * @param params - Request parameters including descriptor, API key, and prompt
- * @returns The generated images, or a failure
  * @public
  */
 declare function callProviderImageGeneration(params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
@@ -432,23 +512,19 @@ declare function callProviderImageGeneration(params: IProviderImageGenerationPar
 /**
  * Lists models available from a provider, routing by `descriptor.apiFormat`.
  * Capabilities are resolved from native provider info and a configurable rule set.
- * @param params - Request parameters including descriptor, API key, and optional capability filter
- * @returns The resolved model list, or a failure
+ * @param params - Request parameters (descriptor, API key, optional capability filter)
  * @public
  */
 declare function callProviderListModels(params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
 
 /**
- * Calls the AI completion endpoint on a proxy server instead of calling
- * the provider API directly from the browser.
- *
- * The proxy server handles provider dispatch, CORS, and API key forwarding.
- * The request shape mirrors {@link IProviderCompletionParams} but is serialized
- * as JSON for the proxy endpoint.
- *
- * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
+ * Calls the AI completion endpoint on a proxy server instead of calling the
+ * provider API directly from the browser. The proxy handles provider dispatch,
+ * CORS, and API key forwarding. The request body serializes the unified
+ * {@link AiAssist.IChatRequest} shape (`system?` + `messages`). Enforces the same
+ * non-empty / trailing-user-turn and image-input invariants as the direct path.
+ * @param proxyUrl - Base URL of the proxy server
  * @param params - Same parameters as {@link callProviderCompletion}
- * @returns The completion response, or a failure
  * @public
  */
 declare function callProxiedCompletion(proxyUrl: string, params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
@@ -476,6 +552,20 @@ declare function callProxiedCompletion(proxyUrl: string, params: IProviderComple
  */
 declare function callProxiedCompletionStream(proxyUrl: string, params: IProviderCompletionStreamParams): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
 
+/**
+ * Calls the embedding endpoint on a proxy server instead of calling the provider
+ * API directly from the browser. Endpoint: `POST ${proxyUrl}/api/ai/embedding`.
+ * Request body: `{ providerId, apiKey, params, modelOverride? }`. The proxy
+ * handles descriptor lookup, model/capability resolution, and provider dispatch.
+ * Error body `{ error: string }` is surfaced as `proxy: ${error}`.
+ *
+ * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`).
+ * @param params - Same parameters as {@link AiAssist.callProviderEmbedding}.
+ * @returns The embedding result, or a failure.
+ * @public
+ */
+declare function callProxiedEmbedding(proxyUrl: string, params: IProviderEmbeddingParams): Promise<Result<IAiEmbeddingResult>>;
+
 /**
  * Calls the image-generation endpoint on a proxy server instead of calling
  * the provider API directly from the browser.
@@ -484,18 +574,17 @@ declare function callProxiedCompletionStream(proxyUrl: string, params: IProvider
  * lookup, model resolution, provider dispatch, and response normalization
  * (including repackaging `referenceImages` for the upstream wire format).
  * Error body `{error: string}` is surfaced as `proxy: ${error}`.
- * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
+ * @param proxyUrl - Base URL of the proxy server
  * @param params - Same parameters as {@link callProviderImageGeneration}
- * @returns The generated images, or a failure
  * @public
  */
 declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
 
 /**
- * Calls the model-listing endpoint on a proxy server.
- * Endpoint: `POST ${proxyUrl}/api/ai/list-models`. Capability config is not
- * forwarded. `capabilities` is serialized as a string array. Error body
- * `{error: string}` is surfaced as `proxy: ${error}`.
+ * Calls the model-listing endpoint on a proxy server. Endpoint:
+ * `POST ${proxyUrl}/api/ai/list-models`. Capability config is not forwarded;
+ * `capabilities` is serialized as a string array. Error body `{error: string}`
+ * is surfaced as `proxy: ${error}`.
  * @public
  */
 declare function callProxiedListModels(proxyUrl: string, params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
@@ -1622,18 +1711,40 @@ declare interface IAiClientToolConfig<TParams = unknown> {
  */
 declare interface IAiClientToolContinuation {
     /**
-     * Provider-native wire-format message objects to supply back on the next
-     * streaming call via `IExecuteClientToolTurnParams.continuationMessages`
-     * (which is forwarded as `rawTail` to the underlying call). The exact
-     * shape depends on the provider format and may contain provider-specific
-     * blocks (e.g. Anthropic thinking/redacted_thinking/tool_use). These are
-     * NOT `IChatMessage[]` and must not be prepended via `messagesBefore` —
-     * the normalized-message path would strip the provider-native fields
-     * (signatures, redacted thinking) that the server requires for
-     * continuation validation.
+     * **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 that was executed in this turn. */
+    /** Summary of each tool call executed in this turn (per-round, not cumulative). */
     readonly toolCallsSummary: ReadonlyArray<IAiClientToolCallSummary>;
 }
 
@@ -1665,6 +1776,104 @@ declare interface IAiCompletionResponse {
     readonly truncated: boolean;
 }
 
+/**
+ * Embedding capability for a model family within a provider. Used as an entry
+ * in {@link IAiProviderDescriptor.embedding}.
+ *
+ * @public
+ */
+declare 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;
+}
+
+/**
+ * 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
+ */
+declare 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;
+}
+
+/**
+ * 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
+ */
+declare 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;
+}
+
+/**
+ * Token-usage accounting for an embedding call, when the provider reports it.
+ * @public
+ */
+declare interface IAiEmbeddingUsage {
+    /** Tokens consumed by the input(s). */
+    readonly promptTokens?: number;
+    /** Total tokens billed. */
+    readonly totalTokens?: number;
+}
+
 /**
  * A single generated image.
  * @public
@@ -1948,6 +2157,23 @@ declare interface IAiProviderDescriptor {
      * `defaultModel.image`, e.g. `{ base: 'gpt-4o', image: 'dall-e-3' }`.
      */
     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: 'gpt-4o', embedding: 'text-embedding-3-small' }`.
+     * Self-hosted providers (`ollama`, `openai-compat`) leave it unset — the
+     * caller supplies the embedding model via `modelOverride`.
+     */
+    readonly embedding?: ReadonlyArray<IAiEmbeddingModelCapability>;
 }
 
 /**
@@ -2228,6 +2454,41 @@ declare 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
+ */
+declare 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>;
 }
 
 /**
@@ -2729,31 +2990,44 @@ declare interface IEncryptionResult {
 
 /**
  * Parameters for {@link AiAssist.executeClientToolTurn}.
+ *
+ * @remarks
+ * Carries the unified {@link AiAssist.IChatRequest} shape (`system?` + ordered
+ * `messages`): the last message is the current user turn and the preceding
+ * messages are history, linearized before the current turn — identically to the
+ * completion and streaming paths. {@link IExecuteClientToolTurnParams.continuationMessages}
+ * remains a distinct post-current-turn axis (see below).
+ *
  * @public
  */
-declare interface IExecuteClientToolTurnParams {
+declare interface IExecuteClientToolTurnParams extends IChatRequest {
     /** The provider descriptor for routing (Anthropic / OpenAI / Gemini). */
     readonly descriptor: IAiProviderDescriptor;
     /** API key for authentication. */
     readonly apiKey: string;
-    /** The structured prompt. */
-    readonly prompt: AiPrompt;
-    /** Prior conversation history (excluding the current turn). */
-    readonly messagesBefore?: ReadonlyArray<IChatMessage>;
-    /**
-     * Provider-specific continuation messages to append after the prompt's user
-     * message. Used to supply the output of {@link AiAssist.IAiClientToolContinuation}'s
-     * `messages` field from a prior turn back to the provider in the follow-up request.
+    /**
+     * The cumulative provider-native wire tail from the previous turn's
+     * {@link AiAssist.IAiClientToolContinuation.messages}. Supply this as-is
+     * each round — `messages` is already cumulative, so **replace** rather
+     * than manually concatenate:
+     *
+     * ```ts
+     * tail = outcome.continuation.messages; // replace — already cumulative
+     * ```
+     *
+     * On the first turn this should be `undefined` (or omitted).
      *
      * Each provider applies its own shape guard to the supplied wire objects:
      * - Anthropic: projects each entry to `{ role, content }` (sufficient for
      *   thinking blocks and `tool_result` arrays).
      * - OpenAI / xAI Responses: passes each item verbatim (`function_call` /
-     *   `function_call_output` items carry distinct fields per `type`); only guards
-     *   that each entry is a JSON object.
+     *   `function_call_output` items carry distinct fields per `type`); only
+     *   guards that each entry is a JSON object.
      * - Gemini: projects each entry to `{ role, parts }`.
      *
      * Entries that fail their provider's shape check are silently skipped.
+     * Do NOT place these objects in the `messages` parameter — the
+     * normalized-message path strips provider-native fields.
      */
     readonly continuationMessages?: ReadonlyArray<JsonObject>;
     /** Temperature (default: 0.7). */
@@ -2764,6 +3038,16 @@ declare interface IExecuteClientToolTurnParams {
     readonly clientTools: ReadonlyArray<IAiClientTool>;
     /** Optional abort signal. */
     readonly signal?: AbortSignal;
+    /**
+     * Optional override of the descriptor's default base URL. Same semantics as
+     * the non-streaming completion path and `callProviderCompletionStream`: a
+     * well-formed `http`/`https` URL is substituted for `descriptor.baseUrl`
+     * when composing the per-format request, with the per-format suffix appended
+     * unchanged. Validated at the dispatcher; auth shape is unaffected. Use this
+     * to point a client-tool turn at a local / LAN OpenAI-compatible server
+     * (Ollama, LM Studio, llama.cpp).
+     */
+    readonly endpoint?: string;
     /** Optional logger for diagnostics. */
     readonly logger?: Logging.ILogger;
     /** Optional resolved thinking config (pre-resolved by the caller). */
@@ -3611,18 +3895,16 @@ declare interface IPrivateKeyStorage {
 }
 
 /**
- * Parameters for a provider completion request.
+ * Parameters for a provider completion request. Carries the unified
+ * {@link AiAssist.IChatRequest} shape (`system?` + ordered `messages`, last =
+ * current user turn); history is linearized before the current turn.
  * @public
  */
-declare interface IProviderCompletionParams {
+declare interface IProviderCompletionParams extends IChatRequest {
     /** The provider descriptor */
     readonly descriptor: IAiProviderDescriptor;
     /** API key for authentication */
     readonly apiKey: string;
-    /** The structured prompt to send */
-    readonly prompt: AiPrompt;
-    /** Additional messages to append after system+user in order (e.g. for correction retries). */
-    readonly additionalMessages?: ReadonlyArray<IChatMessage>;
     /** Sampling temperature (default: 0.7) */
     readonly temperature?: number;
     /** Optional model override — string or context-aware map (uses descriptor.defaultModel otherwise) */
@@ -3652,22 +3934,19 @@ declare interface IProviderCompletionParams {
  * the non-streaming `IProviderCompletionParams`; kept as its own interface
  * so callers can be explicit about which path they're invoking.
  *
+ * @remarks
+ * Carries the unified {@link AiAssist.IChatRequest} shape (`system?` + ordered
+ * `messages`): the last message is the current user turn and the preceding
+ * messages are history, linearized before the current turn (identical to the
+ * completion and client-tool turn paths).
+ *
  * @public
  */
-declare interface IProviderCompletionStreamParams {
+declare interface IProviderCompletionStreamParams extends IChatRequest {
     /** The provider descriptor */
     readonly descriptor: IAiProviderDescriptor;
     /** API key for authentication */
     readonly apiKey: string;
-    /** The structured prompt to send */
-    readonly prompt: AiPrompt;
-    /**
-     * Prior conversation history to insert between the system prompt and the
-     * prompt's user message. The new user turn (carried by `prompt.user`) is
-     * always sent last, so the wire shape becomes
-     * `[system, ...messagesBefore, user=prompt.user]`.
-     */
-    readonly messagesBefore?: ReadonlyArray<IChatMessage>;
     /** Sampling temperature (default: 0.7) */
     readonly temperature?: number;
     /** Optional model override — string or context-aware map. */
@@ -3692,6 +3971,32 @@ declare interface IProviderCompletionStreamParams {
     readonly thinking?: IThinkingConfig;
 }
 
+/**
+ * Parameters for a provider embedding request. Mirrors
+ * {@link AiAssist.IProviderImageGenerationParams}.
+ * @public
+ */
+declare interface IProviderEmbeddingParams {
+    /** The provider descriptor. */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication (empty string for keyless self-hosted providers). */
+    readonly apiKey: string;
+    /** The embedding request (input + optional knobs). */
+    readonly params: IAiEmbeddingParams;
+    /**
+     * Optional model override — string or context-aware map. Uses
+     * `descriptor.defaultModel.embedding` otherwise. Self-hosted providers
+     * (`ollama`, `openai-compat`) have no default and require this.
+     */
+    readonly modelOverride?: ModelSpec;
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
+    /** Optional override of the descriptor's base URL; the `/embeddings` suffix is appended unchanged. */
+    readonly endpoint?: string;
+}
+
 /**
  * Parameters for an image-generation request.
  * @public
@@ -4769,7 +5074,7 @@ declare const modelSpec: Converter<ModelSpec>;
  * Known context keys for model specification maps.
  * @public
  */
-declare type ModelSpecKey = 'base' | 'tools' | 'image' | 'thinking';
+declare type ModelSpecKey = 'base' | 'tools' | 'image' | 'thinking' | 'embedding';
 
 /**
  * Converter for {@link ModelSpecKey}.
@@ -5323,6 +5628,20 @@ export { RecordJar }
  */
 declare function resolveEffectiveTools(descriptor: IAiProviderDescriptor, settingsTools?: ReadonlyArray<IAiToolEnablement>, perCallTools?: ReadonlyArray<AiServerToolConfig>): ReadonlyArray<AiServerToolConfig>;
 
+/**
+ * Resolve the embedding capability that applies to a given model id for a
+ * provider. Returns the entry from {@link IAiProviderDescriptor.embedding} whose
+ * `modelPrefix` is the longest prefix of `modelId`. Ties are broken by
+ * first-encountered.
+ *
+ * @param descriptor - The provider descriptor
+ * @param modelId - The resolved embedding model id
+ * @returns The matching capability, or `undefined` when no rule matches or the
+ *   provider declares no embedding capabilities.
+ * @public
+ */
+declare function resolveEmbeddingCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiEmbeddingModelCapability | undefined;
+
 /**
  * Resolve the image-generation capability that applies to a given model id
  * for a provider. Returns the entry from
@@ -5392,6 +5711,16 @@ declare type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>
  */
 declare const SMART_JSON_PROMPT_HINT: string;
 
+/**
+ * Whether a provider declares any embedding capability at all.
+ *
+ * @param descriptor - The provider descriptor
+ * @returns `true` when {@link IAiProviderDescriptor.embedding} has at least one
+ *   entry; `false` otherwise.
+ * @public
+ */
+declare function supportsEmbedding(descriptor: IAiProviderDescriptor): boolean;
+
 /**
  * Whether a provider declares any image-generation capability at all.
  *