@artooi/ag-ui-web-component 0.5.0 → 0.7.0

package/src/core/agui_client.ts

@@ -1,6 +1,7 @@
 import { type AbstractAgent, type AgentSubscriber, randomUUID } from "@ag-ui/client";
 import type { Context, Message, Tool } from "@ag-ui/core";
 import { MAX_TOOL_ROUNDS } from "../constants.js";
+import type { AttachmentRef } from "./attachment.js";
 
 /** A tool call surfaced to the host by {@link AgUiClient}. */
 export interface AgUiToolCall {
@@ -92,6 +93,26 @@ export interface AgUiClientConfig extends AgUiRunInputs {
    * conversation in-memory only.
    */
   onPersist?: (messages: readonly Message[]) => void;
+  /**
+   * Error text surfaced to {@link AgUiClientHandlers.onError} when a run's
+   * stream closes without a terminal AG-UI event (`RUN_FINISHED`/`RUN_ERROR`) —
+   * a dropped connection. Defaults to `"Connection lost"`; the host passes its
+   * localized string.
+   */
+  connectionLostMessage?: string;
+}
+
+/**
+ * Raised when a run's stream closes cleanly at the transport level but never
+ * emits a terminal AG-UI event, so the run neither finished nor errored. Routed
+ * to {@link AgUiClientHandlers.onError} (it is not an abort), turning a silent
+ * "stuck pending" into a visible "connection lost".
+ */
+export class ConnectionLostError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConnectionLostError";
+  }
 }
 
 /**
@@ -108,6 +129,7 @@ export class AgUiClient {
   readonly #getContext: () => Context[];
   readonly #executeTool: ExecuteTool | null;
   readonly #onPersist: (messages: readonly Message[]) => void;
+  readonly #connectionLostMessage: string;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
   // a cancel between frontend-tool rounds doesn't start another round.
   #cancelled = false;
@@ -119,6 +141,7 @@ export class AgUiClient {
     this.#getContext = config.getContext ?? (() => []);
     this.#executeTool = config.executeTool ?? null;
     this.#onPersist = config.onPersist ?? (() => {});
+    this.#connectionLostMessage = config.connectionLostMessage ?? "Connection lost";
   }
 
   /** Whether a run is currently in flight. */
