@genesislcap/ai-assistant 14.466.0 → 14.467.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.466.0",
+  "version": "14.467.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -64,24 +64,24 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.466.0",
-    "@genesislcap/genx": "14.466.0",
-    "@genesislcap/rollup-builder": "14.466.0",
-    "@genesislcap/ts-builder": "14.466.0",
-    "@genesislcap/uvu-playwright-builder": "14.466.0",
-    "@genesislcap/vite-builder": "14.466.0",
-    "@genesislcap/webpack-builder": "14.466.0",
+    "@genesislcap/foundation-testing": "14.467.0",
+    "@genesislcap/genx": "14.467.0",
+    "@genesislcap/rollup-builder": "14.467.0",
+    "@genesislcap/ts-builder": "14.467.0",
+    "@genesislcap/uvu-playwright-builder": "14.467.0",
+    "@genesislcap/vite-builder": "14.467.0",
+    "@genesislcap/webpack-builder": "14.467.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.466.0",
-    "@genesislcap/foundation-logger": "14.466.0",
-    "@genesislcap/foundation-redux": "14.466.0",
-    "@genesislcap/foundation-ui": "14.466.0",
-    "@genesislcap/foundation-utils": "14.466.0",
-    "@genesislcap/rapid-design-system": "14.466.0",
-    "@genesislcap/web-core": "14.466.0",
+    "@genesislcap/foundation-ai": "14.467.0",
+    "@genesislcap/foundation-logger": "14.467.0",
+    "@genesislcap/foundation-redux": "14.467.0",
+    "@genesislcap/foundation-ui": "14.467.0",
+    "@genesislcap/foundation-utils": "14.467.0",
+    "@genesislcap/rapid-design-system": "14.467.0",
+    "@genesislcap/web-core": "14.467.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -93,5 +93,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "a0ced1e97a07712305acd5675461d5f9273c8e51"
+  "gitHead": "18901315499f3c83de01431b879ec4cfa2676507"
 }

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

