@genesislcap/ai-assistant 15.24.2 → 15.25.1

package/dist/custom-elements.json

@@ -574,6 +574,14 @@
             "package": "./components/agent-picker"
           }
         },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./components/agent-session"
+          }
+        },
         {
           "kind": "js",
           "name": "*",
@@ -2508,7 +2516,7 @@
               "type": {
                 "text": "number"
               },
-              "description": "Aggregated USD cost across every chat turn in this session.\n\nRead-only (unlike previously): it is a projection of `sessionUsage`, and a\nhost assigning it would have set a figure the next transcript change overwrites.",
+              "description": "Aggregated USD cost across every chat turn in this session.\n\nRead-only: a projection of `sessionUsage`, so an assigned figure would be overwritten by\nthe next transcript change.",
               "readonly": true
             },
             {
@@ -2977,7 +2985,7 @@
                 "text": "OrchestratingDriver | undefined"
               },
               "privacy": "private",
-              "description": "This element's driver as an orchestrator, or `undefined` when the session is\nrunning a bare `ChatDriver`.\n\nThe five call sites that used to test the type themselves now read this\n(§11.2 constraint 3 of `docs/code-health.md`): the agent pin, the flow-owner\nlock, the wire-up in `wireDriver`, and the two `driverKind` diagnostics. The\ntype test itself lives in `asOrchestrator`, shared with the session\npersister.",
+              "description": "This element's driver as an orchestrator, or `undefined` when the session is running a bare\n`ChatDriver`. The only place in this element that narrows the type; the test itself lives in\n`asOrchestrator`, shared with the session persister.",
               "readonly": true
             },
             {
@@ -3289,26 +3297,6 @@
                 }
               }
             },
-            {
-              "kind": "method",
-              "name": "getAgentsKey",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "string"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "agents",
-                  "optional": true,
-                  "type": {
-                    "text": "AgentConfig[]"
-                  }
-                }
-              ],
-              "description": "Returns a stable fingerprint for an agents array based on agent names and tool handler keys."
-            },
             {
               "kind": "method",
               "name": "warnUnreachableStatefulAgents",
@@ -3557,7 +3545,7 @@
                   "text": "void"
                 }
               },
