@fgv/ts-extras 5.1.0-55 → 5.1.0-56

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

@@ -0,0 +1,328 @@
+/**
+ * Tool types for AI assist: server-side tool configs, client-defined ("function")
+ * tools, the streaming events a tool call produces, the provider-exclusion vocabulary,
+ * and the client-tool round-trip result types.
+ *
+ * @remarks
+ * Split out of `model.ts` when the provider-exclusion types pushed that file past the
+ * 2000-line lint ceiling. The cut is along a real seam rather than an arbitrary one:
+ * everything here is about tools and nothing here depends on the rest of `model.ts`,
+ * so the module is a leaf. `model.ts` re-exports all of it, which is why no consumer
+ * import changed.
+ * @packageDocumentation
+ */
+import { type Result } from '@fgv/ts-utils';
+import { type JsonObject, type JsonSchema } from '@fgv/ts-json-base';
+/**
+ * Built-in server-side tool types supported across providers.
+ * @public
+ */
+export type AiServerToolType = 'web_search';
+/**
+ * Configuration specific to web search tools.
+ * @public
+ */
+export interface IAiWebSearchToolConfig {
+    readonly type: 'web_search';
+    /** Optional: restrict search to these domains. */
+    readonly allowedDomains?: ReadonlyArray<string>;
+    /** Optional: exclude these domains from search. */
+    readonly blockedDomains?: ReadonlyArray<string>;
+    /** Optional: max number of searches per request. */
+    readonly maxUses?: number;
+    /**
+     * Optional: enable image understanding during web search.
+     * When true, the model can view and analyze images found during search.
+     * Currently supported by xAI only; ignored by other providers.
+     */
+    readonly enableImageUnderstanding?: boolean;
+}
+/**
+ * Union of all server-side tool configurations. Discriminated on `type`.
+ * @public
+ */
+export type AiServerToolConfig = IAiWebSearchToolConfig;
+/**
+ * Declares a tool as enabled/disabled in provider settings.
+ * Tools are disabled by default — consuming apps must opt in explicitly.
+ * @public
+ */
+export interface IAiToolEnablement {
+    /** Which tool type. */
+    readonly type: AiServerToolType;
+    /** Whether this tool is enabled by default for this provider. */
+    readonly enabled: boolean;
+    /** Optional tool-specific configuration. */
+    readonly config?: AiServerToolConfig;
+}
+/**
+ * Behavior annotations for a client-defined tool.
+ *
+ * @remarks
+ * These are **host-advisory-only hints** describing a tool's side-effect profile.
+ * They are consumed by the host's tool loop (e.g. a before-execute gate) and are
+ * **never serialized to the model** — the provider wire tool-schemas whitelist
+ * `{name, description, parameters}` and ignore this field.
+ *
+ * Field names mirror MCP's `ToolAnnotations` (`@modelcontextprotocol/sdk`) 1:1 so
+ * an MCP tool's annotations pass through unchanged. Per the MCP spec, all fields
+ * are hints — a host should never make tool-use decisions based on annotations
+ * received from an untrusted server without its own validation.
+ *
+ * @public
+ */
+export interface IAiToolAnnotations {
+    /** Optional human-readable display title for the tool. */
+    readonly title?: string;
+    /** Hint: the tool does not modify its environment (read-only). */
+    readonly readOnlyHint?: boolean;
+    /** Hint: the tool may perform destructive updates (only meaningful when not read-only). */
+    readonly destructiveHint?: boolean;
+    /** Hint: repeated calls with the same arguments have no additional effect. */
+    readonly idempotentHint?: boolean;
+    /** Hint: the tool interacts with an open world of external entities. */
+    readonly openWorldHint?: boolean;
+}
+/**
+ * Configuration for a client-defined (harness-supplied) tool.
+ *
+ * @remarks
+ * The `parametersSchema` is the single source of truth for both the wire-format
+ * JSON Schema sent to the provider (via `.toJson()`) and the runtime argument
+ * validation (via `.validate(rawArgs)`). Use `JsonSchema.object(...)` from
+ * `@fgv/ts-json-base` to author the schema as a const (e.g. `const mySchema = JsonSchema.object({...})`);
+ * the static type `TParams` is then derived via `JsonSchema.Static<typeof mySchema>` —
+ * no drift between wire schema and runtime validation.
+ *
+ * @public
+ */
+export interface IAiClientToolConfig<TParams = unknown> {
+    /** Discriminator — always `'client_tool'`. */
+    readonly type: 'client_tool';
+    /** Tool name sent to the model (must be unique within a call). */
+    readonly name: string;
+    /** Human-readable description of what the tool does, shown to the model. */
+    readonly description: string;
+    /**
+     * JSON Schema validator for the tool's parameters. Emits wire format via
+     * `.toJson()` and validates model-returned args via `.validate(rawArgs)`.
+     */
+    readonly parametersSchema: JsonSchema.ISchemaValidator<TParams>;
+    /**
+     * Optional host-advisory behavior annotations (read-only / destructive /
+     * idempotent / open-world hints + display title). Consumed by the host's
+     * tool loop; never serialized to the model. See {@link AiAssist.IAiToolAnnotations}.
+     */
+    readonly annotations?: IAiToolAnnotations;
+}
+/**
+ * A client-defined tool: configuration + execution callback pair.
+ *
+ * @remarks
+ * The `execute` callback receives typed `TParams` (already validated by
+ * `config.parametersSchema.validate()`) and returns a `Promise<Result<unknown>>`.
+ * Thrown errors are caught via `captureAsyncResult` in the round-trip helper.
+ *
+ * @public
+ */
+export interface IAiClientTool<TParams = unknown> {
+    /** The tool's configuration (name, description, parameters schema). */
+    readonly config: IAiClientToolConfig<TParams>;
+    /**
+     * Execute the tool with validated parameters.
+     * @param args - Typed arguments, already validated against `config.parametersSchema`.
+     * @returns A `Promise<Result<unknown>>` — the result is stringified and sent back to the model.
+     */
+    readonly execute: (args: TParams) => Promise<Result<unknown>>;
+}
+/**
+ * Union of all tool configurations: server-side or client-defined.
+ * Discriminated on `type`.
+ * @public
+ */
+export type AiToolConfig = AiServerToolConfig | IAiClientToolConfig;
+/**
+ * Emitted when a client-defined tool call begins streaming. Carries the tool name
+ * and optional provider-assigned call ID (Anthropic / OpenAI Responses API; absent
+ * for Gemini which does not assign call IDs).
+ * @public
+ */
+export interface IAiStreamToolUseStart {
+    readonly type: 'client-tool-call-start';
+    /** The name of the client tool being called. */
+    readonly toolName: string;
+    /**
+     * Provider-assigned call identifier (Anthropic: `toolu_*`; OpenAI: `call_*`).
+     * Absent for Gemini (correlation by name).
+     */
+    readonly callId?: string;
+}
+/**
+ * Emitted when a client-defined tool call is complete and its arguments are fully
+ * accumulated. The `args` object is the fully parsed JSON object — no further
+ * streaming deltas follow for this call.
+ * @public
+ */
+export interface IAiStreamToolUseDelta {
+    readonly type: 'client-tool-call-done';
+    /** The name of the client tool being called. */
+    readonly toolName: string;
+    /**
+     * Provider-assigned call identifier. Absent for Gemini.
+     */
+    readonly callId?: string;
+    /** The fully accumulated and parsed tool arguments. */
+    readonly args: JsonObject;
+}
+/**
+ * Emitted after a client-defined tool has been executed and the result is ready
+ * to be fed back to the model in the round-trip continuation.
+ * @public
+ */
+export interface IAiStreamToolUseComplete {
+    readonly type: 'client-tool-result';
+    /** The name of the client tool that was executed. */
+    readonly toolName: string;
+    /**
+     * Provider-assigned call identifier. Absent for Gemini.
+     */
+    readonly callId?: string;
+    /** The stringified result returned by the tool's execute callback. */
+    readonly result: string;
+    /** Whether the tool execution failed (schema validation failure, execute error, or unknown tool). */
+    readonly isError: boolean;
+}
+/**
+ * What to do when a request would combine a server tool with client (function)
+ * tools on a provider that declares the two mutually exclusive (see
+ * `IAiProviderDescriptor.serverToolsExclusiveWithClientTools`).
+ *
+ * @remarks
+ * - `'drop-server-tools'` (the default) removes the offending server tools and
+ *   keeps every client tool. Client tools are what the host registered
+ *   explicitly for this turn; a built-in like grounding is a per-provider
+ *   nicety, and dropping it degrades the turn rather than losing it.
+ * - `'prefer-server-tools'` is the mirror image: keep the server tools and drop
+ *   every client tool. For hosts whose turn is *about* the grounded answer.
+ * - `'fail'` refuses the request up front with a message naming the conflict —
+ *   the behavior before this policy existed. For hosts that would rather
+ *   choose themselves than have either half silently disappear.
+ *
+ * Whichever is chosen, what actually happened is reported, never inferred: see
+ * {@link AiAssist.IAiToolConflictReport}.
+ * @public
+ */
+export type AiToolConflictPolicy = 'drop-server-tools' | 'prefer-server-tools' | 'fail';
+/**
+ * What the conflict resolution did to a turn's tools.
+ *
+ * @remarks
+ * Required on {@link AiAssist.IAiClientToolTurnResult}, not optional, for the same reason
+ * `structuredOutput` is required on a completion response: an absent report is
+ * three-ways ambiguous — nothing conflicted / this build predates the feature /
+ * the resolution ran and said nothing — and disambiguating exactly that is what
+ * it is for. A turn where nothing conflicted reports the policy that was in
+ * force and two empty arrays.
+ * @public
+ */
+export interface IAiToolConflictReport {
+    /** The policy that was in force for this turn (the default when none was passed). */
+    readonly policy: AiToolConflictPolicy;
+    /** Server tool types removed from the request. Empty when nothing was dropped. */
+    readonly droppedServerTools: ReadonlyArray<AiServerToolType>;
+    /** Names of client tools removed from the request. Empty when nothing was dropped. */
+    readonly droppedClientTools: ReadonlyArray<string>;
+}
+/**
+ * Summary of a single client tool call within a turn: the tool name, call ID,
+ * raw arguments, execution result, and whether the execution was an error.
+ * @public
+ */
+export interface IAiClientToolCallSummary {
+    /** The name of the tool that was called. */
+    readonly toolName: string;
+    /** Provider-assigned call identifier (absent for Gemini). */
+    readonly callId?: string;
+    /** The fully accumulated raw arguments object as parsed JSON. */
+    readonly args: JsonObject;
+    /** The stringified result (success value or error message). */
+    readonly result: string;
+    /** Whether execution failed (schema validation failure, execute error, or unknown tool). */
+    readonly isError: boolean;
+}
+/**
+ * The provider-specific continuation data needed to build the follow-up request
+ * for the next round of the conversation.
+ *
+ * @remarks
+ * `messages` are provider-native request objects (Anthropic: content-block arrays,
+ * OpenAI Responses API: input items, Gemini: content parts). The continuation
+ * builder in `clientToolContinuationBuilder.ts` populates this.
+ *
+ * @public
+ */
+export interface IAiClientToolContinuation {
+    /**
+     * **Cumulative** provider-native wire-format message objects covering all
+     * tool rounds so far. On each turn, `executeClientToolTurn` prepends the
+     * inbound `continuationMessages` so that this array always contains the
+     * complete wire tail from round 1 through the current round.
+     *
+     * To drive a multi-round loop, simply **replace** `continuationMessages`
+     * with this value — do not manually concatenate:
+     *
+     * ```ts
+     * let tail: JsonObject[] | undefined;
+     * while (true) {
+     *   const { events, nextTurn } = executeClientToolTurn({
+     *     ..., continuationMessages: tail
+     *   }).orThrow();
+     *   for await (const e of events) { /* observe *\/ }
+     *   const outcome = (await nextTurn).orThrow();
+     *   if (!outcome.continuation) break;
+     *   tail = [...outcome.continuation.messages]; // replace — already cumulative
+     * }
+     * ```
+     *
+     * The exact shape is provider-native and may include provider-specific
+     * blocks (e.g. Anthropic thinking/redacted_thinking/tool_use, OpenAI
+     * function_call/function_call_output items, Gemini functionCall/functionResponse
+     * parts). These are NOT `IChatMessage[]` and must NOT be placed in the
+     * `messages` parameter — the normalized-message path strips provider-native
+     * fields (thinking signatures, redacted_thinking data) that the server
+     * requires for continuation validation.
+     *
+     * `toolCallsSummary` is per-round only (the calls executed in the current
+     * turn). Only `messages` is cumulative.
+     */
+    readonly messages: ReadonlyArray<JsonObject>;
+    /** Summary of each tool call executed in this turn (per-round, not cumulative). */
+    readonly toolCallsSummary: ReadonlyArray<IAiClientToolCallSummary>;
+}
+/**
+ * The result of a single client-tool turn: the optional continuation for the next
+ * call (absent when no tool calls occurred) and whether the stream was truncated.
+ * @public
+ */
+export interface IAiClientToolTurnResult {
+    /**
+     * The continuation data for the next round-trip. `undefined` when the model
+     * completed without invoking any client tools.
+     */
+    readonly continuation: IAiClientToolContinuation | undefined;
+    /** Whether the stream was truncated (token limit or stop reason). */
+    readonly truncated: boolean;
+    /** The full concatenated text from all `text-delta` events in this turn. */
+    readonly fullText: string;
+    /**
+     * What the provider tool-conflict resolution did to this turn's tools.
+     * Always present; empty arrays mean nothing conflicted.
+     *
+     * @remarks
+     * Read this to tell the person (or the model, on a later turn) that a
+     * capability they expected was unavailable — e.g. that web search was dropped
+     * because the pinned model cannot ground and call functions in one request.
+     */
+    readonly toolConflicts: IAiToolConflictReport;
+}
+//# sourceMappingURL=toolTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toolTypes.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/toolTypes.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,22 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=toolTypes.js.map

