@genesislcap/ai-assistant 15.24.2 → 15.25.0-FUI-2611.1

package/dist/ai-assistant.api.json

@@ -1793,6 +1793,673 @@
           },
           "implementsTokenRanges": []
         },
+        {
+          "kind": "Class",
+          "canonicalReference": "@genesislcap/ai-assistant!AgentSession:class",
+          "docComment": "/**\n * The stateful-agent contract: which agent is active, whether a flow or a user pin holds routing, and the `onActivate` / `onDeactivate` lifecycle around a swap. Either driver can own one.\n *\n * Knows nothing about routing, tool surfaces or transcripts — whether an agent is terminal, the continuation tool, the handoff marker in history all stay with the orchestrator, which is the only thing with agents to route between.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare class AgentSession "
+            }
+          ],
+          "fileUrlPath": "src/components/agent-session/agent-session.ts",
+          "releaseTag": "Beta",
+          "isAbstract": false,
+          "name": "AgentSession",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Constructor",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession:constructor(1)",
+              "docComment": "/**\n * Constructs a new instance of the `AgentSession` class\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "constructor(deps: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AgentSessionDeps",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentSessionDeps:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "deps",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ]
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#activate:member(1)",
+              "docComment": "/**\n * Make `agent` active, firing the lifecycle hooks around the swap: outgoing `onDeactivate` first, then incoming `onActivate`. Both are awaited so heavy activation work (a machine restore, say) completes before the agent's first turn runs, and a throw from either is logged rather than propagated — an agent whose hook fails still activates.\n *\n * Re-activating the same agent by name is not a switch: no hooks fire, no lock moves, and no handoff is recorded. That guard matters because a per-turn re-resolve calls through here.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "activate(agent: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AgentConfig",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentConfig:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AgentTransition",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentTransition:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 7
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "agent",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "activate"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#dispose:member(1)",
+              "docComment": "/**\n * Fire `onDeactivate` on the active agent and abort pending lifecycle work, for session teardown, so machines release resources cleanly. The session is not reusable afterwards: the abort 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 would otherwise be handed an already-aborted signal and have to skip its own work. The cost is that an `onActivate` still in flight keeps running until `onDeactivate` finishes — both hold the same signal. Acceptable because the two are sequenced by `activate`, so overlap only happens if a hook resolves before the work it started; a hook that must stop immediately should own its own cancellation.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "dispose(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<void>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "dispose"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#getActive:member(1)",
+              "docComment": "/**\n * The active agent, or `undefined` before the first activation and after a release.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getActive(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AgentConfig",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentConfig:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getActive"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#getFlowOwner:member(1)",
+              "docComment": "/**\n * The transient flow lock, or `null` when no flow holds routing.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getFlowOwner(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getFlowOwner"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#getLockedName:member(1)",
+              "docComment": "/**\n * The name routing is locked to, flow lock first. A flow in progress outranks the user's sticky pick for the duration of the flow; neither being set means automatic routing.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getLockedName(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getLockedName"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#getPinned:member(1)",
+              "docComment": "/**\n * The sticky user pin, or `null` for automatic routing.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getPinned(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getPinned"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#hasRestoredState:member(1)",
+              "docComment": "/**\n * Whether a restored snapshot is waiting for this agent's next activation.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "hasRestoredState(agentName: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "agentName",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "hasRestoredState"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#primeRestoredStates:member(1)",
+              "docComment": "/**\n * Prime per-agent restored state for a rehydrated session. Replaces any pending entries.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "primeRestoredStates(snapshots: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Record",
+                  "canonicalReference": "!Record:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<string, unknown>"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 4,
+                "endIndex": 5
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "snapshots",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 3
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "primeRestoredStates"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#release:member(1)",
+              "docComment": "/**\n * Release the active agent: fire `onDeactivate` and drop the flow lock.\n *\n * The user pin is intentionally **not** cleared — someone who explicitly picked this agent should stay on it after the flow ends, so the next message starts a fresh flow on the same agent rather than routing through the classifier.\n *\n * Returns `undefined` when there was no active agent, so a caller can skip its events.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "release(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AgentTransition",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentTransition:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 5
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "release"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#setFlowOwner:member(1)",
+              "docComment": "/**\n * Set the flow-owner lock directly — used to restore state on driver reconstruction (agents-array changes, pop-in/pop-out), not to steer routing. Writes without firing hooks or reporting a transition, because the flow it names is already running.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "setFlowOwner(name: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "name",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "setFlowOwner"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSession#setPinned:member(1)",
+              "docComment": "/**\n * Set the sticky user pin. `null` returns to automatic routing.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "setPinned(name: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "name",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "setPinned"
+            }
+          ],
+          "implementsTokenRanges": []
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/ai-assistant!AgentSessionDeps:interface",
+          "docComment": "/**\n * Callbacks an {@link AgentSession} needs from its owner.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface AgentSessionDeps "
+            }
+          ],
+          "fileUrlPath": "src/components/agent-session/agent-session.ts",
+          "releaseTag": "Beta",
+          "name": "AgentSessionDeps",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentSessionDeps#sessionKey:member",
+              "docComment": "/**\n * The debug-log session key, read per call rather than captured: a driver's key is assigned after construction on some paths, so a value captured here would pin the wrong one.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "sessionKey: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "() => string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "sessionKey",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/ai-assistant!AgentTransition:interface",
+          "docComment": "/**\n * What changed when an agent was activated or released.\n *\n * Returned rather than dispatched: the host listens on the `OrchestratingDriver`, not on the `ChatDriver` that owns the session, so a self-dispatching session would need telling which target to fire on.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface AgentTransition "
+            }
+          ],
+          "fileUrlPath": "src/components/agent-session/agent-session.ts",
+          "releaseTag": "Beta",
+          "name": "AgentTransition",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentTransition#flowOwnerChangedTo:member",
+              "docComment": "/**\n * Set when the flow-owner lock changed, to the value it changed *to* (`null` on release). `undefined` means unchanged — distinct from `null`, so a caller can tell \"cleared\" from \"not touched\" without re-reading.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "flowOwnerChangedTo?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "flowOwnerChangedTo",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentTransition#previousAgent:member",
+              "docComment": "/**\n * The agent that was active before, if any.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "previousAgent?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AgentConfig",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentConfig:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "previousAgent",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AgentTransition#switched:member",
+              "docComment": "/**\n * True when the activation was a real swap rather than a re-apply of the same agent.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "switched: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "switched",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/ai-assistant!AiAssistantAnimation:type",
@@ -2671,7 +3338,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@genesislcap/ai-assistant!AiDriver#getActiveAgent:member(1)",
-              "docComment": "/**\n * The live `AgentConfig` currently active in the driver — the instance whose `onActivate` ran, so its `serialize`/`getDebugSnapshot` closures hold live state. Prefer this over looking the agent up in the host's `agents` array, which may mint fresh, never-activated configs. Optional — only drivers that retain the active config implement it.\n */\n",
+              "docComment": "/**\n * The live `AgentConfig` currently active in the driver — the instance whose `onActivate` ran, so its `serialize`/`getDebugSnapshot` closures hold live state. Prefer this over looking the agent up in the host's `agents` array, which may mint fresh, never-activated configs.\n *\n * `undefined` means no agent is active (before the first activation, after a release), which is a different statement from the driver not being able to answer. Both drivers implement it since GENC-1580; see {@link AiDriver.primeRestoredAgentState} for why the `?` stays for now.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -3234,7 +3901,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@genesislcap/ai-assistant!AiDriver#primeRestoredAgentState:member(1)",
-              "docComment": "/**\n * Prime per-agent restored state for a session being rehydrated. Each entry (keyed by agent name) is handed to that agent's `onActivate`/`init` as `ctx.restored` on its next activation, then consumed. Optional — only multi-agent drivers that own agent activation implement it.\n */\n",
+              "docComment": "/**\n * Prime per-agent restored state for a session being rehydrated. Each entry (keyed by agent name) is handed to that agent's `onActivate`/`init` as `ctx.restored` on its next activation, then consumed.\n *\n * Implemented by every driver since GENC-1580 — each owns an `AgentSession` — so \"only multi-agent drivers implement it\" is no longer true. Still declared optional: this interface is exported and `@beta`, so requiring it would break any third party implementing it. The `?` comes off with the `installAgent` rename, which is the ticket's one breaking release.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -3528,6 +4195,96 @@
                 }
               ],
               "name": "setContextGuard"
