@genesislcap/foundation-ai 15.14.2 → 15.15.0

package/dist/foundation-ai.api.json

@@ -3529,103 +3529,40 @@
           "extendsTokenRanges": []
         },
         {
-          "kind": "Interface",
-          "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:interface",
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:type",
           "docComment": "/**\n * A file attachment included with a user message.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
-              "text": "export interface ChatAttachment "
-            }
-          ],
-          "fileUrlPath": "src/types/chat.types.ts",
-          "releaseTag": "Beta",
-          "name": "ChatAttachment",
-          "preserveMemberOrder": false,
-          "members": [
+              "text": "export type ChatAttachment = "
+            },
             {
-              "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment#content:member",
-              "docComment": "",
-              "excerptTokens": [
-                {
-                  "kind": "Content",
-                  "text": "content: "
-                },
-                {
-                  "kind": "Content",
-                  "text": "string"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";"
-                }
-              ],
-              "isReadonly": false,
-              "isOptional": false,
-              "releaseTag": "Beta",
-              "name": "content",
-              "propertyTypeTokenRange": {
-                "startIndex": 1,
-                "endIndex": 2
-              }
+              "kind": "Reference",
+              "text": "ChatTextAttachment",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatTextAttachment:interface"
             },
             {
-              "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment#mimeType:member",
-              "docComment": "",
-              "excerptTokens": [
-                {
-                  "kind": "Content",
-                  "text": "mimeType: "
-                },
-                {
-                  "kind": "Content",
-                  "text": "string"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";"
-                }
-              ],
-              "isReadonly": false,
-              "isOptional": false,
-              "releaseTag": "Beta",
-              "name": "mimeType",
-              "propertyTypeTokenRange": {
-                "startIndex": 1,
-                "endIndex": 2
-              }
+              "kind": "Content",
+              "text": " | "
             },
             {
-              "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment#name:member",
-              "docComment": "",
-              "excerptTokens": [
-                {
-                  "kind": "Content",
-                  "text": "name: "
-                },
-                {
-                  "kind": "Content",
-                  "text": "string"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";"
-                }
-              ],
-              "isReadonly": false,
-              "isOptional": false,
-              "releaseTag": "Beta",
-              "name": "name",
-              "propertyTypeTokenRange": {
-                "startIndex": 1,
-                "endIndex": 2
-              }
+              "kind": "Reference",
+              "text": "ChatImageAttachment",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatImageAttachment:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
             }
           ],
