@genesislcap/ai-assistant 15.23.0 → 15.23.1

package/dist/ai-assistant.api.json

@@ -2780,6 +2780,39 @@
               ],
               "name": "getCompactionPlan"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AiDriver#getContextReserve:member(1)",
+              "docComment": "/**\n * Headroom the next turn could need, and which agent set that requirement (GENC-1582). `undefined` when no agent the turn could land on declares a `contextReserve`, which leaves the ambient default in force.\n *\n * The host cannot work this out for itself: it depends on the user pin, the flow-owner lock and the classifier's candidate set, none of which it can see. Reading the ACTIVE agent instead — which is what the gate did first — asks the wrong question, because the agent that last ran is not the agent about to run. Under automatic routing they are routinely different, and the turn that hands over is exactly the one that needs the room.\n *\n * Optional — only drivers that route implement it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getContextReserve?(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ContextReserveResolution",
+                  "canonicalReference": "@genesislcap/ai-assistant!~ContextReserveResolution:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": true,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "releaseTag": "Beta",
+              "overloadIndex": 1,
+              "parameters": [],
+              "name": "getContextReserve"
+            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@genesislcap/ai-assistant!AiDriver#getExternalDiagnostics:member(1)",
@@ -2905,6 +2938,34 @@
               ],
               "name": "getInteractionContext"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AiDriver#getPreambleTokens:member(1)",
+              "docComment": "/**\n * Token cost of the last request's preamble — system prompt, tool definitions and framed tail (GENC-1582). `undefined` before the first call of a turn.\n *\n * A live getter rather than a field stamped on each message, deliberately: every consumer wants the CURRENT preamble, never its history, and a message field would mean a type change in `@genesislcap/foundation-ai` plus churn in every persisted session for a value nobody reads twice.\n *\n * It exists because the preamble cannot be derived reliably. Inferring it as \"first measured prompt minus the messages it covered\" is accurate once and then goes stale, since each agent brings its own prompt and tool surface — and every attempt to compensate downstream ended up comparing stored characters against wire tokens. The driver is the only place that knows what it just sent.\n *\n * Optional — only drivers that build requests implement it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getPreambleTokens?(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": true,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Beta",
+              "overloadIndex": 1,
+              "parameters": [],
+              "name": "getPreambleTokens"
+            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@genesislcap/ai-assistant!AiDriver#getRawHistory:member(1)",
@@ -5113,6 +5174,37 @@
               "isAbstract": false,
               "name": "getInteractionContext"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#getPreambleTokens:member(1)",
