@fgv/ts-extras 5.1.0-33 → 5.1.0-35

package/dist/ts-extras.d.ts

@@ -4,6 +4,7 @@ import { DateTime } from 'luxon';
 import { FileTree } from '@fgv/ts-json-base';
 import { Hash as Hash_2 } from '@fgv/ts-utils';
 import { JsonObject } from '@fgv/ts-json-base';
+import { JsonSchema } from '@fgv/ts-json-base';
 import { JsonValue } from '@fgv/ts-json-base';
 import { Logging } from '@fgv/ts-utils';
 import { Result } from '@fgv/ts-utils';
@@ -26,15 +27,29 @@ declare namespace AiAssist {
     export {
         AiPrompt,
         AiModelCapability,
+        allModelCapabilities,
         AiProviderId,
         AiServerToolType,
         AiServerToolConfig,
+        AiToolConfig,
         IAiWebSearchToolConfig,
+        IAiClientToolConfig,
+        IAiClientTool,
+        IAiClientToolCallSummary,
+        IAiClientToolContinuation,
+        IAiClientToolTurnResult,
         IAiToolEnablement,
         IAiCompletionResponse,
         IChatMessage,
+        IChatRequest,
         AiApiFormat,
         AiImageApiFormat,
+        AiEmbeddingApiFormat,
+        AiEmbeddingTaskType,
+        IAiEmbeddingModelCapability,
+        IAiEmbeddingParams,
+        IAiEmbeddingUsage,
+        IAiEmbeddingResult,
         IAiImageModelCapability,
         IAiProviderDescriptor,
         IAiAssistProviderConfig,
@@ -77,6 +92,9 @@ declare namespace AiAssist {
         IAiStreamEvent,
         IAiStreamTextDelta,
         IAiStreamToolEvent,
+        IAiStreamToolUseStart,
+        IAiStreamToolUseDelta,
+        IAiStreamToolUseComplete,
         IAiStreamDone,
         IAiStreamError,
         ModelSpec,
@@ -110,6 +128,8 @@ declare namespace AiAssist {
         getProviderDescriptor,
         resolveImageCapability,
         supportsImageGeneration,
+        resolveEmbeddingCapability,
+        supportsEmbedding,
         DEFAULT_MODEL_CAPABILITY_CONFIG,
         callProviderCompletion,
         callProxiedCompletion,
@@ -120,13 +140,20 @@ declare namespace AiAssist {
         IProviderCompletionParams,
         IProviderImageGenerationParams,
         IProviderListModelsParams,
+        callProviderEmbedding,
+        callProxiedEmbedding,
+        IProviderEmbeddingParams,
         callProviderCompletionStream,
         callProxiedCompletionStream,
         IProviderCompletionStreamParams,
+        executeClientToolTurn,
+        IExecuteClientToolTurnParams,
+        IExecuteClientToolTurnResult,
         aiProviderId,
         aiServerToolType,
         aiWebSearchToolConfig,
         aiServerToolConfig,
+        aiClientToolConfig,
         aiToolEnablement,
         aiAssistProviderConfig,
         aiAssistSettings,
@@ -142,7 +169,9 @@ declare namespace AiAssist {
         SMART_JSON_PROMPT_HINT,
         IGenerateJsonCompletionParams,
         IGenerateJsonCompletionResult,
-        JsonPromptHint
+        JsonPromptHint,
+        anthropicEffortToBudgetTokens,
+        IResolvedThinkingConfig
     }
 }
 export { AiAssist }
@@ -159,6 +188,49 @@ declare const aiAssistProviderConfig: Converter<IAiAssistProviderConfig>;
  */
 declare const aiAssistSettings: Converter<IAiAssistSettings>;
 
+/**
+ * Converter for {@link AiAssist.IAiClientToolConfig}. Validates the wrapper shape: `type`,
+ * `name`, `description`, and the presence of a usable `parametersSchema`.
+ * Does not inspect the inner JSON Schema structure — `JsonSchema.object(...)` already
+ * guarantees the schema is valid.
+ * @public
+ */
+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.
  *
@@ -194,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,
@@ -219,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;
 }
 
 /**
@@ -263,6 +344,13 @@ declare const aiServerToolType: Converter<AiServerToolType>;
  */
 declare type AiThinkingMode = 'optional' | 'required' | 'unsupported';
 
+/**
+ * Union of all tool configurations: server-side or client-defined.
+ * Discriminated on `type`.
+ * @public
+ */
+declare type AiToolConfig = AiServerToolConfig | IAiClientToolConfig;
+
 /**
  * Converter for {@link IAiToolEnablement}.
  * @public
@@ -299,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
@@ -311,6 +406,19 @@ declare const allModelSpecKeys: ReadonlyArray<ModelSpecKey>;
  */
 declare const allProviderIds: ReadonlyArray<AiProviderId>;
 
+/**
+ * Maps Anthropic effort level to the `thinking.budget_tokens` integer that the
+ * Anthropic API requires when `thinking.type === 'enabled'`.
+ *
+ * Policy: low = 2048, medium = 8192, high = 24000, max = 32000. The lower three
+ * align with the Anthropic-published minimum-meaningful budget, a mid-range
+ * default, and a "deep thinking" allotment respectively. `max` targets Opus 4.6's
+ * deepest budget and stays within typical model limits.
+ *
+ * @public
+ */
+declare function anthropicEffortToBudgetTokens(effort: NonNullable<IAnthropicThinkingConfig['effort']>): number;
+
 /**
  * Model IDs for Anthropic thinking-capable models.
  * @public
@@ -343,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>>;
@@ -373,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>>;
@@ -387,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>>;
@@ -431,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.
@@ -439,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>>>;
@@ -872,6 +1006,29 @@ declare type EncryptionAlgorithm = typeof Constants.DEFAULT_ALGORITHM;
  */
 declare const encryptionAlgorithm: Converter<EncryptionAlgorithm>;
 
+/**
+ * Orchestrates a single client-tool streaming turn for any supported provider.
+ *
+ * Starts a streaming request, iterates the underlying provider stream, and:
+ * - Forwards `text-delta`, `tool-event`, `client-tool-call-start`, and
+ *   `client-tool-call-done` events through to the consumer.
+ * - For each `client-tool-call-done` event: validates the raw args against the
+ *   tool's `parametersSchema`, invokes `execute(typedArgs)`, and emits a
+ *   `client-tool-result` event.
+ * - After stream completion: builds the per-provider continuation (or
+ *   `{ continuation: undefined }` when no tool calls occurred) and resolves
+ *   `nextTurn`.
+ *
+ * **Anthropic constraint (E3):** The continuation for Anthropic does not set
+ * a forced `tool_choice`. Only `tool_choice: 'auto'` (the default, i.e.
+ * omitted) is compatible with extended thinking.
+ *
+ * @param params - Turn parameters
+ * @returns `{ events, nextTurn }` — stream iterable + completion promise
+ * @public
+ */
+declare function executeClientToolTurn(params: IExecuteClientToolTurnParams): Result<IExecuteClientToolTurnResult>;
+
 declare namespace Experimental {
     export {
         ExtendedArray,
@@ -1475,6 +1632,117 @@ declare interface IAiAssistSettings {
     readonly proxyAllProviders?: boolean;
 }
 
+/**
+ * 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
+ */
+declare 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>>;
+}
+
+/**
+ * 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
+ */
+declare 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;
+}
+
+/**
+ * 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
+ */
+declare 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>;
+}
+
+/**
+ * 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
+ */
+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.
+     */
+    readonly messages: ReadonlyArray<JsonObject>;
+    /** Summary of each tool call that was executed in this turn. */
+    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
+ */
+declare 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;
+}
+
 /**
  * Result of an AI provider completion call.
  * @public
@@ -1486,6 +1754,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
@@ -1769,6 +2135,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>;
 }
 
 /**
@@ -1783,6 +2166,15 @@ declare interface IAiStreamDone {
     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;
 }
 
 /**
@@ -1804,9 +2196,15 @@ declare interface IAiStreamError {
 
 /**
  * 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
  */
-declare type IAiStreamEvent = IAiStreamTextDelta | IAiStreamToolEvent | IAiStreamDone | IAiStreamError;
+declare type IAiStreamEvent = IAiStreamTextDelta | IAiStreamToolEvent | IAiStreamToolUseStart | IAiStreamToolUseDelta | IAiStreamToolUseComplete | IAiStreamDone | IAiStreamError;
 
 /**
  * A text-content delta arriving during a streaming completion.
@@ -1837,6 +2235,60 @@ declare interface IAiStreamToolEvent {
     readonly detail?: string;
 }
 
+/**
+ * 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
+ */
+declare 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;
+}
+
+/**
+ * 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
+ */
+declare 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 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
+ */
+declare 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;
+}
+
 /**
  * Declares a tool as enabled/disabled in provider settings.
  * Tools are disabled by default — consuming apps must opt in explicitly.
@@ -1877,7 +2329,9 @@ declare interface IAiWebSearchToolConfig {
  */
 declare interface IAnthropicThinkingConfig {
     /**
-     * Anthropic effort level. Maps 1:1 to `output_config.effort` on the wire.
+     * 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
      */
@@ -1978,6 +2432,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>;
 }
 
 /**
@@ -2477,6 +2966,84 @@ declare interface IEncryptionResult {
     readonly encryptedData: Uint8Array;
 }
 
+/**
+ * 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 extends IChatRequest {
+    /** The provider descriptor for routing (Anthropic / OpenAI / Gemini). */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication. */
+    readonly apiKey: string;
+    /**
+     * Provider-specific continuation messages to append after the current 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.
+     *
+     * 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.
+     * - Gemini: projects each entry to `{ role, parts }`.
+     *
+     * Entries that fail their provider's shape check are silently skipped.
+     */
+    readonly continuationMessages?: ReadonlyArray<JsonObject>;
+    /** Temperature (default: 0.7). */
+    readonly temperature?: number;
+    /** Server-side tools to include. */
+    readonly tools?: ReadonlyArray<AiServerToolConfig>;
+    /** Client-defined tools available for the model to call. */
+    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). */
+    readonly resolvedThinking?: IResolvedThinkingConfig;
+    /** Resolved model string (pre-resolved by the caller). When omitted, uses the descriptor's default model. */
+    readonly model?: string;
+}
+
+/**
+ * Return value of {@link AiAssist.executeClientToolTurn}.
+ * @public
+ */
+declare interface IExecuteClientToolTurnResult {
+    /**
+     * The unified-event iterable. Callers iterate this to drive the streaming UI.
+     * The iterable forwards `text-delta`, `tool-event`, `client-tool-call-start`,
+     * `client-tool-call-done`, and `client-tool-result` events through.
+     */
+    readonly events: AsyncIterable<IAiStreamEvent>;
+    /**
+     * Resolves when the stream terminates. On success, carries the
+     * {@link AiAssist.IAiClientToolTurnResult} with the optional continuation for the
+     * next round. On failure, carries the error message.
+     */
+    readonly nextTurn: Promise<Result<IAiClientToolTurnResult>>;
+}
+
 /**
  * Options shared by every {@link AiAssist.fencedStringifiedJson} call.
  * @public
@@ -3297,18 +3864,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) */
@@ -3338,22 +3903,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. */
@@ -3378,6 +3940,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
@@ -3481,6 +4069,28 @@ declare interface IResolvedImageOptions {
     readonly otherParams?: JsonObject;
 }
 