@@ -326,6 +326,134 @@ stale('splits stale vs hallucinated tools on the unknown-tool-limit error', asyn
 
 stale.run();
 
+// ---------------------------------------------------------------------------
+// onUnresolvedTool hook — an agent can redirect an unresolved tool call
+// ---------------------------------------------------------------------------
+
+const hook = createLogicSuite('ChatDriver onUnresolvedTool hook');
+
+hook.after(() => {
+  agenticActivityBus.close();
+});
+
+hook('replaces the default for a hallucinated tool when the hook returns a string', async () => {
+  const config = agent({
+    name: 'Hooked',
+    toolDefinitions: [def('real_tool')],
+    toolHandlers: { real_tool: async () => 'ok' },
+    onUnresolvedTool: ({ toolName, kind, availableTools }) =>
+      `redirect: ${toolName} is ${kind}; use ${availableTools.join(', ')}`,
+  });
+  const provider = scriptedProvider([callsTool('made_up', 'm1')]);
+  const driver = makeDriver(config, provider);
+
+  await driver.sendMessage('go');
+
+  assert.ok(
+    toolResultContents(driver).includes('redirect: made_up is unknown; use real_tool'),
+    'the hook string should replace the default Unknown tool message',
+  );
+  assert.not.ok(
+    toolResultContents(driver).some((c) => c.startsWith('Unknown tool:')),
+    'the default unknown-tool message must not appear',
+  );
+});
+
+hook('replaces the default for a stale tool when the hook returns a string', async () => {
+  let state: 'A' | 'B' = 'A';
+  const config = agent({
+    name: 'HookedStateful',
+    toolDefinitions: () => (state === 'A' ? [def('tool_a')] : [def('tool_b')]),
+    toolHandlers: () =>
+      state === 'A'
+        ? {
+            tool_a: async () => {
+              state = 'B';
+              return 'advanced to B';
+            },
+          }
+        : { tool_b: async () => 'b done' },
+    onUnresolvedTool: ({ toolName, kind }) => `redirect: ${toolName}/${kind}`,
+  });
+  const provider = scriptedProvider([
+    callsTool('tool_a', 't1'), // real — advances A -> B
+    callsTool('tool_a', 't2'), // stale — tool_a no longer in state B
+    callsTool('tool_b', 't3'), // real — valid in state B
+  ]);
+  const driver = makeDriver(config, provider);
+
+  await driver.sendMessage('go');
+
+  assert.ok(
+    toolResultContents(driver).includes('redirect: tool_a/stale'),
+    'the hook string should replace the default stale message',
+  );
+  assert.not.ok(
+    toolResultContents(driver).some((c) =>
+      c.includes('was available earlier but is not part of the current step'),
+    ),
+    'the default stale message must not appear',
+  );
+});
+
+hook('falls back to the default when the hook returns undefined', async () => {
+  const config = agent({
+    name: 'HookUndefined',
+    toolDefinitions: [def('real_tool')],
+    toolHandlers: { real_tool: async () => 'ok' },
+    onUnresolvedTool: () => undefined,
+  });
+  const provider = scriptedProvider([callsTool('made_up', 'm1')]);
+  const driver = makeDriver(config, provider);
+
+  await driver.sendMessage('go');
+
+  assert.ok(
+    toolResultContents(driver).includes('Unknown tool: made_up'),
+    'an undefined hook result should fall back to the default message',
+  );
+});
+
+hook('falls back to the default when the hook returns a whitespace-only string', async () => {
+  const config = agent({
+    name: 'HookEmpty',
+    toolDefinitions: [def('real_tool')],
+    toolHandlers: { real_tool: async () => 'ok' },
+    onUnresolvedTool: () => '   ',
+  });
+  const provider = scriptedProvider([callsTool('made_up', 'm1')]);
+  const driver = makeDriver(config, provider);
+
+  await driver.sendMessage('go');
+
+  assert.ok(
+    toolResultContents(driver).includes('Unknown tool: made_up'),
+    'a whitespace-only hook result should fall back to the default message',
+  );
+});
+
+hook('falls back to the default when the hook throws', async () => {
+  const config = agent({
+    name: 'HookThrows',
+    toolDefinitions: [def('real_tool')],
+    toolHandlers: { real_tool: async () => 'ok' },
+    onUnresolvedTool: () => {
+      throw new Error('boom');
+    },
+  });
+  const provider = scriptedProvider([callsTool('made_up', 'm1')]);
+  const driver = makeDriver(config, provider);
+
+  await driver.sendMessage('go');
+
+  assert.ok(
+    toolResultContents(driver).includes('Unknown tool: made_up'),
+    'a throwing hook should fall back to the default message',
+  );
+});
+
+hook.run();
+
 // ---------------------------------------------------------------------------
 // timeout handling — a transport `TimeoutError` surfaces a distinct message
 // ---------------------------------------------------------------------------

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

@@ -28,6 +28,7 @@ import type {
   ToolChoiceInput,
   ToolDefinitionsInput,
   ToolHandlersInput,
+  UnresolvedToolInput,
 } from '../../config/config';
 import { resolveChatProvider } from '../../config/validate-providers';
 import { recordMetaEvent, recordTurnError, recordTurnRetry } from '../../state/debug-event-log';
@@ -332,6 +333,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * call; top-level turns are `'auto'`).
    */
   private activeToolChoiceInput?: ToolChoiceInput;
