@genesislcap/ai-assistant 14.420.0 → 14.421.0

package/src/main/main.types.ts

@@ -14,6 +14,17 @@ export type AiAssistantState = 'idle' | 'loading' | 'error';
  */
 export type PopoutMode = 'expand' | 'collapse';
 
+/**
+ * State of the chat suggestions feature.
+ *
+ * @beta
+ */
+export type SuggestionsState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'loaded'; suggestions: string[] }
+  | { status: 'error'; message: string };
+
 /**
  * Metadata describing a UI animation in the assistant.
  *

package/src/state/ai-assistant-slice.ts

@@ -0,0 +1,80 @@
+import type { ChatMessage } from '@genesislcap/foundation-ai';
+import { createSlice } from '@genesislcap/foundation-redux';
+import type { PayloadAction } from '@genesislcap/foundation-redux';
+import type { AgentConfig } from '../config/config';
+import type { AiAssistantAnimation, AiAssistantState, SuggestionsState } from '../main/main.types';
+
+/**
+ * Shape of a single AI assistant session's serializable state.
+ *
+ * @internal
+ */
+export interface AiAssistantSessionState {
+  messages: ChatMessage[];
+  state: AiAssistantState;
+  showToolCalls: boolean;
+  showThinkingSteps: boolean;
+  showAgentSwitchIndicator: boolean;
+  enabledAnimations: AiAssistantAnimation[];
+  suggestionsState: SuggestionsState;
+  contextTokens: number | undefined;
+  contextLimit: number | undefined;
+  activeAgent: Omit<AgentConfig, 'toolHandlers'> | undefined;
+  /** Draft text in the input box — preserved across pop-in/pop-out cycles. */
+  inputValue: string;
+}
+
+export const defaultSessionState: AiAssistantSessionState = {
+  messages: [],
+  state: 'idle',
+  showToolCalls: false,
+  showThinkingSteps: false,
+  showAgentSwitchIndicator: false,
+  enabledAnimations: [],
+  suggestionsState: { status: 'idle' },
+  contextTokens: undefined,
+  contextLimit: undefined,
+  activeAgent: undefined,
+  inputValue: '',
+};
+
+export const aiAssistantSlice = createSlice({
+  name: 'aiAssistant',
+  initialState: defaultSessionState,
+  reducers: {
+    setMessages(state, action: PayloadAction<ChatMessage[]>) {
+      state.messages = action.payload;
+    },
+    setState(state, action: PayloadAction<AiAssistantState>) {
+      state.state = action.payload;
+    },
+    setShowToolCalls(state, action: PayloadAction<boolean>) {
+      state.showToolCalls = action.payload;
+    },
+    setShowThinkingSteps(state, action: PayloadAction<boolean>) {
+      state.showThinkingSteps = action.payload;
+    },
+    setShowAgentSwitchIndicator(state, action: PayloadAction<boolean>) {
+      state.showAgentSwitchIndicator = action.payload;
+    },
+    setEnabledAnimations(state, action: PayloadAction<AiAssistantAnimation[]>) {
+      state.enabledAnimations = action.payload;
+    },
+    setSuggestionsState(state, action: PayloadAction<SuggestionsState>) {
+      state.suggestionsState = action.payload;
+    },
+    setContextTokens(state, action: PayloadAction<number | undefined>) {
+      state.contextTokens = action.payload;
+    },
+    setContextLimit(state, action: PayloadAction<number | undefined>) {
+      state.contextLimit = action.payload;
+    },
+    setActiveAgent(state, action: PayloadAction<Omit<AgentConfig, 'toolHandlers'> | undefined>) {
+      state.activeAgent = action.payload;
+    },
+    setInputValue(state, action: PayloadAction<string>) {
+      state.inputValue = action.payload;
+    },
+  },
+  selectors: {},
+});

package/src/state/driver-registry.ts

@@ -0,0 +1,51 @@
+import type { AiDriver } from '../components/ai-driver/ai-driver';
+
+/**
+ * Module-level registry of AI drivers keyed by session identity string.
+ *
+ * Driver lifetime is tied to the conversation session, not the DOM.
+ * Components look up or create drivers on connect and only unwire
+ * event listeners on disconnect — the driver is never destroyed by
+ * a lifecycle event.
+ *
+ * @internal
+ */
+const driverRegistry = new Map<string, AiDriver>();
+
+/**
+ * Returns the existing driver for the given key, or calls the factory
+ * to create and register a new one.
+ */
+export function getOrCreateDriver(key: string, factory: () => AiDriver): AiDriver {
+  const existing = driverRegistry.get(key);
+  if (existing) return existing;
+  const driver = factory();
+  driverRegistry.set(key, driver);
+  return driver;
+}
+
+/**
+ * Returns the existing driver for the given key, or `undefined`.
+ */
+export function getDriver(key: string): AiDriver | undefined {
+  return driverRegistry.get(key);
+}
+
+/**
+ * Removes and returns the driver for the given key.
+ * Used when agents change (driver must be rebuilt) or on explicit session teardown.
+ */
+export function deleteDriver(key: string): AiDriver | undefined {
+  const driver = driverRegistry.get(key);
+  driverRegistry.delete(key);
+  return driver;
+}
+
+/**
+ * Removes all entries. Exposed for test isolation only — not part of the public API.
+ *
+ * @internal
+ */
+export function clearDriverRegistry(): void {
+  driverRegistry.clear();
+}

