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

package/src/main/main.ts

@@ -0,0 +1,474 @@
+import { AIProvider } from '@genesislcap/foundation-ai';
+import type {
+  ChatAttachment,
+  ChatConfig,
+  ChatMessage,
+  ChatToolDefinition,
+  ChatToolHandlers,
+} from '@genesislcap/foundation-ai';
+import { createTypedBroadcastChannel } from '@genesislcap/foundation-broadcast-channel';
+import type { TypedBroadcastChannel } from '@genesislcap/foundation-broadcast-channel';
+import {
+  customElement,
+  html,
+  GenesisElement,
+  observable,
+  volatile,
+  attr,
+} from '@genesislcap/web-core';
+import { AI_ACTIVITY_CHANNEL_NAME } from '../channel/ai-activity-channel';
+import type { AiActivityEvents } from '../channel/ai-activity-channel';
+import type { AiAssistantSerializedState } from '../channel/ai-activity-channel';
+import { ChatDriver } from '../components/chat-driver/chat-driver';
+import { AiChatInteractionWrapper } from '../components/chat-interaction-wrapper/chat-interaction-wrapper';
+import { AiChatMarkdown } from '../components/chat-markdown/chat-markdown';
+import { AiHaloOverlay } from '../components/halo-overlay';
+import { logger } from '../utils/logger';
+import { styles } from './main.styles';
+import { FoundationAiAssistantTemplate } from './main.template';
+import { ALL_ANIMATIONS } from './main.types';
+import type { AiAssistantAnimation, AiAssistantState, PopoutMode } from './main.types';
+
+AiChatMarkdown;
+AiChatInteractionWrapper;
+AiHaloOverlay;
+
+/**
+ * Foundation AI Assistant component.
+ *
+ * @remarks
+ * Lazy-loaded via `configure()`. Inject an `AIProvider` and `AiAssistantConfig` through the DI
+ * container. The component creates a `ChatDriver` to manage the conversation loop.
+ *
+ * @beta
+ */
+@customElement({
+  name: 'foundation-ai-assistant',
+  template: html`
+    ${(x: FoundationAiAssistant) => FoundationAiAssistantTemplate(x.designSystemPrefix)}
+  `,
+  styles,
+})
+export class FoundationAiAssistant extends GenesisElement {
+  @AIProvider aiProvider!: AIProvider;
+
+  @observable designSystemPrefix: string = 'rapid';
+  @attr({ attribute: 'header-title' }) headerTitle?: string;
+  @attr({ attribute: 'channel-name' }) channelName: string = AI_ACTIVITY_CHANNEL_NAME;
+  @attr({ attribute: 'image-src' }) imageSrc?: string;
+  @attr() placeholder: string = 'Message assistant...';
+  /**
+   * Controls the pop-out button shown next to the settings cog.
+   * "expand" — in bubble, expands to layout panel (fires chat-popout).
+   * "collapse" — in layout panel, collapses back to bubble (fires chat-popin).
+   * Absent — no button (default standalone behaviour, no breaking change).
+   */
+  @attr({ attribute: 'popout-mode' }) popoutMode?: PopoutMode;
+  @observable systemPrompt?: string;
+  @observable toolDefinitions?: ChatToolDefinition[];
+  @observable toolHandlers?: ChatToolHandlers;
+  @observable chatConfig: ChatConfig = {};
+  @observable debugStateFactory?: () => unknown;
+
+  @observable messages: ChatMessage[] = [];
+  @observable state: AiAssistantState = 'idle';
+  @observable inputValue = '';
+  @observable attachments: ChatAttachment[] = [];
+  @observable attachmentErrors: string[] = [];
+
+  /** Current user-facing toggle state for tool call visibility. */
+  @observable showToolCalls = false;
+  /** Current user-facing toggle state for thinking step visibility. */
+  @observable showThinkingSteps = false;
+  /** Currently enabled animations. */
+  @observable enabledAnimations: AiAssistantAnimation[] = [];
+  /** Whether the loading spinner is currently visible. Controlled by the loading delay timer. */
+  @observable showLoadingIndicator = false;
+  /** Whether the settings panel is open. */
+  @observable settingsOpen = false;
+
+  private driver?: ChatDriver;
+  private loadingTimer: ReturnType<typeof setTimeout> | undefined;
+  private activityChannel?: TypedBroadcastChannel<AiActivityEvents>;
+  private haloStartPublished = false;
+
+  /**
+   * Whether the halo animation should be shown.
+   * True when the AI is actively computing (loading state, no pending interaction).
+   */
+  @observable showHalo: boolean = false;
+
+  private syncShowHalo() {
+    if (this.state !== 'loading') {
+      this.showHalo = false;
+      return;
+    }
+    const last = this.messages[this.messages.length - 1];
+    this.showHalo = !last?.interaction;
+  }
+
+  /** True when there is a pending (unresolved) interaction — disables the popout button. */
+  @volatile
+  get hasActivePendingInteraction(): boolean {
+    if (this.state !== 'loading') return false;
+    const last = this.messages[this.messages.length - 1];
+    return !!last?.interaction && !last.interaction.resolved;
+  }
+
+  showHaloChanged() {
+    if (!this.enabledAnimations?.includes('halo')) return;
+    if (!this.showHalo) {
+      this.activityChannel?.postMessage('halo-stop');
+      this.haloStartPublished = false;
+    }
+    // halo-start is published exclusively from messagesChanged when toolCalls arrive,
+    // so we never re-activate grids on non-toolCall transitions (e.g. tool results
+    // arriving after an interaction resolves).
+  }
+
+  private getActiveToolNames(): string[] {
+    for (let i = this.messages.length - 1; i >= 0; i -= 1) {
+      const msg = this.messages[i];
+      if (msg.toolCalls?.length) {
+        return msg.toolCalls.map((tc) => tc.name);
+      }
+    }
+    return [];
+  }
+
+  /**
+   * Messages filtered by the current toggle state.
+   * Tool-related messages (those with toolCalls or toolResult) are hidden when
+   * `showToolCalls` is false.
+   */
+  @volatile
+  get visibleMessages(): ChatMessage[] {
+    return this.messages.filter((m) => {
+      // Never show tool messages to the user
+      if (m.role === 'tool') {
+        return false;
+      }
+      // Filter thinking messages based on toggle
+      if (m.thinking && !this.showThinkingSteps) {
+        return false;
+      }
+      // Filter out empty assistant messages that might have slipped through
+      if (m.role === 'assistant' && !m.content?.trim() && !m.toolCalls?.length && !m.interaction) {
+        return false;
+      }
+      const isToolRelated = !!(m.toolCalls?.length || m.toolResult);
+      return !isToolRelated || this.showToolCalls;
+    });
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.activityChannel = createTypedBroadcastChannel<AiActivityEvents>(this.channelName);
+    const { showToolCalls, showThinkingSteps, animations } = this.chatConfig;
+    this.showToolCalls = showToolCalls === true;
+    this.showThinkingSteps = showThinkingSteps === true;
+    this.enabledAnimations =
+      (animations?.enabled as AiAssistantAnimation[]) ?? (animations ? [...ALL_ANIMATIONS] : []);
+
+    this.driver = new ChatDriver(
+      this.aiProvider,
+      this.toolHandlers ?? {},
+      this.toolDefinitions ?? [],
+      this.systemPrompt,
+    );
+    this.driver.addEventListener('history-updated', (e: Event) => {
+      this.messages = [...(e as CustomEvent<ChatMessage[]>).detail];
+    });
+
+    // When embedded in a bubble (expand mode), listen for chat-popin to restore state
+    // when the layout panel collapses back.
+    if (this.popoutMode === 'expand') {
+      this.activityChannel.addEventListener('message', this.onChannelMessage);
+    }
+
+    logger.debug('FoundationAiAssistant connected');
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.stopLoadingTimer();
+    this.state = 'idle';
+    this.activityChannel?.removeEventListener('message', this.onChannelMessage);
+    this.activityChannel?.close();
+    this.activityChannel = undefined;
+    this.driver = undefined;
+  }
+
+  private onChannelMessage = (event: MessageEvent) => {
+    if (event.data?.type === 'chat-popin' && event.data.detail?.state) {
+      this.applyState(event.data.detail.state as AiAssistantSerializedState);
+    }
+  };
+
+  stateChanged() {
+    this.syncShowHalo();
+  }
+
+  messagesChanged() {
+    // Reset the loading timer when an assistant message arrives mid-loop so each
+    // individual step gets a fresh window before the spinner appears.
+    // If the last message is a blocking interaction, stop the timer — the AI is
+    // waiting for the user, not computing.
+    if (this.state === 'loading') {
+      const last = this.messages[this.messages.length - 1];
+      if (last?.interaction) {
+        this.stopLoadingTimer();
+      } else if (last?.role === 'assistant') {
+        this.startLoadingTimer();
+      }
+    }
+    this.syncShowHalo();
+    // Publish halo-start whenever a new toolCalls message arrives.
+    // If we've already published one this turn, send halo-stop first so grids
+    // not relevant to the new tools begin deactivating (fix #2).
+    // Never publish with empty toolNames (fix #3).
+    if (this.showHalo && this.enabledAnimations?.includes('halo')) {
+      const last = this.messages[this.messages.length - 1];
+      if (last?.toolCalls?.length) {
+        const toolNames = this.getActiveToolNames();
+        if (toolNames.length) {
+          if (this.haloStartPublished) {
+            this.activityChannel?.postMessage('halo-stop');
+          }
+          this.activityChannel?.postMessage('halo-start', { toolNames });
+          this.haloStartPublished = true;
+        }
+      }
+    }
+    this.scrollToBottom();
+  }
+
+  showLoadingIndicatorChanged() {
+    // Scroll to bottom when the spinner appears so it is visible.
+    if (this.showLoadingIndicator) {
+      this.scrollToBottom();
+    }
+  }
+
+  // Double rAF: first frame lets the framework flush the DOM update,
+  // second frame reads the correct scrollHeight after layout.
+  private scrollToBottom() {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        const el = this.shadowRoot?.querySelector('.messages');
+        if (el) el.scrollTop = el.scrollHeight;
+      });
+    });
+  }
+
+  private static readonly DEFAULT_LOADING_DELAY_S = 5;
+  private static readonly MS_PER_SECOND = 1000;
+
+  private startLoadingTimer() {
+    this.clearLoadingTimer();
+    const delay = this.chatConfig.loadingDelay ?? FoundationAiAssistant.DEFAULT_LOADING_DELAY_S;
+    if (delay === 0) {
+      this.showLoadingIndicator = true;
+    } else {
+      this.loadingTimer = setTimeout(() => {
+        this.showLoadingIndicator = true;
+      }, delay * FoundationAiAssistant.MS_PER_SECOND);
+    }
+  }
+
+  private clearLoadingTimer() {
+    if (this.loadingTimer !== undefined) {
+      clearTimeout(this.loadingTimer);
+      this.loadingTimer = undefined;
+    }
+  }
+
+  private stopLoadingTimer() {
+    this.clearLoadingTimer();
+    this.showLoadingIndicator = false;
+  }
+
+  /** Called when the user clicks the popout button. */
+  handlePopout(): void {
+    if (this.popoutMode === 'expand') {
+      this.activityChannel?.postMessage('chat-popout', { state: this.serializeState() });
+    } else if (this.popoutMode === 'collapse') {
+      this.activityChannel?.postMessage('chat-popin', { state: this.serializeState() });
+    }
+  }
+
+  /** Applies a serialized state snapshot to this live instance (used on collapse path). */
+  applyState(state: AiAssistantSerializedState): void {
+    this.messages = [...state.messages];
+    this.showToolCalls = state.showToolCalls;
+    this.showThinkingSteps = state.showThinkingSteps;
+    this.enabledAnimations = [...state.enabledAnimations];
+    this.driver?.loadHistory(state.messages);
+  }
+
+  private serializeState(): AiAssistantSerializedState {
+    return {
+      messages: [...this.messages],
+      showToolCalls: this.showToolCalls,
+      showThinkingSteps: this.showThinkingSteps,
+      enabledAnimations: [...this.enabledAnimations],
+    };
+  }
+
+  toggleSettings() {
+    this.settingsOpen = !this.settingsOpen;
+  }
+
+  toggleShowToolCalls() {
+    this.showToolCalls = !this.showToolCalls;
+  }
+
+  toggleShowThinkingSteps() {
+    this.showThinkingSteps = !this.showThinkingSteps;
+  }
+
+  setEnabledAnimations(animations: AiAssistantAnimation[]) {
+    this.enabledAnimations = animations;
+  }
+
+  downloadHistory() {
+    const timestamp = new Date().toISOString().replace(/:/g, '-');
+    const agentName = (this.headerTitle ?? 'chat').toLowerCase().replace(/\s+/g, '-');
+    const payload = {
+      messages: this.messages,
+      debug: this.debugStateFactory?.(),
+    };
+    const blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `${agentName}-${timestamp}.json`;
+    a.click();
+    URL.revokeObjectURL(url);
+  }
+
+  triggerFileInput(): void {
+    this.shadowRoot?.querySelector<HTMLInputElement>('.file-input')?.click();
+  }
+
+  handleFileSelect(e: Event): void {
+    void this.loadSelectedFiles(e);
+  }
+
+  removeAttachment(attachment: ChatAttachment): void {
+    this.attachments = this.attachments.filter((a) => a !== attachment);
+  }
+
+  removeAttachmentError(message: string): void {
+    const idx = this.attachmentErrors.indexOf(message);
+    if (idx !== -1) {
+      this.attachmentErrors = [
+        ...this.attachmentErrors.slice(0, idx),
+        ...this.attachmentErrors.slice(idx + 1),
+      ];
+    }
+  }
+
+  private isAcceptedFile(file: File): boolean {
+    const accepted = this.chatConfig.acceptedFiles;
+    if (!accepted) return false;
+
+    const acceptedList = accepted.split(',').map((s) => s.trim().toLowerCase());
+    const ext = `.${file.name.split('.').pop()?.toLowerCase() ?? ''}`;
+
+    return acceptedList.some(
+      (a) =>
+        a === ext ||
+        a === file.type ||
+        (a.endsWith('/*') && file.type.startsWith(a.replace('/*', '/'))),
+    );
+  }
+
+  private readFileAsText(file: File): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => resolve(reader.result as string);
+      reader.onerror = () => reject(new Error(`Failed to read file: ${file.name}`));
+      reader.readAsText(file);
+    });
+  }
+
+  private async loadSelectedFiles(e: Event): Promise<void> {
+    const input = e.target as HTMLInputElement;
+    const files = Array.from(input.files ?? []);
+    input.value = '';
+
+    type FileResult = { ok: true; attachment: ChatAttachment } | { ok: false; message: string };
+    const results = await Promise.all(
+      files.map(async (file): Promise<FileResult> => {
+        if (!this.isAcceptedFile(file)) {
+          return { ok: false, message: `"${file.name}" is not an accepted file type.` };
+        }
+        try {
+          const content = await this.readFileAsText(file);
+          return {
+            ok: true,
+            attachment: { name: file.name, content, mimeType: file.type || 'text/plain' },
+          };
+        } catch (readError) {
+          logger.error('Failed to read file:', readError);
+          return { ok: false, message: `Failed to read "${file.name}".` };
+        }
+      }),
+    );
+
+    const newAttachments = results
+      .filter((r): r is Extract<FileResult, { ok: true }> => r.ok)
+      .map((r) => r.attachment);
+    const newErrors = results
+      .filter((r): r is Extract<FileResult, { ok: false }> => !r.ok)
+      .map((r) => r.message);
+
+    if (newAttachments.length) this.attachments = [...this.attachments, ...newAttachments];
+    if (newErrors.length) this.attachmentErrors = [...this.attachmentErrors, ...newErrors];
+  }
+
+  handleSendClick() {
+    this.send();
+  }
+
+  private async send() {
+    const input = this.inputValue.trim();
+    if ((!input && !this.attachments.length) || this.state === 'loading') return;
+    const pendingAttachments = this.attachments.length ? [...this.attachments] : undefined;
+    this.inputValue = '';
+    this.attachments = [];
+    this.attachmentErrors = [];
+    this.state = 'loading';
+    this.startLoadingTimer();
+    const displayInput = pendingAttachments?.length
+      ? `${input}\n\n*Attached: ${pendingAttachments.map((a) => a.name).join(', ')}*`
+      : input;
+    try {
+      await this.driver?.sendMessage(displayInput, pendingAttachments);
+    } finally {
+      this.stopLoadingTimer();
+      this.state = 'idle';
+    }
+  }
+
+  onChatHeaderMouseDown(e: MouseEvent) {
+    if (this.popoutMode !== 'expand') return;
+    e.preventDefault();
+    this.dispatchEvent(
+      new CustomEvent('chat-header-mousedown', {
+        bubbles: true,
+        composed: true,
+        detail: { clientX: e.clientX, clientY: e.clientY },
+      }),
+    );
+  }
+
+  handleInteractionCompleted(e: Event) {
+    const detail = (e as CustomEvent).detail;
+    if (detail && detail.interactionId) {
+      this.startLoadingTimer();
+      this.driver?.resolveInteraction(detail.interactionId, detail);
+    }
+  }
+}

