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

package/src/skills/fill_template.ts

@@ -0,0 +1,31 @@
+/** Result of {@link fillTemplate}: the filled text plus any unresolved keys. */
+export interface TemplateResult {
+  /** The prompt with resolved `{placeholder}`s substituted. */
+  readonly text: string;
+  /** Placeholder names with no value available (deduped, in first-seen order). */
+  readonly missing: readonly string[];
+}
+
+const PLACEHOLDER_RE = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+
+/**
+ * Substitute `{name}` placeholders in `template` from `values`.
+ *
+ * A placeholder whose value is missing, `null`, or an empty string is left
+ * verbatim and reported in `missing`, so the caller can block the send rather
+ * than dispatch a half-filled prompt.
+ */
+export function fillTemplate(template: string, values: Record<string, unknown>): TemplateResult {
+  const missing: string[] = [];
+  const text = template.replace(PLACEHOLDER_RE, (token, key: string) => {
+    const value = values[key];
+    if (value === undefined || value === null || value === "") {
+      if (!missing.includes(key)) {
+        missing.push(key);
+      }
+      return token;
+    }
+    return String(value);
+  });
+  return { text, missing };
+}

package/src/skills/parse_skills.ts

@@ -0,0 +1,31 @@
+import type { Skill } from "./skill.js";
+
+/**
+ * Whether `value` has the required string fields of a {@link Skill}.
+ *
+ * `prompt` must stay optional: a server-resolved skill omits it, and requiring
+ * it would silently drop exactly the skills kept off the client.
+ */
+function isSkill(value: unknown): value is Skill {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record["name"] === "string" &&
+    typeof record["title"] === "string" &&
+    (record["prompt"] === undefined || typeof record["prompt"] === "string")
+  );
+}
+
+/**
+ * Parse an untrusted value (parsed JSON from `data-skills` or a skills
+ * endpoint) into a list of {@link Skill}s, dropping anything malformed. Never
+ * throws — a bad payload yields an empty list.
+ */
+export function parseSkills(value: unknown): Skill[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(isSkill);
+}

package/src/skills/skill.ts

@@ -0,0 +1,32 @@
+/**
+ * A pre-defined prompt the user can launch from the chat — surfaced as a chip
+ * and/or in the `/`-command palette. One catalog feeds both surfaces; the host
+ * provides skills via the `skills` property / `data-skills` attribute / a
+ * fetched endpoint (see {@link AgUiChat}).
+ */
+export interface Skill {
+  /** Stable id; the `/token` (kebab-case) in the palette. */
+  readonly name: string;
+  /** Label shown in chips and the palette. */
+  readonly title: string;
+  /** Secondary line shown in the palette. */
+  readonly description?: string;
+  /**
+   * The prompt to send. May contain `{placeholder}`s filled from the host's
+   * skill context before send; an unfilled placeholder blocks send.
+   *
+   * Omit it to keep the prompt server-side: the skill then sends the bare
+   * `/name` token for the agent to resolve, and the wording never reaches the
+   * browser. Prefer that for anything internal — a fetched catalog is a plain
+   * GET and an embedded one sits in the page source.
+   */
+  readonly prompt?: string;
+  /**
+   * Set `false` to pre-fill the composer instead of sending on pick. Defaults
+   * to sending, and is only meaningful for a skill carrying its own `prompt`;
+   * a server-resolved one always sends.
+   */
+  readonly sendImmediately?: boolean;
+  /** Also surface this skill as a chip (default false; the palette shows all). */
+  readonly chip?: boolean;
+}

package/src/skills/skill_catalog.ts

