@genesislcap/ai-assistant 14.403.0-ai-assistant.1

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

@@ -0,0 +1,389 @@
+import { createTypedBroadcastChannel } from '@genesislcap/foundation-broadcast-channel';
+import type { TypedBroadcastChannel } from '@genesislcap/foundation-broadcast-channel';
+import { attr, customElement, GenesisElement, html, observable } from '@genesislcap/web-core';
+import { AI_ACTIVITY_CHANNEL_NAME } from '../../channel/ai-activity-channel';
+import type { AiActivityEvents } from '../../channel/ai-activity-channel';
+import { styles } from './chat-bubble.styles';
+import { AiChatBubbleTemplate } from './chat-bubble.template';
+
+/** Default dimensions of the dialog panel */
+const DIALOG_DEFAULT_WIDTH = 400;
+const DIALOG_DEFAULT_HEIGHT = 520;
+
+/** Initial position: bubble starts this far from the right/bottom viewport edges */
+const BUBBLE_INITIAL_RIGHT_OFFSET = 90;
+
+/** Initial position: dialog starts this far from the right/bottom viewport edges */
+const DIALOG_INITIAL_RIGHT_OFFSET = 440;
+const DIALOG_INITIAL_BOTTOM_OFFSET = 570;
+
+/** Minimum distance the dialog is allowed from any viewport edge */
+const VIEWPORT_EDGE_MARGIN = 20;
+
+/** Minimum pointer movement (px) to classify an interaction as a drag rather than a click */
+const DRAG_THRESHOLD = 4;
+
+/** Keeps the bubble fully inside the viewport when dragged (accounts for bubble size + border) */
+const BUBBLE_DRAG_MARGIN = 64;
+
+/** Horizontal offset between bubble center and dialog left edge when toggling open/close */
+const DIALOG_BUBBLE_HORIZONTAL_OFFSET = 340;
+
+/** How far above the bubble the dialog opens */
+const DIALOG_OPEN_TOP_OFFSET = 470;
+
+/** How far below the dialog top the bubble snaps when closing via the X button */
+const BUBBLE_SNAP_BOTTOM_OFFSET = 458;
+
+/** Fallback tooltip width used before the element has been measured in the DOM */
+const TOOLTIP_FALLBACK_WIDTH = 155;
+
+@customElement({
+  name: 'foundation-ai-chat-bubble',
+  template: html`
+    ${() => AiChatBubbleTemplate()}
+  `,
+  styles,
+})
+export class AiChatBubble extends GenesisElement {
+  @attr({ attribute: 'title' }) title: string = 'AI Assistant';
+  @attr({ attribute: 'image-src' }) imageSrc?: string;
+  @attr({ attribute: 'channel-name' }) channelName: string = AI_ACTIVITY_CHANNEL_NAME;
+  @attr({ attribute: 'design-system-prefix' }) designSystemPrefix: string = 'rapid';
+
+  @observable dialogContent: HTMLElement[] = [];
+  @observable private tooltipMeasuredWidth: number = 0;
+  @observable bubbleLeft: number = 0;
+  @observable bubbleTop: number = 0;
+  @observable dialogLeft: number = 0;
+  @observable dialogTop: number = 0;
+  @observable dialogWidth: number = DIALOG_DEFAULT_WIDTH;
+  @observable dialogHeight: number = DIALOG_DEFAULT_HEIGHT;
+  @observable dialogOpen: boolean = false;
+  @observable hovered: boolean = false;
+
+  private bubbleChannel?: TypedBroadcastChannel<AiActivityEvents>;
+  private injectedCloseBtn?: Element;
+  private resizeObserver?: ResizeObserver;
+  private dragging: boolean = false;
+  private dragTarget: 'bubble' | 'dialog' | null = null;
+  private startMouseX: number = 0;
+  private startMouseY: number = 0;
+  private startElemLeft: number = 0;
+  private startElemTop: number = 0;
+  private hasDragged: boolean = false;
+  private latestMouseX: number = 0;
+  private latestMouseY: number = 0;
+  private rafHandle?: number;
+  private closeAbort?: AbortController;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.bubbleLeft = window.innerWidth - BUBBLE_INITIAL_RIGHT_OFFSET;
+    this.bubbleTop = window.innerHeight - 100;
+    this.dialogLeft = Math.max(
+      VIEWPORT_EDGE_MARGIN,
+      window.innerWidth - DIALOG_INITIAL_RIGHT_OFFSET,
+    );
+    this.dialogTop = Math.max(
+      VIEWPORT_EDGE_MARGIN,
+      window.innerHeight - DIALOG_INITIAL_BOTTOM_OFFSET,
+    );
+    document.addEventListener('mousemove', this.onDocMouseMove);
+    document.addEventListener('mouseup', this.onDocMouseUp);
+    this.bubbleChannel = createTypedBroadcastChannel<AiActivityEvents>(this.channelName);
+    this.bubbleChannel.addEventListener('message', this.onBubbleChannelMessage);
+    // Measure tooltip width once after first render. The bubble is visible on connect
+    // (dialogOpen starts false), so the element is in the DOM by the time rAF fires.
+    // This value persists through open/close cycles — no re-measurement needed unless
+    // the title attribute changes.
+    requestAnimationFrame(() => {
+      const el = this.shadowRoot?.querySelector<HTMLElement>('.tooltip');
+      if (el) this.tooltipMeasuredWidth = el.offsetWidth;
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('mousemove', this.onDocMouseMove);
+    document.removeEventListener('mouseup', this.onDocMouseUp);
+    this.bubbleChannel?.removeEventListener('message', this.onBubbleChannelMessage);
+    this.bubbleChannel?.close();
+    this.bubbleChannel = undefined;
+    this.injectedCloseBtn?.removeEventListener('click', this.onCloseBtnClick);
+    this.injectedCloseBtn?.remove();
+    this.injectedCloseBtn = undefined;
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = undefined;
+    if (this.rafHandle !== undefined) {
+      cancelAnimationFrame(this.rafHandle);
+      this.rafHandle = undefined;
+    }
+    this.closeAbort?.abort();
+    this.closeAbort = undefined;
+  }
+
+  dialogOpenChanged(_: boolean, next: boolean) {
+    if (next) {
+      requestAnimationFrame(() => {
+        const el = this.shadowRoot?.querySelector<HTMLElement>('.dialog');
+        if (!el) return;
+        this.resizeObserver = new ResizeObserver((entries) => {
+          const size = entries[0]?.borderBoxSize?.[0];
+          if (size) {
+            this.dialogWidth = Math.round(size.inlineSize);
+            this.dialogHeight = Math.round(size.blockSize);
+          }
+        });
+        this.resizeObserver.observe(el);
+      });
+    } else {
+      this.resizeObserver?.disconnect();
+      this.resizeObserver = undefined;
+    }
+  }
+
+  dialogContentChanged(_: HTMLElement[], next: HTMLElement[]) {
+    if (!next?.length || this.injectedCloseBtn) return;
+    for (const el of next) {
+      const assistant =
+        el.tagName.toLowerCase() === 'foundation-ai-assistant'
+          ? el
+          : el.shadowRoot?.querySelector('foundation-ai-assistant');
+      if (assistant) {
+        this.injectCloseButton(assistant);
+        break;
+      }
+    }
+  }
+
+  private injectCloseButton(assistant: Element) {
+    const prefix = this.designSystemPrefix;
+    const btn = document.createElement(`${prefix}-button`);
+    btn.setAttribute('slot', 'header-actions-extra');
+    btn.setAttribute('appearance', 'stealth');
+    btn.setAttribute('title', 'Close');
+    const icon = document.createElement(`${prefix}-icon`);
+    icon.setAttribute('name', 'times');
+    btn.appendChild(icon);
+    btn.addEventListener('click', this.onCloseBtnClick);
+    assistant.appendChild(btn);
+    this.injectedCloseBtn = btn;
+  }
+
+  private onBubbleChannelMessage = (event: MessageEvent) => {
+    if (event.data?.type === 'chat-popout') {
+      this.startCloseDialog();
+      this.hidden = true;
+    } else if (event.data?.type === 'chat-popin') {
+      this.cancelClose();
+      this.hidden = false;
+      this.dialogOpen = true;
+    }
+  };
+
+  onBubbleMouseDown(e: MouseEvent) {
+    e.preventDefault();
+    this.dragging = true;
+    this.dragTarget = 'bubble';
+    this.startMouseX = e.clientX;
+    this.startMouseY = e.clientY;
+    this.latestMouseX = e.clientX;
+    this.latestMouseY = e.clientY;
+    this.startElemLeft = this.bubbleLeft;
+    this.startElemTop = this.bubbleTop;
+    this.hasDragged = false;
+  }
+
+  onDialogHeaderMouseDown(e: CustomEvent<{ clientX: number; clientY: number }>) {
+    // Sync actual rendered size before dragging — the browser's CSS resize handle
+    // updates the element's size but our observables may not have caught up yet.
+    const dialogEl = this.shadowRoot?.querySelector<HTMLElement>('.dialog');
+    if (dialogEl) {
+      this.dialogWidth = dialogEl.offsetWidth;
+      this.dialogHeight = dialogEl.offsetHeight;
+    }
+    this.dragging = true;
+    this.dragTarget = 'dialog';
+    this.startMouseX = e.detail.clientX;
+    this.startMouseY = e.detail.clientY;
+    this.latestMouseX = e.detail.clientX;
+    this.latestMouseY = e.detail.clientY;
+    this.startElemLeft = this.dialogLeft;
+    this.startElemTop = this.dialogTop;
+    this.hasDragged = false;
+  }
+
+  private readonly onCloseBtnClick = () => this.onCloseDialog();
+
+  // Cancels an in-flight close animation and restores the dialog to its open state.
+  // Needed for the chat-popin case: startCloseDialog() may have been called (adding
+  // .closing and an animationend listener) but the host was hidden before the animation
+  // finished. When the host reappears via chat-popin, we cancel the pending close so
+  // the dialog stays open rather than disappearing once animationend eventually fires.
+  private cancelClose() {
+    this.closeAbort?.abort();
+    this.closeAbort = undefined;
+    const el = this.shadowRoot?.querySelector<HTMLElement>('.dialog');
+    el?.classList.remove('closing');
+  }
+
+  // Plays the closing animation before removing the dialog from the DOM.
+  // dialogOpen must stay true while the animation runs — setting it to false
+  // immediately would cause the repeat directive to remove the element before
+  // the animation has a chance to play. We only set dialogOpen = false inside
+  // the animationend callback, at which point FAST removes the element cleanly.
+  // If the user prefers reduced motion we skip the animation and close immediately.
+  private startCloseDialog() {
+    const el = this.shadowRoot?.querySelector<HTMLElement>('.dialog');
+    const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    if (!el || reducedMotion) {
+      this.dialogOpen = false;
+      return;
+    }
+    this.closeAbort = new AbortController();
+    el.classList.add('closing');
+    el.addEventListener(
+      'animationend',
+      () => {
+        this.dialogOpen = false;
+      },
+      {
+        once: true,
+        signal: this.closeAbort.signal,
+      },
+    );
+  }
+
+  // Capture the latest pointer coords and schedule one rAF per display frame.
+  // Pointer events can fire far faster than the display refreshes (up to 1000Hz on
+  // gaming mice), so we only store the coords here and let applyDragFrame do the
+  // actual work. If a frame is already scheduled we just overwrite the coords —
+  // the pending frame will pick up the freshest values when it runs.
+  private onDocMouseMove = (e: MouseEvent) => {
+    if (!this.dragging) return;
+    this.latestMouseX = e.clientX;
+    this.latestMouseY = e.clientY;
+    if (this.rafHandle === undefined) {
+      this.rafHandle = requestAnimationFrame(this.applyDragFrame);
+    }
+  };
+
+  // Runs once per display frame during a drag. Writes the new position directly to
+  // the element's style.translate rather than updating FAST observables, which keeps
+  // the compositor thread doing the work instead of triggering FAST's reactivity
+  // pipeline on every frame. This means the element's visual position is temporarily
+  // ahead of the observables — they are only synced back on mouseup (see onDocMouseUp).
+  // Note: style.translate is an independent CSS property and does not conflict with
+  // the transform used for the bubble's hover scale or the dialog's open animation.
+  private applyDragFrame = () => {
+    this.rafHandle = undefined;
+    const dx = this.latestMouseX - this.startMouseX;
+    const dy = this.latestMouseY - this.startMouseY;
+    if (Math.abs(dx) > DRAG_THRESHOLD || Math.abs(dy) > DRAG_THRESHOLD) this.hasDragged = true;
+    if (this.dragTarget === 'bubble') {
+      const left = Math.max(
+        0,
+        Math.min(window.innerWidth - BUBBLE_DRAG_MARGIN, this.startElemLeft + dx),
+      );
+      const top = Math.max(
+        0,
+        Math.min(window.innerHeight - BUBBLE_DRAG_MARGIN, this.startElemTop + dy),
+      );
+      const el = this.shadowRoot?.querySelector<HTMLElement>('.bubble');
+      if (el) el.style.translate = `${left}px ${top}px`;
+    } else if (this.dragTarget === 'dialog') {
+      const left = Math.max(
+        0,
+        Math.min(window.innerWidth - DIALOG_DEFAULT_WIDTH, this.startElemLeft + dx),
+      );
+      const top = Math.max(0, Math.min(window.innerHeight - 100, this.startElemTop + dy));
+      const el = this.shadowRoot?.querySelector<HTMLElement>('.dialog');
+      if (el) el.style.translate = `${left}px ${top}px`;
+    }
+  };
+
+  // Commits the final drag position back to the FAST observables, bringing them back
+  // in sync with what the user sees. This triggers a single FAST re-render which writes
+  // the same value already on the element — no visible jump. Any pending rAF is
+  // cancelled first; its work is redundant since we recompute from latestMouseX/Y here.
+  private onDocMouseUp = () => {
+    if (this.rafHandle !== undefined) {
+      cancelAnimationFrame(this.rafHandle);
+      this.rafHandle = undefined;
+    }
+    if (this.dragging) {
+      const dx = this.latestMouseX - this.startMouseX;
+      const dy = this.latestMouseY - this.startMouseY;
+      if (this.dragTarget === 'bubble') {
+        this.bubbleLeft = Math.max(
+          0,
+          Math.min(window.innerWidth - BUBBLE_DRAG_MARGIN, this.startElemLeft + dx),
+        );
+        this.bubbleTop = Math.max(
+          0,
+          Math.min(window.innerHeight - BUBBLE_DRAG_MARGIN, this.startElemTop + dy),
+        );
+        if (!this.hasDragged) {
+          if (this.dialogOpen) {
+            this.startCloseDialog();
+          } else {
+            this.dialogLeft = Math.max(
+              VIEWPORT_EDGE_MARGIN,
+              this.bubbleLeft - DIALOG_BUBBLE_HORIZONTAL_OFFSET,
+            );
+            this.dialogTop = Math.max(
+              VIEWPORT_EDGE_MARGIN,
+              this.bubbleTop - DIALOG_OPEN_TOP_OFFSET,
+            );
+            this.dialogOpen = true;
+          }
+        }
+      } else if (this.dragTarget === 'dialog') {
+        this.dialogLeft = Math.max(
+          0,
+          Math.min(window.innerWidth - DIALOG_DEFAULT_WIDTH, this.startElemLeft + dx),
+        );
+        this.dialogTop = Math.max(0, Math.min(window.innerHeight - 100, this.startElemTop + dy));
+      }
+    }
+    this.dragging = false;
+    this.dragTarget = null;
+  };
+
+  onPopout() {
+    this.startCloseDialog();
+  }
+
+  onCloseDialog() {
+    // Snap the bubble orb to the bottom-right of wherever the dialog currently is,
+    // so it reappears near where the user last positioned the window.
+    this.bubbleLeft = Math.max(
+      0,
+      Math.min(
+        window.innerWidth - BUBBLE_DRAG_MARGIN,
+        this.dialogLeft + DIALOG_BUBBLE_HORIZONTAL_OFFSET,
+      ),
+    );
+    this.bubbleTop = Math.max(
+      0,
+      Math.min(window.innerHeight - BUBBLE_DRAG_MARGIN, this.dialogTop + BUBBLE_SNAP_BOTTOM_OFFSET),
+    );
+    this.startCloseDialog();
+  }
+
+  get tooltipStyle(): string {
+    const tooltipWidth = this.tooltipMeasuredWidth || TOOLTIP_FALLBACK_WIDTH;
+    const bubbleWidth = 62; // Fixed in CSS
+    const margin = 8;
+    const naturalLeft = (bubbleWidth - tooltipWidth) / 2;
+    const vpLeft = this.bubbleLeft + naturalLeft;
+    const vpRight = vpLeft + tooltipWidth;
+    let shift = 0;
+    if (vpLeft < margin) shift = margin - vpLeft;
+    else if (vpRight > window.innerWidth - margin) shift = window.innerWidth - margin - vpRight;
+    const tooltipLeft = naturalLeft + shift;
+    const arrowLeft = bubbleWidth / 2 - tooltipLeft;
+    return `left: ${tooltipLeft}px; --arrow-left: ${arrowLeft}px`;
+  }
+}

package/src/components/chat-bubble/index.ts

@@ -0,0 +1 @@
+export * from './chat-bubble';

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

@@ -0,0 +1,254 @@
+import type {
+  AIProvider,
+  ChatAttachment,
+  ChatMessage,
+  ChatRequestOptions,
+  ChatToolDefinition,
+  ChatToolHandlers,
+} from '@genesislcap/foundation-ai';
+import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
+import { logger } from '../../utils/logger';
+
+const MAX_TOOL_ITERATIONS = 10;
+const MAX_MALFORMED_RETRIES = 2;
+
+/**
+ * Event emitted when the chat history is updated (new message appended).
+ *
+ * @beta
+ */
+export type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
+
+/**
+ * Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.
+ * Owned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.
+ *
+ * Dispatches `'history-updated'` events on itself so the owning element can observe changes.
+ *
+ * @beta
+ */
+export class ChatDriver extends EventTarget {
+  private history: ChatMessage[] = [];
+  private busy = false;
+  private pendingInteractions = new Map<
+    string,
+    { resolve: (value: any) => void; reject: (reason?: any) => void }
+  >();
+
+  constructor(
+    private readonly aiProvider: AIProvider,
+    private readonly toolHandlers: ChatToolHandlers = {},
+    private readonly toolDefinitions: ChatToolDefinition[] = [],
+    private readonly systemPrompt?: string,
+  ) {
+    super();
+  }
+
+  getHistory(): ReadonlyArray<ChatMessage> {
+    return this.history;
+  }
+
+  isBusy(): boolean {
+    return this.busy;
+  }
+
+  /**
+   * Request a custom UI interaction. Emits a new message with the interaction.
+   * Tool handlers can call this to pause execution until the user completes the UI interaction.
+   *
+   * @param componentName - The custom element name to render.
+   * @param data - Data to pass to the component.
+   */
+  public async requestInteraction<T>(componentName: string, data: any): Promise<T> {
+    const interactionId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      this.pendingInteractions.set(interactionId, { resolve, reject });
+      this.appendToHistory({
+        role: 'assistant',
+        content: '',
+        interaction: { interactionId, componentName, data },
+      });
+    });
+  }
+
+  /**
+   * Resolve a pending interaction. The wrapper component calls this on completion.
+   * Marks the interaction message as resolved so it renders read-only on re-render.
+   */
+  public resolveInteraction(interactionId: string, result: any): void {
+    const interaction = this.pendingInteractions.get(interactionId);
+    if (interaction) {
+      // Mark the message as resolved before resolving the promise so the next
+      // history-updated event carries the updated flag.
+      const msg = this.history.find((m) => m.interaction?.interactionId === interactionId);
+      if (msg?.interaction) {
+        msg.interaction.resolved = true;
+        this.dispatchEvent(
+          new CustomEvent<ReadonlyArray<ChatMessage>>('history-updated', {
+            detail: this.history,
+          }),
+        );
+      }
+      interaction.resolve(result);
+      this.pendingInteractions.delete(interactionId);
+    } else {
+      logger.warn(`Interaction with ID ${interactionId} not found.`);
+    }
+  }
+
+  /**
+   * Seeds the driver with a prior conversation history so a new component instance
+   * can continue an existing conversation. Call this before the first user message.
+   */
+  public loadHistory(messages: ChatMessage[]): void {
+    this.history = [...messages];
+  }
+
+  async sendMessage(userInput: string, attachments?: ChatAttachment[]): Promise<void> {
+    if (this.busy || (!userInput.trim() && !attachments?.length)) return;
+    if (!this.aiProvider.chat) {
+      logger.warn('ChatDriver: AIProvider does not implement chat()');
+      return;
+    }
+
+    this.busy = true;
+    this.appendToHistory({ role: 'user', content: userInput, attachments });
+
+    try {
+      await this.runToolLoop(userInput, attachments);
+    } catch (e) {
+      logger.error('ChatDriver error:', e);
+      this.appendToHistory({ role: 'assistant', content: 'Sorry, something went wrong.' });
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  private async runToolLoop(userInput: string, attachments?: ChatAttachment[]): Promise<void> {
+    const baseOptions: ChatRequestOptions = {
+      systemPrompt: this.systemPrompt,
+      tools: this.toolDefinitions.length ? this.toolDefinitions : undefined,
+    };
+
+    // History has the user message at the end — pass everything before it as history,
+    // and the user input as the userMessage argument.
+    let currentInput = userInput;
+    let currentAttachments: ChatAttachment[] | undefined = attachments;
+    let iterations = 0;
+    let malformedAttempts = 0;
+
+    while (iterations < MAX_TOOL_ITERATIONS) {
+      iterations += 1;
+
+      // On the first iteration, the last item in history is the user message which is
+      // passed separately as currentInput — exclude it. On subsequent iterations, the
+      // full history (including tool results) should be sent and currentInput is empty.
+      const historyForCall = iterations === 1 ? this.history.slice(0, -1) : [...this.history];
+
+      // On malformed-call retries, augment the system prompt to steer the model
+      // away from generating Python-style batched function call syntax.
+      const systemPrompt =
+        malformedAttempts > 0
+          ? `${baseOptions.systemPrompt ?? ''}\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.`
+          : baseOptions.systemPrompt;
+
+      const options: ChatRequestOptions = {
+        ...baseOptions,
+        systemPrompt,
+        attachments: currentAttachments,
+      };
+
+      let response: ChatMessage;
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        response = await this.aiProvider.chat!(historyForCall, currentInput, options);
+      } catch (e) {
+        if (e instanceof MalformedFunctionCallError) {
+          malformedAttempts += 1;
+          if (malformedAttempts < MAX_MALFORMED_RETRIES) {
+            logger.warn(
+              `ChatDriver: MALFORMED_FUNCTION_CALL, retrying (${malformedAttempts}/${MAX_MALFORMED_RETRIES})`,
+            );
+            iterations -= 1; // don't consume an iteration budget slot for a failed attempt
+            continue;
+          }
+          logger.error('ChatDriver: MALFORMED_FUNCTION_CALL, max retries reached');
+          this.appendToHistory({
+            role: 'assistant',
+            content:
+              "I'm sorry, I wasn't able to complete that request. Please try rephrasing or breaking it into smaller steps.",
+          });
+          return;
+        }
+        throw e;
+      }
+
+      currentAttachments = undefined; // attachments only sent on first call
+
+      const isThinkingStep = response.content && response.toolCalls?.length;
+      const isEmptyResponse = !response.content?.trim() && !response.toolCalls?.length;
+
+      if (isEmptyResponse) {
+        // Do nothing, discard empty/whitespace-only responses
+      } else if (isThinkingStep) {
+        // Separate thinking message and tool call message
+        this.appendToHistory({ ...response, toolCalls: undefined, thinking: true });
+        this.appendToHistory({ ...response, content: '' });
+      } else {
+        this.appendToHistory(response);
+      }
+
+      if (!response.toolCalls?.length) {
+        // Terminal text response — done
+        break;
+      }
+
+      // Execute all tool calls for this iteration concurrently, then append results in order
+      // eslint-disable-next-line no-await-in-loop
+      const toolResults = await Promise.all(
+        response.toolCalls.map(async (tc) => {
+          const handler = this.toolHandlers[tc.name];
+          if (!handler) {
+            logger.warn(`ChatDriver: no handler registered for tool "${tc.name}"`);
+            return { toolCallId: tc.id, content: `Unknown tool: ${tc.name}` };
+          }
+          try {
+            const result = await handler(tc.args, {
+              requestInteraction: (componentName, data) =>
+                this.requestInteraction(componentName, data),
+            });
+            const content = typeof result === 'string' ? result : JSON.stringify(result);
+            return { toolCallId: tc.id, content };
+          } catch (e) {
+            logger.error(`ChatDriver tool "${tc.name}" failed:`, e);
+            return { toolCallId: tc.id, content: `Tool error: ${(e as Error).message}` };
+          }
+        }),
+      );
+
+      for (const result of toolResults) {
+        this.appendToHistory({
+          role: 'tool',
+          content: '',
+          toolResult: result,
+        });
+      }
+
+      // Next iteration sends an empty string — the tool results are in history
+      currentInput = '';
+    }
+
+    if (iterations >= MAX_TOOL_ITERATIONS) {
+      logger.warn('ChatDriver: reached max tool iterations, stopping');
+    }
+  }
+
+  private appendToHistory(message: ChatMessage): void {
+    this.history = [...this.history, message];
+    this.dispatchEvent(
+      new CustomEvent<ReadonlyArray<ChatMessage>>('history-updated', {
+        detail: this.history,
+      }),
+    );
+  }
+}

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

@@ -0,0 +1 @@
+export * from './chat-driver';

package/src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts

@@ -0,0 +1,7 @@
+import { css } from '@genesislcap/web-core';
+
+export const AiChatInteractionWrapperStyles = css`
+  :host {
+    display: block;
+  }
+`;

package/src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts

@@ -0,0 +1,6 @@
+import { html } from '@genesislcap/web-core';
+import type { AiChatInteractionWrapper } from './chat-interaction-wrapper';
+
+export const AiChatInteractionWrapperTemplate = html<AiChatInteractionWrapper>`
+  <div class="container" part="container"></div>
+`;