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

package/src/tools/page_action_tools.ts

@@ -0,0 +1,123 @@
+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 treats the string as a CSS selector; a host with
+ * a page map overrides it to map its own element ids.
+ */
+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",
+  /** The widget's own position: see `createChatSurfaceTools`. */
+  CHAT: "chat",
+} 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. Deliberately 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 must gate it with the element's `confirmPredicate`.
+ *
+ * Both report a model-readable error when a target resolves to nothing.
+ */
+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 HTML5 drag sequence, sharing one {@link DataTransfer} attached to each event explicitly. */
+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/tools/page_map.ts

@@ -0,0 +1,26 @@
+import type { Context } from "@ag-ui/core";
+import { PAGE_MAP_CONTEXT } from "../constants.js";
+
+/**
+ * A compact snapshot of the current page's actionable surface (field
+ * names/types/labels, button labels+handles — not values). Host-defined shape;
+ * kept small because it rides in every `RunAgentInput.context`.
+ */
+export type PageMap = Record<string, unknown>;
+
+/**
+ * Build the per-run context entry for the page map.
+ *
+ * Returns a single `page_map` context item when auto-injection is on and a
+ * provider is set, else nothing. Recomputed each run so it reflects the page
+ * the agent is currently looking at.
+ */
+export function createPageMapContext(
+  getPageMap: (() => PageMap) | null,
+  autoInject: boolean,
+): Context[] {
+  if (!autoInject || getPageMap === null) {
+    return [];
+  }
+  return [{ description: PAGE_MAP_CONTEXT, value: JSON.stringify(getPageMap()) }];
+}

package/src/tools/page_state.ts

@@ -0,0 +1,57 @@
+import { X_DESTRUCTIVE_KEY, X_SUMMARY_KEY } from "../constants.js";
+import type { ClientTool } from "./client_tool_registry.js";
+
+/**
+ * A binding from a named piece of host page state to agent tools.
+ *
+ * Ergonomic sugar over `registerTool` for SPA state (Redux/Zustand/signals):
+ * generates a read tool and, when `write` is given, a destructive set tool.
+ *
+ * Not AG-UI shared state. `STATE_SNAPSHOT` / `STATE_DELTA` are protocol events
+ * carrying state between agent and client; these are ordinary client tools the
+ * agent calls like any other.
+ */
+export interface PageState {
+  /** Base name; tools become `read_<name>` and `set_<name>`. */
+  readonly name: string;
+  /** Returns the current state value. */
+  readonly read: () => unknown;
+  /** Mutates the state from the agent-supplied args. Omit for read-only. */
+  readonly write?: (args: Record<string, unknown>) => unknown;
+  /** JSON-Schema for the set tool's args. Defaults to an open object. */
+  readonly schema?: Record<string, unknown>;
+}
+
+/**
+ * Build the tools for a {@link PageState}: always a `read_<name>` (read-only)
+ * tool, plus a `set_<name>` (`x-destructive`) tool when `write` is supplied.
+ */
+export function createPageStateTools(binding: PageState): ClientTool[] {
+  const tools: ClientTool[] = [
+    {
+      name: `read_${binding.name}`,
+      description: `Read the "${binding.name}" state.`,
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        [X_SUMMARY_KEY]: `Read ${binding.name}`,
+      },
+      handler: () => binding.read(),
+    },
+  ];
+  const write = binding.write;
+  if (write !== undefined) {
+    tools.push({
+      name: `set_${binding.name}`,
+      description: `Update the "${binding.name}" state.`,
+      parameters: {
+        ...(binding.schema ?? { type: "object" }),
+        [X_DESTRUCTIVE_KEY]: true,
+        [X_SUMMARY_KEY]: `Update ${binding.name}`,
+      },
+      handler: (args) => write(args),
+    });
+  }
+  return tools;
+}

package/src/tools/parse_tool_catalog.ts

@@ -0,0 +1,41 @@
+/**
+ * One entry in the server-tool catalog served by django-ag-ui's `tools/`
+ * endpoint and fetched via the `data-tools-url` attribute.
+ */
+export interface ToolCatalogEntry {
+  /** The tool's wire name (matches the name in `TOOL_CALL_START`). */
+  readonly name: string;
+  /** A friendly card label for the tool. */
+  readonly summary: string;
+  /** Optional longer blurb (e.g. for a tooltip). */
+  readonly description?: string;
+}
+
+/**
+ * Parse a fetched tool catalog into a `name → entry` map, skipping any entry
+ * that isn't a `{ name: string, summary: string }` object. Tolerant by design:
+ * a malformed payload yields an empty map rather than throwing, and an
+ * optional field of the wrong type costs that field rather than the entry.
+ * Whole entries are kept, so a consumer can reach `description`.
+ */
+export function parseToolCatalog(data: unknown): Record<string, ToolCatalogEntry> {
+  const out: Record<string, ToolCatalogEntry> = {};
+  if (!Array.isArray(data)) {
+    return out;
+  }
+  for (const entry of data) {
+    if (entry === null || typeof entry !== "object") {
+      continue;
+    }
+    const record = entry as Record<string, unknown>;
+    const name = record["name"];
+    const summary = record["summary"];
+    const description = record["description"];
+    if (typeof name === "string" && typeof summary === "string") {
+      // `exactOptionalPropertyTypes`: absent is not the same type as present-as-undefined.
+      out[name] =
+        typeof description === "string" ? { name, summary, description } : { name, summary };
+    }
+  }
+  return out;
+}

