@genesislcap/ai-assistant 14.434.0 → 14.436.0

package/src/main/main.ts

@@ -109,12 +109,33 @@ avoidTreeShaking(
   AgentPicker,
 );
 
-/** Recursively strips `toolHandlers` from an agent and all its sub-agents. */
+/**
+ * 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).
+ */
 function stripHandlers(agent: AgentConfig): Omit<AgentConfig, 'toolHandlers'> {
-  const { toolHandlers: _, subAgents, ...rest } = agent;
+  const {
+    toolHandlers: _h,
+    onActivate: _on,
+    onDeactivate: _off,
+    getDebugSnapshot: _g,
+    subAgents,
+    systemPrompt,
+    toolDefinitions,
+    ...rest
+  } = agent;
+  const stripped = {
+    ...rest,
+    systemPrompt: typeof systemPrompt === 'function' ? undefined : systemPrompt,
+    toolDefinitions: typeof toolDefinitions === 'function' ? undefined : toolDefinitions,
+  };
   return subAgents?.length
-    ? { ...rest, subAgents: subAgents.map(stripHandlers) as AgentConfig[] }
-    : rest;
+    ? { ...stripped, subAgents: subAgents.map(stripHandlers) as AgentConfig[] }
+    : stripped;
 }
 
 /**
@@ -504,8 +525,15 @@ export class FoundationAiAssistant extends GenesisElement {
     // down a mid-flight driver and creating a fresh idle one.
     if (this.driver.isBusy()) return;
     const history = this.driver.getRawHistory?.() ?? [];
+    const oldDriver = this.driver;
     this.unwireDriver();
     deleteDriver(key);
+    // Fire the active agent's `onDeactivate` so machines / per-agent state get
+    // torn down before the replacement driver instantiates them again. Fire
+    // and forget — the old driver is about to be GC'd, errors are non-fatal.
+    if (oldDriver && 'dispose' in oldDriver && typeof oldDriver.dispose === 'function') {
+      void oldDriver.dispose();
+    }
     this.driver = getOrCreateDriver(key, () => this.createDriver());
     this.wireDriver();
     if (history.length) this.driver.loadHistory([...history]);
@@ -529,30 +557,72 @@ export class FoundationAiAssistant extends GenesisElement {
    * current agent configuration. Does not wire event listeners or register in
    * the driver registry.
    */
