@genesislcap/ai-assistant 15.20.2 → 15.21.1

package/dist/chat-driver.cjs

@@ -27,10 +27,12 @@ __export(chat_driver_node_exports, {
   AnthropicTransport: () => AnthropicTransport,
   ChatDriver: () => ChatDriver,
   DEFAULT_PROVIDER_REFUSED_MESSAGE: () => DEFAULT_PROVIDER_REFUSED_MESSAGE,
+  EMPTY_RESPONSE_NUDGE: () => EMPTY_RESPONSE_NUDGE,
   GEMINI_CACHED_INPUT_MULTIPLIER: () => GEMINI_CACHED_INPUT_MULTIPLIER,
   GEMINI_LONG_CONTEXT_THRESHOLD: () => GEMINI_LONG_CONTEXT_THRESHOLD,
   GeminiProvider: () => GeminiProvider,
   GeminiTransport: () => GeminiTransport,
+  MALFORMED_CALL_NUDGE: () => MALFORMED_CALL_NUDGE,
   MutableAIProviderRegistry: () => MutableAIProviderRegistry,
   NOOP_ACTIVITY_BUS: () => NOOP_ACTIVITY_BUS,
   OrchestratingDriver: () => OrchestratingDriver,
@@ -39,6 +41,8 @@ __export(chat_driver_node_exports, {
   REQUEST_CONTINUATION_TOOL: () => REQUEST_CONTINUATION_TOOL,
   SUPPORTED_ANTHROPIC_MODEL_IDS: () => SUPPORTED_ANTHROPIC_MODEL_IDS,
   SUPPORTED_GEMINI_MODEL_IDS: () => SUPPORTED_GEMINI_MODEL_IDS,
+  UNROUTABLE_INSTRUCTION: () => UNROUTABLE_INSTRUCTION,
+  UNROUTABLE_PLACEHOLDER: () => UNROUTABLE_PLACEHOLDER,
   addUsage: () => addUsage,
   agenticActivityBus: () => agenticActivityBus,
   anthropicRatesFor: () => anthropicRatesFor,
@@ -2240,7 +2244,8 @@ ${att.content}` });
       return { images, texts };
     };
     for (const msg of history) {
-      if (msg.role === "system" || msg.role === "system-event" || msg.role === "synthetic-user" || msg.role === "compacted-summary" || msg.category === "reasoning" || msg.category === "narration" || msg.thinking)
+      if (msg.role === "system" || msg.role === "system-event" || msg.role === "synthetic-user" || msg.role === "compacted-summary" || msg.category === "reasoning" || msg.category === "narration" || // Driver-authored prose no model produced — see ChatMessage.excludeFromProvider.
+      msg.excludeFromProvider || msg.thinking)
         continue;
       if (msg.toolResult) {
         const resultImages = (_a = msg.toolResult.attachments) !== null && _a !== void 0 ? _a : [];
@@ -2503,12 +2508,16 @@ ${att.content}` });
     if (cost != null)
       base.cost = cost;
     base.model = servingModel;
-    if (response.stop_reason === "max_tokens") {
-      base.responseMeta = { finishReason: "max_tokens" };
-    }
-    if (response.stop_reason === "refusal") {
-      base.responseMeta = { finishReason: "refusal" };
-    }
+    const responseMeta = {
+      parts: {
+        functionCall: blocks.filter((b) => b.type === "tool_use").length,
+        thought: blocks.filter((b) => b.type === "thinking" || b.type === "redacted_thinking").length,
+        text: blocks.filter((b) => b.type === "text").length
+      }
+    };
+    if (response.stop_reason)
+      responseMeta.finishReason = response.stop_reason;
+    base.responseMeta = responseMeta;
     return base;
   }
   buildEndpoint() {
@@ -3057,7 +3066,8 @@ var GeminiTransport = class _GeminiTransport {
     const contents = [];
     const toolCallNameById = /* @__PURE__ */ new Map();
     for (const msg of history) {
-      if (msg.role === "system" || msg.role === "system-event" || msg.role === "synthetic-user" || msg.role === "compacted-summary" || msg.category === "reasoning" || msg.category === "narration" || msg.thinking)
+      if (msg.role === "system" || msg.role === "system-event" || msg.role === "synthetic-user" || msg.role === "compacted-summary" || msg.category === "reasoning" || msg.category === "narration" || // Driver-authored prose no model produced — see ChatMessage.excludeFromProvider.
+      msg.excludeFromProvider || msg.thinking)
         continue;
       const role = msg.role === "user" ? "user" : "model";
       if (msg.toolResult) {
@@ -3642,6 +3652,9 @@ var 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",
@@ -3803,6 +3816,7 @@ var COMPACTION_SUMMARY_TOKEN_ESTIMATE = 1200;
 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;
 }
 function imageCount(m) {
@@ -4132,10 +4146,27 @@ function maskToolPayload(msg) {
   }
   return msg;
 }
+function foreignToolCallText(msg) {
+  const names = (msg.toolCalls ?? []).map((tc) => tc.name).join(", ");
+  const trace = names ? `[Earlier tool call: ${names}]` : "";
+  return msg.content && trace ? `${msg.content}
+${trace}` : msg.content || trace;
+}
 function transformHistoryForAgent(history, agentName) {
+  const isForeign = (msg) => !!msg.agentName && msg.agentName !== agentName;
+  const foreignCallIds = /* @__PURE__ */ new Set();
+  for (const msg of history) {
+    if (!isForeign(msg)) continue;
+    for (const tc of msg.toolCalls ?? []) foreignCallIds.add(tc.id);
+    if (msg.toolResult) foreignCallIds.add(msg.toolResult.toolCallId);
+  }
   return history.map((msg) => {
-    if (!msg.agentName || msg.agentName === agentName) return msg;
-    return maskToolPayload(msg);
+    const pairIsForeign = (msg.toolCalls ?? []).some((tc) => foreignCallIds.has(tc.id)) || (msg.toolResult ? foreignCallIds.has(msg.toolResult.toolCallId) : false);
+    if (!pairIsForeign) return msg;
+    if (msg.toolResult) {
+      return { ...maskToolPayload(msg), excludeFromProvider: true };
+    }
+    return { ...msg, content: foreignToolCallText(msg), toolCalls: void 0 };
   });
 }
 function applyHistoryCap(history, cap) {
@@ -4339,6 +4370,8 @@ var DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
 var MAX_STALE_TOOL_CALLS = DEFAULT_MAX_UNKNOWN_TOOL_CALLS * 2;
 var MAX_MALFORMED_RETRIES = 5;
 var MAX_EMPTY_RESPONSE_RETRIES = 3;
+var MALFORMED_CALL_NUDGE = "IMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools.";
+var EMPTY_RESPONSE_NUDGE = "IMPORTANT: Your previous attempt returned nothing at all, which is never a valid response. Answer the user's last message now, in prose \u2014 even if all you can honestly say is that you cannot help with it and why. If a tool is the right way to answer, call it. Do not return an empty response.";
 var MAX_SETUP_TRANSPORT_RETRIES = 3;
 var SUGGESTIONS_HISTORY_WINDOW = 8;
 var HARVESTED_SUBAGENT_EVENTS = /* @__PURE__ */ new Set([
@@ -4725,7 +4758,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
       spentUsd: e.spentUsd,
       isSubAgent: this.isSubAgent
     });
-    this.appendToHistory({ role: "assistant", content: this.budgetExhaustedBubble(e) });
+    this.appendDriverNotice(this.budgetExhaustedBubble(e));
     return this.turnDone("budget-exhausted", budgetDetailOf(e));
   }
   /**
@@ -4761,7 +4794,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
       upstreamType: e.upstreamType,
       isSubAgent: this.isSubAgent
     });
-    this.appendToHistory({ role: "assistant", content: this.providerRefusedBubble() });
+    this.appendDriverNotice(this.providerRefusedBubble());
     return this.turnDone("provider-refused", void 0, detail);
   }
   /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
@@ -5285,12 +5318,12 @@ Output format (strict):
       summaryText = (await defaultProvider.prompt(userMessage, { systemPrompt }))?.trim() ?? "";
     } catch (e) {
       logger2.warn(`ChatDriver: compaction summary failed: ${e instanceof Error ? e.message : e}`);
-      this.appendToHistory({ role: "assistant", content: failMessage });
+      this.appendDriverNotice(failMessage);
       return null;
     }
     if (!summaryText) {
       logger2.warn("ChatDriver: compaction summary was empty; leaving history untouched");
-      this.appendToHistory({ role: "assistant", content: failMessage });
+      this.appendDriverNotice(failMessage);
       return null;
     }
     let tokensBefore;
@@ -5607,10 +5640,9 @@ Output format (strict):
         name: e instanceof Error ? e.name : void 0,
         message: e instanceof Error ? e.message : String(e)
       });
-      this.appendToHistory({
-        role: "assistant",
-        content: "Sorry, something went wrong on my end. Please try again in a moment."
-      });
+      this.appendDriverNotice(
+        "Sorry, something went wrong on my end. Please try again in a moment."
+      );
       result = this.turnDone("exception");
       return result;
     } finally {
@@ -5872,10 +5904,9 @@ Output format (strict):
         name: e instanceof Error ? e.name : void 0,
         message: e instanceof Error ? e.message : String(e)
       });
-      this.appendToHistory({
-        role: "assistant",
-        content: "Sorry, something went wrong on my end. Please try again in a moment."
-      });
+      this.appendDriverNotice(
+        "Sorry, something went wrong on my end. Please try again in a moment."
+      );
       result = this.turnDone("exception");
       return result;
     } finally {
@@ -6054,7 +6085,7 @@ Output format (strict):
         if (this.isSubAgent) {
           this.failSubAgent("provider_refused", void 0, this.providerRefusedDetail);
         } else {
-          this.appendToHistory({ role: "assistant", content: this.providerRefusedBubble() });
+          this.appendDriverNotice(this.providerRefusedBubble());
         }
         return this.turnDone("provider-refused", void 0, this.providerRefusedDetail);
       }
@@ -6079,10 +6110,7 @@ Output format (strict):
         if (this.isSubAgent) {
           this.failSubAgent("budget_exhausted", this.budgetWallDetail);
         } else {
-          this.appendToHistory({
-            role: "assistant",
-            content: this.budgetExhaustedBubble(this.budgetWallDetail)
-          });
+          this.appendDriverNotice(this.budgetExhaustedBubble(this.budgetWallDetail));
         }
         return this.turnDone("budget-exhausted", this.budgetWallDetail);
       }
@@ -6119,7 +6147,11 @@ Output format (strict):
         this.activeAgentLabel = await this.displayName(promptCtx);
       }
       const foldSuffix = this.buildFoldSystemPromptSuffix();
-      const retryNudge = malformedAttempts > 0 ? "\n\nIMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools." : emptyResponseAttempts > 0 ? "\n\nIMPORTANT: You must respond to the user's message. Call the appropriate tool or provide a text response \u2014 do not return an empty response." : "";
+      const retryNudge = malformedAttempts > 0 ? `
+
+${MALFORMED_CALL_NUDGE}` : emptyResponseAttempts > 0 ? `
+
+${EMPTY_RESPONSE_NUDGE}` : "";
       const frameworkSystemSuffix = `${foldSuffix}${retryNudge}`;
       const primer = normalizeForProvider([
         ...this.primerHistory ?? [],
@@ -6243,10 +6275,9 @@ ${tailBody}
         if (this.isSubAgent) {
           this.failSubAgent("context_exhausted");
         } else {
-          this.appendToHistory({
-            role: "assistant",
-            content: "I had to stop here \u2014 this conversation has filled the available context. Compact it to free up room, then ask me to continue."
-          });
+          this.appendDriverNotice(
+            "I had to stop here \u2014 this conversation has filled the available context. Compact it to free up room, then ask me to continue."
+          );
         }
         return this.turnDone("context-exhausted");
       }
@@ -6281,10 +6312,9 @@ ${tailBody}
           if (this.isSubAgent) {
             this.failSubAgent("malformed_tool_call");
           } else {
-            this.appendToHistory({
-              role: "assistant",
-              content: "While working on your request, I repeatedly called my tools incorrectly. This often works on a second try \u2014 would you like me to try again? If it happens again, try breaking your request into smaller steps."
-            });
+            this.appendDriverNotice(
+              "While working on your request, I repeatedly called my tools incorrectly. This often works on a second try \u2014 would you like me to try again? If it happens again, try breaking your request into smaller steps."
+            );
           }
           return this.turnDone("malformed-function-call");
         }
@@ -6302,10 +6332,9 @@ ${tailBody}
           if (this.isSubAgent) {
             this.failSubAgent("response_truncated");
           } else {
-            this.appendToHistory({
-              role: "assistant",
-              content: "My response was cut off because a single step reached the model output limit. This usually means one step tried to produce too much at once \u2014 try breaking your request into smaller steps."
-            });
+            this.appendDriverNotice(
+              "My response was cut off because a single step reached the model output limit. This usually means one step tried to produce too much at once \u2014 try breaking your request into smaller steps."
+            );
           }
           return this.turnDone("response-truncated");
         }
@@ -6323,10 +6352,7 @@ ${tailBody}
           if (this.isSubAgent) {
             this.failSubAgent("context_exhausted");
           } else {
-            this.appendToHistory({
-              role: "assistant",
-              content: DEFAULT_CONTEXT_OVERFLOW_MESSAGE
-            });
+            this.appendDriverNotice(DEFAULT_CONTEXT_OVERFLOW_MESSAGE);
           }
           return this.turnDone("context-exhausted");
         }
@@ -6379,10 +6405,9 @@ ${tailBody}
           if (this.isSubAgent) {
             this.failSubAgent("timeout");
           } else {
-            this.appendToHistory({
-              role: "assistant",
-              content: "The request timed out. You can ask me to try again, or break this into a smaller step."
-            });
+            this.appendDriverNotice(
+              "The request timed out. You can ask me to try again, or break this into a smaller step."
+            );
           }
           return this.turnDone("exception");
         }
@@ -6422,6 +6447,11 @@ ${tailBody}
             provider: this.lastResolvedProviderName,
             attempt: emptyResponseAttempts,
             maxAttempts: MAX_EMPTY_RESPONSE_RETRIES,
+            // How many tools the agent was holding. Every empty response in the session that
+            // motivated this (GENC-1573) came from an agent with ZERO — a tool-less agent asked
+            // something its prompt gives it no instruction for has nothing it is allowed to do,
+            // and reads as a model fault unless this number is on the record.
+            toolCount: this.toolDefinitions.length,
             // Provider diagnostic (Gemini: finishReason, thoughtsTokens, parts,
             // blockReason) so the timeline shows *why* the turn came back blank —
             // e.g. a high thoughtsTokens with a 'STOP' finish is "thought, then
@@ -6439,16 +6469,18 @@ ${tailBody}
           agent: this.activeAgentName,
           provider: this.lastResolvedProviderName,
           attempts: emptyResponseAttempts,
+          // See the retry above: a zero here says the agent had no tools, which is most of the
+          // explanation for a blank turn and is otherwise invisible.
+          toolCount: this.toolDefinitions.length,
           isSubAgent: this.isSubAgent,
           ...response.responseMeta
         });
         if (this.isSubAgent) {
           this.failSubAgent(isRefusal ? "refusal" : "empty_response");
         } else {
-          this.appendToHistory({
-            role: "assistant",
-            content: isRefusal ? "This request was declined. Try rephrasing it, or breaking it into smaller steps." : "While working on your request, I repeatedly generated a blank response. This often works on a second try \u2014 would you like me to try again? If it happens again, try breaking your request into smaller steps."
-          });
+          this.appendDriverNotice(
+            isRefusal ? "This request was declined. Try rephrasing it, or breaking it into smaller steps." : "While working on your request, I repeatedly generated a blank response. This often works on a second try \u2014 would you like me to try again? If it happens again, try breaking your request into smaller steps."
+          );
         }
         return this.turnDone(failureReason2);
       } else {
@@ -6753,10 +6785,9 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
         if (this.isSubAgent) {
           this.failSubAgent("unknown_tool_limit");
         } else {
-          this.appendToHistory({
-            role: "assistant",
-            content: "I'm sorry, I repeatedly tried to use tools that aren't available to me, so I couldn't complete that. If a 'Download agent log' option appears in the Settings (cog) menu, you can download the log and share it with whoever set up this assistant to help fix the issue."
-          });
+          this.appendDriverNotice(
+            "I'm sorry, I repeatedly tried to use tools that aren't available to me, so I couldn't complete that. If a 'Download agent log' option appears in the Settings (cog) menu, you can download the log and share it with whoever set up this assistant to help fix the issue."
+          );
         }
         return this.turnDone("unknown-tool-limit");
       }
@@ -6782,15 +6813,33 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
       if (this.isSubAgent) {
         this.failSubAgent("max_iterations");
       } else {
-        this.appendToHistory({
-          role: "assistant",
-          content: "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off."
-        });
+        this.appendDriverNotice(
+          "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off."
+        );
       }
       failureReason = "max-iterations";
     }
     return this.turnDone(failureReason);
   }
+  /**
+   * Append prose the DRIVER wrote rather than the model — a failure notice, a limit explanation,
+   * the budget wall. Renders as an ordinary assistant bubble and is flagged
+   * `excludeFromProvider`, so it never re-enters the next request.
+   *
+   * Every such notice must go through here. Written as one funnel rather than a flag repeated at
+   * eleven call sites because the failure mode is silent: a notice that keeps the flag reads
+   * identically in the transcript to one that loses it, and the damage only shows up a turn later
+   * as the model echoing its own error message. Measured (GENC-1573): with the empty-response
+   * notice in history, the next turn reproduced it verbatim in 45 output tokens — succeeding,
+   * with no retry and no `turn.error`, while still showing the user a failure. From there the
+   * loop sustains itself whether or not the model answers, which is why "try again" never worked.
+   *
+   * Not for anything the model produced, and not for a widget/interaction message: those are real
+   * turn content and the model must keep seeing them.
+   */
+  appendDriverNotice(content) {
+    this.appendToHistory({ role: "assistant", content, excludeFromProvider: true });
+  }
   appendToHistory(message) {
     const tagged = {
       ...message,
@@ -6815,6 +6864,8 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
 var DEFAULT_MAX_HANDOFFS = 3;
 var DEFAULT_CLASSIFIER_HISTORY_LENGTH = 4;
 var DEFAULT_CLASSIFIER_RETRIES = 2;
+var CLASSIFIER_MESSAGE_CHARS = 600;
+var CLASSIFIER_TRANSCRIPT_CHARS = 3e3;
 var 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 \u2014 another specialist will be selected automatically.",
@@ -6839,10 +6890,19 @@ function isSpecialist(agent) {
 function isFallback(agent) {
   return agent.fallback === true;
 }
+var UNROUTABLE_PLACEHOLDER = "{{unroutable}}";
+var 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 \u2014 "fix it", "try again", "why?" \u2014 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}
+
+${UNROUTABLE_INSTRUCTION}`;
   }
   if (typeof fallback.systemPrompt === "function") {
     return fallback.systemPrompt;
@@ -6851,7 +6911,9 @@ function buildFallbackSystemPrompt(fallback, specialists) {
 
 ${agentList}
 
-Politely let the user know what you can help with and invite them to rephrase their request.`;
+Politely let the user know what you can help with and invite them to rephrase their request.
+
+${UNROUTABLE_INSTRUCTION}`;
 }
 var OrchestratingDriver = class extends EventTarget {
   constructor(providerRegistry, agents, options = {}) {
@@ -7082,11 +7144,19 @@ var OrchestratingDriver = class extends EventTarget {
     );
     const pinned = this.resolvePinnedAgent();
     if (!pinned) this.dispatchEvent(new CustomEvent("orchestrating-start"));
-    let currentAgent = pinned ?? await this.classify(input, history, this.activeAgent);
+    let routed;
+    if (pinned) {
+      this.recordRouting("pinned", pinned, { durationMs: 0 });
+      routed = { agent: pinned, decision: "pinned" };
+    } else {
+      routed = await this.classify(input, history, this.activeAgent);
+    }
+    let currentAgent = routed.agent;
     let isHandoff = false;
     let handoffs = 0;
     let handoffSummary = "";
     let remainingTask = "";
+    const attempted = [];
     let lastResult;
     while (true) {
       if (this.cancelled) break;
@@ -7094,6 +7164,14 @@ var OrchestratingDriver = class extends EventTarget {
       let result;
       if (isHandoff) {
         const contextPrimer = handoffSummary ? [{ role: "user", content: `[Context from previous agent]: ${handoffSummary}` }] : [];
+        if (isFallback(currentAgent)) {
+          const work = remainingTask?.trim() || handoffSummary?.trim();
+          contextPrimer.push({
+            role: "user",
+            content: (work ? `[Routing note]: no specialist is available for the remaining work: ${work}
+` : "[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."
+          });
+        }
         result = await this.chatDriver.continueFromHistory(contextPrimer);
       } else {
         this.userMessageAppended = true;
@@ -7117,9 +7195,13 @@ var OrchestratingDriver = class 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"));
-      currentAgent = await this.classify(remainingTask, updatedHistory);
+      routed = await this.classify(remainingTask, updatedHistory, void 0, attempted);
+      currentAgent = routed.agent;
     }
     return lastResult?.reason === "done" ? lastResult : { reason: "done" };
   }
@@ -7265,28 +7347,99 @@ var OrchestratingDriver = class extends EventTarget {
     this.chatDriver.dispose();
     this.activeAgent = void 0;
   }
-  async classify(input, history, contextAgent) {
+  /**
+   * 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, ...rest } = detail;
+    const usage = response ? messageUsage(response) : void 0;
+    recordMetaEvent(this.sessionKey, "routing.decided", {
+      decision,
+      to: agent.name,
+      fallback: isFallback(agent),
+      // The BALLOT, not `this.specialists`. `index` is a position in the ballot (see its
+      // construction in `classify`), so publishing the unfiltered specialist list beside it made
+      // `candidates[index]` resolve to the wrong agent whenever `excluded` was non-empty — and the
+      // README sentence invited exactly that join. `this.specialists` stays recoverable as
+      // `candidates ∪ excluded`. Absent where nothing was put to a vote, which is more truthful
+      // than a full list. Reviewer catch on #2496.
+      ...ballot ? { candidates: ballot } : {},
+      ...rest,
+      ...usage ? { usage } : {},
+      ...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.filter((m) => (m.role === "user" || m.role === "assistant") && reachesProvider(m)).filter((m) => !!m.content?.trim()).slice(-this.classifierHistoryLength).map((m) => {
+      const speaker = m.role === "user" ? "User" : "Assistant";
+      const content = m.content ?? "";
+      const body = content.length > CLASSIFIER_MESSAGE_CHARS ? `${content.slice(0, CLASSIFIER_MESSAGE_CHARS)}\u2026` : content;
+      return `${speaker}: ${body}`;
+    });
+    while (lines.length > 1 && lines.join("\n").length > CLASSIFIER_TRANSCRIPT_CHARS) {
+      lines.shift();
+    }
+    return lines.join("\n");
+  }
+  async classify(input, history, contextAgent, excludeAgents = []) {
+    const classifyStartedAt = Date.now();
     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) {
       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 this.fallback ?? { name: "Assistant", fallback: true };
+      const leaf = this.fallback ?? { name: "Assistant", fallback: true };
+      this.recordRouting("no-specialists", leaf, { durationMs: Date.now() - classifyStartedAt });
+      return { agent: leaf, decision: "no-specialists" };
     }
-    const agentList = this.specialists.map((a, i) => `${i}: ${a.name} \u2014 ${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 ballot = excludeAgents.length ? this.specialists.filter((a) => !excludeAgents.includes(a.name)) : this.specialists;
+    if (ballot.length === 0) {
+      const leaf = this.fallback ?? this.specialists[0];
+      this.recordRouting("ballot-exhausted", leaf, {
+        excluded: excludeAgents,
+        durationMs: Date.now() - classifyStartedAt
+      });
+      return { agent: leaf, decision: "ballot-exhausted" };
+    }
+    const agentList = ballot.map((a, i) => `${i}: ${a.name} \u2014 ${a.description}`).join("\n");
+    const recentMessages = this.classifierTranscript(history);
+    const continuationHint = contextAgent && isSpecialist(contextAgent) && !excludeAgents.includes(contextAgent.name) ? `
 
 The previous turn was handled by "${contextAgent.name}". If the new message is a refinement, correction, or continuation of that work, prefer "${contextAgent.name}" \u2014 unless the topic has clearly shifted to another specialist's domain.` : "";
+    const attemptedHint = excludeAgents.length ? `
+
+Already 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 \u2014 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.
 
 Agents:
-${agentList}${continuationHint}${recentMessages ? `
+${agentList}${continuationHint}${attemptedHint}${recentMessages ? `
 
 Recent conversation:
 ${recentMessages}` : ""}`;
@@ -7304,8 +7457,12 @@ ${recentMessages}` : ""}`;
         }
       }
     };
-    let routedNoMatch = false;
+    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,
@@ -7316,32 +7473,56 @@ ${recentMessages}` : ""}`;
           logger2.warn(
             "OrchestratingDriver: default AI provider does not implement chat() \u2014 cannot classify."
           );
+          decision = "provider-unavailable";
           break;
         }
         const response = await classifierProvider.chat([], input, options);
+        lastResponse = response;
         const tc = response.toolCalls?.[0];
         const index = 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, {
+            index,
+            attempts,
+            durationMs: Date.now() - classifyStartedAt,
+            response,
+            ballot: ballot.map((a) => a.name),
+            ...excludeAgents.length ? { excluded: excludeAgents } : {}
+          });
+          return { agent: chosen, decision: "classified" };
         }
-        routedNoMatch = true;
+        decision = "no-match";
         break;
       } catch (e) {
         if (e instanceof BudgetExhaustedError) throw e;
+        lastError = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
         logger2.warn(`OrchestratingDriver: classifier attempt ${attempt + 1} failed:`, e);
         if (attempt === this.classifierRetries) {
           logger2.error("OrchestratingDriver: classifier failed after all retries, using fallback");
         }
       }
     }
-    if (this.fallback) return this.fallback;
-    if (routedNoMatch) {
+    const routingDetail = {
+      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 };
+    }
+    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 };
   }
   /**
    * Returns the agent that the current turn is locked to, if any. Flow-owner
@@ -7363,11 +7544,22 @@ ${recentMessages}` : ""}`;
     }
     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: (/* @__PURE__ */ new Date()).toISOString() }
+      {
+        role: "assistant",
+        content,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        excludeFromProvider: true
+      }
     ]);
     this.dispatchEvent(
       new CustomEvent("history-updated", { detail: this.chatDriver.getHistory() })
@@ -7583,7 +7775,11 @@ Politely let the user know what you can help with and invite them to rephrase th
 var 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.`
 };
 
 // src/utils/usage-rows.ts
@@ -7749,10 +7945,12 @@ function withFreshMetaSnapshot(stored, fresh) {
   AnthropicTransport,
   ChatDriver,
   DEFAULT_PROVIDER_REFUSED_MESSAGE,
+  EMPTY_RESPONSE_NUDGE,
   GEMINI_CACHED_INPUT_MULTIPLIER,
   GEMINI_LONG_CONTEXT_THRESHOLD,
   GeminiProvider,
   GeminiTransport,
+  MALFORMED_CALL_NUDGE,
   MutableAIProviderRegistry,
   NOOP_ACTIVITY_BUS,
   OrchestratingDriver,
@@ -7761,6 +7959,8 @@ function withFreshMetaSnapshot(stored, fresh) {
   REQUEST_CONTINUATION_TOOL,
   SUPPORTED_ANTHROPIC_MODEL_IDS,
   SUPPORTED_GEMINI_MODEL_IDS,
+  UNROUTABLE_INSTRUCTION,
+  UNROUTABLE_PLACEHOLDER,
   addUsage,
   agenticActivityBus,
   anthropicRatesFor,