+            },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AiDriver#setFlowOwner:member(1)",
+              "docComment": "/**\n * Set the transient flow lock — used to restore state on driver reconstruction (agents-array changes, pop-in/pop-out), **not** to steer routing; that is {@link AiDriver.setPinnedAgent}'s job. Writes without firing lifecycle hooks, because the flow it names is already running.\n *\n * Added to the interface in GENC-1580, as for {@link AiDriver.setPinnedAgent}.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "setFlowOwner?(name: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": true,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Beta",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "name",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "setFlowOwner"
+            },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AiDriver#setPinnedAgent:member(1)",
+              "docComment": "/**\n * Pin routing to an agent by name, or `null` for automatic routing. A pin is sticky: it survives a stateful flow completing, so the next turn starts fresh on the same agent.\n *\n * On a driver with nothing to route between this is recorded rather than acted on — the pick belongs to the session, which outlives the question of which driver holds it.\n *\n * Added to the interface in GENC-1580 — it was previously reached by narrowing to `OrchestratingDriver` with `instanceof`. Optional, so adding it breaks no implementor.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "setPinnedAgent?(name: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": true,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Beta",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "name",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "setPinnedAgent"
             }
           ],
           "extendsTokenRanges": [
@@ -4533,35 +5290,89 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ");"
+                  "text": ");"
+                }
+              ],
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "providerRegistry",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "config",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": true
+                }
+              ]
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#activateAgent:member(1)",
+              "docComment": "/**\n * Make `config` the active agent, firing its lifecycle hooks — `onDeactivate` on the outgoing agent, then `onActivate` on this one — before installing it.\n *\n * This is the entry point a host should use. {@link ChatDriver.applyAgent} installs a config *without* firing hooks, which is right for the two callers that need it (the orchestrator, which fires them through the shared session, and `invokeSubAgent`, where a child's config is not an activation) and wrong for everyone else.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "activateAgent(config: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AgentConfig",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentConfig:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<void>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
                 }
               ],