package/lib/packlets/ai-assist/toolTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolTypes.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/toolTypes.ts"],"names":[],"mappings":";AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Tool types for AI assist: server-side tool configs, client-defined (\"function\")\n * tools, the streaming events a tool call produces, the provider-exclusion vocabulary,\n * and the client-tool round-trip result types.\n *\n * @remarks\n * Split out of `model.ts` when the provider-exclusion types pushed that file past the\n * 2000-line lint ceiling. The cut is along a real seam rather than an arbitrary one:\n * everything here is about tools and nothing here depends on the rest of `model.ts`,\n * so the module is a leaf. `model.ts` re-exports all of it, which is why no consumer\n * import changed.\n * @packageDocumentation\n */\n\nimport { type Result } from '@fgv/ts-utils';\nimport { type JsonObject, type JsonSchema } from '@fgv/ts-json-base';\n\n// ============================================================================\n// Server-Side Tools\n// ============================================================================\n\n/**\n * Built-in server-side tool types supported across providers.\n * @public\n */\nexport type AiServerToolType = 'web_search';\n\n/**\n * Configuration specific to web search tools.\n * @public\n */\nexport interface IAiWebSearchToolConfig {\n  readonly type: 'web_search';\n  /** Optional: restrict search to these domains. */\n  readonly allowedDomains?: ReadonlyArray<string>;\n  /** Optional: exclude these domains from search. */\n  readonly blockedDomains?: ReadonlyArray<string>;\n  /** Optional: max number of searches per request. */\n  readonly maxUses?: number;\n  /**\n   * Optional: enable image understanding during web search.\n   * When true, the model can view and analyze images found during search.\n   * Currently supported by xAI only; ignored by other providers.\n   */\n  readonly enableImageUnderstanding?: boolean;\n}\n\n/**\n * Union of all server-side tool configurations. Discriminated on `type`.\n * @public\n */\nexport type AiServerToolConfig = IAiWebSearchToolConfig;\n\n/**\n * Declares a tool as enabled/disabled in provider settings.\n * Tools are disabled by default — consuming apps must opt in explicitly.\n * @public\n */\nexport interface IAiToolEnablement {\n  /** Which tool type. */\n  readonly type: AiServerToolType;\n  /** Whether this tool is enabled by default for this provider. */\n  readonly enabled: boolean;\n  /** Optional tool-specific configuration. */\n  readonly config?: AiServerToolConfig;\n}\n\n// ============================================================================\n// Client-Defined Tools\n// ============================================================================\n\n/**\n * Behavior annotations for a client-defined tool.\n *\n * @remarks\n * These are **host-advisory-only hints** describing a tool's side-effect profile.\n * They are consumed by the host's tool loop (e.g. a before-execute gate) and are\n * **never serialized to the model** — the provider wire tool-schemas whitelist\n * `{name, description, parameters}` and ignore this field.\n *\n * Field names mirror MCP's `ToolAnnotations` (`@modelcontextprotocol/sdk`) 1:1 so\n * an MCP tool's annotations pass through unchanged. Per the MCP spec, all fields\n * are hints — a host should never make tool-use decisions based on annotations\n * received from an untrusted server without its own validation.\n *\n * @public\n */\nexport interface IAiToolAnnotations {\n  /** Optional human-readable display title for the tool. */\n  readonly title?: string;\n  /** Hint: the tool does not modify its environment (read-only). */\n  readonly readOnlyHint?: boolean;\n  /** Hint: the tool may perform destructive updates (only meaningful when not read-only). */\n  readonly destructiveHint?: boolean;\n  /** Hint: repeated calls with the same arguments have no additional effect. */\n  readonly idempotentHint?: boolean;\n  /** Hint: the tool interacts with an open world of external entities. */\n  readonly openWorldHint?: boolean;\n}\n\n/**\n * Configuration for a client-defined (harness-supplied) tool.\n *\n * @remarks\n * The `parametersSchema` is the single source of truth for both the wire-format\n * JSON Schema sent to the provider (via `.toJson()`) and the runtime argument\n * validation (via `.validate(rawArgs)`). Use `JsonSchema.object(...)` from\n * `@fgv/ts-json-base` to author the schema as a const (e.g. `const mySchema = JsonSchema.object({...})`);\n * the static type `TParams` is then derived via `JsonSchema.Static<typeof mySchema>` —\n * no drift between wire schema and runtime validation.\n *\n * @public\n */\nexport interface IAiClientToolConfig<TParams = unknown> {\n  /** Discriminator — always `'client_tool'`. */\n  readonly type: 'client_tool';\n  /** Tool name sent to the model (must be unique within a call). */\n  readonly name: string;\n  /** Human-readable description of what the tool does, shown to the model. */\n  readonly description: string;\n  /**\n   * JSON Schema validator for the tool's parameters. Emits wire format via\n   * `.toJson()` and validates model-returned args via `.validate(rawArgs)`.\n   */\n  readonly parametersSchema: JsonSchema.ISchemaValidator<TParams>;\n  /**\n   * Optional host-advisory behavior annotations (read-only / destructive /\n   * idempotent / open-world hints + display title). Consumed by the host's\n   * tool loop; never serialized to the model. See {@link AiAssist.IAiToolAnnotations}.\n   */\n  readonly annotations?: IAiToolAnnotations;\n}\n\n/**\n * A client-defined tool: configuration + execution callback pair.\n *\n * @remarks\n * The `execute` callback receives typed `TParams` (already validated by\n * `config.parametersSchema.validate()`) and returns a `Promise<Result<unknown>>`.\n * Thrown errors are caught via `captureAsyncResult` in the round-trip helper.\n *\n * @public\n */\nexport interface IAiClientTool<TParams = unknown> {\n  /** The tool's configuration (name, description, parameters schema). */\n  readonly config: IAiClientToolConfig<TParams>;\n  /**\n   * Execute the tool with validated parameters.\n   * @param args - Typed arguments, already validated against `config.parametersSchema`.\n   * @returns A `Promise<Result<unknown>>` — the result is stringified and sent back to the model.\n   */\n  readonly execute: (args: TParams) => Promise<Result<unknown>>;\n}\n\n/**\n * Union of all tool configurations: server-side or client-defined.\n * Discriminated on `type`.\n * @public\n */\nexport type AiToolConfig = AiServerToolConfig | IAiClientToolConfig;\n\n// ============================================================================\n// Client Tool Streaming Events\n// ============================================================================\n\n/**\n * Emitted when a client-defined tool call begins streaming. Carries the tool name\n * and optional provider-assigned call ID (Anthropic / OpenAI Responses API; absent\n * for Gemini which does not assign call IDs).\n * @public\n */\nexport interface IAiStreamToolUseStart {\n  readonly type: 'client-tool-call-start';\n  /** The name of the client tool being called. */\n  readonly toolName: string;\n  /**\n   * Provider-assigned call identifier (Anthropic: `toolu_*`; OpenAI: `call_*`).\n   * Absent for Gemini (correlation by name).\n   */\n  readonly callId?: string;\n}\n\n/**\n * Emitted when a client-defined tool call is complete and its arguments are fully\n * accumulated. The `args` object is the fully parsed JSON object — no further\n * streaming deltas follow for this call.\n * @public\n */\nexport interface IAiStreamToolUseDelta {\n  readonly type: 'client-tool-call-done';\n  /** The name of the client tool being called. */\n  readonly toolName: string;\n  /**\n   * Provider-assigned call identifier. Absent for Gemini.\n   */\n  readonly callId?: string;\n  /** The fully accumulated and parsed tool arguments. */\n  readonly args: JsonObject;\n}\n\n/**\n * Emitted after a client-defined tool has been executed and the result is ready\n * to be fed back to the model in the round-trip continuation.\n * @public\n */\nexport interface IAiStreamToolUseComplete {\n  readonly type: 'client-tool-result';\n  /** The name of the client tool that was executed. */\n  readonly toolName: string;\n  /**\n   * Provider-assigned call identifier. Absent for Gemini.\n   */\n  readonly callId?: string;\n  /** The stringified result returned by the tool's execute callback. */\n  readonly result: string;\n  /** Whether the tool execution failed (schema validation failure, execute error, or unknown tool). */\n  readonly isError: boolean;\n}\n\n// ============================================================================\n// Server/Client Tool Conflicts\n// ============================================================================\n\n/**\n * What to do when a request would combine a server tool with client (function)\n * tools on a provider that declares the two mutually exclusive (see\n * `IAiProviderDescriptor.serverToolsExclusiveWithClientTools`).\n *\n * @remarks\n * - `'drop-server-tools'` (the default) removes the offending server tools and\n *   keeps every client tool. Client tools are what the host registered\n *   explicitly for this turn; a built-in like grounding is a per-provider\n *   nicety, and dropping it degrades the turn rather than losing it.\n * - `'prefer-server-tools'` is the mirror image: keep the server tools and drop\n *   every client tool. For hosts whose turn is *about* the grounded answer.\n * - `'fail'` refuses the request up front with a message naming the conflict —\n *   the behavior before this policy existed. For hosts that would rather\n *   choose themselves than have either half silently disappear.\n *\n * Whichever is chosen, what actually happened is reported, never inferred: see\n * {@link AiAssist.IAiToolConflictReport}.\n * @public\n */\nexport type AiToolConflictPolicy = 'drop-server-tools' | 'prefer-server-tools' | 'fail';\n\n/**\n * What the conflict resolution did to a turn's tools.\n *\n * @remarks\n * Required on {@link AiAssist.IAiClientToolTurnResult}, not optional, for the same reason\n * `structuredOutput` is required on a completion response: an absent report is\n * three-ways ambiguous — nothing conflicted / this build predates the feature /\n * the resolution ran and said nothing — and disambiguating exactly that is what\n * it is for. A turn where nothing conflicted reports the policy that was in\n * force and two empty arrays.\n * @public\n */\nexport interface IAiToolConflictReport {\n  /** The policy that was in force for this turn (the default when none was passed). */\n  readonly policy: AiToolConflictPolicy;\n  /** Server tool types removed from the request. Empty when nothing was dropped. */\n  readonly droppedServerTools: ReadonlyArray<AiServerToolType>;\n  /** Names of client tools removed from the request. Empty when nothing was dropped. */\n  readonly droppedClientTools: ReadonlyArray<string>;\n}\n\n// ============================================================================\n// Client Tool Round-Trip Types\n// ============================================================================\n\n/**\n * Summary of a single client tool call within a turn: the tool name, call ID,\n * raw arguments, execution result, and whether the execution was an error.\n * @public\n */\nexport interface IAiClientToolCallSummary {\n  /** The name of the tool that was called. */\n  readonly toolName: string;\n  /** Provider-assigned call identifier (absent for Gemini). */\n  readonly callId?: string;\n  /** The fully accumulated raw arguments object as parsed JSON. */\n  readonly args: JsonObject;\n  /** The stringified result (success value or error message). */\n  readonly result: string;\n  /** Whether execution failed (schema validation failure, execute error, or unknown tool). */\n  readonly isError: boolean;\n}\n\n/**\n * The provider-specific continuation data needed to build the follow-up request\n * for the next round of the conversation.\n *\n * @remarks\n * `messages` are provider-native request objects (Anthropic: content-block arrays,\n * OpenAI Responses API: input items, Gemini: content parts). The continuation\n * builder in `clientToolContinuationBuilder.ts` populates this.\n *\n * @public\n */\nexport interface IAiClientToolContinuation {\n  /**\n   * **Cumulative** provider-native wire-format message objects covering all\n   * tool rounds so far. On each turn, `executeClientToolTurn` prepends the\n   * inbound `continuationMessages` so that this array always contains the\n   * complete wire tail from round 1 through the current round.\n   *\n   * To drive a multi-round loop, simply **replace** `continuationMessages`\n   * with this value — do not manually concatenate:\n   *\n   * ```ts\n   * let tail: JsonObject[] | undefined;\n   * while (true) {\n   *   const { events, nextTurn } = executeClientToolTurn({\n   *     ..., continuationMessages: tail\n   *   }).orThrow();\n   *   for await (const e of events) { /* observe *\\/ }\n   *   const outcome = (await nextTurn).orThrow();\n   *   if (!outcome.continuation) break;\n   *   tail = [...outcome.continuation.messages]; // replace — already cumulative\n   * }\n   * ```\n   *\n   * The exact shape is provider-native and may include provider-specific\n   * blocks (e.g. Anthropic thinking/redacted_thinking/tool_use, OpenAI\n   * function_call/function_call_output items, Gemini functionCall/functionResponse\n   * parts). These are NOT `IChatMessage[]` and must NOT be placed in the\n   * `messages` parameter — the normalized-message path strips provider-native\n   * fields (thinking signatures, redacted_thinking data) that the server\n   * requires for continuation validation.\n   *\n   * `toolCallsSummary` is per-round only (the calls executed in the current\n   * turn). Only `messages` is cumulative.\n   */\n  readonly messages: ReadonlyArray<JsonObject>;\n  /** Summary of each tool call executed in this turn (per-round, not cumulative). */\n  readonly toolCallsSummary: ReadonlyArray<IAiClientToolCallSummary>;\n}\n\n/**\n * The result of a single client-tool turn: the optional continuation for the next\n * call (absent when no tool calls occurred) and whether the stream was truncated.\n * @public\n */\nexport interface IAiClientToolTurnResult {\n  /**\n   * The continuation data for the next round-trip. `undefined` when the model\n   * completed without invoking any client tools.\n   */\n  readonly continuation: IAiClientToolContinuation | undefined;\n  /** Whether the stream was truncated (token limit or stop reason). */\n  readonly truncated: boolean;\n  /** The full concatenated text from all `text-delta` events in this turn. */\n  readonly fullText: string;\n  /**\n   * What the provider tool-conflict resolution did to this turn's tools.\n   * Always present; empty arrays mean nothing conflicted.\n   *\n   * @remarks\n   * Read this to tell the person (or the model, on a later turn) that a\n   * capability they expected was unavailable — e.g. that web search was dropped\n   * because the pinned model cannot ground and call functions in one request.\n   */\n  readonly toolConflicts: IAiToolConflictReport;\n}\n"]}

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

