@genesislcap/ai-assistant 15.21.0 → 15.21.1

package/dist/ai-assistant.api.json

@@ -7393,6 +7393,33 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/ai-assistant!EMPTY_RESPONSE_NUDGE:var",
+          "docComment": "/**\n * Framed-tail nudge added to a retry after an EMPTY response.\n *\n * Rewritten in GENC-1573. The previous copy (\"You must respond to the user's message. Call the appropriate tool or provide a text response\") told a model that had just returned nothing to respond, without naming the one exit available to an agent that genuinely cannot act: saying so. Across nine failures in the measured session it changed nothing — all 29 attempts came back at 8–9 output tokens — and most of those were on a tool-less agent, for which \"call the appropriate tool\" is not an option at all. This version names the honest answer explicitly.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "EMPTY_RESPONSE_NUDGE = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"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.\""
+            }
+          ],
+          "fileUrlPath": "src/components/chat-driver/chat-driver.ts",
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "EMPTY_RESPONSE_NUDGE",
+          "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@genesislcap/ai-assistant!expandToolTree:function(1)",
@@ -14961,6 +14988,33 @@
           "parameters": [],
           "name": "isAiAssistantDocked"
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/ai-assistant!MALFORMED_CALL_NUDGE:var",
+          "docComment": "/**\n * Framed-tail nudge added to a retry after a MALFORMED tool call.\n *\n * Exported so tests can assert placement (framed tail, never the system prompt) without pinning the wording — the copy is a prompt, and a prompt should be free to improve.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "MALFORMED_CALL_NUDGE = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"IMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools.\""
+            }
+          ],
+          "fileUrlPath": "src/components/chat-driver/chat-driver.ts",
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "MALFORMED_CALL_NUDGE",
+          "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!ManualSelectionConfig:interface",
@@ -17081,6 +17135,32 @@
           ],
           "name": "restoreMachine"
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/ai-assistant!RoutingDecision:type",
+          "docComment": "/**\n * Why {@link OrchestratingDriver.classify} returned the agent it did — reported on the `routing.decided` timeline event.\n *\n * Every value here used to be indistinguishable from the others in the debug log: four separate paths returned the fallback, all four `logger.warn`-only, and `classify` runs outside any ChatDriver turn so it recorded no turn either. Triaging a session where UI work kept landing on the fallback (GENC-1573) it was impossible to tell a legitimate \"no specialist covers this\" from a classifier that never ran — the only surviving signal was that the decision had taken 0.1s rather than the usual 1–5s.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type RoutingDecision = \n/** The classifier ran and picked a specialist. */\n"
+            },
+            {
+              "kind": "Content",
+              "text": "'classified'\n/** The classifier ran and answered -1: nothing listed covers the request. */\n | 'no-match'\n/**\n * Every classifier-eligible specialist had already handled part of this turn and handed on, so\n * the ballot was empty and no call was made. Distinct from `'no-match'`, which means a\n * classifier RAN and declined — conflating the two re-creates exactly the \"did anything actually\n * get asked?\" ambiguity this event exists to remove.\n */\n | 'ballot-exhausted'\n/** One viable specialist and no fallback — no point asking. */\n | 'single-candidate'\n/** Nothing classifier-eligible was configured. */\n | 'no-specialists'\n/** The registry default exposes no `chat()`, so no classification is possible. */\n | 'provider-unavailable'\n/** Every attempt threw. `detail.error` carries the last message. */\n | 'classifier-failed'\n/** A pin or an active flow owned the turn; the classifier was skipped. */\n | 'pinned'"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/components/orchestrating-driver/orchestrating-driver.ts",
+          "releaseTag": "Beta",
+          "name": "RoutingDecision",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!SessionClearedDetail:interface",
@@ -19527,7 +19607,7 @@
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/ai-assistant!strictFallbackAgent:var",
-          "docComment": "/**\n * A brief, professional fallback agent. States what is available without elaboration. The `{{agents}}` placeholder is replaced at runtime by `OrchestratingDriver` with the generated specialist list.\n *\n * @beta\n */\n",
+          "docComment": "/**\n * A brief, professional fallback agent. States what is available without elaboration. The `{{agents}}` placeholder is replaced at runtime by `OrchestratingDriver` with the generated specialist list.\n *\n * 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.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -20898,6 +20978,60 @@
             "endIndex": 6
           }
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/ai-assistant!UNROUTABLE_INSTRUCTION:var",
+          "docComment": "/**\n * The instruction a fallback agent needs and, left to itself, tends not to have.\n *\n * 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.\n *\n * 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.\n *\n * 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.\n *\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "UNROUTABLE_INSTRUCTION = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"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.\\n\\nIf 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.\\n\\nNever 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.\""
+            }
+          ],
+          "fileUrlPath": "src/components/orchestrating-driver/orchestrating-driver.ts",
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "UNROUTABLE_INSTRUCTION",
+          "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          }
+        },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/ai-assistant!UNROUTABLE_PLACEHOLDER:var",
+          "docComment": "/**\n * Placeholder a consumer can put in its fallback prompt to position {@link UNROUTABLE_INSTRUCTION} itself, instead of having it appended.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "UNROUTABLE_PLACEHOLDER = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"{{unroutable}}\""
+            }
+          ],
+          "fileUrlPath": "src/components/orchestrating-driver/orchestrating-driver.ts",
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "UNROUTABLE_PLACEHOLDER",
+          "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          }
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/ai-assistant!userIconSvg:var",

