@iloveagents/foundry-web-ui 0.1.0

package/src/lib/ag-ui-adapter.ts

@@ -0,0 +1,362 @@
+/**
+ * AG-UI Adapter for assistant-ui.
+ *
+ * Thin shim around `@iloveagents/foundry-agent`'s `AGUIRunner`:
+ *   - converts assistant-ui `Message[]` → AG-UI `Message[]` on input,
+ *   - feeds the runner, drains its `RunnerEvent` stream,
+ *   - accumulates text + tool-call state,
+ *   - yields cumulative `ChatModelRunResult` snapshots (assistant-ui requires
+ *     each yield to carry the *complete* content array — never deltas).
+ *
+ * Wires the React-only stores that don't belong in `@iloveagents/foundry-agent`:
+ *   - `useAppStore` for context-item snapshot + lifecycle hooks
+ *   - `useDevStore` for dev-panel request/tool capture (driven by the
+ *     runner's `request-sent` event).
+ *
+ * @see https://docs.ag-ui.com/sdk/js/client/http-agent
+ * @see https://www.assistant-ui.com/docs/runtimes/custom/local
+ */
+
+import type {
+  ChatModelAdapter,
+  ChatModelRunOptions,
+  ChatModelRunResult,
+  TextMessagePart,
+  ToolCallMessagePart,
+} from "@assistant-ui/react";
+import type { Message as AGUIMessage } from "@ag-ui/core";
+import {
+  AGUIRunner,
+  clientToolRegistry,
+  streamingStatusStore,
+} from "@iloveagents/foundry-agent";
+import { tokenFetch } from "@iloveagents/foundry-agent/msal";
+import { useAppStore } from "./app-store.ts";
+import { useDevStore } from "./dev-store.ts";
+
+interface ToolCallSnapshot {
+  id: string;
+  name: string;
+  args: string;
+  result?: unknown;
+  isError?: boolean;
+}
+
+export class AGUIAdapterSDK implements ChatModelAdapter {
+  private readonly runner: AGUIRunner;
+
+  constructor(
+    url: string = "/api/agent",
+    options?: { threadId?: string; fetchFn?: typeof fetch },
+  ) {
+    this.runner = new AGUIRunner({
+      url,
+      threadId: options?.threadId,
+      fetchFn: options?.fetchFn ?? tokenFetch,
+    });
+  }
+
+  get threadId(): string {
+    return this.runner.threadId;
+  }
+
+  get state(): unknown {
+    return this.runner.state;
+  }
+
+  async *run({ messages, abortSignal }: ChatModelRunOptions): AsyncGenerator<ChatModelRunResult> {
+    const aguiMessages = convertMessagesToAGUI(messages);
+
+    // App-level lifecycle: mark thread active, snapshot context, consume
+    // ephemeral context off the last user message.
+    useAppStore.getState().markThreadActive();
+    const appState = useAppStore.getState().getAgentState();
+    const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
+    if (lastUserMsg) {
+      useAppStore.getState().consumeContextForMessage(lastUserMsg.id);
+    }
+
+    let currentText = "";
+    const toolCalls = new Map<string, ToolCallSnapshot>();
+    let runError: string | null = null;
+
+    /**
+     * Build a `ChatModelRunResult` from the accumulated state.
+     *
+     * Per assistant-ui v0.12 contract, every yield must carry the COMPLETE
+     * cumulative content array (not deltas). The runner drives multi-turn
+     * follow-ups internally; we yield `running` for every intermediate
+     * yield, then a single terminal `complete` after the runner's
+     * generator returns. assistant-ui leaves the message stuck in the
+     * loading state if the last yield's status is `running`.
+     */
+    const buildResult = (
+      statusOverride?: ChatModelRunResult["status"],
+    ): ChatModelRunResult => {
+      const content: (ToolCallMessagePart | TextMessagePart)[] = [];
+
+      for (const [id, tc] of toolCalls) {
+        let parsedArgs: unknown = {};
+        try {
+          parsedArgs = JSON.parse(tc.args || "{}");
+        } catch {
+          // Keep empty object for invalid JSON
+        }
+        content.push({
+          type: "tool-call",
+          toolCallId: id,
+          toolName: tc.name,
+          args: parsedArgs as ToolCallMessagePart["args"],
+          argsText: tc.args,
+          result: tc.result,
+          isError: tc.isError,
+        });
+      }
+
+      if (currentText) {
+        content.push({ type: "text", text: currentText });
+      }
+
+      const status: ChatModelRunResult["status"] = statusOverride ?? { type: "running" };
+
+      return {
+        content,
+        status,
+        metadata: {
+          custom: {
+            threadId: this.runner.threadId,
+            timestamp: Date.now(),
+            state: this.runner.state,
+          },
+        },
+      };
+    };
+
+    try {
+      for await (const event of this.runner.run({
+        messages: aguiMessages,
+        state: appState as unknown as Record<string, unknown>,
+        registry: clientToolRegistry.getState(),
+        abortSignal,
+      })) {
+        let shouldYield = false;
+
+        switch (event.type) {
+          case "request-sent":
+            if (import.meta.env.DEV) {
+              useDevStore.getState().captureRequest(event.input);
+            }
+            break;
+
+          case "turn-started":
+            currentText = "";
+            shouldYield = true;
+            break;
+
+          case "run-started":
+            // Per-turn signal — the runner may issue multiple turns for
+            // multi-turn tool follow-ups. Terminal completion is yielded
+            // post-loop, not on the per-turn run-finished.
+            break;
+
+          case "run-finished":
+            // Intermediate yield — keeps the message in the running state
+            // while the runner decides whether to re-issue.
+            shouldYield = true;
+            break;
+
+          case "run-error":
+            runError = event.message;
+            console.error("Run error:", event.message);
+            shouldYield = true;
+            break;
+
+          case "streaming-status":
+            streamingStatusStore.getState().setStreamingStatus(event.status);
+            break;
+
+          case "text-delta":
+            currentText += event.delta;
+            shouldYield = true;
+            break;
+
+          case "text-message-end":
+            shouldYield = true;
+            break;
+
+          case "tool-call-start":
+            toolCalls.set(event.id, { id: event.id, name: event.name, args: "" });
+            if (import.meta.env.DEV) {
+              useDevStore.getState().addToolCall({
+                id: event.id,
+                name: event.name,
+                args: "",
+                isClientSide: event.isClientSide,
+                timestamp: Date.now(),
+              });
+            }
+            shouldYield = true;
+            break;
+
+          case "tool-call-args": {
+            const tc = toolCalls.get(event.id);
+            if (tc) {
+              tc.args += event.delta;
+              shouldYield = true;
+            }
+            break;
+          }
+
+          case "tool-call-end": {
+            const tc = toolCalls.get(event.id);
+            if (tc) {
+              tc.args = event.args;
+              if (event.result !== undefined) tc.result = event.result;
+              if (event.isError !== undefined) tc.isError = event.isError;
+              if (import.meta.env.DEV) {
+                useDevStore.getState().updateToolCall(event.id, {
+                  args: tc.args,
+                  result: tc.result,
+                });
+              }
+              shouldYield = true;
+            }
+            break;
+          }
+
+          case "tool-call-result": {
+            const tc = toolCalls.get(event.id);
+            if (tc) {
+              tc.result = event.result;
+              tc.isError = event.isError;
+              if (import.meta.env.DEV) {
+                useDevStore.getState().updateToolCall(event.id, {
+                  result: tc.result,
+                });
+              }
+              shouldYield = true;
+            }
+            break;
+          }
+        }
+
+        if (shouldYield) {
+          const result = buildResult();
+          if ((result.content?.length ?? 0) > 0) {
+            yield result;
+          }
+        }
+      }
+
+      // Terminal yield — runner generator returned. assistant-ui leaves
+      // the message stuck in the loading state if the last yield's
+      // `status` is `running`, so we always emit a final `complete` once
+      // the runner is fully done (after every turn + every follow-up).
+      // `runError` is recorded above but not re-thrown: the terminal yield
+      // settles the message with reason=stop so the bubble unsticks; an
+      // unhandled throw would re-introduce the stuck-running bug.
+      void runError;
+      yield buildResult({ type: "complete", reason: "stop" });
+    } finally {
+      streamingStatusStore.getState().setStreamingStatus({ status: "idle" });
+    }
+  }
+}
+
+/**
+ * Convert assistant-ui's `Message[]` into AG-UI's wire format.
+ *
+ * Our Python backend doesn't keep server-side thread state, so prior turns'
+ * tool calls + results need to ride along on every request.
+ */
+function convertMessagesToAGUI(messages: ChatModelRunOptions["messages"]): AGUIMessage[] {
+  const out: AGUIMessage[] = [];
+
+  for (let idx = 0; idx < messages.length; idx++) {
+    const msg = messages[idx];
+    const id = msg.id || `msg-${idx}`;
+    const textContent = msg.content
+      .filter((c): c is Extract<typeof c, { type: "text" }> => c.type === "text")
+      .map((c) => c.text)
+      .join("\n");
+
+    if (msg.role === "system") {
+      out.push({ id, role: "system", content: textContent });
+      continue;
+    }
+
+    if (msg.role === "assistant") {
+      const toolCallParts = msg.content.filter(
+        (c): c is Extract<typeof c, { type: "tool-call" }> => c.type === "tool-call",
+      );
+
+      if (toolCallParts.length > 0) {
+        out.push({
+          id,
+          role: "assistant",
+          content: textContent || undefined,
+          toolCalls: toolCallParts.map((tc) => ({
+            id: tc.toolCallId,
+            type: "function" as const,
+            function: {
+              name: tc.toolName,
+              arguments: tc.argsText ?? JSON.stringify(tc.args ?? {}),
+            },
+          })),
+        });
+        for (const tc of toolCallParts) {
+          if (tc.result !== undefined) {
+            out.push({
+              id: `tool-result-${tc.toolCallId}`,
+              role: "tool",
+              toolCallId: tc.toolCallId,
+              content: typeof tc.result === "string" ? tc.result : JSON.stringify(tc.result),
+            });
+          }
+        }
+      } else {
+        out.push({ id, role: "assistant", content: textContent });
+      }
+      continue;
+    }
+
+    // User role: extract binary attachments if present
+    const parts: (
+      | { type: "text"; text: string }
+      | { type: "binary"; mimeType: string; data?: string; filename?: string }
+    )[] = [];
+    for (const c of msg.content) {
+      if (c.type === "text") {
+        parts.push({ type: "text", text: c.text });
+      }
+    }
+    if ("attachments" in msg && Array.isArray(msg.attachments)) {
+      for (const att of msg.attachments) {
+        if (!att.content) continue;
+        for (const part of att.content) {
+          if (part.type === "text") {
+            parts.push({ type: "text", text: part.text });
+          } else if (part.type === "file" && "data" in part) {
+            parts.push({
+              type: "binary",
+              mimeType: part.mimeType,
+              data: part.data as string,
+              filename: part.filename,
+            });
+          } else if (part.type === "image" && "image" in part) {
+            parts.push({
+              type: "binary",
+              mimeType: "image/*",
+              data: part.image as string,
+            });
+          }
+        }
+      }
+    }
+
+    const hasBinary = parts.some((p) => p.type === "binary");
+    out.push({ id, role: "user", content: hasBinary ? parts : textContent });
+  }
+
+  return out;
+}