package/src/state/session-store.ts

@@ -0,0 +1,56 @@
+import { createStore } from '@genesislcap/foundation-redux';
+import {
+  aiAssistantSlice,
+  defaultSessionState,
+  type AiAssistantSessionState,
+} from './ai-assistant-slice';
+
+type SessionStoreReturn = ReturnType<typeof makeStore>;
+
+const sessionStores = new Map<string, SessionStoreReturn>();
+
+function makeStore(devTools: boolean | undefined) {
+  return createStore(
+    [aiAssistantSlice],
+    { aiAssistant: defaultSessionState },
+    devTools !== undefined ? { devTools } : undefined,
+  );
+}
+
+/**
+ * Returns the session store for the given key, creating one if it does not
+ * already exist. Omit `devTools` (or pass `undefined`) to defer to `isDev()`.
+ * Pass `true` to force-enable or `false` to force-disable Redux DevTools.
+ */
+export function getSessionStore(key: string, devTools?: boolean): SessionStoreReturn {
+  const existing = sessionStores.get(key);
+  if (existing) return existing;
+  const created = makeStore(devTools);
+  sessionStores.set(key, created);
+  return created;
+}
+
+/**
+ * Returns true if a session store already exists for the given key.
+ */
+export function hasSessionStore(key: string): boolean {
+  return sessionStores.has(key);
+}
+
+/**
+ * Deletes the session store for the given key.
+ */
+export function deleteSessionStore(key: string): void {
+  sessionStores.delete(key);
+}
+
+/**
+ * Removes all session stores. Exposed for test isolation only — not part of the public API.
+ *
+ * @internal
+ */
+export function clearAllSessionStores(): void {
+  sessionStores.clear();
+}
+
+export type { SessionStoreReturn, AiAssistantSessionState };

package/src/suggestions/chat-suggestions.ts