-          "extendsTokenRanges": []
+          "fileUrlPath": "src/types/chat.types.ts",
+          "releaseTag": "Beta",
+          "name": "ChatAttachment",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 4
+          }
         },
         {
           "kind": "Interface",
@@ -4108,6 +4045,159 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/foundation-ai!ChatImageAttachment:interface",
+          "docComment": "/**\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface ChatImageAttachment "
+            }
+          ],
+          "fileUrlPath": "src/types/chat.types.ts",
+          "releaseTag": "Beta",
+          "name": "ChatImageAttachment",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatImageAttachment#data:member",
+              "docComment": "/**\n * 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`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "data: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "data",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatImageAttachment#detail:member",
+              "docComment": "/**\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "detail?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "'low' | 'medium' | 'high'"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "detail",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatImageAttachment#kind:member",
+              "docComment": "/**\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "kind: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "'image'"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "kind",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatImageAttachment#mimeType:member",
+              "docComment": "/**\n * One of the four both vendors accept: `image/png`, `image/jpeg`, `image/gif`, `image/webp`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "mimeType: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "mimeType",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatImageAttachment#name:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "name: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "name",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-ai!ChatInputDuringExecutionMode:type",
@@ -4374,7 +4464,7 @@
                 {
                   "kind": "Reference",
                   "text": "ChatAttachment",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:interface"
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:type"
                 },
                 {
                   "kind": "Content",
@@ -4975,7 +5065,7 @@
                 {
                   "kind": "Reference",
                   "text": "ChatAttachment",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:interface"
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:type"
                 },
                 {
                   "kind": "Content",
@@ -5055,6 +5145,33 @@
                 "endIndex": 3
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatRequestOptions#maxTokens:member",
+              "docComment": "/**\n * Output-token ceiling for THIS turn, overriding the transport's configured `maxTokens`.\n *\n * 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).\n *\n * 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.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "maxTokens?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "maxTokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/foundation-ai!ChatRequestOptions#responseSchema:member",
@@ -5587,10 +5704,176 @@
             "endIndex": 2
           }
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/foundation-ai!ChatTextAttachment:interface",
+          "docComment": "/**\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface ChatTextAttachment "
+            }
+          ],
+          "fileUrlPath": "src/types/chat.types.ts",
+          "releaseTag": "Beta",
+          "name": "ChatTextAttachment",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatTextAttachment#content:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "content: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "content",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatTextAttachment#kind:member",
+              "docComment": "/**\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "kind?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "'text'"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "kind",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatTextAttachment#mimeType:member",
+              "docComment": "/**\n * 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}.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "mimeType: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "mimeType",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatTextAttachment#name:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "name: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "name",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-ai!ChatThinkingLevel:type",
+          "docComment": "/**\n * 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\".\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ChatThinkingLevel = "
+            },
+            {
+              "kind": "Reference",
+              "text": "Extract",
+              "canonicalReference": "!Extract:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "ChatThinkingPolicy",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatThinkingPolicy:type"
+            },
+            {
+              "kind": "Content",
+              "text": ", 'minimal' | 'low' | 'medium' | 'high' | 'max'>"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/types/chat.types.ts",
+          "releaseTag": "Public",
+          "name": "ChatThinkingLevel",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-ai!ChatThinkingPolicy:type",
-          "docComment": "/**\n * Whether the model should reason before answering, resolved per turn. **Provider-neutral intent, provider-specific effect**, and — like `tool_choice` — a *request*, not a guarantee: a model that cannot honour it keeps its default.\n *\n * - `'auto'` — the model decides how much to think (Anthropic `thinking: {type:'adaptive'}`, Gemini `thinkingConfig.thinkingBudget: -1`). On a model whose default is thinking-*off* this turns it **on**, which is the point: it is the opt-in for models where adaptive thinking is available but not default. - `'off'` — no reasoning tokens (Anthropic `thinking: {type:'disabled'}`, Gemini `thinkingBudget: 0`). The lever for turns that only step a known sequence, where reasoning is billed as output at the full candidate rate to decide something already determined.\n *\n * **Choose it per turn, not per model call.** A tool-use loop is one assistant turn, and Anthropic requires a single thinking mode for its duration; toggling part-way through does not error but silently disables thinking for that request, strips blocks that would leave the turn structure invalid, and invalidates the prompt cache. The driver pins whatever it resolves on a turn's first model call for the rest of that turn.\n *\n * 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.\n *\n * **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 returning `undefined` on some turns leaves those turns exactly as they were before this option existed, rather than silently re-pricing them.\n *\n * Not every model can honour every value, and the two providers hit the same wall at the top of their ranges: Anthropic Fable 5 and Gemini 2.5 Pro both think unconditionally and reject (or ignore) a request to stop. Transports **clamp** rather than forward a request that would 400 — the turn runs at the model's default and a one-time warning is logged. Never assume `'off'` means zero reasoning tokens were billed; read the usage back.\n *\n * @beta\n */\n",
+          "docComment": "/**\n * Whether the model should reason before answering, resolved per turn. **Provider-neutral intent, provider-specific effect**, and — like `tool_choice` — a *request*, not a guarantee: a model that cannot honour it keeps its default.\n *\n * - `'auto'` — the model decides how much to think (Anthropic `thinking: {type:'adaptive'}`, Gemini `thinkingConfig.thinkingBudget: -1`). On a model whose default is thinking-*off* this turns it **on**, which is the point: it is the opt-in for models where adaptive thinking is available but not default. - `'off'` — no reasoning tokens (Anthropic `thinking: {type:'disabled'}`, Gemini `thinkingBudget: 0`). The lever for turns that only step a known sequence, where reasoning is billed as output at the full candidate rate to decide something already determined.\n *\n * **Choose it per turn, not per model call.** A tool-use loop is one assistant turn, and Anthropic requires a single thinking mode for its duration; toggling part-way through does not error but silently disables thinking for that request, strips blocks that would leave the turn structure invalid, and invalidates the prompt cache. The driver pins whatever it resolves on a turn's first model call for the rest of that turn.\n *\n * 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. The graded levels below are that idea done vendor-neutrally: Anthropic `output_config.effort` and Gemini `thinkingConfig.thinkingLevel` line up, as anticipated here.\n *\n * **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:\n *\n * - 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.\n *\n * 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.\n *\n * **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 returning `undefined` on some turns leaves those turns exactly as they were before this option existed, rather than silently re-pricing them.\n *\n * Not every model can honour every value, and the two providers hit the same wall at the top of their ranges: Anthropic Fable 5 and Gemini 2.5 Pro both think unconditionally and reject (or ignore) a request to stop. Transports **clamp** rather than forward a request that would 400 — the turn runs at the model's default and a one-time warning is logged. Never assume `'off'` means zero reasoning tokens were billed; read the usage back.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -5598,7 +5881,7 @@
             },
             {
               "kind": "Content",
-              "text": "'auto' | 'off'"
+              "text": "'auto' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'"
             },
             {
               "kind": "Content",
@@ -5984,6 +6267,38 @@
           "name": "ChatToolResult",
           "preserveMemberOrder": false,
           "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatToolResult#attachments:member",
+              "docComment": "/**\n * Images the tool produced, sent alongside `content` as real image blocks.\n *\n * 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.\n *\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "attachments?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatImageAttachment",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatImageAttachment:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "[]"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "attachments",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/foundation-ai!ChatToolResult#content:member",