-              "description": "Runs side effects that were previously in `messagesChanged()`.\nCalled from the `messages` setter after dispatching to the store."
+              "description": "Transcript side effects, called from the `messages` setter after it dispatches to the store."
             },
             {
               "kind": "method",
@@ -5699,6 +5687,161 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/suggestions/generate-suggestions.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "SUGGESTIONS_SYSTEM_PROMPT",
+          "description": "The system prompt sets the role only.\n\nConcrete instructions live in the user message *after* the transcript, so the context\nimmediately preceding the model is \"here is data, now do X\" rather than \"here is a dialogue,\ncontinue it\". This matters for Anthropic — without it, Claude reads the transcript as an\nin-progress conversation and produces a normal assistant turn instead of a list."
+        },
+        {
+          "kind": "function",
+          "name": "buildSuggestionsPrompt",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
+            {
+              "name": "ctx",
+              "type": {
+                "text": "SuggestionsContext"
+              }
+            },
+            {
+              "name": "history",
+              "type": {
+                "text": "ChatMessage[]"
+              }
+            },
+            {
+              "name": "prompt",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "count",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "allAgentInfo",
+              "optional": true,
+              "type": {
+                "text": "AllAgentSummary[]"
+              }
+            }
+          ],
+          "description": "Build the user message: starter prompts for an empty transcript, follow-ups otherwise."
+        },
+        {
+          "kind": "function",
+          "name": "parseSuggestions",
+          "return": {
+            "type": {
+              "text": "string[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "text",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "count",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "Lenient parsing, as a backstop: even with the strict format above, models slip in numbering,\nbullets or surrounding markdown."
+        },
+        {
+          "kind": "function",
+          "name": "generateSuggestions",
+          "return": {
+            "type": {
+              "text": "Promise<string[]>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "ctx",
+              "type": {
+                "text": "SuggestionsContext"
+              }
+            },
+            {
+              "name": "history",
+              "type": {
+                "text": "ChatMessage[]"
+              }
+            },
+            {
+              "name": "prompt",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "count",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "allAgentInfo",
+              "optional": true,
+              "type": {
+                "text": "AllAgentSummary[]"
+              }
+            }
+          ],
+          "description": "Suggested prompts for the composer.\n\nBest-effort throughout: a default provider with no `prompt()` means no suggestions, not an\nerror, because this is an out-of-turn UI helper."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "SUGGESTIONS_SYSTEM_PROMPT",
+          "declaration": {
+            "name": "SUGGESTIONS_SYSTEM_PROMPT",
+            "module": "src/suggestions/generate-suggestions.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "buildSuggestionsPrompt",
+          "declaration": {
+            "name": "buildSuggestionsPrompt",
+            "module": "src/suggestions/generate-suggestions.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "parseSuggestions",
+          "declaration": {
+            "name": "parseSuggestions",
+            "module": "src/suggestions/generate-suggestions.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "generateSuggestions",
+          "declaration": {
+            "name": "generateSuggestions",
+            "module": "src/suggestions/generate-suggestions.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/tags/index.ts",
@@ -5717,6 +5860,41 @@
       "declarations": [],
       "exports": []
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/agents-key.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "agentsKey",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
+            {
+              "name": "agents",
+              "optional": true,
+              "type": {
+                "text": "AgentConfig[]"
+              }
+            }
+          ],
+          "description": "A stable fingerprint for an agents array, compared against the installed driver's to decide\nwhether an `agents` change needs the driver rebuilt.\n\nSo it must change when the driver's tool surface would, and not otherwise: handler key order is\nsorted out, agent order is significant."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "agentsKey",
+          "declaration": {
+            "name": "agentsKey",
+            "module": "src/utils/agents-key.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/animated-panel-toggle.ts",
@@ -7232,6 +7410,46 @@
       "declarations": [],
       "exports": []
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/resolve-turn-input.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "resolveTurnInput",
+          "return": {
+            "type": {
+              "text": "Promise<T | undefined>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "input",
+              "type": {
+                "text": "T | ((ctx: SystemPromptContext) => T | Promise<T>) | undefined"
+              }
+            },
+            {
+              "name": "ctx",
+              "type": {
+                "text": "SystemPromptContext"
+              }
+            }
+          ],
+          "description": "Resolve a config input that may be a static value or a per-turn resolver.\n\n`undefined` in, `undefined` out — an unset input stays unset rather than resolving to a default\nthe caller never asked for."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "resolveTurnInput",
+          "declaration": {
+            "name": "resolveTurnInput",
+            "module": "src/utils/resolve-turn-input.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/strip-agent-handlers.ts",
@@ -7869,59 +8087,318 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/ai-driver/ai-driver.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/components/ai-driver/index.ts",
-      "declarations": [],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "AiDriver",
-          "declaration": {
-            "name": "AiDriver",
-            "module": "./ai-driver"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/components/chat-bubble/chat-bubble.styles.ts",
-      "declarations": [
-        {
-          "kind": "variable",
-          "name": "styles",
-          "default": "css`\n  :host {\n    position: fixed;\n    inset: 0;\n    pointer-events: none;\n    z-index: 9999;\n    overflow: visible;\n  }\n\n  :host([hidden]) {\n    display: none;\n  }\n\n  .bubble {\n    position: absolute;\n    width: 62px;\n    height: 62px;\n    border-radius: 50%;\n    cursor: grab;\n    pointer-events: all;\n    overflow: visible;\n    display: flex;\n    align-items: center;\n    justify-content: center;\n    user-select: none;\n    transition:\n      transform 0.25s cubic-bezier(0.34, 1.56, 0.64, 1),\n      box-shadow 0.25s ease;\n    background: linear-gradient(135deg, #0e1628 0%, #192340 100%);\n    box-shadow: 0 4px 20px rgb(0 0 0 / 45%);\n    border: 2px solid rgb(255 255 255 / 15%);\n    color: white;\n  }\n\n  .bubble img {\n    width: 62px;\n    height: 62px;\n    border-radius: 50%;\n    object-fit: cover;\n    pointer-events: none;\n    box-shadow: 0 4px 20px rgb(0 0 0 / 45%);\n    border: 2px solid rgb(255 255 255 / 15%);\n  }\n\n  .bubble svg {\n    pointer-events: none;\n  }\n\n  .bubble:hover,\n  .bubble.hovered {\n    transform: scale(1.18);\n  }\n\n  .bubble:hover img,\n  .bubble.hovered img {\n    box-shadow:\n      0 6px 32px rgb(0 100 255 / 55%),\n      0 0 0 3px rgb(0 120 255 / 35%);\n  }\n\n  .bubble:active {\n    cursor: grabbing;\n  }\n\n  .tooltip {\n    position: absolute;\n    bottom: calc(100% + 10px);\n    background: linear-gradient(135deg, #0078ff 0%, #0050d0 100%);\n    color: #fff;\n    font-size: 0.78em;\n    font-weight: 600;\n    letter-spacing: 0.03em;\n    white-space: nowrap;\n    padding: 5px 10px;\n    border-radius: 8px;\n    box-shadow: 0 4px 14px rgb(0 120 255 / 45%);\n    pointer-events: none;\n    opacity: 0%;\n    translate: 0 4px;\n    transition:\n      opacity 0.18s ease,\n      translate 0.18s ease;\n  }\n\n  .tooltip::after {\n    content: '';\n    position: absolute;\n    top: 100%;\n    left: var(--arrow-left, 50%);\n    transform: translateX(-50%);\n    border: 5px solid transparent;\n    border-top-color: #0050d0;\n  }\n\n  .bubble:hover .tooltip,\n  .bubble.hovered .tooltip {\n    opacity: 100%;\n    translate: 0 0;\n  }\n\n  .pulse-ring {\n    position: absolute;\n    width: 62px;\n    height: 62px;\n    border-radius: 50%;\n    border: 2px solid rgb(0 120 255 / 50%);\n    animation: pulse 2.5s ease-out infinite;\n    pointer-events: none;\n  }\n\n  @keyframes pulse {\n    0% {\n      transform: scale(1);\n      opacity: 70%;\n    }\n\n    70% {\n      transform: scale(1.5);\n      opacity: 0%;\n    }\n\n    100% {\n      transform: scale(1.5);\n      opacity: 0%;\n    }\n  }\n\n  .dialog {\n    position: absolute;\n    box-sizing: border-box;\n    width: 400px;\n    height: 520px;\n    min-width: 300px;\n    min-height: 300px;\n    max-width: 50vw;\n    max-height: calc(100vh - 40px);\n    background: var(--neutral-layer-1);\n    border-radius: 14px;\n    box-shadow:\n      0 12px 50px rgb(0 0 0 / 55%),\n      0 0 0 1px rgb(255 255 255 / 6%);\n    pointer-events: all;\n    display: flex;\n    flex-direction: column;\n    overflow: hidden;\n    resize: both;\n    border: 1px solid var(--neutral-stroke-rest);\n    animation: dialog-in 0.25s cubic-bezier(0.34, 1.56, 0.64, 1);\n  }\n\n  @keyframes dialog-in {\n    from {\n      opacity: 0%;\n      transform: scale(0.85) translateY(12px);\n    }\n\n    to {\n      opacity: 100%;\n      transform: scale(1) translateY(0);\n    }\n  }\n\n  @keyframes dialog-out {\n    from {\n      opacity: 100%;\n      transform: scale(1) translateY(0);\n    }\n\n    to {\n      opacity: 0%;\n      transform: scale(0.85) translateY(12px);\n    }\n  }\n\n  .dialog.closing {\n    animation: dialog-out 0.2s cubic-bezier(0.4, 0, 0.6, 1) forwards;\n  }\n\n  .dialog-content {\n    flex: 1;\n    overflow: hidden;\n    display: flex;\n    min-height: 0;\n  }\n\n  .dialog-content ::slotted(*) {\n    display: flex;\n    flex: 1;\n    width: 100%;\n    min-height: 0;\n  }\n`"
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "styles",
-          "declaration": {
-            "name": "styles",
-            "module": "src/components/chat-bubble/chat-bubble.styles.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/components/chat-bubble/chat-bubble.template.ts",
+      "path": "src/components/agent-session/agent-session.ts",
       "declarations": [
         {
-          "kind": "function",
-          "name": "AiChatBubbleTemplate",
-          "return": {
-            "type": {
-              "text": "ViewTemplate<AiChatBubble>"
-            }
-          }
-        }
+          "kind": "class",
+          "description": "The stateful-agent contract: which agent is active, whether a flow or a user pin holds routing,\nand the `onActivate` / `onDeactivate` lifecycle around a swap. Either driver can own one.\n\nKnows nothing about routing, tool surfaces or transcripts — whether an agent is terminal, the\ncontinuation tool, the handoff marker in history all stay with the orchestrator, which is the\nonly thing with agents to route between.",
+          "name": "AgentSession",
+          "members": [
+            {
+              "kind": "field",
+              "name": "lifecycleAbortController",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new AbortController()",
+              "description": "Aborted on disposal. Threaded into `AgentLifecycleContext.signal` so long-running\n`onActivate` work can bail if the session disconnects."
+            },
+            {
+              "kind": "field",
+              "name": "active",
+              "type": {
+                "text": "AgentConfig | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "pinned",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "Sticky user pick from the picker (or the host's `setAgent` API). Only changes on explicit\nuser action. Survives flow completion: when a stateful agent releases, the user-pin stays put\nand routing falls back to it on the next turn."
+            },
+            {
+              "kind": "field",
+              "name": "flowOwner",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "Transient flow lock — set when a stateful agent activates, cleared on release. While\nnon-null, routing precedence goes to this agent and the picker is locked. Independent of\nthe user pin so completing a flow doesn't wipe the user's sticky choice."
+            },
+            {
+              "kind": "field",
+              "name": "restoredStates",
+              "type": {
+                "text": "Record<string, unknown>"
+              },
+              "privacy": "private",
+              "default": "{}",
+              "description": "Per-agent restored state for a rehydrated session, keyed by agent name. Primed by the host on\nrestore; each entry is passed to that agent's `onActivate` as `ctx.restored` on its next\nactivation, then deleted so a later re-activation starts fresh."
+            },
+            {
+              "kind": "method",
+              "name": "getActive",
+              "return": {
+                "type": {
+                  "text": "AgentConfig | undefined"
+                }
+              },
+              "description": "The active agent, or `undefined` before the first activation and after a release."
+            },
+            {
+              "kind": "method",
+              "name": "getPinned",
+              "return": {
+                "type": {
+                  "text": "string | null"
+                }
+              },
+              "description": "The sticky user pin, or `null` for automatic routing."
+            },
+            {
+              "kind": "method",
+              "name": "getFlowOwner",
+              "return": {
+                "type": {
+                  "text": "string | null"
+                }
+              },
+              "description": "The transient flow lock, or `null` when no flow holds routing."
+            },
+            {
+              "kind": "method",
+              "name": "getLockedName",
+              "return": {
+                "type": {
+                  "text": "string | null"
+                }
+              },
+              "description": "The name routing is locked to, flow lock first. A flow in progress outranks the user's\nsticky pick for the duration of the flow; neither being set means automatic routing."
+            },
+            {
+              "kind": "method",
+              "name": "setPinned",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string | null"
+                  }
+                }
+              ],
+              "description": "Set the sticky user pin. `null` returns to automatic routing."
+            },
+            {
+              "kind": "method",
+              "name": "setFlowOwner",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string | null"
+                  }
+                }
+              ],
+              "description": "Set the flow-owner lock directly — used to restore state on driver reconstruction\n(agents-array changes, pop-in/pop-out), not to steer routing. Writes without firing hooks or\nreporting a transition, because the flow it names is already running."
+            },
+            {
+              "kind": "method",
+              "name": "primeRestoredStates",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "snapshots",
+                  "type": {
+                    "text": "Record<string, unknown>"
+                  }
+                }
+              ],
+              "description": "Prime per-agent restored state for a rehydrated session. Replaces any pending entries."
+            },
+            {
+              "kind": "method",
+              "name": "hasRestoredState",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agentName",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Whether a restored snapshot is waiting for this agent's next activation."
+            },
+            {
+              "kind": "method",
+              "name": "activate",
+              "return": {
+                "type": {
+                  "text": "Promise<AgentTransition>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agent",
+                  "type": {
+                    "text": "AgentConfig"
+                  }
+                }
+              ],
+              "description": "Make `agent` active, firing the lifecycle hooks around the swap: outgoing `onDeactivate`\nfirst, then incoming `onActivate`. Both are awaited so heavy activation work (a machine\nrestore, say) completes before the agent's first turn runs, and a throw from either is logged\nrather than propagated — an agent whose hook fails still activates.\n\nRe-activating the same agent by name is not a switch: no hooks fire, no lock moves, and no\nhandoff is recorded. That guard matters because a per-turn re-resolve calls through here."
+            },
+            {
+              "kind": "method",
+              "name": "release",
+              "return": {
+                "type": {
+                  "text": "Promise<AgentTransition | undefined>"
+                }
+              },
+              "description": "Release the active agent: fire `onDeactivate` and drop the flow lock.\n\nThe user pin is intentionally **not** cleared — someone who explicitly picked this agent\nshould stay on it after the flow ends, so the next message starts a fresh flow on the same\nagent rather than routing through the classifier.\n\nReturns `undefined` when there was no active agent, so a caller can skip its events."
+            },
+            {
+              "kind": "method",
+              "name": "dispose",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "description": "Fire `onDeactivate` on the active agent and abort pending lifecycle work, for session\nteardown, so machines release resources cleanly. The session is not reusable afterwards: the\nabort signal stays aborted, so a later `activate` would hand its hook a dead signal.\n\n`onDeactivate` runs **before** the abort, deliberately: teardown that needs to flush state\nwould otherwise be handed an already-aborted signal and have to skip its own work. The cost is\nthat an `onActivate` still in flight keeps running until `onDeactivate` finishes — both hold\nthe same signal. Acceptable because the two are sequenced by `activate`, so overlap only\nhappens if a hook resolves before the work it started; a hook that must stop immediately\nshould own its own cancellation."
+            },
+            {
+              "kind": "method",
+              "name": "fireDeactivate",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agent",
+                  "type": {
+                    "text": "AgentConfig"
+                  }
+                },
+                {
+                  "name": "reason",
+                  "type": {
+                    "text": "'switch' | 'release' | 'dispose'"
+                  }
+                }
+              ],
+              "description": "The one place `onDeactivate` is invoked. `reason` only reaches the warning text, which is what\ntells a log reader which path fired."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "AgentSession",
+          "declaration": {
+            "name": "AgentSession",
+            "module": "src/components/agent-session/agent-session.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/agent-session/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./agent-session"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/ai-driver/ai-driver.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/ai-driver/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "AiDriver",
+          "declaration": {
+            "name": "AiDriver",
+            "module": "./ai-driver"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/chat-bubble/chat-bubble.styles.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "styles",
+          "default": "css`\n  :host {\n    position: fixed;\n    inset: 0;\n    pointer-events: none;\n    z-index: 9999;\n    overflow: visible;\n  }\n\n  :host([hidden]) {\n    display: none;\n  }\n\n  .bubble {\n    position: absolute;\n    width: 62px;\n    height: 62px;\n    border-radius: 50%;\n    cursor: grab;\n    pointer-events: all;\n    overflow: visible;\n    display: flex;\n    align-items: center;\n    justify-content: center;\n    user-select: none;\n    transition:\n      transform 0.25s cubic-bezier(0.34, 1.56, 0.64, 1),\n      box-shadow 0.25s ease;\n    background: linear-gradient(135deg, #0e1628 0%, #192340 100%);\n    box-shadow: 0 4px 20px rgb(0 0 0 / 45%);\n    border: 2px solid rgb(255 255 255 / 15%);\n    color: white;\n  }\n\n  .bubble img {\n    width: 62px;\n    height: 62px;\n    border-radius: 50%;\n    object-fit: cover;\n    pointer-events: none;\n    box-shadow: 0 4px 20px rgb(0 0 0 / 45%);\n    border: 2px solid rgb(255 255 255 / 15%);\n  }\n\n  .bubble svg {\n    pointer-events: none;\n  }\n\n  .bubble:hover,\n  .bubble.hovered {\n    transform: scale(1.18);\n  }\n\n  .bubble:hover img,\n  .bubble.hovered img {\n    box-shadow:\n      0 6px 32px rgb(0 100 255 / 55%),\n      0 0 0 3px rgb(0 120 255 / 35%);\n  }\n\n  .bubble:active {\n    cursor: grabbing;\n  }\n\n  .tooltip {\n    position: absolute;\n    bottom: calc(100% + 10px);\n    background: linear-gradient(135deg, #0078ff 0%, #0050d0 100%);\n    color: #fff;\n    font-size: 0.78em;\n    font-weight: 600;\n    letter-spacing: 0.03em;\n    white-space: nowrap;\n    padding: 5px 10px;\n    border-radius: 8px;\n    box-shadow: 0 4px 14px rgb(0 120 255 / 45%);\n    pointer-events: none;\n    opacity: 0%;\n    translate: 0 4px;\n    transition:\n      opacity 0.18s ease,\n      translate 0.18s ease;\n  }\n\n  .tooltip::after {\n    content: '';\n    position: absolute;\n    top: 100%;\n    left: var(--arrow-left, 50%);\n    transform: translateX(-50%);\n    border: 5px solid transparent;\n    border-top-color: #0050d0;\n  }\n\n  .bubble:hover .tooltip,\n  .bubble.hovered .tooltip {\n    opacity: 100%;\n    translate: 0 0;\n  }\n\n  .pulse-ring {\n    position: absolute;\n    width: 62px;\n    height: 62px;\n    border-radius: 50%;\n    border: 2px solid rgb(0 120 255 / 50%);\n    animation: pulse 2.5s ease-out infinite;\n    pointer-events: none;\n  }\n\n  @keyframes pulse {\n    0% {\n      transform: scale(1);\n      opacity: 70%;\n    }\n\n    70% {\n      transform: scale(1.5);\n      opacity: 0%;\n    }\n\n    100% {\n      transform: scale(1.5);\n      opacity: 0%;\n    }\n  }\n\n  .dialog {\n    position: absolute;\n    box-sizing: border-box;\n    width: 400px;\n    height: 520px;\n    min-width: 300px;\n    min-height: 300px;\n    max-width: 50vw;\n    max-height: calc(100vh - 40px);\n    background: var(--neutral-layer-1);\n    border-radius: 14px;\n    box-shadow:\n      0 12px 50px rgb(0 0 0 / 55%),\n      0 0 0 1px rgb(255 255 255 / 6%);\n    pointer-events: all;\n    display: flex;\n    flex-direction: column;\n    overflow: hidden;\n    resize: both;\n    border: 1px solid var(--neutral-stroke-rest);\n    animation: dialog-in 0.25s cubic-bezier(0.34, 1.56, 0.64, 1);\n  }\n\n  @keyframes dialog-in {\n    from {\n      opacity: 0%;\n      transform: scale(0.85) translateY(12px);\n    }\n\n    to {\n      opacity: 100%;\n      transform: scale(1) translateY(0);\n    }\n  }\n\n  @keyframes dialog-out {\n    from {\n      opacity: 100%;\n      transform: scale(1) translateY(0);\n    }\n\n    to {\n      opacity: 0%;\n      transform: scale(0.85) translateY(12px);\n    }\n  }\n\n  .dialog.closing {\n    animation: dialog-out 0.2s cubic-bezier(0.4, 0, 0.6, 1) forwards;\n  }\n\n  .dialog-content {\n    flex: 1;\n    overflow: hidden;\n    display: flex;\n    min-height: 0;\n  }\n\n  .dialog-content ::slotted(*) {\n    display: flex;\n    flex: 1;\n    width: 100%;\n    min-height: 0;\n  }\n`"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "styles",
+          "declaration": {
+            "name": "styles",
+            "module": "src/components/chat-bubble/chat-bubble.styles.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/chat-bubble/chat-bubble.template.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "AiChatBubbleTemplate",
+          "return": {
+            "type": {
+              "text": "ViewTemplate<AiChatBubble>"
+            }
+          }
+        }
       ],
       "exports": [
         {
@@ -8363,8 +8840,61 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/chat-driver/chat-driver.ts",
+      "path": "src/components/chat-driver/chat-driver.constants.ts",
       "declarations": [
+        {
+          "kind": "variable",
+          "name": "DEFAULT_MAX_TOOL_ITERATIONS",
+          "type": {
+            "text": "number"
+          },
+          "default": "50",
+          "description": "Tuning constants for the tool loop — caps, retry ceilings, and the two retry nudges."
+        },
+        {
+          "kind": "variable",
+          "name": "DEFAULT_MAX_FOLD_OPERATIONS",
+          "type": {
+            "text": "number"
+          },
+          "default": "5"
+        },
+        {
+          "kind": "variable",
+          "name": "DEFAULT_MAX_TURN_SNAPSHOTS",
+          "type": {
+            "text": "number"
+          },
+          "default": "400"
+        },
+        {
+          "kind": "variable",
+          "name": "DEFAULT_MAX_UNKNOWN_TOOL_CALLS",
+          "type": {
+            "text": "number"
+          },
+          "default": "5"
+        },
+        {
+          "kind": "variable",
+          "name": "MAX_STALE_TOOL_CALLS"
+        },
+        {
+          "kind": "variable",
+          "name": "MAX_MALFORMED_RETRIES",
+          "type": {
+            "text": "number"
+          },
+          "default": "5"
+        },
+        {
+          "kind": "variable",
+          "name": "MAX_EMPTY_RESPONSE_RETRIES",
+          "type": {
+            "text": "number"
+          },
+          "default": "3"
+        },
         {
           "kind": "variable",
           "name": "MALFORMED_CALL_NUDGE",
@@ -8383,6 +8913,23 @@
           "default": "\"IMPORTANT: Your previous attempt returned nothing at all, which is never a valid response. Answer the user's last message now, in prose — 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.\"",
           "description": "Framed-tail nudge added to a retry after an EMPTY response.\n\nRewritten in GENC-1573. The previous copy (\"You must respond to the user's message. Call the\nappropriate tool or provide a text response\") told a model that had just returned nothing to\nrespond, without naming the one exit available to an agent that genuinely cannot act: saying so.\nAcross nine failures in the measured session it changed nothing — all 29 attempts came back at\n8–9 output tokens — and most of those were on a tool-less agent, for which \"call the appropriate\ntool\" is not an option at all. This version names the honest answer explicitly."
         },
+        {
+          "kind": "variable",
+          "name": "MAX_SETUP_TRANSPORT_RETRIES",
+          "type": {
+            "text": "number"
+          },
+          "default": "3"
+        },
+        {
+          "kind": "variable",
+          "name": "HARVESTED_SUBAGENT_EVENTS",
+          "type": {
+            "text": "ReadonlySet<MetaEventType>"
+          },
+          "default": "new Set([\n  'turn.retry',\n  'turn.error',\n  'tool.failed',\n  'tool.unresolved',\n])",
+          "description": "Sub-agent meta events worth folding into the parent's debug timeline: the\nper-attempt and per-failure signals that do NOT otherwise surface in the\nsub-agent's (now hoisted) messages — a retried-away malformed/empty attempt\nproduces no message, and the stale-vs-hallucinated/streak diagnostics live only\non the event. High-volume, message-derivable events (turn.start/turn.end,\nprovider.selected, context.updated) are intentionally excluded: read the\nsub-agent's hoisted messages for model/tokens/cost and turn-by-turn activity.\nSee `ChatDriver.invokeSubAgent`."
+        },
         {
           "kind": "variable",
           "name": "REQUEST_CONTINUATION_TOOL",
@@ -8392,6 +8939,127 @@
           "default": "'request_continuation'",
           "description": "Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver."
         },
+        {
+          "kind": "variable",
+          "name": "HANDOFF_TOOL_RESULT_PLACEHOLDER",
+          "type": {
+            "text": "string"
+          },
+          "default": "'Handoff to another specialist — routing continues on the next turn.'",
+          "description": "Paired in history for each `request_continuation` so tool_calls stay balanced for the provider."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DEFAULT_MAX_TOOL_ITERATIONS",
+          "declaration": {
+            "name": "DEFAULT_MAX_TOOL_ITERATIONS",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DEFAULT_MAX_FOLD_OPERATIONS",
+          "declaration": {
+            "name": "DEFAULT_MAX_FOLD_OPERATIONS",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DEFAULT_MAX_TURN_SNAPSHOTS",
+          "declaration": {
+            "name": "DEFAULT_MAX_TURN_SNAPSHOTS",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DEFAULT_MAX_UNKNOWN_TOOL_CALLS",
+          "declaration": {
+            "name": "DEFAULT_MAX_UNKNOWN_TOOL_CALLS",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MAX_STALE_TOOL_CALLS",
+          "declaration": {
+            "name": "MAX_STALE_TOOL_CALLS",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MAX_MALFORMED_RETRIES",
+          "declaration": {
+            "name": "MAX_MALFORMED_RETRIES",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MAX_EMPTY_RESPONSE_RETRIES",
+          "declaration": {
+            "name": "MAX_EMPTY_RESPONSE_RETRIES",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MALFORMED_CALL_NUDGE",
+          "declaration": {
+            "name": "MALFORMED_CALL_NUDGE",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "EMPTY_RESPONSE_NUDGE",
+          "declaration": {
+            "name": "EMPTY_RESPONSE_NUDGE",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MAX_SETUP_TRANSPORT_RETRIES",
+          "declaration": {
+            "name": "MAX_SETUP_TRANSPORT_RETRIES",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HARVESTED_SUBAGENT_EVENTS",
+          "declaration": {
+            "name": "HARVESTED_SUBAGENT_EVENTS",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "REQUEST_CONTINUATION_TOOL",
+          "declaration": {
+            "name": "REQUEST_CONTINUATION_TOOL",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HANDOFF_TOOL_RESULT_PLACEHOLDER",
+          "declaration": {
+            "name": "HANDOFF_TOOL_RESULT_PLACEHOLDER",
+            "module": "src/components/chat-driver/chat-driver.constants.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/chat-driver/chat-driver.ts",
+      "declarations": [
         {
           "kind": "class",
           "description": "",
@@ -8594,23 +9262,11 @@
             },
             {
               "kind": "field",
-              "name": "foldStack",
-              "type": {
-                "text": "FoldStackFrame[]"
-              },
-              "privacy": "private",
-              "default": "[]",
-              "description": "Stack of fold frames — grows when a fold opens, shrinks when it closes."
-            },
-            {
-              "kind": "field",
-              "name": "consecutiveFoldOps",
-              "type": {
-                "text": "number"
-              },
+              "name": "folds",
               "privacy": "private",
-              "default": "0",
-              "description": "Consecutive fold open/close ops without a real tool call. Reset on real tool execution."
+              "readonly": true,
+              "default": "new FoldController({\n    getDefinitions: () => this.toolDefinitions,\n    setDefinitions: (defs) => {\n      this.toolDefinitions = defs;\n    },\n    getHandlers: () => this.toolHandlers,\n    setHandlers: (handlers) => {\n      this.toolHandlers = handlers;\n    },\n    handlerContext: (activeToolCallId) => this.buildHandlerContext(activeToolCallId),\n  })",
+              "description": "Tool folds: the open-fold stack, the no-progress counter, and the tool-surface swap."
             },
             {
               "kind": "field",
@@ -8971,6 +9627,17 @@
               "description": "Session identity used to file meta events onto the shared debug-log timeline.",
               "default": "sessionKey"
             },
+            {
+              "kind": "field",
+              "name": "deferAgentRelease",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "See ChatDriverConfig.deferAgentRelease.",
+              "default": "deferAgentRelease"
+            },
             {
               "kind": "field",
               "name": "activityBus",
@@ -9057,7 +9724,7 @@
               "name": "dispose",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "Promise<void>"
                 }
               },
               "description": "Tear down the driver: aborts the lifecycle signal so any in-flight provider\nrequest (and prompt/tool factories awaiting it) cancels instead of running\non to completion or the transport timeout. Called by the host on driver\nswap and by `OrchestratingDriver.dispose()`. Idempotent.\n\nDeliberately does NOT settle `pendingInteractions` here: dispose is never\nreached while one is pending. The only host-level dispose is the agent-swap\nrebuild, which is guarded by `isBusy()` — a pending interaction keeps the\ntool loop suspended (`busy === true`), so the swap is deferred until the\nwidget resolves. Sub-agent child disposes always have an empty pending map\n(widgets park on the parent via `setHostInteractionRequester`). A pending\ninteraction is instead settled by `resolveInteraction` (user response or\ntimeout), which also stamps history and reverts the chat-input override."
@@ -9105,40 +9772,6 @@
               },
               "description": "Finish a turn whose signal aborted. A user cancel adds a subtle \"Stopped.\"\nmarker; a dispose-driven abort stops quietly (the widget is gone and the\ncached history would otherwise gain a stray marker on remount)."
             },
-            {
-              "kind": "method",
-              "name": "turnDone",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "ChatDriverResult"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "failureReason",
-                  "optional": true,
-                  "type": {
-                    "text": "TurnFailureReason"
-                  }
-                },
-                {
-                  "name": "budget",
-                  "optional": true,
-                  "type": {
-                    "text": "BudgetDetail"
-                  }
-                },
-                {
-                  "name": "providerRefused",
-                  "optional": true,
-                  "type": {
-                    "text": "ProviderRefusedDetail"
-                  }
-                }
-              ],
-              "description": "Build the `done` loop result, carrying the typed failure reason when the turn\nbailed (PTC-0). The discriminant stays `'done'` either way — the same value a\nclean turn returns — so consumers matching on `reason === 'done'` are unchanged;\n`failureReason` is simply present on a failure and absent on success. Omitted\n(rather than set to `undefined`) so a happy-path result stays byte-identical to\nthe historical `{ reason: 'done' }`."
-            },
             {
               "kind": "method",
               "name": "endTurnWithFailure",
@@ -9239,6 +9872,88 @@
               ],
               "description": "Build the `tool-loop-end` event detail for a turn's result. A failure carries a\n`{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,\nkept byte-identical so subscribers see exactly what they always have.\n\nA budget failure additionally carries `vendor` — the concrete vendor\n(`'anthropic'`/`'gemini'`) the walled turn resolved to, which the driver knows\nand used to discard. Optional and additive: a subscriber reading only\n`failureReason` is unaffected, a non-budget failure still emits the historical\n`{ failureReason }` with no `vendor` key, and the value is a plain string so\nthe detail stays structured-cloneable for the cross-tab hop. It is the field a\nper-vendor budget model needs and the one that would be awkward to retrofit."
             },
+            {
+              "kind": "method",
+              "name": "activateAgent",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "config",
+                  "type": {
+                    "text": "AgentConfig"
+                  }
+                }
+              ],
+              "description": "Make `config` the active agent, firing its lifecycle hooks — `onDeactivate` on the outgoing\nagent, then `onActivate` on this one — before installing it.\n\nThis is the entry point a host should use. ChatDriver.applyAgent installs a config\n*without* firing hooks, which is right for the two callers that need it (the orchestrator,\nwhich fires them through the shared session, and `invokeSubAgent`, where a child's config is\nnot an activation) and wrong for everyone else."
+            },
+            {
+              "kind": "method",
+              "name": "getActiveAgent",
+              "return": {
+                "type": {
+                  "text": "AgentConfig | undefined"
+                }
+              },
+              "description": "{@inheritDoc AiDriver.getActiveAgent}"
+            },
+            {
+              "kind": "method",
+              "name": "primeRestoredAgentState",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "snapshots",
+                  "type": {
+                    "text": "Record<string, unknown>"
+                  }
+                }
+              ],
+              "description": "{@inheritDoc AiDriver.primeRestoredAgentState}"
+            },
+            {
+              "kind": "method",
+              "name": "setPinnedAgent",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string | null"
+                  }
+                }
+              ],
+              "description": "Record the sticky agent pin. See AiDriver.setPinnedAgent for the contract.\n\nRecorded, not acted on: this driver has one agent and nothing to route between, so a pin\nchanges no behaviour here. It is still honoured as state, because the session outlives the\nquestion of which driver is holding it — a host that pins before an orchestrator is built\nwould otherwise lose the pick."
+            },
+            {
+              "kind": "method",
+              "name": "setFlowOwner",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string | null"
+                  }
+                }
+              ],
+              "description": "Record the transient flow lock. See AiDriver.setFlowOwner for the contract.\n\nRecorded, not acted on, for the same reason as ChatDriver.setPinnedAgent."
+            },
             {
               "kind": "method",
               "name": "applyAgent",
@@ -9255,7 +9970,7 @@
                   }
                 }
               ],
-              "description": "Swap in a new agent's configuration. Called by OrchestratingDriver before\neach specialist turn so the shared driver runs with the right tools and prompt."
+              "description": "Install `config` as the active agent **without firing lifecycle hooks**.\n\nPrefer ChatDriver.activateAgent unless you are deliberately skipping the hooks. Two\ncallers are: `OrchestratingDriver`, which fires them through the shared\nChatDriver.agentSession and then installs a decorated config, and `invokeSubAgent`,\nwhere the child driver's config is a tool surface rather than an activation.\n\nRenamed to `installAgent` in a follow-up (GENC-1580) — see `docs/migration-GENC-1580.md`.\nUntil then the name says less than it should, so do not add a third caller to this path\nwithout checking which of the two above it resembles."
             },
             {
               "kind": "method",
@@ -9344,53 +10059,28 @@
             },
             {
               "kind": "method",
-              "name": "resolveStatusForProvider",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "Promise<{ model?: string; provider?: AIProviderType; contextLimit?: number }>"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "name",
-                  "type": {
-                    "text": "string"
-                  }
-                },
-                {
-                  "name": "provider",
-                  "type": {
-                    "text": "AIProvider"
-                  }
-                }
-              ],
-              "description": "Resolve model id and vendor from a provider via its optional `getStatus()`,\nmemoised by registry name. Used to stamp `model` and `provider` onto outgoing\nmessages. Best-effort: a provider without `getStatus`, a null status, or a\nthrow all yield empty fields — attribution is diagnostic, never load-bearing."
-            },
-            {
-              "kind": "method",
-              "name": "resolveTurnInput",
+              "name": "resolveStatusForProvider",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "Promise<T | undefined>"
+                  "text": "Promise<{ model?: string; provider?: AIProviderType; contextLimit?: number }>"
                 }
               },
               "parameters": [
                 {
-                  "name": "input",
+                  "name": "name",
                   "type": {
-                    "text": "T | ((ctx: SystemPromptContext) => T | Promise<T>) | undefined"
+                    "text": "string"
                   }
                 },
                 {
-                  "name": "ctx",
+                  "name": "provider",
                   "type": {
-                    "text": "SystemPromptContext"
+                    "text": "AIProvider"
                   }
                 }
               ],
-              "description": "Resolve a per-turn config input that is either a static value or a function\nof the turn context — the value-or-resolver shape shared by `provider`,\n`temperature`, and `toolChoice`. Returns undefined when the input is unset."
+              "description": "Resolve model id and vendor from a provider via its optional `getStatus()`,\nmemoised by registry name. Used to stamp `model` and `provider` onto outgoing\nmessages. Best-effort: a provider without `getStatus`, a null status, or a\nthrow all yield empty fields — attribution is diagnostic, never load-bearing."
             },
             {
               "kind": "method",
@@ -9465,6 +10155,17 @@
               },
               "description": "Returns true if `releaseAgent` was called during the most recent turn.\nConsumed by the orchestrator to trigger the auto-pin release path."
             },
+            {
+              "kind": "method",
+              "name": "releaseIfRequested",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "description": "Act on a `releaseAgent` call from a tool handler: fire `onDeactivate` and drop the flow lock,\nso the next turn starts clean and the persister does not serialize a flow that is over.\n\nNo-op when the owner handles release (ChatDriverConfig.deferAgentRelease). The flag is\ncleared here rather than only at the next `sendMessage`, so the signal cannot be acted on twice\nand release a later agent that never asked."
+            },
             {
               "kind": "method",
               "name": "getTurnSnapshots",
@@ -9694,7 +10395,8 @@
                     "text": "AllAgentSummary[]"
                   }
                 }
-              ]
+              ],
+              "description": "{@inheritDoc AiDriver.getSuggestions}"
             },
             {
               "kind": "method",
@@ -10011,27 +10713,272 @@
             },
             {
               "kind": "method",
-              "name": "continueFromHistory",
+              "name": "continueFromHistory",
+              "return": {
+                "type": {
+                  "text": "Promise<ChatDriverResult>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "transientPrimer",
+                  "optional": true,
+                  "type": {
+                    "text": "ChatMessage[]"
+                  }
+                }
+              ],
+              "description": "Continue the tool loop from current history without appending a new user message.\nUsed by OrchestratingDriver after an agent handoff."
+            },
+            {
+              "kind": "method",
+              "name": "runToolLoop",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<ChatDriverResult>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "userInput",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "attachments",
+                  "optional": true,
+                  "type": {
+                    "text": "ChatAttachment[]"
+                  }
+                },
+                {
+                  "name": "transientPrimer",
+                  "optional": true,
+                  "type": {
+                    "text": "ChatMessage[]"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "appendDriverNotice",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "content",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Append prose the DRIVER wrote rather than the model — a failure notice, a limit explanation,\nthe budget wall. Renders as an ordinary assistant bubble and is flagged\n`excludeFromProvider`, so it never re-enters the next request.\n\nEvery such notice must go through here. Written as one funnel rather than a flag repeated at\neleven call sites because the failure mode is silent: a notice that keeps the flag reads\nidentically in the transcript to one that loses it, and the damage only shows up a turn later\nas the model echoing its own error message. Measured (GENC-1573): with the empty-response\nnotice in history, the next turn reproduced it verbatim in 45 output tokens — succeeding,\nwith no retry and no `turn.error`, while still showing the user a failure. From there the\nloop sustains itself whether or not the model answers, which is why \"try again\" never worked.\n\nNot for anything the model produced, and not for a widget/interaction message: those are real\nturn content and the model must keep seeing them."
+            },
+            {
+              "kind": "method",
+              "name": "appendToHistory",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "message",
+                  "type": {
+                    "text": "ChatMessage"
+                  }
+                }
+              ]
+            }
+          ],
+          "events": [
+            {
+              "name": "provider-changed",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "interaction-start",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "external-cost-recorded",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "history-updated",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "interaction-stop",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "sub-agent-history-updated",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "sub-agent-start",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "sub-agent-stop",
+              "type": {
+                "text": "CustomEvent"
+              }
+            }
+          ],
+          "superclass": {
+            "name": "EventTarget",
+            "module": "src/components/chat-driver/chat-driver.ts"
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "EMPTY_RESPONSE_NUDGE",
+          "declaration": {
+            "name": "EMPTY_RESPONSE_NUDGE",
+            "module": "./chat-driver.constants"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MALFORMED_CALL_NUDGE",
+          "declaration": {
+            "name": "MALFORMED_CALL_NUDGE",
+            "module": "./chat-driver.constants"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "REQUEST_CONTINUATION_TOOL",
+          "declaration": {
+            "name": "REQUEST_CONTINUATION_TOOL",
+            "module": "./chat-driver.constants"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatDriver",
+          "declaration": {
+            "name": "ChatDriver",
+            "module": "src/components/chat-driver/chat-driver.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/chat-driver/fold-controller.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Tool folds: grouping tools behind a facade so the model sees a small surface, and swapping the\nsurface as it opens and closes them.\n\nOwns the fold stack and the no-progress counter. Everything else it needs is the driver's tool\nsurface, reached through FoldDeps.",
+          "name": "FoldController",
+          "members": [
+            {
+              "kind": "field",
+              "name": "stack",
+              "type": {
+                "text": "FoldStackFrame[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "consecutiveOps",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "Consecutive fold opens/closes with no tool call between them. A model that only opens and\ncloses is making no progress, and the loop breaks out past a ceiling."
+            },
+            {
+              "kind": "method",
+              "name": "reset",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Drop all fold state. Called on an agent swap — each agent starts outside every fold."
+            },
+            {
+              "kind": "method",
+              "name": "activeNames",
+              "return": {
+                "type": {
+                  "text": "string[]"
+                }
+              },
+              "description": "Names of the currently open folds, outermost first."
+            },
+            {
+              "kind": "field",
+              "name": "depth",
+              "type": {
+                "text": "number"
+              },
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "topName",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The innermost open fold's name, or `undefined` when none is open.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "noteOp",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "description": "Count one fold operation and return the new consecutive total."
+            },
+            {
+              "kind": "method",
+              "name": "clearOps",
               "return": {
                 "type": {
-                  "text": "Promise<ChatDriverResult>"
+                  "text": "void"
                 }
               },
-              "parameters": [
-                {
-                  "name": "transientPrimer",
-                  "optional": true,
-                  "type": {
-                    "text": "ChatMessage[]"
-                  }
-                }
-              ],
-              "description": "Continue the tool loop from current history without appending a new user message.\nUsed by OrchestratingDriver after an agent handoff."
+              "description": "Real work happened, so the no-progress streak restarts."
             },
             {
               "kind": "method",
-              "name": "getFold",
-              "privacy": "private",
+              "name": "foldFor",
               "return": {
                 "type": {
                   "text": "ToolFold | undefined"
@@ -10045,12 +10992,11 @@
                   }
                 }
               ],
-              "description": "Extract ToolFold metadata from a handler, or undefined if it isn't a fold facade."
+              "description": "Fold metadata for a tool name, or `undefined` if it is not a fold facade."
             },
             {
               "kind": "method",
-              "name": "findFoldContaining",
-              "privacy": "private",
+              "name": "findContaining",
               "return": {
                 "type": {
                   "text": "string | null"
@@ -10071,12 +11017,11 @@
                   }
                 }
               ],
-              "description": "Search all currently registered fold facades (and their nested folds recursively)\nto find which fold contains a given tool name. Returns the immediate parent fold name."
+              "description": "Which fold to **open** to reach `toolName`, or `null` if no registered fold contains it.\n\nReturns the outermost *registered* ancestor, not the innermost fold holding the tool — the one\nconsumer uses the answer to tell the model what to call next, and a nested fold cannot be\nopened before its parent. The recursion therefore only descends through closed folds: once a\nfold is open its children are top-level in the live handler map and match directly."
             },
             {
               "kind": "method",
-              "name": "foldHidingTool",
-              "privacy": "private",
+              "name": "hidingTool",
               "return": {
                 "type": {
                   "text": "string | null"
@@ -10090,37 +11035,11 @@
                   }
                 }
               ],
-              "description": "If an open fold is hiding a previously-available tool, return the name of\nthe fold to close to start getting it back. Only exclusive folds hide tools\n(they replace the tool set on open rather than extending it), so a base tool\nthat was visible before the fold opened now sits in a fold-stack frame's\n`previousHandlers` but not in the live handler map. Only the top fold's\n`close_` tool is active, so that's always the actionable next step — even\nwhen the tool lives further down the stack, closing repeatedly walks back to\nit. Returns null when no open fold accounts for the tool."
-            },
-            {
-              "kind": "method",
-              "name": "applyFoldToolSet",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "fold",
-                  "type": {
-                    "text": "ToolFold"
-                  }
-                },
-                {
-                  "name": "foldName",
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ],
-              "description": "Install the fold's inner tool set, replacing (exclusive) or extending (non-exclusive)\nthe current tool set. Also injects the close tool. Does NOT touch the fold stack."
+              "description": "If an open fold is hiding a previously-available tool, the fold to close to start getting it\nback, else `null`.\n\nOnly exclusive folds hide tools — they replace the tool set on open rather than extending it —\nso a base tool that was visible beforehand sits in a frame's `previousHandlers` but not in the\nlive map. Only the top fold's `close_` tool is active, so that is always the actionable step:\nclosing repeatedly walks back to a tool further down the stack."
             },
             {
               "kind": "method",
-              "name": "openFold",
-              "privacy": "private",
+              "name": "open",
               "return": {
                 "type": {
                   "text": "Promise<string>"
@@ -10153,83 +11072,49 @@
                   }
                 }
               ],
-              "description": "Open a fold: push a stack frame, swap the tool set, return the response message."
-            },
-            {
-              "kind": "method",
-              "name": "pushFoldFrame",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "foldName",
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ]
+              "description": "Open a fold: push a frame, swap the tool set, and return the response for the model."
             },
             {
               "kind": "method",
-              "name": "closeFold",
-              "privacy": "private",
+              "name": "close",
               "return": {
                 "type": {
                   "text": "string"
                 }
               },
-              "description": "Close the top fold: pop the stack frame, restore the previous tool set."
+              "description": "Close the top fold: pop the frame, restore the tool set it captured."
             },
             {
               "kind": "method",
-              "name": "buildFoldSystemPromptSuffix",
-              "privacy": "private",
+              "name": "systemPromptSuffix",
               "return": {
                 "type": {
                   "text": "string"
                 }
               },
-              "description": "Build the fold-awareness suffix appended to the system prompt each LLM call."
+              "description": "The fold-awareness suffix appended to the system prompt on each LLM call."
             },
             {
               "kind": "method",
-              "name": "runToolLoop",
+              "name": "pushFrame",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "Promise<ChatDriverResult>"
+                  "text": "void"
                 }
               },
               "parameters": [
                 {
-                  "name": "userInput",
+                  "name": "foldName",
                   "type": {
                     "text": "string"
                   }
-                },
-                {
-                  "name": "attachments",
-                  "optional": true,
-                  "type": {
-                    "text": "ChatAttachment[]"
-                  }
-                },
-                {
-                  "name": "transientPrimer",
-                  "optional": true,
-                  "type": {
-                    "text": "ChatMessage[]"
-                  }
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "appendDriverNotice",
+              "name": "applyToolSet",
               "privacy": "private",
               "return": {
                 "type": {
@@ -10238,120 +11123,30 @@
               },
               "parameters": [
                 {
-                  "name": "content",
+                  "name": "fold",
                   "type": {
-                    "text": "string"
+                    "text": "ToolFold"
                   }
-                }
-              ],
-              "description": "Append prose the DRIVER wrote rather than the model — a failure notice, a limit explanation,\nthe budget wall. Renders as an ordinary assistant bubble and is flagged\n`excludeFromProvider`, so it never re-enters the next request.\n\nEvery such notice must go through here. Written as one funnel rather than a flag repeated at\neleven call sites because the failure mode is silent: a notice that keeps the flag reads\nidentically in the transcript to one that loses it, and the damage only shows up a turn later\nas the model echoing its own error message. Measured (GENC-1573): with the empty-response\nnotice in history, the next turn reproduced it verbatim in 45 output tokens — succeeding,\nwith no retry and no `turn.error`, while still showing the user a failure. From there the\nloop sustains itself whether or not the model answers, which is why \"try again\" never worked.\n\nNot for anything the model produced, and not for a widget/interaction message: those are real\nturn content and the model must keep seeing them."
-            },
-            {
-              "kind": "method",
-              "name": "appendToHistory",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
+                },
                 {
-                  "name": "message",
+                  "name": "foldName",
                   "type": {
-                    "text": "ChatMessage"
+                    "text": "string"
                   }
                 }
-              ]
-            }
-          ],
-          "events": [
-            {
-              "name": "provider-changed",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "interaction-start",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "external-cost-recorded",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "history-updated",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "interaction-stop",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "sub-agent-history-updated",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "sub-agent-start",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "sub-agent-stop",
-              "type": {
-                "text": "CustomEvent"
-              }
+              ],
+              "description": "Install the fold's inner tool set, replacing it (exclusive) or extending it (non-exclusive),\nand inject the close tool. Does not touch the stack."
             }