-              "releaseTag": "Public",
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 5
+              },
+              "releaseTag": "Beta",
               "isProtected": false,
               "overloadIndex": 1,
               "parameters": [
                 {
-                  "parameterName": "providerRegistry",
+                  "parameterName": "config",
                   "parameterTypeTokenRange": {
                     "startIndex": 1,
                     "endIndex": 2
                   },
                   "isOptional": false
-                },
-                {
-                  "parameterName": "config",
-                  "parameterTypeTokenRange": {
-                    "startIndex": 3,
-                    "endIndex": 4
-                  },
-                  "isOptional": true
                 }
-              ]
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "activateAgent"
             },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#applyAgent:member(1)",
-              "docComment": "/**\n * Swap in a new agent's configuration. Called by OrchestratingDriver before each specialist turn so the shared driver runs with the right tools and prompt.\n */\n",
+              "docComment": "/**\n * Install `config` as the active agent **without firing lifecycle hooks**.\n *\n * Prefer {@link ChatDriver.activateAgent} unless you are deliberately skipping the hooks. Two callers are: `OrchestratingDriver`, which fires them through the shared {@link ChatDriver.agentSession} and then installs a decorated config, and `invokeSubAgent`, where the child driver's config is a tool surface rather than an activation.\n *\n * Renamed to `installAgent` in a follow-up (GENC-1580) — see `docs/migration-GENC-1580.md`. Until then the name says less than it should, so do not add a third caller to this path without checking which of the two above it resembles.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -4826,9 +5637,14 @@
                   "kind": "Content",
                   "text": "dispose(): "
                 },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
                 {
                   "kind": "Content",
-                  "text": "void"
+                  "text": "<void>"
                 },
                 {
                   "kind": "Content",
@@ -4838,7 +5654,7 @@
               "isStatic": false,
               "returnTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 2
+                "endIndex": 3
               },
               "releaseTag": "Public",
               "isProtected": false,
@@ -4848,6 +5664,42 @@
               "isAbstract": false,
               "name": "dispose"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#getActiveAgent:member(1)",
