@artooi/agents-web-components 0.0.0-stage → 0.1.0

package/src/core/create_http_agent.ts

@@ -0,0 +1,97 @@
+import { type AbstractAgent, HttpAgent } from "@ag-ui/client";
+import type { Message } from "@ag-ui/core";
+import { warnOnCrossOriginCredentials, withCredentials } from "./utils.js";
+
+/** Config for {@link createHttpAgent}. */
+export interface HttpAgentOptions {
+  endpoint: string;
+  headers?: Record<string, string>;
+  /**
+   * Cookie policy for the run request, as `fetch`'s own `credentials` mode.
+   * Unset leaves the browser default (`same-origin`), which sends no cookies
+   * to an agent endpoint on a different origin or subdomain. A
+   * cookie-authenticated cross-origin deployment needs `"include"` here plus a
+   * server answering with `Access-Control-Allow-Credentials: true` and a
+   * concrete origin.
+   */
+  credentials?: RequestCredentials;
+  /**
+   * Live header source, re-read on every request, overlaid on `headers`.
+   * `HttpAgent` bakes static `headers` in at construction and the element
+   * caches the agent for the whole conversation, so rotating credentials (CSRF,
+   * short-lived JWT) must come through here.
+   */
+  getHeaders?: () => Record<string, string>;
+  /** Stable conversation id, so the agent's runs share a thread. */
+  threadId?: string;
+  /** Rehydrated history to seed the agent with (durable conversation). */
+  initialMessages?: readonly Message[];
+  /**
+   * AG-UI shared state to seed the agent with. `@ag-ui/client` sends it as
+   * `RunAgentInput.state` on every run and replaces it in place when the
+   * server streams `STATE_SNAPSHOT` / `STATE_DELTA`.
+   */
+  initialState?: Readonly<Record<string, unknown>>;
+  /**
+   * Origins, besides the document's own, this agent may carry the host's
+   * credentials to.
+   *
+   * Running the agent on another subdomain is a normal deployment and stays
+   * supported, so a cross-origin endpoint is not refused — it is *announced*,
+   * once per origin, on the console. Listing an origin here says the
+   * destination was chosen deliberately and silences the notice for it.
+   *
+   * Entries are compared as serialized origins (`https://agent.example.com`,
+   * scheme and port included), which is what `URL.origin` produces.
+   */
+  trustedOrigins?: readonly string[];
+}
+
+/**
+ * Build an AG-UI {@link HttpAgent} pointed at `endpoint`.
+ *
+ * The default agent factory for `<ag-ui-chat>`; tests and advanced hosts
+ * override the element's `agentFactory` to inject a different
+ * {@link AbstractAgent}.
+ */
+export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
+  const staticHeaders = options.headers ?? {};
+  const warned = new Set<string>();
+  return new HttpAgent({
+    url: options.endpoint,
+    headers: staticHeaders,
+    initialState: { ...(options.initialState ?? {}) },
+    // HttpAgent invokes its configured fetch as a method (`this.fetch(...)`),
+    // rebinding the global `fetch` to the agent instance — "Illegal invocation"
+    // in browsers. The wrapper keeps `fetch` a free call, and is also where the
+    // per-request `getHeaders()` overlay and the cookie policy go, the agent's
+    // own config having no seam for either.
+    fetch: (url, init) => {
+      const fresh = options.getHeaders?.();
+      // Only the names the *host* supplied. `HttpAgent` adds `Content-Type` and
+      // `Accept` to every request and neither is a credential, so reporting the
+      // outgoing header set wholesale would cry wolf on every plain request.
+      const credentialNames = [
+        ...new Set([...Object.keys(staticHeaders), ...Object.keys(fresh ?? {})]),
+      ].sort();
+      warnOnCrossOriginCredentials(url, credentialNames, options.trustedOrigins ?? [], warned);
+      if (fresh === undefined) {
+        return fetch(url, withCredentials(init, options.credentials));
+      }
+      const headers = new Headers(init?.headers);
+      for (const [name, value] of Object.entries(fresh)) {
+        headers.set(name, value);
+      }
+      return fetch(url, withCredentials({ ...init, headers }, options.credentials));
+    },
+    // Spread conditionally: under `exactOptionalPropertyTypes` an explicit
+    // `undefined` is not assignable to an optional field.
+    ...(options.threadId !== undefined ? { threadId: options.threadId } : {}),
+    ...(options.initialMessages !== undefined
+      ? { initialMessages: [...options.initialMessages] }
+      : {}),
+  });
+}
+
+/** Signature of the agent factory the element calls to build its agent. */
+export type AgentFactory = (options: HttpAgentOptions) => AbstractAgent;

