@genesislcap/foundation-ai 15.22.2 → 15.23.0

package/dist/dts/transports/gemini-transport.d.ts

@@ -1,6 +1,36 @@
 import { type AITransport, type CostReportingTransport, type GeminiModelId, type StructuredPromptOptions } from '../types';
 import type { ChatTransport } from '../types/chat-transport.types';
 import type { ChatMessage, ChatRequestOptions } from '../types/chat.types';
+/**
+ * Gemini's `thinkingLevel` enum, weakest to strongest. The ORDER is load-bearing:
+ * {@link clampThinkingLevel} measures distance along it.
+ */
+type GeminiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
+/**
+ * Clamp `level` onto the nearest level in `supported`, measured along {@link GEMINI_LEVEL_LADDER}.
+ * Returns `level` untouched when it is already supported, or when `supported` is empty/absent.
+ *
+ * Takes the SET, not a model id, so it is a pure function of its arguments. A helper that read
+ * {@link GEMINI_THINKING_LEVELS} internally could only ever be tested through whichever rows
+ * happen to be in it — and the tie-break below is precisely the rule no current row exercises.
+ *
+ * Ties resolve UPWARD. **Not for continuity** — the shipped rows changed deliberately when they
+ * were widened to the measured sets, so `medium` on `gemini-3.5-flash` no longer folds to `high`.
+ * The reason is cost visibility: a clamp that reasons a little harder than asked shows up in the
+ * bill, where one that quietly reasons less shows up only as a worse answer nobody attributes to
+ * this function.
+ *
+ * **No current row can produce a tie**, and that is a property of their shape rather than luck. A
+ * tie needs two supported levels equidistant from an unsupported target, which needs a GAP inside
+ * the set; every row today is a contiguous suffix of the ladder, so the only clamp any of them
+ * produces is `minimal` → `low`, at distances 1/2/3. The old coarse `['low','high']` pair WAS the
+ * gapped shape — `medium` sat equidistant between them, which is why that table folded it up —
+ * and widening the rows removed it. The rule is kept, and pinned in the tests against a synthesised
+ * gapped set, so whoever adds such a row next finds the behaviour decided rather than discovers it.
+ *
+ * @internal
+ */
+export declare function clampThinkingLevel(supported: readonly GeminiThinkingLevel[] | undefined, level: GeminiThinkingLevel): GeminiThinkingLevel;
 export interface GeminiTransportConfig {
     /**
      * Defaults to `gemini-2.5-flash-lite`. Only {@link SUPPORTED_GEMINI_MODEL_IDS} are accepted.
@@ -73,7 +103,7 @@ export declare class GeminiTransport implements AITransport, ChatTransport, Cost
     /**
      * 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):
+     * turn. Three shapes reach here (the Anthropic twin warns on the first two):
      *
      * - `'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
@@ -83,6 +113,12 @@ export declare class GeminiTransport implements AITransport, ChatTransport, Cost
      *   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.
+     * - A graded depth whose DIALECT a Gemini 3 tier speaks but whose particular value it does not
+     *   accept — `minimal` on `gemini-3.8-flash` or `gemini-3.1-pro-preview`, the two tiers that
+     *   reject it outright. Nothing is dropped here; `clampThinkingLevel` MOVES the level onto the
+     *   nearest one the tier takes, and since ties resolve upward the move is usually to something
+     *   DEARER than the caller chose. A cost decision reversed on the wire in the expensive
+     *   direction is exactly what this warning exists for — without it the only trace is the bill.
      */
     private warnIfThinkingUnclampable;
     constructor(config?: GeminiTransportConfig);
@@ -165,4 +201,5 @@ export declare class GeminiTransport implements AITransport, ChatTransport, Cost
     private post;
     private toDirectPayload;
 }
+export {};
 //# sourceMappingURL=gemini-transport.d.ts.map

