@genesislcap/foundation-ai 15.19.6 → 15.20.0

package/dist/foundation-ai.api.json

@@ -3607,6 +3607,34 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatConfig#context:member",
+              "docComment": "/**\n * Context-window headroom and the compaction gate.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "context?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatContextConfig",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatContextConfig:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "context",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/foundation-ai!ChatConfig#costHistory:member",
@@ -3722,6 +3750,159 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/foundation-ai!ChatContextConfig:interface",
+          "docComment": "/**\n * Context-window management for the chat assistant (GENC-1567).\n *\n * The assistant reserves headroom rather than letting the conversation run to the edge of the model's window and compacting automatically at the last moment. The reason is that a turn is not atomic in cost: a send allowed just under a threshold can run a long tool loop and add a large amount on its own, so a threshold set as a fraction of the window bounds only the size at the START of a turn. What has to be bounded is the growth of one whole turn — and that is a number of tokens, not a percentage.\n *\n * It is also why compaction here is user-initiated rather than automatic: machine state for a stateful flow lives outside the transcript, so rewriting the transcript underneath a mid-flow agent is a judgement the user should make, at a moment of their choosing, rather than something that happens to them mid-journey.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface ChatContextConfig "
+            }
+          ],
+          "fileUrlPath": "src/types/chat.types.ts",
+          "releaseTag": "Beta",
+          "name": "ChatContextConfig",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatContextConfig#enabled:member",
+              "docComment": "/**\n * Whether the context gate is active at all. - `true` or `undefined` (default) — warn, then block, as the window fills - `false` — no warning and no block; the context indicator still shows\n *\n * An escape hatch for a host that would rather take the provider error than ever have its composer disabled.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "enabled?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "enabled",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatContextConfig#fallbackContextLimit:member",
+              "docComment": "/**\n * Context window to assume when the active provider reports none.\n *\n * Without a limit there is no percentage and so no gate, which is the right default — guessing a window and blocking against the guess would be worse than not blocking. Set this when you know the window but your provider does not report it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "fallbackContextLimit?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "fallbackContextLimit",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatContextConfig#minReclaimTokens:member",
+              "docComment": "/**\n * Smallest reclaim, in tokens, for compaction to be worth running and to be offered as the way past a block.\n *\n * A compaction spends a summarizer call on most of the conversation, so a plan that frees less than this costs more than it buys — and, when the composer is blocked, would be an escape that does not actually clear the block. Default: `5000`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "minReclaimTokens?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "minReclaimTokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatContextConfig#reserveTokens:member",
+              "docComment": "/**\n * Tokens kept free for a single turn to complete in. The assistant blocks new sends once the conversation would leave less than this much headroom.\n *\n * Deliberately a token count and not a percentage of the window: the reserve needs to cover the worst-case growth of one agentic turn, which does not scale with the model's context size. A percentage gives a 1M-token model a reserve far larger than any turn needs while potentially starving a 200k-token one. Default: `25000`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "reserveTokens?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "reserveTokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatContextConfig#warnMultiplier:member",
+              "docComment": "/**\n * How many reserves ahead of the block the warning appears, as a multiple of {@link ChatContextConfig.reserveTokens}. At the default `2` the warning arrives one full reserve before the block, leaving room to compact at a convenient moment rather than at the wall. Default: `2`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "warnMultiplier?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "warnMultiplier",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/foundation-ai!ChatCostHistoryConfig:interface",
@@ -7325,6 +7506,320 @@
             "endIndex": 2
           }
         },
