@fgv/ts-extras 5.1.0-5 → 5.1.0-50

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.57.7"
+      "packageVersion": "7.58.9"
     }
   ]
 }

package/lib/index.browser.d.ts

@@ -1,10 +1,13 @@
-import * as Crypto from './packlets/crypto-utils/index.browser';
+import * as AiAssist from './packlets/ai-assist';
+import * as CryptoUtils from './packlets/crypto-utils/index.browser';
 import * as Csv from './packlets/csv/index.browser';
 import * as Experimental from './packlets/experimental';
 import * as Hash from './packlets/hash/index.browser';
 import * as Mustache from './packlets/mustache';
 import * as RecordJar from './packlets/record-jar/index.browser';
+import * as SaferFetch from './packlets/safer-fetch/index.browser';
+import * as Yaml from './packlets/yaml';
 import * as ZipFileTree from './packlets/zip-file-tree';
 import { Converters } from './packlets/conversion';
-export { Converters, Crypto, Csv, Experimental, Hash, Mustache, RecordJar, ZipFileTree };
+export { AiAssist, Converters, CryptoUtils, CryptoUtils as Crypto, Csv, Experimental, Hash, Mustache, RecordJar, SaferFetch, Yaml, ZipFileTree };
 //# sourceMappingURL=index.browser.d.ts.map

package/lib/index.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AAEjD,OAAO,KAAK,WAAW,MAAM,uCAAuC,CAAC;AAErE,OAAO,KAAK,GAAG,MAAM,8BAA8B,CAAC;AACpD,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AAExD,OAAO,KAAK,IAAI,MAAM,+BAA+B,CAAC;AACtD,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAEhD,OAAO,KAAK,SAAS,MAAM,qCAAqC,CAAC;AAEjE,OAAO,KAAK,UAAU,MAAM,sCAAsC,CAAC;AACnE,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAInD,OAAO,EACL,QAAQ,EACR,UAAU,EACV,WAAW,EACX,WAAW,IAAI,MAAM,EACrB,GAAG,EACH,YAAY,EACZ,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,UAAU,EACV,IAAI,EACJ,WAAW,EACZ,CAAC"}

package/lib/index.browser.js

@@ -54,11 +54,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZipFileTree = exports.RecordJar = exports.Mustache = exports.Hash = exports.Experimental = exports.Csv = exports.Crypto = exports.Converters = void 0;
+exports.ZipFileTree = exports.Yaml = exports.SaferFetch = exports.RecordJar = exports.Mustache = exports.Hash = exports.Experimental = exports.Csv = exports.Crypto = exports.CryptoUtils = exports.Converters = exports.AiAssist = void 0;
 /* c8 ignore start - Browser-specific export used conditionally in package.json */
+const AiAssist = __importStar(require("./packlets/ai-assist"));
+exports.AiAssist = AiAssist;
 // eslint-disable-next-line @rushstack/packlets/mechanics
-const Crypto = __importStar(require("./packlets/crypto-utils/index.browser"));
-exports.Crypto = Crypto;
+const CryptoUtils = __importStar(require("./packlets/crypto-utils/index.browser"));
+exports.CryptoUtils = CryptoUtils;
+exports.Crypto = CryptoUtils;
 // eslint-disable-next-line @rushstack/packlets/mechanics
 const Csv = __importStar(require("./packlets/csv/index.browser"));
 exports.Csv = Csv;
@@ -72,6 +75,11 @@ exports.Mustache = Mustache;
 // eslint-disable-next-line @rushstack/packlets/mechanics
 const RecordJar = __importStar(require("./packlets/record-jar/index.browser"));
 exports.RecordJar = RecordJar;
+// eslint-disable-next-line @rushstack/packlets/mechanics
+const SaferFetch = __importStar(require("./packlets/safer-fetch/index.browser"));
+exports.SaferFetch = SaferFetch;
+const Yaml = __importStar(require("./packlets/yaml"));
+exports.Yaml = Yaml;
 const ZipFileTree = __importStar(require("./packlets/zip-file-tree"));
 exports.ZipFileTree = ZipFileTree;
 const conversion_1 = require("./packlets/conversion");

package/lib/index.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,kFAAkF;AAClF,+DAAiD;AAqB/C,4BAAQ;AApBV,yDAAyD;AACzD,mFAAqE;AAqBnE,kCAAW;AACI,6BAAM;AArBvB,yDAAyD;AACzD,kEAAoD;AAqBlD,kBAAG;AApBL,sEAAwD;AAqBtD,oCAAY;AApBd,yDAAyD;AACzD,oEAAsD;AAoBpD,oBAAI;AAnBN,8DAAgD;AAoB9C,4BAAQ;AAnBV,yDAAyD;AACzD,+EAAiE;AAmB/D,8BAAS;AAlBX,yDAAyD;AACzD,iFAAmE;AAkBjE,gCAAU;AAjBZ,sDAAwC;AAkBtC,oBAAI;AAjBN,sEAAwD;AAkBtD,kCAAW;AAhBb,sDAAmD;AAMjD,2FANO,uBAAU,OAMP;AAYZ,oBAAoB","sourcesContent":["/*\n * Copyright (c) 2020 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/* c8 ignore start - Browser-specific export used conditionally in package.json */\nimport * as AiAssist from './packlets/ai-assist';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as CryptoUtils from './packlets/crypto-utils/index.browser';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as Csv from './packlets/csv/index.browser';\nimport * as Experimental from './packlets/experimental';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as Hash from './packlets/hash/index.browser';\nimport * as Mustache from './packlets/mustache';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as RecordJar from './packlets/record-jar/index.browser';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as SaferFetch from './packlets/safer-fetch/index.browser';\nimport * as Yaml from './packlets/yaml';\nimport * as ZipFileTree from './packlets/zip-file-tree';\n\nimport { Converters } from './packlets/conversion';\n\n// Browser-safe exports - Node.js crypto-based providers excluded\n// Use BrowserCryptoProvider from @fgv/ts-web-extras for browser crypto\nexport {\n  AiAssist,\n  Converters,\n  CryptoUtils,\n  CryptoUtils as Crypto,\n  Csv,\n  Experimental,\n  Hash,\n  Mustache,\n  RecordJar,\n  SaferFetch,\n  Yaml,\n  ZipFileTree\n};\n/* c8 ignore stop */\n"]}

