@genesislcap/ai-assistant 14.420.0 → 14.421.1

package/docs/sub_agent.md

@@ -0,0 +1,310 @@
+# Sub-Agent Architecture
+
+## Overview
+
+Sub-agents are specialist agents embedded inside a parent agent. Tool handlers on the parent invoke them explicitly via `requestSubAgent` — a sibling to the existing `requestInteraction` API. Each sub-agent runs its own full tool loop to completion and returns its final response to the calling handler as a resolved promise. From the LLM's perspective, it called a normal tool and got a result back — it has no visibility into the sub-agent that produced it.
+
+The goal is to improve quality and reduce hallucinations by routing bounded, well-defined tasks (data extraction, validation, enrichment, judge passes) to purpose-built agents with focused prompts and tight tool sets, without burdening the parent's context window.
+
+---
+
+## Motivating Example
+
+**Trade File Extraction sub-agent**
+
+A user attaches a CSV of trades they want booked. The parent (Trades Agent) is good at booking and querying trades but is not the right place to parse arbitrary file formats, normalise field names, and resolve ambiguous values. Instead, the parent's `process_trade_file` tool handler delegates to a sub-agent:
+
+```ts
+const processTradeFile: ChatToolHandler = async (args, { requestSubAgent }) => {
+  const result = await requestSubAgent('trade_file_extractor', {
+    task: `Extract and normalise all trades from this file content: ${args.file_content}`,
+  });
+  // result is the sub-agent's final assistant message — a JSON string of normalised trades
+  return result;
+};
+```
+
+The sub-agent runs its own tool loop — calling `parse_csv`, `resolve_instrument`, `validate_trade_fields` etc. — and when it finishes, its final message is handed back to the parent handler. The parent then proceeds to book each trade with its own tools.
+
+Other natural candidates in the trades domain:
+- **Risk Judge sub-agent** — called inside a `confirm_trade` handler to validate against risk limits before confirming. The same sub-agent can be reused across multiple handlers with different `task` descriptions and `context` payloads.
+- **Counterparty Resolver sub-agent** — called inside a search handler to resolve raw counterparty names to canonical IDs. Multiple handlers can call it in parallel if they are invoked in the same LLM turn.
+
+---
+
+## Config
+
+Sub-agents are declared on the parent `AgentConfig` using a new optional `subAgents` field. They use the identical `AgentConfig` shape — no new interface is needed. The `name` field is used to look up the sub-agent at call time.
+
+```ts
+// config.ts  (BaseAgentConfig addition)
+interface BaseAgentConfig {
+  // ... existing fields ...
+
+  /**
+   * Sub-agents available to this agent's tool handlers via `requestSubAgent`.
+   * Sub-agents are leaf nodes — their own `subAgents` field is ignored.
+   */
+  subAgents?: AgentConfig[];
+
+  /**
+   * When this config is used as a sub-agent, caps the number of parent history
+   * messages passed as context. If unset, full history is passed. Messages within
+   * the cap are passed verbatim; messages older than the cap have tool args and
+   * results masked (same transform used by OrchestratingDriver for cross-agent history).
+   */
+  historyCap?: number;
+}
+```
+
+Example declaration in the host app:
+
+```ts
+const tradesAgent: SpecialistAgentConfig = {
+  name: 'Trades Agent',
+  description: 'Books, searches, and manages trades',
+  systemPrompt: '...',
+  toolDefinitions: [...tradeTools],
+  toolHandlers: { ...tradeHandlers },
+  subAgents: [
+    {
+      name: 'trade_file_extractor',
+      description: 'Extracts and normalises trade data from uploaded files',
+      historyCap: 4,
+      systemPrompt: `You are a data extraction specialist. Your only job is to parse the
+        provided file content and return a JSON array of normalised trade objects.
+        Each trade must have: instrument, quantity, side, price, counterparty.
+        Do not book trades. Do not ask the user questions. Just extract.`,
+      toolDefinitions: [parseCsvDefinition, resolveInstrumentDefinition],
+      toolHandlers: { parse_csv: parseCsvHandler, resolve_instrument: resolveInstrumentHandler },
+    },
+    {
+      name: 'risk_judge',
+      description: 'Validates a proposed action against risk limits',
+      systemPrompt: `You are a risk validation specialist. Assess the provided action
+        against the supplied risk limits and return a JSON object with approved (boolean)
+        and reason (string).`,
+      toolDefinitions: [getRiskLimitsDefinition],
+      toolHandlers: { get_risk_limits: getRiskLimitsHandler },
+    },
+  ],
+};
+```
+
+---
+
+## Invocation API
+
+Sub-agents are invoked from within tool handlers via `requestSubAgent`, available on the handler context alongside `requestInteraction`:
+
+```ts
+// ChatToolHandlers context (extended)
+context: {
+  requestInteraction: <T>(componentName: string, data: any) => Promise<T>,
+  requestSubAgent: <T = never>(name: string, options?: SubAgentRequestOptions) => Promise<T | string>,
+}
+
+interface SubAgentRequestOptions {
+  /** Plain-language description of what this specific invocation should do. */
+  task?: string;
+  /** Per-call override of the config-level historyCap. */
+  historyCap?: number;
+  /**
+   * Extra dynamic data for this invocation. Injected as a primer message before
+   * the task so the sub-agent sees it as part of its context.
+   */
+  context?: Record<string, unknown>;
+}
+```
+
+The return type is `T | string`:
+- `T` — when the sub-agent explicitly calls `completeSubAgent(result)` from within one of its tool handlers. The result is the structured value passed to `completeSubAgent`, fully typed.
+- `string` — when the sub-agent finishes its tool loop naturally with a plain text response, without calling `completeSubAgent`. This is always valid and requires no special tooling.
+
+With `T` defaulting to `never`, `T | string` collapses to `string` when no type parameter is provided — so untyped callers get a plain string with no extra ceremony.
+
+The `name` must match a declared sub-agent on the parent config — validated at call time with a clear error if not found.
+
+### `completeSubAgent`
+
+Sub-agent tool handlers receive `completeSubAgent` on their context. Calling it signals explicit completion with a structured result:
+
+```ts
+// Sub-agent tool handler context
+context: {
+  requestInteraction: <T>(componentName: string, data: any) => Promise<T>,
+  completeSubAgent: (result: unknown) => void,
+}
+```
+
+Example — a judge sub-agent with an explicit completion tool:
+
+```ts
+toolHandlers: {
+  submit_judgment: async (args, { completeSubAgent }) => {
+    completeSubAgent({ approved: args.approved, feedback: args.feedback });
+    return 'Judgment submitted.'; // still appended to the trace for debug visibility
+  },
+  get_risk_limits: async (args) => {
+    // normal tool — no completeSubAgent call needed
+    return fetchRiskLimits();
+  },
+}
+```
+
+When `completeSubAgent` is called, `SubAgentRunner` stores the result, and after that tool iteration completes the loop exits and resolves `requestSubAgent` with the stored value. If no tool ever calls `completeSubAgent`, the runner falls back to the final assistant message text.
+
+The parent handler then gets fully typed structured data with no `JSON.parse`:
+
+```ts
+const result = await requestSubAgent<{ approved: boolean; feedback: string }>('risk_judge', {
+  task: `Validate this trade: ${JSON.stringify(args.trade)}`,
+  context: { limits: getCurrentRiskLimits() },
+});
+
+if (typeof result === 'string') {
+  // sub-agent returned plain text — handle gracefully
+} else {
+  const { approved, feedback } = result;
+}
+```
+
+---
+
+## Runtime Mechanics
+
+### SubAgentRunner
+
+A lightweight class that owns a sub-agent's execution. Creates its own private `ChatDriver` instance, completely isolated from the parent's history.
+
+```
+SubAgentRunner
+  ├── Creates its own ChatDriver instance (sub-agent config)
+  ├── Builds the history snapshot from the parent (applying historyCap + masking if set)
+  ├── Prepends any call-time context as a primer message
+  ├── Sends the task string as the initial user message
+  └── Runs the tool loop to completion → returns the final assistant message text + trace
+```
+
+The parent's `ChatDriver` never sees the sub-agent's intermediate messages. It only receives the final string result when the handler's promise resolves — exactly as for any other tool.
+
+### Parallel execution
+
+No special work needed. The parent's tool loop already runs all tool calls from a single LLM turn in parallel via `Promise.all`. If two tool handlers both call `requestSubAgent`, their `SubAgentRunner` instances start concurrently and the parent resumes after the last one resolves.
+
+### History passed to the sub-agent
+
+By default the sub-agent receives a read-only snapshot of the full parent history as primer context. With `historyCap: N`:
+- The last N messages are passed verbatim with full fidelity.
+- Messages older than N have tool call args and results masked — using the same `transformHistoryForAgent` function already in `OrchestratingDriver`. No new logic needed.
+
+Any `context` object passed at call time is injected as an additional primer message immediately before the task, so the sub-agent sees it naturally as part of the conversation.
+
+---
+
+## History & Debug
+
+All sub-agent activity is hidden behind the existing `showToolCalls` toggle — no new UI settings needed. Sub-agents are an implementation detail of a tool call and are treated as such.
+
+### What the parent sees (always)
+
+A single `tool` role message containing the sub-agent's result. Compact, no noise.
+
+```
+[tool] process_trade_file → '[{"instrument":"AAPL","qty":100,...}, ...]'
+```
+
+### What the debug view sees (`showToolCalls: true`)
+
+The `tool` message carries an additional `subAgentTrace` field (UI-only, stripped from provider calls — same pattern as `foldPath`/`foldEvent`):
+
+```ts
+// Extension to ChatToolResult
+interface ChatToolResult {
+  toolCallId: string;
+  content: string;
+  /** Full message history from the sub-agent run, for debug display only. */
+  subAgentTrace?: ChatMessage[];
+}
+```
+
+The trace is rendered as a nested, collapsible conversation inside the parent tool call. It is breadcrumbed with the sub-agent name — consistent with how `foldPath` labels tool calls inside folds:
+
+```
+▼ process_trade_file
+    Trades Agent › trade_file_extractor
+    ├── [assistant] I'll parse the file and extract the trade data.
+    ├── [tool call] parse_csv(...)
+    ├── [tool result] ...
+    └── [complete] { trades: [...], warnings: [...] }
+```
+
+The `agentName` field is already set on every message by `ChatDriver.appendToHistory` — the UI uses it as the breadcrumb label without any additional tagging.
+
+### Live activity indicator
+
+While a sub-agent is running, `SubAgentRunner` fires `sub-agent-start` / `sub-agent-stop` events (with `detail: { name: string }`) via an `onProgress` callback provided by the parent `ChatDriver`. The parent dispatches these on itself so `FoundationAiAssistant` can show a contextual activity label (e.g. "Consulting risk judge...") in the same overlay used for the orchestrating classifier. Hidden behind `showToolCalls: false` by default — visible only when tool calls are shown.
+
+---
+
+## State Sharing
+
+**Structured result via `completeSubAgent` (preferred)**
+
+Define an explicit completion tool on the sub-agent. When called, `completeSubAgent` resolves the `requestSubAgent` promise with a typed object — no `JSON.parse`, no brittle string parsing.
+
+**Plain text fallback**
+
+If no tool calls `completeSubAgent`, the sub-agent's final assistant message text is returned as a `string`. Sufficient for simple cases where the sub-agent's response is human-readable prose the parent just forwards on.
+
+**Shared store via tools (for side-effects)**
+
+A sub-agent that needs to write to shared application state can be given tools that do so directly. The parent reads that state via its own tools. No built-in bridge needed — this is normal tool use, wired up by the host app.
+
+---
+
+## Implementation Plan
+
+### 1. Config (`config.ts`)
+- Add `subAgents?: AgentConfig[]` and `historyCap?: number` to `BaseAgentConfig`.
+
+### 2. Types (`chat.types.ts`)
+- Add `SubAgentRequestOptions` interface.
+- Extend `ChatToolHandlers` handler context with `requestSubAgent` and `completeSubAgent`.
+
+### 3. SubAgentRunner (`sub-agent-runner.ts`)
+New class, lives alongside `ChatDriver`:
+- Constructor: `(aiProvider, subAgentConfig, parentHistory: readonly ChatMessage[], onProgress: (event: 'start' | 'stop', name: string) => void)`
+- Method: `run(task: string, options?: SubAgentRequestOptions): Promise<{ result: unknown | string; trace: ChatMessage[] }>`
+- Applies `historyCap` masking, prepends `context` as a primer message, creates a `ChatDriver`.
+- Fires `onProgress('start', name)` before `sendMessage` and `onProgress('stop', name)` when the loop completes.
+- Provides `completeSubAgent` in the handler context. When called, stores the result and sets a completion flag.
+- After each tool iteration, checks the flag — if set, exits the loop and resolves with the stored value.
+- If the loop ends without `completeSubAgent` being called, resolves with the final assistant message text.
+- Ignores `subAgents` on the sub-agent config and logs a warning if present (leaf-only, v1).
+
+### 4. ChatDriver — `requestSubAgent` in handler context
+- In `applyAgent`, store `config.subAgents` as a map keyed by name.
+- When building the handler context object (currently `{ requestInteraction }`), add `requestSubAgent`: looks up the sub-agent config by name, constructs a `SubAgentRunner` with an `onProgress` callback that dispatches `sub-agent-start` / `sub-agent-stop` `CustomEvent`s on the `ChatDriver` itself, calls `runner.run(task, options)`, and returns the result.
+- If the sub-agent name is not found in the declared sub-agents, throws a descriptive error listing available names. This is caught by the existing tool error handler in `runToolLoop` and returned to the LLM as a tool result string — no special error path needed.
+
+### 5. `ChatToolResult` — trace field (`chat.types.ts`)
+- Add `subAgentTrace?: ChatMessage[]` to `ChatToolResult`.
+- In `ChatDriver.runToolLoop`, after a handler resolves, attach the trace if present.
+- Strip `subAgentTrace` in `providerHistoryTransform` so it is never sent to the AI provider.
+
+### 6. Debug UI
+- In the tool-calls panel, detect `toolResult.subAgentTrace` and render a collapsible nested conversation.
+- Style it distinctly (indented, labelled with the sub-agent name).
+
+---
+
+## Resolved Questions
+
+1. **Sub-agent of sub-agent?** Not supported in v1. Sub-agents are leaf nodes — `SubAgentRunner` ignores `subAgents` on the sub-agent config and logs a warning. Revisit if a concrete use case emerges.
+
+2. **Abort / cancellation**: Not needed. The driver registry PR (FUI-2495-ai-redux-store) decouples driver lifetime from DOM lifetime — a sub-agent that outlives a component disconnect simply completes against an unobserved driver. No abort mechanism required for v1.
+
+3. **Token budget / concurrency cap**: Deferred. A concurrency cap can be added later as a semaphore in `SubAgentRunner` without any interface changes.
+
+4. **History truncation**: Handled via `historyCap` on the sub-agent config (or overridden per-call). Messages within the cap are passed verbatim; older messages are masked using the existing `transformHistoryForAgent` function from `OrchestratingDriver`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.420.0",
+  "version": "14.421.1",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -64,23 +64,24 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.420.0",
-    "@genesislcap/genx": "14.420.0",
-    "@genesislcap/rollup-builder": "14.420.0",
-    "@genesislcap/ts-builder": "14.420.0",
-    "@genesislcap/uvu-playwright-builder": "14.420.0",
-    "@genesislcap/vite-builder": "14.420.0",
-    "@genesislcap/webpack-builder": "14.420.0",
+    "@genesislcap/foundation-testing": "14.421.1",
+    "@genesislcap/genx": "14.421.1",
+    "@genesislcap/rollup-builder": "14.421.1",
+    "@genesislcap/ts-builder": "14.421.1",
+    "@genesislcap/uvu-playwright-builder": "14.421.1",
+    "@genesislcap/vite-builder": "14.421.1",
+    "@genesislcap/webpack-builder": "14.421.1",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.420.0",
-    "@genesislcap/foundation-logger": "14.420.0",
-    "@genesislcap/foundation-ui": "14.420.0",
-    "@genesislcap/foundation-utils": "14.420.0",
-    "@genesislcap/rapid-design-system": "14.420.0",
-    "@genesislcap/web-core": "14.420.0",
+    "@genesislcap/foundation-ai": "14.421.1",
+    "@genesislcap/foundation-logger": "14.421.1",
+    "@genesislcap/foundation-redux": "14.421.1",
+    "@genesislcap/foundation-ui": "14.421.1",
+    "@genesislcap/foundation-utils": "14.421.1",
+    "@genesislcap/rapid-design-system": "14.421.1",
+    "@genesislcap/web-core": "14.421.1",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -95,5 +96,5 @@
   "peerDependencies": {
     "@microsoft/fast-react-wrapper": ">=0.3.0"
   },