@@ -0,0 +1,58 @@
+/**
+ * Per-wire-shape `usage` block normalization, shared by the non-streaming
+ * adapters (`completionClient.ts`) and the streaming adapters
+ * (`streamingAdapters/*.ts`) so the same JSON layout is parsed once.
+ *
+ * @remarks
+ * Every function here follows one rule throughout: a field that is absent
+ * from the wire response stays absent on {@link AiAssist.IAiCompletionUsage} —
+ * never defaulted to `0`, and never derived from a sibling field unless the
+ * value that sibling would need is itself known. See `IAiCompletionUsage`
+ * for why.
+ * @packageDocumentation
+ */
+import { type JsonObject } from '@fgv/ts-json-base';
+import { type IAiCompletionUsage } from './usageTypes';
+/**
+ * Normalizes an Anthropic Messages API `usage` block. Anthropic always
+ * reports both reads and writes, so `reports` is unconditionally
+ * `'reads-and-writes'` — an absent `cache_creation_input_tokens` genuinely
+ * means zero tokens were written this request.
+ * @internal
+ */
+export declare function normalizeAnthropicUsage(raw: JsonObject | undefined): IAiCompletionUsage | undefined;
+/**
+ * Normalizes an OpenAI/xAI Chat Completions `usage` block. `reports` is
+ * unconditionally `'reads'`: `cache_write_tokens` does not exist on this API
+ * for any provider reached through it, so `cacheWriteTokens` is never set —
+ * not even to `0`.
+ * @internal
+ */
+export declare function normalizeOpenAiChatUsage(raw: JsonObject | undefined): IAiCompletionUsage | undefined;
+/**
+ * Normalizes an OpenAI/xAI Responses API `usage` block. This route is shared
+ * by two providers that disagree about write reporting — OpenAI always sends
+ * `cache_write_tokens` (even when `0`), xAI never does — so `reports` is
+ * derived from field **presence**, not from provider identity: a wire that
+ * sends the field, however small its value, is `'reads-and-writes'`; a wire
+ * that omits it entirely is `'reads'`.
+ * @internal
+ */
+export declare function normalizeOpenAiResponsesUsage(raw: JsonObject | undefined): IAiCompletionUsage | undefined;
+/**
+ * Normalizes a Gemini `usageMetadata` block. `reports` is unconditionally
+ * `'reads'` — Gemini has no cache-write concept in a `generateContent` call;
+ * writes happen out-of-band via the explicit `cachedContents` resource,
+ * out of scope per the design (§10).
+ *
+ * @remarks
+ * The Gemini-specific footgun: `promptTokenCount` already **includes**
+ * `cachedContentTokenCount` (it is the total effective prompt size), unlike
+ * OpenAI where the cached figure sits in a sub-object alongside a separate
+ * total. `uncachedInputTokens` subtracts to correct for it — but only when
+ * `cachedContentTokenCount` is itself present, per the module's absent-means-
+ * absent rule.
+ * @internal
+ */
+export declare function normalizeGeminiUsage(raw: JsonObject | undefined): IAiCompletionUsage | undefined;
+//# sourceMappingURL=usageNormalization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usageNormalization.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/usageNormalization.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAA8B,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAqBnF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAuBnG;AA2BD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CA6BpG;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CA4BzG;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CA4BhG"}

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