package/dist/dts/transports/gemini-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gemini-transport.d.ts","sourceRoot":"","sources":["../../../src/transports/gemini-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC7B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAEV,WAAW,EACX,kBAAkB,EAMnB,MAAM,qBAAqB,CAAC;AA8K7B,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AA6ED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM;gBAAtB,aAAa,CAAC,EAAE,MAAM;CAI5C;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,YAAW,WAAW,EAAE,aAAa,EAAE,sBAAsB;IACxF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD;;;;;OAKG;IACH,OAAO,CAAC,eAAe,CAAK;IAC5B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB,CAAK;IAC/B;;;OAGG;IACH,OAAO,CAAC,qBAAqB,CAAS;IAEtC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,yBAAyB;gBAmBrB,MAAM,GAAE,qBAA0B;IAe9C,SAAS,IAAI;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,aAAa,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAQ/E,iGAAiG;IACjG,eAAe,IAAI,MAAM;IAIzB,mGAAmG;IACnG,kBAAkB,IAAI,MAAM;IAI5B,+FAA+F;IAC/F,iBAAiB,IAAI,IAAI;IAOnB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBvE,eAAe,CACnB,OAAO,EAAE,WAAW,EAAE,EACtB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,WAAW,CAAC;IA+HvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAa;IACvD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAK;IAEhD;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAqCrB,OAAO,CAAC,gBAAgB;IAwGxB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IAyCvB,OAAO,CAAC,kBAAkB;IAsI1B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,wBAAwB;IAoBhC;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IAkC3B,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAO;IAChD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAAO;IACzD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAO;IACjD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAIxC;IAEF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAQ;YAEjC,IAAI;IAgBlB,OAAO,CAAC,eAAe;CAexB"}
+{"version":3,"file":"gemini-transport.d.ts","sourceRoot":"","sources":["../../../src/transports/gemini-transport.ts"],"names":[],"mappings":"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"}

package/dist/dts/types/config.types.d.ts

@@ -9,7 +9,7 @@ export type AIProviderType = 'openai' | 'chrome' | 'gemini' | 'anthropic' | 'non
  *
  * @beta
  */