package/src/core/define_chat.ts

@@ -0,0 +1,25 @@
+import { ELEMENT_TAG } from "../constants.js";
+import { AgUiChat } from "./ag_ui_chat.js";
+
+/**
+ * Register the `<ag-ui-chat>` Custom Element.
+ *
+ * Idempotent: a second call, or one after this package's `AgUiChat` already
+ * holds the tag, is a no-op. If another class holds the tag it throws naming
+ * the tag, because two copies of the element on one page (two bundles, or this
+ * package beside its predecessor) would otherwise run the other one. The class
+ * is not named: in a minified bundle its name is a one-letter identifier.
+ * Registration is an explicit step rather than an import side effect, so
+ * importing the package defines nothing and stays tree-shakeable.
+ */
+export function defineChat(): void {
+  const existing = customElements.get(ELEMENT_TAG);
+  if (existing === undefined) {
+    customElements.define(ELEMENT_TAG, AgUiChat);
+  } else if (existing !== AgUiChat) {
+    throw new Error(
+      `<${ELEMENT_TAG}> is already defined by another class: ` +
+        "a second copy of this package, or another package, is on the page",
+    );
+  }
+}

package/src/core/events/attachments_detail.ts

@@ -0,0 +1,9 @@
+import type { AttachmentRef } from "../attachment.js";
+
+/** `detail` shape of the {@link ATTACHMENT_EVENT} CustomEvent. */
+export interface AttachmentsDetail {
+  /** Durable refs for every file that has finished uploading. */
+  readonly attachments: readonly AttachmentRef[];
+  /** How many files are still uploading; a send now would leave these behind. */
+  readonly pending: number;
+}

package/src/core/events/bar_height_detail.ts

@@ -0,0 +1,5 @@
+/** `detail` shape of the {@link BAR_HEIGHT_EVENT} CustomEvent. */
+export interface BarHeightDetail {
+  /** The bottom bar's height in CSS px; 0 when no bar is drawn. */
+  readonly height: number;
+}

package/src/core/events/custom_agent_detail.ts

@@ -0,0 +1,7 @@
+/** `detail` shape of the {@link CUSTOM_AGENT_EVENT} CustomEvent. */
+export interface CustomAgentDetail {
+  /** The `CUSTOM` event's `name`, verbatim. An open string; never interpreted here. */
+  readonly name: string;
+  /** Its `value`, verbatim and unparsed. `unknown` because the protocol says nothing about it. */
+  readonly value: unknown;
+}

package/src/core/events/dock_width_detail.ts

@@ -0,0 +1,7 @@
+/** `detail` shape of the {@link DOCK_WIDTH_EVENT} CustomEvent. */
+export interface DockWidthDetail {
+  /** The CSS px the docked panel covers at rest; 0 when it covers none of the page. */
+  readonly width: number;
+  /** The edge the panel docks against. */
+  readonly side: "left" | "right";
+}

package/src/core/events/feedback_detail.ts

@@ -0,0 +1,27 @@
+/** {@link FEEDBACK_EVENT} detail: what was rated, and how. */
+export interface FeedbackDetail {
+  /** The rated message's text, as rendered. */
+  readonly content: string;
+  readonly rating: "up" | "down";
+  /**
+   * The AG-UI id of the rated assistant message: the id it streamed under, or
+   * the stored message's `id` when it was restored from history.
+   *
+   * What a host stores a rating against. `content` cannot be: two answers can
+   * read the same, and the text says nothing about which stored message it
+   * was. A restored message carries whatever id its store returns: the
+   * built-in browser store keeps the streamed ids, and a server-backed one
+   * keeps them only where the server persists the ids it streamed.
+   */
+  readonly messageId: string;
+  /** The conversation the message belongs to: the element's thread when it was drawn. */
+  readonly threadId: string;
+  /**
+   * The run that streamed the message, as its `RUN_STARTED` named it.
+   *
+   * Present only on a message that arrived live. A restored one has none to
+   * give -- an AG-UI message carries no run id -- so the key is absent there
+   * rather than holding a value that only looks like one.
+   */
+  readonly runId?: string;
+}

package/src/core/events/invalidate_detail.ts

