@genesislcap/foundation-ai 14.469.0 → 14.470.0

package/dist/foundation-ai.api.json

@@ -2080,10 +2080,41 @@
               "isAbstract": false,
               "name": "getLifetimeCost"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/foundation-ai!AnthropicTransport#getLifetimeSavings:member(1)",
+              "docComment": "/**\n * Estimated USD saved by prompt caching (net of write premiums) across this instance.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getLifetimeSavings(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getLifetimeSavings"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/foundation-ai!AnthropicTransport#resetLifetimeCost:member(1)",
-              "docComment": "/**\n * Reset the lifetime cost counter. Intended for chat-clear / new-session flows.\n */\n",
+              "docComment": "/**\n * Reset the lifetime cost + savings counters. Intended for chat-clear / new-session flows.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -2281,6 +2312,32 @@
             }
           ]
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-ai!CachePolicy:type",
+          "docComment": "/**\n * Prompt-cache policy for a chat request, resolved per turn. **Provider-neutral intent, provider-specific effect** — read this carefully, the two providers differ sharply:\n *\n * - **Anthropic** — `scope` controls where explicit `cache_control` breakpoints are placed (see each variant). This is the *only* way Anthropic caches; no scope → no caching. - **Gemini** — `scope` is effectively a **no-op**. Gemini 2.5+ does *implicit* caching automatically and always-on, caching as much of the stable prefix as it can (everything up to the volatile tail) on every request — regardless of `scope`, **including under `'default'`**. We issue no explicit `cachedContent`, so nothing here changes the Gemini request. Do NOT expect `'tools'`/`'prompt'` to *limit* Gemini caching, nor `'default'` to *disable* it; the most you control on Gemini is keeping the prefix byte-stable so implicit caching can engage.\n *\n * Omit, or use `{ scope: 'default' }`, to add no breakpoints of our own.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type CachePolicy = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    scope: 'default';\n} | {\n    scope: 'tools' | 'prompt' | 'history';\n    ttl?: '5m' | '1h';\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/types/chat.types.ts",
+          "releaseTag": "Beta",
+          "name": "CachePolicy",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/foundation-ai!ChatAgentConfig:interface",
@@ -3611,6 +3668,34 @@
                 "endIndex": 3
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatRequestOptions#cachePolicy:member",
+              "docComment": "/**\n * Prompt-cache policy for this turn. See {@link CachePolicy} — Anthropic places explicit `cache_control` breakpoints per `scope`; Gemini caches implicitly regardless. Omit to add no breakpoints of our own.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "cachePolicy?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "CachePolicy",
+                  "canonicalReference": "@genesislcap/foundation-ai!CachePolicy:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "cachePolicy",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/foundation-ai!ChatRequestOptions#signal:member",
@@ -3666,6 +3751,33 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatRequestOptions#tailContext:member",
+              "docComment": "/**\n * Operator/volatile context to inject at the **very tail** of the outbound messages — after the stored history *and* after any cache breakpoint — so the model sees it every turn without invalidating the cached prefix. **Never persisted to stored history**; it is re-supplied per request. Anthropic appends it as a text block on the final user turn; Gemini as a trailing `user` content. The caller is responsible for any framing (e.g. a `<system-reminder>` / `<current_context>` marker) so the model reads it as ambient context, not user input.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "tailContext?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "tailContext",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/foundation-ai!ChatRequestOptions#temperature:member",
@@ -4344,7 +4456,7 @@
             },
             {
               "kind": "Content",
-              "text": ";\n    }>;\n    completeSubAgent?: (result: unknown) => void;\n    releaseAgent?: () => void;\n    condenseWhen: (policy: "
+              "text": ";\n    }>;\n    completeSubAgent?: (result: unknown) => void;\n    releaseAgent?: () => void;\n    endPhase?: () => void;\n    condenseWhen: (policy: "
             },
             {
               "kind": "Reference",
@@ -5354,7 +5466,7 @@
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-ai!CondenseTrigger:type",
-          "docComment": "/**\n * When a tool call's declared payload(s) become stale and should be condensed out of the to-model history. The kinds form a spectrum of widening staleness horizons — call, model-call, request, and agent-flow.\n *\n * - `superseded` — keep only the LATEST call sharing `by` in the history sent to the model; collapse the targeted payload of all earlier ones. The natural key is the resource identity (e.g. a file path), so reads and writes of the same path share a `by` and an earlier read collapses once a later write/read of the same path lands. A re-call with the same `by` re-arms automatically. - `age` — a tool result first reaches the model on the model-call AFTER the call, so `turns` is how many model-calls may see the full result before it collapses: `turns: 1` lets the model read it on exactly one model-call, then collapses it; `turns: 2` keeps it for two; and so on. Use `turns >= 1`. The clock is monotonic across user turns (a sub-agent invocation counts as one call in the parent loop). For keyless payloads (grep / source / doc dumps). - `turnEnd` — collapse once the user turn (`sendMessage`) that made the call has ended: the payload stays full for the rest of that request, then collapses on every later one. \"Relevant only to the request that fetched it.\" This is the right choice for a non-pinned agent (one that answers and hands straight back to the user); reach for it whenever the payload is per-request. - `agentEnd` — collapse once the agent's *continuous activation* ends. An activation spans every turn the agent stays in control — a pinned stateful flow is one activation across all its turns (mid-flow `requestInteraction` round-trips and turn boundaries do NOT end it) — and it ends only when the agent hands off to a different agent or releases its pin (`releaseAgent` / `completeSubAgent`). The right choice for a multi-turn stateful flow whose payload is needed throughout but dead afterwards (where `turnEnd` would be too eager). NOTE: for a non-pinned agent, \"the agent\" is only considered to have ended when routing actually moves to a *different* agent — if the classifier re-selects the same agent on the next turn it is treated as the same activation, so use `turnEnd` (not `agentEnd`) when you want per-request collapse on a non-stateful agent.\n *\n * @beta\n */\n",
+          "docComment": "/**\n * When a tool call's declared payload(s) become stale and should be condensed out of the to-model history. The kinds form a spectrum of widening staleness horizons — call, model-call, request, and agent-flow.\n *\n * - `superseded` — keep only the LATEST call sharing `by` in the history sent to the model; collapse the targeted payload of all earlier ones. The natural key is the resource identity (e.g. a file path), so reads and writes of the same path share a `by` and an earlier read collapses once a later write/read of the same path lands. A re-call with the same `by` re-arms automatically. - `age` — a tool result first reaches the model on the model-call AFTER the call, so `turns` is how many model-calls may see the full result before it collapses: `turns: 1` lets the model read it on exactly one model-call, then collapses it; `turns: 2` keeps it for two; and so on. Use `turns >= 1`. The clock is monotonic across user turns (a sub-agent invocation counts as one call in the parent loop). For keyless payloads (grep / source / doc dumps). - `turnEnd` — collapse once the user turn (`sendMessage`) that made the call has ended: the payload stays full for the rest of that request, then collapses on every later one. \"Relevant only to the request that fetched it.\" This is the right choice for a non-pinned agent (one that answers and hands straight back to the user); reach for it whenever the payload is per-request. - `agentEnd` — collapse once the agent's *continuous activation* ends. An activation spans every turn the agent stays in control — a pinned stateful flow is one activation across all its turns (mid-flow `requestInteraction` round-trips and turn boundaries do NOT end it) — and it ends only when the agent hands off to a different agent or releases its pin (`releaseAgent` / `completeSubAgent`). The right choice for a multi-turn stateful flow whose payload is needed throughout but dead afterwards (where `turnEnd` would be too eager). NOTE: for a non-pinned agent, \"the agent\" is only considered to have ended when routing actually moves to a *different* agent — if the classifier re-selects the same agent on the next turn it is treated as the same activation, so use `turnEnd` (not `agentEnd`) when you want per-request collapse on a non-stateful agent. - `phaseEnd` — collapse once the agent declares the current *phase* finished by calling `endPhase()` from a tool handler. A phase is an app-defined span *within* one activation — narrower than `agentEnd` (which only fires at whole- agent disposal) and phase-aware in a way `age:N` is not. The intended use is a long, multi-phase stateful flow (e.g. a bootstrap journey) that wants to trim each phase's grounding reads as it moves on, without waiting for the whole agent to end. It is NOT tied to any state-machine library: the author fires `endPhase()` from whichever tool handlers advance their own notion of state, exactly as `condenseWhen` is itself called from tool handlers. If `endPhase()` is never called, the payload still collapses at `agentEnd` — so `phaseEnd` degrades to `agentEnd` rather than never firing.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -5362,7 +5474,7 @@
             },
             {
               "kind": "Content",
-              "text": "{\n    kind: 'superseded';\n    by: string;\n} | {\n    kind: 'age';\n    turns: number;\n} | {\n    kind: 'turnEnd';\n} | {\n    kind: 'agentEnd';\n}"
+              "text": "{\n    kind: 'superseded';\n    by: string;\n} | {\n    kind: 'age';\n    turns: number;\n} | {\n    kind: 'turnEnd';\n} | {\n    kind: 'agentEnd';\n} | {\n    kind: 'phaseEnd';\n}"
             },
             {
               "kind": "Content",
@@ -5420,10 +5532,38 @@
               "parameters": [],
               "name": "getLifetimeCost"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/foundation-ai!CostReportingTransport#getLifetimeSavings:member(1)",
+              "docComment": "/**\n * Estimated USD saved by prompt caching vs paying full input price, accumulated across this instance. Net of cache-write premiums, so it can be briefly negative before reads accrue.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getLifetimeSavings(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Beta",
+              "overloadIndex": 1,
+              "parameters": [],
+              "name": "getLifetimeSavings"
+            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@genesislcap/foundation-ai!CostReportingTransport#resetLifetimeCost:member(1)",
-              "docComment": "/**\n * Reset the lifetime cost counter. Intended for chat-clear / new-session flows.\n */\n",
+              "docComment": "/**\n * Reset the lifetime cost + savings counters. Intended for chat-clear / new-session flows.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -6622,10 +6762,41 @@
               "isAbstract": false,
               "name": "getLifetimeCost"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/foundation-ai!GeminiTransport#getLifetimeSavings:member(1)",
+              "docComment": "/**\n * Estimated USD saved by context caching across this instance (implicit caching → always ≥ 0).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getLifetimeSavings(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getLifetimeSavings"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/foundation-ai!GeminiTransport#resetLifetimeCost:member(1)",
-              "docComment": "/**\n * Reset the lifetime cost counter. Intended for chat-clear / new-session flows.\n */\n",
+              "docComment": "/**\n * Reset the lifetime cost + savings counters. Intended for chat-clear / new-session flows.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -8299,6 +8470,238 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Class",
+          "canonicalReference": "@genesislcap/foundation-ai!ResponseTruncatedError:class",
+          "docComment": "/**\n * Thrown when a response stops at `stop_reason: 'max_tokens'` while it still carries tool calls. The model ran out of its output-token budget mid-stream, so the truncated tool call's argument JSON was cut off before it closed — the arguments are incomplete and the call is unusable (e.g. a `vfs_write` whose `content` never finished serializing). Rather than hand a corrupt tool call to the caller — which silently runs with missing args and tends to be retried into an identical wall — the transport raises this so the failure is loud and diagnosable.\n *\n * It is deterministic: re-issuing the same request hits the same cap. The remedy is to raise the provider's `maxTokens` (see {@link AnthropicAIConfig.maxTokens}) or to split the work into smaller outputs — not to retry verbatim.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare class ResponseTruncatedError extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "Error",
+              "canonicalReference": "!Error:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "src/transports/anthropic-transport.ts",
+          "releaseTag": "Beta",
+          "isAbstract": false,
+          "name": "ResponseTruncatedError",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Constructor",
+              "canonicalReference": "@genesislcap/foundation-ai!ResponseTruncatedError:constructor(1)",
+              "docComment": "/**\n * Constructs a new instance of the `ResponseTruncatedError` class\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "constructor(\n    model: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    maxTokens: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    outputTokens: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    toolNames: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string[]"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "model",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "maxTokens",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "outputTokens",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 5,
+                    "endIndex": 6
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "toolNames",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 7,
+                    "endIndex": 8
+                  },
+                  "isOptional": false
+                }
+              ]
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ResponseTruncatedError#maxTokens:member",
+              "docComment": "/**\n * The `max_tokens` cap the request was sent with.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly maxTokens: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "maxTokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ResponseTruncatedError#model:member",
+              "docComment": "/**\n * The model that produced the truncated response.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly model: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "model",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ResponseTruncatedError#outputTokens:member",
+              "docComment": "/**\n * Output tokens generated before truncation, when the usage block is present.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly outputTokens: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "outputTokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ResponseTruncatedError#toolNames:member",
+              "docComment": "/**\n * Names of the tool call(s) on the truncated turn (the last is the cut-off one).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly toolNames: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string[]"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "toolNames",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            }
+          ],
+          "extendsTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "implementsTokenRanges": []
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/foundation-ai!ServerAIConfig:interface",
@@ -8425,7 +8828,7 @@
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-ai!SubAgentFailureReason:type",
-          "docComment": "/**\n * Why a sub-agent run ended without producing a structured result via `completeSubAgent`. Surfaced on the `{ ok: false }` branch of `requestSubAgent` so the parent tool handler can decide how to recover.\n *\n * - `max_iterations` — the sub-agent's tool loop ended without calling its completion tool (hit the iteration cap, or — defensively — a provider ignored forced tool use and returned a free-text turn). - `malformed_tool_call` — the provider repeatedly returned an unparseable tool call (e.g. Gemini `MALFORMED_FUNCTION_CALL`) after retries. - `empty_response` — the model repeatedly returned an empty response after retries. - `unknown_tool_limit` — the model repeatedly called tools that aren't available to it. - `timeout` — the sub-agent did not finish within {@link SubAgentRequestOptions.timeoutMs}; its run was aborted.\n *\n * @beta\n */\n",
+          "docComment": "/**\n * Why a sub-agent run ended without producing a structured result via `completeSubAgent`. Surfaced on the `{ ok: false }` branch of `requestSubAgent` so the parent tool handler can decide how to recover.\n *\n * - `max_iterations` — the sub-agent's tool loop ended without calling its completion tool (hit the iteration cap, or — defensively — a provider ignored forced tool use and returned a free-text turn). - `malformed_tool_call` — the provider repeatedly returned an unparseable tool call (e.g. Gemini `MALFORMED_FUNCTION_CALL`) after retries. - `empty_response` — the model repeatedly returned an empty response after retries. - `unknown_tool_limit` — the model repeatedly called tools that aren't available to it. - `timeout` — the sub-agent did not finish within {@link SubAgentRequestOptions.timeoutMs}; its run was aborted. - `response_truncated` — a turn stopped at the provider's output-token cap with an incomplete tool call; deterministic, so it is not retried.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -8433,7 +8836,7 @@
             },
             {
               "kind": "Content",
-              "text": "'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout'"
+              "text": "'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated'"
             },
             {
               "kind": "Content",