-export type GeminiModelId = 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-3.5-flash' | 'gemini-3.1-flash-lite' | 'gemini-3.1-pro-preview';
+export type GeminiModelId = 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-3.8-flash' | 'gemini-3.5-flash' | 'gemini-3.1-flash-lite' | 'gemini-3.1-pro-preview';
 /** @beta */
 export declare const SUPPORTED_GEMINI_MODEL_IDS: readonly GeminiModelId[];
 /**

package/dist/dts/types/config.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.types.d.ts","sourceRoot":"","sources":["../../../src/types/config.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC;AAEnF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,kBAAkB,GAClB,uBAAuB,GAEvB,wBAAwB,CAAC;AAE7B,YAAY;AACZ,eAAO,MAAM,0BAA0B,EAAE,SAAS,aAAa,EAOrD,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,2BAA2B,CAAC;AAEhC,YAAY;AACZ,eAAO,MAAM,6BAA6B,EAAE,SAAS,gBAAgB,EAO3D,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAIzE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,6DAA6D;AAC7D,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;AAErE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,YAAY,CAAC,EAAE,QAAQ,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,YAAY,EAAE,QAAQ,CAAC;IACvB,4GAA4G;IAC5G,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,YAAY,EAAE,WAAW,CAAC;IAC1B,mHAAmH;IACnH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,cAAc,GAAG,cAAc,GAAG,iBAAiB,CAAC"}
+{"version":3,"file":"config.types.d.ts","sourceRoot":"","sources":["../../../src/types/config.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC;AAEnF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,kBAAkB,GAClB,kBAAkB,GAClB,uBAAuB,GAEvB,wBAAwB,CAAC;AAE7B,YAAY;AACZ,eAAO,MAAM,0BAA0B,EAAE,SAAS,aAAa,EAQrD,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,2BAA2B,CAAC;AAEhC,YAAY;AACZ,eAAO,MAAM,6BAA6B,EAAE,SAAS,gBAAgB,EAO3D,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAIzE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,6DAA6D;AAC7D,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;AAErE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,YAAY,CAAC,EAAE,QAAQ,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,YAAY,EAAE,QAAQ,CAAC;IACvB,4GAA4G;IAC5G,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,YAAY,EAAE,WAAW,CAAC;IAC1B,mHAAmH;IACnH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,cAAc,GAAG,cAAc,GAAG,iBAAiB,CAAC"}

package/dist/dts/utils/token-cost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-cost.d.ts","sourceRoot":"","sources":["../../../src/utils/token-cost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAkDhE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;CACtB;AAiCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CAErE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AACnD,YAAY;AACZ,eAAO,MAAM,mCAAmC,OAAO,CAAC;AACxD,YAAY;AACZ,eAAO,MAAM,mCAAmC,IAAI,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4FAA4F;IAC5F,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;;;OASG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,oBAAoB,GAC1B,SAAS,CAiCX;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAsClD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,GAAG,UAAU,CAMrF;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB,GAAG,SAAS,CAuBzF"}
+{"version":3,"file":"token-cost.d.ts","sourceRoot":"","sources":["../../../src/utils/token-cost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAkDhE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;CACtB;AAiCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CAErE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AACnD,YAAY;AACZ,eAAO,MAAM,mCAAmC,OAAO,CAAC;AACxD,YAAY;AACZ,eAAO,MAAM,mCAAmC,IAAI,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4FAA4F;IAC5F,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;;;OASG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,oBAAoB,GAC1B,SAAS,CAiCX;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAsDlD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,GAAG,UAAU,CAMrF;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB,GAAG,SAAS,CAuBzF"}

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

@@ -21,6 +21,7 @@ const GEMINI_CONTEXT_LIMITS = {
     'gemini-2.5-pro': 1048576,
     'gemini-2.5-flash': 1048576,
     'gemini-2.5-flash-lite': 1048576,
+    'gemini-3.8-flash': 1048576,
     'gemini-3.5-flash': 1048576,
     'gemini-3.1-flash-lite': 1048576,
     'gemini-3.1-pro-preview': 1048576,
@@ -55,6 +56,10 @@ const GEMINI_MODEL_WARNINGS = {
     'gemini-2.5-flash': 'GeminiTransport: using gemini-2.5-flash — higher cost than flash-lite; use for harder reasoning or agent tasks.',
     'gemini-2.5-pro': 'GeminiTransport: using gemini-2.5-pro — significantly higher, prompt-size-tiered cost; reserve for tasks where flash reliability is insufficient.',
     'gemini-3.5-flash': 'GeminiTransport: using gemini-3.5-flash — frontier model, materially higher cost than flash-lite; use for harder reasoning or agent tasks.',
+    // Warns despite currently costing LESS than gemini-3.5-flash, because that is temporary: the
+    // rate doubles on 2027-01-01 (see GEMINI_PRICING). A caller that picks this tier on today's
+    // price and never revisits the choice gets twice the bill in January without changing a line.
+    'gemini-3.8-flash': 'GeminiTransport: using gemini-3.8-flash — frontier model, materially higher cost than flash-lite. Its $0.75/$3.75 per-MTok rate is introductory and DOUBLES to $1.50/$7.50 on 2027-01-01; re-check this tier choice before then.',
     'gemini-3.1-pro-preview': 'GeminiTransport: using gemini-3.1-pro-preview — PREVIEW model (no stability guarantee, may be withdrawn) with significantly higher, prompt-size-tiered cost; reserve for tasks where flash reliability is insufficient.',
 };
 /**
@@ -84,21 +89,100 @@ const GEMINI_THINKING_DISABLEABLE = [
 ];
 /** Tiers that accept `generationConfig.mediaResolution`. Gemini 3 only, like `thinkingLevel`. */
 const GEMINI_MEDIA_RESOLUTION_TIERS = [
+    'gemini-3.8-flash',
     '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',
-];
+const GEMINI_LEVEL_LADDER = ['minimal', 'low', 'medium', 'high'];
+/**
+ * The `thinkingLevel` values each Gemini 3 tier accepts, weakest first — and, by carrying an entry
+ * at all, WHICH tiers speak the `thinkingLevel` dialect rather than the 2.5 numeric
+ * `thinkingBudget`. One table where there were two parallel lists, so a tier can no longer be
+ * added to the dialect list and forgotten in the level list.
+ *
+ * Replaces a boolean "full four-level enum, or only the coarse `low`/`high` pair", a shape
+ * `gemini-3.8-flash` does not fit: it takes `low`, `medium` and `high` but NOT `minimal`. The
+ * boolean could only round that to a wrong answer in one direction or the other — coarsening it
+ * sends every `medium` request as `high` and pays for reasoning nobody asked for, while leaving it
+ * uncoarsened forwards `minimal` to a tier that rejects it. Google now publishes the accepted set
+ * per model, so that table is what is encoded here.
+ * https://ai.google.dev/gemini-api/docs/thinking
+ *
+ * **Every row here is OBSERVED, not documented** — the bar this file has always set for forwarding
+ * an enum value ("a clamp costs money, but a guess costs a 400 on a turn the user is waiting for"),
+ * and the reason the previous version pinned all three shipped tiers to the coarse `low`/`high`
+ * pair rather than trusting a docs table. Measured 2026-09-04 by POSTing each level at each tier
+ * directly, bypassing this clamp (which can never observe a rejection, since it prevents one):
+ *
+ * | tier | minimal | low | medium | high |
+ * |---|---|---|---|---|
+ * | `gemini-3.8-flash` | **400** | ok | ok | ok |
+ * | `gemini-3.5-flash` | ok | ok | ok | ok |
+ * | `gemini-3.1-flash-lite` | ok | ok | ok | ok |
+ * | `gemini-3.1-pro-preview` | **400** | ok | ok | ok |
+ *
+ * So the two `minimal` clamps are load-bearing — unclamped they are a hard
+ * `Thinking level MINIMAL is not supported for this model` on a turn the user is waiting for —
+ * and the coarse pair was over-clamping the other three tiers, quietly buying `high` reasoning for
+ * every caller who asked for `medium` and billing it at the candidate rate.
+ *
+ * Worth noting against future doc-reading: Google's own thinking-level table disagrees with this
+ * measurement on `gemini-3.1-flash-lite` (it lists minimal/high only, where the API accepts all
+ * four). Re-measure with the probe rather than re-reading the docs when a tier is added.
+ */
+const GEMINI_THINKING_LEVELS = {
+    'gemini-3.8-flash': ['low', 'medium', 'high'],
+    'gemini-3.5-flash': ['minimal', 'low', 'medium', 'high'],
+    'gemini-3.1-flash-lite': ['minimal', 'low', 'medium', 'high'],
+    'gemini-3.1-pro-preview': ['low', 'medium', 'high'],
+};
+/**
+ * Clamp `level` onto the nearest level in `supported`, measured along {@link GEMINI_LEVEL_LADDER}.
+ * Returns `level` untouched when it is already supported, or when `supported` is empty/absent.
+ *
+ * Takes the SET, not a model id, so it is a pure function of its arguments. A helper that read
+ * {@link GEMINI_THINKING_LEVELS} internally could only ever be tested through whichever rows
+ * happen to be in it — and the tie-break below is precisely the rule no current row exercises.
+ *
+ * Ties resolve UPWARD. **Not for continuity** — the shipped rows changed deliberately when they
+ * were widened to the measured sets, so `medium` on `gemini-3.5-flash` no longer folds to `high`.
+ * The reason is cost visibility: a clamp that reasons a little harder than asked shows up in the
+ * bill, where one that quietly reasons less shows up only as a worse answer nobody attributes to
+ * this function.
+ *
+ * **No current row can produce a tie**, and that is a property of their shape rather than luck. A
+ * tie needs two supported levels equidistant from an unsupported target, which needs a GAP inside
+ * the set; every row today is a contiguous suffix of the ladder, so the only clamp any of them
+ * produces is `minimal` → `low`, at distances 1/2/3. The old coarse `['low','high']` pair WAS the
+ * gapped shape — `medium` sat equidistant between them, which is why that table folded it up —
+ * and widening the rows removed it. The rule is kept, and pinned in the tests against a synthesised
+ * gapped set, so whoever adds such a row next finds the behaviour decided rather than discovers it.
+ *
+ * @internal
+ */
+export function clampThinkingLevel(supported, level) {
+    if (!(supported === null || supported === void 0 ? void 0 : supported.length) || supported.includes(level)) {
+        return level;
+    }
+    const target = GEMINI_LEVEL_LADDER.indexOf(level);
+    const distance = (candidate) => Math.abs(GEMINI_LEVEL_LADDER.indexOf(candidate) - target);
+    // `supported` is weakest-first, and `<=` lets a later (stronger) candidate win an equal
+    // distance — that is the upward tie-break.
+    let best = supported[0];
+    for (const candidate of supported) {
+        if (distance(candidate) <= distance(best)) {
+            best = candidate;
+        }
+    }
+    return best;
+}
 /**
  * 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}.
+ * The result is then clamped again, per tier, by {@link clampThinkingLevel}.
  */
 const GEMINI_THINKING_LEVEL = {
     minimal: 'minimal',
@@ -107,36 +191,18 @@ const GEMINI_THINKING_LEVEL = {
     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 (isGradedLevel(policy)) {
+        // Presence in the table IS the "speaks the thinkingLevel dialect" test, so one lookup answers
+        // both questions and there is no separate predicate to keep in step with it.
+        const accepted = GEMINI_THINKING_LEVELS[model];
+        if (accepted) {
+            return {
+                includeThoughts: true,
+                thinkingLevel: clampThinkingLevel(accepted, GEMINI_THINKING_LEVEL[policy]),
+            };
+        }
     }
     if (policy === 'off' && GEMINI_THINKING_DISABLEABLE.includes(model)) {
         // No reasoning to return once there is none to bill for.
@@ -215,7 +281,7 @@ export class GeminiTransport {
     /**
      * 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):
+     * turn. Three shapes reach here (the Anthropic twin warns on the first two):
      *
      * - `'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
@@ -225,6 +291,12 @@ export class GeminiTransport {
      *   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.
+     * - A graded depth whose DIALECT a Gemini 3 tier speaks but whose particular value it does not
+     *   accept — `minimal` on `gemini-3.8-flash` or `gemini-3.1-pro-preview`, the two tiers that
+     *   reject it outright. Nothing is dropped here; `clampThinkingLevel` MOVES the level onto the
+     *   nearest one the tier takes, and since ties resolve upward the move is usually to something
+     *   DEARER than the caller chose. A cost decision reversed on the wire in the expensive
+     *   direction is exactly what this warning exists for — without it the only trace is the bill.
      */
     warnIfThinkingUnclampable(policy) {
         if (this.warnedThinkingClamped) {
@@ -235,9 +307,24 @@ export class GeminiTransport {
             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;
         }
-        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.`);
+        if (isGradedLevel(policy)) {
+            // ONE lookup, and both graded cases hang off whether it found anything. Written this way
+            // rather than as two separate membership tests so the non-null below is established by the
+            // early return rather than asserted — no fallback guarding a state the control flow already
+            // rules out, and it still compiles if `strictNullChecks` is ever turned on (indexing a
+            // `Partial<Record>` yields `T | undefined` under it).
+            const accepted = GEMINI_THINKING_LEVELS[this.model];
+            if (!accepted) {
+                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.`);
+                return;
+            }
+            const requested = GEMINI_THINKING_LEVEL[policy];
+            const sent = clampThinkingLevel(accepted, requested);
+            if (sent !== requested) {
+                this.warnedThinkingClamped = true;
+                logger.warn(`GeminiTransport: thinkingPolicy '${policy}' sent as thinkingLevel '${sent}' — ${this.model} does not accept '${requested}' (it takes ${accepted.join('/')}). Reasoning bills at the candidate rate, so an upward clamp costs more than you asked for.`);
+            }
         }
     }
     constructor(config = {}) {

package/dist/esm/types/config.types.js

@@ -3,6 +3,7 @@ export const SUPPORTED_GEMINI_MODEL_IDS = [
     'gemini-2.5-pro',
     'gemini-2.5-flash',
     'gemini-2.5-flash-lite',
+    'gemini-3.8-flash',
     'gemini-3.5-flash',
     'gemini-3.1-flash-lite',
     'gemini-3.1-pro-preview',

package/dist/esm/utils/token-cost.js

@@ -181,6 +181,22 @@ const GEMINI_PRICING = {
         rate: { promptPerMillion: 0.25, candidatePerMillion: 1.5 },
     },
     'gemini-3.5-flash': { kind: 'flat', rate: { promptPerMillion: 1.5, candidatePerMillion: 9.0 } },
+    // INTRODUCTORY RATE, and the only dated entry in this file. Google publishes
+    // $0.75 / $3.75 per MTok **through 2026-12-31**, rising to $1.50 / $7.50 on 2027-01-01 —
+    // so today this model is CHEAPER than gemini-3.5-flash above and in January it is not.
+    //
+    // The listed figure is the one in force, not the one coming. That is the lesson the
+    // `claude-sonnet-5` entry records from the other direction: charging a scheduled future
+    // rate early over-billed every request by 50% for as long as nobody noticed. A rate that
+    // has not taken effect is not a price, and `GeminiPricing` deliberately has no time
+    // dimension to express one — flip these two numbers on 2027-01-01 instead.
+    //
+    // That flip is ENFORCED, not remembered: `token-cost.test.ts` carries a dated assertion that
+    // turns the build red on 2027-01-01 and names the three-line edit (these two rates, plus the
+    // now-false `< gemini-3.5-flash` comparison in that same test — both models are $1.50 input
+    // from that date). There is no ticket to lose.
+    // https://ai.google.dev/gemini-api/docs/pricing
+    'gemini-3.8-flash': { kind: 'flat', rate: { promptPerMillion: 0.75, candidatePerMillion: 3.75 } },
     'gemini-3.1-pro-preview': {
         kind: 'tiered',
         standard: { promptPerMillion: 2.0, candidatePerMillion: 12.0 },

package/dist/foundation-ai.api.json

@@ -8608,7 +8608,7 @@
             },
             {
               "kind": "Content",
-              "text": "'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-3.5-flash' | 'gemini-3.1-flash-lite' | 'gemini-3.1-pro-preview'"
+              "text": "'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-3.8-flash' | 'gemini-3.5-flash' | 'gemini-3.1-flash-lite' | 'gemini-3.1-pro-preview'"
             },
             {
               "kind": "Content",

package/dist/foundation-ai.d.ts

@@ -2405,7 +2405,7 @@ export declare interface GeminiAIConfig extends AIProviderConfig {
  *
  * @beta
  */
-export declare type GeminiModelId = 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-3.5-flash' | 'gemini-3.1-flash-lite' | 'gemini-3.1-pro-preview';
+export declare type GeminiModelId = 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-3.8-flash' | 'gemini-3.5-flash' | 'gemini-3.1-flash-lite' | 'gemini-3.1-pro-preview';
 
 /**
  * Gemini AI provider. Uses {@link GeminiTransport} to handle requests.
@@ -2488,7 +2488,7 @@ export declare class GeminiTransport implements AITransport, ChatTransport, Cost
     /**
      * 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):
+     * turn. Three shapes reach here (the Anthropic twin warns on the first two):
      *
      * - `'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
@@ -2498,6 +2498,12 @@ export declare class GeminiTransport implements AITransport, ChatTransport, Cost
      *   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.
+     * - A graded depth whose DIALECT a Gemini 3 tier speaks but whose particular value it does not
+     *   accept — `minimal` on `gemini-3.8-flash` or `gemini-3.1-pro-preview`, the two tiers that
+     *   reject it outright. Nothing is dropped here; `clampThinkingLevel` MOVES the level onto the
+     *   nearest one the tier takes, and since ties resolve upward the move is usually to something
+     *   DEARER than the caller chose. A cost decision reversed on the wire in the expensive
+     *   direction is exactly what this warning exists for — without it the only trace is the bill.
      */
     private warnIfThinkingUnclampable;
     constructor(config?: GeminiTransportConfig);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-ai",
   "description": "Genesis Foundation AI - Provider-agnostic AI configuration and shared utilities",
-  "version": "15.22.2",
+  "version": "15.23.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -52,17 +52,17 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.22.2",
-    "@genesislcap/genx": "15.22.2",
-    "@genesislcap/rollup-builder": "15.22.2",
-    "@genesislcap/ts-builder": "15.22.2",
-    "@genesislcap/uvu-playwright-builder": "15.22.2",
-    "@genesislcap/vite-builder": "15.22.2",
-    "@genesislcap/webpack-builder": "15.22.2"
+    "@genesislcap/foundation-testing": "15.23.0",
+    "@genesislcap/genx": "15.23.0",
+    "@genesislcap/rollup-builder": "15.23.0",
+    "@genesislcap/ts-builder": "15.23.0",
+    "@genesislcap/uvu-playwright-builder": "15.23.0",
+    "@genesislcap/vite-builder": "15.23.0",
+    "@genesislcap/webpack-builder": "15.23.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-logger": "15.22.2",
-    "@genesislcap/foundation-utils": "15.22.2",
+    "@genesislcap/foundation-logger": "15.23.0",
+    "@genesislcap/foundation-utils": "15.23.0",
     "@microsoft/fast-foundation": "2.50.0"
   },
   "repository": {