package/lib/index.d.ts

@@ -5,8 +5,9 @@ import * as Experimental from './packlets/experimental';
 import * as Hash from './packlets/hash';
 import * as Mustache from './packlets/mustache';
 import * as RecordJar from './packlets/record-jar';
+import * as SaferFetch from './packlets/safer-fetch';
 import * as Yaml from './packlets/yaml';
 import * as ZipFileTree from './packlets/zip-file-tree';
 import { Converters } from './packlets/conversion';
-export { AiAssist, Converters, CryptoUtils, Csv, Experimental, Hash, Mustache, RecordJar, Yaml, ZipFileTree };
+export { AiAssist, Converters, CryptoUtils, Csv, Experimental, Hash, Mustache, RecordJar, SaferFetch, Yaml, ZipFileTree };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EACL,QAAQ,EACR,UAAU,EACV,WAAW,EACX,GAAG,EACH,YAAY,EACZ,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,UAAU,EACV,IAAI,EACJ,WAAW,EACZ,CAAC"}

package/lib/index.js

@@ -54,7 +54,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZipFileTree = exports.Yaml = exports.RecordJar = exports.Mustache = exports.Hash = exports.Experimental = exports.Csv = exports.CryptoUtils = exports.Converters = exports.AiAssist = void 0;
+exports.ZipFileTree = exports.Yaml = exports.SaferFetch = exports.RecordJar = exports.Mustache = exports.Hash = exports.Experimental = exports.Csv = exports.CryptoUtils = exports.Converters = exports.AiAssist = void 0;
 const AiAssist = __importStar(require("./packlets/ai-assist"));
 exports.AiAssist = AiAssist;
 const CryptoUtils = __importStar(require("./packlets/crypto-utils"));
@@ -69,6 +69,8 @@ const Mustache = __importStar(require("./packlets/mustache"));
 exports.Mustache = Mustache;
 const RecordJar = __importStar(require("./packlets/record-jar"));
 exports.RecordJar = RecordJar;
