@genesislcap/ai-assistant 14.421.1 → 14.422.0

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

@@ -7,9 +7,11 @@ import type {
   ChatToolCall,
   ChatToolDefinition,
   ChatToolHandlers,
+  SubAgentRequestOptions,
 } from '@genesislcap/foundation-ai';
 import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
 import type { AgentConfig } from '../../config/config';
+import { applyHistoryCap } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { TOOL_FOLD_SYMBOL, type ToolFold } from '../../utils/tool-fold';
 import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
@@ -18,6 +20,7 @@ const DEFAULT_MAX_TOOL_ITERATIONS = 50;
 const DEFAULT_MAX_FOLD_OPERATIONS = 5;
 const DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
 const MAX_MALFORMED_RETRIES = 2;
+const MAX_EMPTY_RESPONSE_RETRIES = 3;
 const SUGGESTIONS_HISTORY_WINDOW = 8;
 
 /** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
@@ -77,6 +80,16 @@ export class ChatDriver extends EventTarget implements AiDriver {
   private consecutiveUnknownToolCalls = 0;
   private readonly maxFoldOperations: number;
 
+  /** Sub-agents declared on the active agent config, keyed by name. */
+  private subAgentsMap: Map<string, AgentConfig> = new Map();
+  /**
+   * Set by `completeSubAgent` inside a sub-agent tool handler. Checked at the
+   * same point in the loop as `REQUEST_CONTINUATION_TOOL` — after tool results
+   * are appended — so the exit path mirrors the system-call pattern.
+   * `undefined` means the loop has not been stopped early.
+   */
+  private subAgentCompletion: { result: unknown } | undefined;
+
   constructor(
     private readonly aiProvider: AIProvider,
     toolHandlers: ChatToolHandlers = {},
@@ -104,11 +117,20 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.toolHandlers = config.toolHandlers ?? {};
     this.primerHistory = config.primerHistory;
     this.activeAgentName = config.name;
+    this.subAgentsMap = new Map((config.subAgents ?? []).map((s) => [s.name, s]));
     // Reset fold state when agent changes — each specialist starts fresh
     this.foldStack = [];
     this.consecutiveFoldOps = 0;
   }
 
