@genesislcap/ai-assistant 15.23.0 → 15.23.1

package/dist/esm/components/orchestrating-driver/orchestrating-driver.js

@@ -46,6 +46,40 @@ function isSpecialist(agent) {
 function isFallback(agent) {
     return agent.fallback === true;
 }
+/**
+ * Flatten a `contextReserve` declaration to the two numbers the gate reads
+ * (GENC-1582), or `undefined` when the agent declared nothing.
+ *
+ * A bare number is the peak-only form and leaves the warning to the host's
+ * `warnMultiplier`. Non-positive `tokens` is treated as no declaration rather
+ * than as "needs no headroom": zero would resolve to a reserve of 0, which sets
+ * `blockAt` to the whole window and switches the gate off for every agent the
+ * turn could reach — the opposite of what declaring a reserve is for.
+ *
+ * **Validated at runtime, not just by the type.** `contextReserve` is host-supplied
+ * `@beta` config and can arrive from JS, from JSON, or from a dynamic source, so
+ * `tokens` may be absent or not a number whatever the signature says. That matters
+ * more than a violated return type: `undefined <= 0` is `false`, so a bare
+ * comparison passed a malformed reserve straight through as `{ tokens: undefined }`,
+ * and the caller's `reserve.tokens > winner.tokens` then compared against
+ * `undefined` — always false. One malformed entry on an earlier-listed agent
+ * therefore SUPPRESSED every valid reserve behind it, and the gate fell back to the
+ * ambient default while still naming the malformed agent. Silent, because
+ * `resolveContextBudget` coalesces an undefined reserve to that same default
+ * (reviewer catch on #2504).
+ */
+function normalizeContextReserve(input) {
+    if (input == null)
+        return undefined;
+    const positive = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0;
+    if (typeof input === 'number')
+        return positive(input) ? { tokens: input } : undefined;
+    if (!positive(input.tokens))
+        return undefined;
+    return positive(input.warnAheadTokens)
+        ? { tokens: input.tokens, warnAheadTokens: input.warnAheadTokens }
+        : { tokens: input.tokens };
+}
 /**
  * Placeholder a consumer can put in its fallback prompt to position
  * {@link UNROUTABLE_INSTRUCTION} itself, instead of having it appended.
@@ -293,6 +327,10 @@ export class OrchestratingDriver extends EventTarget {
     canCompact(options) {
         return this.chatDriver.canCompact(options);
     }
+    /** {@inheritDoc AiDriver.getPreambleTokens} */
+    getPreambleTokens() {
+        return this.chatDriver.getPreambleTokens();
+    }
     /** {@inheritDoc AiDriver.getCompactionPlan} */
     getCompactionPlan(options) {
         return this.chatDriver.getCompactionPlan(options);
@@ -499,6 +537,60 @@ export class OrchestratingDriver extends EventTarget {
     primeRestoredAgentState(snapshots) {
         this.restoredAgentStates = Object.assign({}, snapshots);
     }
+    /**
+     * {@inheritDoc AiDriver.getContextReserve}
+     *
+     * Two cases, because routing has two modes and they need opposite answers.
+     */
+    getContextReserve() {
+        // LOCKED — a user pin or a flow-owner lock. `handleTurn` routes straight to
+        // this agent and the handoff branch at the bottom of the routing loop refuses
+        // to route away while a lock is held, so no other agent's headroom can come
+        // into play until it clears. Its reserve is the whole requirement.
+        const locked = this.resolvePinnedAgent();
+        if (locked) {
+            const reserve = normalizeContextReserve(locked.contextReserve);
+            return reserve == null ? undefined : Object.assign(Object.assign({}, reserve), { agentName: locked.name, basis: 'locked' });
+        }
+        // AUTOMATIC — the classifier picks a specialist, may fall through to the
+        // fallback, and may hand off and re-classify more than once inside the one
+        // turn. Any of them could be the agent that runs, and the send is allowed or
+        // refused before we know which, so the requirement is the largest reserve
+        // among them: the turn has to fit whichever way it routes.
+        //
+        // The MAX, not the sum, even though a handoff chain really does add each leg's
+        // growth on top of the last. Summing every reachable agent would reserve room
+        // for a journey nobody is taking and strand most of the window on a two-line
+        // question; the mid-loop context guard is what bounds a chain that does run
+        // long. The max is the smallest reserve that makes the FIRST leg safe, which
+        // is the only leg this gate can speak for.
+        //
+        // `excludeFromClassifier` agents are absent by construction — they are
+        // reachable only by pin or by a restored flow-owner lock, and both of those
+        // are the locked arm above. The active agent is folded in as a floor: on the
+        // turn after a lock clears it is still the agent holding the context, and it
+        // need not be one the classifier could have picked.
+        const candidates = [...this.specialists];
+        if (this.fallback)
+            candidates.push(this.fallback);
+        if (this.activeAgent)
+            candidates.push(this.activeAgent);
+        // Compared on `tokens` — the figure that decides whether a turn may start.
+        // `warnAheadTokens` is not a candidate for the max in its own right; it rides
+        // along with whichever agent wins.
+        let winner;
+        let agentName = '';
+        for (const agent of candidates) {
+            const reserve = normalizeContextReserve(agent.contextReserve);
+            if (!reserve)
+                continue;
+            if (!winner || reserve.tokens > winner.tokens) {
+                winner = reserve;
+                agentName = agent.name;
+            }
+        }
+        return winner ? Object.assign(Object.assign({}, winner), { agentName, basis: 'reachable-max' }) : undefined;
+    }
     /** {@inheritDoc AiDriver.getActiveAgent} */
     getActiveAgent() {
         return this.activeAgent;

package/dist/esm/config/define-stateful-agent.js

@@ -264,6 +264,7 @@ export function defineStatefulAgent(opts) {
         onUnresolvedTool: wrappedOnUnresolvedTool,
         resumable: wrappedResumable,
         notResumableMessage: opts.notResumableMessage,
+        contextReserve: opts.contextReserve,
         onActivate: (ctx) => __awaiter(this, void 0, void 0, function* () {
             state = yield opts.init(ctx);
             // Sample once with the init state to fail loud on fold misuse at the

package/dist/esm/main/main.js

@@ -55,7 +55,7 @@ import { AnimatedPanelToggle } from '../utils/animated-panel-toggle';
 import { resolveExclusiveLoadingStyle } from '../utils/animation-exclusivity';
 import { deleteBankedBaseline, getBankedBaseline, setBankedBaseline, } from '../utils/banked-usage-baselines';
 import { collectSessionModels } from '../utils/collect-session-models';
-import { estimateContextTokens, estimateSystemOverhead, isContextMeasurable, } from '../utils/context-tokens';
+import { estimateContextTokens, isContextMeasurable, } from '../utils/context-tokens';
 import { clearCostSessionHistory, isCostSessionRecord, loadCostSessionHistory, resolveBankedUsage, saveCostSessionHistory, sortRecordsByRecency, upsertRecord, } from '../utils/cost-session-history';
 import { deriveCostSessionTitleFromMessages, resolveCostSessionTitle, } from '../utils/derive-cost-session-title';
 import { formatUsd } from '../utils/format-usd';
@@ -607,6 +607,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         // immediately, but only if they haven't moved on to something else.
         // `cancelling` is busy too, so loading → cancelling must NOT settle yet.
         if (this.isBusyState(prev) && !this.isBusyState(value)) {
+            this.rearmContextGate();
             this.maybeAutoFocusChatInput();
             // Apply a session re-key deferred by the busy guard first (it rebuilds the
             // driver against current agents, so the agents-swap below then no-ops).
@@ -622,6 +623,31 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     isBusyState(s) {
         return s === 'loading' || s === 'cancelling';
     }
+    /**
+     * Re-arm {@link FoundationAiAssistant.contextGate} against the size the turn
+     * just left behind (GENC-1582).
+     *
+     * The final call of a turn is made AFTER `agentEnd` condensation fires, so by
+     * the time a turn settles `contextTokens` is the resting figure rather than the
+     * mid-turn peak — which is the number the reserve's thresholds are drawn
+     * against.
+     *
+     * **Called from BOTH settle paths, and it has to be.** A turn does not end
+     * through the `state` setter: `send()`'s `finally` writes `setState('idle')`
+     * straight to the captured session ref, because the element may have
+     * disconnected mid-turn, and that block then replicates the parts of the
+     * setter's settle that matter. Arming the gate inline in the setter therefore
+     * armed it on the one path a real turn never takes — the gate silently kept
+     * falling back to the live figure and the hold did nothing at all. Found by
+     * driving a real UI Builder turn and reading `_gateContextTokens`, which was
+     * `undefined` from start to finish; no unit test noticed, because the test
+     * harness sets `state` through the property.
+     *
+     * One method rather than two assignments so the two paths cannot drift again.
+     */
+    rearmContextGate() {
+        this._gateContextTokens = this.contextTokens;
+    }
     /**
      * True while a turn is active — `loading` or `cancelling` (a stop was
      * requested but the turn is still winding down). The single "is a turn
@@ -3205,6 +3231,12 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         if (isContextMeasurable(this.messages)) {
             this.contextTokens = estimateContextTokens(this.messages);
         }
+        // Keep the gate's figure in step while at rest. Deliberately skipped mid-turn:
+        // that is the spike the gate must not react to (see `_gateContextTokens`). A
+        // compaction reaches this branch — it runs under `compacting`, not `busy` — so
+        // the shrink it produces is picked up immediately rather than waiting for a turn.
+        if (!this.busy)
+            this._gateContextTokens = this.contextTokens;
         // Recompute cost and all four token buckets from the transcript in one walk.
         // Recomputing (rather than incrementing on append) keeps the totals correct under
         // any mutation of the message list — clear-chat, re-render, restore. `sumUsage`
@@ -3503,6 +3535,13 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         var _a;
         if (this.contextGate === 'ok')
             return false;
+        // The `'model'` cause is the exception (GENC-1582). This override exists so a
+        // user told to compact can reach Compact — but when the window cannot host the
+        // agent, Compact and Clear are both futile, and forcing a menu of dead actions
+        // in front of someone is worse than not opening it. The copy points at the
+        // model picker instead.
+        if (this.contextBlockCause === 'model')
+            return false;
         return ((_a = this.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.showSessionMenu) === false || !this.persistence.provider;
     }
     /**
@@ -3535,11 +3574,11 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * 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:
@@ -3548,32 +3587,63 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * and driver history is only ever at the tail.
      */
     get contextBudget() {
+        // Resolved ONCE. `contextReserve` re-reads live routing state on every access,
+        // so two reads can land on different winners and pair one agent's
+        // `warnAheadTokens` with another's `tokens` — the exact pairing
+        // `ContextReserveResolution` warns against, and the reason this is a local
+        // rather than two property reads (reviewer catch on #2504). It also stops the
+        // orchestrator walking every specialist plus the fallback twice per evaluation.
+        const reserve = this.contextReserve;
         return resolveContextBudget({
             chatConfig: this.chatConfig,
             contextLimit: this.contextLimit,
-            agentReserveTokens: this.activeAgentReserveTokens,
-            systemOverhead: estimateSystemOverhead(this.messages),
+            agentReserveTokens: reserve === null || reserve === void 0 ? void 0 : reserve.tokens,
+            agentWarnAheadTokens: reserve === null || reserve === void 0 ? void 0 : reserve.warnAheadTokens,
         });
     }
     /**
-     * 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.
+     *
+     * 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.
      *
-     * 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.
+     * 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
      */
-    get activeAgentReserveTokens() {
-        var _a, _b, _c;
-        return (_c = (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getActiveAgent) === null || _b === void 0 ? void 0 : _b.call(_a)) === null || _c === void 0 ? void 0 : _c.contextReserve;
+    get contextReserve() {
+        var _a, _b, _c, _d;
+        const resolved = (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getContextReserve) === null || _b === void 0 ? void 0 : _b.call(_a);
+        if (resolved)
+            return resolved;
+        const active = (_d = (_c = this.driver) === null || _c === void 0 ? void 0 : _c.getActiveAgent) === null || _d === void 0 ? void 0 : _d.call(_c);
+        const declared = active === null || active === void 0 ? void 0 : active.contextReserve;
+        if (declared == null)
+            return undefined;
+        // Runtime-validated for the same reason `normalizeContextReserve` is: this is
+        // host-supplied config, and `undefined <= 0` is `false`, so a bare comparison
+        // lets a malformed reserve through as `tokens: undefined` (reviewer catch on #2504).
+        const positive = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0;
+        const tokens = typeof declared === 'number' ? declared : declared.tokens;
+        if (!positive(tokens))
+            return undefined;
+        const warnAhead = typeof declared === 'number' ? undefined : declared.warnAheadTokens;
+        return {
+            tokens,
+            warnAheadTokens: positive(warnAhead) ? warnAhead : undefined,
+            agentName: active.name,
+            basis: 'locked',
+        };
     }
     /**
      * What compacting right now would reclaim, or `null` when it would not be
@@ -3585,14 +3655,15 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * re-evaluation off the Redux mirror.
      */
     get compactionPlan() {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         if (this.messages.length === 0)
             return null;
         const budget = this.contextBudget;
-        return ((_c = (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getCompactionPlan) === null || _b === void 0 ? void 0 : _b.call(_a, {
+        return ((_e = (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getCompactionPlan) === null || _b === void 0 ? void 0 : _b.call(_a, {
+            preambleTokens: (_d = (_c = this.driver) === null || _c === void 0 ? void 0 : _c.getPreambleTokens) === null || _d === void 0 ? void 0 : _d.call(_c),
             tailTokenBudget: budget.tailTokenBudget,
             minReclaimTokens: budget.minReclaimTokens,
-        })) !== null && _c !== void 0 ? _c : null);
+        })) !== null && _e !== void 0 ? _e : null);
     }
     /**
      * Tooltip and hint for the Compact row — why it is or is not available.
@@ -3630,11 +3701,48 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * and gating on the way out is the lesser harm; the headroom reserve exists so
      * this is rare rather than routine.
      */
+    /**
+     * WHY the composer is blocked, when it is (GENC-1582). `undefined` unless
+     * {@link FoundationAiAssistant.contextGate} is `'blocked'`.
+     *
+     * A cause rather than a fourth gate level: the severity is identical — sends are
+     * refused either way — and every consumer switches on the three levels. What
+     * differs is what the user can do about it, which is worth splitting because the
+     * two answers have no remedy in common.
+     *
+     * - `'transcript'` — the conversation has grown into the reserve. Compacting or
+     *   clearing helps, and the copy says so.
+     * - `'model'` — the active agent's reserve meets or exceeds the whole window, so
+     *   `blockAt` is 0 and EVERY message is refused, including the first of an empty
+     *   chat. Neither compacting nor clearing can help: the constraint is the model,
+     *   not the transcript. Before this existed the user was told to clear the chat,
+     *   did, and hit the identical block with no way to understand why.
+     *
+     * Keyed off `blockAt === 0`, deliberately NOT off whether a compaction plan
+     * exists. A null plan has two unrelated causes — nothing left worth summarizing,
+     * versus a window that cannot host the agent at all — and conflating them is what
+     * produced the misleading copy.
+     *
+     * Note the block itself is correct in both cases and must stay: an agent that
+     * measurably cannot complete a turn in this window would otherwise start one and
+     * die mid-loop on a provider context error, with partial writes and no clean
+     * exit. Refusing up front is the better failure.
+     *
+     * @internal
+     */
+    get contextBlockCause() {
+        if (this.contextGate !== 'blocked')
+            return undefined;
+        return this.contextBudget.blockAt === 0 ? 'model' : 'transcript';
+    }
     get contextGate() {
+        var _a;
         const budget = this.contextBudget;
         if (!budget.enabled)
             return 'ok';
-        const tokens = this.contextTokens;
+        // The figure from the last moment nothing was running, not the live one — see
+        // `_gateContextTokens` for why the gauge and the gate differ here.
+        const tokens = (_a = this._gateContextTokens) !== null && _a !== void 0 ? _a : this.contextTokens;
         if (tokens == null || budget.blockAt == null || budget.warnAt == null)
             return 'ok';
         if (tokens >= budget.blockAt)
@@ -3653,12 +3761,36 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * @internal
      */
     get contextGateReason() {
+        var _a, _b;
         const level = this.contextGate;
         const canHelp = this.compactionPlan != null;
+        if (level === 'blocked' && this.contextBlockCause === 'model') {
+            // The window cannot host this agent, so neither remedy the other branches
+            // offer can help. Name the agent and both figures instead: the numbers are
+            // what make "switch model" an instruction rather than a shrug, and they are
+            // already to hand.
+            const reserve = this.contextReserve;
+            const need = reserve ? `${reserve.tokens.toLocaleString()} tokens` : 'more headroom';
+            const have = (_a = this.contextLimit) === null || _a === void 0 ? void 0 : _a.toLocaleString();
+            const who = (_b = reserve === null || reserve === void 0 ? void 0 : reserve.agentName) !== null && _b !== void 0 ? _b : 'This task';
+            return (`${who} needs about ${need} of context headroom to complete a turn, and this model has ` +
+                `${have !== null && have !== void 0 ? have : 'less than that'}. Switch to a model with a larger context window, or pick a ` +
+                `different agent — compacting or clearing this conversation will not help.`);
+        }
         if (level === 'blocked') {
-            return canHelp
-                ? 'There is not enough room in the model context for more work. Click the error pill and compact the context to continue working.'
-                : 'There is not enough room in the model context for more work. Compacting the context will not free enough room, click the error pill to clear and start a new conversation.';
+            // Name the agent whose headroom is binding when routing is automatic
+            // (GENC-1582). The reserve is then the hungriest agent the turn could land
+            // on, so the composer can close while there is plenty of room for the short
+            // question the user was about to type — and a message that only said "not
+            // enough room for more work" would read as a bug rather than a reason.
+            const reserve = this.contextReserve;
+            const cause = (reserve === null || reserve === void 0 ? void 0 : reserve.basis) === 'reachable-max'
+                ? `There is not enough room in the model context to start another task — ${reserve.agentName} needs the most of any I could pick up next.`
+                : 'There is not enough room in the model context for more work.';
+            const remedy = canHelp
+                ? 'Click the error pill and compact the context to continue working.'
+                : 'Compacting the context will not free enough room, click the error pill to clear and start a new conversation.';
+            return `${cause} ${remedy}`;
         }
         if (this.flowOwnerAgentName !== null) {
             return 'This conversation is nearly full. The task in progress will finish, but compact before starting another.';
@@ -3963,6 +4095,10 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             if (this.driver)
                 this.teardownDriver(key);
             (_g = this._sessionRef) === null || _g === void 0 ? void 0 : _g.actions.aiAssistant.resetSession();
+            // `resetSession` zeroes the store-backed `contextTokens`; the gate's held copy
+            // is ours to drop. Leaving it would carry a block into a conversation that no
+            // longer exists — the one thing `contextGate` must never do (GENC-1582).
+            this._gateContextTokens = undefined;
             if (key) {
                 this.rebaselineOnClearedTranscript(key, discarded);
                 this.rebuildDriver(key);
@@ -5172,6 +5308,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 // setState was dispatched directly via the captured ref (not via the
                 // state setter) so the setter's loading→idle cleanup path doesn't fire
                 // here. Replicate the parts of it that matter for the post-turn settle.
+                this.rearmContextGate();
                 this.maybeAutoFocusChatInput();
                 this.applyDeferredSessionSwitch();
                 this.applyDeferredAgentsSwap();
@@ -5385,6 +5522,9 @@ __decorate([
 __decorate([
     observable
 ], FoundationAiAssistant.prototype, "_sessionRef", void 0);
+__decorate([
+    observable
+], FoundationAiAssistant.prototype, "_gateContextTokens", void 0);
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "busy", null);
@@ -5528,13 +5668,16 @@ __decorate([
 ], FoundationAiAssistant.prototype, "contextBudget", null);
 __decorate([
     volatile
-], FoundationAiAssistant.prototype, "activeAgentReserveTokens", null);
+], FoundationAiAssistant.prototype, "contextReserve", null);
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "compactionPlan", null);
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "compactHint", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "contextBlockCause", null);
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "contextGate", null);