-  "gitHead": "52c9259f8fb7a203979c832b08388579ae728a38"
+  "gitHead": "ef3efc54221d1c0af5c842f0b98225ca813b4042"
 }

package/src/channel/ai-activity-channel.ts

@@ -1,19 +1,3 @@
-import type { ChatMessage } from '@genesislcap/foundation-ai';
-import type { AiAssistantAnimation } from '../main/main.types';
-
-/**
- * Serialized state of a `FoundationAiAssistant` instance.
- * All fields are JSON-serializable.
- *
- * @beta
- */
-export interface AiAssistantSerializedState {
-  messages: ChatMessage[];
-  showToolCalls: boolean;
-  showThinkingSteps: boolean;
-  enabledAnimations: AiAssistantAnimation[];
-}
-
 /**
  * Event map for the AI activity bus.
  *
@@ -33,8 +17,8 @@ export interface AgenticActivityEvents {
   'halo-start': { toolNames: string[] };
   /** Fired when the assistant finishes all tool processing and returns to idle. */
   'halo-stop': undefined;
-  /** Fired when the user clicks the expand button — moves assistant from bubble into layout. */
-  'chat-popout': { state: AiAssistantSerializedState };
-  /** Fired when the user clicks the collapse button — moves assistant from layout back to bubble. */
-  'chat-popin': { state: AiAssistantSerializedState };
+  /** Fired when the user clicks the expand button — moves assistant from bubble into layout. State lives in the session store, not in this event. */
+  'chat-popout': undefined;
+  /** Fired when the user clicks the collapse button — moves assistant from layout back to bubble. State lives in the session store, not in this event. */
+  'chat-popin': undefined;
 }

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