package/src/lib/app-store.ts

@@ -0,0 +1,294 @@
+/**
+ * App Store — unified shared state for the AG-UI multi-page application.
+ *
+ * - Navigation context (synced from nav store via app-layout)
+ * - Persistent vs ephemeral context lifecycle
+ * - Shared UI state (selectedItemId, content, highlights)
+ * - Strict AG-UI state projection sent to the agent on every request
+ */
+
+import { create } from "zustand";
+
+export type ContextPersistence = "persistent" | "ephemeral";
+
+// --- Domain-agnostic context payloads ---
+
+export interface TextPayload {
+  kind: "text";
+  text: string;
+}
+
+export interface PagePayload {
+  kind: "page";
+  path: string;
+  label: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface ReferencePayload {
+  kind: "ref";
+  /** Domain decides: "block", "entity", "row", "cell", etc. */
+  refType: string;
+  /** Domain-specific ID: "entityId:blockId", "table:row", etc. */
+  refId: string;
+  /** Optional display text (~100 chars) */
+  preview?: string;
+  /** Domain-specific data the agent can use */
+  meta?: Record<string, unknown>;
+}
+
+export type ContextPayload = TextPayload | PagePayload | ReferencePayload;
+
+export type ContextItemType = "selection" | "page" | "ref" | "note";
+
+export interface ContextItem {
+  id: string;
+  type: ContextItemType;
+  label: string;
+  payload: ContextPayload;
+  sourcePage: string;
+  persistence: ContextPersistence;
+  createdAt: number;
+}
+
+export interface NavContext {
+  group: string | null;
+  groupDescription: string | null;
+  groupMeta: Record<string, unknown>;
+  label: string;
+  description: string | null;
+  meta: Record<string, unknown>;
+  /** Merged instructions from group + page (assembled by app-layout from hierarchy) */
+  contextInstructions: string | null;
+}
+
+export interface AgentStateProjection {
+  navigation: {
+    group: string | null;
+    groupDescription: string | null;
+    groupMeta: Record<string, unknown>;
+    page: string;
+    label: string;
+    description: string | null;
+    meta: Record<string, unknown>;
+    contextInstructions: string | null;
+  };
+  selectedItemId: string | null;
+  content: Record<string, unknown>;
+  highlights: string[];
+  /** Compact context items — text truncated, pages as paths, refs as IDs */
+  contextItems: Array<Record<string, unknown>>;
+}
+
+const MAX_ITEMS = 10;
+const MAX_LABEL_LENGTH = 500;
+
+const DEFAULT_NAV_CONTEXT: NavContext = {
+  group: null,
+  groupDescription: null,
+  groupMeta: {},
+  label: "Chat",
+  description: null,
+  meta: {},
+  contextInstructions: null,
+};
+
+interface AppState {
+  // Thread state
+  threadActive: boolean;
+  markThreadActive: () => void;
+
+  // Current page (set by router, used for ephemeral context clearing)
+  currentPage: string;
+  setCurrentPage: (page: string) => void;
+
+  // Navigation context (synced from nav store by app-layout)
+  navContext: NavContext;
+  setNavContext: (ctx: NavContext) => void;
+
+  // Shared UI state
+  selectedItemId: string | null;
+  setSelectedItemId: (id: string | null) => void;
+  content: Record<string, unknown>;
+  updateContentField: (key: string, value: unknown) => void;
+  clearContent: () => void;
+  highlights: string[];
+  addHighlight: (id: string) => void;
+  removeHighlight: (id: string) => void;
+  clearHighlights: () => void;
+
+  // Context items
+  contextItems: ContextItem[];
+  sentContext: Record<string, ContextItem[]>;
+  addContextItem: (item: Omit<ContextItem, "id" | "createdAt">) => void;
+  removeContextItem: (id: string) => void;
+  promoteContextItem: (id: string) => void;
+  clearAllContext: () => void;
+  consumeContextForMessage: (messageId: string) => ContextItem[];
+
+  // AG-UI state projection
+  getAgentState: () => AgentStateProjection;
+
+  // Full reset (new conversation)
+  resetAll: () => void;
+}
+
+export const useAppStore = create<AppState>((set, get) => ({
+  // Thread state
+  threadActive: false,
+  markThreadActive: () => set({ threadActive: true }),
+
+  // Current page
+  currentPage: "/chat",
+  setCurrentPage: (page) => {
+    const prev = get().currentPage;
+    if (prev === page) return;
+
+    // Clear ephemeral context on navigation
+    set({
+      currentPage: page,
+      contextItems: get().contextItems.filter((i) => i.persistence !== "ephemeral"),
+    });
+  },
+
+  // Navigation context
+  navContext: DEFAULT_NAV_CONTEXT,
+  setNavContext: (ctx) => set({ navContext: ctx }),
+
+  // Shared UI state
+  selectedItemId: null,
+  setSelectedItemId: (id) => set({ selectedItemId: id }),
+  content: {},
+  updateContentField: (key, value) => set({ content: { ...get().content, [key]: value } }),
+  clearContent: () => set({ content: {} }),
+  highlights: [],
+  addHighlight: (id) => {
+    const { highlights } = get();
+    if (!highlights.includes(id)) {
+      set({ highlights: [...highlights, id] });
+    }
+  },
+  removeHighlight: (id) => set({ highlights: get().highlights.filter((h) => h !== id) }),
+  clearHighlights: () => set({ highlights: [] }),
+
+  // Context items
+  contextItems: [],
+  sentContext: {},
+
+  addContextItem: (item) => {
+    const { contextItems } = get();
+
+    // Deduplicate by type-specific key
+    const isDuplicate = contextItems.some((existing) => {
+      if (item.type === "page" && existing.type === "page") {
+        const a = item.payload as PagePayload;
+        const b = existing.payload as PagePayload;
+        return a.path === b.path;
+      }
+      if (item.type === "ref" && existing.type === "ref") {
+        const a = item.payload as ReferencePayload;
+        const b = existing.payload as ReferencePayload;
+        return a.refId === b.refId;
+      }
+      // selection / note: dedup by label + sourcePage
+      return existing.label === item.label && existing.sourcePage === item.sourcePage;
+    });
+    if (isDuplicate) return;
+
+    if (contextItems.length >= MAX_ITEMS) return;
+
+    const label =
+      item.label.length > MAX_LABEL_LENGTH
+        ? item.label.slice(0, MAX_LABEL_LENGTH) + "..."
+        : item.label;
+
+    set({
+      contextItems: [
+        ...contextItems,
+        { ...item, label, id: crypto.randomUUID(), createdAt: Date.now() },
+      ],
+    });
+  },
+
+  removeContextItem: (id) => set({ contextItems: get().contextItems.filter((i) => i.id !== id) }),
+
+  promoteContextItem: (id) =>
+    set({
+      contextItems: get().contextItems.map((i) =>
+        i.id === id ? { ...i, persistence: "persistent" as const } : i,
+      ),
+    }),
+
+  clearAllContext: () => set({ contextItems: [], sentContext: {} }),
+
+  consumeContextForMessage: (messageId) => {
+    const { contextItems, sentContext } = get();
+    if (contextItems.length === 0) return [];
+
+    const snapshot = [...contextItems];
+
+    // Keep persistent, remove ephemeral
+    set({
+      contextItems: contextItems.filter((i) => i.persistence === "persistent"),
+      sentContext: { ...sentContext, [messageId]: snapshot },
+    });
+
+    return snapshot;
+  },
+
+  // AG-UI state projection
+  getAgentState: () => {
+    const s = get();
+    return {
+      navigation: {
+        group: s.navContext.group,
+        groupDescription: s.navContext.groupDescription,
+        groupMeta: s.navContext.groupMeta,
+        page: s.currentPage,
+        label: s.navContext.label,
+        description: s.navContext.description,
+        meta: s.navContext.meta,
+        contextInstructions: s.navContext.contextInstructions,
+      },
+      selectedItemId: s.selectedItemId,
+      content: s.content,
+      highlights: s.highlights,
+      contextItems: s.contextItems.map(({ type, label, payload, sourcePage }) => {
+        switch (payload.kind) {
+          case "text":
+            return {
+              type,
+              label: label.slice(0, 200),
+              text: payload.text.slice(0, 500),
+              sourcePage,
+            };
+          case "page":
+            return { type, label, path: payload.path, sourcePage };
+          case "ref":
+            return {
+              type,
+              refType: payload.refType,
+              refId: payload.refId,
+              preview: payload.preview?.slice(0, 100),
+              sourcePage,
+            };
+          default:
+            return { type, label, sourcePage };
+        }
+      }),
+    };
+  },
+
+  // Full reset
+  resetAll: () =>
+    set({
+      threadActive: false,
+      currentPage: "/chat",
+      navContext: DEFAULT_NAV_CONTEXT,
+      selectedItemId: null,
+      content: {},
+      highlights: [],
+      contextItems: [],
+      sentContext: {},
+    }),
+}));