package/src/tools/route_map.ts

@@ -0,0 +1,132 @@
+import { X_NAVIGATES_KEY, X_SUMMARY_KEY } from "../constants.js";
+import type { ClientTool } from "./client_tool_registry.js";
+
+/** A single navigable route the host declares for the agent. */
+export interface Route {
+  /** Stable id the agent uses with `navigate_to_route`. */
+  readonly id: string;
+  /**
+   * The URL path to navigate to. May contain `:name` placeholders for dynamic
+   * segments (e.g. `/admin/shop/book/:pk/change/`), which the agent fills via
+   * `navigate_to_route`'s `params` argument.
+   */
+  readonly path: string;
+  /** Human label shown to the agent. */
+  readonly title?: string;
+  /** Optional grouping (e.g. an app or section). */
+  readonly group?: string;
+  /** Optional longer description of when to use the route. */
+  readonly description?: string;
+}
+
+/** The host-declared catalog of navigable routes. */
+export type RouteMap = readonly Route[];
+
+/** A route enriched with its derived dynamic-segment parameter names. */
+export interface RouteWithParams extends Route {
+  /** Names of the `:name` placeholders in {@link Route.path} (may be empty). */
+  readonly pathParams: readonly string[];
+}
+
+const PATH_PARAM_RE = /:([A-Za-z_][A-Za-z0-9_]*)/g;
+
+/** The `:name` path-parameter names declared in a path template, in order. */
+function pathParamNames(path: string): string[] {
+  // Slicing the match avoids an uncoverable `undefined` guard on the capture group.
+  return [...path.matchAll(PATH_PARAM_RE)].map((match) => match[0].slice(1));
+}
+
+/**
+ * Substitute `:name` placeholders in `path` from `params`.
+ *
+ * Returns the concrete path plus the params no placeholder consumed, for the
+ * caller to append as a query string. Throws (naming `routeId`) when a declared
+ * path param is missing or empty — a half-filled path must never be navigated
+ * to.
+ */
+function fillPath(
+  routeId: string,
+  path: string,
+  params: Record<string, unknown>,
+): { path: string; leftover: Record<string, unknown> } {
+  const leftover: Record<string, unknown> = { ...params };
+  const filled = path.replace(PATH_PARAM_RE, (_match, name: string) => {
+    const value = params[name];
+    if (value === undefined || value === null || String(value) === "") {
+      throw new Error(`route "${routeId}" requires path param "${name}"`);
+    }
+    delete leftover[name];
+    return encodeURIComponent(String(value));
+  });
+  return { path: filled, leftover };
+}
+
+/** Append `params` to `path` as a query string (no-op when empty). */
+function withQuery(path: string, params: Record<string, unknown>): string {
+  const usp = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    usp.set(key, String(value));
+  }
+  const query = usp.toString();
+  return query === "" ? path : `${path}?${query}`;
+}
+
+/**
+ * The built-in `route.*` tools, bound to live getters so a host can set
+ * `routeMap` / `navigate` before or after mount.
+ *
+ * `list_routes` is read-only and advertises each route's `pathParams` so the
+ * model knows what to supply. `navigate_to_route` fills those params, appends
+ * the rest as a query string, and is stamped `x-navigates` so an MPA reload
+ * checkpoints and resumes; with a host `navigate(path)` callback (an SPA) it
+ * routes client-side and the run loop continues instead.
+ */
+export function createRouteTools(
+  getRouteMap: () => RouteMap,
+  getNavigate: () => ((path: string) => void) | null,
+): ClientTool[] {
+  return [
+    {
+      name: "list_routes",
+      description:
+        "List the routes the app can navigate to. Each route's `pathParams` " +
+        "names the dynamic segments to pass as `params` to `navigate_to_route`.",
+      parameters: { type: "object", properties: {}, required: [], [X_SUMMARY_KEY]: "List pages" },
+      handler: (): RouteWithParams[] =>
+        getRouteMap().map((route) => ({ ...route, pathParams: pathParamNames(route.path) })),
+    },
+    {
+      name: "navigate_to_route",
+      description:
+        "Navigate to one of the app's routes by its id, filling any dynamic " +
+        "`:name` path segments (and extra query params) from `params`.",
+      parameters: {
+        type: "object",
+        properties: {
+          route_id: { type: "string" },
+          params: { type: "object" },
+        },
+        required: ["route_id"],
+        [X_NAVIGATES_KEY]: true,
+        [X_SUMMARY_KEY]: "Navigate",
+      },
+      handler: (args) => {
+        const routeId = args["route_id"];
+        const route = getRouteMap().find((r) => r.id === routeId);
+        if (route === undefined) {
+          throw new Error(`unknown route "${String(routeId)}"`);
+        }
+        const provided = (args["params"] as Record<string, unknown> | undefined) ?? {};
+        const { path: filledPath, leftover } = fillPath(route.id, route.path, provided);
+        const path = withQuery(filledPath, leftover);
+        const navigate = getNavigate();
+        if (navigate !== null) {
+          navigate(path);
+        } else {
+          window.location.assign(path);
+        }
+        return { navigated: true, path };
+      },
+    },
+  ];
+}