@genesislcap/ai-assistant 14.437.0 → 14.437.2

package/dist/ai-assistant.api.json

@@ -2430,8 +2430,8 @@
                 },
                 {
                   "kind": "Reference",
-                  "text": "ChatToolHandlers",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatToolHandlers:type"
+                  "text": "ToolHandlersInput",
+                  "canonicalReference": "@genesislcap/ai-assistant!ToolHandlersInput:type"
                 },
                 {
                   "kind": "Content",
@@ -4711,16 +4711,25 @@
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n        meta: {\n            timestamp: string;\n            host: string;\n            agentSummary: ({\n                toolDefinitions: string | import(\"../utils/tool-fold\")."
+                  "text": "[];\n        meta: {\n            timestamp: string;\n            host: string;\n            agentSummary: ({\n                toolDefinitions: string | import(\"@genesislcap/foundation-ai\")."
                 },
                 {
                   "kind": "Reference",
-                  "text": "ToolTreeNode",
-                  "canonicalReference": "@genesislcap/ai-assistant!ToolTreeNode:interface"
+                  "text": "ChatToolDefinition",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatToolDefinition:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "[];\n                toolHandlers: any;\n                onActivate: any;\n                onDeactivate: any;\n                getDebugSnapshot: any;\n                description: string;\n                fallback?: never;\n                excludeFromClassifier?: boolean;\n                name: string;\n                displayName?: import(\"../config/config\")."
+                },
+                {
+                  "kind": "Reference",
+                  "text": "SystemPromptInput",
+                  "canonicalReference": "@genesislcap/ai-assistant!SystemPromptInput:type"
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n                toolHandlers: any;\n                onActivate: any;\n                onDeactivate: any;\n                getDebugSnapshot: any;\n                description: string;\n                fallback?: never;\n                excludeFromClassifier?: boolean;\n                name: string;\n                systemPrompt?: import(\"../config/config\")."
+                  "text": ";\n                systemPrompt?: import(\"../config/config\")."
                 },
                 {
                   "kind": "Reference",
@@ -4765,16 +4774,25 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n            } | {\n                toolDefinitions: string | import(\"../utils/tool-fold\")."
+                  "text": ";\n            } | {\n                toolDefinitions: string | import(\"@genesislcap/foundation-ai\")."
                 },
                 {
                   "kind": "Reference",
-                  "text": "ToolTreeNode",
-                  "canonicalReference": "@genesislcap/ai-assistant!ToolTreeNode:interface"
+                  "text": "ChatToolDefinition",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatToolDefinition:interface"
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n                toolHandlers: any;\n                onActivate: any;\n                onDeactivate: any;\n                getDebugSnapshot: any;\n                fallback: true;\n                description?: never;\n                name: string;\n                systemPrompt?: import(\"../config/config\")."
+                  "text": "[];\n                toolHandlers: any;\n                onActivate: any;\n                onDeactivate: any;\n                getDebugSnapshot: any;\n                fallback: true;\n                description?: never;\n                name: string;\n                displayName?: import(\"../config/config\")."
+                },
+                {
+                  "kind": "Reference",
+                  "text": "SystemPromptInput",
+                  "canonicalReference": "@genesislcap/ai-assistant!SystemPromptInput:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";\n                systemPrompt?: import(\"../config/config\")."
                 },
                 {
                   "kind": "Reference",
@@ -4847,7 +4865,7 @@
               "isStatic": false,
               "returnTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 32
+                "endIndex": 36
               },
               "releaseTag": "Beta",
               "isProtected": false,
@@ -7749,6 +7767,50 @@
             }
           ]
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentContext:type",
+          "docComment": "/**\n * Context passed to per-turn resolvers on a stateful agent — the standard {@link SystemPromptContext} plus the live `state` value. Used by `systemPrompt`, `displayName`, and the function form of `toolDefinitions`.\n *\n * Exported so consumers can lift resolvers into separate files without re-deriving the shape.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type StatefulAgentContext<S> = "
+            },
+            {
+              "kind": "Reference",
+              "text": "SystemPromptContext",
+              "canonicalReference": "@genesislcap/ai-assistant!SystemPromptContext:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " & {\n    state: S;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/config/define-stateful-agent.ts",
+          "releaseTag": "Beta",
+          "name": "StatefulAgentContext",
+          "typeParameters": [
+            {
+              "typeParameterName": "S",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 3
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit:interface",
@@ -7832,6 +7894,51 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#displayName:member",
+              "docComment": "/**\n * Per-turn display label, e.g. \"Guided Booking (Counterparties)\". Resolved each tool-loop iteration and stamped onto outgoing messages and the debug-log timeline — display only. The agent's `name` stays as the canonical identity used for routing/history filtering.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "displayName?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "(ctx: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "StatefulAgentContext",
+                  "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentContext:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<S>) => string | "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<string>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "displayName",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 6
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#dispose:member",
@@ -8110,12 +8217,12 @@
                 },
                 {
                   "kind": "Reference",
-                  "text": "SystemPromptContext",
-                  "canonicalReference": "@genesislcap/ai-assistant!SystemPromptContext:interface"
+                  "text": "StatefulAgentContext",
+                  "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentContext:type"
                 },
                 {
                   "kind": "Content",
-                  "text": " & {\n        state: S;\n    }) => string | "
+                  "text": "<S>) => string | "
                 },
                 {
                   "kind": "Reference",
@@ -8160,12 +8267,12 @@
                 },
                 {
                   "kind": "Reference",
-                  "text": "SystemPromptContext",
-                  "canonicalReference": "@genesislcap/ai-assistant!SystemPromptContext:interface"
+                  "text": "StatefulAgentContext",
+                  "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentContext:type"
                 },
                 {
                   "kind": "Content",
-                  "text": " & {\n        state: S;\n    }) => "
+                  "text": "<S>) => "
                 },
                 {
                   "kind": "Reference",
@@ -8211,7 +8318,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#toolHandlers:member",
-              "docComment": "/**\n * Factory returning the tool handler map. Called with the live `state` at `onActivate` time; the handlers it returns are cached for the lifetime of this activation. Each handler closes over `state` and any other deps you captured.\n *\n * The handler set returned must be the **union** of every tool name your agent might advertise across all states — `toolDefinitions` filters which are visible to the LLM per turn, but every name still needs an entry here.\n */\n",
+              "docComment": "/**\n * Factory returning the handler map for the **current state**. Called each tool-loop iteration with the live `state` value, so the handler set the driver dispatches against matches what `toolDefinitions` exposes to the LLM that turn. Return only the handlers valid right now — no need to advertise every handler the agent might ever expose, and no defensive `if (!machine.matches(...))` guards inside each handler.\n *\n * Pair with the function form of `toolDefinitions` so the visible tools and the dispatchable handlers stay in lockstep.\n *\n * **Constraint:** resolved handlers must not include fold facades. Folds and state-machine-driven tool filtering both try to control the LLM's tool view — pick one. Helper samples once on activation (init state) and throws if a fold-tagged handler is detected; subsequent resolves also validate, so misuse on a non-init state surfaces when that state is reached.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -8226,6 +8333,28 @@
                   "text": "ChatToolHandlers",
                   "canonicalReference": "@genesislcap/foundation-ai!ChatToolHandlers:type"
                 },
+                {
+                  "kind": "Content",
+                  "text": " | "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatToolHandlers",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatToolHandlers:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">"
+                },
                 {
                   "kind": "Content",
                   "text": ";"
@@ -8237,7 +8366,7 @@
               "name": "toolHandlers",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 3
+                "endIndex": 8
               }
             }
           ],
@@ -8619,6 +8748,73 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/ai-assistant!ToolHandlersInput:type",
+          "docComment": "/**\n * Tool handlers for an agent. Either a static map (the conventional shape) or a function resolved each tool-loop iteration. The function form lets the agent narrow the dispatchable handler set per turn — pair it with the function form of `toolDefinitions` so the LLM-visible tools and the dispatchable handlers stay in lockstep, and handlers don't have to defend themselves against being dispatched in states where their tool isn't advertised.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ToolHandlersInput = "
+            },
+            {
+              "kind": "Reference",
+              "text": "ChatToolHandlers",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatToolHandlers:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | ((ctx: "
+            },
+            {
+              "kind": "Reference",
+              "text": "SystemPromptContext",
+              "canonicalReference": "@genesislcap/ai-assistant!SystemPromptContext:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ") => "
+            },
+            {
+              "kind": "Reference",
+              "text": "ChatToolHandlers",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatToolHandlers:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | "
+            },
+            {
+              "kind": "Reference",
+              "text": "Promise",
+              "canonicalReference": "!Promise:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "ChatToolHandlers",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatToolHandlers:type"
+            },
+            {
+              "kind": "Content",
+              "text": ">)"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/config/config.ts",
+          "releaseTag": "Beta",
+          "name": "ToolHandlersInput",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 11
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!ToolTreeNode:interface",
@@ -8698,6 +8894,33 @@
           "name": "TurnSnapshot",
           "preserveMemberOrder": false,
           "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#agentLabel:member",
+              "docComment": "/**\n * Per-turn display label resolved from the agent's `displayName`, e.g. \"Guided Booking (Counterparties)\". `agentName` stays as the canonical identity used for routing/filtering.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "agentLabel?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "agentLabel",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#agentName:member",

package/dist/ai-assistant.d.ts

@@ -5,7 +5,7 @@ import type { ChatConfig } from '@genesislcap/foundation-ai';
 import type { ChatDriverResult } from '@genesislcap/foundation-ai';
 import type { ChatInputDuringExecutionMode } from '@genesislcap/foundation-ai';
 import type { ChatMessage } from '@genesislcap/foundation-ai';
-import type { ChatToolDefinition } from '@genesislcap/foundation-ai';
+import { ChatToolDefinition } from '@genesislcap/foundation-ai';
 import type { ChatToolHandlers } from '@genesislcap/foundation-ai';
 import { GenesisElement } from '@genesislcap/web-core';
 import type { InteractionRequestOptions } from '@genesislcap/foundation-ai';
@@ -376,9 +376,21 @@ export declare const ANIMATION_DEFS: {
 
 declare interface BaseAgentConfig {
     /**
-     * Display name shown in the chat header when this agent is active.
+     * Stable identity for this agent. Used for classifier routing, manual
+     * pinning, and history filtering — must not vary per turn. For a per-turn
+     * display label (e.g. "Guided Booking (Counterparties)"), supply
+     * {@link BaseAgentConfig.displayName}.
      */
     name: string;
+    /**
+     * Optional per-turn display label. Resolved each tool-loop iteration and
+     * stamped onto outgoing messages (`agentLabel`) and the debug-log timeline.
+     * Renderers fall back to `name` when this is unset. Use the function form
+     * to vary the label by current state (e.g. a state machine's step).
+     *
+     * Identity stays on `name` — this is for UX only.
+     */
+    displayName?: SystemPromptInput;
     /**
      * System prompt injected into every conversation turn for this agent.
      *
@@ -398,8 +410,13 @@ declare interface BaseAgentConfig {
     toolDefinitions?: ToolDefinitionsInput;
     /**
      * Tool handler implementations for this agent.
+     *
+     * Either a static map or a function resolved each tool-loop iteration —
+     * pick the function form to narrow the dispatchable handler set per turn,
+     * matching the function form of `toolDefinitions`.
+     * See {@link ToolHandlersInput}.
      */
-    toolHandlers?: ChatToolHandlers;
+    toolHandlers?: ToolHandlersInput;
     /**
      * Optional primer history prepended to every call (not visible to the user).
      * Used to establish agent identity and behavioural rules.
@@ -486,9 +503,31 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * in that case.
      */
     private toolDefinitionsFactory?;
+    /**
+     * Resolved tool handler map used for dispatch. When `toolHandlersFactory` is
+     * set, this is overwritten each tool-loop iteration with the factory's output
+     * — keeping it in lockstep with `toolDefinitions` so handlers don't have to
+     * defend themselves against being dispatched in states where their tool
+     * isn't advertised. Folds mutate this in place; `defineStatefulAgent`
+     * forbids folds when a factory is set, so the fold-mutation path is
+     * unreachable in that case.
+     */
     private toolHandlers;
+    /**
+     * Optional per-turn handler-map source. Mirrors `toolDefinitionsFactory` so
+     * the LLM-visible tools and the dispatchable handlers can be narrowed in
+     * lockstep. Resolved each tool-loop iteration before the LLM call.
+     */
+    private toolHandlersFactory?;
     private primerHistory?;
     private activeAgentName?;
+    /**
+     * Per-turn display label resolved from the agent's `displayName`. Stamped
+     * onto outgoing messages and turn snapshots for UX; `activeAgentName` stays
+     * stable for routing/history-transform identity matching.
+     */
+    private activeAgentLabel?;
+    private displayName?;
     /**
      * When set, `requestInteraction` delegates to this callback instead of using
      * this driver's own pending map. Wired by `invokeSubAgent` so a sub-agent's
@@ -538,7 +577,7 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     /** Captured from `applyAgent` so we don't store the whole `AgentConfig`. */
     private debugSnapshotter?;
     private readonly maxTurnSnapshots;
-    constructor(aiProvider: AIProvider, toolHandlers?: ChatToolHandlers, toolDefinitions?: ToolDefinitionsInput, systemPrompt?: SystemPromptInput, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number, maxTurnSnapshots?: number);
+    constructor(aiProvider: AIProvider, toolHandlers?: ToolHandlersInput, toolDefinitions?: ToolDefinitionsInput, systemPrompt?: SystemPromptInput, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number, maxTurnSnapshots?: number);
     /**
      * 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.
@@ -1084,7 +1123,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
             timestamp: string;
             host: string;
             agentSummary: ({
-                toolDefinitions: string | ToolTreeNode[];
+                toolDefinitions: string | ChatToolDefinition[];
                 toolHandlers: any;
                 onActivate: any;
                 onDeactivate: any;
@@ -1093,13 +1132,14 @@ export declare class FoundationAiAssistant extends GenesisElement {
                 fallback?: never;
                 excludeFromClassifier?: boolean;
                 name: string;
+                displayName?: SystemPromptInput;
                 systemPrompt?: SystemPromptInput;
                 primerHistory?: ChatMessage[];
                 subAgents?: AgentConfig[];
                 chatInputDuringExecution?: ChatInputDuringExecutionMode;
                 manualSelection?: ManualSelectionConfig;
             } | {
-                toolDefinitions: string | ToolTreeNode[];
+                toolDefinitions: string | ChatToolDefinition[];
                 toolHandlers: any;
                 onActivate: any;
                 onDeactivate: any;
@@ -1107,6 +1147,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
                 fallback: true;
                 description?: never;
                 name: string;
+                displayName?: SystemPromptInput;
                 systemPrompt?: SystemPromptInput;
                 primerHistory?: ChatMessage[];
                 subAgents?: AgentConfig[];
@@ -1352,6 +1393,20 @@ export declare interface SpecialistAgentConfig extends BaseAgentConfig {
     excludeFromClassifier?: boolean;
 }
 
+/**
+ * Context passed to per-turn resolvers on a stateful agent — the standard
+ * {@link SystemPromptContext} plus the live `state` value. Used by
+ * `systemPrompt`, `displayName`, and the function form of `toolDefinitions`.
+ *
+ * Exported so consumers can lift resolvers into separate files without
+ * re-deriving the shape.
+ *
+ * @beta
+ */
+export declare type StatefulAgentContext<S> = SystemPromptContext & {
+    state: S;
+};
+
 /**
  * Init options for {@link defineStatefulAgent}. Generic over the state shape `S`
  * the agent owns (a state machine, an observable controller, anything).
@@ -1399,9 +1454,14 @@ export declare interface StatefulAgentInit<S> {
      * iteration. Use this to feed the LLM whatever the current state implies
      * (e.g. a state machine's `meta.systemPrompt` plus captured context).
      */
-    systemPrompt?: (ctx: SystemPromptContext & {
-        state: S;
-    }) => string | Promise<string>;
+    systemPrompt?: (ctx: StatefulAgentContext<S>) => string | Promise<string>;
+    /**
+     * Per-turn display label, e.g. "Guided Booking (Counterparties)". Resolved
+     * each tool-loop iteration and stamped onto outgoing messages and the
+     * debug-log timeline — display only. The agent's `name` stays as the
+     * canonical identity used for routing/history filtering.
+     */
+    displayName?: (ctx: StatefulAgentContext<S>) => string | Promise<string>;
     /**
      * Tool definitions the LLM sees. Either a static array (resolved once) or a
      * function resolved each tool-loop iteration. The function form is how a
@@ -1413,20 +1473,26 @@ export declare interface StatefulAgentInit<S> {
      * has to be in charge. Helper throws at init time if a fold-tagged handler
      * is detected.
      */
-    toolDefinitions?: ChatToolDefinition[] | ((ctx: SystemPromptContext & {
-        state: S;
-    }) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>);
+    toolDefinitions?: ChatToolDefinition[] | ((ctx: StatefulAgentContext<S>) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>);
     /**
-     * Factory returning the tool handler map. Called with the live `state` at
-     * `onActivate` time; the handlers it returns are cached for the lifetime of
-     * this activation. Each handler closes over `state` and any other deps you
-     * captured.
+     * Factory returning the handler map for the **current state**. Called each
+     * tool-loop iteration with the live `state` value, so the handler set the
+     * driver dispatches against matches what `toolDefinitions` exposes to the
+     * LLM that turn. Return only the handlers valid right now — no need to
+     * advertise every handler the agent might ever expose, and no defensive
+     * `if (!machine.matches(...))` guards inside each handler.
+     *
+     * Pair with the function form of `toolDefinitions` so the visible tools and
+     * the dispatchable handlers stay in lockstep.
      *
-     * The handler set returned must be the **union** of every tool name your
-     * agent might advertise across all states — `toolDefinitions` filters which
-     * are visible to the LLM per turn, but every name still needs an entry here.
+     * **Constraint:** resolved handlers must not include fold facades. Folds and
+     * state-machine-driven tool filtering both try to control the LLM's tool
+     * view — pick one. Helper samples once on activation (init state) and
+     * throws if a fold-tagged handler is detected; subsequent resolves also
+     * validate, so misuse on a non-init state surfaces when that state is
+     * reached.
      */
-    toolHandlers?: (state: S) => ChatToolHandlers;
+    toolHandlers?: (state: S) => ChatToolHandlers | Promise<ChatToolHandlers>;
     /**
      * Optional getter for the debug-log snapshot. Defaults to auto-snapshotting
      * any property on `state` that looks like a foundation-state-machine
@@ -1553,6 +1619,18 @@ export declare interface ToolFoldResult {
     handler: ChatToolHandlers;
 }
 
+/**
+ * Tool handlers for an agent. Either a static map (the conventional shape) or a
+ * function resolved each tool-loop iteration. The function form lets the agent
+ * narrow the dispatchable handler set per turn — pair it with the function form
+ * of `toolDefinitions` so the LLM-visible tools and the dispatchable handlers
+ * stay in lockstep, and handlers don't have to defend themselves against being
+ * dispatched in states where their tool isn't advertised.
+ *
+ * @beta
+ */
+export declare type ToolHandlersInput = ChatToolHandlers | ((ctx: SystemPromptContext) => ChatToolHandlers | Promise<ChatToolHandlers>);
+
 /**
  * A tool entry in the expanded debug tree.
  * Folds are represented as nodes with a `tools` array; regular tools have none.
@@ -1585,6 +1663,12 @@ export declare interface TurnSnapshot {
     systemPrompt?: string;
     /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
     toolNames: string[];
+    /**
+     * Per-turn display label resolved from the agent's `displayName`, e.g.
+     * "Guided Booking (Counterparties)". `agentName` stays as the canonical
+     * identity used for routing/filtering.
+     */
+    agentLabel?: string;
     /** Agent-supplied snapshot — machine state/context for stateful agents, undefined otherwise. */
     agentSnapshot?: unknown;
 }

package/dist/dts/components/chat-driver/chat-driver.d.ts

@@ -1,5 +1,5 @@
-import type { AIProvider, ChatAttachment, ChatDriverResult, ChatMessage, ChatToolHandlers, InteractionRequestOptions } from '@genesislcap/foundation-ai';
-import type { AgentConfig, SystemPromptInput, ToolDefinitionsInput } from '../../config/config';
+import type { AIProvider, ChatAttachment, ChatDriverResult, ChatMessage, InteractionRequestOptions } from '@genesislcap/foundation-ai';
+import type { AgentConfig, SystemPromptInput, ToolDefinitionsInput, ToolHandlersInput } from '../../config/config';
 import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
 /** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
 export declare const REQUEST_CONTINUATION_TOOL = "request_continuation";
@@ -30,6 +30,12 @@ export interface TurnSnapshot {
     systemPrompt?: string;
     /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
     toolNames: string[];
+    /**
+     * Per-turn display label resolved from the agent's `displayName`, e.g.
+     * "Guided Booking (Counterparties)". `agentName` stays as the canonical
+     * identity used for routing/filtering.
+     */
+    agentLabel?: string;
     /** Agent-supplied snapshot — machine state/context for stateful agents, undefined otherwise. */
     agentSnapshot?: unknown;
 }
@@ -63,9 +69,31 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * in that case.
      */
     private toolDefinitionsFactory?;
+    /**
+     * Resolved tool handler map used for dispatch. When `toolHandlersFactory` is
+     * set, this is overwritten each tool-loop iteration with the factory's output
+     * — keeping it in lockstep with `toolDefinitions` so handlers don't have to
+     * defend themselves against being dispatched in states where their tool
+     * isn't advertised. Folds mutate this in place; `defineStatefulAgent`
+     * forbids folds when a factory is set, so the fold-mutation path is
+     * unreachable in that case.
+     */
     private toolHandlers;
+    /**
+     * Optional per-turn handler-map source. Mirrors `toolDefinitionsFactory` so
+     * the LLM-visible tools and the dispatchable handlers can be narrowed in
+     * lockstep. Resolved each tool-loop iteration before the LLM call.
+     */
+    private toolHandlersFactory?;
     private primerHistory?;
     private activeAgentName?;
+    /**
+     * Per-turn display label resolved from the agent's `displayName`. Stamped
+     * onto outgoing messages and turn snapshots for UX; `activeAgentName` stays
+     * stable for routing/history-transform identity matching.
+     */
+    private activeAgentLabel?;
+    private displayName?;
     /**
      * When set, `requestInteraction` delegates to this callback instead of using
      * this driver's own pending map. Wired by `invokeSubAgent` so a sub-agent's
@@ -115,7 +143,7 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     /** Captured from `applyAgent` so we don't store the whole `AgentConfig`. */
     private debugSnapshotter?;
     private readonly maxTurnSnapshots;
-    constructor(aiProvider: AIProvider, toolHandlers?: ChatToolHandlers, toolDefinitions?: ToolDefinitionsInput, systemPrompt?: SystemPromptInput, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number, maxTurnSnapshots?: number);
+    constructor(aiProvider: AIProvider, toolHandlers?: ToolHandlersInput, toolDefinitions?: ToolDefinitionsInput, systemPrompt?: SystemPromptInput, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number, maxTurnSnapshots?: number);
     /**
      * 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.