@@ -0,0 +1,15 @@
+/** `detail` shape of the {@link INVALIDATE_EVENT} CustomEvent. */
+export interface InvalidateDetail {
+  /**
+   * The resources that moved, as the server named them.
+   *
+   * **Opaque strings, and matching is exact.** `orders/42` does not imply
+   * `orders` -- a prefix rule would be this component guessing at a scheme it
+   * does not own, and `orders/1` would match `orders/11`. A server that wants
+   * the collection refreshed names it. Your own matching may be hierarchical,
+   * because in your vocabulary the scheme is known.
+   */
+  readonly keys: readonly string[];
+  /** What caused the write -- usually the tool's name. `null` when unstated. */
+  readonly reason: string | null;
+}

package/src/core/events/maximize_detail.ts

@@ -0,0 +1,4 @@
+/** `detail` shape of the {@link MAXIMIZE_EVENT} CustomEvent. */
+export interface MaximizeDetail {
+  readonly maximized: boolean;
+}

package/src/core/events/run_finished_detail.ts

@@ -0,0 +1,36 @@
+import type { ToolRun } from "./tool_run.js";
+
+/** `detail` shape of the {@link RUN_FINISHED_EVENT} CustomEvent. */
+export interface RunFinishedDetail {
+  /**
+   * The thread the run belonged to, fixed when its client was built. Not always
+   * the thread on screen: a run stopped by a new chat or a thread switch still
+   * reports once its request closes, and by then another thread is.
+   */
+  readonly threadId: string;
+  /** In settle order. Empty when the interaction called no tools. */
+  readonly tools: readonly ToolRun[];
+  /**
+   * Every key announced during the interaction, de-duplicated, first-seen order.
+   *
+   * **This is the field that makes adoption one line** for a host already
+   * listening here, and the `else` is the whole compatibility story:
+   *
+   * ```js
+   * if (detail.invalidated.length > 0) refetchOnly(detail.invalidated);
+   * else if (detail.tools.some((t) => t.side === "server")) refetchEverything();
+   * ```
+   *
+   * Empty against a server that announces nothing, so an old server and a new
+   * client fall through to the coarse refetch that shipped before either.
+   */
+  readonly invalidated: readonly string[];
+  /**
+   * How the interaction ended: `"completed"` when it ran to its end, `"stopped"`
+   * when Stop, a new chat or a thread switch cut it off, `"failed"` when the
+   * agent reported an error. Reported for a run the conversation has left
+   * behind too, so a host can tell a cancelled run's late event from the live
+   * run's own. A host should ignore a value it does not know.
+   */
+  readonly outcome: "completed" | "stopped" | "failed";
+}

package/src/core/events/state_detail.ts

@@ -0,0 +1,4 @@
+/** `detail` shape of the {@link STATE_EVENT} CustomEvent. */
+export interface StateDetail {
+  readonly state: Readonly<Record<string, unknown>>;
+}

package/src/core/events/submit_detail.ts

@@ -0,0 +1,8 @@
+import type { AttachmentRef } from "../attachment.js";
+
+/** `detail` shape of the {@link SUBMIT_EVENT} CustomEvent. */
+export interface SubmitDetail {
+  readonly content: string;
+  /** Durable refs for the files attached to this message (empty when none). */
+  readonly attachments: readonly AttachmentRef[];
+}

package/src/core/events/thread_detail.ts

@@ -0,0 +1,26 @@
+/** `detail` shape of the {@link THREAD_EVENT} CustomEvent. */
+export interface ThreadDetail {
+  /** The thread now on screen. */
+  readonly threadId: string;
+  /**
+   * The thread on screen before the change: the one the previous event
+   * reported, and `null` before the first, as at the restore when the element
+   * first connects. Equal to `threadId` when the same thread was restored
+   * again (`reload()`, the element connecting again).
+   */
+  readonly previousThreadId: string | null;
+  /**
+   * What changed it:
+   *
+   * - `new`: `newChat()` or the built-in New chat button.
+   * - `switch`: `switchThread()` or a row picked in the conversation list.
+   * - `delete`: the active thread was deleted, and a fresh one took its place.
+   * - `restore`: the stored thread was replayed, on connect or by `reload()`.
+   * - `rescope`: a `user-key` change handed the element to another principal,
+   *   live or while it was out of the document.
+   *
+   * A closed set today; a host should ignore a reason it does not know, so a
+   * later one can be added without breaking it.
+   */
+  readonly reason: "new" | "switch" | "delete" | "restore" | "rescope";
+}