+        {
+          "kind": "Class",
+          "canonicalReference": "@genesislcap/foundation-ai!ContextOverflowError:class",
+          "docComment": "/**\n * Thrown when the provider rejects a request because the prompt exceeds the model's context window.\n *\n * Terminal for the attempt in the same sense as its siblings — retrying the same request cannot clear it — but unlike them it is terminal only until the user acts. Compaction genuinely resolves it, which is why the copy says so.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare class ContextOverflowError extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "Error",
+              "canonicalReference": "!Error:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "src/transports/context-overflow-error.ts",
+          "releaseTag": "Beta",
+          "isAbstract": false,
+          "name": "ContextOverflowError",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Constructor",
+              "canonicalReference": "@genesislcap/foundation-ai!ContextOverflowError:constructor(1)",
+              "docComment": "/**\n * Constructs a new instance of the `ContextOverflowError` class\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "constructor(\n    vendorLabel: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    promptTokens?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    limitTokens?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    detail?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "vendorLabel",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "promptTokens",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": true
+                },
+                {
+                  "parameterName": "limitTokens",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 5,
+                    "endIndex": 6
+                  },
+                  "isOptional": true
+                },
+                {
+                  "parameterName": "detail",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 7,
+                    "endIndex": 8
+                  },
+                  "isOptional": true
+                }
+              ]
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ContextOverflowError#detail:member",
+              "docComment": "/**\n * The provider's human-readable message, verbatim, for the log. Never shown to the user.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly detail?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "detail",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ContextOverflowError#limitTokens:member",
+              "docComment": "/**\n * Window size the provider reported, when its message stated one.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly limitTokens?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "limitTokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ContextOverflowError#promptTokens:member",
+              "docComment": "/**\n * Prompt size the provider reported, when its message stated one.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly promptTokens?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "promptTokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ContextOverflowError#vendorLabel:member",
+              "docComment": "/**\n * Vendor label of the transport that refused (e.g. `'Anthropic'`).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly vendorLabel: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "vendorLabel",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            }
+          ],
+          "extendsTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "implementsTokenRanges": []
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-ai!contextOverflowOf:function(1)",
+          "docComment": "/**\n * Classify a rejection as a context overflow, returning the reported figures when the provider stated them, or `undefined` when it is something else.\n *\n * Vendor-agnostic, unlike `providerRefusalOf`: the failure is a property of the request rather than of a vendor's account model, both observed shapes are a `400` with a phrase, and — critically — a false positive here cannot break a retry ladder, so the caution that scopes the spend classifier to Anthropic does not apply.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function contextOverflowOf(_vendor: "
+            },
+            {
+              "kind": "Reference",
+              "text": "AIProviderType",
+              "canonicalReference": "@genesislcap/foundation-ai!AIProviderType:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | undefined"
+            },
+            {
+              "kind": "Content",
+              "text": ", status: "
+            },
+            {
+              "kind": "Content",
+              "text": "number | undefined"
+            },
+            {
+              "kind": "Content",
+              "text": ", payload: "
+            },
+            {
+              "kind": "Content",
+              "text": "unknown"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    promptTokens?: number;\n    limitTokens?: number;\n    message?: string;\n} | undefined"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/transports/context-overflow-error.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 8,
+            "endIndex": 9
+          },
+          "releaseTag": "Beta",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "_vendor",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "status",
+              "parameterTypeTokenRange": {
+                "startIndex": 4,
+                "endIndex": 5
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "payload",
+              "parameterTypeTokenRange": {
+                "startIndex": 6,
+                "endIndex": 7
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "contextOverflowOf"
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/foundation-ai!CostReportingTransport:interface",
@@ -7808,6 +8303,29 @@
             "endIndex": 0
           }
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-ai!DEFAULT_CONTEXT_OVERFLOW_MESSAGE:var",
+          "docComment": "/**\n * The single sentence shown to a user whose request overran the context window.\n *\n * Unlike {@link DEFAULT_PROVIDER_REFUSED_MESSAGE} this one deliberately DOES name a cause and an action, because both are true and both are the user's: they can see the conversation that caused it, and compacting fixes it. Telling them it \"needs no action from you\" would be the wrong advice as well as the wrong fact.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "DEFAULT_CONTEXT_OVERFLOW_MESSAGE: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            }
+          ],
+          "fileUrlPath": "src/transports/context-overflow-error.ts",
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "DEFAULT_CONTEXT_OVERFLOW_MESSAGE",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/foundation-ai!DEFAULT_PROVIDER_REFUSED_MESSAGE:var",
@@ -11615,7 +12133,7 @@
             },
             {
               "kind": "Content",
-              "text": "'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal' | 'budget_exhausted'\n/**\n * The upstream vendor refused the account (GENC-1506). **Terminal for the PARENT turn too**, on the\n * same reasoning as `budget_exhausted`: the parent cannot recover by calling the model again,\n * because the very next call hits the same wall. N batched sub-agent calls would otherwise cost N\n * doomed children AND a doomed parent call.\n */\n | 'provider_refused'"
+              "text": "'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal' | 'budget_exhausted'\n/**\n * The upstream vendor refused the account (GENC-1506). **Terminal for the PARENT turn too**, on the\n * same reasoning as `budget_exhausted`: the parent cannot recover by calling the model again,\n * because the very next call hits the same wall. N batched sub-agent calls would otherwise cost N\n * doomed children AND a doomed parent call.\n */\n | 'provider_refused'\n/**\n * The sub-agent was stopped because continuing would have overrun the context\n * window (GENC-1567). **Terminal for the PARENT turn too**, on the same\n * reasoning as `budget_exhausted` and `provider_refused`: the parent shares the\n * conversation whose size caused it, so calling the model again hits the same\n * wall.\n */\n | 'context_exhausted'"
             },
             {
               "kind": "Content",
@@ -12162,7 +12680,7 @@
             },
             {
               "kind": "Content",
-              "text": "'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted' | 'provider-refused'"
+              "text": "'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted' | 'provider-refused'\n/**\n * The turn was stopped because continuing it would have overrun the model's\n * context window (GENC-1567). Pre-emptive: the driver ends the tool loop at\n * the edge rather than issuing a request the provider would reject, so the\n * transcript stays intact and compaction is still possible.\n */\n | 'context-exhausted'"
             },
             {
               "kind": "Content",