+  /**
+   * Returns the early-stop result set by `completeSubAgent`, if any.
+   * Called by a parent `ChatDriver` after running this instance as a sub-agent.
+   */
+  getSubAgentCompletion(): { result: unknown } | undefined {
+    return this.subAgentCompletion;
+  }
+
   /**
    * Optional transform applied to conversation history immediately before each LLM request.
    * Cleared when `undefined`. Does not alter stored history.
@@ -281,6 +303,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
     }
 
     this.busy = true;
+    this.subAgentCompletion = undefined;
     this.appendToHistory({ role: 'user', content: userInput, attachments });
 
     try {
@@ -294,6 +317,116 @@ export class ChatDriver extends EventTarget implements AiDriver {
     }
   }
 
+  /**
+   * Builds the context object passed to every tool handler call.
+   * Centralised here so fold shortcut dispatch and the main tool loop use the
+   * same context without duplication.
+   *
+   * @param traceCapture - Optional per-invocation slot. When provided, the trace
+   *   from any sub-agent call is written here rather than to shared instance state,
+   *   so parallel tool calls each capture their own trace independently.
+   */
+  private buildHandlerContext(traceCapture?: { trace?: ChatMessage[] }) {
+    return {
+      requestInteraction: <T>(componentName: string, data: any): Promise<T> =>
+        this.requestInteraction(componentName, data),
+      ...(this.subAgentsMap.size > 0 && {
+        requestSubAgent: <T = never>(
+          name: string,
+          options?: SubAgentRequestOptions,
+        ): Promise<T | string> =>
+          this.invokeSubAgent<T>(name, options).then(({ result, trace }) => {
+            if (traceCapture) traceCapture.trace = trace;
+            return result;
+          }),
+      }),
+      completeSubAgent: (result: unknown): void => {
+        if (this.subAgentCompletion) {
+          logger.warn(
+            `ChatDriver(${this.activeAgentName ?? 'unknown'}): completeSubAgent called more than once — ignoring`,
+          );
+          return;
+        }
+        this.subAgentCompletion = { result };
+      },
+    };
+  }
+
+  /**
+   * Creates a child `ChatDriver` for the named sub-agent, runs it to completion,
+   * and returns its structured result (or final text fallback) together with the
+   * full child conversation trace. Callers receive both values so each parallel
+   * invocation can capture its own trace without touching shared instance state.
+   */
+  private async invokeSubAgent<T = never>(
+    name: string,
+    options?: SubAgentRequestOptions,
+  ): Promise<{ result: T | string; trace: ChatMessage[] }> {
+    const subConfig = this.subAgentsMap.get(name);
+    if (!subConfig) {
+      const available = [...this.subAgentsMap.keys()].join(', ') || '(none)';
+      throw new Error(
+        `Sub-agent "${name}" not found on agent "${this.activeAgentName}". Available: ${available}`,
+      );
+    }
+
+    const { task, historyCap, context } = options ?? {};
+
+    // Exclude the current in-flight assistant message (the one with tool calls that
+    // triggered this invocation) — it has unresolved tool calls that would confuse
+    // the sub-agent into thinking it needs to handle tools it doesn't own.
+    const lastMsg = this.history[this.history.length - 1];
+    const baseHistory =
+      lastMsg?.role === 'assistant' && lastMsg.toolCalls?.length
+        ? this.history.slice(0, -1)
+        : this.history;
+
+    const snapshotHistory =
+      historyCap != null ? applyHistoryCap(baseHistory, historyCap) : [...baseHistory];
+
+    const contextMessages: ChatMessage[] = context
+      ? [{ role: 'user', content: `[Sub-agent context]: ${JSON.stringify(context)}` }]
+      : [];
+
+    const effectivePrimer: ChatMessage[] = [
+      ...snapshotHistory,
+      ...contextMessages,
+      ...(subConfig.primerHistory ?? []),
+    ];
+
+    const child = new ChatDriver(this.aiProvider);
+    child.applyAgent({ ...subConfig, primerHistory: effectivePrimer });
+
+    const forwardTrace = (e: Event) => {
+      this.dispatchEvent(
+        new CustomEvent('sub-agent-history-updated', {
+          detail: { agentName: subConfig.name, history: (e as CustomEvent<ChatMessage[]>).detail },
+        }),
+      );
+    };
+    child.addEventListener('history-updated', forwardTrace);
+
+    this.dispatchEvent(new CustomEvent('sub-agent-start', { detail: { name } }));
+    try {
+      await child.sendMessage(task ?? '');
+    } finally {
+      child.removeEventListener('history-updated', forwardTrace);
+      this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: { name } }));
+    }
+
+    const trace = child.getHistory() as ChatMessage[];
+    const completion = child.getSubAgentCompletion();
+
+    if (completion) {
+      return { result: completion.result as T, trace };
+    }
+
+    const finalMsg = [...trace]
+      .reverse()
+      .find((m) => m.role === 'assistant' && !m.toolCalls?.length && m.content?.trim());
+    return { result: (finalMsg?.content ?? '') as string, trace };
+  }
+
   /**
    * Continue the tool loop from current history without appending a new user message.
    * Used by OrchestratingDriver after an agent handoff.
@@ -306,6 +439,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
     }
 
     this.busy = true;
+    this.subAgentCompletion = undefined;
     try {
       return await this.runToolLoop('', undefined, transientPrimer);
     } catch (e) {
@@ -400,9 +534,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
           typeof args[key] === 'object' && args[key] !== null
             ? (args[key] as Record<string, unknown>)
             : {};
-        return innerHandler(innerArgs, {
-          requestInteraction: (c, d) => this.requestInteraction(c, d),
-        }).then((r) => (typeof r === 'string' ? r : JSON.stringify(r)));
+        return innerHandler(innerArgs, this.buildHandlerContext()).then((r) =>
+          typeof r === 'string' ? r : JSON.stringify(r),
+        );
       }
     }
 
@@ -487,7 +621,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
     let currentAttachments: ChatAttachment[] | undefined = attachments;
     let iterations = 0;
     let malformedAttempts = 0;
-    const startIteration = currentInput ? 1 : 0;
+    let emptyResponseAttempts = 0;
+    // True only for the very first LLM call. Used to exclude the pending user message
+    // from history (it is passed separately as currentInput). Must not be derived from
+    // `iterations` because fold operations decrement iterations, which would incorrectly
+    // re-trigger the slice on subsequent calls after a fold open/close.
+    let firstLlmCall = !!currentInput;
 
     while (iterations < this.maxToolIterations) {
       iterations += 1;
@@ -498,7 +637,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
         : foldSuffix || undefined;
 
       const primer = [...(this.primerHistory ?? []), ...(transientPrimer ?? [])];
-      const baseHistory = iterations === startIteration ? this.history.slice(0, -1) : this.history;
+      const baseHistory = firstLlmCall ? this.history.slice(0, -1) : this.history;
+      firstLlmCall = false;
       const historyForProvider = this.providerHistoryTransform
         ? this.providerHistoryTransform([...baseHistory])
         : baseHistory;
@@ -507,7 +647,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
       const systemPrompt =
         malformedAttempts > 0
           ? `${baseSystemPrompt ?? ''}\n\nIMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools.`
-          : baseSystemPrompt;
+          : emptyResponseAttempts > 0
+            ? `${baseSystemPrompt ?? ''}\n\nIMPORTANT: You must respond to the user's message. Call the appropriate tool or provide a text response — do not return an empty response.`
+            : baseSystemPrompt;
 
       const options: ChatRequestOptions = {
         systemPrompt,
@@ -547,10 +689,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
       const isEmptyResponse = !response.content?.trim() && !response.toolCalls?.length;
 
       if (isEmptyResponse) {
-        malformedAttempts += 1;
-        if (malformedAttempts < MAX_MALFORMED_RETRIES) {
+        emptyResponseAttempts += 1;
+        if (emptyResponseAttempts < MAX_EMPTY_RESPONSE_RETRIES) {
           logger.warn(
-            `ChatDriver: empty model response, retrying (${malformedAttempts}/${MAX_MALFORMED_RETRIES})`,
+            `ChatDriver: empty model response, retrying (${emptyResponseAttempts}/${MAX_EMPTY_RESPONSE_RETRIES})`,
           );
           iterations -= 1;
           continue;
@@ -581,7 +723,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
         [[], []],
       );
 
-      const executedById = new Map<string, { toolCallId: string; content: string }>();
+      const executedById = new Map<
+        string,
+        { toolCallId: string; content: string; subAgentTrace?: ChatMessage[] }
+      >();
       const unknownToolIds = new Set<string>();
       let anyRealToolExecuted = false;
       let hitUnknownToolLimit = false;
@@ -660,12 +805,14 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
             // Real tool execution
             try {
-              const result = await handler(tc.args, {
-                requestInteraction: (componentName, data) =>
-                  this.requestInteraction(componentName, data),
-              });
+              const traceCapture: { trace?: ChatMessage[] } = {};
+              const result = await handler(tc.args, this.buildHandlerContext(traceCapture));
               const content = typeof result === 'string' ? result : JSON.stringify(result);
-              executedById.set(tc.id, { toolCallId: tc.id, content });
+              executedById.set(tc.id, {
+                toolCallId: tc.id,
+                content,
+                subAgentTrace: traceCapture.trace,
+              });
               anyRealToolExecuted = true;
             } catch (e) {
               logger.error(`ChatDriver tool "${tc.name}" failed:`, e);
@@ -734,6 +881,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
             foldPath: !isFoldOpen && !isFoldClose && foldPath.length > 0 ? foldPath : undefined,
             unknown: isUnknown || undefined,
             availableTools: isUnknown ? availableToolNames : undefined,
+            subAgentTrace: executedById.get(tc.id)?.subAgentTrace,
           };
         });
         this.history[tcMsgIdx] = { ...tcMsg, toolCalls: annotatedCalls };
@@ -765,6 +913,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
         return { reason: 'agent-handoff', summary, remainingTask };
       }
 
+      // Sub-agent early exit — checked here so the exit point mirrors the
+      // system-call pattern above. Set by completeSubAgent() in a tool handler.
+      if (this.subAgentCompletion) {
+        return { reason: 'done' };
+      }
+
       currentInput = '';
     }
 

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

@@ -6,6 +6,7 @@ import type {
   ChatRequestOptions,
 } from '@genesislcap/foundation-ai';
 import type { AgentConfig, FallbackAgentConfig, SpecialistAgentConfig } from '../../config/config';
+import { transformHistoryForAgent } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
 import { ChatDriver, REQUEST_CONTINUATION_TOOL } from '../chat-driver/chat-driver';
@@ -54,27 +55,6 @@ function buildFallbackSystemPrompt(
   return `You are a helpful assistant. You cannot directly help with the user's request, but the following specialists are available:\n\n${agentList}\n\nPolitely let the user know what you can help with and invite them to rephrase their request.`;
 }
 
-/**
- * Prepares history for the LLM only: masks tool call args and results from other
- * agents so the active specialist is not confused by tools it does not have.
- * Canonical history in `ChatDriver` stays unmasked for UI and logging.
- */
-function transformHistoryForAgent(history: ChatMessage[], agentName: string): ChatMessage[] {
-  return history.map((msg) => {
-    if (!msg.agentName || msg.agentName === agentName) return msg;
-    if (msg.toolCalls?.length) {
-      return { ...msg, toolCalls: msg.toolCalls.map((tc) => ({ ...tc, args: {} })) };
-    }
-    if (msg.toolResult) {
-      return {
-        ...msg,
-        toolResult: { ...msg.toolResult, content: "[other agent's tool result omitted]" },
-      };
-    }
-    return msg;
-  });
-}
-
 /**
  * Orchestrates multiple specialist agents. Sits between `FoundationAiAssistant`
  * and `ChatDriver`, classifying each user message and routing it to the right
@@ -132,10 +112,18 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
       options.maxFoldOperations,
     );
 
-    // Proxy history-updated events from the shared driver
+    // Proxy events from the shared driver
     this.chatDriver.addEventListener('history-updated', (e: Event) => {
       this.dispatchEvent(new CustomEvent('history-updated', { detail: (e as CustomEvent).detail }));
     });
+    this.chatDriver.addEventListener('sub-agent-history-updated', (e: Event) => {
+      this.dispatchEvent(
+        new CustomEvent('sub-agent-history-updated', { detail: (e as CustomEvent).detail }),
+      );
+    });
+    this.chatDriver.addEventListener('sub-agent-stop', (e: Event) => {
+      this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: (e as CustomEvent).detail }));
+    });
   }
 
   resolveInteraction(interactionId: string, result: unknown): void {

package/src/config/config.ts

@@ -22,6 +22,10 @@ interface BaseAgentConfig {
    * Used to establish agent identity and behavioural rules.
    */
   primerHistory?: ChatMessage[];