package/src/core/events/thread_title_detail.ts

@@ -0,0 +1,7 @@
+/** `detail` shape of the {@link THREAD_TITLE_EVENT} CustomEvent. */
+export interface ThreadTitleDetail {
+  /** The thread on screen. */
+  readonly threadId: string;
+  /** Its title, as `threadTitle` reads it now; `""` for a thread with nothing sent. */
+  readonly title: string;
+}

package/src/core/events/toggle_detail.ts

@@ -0,0 +1,4 @@
+/** `detail` shape of the {@link TOGGLE_EVENT} CustomEvent. */
+export interface ToggleDetail {
+  readonly collapsed: boolean;
+}

package/src/core/events/tool_run.ts

@@ -0,0 +1,10 @@
+/** One tool that ran during an interaction, as {@link RunFinishedDetail} lists it. */
+export interface ToolRun {
+  readonly name: string;
+  /**
+   * Where it executed. `"server"` is the one a data-rendering host cares about:
+   * a `"client"` tool ran in the host's own handler, so the host already knows
+   * whatever it did.
+   */
+  readonly side: "server" | "client";
+}

package/src/core/events/unread_detail.ts

@@ -0,0 +1,10 @@
+/** `detail` shape of the {@link UNREAD_EVENT} CustomEvent. */
+export interface UnreadDetail {
+  /** Unseen answers across every thread: what the launcher badge shows. */
+  readonly unread: number;
+  /**
+   * The threads whose unseen answers this change marked or cleared; empty when
+   * none did (a collapse toggle still reports the total).
+   */
+  readonly threadIds: readonly string[];
+}

package/src/core/message_role.ts

@@ -0,0 +1,4 @@
+import type { MESSAGE_ROLE } from "../constants.js";
+
+/** The role a rendered chat message takes. */
+export type MessageRole = (typeof MESSAGE_ROLE)[keyof typeof MESSAGE_ROLE];

package/src/core/read_flag.ts

@@ -0,0 +1,13 @@
+/**
+ * Read an opt-in flag attribute on `element` the way HTML reads a boolean
+ * attribute.
+ *
+ * Present means on: bare (`data-prompt-chips`), empty (`=""`), or any value
+ * except the literal `"false"`. Comparing against `"true"` instead would make
+ * the bare spelling every native boolean attribute uses silently disable the
+ * feature it names. `="false"` still turns it off.
+ */
+export function readFlag(element: Element, name: string): boolean {
+  const value = element.getAttribute(name);
+  return value !== null && value !== "false";
+}

package/src/core/read_json_attribute.ts

@@ -0,0 +1,30 @@
+/**
+ * Parse a JSON-valued attribute on `element`, saying so when it will not parse.
+ *
+ * `null` for an absent attribute, and `null` again for one that is not JSON --
+ * but not quietly the second time. Quoting JSON inside an HTML attribute is
+ * fiddly, and the result of getting it wrong is indistinguishable from the
+ * feature being switched off: no chips appear, or the strings stay English,
+ * with nothing anywhere saying why. That is the same failure `data-paste-attach`
+ * already reports for a value it cannot read.
+ *
+ * Console only. A page author's typo is not the reader's business, nothing the
+ * reader did was refused, and the degraded widget is still perfectly usable.
+ */
+export function readJsonAttribute(element: Element, name: string): unknown {
+  const raw = element.getAttribute(name);
+  if (raw === null) {
+    return null;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    console.warn(
+      `<ag-ui-chat>: ${name} is not valid JSON, so it was ignored entirely and ` +
+        "the built-in default is being used. Check the quoting -- JSON inside " +
+        "an HTML attribute needs single quotes around the attribute value, or " +
+        "its own double quotes escaped.",
+    );
+    return null;
+  }
+}

package/src/core/read_max_tool_rounds.ts

@@ -0,0 +1,13 @@
+import { MAX_TOOL_ROUNDS } from "../constants.js";
+
+/**
+ * The tool-round budget from `element`'s `data-max-tool-rounds`, for one send.
+ *
+ * Anything unparseable becomes `NaN`, which {@link AgUiClient} rejects along
+ * with a bound below one -- so the two ways of setting this are validated in
+ * one place rather than agreeing by coincidence.
+ */
+export function readMaxToolRounds(element: Element): number {
+  const attr = element.getAttribute("data-max-tool-rounds");
+  return attr === null ? MAX_TOOL_ROUNDS : Number.parseInt(attr, 10);
+}