-          ],
-          "superclass": {
-            "name": "EventTarget",
-            "module": "src/components/chat-driver/chat-driver.ts"
-          }
+          ]
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "MALFORMED_CALL_NUDGE",
-          "declaration": {
-            "name": "MALFORMED_CALL_NUDGE",
-            "module": "src/components/chat-driver/chat-driver.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "EMPTY_RESPONSE_NUDGE",
-          "declaration": {
-            "name": "EMPTY_RESPONSE_NUDGE",
-            "module": "src/components/chat-driver/chat-driver.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "REQUEST_CONTINUATION_TOOL",
-          "declaration": {
-            "name": "REQUEST_CONTINUATION_TOOL",
-            "module": "src/components/chat-driver/chat-driver.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "ChatDriver",
+          "name": "FoldController",
           "declaration": {
-            "name": "ChatDriver",
-            "module": "src/components/chat-driver/chat-driver.ts"
+            "name": "FoldController",
+            "module": "src/components/chat-driver/fold-controller.ts"
           }
         }
       ]
@@ -10393,6 +11188,39 @@
           "kind": "variable",
           "name": "Record",
           "description": "The terminal outcomes of a tool loop.\n\n`contextGuard` and `contextOverflow` share a `subReason` because one failure is reached\ntwo ways the user experiences differently: the guard stops at the edge of the window with\nthe transcript intact, so its copy can point at compaction, while an overflow means the\nprovider has already rejected the request.\n\nThree entries take their copy from `@genesislcap/foundation-ai`, which owns the default\nmessage for every failure it also exports an error class for. The rest is for conditions\nthis driver detects itself, which have no upstream home."
+        },
+        {
+          "kind": "function",
+          "name": "turnDone",
+          "return": {
+            "type": {
+              "text": "ChatDriverResult"
+            }
+          },
+          "parameters": [
+            {
+              "name": "failureReason",
+              "optional": true,
+              "type": {
+                "text": "TurnFailureReason"
+              }
+            },
+            {
+              "name": "budget",
+              "optional": true,
+              "type": {
+                "text": "BudgetDetail"
+              }
+            },
+            {
+              "name": "providerRefused",
+              "optional": true,
+              "type": {
+                "text": "ProviderRefusedDetail"
+              }
+            }
+          ],
+          "description": "Build the `done` loop result, carrying the typed failure reason when the turn bailed (PTC-0).\n\nThe discriminant stays `'done'` either way, so consumers matching on `reason === 'done'` are\nunchanged. Both payloads are omitted rather than set to `undefined`, which keeps a happy-path\nresult byte-identical to `{ reason: 'done' }` for a consumer that structurally compares it."
         }
       ],
       "exports": [
@@ -10419,6 +11247,14 @@
             "name": "Record",
             "module": "src/components/chat-driver/turn-failures.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "turnDone",
+          "declaration": {
+            "name": "turnDone",
+            "module": "src/components/chat-driver/turn-failures.ts"
+          }
         }
       ]
     },