package/src/main/main.types.ts

@@ -0,0 +1,58 @@
+/**
+ * State of the AI assistant component.
+ *
+ * @beta
+ */
+export type AiAssistantState = 'idle' | 'loading' | 'error';
+
+/**
+ * Controls the pop-out button shown in the assistant header.
+ * - `"expand"` — assistant is embedded in the bubble dialog; button expands it to a layout panel.
+ * - `"collapse"` — assistant is in a layout panel; button collapses it back to the bubble.
+ *
+ * @beta
+ */
+export type PopoutMode = 'expand' | 'collapse';
+
+/**
+ * Metadata describing a UI animation in the assistant.
+ *
+ * @beta
+ */
+export interface AiAssistantAnimationDef {
+  /** Display label shown in the settings multiselect. */
+  label: string;
+  /** Short description shown as a tooltip on the option. */
+  tooltip: string;
+}
+
+/**
+ * Registry of all available animations with their display metadata.
+ * Adding an entry here automatically extends the {@link AiAssistantAnimation} type.
+ *
+ * @beta
+ */
+export const ANIMATION_DEFS = {
+  loading: {
+    label: 'Loading indicator',
+    tooltip: 'Shows a pulsing animation while the assistant is generating a response.',
+  },
+  halo: {
+    label: 'Halo',
+    tooltip: 'Displays a glowing halo around the assistant avatar while a response is streaming.',
+  },
+} satisfies Record<string, AiAssistantAnimationDef>;
+
+/**
+ * Union of all available animation names, derived from {@link ANIMATION_DEFS}.
+ *
+ * @beta
+ */
+export type AiAssistantAnimation = keyof typeof ANIMATION_DEFS;
+
+/**
+ * All available animation names, derived from the registry.
+ *
+ * @internal
+ */
+export const ALL_ANIMATIONS = Object.keys(ANIMATION_DEFS) as AiAssistantAnimation[];

package/src/styles/index.ts

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