@@ -0,0 +1,184 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAnthropicUsage = normalizeAnthropicUsage;
+exports.normalizeOpenAiChatUsage = normalizeOpenAiChatUsage;
+exports.normalizeOpenAiResponsesUsage = normalizeOpenAiResponsesUsage;
+exports.normalizeGeminiUsage = normalizeGeminiUsage;
+const ts_utils_1 = require("@fgv/ts-utils");
+const anthropicRawUsage = ts_utils_1.Validators.object({
+    input_tokens: ts_utils_1.Validators.number,
+    output_tokens: ts_utils_1.Validators.number.optional(),
+    cache_creation_input_tokens: ts_utils_1.Validators.number.optional(),
+    cache_read_input_tokens: ts_utils_1.Validators.number.optional()
+});
+/**
+ * Normalizes an Anthropic Messages API `usage` block. Anthropic always
+ * reports both reads and writes, so `reports` is unconditionally
+ * `'reads-and-writes'` — an absent `cache_creation_input_tokens` genuinely
+ * means zero tokens were written this request.
+ * @internal
+ */
+function normalizeAnthropicUsage(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = anthropicRawUsage.validate(raw);
+    if (parsed.isFailure()) {
+        return undefined;
+    }
+    const { input_tokens: uncachedInputTokens, output_tokens: outputTokens, cache_creation_input_tokens: cacheWriteTokens, cache_read_input_tokens: cachedInputTokens } = parsed.value;
+    return {
+        reports: 'reads-and-writes',
+        uncachedInputTokens,
+        cachedInputTokens,
+        cacheWriteTokens,
+        outputTokens,
+        totalInputTokens: cachedInputTokens !== undefined ? uncachedInputTokens + cachedInputTokens : undefined,
+        raw
+    };
+}
+const openAiChatPromptTokensDetails = ts_utils_1.Validators.object({ cached_tokens: ts_utils_1.Validators.number.optional() });
+const openAiChatRawUsage = ts_utils_1.Validators.object({
+    prompt_tokens: ts_utils_1.Validators.number.optional(),
+    completion_tokens: ts_utils_1.Validators.number.optional(),
+    prompt_tokens_details: openAiChatPromptTokensDetails.optional()
+});
+/**
+ * Normalizes an OpenAI/xAI Chat Completions `usage` block. `reports` is
+ * unconditionally `'reads'`: `cache_write_tokens` does not exist on this API
+ * for any provider reached through it, so `cacheWriteTokens` is never set —
+ * not even to `0`.
+ * @internal
+ */
+function normalizeOpenAiChatUsage(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = openAiChatRawUsage.validate(raw);
+    if (parsed.isFailure()) {
+        return undefined;
+    }
+    const { prompt_tokens: promptTokens, completion_tokens: outputTokens, prompt_tokens_details } = parsed.value;
+    const cachedInputTokens = prompt_tokens_details === null || prompt_tokens_details === void 0 ? void 0 : prompt_tokens_details.cached_tokens;
+    const uncachedInputTokens = cachedInputTokens !== undefined && promptTokens !== undefined
+        ? promptTokens - cachedInputTokens
+        : undefined;
+    return {
+        reports: 'reads',
+        uncachedInputTokens,
+        cachedInputTokens,
+        outputTokens,
+        totalInputTokens: uncachedInputTokens !== undefined && cachedInputTokens !== undefined
+            ? uncachedInputTokens + cachedInputTokens
+            : undefined,
+        raw
+    };
+}
+const openAiResponsesInputTokensDetails = ts_utils_1.Validators.object({
+    cached_tokens: ts_utils_1.Validators.number.optional(),
+    cache_write_tokens: ts_utils_1.Validators.number.optional()
+});
+const openAiResponsesRawUsage = ts_utils_1.Validators.object({
+    input_tokens: ts_utils_1.Validators.number.optional(),
+    output_tokens: ts_utils_1.Validators.number.optional(),
+    input_tokens_details: openAiResponsesInputTokensDetails.optional()
+});
+/**
+ * Normalizes an OpenAI/xAI Responses API `usage` block. This route is shared
+ * by two providers that disagree about write reporting — OpenAI always sends
+ * `cache_write_tokens` (even when `0`), xAI never does — so `reports` is
+ * derived from field **presence**, not from provider identity: a wire that
+ * sends the field, however small its value, is `'reads-and-writes'`; a wire
+ * that omits it entirely is `'reads'`.
+ * @internal
+ */
+function normalizeOpenAiResponsesUsage(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = openAiResponsesRawUsage.validate(raw);
+    if (parsed.isFailure()) {
+        return undefined;
+    }
+    const { input_tokens: inputTokens, output_tokens: outputTokens, input_tokens_details } = parsed.value;
+    const cachedInputTokens = input_tokens_details === null || input_tokens_details === void 0 ? void 0 : input_tokens_details.cached_tokens;
+    const cacheWriteTokens = input_tokens_details === null || input_tokens_details === void 0 ? void 0 : input_tokens_details.cache_write_tokens;
+    const reports = cacheWriteTokens !== undefined ? 'reads-and-writes' : 'reads';
+    const uncachedInputTokens = cachedInputTokens !== undefined && inputTokens !== undefined
+        ? inputTokens - cachedInputTokens
+        : undefined;
+    return {
+        reports,
+        uncachedInputTokens,
+        cachedInputTokens,
+        cacheWriteTokens,
+        outputTokens,
+        totalInputTokens: uncachedInputTokens !== undefined && cachedInputTokens !== undefined
+            ? uncachedInputTokens + cachedInputTokens
+            : undefined,
+        raw
+    };
+}
+const geminiRawUsage = ts_utils_1.Validators.object({
+    promptTokenCount: ts_utils_1.Validators.number.optional(),
+    candidatesTokenCount: ts_utils_1.Validators.number.optional(),
+    cachedContentTokenCount: ts_utils_1.Validators.number.optional()
+});
+/**
+ * Normalizes a Gemini `usageMetadata` block. `reports` is unconditionally
+ * `'reads'` — Gemini has no cache-write concept in a `generateContent` call;
+ * writes happen out-of-band via the explicit `cachedContents` resource,
+ * out of scope per the design (§10).
+ *
+ * @remarks
+ * The Gemini-specific footgun: `promptTokenCount` already **includes**
+ * `cachedContentTokenCount` (it is the total effective prompt size), unlike
+ * OpenAI where the cached figure sits in a sub-object alongside a separate
+ * total. `uncachedInputTokens` subtracts to correct for it — but only when
+ * `cachedContentTokenCount` is itself present, per the module's absent-means-
+ * absent rule.
+ * @internal
+ */
+function normalizeGeminiUsage(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = geminiRawUsage.validate(raw);
+    if (parsed.isFailure()) {
+        return undefined;
+    }
+    const { promptTokenCount, candidatesTokenCount: outputTokens, cachedContentTokenCount: cachedInputTokens } = parsed.value;
+    const uncachedInputTokens = cachedInputTokens !== undefined && promptTokenCount !== undefined
+        ? promptTokenCount - cachedInputTokens
+        : undefined;
+    return {
+        reports: 'reads',
+        uncachedInputTokens,
+        cachedInputTokens,
+        outputTokens,
+        totalInputTokens: uncachedInputTokens !== undefined && cachedInputTokens !== undefined
+            ? uncachedInputTokens + cachedInputTokens
+            : undefined,
+        raw
+    };
+}
+//# sourceMappingURL=usageNormalization.js.map