@@ -0,0 +1,172 @@
+import type { SkillsMenu } from "../ui/composer/skills_menu.js";
+import { fillUiString } from "../ui/fill_ui_string.js";
+import type { UiStrings } from "../ui/ui_strings.js";
+import { fillTemplate } from "./fill_template.js";
+import { parseSkills } from "./parse_skills.js";
+import type { Skill } from "./skill.js";
+
+/** What the skill catalog needs from the element that owns it. */
+export interface SkillCatalogHost {
+  /** The custom element, whose `data-skills-url` names the backend catalog. */
+  readonly element: HTMLElement;
+  /** The chips row and the slash palette the merged catalog is shown in. */
+  readonly menu: SkillsMenu;
+  /** The composer a picked skill's prompt is written into. */
+  readonly input: HTMLTextAreaElement;
+  /** The hint above the composer, saying what a skill still needs. */
+  readonly hint: HTMLElement;
+  /** The resolved string table. */
+  readonly strings: () => UiStrings;
+  /** The host's `skillContext`, read at the moment of the pick. */
+  readonly context: () => Record<string, unknown>;
+  /** Read an opt-in flag attribute. */
+  readonly flag: (name: string) => boolean;
+  /** Parse a JSON-valued attribute, warning when it will not parse. */
+  readonly readJsonAttribute: (name: string) => unknown;
+  /** The fetch options every request the element makes carries. */
+  readonly fetchInit: (url: string) => RequestInit | undefined;
+  /** The element's public `sendMessage`. */
+  readonly send: (content: string) => void;
+  /** Send whatever the composer holds, as the Send button does. */
+  readonly submit: () => void;
+  /** Resize the composer to what it now holds. */
+  readonly autoGrow: () => void;
+}
+
+/**
+ * The element's skills: the three catalogs a skill can come from, merged into
+ * the chips and the slash palette, and what picking one does to the composer.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class SkillCatalog {
+  readonly #host: SkillCatalogHost;
+  // Skill catalog by source; merged backend → embed → client (later wins).
+  #backendSkills: readonly Skill[] = [];
+  #embedSkills: readonly Skill[] = [];
+  #clientSkills: readonly Skill[] = [];
+  readonly #merged = new Map<string, Skill>();
+
+  constructor(host: SkillCatalogHost) {
+    this.#host = host;
+  }
+
+  /** The replacement behind `AgUiChat.setSkills`, whose doc is the contract. */
+  setClientSkills(skills: readonly Skill[]): void {
+    this.#clientSkills = skills;
+    this.#recompute();
+  }
+
+  /**
+   * Wire the skill surfaces: opt-in flags and the embedded catalog. The backend
+   * catalog is fetched from the element's startup, a microtask later, so it
+   * carries the host's transport configuration.
+   */
+  init(): void {
+    this.#host.menu.enableChips(this.#host.flag("data-prompt-chips"));
+    this.#host.menu.enableSlash(this.#host.flag("data-slash-commands"));
+    this.#embedSkills = this.#readEmbedded();
+    this.#recompute();
+  }
+
+  /** Fetch the backend skills catalog from `data-skills-url`, if set. */
+  async fetch(): Promise<void> {
+    const url = this.#host.element.getAttribute("data-skills-url");
+    if (url === null) {
+      return;
+    }
+    try {
+      const response = await fetch(url, this.#host.fetchInit(url));
+      this.#backendSkills = parseSkills(await response.json());
+      this.#recompute();
+    } catch {
+      // Network/parse failure: skills just stay as the embedded/client set.
+    }
+  }
+
+  /**
+   * Act on a picked skill.
+   *
+   * A skill with no `prompt` is server-resolved: picking it sends the bare
+   * `/name` token for the agent to expand, so the wording never reaches the
+   * browser. Prefer that shape — a skill often states a project's internal
+   * workflow most plainly, and a catalog endpoint is a plain GET.
+   *
+   * A skill carrying a `prompt` has the client fill its `{placeholder}`s from
+   * the page instead, which is right for placeholders only the page can supply.
+   *
+   * Either way a pick sends; `sendImmediately: false` opts into pre-filling the
+   * composer instead.
+   */
+  apply(skill: Skill): void {
+    const { input, hint } = this.#host;
+    if (skill.prompt === undefined) {
+      hint.hidden = true;
+      this.#host.send(`/${skill.name}`);
+      return;
+    }
+    const { text, missing } = fillTemplate(skill.prompt, this.#host.context());
+    if (missing.length > 0) {
+      // Hand the user something to work with rather than only a refusal. The
+      // partially-filled template goes into the composer with its unresolved
+      // `{placeholder}`s intact and the first one selected, so the next
+      // keystroke replaces it. A hint alone would leave what the user typed to
+      // open the palette (a lone "/") sitting there, saying nothing about what
+      // the skill wanted or how to give it.
+      hint.textContent = fillUiString(this.#host.strings().skillNeeds, {
+        title: skill.title,
+        fields: missing.join(", "),
+      });
+      hint.hidden = false;
+      input.value = text;
+      this.#host.autoGrow();
+      input.focus();
+      this.#selectFirstPlaceholder(text);
+      return;
+    }
+    hint.hidden = true;
+    input.value = text;
+    this.#host.autoGrow();
+    if (skill.sendImmediately === false) {
+      input.focus();
+      return;
+    }
+    this.#host.submit();
+  }
+
+  /** Parse the inline `data-skills` JSON catalog (empty when absent/malformed). */
+  #readEmbedded(): readonly Skill[] {
+    // `parseSkills` drops anything that is not a well-formed skill, `null`
+    // included, so the absent and unparseable cases need no branch here.
+    return parseSkills(this.#host.readJsonAttribute("data-skills"));
+  }
+
+  /** The title of the skill named `name` in the merged catalog, if it has one. */
+  title(name: string): string | undefined {
+    return this.#merged.get(name)?.title;
+  }
+
+  /** Merge the three sources (backend → embed → client; later wins by name). */
+  #recompute(): void {
+    this.#merged.clear();
+    for (const skill of [...this.#backendSkills, ...this.#embedSkills, ...this.#clientSkills]) {
+      this.#merged.set(skill.name, skill);
+    }
+    this.#host.menu.setSkills([...this.#merged.values()]);
+  }
+
+  /**
+   * Put the caret on the first unresolved placeholder, selected.
+   *
+   * Typing then replaces it, which is the shortest path from "this skill needs
+   * a topic" to a sendable prompt.
+   */
+  #selectFirstPlaceholder(text: string): void {
+    // The first surviving brace *is* the first unresolved placeholder — a
+    // resolved one was substituted away — so this needs no search through the
+    // missing keys and no not-found branch to defend.
+    const start = text.indexOf("{");
+    this.#host.input.setSelectionRange(start, text.indexOf("}", start) + 1);
+  }
+}