@@ -10749,7 +11585,7 @@
               },
               "privacy": "private",
               "readonly": true,
-              "default": "new ChatDriver(providerRegistry, {\n      maxToolIterations: options.maxToolIterations,\n      maxFoldOperations: options.maxFoldOperations,\n      maxTurnSnapshots: options.maxTurnSnapshots,\n      sessionKey: this.sessionKey,\n      activityBus: options.activityBus,\n      budgetExhaustedMessage: options.budgetExhaustedMessage,\n    })"
+              "default": "new ChatDriver(providerRegistry, {\n      maxToolIterations: options.maxToolIterations,\n      maxFoldOperations: options.maxFoldOperations,\n      maxTurnSnapshots: options.maxTurnSnapshots,\n      sessionKey: this.sessionKey,\n      activityBus: options.activityBus,\n      budgetExhaustedMessage: options.budgetExhaustedMessage,\n      // This driver releases after the turn so it can fire the host-facing events; see the option.\n      deferAgentRelease: true,\n    })"
             },
             {
               "kind": "field",
@@ -10807,11 +11643,13 @@
             },
             {
               "kind": "field",
-              "name": "lifecycleAbortController",
+              "name": "agentSession",
+              "type": {
+                "text": "AgentSession"
+              },
               "privacy": "private",
-              "readonly": true,
-              "default": "new AbortController()",
-              "description": "Aborted on driver disposal. Threaded into `AgentLifecycleContext.signal`\nso long-running `onActivate` work can bail if the session disconnects."
+              "description": "The stateful-agent contract (§7.1): active agent, user pin, flow lock, restored state, and\nthe `onActivate` / `onDeactivate` hooks.\n\n**The inner driver's session, not one of our own.** One session is the invariant: two would\nlet the outer and inner driver disagree about which agent is active, and the inner one would\nnever be activated at all, because this driver installs a *decorated* config through\n`applyAgent` rather than going via `ChatDriver.activateAgent`. This driver keeps the routing\ndecisions; the session owns the lifecycle.",
+              "readonly": true
             },
             {
               "kind": "field",
@@ -10833,42 +11671,14 @@
               "default": "false",
               "description": "Whether the CURRENT turn's user message has reached the inner driver's\nhistory. False through the pre-first-turn classify (where the only echo of\nthe message is an optimistic `history-updated` dispatch), true from the\nmoment `chatDriver.sendMessage` is entered — including through every later\nhandoff classify. Read by the budget-wall catch in `sendMessage` to decide\nwhether `reportBudgetExhausted` must append the message itself: appending\nit when already appended duplicated it; not appending it when unappended\nmade it vanish. Reset at the top of each `runOrchestratedTurn`."
             },
