@genesislcap/ai-assistant 14.434.0 → 14.436.0

package/src/config/config.ts

@@ -7,6 +7,60 @@ import type {
 
 export type { ChatInputDuringExecutionMode };
 
+/**
+ * Context passed to `onActivate` / `onDeactivate` lifecycle hooks on an agent.
+ *
+ * @beta
+ */
+export interface AgentLifecycleContext {
+  /** The agent the hook is firing for. */
+  agentName: string;
+  /** The assistant session key — stable across reloads, unique per assistant instance. */
+  sessionKey: string;
+  /** The agent that was active immediately before this one, if any. Only set on `onActivate`. */
+  previousAgentName?: string;
+  /** Aborted if the session disconnects mid-activation. */
+  signal: AbortSignal;
+}
+
+/**
+ * Context passed to the function form of `systemPrompt` / `toolDefinitions`.
+ * Resolved each tool-loop iteration so the agent can vary what the LLM sees per turn.
+ *
+ * @beta
+ */
+export interface SystemPromptContext {
+  /** The active agent's name. */
+  agentName: string;
+  /** Full conversation history up to (but not including) the message being processed. */
+  history: ReadonlyArray<ChatMessage>;
+  /** 0 = first LLM call this turn; > 0 = retry or subsequent tool-loop iteration. */
+  turnIndex: number;
+  /** Aborted if the turn is cancelled. */
+  signal: AbortSignal;
+}
+
+/**
+ * System prompt for an agent. Either a static string (resolved once) or a function
+ * resolved each tool-loop iteration. The function form lets the agent compute the
+ * prompt from external state — e.g. a state machine's current step.
+ *
+ * @beta
+ */
+export type SystemPromptInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
+
+/**
+ * Tool definitions for an agent. Either a static array (the conventional shape) or
+ * a function resolved each tool-loop iteration. The function form lets the agent
+ * narrow the tool surface per turn — e.g. expose only the tools valid in the
+ * current state of a state machine.
+ *
+ * @beta
+ */
+export type ToolDefinitionsInput =
+  | ChatToolDefinition[]
+  | ((ctx: SystemPromptContext) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>);
+
 /**
  * Opts an agent in to manual selection from the assistant's agent picker.
  *
@@ -34,12 +88,21 @@ interface BaseAgentConfig {
   name: string;
   /**
    * System prompt injected into every conversation turn for this agent.
+   *
+   * Either a string (resolved once) or a function resolved each tool-loop
+   * iteration — pick the function form when the prompt depends on per-turn state
+   * (e.g. a state machine's current step). See {@link SystemPromptInput}.
    */
-  systemPrompt?: string;
+  systemPrompt?: SystemPromptInput;
   /**
    * Tool definitions (JSON Schema) passed to the AI provider for this agent.
+   *
+   * Either a static array or a function resolved each tool-loop iteration —
+   * pick the function form to narrow the tool surface per turn (e.g. expose
+   * only the tools valid in the current state of a state machine).
+   * See {@link ToolDefinitionsInput}.
    */
-  toolDefinitions?: ChatToolDefinition[];
+  toolDefinitions?: ToolDefinitionsInput;
   /**
    * Tool handler implementations for this agent.
    */
@@ -64,6 +127,40 @@ interface BaseAgentConfig {
    * disabled. See {@link ManualSelectionConfig}.
    */
   manualSelection?: ManualSelectionConfig;
+  /**
+   * Fires when this agent becomes the active specialist (including being pinned).
+   * Use to instantiate per-agent state that should outlive a single turn — e.g.
+   * a state machine the agent owns across the conversation. Awaited before the
+   * agent's first turn runs.
+   *
+   * Capture dependencies (services, redux store refs, etc.) via closure on the
+   * host element rather than expecting them on the context.
+   *
+   * @beta
+   */
+  onActivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
+  /**
+   * Fires when this agent is being deactivated (the user switches to another
+   * agent, the session is torn down, or the agent is unpinned and replaced).
+   * Use to dispose per-agent state created in `onActivate`. Awaited before the
+   * incoming agent's `onActivate` runs.
+   *
+   * @beta
+   */
+  onDeactivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
+  /**
+   * Returns an agent-supplied debug payload for the export log. Called once per
+   * LLM call by the driver (alongside the resolved prompt and tool list) and
+   * once at log-export time for the latest snapshot. Stateful agents should
+   * return their machine state and captured context so the exported timeline
+   * captures what drove each turn.
+   *
+   * Return value must be JSON-serializable. {@link defineStatefulAgent} wires a
+   * sensible default that snapshots any machine-shaped state automatically.
+   *
+   * @beta
+   */
+  getDebugSnapshot?: () => unknown;
 }
 
 /**
@@ -82,6 +179,19 @@ export interface SpecialistAgentConfig extends BaseAgentConfig {
    */
   description: string;
   fallback?: never;
+  /**
+   * When `true`, the classifier never auto-routes to this agent. The user can
+   * still select it manually via the picker, provided both prerequisites are
+   * met: this agent has `manualSelection.enabled` set to `true`, *and* the
+   * assistant has the picker enabled via `chatConfig.picker.mode`.
+   *
+   * Use this for agents that overlap heavily with a sibling (e.g. a guided
+   * wizard sitting next to a free-form agent in the same domain) and should
+   * only be reached intentionally rather than via classifier routing.
+   *
+   * @beta
+   */
+  excludeFromClassifier?: boolean;
 }
 
 /**

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

@@ -0,0 +1,293 @@
+import type { ChatMessage, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
+import { TOOL_FOLD_SYMBOL } from '../utils/tool-fold';
+import type {
+  AgentConfig,
+  AgentLifecycleContext,
+  ChatInputDuringExecutionMode,
+  ManualSelectionConfig,
+  SystemPromptContext,
+  ToolDefinitionsInput,
+} from './config';
+
+/**
+ * Init options for {@link defineStatefulAgent}. Generic over the state shape `S`
+ * the agent owns (a state machine, an observable controller, anything).
+ *
+ * The helper threads `state` through `systemPrompt`, `toolDefinitions`, and the
+ * `toolHandlers` factory so consumer code never has to reach for a closure or
+ * a module-level mutable.
+ *
+ * @beta
+ */
+export interface StatefulAgentInit<S> {
+  /** Display name — must be unique within the agents array. */
+  name: string;
+  /** Plain-language description used by the classifier. Required: stateful agents are always specialists. */
+  description: string;
+  /**
+   * Hide this agent from the classifier — only reachable via manual pinning.
+   * Stateful agents are always specialists; they cannot be the fallback (a
+   * fallback is a leaf invoked when no specialist matches, with no flow to
+   * own state for).
+   */
+  excludeFromClassifier?: boolean;
+  /** Static primer history prepended to every call (not visible to the user). */
+  primerHistory?: ChatMessage[];
+  /** Sub-agents available to this agent's tool handlers via `requestSubAgent`. */
+  subAgents?: AgentConfig[];
+  /** Opt this agent in to manual picker selection. */
+  manualSelection?: ManualSelectionConfig;
+  /** How the main chat input behaves while this agent is executing. */
+  chatInputDuringExecution?: ChatInputDuringExecutionMode;
+
+  /**
+   * Construct the agent-scoped state. Called by the framework when this agent
+   * becomes active (`onActivate`). Awaited before the agent's first turn runs.
+   */
+  init: (ctx: AgentLifecycleContext) => S | Promise<S>;
+
+  /**
+   * Tear down the agent-scoped state. Called when the agent is being replaced.
+   * Awaited before the incoming agent's `init` runs.
+   */
+  dispose?: (ctx: AgentLifecycleContext & { state: S }) => void | Promise<void>;
+
+  /**
+   * System prompt composed from current state. Resolved each tool-loop
+   * 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>;
+
+  /**
+   * 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
+   * machine-driven agent narrows the surface per state.
+   *
+   * **Constraint:** the resolved handlers (returned from {@link StatefulAgentInit.toolHandlers})
+   * must not include fold facades. Folds are an LLM-driven UX optimisation
+   * that competes with the machine for control of the tool view; one of them
+   * 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[]>);
+
+  /**
+   * 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.
+   *
+   * 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.
+   */
+  toolHandlers?: (state: S) => ChatToolHandlers;
+
+  /**
+   * Optional getter for the debug-log snapshot. Defaults to auto-snapshotting
+   * any property on `state` that looks like a foundation-state-machine
+   * instance (has `state`, `context`, and `complete` fields). Override when
+   * the default doesn't capture what you need — e.g. multiple machines, or
+   * non-machine state worth recording.
+   *
+   * Return value must be JSON-serializable.
+   */
+  getDebugSnapshot?: (state: S) => unknown;
+}
+
+/**
+ * Walk a state object and snapshot any machine-shaped values found on it.
+ * Recognises foundation-state-machine instances by structural shape rather
+ * than `instanceof`, so the helper stays free of a runtime dep on
+ * foundation-state-machine.
+ *
+ * Strips the `errors`/`error` framework noise from each machine's context —
+ * these are foundation-state-machine internals (an ErrorMap instance and its
+ * last-error pointer) that bloat the debug payload without aiding debugging.
+ */
+function defaultStatefulDebugSnapshot(state: unknown): unknown {
+  if (!state || typeof state !== 'object') return state;
+  const result: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(state as Record<string, unknown>)) {
+    if (val && typeof val === 'object' && 'state' in val && 'context' in val && 'complete' in val) {
+      const m = val as {
+        state: unknown;
+        context: Record<string, unknown>;
+        complete: unknown;
+        output?: unknown;
+      };
+      const ctx = m.context ?? {};
+      const { errors: _e, error: _err, ...userContext } = ctx;
+      result[key] = {
+        state: m.state,
+        context: userContext,
+        complete: m.complete,
+        output: m.output,
+      };
+    }
+  }
+  return Object.keys(result).length
+    ? result
+    : '<no auto-snapshot — state has no machine-shaped properties; provide getDebugSnapshot>';
+}
+
+/**
+ * Build an `AgentConfig` whose `systemPrompt`, `toolDefinitions`, and tool
+ * handlers all close over a long-lived state object created on activation.
+ *
+ * The framework wires the lifecycle: `init` on `onActivate`, `dispose` on
+ * `onDeactivate`. State is held inside the helper's closure — never exposed on
+ * the resulting `AgentConfig` — so the redux serializer doesn't see it.
+ *
+ * @example
+ * ```ts
+ * const guidedBooking = defineStatefulAgent<{ machine: GuidedBookingMachine }>({
+ *   name: 'Guided Booking',
+ *   description: 'Books a trade via a guided wizard.',
+ *   excludeFromClassifier: true,
+ *   manualSelection: { enabled: true, hint: 'Step-by-step trade booking' },
+ *   init: () => ({ machine: new GuidedBookingMachine() }),
+ *   dispose: ({ state }) => state.machine.stop(),
+ *   systemPrompt: ({ state }) => composeFromMachine(state.machine),
+ *   toolDefinitions: ({ state }) => toolsForState(state.machine.state),
+ *   toolHandlers: ({ machine }) => ({ ... }),
+ * });
+ * ```
+ *
+ * @beta
+ */
+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)) {
+      if ((handler as any)[TOOL_FOLD_SYMBOL]) {
+        throw new Error(
+          `Stateful agent "${opts.name}" tool "${name}" carries fold metadata. ` +
+            `Folds and state-machine-driven tool filtering both try to control the ` +
+            `LLM's tool view — pick one. Remove the fold or migrate this agent to ` +
+            `a non-stateful AgentConfig.`,
+        );
+      }
+    }
+  };
+
+  // Wrap the optional dynamic-tools factory so it threads `state` in and asserts
+  // we never accidentally resolved a fold-tagged tool. Static arrays are passed
+  // through unchanged.
+  const wrappedTools: ToolDefinitionsInput | undefined = (() => {
+    const td = opts.toolDefinitions;
+    if (typeof td === 'function') {
+      return async (ctx: SystemPromptContext) => {
+        if (!state) {
+          throw new Error(`Stateful agent "${opts.name}" tools called before init`);
+        }
+        return td({ ...ctx, state });
+      };
+    }
+    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}"`);
+        }
+        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;
+
+  // 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 base = {
+    name: opts.name,
+    primerHistory: opts.primerHistory,
+    subAgents: opts.subAgents,
+    manualSelection: opts.manualSelection,
+    chatInputDuringExecution: opts.chatInputDuringExecution,
+    toolDefinitions: wrappedTools,
+    toolHandlers: opts.toolHandlers ? resolvedHandlers : undefined,
+
+    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);
+      }
+    },
+
+    onDeactivate: async (ctx: AgentLifecycleContext) => {
+      if (state !== undefined && opts.dispose) {
+        await opts.dispose({ ...ctx, state });
+      }
+      // Orchestrator serializes onActivate/onDeactivate; concurrent calls
+      // cannot interleave the read-then-write of `state`.
+      // eslint-disable-next-line require-atomic-updates
+      state = undefined;
+      cachedHandlers = undefined;
+    },
+
+    systemPrompt: opts.systemPrompt
+      ? async (ctx: SystemPromptContext) => {
+          if (!state) {
+            throw new Error(`Stateful agent "${opts.name}" systemPrompt called before init`);
+          }
+          return opts.systemPrompt!({ ...ctx, state });
+        }
+      : undefined,
+
+    // Called per LLM call by ChatDriver, and once at debug-log export time.
+    // Returns `undefined` before activation (state hasn't been built yet) and
+    // after deactivation (state was disposed) — the snapshotter is best-effort
+    // and the driver tolerates undefined.
+    getDebugSnapshot: () => {
+      if (!state) return undefined;
+      return opts.getDebugSnapshot
+        ? opts.getDebugSnapshot(state)
+        : defaultStatefulDebugSnapshot(state);
+    },
+  };
+
+  return {
+    ...base,
+    description: opts.description,
+    excludeFromClassifier: opts.excludeFromClassifier,
+  } as AgentConfig;
+}

package/src/index.ts

@@ -9,6 +9,7 @@ export * from './components/popout-manager';
 export * from './channel/ai-activity-channel';
 export * from './channel/ai-activity-bus';
 export * from './config/config';
+export * from './config/define-stateful-agent';
 export * from './config/fallback-agents';
 export * from './utils/tool-fold';
 export type { AiChatWidget } from './types/ai-chat-widget';

package/src/main/main.template.ts

@@ -275,15 +275,8 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
       class="agent-toggle-button"
       part="agent-toggle-button"
       appearance="stealth"
-      title=${(x) =>
-        x.agentPickerOpen
-          ? 'Close agent picker'
-          : x.pinnedAgentName !== null
-            ? x.pinnedAgentHint
-              ? `${x.pinnedAgentName} — ${x.pinnedAgentHint}`
-              : (x.pinnedAgentName ?? '')
-            : 'Attempts to route messages to the correct available agent. Click to manually pin an agent.'}
-      ?disabled=${(x) => x.state === 'loading'}
+      title=${(x) => x.agentToggleTitle}
+      ?disabled=${(x) => x.state === 'loading' || x.pinLocked}
       @click=${(x) => x.toggleAgentPicker()}
     >
       ${when(