+const SaferFetch = __importStar(require("./packlets/safer-fetch"));
+exports.SaferFetch = SaferFetch;
 const Yaml = __importStar(require("./packlets/yaml"));
 exports.Yaml = Yaml;
 const ZipFileTree = __importStar(require("./packlets/zip-file-tree"));

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,+DAAiD;AAc/C,4BAAQ;AAbV,qEAAuD;AAerD,kCAAW;AAdb,oDAAsC;AAepC,kBAAG;AAdL,sEAAwD;AAetD,oCAAY;AAdd,sDAAwC;AAetC,oBAAI;AAdN,8DAAgD;AAe9C,4BAAQ;AAdV,iEAAmD;AAejD,8BAAS;AAdX,mEAAqD;AAenD,gCAAU;AAdZ,sDAAwC;AAetC,oBAAI;AAdN,sEAAwD;AAetD,kCAAW;AAbb,sDAAmD;AAIjD,2FAJO,uBAAU,OAIP","sourcesContent":["/*\n * Copyright (c) 2020 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\nimport * as AiAssist from './packlets/ai-assist';\nimport * as CryptoUtils from './packlets/crypto-utils';\nimport * as Csv from './packlets/csv';\nimport * as Experimental from './packlets/experimental';\nimport * as Hash from './packlets/hash';\nimport * as Mustache from './packlets/mustache';\nimport * as RecordJar from './packlets/record-jar';\nimport * as SaferFetch from './packlets/safer-fetch';\nimport * as Yaml from './packlets/yaml';\nimport * as ZipFileTree from './packlets/zip-file-tree';\n\nimport { Converters } from './packlets/conversion';\n\nexport {\n  AiAssist,\n  Converters,\n  CryptoUtils,\n  Csv,\n  Experimental,\n  Hash,\n  Mustache,\n  RecordJar,\n  SaferFetch,\n  Yaml,\n  ZipFileTree\n};\n"]}

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

@@ -0,0 +1,149 @@
+/**
+ * Per-format chat request shape builders. Shared between the synchronous
+ * (`apiClient.ts`) and streaming (`streamingClient.ts`) paths so the wire
+ * shapes stay consistent.
+ *
+ * @packageDocumentation
+ */
+import { type JsonObject } from '@fgv/ts-json-base';
+import { Result } from '@fgv/ts-utils';
+import { AiPrompt, type IChatMessage } from './model';
+/**
+ * The result of splitting an {@link AiAssist.IChatRequest} into the per-builder
+ * inputs: the current turn (as an {@link AiPrompt}, carrying system + the final
+ * user message + any attachments) and the preceding conversation history.
+ * @internal
+ */
+export interface ISplitChatRequest {
+    /** The current turn lowered to an {@link AiPrompt} (system + user + attachments). */
+    readonly prompt: AiPrompt;
+    /** Prior conversation history — every message before the current turn. */
+    readonly head: ReadonlyArray<IChatMessage>;
+}
+/**
+ * Splits a unified {@link AiAssist.IChatRequest} into `{ prompt, head }` for the
+ * per-provider builders. The **last** message is the current `user` turn; the
+ * preceding messages are history (`head`). This is the single linearization
+ * shared by every turn entry point, so the completion path and the client-tool
+ * turn path place history at the identical position relative to the current turn.
+ *
+ * Fails when `messages` is empty (no current turn) or when the last message is
+ * not a `user` turn — relabelling a trailing assistant message as the user turn
+ * would be a silent footgun, so it is rejected loudly instead.
+ *
+ * @internal
+ */
+export declare function splitChatRequest(system: string | undefined, messages: ReadonlyArray<IChatMessage>): Result<ISplitChatRequest>;
+/**
+ * Rebuilds the ordered messages for a proxy wire body so that only the current
+ * turn can carry attachments — history (non-current) messages are reduced to
+ * `{ role, content }`. The direct per-provider builders already drop attachments
+ * on history turns (only the current user turn's attachments are honored), so
+ * normalizing here keeps the proxy wire shape consistent with the direct paths
+ * and avoids transmitting attachment payloads the upstream provider would ignore.
+ *
+ * @internal
+ */
+export declare function normalizeOutboundMessages(split: ISplitChatRequest): IChatMessage[];
+/**
+ * Optional history (`head`) and raw continuation (`rawTail`) messages to weave
+ * around the prompt's current user message.
+ *
+ * @internal
+ */
+export interface IBuildMessagesOptions {
+    /**
+     * Prior conversation history inserted between the system prompt and the
+     * prompt's current user message (multi-turn chat / correction retries). The
+     * single ordered linearization is `[system, ...head, user, ...rawTail]`.
+     */
+    readonly head?: ReadonlyArray<IChatMessage>;
+    /**
+     * Raw JSON objects appended after the prompt's user message. Used to
+     * inject provider-specific continuation messages (e.g. Anthropic assistant
+     * turns with thinking blocks, OpenAI Responses `function_call` /
+     * `function_call_output` items, Gemini `functionCall` / `functionResponse`
+     * turns) that cannot be expressed as plain {@link IChatMessage} objects.
+     *
+     * Each builder applies its own provider-specific shape guard:
+     * - {@link buildAnthropicMessages} projects each entry to `{ role, content }`.
+     * - {@link buildMessages} (OpenAI / xAI Responses) preserves each item
+     *   verbatim (item fields differ per `type`), guarding only that it is a
+     *   JSON object.
+     * - {@link buildGeminiContents} projects each entry to `{ role, parts }`.
+     *
+     * Entries that fail their builder's shape check are silently skipped (the
+     * caller is responsible for supplying well-formed continuation messages).
+     * Appended after the current user message.
+     */
+    readonly rawTail?: ReadonlyArray<JsonObject>;
+}
+/**
+ * Builds the messages array from prompt + optional history (`head`) and raw
+ * continuation (`rawTail`) messages. The caller supplies the user content
+ * (string for text-only, parts array for vision prompts) since the parts shape
+ * differs by format.
+ *
+ * `rawTail` items (OpenAI / xAI Responses `function_call` /
+ * `function_call_output` continuation items) are appended verbatim after the
+ * user message — their fields differ per item `type`, so they are preserved
+ * rather than projected. The return type is `Array<Record<string, unknown>>`
+ * to accommodate both `{ role, content }` messages and these heterogeneous
+ * input items.
+ *
+ * @internal
+ */
+export declare function buildMessages(systemPrompt: string, userContent: string | unknown[], options?: IBuildMessagesOptions): Array<Record<string, unknown>>;
+/**
+ * Builds the user content for OpenAI Chat Completions when attachments are
+ * present. Returns a string when there are no attachments.
+ *
+ * @internal
+ */
+export declare function buildOpenAiChatUserContent(prompt: AiPrompt): string | unknown[];
+/**
+ * Builds the user content for OpenAI / xAI Responses API when attachments
+ * are present. Responses API uses `input_text` / `input_image` part types,
+ * distinct from Chat Completions' `text` / `image_url`.
+ *
+ * @internal
+ */
+export declare function buildOpenAiResponsesUserContent(prompt: AiPrompt): string | unknown[];
+/**
+ * Builds the user-message content for Anthropic when attachments are present.
+ *
+ * @internal
+ */
+export declare function buildAnthropicUserContent(prompt: AiPrompt): string | unknown[];
+/**
+ * Builds the Gemini `parts` array for the user turn, including any image
+ * attachments as `inlineData` parts.
+ *
+ * @internal
+ */
+export declare function buildGeminiUserParts(prompt: AiPrompt): Array<Record<string, unknown>>;
+/**
+ * Builds the Anthropic messages array, weaving any `head` history messages
+ * between implicit system + the prompt's user message and appending `rawTail`
+ * continuation messages after. System messages are filtered out (Anthropic uses
+ * a top-level system field).
+ *
+ * @internal
+ */
+export declare function buildAnthropicMessages(prompt: AiPrompt, options?: IBuildMessagesOptions): Array<{
+    role: string;
+    content: string | unknown[];
+}>;
+/**
+ * Builds the Gemini `contents` array, weaving any `head` history messages before
+ * the prompt's user parts and appending `rawTail` continuation messages after.
+ * System messages are filtered out (Gemini uses a top-level systemInstruction
+ * field) and assistant roles are mapped to Gemini's `model` role.
+ *
+ * @internal
+ */
+export declare function buildGeminiContents(prompt: AiPrompt, options?: IBuildMessagesOptions): Array<{
+    role: string;
+    parts: unknown[];
+}>;
+//# sourceMappingURL=chatRequestBuilders.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chatRequestBuilders.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/chatRequestBuilders.ts"],"names":[],"mappings":"AAoBA;;;;;;GAMG;AAEH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAoC,MAAM,EAAW,MAAM,eAAe,CAAC;AAElF,OAAO,EAAE,QAAQ,EAA2B,KAAK,YAAY,EAAa,MAAM,SAAS,CAAC;AAE1F;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,GACpC,MAAM,CAAC,iBAAiB,CAAC,CAW3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,EAAE,CAKlF;AAgED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAC5C;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE,EAC/B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAoBhC;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,EAAE,CAc/E;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,EAAE,CAYpF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,EAAE,CAe9E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAMrF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,QAAQ,EAChB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,CAAA;CAAE,CAAC,CAmBtD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,QAAQ,EAChB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC,CAwB3C"}

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