@@ -0,0 +1,158 @@
+import { customElement, observable, html, css, repeat, when } from '@genesislcap/web-core';
+import { GenesisElement } from '@genesislcap/web-core';
+import type { SuggestionsState } from '../main/main.types';
+
+type LoadedState = { status: 'loaded'; suggestions: string[] };
+
+const PILL_ANIMATION_STAGGER_MS = 70;
+
+const template = html<ChatSuggestions>`
+  ${when(
+    (x) => x.state.status === 'loading',
+    html<ChatSuggestions>`
+      <div class="suggestions-container">
+        ${repeat(
+          () => Array.from({ length: 3 }),
+          html`
+            <div class="suggestion-placeholder"></div>
+          `,
+        )}
+      </div>
+    `,
+  )}
+  ${when(
+    (x) => x.state.status === 'loaded',
+    html<ChatSuggestions>`
+      <div class="suggestions-container">
+        ${repeat(
+          (x) => (x.state as LoadedState).suggestions,
+          html<string, ChatSuggestions>`
+            <button
+              class="suggestion-pill"
+              style="animation-delay: ${(_, c) => c.index * PILL_ANIMATION_STAGGER_MS}ms"
+              @click="${(suggestion, c) => c.parent.handleSuggestionClick(suggestion)}"
+            >
+              ${(suggestion) => suggestion}
+            </button>
+          `,
+        )}
+      </div>
+    `,
+  )}
+`;
+
+const styles = css`
+  :host {
+    display: block;
+  }
+
+  .suggestions-container {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+    padding: 10px calc(var(--design-unit) * 3px) 6px;
+    background-color: var(--neutral-layer-2);
+    animation: suggestions-appear 0.2s ease-out both;
+  }
+
+  @keyframes suggestions-appear {
+    from {
+      opacity: 0;
+      transform: translateY(6px);
+    }
+
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  .suggestion-pill {
+    display: inline-flex;
+    align-items: center;
+    padding: 5px 14px;
+    background: color-mix(in srgb, var(--accent-fill-rest) 10%, var(--neutral-layer-3));
+    color: var(--neutral-foreground-rest);
+    border: 1px solid color-mix(in srgb, var(--accent-fill-rest) 25%, var(--neutral-stroke-rest));
+    border-radius: 20px;
+    font-family: var(--body-font);
+    font-size: 0.85em;
+    cursor: pointer;
+    transition:
+      background 0.15s ease,
+      border-color 0.15s ease,
+      transform 0.15s ease,
+      box-shadow 0.15s ease;
+    animation: pill-appear 0.3s ease-out both;
+    max-width: 100%;
+    white-space: normal;
+    text-align: left;
+  }
+
+  .suggestion-pill:hover {
+    background: color-mix(in srgb, var(--accent-fill-rest) 20%, var(--neutral-layer-3));
+    border-color: color-mix(in srgb, var(--accent-fill-rest) 50%, var(--neutral-stroke-rest));
+    transform: translateY(-1px);
+    box-shadow: 0 2px 8px color-mix(in srgb, var(--accent-fill-rest) 20%, transparent);
+  }
+
+  .suggestion-pill:active {
+    transform: translateY(0);
+    box-shadow: none;
+  }
+
+  @keyframes pill-appear {
+    from {
+      opacity: 0;
+      transform: scale(0.88) translateY(4px);
+    }
+
+    to {
+      opacity: 1;
+      transform: scale(1) translateY(0);
+    }
+  }
+
+  .suggestion-placeholder {
+    height: 30px;
+    width: 110px;
+    background: var(--neutral-layer-3);
+    border-radius: 20px;
+    animation: placeholder-pulse 1.6s ease-in-out infinite;
+  }
+
+  .suggestion-placeholder:nth-child(2) {
+    width: 150px;
+    animation-delay: 0.25s;
+  }
+
+  .suggestion-placeholder:nth-child(3) {
+    width: 130px;
+    animation-delay: 0.5s;
+  }
+
+  @keyframes placeholder-pulse {
+    0%,
+    100% {
+      opacity: 0.35;
+    }
+
+    50% {
+      opacity: 0.65;
+    }
+  }
+`;
+
+@customElement({
+  name: 'chat-suggestions',
+  template,
+  styles,
+})
+export class ChatSuggestions extends GenesisElement {
+  @observable
+  state: SuggestionsState = { status: 'idle' };
+
+  handleSuggestionClick(suggestion: string): void {
+    this.$emit('suggestion-clicked', suggestion);
+  }
+}

package/src/types/ai-chat-widget.ts

@@ -1,3 +1,5 @@
+import type { InteractionResult } from '@genesislcap/foundation-ai';
+
 /**
  * Interface that AI inline interaction components can implement.
  * The `AiChatInteractionWrapper` always sets `data` and `resolved` on the rendered element.
@@ -6,6 +8,6 @@
  */
 export interface AiChatWidget {
   data: unknown;
-  /** When true, the interaction has already been resolved. Components should render read-only. */
-  resolved?: boolean;
+  /** The result when the interaction has been resolved. Truthy = resolved; value contains status/payload for display. */
+  resolved?: InteractionResult<unknown>;
 }

package/src/utils/index.ts

@@ -1 +1,2 @@
 export * from './logger';
+export * from './tool-fold';

package/src/utils/tool-fold.ts