+  /**
+   * Sub-agents available to this agent's tool handlers via `requestSubAgent`.
+   */
+  subAgents?: AgentConfig[];
 }
 
 /**
@@ -67,3 +71,23 @@ export interface FallbackAgentConfig extends BaseAgentConfig {
  * @beta
  */
 export type AgentConfig = SpecialistAgentConfig | FallbackAgentConfig;
+
+/**
+ * Identity helper that infers the narrowest possible type for an agent config,
+ * preserving string literal types (including `name`) without requiring `as const`.
+ *
+ * Use this when you need `typeof myAgent` to carry the literal `name` type —
+ * for example, when wiring `ChatToolHandlers<typeof myAgent>`.
+ *
+ * ```ts
+ * const myAgent = defineAgent({ name: 'my_agent', ... });
+ * type Handlers = ChatToolHandlers<typeof myAgent>;
+ * // requestSubAgent name param is now typed as 'my_agent'
+ * ```
+ *
+ * @beta
+ */
+
+export function defineAgent<const T extends AgentConfig>(config: T): T {
+  return config;
+}

package/src/main/main.styles.ts

@@ -451,6 +451,68 @@ export const styles = css`
     padding-left: 8px;
   }
 
+  .live-sub-agent-trace {
+    animation: slide-in-left 0.25s ease-out;
+    border-left: 2px solid var(--neutral-stroke-rest);
+    padding: 4px 8px;
+    margin: 4px 0;
+    opacity: 80%;
+  }
+
+  .live-sub-agent-name {
+    font-family: monospace;
+    font-size: 0.8em;
+    opacity: 70%;
+    font-style: italic;
+    display: block;
+    margin-bottom: 2px;
+  }
+
+  .sub-agent-trace {
+    margin-top: 6px;
+    border-left: 2px solid var(--neutral-stroke-rest);
+    padding-left: 8px;
+  }
+
+  .sub-agent-trace-summary {
+    font-family: monospace;
+    font-size: 0.85em;
+    opacity: 70%;
+    cursor: pointer;
+    user-select: none;
+    padding: 2px 0;
+  }
+
+  .sub-agent-trace-summary:hover {
+    opacity: 100%;
+  }
+
+  .sub-agent-message {
+    font-family: monospace;
+    font-size: 0.85em;
+    margin-top: 4px;
+  }
+
+  .sub-agent-assistant {
+    opacity: 85%;
+    white-space: pre-wrap;
+  }
+
+  .sub-agent-tool-call {
+    opacity: 60%;
+  }
+
+  .sub-agent-tool-name::before {
+    content: '⚙ ';
+  }
+
+  .sub-agent-tool-result {
+    opacity: 50%;
+    border-left: 1px solid var(--neutral-stroke-rest);
+    padding-left: 6px;
+    white-space: pre-wrap;
+  }
+
   .input-row {
     display: flex;
     gap: calc(var(--design-unit) * 2px);