@@ -137,9 +160,21 @@ export class AgUiClient {
    * When the agent calls frontend tools, this executes them and re-runs the
    * agent with the results, looping until the agent stops calling frontend
    * tools (bounded by {@link MAX_TOOL_ROUNDS}).
+   *
+   * `attachments` ride on the user message as a non-standard field so the
+   * default client store round-trips them for history replay; the agent learns
+   * the ids from the run context (the server's strict validation ignores the
+   * unknown message field), then reads bytes via the `read_attachment` tool.
    */
-  async send(content: string): Promise<void> {
-    this.#agent.addMessage({ id: randomUUID(), role: "user", content });
+  async send(content: string, attachments: readonly AttachmentRef[] = []): Promise<void> {
+    // Cast at the AG-UI boundary: `attachments` is a web-component augmentation
+    // the strict `Message` union doesn't declare, but `addMessage` /
+    // `structuredClone` preserve it verbatim.
+    const message = { id: randomUUID(), role: "user", content } as Message;
+    if (attachments.length > 0) {
+      (message as { attachments?: readonly AttachmentRef[] }).attachments = attachments;
+    }
+    this.#agent.addMessage(message);
     this.#onPersist(this.#agent.messages);
     await this.#run();
   }
@@ -207,9 +242,10 @@ export class AgUiClient {
         return;
       }
       const pending: AgUiToolCall[] = [];
+      const runState = { terminal: false };
       await this.#agent.runAgent(
         { tools: this.#getTools(), context: this.#getContext() },
-        this.#buildSubscriber(pending),
+        this.#buildSubscriber(pending, runState),
       );
       this.#onPersist(this.#agent.messages);
       // Cancelled mid-stream: the user said stop — don't execute the tool
@@ -217,6 +253,12 @@ export class AgUiClient {
       if (this.#cancelled) {
         return;
       }
+      // The stream resolved without RUN_FINISHED / RUN_ERROR: the transport
+      // dropped mid-run. Surface it as an error so the UI doesn't rest silently
+      // with a stuck pending indicator (caught by #run → onError).
+      if (!runState.terminal) {
+        throw new ConnectionLostError(this.#connectionLostMessage);
+      }
       if (this.#executeTool === null || pending.length === 0) {
         return;
       }
@@ -246,7 +288,7 @@ export class AgUiClient {
     }
   }
 
-  #buildSubscriber(pending: AgUiToolCall[]): AgentSubscriber {
+  #buildSubscriber(pending: AgUiToolCall[], runState: { terminal: boolean }): AgentSubscriber {
     const h = this.#handlers;
     return {
       onRunInitialized() {
@@ -271,9 +313,11 @@ export class AgUiClient {
         h.onToolResult(event.toolCallId, event.content);
       },
       onRunErrorEvent({ event }) {
+        runState.terminal = true;
         h.onError(event.message);
       },
       onRunFinalized() {
+        runState.terminal = true;
         h.onRunEnd();
       },
     };

package/src/core/attachment.ts

@@ -0,0 +1,39 @@
+import type { Message } from "@ag-ui/core";
+
+/**
+ * A durable, lightweight reference to one uploaded file — what an upload
+ * returns and what rides on a sent message, never the bytes.
+ *
+ * Mirrors django-ag-ui's `AttachmentRef`: a file uploads out-of-band to the
+ * attachments endpoint, the server hands back this ref, and the agent reads the
+ * actual content server-side via the `read_attachment` tool. Keeping the AG-UI
+ * message stream free of base64 mirrors how the tool catalog keeps schemas off
+ * the wire.
+ */
+export interface AttachmentRef {
+  /** Opaque, owner-scoped handle the server resolves back to bytes. */
+  readonly id: string;
+  /** Original filename, for display on the chip. */
+  readonly name: string;
+  /** Declared content type (a hint — the server is authoritative). */
+  readonly mime: string;
+  /** Size in bytes. */
+  readonly size: number;
+  /** Optional direct fetch URL (the owner-checked download endpoint). */
+  readonly url?: string;
+}
+
+/**
+ * The attachment refs a user message carries.
+ *
+ * Refs are stored on the user message as a non-standard `attachments` field: a
+ * web-component augmentation that the default client store round-trips and
+ * `@ag-ui/client` preserves through `addMessage` / `structuredClone`, so a
+ * restored conversation re-renders its attachment chips. The server's strict
+ * `RunAgentInput` validation ignores the unknown field — the model learns the
+ * ids from the run context manifest instead.
+ */
+export function messageAttachments(message: Message): readonly AttachmentRef[] {
+  const refs = (message as { attachments?: unknown }).attachments;
+  return Array.isArray(refs) ? (refs as readonly AttachmentRef[]) : [];
+}

package/src/core/upload_attachment.ts

@@ -0,0 +1,113 @@
+import type { AttachmentRef } from "./attachment.js";
+
+/**
+ * The composer's upload contract: take a `File`, report `0..1` progress, and
+ * resolve to a durable {@link AttachmentRef}. The built-in handler is
+ * {@link uploadAttachment} (multipart POST); a host swaps in its own — e.g. a
+ * `tus-js-client` or direct-to-S3 adapter — via `AgUiChat.uploadHandler`,
+ * **without** touching the tray, the chips, or the AG-UI wire (refs are
+ * transport-agnostic).
+ */
+export type UploadHandler = (
+  file: File,
+  onProgress: (fraction: number) => void,
+) => Promise<AttachmentRef>;
+
+/** Options for {@link uploadAttachment}. */
+export interface UploadOptions {
+  /** The attachments endpoint (`data-attachments-url`). */
+  readonly url: string;
+  /** Extra HTTP headers (CSRF / auth), read fresh per upload. */
+  readonly headers?: Record<string, string>;
+  /** Progress callback, `0..1`, fired as the body uploads. */
+  readonly onProgress?: (fraction: number) => void;
+  /** Abort signal to cancel the in-flight upload. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Upload one file to the attachments endpoint and resolve to its durable
+ * {@link AttachmentRef}.
+ *
+ * Uses `XMLHttpRequest` (not `fetch`) for real upload-progress events: the file
+ * is sent as multipart under the `file` field, with the element's `headers` so
+ * CSRF / auth ride along exactly like the skills/tools fetches. A non-2xx
+ * response or a network/abort error rejects, so the tray can show an error chip.
+ */
+export function uploadAttachment(file: File, options: UploadOptions): Promise<AttachmentRef> {
+  return new Promise<AttachmentRef>((resolve, reject) => {
+    const form = new FormData();
+    form.append("file", file);
+
+    const xhr = new XMLHttpRequest();
+    xhr.open("POST", options.url);
+    for (const [key, value] of Object.entries(options.headers ?? {})) {
+      xhr.setRequestHeader(key, value);
+    }
+
+    const onProgress = options.onProgress;
+    if (onProgress !== undefined) {
+      xhr.upload.addEventListener("progress", (event) => {
+        if (event.lengthComputable) {
+          onProgress(event.total === 0 ? 0 : event.loaded / event.total);
+        }
+      });
+    }
+
+    xhr.addEventListener("load", () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        try {
+          resolve(parseRef(JSON.parse(xhr.responseText)));
+        } catch {
+          reject(new Error("upload returned an unreadable response"));
+        }
+      } else {
+        reject(new Error(errorMessage(xhr)));
+      }
+    });
+    xhr.addEventListener("error", () => reject(new Error("upload failed")));
+    xhr.addEventListener("abort", () => reject(new Error("upload cancelled")));
+
+    const signal = options.signal;
+    if (signal !== undefined) {
+      signal.addEventListener("abort", () => xhr.abort());
+    }
+
+    xhr.send(form);
+  });
+}
+
+/** Validate + narrow the server's `201` body into an {@link AttachmentRef}. */
+function parseRef(body: unknown): AttachmentRef {
+  if (typeof body !== "object" || body === null) {
+    throw new Error("not an object");
+  }
+  const o = body as Record<string, unknown>;
+  const id = o["id"];
+  const name = o["name"];
+  const mime = o["mime"];
+  const size = o["size"];
+  const url = o["url"];
+  if (
+    typeof id !== "string" ||
+    typeof name !== "string" ||
+    typeof mime !== "string" ||
+    typeof size !== "number"
+  ) {
+    throw new Error("missing fields");
+  }
+  return typeof url === "string" ? { id, name, mime, size, url } : { id, name, mime, size };
+}
+
+/** A human-readable message from a non-2xx upload response. */
+function errorMessage(xhr: XMLHttpRequest): string {
+  try {
+    const body = JSON.parse(xhr.responseText) as { error?: unknown };
+    if (typeof body.error === "string") {
+      return body.error;
+    }
+  } catch {
+    // Non-JSON error body — fall through to the status text.
+  }
+  return `upload failed (${xhr.status})`;
+}

package/src/index.ts

@@ -25,9 +25,11 @@ export {
   type AgUiClientHandlers,
   type AgUiRunInputs,
   type AgUiToolCall,
+  ConnectionLostError,
   type ExecuteTool,
   type ToolExecution,
 } from "./core/agui_client.js";
+export { type AttachmentRef, messageAttachments } from "./core/attachment.js";
 export {
   type ClientConversationStore,
   type NavigationCheckpoint,
@@ -41,6 +43,11 @@ export {
 } from "./core/create_http_agent.js";
 export { defineAgUiChat } from "./core/define_ag_ui_chat.js";
 export { RemoteConversationStore } from "./core/remote_conversation_store.js";
+export {
+  type UploadHandler,
+  type UploadOptions,
+  uploadAttachment,
+} from "./core/upload_attachment.js";
 export {
   type FlashOptions,
   focusWithFlash,
@@ -72,6 +79,11 @@ export type { Skill } from "./skills/skill.js";
 export { type ClientTool, ClientToolRegistry } from "./tools/client_tool_registry.js";
 export { isDestructive } from "./tools/is_destructive.js";
 export { isNavigates } from "./tools/is_navigates.js";
+export {
+  createPageActionTools,
+  PAGE_ACTIONS,
+  type ResolvePageTarget,
+} from "./tools/page_action_tools.js";
 export { createPageMapContext, type PageMap } from "./tools/page_map.js";
 export { parseToolCatalog, type ToolCatalogEntry } from "./tools/parse_tool_catalog.js";
 export {
@@ -94,4 +106,5 @@ export {
   type ToolCallStatus,
   type ToolDisplayMode,
 } from "./ui/tool_call_card.js";
+export { DEFAULT_UI_STRINGS, mergeUiStrings, type UiStrings } from "./ui/ui_strings.js";
 export { VERSION } from "./version.js";

package/src/tools/page_action_tools.ts

@@ -0,0 +1,130 @@
+import { X_SUMMARY_KEY } from "../constants.js";
+import { scrollIntoCenterView } from "../dom/animations.js";
+import type { ClientTool } from "./client_tool_registry.js";
+
+/**
+ * Resolve a page-action target string to a host-page element, or `null` when it
+ * matches nothing. The default (`document.querySelector`) treats the string as a
+ * CSS selector; a host with a page map overrides it to map its own element ids,
+ * the same way host packages wrap the DOM-driver primitives with environment-
+ * aware lookups.
+ */
+export type ResolvePageTarget = (target: string) => HTMLElement | null;
+
+/** The built-in page-action tool tokens, opted in via `data-page-actions`. */
+export const PAGE_ACTIONS = {
+  SCROLL: "scroll",
+  DRAG: "drag",
+} as const;
+
+/**
+ * The opt-in page-action tools selected by `enabled` (a set of
+ * {@link PAGE_ACTIONS} tokens), bound to a {@link ResolvePageTarget}.
+ *
+ * - `scroll_to` — scroll a target (`top` / `bottom` / a resolver target) into
+ *   view. Benign; no confirmation.
+ * - `drag_and_drop` — drag one element onto another, firing the standard HTML5
+ *   drag sequence so the host page's own drop handler reacts. Not stamped
+ *   destructive: a drag rearranges transient state and the durable change
+ *   happens at the page's explicit commit. A host whose page persists *on drop*
+ *   gates it with the element's `confirmPredicate`.
+ *
+ * Both report a clean, model-readable error when a target resolves to nothing,
+ * rather than throwing an opaque crash.
+ */
+export function createPageActionTools(
+  enabled: ReadonlySet<string>,
+  resolveTarget: ResolvePageTarget,
+): ClientTool[] {
+  const tools: ClientTool[] = [];
+  if (enabled.has(PAGE_ACTIONS.SCROLL)) {
+    tools.push(scrollTool(resolveTarget));
+  }
+  if (enabled.has(PAGE_ACTIONS.DRAG)) {
+    tools.push(dragTool(resolveTarget));
+  }
+  return tools;
+}
+
+function scrollTool(resolveTarget: ResolvePageTarget): ClientTool {
+  return {
+    name: "scroll_to",
+    description:
+      "Scroll a target into view. `target` is `top`, `bottom`, or a CSS " +
+      "selector / page-map element id. Read-only: it changes nothing on the page.",
+    parameters: {
+      type: "object",
+      properties: { target: { type: "string" } },
+      required: ["target"],
+      [X_SUMMARY_KEY]: "Scroll into view",
+    },
+    handler: (args) => {
+      const target = String(args["target"] ?? "");
+      if (target === "top" || target === "bottom") {
+        const top = target === "top" ? 0 : document.body.scrollHeight;
+        window.scrollTo({ top, behavior: "smooth" });
+        return { scrolled: true, target };
+      }
+      const element = resolveTarget(target);
+      if (element === null) {
+        throw new Error(`no element matching "${target}"`);
+      }
+      scrollIntoCenterView(element);
+      return { scrolled: true, target };
+    },
+  };
+}
+
+function dragTool(resolveTarget: ResolvePageTarget): ClientTool {
+  return {
+    name: "drag_and_drop",
+    description:
+      "Drag the `from` element onto the `to` element (CSS selectors or page-map " +
+      "element ids), firing the page's native drag-and-drop. Use for reordering " +
+      "sortable lists. The page decides what the drop commits.",
+    parameters: {
+      type: "object",
+      properties: { from: { type: "string" }, to: { type: "string" } },
+      required: ["from", "to"],
+      [X_SUMMARY_KEY]: "Drag and drop",
+    },
+    handler: (args) => {
+      const fromTarget = String(args["from"] ?? "");
+      const toTarget = String(args["to"] ?? "");
+      const from = resolveTarget(fromTarget);
+      if (from === null) {
+        throw new Error(`no element matching "${fromTarget}"`);
+      }
+      const to = resolveTarget(toTarget);
+      if (to === null) {
+        throw new Error(`no element matching "${toTarget}"`);
+      }
+      dispatchDragSequence(from, to);
+      return { dragged: true, from: fromTarget, to: toTarget };
+    },
+  };
+}
+
+/**
+ * Fire the standard HTML5 drag sequence — `dragstart` on the source, then
+ * `dragenter` / `dragover` / `drop` on the target, then `dragend` on the source —
+ * sharing one {@link DataTransfer}. Dispatched as typed, bubbling events (the
+ * `dataTransfer` is attached explicitly so a drop handler reads it in every
+ * environment).
+ */
+function dispatchDragSequence(from: HTMLElement, to: HTMLElement): void {
+  const dataTransfer = new DataTransfer();
+  fire(from, "dragstart", dataTransfer);
+  fire(to, "dragenter", dataTransfer);
+  fire(to, "dragover", dataTransfer);
+  fire(to, "drop", dataTransfer);
+  fire(from, "dragend", dataTransfer);
+}
+
+function fire(target: HTMLElement, type: string, dataTransfer: DataTransfer): void {
+  const event = new Event(type, { bubbles: true, cancelable: true }) as Event & {
+    dataTransfer: DataTransfer;
+  };
+  event.dataTransfer = dataTransfer;
+  target.dispatchEvent(event);
+}

package/src/ui/attachment_chips.ts

@@ -0,0 +1,68 @@
+import type { AttachmentRef } from "../core/attachment.js";
+
+/**
+ * Render the read-only attachment chips shown on a sent user message bubble
+ * (and on restored history) — one chip per ref with a type icon, the filename,
+ * and a human size. Static by design: no progress, no remove (that lives in the
+ * composer tray); a restored bubble re-renders these with no animation.
+ */
+export function renderAttachmentChips(refs: readonly AttachmentRef[]): HTMLDivElement {
+  const list = document.createElement("div");
+  list.className = "attachment-chips";
+  for (const ref of refs) {
+    list.appendChild(renderChip(ref));
+  }
+  return list;
+}
+
+function renderChip(ref: AttachmentRef): HTMLDivElement {
+  const chip = document.createElement("div");
+  chip.className = "attachment-chip attachment-chip--ready";
+
+  const icon = document.createElement("span");
+  icon.className = "attachment-chip-icon";
+  icon.textContent = iconFor(ref.mime);
+  icon.setAttribute("aria-hidden", "true");
+
+  const name = document.createElement("span");
+  name.className = "attachment-chip-name";
+  name.textContent = ref.name;
+  name.title = ref.name;
+
+  const size = document.createElement("span");
+  size.className = "attachment-chip-size";
+  size.textContent = formatBytes(ref.size);
+
+  chip.append(icon, name, size);
+  return chip;
+}
+
+/** A coarse type icon for a chip — image, document, or generic file. */
+export function iconFor(mime: string): string {
+  if (mime.startsWith("image/")) {
+    return "🖼";
+  }
+  if (mime === "application/pdf") {
+    return "📕";
+  }
+  if (mime.startsWith("text/")) {
+    return "📄";
+  }
+  return "📎";
+}
+
+/** A compact human-readable byte size (e.g. `1.2 MB`). */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const units = ["KB", "MB", "GB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  const rounded = value < 10 ? Math.round(value * 10) / 10 : Math.round(value);
+  return `${rounded} ${units[unit]}`;
+}