@@ -0,0 +1,293 @@
+"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.splitChatRequest = splitChatRequest;
+exports.normalizeOutboundMessages = normalizeOutboundMessages;
+exports.buildMessages = buildMessages;
+exports.buildOpenAiChatUserContent = buildOpenAiChatUserContent;
+exports.buildOpenAiResponsesUserContent = buildOpenAiResponsesUserContent;
+exports.buildAnthropicUserContent = buildAnthropicUserContent;
+exports.buildGeminiUserParts = buildGeminiUserParts;
+exports.buildAnthropicMessages = buildAnthropicMessages;
+exports.buildGeminiContents = buildGeminiContents;
+/**
+ * Per-format chat request shape builders. Shared between the synchronous
+ * (`apiClient.ts`) and streaming (`streamingClient.ts`) paths so the wire
+ * shapes stay consistent.
+ *
+ * @packageDocumentation
+ */
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const ts_utils_1 = require("@fgv/ts-utils");
+const model_1 = require("./model");
+/**
+ * Splits a unified {@link AiAssist.IChatRequest} into `{ prompt, head }` for the
+ * per-provider builders. The **last** message is the current `user` turn; the
+ * preceding messages are history (`head`). This is the single linearization
+ * shared by every turn entry point, so the completion path and the client-tool
+ * turn path place history at the identical position relative to the current turn.
+ *
+ * Fails when `messages` is empty (no current turn) or when the last message is
+ * not a `user` turn — relabelling a trailing assistant message as the user turn
+ * would be a silent footgun, so it is rejected loudly instead.
+ *
+ * @internal
+ */
+function splitChatRequest(system, messages) {
+    if (messages.length === 0) {
+        return (0, ts_utils_1.fail)('messages must contain at least one entry (the current user turn)');
+    }
+    const current = messages[messages.length - 1];
+    if (current.role !== 'user') {
+        return (0, ts_utils_1.fail)(`the last message must be the current user turn (role 'user'); got '${current.role}'`);
+    }
+    const head = messages.slice(0, messages.length - 1);
+    const prompt = new model_1.AiPrompt(current.content, system !== null && system !== void 0 ? system : '', current.attachments);
+    return (0, ts_utils_1.succeed)({ prompt, head });
+}
+/**
+ * Rebuilds the ordered messages for a proxy wire body so that only the current
+ * turn can carry attachments — history (non-current) messages are reduced to
+ * `{ role, content }`. The direct per-provider builders already drop attachments
+ * on history turns (only the current user turn's attachments are honored), so
+ * normalizing here keeps the proxy wire shape consistent with the direct paths
+ * and avoids transmitting attachment payloads the upstream provider would ignore.
+ *
+ * @internal
+ */
+function normalizeOutboundMessages(split) {
+    return [
+        ...split.head.map((m) => ({ role: m.role, content: m.content })),
+        ...split.prompt.toRequest().messages
+    ];
+}
+/**
+ * Converter for a rawTail message entry. Narrows a `JsonObject` to
+ * `{ role: string; content: string | unknown[] }` at runtime using the
+ * Converter pattern. Entries that fail validation are silently skipped — the
+ * surrounding function is infallible, and a malformed continuation message is
+ * better omitted than transmitted verbatim.
+ * @internal
+ */
+const rawTailMessageConverter = ts_utils_1.Converters.object({
+    role: ts_utils_1.Converters.enumeratedValue(['user', 'assistant']),
+    content: ts_utils_1.Converters.oneOf([
+        ts_utils_1.Converters.string,
+        ts_utils_1.Converters.isA('array', (v) => Array.isArray(v))
+    ])
+}, { strict: false });
+/**
+ * Converter for an OpenAI / xAI Responses API `rawTail` item. These are
+ * provider-native input items (`function_call`, `function_call_output`) whose
+ * fields differ per item type, so — unlike the Anthropic `{ role, content }`
+ * projection — the whole object is preserved verbatim.
+ *
+ * The static input is already typed `JsonObject`, so the `isJsonObject` guard
+ * is a runtime backstop, not a compile-time narrowing: continuation messages
+ * originate from a prior turn's `IAiClientToolContinuation.messages` and a
+ * consumer may persist and reload them through untyped JSON before passing them
+ * back. The guard preserves the same "a malformed continuation message is
+ * better omitted than transmitted verbatim" posture as the Anthropic path —
+ * non-object entries fail conversion and are skipped by the caller.
+ * @internal
+ */
+const openAiRawTailItemConverter = ts_utils_1.Converters.isA('JsonObject', (v) => (0, ts_json_base_1.isJsonObject)(v));
+/**
+ * Converter for a Gemini `rawTail` item. Gemini continuation messages are
+ * `{ role, parts }` turns (a model turn with `functionCall` parts followed by a
+ * user turn with `functionResponse` parts). Narrows a `JsonObject` to
+ * `{ role: 'user' | 'model'; parts: Array<Record<string, unknown>> }`; entries
+ * that fail validation are skipped by the caller.
+ * @internal
+ */
+const geminiRawTailMessageConverter = ts_utils_1.Converters.object({
+    role: ts_utils_1.Converters.enumeratedValue(['user', 'model']),
+    // `parts` is preserved verbatim and serialized into the request body, so the
+    // element shape is not narrowed here — `Array.isArray` soundly guarantees
+    // `unknown[]` (narrowing to `Record<string, unknown>[]` would be an unchecked cast).
+    parts: ts_utils_1.Converters.isA('array', (v) => Array.isArray(v))
+}, { strict: false });
+/**
+ * Builds the messages array from prompt + optional history (`head`) and raw
+ * continuation (`rawTail`) messages. The caller supplies the user content
+ * (string for text-only, parts array for vision prompts) since the parts shape
+ * differs by format.
+ *
+ * `rawTail` items (OpenAI / xAI Responses `function_call` /
+ * `function_call_output` continuation items) are appended verbatim after the
+ * user message — their fields differ per item `type`, so they are preserved
+ * rather than projected. The return type is `Array<Record<string, unknown>>`
+ * to accommodate both `{ role, content }` messages and these heterogeneous
+ * input items.
+ *
+ * @internal
+ */
+function buildMessages(systemPrompt, userContent, options) {
+    const messages = [{ role: 'system', content: systemPrompt }];
+    if (options === null || options === void 0 ? void 0 : options.head) {
+        for (const msg of options.head) {
+            messages.push({ role: msg.role, content: msg.content });
+        }
+    }
+    messages.push({ role: 'user', content: userContent });
+    // OpenAI / xAI Responses continuation items (function_call /
+    // function_call_output) are appended verbatim — their field set differs per
+    // item type, so the whole object is preserved rather than projected.
+    if (options === null || options === void 0 ? void 0 : options.rawTail) {
+        for (const item of options.rawTail) {
+            const converted = openAiRawTailItemConverter.convert(item);
+            if (converted.isSuccess()) {
+                messages.push(converted.value);
+            }
+        }
+    }
+    return messages;
+}
+/**
+ * Builds the user content for OpenAI Chat Completions when attachments are
+ * present. Returns a string when there are no attachments.
+ *
+ * @internal
+ */
+function buildOpenAiChatUserContent(prompt) {
+    if (prompt.attachments.length === 0) {
+        return prompt.user;
+    }
+    return [
+        { type: 'text', text: prompt.user },
+        ...prompt.attachments.map((att) => ({
+            type: 'image_url',
+            image_url: Object.assign({ url: (0, model_1.toDataUrl)(att) }, (att.detail !== undefined ? { detail: att.detail } : {}))
+        }))
+    ];
+}
+/**
+ * Builds the user content for OpenAI / xAI Responses API when attachments
+ * are present. Responses API uses `input_text` / `input_image` part types,
+ * distinct from Chat Completions' `text` / `image_url`.
+ *
+ * @internal
+ */
+function buildOpenAiResponsesUserContent(prompt) {
+    if (prompt.attachments.length === 0) {
+        return prompt.user;
+    }
+    return [
+        { type: 'input_text', text: prompt.user },
+        ...prompt.attachments.map((att) => (Object.assign({ type: 'input_image', image_url: (0, model_1.toDataUrl)(att) }, (att.detail !== undefined ? { detail: att.detail } : {}))))
+    ];
+}
+/**
+ * Builds the user-message content for Anthropic when attachments are present.
+ *
+ * @internal
+ */
+function buildAnthropicUserContent(prompt) {
+    if (prompt.attachments.length === 0) {
+        return prompt.user;
+    }
+    return [
+        { type: 'text', text: prompt.user },
+        ...prompt.attachments.map((att) => ({
+            type: 'image',
+            source: {
+                type: 'base64',
+                media_type: att.mimeType,
+                data: att.base64
+            }
+        }))
+    ];
+}
+/**
+ * Builds the Gemini `parts` array for the user turn, including any image
+ * attachments as `inlineData` parts.
+ *
+ * @internal
+ */
+function buildGeminiUserParts(prompt) {
+    const parts = [{ text: prompt.user }];
+    for (const att of prompt.attachments) {
+        parts.push({ inlineData: { mimeType: att.mimeType, data: att.base64 } });
+    }
+    return parts;
+}
+/**
+ * Builds the Anthropic messages array, weaving any `head` history messages
+ * between implicit system + the prompt's user message and appending `rawTail`
+ * continuation messages after. System messages are filtered out (Anthropic uses
+ * a top-level system field).
+ *
+ * @internal
+ */
+function buildAnthropicMessages(prompt, options) {
+    const messages = [];
+    if (options === null || options === void 0 ? void 0 : options.head) {
+        for (const msg of options.head) {
+            if (msg.role !== 'system') {
+                messages.push({ role: msg.role, content: msg.content });
+            }
+        }
+    }
+    messages.push({ role: 'user', content: buildAnthropicUserContent(prompt) });
+    if (options === null || options === void 0 ? void 0 : options.rawTail) {
+        for (const msg of options.rawTail) {
+            const converted = rawTailMessageConverter.convert(msg);
+            if (converted.isSuccess()) {
+                messages.push(converted.value);
+            }
+        }
+    }
+    return messages;
+}
+/**
+ * Builds the Gemini `contents` array, weaving any `head` history messages before
+ * the prompt's user parts and appending `rawTail` continuation messages after.
+ * System messages are filtered out (Gemini uses a top-level systemInstruction
+ * field) and assistant roles are mapped to Gemini's `model` role.
+ *
+ * @internal
+ */
+function buildGeminiContents(prompt, options) {
+    const contents = [];
+    if (options === null || options === void 0 ? void 0 : options.head) {
+        for (const msg of options.head) {
+            if (msg.role !== 'system') {
+                contents.push({
+                    role: msg.role === 'assistant' ? 'model' : msg.role,
+                    parts: [{ text: msg.content }]
+                });
+            }
+        }
+    }
+    contents.push({ role: 'user', parts: buildGeminiUserParts(prompt) });
+    // Gemini continuation turns (model `functionCall` parts + user
+    // `functionResponse` parts) are projected to `{ role, parts }`.
+    if (options === null || options === void 0 ? void 0 : options.rawTail) {
+        for (const item of options.rawTail) {
+            const converted = geminiRawTailMessageConverter.convert(item);
+            if (converted.isSuccess()) {
+                contents.push(converted.value);
+            }
+        }
+    }
+    return contents;
+}
+//# sourceMappingURL=chatRequestBuilders.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chatRequestBuilders.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/chatRequestBuilders.ts"],"names":[],"mappings":"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","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 * Per-format chat request shape builders. Shared between the synchronous\n * (`apiClient.ts`) and streaming (`streamingClient.ts`) paths so the wire\n * shapes stay consistent.\n *\n * @packageDocumentation\n */\n\nimport { isJsonObject, type JsonObject } from '@fgv/ts-json-base';\nimport { type Converter, Converters, fail, Result, succeed } from '@fgv/ts-utils';\n\nimport { AiPrompt, type IAiImageAttachment, type IChatMessage, toDataUrl } from './model';\n\n/**\n * The result of splitting an {@link AiAssist.IChatRequest} into the per-builder\n * inputs: the current turn (as an {@link AiPrompt}, carrying system + the final\n * user message + any attachments) and the preceding conversation history.\n * @internal\n */\nexport interface ISplitChatRequest {\n  /** The current turn lowered to an {@link AiPrompt} (system + user + attachments). */\n  readonly prompt: AiPrompt;\n  /** Prior conversation history — every message before the current turn. */\n  readonly head: ReadonlyArray<IChatMessage>;\n}\n\n/**\n * Splits a unified {@link AiAssist.IChatRequest} into `{ prompt, head }` for the\n * per-provider builders. The **last** message is the current `user` turn; the\n * preceding messages are history (`head`). This is the single linearization\n * shared by every turn entry point, so the completion path and the client-tool\n * turn path place history at the identical position relative to the current turn.\n *\n * Fails when `messages` is empty (no current turn) or when the last message is\n * not a `user` turn — relabelling a trailing assistant message as the user turn\n * would be a silent footgun, so it is rejected loudly instead.\n *\n * @internal\n */\nexport function splitChatRequest(\n  system: string | undefined,\n  messages: ReadonlyArray<IChatMessage>\n): Result<ISplitChatRequest> {\n  if (messages.length === 0) {\n    return fail('messages must contain at least one entry (the current user turn)');\n  }\n  const current = messages[messages.length - 1];\n  if (current.role !== 'user') {\n    return fail(`the last message must be the current user turn (role 'user'); got '${current.role}'`);\n  }\n  const head = messages.slice(0, messages.length - 1);\n  const prompt = new AiPrompt(current.content, system ?? '', current.attachments);\n  return succeed({ prompt, head });\n}\n\n/**\n * Rebuilds the ordered messages for a proxy wire body so that only the current\n * turn can carry attachments — history (non-current) messages are reduced to\n * `{ role, content }`. The direct per-provider builders already drop attachments\n * on history turns (only the current user turn's attachments are honored), so\n * normalizing here keeps the proxy wire shape consistent with the direct paths\n * and avoids transmitting attachment payloads the upstream provider would ignore.\n *\n * @internal\n */\nexport function normalizeOutboundMessages(split: ISplitChatRequest): IChatMessage[] {\n  return [\n    ...split.head.map((m) => ({ role: m.role, content: m.content })),\n    ...split.prompt.toRequest().messages\n  ];\n}\n\n/**\n * Converter for a rawTail message entry. Narrows a `JsonObject` to\n * `{ role: string; content: string | unknown[] }` at runtime using the\n * Converter pattern. Entries that fail validation are silently skipped — the\n * surrounding function is infallible, and a malformed continuation message is\n * better omitted than transmitted verbatim.\n * @internal\n */\nconst rawTailMessageConverter: Converter<{ role: 'user' | 'assistant'; content: string | unknown[] }> =\n  Converters.object<{ role: 'user' | 'assistant'; content: string | unknown[] }>(\n    {\n      role: Converters.enumeratedValue<'user' | 'assistant'>(['user', 'assistant']),\n      content: Converters.oneOf<string | unknown[]>([\n        Converters.string,\n        Converters.isA('array', (v): v is unknown[] => Array.isArray(v))\n      ])\n    },\n    { strict: false }\n  );\n\n/**\n * Converter for an OpenAI / xAI Responses API `rawTail` item. These are\n * provider-native input items (`function_call`, `function_call_output`) whose\n * fields differ per item type, so — unlike the Anthropic `{ role, content }`\n * projection — the whole object is preserved verbatim.\n *\n * The static input is already typed `JsonObject`, so the `isJsonObject` guard\n * is a runtime backstop, not a compile-time narrowing: continuation messages\n * originate from a prior turn's `IAiClientToolContinuation.messages` and a\n * consumer may persist and reload them through untyped JSON before passing them\n * back. The guard preserves the same \"a malformed continuation message is\n * better omitted than transmitted verbatim\" posture as the Anthropic path —\n * non-object entries fail conversion and are skipped by the caller.\n * @internal\n */\nconst openAiRawTailItemConverter: Converter<JsonObject> = Converters.isA<JsonObject>(\n  'JsonObject',\n  (v): v is JsonObject => isJsonObject(v)\n);\n\n/**\n * Converter for a Gemini `rawTail` item. Gemini continuation messages are\n * `{ role, parts }` turns (a model turn with `functionCall` parts followed by a\n * user turn with `functionResponse` parts). Narrows a `JsonObject` to\n * `{ role: 'user' | 'model'; parts: Array<Record<string, unknown>> }`; entries\n * that fail validation are skipped by the caller.\n * @internal\n */\nconst geminiRawTailMessageConverter: Converter<{\n  role: 'user' | 'model';\n  parts: unknown[];\n}> = Converters.object<{ role: 'user' | 'model'; parts: unknown[] }>(\n  {\n    role: Converters.enumeratedValue<'user' | 'model'>(['user', 'model']),\n    // `parts` is preserved verbatim and serialized into the request body, so the\n    // element shape is not narrowed here — `Array.isArray` soundly guarantees\n    // `unknown[]` (narrowing to `Record<string, unknown>[]` would be an unchecked cast).\n    parts: Converters.isA('array', (v): v is unknown[] => Array.isArray(v))\n  },\n  { strict: false }\n);\n\n/**\n * Optional history (`head`) and raw continuation (`rawTail`) messages to weave\n * around the prompt's current user message.\n *\n * @internal\n */\nexport interface IBuildMessagesOptions {\n  /**\n   * Prior conversation history inserted between the system prompt and the\n   * prompt's current user message (multi-turn chat / correction retries). The\n   * single ordered linearization is `[system, ...head, user, ...rawTail]`.\n   */\n  readonly head?: ReadonlyArray<IChatMessage>;\n  /**\n   * Raw JSON objects appended after the prompt's user message. Used to\n   * inject provider-specific continuation messages (e.g. Anthropic assistant\n   * turns with thinking blocks, OpenAI Responses `function_call` /\n   * `function_call_output` items, Gemini `functionCall` / `functionResponse`\n   * turns) that cannot be expressed as plain {@link IChatMessage} objects.\n   *\n   * Each builder applies its own provider-specific shape guard:\n   * - {@link buildAnthropicMessages} projects each entry to `{ role, content }`.\n   * - {@link buildMessages} (OpenAI / xAI Responses) preserves each item\n   *   verbatim (item fields differ per `type`), guarding only that it is a\n   *   JSON object.\n   * - {@link buildGeminiContents} projects each entry to `{ role, parts }`.\n   *\n   * Entries that fail their builder's shape check are silently skipped (the\n   * caller is responsible for supplying well-formed continuation messages).\n   * Appended after the current user message.\n   */\n  readonly rawTail?: ReadonlyArray<JsonObject>;\n}\n\n/**\n * Builds the messages array from prompt + optional history (`head`) and raw\n * continuation (`rawTail`) messages. The caller supplies the user content\n * (string for text-only, parts array for vision prompts) since the parts shape\n * differs by format.\n *\n * `rawTail` items (OpenAI / xAI Responses `function_call` /\n * `function_call_output` continuation items) are appended verbatim after the\n * user message — their fields differ per item `type`, so they are preserved\n * rather than projected. The return type is `Array<Record<string, unknown>>`\n * to accommodate both `{ role, content }` messages and these heterogeneous\n * input items.\n *\n * @internal\n */\nexport function buildMessages(\n  systemPrompt: string,\n  userContent: string | unknown[],\n  options?: IBuildMessagesOptions\n): Array<Record<string, unknown>> {\n  const messages: Array<Record<string, unknown>> = [{ role: 'system', content: systemPrompt }];\n  if (options?.head) {\n    for (const msg of options.head) {\n      messages.push({ role: msg.role, content: msg.content });\n    }\n  }\n  messages.push({ role: 'user', content: userContent });\n  // OpenAI / xAI Responses continuation items (function_call /\n  // function_call_output) are appended verbatim — their field set differs per\n  // item type, so the whole object is preserved rather than projected.\n  if (options?.rawTail) {\n    for (const item of options.rawTail) {\n      const converted = openAiRawTailItemConverter.convert(item);\n      if (converted.isSuccess()) {\n        messages.push(converted.value);\n      }\n    }\n  }\n  return messages;\n}\n\n/**\n * Builds the user content for OpenAI Chat Completions when attachments are\n * present. Returns a string when there are no attachments.\n *\n * @internal\n */\nexport function buildOpenAiChatUserContent(prompt: AiPrompt): string | unknown[] {\n  if (prompt.attachments.length === 0) {\n    return prompt.user;\n  }\n  return [\n    { type: 'text', text: prompt.user },\n    ...prompt.attachments.map((att: IAiImageAttachment) => ({\n      type: 'image_url',\n      image_url: {\n        url: toDataUrl(att),\n        ...(att.detail !== undefined ? { detail: att.detail } : {})\n      }\n    }))\n  ];\n}\n\n/**\n * Builds the user content for OpenAI / xAI Responses API when attachments\n * are present. Responses API uses `input_text` / `input_image` part types,\n * distinct from Chat Completions' `text` / `image_url`.\n *\n * @internal\n */\nexport function buildOpenAiResponsesUserContent(prompt: AiPrompt): string | unknown[] {\n  if (prompt.attachments.length === 0) {\n    return prompt.user;\n  }\n  return [\n    { type: 'input_text', text: prompt.user },\n    ...prompt.attachments.map((att: IAiImageAttachment) => ({\n      type: 'input_image',\n      image_url: toDataUrl(att),\n      ...(att.detail !== undefined ? { detail: att.detail } : {})\n    }))\n  ];\n}\n\n/**\n * Builds the user-message content for Anthropic when attachments are present.\n *\n * @internal\n */\nexport function buildAnthropicUserContent(prompt: AiPrompt): string | unknown[] {\n  if (prompt.attachments.length === 0) {\n    return prompt.user;\n  }\n  return [\n    { type: 'text', text: prompt.user },\n    ...prompt.attachments.map((att: IAiImageAttachment) => ({\n      type: 'image',\n      source: {\n        type: 'base64',\n        media_type: att.mimeType,\n        data: att.base64\n      }\n    }))\n  ];\n}\n\n/**\n * Builds the Gemini `parts` array for the user turn, including any image\n * attachments as `inlineData` parts.\n *\n * @internal\n */\nexport function buildGeminiUserParts(prompt: AiPrompt): Array<Record<string, unknown>> {\n  const parts: Array<Record<string, unknown>> = [{ text: prompt.user }];\n  for (const att of prompt.attachments) {\n    parts.push({ inlineData: { mimeType: att.mimeType, data: att.base64 } });\n  }\n  return parts;\n}\n\n/**\n * Builds the Anthropic messages array, weaving any `head` history messages\n * between implicit system + the prompt's user message and appending `rawTail`\n * continuation messages after. System messages are filtered out (Anthropic uses\n * a top-level system field).\n *\n * @internal\n */\nexport function buildAnthropicMessages(\n  prompt: AiPrompt,\n  options?: IBuildMessagesOptions\n): Array<{ role: string; content: string | unknown[] }> {\n  const messages: Array<{ role: string; content: string | unknown[] }> = [];\n  if (options?.head) {\n    for (const msg of options.head) {\n      if (msg.role !== 'system') {\n        messages.push({ role: msg.role, content: msg.content });\n      }\n    }\n  }\n  messages.push({ role: 'user', content: buildAnthropicUserContent(prompt) });\n  if (options?.rawTail) {\n    for (const msg of options.rawTail) {\n      const converted = rawTailMessageConverter.convert(msg);\n      if (converted.isSuccess()) {\n        messages.push(converted.value);\n      }\n    }\n  }\n  return messages;\n}\n\n/**\n * Builds the Gemini `contents` array, weaving any `head` history messages before\n * the prompt's user parts and appending `rawTail` continuation messages after.\n * System messages are filtered out (Gemini uses a top-level systemInstruction\n * field) and assistant roles are mapped to Gemini's `model` role.\n *\n * @internal\n */\nexport function buildGeminiContents(\n  prompt: AiPrompt,\n  options?: IBuildMessagesOptions\n): Array<{ role: string; parts: unknown[] }> {\n  const contents: Array<{ role: string; parts: unknown[] }> = [];\n  if (options?.head) {\n    for (const msg of options.head) {\n      if (msg.role !== 'system') {\n        contents.push({\n          role: msg.role === 'assistant' ? 'model' : msg.role,\n          parts: [{ text: msg.content }]\n        });\n      }\n    }\n  }\n  contents.push({ role: 'user', parts: buildGeminiUserParts(prompt) });\n  // Gemini continuation turns (model `functionCall` parts + user\n  // `functionResponse` parts) are projected to `{ role, parts }`.\n  if (options?.rawTail) {\n    for (const item of options.rawTail) {\n      const converted = geminiRawTailMessageConverter.convert(item);\n      if (converted.isSuccess()) {\n        contents.push(converted.value);\n      }\n    }\n  }\n  return contents;\n}\n"]}