+              "docComment": "/**\n * Token cost of the last request's preamble — system prompt, tool definitions and framed tail (GENC-1582). `undefined` before the first call of a turn.\n *\n * A live getter rather than a field stamped on each message, deliberately: every consumer wants the CURRENT preamble, never its history, and a message field would mean a type change in `@genesislcap/foundation-ai` plus churn in every persisted session for a value nobody reads twice.\n *\n * It exists because the preamble cannot be derived reliably. Inferring it as \"first measured prompt minus the messages it covered\" is accurate once and then goes stale, since each agent brings its own prompt and tool surface — and every attempt to compensate downstream ended up comparing stored characters against wire tokens. The driver is the only place that knows what it just sent.\n *\n * Optional — only drivers that build requests implement it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getPreambleTokens(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getPreambleTokens"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#getRawHistory:member(1)",
@@ -6555,10 +6647,82 @@
             "endIndex": 7
           }
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/ai-assistant!ContextReserve:interface",
+          "docComment": "/**\n * Context headroom an agent reserves for itself (GENC-1582).\n *\n * Two figures, because a turn has two costs and only one of them is permanent.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface ContextReserve "
+            }
+          ],
+          "fileUrlPath": "src/config/config.ts",
+          "releaseTag": "Beta",
+          "name": "ContextReserve",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!ContextReserve#tokens:member",
+              "docComment": "/**\n * Tokens that must be free before one of this agent's turns may START — the agent's PEAK growth, not its lasting cost.\n *\n * The peak is the binding figure even for an agent that sheds most of it again: `condenseWhen` stubs a spent payload at the end of the turn, so the room has to be there while the turn is running, before any of that fires.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "tokens: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "tokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!ContextReserve#warnAheadTokens:member",
+              "docComment": "/**\n * Extra tokens ABOVE {@link ContextReserve.tokens} at which the warning appears. Omit to fall back to `chatConfig.context.warnMultiplier`.\n *\n * The figure that belongs here is what one of this agent's turns costs PERMANENTLY — its growth measured after condensation, not at its peak. That makes the warning land exactly two turns before the block: at the warning line there is room for a full turn plus the residue it leaves, which is one turn, and then room for one more.\n *\n * It exists because the multiplier cannot express that. `warnMultiplier` scales the whole reserve, so an agent that peaks at 400k and keeps 30k gets a warning 800k below the window — a line every one of its turns crosses transiently and then clears, which is noise rather than a signal.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "warnAheadTokens?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "warnAheadTokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/ai-assistant!ContextReserveInput:type",
-          "docComment": "/**\n * Context headroom an agent reserves for itself, in tokens.\n *\n * A plain number, unlike the value-or-resolver shape `provider` / `temperature` / `resumable` use. The resolver form was drafted for it and removed before release: the gate is recomputed from a synchronous getter with no turn context to resolve against, so no path could ever have invoked one. Accepting a type-correct option that is guaranteed to do nothing is worse than not offering it — a warning after the fact still leaves the configuration inert.\n *\n * It can widen to a resolver later without breaking a caller, since every existing `number` stays valid.\n *\n * @beta\n */\n",
+          "docComment": "/**\n * Context headroom an agent reserves for itself: a token count, or a {@link ContextReserve} when the agent also wants to say where the warning goes.\n *\n * NOT the value-or-resolver shape `provider` / `temperature` / `resumable` use. The resolver form was drafted and removed before release: the gate is recomputed from a synchronous getter with no turn context to resolve against, so no path could ever have invoked one. Accepting a type-correct option guaranteed to do nothing is worse than not offering it.\n *\n * The object arm was added the way the plain form's docblock anticipated — additively, so every existing `number` stays valid and means what it did.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -6566,7 +6730,12 @@
             },
             {
               "kind": "Content",
-              "text": "number"
+              "text": "number | "
+            },
+            {
+              "kind": "Reference",
+              "text": "ContextReserve",
+              "canonicalReference": "@genesislcap/ai-assistant!ContextReserve:interface"
             },
             {
               "kind": "Content",
@@ -6578,7 +6747,7 @@
           "name": "ContextReserveInput",
           "typeTokenRange": {
             "startIndex": 1,
-            "endIndex": 2
+            "endIndex": 3
           }
         },
         {
@@ -8855,7 +9024,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#contextBudget:member",
-              "docComment": "/**\n * Context-headroom thresholds for the active model (GENC-1567) — the warning and block lines, plus the tail budget compaction aims at.\n *\n * The agent's own `contextReserve` is deliberately NOT folded in here. This is the AMBIENT budget, which protects any turn from any agent; a per-agent reserve is an additional, larger requirement checked when that agent takes ownership of a flow, where there is a turn context to resolve its function form against.\n *\n * Overhead is read off `messages` (the Redux mirror) rather than the driver's own history, which the compaction plan uses. That is safe rather than sloppy: `estimateSystemOverhead` only looks at messages BEFORE the first usage-bearing one, and the two lists agree completely that early — the drift between mirror and driver history is only ever at the tail.\n */\n",
+              "docComment": "/**\n * Context-headroom thresholds for the active model (GENC-1567) — the warning and block lines, plus the tail budget compaction aims at.\n *\n * The per-agent `contextReserve` IS folded in, via the driver (GENC-1582). It used to be described here as a separate, later check made when an agent took ownership of a flow — but there is no such check, and by flow entry the send has already been allowed. Resolving it here, before the send, is what makes it a gate rather than a label.\n *\n * Overhead is read off `messages` (the Redux mirror) rather than the driver's own history, which the compaction plan uses. That is safe rather than sloppy: `estimateSystemOverhead` only looks at messages BEFORE the first usage-bearing one, and the two lists agree completely that early — the drift between mirror and driver history is only ever at the tail.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -8886,7 +9055,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#contextGate:member",
-              "docComment": "/**\n * How close this conversation is to the model's context window (GENC-1567).\n *\n * **Derived, never latched** — the opposite of {@link FoundationAiAssistant.blocked}. A budget wall stays set because nothing the user does fixes it; this clears itself the moment the conversation shrinks, which is precisely what the user is being asked to do. The two must not be conflated: `blocked` is also deliberately preserved across `resetSession`, and a context gate obviously must not survive starting a new chat.\n *\n * **A flow in progress is never blocked, only warned.** Machine state lives outside the transcript, so a stateful flow is not desynced by compaction — but the summary can still drop detail the flow's own prompt leans on, and blocking mid-journey would strand the user between a flow they cannot finish and a compaction that is a poor idea right there. Letting the flow complete and gating on the way out is the lesser harm; the headroom reserve exists so this is rare rather than routine.\n */\n",
+              "docComment": "",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -15622,6 +15791,42 @@
               "isAbstract": false,
               "name": "getCompactionPlan"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#getContextReserve:member(1)",
+              "docComment": "/**\n * Headroom the next turn could need, and which agent set that requirement (GENC-1582). `undefined` when no agent the turn could land on declares a `contextReserve`, which leaves the ambient default in force.\n *\n * The host cannot work this out for itself: it depends on the user pin, the flow-owner lock and the classifier's candidate set, none of which it can see. Reading the ACTIVE agent instead — which is what the gate did first — asks the wrong question, because the agent that last ran is not the agent about to run. Under automatic routing they are routinely different, and the turn that hands over is exactly the one that needs the room.\n *\n * Optional — only drivers that route implement it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getContextReserve(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ContextReserveResolution",
+                  "canonicalReference": "@genesislcap/ai-assistant!~ContextReserveResolution:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getContextReserve"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#getExternalDiagnostics:member(1)",
@@ -15756,6 +15961,37 @@
               "isAbstract": false,
               "name": "getInteractionContext"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#getPreambleTokens:member(1)",
+              "docComment": "/**\n * Token cost of the last request's preamble — system prompt, tool definitions and framed tail (GENC-1582). `undefined` before the first call of a turn.\n *\n * A live getter rather than a field stamped on each message, deliberately: every consumer wants the CURRENT preamble, never its history, and a message field would mean a type change in `@genesislcap/foundation-ai` plus churn in every persisted session for a value nobody reads twice.\n *\n * It exists because the preamble cannot be derived reliably. Inferring it as \"first measured prompt minus the messages it covered\" is accurate once and then goes stale, since each agent brings its own prompt and tool surface — and every attempt to compensate downstream ended up comparing stored characters against wire tokens. The driver is the only place that knows what it just sent.\n *\n * Optional — only drivers that build requests implement it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getPreambleTokens(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getPreambleTokens"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#getRawHistory:member(1)",
@@ -18631,6 +18867,34 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#contextReserve:member",
+              "docComment": "/**\n * Tokens of context headroom to keep free for one of this agent's turns — see `AgentConfig.contextReserve`, which this is passed straight through to.\n *\n * The third member of the flow-safety group with {@link StatefulAgentInit.resumable} and {@link StatefulAgentInit.notResumableMessage}, and the one that was missing (GENC-1582): a stateful flow is the case the reserve was designed for — it is what runs the long tool loop — and yet the helper for building one could not express it. Both agents that needed it in the field are built here.\n *\n * Set it from measurement. Per-turn `inputTokens` is recorded for every call, so one real run of the flow gives you its peak growth; leaving it unset inherits the global default, which is the right starting position.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "contextReserve?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ContextReserveInput",
+                  "canonicalReference": "@genesislcap/ai-assistant!ContextReserveInput:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "contextReserve",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#description:member",