@@ -0,0 +1,69 @@
+import type {
+  ChatAttachment,
+  ChatDriverResult,
+  ChatMessage,
+  ChatToolDefinition,
+} from '@genesislcap/foundation-ai';
+
+/** @internal */
+export interface AllAgentSummary {
+  name: string;
+  description: string;
+  tools: ChatToolDefinition[];
+}
+
+/**
+ * Common interface implemented by both `ChatDriver` (single-agent) and
+ * `OrchestratingDriver` (multi-agent). `FoundationAiAssistant` depends only
+ * on this interface — the concrete class is chosen at startup based on how
+ * many agents are configured.
+ *
+ * Extends `EventTarget` so consumers can subscribe to `history-updated` events
+ * without knowing the concrete implementation.
+ *
+ * @beta
+ */
+export interface AiDriver extends EventTarget {
+  /**
+   * Send a user message and run the tool loop to completion.
+   */
+  sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
+
+  /**
+   * Continue the tool loop from the current history without appending a new
+   * user message. Used by `OrchestratingDriver` on agent handoffs — the
+   * handoff context is already in history; `transientPrimer` is injected as
+   * an invisible one-shot message for this call only.
+   */
+  continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
+
+  /**
+   * Resolve a pending blocking interaction with the given result.
+   */
+  resolveInteraction(interactionId: string, result: unknown): void;
+
+  /**
+   * Seed the driver's message history (called on state restore / pop-in).
+   */
+  loadHistory(messages: ChatMessage[]): void;
+
+  /**
+   * Return the full, unredacted conversation history.
+   */
+  getRawHistory?(): readonly ChatMessage[];
+
+  /**
+   * Returns true if the driver is currently processing a request.
+   */
+  isBusy(): boolean;
+
+  /**
+   * Get query suggestions from the AI.
+   */
+  getSuggestions(
+    history: ChatMessage[],
+    prompt: string,
+    count: number,
+    allAgentInfo?: AllAgentSummary[],
+  ): Promise<string[]>;
+}

package/src/components/ai-driver/index.ts

@@ -0,0 +1 @@
+export type { AiDriver } from './ai-driver';