@genesislcap/ai-assistant 15.19.6 → 15.20.0

package/dist/ai-assistant.d.ts

@@ -638,6 +638,16 @@ export declare interface AiDriver extends EventTarget {
      * retain the active config implement it.
      */
     getActiveAgent?(): AgentConfig | undefined;
+    /**
+     * Set the mid-loop context guard (GENC-1567). `undefined` disables it.
+     *
+     * Carries a margin rather than an absolute threshold: the window belongs to
+     * whichever provider the next call resolves to, which the driver learns during
+     * the call and the host cannot know until afterwards. The host owns the policy;
+     * the driver applies it against the model actually being addressed. Optional —
+     * only drivers that own a tool loop implement it.
+     */
+    setContextGuard?(policy?: ContextGuardPolicy): void;
     /**
      * Destructively compact older conversation turns into a single
      * `compacted-summary` message (GENC-1351 §5.7), summarizing them via the
@@ -645,15 +655,29 @@ export declare interface AiDriver extends EventTarget {
      * success. Resolves to the created summary message, or `null` when there is
      * nothing worth compacting or the provider cannot summarize. Optional — only
      * drivers that own history implement it.
+     *
+     * Pass the same `options` used for {@link AiDriver.getCompactionPlan} so the
+     * action does exactly what the affordance advertised.
      */
-    compact?(): Promise<ChatMessage | null>;
+    compact?(options?: CompactionPlanOptions): Promise<ChatMessage | null>;
     /**
-     * Whether `compact()` would compact something right now — a summarizable run of
-     * older turns exists behind a clean boundary. The UI gates its "Compact"
-     * affordance on this, so the button reflects the exact history `compact()` acts
-     * on (GENC-1351). Optional — only history-owning drivers implement it.
+     * What compacting right now would cost and reclaim, without running the
+     * summarizer (GENC-1567) — or `null` when there is no safe cut, or the
+     * projected reclaim is not worth the call.
+     *
+     * The single source of truth for every compaction affordance: the menu's
+     * enabled state, its tooltip, the context gate's banner copy, and the action
+     * itself all read this, so none of them can promise a reclaim the action does
+     * not deliver. Optional — only history-owning drivers implement it.
      */
-    canCompact?(): boolean;
+    getCompactionPlan?(options?: CompactionPlanOptions): CompactionProjection | null;
+    /**
+     * Whether `compact()` would compact something right now. Convenience over
+     * {@link AiDriver.getCompactionPlan} — prefer the plan where the caller needs
+     * to say how much would be reclaimed. Optional — only history-owning drivers
+     * implement it.
+     */
+    canCompact?(options?: CompactionPlanOptions): boolean;
     /**
      * Returns true if the driver is currently processing a request.
      */
@@ -1133,6 +1157,34 @@ declare interface BaseAgentConfig {
      * @beta
      */
     notResumableMessage?: string;
+    /**
+     * Tokens this agent wants kept free for one of its turns (GENC-1567).
+     * Overrides `chatConfig.context.reserveTokens` while this agent is active;
+     * leave unset to inherit it.
+     *
+     * The third member of the flow-safety group, alongside
+     * {@link BaseAgentConfig.resumable} and {@link BaseAgentConfig.notResumableMessage}:
+     * `resumable` says whether the agent may be interrupted, and this says how much
+     * 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.
+     *
+     * **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
+     * growth; a number invented up front will be wrong in whichever direction is
+     * least convenient. Leaving it unset and inheriting the global default is the
+     * right starting position.
+     *
+     * @beta
+     */
+    contextReserve?: ContextReserveInput;
 }
 
 /**
@@ -1201,16 +1253,6 @@ export { CachePolicy }
  */
 export declare type CachePolicyInput = CachePolicy | ((ctx: SystemPromptContext) => CachePolicy | Promise<CachePolicy>);
 
-/**
- * Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.
- * Owned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.
- *
- * Dispatches `'history-updated'` events on itself so the owning element can observe changes.
- *
- * @fires history-updated - Fired whenever the in-memory chat history changes (append, tool loop, interaction resolution, post-resolve external cost) with the full history snapshot. detail: `ReadonlyArray<ChatMessage>`
- *
- * @beta
- */
 export declare class ChatDriver extends EventTarget implements AiDriver {
     private readonly providerRegistry;
     private history;
@@ -1819,6 +1861,39 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * Optional transform applied to conversation history immediately before each LLM request.
      * Cleared when `undefined`. Does not alter stored history.
      */
+    /**
+     * Mid-loop context guard policy (GENC-1567). `undefined` disables the guard.
+     *
+     * Carries a MARGIN rather than an absolute threshold, and the difference is the
+     * whole point: the threshold depends on the window of whichever provider the
+     * next call resolves to, which the driver learns during the call and the host
+     * cannot know until afterwards. The host owns the policy; the driver applies it
+     * against the model actually being addressed.
+     */
+    private contextGuard?;
+    /** Window of the provider the current call resolved to, if it reports one. */
+    private lastResolvedContextLimit?;
+    /**
+     * Set the mid-loop context guard. Its margin is deliberately far smaller than
+     * the reserve that blocks NEW turns: that reserve exists so an accepted turn can
+     * spend it, and a guard set at the same line would kill every turn that used
+     * the headroom it was given.
+     */
+    setContextGuard(policy?: ContextGuardPolicy): void;
+    /**
+     * Whether issuing `requestHistory` would run the context window out.
+     *
+     * Inert unless a margin has been set AND the resolved provider reports a
+     * window — with no window there is nothing to measure against, and inventing
+     * one to refuse a request is worse than letting the provider answer.
+     *
+     * Stopping here is strictly better than letting the request go: the provider
+     * would reject an oversized prompt outright, leaving a transcript still too
+     * large to retry and no explanation the user can act on, whereas ending the
+     * turn keeps history intact so compaction is still available and the work so
+     * far is not lost.
+     */
+    private contextExhausted;
     setProviderHistoryTransform(transform?: (history: ChatMessage[]) => ChatMessage[]): void;
     getHistory(): ReadonlyArray<ChatMessage>;
     getRawHistory(): readonly ChatMessage[];
@@ -1830,7 +1905,16 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * turns exists behind a clean boundary. Uses the same `history` `compact()`
      * acts on, so the UI's gate can't disagree with the action (GENC-1351 follow-up).
      */
-    canCompact(): boolean;
+    canCompact(options?: CompactionPlanOptions): boolean;
+    /**
+     * {@inheritDoc AiDriver.getCompactionPlan}
+     *
+     * Runs against the driver's own `history` — the exact list `compact()` acts on
+     * — so a projection and the compaction it describes can never be computed from
+     * different transcripts (the GENC-1351 follow-up that first made `canCompact`
+     * read `history` rather than a mirrored copy).
+     */
+    getCompactionPlan(options?: CompactionPlanOptions): CompactionProjection | null;
     /**
      * Destructively compact older turns into a single `compacted-summary` message
      * (GENC-1351 §5.7). Summarizes everything before a clean recent-tail boundary
@@ -1840,7 +1924,7 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * the new one. Returns the created summary message, or `null` when there is
      * nothing worth compacting or the default provider cannot summarize.
      */
-    compact(): Promise<ChatMessage | null>;
+    compact(options?: CompactionPlanOptions): Promise<ChatMessage | null>;
     isBusy(): boolean;
     /**
      * Wire a parent driver as the host for this driver's interactions. When set,
@@ -2108,6 +2192,28 @@ export { ChatThinkingPolicy }
 
 export { ChatToolChoice }
 
+/** Options for {@link planCompaction}. */
+declare interface CompactionPlanOptions {
+    /** Token budget for the verbatim tail. */
+    tailTokenBudget?: number;
+    /** Minimum reclaim for the plan to be considered worth running. */
+    minReclaimTokens?: number;
+}
+
+/** What a compaction at a given cut would cost and reclaim. */
+declare interface CompactionProjection {
+    /** Index the verbatim tail starts at — everything before it is summarized. */
+    cut: number;
+    /** How many messages the summary would replace. */
+    compactedCount: number;
+    /** Estimated context now. */
+    tokensBefore: number;
+    /** Estimated context afterwards — preamble + summary allowance + the tail. */
+    tokensAfter: number;
+    /** `tokensBefore − tokensAfter`, floored at zero. */
+    reclaimed: number;
+}
+
 /**
  * `aria-describedby` for the composer's textarea, send button and attach button:
  * the banner's id whenever the banner has something to say, otherwise `null` (so
@@ -2133,6 +2239,51 @@ export { ChatToolChoice }
  */
 export declare const composerDescribedBy: (x: FoundationAiAssistant) => string | null;
 
+/**
+ * Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.
+ * Owned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.
+ *
+ * Dispatches `'history-updated'` events on itself so the owning element can observe changes.
+ *
+ * @fires history-updated - Fired whenever the in-memory chat history changes (append, tool loop, interaction resolution, post-resolve external cost) with the full history snapshot. detail: `ReadonlyArray<ChatMessage>`
+ *
+ * @beta
+ */
+/**
+ * Mid-loop context guard policy, pushed down by the host (GENC-1567).
+ *
+ * @internal
+ */
+export declare interface ContextGuardPolicy {
+    /**
+     * How close to the model's context window a running tool loop may get before
+     * it is stopped.
+     */
+    marginTokens: number;
+    /**
+     * Window to assume when the resolved provider reports none. Consulted only in
+     * that case — a provider that states its own window always wins.
+     */
+    fallbackLimit?: number;
+}
+
+/**
+ * Context headroom an agent reserves for itself, in tokens.
+ *
+ * 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.
+ *
+ * It can widen to a resolver later without breaking a caller, since every
+ * existing `number` stays valid.
+ *
+ * @beta
+ */
+export declare type ContextReserveInput = number;
+
 /** A model used during a recorded cost session. */
 export declare interface CostSessionModelEntry {
     model: string;
@@ -3664,6 +3815,27 @@ export declare class FoundationAiAssistant extends GenesisElement {
     sessionKeyChanged(_oldValue: string | undefined, _newValue: string | undefined): void;
     disconnectedCallback(): void;
     private resolveContextLimit;
+    /**
+     * Push the mid-loop context guard down to the driver (GENC-1567).
+     *
+     * Called wherever the inputs can change — the resolved provider status, and a
+     * freshly built driver. A driver that never receives one simply runs without
+     * the guard, which is the right default: it fires only when a real context
+     * window is known.
+     */
+    private syncContextGuard;
+    /**
+     * Guard policy pushed to the driver, or `undefined` when the host has switched
+     * the gate off — so `enabled: false` really does mean no local blocking of any
+     * kind, UI or mid-loop.
+     *
+     * A MARGIN, not a threshold: the driver resolves the window of the provider
+     * each call actually goes to. The fallback window rides along because the
+     * driver cannot learn it any other way — without it, a host that knows its
+     * window while its provider does not report one had `fallbackContextLimit`
+     * protecting the composer and nothing else.
+     */
+    private get contextGuardPolicy();
     private loadProviderStatuses;
     chatConfigChanged(): void;
     /**
@@ -3795,16 +3967,175 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * clearing/compacting mid-journey would be disruptive).
      */
     get sessionMenuEnabled(): boolean;
+    /**
+     * Whether the menu is on screen ONLY because the context gate put it there.
+     *
+     * @internal
+     */
+    get sessionMenuForcedByContext(): boolean;
+    /**
+     * Whether to withhold Clear from a menu the context gate forced open.
+     *
+     * The hosts who hid this menu did so to protect a flow from being cleared
+     * mid-journey, and handing someone a Clear button at the moment they are stuck
+     * hunting for a way out is how a conversation gets destroyed by accident.
+     *
+     * But only **while Compact is a real escape**. When the plan says compacting
+     * would not free enough, starting a new conversation is the only way out — and
+     * the blocked copy says exactly that, pointing the user at this menu to do it.
+     * Withholding Clear there would send them to a menu that does not contain the
+     * action they were just told to take.
+     *
+     * @internal
+     */
+    get clearWithheldByContext(): boolean;
     /** The persistence toggle row renders only when a provider is configured. */
     get persistenceToggleable(): boolean;
     /** Whether persistence is currently active (on + a provider) for this session. */
     get persistenceActive(): boolean;
     /**
-     * Whether the menu's "Compact" action would do anything (GENC-1351 §5.7).
-     * Delegates to `driver.canCompact()` so the gate uses the exact same history
-     * `compact()` acts on — one source of truth. Also reads `messages`, purely to
-     * stay reactive as the conversation grows: the driver's history isn't a tracked
-     * observable, so the button keys its re-evaluation off the Redux mirror.
+     * 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.
+     *
+     * 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.
+     */
+    get contextBudget(): ResolvedContextBudget;
+    /**
+     * The active agent's declared `contextReserve`, when it is a plain number.
+     *
+     * 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.
+     *
+     * `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();
+    /**
+     * What compacting right now would reclaim, or `null` when it would not be
+     * worth it (GENC-1567). Sized against {@link FoundationAiAssistant.contextBudget},
+     * so the plan aims at this model's window rather than a fixed default.
+     *
+     * Reads `messages` to stay reactive as the conversation grows: the driver's
+     * history is not a tracked observable, so every consumer of this keys its
+     * re-evaluation off the Redux mirror.
+     */
+    get compactionPlan(): CompactionProjection | null;
+    /**
+     * Tooltip and hint for the Compact row — why it is or is not available.
+     *
+     * Replaces a fixed "Not enough conversation yet to be worth compacting", which
+     * since GENC-1567 could be flatly wrong: a long conversation whose tail is one
+     * indivisible tool result has plenty of conversation and still cannot be
+     * compacted. Reading the plan means the hint states the actual reason.
+     *
+     * @internal
+     */
+    get compactHint(): string;
+    /**
+     * How close this conversation is to the model's context window (GENC-1567).
+     *
+     * **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.
+     *
+     * **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.
+     */
+    get contextGate(): 'ok' | 'warn' | 'blocked';
+    /**
+     * What the composer notice says about the context gate.
+     *
+     * The copy is a function of whether compaction can actually clear the gate,
+     * which is why it reads {@link FoundationAiAssistant.compactionPlan} rather
+     * than assuming. Telling someone to compact when the projection says it would
+     * not free enough — a tail that is one indivisible tool result, say — sends
+     * them into a summarizer call that leaves them exactly where they were.
+     *
+     * @internal
+     */
+    get contextGateReason(): string;
+    /**
+     * Short label the session-menu pill wears while the gate is active — the
+     * primary visible signal, in place of a banner.
+     *
+     * Borrowed from the agent pin, which is the established way this composer says
+     * "a mode is in force": a pill that grows a label rather than a strip of prose
+     * above the input. It states the CONDITION only; the remedy lives in the
+     * placeholder once the composer is actually blocked, which is the moment the
+     * user needs to be told what to do rather than merely warned.
+     *
+     * @internal
+     */
+    get contextGateLabel(): string;
+    /**
+     * Whether the composer notice has anything to show — a budget wall or the
+     * context gate. One region for both, so the live region stays single and
+     * registered (see the banner template's accessibility note).
+     *
+     * @internal
+     */
+    get composerNoticeVisible(): boolean;
+    /**
+     * Text for that region. A budget wall outranks the context gate: it is the
+     * condition the user cannot clear, so it must not be hidden behind advice
+     * about compacting that would not restore sending anyway.
+     *
+     * For the context gate the region is present and announced but not drawn — see
+     * {@link FoundationAiAssistant.composerNoticeSrOnly}.
+     *
+     * @internal
+     */
+    get composerNoticeText(): string;
+    /**
+     * Whether the notice region should be announced but not drawn.
+     *
+     * The context gate shows itself visually through the pill's label, the
+     * composer outline and the placeholder — a strip of prose on top of those
+     * would be a fourth statement of the same thing. But dropping the region
+     * outright would be an accessibility regression, and a documented one: a
+     * `role="status"` region announces MUTATIONS to a region already being
+     * observed, and it is the only announcement available here, because the
+     * composer flips to `disabled` at the same moment and a disabled control is out
+     * of the tab order — so neither the placeholder nor an `aria-label` on it is
+     * ever voiced.
+     *
+     * So the region stays mounted, keeps its text and keeps announcing; only the
+     * visual treatment is withheld. A budget wall still draws its banner, because
+     * that condition has no other visible expression.
+     *
+     * @internal
+     */
+    get composerNoticeSrOnly(): boolean;
+    /**
+     * Whether the menu's "Compact" action would do anything (GENC-1351 §5.7,
+     * GENC-1567). Delegates to the driver's plan so the gate uses the exact same
+     * history `compact()` acts on, judged against the same budget — one source of
+     * truth for both whether a cut is legal and whether it reclaims enough.
      */
     get compactable(): boolean;
     toggleSessionMenu(): void;
@@ -4591,10 +4922,14 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     setFlowOwner(name: string | null): void;
     loadHistory(messages: ChatMessage[]): void;
     getRawHistory(): readonly ChatMessage[];
+    /** {@inheritDoc AiDriver.setContextGuard} */
+    setContextGuard(policy?: ContextGuardPolicy): void;
     /** {@inheritDoc AiDriver.compact} */
-    compact(): Promise<ChatMessage | null>;
+    compact(options?: CompactionPlanOptions): Promise<ChatMessage | null>;
     /** {@inheritDoc AiDriver.canCompact} */
-    canCompact(): boolean;
+    canCompact(options?: CompactionPlanOptions): boolean;
+    /** {@inheritDoc AiDriver.getCompactionPlan} */
+    getCompactionPlan(options?: CompactionPlanOptions): CompactionProjection | null;
     /** Delegates to the inner {@link ChatDriver} — turns are captured there. */
     getTurnSnapshots(): ReadonlyArray<TurnSnapshot>;
     /** Delegates to the inner {@link ChatDriver} — interactions resolve there, so it holds the buffer. */
@@ -4745,6 +5080,50 @@ declare type ProviderRefusedDetail = NonNullable<Extract<ChatDriverResult, {
 /** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
 export declare const REQUEST_CONTINUATION_TOOL = "request_continuation";
 
+/** Resolved context-headroom thresholds for the active model. */
+declare interface ResolvedContextBudget {
+    /**
+     * Whether the gate can act. False when the host disabled it, or when no
+     * context limit is known — with no limit there is no percentage, and blocking
+     * against a guessed window would be worse than not blocking at all.
+     */
+    enabled: boolean;
+    /** The context window in play, from the provider or the configured fallback. */
+    limit?: number;
+    /** Headroom reserved for one turn. */
+    reserveTokens: number;
+    /** Context size at which the warning appears. */
+    warnAt?: number;
+    /** Context size at which new sends are blocked. */
+    blockAt?: number;
+    /**
+     * Token budget for the verbatim tail a compaction leaves behind.
+     *
+     * Derived so a compaction lands back below the WARNING line, not merely below
+     * the block: clearing the block by a hair would re-warn on the next turn and
+     * make the user compact again almost immediately. The summary's own allowance
+     * is subtracted because it occupies the space it is meant to free.
+     */
+    tailTokenBudget: number;
+    /** Smallest reclaim for compaction to be worth running. */
+    minReclaimTokens: number;
+    /**
+     * Context size at which a RUNNING turn is stopped mid-loop (GENC-1567).
+     *
+     * Deliberately far higher than {@link ResolvedContextBudget.blockAt}, and the
+     * gap is the whole point: `blockAt` is where new turns stop being ACCEPTED, and
+     * the reserve below it exists precisely so an accepted turn can spend it. A
+     * mid-loop guard set at `blockAt` would kill every turn that used the headroom
+     * it was given, which is the opposite of the intent.
+     *
+     * This is the last-resort edge — close enough to the window that one more
+     * request would likely be rejected outright. Stopping here keeps the
+     * transcript intact and compaction possible, where letting the request go
+     * gives a provider error and a conversation still too big to retry.
+     */
+    abortAt?: number;
+}
+
 /** Resolved cost-history settings from `chatConfig.costHistory`. */
 declare interface ResolvedCostHistoryConfig {
     /** When `true`, sessions are persisted automatically and history is shown. */