+  /**
+   * Active agent's unresolved-tool hook, captured from `applyAgent`. Consulted
+   * only when a tool call cannot be dispatched (a stale or hallucinated name);
+   * `undefined` keeps the framework's default messages. See
+   * `resolveUnresolvedToolContent`.
+   */
+  private activeOnUnresolvedTool?: UnresolvedToolInput;
   /**
    * Caches validated provider lookups per name within the current agent. Cleared
    * by `applyAgent` so each new agent's static/function-resolved names are
@@ -527,6 +535,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.activeProviderInput = config.provider;
     this.activeTemperatureInput = config.temperature;
     this.activeToolChoiceInput = config.toolChoice;
+    this.activeOnUnresolvedTool = config.onUnresolvedTool;
     this.resolvedProviderCache.clear();
     this.lastResolvedProviderName = undefined;
     // Static validation: resolve the name now so unknown-provider and missing-
@@ -544,6 +553,38 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.everSeenToolNames.clear();
   }
 
+  /**
+   * Resolve the tool-result content for an unresolved tool call. Consults the
+   * active agent's `onUnresolvedTool` hook (if any) with the attempted tool
+   * name, the failure `kind`, and the currently dispatchable tools, and returns
+   * the hook's non-empty string. Falls back to `fallback` when no hook is set,
+   * the hook returns nothing/empty, or the hook throws — so a misbehaving hook
+   * can never break tool dispatch.
+   */
+  private async resolveUnresolvedToolContent(
+    toolName: string,
+    kind: 'stale' | 'unknown',
+    fallback: string,
+  ): Promise<string> {
+    if (typeof this.activeOnUnresolvedTool !== 'function') {
+      return fallback;
+    }
+    try {
+      const custom = await this.activeOnUnresolvedTool({
+        toolName,
+        kind,
+        availableTools: Object.keys(this.toolHandlers),
+      });
+      return typeof custom === 'string' && custom.trim().length > 0 ? custom : fallback;
+    } catch (e) {
+      logger.warn(
+        `ChatDriver: onUnresolvedTool threw for "${toolName}" — using default message`,
+        e,
+      );
+      return fallback;
+    }
+  }
+
   /**
    * Returns the most recently resolved provider name. Falls back to the
    * registry's default when no per-turn resolution has happened yet.
@@ -2044,7 +2085,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
                   consecutive: this.consecutiveUnknownToolCalls,
                   max: MAX_STALE_TOOL_CALLS,
                 });
-                executedById.set(tc.id, { toolCallId: tc.id, content });
+                // Fold-hidden tools keep their fold-specific guidance; a plain
+                // stale tool is a step-ordering miss, so offer the agent's
+                // redirect when it supplies one.
+                const staleContent = hidingFold
+                  ? content
+                  : await this.resolveUnresolvedToolContent(tc.name, 'stale', content);
+                executedById.set(tc.id, { toolCallId: tc.id, content: staleContent });
                 unknownToolIds.add(tc.id);
                 staleToolIds.add(tc.id);
                 this.recentUnknownToolNames.add(tc.name);
@@ -2068,7 +2115,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 max: DEFAULT_MAX_UNKNOWN_TOOL_CALLS,
                 availableTools: Object.keys(this.toolHandlers),
               });
-              executedById.set(tc.id, { toolCallId: tc.id, content: `Unknown tool: ${tc.name}` });
+              const unknownContent = await this.resolveUnresolvedToolContent(
+                tc.name,
+                'unknown',
+                `Unknown tool: ${tc.name}`,
+              );
+              executedById.set(tc.id, { toolCallId: tc.id, content: unknownContent });
               unknownToolIds.add(tc.id);
               this.recentUnknownToolNames.add(tc.name);
               if (this.consecutiveUnknownToolCalls >= DEFAULT_MAX_UNKNOWN_TOOL_CALLS) {

package/src/config/config.ts

@@ -116,6 +116,46 @@ export type ToolChoiceInput =
   | ChatToolChoice
   | ((ctx: SystemPromptContext) => ChatToolChoice | Promise<ChatToolChoice>);
 
+/**
+ * Context passed to an agent's `onUnresolvedTool` hook when the model calls a
+ * tool the driver cannot dispatch.
+ *
+ * @beta
+ */
+export interface UnresolvedToolContext {
+  /** The tool name the model attempted to call. */
+  toolName: string;
+  /**
+   * Why the call could not be dispatched:
+   * - `'stale'` — the tool was advertised earlier this activation but is not
+   *   part of the current step (e.g. a stateful agent has moved on).
+   * - `'unknown'` — the tool was never advertised this activation (a
+   *   hallucinated name).
+   */
+  kind: 'stale' | 'unknown';
+  /**
+   * The tool names dispatchable right now, so the hook can steer the model
+   * back to a valid call.
+   */
+  availableTools: string[];
+}
+
+/**
+ * Optional per-agent hook consulted only on the already-failing unresolved-tool
+ * path — when the model calls a tool the driver cannot dispatch. Lets the agent
+ * replace the framework's default message with a context-aware redirect.
+ *
+ * Return a non-empty string to override the default tool-result message; return
+ * `undefined` (or an empty/whitespace string, or throw) to fall back to the
+ * framework default. The happy path is never affected. See
+ * {@link UnresolvedToolContext}.
+ *
+ * @beta
+ */
+export type UnresolvedToolInput = (
+  ctx: UnresolvedToolContext,
+) => string | undefined | Promise<string | undefined>;
+
 /**
  * Opts an agent in to manual selection from the assistant's agent picker.
  *
@@ -218,6 +258,18 @@ interface BaseAgentConfig {
    * @beta
    */
   toolChoice?: ToolChoiceInput;
