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

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

@@ -25,8 +25,49 @@
  * @packageDocumentation
  */
 import { isJsonObject } from '@fgv/ts-json-base';
-import { Converters } from '@fgv/ts-utils';
-import { toDataUrl } from './model';
+import { Converters, fail, succeed } from '@fgv/ts-utils';
+import { AiPrompt, toDataUrl } from './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
+ */
+export function splitChatRequest(system, messages) {
+    if (messages.length === 0) {
+        return fail('messages must contain at least one entry (the current user turn)');
+    }
+    const current = messages[messages.length - 1];
+    if (current.role !== 'user') {
+        return 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 AiPrompt(current.content, system !== null && system !== void 0 ? system : '', current.attachments);
+    return 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
+ */
+export 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
@@ -74,9 +115,10 @@ const geminiRawTailMessageConverter = Converters.object({
     parts: Converters.isA('array', (v) => Array.isArray(v))
 }, { strict: false });
 /**
- * Builds the messages array from prompt + optional head/tail messages.
- * The caller supplies the user content (string for text-only, parts array
- * for vision prompts) since the parts shape differs by format.
+ * 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
@@ -89,19 +131,12 @@ const geminiRawTailMessageConverter = Converters.object({
  */
 export function buildMessages(systemPrompt, userContent, options) {
     const messages = [{ role: 'system', content: systemPrompt }];
-    /* c8 ignore next 4 - head branch: options?.head short-circuit not reached from current call sites */
     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 });
-    /* c8 ignore next 4 - tail branch: options?.tail short-circuit not reached from current call sites */
-    if (options === null || options === void 0 ? void 0 : options.tail) {
-        for (const msg of options.tail) {
-            messages.push({ role: msg.role, content: msg.content });
-        }
-    }
     // 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.
@@ -184,16 +219,15 @@ export function buildGeminiUserParts(prompt) {
     return parts;
 }
 /**
- * Builds the Anthropic messages array, weaving any `head` messages between
- * implicit system + the prompt's user message and appending `tail` messages
- * after. System messages are filtered out (Anthropic uses a top-level system
- * field).
+ * 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 function buildAnthropicMessages(prompt, options) {
     const messages = [];
-    /* c8 ignore next 5 - head branch: options?.head short-circuit not reached from current call sites */
     if (options === null || options === void 0 ? void 0 : options.head) {
         for (const msg of options.head) {
             if (msg.role !== 'system') {
@@ -202,15 +236,6 @@ export function buildAnthropicMessages(prompt, options) {
         }
     }
     messages.push({ role: 'user', content: buildAnthropicUserContent(prompt) });
-    /* c8 ignore next 5 - tail branch: options?.tail short-circuit not reached from current call sites */
-    if (options === null || options === void 0 ? void 0 : options.tail) {
-        for (const msg of options.tail) {
-            if (msg.role !== 'system') {
-                messages.push({ role: msg.role, content: msg.content });
-            }
-        }
-    }
-    /* c8 ignore next 7 - options?.rawTail optional-chain short-circuit (options=undefined) not reached in unit tests */
     if (options === null || options === void 0 ? void 0 : options.rawTail) {
         for (const msg of options.rawTail) {
             const converted = rawTailMessageConverter.convert(msg);
@@ -222,16 +247,15 @@ export function buildAnthropicMessages(prompt, options) {
     return messages;
 }
 /**
- * Builds the Gemini `contents` array, weaving any `head` messages before the
- * prompt's user parts and appending `tail` messages after. System messages
- * are filtered out (Gemini uses a top-level systemInstruction field) and
- * assistant roles are mapped to Gemini's `model` role.
+ * 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 function buildGeminiContents(prompt, options) {
     const contents = [];
-    /* c8 ignore next 7 - head branch: options?.head short-circuit not reached from current call sites */
     if (options === null || options === void 0 ? void 0 : options.head) {
         for (const msg of options.head) {
             if (msg.role !== 'system') {
@@ -243,17 +267,6 @@ export function buildGeminiContents(prompt, options) {
         }
     }
     contents.push({ role: 'user', parts: buildGeminiUserParts(prompt) });
-    /* c8 ignore next 7 - tail branch: options?.tail short-circuit not reached from current call sites */
-    if (options === null || options === void 0 ? void 0 : options.tail) {
-        for (const msg of options.tail) {
-            if (msg.role !== 'system') {
-                contents.push({
-                    role: msg.role === 'assistant' ? 'model' : msg.role,
-                    parts: [{ text: msg.content }]
-                });
-            }
-        }
-    }
     // Gemini continuation turns (model `functionCall` parts + user
     // `functionResponse` parts) are projected to `{ role, parts }`.
     if (options === null || options === void 0 ? void 0 : options.rawTail) {

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

@@ -1 +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 } from '@fgv/ts-utils';\n\nimport { AiPrompt, type IAiImageAttachment, type IChatMessage, toDataUrl } from './model';\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 head/tail messages to weave around the prompt's user message.\n *\n * @internal\n */\nexport interface IBuildMessagesOptions {\n  /**\n   * Messages inserted between the system prompt and the prompt's user\n   * message (e.g. prior conversation history for multi-turn chat).\n   */\n  readonly head?: ReadonlyArray<IChatMessage>;\n  /**\n   * Messages appended after the prompt's user message (e.g. assistant\n   * + correction turns for the JSON-validation retry loop).\n   */\n  readonly tail?: 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   * Takes precedence over (and is appended after) `tail`.\n   */\n  readonly rawTail?: ReadonlyArray<JsonObject>;\n}\n\n/**\n * Builds the messages array from prompt + optional head/tail messages.\n * The caller supplies the user content (string for text-only, parts array\n * for vision prompts) since the parts shape 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  /* c8 ignore next 4 - head branch: options?.head short-circuit not reached from current call sites */\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  /* c8 ignore next 4 - tail branch: options?.tail short-circuit not reached from current call sites */\n  if (options?.tail) {\n    for (const msg of options.tail) {\n      messages.push({ role: msg.role, content: msg.content });\n    }\n  }\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` messages between\n * implicit system + the prompt's user message and appending `tail` messages\n * after. System messages are filtered out (Anthropic uses a top-level system\n * 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  /* c8 ignore next 5 - head branch: options?.head short-circuit not reached from current call sites */\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  /* c8 ignore next 5 - tail branch: options?.tail short-circuit not reached from current call sites */\n  if (options?.tail) {\n    for (const msg of options.tail) {\n      if (msg.role !== 'system') {\n        messages.push({ role: msg.role, content: msg.content });\n      }\n    }\n  }\n  /* c8 ignore next 7 - options?.rawTail optional-chain short-circuit (options=undefined) not reached in unit tests */\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` messages before the\n * prompt's user parts and appending `tail` messages after. System messages\n * are filtered out (Gemini uses a top-level systemInstruction field) and\n * 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  /* c8 ignore next 7 - head branch: options?.head short-circuit not reached from current call sites */\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  /* c8 ignore next 7 - tail branch: options?.tail short-circuit not reached from current call sites */\n  if (options?.tail) {\n    for (const msg of options.tail) {\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  // 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"]}
+{"version":3,"file":"chatRequestBuilders.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/chatRequestBuilders.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;AAEZ;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAkB,UAAU,EAAE,IAAI,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAElF,OAAO,EAAE,QAAQ,EAA8C,SAAS,EAAE,MAAM,SAAS,CAAC;AAe1F;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA0B,EAC1B,QAAqC;IAErC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,kEAAkE,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9C,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,sEAAsE,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;IACrG,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,EAAE,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAChF,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAwB;IAChE,OAAO;QACL,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAChE,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,QAAQ;KACrC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,uBAAuB,GAC3B,UAAU,CAAC,MAAM,CACf;IACE,IAAI,EAAE,UAAU,CAAC,eAAe,CAAuB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7E,OAAO,EAAE,UAAU,CAAC,KAAK,CAAqB;QAC5C,UAAU,CAAC,MAAM;QACjB,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,EAAkB,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;KACjE,CAAC;CACH,EACD,EAAE,MAAM,EAAE,KAAK,EAAE,CAClB,CAAC;AAEJ;;;;;;;;;;;;;;GAcG;AACH,MAAM,0BAA0B,GAA0B,UAAU,CAAC,GAAG,CACtE,YAAY,EACZ,CAAC,CAAC,EAAmB,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,6BAA6B,GAG9B,UAAU,CAAC,MAAM,CACpB;IACE,IAAI,EAAE,UAAU,CAAC,eAAe,CAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrE,6EAA6E;IAC7E,0EAA0E;IAC1E,qFAAqF;IACrF,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,EAAkB,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,EACD,EAAE,MAAM,EAAE,KAAK,EAAE,CAClB,CAAC;AAoCF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,YAAoB,EACpB,WAA+B,EAC/B,OAA+B;IAE/B,MAAM,QAAQ,GAAmC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;IAC7F,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,IAAI,EAAE,CAAC;QAClB,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;IACtD,6DAA6D;IAC7D,4EAA4E;IAC5E,qEAAqE;IACrE,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,EAAE,CAAC;QACrB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACnC,MAAM,SAAS,GAAG,0BAA0B,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC3D,IAAI,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC;gBAC1B,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAgB;IACzD,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IACD,OAAO;QACL,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE;QACnC,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAuB,EAAE,EAAE,CAAC,CAAC;YACtD,IAAI,EAAE,WAAW;YACjB,SAAS,kBACP,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,IAChB,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC5D;SACF,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAAC,MAAgB;IAC9D,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IACD,OAAO;QACL,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE;QACzC,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAuB,EAAE,EAAE,CAAC,iBACrD,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,IACtB,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAC3D,CAAC;KACJ,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAgB;IACxD,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IACD,OAAO;QACL,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE;QACnC,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAuB,EAAE,EAAE,CAAC,CAAC;YACtD,IAAI,EAAE,OAAO;YACb,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,GAAG,CAAC,QAAQ;gBACxB,IAAI,EAAE,GAAG,CAAC,MAAM;aACjB;SACF,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAgB;IACnD,MAAM,KAAK,GAAmC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAgB,EAChB,OAA+B;IAE/B,MAAM,QAAQ,GAAyD,EAAE,CAAC;IAC1E,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,IAAI,EAAE,CAAC;QAClB,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5E,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,EAAE,CAAC;QACrB,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YAClC,MAAM,SAAS,GAAG,uBAAuB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACvD,IAAI,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC;gBAC1B,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAgB,EAChB,OAA+B;IAE/B,MAAM,QAAQ,GAA8C,EAAE,CAAC;IAC/D,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,IAAI,EAAE,CAAC;QAClB,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC1B,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI;oBACnD,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;iBAC/B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACrE,+DAA+D;IAC/D,gEAAgE;IAChE,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,EAAE,CAAC;QACrB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACnC,MAAM,SAAS,GAAG,6BAA6B,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC9D,IAAI,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC;gBAC1B,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","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"]}

package/dist/packlets/ai-assist/embeddingClient.js

@@ -0,0 +1,346 @@
+// 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.
+/**
+ * Cross-provider embedding client for AI assist. Mirrors the completion and
+ * image-generation primitives in `apiClient.ts`: a single dispatcher
+ * ({@link AiAssist.callProviderEmbedding}) resolves the provider descriptor's
+ * embedding capability and routes to the per-format adapter. `text -> vector`,
+ * batch in, `number[][]` out.
+ *
+ * @packageDocumentation
+ */
+import { fail, succeed, Validators } from '@fgv/ts-utils';
+import { resolveModel } from './model';
+import { bearerAuthHeader, resolveEffectiveBaseUrl } from './endpoint';
+import { resolveEmbeddingCapability, supportsEmbedding } from './registry';
+import { fetchJson } from './http';
+const openAiEmbeddingItem = Validators.object({
+    index: Validators.number,
+    embedding: Validators.arrayOf(Validators.number)
+});
+const openAiEmbeddingUsage = Validators.object({
+    prompt_tokens: Validators.number.optional(),
+    total_tokens: Validators.number.optional()
+});
+const openAiEmbeddingResponse = Validators.object({
+    data: Validators.arrayOf(openAiEmbeddingItem).withConstraint((arr) => arr.length > 0),
+    model: Validators.string.optional(),
+    usage: openAiEmbeddingUsage.optional()
+});
+// ============================================================================
+// Shared helpers
+// ============================================================================
+/**
+ * Normalizes the `input` field (string | string[]) into a concrete string array.
+ * @internal
+ */
+function toInputArray(input) {
+    return typeof input === 'string' ? [input] : input;
+}
+/**
+ * Builds an {@link IAiEmbeddingUsage} from OpenAI-format usage, or `undefined`
+ * when no token counts are reported.
+ * @internal
+ */
+function toEmbeddingUsage(usage) {
+    if (usage === undefined || (usage.prompt_tokens === undefined && usage.total_tokens === undefined)) {
+        return undefined;
+    }
+    return Object.assign(Object.assign({}, (usage.prompt_tokens !== undefined ? { promptTokens: usage.prompt_tokens } : {})), (usage.total_tokens !== undefined ? { totalTokens: usage.total_tokens } : {}));
+}
+// ============================================================================
+// OpenAI-format adapter
+// ============================================================================
+/**
+ * Calls the OpenAI `/v1/embeddings` endpoint. Serves OpenAI, Ollama (via `/v1`),
+ * openai-compat self-hosted servers, and Mistral. Sends `dimensions` only when
+ * the capability declares `supportsDimensions`; always requests
+ * `encoding_format: 'float'`.
+ *
+ * @remarks
+ * `encoding_format: 'float'` is a known assumption (design §14 #5): a strict
+ * openai-compat server could in principle reject the field, but mainstream
+ * servers accept it and it keeps us off the base64 decode path. Low risk.
+ *
+ * @internal
+ */
+async function callOpenAiEmbeddings(config, inputs, request, capability, logger, signal) {
+    const body = {
+        model: config.model,
+        input: inputs,
+        encoding_format: 'float'
+    };
+    if (capability.supportsDimensions && request.dimensions !== undefined) {
+        body.dimensions = request.dimensions;
+    }
+    const headers = bearerAuthHeader(config.apiKey);
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI embedding: format=openai-embeddings, model=${config.model}, inputs=${inputs.length}`);
+    const jsonResult = await fetchJson(`${config.baseUrl}/embeddings`, headers, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return openAiEmbeddingResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `OpenAI embeddings API response: ${msg}`)
+        .onSuccess((response) => {
+        var _a;
+        // The spec allows `data` in any order; align to request order by `index`.
+        const ordered = [...response.data].sort((a, b) => a.index - b.index);
+        // Validate the response is well-formed against the request before trusting
+        // the alignment: a compat server could return an incomplete batch, gapped
+        // or duplicate indices, or ragged dimensions — all of which would silently
+        // yield misaligned/partial vectors. (inputs is non-empty here; the
+        // empty-input case short-circuits before the wire call.)
+        if (ordered.length !== inputs.length) {
+            return fail(`OpenAI embeddings API response: expected ${inputs.length} embedding(s), got ${ordered.length}`);
+        }
+        // After sorting, a perfect 0..n-1 sequence has item.index === position at
+        // every slot. Any gap OR duplicate shifts a later element off its position
+        // (the second copy of value k, or the element after a missing k, lands at
+        // position > its index), so this single walk catches both.
+        const misindexed = ordered.findIndex((item, i) => item.index !== i);
+        if (misindexed !== -1) {
+            return fail(`OpenAI embeddings API response: malformed embedding indices ` +
+                `(expected 0..${inputs.length - 1}; gap or duplicate at position ${misindexed})`);
+        }
+        const vectors = ordered.map((item) => item.embedding);
+        const dimensions = vectors[0].length;
+        const ragged = vectors.findIndex((v) => v.length !== dimensions);
+        if (ragged !== -1) {
+            return fail(`OpenAI embeddings API response: inconsistent vector dimensionality ` +
+                `(vector ${ragged} has length ${vectors[ragged].length}, expected ${dimensions})`);
+        }
+        const usage = toEmbeddingUsage(response.usage);
+        return succeed(Object.assign({ vectors, model: (_a = response.model) !== null && _a !== void 0 ? _a : config.model, dimensions }, (usage !== undefined ? { usage } : {})));
+    });
+}
+const geminiEmbedding = Validators.object({
+    values: Validators.arrayOf(Validators.number)
+});
+const geminiEmbeddingResponse = Validators.object({
+    embeddings: Validators.arrayOf(geminiEmbedding).withConstraint((arr) => arr.length > 0)
+});
+/**
+ * Maps a cross-provider {@link AiAssist.AiEmbeddingTaskType} (kebab-case) to the
+ * Gemini wire form (`SCREAMING_SNAKE_CASE`), e.g. `'retrieval-document'` becomes
+ * `'RETRIEVAL_DOCUMENT'`.
+ * @internal
+ */
+function toGeminiTaskType(taskType) {
+    return taskType.replace(/-/g, '_').toUpperCase();
+}
+/**
+ * Strips a leading `models/` from a model id so the URL path and the per-request
+ * `model` field can each apply the prefix exactly once.
+ * @internal
+ */
+function bareGeminiModel(model) {
+    return model.startsWith('models/') ? model.slice('models/'.length) : model;
+}
+/**
+ * Calls the Google Gemini `:batchEmbedContents` endpoint. Always uses the batch
+ * route (a single input is a one-element batch). Sends `taskType` /
+ * `outputDimensionality` only when the capability declares support. Gemini does
+ * not report token usage for embeddings, so `usage` is omitted.
+ * @internal
+ */
+async function callGeminiEmbeddings(config, inputs, request, capability, logger, signal) {
+    const bare = bareGeminiModel(config.model);
+    const qualified = `models/${bare}`;
+    // `request.taskType` is the open `AiEmbeddingTaskType` union (includes `string & {}`),
+    // which `!== undefined` cannot narrow to `string`; resolve it cast-free here.
+    const taskType = capability.supportsTaskType && request.taskType !== undefined
+        ? toGeminiTaskType(request.taskType)
+        : undefined;
+    const sendDimensions = capability.supportsDimensions && request.dimensions !== undefined;
+    const requests = inputs.map((text) => (Object.assign(Object.assign({ model: qualified, content: { parts: [{ text }] } }, (taskType !== undefined ? { taskType } : {})), (sendDimensions ? { outputDimensionality: request.dimensions } : {}))));
+    const body = { requests };
+    const headers = { 'x-goog-api-key': config.apiKey };
+    const url = `${config.baseUrl}/models/${bare}:batchEmbedContents`;
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI embedding: format=gemini-embeddings, model=${bare}, inputs=${inputs.length}`);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return geminiEmbeddingResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Gemini embeddings API response: ${msg}`)
+        .onSuccess((response) => {
+        // Gemini returns embeddings aligned to request order (no index field), so
+        // there is no per-item index to re-sort or gap-check (unlike the OpenAI
+        // path). Validate the response is well-formed against the request before
+        // trusting the positional alignment: a truncated batch or ragged
+        // dimensions would silently yield misaligned/partial vectors. (inputs is
+        // non-empty here; the empty-input case short-circuits before the wire call.)
+        const vectors = response.embeddings.map((e) => e.values);
+        if (vectors.length !== inputs.length) {
+            return fail(`Gemini embeddings API response: expected ${inputs.length} embedding(s), got ${vectors.length}`);
+        }
+        const dimensions = vectors[0].length;
+        const ragged = vectors.findIndex((v) => v.length !== dimensions);
+        if (ragged !== -1) {
+            return fail(`Gemini embeddings API response: inconsistent vector dimensionality ` +
+                `(vector ${ragged} has length ${vectors[ragged].length}, expected ${dimensions})`);
+        }
+        const result = { vectors, model: bare, dimensions };
+        return succeed(result);
+    });
+}
+// ============================================================================
+// Dispatcher
+// ============================================================================
+/**
+ * Notes any caller-supplied embedding knobs that the resolved capability does
+ * not honor. Per design §7 these are a no-op (logged, never a failure) so a
+ * cross-provider call site can pass `taskType`/`dimensions` once and have them
+ * apply only where supported.
+ * @internal
+ */
+function noteUnsupportedKnobs(model, request, capability, logger) {
+    if (logger === undefined) {
+        return;
+    }
+    if (request.taskType !== undefined && !capability.supportsTaskType) {
+        logger.info(`AI embedding: model "${model}" ignores taskType (not supported); proceeding without it`);
+    }
+    if (request.dimensions !== undefined && !capability.supportsDimensions) {
+        logger.info(`AI embedding: model "${model}" ignores dimensions (not supported); proceeding without it`);
+    }
+}
+/**
+ * Calls the appropriate embedding API for a given provider. Routes by the
+ * `format` of the resolved {@link AiAssist.IAiEmbeddingModelCapability}:
+ * `'openai-embeddings'` or `'gemini-embeddings'`.
+ *
+ * @remarks
+ * - Rejects up front when the provider declares no embedding capability, when no
+ *   embedding model resolves, or when the batch exceeds the capability's
+ *   `maxBatchSize` (no auto-chunking).
+ * - An empty `input` array short-circuits to an empty result with no wire call
+ *   (most providers HTTP-400 on empty input).
+ * - Caller-supplied `dimensions`/`taskType` that the model doesn't support are a
+ *   no-op (logged), not a failure (design §7).
+ *
+ * @param params - Request parameters including descriptor, API key, and input.
+ * @returns The embedding vectors aligned to input order, or a failure.
+ * @public
+ */
+export async function callProviderEmbedding(params) {
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal, endpoint } = params;
+    if (!supportsEmbedding(descriptor)) {
+        return fail(`provider "${descriptor.id}" does not support embeddings`);
+    }
+    const model = resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, 'embedding');
+    if (model.length === 0) {
+        return fail(`provider "${descriptor.id}": no embedding model resolved; ` +
+            `pass modelOverride or set descriptor.defaultModel ` +
+            `(a plain string, or an object with an "embedding" entry)`);
+    }
+    const capability = resolveEmbeddingCapability(descriptor, model);
+    if (capability === undefined) {
+        return fail(`provider "${descriptor.id}" does not support embeddings for model "${model}"`);
+    }
+    const inputs = toInputArray(request.input);
+    if (inputs.length === 0) {
+        // Short-circuit: empty batch never hits the wire (design §14 #2).
+        return succeed({ vectors: [], model, dimensions: 0 });
+    }
+    if (capability.maxBatchSize !== undefined && inputs.length > capability.maxBatchSize) {
+        return fail(`provider "${descriptor.id}": embedding batch of ${inputs.length} exceeds ` +
+            `model "${model}" maximum of ${capability.maxBatchSize}`);
+    }
+    const baseUrlResult = resolveEffectiveBaseUrl(descriptor, endpoint);
+    if (baseUrlResult.isFailure()) {
+        return fail(baseUrlResult.message);
+    }
+    noteUnsupportedKnobs(model, request, capability, logger);
+    const config = { baseUrl: baseUrlResult.value, apiKey, model };
+    return dispatchEmbedding(capability.format, config, inputs, request, capability, logger, signal);
+}
+/**
+ * Routes a resolved embedding request to the per-format adapter.
+ * @internal
+ */
+function dispatchEmbedding(format, config, inputs, request, capability, logger, signal) {
+    switch (format) {
+        case 'openai-embeddings':
+            return callOpenAiEmbeddings(config, inputs, request, capability, logger, signal);
+        case 'gemini-embeddings':
+            return callGeminiEmbeddings(config, inputs, request, capability, logger, signal);
+        /* c8 ignore next 4 - defensive: exhaustive switch guaranteed by TypeScript */
+        default: {
+            const _exhaustive = format;
+            return Promise.resolve(fail(`unsupported embedding API format: ${String(_exhaustive)}`));
+        }
+    }
+}
+// ============================================================================
+// Proxied embedding
+// ============================================================================
+const proxiedEmbeddingUsage = Validators.object({
+    promptTokens: Validators.number.optional(),
+    totalTokens: Validators.number.optional()
+});
+const proxiedEmbeddingResponse = Validators.object({
+    vectors: Validators.arrayOf(Validators.arrayOf(Validators.number)),
+    model: Validators.string,
+    dimensions: Validators.number,
+    usage: proxiedEmbeddingUsage.optional()
+});
+/**
+ * Calls the embedding endpoint on a proxy server instead of calling the provider
+ * API directly from the browser. Endpoint: `POST ${proxyUrl}/api/ai/embedding`.
+ * Request body: `{ providerId, apiKey, params, modelOverride? }`. The proxy
+ * handles descriptor lookup, model/capability resolution, and provider dispatch.
+ * Error body `{ error: string }` is surfaced as `proxy: ${error}`.
+ *
+ * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`).
+ * @param params - Same parameters as {@link AiAssist.callProviderEmbedding}.
+ * @returns The embedding result, or a failure.
+ * @public
+ */
+export async function callProxiedEmbedding(proxyUrl, params) {
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal } = params;
+    const body = {
+        providerId: descriptor.id,
+        apiKey,
+        params: request
+    };
+    if (modelOverride !== undefined) {
+        body.modelOverride = modelOverride;
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI embedding proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
+    const url = `${proxyUrl}/api/ai/embedding`;
+    const jsonResult = await fetchJson(url, {}, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    const response = jsonResult.value;
+    if (typeof response.error === 'string') {
+        return fail(`proxy: ${response.error}`);
+    }
+    return proxiedEmbeddingResponse
+        .validate(response)
+        .withErrorFormat((msg) => `proxy returned invalid response: ${msg}`);
+}
+//# sourceMappingURL=embeddingClient.js.map