@genesislcap/ai-assistant 15.22.0 → 15.22.1-GENC-1582.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)",
@@ -6555,10 +6588,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 +6671,12 @@
             },
             {
               "kind": "Content",
-              "text": "number"
+              "text": "number | "
+            },
+            {
+              "kind": "Reference",
+              "text": "ContextReserve",
+              "canonicalReference": "@genesislcap/ai-assistant!ContextReserve:interface"
             },
             {
               "kind": "Content",
@@ -6578,7 +6688,7 @@
           "name": "ContextReserveInput",
           "typeTokenRange": {
             "startIndex": 1,
-            "endIndex": 2
+            "endIndex": 3
           }
         },
         {
@@ -8855,7 +8965,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",
@@ -15622,6 +15732,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)",
@@ -18631,6 +18777,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",

package/dist/ai-assistant.d.ts

@@ -645,6 +645,21 @@ export declare interface AiDriver extends EventTarget {
      * retain the active config implement it.
      */
     getActiveAgent?(): AgentConfig | undefined;
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * Optional — only drivers that route implement it.
+     */
+    getContextReserve?(): ContextReserveResolution | undefined;
     /**
      * Set the mid-loop context guard (GENC-1567). `undefined` disables it.
      *
@@ -1175,13 +1190,15 @@ declare interface BaseAgentConfig {
      * room it needs so that it does not have to be. An agent whose flow runs a long
      * tool loop, or returns large payloads, needs more than the global default.
      *
-     * **When it takes effect.** The reserve is read from the agent that is already
-     * ACTIVE, so it governs the gate from that agent's next send onwards — one turn
-     * later than a true pre-flight. It is deliberately not enforced at flow entry:
-     * `flow-owner-changed` fires while the driver is already routing the turn, so
-     * gating there would mean aborting a turn in flight. An agent that activates
-     * mid-turn therefore gets its first turn under the global reserve; the mid-loop
-     * context guard is what stops that turn running away.
+     * **When it takes effect.** Before the send, as a real pre-flight (GENC-1582).
+     * The driver resolves it against how routing is currently constrained — the
+     * pinned or flow-owning agent when there is one, otherwise the largest reserve
+     * among the agents the classifier could route to — so a turn is refused before
+     * it can start rather than after. This used to read the agent that was already
+     * ACTIVE, which is a different agent from the one about to run whenever the
+     * orchestrator is doing its job, and the handover turn is exactly the one that
+     * needs the room. The mid-loop context guard remains the backstop for a turn
+     * that outgrows what it reserved.
      *
      * **Set this from measurement, not from a guess.** Per-turn `inputTokens` is
      * recorded for every call, so a single real run of the flow tells you its peak
@@ -2310,21 +2327,87 @@ export declare interface ContextGuardPolicy {
 }
 
 /**
- * Context headroom an agent reserves for itself, in tokens.
+ * Context headroom an agent reserves for itself (GENC-1582).
  *
- * 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.
+ * Two figures, because a turn has two costs and only one of them is permanent.
  *
- * It can widen to a resolver later without breaking a caller, since every
- * existing `number` stays valid.
+ * @beta
+ */
+export declare interface ContextReserve {
+    /**
+     * Tokens that must be free before one of this agent's turns may START — the
+     * agent's PEAK growth, not its lasting cost.
+     *
+     * 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.
+     */
+    tokens: number;
+    /**
+     * Extra tokens ABOVE {@link ContextReserve.tokens} at which the warning
+     * appears. Omit to fall back to `chatConfig.context.warnMultiplier`.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    warnAheadTokens?: number;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
  *
  * @beta
  */
-export declare type ContextReserveInput = number;
+export declare type ContextReserveInput = number | ContextReserve;
+
+/**
+ * How much context headroom the next turn needs, and where that figure came from
+ * (GENC-1582).
+ *
+ * @internal
+ */
+declare interface ContextReserveResolution {
+    /** Tokens to keep free for one turn — the winning agent's peak growth. */
+    tokens: number;
+    /**
+     * Extra tokens above {@link ContextReserveResolution.tokens} at which the
+     * warning appears, when the winning agent declared one. Travels WITH the winner
+     * rather than being resolved separately: the two figures describe the same
+     * agent's turn, and pairing a lean agent's warning with a hungry agent's block
+     * would put the warning on the wrong side of it.
+     */
+    warnAheadTokens?: number;
+    /** The agent whose `contextReserve` this is. */
+    agentName: string;
+    /**
+     * Why this agent's reserve governs — which is what lets a blocked composer say
+     * something TRUE about an agent the user has not invoked yet.
+     *
+     * `locked`: a user pin or a flow-owner lock means the next turn can only go to
+     * this agent, so its reserve is the whole requirement. `reachable-max`: routing
+     * is automatic, so the turn could land on any agent the classifier can pick, and
+     * the hungriest of them is the one that has to fit.
+     */
+    basis: 'locked' | 'reachable-max';
+}
 
 /** A model used during a recorded cost session. */
 export declare interface CostSessionModelEntry {
@@ -2734,6 +2817,37 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * redux actions re-renders without this; a store *swap* needs it.)
      */
     private _sessionRef?;
+    /**
+     * {@link FoundationAiAssistant.contextTokens} as of the last moment no turn was
+     * running — the figure {@link FoundationAiAssistant.contextGate} is judged
+     * against (GENC-1582).
+     *
+     * **Why the gate reads a held figure and the gauge does not.** They answer
+     * different questions. The gauge is a meter: "how much context is in play right
+     * now", and a build that momentarily fills 900k of a 1M window should say so.
+     * The gate answers "may the next turn START", which is only meaningful when no
+     * turn is running — the composer is disabled by `busy` throughout one anyway, so
+     * a warning raised mid-turn is unactionable by construction.
+     *
+     * Reading the live figure meant the pill went amber part-way through every large
+     * build and cleared itself at the end, because a `condenseWhen` agent's context
+     * peaks mid-turn and is shed before the turn finishes. A signal that fires and
+     * withdraws on its own each time teaches people to ignore it.
+     *
+     * **Held, not latched.** The distinction matters, because `contextGate` is
+     * documented as derived-never-latched and the reason is a real dead end: a figure
+     * pinned to a conversation that has since shrunk blocks the user out of the very
+     * actions that would fix it. This holds only for the duration of a turn and is
+     * refreshed the moment one settles, so no shrink can outlive it — a compaction
+     * runs under `compacting` rather than `busy` and therefore updates it as it goes,
+     * and Clear drops it outright. What it costs is one turn of lag: a turn that
+     * balloons the resting size does not warn until it ends, which is the same trade
+     * the flow-owner soften already makes deliberately.
+     *
+     * Unset falls back to the live figure, which is correct wherever there is no held
+     * value yet — first paint, and a remount, both of which happen at rest.
+     */
+    private _gateContextTokens?;
     get messages(): ChatMessage[];
     set messages(value: ChatMessage[]);
     get state(): AiAssistantState;
@@ -4053,11 +4167,11 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * Context-headroom thresholds for the active model (GENC-1567) — the warning
      * and block lines, plus the tail budget compaction aims at.
      *
-     * 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.
+     * 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.
      *
      * 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:
@@ -4067,22 +4181,26 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     get contextBudget(): ResolvedContextBudget;
     /**
-     * The active agent's declared `contextReserve`, when it is a plain number.
+     * Headroom the next turn needs, resolved against how routing is currently
+     * constrained (GENC-1582), and which agent set it.
      *
-     * Read off the LIVE active agent rather than checked at flow entry, which is
-     * where the design first put it. `flow-owner-changed` turned out to fire while
-     * the driver is already routing the turn — after the send was allowed — so it
-     * is not a pre-flight hook, and gating there would mean aborting a turn in
-     * flight. Reading the active agent instead means a hungry agent's reserve
-     * governs the gate from its next send onwards: one turn later than a true
-     * pre-flight, but synchronous, and it never has to interrupt anything.
+     * The driver owns the answer because the driver owns routing: whether a pin or a
+     * flow-owner lock is in force, which agents the classifier can reach, and which
+     * one is active. This used to read `getActiveAgent()?.contextReserve` — the agent
+     * that LAST ran — which is a different agent from the one about to run whenever
+     * the orchestrator is doing its job, and the handover turn is precisely the one
+     * that needs the room.
+     *
+     * Falls back to the active agent for a host-supplied driver that does not
+     * implement the resolution, so an existing single-agent driver keeps the old
+     * behaviour rather than silently losing its reserve.
      *
      * `contextReserve` is a plain number by design — see `ContextReserveInput` for
      * why a resolver form was dropped rather than accepted and ignored.
      *
      * @internal
      */
-    private get activeAgentReserveTokens();
+    private get contextReserve();
     /**
      * What compacting right now would reclaim, or `null` when it would not be
      * worth it (GENC-1567). Sized against {@link FoundationAiAssistant.contextBudget},
@@ -5020,6 +5138,12 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
     /** {@inheritDoc AiDriver.primeRestoredAgentState} */
     primeRestoredAgentState(snapshots: Record<string, unknown>): void;
+    /**
+     * {@inheritDoc AiDriver.getContextReserve}
+     *
+     * Two cases, because routing has two modes and they need opposite answers.
+     */
+    getContextReserve(): ContextReserveResolution | undefined;
     /** {@inheritDoc AiDriver.getActiveAgent} */
     getActiveAgent(): AgentConfig | undefined;
     private applyAgent;
@@ -5745,6 +5869,21 @@ export declare interface StatefulAgentInit<S> {
      * (fail-safe — never drop a resumable chat on a predicate bug).
      */
     resumable?: (ctx: StatefulAgentPersistenceContext<S>) => boolean | Promise<boolean>;
+    /**
+     * Tokens of context headroom to keep free for one of this agent's turns —
+     * see `AgentConfig.contextReserve`, which this is passed straight through to.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    contextReserve?: ContextReserveInput;
     /**
      * Message shown on return when {@link StatefulAgentInit.resumable} returned
      * `false`. Falls back to a built-in default when omitted.