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

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';
@@ -29,7 +30,13 @@ declare namespace AiAssist {
         AiProviderId,
         AiServerToolType,
         AiServerToolConfig,
+        AiToolConfig,
         IAiWebSearchToolConfig,
+        IAiClientToolConfig,
+        IAiClientTool,
+        IAiClientToolCallSummary,
+        IAiClientToolContinuation,
+        IAiClientToolTurnResult,
         IAiToolEnablement,
         IAiCompletionResponse,
         IChatMessage,
@@ -77,6 +84,9 @@ declare namespace AiAssist {
         IAiStreamEvent,
         IAiStreamTextDelta,
         IAiStreamToolEvent,
+        IAiStreamToolUseStart,
+        IAiStreamToolUseDelta,
+        IAiStreamToolUseComplete,
         IAiStreamDone,
         IAiStreamError,
         ModelSpec,
@@ -123,10 +133,14 @@ declare namespace AiAssist {
         callProviderCompletionStream,
         callProxiedCompletionStream,
         IProviderCompletionStreamParams,
+        executeClientToolTurn,
+        IExecuteClientToolTurnParams,
+        IExecuteClientToolTurnResult,
         aiProviderId,
         aiServerToolType,
         aiWebSearchToolConfig,
         aiServerToolConfig,
+        aiClientToolConfig,
         aiToolEnablement,
         aiAssistProviderConfig,
         aiAssistSettings,
@@ -142,7 +156,9 @@ declare namespace AiAssist {
         SMART_JSON_PROMPT_HINT,
         IGenerateJsonCompletionParams,
         IGenerateJsonCompletionResult,
-        JsonPromptHint
+        JsonPromptHint,
+        anthropicEffortToBudgetTokens,
+        IResolvedThinkingConfig
     }
 }
 export { AiAssist }
@@ -159,6 +175,15 @@ 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 image-generation provider routing.
  *
@@ -263,6 +288,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
@@ -311,6 +343,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
@@ -751,6 +796,115 @@ declare type EncryptedFileFormat = typeof Constants.ENCRYPTED_FILE_FORMAT;
  */
 declare const encryptedFileFormat: Converter<EncryptedFileFormat>;
 
+/**
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage | IPrivateKeyStorage}
+ * implementation that persists each private key as its own AES-256-GCM-encrypted
+ * file in a directory. The file content is the key's JWK, encrypted with a
+ * consumer-supplied 32-byte key via the supplied
+ * {@link CryptoUtils.ICryptoProvider | crypto provider}.
+ *
+ * `supportsNonExtractable` is `false`: persisting to disk requires exporting the
+ * private key to JWK, which only works for `extractable: true` keys. The
+ * keystore generates extractable keys when a backend reports `false` here.
+ *
+ * I/O goes through the {@link FileTree.FileTree | FileTree} abstraction (default
+ * `FsTree`), so the same implementation works against an in-memory tree (tests)
+ * or any other Node-compatible backend.
+ *
+ * This backend is **Node-only**: it round-trips private keys through
+ * `node:crypto` (`crypto.webcrypto.subtle`), so it is intentionally excluded
+ * from the browser entry point. Browser consumers should use
+ * `IdbPrivateKeyStorage` from `@fgv/ts-web-extras` instead.
+ *
+ * Single-process assumption: there is no inter-process locking. Concurrent
+ * writers to the same directory may race.
+ *
+ * @public
+ */
+declare class EncryptedFilePrivateKeyStorage implements IPrivateKeyStorage {
+    /**
+     * `false` — disk persistence round-trips via JWK, which requires extractable
+     * keys.
+     */
+    readonly supportsNonExtractable: false;
+    private readonly _directory;
+    private readonly _encryptionKey;
+    private readonly _cryptoProvider;
+    private constructor();
+    /**
+     * Creates a new {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage}.
+     * @param params - {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams}.
+     * @returns `Success` with the new instance, or `Failure` if the encryption
+     * key is the wrong size or the storage directory cannot be opened.
+     */
+    static create(params: IEncryptedFilePrivateKeyStorageCreateParams): Result<EncryptedFilePrivateKeyStorage>;
+    /**
+     * Stores `key` under `id` as an encrypted JWK file.
+     * @param id - Storage handle. Must be a safe filename token
+     * (`[A-Za-z0-9._-]+`, not `.`/`..`).
+     * @param key - The extractable private `CryptoKey` to persist.
+     */
+    store(id: string, key: CryptoKey): Promise<Result<string>>;
+    /**
+     * Loads the private key stored under `id`, decrypting and re-importing it from
+     * JWK.
+     * @param id - Storage handle.
+     */
+    load(id: string): Promise<Result<CryptoKey>>;
+    /**
+     * Deletes the entry stored under `id`. Missing ids fail (the read path is
+     * keystore-driven and never asks to delete an id it did not store).
+     * @param id - Storage handle.
+     */
+    delete(id: string): Promise<Result<string>>;
+    /**
+     * Lists every stored id.
+     */
+    list(): Promise<Result<readonly string[]>>;
+    private _fileNameFor;
+    /**
+     * Validates the synchronous preconditions for a store: the id is filename-safe,
+     * the key is actually a private key, and its algorithm is one we support.
+     * Returns the resolved filename and algorithm so the async pipeline can run
+     * without re-deriving them.
+     */
+    private _validateKeyToStore;
+    /**
+     * Exports `key` to JWK, wraps it in the stored envelope, encrypts it with
+     * AES-256-GCM, and writes the resulting file as serialized JSON to `fileName`.
+     * Returns the stored `id` on success.
+     */
+    private _encryptAndWrite;
+    private _algorithmOf;
+    private _findFile;
+    private _writeFile;
+    /**
+     * Reads `file`, decrypts the AES-256-GCM envelope, and validates it into the
+     * typed `IStoredPrivateKeyEnvelope`. Read, decrypt, and shape failures
+     * all surface as a decrypt failure for `id`.
+     */
+    private _decryptEnvelope;
+    /**
+     * Parses and shape-validates the stored JWK, then re-imports it as a private
+     * `CryptoKey` for the envelope's algorithm. The WebCrypto JWK-import algorithm
+     * descriptor is shared between public and private keys for every supported
+     * algorithm, so `IKeyPairAlgorithmParams.importPublicKey` is reused here;
+     * the public/private distinction is carried by the requested `usages`.
+     */
+    private _importPrivateKey;
+    /**
+     * Computes the key usages to request when re-importing a stored private key.
+     * WebCrypto rejects `importKey` if the requested usages include operations
+     * absent from the JWK's `key_ops`, so a key originally created with a narrower
+     * usage set than the algorithm default (e.g. an ECDH key with only
+     * `deriveBits`) would fail to load against the algorithm-wide defaults.
+     * Intersect the algorithm's private usages with the JWK's recorded `key_ops`
+     * so we request exactly the operations the stored key actually supports;
+     * fall back to the algorithm's private usages when `key_ops` is absent.
+     */
+    private _importUsagesFor;
+}
+
 /**
  * Supported encryption algorithms.
  * @public
@@ -763,6 +917,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,
@@ -1366,6 +1543,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
@@ -1674,6 +1962,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;
 }
 
 /**
@@ -1695,9 +1992,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.
@@ -1728,6 +2031,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.
@@ -1768,7 +2125,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
      */
@@ -2260,6 +2619,42 @@ declare interface IEncryptedFile<TMetadata = JsonValue> {
     readonly keyDerivation?: IKeyDerivationParams;
 }
 
+/**
+ * Parameters for {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage.create}.
+ * @public
+ */
+declare interface IEncryptedFilePrivateKeyStorageCreateParams {
+    /**
+     * Filesystem path to the directory that holds the encrypted private-key
+     * files. Used only when {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.tree}
+     * is omitted (the default `FsTree` backing). The directory must already
+     * exist.
+     */
+    readonly directory: string;
+    /**
+     * Raw AES-256-GCM key (32 bytes) used to encrypt each file's JWK content.
+     * Consumer-supplied and decoupled from the keystore's password lifecycle —
+     * derive it however the application sees fit (typically the same
+     * password-derived key material the keystore vault uses).
+     */
+    readonly encryptionKey: Uint8Array;
+    /**
+     * {@link CryptoUtils.ICryptoProvider | Crypto provider} used for the
+     * AES-256-GCM encrypt/decrypt of each file's contents.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * Optional {@link FileTree.IFileTreeDirectoryItem | FileTree directory}
+     * override. When supplied it is used as the storage directory directly and
+     * {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.directory} is ignored —
+     * pass an in-memory tree for tests, or another Node-compatible backend. When
+     * omitted, a mutable `FsTree` rooted at `directory` is used. (This backend is
+     * Node-only — it round-trips keys through `node:crypto` — so a browser file
+     * tree is not a supported target.)
+     */
+    readonly tree?: FileTree.IFileTreeDirectoryItem;
+}
+
 /**
  * Configuration for encrypted file handling during loading.
  * @public
@@ -2332,6 +2727,70 @@ declare interface IEncryptionResult {
     readonly encryptedData: Uint8Array;
 }
 
+/**
+ * Parameters for {@link AiAssist.executeClientToolTurn}.
+ * @public
+ */
+declare interface IExecuteClientToolTurnParams {
+    /** 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.
+     *
+     * 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 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
@@ -3101,9 +3560,12 @@ declare interface IPbkdf2KeyDerivationParams {
 
 /**
  * Pluggable backend that persists raw asymmetric private keys outside of the
- * encrypted keystore vault. Concrete implementations live in platform-specific
- * packages (e.g. an IndexedDB-backed implementation in `@fgv/ts-web-extras` or
- * an encrypted-file implementation in `@fgv/ts-chocolate`).
+ * encrypted keystore vault. Concrete implementations:
+ * - {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage} in
+ *   `@fgv/ts-extras` — directory-on-disk, AES-256-GCM-encrypted JWK per key
+ *   (Node; `supportsNonExtractable: false`).
+ * - `IdbPrivateKeyStorage` in `@fgv/ts-web-extras` — IndexedDB-backed, stores
+ *   `CryptoKey` objects directly (browser; `supportsNonExtractable: true`).
  *
  * The keystore writes storage-first: a private key is always stored here
  * before the corresponding public-key vault entry is committed. Conversely,
@@ -3333,6 +3795,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.
@@ -3666,6 +4150,8 @@ declare namespace KeyStore {
     export {
         Converters_2 as Converters,
         KeyStore_2 as KeyStore,
+        EncryptedFilePrivateKeyStorage,
+        IEncryptedFilePrivateKeyStorageCreateParams,
         isKeyStoreFile,
         allKeyPairAlgorithms,
         KeyPairAlgorithm,

package/lib/packlets/ai-assist/apiClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/apiClient.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAQ,KAAK,OAAO,EAAc,MAAM,EAAuC,MAAM,eAAe,CAAC;AAE5G,OAAO,EACL,QAAQ,EACR,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAG1B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAE/B,KAAK,wBAAwB,EAE7B,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,SAAS,EAEf,MAAM,SAAS,CAAC;AAqCjB;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,8FAA8F;IAC9F,QAAQ,CAAC,kBAAkB,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAC1D,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAClC,uGAAuG;IACvG,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IACnD,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;CACrC;AAomBD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAyHxC;AAMD;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,2GAA2G;IAC3G,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAseD;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,8BAA8B,GACrC,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC,CAgF7C;AAMD;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IACxC,iGAAiG;IACjG,QAAQ,CAAC,gBAAgB,CAAC,EAAE,wBAAwB,CAAC;IACrD,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,wGAAwG;IACxG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AA6QD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAwC9C;AAMD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAoC9C;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CA2DxC;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,8BAA8B,GACrC,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC,CA6B7C"}
+{"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/apiClient.ts"],"names":[],"mappings":"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"}

package/lib/packlets/ai-assist/apiClient.js

@@ -388,9 +388,9 @@ async function callAnthropicCompletion(config, prompt, additionalMessages, tempe
     const url = `${config.baseUrl}/messages`;
     const messages = (0, chatRequestBuilders_1.buildAnthropicMessages)(prompt, { tail: additionalMessages });
     const body = Object.assign({ model: config.model, system: prompt.system, messages, max_tokens: 4096 }, ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort) === undefined ? { temperature } : {}));
-    if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort) !== undefined) {
-        body.thinking = { type: 'enabled' };
-        body.output_config = { effort: resolvedThinking.anthropicEffort };
+    const effort = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort;
+    if (effort !== undefined) {
+        body.thinking = { type: 'enabled', budget_tokens: (0, thinkingOptionsResolver_1.anthropicEffortToBudgetTokens)(effort) };
     }
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
         Object.assign(body, resolvedThinking.otherParams);