+              "docComment": "/**\n * The live `AgentConfig` currently active in the driver — the instance whose `onActivate` ran, so its `serialize`/`getDebugSnapshot` closures hold live state. Prefer this over looking the agent up in the host's `agents` array, which may mint fresh, never-activated configs.\n *\n * `undefined` means no agent is active (before the first activation, after a release), which is a different statement from the driver not being able to answer. Both drivers implement it since GENC-1580; see {@link AiDriver.primeRestoredAgentState} for why the `?` stays for now.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getActiveAgent(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AgentConfig",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentConfig:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getActiveAgent"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#getActiveFoldNames:member(1)",
@@ -5337,7 +6189,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#getSuggestions:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Get query suggestions from the AI.\n *\n * @beta\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -5404,7 +6256,7 @@
                 "startIndex": 11,
                 "endIndex": 13
               },
-              "releaseTag": "Public",
+              "releaseTag": "Beta",
               "isProtected": false,
               "overloadIndex": 1,
               "parameters": [
@@ -5605,6 +6457,59 @@
               "isAbstract": false,
               "name": "markAsSubAgent"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#primeRestoredAgentState:member(1)",
+              "docComment": "/**\n * Prime per-agent restored state for a session being rehydrated. Each entry (keyed by agent name) is handed to that agent's `onActivate`/`init` as `ctx.restored` on its next activation, then consumed.\n *\n * Implemented by every driver since GENC-1580 — each owns an `AgentSession` — so \"only multi-agent drivers implement it\" is no longer true. Still declared optional: this interface is exported and `@beta`, so requiring it would break any third party implementing it. The `?` comes off with the `installAgent` rename, which is the ticket's one breaking release.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "primeRestoredAgentState(snapshots: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Record",
+                  "canonicalReference": "!Record:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<string, unknown>"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 4,
+                "endIndex": 5
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "snapshots",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 3
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "primeRestoredAgentState"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#recordExternalCost:member(1)",
@@ -6031,6 +6936,54 @@
               "isAbstract": false,
               "name": "setContextGuard"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#setFlowOwner:member(1)",
+              "docComment": "/**\n * Record the transient flow lock. See {@link AiDriver.setFlowOwner} for the contract.\n *\n * Recorded, not acted on, for the same reason as {@link ChatDriver.setPinnedAgent}.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "setFlowOwner(name: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "name",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "setFlowOwner"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#setHostInteractionRequester:member(1)",
@@ -6097,6 +7050,54 @@
               "isAbstract": false,
               "name": "setHostInteractionRequester"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#setPinnedAgent:member(1)",
+              "docComment": "/**\n * Record the sticky agent pin. See {@link AiDriver.setPinnedAgent} for the contract.\n *\n * Recorded, not acted on: this driver has one agent and nothing to route between, so a pin changes no behaviour here. It is still honoured as state, because the session outlives the question of which driver is holding it — a host that pins before an orchestrator is built would otherwise lose the pick.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "setPinnedAgent(name: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "name",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "setPinnedAgent"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#setProviderHistoryTransform:member(1)",
@@ -6272,6 +7273,33 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriverConfig#deferAgentRelease:member",
+              "docComment": "/**\n * Leave acting on `releaseAgent` to the owner of this driver.\n *\n * Set by `OrchestratingDriver` for its inner driver, which performs the release itself after the turn so it can fire the host-facing `agent-released` / `agent-changed` / `flow-owner-changed` events. Both drivers share one `AgentSession`, so releasing here first would empty it and make the orchestrator's own release a silent no-op — leaving the host with a locked picker and a stale active agent.\n *\n * Left unset, a driver releases its own agent, which is what a bare `ChatDriver` needs: nothing else is watching the flag.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "deferAgentRelease?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "deferAgentRelease",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriverConfig#maxFoldOperations:member",
@@ -7576,7 +8604,7 @@
               "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",
+          "fileUrlPath": "src/components/chat-driver/chat-driver.constants.ts",
           "initializerTokenRange": {
             "startIndex": 1,
             "endIndex": 2
@@ -12000,7 +13028,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#sessionCostUsd:member",
-              "docComment": "/**\n * Aggregated USD cost across every chat turn in this session.\n *\n * Read-only (unlike previously): it is a projection of `sessionUsage`, and a host assigning it would have set a figure the next transcript change overwrites.\n */\n",
+              "docComment": "/**\n * Aggregated USD cost across every chat turn in this session.\n *\n * Read-only: a projection of `sessionUsage`, so an assigned figure would be overwritten by the next transcript change.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -15414,7 +16442,7 @@
               "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",
+          "fileUrlPath": "src/components/chat-driver/chat-driver.constants.ts",
           "initializerTokenRange": {
             "startIndex": 1,
             "endIndex": 2
@@ -15639,29 +16667,33 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#activeAgent:member",
-              "docComment": "",
+              "docComment": "/**\n * The active agent, or `undefined` before the first activation and after a release.\n *\n * Kept as an accessor over `agentSession` rather than removed: it is a public member of an exported class, so nothing in this package reading it is not the same as nothing reading it.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "activeAgent?: "
+                  "text": "get activeAgent(): "
                 },
                 {
                   "kind": "Reference",
                   "text": "AgentConfig",
                   "canonicalReference": "@genesislcap/ai-assistant!AgentConfig:type"
                 },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
                 {
                   "kind": "Content",
                   "text": ";"
                 }
               ],
-              "isReadonly": false,
-              "isOptional": true,
+              "isReadonly": true,
+              "isOptional": false,
               "releaseTag": "Beta",
               "name": "activeAgent",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 2
+                "endIndex": 3
               },
               "isStatic": false,
               "isProtected": false,
@@ -15916,7 +16948,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#getActiveAgent:member(1)",
-              "docComment": "/**\n * The live `AgentConfig` currently active in the driver — the instance whose `onActivate` ran, so its `serialize`/`getDebugSnapshot` closures hold live state. Prefer this over looking the agent up in the host's `agents` array, which may mint fresh, never-activated configs. Optional — only drivers that retain the active config implement it.\n */\n",
+              "docComment": "/**\n * The live `AgentConfig` currently active in the driver — the instance whose `onActivate` ran, so its `serialize`/`getDebugSnapshot` closures hold live state. Prefer this over looking the agent up in the host's `agents` array, which may mint fresh, never-activated configs.\n *\n * `undefined` means no agent is active (before the first activation, after a release), which is a different statement from the driver not being able to answer. Both drivers implement it since GENC-1580; see {@link AiDriver.primeRestoredAgentState} for why the `?` stays for now.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -16518,7 +17550,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#primeRestoredAgentState:member(1)",
-              "docComment": "/**\n * Prime per-agent restored state for a session being rehydrated. Each entry (keyed by agent name) is handed to that agent's `onActivate`/`init` as `ctx.restored` on its next activation, then consumed. Optional — only multi-agent drivers that own agent activation implement it.\n */\n",
+              "docComment": "/**\n * Prime per-agent restored state for a session being rehydrated. Each entry (keyed by agent name) is handed to that agent's `onActivate`/`init` as `ctx.restored` on its next activation, then consumed.\n *\n * Implemented by every driver since GENC-1580 — each owns an `AgentSession` — so \"only multi-agent drivers implement it\" is no longer true. Still declared optional: this interface is exported and `@beta`, so requiring it would break any third party implementing it. The `?` comes off with the `installAgent` rename, which is the ticket's one breaking release.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -17469,7 +18501,7 @@
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/ai-assistant!REQUEST_CONTINUATION_TOOL:var",
-          "docComment": "/**\n * Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver.\n */\n",
+          "docComment": "/**\n * Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -17480,13 +18512,13 @@
               "text": "\"request_continuation\""
             }
           ],
-          "fileUrlPath": "src/components/chat-driver/chat-driver.ts",
+          "fileUrlPath": "src/components/chat-driver/chat-driver.constants.ts",
           "initializerTokenRange": {
             "startIndex": 1,
             "endIndex": 2
           },
           "isReadonly": true,
-          "releaseTag": "Public",
+          "releaseTag": "Beta",
           "name": "REQUEST_CONTINUATION_TOOL",
           "variableTypeTokenRange": {
             "startIndex": 0,
@@ -21250,7 +22282,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#systemPrompt:member",
-              "docComment": "/**\n * The agent's resolved system prompt sent to the LLM, verbatim. NOTE: this is now the *bare* prompt — the fold-surface suffix and the malformed/empty retry nudge no longer mutate it (they kept it byte-unstable and busted prompt caching), so they moved to {@link TurnSnapshot.tailContext}. To reconstruct exactly what the model saw, read both fields.\n */\n",
+              "docComment": "/**\n * The agent's resolved system prompt sent to the LLM, verbatim — the **bare** prompt. The fold-surface suffix and the retry nudges live in {@link TurnSnapshot.tailContext} instead, to keep this byte-stable for prompt caching; read both fields to reconstruct what the model saw.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",