@genesislcap/foundation-ai 15.14.2 → 15.15.0

package/dist/foundation-ai.d.ts

@@ -382,6 +382,15 @@ export declare class AnthropicTransport implements AITransport, ChatTransport, C
      * the same silence would hide a real difference.)
      */
     private warnIfThinkingUnclampable;
+    /**
+     * The warning for a policy this model cannot honour, or `undefined` when it can.
+     *
+     * An exhaustive `switch` with a `never` check rather than a condition chain: a new
+     * {@link ChatThinkingPolicy} member must be considered HERE or the build fails. The condition
+     * chain this replaced would have let every graded level clamp in silence, which is the one
+     * outcome the type's own docs promise callers never happens.
+     */
+    private clampWarning;
     constructor(config?: AnthropicTransportConfig);
     getConfig(): {
         provider: 'anthropic';
@@ -794,11 +803,7 @@ export declare interface ChatAnimationsConfig {
  *
  * @beta
  */
-export declare interface ChatAttachment {
-    name: string;
-    content: string;
-    mimeType: string;
-}
+export declare type ChatAttachment = ChatTextAttachment | ChatImageAttachment;
 
 /**
  * Display and engine configuration for the chat assistant.
@@ -991,6 +996,38 @@ export declare interface ChatFallback {
     maxTokens?: number;
 }
 
+/**
+ * An image attachment included with a user message or a tool result. Sent as a real image
+ * content block — an Anthropic `type: 'image'` block or a Gemini `inlineData` part — not
+ * flattened to text.
+ *
+ * @beta
+ */
+export declare interface ChatImageAttachment {
+    /**
+     * REQUIRED, and the only thing either transport branches on. Deliberately not inferred from
+     * `mimeType`: the composer's `readAsText` path can produce `mimeType: 'image/png'` with text
+     * content, so a mime-based branch would send mojibake as base64 image data.
+     */
+    kind: 'image';
+    name: string;
+    /** One of the four both vendors accept: `image/png`, `image/jpeg`, `image/gif`, `image/webp`. */
+    mimeType: string;
+    /**
+     * Base64 payload — the bare bytes both APIs expect, ideally with NO `data:` URL prefix. A
+     * leading `data:<mime>;base64,` preamble (what `FileReader.readAsDataURL` produces, the easy
+     * mistake) is tolerated: the transports strip it before sending via `stripImageDataUrl`.
+     */
+    data: string;
+    /**
+     * Advisory resolution hint. Honoured on Gemini (`mediaResolution`); a documented no-op on
+     * Anthropic, where the only lever is the pixels you send — resize before attaching. Named
+     * as advisory rather than mapped to a fake Anthropic equivalent, following the precedent of
+     * {@link CachePolicy}'s `ttl` being Anthropic-only and ignored on Gemini.
+     */
+    detail?: 'low' | 'medium' | 'high';
+}
+
 /**
  * Controls how the main chat input area behaves while an agent (or sub-agent)
  * is executing.
@@ -1281,6 +1318,21 @@ export declare interface ChatRequestOptions {
      * @beta
      */
     thinkingPolicy?: ChatThinkingPolicy;
+    /**
+     * Output-token ceiling for THIS turn, overriding the transport's configured `maxTokens`.
+     *
+     * Needed because the configured value is per-transport-INSTANCE, so a caller that wants two
+     * ceilings has to register two providers — which is why ai-service carries separate
+     * `anthropic` and `anthropicFast` slots. That does not scale to a pipeline whose stages
+     * legitimately want very different budgets (a full mockup versus a one-line critique).
+     *
+     * Reaches `max_tokens` on Anthropic and `generationConfig.maxOutputTokens` on Gemini, and is
+     * also what a `ResponseTruncatedError` reports as the cap it hit — otherwise the truncation
+     * message names the instance default and sends you looking at the wrong number.
+     *
+     * @beta
+     */
+    maxTokens?: number;
 }
 
 /**
@@ -1402,6 +1454,36 @@ export declare const ChatTemperature: {
     readonly Maximum: 1;
 };
 
+/**
+ * A text file attachment included with a user message. Serialised to the model as
+ * `[File: <name>]\n<content>` — a plain text block on both vendors.
+ *
+ * @beta
+ */
+export declare interface ChatTextAttachment {
+    /**
+     * Optional on this arm so an attachment authored before images existed — `{ name, content,
+     * mimeType }` — is still a valid `ChatAttachment` with no edit. The image arm requires it.
+     */
+    kind?: 'text';
+    name: string;
+    content: string;
+    /**
+     * Advisory only on this arm. Note the composer reads files with `readAsText`, so a binary
+     * file dropped there arrives with a truthy image mime and mojibake `content` — which is why
+     * the transports branch on `kind`, never on `mimeType`. See {@link ChatImageAttachment}.
+     */
+    mimeType: string;
+}
+
+/**
+ * The graded members of {@link ChatThinkingPolicy} — the ones that carry a depth rather than
+ * merely switching reasoning on or off. Split out so each transport's clamp table can be an
+ * exhaustive `Record` and adding a level to the union becomes a compile error at every mapping
+ * site, rather than a value that silently falls through to "model default".
+ */
+export declare type ChatThinkingLevel = Extract<ChatThinkingPolicy, 'minimal' | 'low' | 'medium' | 'high' | 'max'>;
+
 /**
  * Whether the model should reason before answering, resolved per turn.
  * **Provider-neutral intent, provider-specific effect**, and — like `tool_choice` — a
@@ -1424,8 +1506,23 @@ export declare const ChatTemperature: {
  * Deliberately has **no token-budget member**. Gemini accepts a numeric `thinkingBudget`, but
  * Anthropic *removed* `budget_tokens` and returns a 400 for it on Sonnet 5 and every Opus 5-era
  * model — so a budget field would be unimplementable on half the supported fleet and would exist
- * only to be ignored. `'low' | 'high'` can be added later if wanted: Anthropic `effort` and
- * Gemini `thinkingLevel` do line up.
+ * only to be ignored. The graded levels below are that idea done vendor-neutrally: Anthropic
+ * `output_config.effort` and Gemini `thinkingConfig.thinkingLevel` line up, as anticipated here.
+ *
+ * **The graded levels** (`'minimal'` … `'max'`) ask for a DEPTH of reasoning rather than merely
+ * on/off. On Anthropic they set `output_config.effort` alongside adaptive thinking; on Gemini
+ * they set `thinkingLevel`. Two honest edges:
+ *
+ * - Anthropic has no `'minimal'`, so it clamps to `low`; Gemini has no `'max'`, so it clamps to
+ *   `high`. Each clamp is toward the nearer neighbour, never toward a value that would 400.
+ * - Anthropic's `xhigh` (between `high` and `max`, and its recommended setting for agentic
+ *   coding) is **not exposed**, because Gemini has no equivalent and a value only one vendor can
+ *   express is how a "vendor-neutral" option quietly stops being one. Ask for `'max'` if you want
+ *   the ceiling.
+ *
+ * Models that predate the effort parameter (Sonnet 4.5, Haiku 4.5) reject it, so a graded level
+ * there falls back to that model's adaptive-or-default posture with a one-time warning — the same
+ * clamp discipline the on/off values already follow.
  *
  * **Omitting this is a distinct third state** — each model keeps its own default posture
  * (see `anthropicThinking`), which is *not* uniformly `'auto'` or `'off'`. So a resolver
@@ -1440,7 +1537,7 @@ export declare const ChatTemperature: {
  *
  * @beta
  */
-export declare type ChatThinkingPolicy = 'auto' | 'off';
+export declare type ChatThinkingPolicy = 'auto' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max';
 
 /**
  * A tool call requested by the assistant.
@@ -1691,6 +1788,19 @@ export declare type ChatToolHandlers<TSubAgent extends {
 export declare interface ChatToolResult {
     toolCallId: string;
     content: string;
+    /**
+     * Images the tool produced, sent alongside `content` as real image blocks.
+     *
+     * This is the half that makes a vision AGENT possible rather than a one-shot vision call:
+     * a tool that renders something can hand the render back for the model to LOOK at, instead
+     * of describing it in prose. Only `kind: 'image'` attachments are carried — a text
+     * attachment here would be indistinguishable from `content` and is dropped by the
+     * transports rather than double-sent.
+     *
+     * Absent on every existing tool result, and the transports emit the historical
+     * string-content shape whenever it is absent, so nothing already on the wire moves.
+     */
+    attachments?: ChatImageAttachment[];
 }
 
 /**
@@ -2207,14 +2317,18 @@ export declare class GeminiTransport implements AITransport, ChatTransport, Cost
      */
     private warnedThinkingClamped;
     /**
-     * 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.
      */
     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.14.2",