+  /**
+   * Optional hook consulted when the model calls a tool the driver cannot
+   * dispatch — either a *stale* tool (advertised earlier this activation but
+   * not part of the current step) or an *unknown* one (never advertised this
+   * activation). Return a context-aware redirect string to replace the
+   * framework's default message, or `undefined` to keep it. Consulted only on
+   * the already-failing unresolved-tool path; the happy path is unaffected.
+   * See {@link UnresolvedToolInput}.
+   *
+   * @beta
+   */
+  onUnresolvedTool?: UnresolvedToolInput;
   /**
    * 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.test.ts

@@ -0,0 +1,64 @@
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import type { AgentLifecycleContext } from './config';
+import { defineStatefulAgent } from './define-stateful-agent';
+
+// A minimal lifecycle context — `onActivate`/`onDeactivate` only read what the
+// helper passes through, so the agent name, session key, and a live signal are
+// enough to drive init/dispose in a Node-runnable test.
+const lifecycleCtx = (): AgentLifecycleContext => ({
+  agentName: 'wizard',
+  sessionKey: 'test-session',
+  signal: new AbortController().signal,
+});
+
+const onUnresolvedTool = createLogicSuite('defineStatefulAgent onUnresolvedTool');
+
+onUnresolvedTool('threads the live state into the hook after init', async () => {
+  const config = defineStatefulAgent<{ step: string }>({
+    name: 'wizard',
+    description: 'guided wizard',
+    init: () => ({ step: 'intake' }),
+    onUnresolvedTool: ({ state, toolName, kind, availableTools }) =>
+      `step=${state.step} tool=${toolName} kind=${kind} avail=${availableTools.join(',')}`,
+  });
+
+  await config.onActivate!(lifecycleCtx());
+
+  const result = await config.onUnresolvedTool!({
+    toolName: 'generate_view',
+    kind: 'stale',
+    availableTools: ['ask_user', 'validate'],
+  });
+  assert.is(result, 'step=intake tool=generate_view kind=stale avail=ask_user,validate');
+});
+
+onUnresolvedTool('returns undefined before init rather than throwing', async () => {
+  const config = defineStatefulAgent<{ step: string }>({
+    name: 'wizard',
+    description: 'guided wizard',
+    init: () => ({ step: 'intake' }),
+    // Would throw if it were ever reached without state — proves the wrapper
+    // short-circuits before delegating.
+    onUnresolvedTool: ({ state }) => `step=${state.step}`,
+  });
+
+  // No `onActivate` call — state has not been built yet.
+  const result = await config.onUnresolvedTool!({
+    toolName: 'generate_view',
+    kind: 'unknown',
+    availableTools: [],
+  });
+  assert.is(result, undefined, 'a pre-init call must degrade to the framework default');
+});
+
+onUnresolvedTool('omits the hook from the config when not supplied', () => {
+  const config = defineStatefulAgent<{ step: string }>({
+    name: 'wizard',
+    description: 'guided wizard',
+    init: () => ({ step: 'intake' }),
+  });
+
+  assert.is(config.onUnresolvedTool, undefined);
+});
+
+onUnresolvedTool.run();

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

@@ -17,6 +17,8 @@ import type {
   ToolChoiceInput,
   ToolDefinitionsInput,
   ToolHandlersInput,
+  UnresolvedToolContext,
+  UnresolvedToolInput,
 } from './config';
 
 /**
@@ -153,6 +155,20 @@ export interface StatefulAgentInit<S> {
     | ChatToolChoice
     | ((ctx: StatefulAgentContext<S>) => ChatToolChoice | Promise<ChatToolChoice>);
 
+  /**
+   * Hook consulted when the model calls a tool that isn't dispatchable in the
+   * current state — a *stale* tool (valid in an earlier state of this agent) or
+   * an *unknown* one. Receives the current `state` alongside the attempted tool
+   * name and the currently dispatchable tools, so a machine-driven agent can
+   * return a step-aware redirect (e.g. "that belongs to a later step — finish
+   * this one first"). Return `undefined` to keep the framework default; a
+   * pre-init call also degrades to the default rather than throwing.
+   * See {@link UnresolvedToolContext}.
+   */
+  onUnresolvedTool?: (
+    ctx: UnresolvedToolContext & { state: S },
+  ) => string | undefined | Promise<string | undefined>;
+
   /**
    * Optional getter for the debug-log snapshot. Defaults to auto-snapshotting
    * any property on `state` that looks like a foundation-state-machine
@@ -328,6 +344,20 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
         }
       : opts.toolChoice;
 
+  // `onUnresolvedTool` threads `state` in like the resolvers above, but unlike
+  // them returns `undefined` before init rather than throwing: it fires on the
+  // tool-dispatch path, so a pre-init call must degrade to the framework
+  // default instead of breaking dispatch.
+  const wrappedOnUnresolvedTool: UnresolvedToolInput | undefined =
+    typeof opts.onUnresolvedTool === 'function'
+      ? async (ctx) => {
+          if (!state) {
+            return undefined;
+          }
+          return opts.onUnresolvedTool!({ ...ctx, state });
+        }
+      : opts.onUnresolvedTool;
+
   const base = {
     name: opts.name,
     displayName: wrappedDisplayName,
@@ -340,6 +370,7 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
     provider: wrappedProvider,
     temperature: wrappedTemperature,
     toolChoice: wrappedToolChoice,
+    onUnresolvedTool: wrappedOnUnresolvedTool,
 
     onActivate: async (ctx: AgentLifecycleContext) => {
       state = await opts.init(ctx);

package/src/main/main.ts

@@ -151,43 +151,33 @@ avoidTreeShaking(
 );
 
 /**
- * Recursively strips non-serializable fields from an agent before storing in Redux:
- *  - `toolHandlers` (functions),
- *  - `onActivate` / `onDeactivate` (lifecycle hooks, functions),
- *  - `getDebugSnapshot` (function),
- *  - function-form `systemPrompt` / `toolDefinitions` / `displayName` / `provider` /
- *    `temperature` / `toolChoice`
- *    (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).
- *    Static forms (string / number / plain-object `toolChoice`) pass through.
+ * Recursively strips non-serializable fields from an agent before storing in
+ * Redux. Drops **every function-valued property** — `toolHandlers`, the
+ * lifecycle/dispatch hooks (`onActivate`, `onDeactivate`, `getDebugSnapshot`,
+ * `onUnresolvedTool`), and the function form of the per-turn resolvers
+ * (`systemPrompt`, `toolDefinitions`, `displayName`, `provider`, `temperature`,
+ * `toolChoice`). Static forms (string / number / array / plain object) pass
+ * through unchanged; `subAgents` are stripped recursively.
+ *
+ * Filtering by *value* (any function) rather than by an explicit field list
+ * means a new function-valued field added to `AgentConfig` is handled
+ * automatically and can never leak a live function into serialized store
+ * state — no denylist to keep in sync. The live config on the driver stays the
+ * source of truth; the slice only holds this serializable projection, and
+ * functions are never read back from it.
  */
 function stripHandlers(agent: AgentConfig): Omit<AgentConfig, 'toolHandlers'> {
-  const {
-    toolHandlers: _h,
-    onActivate: _on,
-    onDeactivate: _off,
-    getDebugSnapshot: _g,
-    subAgents,
-    systemPrompt,
-    toolDefinitions,
-    displayName,
-    provider,
-    temperature,
-    toolChoice,
-    ...rest
-  } = agent;
-  const stripped = {
-    ...rest,
-    systemPrompt: typeof systemPrompt === 'function' ? undefined : systemPrompt,
-    toolDefinitions: typeof toolDefinitions === 'function' ? undefined : toolDefinitions,
-    displayName: typeof displayName === 'function' ? undefined : displayName,
-    provider: typeof provider === 'function' ? undefined : provider,
-    temperature: typeof temperature === 'function' ? undefined : temperature,
-    toolChoice: typeof toolChoice === 'function' ? undefined : toolChoice,
-  };
-  return subAgents?.length
-    ? { ...stripped, subAgents: subAgents.map(stripHandlers) as AgentConfig[] }
-    : stripped;
+  const serializable: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(agent)) {
+    // `subAgents` is handled separately (recursively, below); drop everything
+    // function-valued.
+    if (key === 'subAgents' || typeof value === 'function') continue;
+    serializable[key] = value;
+  }
+  if (agent.subAgents?.length) {
+    serializable.subAgents = agent.subAgents.map(stripHandlers);
+  }
+  return serializable as unknown as Omit<AgentConfig, 'toolHandlers'>;
 }
 
 /**
@@ -1619,8 +1609,12 @@ export class FoundationAiAssistant extends GenesisElement {
       meta: {
         timestamp,
         host: window.location.host,
+        // stripHandlers drops every function-valued field (handlers, lifecycle
+        // hooks, onUnresolvedTool, function-form resolvers) and recurses
+        // subAgents — no manual exclusion list to keep in sync. We only override
+        // toolDefinitions afterwards to expand the fold tree for the log.
         agentSummary: this.agents?.map((a) => ({
-          ...a,
+          ...stripHandlers(a),
           toolDefinitions: Array.isArray(a.toolDefinitions)
             ? typeof a.toolHandlers === 'function'
               ? // Static defs + dynamic handlers — can't walk fold tree
@@ -1630,10 +1624,6 @@ export class FoundationAiAssistant extends GenesisElement {
             : typeof a.toolDefinitions === 'function'
               ? '<dynamic — resolved per turn>'
               : [],
-          toolHandlers: undefined,
-          onActivate: undefined,
-          onDeactivate: undefined,
-          getDebugSnapshot: undefined,
         })),
         activeSystemPrompt:
           typeof this.activeAgent?.systemPrompt === 'function'