-            {
-              "kind": "field",
-              "name": "pinnedAgentName",
-              "type": {
-                "text": "string | null"
-              },
-              "privacy": "private",
-              "default": "null",
-              "description": "Sticky user pick from the picker (or the host's `setAgent` API). Only\nchanges on explicit user action. Survives flow completion: when a stateful\nagent releases, the user-pin stays put and routing falls back to it on\nthe next turn."
-            },
-            {
-              "kind": "field",
-              "name": "flowOwnerAgentName",
-              "type": {
-                "text": "string | null"
-              },
-              "privacy": "private",
-              "default": "null",
-              "description": "Transient flow lock — set when a stateful agent's `onActivate` fires,\ncleared by `releaseActiveAgent`. While non-null, routing precedence goes\nto this agent and the picker is locked. Independent of\n`pinnedAgentName` so completing a flow doesn't wipe the user's sticky\nchoice."
-            },
-            {
-              "kind": "field",
-              "name": "restoredAgentStates",
-              "type": {
-                "text": "Record<string, unknown>"
-              },
-              "privacy": "private",
-              "default": "{}",
-              "description": "Per-agent restored state for a rehydrated session, keyed by agent name.\nPrimed by the host on restore; each entry is passed to that agent's\n`onActivate` as `ctx.restored` on its next activation, then deleted so a\nlater re-activation starts fresh."
-            },
             {
               "kind": "field",
               "name": "activeAgent",
               "type": {
                 "text": "AgentConfig | undefined"
-              }
+              },
+              "description": "The active agent, or `undefined` before the first activation and after a release.\n\nKept as an accessor over `agentSession` rather than removed: it is a public member of an\nexported class, so nothing in this package reading it is not the same as nothing reading it.",
+              "readonly": true
             },
             {
               "kind": "method",