@@ -0,0 +1,181 @@
+import type { ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
+
+/**
+ * Symbol used to attach ToolFold metadata to a facade handler function.
+ * The ChatDriver inspects this to detect fold facades at runtime.
+ *
+ * @internal
+ */
+export const TOOL_FOLD_SYMBOL = Symbol('toolFold');
+
+/**
+ * Internal metadata for a tool fold. Attached to the facade handler via TOOL_FOLD_SYMBOL.
+ *
+ * @internal
+ */
+export interface ToolFold {
+  /** Facade tool name. */
+  name: string;
+  /** Description shown to the model. */
+  description: string;
+  /** Optional guidance injected in the fold-open response. */
+  usageNotes?: string;
+  /** Tool definitions inside this fold. */
+  tools: ChatToolDefinition[];
+  /** Handlers for the inner tools (keyed by tool name). */
+  handlers: ChatToolHandlers;
+  /**
+   * When true (default), all other tools are removed when this fold opens —
+   * the model can only see this fold's tools until it closes.
+   * When false, sibling tools remain alongside the inner tools.
+   */
+  exclusive: boolean;
+}
+
+/**
+ * The value returned by `createToolFold`.
+ *
+ * @beta
+ */
+export interface ToolFoldResult {
+  /**
+   * The facade tool definition. Add this to your agent's `toolDefinitions`.
+   * It is a regular `ChatToolDefinition` with an empty parameter schema.
+   */
+  definition: ChatToolDefinition;
+  /**
+   * The facade handler — a single-entry map keyed by the fold name.
+   * Spread this into your agent's `toolHandlers`.
+   * Inner tool handlers are NOT included here — they are encapsulated inside
+   * the fold metadata and installed by the driver only when the fold opens.
+   */
+  handler: ChatToolHandlers;
+}
+
+/**
+ * Creates a tool fold — a facade that hides a group of related tools behind a single
+ * named entry, revealing them progressively when the model invokes the facade.
+ *
+ * The `tools` and `handlers` parameters accept the exact same types as `AgentConfig.toolDefinitions`
+ * and `AgentConfig.toolHandlers`, so existing tool creation functions can be passed in unchanged.
+ *
+ * @example
+ * ```typescript
+ * const tradingTools = createToolFold({
+ *   name: 'trading_tools',
+ *   tools: createTradesToolDefinitions(),
+ *   handlers: createTradesToolHandlers(connect),
+ * });
+ *
+ * const agent: AgentConfig = {
+ *   name: 'Trades',
+ *   systemPrompt: '...',
+ *   toolDefinitions: [getCurrentDateDef, tradingTools.definition],
+ *   toolHandlers: { get_current_date: handler, ...tradingTools.handler },
+ * };
+ * ```
+ *
+ * @example Nesting folds
+ * ```typescript
+ * const insertFold = createToolFold({
+ *   name: 'trade_insertion',
+ *   tools: [validateDef, insertDef],
+ *   handlers: { validate_trade: vHandler, insert_trade: iHandler },
+ * });
+ *
+ * const tradingFold = createToolFold({
+ *   name: 'trading_tools',
+ *   tools: [searchDef, insertFold.definition],
+ *   handlers: { search_trades: sHandler, ...insertFold.handler },
+ * });
+ * ```
+ *
+ * @beta
+ */
+export function createToolFold(config: {
+  /** Facade tool name — used as the tool name the model calls to open this fold. */
+  name: string;
+  /**
+   * Description shown to the model for the facade tool.
+   * If omitted, auto-generated from the inner tool names:
+   * "Contains: tool_a, tool_b. Invoke to access these tools."
+   */
+  description?: string;
+  /**
+   * Optional usage guidance injected into the fold-open response message.
+   * Not included in the facade description — only visible once the fold is open.
+   */
+  usageNotes?: string;
+  /** Inner tool definitions. Same type as `AgentConfig.toolDefinitions`. */
+  tools: ChatToolDefinition[];
+  /** Inner tool handlers. Same type as `AgentConfig.toolHandlers`. */
+  handlers: ChatToolHandlers;
+  /**
+   * When true (default), all other tools are removed when this fold opens.
+   * When false, sibling tools remain available alongside the inner tools.
+   */
+  exclusive?: boolean;
+}): ToolFoldResult {
+  const description =
+    config.description ??
+    `Contains: ${config.tools.map((t) => t.name).join(', ')}. Invoke to access these tools.`;
+
+  const fold: ToolFold = {
+    name: config.name,
+    description,
+    usageNotes: config.usageNotes,
+    tools: config.tools,
+    handlers: config.handlers,
+    exclusive: config.exclusive ?? true,
+  };
+
+  const definition: ChatToolDefinition = {
+    name: config.name,
+    description,
+    parameters: { type: 'object', properties: {} },
+  };
+
+  // The facade handler body is never actually called — the driver intercepts it
+  // via TOOL_FOLD_SYMBOL before dispatch. The body is a no-op fallback.
+  const facadeHandler = async (): Promise<string> => `Fold: ${config.name}`;
+  (facadeHandler as any)[TOOL_FOLD_SYMBOL] = fold;
+
+  return {
+    definition,
+    handler: {
+      [config.name]: facadeHandler,
+    },
+  };
+}
+
+/**
+ * A tool entry in the expanded debug tree.
+ * Folds are represented as nodes with a `tools` array; regular tools have none.
+ *
+ * @beta
+ */
+export interface ToolTreeNode extends ChatToolDefinition {
+  /** Present when this tool is a fold — contains its inner tools recursively expanded. */
+  tools?: ToolTreeNode[];
+}
+
+/**
+ * Expands a flat list of tool definitions into a nested tree by resolving fold
+ * metadata from the corresponding handlers. Use this for debug output so the
+ * full tool hierarchy is visible rather than just the top-level facade names.
+ *
+ * @beta
+ */
+export function expandToolTree(
+  definitions: ChatToolDefinition[],
+  handlers: ChatToolHandlers,
+): ToolTreeNode[] {
+  return definitions.map((def) => {
+    const handler = handlers[def.name];
+    const fold: ToolFold | undefined = handler ? (handler as any)[TOOL_FOLD_SYMBOL] : undefined;
+    if (fold) {
+      return { ...def, tools: expandToolTree(fold.tools, fold.handlers) };
+    }
+    return { ...def };
+  });
+}