package/src/skills/skill_name_from.ts

@@ -0,0 +1,19 @@
+import { LOAD_CAPABILITY_TOOL } from "../constants.js";
+import type { AgUiToolCall } from "../core/agui_client.js";
+
+/**
+ * The skill name a `load_capability` call activated, or `null` when the call is
+ * something else.
+ *
+ * Every deferred capability loads through this one tool, so the id is a skill
+ * name only when the project wired agent skills; another project's capability
+ * id surfaces here too. Acceptable for a muted notice, and better than a
+ * parallel signal — the id is exactly what the model selected.
+ */
+export function skillNameFrom(call: AgUiToolCall): string | null {
+  if (call.name !== LOAD_CAPABILITY_TOOL) {
+    return null;
+  }
+  const id = (call.args as { id?: unknown } | null | undefined)?.id;
+  return typeof id === "string" && id !== "" ? id : null;
+}

package/src/tools/chat_surface_tools.ts

@@ -0,0 +1,183 @@
+import { X_SUMMARY_KEY } from "../constants.js";
+import type { CollapseTarget } from "../ui/placement/surface_for.js";
+import type { ClientTool } from "./client_tool_registry.js";
+
+/** Every corner the panel can be sent to, in the order the schema states them. */
+export const CHAT_CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right"] as const;
+
+/** A corner the panel can be sent to. */
+export type ChatCorner = (typeof CHAT_CORNERS)[number];
+
+/** What the agent is told about the surface it is speaking from. */
+export interface ChatSurfaceReport {
+  /** The placement in force, or `null` when the host set none. */
+  readonly placement: string | null;
+  /**
+   * What the panel collapses to: `launcher`, `rail`, `header`, `bar` (the
+   * bottom bar it rises from), `none` (hidden, brought back by the host's own
+   * control), or `null` when it cannot collapse.
+   */
+  readonly collapseTo: CollapseTarget;
+  /** Whether the panel is currently collapsed. */
+  readonly collapsed: boolean;
+  /** Whether this placement has a collapsed state at all. */
+  readonly collapsible: boolean;
+  /**
+   * Whether the reader maximized the panel with its header control. Read-only:
+   * no tool changes it, and it is not kept across a reload.
+   */
+  readonly maximized: boolean;
+  /** Whether the panel can be moved, or the placement owns its position. */
+  readonly movable: boolean;
+  /**
+   * Whether this page allows the panel to be moved at all: true for every
+   * placement unless the host set `data-launcher-drag="false"`. It is the
+   * page's setting alone and does not vary with the placement or `collapse-to`;
+   * whether this panel moves is {@link ChatSurfaceReport.movable}. Kept apart because
+   * the two refusals need different sentences.
+   */
+  readonly draggable: boolean;
+  /** Whether the panel currently covers the whole viewport. */
+  readonly fullBleed: boolean;
+  /** The panel's box, in viewport coordinates. */
+  readonly box: {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  };
+  /**
+   * The part of the viewport the panel may rest in, with an origin: a host can reserve
+   * edges for its own chrome, so it is not always the screen's.
+   */
+  readonly viewport: {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  };
+}
+
+/** Whether a string names one of the four corners. */
+export function isChatCorner(value: string): value is ChatCorner {
+  return (CHAT_CORNERS as readonly string[]).includes(value);
+}
+
+/** The part of the widget these tools drive: a port, since the element imports this module. */
+export interface ChatSurface {
+  describeSurface(): ChatSurfaceReport;
+  /** `announce` writes a transcript notice with an undo; the tools always pass it. */
+  moveTo(corner: ChatCorner, options?: { readonly announce?: boolean }): boolean;
+  setCollapsed(collapsed: boolean, options?: { readonly announce?: boolean }): void;
+}
+
+/**
+ * Tools that let the agent move or collapse the panel it is speaking from.
+ *
+ * They report what happened, not what was asked: `move_chat` answers `moved: false`
+ * with the reason when the panel cannot move, rather than succeeding on a panel that
+ * did not budge.
+ */
+export function createChatSurfaceTools(surface: ChatSurface): ClientTool[] {
+  return [
+    {
+      name: "read_chat_surface",
+      description:
+        "Describe the chat panel you are speaking from: its placement, whether it is " +
+        "collapsed, whether it can be moved, and the box it occupies. Read this before " +
+        "moving or minimising yourself, since a full-screen panel has nowhere to move to. " +
+        "Read-only.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        [X_SUMMARY_KEY]: "Read the chat's own position",
+      },
+      handler: () => surface.describeSurface(),
+    },
+    {
+      name: "move_chat",
+      description:
+        "Move your own panel to a corner, to uncover something the user needs to see. " +
+        "`corner` is top-left, top-right, bottom-left or bottom-right. Answers " +
+        "`moved: false` with a reason when the placement owns its position or the panel " +
+        "fills the screen; check `read_chat_surface` first, and prefer minimise_chat when " +
+        "there is nowhere to move to.",
+      parameters: {
+        type: "object",
+        properties: {
+          corner: {
+            type: "string",
+            enum: [...CHAT_CORNERS],
+          },
+        },
+        required: ["corner"],
+        [X_SUMMARY_KEY]: "Move the chat out of the way",
+      },
+      handler: (args) => {
+        const asked = String(args["corner"] ?? "");
+        const report = surface.describeSurface();
+        // `required` is advisory: an unknown corner would send the panel bottom-right yet report success.
+        if (!isChatCorner(asked)) {
+          return {
+            moved: false,
+            reason: `"${asked}" is not a corner; use one of ${CHAT_CORNERS.join(", ")}`,
+          };
+        }
+        if (!report.movable) {
+          // A fact the agent can act on (minimise instead), not a malformed call.
+          return {
+            moved: false,
+            reason: report.fullBleed
+              ? "the panel fills the screen, so there is nowhere to move it to"
+              : report.draggable === false
+                ? "this page has turned off moving the panel"
+                : `the "${report.placement ?? ""}" placement owns the panel's position`,
+            suggestion: report.collapsible ? "minimise_chat" : null,
+          };
+        }
+        return { moved: surface.moveTo(asked, { announce: true }), corner: asked };
+      },
+    },
+    {
+      name: "minimise_chat",
+      description:
+        "Collapse your own panel, so the user can see the whole page. The user reopens " +
+        "it from where it collapsed to (a launcher, a rail, a bottom bar or the page's " +
+        "own control). Answers `minimised: false` when the placement has no collapsed " +
+        "state, which is the case for a full-page chat.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        [X_SUMMARY_KEY]: "Minimise the chat",
+      },
+      handler: () => {
+        const report = surface.describeSurface();
+        if (!report.collapsible) {
+          return {
+            minimised: false,
+            reason: "this placement has no collapsed state, so there is nothing to minimise to",
+          };
+        }
+        surface.setCollapsed(true, { announce: true });
+        return { minimised: true };
+      },
+    },
+    {
+      name: "restore_chat",
+      description: "Open your own panel again after minimising it.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        [X_SUMMARY_KEY]: "Restore the chat",
+      },
+      handler: () => {
+        // No notice: the user sees the panel come back.
+        surface.setCollapsed(false);
+        return { restored: true };
+      },
+    },
+  ];
+}