+  /**
+   * Warn at config time if any stateful agent (one with lifecycle hooks) is
+   * configured in a way that makes it unreachable: `excludeFromClassifier`
+   * removes the classifier path, so the only entry left is manual pinning —
+   * which requires both `manualSelection.enabled` on the agent and the picker
+   * itself being enabled at the assistant level.
+   */
+  private warnUnreachableStatefulAgents(): void {
+    const pickerDisabled = this.agentPicker === 'disabled';
+    for (const a of this.agents ?? []) {
+      const isStateful = !!(a.onActivate || a.onDeactivate);
+      if (!isStateful) continue;
+      // Specialists only — defineStatefulAgent rejects fallback.
+      const excluded = 'excludeFromClassifier' in a && a.excludeFromClassifier === true;
+      if (!excluded) continue;
+      const manual = a.manualSelection?.enabled === true;
+      if (manual && !pickerDisabled) continue;
+      const reason = pickerDisabled
+        ? 'the picker is disabled at chatConfig.picker.mode'
+        : 'manualSelection.enabled is not set on the agent';
+      logger.warn(
+        `Stateful agent "${a.name}" is unreachable: excludeFromClassifier is true and ${reason}. ` +
+          'Either remove excludeFromClassifier, enable manualSelection on the agent, or enable the picker.',
+      );
+    }
+  }
+
   private createDriver(): AiDriver {
+    this.warnUnreachableStatefulAgents();
     const agent = this.chatConfig.agent ?? {};
     const { agents } = this;
 
-    if (agents && agents.length > 1) {
+    // Always route through OrchestratingDriver when agents are configured —
+    // even with a single agent — so lifecycle hooks (`onActivate`/
+    // `onDeactivate`), auto-pin, and release semantics fire uniformly. The
+    // classifier short-circuits when there's only one viable candidate, so
+    // single-agent setups pay no LLM cost for routing. With no agents
+    // configured at all, fall back to a bare ChatDriver — there's nothing to
+    // orchestrate and no hooks to fire.
+    if (agents && agents.length > 0) {
+      if (agents.length === 1 && !agents[0].fallback) {
+        // Preset for getters that read activeAgent before the first turn
+        // (e.g. chatInputDuringExecution). The orchestrator will overwrite
+        // this via `agent-changed` once applyAgent fires on first sendMessage.
+        this.activeAgent = agents[0];
+      }
       return new OrchestratingDriver(this.aiProvider, agents, {
+        sessionKey: this.getStateKey() ?? '',
         maxHandoffs: agent.maxHandoffs,
         classifierHistoryLength: agent.classifierHistoryLength,
         classifierRetries: agent.classifierRetries,
         maxToolIterations: agent.maxToolIterations,
         maxFoldOperations: agent.maxFoldOperations,
+        maxTurnSnapshots: agent.maxTurnSnapshots,
       });
     }
 
-    const singleAgent = agents?.[0];
-    this.activeAgent = singleAgent;
     return new ChatDriver(
       this.aiProvider,
-      singleAgent?.toolHandlers ?? {},
-      singleAgent?.toolDefinitions ?? [],
-      singleAgent?.systemPrompt,
-      singleAgent?.primerHistory,
+      {},
+      [],
+      undefined,
+      undefined,
       agent.maxToolIterations,
       agent.maxFoldOperations,
+      agent.maxTurnSnapshots,
     );
   }
 
@@ -623,13 +693,25 @@ export class FoundationAiAssistant extends GenesisElement {
       const onAgentChanged = (e: Event) => {
         this.activeAgent = (e as CustomEvent<AgentConfig>).detail;
       };
+      // Orchestrator-initiated pin changes (auto-pin on stateful activation,
+      // auto-clear on release). User-initiated pins flow the other direction
+      // via the `pinnedAgentName` setter, which already calls setPinnedAgent
+      // back into the driver — guard against the redundant round-trip.
+      const onPinnedChanged = (e: Event) => {
+        const name = (e as CustomEvent<string | null>).detail;
+        if (this._sessionRef?.store.aiAssistant.pinnedAgentName !== name) {
+          this._sessionRef?.actions.aiAssistant.setPinnedAgentName(name);
+        }
+      };
       driver.addEventListener('orchestrating-start', onOrchStart);
       driver.addEventListener('orchestrating-stop', onOrchStop);
       driver.addEventListener('agent-changed', onAgentChanged);
+      driver.addEventListener('pinned-changed', onPinnedChanged);
       cleanups.push(
         () => driver.removeEventListener('orchestrating-start', onOrchStart),
         () => driver.removeEventListener('orchestrating-stop', onOrchStop),
         () => driver.removeEventListener('agent-changed', onAgentChanged),
+        () => driver.removeEventListener('pinned-changed', onPinnedChanged),
       );
     }
 
@@ -964,6 +1046,44 @@ export class FoundationAiAssistant extends GenesisElement {
     return this.agents?.find((a) => a.name === this.pinnedAgentName)?.manualSelection?.hint;
   }
 
+  /**
+   * The pin is locked when a stateful agent (one with lifecycle hooks) is
+   * *actively running* — i.e. its `onActivate` has fired and it owns live
+   * state. Until the user sends their first message, a freshly pinned stateful
+   * agent is not yet active and the picker should remain free; the user might
+   * change their mind and unpin without anything to clean up.
+   *
+   * We derive from `activeAgent` (set by the orchestrator after `onActivate`
+   * completes) rather than `pinnedAgentName` (set immediately on picker
+   * click). The serialized `activeAgent` strips lifecycle hooks, so we look
+   * up the live config from `this.agents` to check for them.
+   */
+  @volatile
+  get pinLocked(): boolean {
+    if (!this.activeAgent) return false;
+    const live = this.agents?.find((a) => a.name === this.activeAgent!.name);
+    if (!live) return false;
+    return !!(live.onActivate || live.onDeactivate);
+  }
+
+  /** Tooltip shown on the picker toggle button. */
+  @volatile
+  get agentToggleTitle(): string {
+    if (this.pinLocked) {
+      const name = this.pinnedAgentName ?? 'This agent';
+      return `${name} is in the middle of a guided flow. Agent switching is disabled until the flow completes.`;
+    }
+    if (this.agentPickerOpen) {
+      return 'Close agent picker';
+    }
+    if (this.pinnedAgentName !== null) {
+      return this.pinnedAgentHint
+        ? `${this.pinnedAgentName} — ${this.pinnedAgentHint}`
+        : this.pinnedAgentName;
+    }
+    return 'Attempts to route messages to the correct available agent. Click to manually pin an agent.';
+  }
+
   /**
    * Tint applied to the pin icon when an agent is pinned. Picked from the
    * brand palette by agent position (modulo the palette length), so each agent
@@ -1009,6 +1129,18 @@ export class FoundationAiAssistant extends GenesisElement {
 
   getDebugLog() {
     const timestamp = new Date().toISOString().replace(/:/g, '-');
+    // Live agent reference — `this.activeAgent` is the redux-stripped projection,
+    // so getDebugSnapshot is not on it. Look up the live config from the agents
+    // array to get the function back.
+    const liveActiveAgent = this.activeAgent
+      ? this.agents?.find((a) => a.name === this.activeAgent!.name)
+      : undefined;
+    let activeDebugSnapshot: unknown;
+    try {
+      activeDebugSnapshot = liveActiveAgent?.getDebugSnapshot?.();
+    } catch (e) {
+      activeDebugSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
+    }
     return {
       messages: this.driver?.getRawHistory?.() ?? this.messages,
       meta: {
@@ -1016,13 +1148,29 @@ export class FoundationAiAssistant extends GenesisElement {
         host: window.location.host,
         agentSummary: this.agents?.map((a) => ({
           ...a,
-          toolDefinitions: expandToolTree(a.toolDefinitions ?? [], a.toolHandlers ?? {}),
+          toolDefinitions: Array.isArray(a.toolDefinitions)
+            ? expandToolTree(a.toolDefinitions, a.toolHandlers ?? {})
+            : typeof a.toolDefinitions === 'function'
+              ? '<dynamic — resolved per turn>'
+              : [],
           toolHandlers: undefined,
+          onActivate: undefined,
+          onDeactivate: undefined,
+          getDebugSnapshot: undefined,
         })),
-        activeSystemPrompt: this.activeAgent?.systemPrompt,
+        activeSystemPrompt:
+          typeof this.activeAgent?.systemPrompt === 'function'
+            ? '<dynamic — resolved per turn>'
+            : this.activeAgent?.systemPrompt,
         activePrimerHistory: this.activeAgent?.primerHistory,
         activeFoldStack:
           this.driver instanceof ChatDriver ? this.driver.getActiveFoldNames() : undefined,
+        // Snapshot captured fresh at log-export time — reflects state NOW, which
+        // may have transitioned since the last LLM call.
+        activeDebugSnapshot,
+        // Per-LLM-call timeline — pairs each turn with the prompt + tool surface
+        // + agent state that drove it. Capped to the most recent N entries.
+        turnSnapshots: this.driver?.getTurnSnapshots?.() ?? [],
         debug: this.debugStateFactory?.(),
       },
     };
@@ -1167,7 +1315,12 @@ export class FoundationAiAssistant extends GenesisElement {
           {
             name: this.activeAgent.name,
             description: 'description' in this.activeAgent ? this.activeAgent.description : '',
-            tools: this.activeAgent.toolDefinitions ?? [],
+            // Dynamic-tools agents have no resolvable tool list outside a
+            // per-turn context — suggestions just get an empty hint, matching
+            // what `OrchestratingDriver.getSuggestions` does for them.
+            tools: Array.isArray(this.activeAgent.toolDefinitions)
+              ? this.activeAgent.toolDefinitions
+              : [],
           },
         ]
       : undefined;