+  "version": "15.15.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -52,17 +52,17 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.14.2",
-    "@genesislcap/genx": "15.14.2",
-    "@genesislcap/rollup-builder": "15.14.2",
-    "@genesislcap/ts-builder": "15.14.2",
-    "@genesislcap/uvu-playwright-builder": "15.14.2",
-    "@genesislcap/vite-builder": "15.14.2",
-    "@genesislcap/webpack-builder": "15.14.2"
+    "@genesislcap/foundation-testing": "15.15.0",
+    "@genesislcap/genx": "15.15.0",
+    "@genesislcap/rollup-builder": "15.15.0",
+    "@genesislcap/ts-builder": "15.15.0",
+    "@genesislcap/uvu-playwright-builder": "15.15.0",
+    "@genesislcap/vite-builder": "15.15.0",
+    "@genesislcap/webpack-builder": "15.15.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-logger": "15.14.2",
-    "@genesislcap/foundation-utils": "15.14.2",
+    "@genesislcap/foundation-logger": "15.15.0",
+    "@genesislcap/foundation-utils": "15.15.0",
     "@microsoft/fast-foundation": "2.50.0"
   },
   "repository": {
@@ -73,5 +73,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "bd1cb4a789548d9c7c6777f8adb7bce3f43c3317"
+  "gitHead": "6cb5a251c9b3e1bf509fece8db32acdc1d4c747b"
 }