package/dist/ai-assistant.d.ts

@@ -2102,6 +2102,23 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     /** Build the fold-awareness suffix appended to the system prompt each LLM call. */
     private buildFoldSystemPromptSuffix;
     private runToolLoop;
+    /**
+     * 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.
+     */
+    private appendDriverNotice;
     private appendToHistory;
 }
 
@@ -2546,6 +2563,20 @@ export declare interface DiagnosticEntry {
     [key: string]: unknown;
 }
 
+/**
+ * Framed-tail nudge added to a retry after an EMPTY response.
+ *
+ * Rewritten in GENC-1573. The previous copy ("You must respond to the user's message. Call the
+ * appropriate tool or provide a text response") told a model that had just returned nothing to
+ * respond, without naming the one exit available to an agent that genuinely cannot act: saying so.
+ * Across nine failures in the measured session it changed nothing — all 29 attempts came back at
+ * 8–9 output tokens — and most of those were on a tool-less agent, for which "call the appropriate
+ * tool" is not an option at all. This version names the honest answer explicitly.
+ *
+ * @beta
+ */
+export declare const 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.";
+
 /**
  * Expands a flat list of tool definitions into a nested tree by resolving fold
  * metadata from the corresponding handlers. Use this for debug output so the
@@ -4818,6 +4849,16 @@ export declare function isAiAssistantDocked(): boolean;
  */
 export declare const LOADING_STYLE_ANIMATIONS: readonly ["loading", "waves", "flowingWaves", "plasma"];
 
+/**
+ * Framed-tail nudge added to a retry after a MALFORMED tool call.
+ *
+ * Exported so tests can assert placement (framed tail, never the system prompt) without pinning
+ * the wording — the copy is a prompt, and a prompt should be free to improve.
+ *
+ * @beta
+ */
+export declare const 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.";
+
 /**
  * Opts an agent in to manual selection from the assistant's agent picker.
  *
@@ -5006,6 +5047,26 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
      * release resources cleanly.
      */
     dispose(): Promise<void>;
+    /**
+     * 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.
+     */
+    private recordRouting;
+    /**
+     * 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.
+     */
+    private classifierTranscript;
     private classify;
     /**
      * Returns the agent that the current turn is locked to, if any. Flow-owner
@@ -5016,6 +5077,12 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
      * — protects against stale state after an agents-array reassignment.
      */
     private resolvePinnedAgent;
+    /**
+     * 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`.
+     */
     private appendInlineMessage;
 }
 
@@ -5231,6 +5298,42 @@ export declare function restoreMachine(machine: {
     }) => void;
 }, restored: unknown, key?: string): void;
 
+/**
+ * Why {@link OrchestratingDriver.classify} returned the agent it did — reported on the
+ * `routing.decided` timeline event.
+ *
+ * Every value here used to be indistinguishable from the others in the debug log: four separate
+ * paths returned the fallback, all four `logger.warn`-only, and `classify` runs outside any
+ * ChatDriver turn so it recorded no turn either. Triaging a session where UI work kept landing on
+ * the fallback (GENC-1573) it was impossible to tell a legitimate "no specialist covers this"
+ * from a classifier that never ran — the only surviving signal was that the decision had taken
+ * 0.1s rather than the usual 1–5s.
+ *
+ * @beta
+ */
+export declare type RoutingDecision = 
+/** The classifier ran and picked a specialist. */
+'classified'
+/** The classifier ran and answered -1: nothing listed covers the request. */
+| 'no-match'
+/**
+* Every classifier-eligible specialist had already handled part of this turn and handed on, so
+* the ballot was empty and no call was made. Distinct from `'no-match'`, which means a
+* classifier RAN and declined — conflating the two re-creates exactly the "did anything actually
+* get asked?" ambiguity this event exists to remove.
+*/
+| 'ballot-exhausted'
+/** One viable specialist and no fallback — no point asking. */
+| 'single-candidate'
+/** Nothing classifier-eligible was configured. */
+| 'no-specialists'
+/** The registry default exposes no `chat()`, so no classification is possible. */
+| 'provider-unavailable'
+/** Every attempt threw. `detail.error` carries the last message. */
+| 'classifier-failed'
+/** A pin or an active flow owned the turn; the classifier was skipped. */
+| 'pinned';
+
 /**
  * `detail` of the `AiAssistantEvent.SessionCleared` event. Captured *before*
  * teardown so a host can tidy up whatever the active agent was working on
@@ -5666,6 +5769,13 @@ export declare type StatefulAgentPersistenceContext<S> = Omit<AgentPersistenceCo
  * 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 declare const strictFallbackAgent: FallbackAgentConfig;
@@ -6036,6 +6146,48 @@ export declare interface UnresolvedToolContext {
  */
 export declare type UnresolvedToolInput = (ctx: UnresolvedToolContext) => string | undefined | Promise<string | undefined>;
 
+/**
+ * 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 declare 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.\n\nIf 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.\n\nNever 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.";
+
+/**
+ * Placeholder a consumer can put in its fallback prompt to position
+ * {@link UNROUTABLE_INSTRUCTION} itself, instead of having it appended.
+ *
+ * @beta
+ */
+export declare const UNROUTABLE_PLACEHOLDER = "{{unroutable}}";
+
 /** Person silhouette — default user avatar. */
 export declare const userIconSvg = "<svg viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z\" fill=\"currentColor\"/></svg>";