package/src/tools/client_tool_registry.ts

@@ -0,0 +1,80 @@
+import type { Tool } from "@ag-ui/core";
+
+/** Draws one call from its arguments alone; the replay path takes this, never a `handler`. */
+export type ChartRenderer = (args: Record<string, unknown>) => Node | null;
+
+/**
+ * A tool the frontend declares and executes itself.
+ *
+ * `parameters` is a JSON Schema (and may carry the `x-destructive` extension).
+ * `handler` receives the parsed arguments and returns a result that is
+ * JSON-serialised into the AG-UI tool-result message sent back to the agent.
+ */
+export interface ClientTool {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  /**
+   * Run the tool. `callId` identifies the call being executed, for a handler
+   * that renders into the transcript and needs to place itself against its own
+   * card; handlers that only act on the page ignore it.
+   */
+  handler: (args: Record<string, unknown>, callId?: string) => unknown | Promise<unknown>;
+  /**
+   * Draw this call, from its arguments alone.
+   *
+   * Optional, and the only half that is replayed: a restored transcript calls
+   * `render`, never {@link handler}, so a reload cannot re-run an effect.
+   *
+   * It runs again on every restore, so it must be:
+   *
+   * - a pure function of `args` — no host state, no network, no clock;
+   * - deterministic, so a reload reproduces what was there before;
+   * - free of effects outside the node it returns, which the component places.
+   *
+   * Return `null` for arguments that say nothing worth drawing.
+   */
+  render?: ChartRenderer;
+}
+
+/**
+ * Holds the frontend tools a host has declared on an `<ag-ui-chat>` element.
+ *
+ * Produces AG-UI {@link Tool} definitions for `RunAgentInput.tools` and looks
+ * up handlers when the agent calls a tool. Pure (no DOM); the element owns one
+ * instance.
+ */
+export class ClientToolRegistry {
+  readonly #tools = new Map<string, ClientTool>();
+
+  /**
+   * Register a tool, replacing any existing one with the same name.
+   *
+   * Replacing rather than throwing keeps a re-fired host ref or StrictMode double-invoke safe.
+   */
+  register(tool: ClientTool): void {
+    this.#tools.set(tool.name, tool);
+  }
+
+  has(name: string): boolean {
+    return this.#tools.has(name);
+  }
+
+  /** Return a registered tool or throw. */
+  get(name: string): ClientTool {
+    const tool = this.#tools.get(name);
+    if (tool === undefined) {
+      throw new Error(`tool "${name}" is not registered`);
+    }
+    return tool;
+  }
+
+  /** AG-UI tool definitions for `RunAgentInput.tools`. */
+  tools(): Tool[] {
+    return [...this.#tools.values()].map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    }));
+  }
+}

package/src/tools/is_destructive.ts

@@ -0,0 +1,17 @@
+import { X_DESTRUCTIVE_KEY } from "../constants.js";
+
+/**
+ * Whether a tool's JSON-Schema `parameters` marks it destructive.
+ *
+ * Reads the `x-destructive` extension off a schema the **host** declared —
+ * a tool passed to `registerTool`, or one of the built-ins. A server-side
+ * tool's schema never reaches the browser: tool definitions travel
+ * client-to-server on `RunAgentInput.tools`, and the only channel coming the
+ * other way is the tool catalog (`data-tools-url`), which carries labels, not
+ * schemas. So a server tool marked destructive there is not gated here, and
+ * must be gated server-side instead — the confirmation this flag drives is a
+ * property of tools the browser itself executes.
+ */
+export function isDestructive(parameters: Record<string, unknown>): boolean {
+  return parameters[X_DESTRUCTIVE_KEY] === true;
+}

package/src/tools/is_navigates.ts

@@ -0,0 +1,12 @@
+import { X_NAVIGATES_KEY } from "../constants.js";
+
+/**
+ * Whether a tool's JSON-Schema `parameters` marks it as navigating.
+ *
+ * Reads the `x-navigates` extension. A navigating tool's handler reloads the
+ * page (MPA navigation), so the element checkpoints the call and resumes the
+ * run loop after the next page mounts, rather than awaiting a result inline.
+ */
+export function isNavigates(parameters: Record<string, unknown>): boolean {
+  return parameters[X_NAVIGATES_KEY] === true;
+}