@genesislcap/ai-assistant 15.20.2 → 15.21.1

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

@@ -1,13 +1,27 @@
-import { __awaiter } from "tslib";
+import { __awaiter, __rest } from "tslib";
 import { BudgetExhaustedError } from '@genesislcap/foundation-ai';
 import { validateStaticAgentProviders } from '../../config/validate-providers';
 import { recordMetaEvent } from '../../state/debug-event-log';
+import { reachesProvider } from '../../utils/context-tokens';
 import { transformHistoryForAgent } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
+import { messageUsage } from '../../utils/sum-usage';
 import { ChatDriver, REQUEST_CONTINUATION_TOOL, } from '../chat-driver/chat-driver';
 const DEFAULT_MAX_HANDOFFS = 3;
 const DEFAULT_CLASSIFIER_HISTORY_LENGTH = 4;
 const DEFAULT_CLASSIFIER_RETRIES = 2;
+/**
+ * Per-message and whole-block ceilings, in characters, on the recent-conversation excerpt in the
+ * classifier prompt.
+ *
+ * `classifierHistoryLength` bounds the message COUNT and nothing bounded their size, so the
+ * excerpt was as large as the last few messages happened to be — measured at 32,937 characters in
+ * one session (GENC-1573), on every routed turn, to answer one multiple-choice question. Routing
+ * reads the topic, not the detail: the opening of each message carries what the user asked for,
+ * and a truncated tail costs a router nothing.
+ */
+const CLASSIFIER_MESSAGE_CHARS = 600;
+const CLASSIFIER_TRANSCRIPT_CHARS = 3000;
 const REQUEST_CONTINUATION_DEFINITION = {
     name: REQUEST_CONTINUATION_TOOL,
     description: "Call this when you have completed your part of the task but fulfilling the user's full request requires capabilities outside your domain. Do not call this if you can complete the request yourself. Pass a plain-language description of what still needs to be done — another specialist will be selected automatically.",
@@ -32,18 +46,66 @@ function isSpecialist(agent) {
 function isFallback(agent) {
     return agent.fallback === true;
 }
+/**
+ * Placeholder a consumer can put in its fallback prompt to position
+ * {@link UNROUTABLE_INSTRUCTION} itself, instead of having it appended.
+ *
+ * @beta
+ */
+export const UNROUTABLE_PLACEHOLDER = '{{unroutable}}';
+/**
+ * The instruction a fallback agent needs and, left to itself, tends not to have.
+ *
+ * A fallback prompt written by a consumer reliably covers two cases — small talk, and a request
+ * that belongs to a specialist — because those are the ones you think of when you write it. The
+ * case it exists FOR is the third: a substantive request that no specialist covers, and no way to
+ * act on it, because a fallback holds no tools and is denied the continuation tool as a leaf.
+ *
+ * Create's fallback prompt is the worked example (GENC-1573). It covered chit-chat and
+ * "out of scope, here are the specialists", said nothing about a request nothing can serve, and
+ * nothing about a terse follow-up ("fix it", "try again") aimed at an answer already given. Asked
+ * to fix a Kotlin null pointer no agent could touch, it returned nine blank turns across three
+ * page loads — a model with no instruction covering its situation and no tool to reach for.
+ *
+ * So the framework supplies it. Appended to a string-form prompt (or substituted at
+ * {@link UNROUTABLE_PLACEHOLDER} if the consumer positions it), because a fallback with no answer
+ * for its own reason to exist is a defect in every host, not a matter of taste. It is additive and
+ * static: being fixed it cannot destabilise a cached prefix, and the fallback prompt already
+ * changes whenever the agents array does (`{{agents}}` interpolates the specialist list). The
+ * function form still passes through untouched — a consumer that wants full control has it there.
+ *
+ * DELIBERATELY CONFINED TO WHAT A TERSE PROMPT CAN ALSO OBEY, and it must stay that way. Since
+ * this is appended by default it lands on top of prompts written with their own tone rules, and
+ * an earlier draft asked the model to "state what you can establish… and suggest what the user
+ * could do next" — a direct contradiction of {@link strictFallbackAgent}, a preset THIS PACKAGE
+ * ships, whose whole instruction is "a single short sentence… Do not elaborate". What is left
+ * here is compatible with brevity: say so, don't promise work you cannot do, read a short
+ * follow-up in context, and never answer with nothing. Adding anything that presumes room to
+ * elaborate breaks a shipped preset — put it in the consumer's own prompt instead.
+ *
+ * @beta
+ */
+export const UNROUTABLE_INSTRUCTION = `When the request is substantive but nothing above covers it, say so directly. Do not offer to do it yourself, and do not imply a specialist will pick it up.
+
+If the user's message is a short follow-up to something already discussed — "fix it", "try again", "why?" — read it against the conversation above and answer that, rather than treating it as a new request with no context.
+
+Never end your turn without saying something. An empty reply is never a valid response: if you genuinely cannot help, say briefly that you cannot, and why.`;
 function buildFallbackSystemPrompt(fallback, specialists) {
     const agentList = specialists.map((s) => `- ${s.name}: ${s.description}`).join('\n');
     if (typeof fallback.systemPrompt === 'string') {
-        return fallback.systemPrompt.replace('{{agents}}', agentList);
+        const withAgents = fallback.systemPrompt.replace('{{agents}}', agentList);
+        return withAgents.includes(UNROUTABLE_PLACEHOLDER)
+            ? withAgents.replace(UNROUTABLE_PLACEHOLDER, UNROUTABLE_INSTRUCTION)
+            : `${withAgents}\n\n${UNROUTABLE_INSTRUCTION}`;
     }
     if (typeof fallback.systemPrompt === 'function') {
         // Function-form fallback prompt — pass through unchanged. The `{{agents}}`
         // substitution is a string-template convenience; consumers using the
-        // function form can compose the agent list themselves if they want it.
+        // function form can compose the agent list themselves if they want it, and
+        // {@link UNROUTABLE_INSTRUCTION} is exported for them to include.
         return fallback.systemPrompt;
     }
-    return `You are a helpful assistant. You cannot directly help with the user's request, but the following specialists are available:\n\n${agentList}\n\nPolitely let the user know what you can help with and invite them to rephrase their request.`;
+    return `You are a helpful assistant. You cannot directly help with the user's request, but the following specialists are available:\n\n${agentList}\n\nPolitely let the user know what you can help with and invite them to rephrase their request.\n\n${UNROUTABLE_INSTRUCTION}`;
 }
 /**
  * Orchestrates multiple specialist agents. Sits between `FoundationAiAssistant`
@@ -303,11 +365,28 @@ export class OrchestratingDriver extends EventTarget {
             const pinned = this.resolvePinnedAgent();
             if (!pinned)
                 this.dispatchEvent(new CustomEvent('orchestrating-start'));
-            let currentAgent = pinned !== null && pinned !== void 0 ? pinned : (yield this.classify(input, history, this.activeAgent));
+            let routed;
+            if (pinned) {
+                // `classify` is never entered on a pin, so there is no ladder to time — but the field stays
+                // unconditional across every `routing.decided`, and 0 is the honest reading: no time was
+                // spent deciding, because nothing was decided.
+                this.recordRouting('pinned', pinned, { durationMs: 0 });
+                routed = { agent: pinned, decision: 'pinned' };
+            }
+            else {
+                routed = yield this.classify(input, history, this.activeAgent);
+            }
+            let currentAgent = routed.agent;
             let isHandoff = false;
             let handoffs = 0;
             let handoffSummary = '';
             let remainingTask = '';
+            /**
+             * Specialists that have already handled part of THIS turn and handed on. Fed to each
+             * re-classify so the remaining work cannot be routed back to an agent that just declined it
+             * — see the `excludeAgents` parameter on `classify`.
+             */
+            const attempted = [];
             // The outcome of the agent turn that ENDS the loop — see the return below.
             let lastResult;
             while (true) {
@@ -323,6 +402,34 @@ export class OrchestratingDriver extends EventTarget {
                     const contextPrimer = handoffSummary
                         ? [{ role: 'user', content: `[Context from previous agent]: ${handoffSummary}` }]
                         : [];
+                    // A handoff that reaches the fallback is the one case where routing has genuinely run out
+                    // of options, and it used to be the worst-served: the fallback holds no tools (it is
+                    // denied the continuation tool as a leaf), so it was handed a remaining task phrased as
+                    // work — "debug and fix the null pointer in the event handler" — with no instruction for
+                    // what to do when nothing can. Measured (GENC-1573), it answered with three consecutive
+                    // blank turns.
+                    //
+                    // Naming the situation is what it was missing. The remaining task and the fact that no
+                    // specialist covers it are both real, useful things to tell a user, and an agent told
+                    // them plainly has something to say instead of nothing. Transient primer, so it steers
+                    // this turn without becoming a permanent instruction in the transcript.
+                    if (isFallback(currentAgent)) {
+                        // `remainingTask` is model-supplied — it arrives from `request_continuation`'s
+                        // `remaining_task` through an unvalidated cast — and this is the one primer where a
+                        // degraded input is already known to be in play, since it exists because the fallback
+                        // answered this path with three blank turns. Name the situation without the clause
+                        // rather than render "the remaining work: undefined".
+                        const work = (remainingTask === null || remainingTask === void 0 ? void 0 : remainingTask.trim()) || (handoffSummary === null || handoffSummary === void 0 ? void 0 : handoffSummary.trim());
+                        contextPrimer.push({
+                            role: 'user',
+                            content: (work
+                                ? `[Routing note]: no specialist is available for the remaining work: ${work}\n`
+                                : '[Routing note]: no specialist is available for the work that remains.\n') +
+                                'Tell the user plainly what was established, that this part falls outside what any ' +
+                                'specialist here can do, and what they could do next. Do not claim you will do it ' +
+                                'yourself, and do not return an empty response.',
+                        });
+                    }
                     // oxlint-disable-next-line no-await-in-loop
                     result = yield this.chatDriver.continueFromHistory(contextPrimer);
                 }
@@ -358,10 +465,14 @@ export class OrchestratingDriver extends EventTarget {
                 handoffSummary = result.summary;
                 remainingTask = result.remainingTask;
                 isHandoff = true;
+                if (isSpecialist(currentAgent) && !attempted.includes(currentAgent.name)) {
+                    attempted.push(currentAgent.name);
+                }
                 const updatedHistory = this.chatDriver.getHistory();
                 this.dispatchEvent(new CustomEvent('orchestrating-start'));
                 // oxlint-disable-next-line no-await-in-loop
-                currentAgent = yield this.classify(remainingTask, updatedHistory);
+                routed = yield this.classify(remainingTask, updatedHistory, undefined, attempted);
+                currentAgent = routed.agent;
             }
             // The orchestrated turn reports the outcome of the agent turn that ENDED it.
             // The hardcoded `{ reason: 'done' }` that used to live here made every
@@ -565,16 +676,85 @@ export class OrchestratingDriver extends EventTarget {
             this.activeAgent = undefined;
         });
     }
-    classify(input, history, contextAgent) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+    /**
+     * Record one routing decision on the debug timeline — what was chosen, why, what it cost, and
+     * (on a failure) what went wrong.
+     *
+     * This is the event whose absence made GENC-1573 undiagnosable. `classify` reaches the fallback
+     * by four different routes and every one of them only warned to the console; because it runs
+     * outside any ChatDriver turn it produces no `kind:'turn'` entry either, so both the decision
+     * and its spend were invisible in an exported log.
+     *
+     * `usage` is why the spend line exists at all. A classifier call is a real billed request that
+     * never enters the transcript, and `sessionUsage` is derived from the transcript — so classifier
+     * spend is absent from the session total by construction. Recording it per decision keeps it
+     * auditable and tells a reconciler exactly where the gap comes from: sum these to close it.
+     */
+    recordRouting(decision, agent, detail = {}) {
+        const { response, ballot } = detail, rest = __rest(detail, ["response", "ballot"]);
+        const usage = response ? messageUsage(response) : undefined;
+        recordMetaEvent(this.sessionKey, 'routing.decided', Object.assign(Object.assign(Object.assign(Object.assign({ decision, to: agent.name, fallback: isFallback(agent) }, (ballot ? { candidates: ballot } : {})), rest), (usage ? { usage } : {})), ((response === null || response === void 0 ? void 0 : response.model) ? { model: response.model } : {})));
+    }
+    /**
+     * The recent-conversation excerpt for the classifier prompt, bounded in size as well as in
+     * message count — see the `CLASSIFIER_MESSAGE_CHARS` docblock for why.
+     */
+    classifierTranscript(history) {
+        const lines = history
+            // `reachesProvider`, not a role test. This is fed CANONICAL history, and a classify call is a
+            // real billed provider request — so without the predicate the driver's own failure notices
+            // (`excludeFromProvider`) arrive here as the assistant's last utterance, and the loop the
+            // rest of GENC-1573 closes stays open at the one request that decides where the turn goes.
+            // It also drops the `reasoning` / `narration` splits, which are `role: 'assistant'` too and
+            // would otherwise show up as duplicate `Assistant:` lines. Reviewer catch on #2496.
+            .filter((m) => (m.role === 'user' || m.role === 'assistant') && reachesProvider(m))
+            // Blank rows need their own test: `reachesProvider` keys on role, category and the exclusion
+            // flag, never on content, so a tool-call carrier or an interaction placeholder still passes
+            // it and renders as a bare `Assistant: ` — a line that spends prompt on nothing and tells a
+            // router less than omitting it does.
+            .filter((m) => { var _a; return !!((_a = m.content) === null || _a === void 0 ? void 0 : _a.trim()); })
+            .slice(-this.classifierHistoryLength)
+            .map((m) => {
+            var _a;
+            const speaker = m.role === 'user' ? 'User' : 'Assistant';
+            const content = (_a = m.content) !== null && _a !== void 0 ? _a : '';
+            const body = content.length > CLASSIFIER_MESSAGE_CHARS
+                ? `${content.slice(0, CLASSIFIER_MESSAGE_CHARS)}…`
+                : content;
+            return `${speaker}: ${body}`;
+        });
+        // Drop from the OLDEST end if the block is still too big: the most recent message is the one
+        // being routed, so it is the last thing that may be sacrificed.
+        while (lines.length > 1 && lines.join('\n').length > CLASSIFIER_TRANSCRIPT_CHARS) {
+            lines.shift();
+        }
+        return lines.join('\n');
+    }
+    classify(input_1, history_1, contextAgent_1) {
+        return __awaiter(this, arguments, void 0, function* (input, history, contextAgent, 
+        /**
+         * Specialists to leave off the ballot — the agents that have already handled (and handed off)
+         * part of this turn. Without it a re-classify can hand the remaining work straight back to
+         * the agent that just declined it, and in the worst case ping-pong until `maxHandoffs`.
+         */
+        excludeAgents = []) {
+            var _a, _b, _c;
+            // Started before every early return, and EVERY exit below reports against it — so
+            // `durationMs` is present on every `routing.decided`, and a decision that made no call says so
+            // with a ~0ms reading rather than an absent field. Uniform on purpose: a field that is always
+            // there is far easier to document, and to trust, than a per-decision matrix of when it is.
+            const classifyStartedAt = Date.now();
             // Single-candidate short-circuits. No point asking the LLM to route
             // when there's only one viable choice. Skipped if a fallback is
             // configured — that's an explicit "escape hatch" signal from the
             // consumer, and we preserve the LLM's ability to send unrelated
             // messages there by returning -1 from select_agent.
             if (this.specialists.length === 1 && !this.fallback) {
-                return this.specialists[0];
+                const only = this.specialists[0];
+                this.recordRouting('single-candidate', only, {
+                    durationMs: Date.now() - classifyStartedAt,
+                });
+                return { agent: only, decision: 'single-candidate' };
             }
             if (this.specialists.length === 0) {
                 // No classifier-eligible specialists. If exactly one non-fallback
@@ -586,23 +766,45 @@ export class OrchestratingDriver extends EventTarget {
                 if (!this.fallback) {
                     const routable = this.agents.filter((a) => !isFallback(a));
                     if (routable.length === 1) {
-                        return routable[0];
+                        this.recordRouting('no-specialists', routable[0], {
+                            durationMs: Date.now() - classifyStartedAt,
+                        });
+                        return { agent: routable[0], decision: 'no-specialists' };
                     }
                 }
-                return (_a = this.fallback) !== null && _a !== void 0 ? _a : { name: 'Assistant', fallback: true };
+                const leaf = (_a = this.fallback) !== null && _a !== void 0 ? _a : { name: 'Assistant', fallback: true };
+                this.recordRouting('no-specialists', leaf, { durationMs: Date.now() - classifyStartedAt });
+                return { agent: leaf, decision: 'no-specialists' };
+            }
+            // The ballot for THIS classification. Indices are positions in `ballot`, not in
+            // `this.specialists`, so an exclusion cannot silently shift what an index means.
+            const ballot = excludeAgents.length
+                ? this.specialists.filter((a) => !excludeAgents.includes(a.name))
+                : this.specialists;
+            if (ballot.length === 0) {
+                // Every specialist has already had a go at this turn. Asking again can only return one of
+                // them, so go straight to the escape hatch. `durationMs` is reported even though it is ~0,
+                // because that is the documented signal for "no network call happened" — omitting it left a
+                // reader with no way to tell this record from a truncated one.
+                const leaf = (_b = this.fallback) !== null && _b !== void 0 ? _b : this.specialists[0];
+                this.recordRouting('ballot-exhausted', leaf, {
+                    excluded: excludeAgents,
+                    durationMs: Date.now() - classifyStartedAt,
+                });
+                return { agent: leaf, decision: 'ballot-exhausted' };
             }
-            const agentList = this.specialists
-                .map((a, i) => `${i}: ${a.name} — ${a.description}`)
-                .join('\n');
-            const recentMessages = history
-                .filter((m) => m.role === 'user' || m.role === 'assistant')
-                .slice(-this.classifierHistoryLength)
-                .map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`)
-                .join('\n');
-            const continuationHint = contextAgent && isSpecialist(contextAgent)
+            const agentList = ballot.map((a, i) => `${i}: ${a.name} — ${a.description}`).join('\n');
+            const recentMessages = this.classifierTranscript(history);
+            const continuationHint = contextAgent && isSpecialist(contextAgent) && !excludeAgents.includes(contextAgent.name)
                 ? `\n\nThe previous turn was handled by "${contextAgent.name}". If the new message is a refinement, correction, or continuation of that work, prefer "${contextAgent.name}" — unless the topic has clearly shifted to another specialist's domain.`
                 : '';
-            const classifierPrompt = `You are a routing classifier. Call select_agent with the index of the best matching agent for the user message. Use -1 only if the request is entirely unrelated to every agent listed — prefer the closest match when in doubt. If the request spans multiple agents, pick the one that should act first; I will re-classify and route again once that agent is done.\n\nAgents:\n${agentList}${continuationHint}${recentMessages ? `\n\nRecent conversation:\n${recentMessages}` : ''}`;
+            // Naming what has already been tried, rather than just removing it from the list, so the
+            // model can tell "nobody here covers this" from "I haven't looked hard enough" — the latter
+            // is what makes a classifier pick a poor closest match.
+            const attemptedHint = excludeAgents.length
+                ? `\n\nAlready attempted this turn and handed the work on, so not listed above: ${excludeAgents.join(', ')}. Do not expect another agent to repeat their part.`
+                : '';
+            const classifierPrompt = `You are a routing classifier. Call select_agent with the index of the best matching agent for the user message. Use -1 only if the request is entirely unrelated to every agent listed — prefer the closest match when in doubt. If the request spans multiple agents, pick the one that should act first; I will re-classify and route again once that agent is done.\n\nAgents:\n${agentList}${continuationHint}${attemptedHint}${recentMessages ? `\n\nRecent conversation:\n${recentMessages}` : ''}`;
             const routingTool = {
                 name: 'select_agent',
                 description: 'Select the most appropriate agent for the user message.',
@@ -617,12 +819,15 @@ export class OrchestratingDriver extends EventTarget {
                     },
                 },
             };
-            // True only when the classifier RAN and answered "no match" (index -1). The
-            // no-fallback apology below is gated on it: an exhausted-retries exit never
-            // earned that apology, and emitting it there put a routing excuse ahead of
-            // the real error the routed turn is about to produce.
-            let routedNoMatch = false;
+            // Which exit the loop is heading for. Was a bare `routedNoMatch` boolean; now the reason is
+            // reported on the timeline as well as gating the apology, so it has to distinguish all three
+            // of "the classifier said none of these", "it never answered", and "it could not be called".
+            let decision = 'classifier-failed';
+            let lastError;
+            let attempts = 0;
+            let lastResponse;
             for (let attempt = 0; attempt <= this.classifierRetries; attempt += 1) {
+                attempts = attempt + 1;
                 try {
                     const options = {
                         systemPrompt: classifierPrompt,
@@ -633,17 +838,22 @@ export class OrchestratingDriver extends EventTarget {
                     const classifierProvider = this.providerRegistry.default();
                     if (!classifierProvider.chat) {
                         logger.warn('OrchestratingDriver: default AI provider does not implement chat() — cannot classify.');
+                        decision = 'provider-unavailable';
                         break;
                     }
                     // oxlint-disable-next-line no-await-in-loop
                     const response = yield classifierProvider.chat([], input, options);
-                    const tc = (_b = response.toolCalls) === null || _b === void 0 ? void 0 : _b[0];
+                    lastResponse = response;
+                    const tc = (_c = response.toolCalls) === null || _c === void 0 ? void 0 : _c[0];
                     const index = (tc === null || tc === void 0 ? void 0 : tc.name) === 'select_agent' ? tc.args.agent_index : -1;
-                    if (index >= 0 && index < this.specialists.length) {
-                        return this.specialists[index];
+                    if (index >= 0 && index < ballot.length) {
+                        const chosen = ballot[index];
+                        this.recordRouting('classified', chosen, Object.assign({ index,
+                            attempts, durationMs: Date.now() - classifyStartedAt, response, ballot: ballot.map((a) => a.name) }, (excludeAgents.length ? { excluded: excludeAgents } : {})));
+                        return { agent: chosen, decision: 'classified' };
                     }
                     // index === -1 — fall through to fallback
-                    routedNoMatch = true;
+                    decision = 'no-match';
                     break;
                 }
                 catch (e) {
@@ -655,24 +865,33 @@ export class OrchestratingDriver extends EventTarget {
                     // narrow: a generic classifier failure must still retry and fall back.
                     if (e instanceof BudgetExhaustedError)
                         throw e;
+                    lastError = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
                     logger.warn(`OrchestratingDriver: classifier attempt ${attempt + 1} failed:`, e);
                     if (attempt === this.classifierRetries) {
                         logger.error('OrchestratingDriver: classifier failed after all retries, using fallback');
                     }
                 }
             }
-            if (this.fallback)
-                return this.fallback;
+            // Everything from here reaches the fallback (or, with none configured, a no-op specialist).
+            // `durationMs` is the whole ladder: a decision that reached this point in a few tens of
+            // milliseconds did not make a network call at all, and that gap between "the classifier
+            // declined" and "the classifier never ran" is precisely what an exported log could not show.
+            const routingDetail = Object.assign(Object.assign(Object.assign({ attempts, durationMs: Date.now() - classifyStartedAt, ballot: ballot.map((a) => a.name) }, (lastError ? { error: lastError } : {})), (lastResponse ? { response: lastResponse } : {})), (excludeAgents.length ? { excluded: excludeAgents } : {}));
+            if (this.fallback) {
+                this.recordRouting(decision, this.fallback, routingDetail);
+                return { agent: this.fallback, decision };
+            }
             // No fallback configured. Route to the first specialist as a no-op — but
             // only APOLOGISE when the classifier actually said "none of these". On an
             // exhausted-retries exit the classifier never expressed an opinion, so the
             // apology would be a routing excuse the user reads immediately above the
             // real error that turn is about to produce.
-            if (routedNoMatch) {
+            if (decision === 'no-match') {
                 const specialistNames = this.specialists.map((s) => s.name).join(', ');
                 this.appendInlineMessage(`I'm not sure how to help with that. I can assist with: ${specialistNames}.`);
             }
-            return this.specialists[0];
+            this.recordRouting(decision, this.specialists[0], routingDetail);
+            return { agent: this.specialists[0], decision };
         });
     }
     /**
@@ -695,11 +914,22 @@ export class OrchestratingDriver extends EventTarget {
         }
         return match;
     }
+    /**
+     * Append prose the ORCHESTRATOR wrote — the handoff cap, the no-specialist apology. Flagged
+     * `excludeFromProvider` for the same reason the driver's own notices are: it is not something a
+     * model said, and feeding it back invites the model to echo it. See
+     * `ChatMessage.excludeFromProvider`.
+     */
     appendInlineMessage(content) {
         const history = this.chatDriver.getHistory();
         this.chatDriver.loadHistory([
             ...history,
-            { role: 'assistant', content, timestamp: new Date().toISOString() },
+            {
+                role: 'assistant',
+                content,
+                timestamp: new Date().toISOString(),
+                excludeFromProvider: true,
+            },
         ]);
         this.dispatchEvent(new CustomEvent('history-updated', { detail: this.chatDriver.getHistory() }));
     }

package/dist/esm/config/fallback-agents.js

@@ -17,10 +17,21 @@ export const friendlyFallbackAgent = {
  * elaboration. The `{{agents}}` placeholder is replaced at runtime by
  * `OrchestratingDriver` with the generated specialist list.
  *
+ * The `{{unroutable}}` placeholder positions `UNROUTABLE_INSTRUCTION` — the framework's
+ * instruction for a substantive request no specialist covers, which is otherwise APPENDED to a
+ * string-form prompt. Positioned rather than appended for one reason: this preset's whole point is
+ * brevity, and appended text would be the last thing the model reads. Putting the block above the
+ * brevity rule leaves "a single short sentence" with the recency, so the two compose instead of
+ * competing. A prompt whose tone rules matter should do the same.
+ *
  * @beta
  */
 export const strictFallbackAgent = {
     name: 'Assistant',
     fallback: true,
-    systemPrompt: `You are a concise assistant. The user's request is outside your scope. Respond with a single short sentence stating what you can assist with. Do not elaborate. The available specialists are: {{agents}}.`,
+    systemPrompt: `You are a concise assistant. The user's request is outside your scope. The available specialists are: {{agents}}.
+
+{{unroutable}}
+
+Answer in a single short sentence. Do not elaborate.`,
 };

package/dist/esm/state/debug-event-log.js

@@ -57,6 +57,9 @@ export const META_EVENT_IMPORTANCE = {
     'tool.unresolved': 'normal',
     'subagent.started': 'normal',
     'subagent.completed': 'normal',
+    // One per routing decision, with what the classifier answered and what the call cost. Same
+    // level as the handoff it produces: you read them together to follow how a turn was routed.
+    'routing.decided': 'normal',
     'agent.handoff': 'normal',
     'agent.pinned': 'normal',
     'agent.unpinned': 'normal',
@@ -219,11 +222,13 @@ export const DEBUG_LOG_README = [
     "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
     "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",
     "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.",
-    'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted/provider-refused/context-exhausted, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, for context-exhausted the estimated contextTokens against the guard that stopped the turn plus the iterations reached — the driver ending a runaway tool loop at the edge of the context window rather than issuing a request the provider would reject, so the transcript survives intact and can still be compacted, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted/provider_refused/context_exhausted; budget_exhausted, provider_refused and context_exhausted are all terminal for the PARENT turn too — the parent stops rather than calling the model again into the same wall), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+    'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted/provider-refused/context-exhausted, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, for context-exhausted the estimated contextTokens against the guard that stopped the turn plus the iterations reached — the driver ending a runaway tool loop at the edge of the context window rather than issuing a request the provider would reject, so the transcript survives intact and can still be compacted, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted/provider_refused/context_exhausted; budget_exhausted, provider_refused and context_exhausted are all terminal for the PARENT turn too — the parent stops rather than calling the model again into the same wall), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), routing.decided (ONE PER ROUTING DECISION — see its own paragraph below), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
     'Sub-agent meta events: a sub-agent\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `"<parent> › <sub-agent>"` breadcrumb that composes when nested (e.g. `"UI Builder › Planner › Grounding"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\'s span.',
     "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
     'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',
-    'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it.',
+    "kind:'event' type 'routing.decided' — how ONE turn was routed, emitted by the orchestrating driver before the agent runs (and again after every handoff). `decision` is why that agent was chosen: 'classified' (the classifier ran and picked one), 'no-match' (it ran and answered -1 — nothing listed covers the request), 'ballot-exhausted' (every eligible specialist had already handed off this turn, so the ballot was empty and NO call was made — distinct from 'no-match', where one ran and declined), 'pinned' (a user pin or an active stateful flow owned the turn, so no call was made), 'single-candidate'/'no-specialists' (configuration left nothing to decide), 'provider-unavailable' (the registry default exposes no chat()), 'classifier-failed' (every attempt threw — `error` carries the last one). `to` names the agent and `fallback` says whether that agent is the fallback. `candidates` is what was actually ON THE BALLOT, in ballot order, so `index` — the classifier's own answer — indexes it directly; `excluded` names the specialists left off because they already handed off this turn, so the full eligible set is `candidates` ∪ `excluded`. `candidates` is absent on the four decisions that put nothing to a vote — 'pinned', 'single-candidate', 'no-specialists', 'ballot-exhausted'. It IS present on 'provider-unavailable', which is not an exception worth removing: the ballot was built there, it simply never got sent. `attempts` covers the retry ladder. `durationMs` is on EVERY routing.decided, and is the field to read when a decision looks wrong: the four decisions that can reach the fallback are told apart by the clock as much as by their name, because a fallback routing that resolved in tens of milliseconds made no network call at all whatever its `decision` says.",
+    "kind:'event' type 'routing.decided'.`usage` — what that classifier call cost, in the same four-bucket + costUsd shape as `sessionUsage`, plus `model`. Absent on the decisions that make no call (see 'pinned' and the configuration ones). THIS SPEND IS NOT IN `sessionUsage`: a classifier call never enters the transcript and `sessionUsage` is derived from the transcript, so classifier cost is missing from the session total by construction, not by accident. Sum these events to close that gap — it is the one component of a session's real spend that the totals cannot see.",
+    'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it. For a turn that went to the wrong agent, read its routing.decided first — `decision` says whether anything was actually asked.',
 ];
 /**
  * Removes all entries. Exposed for test isolation only — not part of the

package/dist/esm/utils/context-tokens.js

@@ -42,16 +42,40 @@ export const COMPACTION_SUMMARY_TOKEN_ESTIMATE = 1200;
  * `assistant(toolCalls)` and its results must not be mistaken for a safe split.
  *
  * Mirrors what the request-build chokepoint and the transports actually send:
- * `system-event` / `synthetic-user` are display-only rows, and the
+ * `system-event` / `synthetic-user` are display-only rows, the
  * reasoning/narration splits (GENC-1410, plus the legacy `thinking` flag they
- * superseded) are skipped when building the request. Counting any of them would
- * inflate every estimate against a prompt that never carries them.
+ * superseded) are skipped when building the request, and `excludeFromProvider`
+ * marks prose the driver wrote rather than the model (GENC-1573). Counting any
+ * of them would inflate every estimate against a prompt that never carries
+ * them.
+ *
+ * Keep this list aligned with the skip block in `toAnthropicMessages` /
+ * `toGeminiContents` — it exists to predict them.
+ *
+ * SCOPED TO WHAT CANONICAL HISTORY CARRIES, though, which is less than the wire
+ * decides. This runs against stored history, whereas `transformHistoryForAgent`
+ * is applied later and only at the request-build site — so neither of the things
+ * that transform does is visible here: the `excludeFromProvider` it stamps on
+ * another agent's `toolResult`, nor the foreign `tool_use` blocks it flattens to
+ * prose. In the session quoted in its docblock that is 389 `tool_use` + 313
+ * `tool_result` payloads still counted in full against a prompt that no longer
+ * carries them. So for `excludeFromProvider` this predicate is exact only for the
+ * driver-authored notices that carry the flag in stored history.
+ *
+ * The divergence predates the flag — masking already emptied `args` after
+ * estimation — and is left as is deliberately: the estimator over-counts, which
+ * errs towards compacting early rather than towards an over-limit request. Noted
+ * because the next person to trust this as an exact mirror will be debugging a
+ * multi-agent session that compacts sooner than they expect. Reviewer catch on
+ * #2496.
  */
 export function reachesProvider(m) {
     if (m.role === 'system-event' || m.role === 'synthetic-user')
         return false;
     if (m.category === 'reasoning' || m.category === 'narration')
         return false;
+    if (m.excludeFromProvider)
+        return false;
     return !m.thinking;
 }
 /** Images on a message — both the user-attached kind and the kind a tool handed back. */