@genesislcap/ai-assistant 14.437.0 → 14.437.2

package/src/components/chat-driver/chat-driver.ts

@@ -16,6 +16,7 @@ import type {
   SystemPromptContext,
   SystemPromptInput,
   ToolDefinitionsInput,
+  ToolHandlersInput,
 } from '../../config/config';
 import { applyHistoryCap } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
@@ -65,6 +66,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;
 }
@@ -114,9 +121,33 @@ export class ChatDriver extends EventTarget implements AiDriver {
   private toolDefinitionsFactory?: (
     ctx: SystemPromptContext,
   ) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>;
+  /**
+   * 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: ChatToolHandlers;
+  /**
+   * 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?: (
+    ctx: SystemPromptContext,
+  ) => ChatToolHandlers | Promise<ChatToolHandlers>;
   private primerHistory?: ChatMessage[];
   private activeAgentName?: string;
+  /**
+   * 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?: string;
+  private displayName?: SystemPromptInput;
   /**
    * When set, `requestInteraction` delegates to this callback instead of using
    * this driver's own pending map. Wired by `invokeSubAgent` so a sub-agent's
@@ -175,7 +206,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
   constructor(
     private readonly aiProvider: AIProvider,
-    toolHandlers: ChatToolHandlers = {},
+    toolHandlers: ToolHandlersInput = {},
     toolDefinitions: ToolDefinitionsInput = [],
     systemPrompt?: SystemPromptInput,
     primerHistory?: ChatMessage[],
@@ -184,7 +215,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
     maxTurnSnapshots: number = DEFAULT_MAX_TURN_SNAPSHOTS,
   ) {
     super();
-    this.toolHandlers = toolHandlers;
+    if (typeof toolHandlers === 'function') {
+      this.toolHandlersFactory = toolHandlers;
+      this.toolHandlers = {};
+    } else {
+      this.toolHandlersFactory = undefined;
+      this.toolHandlers = toolHandlers;
+    }
     if (typeof toolDefinitions === 'function') {
       this.toolDefinitionsFactory = toolDefinitions;
       this.toolDefinitions = [];
@@ -213,9 +250,23 @@ export class ChatDriver extends EventTarget implements AiDriver {
       this.toolDefinitionsFactory = undefined;
       this.toolDefinitions = config.toolDefinitions ?? [];
     }
-    this.toolHandlers = config.toolHandlers ?? {};
+    if (typeof config.toolHandlers === 'function') {
+      this.toolHandlersFactory = config.toolHandlers;
+      // Cleared each turn by the factory in runToolLoop; empty is safe in the
+      // meantime (no LLM call happens before resolution).
+      this.toolHandlers = {};
+    } else {
+      this.toolHandlersFactory = undefined;
+      this.toolHandlers = config.toolHandlers ?? {};
+    }
     this.primerHistory = config.primerHistory;
     this.activeAgentName = config.name;
+    this.displayName = config.displayName;
+    // Static string form resolves to a stable label up-front; the function
+    // form gets re-resolved each tool-loop iteration. Falls back to the
+    // canonical name when displayName is unset.
+    this.activeAgentLabel =
+      typeof config.displayName === 'string' ? config.displayName : config.name;
     this.debugSnapshotter = config.getDebugSnapshot;
     this.subAgentsMap = new Map((config.subAgents ?? []).map((s) => [s.name, s]));
     // Reset fold state when agent changes — each specialist starts fresh
@@ -273,6 +324,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       turnIndex,
       timestamp: new Date().toISOString(),
       agentName: this.activeAgentName,
+      agentLabel: this.activeAgentLabel,
       systemPrompt: resolvedSystemPrompt,
       toolNames: this.toolDefinitions.map((t) => t.name),
       agentSnapshot,
@@ -835,6 +887,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
   // Tool loop
   // ---------------------------------------------------------------------------
 
+  // eslint-disable-next-line complexity
   private async runToolLoop(
     userInput: string,
     attachments?: ChatAttachment[],
@@ -877,6 +930,14 @@ export class ChatDriver extends EventTarget implements AiDriver {
         // eslint-disable-next-line no-await-in-loop
         this.toolDefinitions = await this.toolDefinitionsFactory(promptCtx);
       }
+      // Same story for the handler-map factory: re-resolve so dispatch sees
+      // only the handlers valid for the current state, in lockstep with the
+      // tool definitions exposed above. Folds are forbidden when this is set,
+      // so the fold-mutation paths on `this.toolHandlers` are unreachable.
+      if (this.toolHandlersFactory) {
+        // eslint-disable-next-line no-await-in-loop
+        this.toolHandlers = await this.toolHandlersFactory(promptCtx);
+      }
 
       const resolvedSystemPrompt =
         typeof this.systemPrompt === 'function'
@@ -884,6 +945,15 @@ export class ChatDriver extends EventTarget implements AiDriver {
             await this.systemPrompt(promptCtx)
           : this.systemPrompt;
 
+      // Re-resolve the per-turn display label. Falls back to the canonical
+      // agent name when displayName is unset. Stamped onto outgoing messages
+      // and turn snapshots for UX only; routing/history-transform continues
+      // to read `activeAgentName`.
+      if (typeof this.displayName === 'function') {
+        // eslint-disable-next-line no-await-in-loop
+        this.activeAgentLabel = await this.displayName(promptCtx);
+      }
+
       const foldSuffix = this.buildFoldSystemPromptSuffix();
       const baseSystemPrompt = resolvedSystemPrompt
         ? `${resolvedSystemPrompt}${foldSuffix}`
@@ -1198,7 +1268,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
   private appendToHistory(message: ChatMessage): void {
     const tagged: ChatMessage = this.activeAgentName
-      ? { ...message, agentName: this.activeAgentName }
+      ? {
+          ...message,
+          agentName: this.activeAgentName,
+          // Display-only — falls back to agentName in renderers when unset.
+          agentLabel: this.activeAgentLabel,
+        }
       : message;
     this.history = [...this.history, tagged];
     this.dispatchEvent(

package/src/config/config.ts

@@ -61,6 +61,20 @@ export type ToolDefinitionsInput =
   | ChatToolDefinition[]
   | ((ctx: SystemPromptContext) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>);
 
+/**
+ * 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 type ToolHandlersInput =
+  | ChatToolHandlers
+  | ((ctx: SystemPromptContext) => ChatToolHandlers | Promise<ChatToolHandlers>);
+
 /**
  * Opts an agent in to manual selection from the assistant's agent picker.
  *
@@ -83,9 +97,21 @@ export interface ManualSelectionConfig {
 
 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.
    *
@@ -105,8 +131,13 @@ 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.

package/src/config/define-stateful-agent.ts

@@ -6,9 +6,23 @@ import type {
   ChatInputDuringExecutionMode,
   ManualSelectionConfig,
   SystemPromptContext,
+  SystemPromptInput,
   ToolDefinitionsInput,
+  ToolHandlersInput,
 } from './config';
 
+/**
+ * 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 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).
@@ -57,7 +71,15 @@ export 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
@@ -72,21 +94,27 @@ export interface StatefulAgentInit<S> {
    */
   toolDefinitions?:
     | ChatToolDefinition[]
-    | ((
-        ctx: SystemPromptContext & { state: S },
-      ) => ChatToolDefinition[] | Promise<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
@@ -163,7 +191,6 @@ function defaultStatefulDebugSnapshot(state: unknown): unknown {
  */
 export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig {
   let state: S | undefined;
-  let cachedHandlers: ChatToolHandlers | undefined;
 
   const assertNoFolds = (handlers: ChatToolHandlers): void => {
     for (const [name, handler] of Object.entries(handlers)) {
@@ -194,62 +221,51 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
     return td;
   })();
 
-  // Each proxy entry calls into `cachedHandlers`, which is populated eagerly
-  // inside `onActivate` (see below). Eager population means the no-folds
-  // assertion fires at activation time — not on first tool call — so a
-  // misconfigured agent fails loud and immediately instead of silently
-  // appearing to work until the LLM happens to invoke a tool.
-  const buildHandlerProxy = (names: readonly string[]): ChatToolHandlers => {
-    const out: ChatToolHandlers = {};
-    for (const name of names) {
-      out[name] = async (args, ctx) => {
-        if (!state || !cachedHandlers) {
-          throw new Error(`Stateful agent "${opts.name}" handler called before init`);
-        }
-        const handler = cachedHandlers[name];
-        if (!handler) {
-          throw new Error(`Tool "${name}" has no handler on stateful agent "${opts.name}"`);
+  // Wrap the handler factory into the ctx-shaped form the driver expects, and
+  // validate folds on each resolve. The driver re-resolves this per tool-loop
+  // iteration, so the handler set the driver dispatches against always
+  // matches the LLM-visible tools for the current state — handlers don't need
+  // defensive `if (!machine.matches(...))` guards.
+  const wrappedHandlers: ToolHandlersInput | undefined = opts.toolHandlers
+    ? async () => {
+        if (!state) {
+          throw new Error(`Stateful agent "${opts.name}" handlers called before init`);
         }
-        return handler(args, ctx);
-      };
-    }
-    return out;
-  };
-
-  // Static-tools case: handler names are knowable from the definitions array.
-  // Dynamic-tools case: we discover names from a sample of `toolHandlers(state)`
-  // taken inside onActivate. Until then, the handler dict is empty — fine
-  // because no tool call can happen before activation completes.
-  const staticHandlerProxy =
-    Array.isArray(opts.toolDefinitions) && opts.toolHandlers
-      ? buildHandlerProxy(opts.toolDefinitions.map((d) => d.name))
-      : undefined;
+        const handlers = await opts.toolHandlers!(state);
+        assertNoFolds(handlers);
+        return handlers;
+      }
+    : undefined;
 
-  // For the dynamic case we patch this object in place on activation. The
-  // driver reads `toolHandlers` by reference, so mutating in place is enough.
-  const resolvedHandlers: ChatToolHandlers = staticHandlerProxy ?? {};
+  const wrappedDisplayName: SystemPromptInput | undefined = opts.displayName
+    ? async (ctx: SystemPromptContext) => {
+        if (!state) {
+          throw new Error(`Stateful agent "${opts.name}" displayName called before init`);
+        }
+        return opts.displayName!({ ...ctx, state });
+      }
+    : undefined;
 
   const base = {
     name: opts.name,
+    displayName: wrappedDisplayName,
     primerHistory: opts.primerHistory,
     subAgents: opts.subAgents,
     manualSelection: opts.manualSelection,
     chatInputDuringExecution: opts.chatInputDuringExecution,
     toolDefinitions: wrappedTools,
-    toolHandlers: opts.toolHandlers ? resolvedHandlers : undefined,
+    toolHandlers: wrappedHandlers,
 
     onActivate: async (ctx: AgentLifecycleContext) => {
       state = await opts.init(ctx);
-      // Sample handlers eagerly and validate up-front. Throws here are visible
-      // at the agent-switch boundary instead of buried inside a future tool
-      // dispatch.
-      cachedHandlers = opts.toolHandlers?.(state) ?? {};
-      assertNoFolds(cachedHandlers);
-      // Dynamic-tools path: handler names are discovered from the sample.
-      if (!staticHandlerProxy && opts.toolHandlers) {
-        const dynamicProxy = buildHandlerProxy(Object.keys(cachedHandlers));
-        for (const key of Object.keys(resolvedHandlers)) delete resolvedHandlers[key];
-        Object.assign(resolvedHandlers, dynamicProxy);
+      // Sample once with the init state to fail loud on fold misuse at the
+      // agent-switch boundary instead of waiting for the first tool call.
+      // The driver re-resolves the factory each iteration, so misuse on
+      // handlers gated behind a non-init state surfaces when that state is
+      // reached — same loud failure mode, narrower coverage.
+      if (opts.toolHandlers) {
+        const sampled = await opts.toolHandlers(state);
+        assertNoFolds(sampled);
       }
     },
 
@@ -261,7 +277,6 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
       // cannot interleave the read-then-write of `state`.
       // eslint-disable-next-line require-atomic-updates
       state = undefined;
-      cachedHandlers = undefined;
     },
 
     systemPrompt: opts.systemPrompt

package/src/main/main.template.ts

@@ -233,7 +233,7 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
                 messageType(m) === 'ai-function' &&
                 m.agentName &&
                 (c.parent as FoundationAiAssistant).showAgentSwitchIndicator
-                  ? `Tool Call · ${m.agentName}`
+                  ? `Tool Call · ${m.agentLabel ?? m.agentName}`
                   : senderLabel[messageType(m)]}
             </div>
             <div class="content">

package/src/main/main.ts

@@ -113,9 +113,10 @@ avoidTreeShaking(
  * Recursively strips non-serializable fields from an agent before storing in Redux:
  *  - `toolHandlers` (functions),
  *  - `onActivate` / `onDeactivate` (lifecycle hooks, functions),
- *  - function-form `systemPrompt` / `toolDefinitions` (downgraded to `undefined`
- *    in the snapshot — the live config on the driver is still the source of
- *    truth; the slice only stores a serializable projection).
+ *  - `getDebugSnapshot` (function),
+ *  - function-form `systemPrompt` / `toolDefinitions` / `displayName` (downgraded
+ *    to `undefined` in the snapshot — the live config on the driver is still
+ *    the source of truth; the slice only stores a serializable projection).
  */
 function stripHandlers(agent: AgentConfig): Omit<AgentConfig, 'toolHandlers'> {
   const {
@@ -126,12 +127,14 @@ function stripHandlers(agent: AgentConfig): Omit<AgentConfig, 'toolHandlers'> {
     subAgents,
     systemPrompt,
     toolDefinitions,
+    displayName,
     ...rest
   } = agent;
   const stripped = {
     ...rest,
     systemPrompt: typeof systemPrompt === 'function' ? undefined : systemPrompt,
     toolDefinitions: typeof toolDefinitions === 'function' ? undefined : toolDefinitions,
+    displayName: typeof displayName === 'function' ? undefined : displayName,
   };
   return subAgents?.length
     ? { ...stripped, subAgents: subAgents.map(stripHandlers) as AgentConfig[] }
@@ -544,9 +547,16 @@ export class FoundationAiAssistant extends GenesisElement {
     if (!agents?.length) return '';
     return agents
       .map((a) => {
-        const toolNames = Object.keys(a.toolHandlers ?? {})
-          .sort()
-          .join('+');
+        // Function-form handlers are resolved per turn — their full key set
+        // isn't knowable at fingerprint time. A constant marker still
+        // distinguishes static-vs-dynamic shape changes; finer-grained
+        // detection isn't load-bearing here.
+        const toolNames =
+          typeof a.toolHandlers === 'function'
+            ? '<fn>'
+            : Object.keys(a.toolHandlers ?? {})
+                .sort()
+                .join('+');
         return `${a.name}[${toolNames}]`;
       })
       .join(',');
@@ -1170,7 +1180,11 @@ export class FoundationAiAssistant extends GenesisElement {
         agentSummary: this.agents?.map((a) => ({
           ...a,
           toolDefinitions: Array.isArray(a.toolDefinitions)
-            ? expandToolTree(a.toolDefinitions, a.toolHandlers ?? {})
+            ? typeof a.toolHandlers === 'function'
+              ? // Static defs + dynamic handlers — can't walk fold tree
+                // because the handler map isn't materialized at log time.
+                a.toolDefinitions
+              : expandToolTree(a.toolDefinitions, a.toolHandlers ?? {})
             : typeof a.toolDefinitions === 'function'
               ? '<dynamic — resolved per turn>'
               : [],