@genesislcap/foundation-ai 15.14.2 → 15.15.0

package/dist/esm/transports/gemini-transport.js

@@ -1,5 +1,6 @@
 import { __awaiter } from "tslib";
 import { SUPPORTED_GEMINI_MODEL_IDS, } from '../types';
+import { normalizeImageMime, stripImageDataUrl } from '../utils/image-mime';
 import { logger } from '../utils/logger';
 import { scaleTemperature } from '../utils/temperature';
 import { geminiTokenCost } from '../utils/token-cost';
@@ -71,16 +72,72 @@ const GEMINI_MODEL_WARNINGS = {
  * Only the flash tiers can actually be turned off. `gemini-2.5-pro` always thinks (its minimum
  * budget is 128; `0` is rejected), which is the same constraint Anthropic's Fable 5 has — so a
  * clamp here is the norm across providers, not a Gemini quirk. The 3.x tiers moved to a
- * `thinkingLevel` enum and do not take a numeric budget on every tier, so they are deliberately
- * left on their default rather than sent a value that may not apply: a clamp costs money, but a
- * guess costs a 400 on a turn the user is waiting for. Wire `thinkingLevel` through when the
- * per-tier support is confirmed.
+ * `thinkingLevel` enum instead of a numeric budget, and a graded {@link ChatThinkingPolicy} now
+ * maps onto it (GENC-1508) — the "wire it through once per-tier support is confirmed" this
+ * comment used to defer. The 2.5 tiers keep the budget dialect and ignore graded levels rather
+ * than being sent an enum they do not take: a clamp costs money, but a guess costs a 400 on a
+ * turn the user is waiting for.
  */
 const GEMINI_THINKING_DISABLEABLE = [
     'gemini-2.5-flash',
     'gemini-2.5-flash-lite',
 ];
+/** Tiers that accept `generationConfig.mediaResolution`. Gemini 3 only, like `thinkingLevel`. */
+const GEMINI_MEDIA_RESOLUTION_TIERS = [
+    'gemini-3.5-flash',
+    'gemini-3.1-flash-lite',
+    'gemini-3.1-pro-preview',
+];
+/** The tiers that take `thinkingConfig.thinkingLevel` rather than a numeric `thinkingBudget`. */
+const GEMINI_THINKING_LEVEL_TIERS = [
+    'gemini-3.5-flash',
+    'gemini-3.1-flash-lite',
+    'gemini-3.1-pro-preview',
+];
+/**
+ * Graded policy → Gemini `thinkingLevel`. Exhaustive `Record` for the same reason as the
+ * Anthropic table: a new level must be mapped here or the build fails.
+ *
+ * `'max'` clamps DOWN to `high` — Gemini's ladder stops there. See {@link ChatThinkingPolicy}.
+ */
+const GEMINI_THINKING_LEVEL = {
+    minimal: 'minimal',
+    low: 'low',
+    medium: 'medium',
+    high: 'high',
+    max: 'high',
+};
+/**
+ * Tiers that accept only the coarse `low` / `high` pair rather than the full four-level enum.
+ *
+ * Currently EVERY `thinkingLevel` tier. The Gemini 3 line did not ship `minimal` and `medium`
+ * across every tier at once, and this file's own doctrine is that an unverified enum value is
+ * worse than a coarser one — "a clamp costs money, but a guess costs a 400 on a turn the user is
+ * waiting for". `low`/`high` are the pair confirmed across the line, so the fine levels fold onto
+ * their nearer neighbour here rather than being forwarded on faith to a tier that may 400 on
+ * them. Remove a tier from this list once its support for the full enum has been OBSERVED, not
+ * assumed — `GEMINI_THINKING_LEVEL`'s finer mapping then takes effect for it immediately.
+ */
+const GEMINI_COARSE_LEVEL_TIERS = [
+    'gemini-3.5-flash',
+    'gemini-3.1-flash-lite',
+    'gemini-3.1-pro-preview',
+];
+const GEMINI_COARSE_LEVEL = {
+    minimal: 'low',
+    low: 'low',
+    medium: 'high',
+    high: 'high',
+};
+const isGradedLevel = (p) => p !== undefined && p !== 'auto' && p !== 'off';
 function geminiThinkingConfig(model, policy) {
+    if (isGradedLevel(policy) && GEMINI_THINKING_LEVEL_TIERS.includes(model)) {
+        const level = GEMINI_THINKING_LEVEL[policy];
+        return {
+            includeThoughts: true,
+            thinkingLevel: GEMINI_COARSE_LEVEL_TIERS.includes(model) ? GEMINI_COARSE_LEVEL[level] : level,
+        };
+    }
     if (policy === 'off' && GEMINI_THINKING_DISABLEABLE.includes(model)) {
         // No reasoning to return once there is none to bill for.
         return { includeThoughts: false, thinkingBudget: 0 };
@@ -105,6 +162,32 @@ const SKIP_SIGNATURE = 'skip_thought_signature_validator';
  * provider-neutral `providerMetadata` bag. Private to GeminiTransport.
  */
 const GEMINI_PROVIDER_KEY = 'gemini';
+/**
+ * Split attachments into image parts and text parts.
+ *
+ * Images are emitted BEFORE the accompanying text part; text attachments keep their existing
+ * position AFTER it, so a turn carrying no images serialises byte-identically to before this
+ * existed. Branches on `kind`, never on `mimeType` — the composer's `readAsText` path can
+ * produce an image mime with text content (see `ChatImageAttachment`).
+ */
+function splitAttachmentParts(atts) {
+    const imageParts = [];
+    const textParts = [];
+    for (const att of atts) {
+        if (att.kind === 'image') {
+            imageParts.push({
+                inlineData: {
+                    mimeType: normalizeImageMime(att.mimeType),
+                    data: stripImageDataUrl(att.data),
+                },
+            });
+        }
+        else {
+            textParts.push({ text: `[File: ${att.name}]\n${att.content}` });
+        }
+    }
+    return { imageParts, textParts };
+}
 /**
  * Thrown when Gemini returns a `MALFORMED_FUNCTION_CALL` finish reason,
  * typically because the model tried to batch multiple tool calls using
@@ -130,23 +213,32 @@ export class MalformedFunctionCallError extends Error {
  */
 export class GeminiTransport {
     /**
-     * Warn once when a requested policy is silently clamped. Turning thinking off is a *cost*
-     * decision, so a caller who asked for it and kept paying for reasoning tokens needs to hear
-     * about it — but only once, not per turn.
+     * Warn once when a requested policy cannot be honoured on this model — a *cost* decision the
+     * caller made that the wire silently reversed, so they hear about it, but only once, not per
+     * turn. Two shapes reach here (the Anthropic twin warns on the same two):
      *
-     * Only `'off'` can actually be denied. `'auto'` is already what an omitted budget produces on
-     * every model here — dynamic thinking is the documented default — so warning that it was
-     * "ignored" would be false, and latching on it would spend the one warning the genuinely
-     * unhonourable `'off'` needs.
+     * - `'off'` on a tier that can't disable thinking — only the flash tiers accept a zero thinking
+     *   budget; everything else keeps paying for reasoning it was told to stop. (`'auto'` is NOT this
+     *   case: it is already what an omitted budget produces on every model here, so warning it was
+     *   "ignored" would be false and would spend the one warning the genuine cases need.)
+     * - A graded depth (`minimal`…`max`) on a 2.5 tier — those speak the numeric-budget dialect,
+     *   not the Gemini 3 `thinkingLevel` enum, so the level is dropped and the turn runs at the
+     *   default posture. Without this, a caller asking for `high` on `gemini-2.5-pro` and quietly
+     *   getting the default is left to wonder why.
      */
     warnIfThinkingUnclampable(policy) {
-        if (policy !== 'off' ||
-            GEMINI_THINKING_DISABLEABLE.includes(this.model) ||
-            this.warnedThinkingClamped) {
+        if (this.warnedThinkingClamped) {
+            return;
+        }
+        if (policy === 'off' && !GEMINI_THINKING_DISABLEABLE.includes(this.model)) {
+            this.warnedThinkingClamped = true;
+            logger.warn(`GeminiTransport: thinkingPolicy 'off' ignored — ${this.model} runs its default thinking posture and takes no budget we can safely set. Reasoning tokens are still billed at the candidate rate; use a flash tier if you need them gone.`);
             return;
         }
-        this.warnedThinkingClamped = true;
-        logger.warn(`GeminiTransport: thinkingPolicy 'off' ignored — ${this.model} runs its default thinking posture and takes no budget we can safely set. Reasoning tokens are still billed at the candidate rate; use a flash tier if you need them gone.`);
+        if (isGradedLevel(policy) && !GEMINI_THINKING_LEVEL_TIERS.includes(this.model)) {
+            this.warnedThinkingClamped = true;
+            logger.warn(`GeminiTransport: thinkingPolicy '${policy}' ignored — ${this.model} takes a numeric thinking budget, not the graded 'thinkingLevel' the Gemini 3 tiers use, so this turn runs at its default reasoning posture. Use a Gemini 3 tier to set reasoning depth.`);
+        }
     }
     constructor(config = {}) {
         var _a, _b, _c;
@@ -218,7 +310,7 @@ export class GeminiTransport {
     // ── ChatTransport (multi-turn chat) ────────────────────────────────────
     sendChatMessage(history, userMessage, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a, _b, _c;
             // NOTE: `options.cachePolicy` is intentionally NOT read here. Gemini 2.5+ does *implicit*
             // caching automatically and always-on — it caches as much of the stable request prefix as it
             // can on every call, regardless of the policy's `scope` (including `'default'`). We issue no
@@ -264,6 +356,31 @@ export class GeminiTransport {
             // supports one; Gemini 2.5 Pro always thinks regardless. See `geminiThinkingConfig`.
             this.warnIfThinkingUnclampable(options === null || options === void 0 ? void 0 : options.thinkingPolicy);
             const generationConfig = { thinkingConfig: geminiThinkingConfig(this.model, options === null || options === void 0 ? void 0 : options.thinkingPolicy) };
+            // Per-turn output ceiling; see ChatRequestOptions.maxTokens for why the instance default
+            // is not enough. Omitted when unset, so an unchanged caller sends an unchanged body.
+            if ((options === null || options === void 0 ? void 0 : options.maxTokens) != null) {
+                generationConfig.maxOutputTokens = options.maxTokens;
+            }
+            // Image fidelity, from the FIRST image attachment that states a preference. Gemini bills
+            // image tokens by resolution, so this is a real cost lever — and it is the one thing on
+            // ChatImageAttachment that Anthropic has no equivalent for, where the only lever is the
+            // pixels you send. Deliberately not synthesised into an Anthropic knob.
+            const resolutionHint = [
+                ...((_b = options === null || options === void 0 ? void 0 : options.attachments) !== null && _b !== void 0 ? _b : []),
+                ...history.flatMap((m) => { var _a; return (_a = m.attachments) !== null && _a !== void 0 ? _a : []; }),
+                // Tool-result images too: `ChatToolResult.attachments` is typed ChatImageAttachment[], so
+                // `detail` is offerable there, and a render handed back by a tool is the whole point of
+                // the tool-result image path. Omitting this source made the field silently inert there.
+                ...history.flatMap((m) => { var _a, _b; return (_b = (_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.attachments) !== null && _b !== void 0 ? _b : []; }),
+            ].find((att) => att.kind === 'image' && att.detail);
+            // Gated by tier for the same reason thinkingLevel is: a clamp costs money, a guess costs a
+            // 400. Note it is per-REQUEST, so the first stated preference governs every image in the
+            // turn — there is no per-image control on the wire.
+            if ((resolutionHint === null || resolutionHint === void 0 ? void 0 : resolutionHint.kind) === 'image' &&
+                resolutionHint.detail &&
+                GEMINI_MEDIA_RESOLUTION_TIERS.includes(this.model)) {
+                generationConfig.mediaResolution = `MEDIA_RESOLUTION_${resolutionHint.detail.toUpperCase()}`;
+            }
             // Normalized [0,1] temperature → Gemini's native range, anchored so 0.5
             // maps to its default (native 1) and 1 to its ceiling (native 2).
             if ((options === null || options === void 0 ? void 0 : options.temperature) != null) {
@@ -274,7 +391,7 @@ export class GeminiTransport {
             }
             // Names of the tools offered this turn — used to validate a repaired
             // malformed call against the real tool surface before accepting it.
-            const offeredToolNames = new Set(((_b = options === null || options === void 0 ? void 0 : options.tools) !== null && _b !== void 0 ? _b : []).map((t) => t.name));
+            const offeredToolNames = new Set(((_c = options === null || options === void 0 ? void 0 : options.tools) !== null && _c !== void 0 ? _c : []).map((t) => t.name));
             // Structured output (native JSON mode). Gemini 3 can combine it with function calling;
             // Gemini 2.x cannot, so on 2.x apply the schema only on a pure structured turn (no tools) and
             // otherwise drop it (the caller keeps a prompt-instruction + validator fallback). Passed as a
@@ -289,7 +406,7 @@ export class GeminiTransport {
                 generationConfig }, (applyResponseSchema
                 ? { responseSchema: toGeminiSchema(options.responseSchema) }
                 : {})), options === null || options === void 0 ? void 0 : options.signal);
-            return this.fromGeminiResponse(response, offeredToolNames);
+            return this.fromGeminiResponse(response, offeredToolNames, generationConfig.maxOutputTokens);
         });
     }
     /**
@@ -321,7 +438,7 @@ export class GeminiTransport {
         return costUsd;
     }
     toGeminiContents(history, userMessage, attachments) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const contents = [];
         // Gemini requires functionResponse.name to match the original functionCall.name.
         // Our internal IDs are UUIDs, so build a lookup from ID → function name as we go.
@@ -350,8 +467,22 @@ export class GeminiTransport {
                         },
                     ],
                 });
+                // Images ride in their OWN following user content rather than inside
+                // `functionResponse.response`. That field is a protobuf Struct and per-tier support for
+                // media nested in it is unverified; a separate content is plainly legal and costs an
+                // extra content entry. Only emitted when the tool actually returned images, so a
+                // result without them is byte-identical to before.
+                const resultImages = (_b = msg.toolResult.attachments) !== null && _b !== void 0 ? _b : [];
+                if (resultImages.length) {
+                    contents.push({
+                        role: 'user',
+                        parts: resultImages.map((att) => ({
+                            inlineData: { mimeType: normalizeImageMime(att.mimeType), data: att.data },
+                        })),
+                    });
+                }
             }
-            else if ((_b = msg.toolCalls) === null || _b === void 0 ? void 0 : _b.length) {
+            else if ((_c = msg.toolCalls) === null || _c === void 0 ? void 0 : _c.length) {
                 for (const tc of msg.toolCalls) {
                     toolCallNameById.set(tc.id, tc.name);
                 }
@@ -378,21 +509,25 @@ export class GeminiTransport {
                     }),
                 });
             }
-            else if (role === 'user' && ((_c = msg.attachments) === null || _c === void 0 ? void 0 : _c.length)) {
-                const msgAttachmentParts = msg.attachments.map((att) => ({
-                    text: `[File: ${att.name}]\n${att.content}`,
-                }));
-                contents.push({ role: 'user', parts: [{ text: msg.content }, ...msgAttachmentParts] });
+            else if (role === 'user' && ((_d = msg.attachments) === null || _d === void 0 ? void 0 : _d.length)) {
+                const { imageParts, textParts } = splitAttachmentParts(msg.attachments);
+                // Empty text parts are dropped, not sent — see the Anthropic twin. An image-only
+                // message has no caption to carry.
+                contents.push({
+                    role: 'user',
+                    parts: [...imageParts, ...(msg.content ? [{ text: msg.content }] : []), ...textParts],
+                });
             }
             else {
                 contents.push({ role, parts: [{ text: msg.content }] });
             }
         }
-        const attachmentParts = (attachments !== null && attachments !== void 0 ? attachments : []).map((att) => ({
-            text: `[File: ${att.name}]\n${att.content}`,
-        }));
-        if (userMessage || attachmentParts.length) {
-            contents.push({ role: 'user', parts: [{ text: userMessage }, ...attachmentParts] });
+        const { imageParts, textParts } = splitAttachmentParts(attachments !== null && attachments !== void 0 ? attachments : []);
+        if (userMessage || imageParts.length || textParts.length) {
+            contents.push({
+                role: 'user',
+                parts: [...imageParts, ...(userMessage ? [{ text: userMessage }] : []), ...textParts],
+            });
         }
         return contents;
     }
@@ -431,7 +566,13 @@ export class GeminiTransport {
             cost,
         };
     }
-    fromGeminiResponse(response, offeredToolNames = new Set()) {
+    fromGeminiResponse(response, offeredToolNames = new Set(), 
+    /**
+     * The per-turn cap actually sent, when one was. Left `undefined` on the default path so a
+     * truncation still reports "the model's output-token limit" — which is the truth when no
+     * `maxOutputTokens` was set, and a lie the moment one is.
+     */
+    effectiveMaxTokens) {
         var _a, _b, _c, _d;
         const { inputTokens, outputTokens, thoughtsTokens, cacheReadTokens, cost } = this.usageFromGemini(response.usageMetadata);
         const candidates = response === null || response === void 0 ? void 0 : response.candidates;
@@ -502,7 +643,7 @@ export class GeminiTransport {
                 textParts: textParts.length,
             });
         }
-        this.guardMaxTokensTruncation(finishReason, toolCalls, narration, outputTokens);
+        this.guardMaxTokensTruncation(finishReason, toolCalls, narration, outputTokens, effectiveMaxTokens);
         if (inputTokens != null)
             base.inputTokens = inputTokens;
         if (outputTokens != null)
@@ -543,14 +684,16 @@ export class GeminiTransport {
      * `responseMeta.finishReason`, for the caller to decide. Usage/cost is logged
      * before this check runs, so the spent tokens stay accounted for.
      */
-    guardMaxTokensTruncation(finishReason, toolCalls, narration, outputTokens) {
+    guardMaxTokensTruncation(finishReason, toolCalls, narration, outputTokens, 
+    /** The per-turn cap sent, when one was — so the error names the cap it actually hit. */
+    effectiveMaxTokens) {
         if (finishReason !== 'MAX_TOKENS')
             return;
         // A truncated text-only answer is partial but legible — keep it (the driver's
         // emptiness rule is `!content.trim()`, so whitespace-only does NOT count).
         if (toolCalls.length === 0 && narration.trim() !== '')
             return;
-        throw new ResponseTruncatedError(this.model, undefined, outputTokens, toolCalls.map((tc) => tc.name));
+        throw new ResponseTruncatedError(this.model, effectiveMaxTokens, outputTokens, toolCalls.map((tc) => tc.name));
     }
     /**
      * Log the full shape of a blank or non-STOP response so its cause is legible

package/dist/esm/utils/image-mime.js

@@ -0,0 +1,37 @@
+/**
+ * Normalise an image MIME type to the spelling both vendors accept.
+ *
+ * Only `image/jpg` → `image/jpeg` today. That is a rename, not a guess: it is the same format
+ * under a label neither API recognises — Anthropic documents `image/jpeg`, `image/png`,
+ * `image/gif` and `image/webp`, and rejects `image/jpg` with a 400. The alias is common enough
+ * to be worth absorbing (anything deriving a type from a `.jpg` extension produces it), and the
+ * cost of not absorbing it is a failed turn the user is waiting on.
+ *
+ * Deliberately NOT a validator. A genuinely unsupported type (`image/bmp`, `image/svg+xml`)
+ * passes through untouched so the vendor's own error names it, rather than this function
+ * inventing a substitute or throwing on input a future model tier might accept.
+ *
+ * Lives here rather than inline in each transport because it is one rule that must hold for
+ * both; copied into two files it drifts the first time only one is updated.
+ */
+export function normalizeImageMime(mimeType) {
+    return mimeType === 'image/jpg' ? 'image/jpeg' : mimeType;
+}
+/**
+ * Strip a leading `data:` URL prefix from a base64 image payload, returning the bare bytes both
+ * vendors' image blocks expect.
+ *
+ * {@link ChatImageAttachment.data} is documented as bare base64, but the natural browser way to
+ * produce it — `FileReader.readAsDataURL` — yields `data:image/png;base64,…`, and handed in
+ * verbatim that prefix is a 400 on both APIs. This absorbs that one mistake: a
+ * `data:<mime>;base64,` preamble (any or no mime) is removed; anything already bare passes
+ * through untouched. Anchored and `;base64,`-terminated so it only ever removes a real data-URL
+ * header, never a slice of the payload (base64 contains no comma).
+ *
+ * Like {@link normalizeImageMime} it is a normaliser, not a validator — it does not check that
+ * the remainder is valid base64, and lives here for the same reason: one rule both transports
+ * must share.
+ */
+export function stripImageDataUrl(data) {
+    return data.replace(/^data:[^,]*;base64,/, '');
+}