+/**
+ * Resolved thinking wire parameters for a specific provider, after merging
+ * all applicable config blocks. Ready for provider-specific wire encoding.
+ *
+ * Callers that pre-resolve thinking config outside of the standard streaming
+ * helpers (e.g. `executeClientToolTurn`) accept this type via the
+ * `resolvedThinking` parameter and pass it directly to the adapter layer.
+ * @public
+ */
+declare interface IResolvedThinkingConfig {
+    /** Anthropic: effort level; emit-site converts to `thinking.budget_tokens` via `anthropicEffortToBudgetTokens`. */
+    readonly anthropicEffort?: IAnthropicThinkingConfig['effort'];
+    /** OpenAI Chat: reasoning_effort value; OpenAI Responses: reasoning.effort */
+    readonly openAiEffort?: IOpenAiThinkingConfig['effort'];
+    /** Gemini: generationConfig.thinkingConfig.thinkingBudget */
+    readonly geminiThinkingBudget?: number;
+    /** xAI: reasoning_effort value (omit for grok-4) */
+    readonly xaiEffort?: IXAiThinkingConfig['effort'];
+    /** Other/passthrough: merged verbatim into wire request */
+    readonly otherParams?: JsonObject;
+}
+
 /**
  * Checks if a JSON object appears to be an encrypted file.
  * Uses the format field as a discriminator.
@@ -4433,7 +5043,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}.
@@ -4987,6 +5597,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
@@ -5056,6 +5680,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.
  *