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

package/src/tools/tool_catalog.ts

@@ -0,0 +1,334 @@
+import type { Tool } from "@ag-ui/core";
+import { READ_PAGE_TOOL, X_SUMMARY_KEY } from "../constants.js";
+import { commaTokens } from "../core/utils.js";
+import type { PendingDecision } from "../ui/interrupts/pending_decision.js";
+import {
+  type QuestionRenderer,
+  type QuestionRequest,
+  requestQuestion,
+} from "../ui/interrupts/question_card.js";
+import type { UiStrings } from "../ui/ui_strings.js";
+import { type ChatSurface, createChatSurfaceTools } from "./chat_surface_tools.js";
+import { type ClientTool, ClientToolRegistry } from "./client_tool_registry.js";
+import { createPageActionTools, PAGE_ACTIONS } from "./page_action_tools.js";
+import type { PageMap } from "./page_map.js";
+import { createPageStateTools, type PageState } from "./page_state.js";
+import { parseToolCatalog, type ToolCatalogEntry } from "./parse_tool_catalog.js";
+import { createRouteTools, type RouteMap } from "./route_map.js";
+
+/** What the tool catalog needs from the element that owns it. */
+export interface ToolCatalogHost {
+  /** The custom element: its tool attributes, and the surface the chat tools drive. */
+  readonly element: HTMLElement & ChatSurface;
+  /** The element's `routeMap`, read per call. */
+  readonly routeMap: () => RouteMap;
+  /** The element's `navigate`, read per call. */
+  readonly navigate: () => ((path: string) => void) | null;
+  /** The element's `getPageMap`, read per call. */
+  readonly getPageMap: () => (() => PageMap) | null;
+  /** Whether the user withheld the place, which withholds the page with it. */
+  readonly pageWithheld: () => boolean;
+  /** The element's `resolvePageTarget`, called per target. */
+  readonly resolvePageTarget: (target: string) => HTMLElement | null;
+  /** The element's `getTools`, which a host may have replaced. */
+  readonly getTools: () => Tool[];
+  /** The element's `askUser` flag. */
+  readonly askUser: () => boolean;
+  /** The element's `askUserRenderer`. */
+  readonly askUserRenderer: () => QuestionRenderer | null;
+  /** The decision a run is suspended on, which a Stop abandons. */
+  readonly decision: PendingDecision;
+  /**
+   * Mark the card of ``callId`` as asking the user, or no longer. The call id is
+   * absent for a handler run outside a tool call, which has no card to mark.
+   */
+  readonly setAsking: (callId: string | undefined, asking: boolean) => void;
+  /** The current answer group, opening one if none is open. */
+  readonly ensureGroup: () => HTMLDivElement;
+  /** The resolved string table. */
+  readonly strings: () => UiStrings;
+  /** Remove the pending indicator if shown. */
+  readonly hidePending: () => void;
+  /** Update the empty state after the transcript changed. */
+  readonly updateEmptyState: () => void;
+  /** Keep the transcript at its foot, if the reader is there. */
+  readonly follow: () => void;
+  /** The fetch options every request the element makes carries. */
+  readonly fetchInit: (url: string) => RequestInit | undefined;
+}
+
+/**
+ * The frontend tools the agent is offered: the host's registered tools, the
+ * built-in ones the element's configuration switches on, what the current round
+ * advertised, and the server's catalog of labels for the tools it runs itself.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class ToolCatalog {
+  readonly #host: ToolCatalogHost;
+  /** The `data-tools-url` catalog by tool name: the base layer behind `toolSummaries`, filled once on connect. */
+  #toolCatalog: Record<string, ToolCatalogEntry> = {};
+  /**
+   * The tool names the current round handed the agent, snapshotted as the catalog went out.
+   *
+   * The registry is mount-wide but `getTools` is per-run, so a call naming a tool this run
+   * withheld must not reach a handler that is merely still registered. Not re-asked at
+   * dispatch: the provider is a function and may answer differently. Empty until the first
+   * round advertises, which always precedes the calls that round produces.
+   */
+  #advertisedTools: ReadonlySet<string> = new Set();
+  readonly #toolRegistry = new ClientToolRegistry();
+
+  constructor(host: ToolCatalogHost) {
+    this.#host = host;
+  }
+
+  /** The registration behind `AgUiChat.registerTool`, whose doc is the contract. */
+  register(tool: ClientTool): void {
+    this.#toolRegistry.register(tool);
+  }
+
+  /** The binding behind `AgUiChat.registerPageState`, whose doc is the contract. */
+  registerPageState(binding: PageState): void {
+    for (const tool of createPageStateTools(binding)) {
+      this.#toolRegistry.register(tool);
+    }
+  }
+
+  /** Whether a tool of this name is registered, built-ins aside. */
+  has(name: string): boolean {
+    return this.#toolRegistry.has(name);
+  }
+
+  /** The catalog behind the default `AgUiChat.getTools`, whose doc is the contract. */
+  defaultTools(): Tool[] {
+    return [
+      ...this.#builtinTools().map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      })),
+      ...this.#toolRegistry.tools(),
+    ];
+  }
+
+  /**
+   * The catalog for the round about to start, remembering what it offered.
+   *
+   * Every path to a frontend tool goes through here first — the client asks
+   * for `RunAgentInput.tools` at the top of each round — so this is the one
+   * place that can know what the agent was actually told about.
+   */
+  advertise(): Tool[] {
+    const tools = this.#host.getTools();
+    this.#advertisedTools = new Set(tools.map((tool) => tool.name));
+    return tools;
+  }
+
+  /** Whether the current round offered a tool of this name. */
+  wasAdvertised(name: string): boolean {
+    return this.#advertisedTools.has(name);
+  }
+
+  /** Resolve a tool by name: built-in tools first, then the registry. */
+  resolve(name: string): ClientTool | null {
+    const builtin = this.#builtinTools().find((t) => t.name === name);
+    if (builtin !== undefined) {
+      return builtin;
+    }
+    return this.#toolRegistry.has(name) ? this.#toolRegistry.get(name) : null;
+  }
+
+  /** The server catalog's label for a tool, if it sent one. */
+  summary(name: string): string | undefined {
+    return this.#toolCatalog[name]?.summary;
+  }
+
+  /** Fetch the server tool-label catalog from `data-tools-url`, if set. */
+  async fetchCatalog(): Promise<void> {
+    const url = this.#host.element.getAttribute("data-tools-url");
+    if (url === null) {
+      return;
+    }
+    try {
+      const response = await fetch(url, this.#host.fetchInit(url));
+      this.#toolCatalog = parseToolCatalog(await response.json());
+    } catch {
+      // Network/parse failure: cards fall back to toolSummaries / raw names.
+    }
+  }
+
+  /** The built-in `route.*` tools, present only when a route map is set. */
+  #routeTools(): ClientTool[] {
+    if (this.#host.routeMap().length === 0) {
+      return [];
+    }
+    return createRouteTools(
+      () => this.#host.routeMap(),
+      () => this.#host.navigate(),
+    );
+  }
+
+  /**
+   * The built-in `read_page` tool, present only when a `getPageMap`
+   * provider is set and the user has not withheld the place. A *pull* the
+   * agent can call mid-turn to see the page after it has acted (the
+   * auto-injected context is a send-time snapshot).
+   */
+  #pageTools(): ClientTool[] {
+    const getPageMap = this.#host.getPageMap();
+    if (getPageMap === null || this.#host.pageWithheld()) {
+      return [];
+    }
+    return [
+      {
+        name: READ_PAGE_TOOL,
+        description:
+          "Read the current page's structure (fields, buttons, route). Call after " +
+          "acting to observe the result within the same turn.",
+        parameters: {
+          type: "object",
+          properties: {},
+          required: [],
+          [X_SUMMARY_KEY]: "Read the page",
+        },
+        handler: () => getPageMap(),
+      },
+    ];
+  }
+
+  /**
+   * Opt-in page-action tools (`scroll_to` / `drag_and_drop`), enabled per token
+   * via the `data-page-actions` attribute (e.g. `"scroll,drag"`). Targets resolve
+   * through `resolvePageTarget` so a host controls the agent's interaction
+   * surface; absent attribute ⇒ no tools registered.
+   */
+  #pageActionTools(): ClientTool[] {
+    const attr = this.#host.element.getAttribute("data-page-actions");
+    if (attr === null) {
+      return [];
+    }
+    const enabled = new Set(commaTokens(attr));
+    return [
+      ...createPageActionTools(enabled, (target) => this.#host.resolvePageTarget(target)),
+      ...(enabled.has(PAGE_ACTIONS.CHAT) ? createChatSurfaceTools(this.#host.element) : []),
+    ];
+  }
+
+  /** All built-in (route + page + page-action + ask_user) frontend tools. */
+  #builtinTools(): ClientTool[] {
+    return [
+      ...this.#routeTools(),
+      ...this.#pageTools(),
+      ...this.#pageActionTools(),
+      ...this.#askUserTool(),
+    ];
+  }
+
+  /**
+   * The built-in `ask_user` frontend tool, or `[]` when `askUser` is off.
+   *
+   * The agent calls it, the client executes it locally through the normal
+   * frontend-tool path by rendering a {@link requestQuestion} card, and the
+   * answer flows back as the tool result. No new protocol.
+   */
+  #askUserTool(): ClientTool[] {
+    if (!this.#host.askUser()) {
+      return [];
+    }
+    return [
+      {
+        name: "ask_user",
+        description:
+          "Ask the user a question and wait for their answer. Provide `options` for a " +
+          "multiple-choice prompt; set `allow_custom` to also accept a free-text answer.",
+        parameters: {
+          type: "object",
+          properties: {
+            question: { type: "string", description: "The question to ask the user." },
+            options: {
+              type: "array",
+              items: { type: "string" },
+              description: "Preset choices offered as radio buttons.",
+            },
+            allow_custom: {
+              type: "boolean",
+              description: "Allow a free-text answer in addition to any options.",
+            },
+          },
+          required: ["question"],
+        },
+        handler: (args, callId) => this.#askUser(args, callId),
+      },
+    ];
+  }
+
+  /** Render the `ask_user` question card and resolve with the user's answer. */
+  async #askUser(args: Record<string, unknown>, callId: string | undefined): Promise<string> {
+    const question = typeof args["question"] === "string" ? args["question"] : "";
+    const request: QuestionRequest = { question };
+    const rawOptions = args["options"];
+    if (Array.isArray(rawOptions)) {
+      request.options = rawOptions.filter((option): option is string => typeof option === "string");
+    }
+    if (args["allow_custom"] === true) {
+      request.allowCustom = true;
+    }
+    // A Stop aborts the signal, resolving the card with an empty answer.
+    const signal = this.#host.decision.open();
+    this.#host.hidePending();
+    const builtIn = (): Promise<string> =>
+      requestQuestion(this.#host.ensureGroup(), request, {
+        signal,
+        strings: this.#host.strings(),
+      });
+    const renderer = this.#host.askUserRenderer();
+    let answer: string;
+    // Asking until answered, stopped or failed, so the step row does not read as running.
+    this.#host.setAsking(callId, true);
+    try {
+      if (renderer === null) {
+        answer = await builtIn();
+      } else {
+        // Called on the element, as `this.askUserRenderer(...)` always was.
+        // Awaited here, not in a helper, to keep the microtask count of an answering renderer.
+        try {
+          answer = await renderer.call(this.#host.element, request, { signal });
+        } catch (error) {
+          answer = await this.#afterRendererFailed(error, signal, callId, builtIn);
+        }
+      }
+    } finally {
+      this.#host.setAsking(callId, false);
+    }
+    this.#host.decision.close();
+    this.#host.updateEmptyState();
+    this.#host.follow();
+    return answer;
+  }
+
+  /**
+   * Answer an `ask_user` call whose host renderer failed: the built-in card asks instead.
+   *
+   * A renderer is presentation, not policy, so its failure must neither reach the agent as
+   * the tool result nor leave the pending decision open. A rejection after a Stop is the
+   * signal working: it resolves empty and says nothing.
+   */
+  #afterRendererFailed(
+    error: unknown,
+    signal: AbortSignal,
+    callId: string | undefined,
+    builtIn: () => Promise<string>,
+  ): Promise<string> {
+    if (signal.aborted) {
+      return Promise.resolve("");
+    }
+    // Named by call id: the model can ask the same question twice in a turn.
+    console.warn(
+      `ag-ui-chat: askUserRenderer failed for tool call ${callId}, so the built-in question card asks instead`,
+      error,
+    );
+    return builtIn();
+  }
+}