@alquimia-ai/tools 2.2.0 → 2.3.0

package/dist/hooks/index.mjs

@@ -1,5 +1,5 @@
 // src/hooks/alquimia.hook.tsx
-import { useMemo, useRef, useState } from "react";
+import { useCallback as useCallback2, useEffect, useMemo, useRef, useState } from "react";
 
 // src/sdk/alquimia-sdk.ts
 import axios from "axios";
@@ -139,6 +139,32 @@ var AlquimiaSDK = class {
     this.attachments = [];
     return this;
   }
+  /**
+   * Complete a pending client-tool execution (the missing "submit half" of the
+   * client-tool loop). POSTs a {@link ToolExecutionResponse} to the runtime's
+   * `/event/tool-completion`. For interactive `render_ui` surfaces `result` is
+   * the user's data; for display-only surfaces the SDK sends `{ shown: true }`.
+   * The pending call is correlated by `control_id` in the body + the
+   * `context-metadata` header (taskid + sessionid).
+   */
+  async submitToolResult(response) {
+    const url = this.adapter.resolveToolCompletionUrl?.();
+    if (!url) {
+      throw new Error(
+        "AlquimiaSDK: adapter does not support tool completion (resolveToolCompletionUrl missing)"
+      );
+    }
+    const adapterHeaders = this.adapter.getHeaders?.() ?? {};
+    const headers = {
+      "Content-Type": "application/json",
+      assistantid: this.assistantId,
+      ...this.streamId && { taskid: this.streamId },
+      ...this.conversationId && { sessionid: this.conversationId },
+      ...this.userId && { userid: this.userId },
+      ...adapterHeaders
+    };
+    await this.axiosInstance.post(url, response, { headers });
+  }
   async generateImage(query) {
     if (!this.stableDiffusionProvider) {
       throw new Error("Stable Diffusion provider not initialized");
@@ -300,6 +326,9 @@ function mergeToolEvents(initial, toolEvents) {
     initial
   );
 }
+function resolveGenuiAllow(catalog, allow) {
+  return !allow || allow === "all" ? Object.keys(catalog.components) : allow;
+}
 
 // src/worklog/types.ts
 function initialWorklogState(taskId = null) {
@@ -461,6 +490,338 @@ function frameToRecord(frame) {
   };
 }
 
+// src/hooks/pending-client-tool.ts
+function extractPendingClientTool(frame) {
+  if (!frame || typeof frame !== "object") return null;
+  const f = frame;
+  if (f.event_class !== "ClientToolExecution") return null;
+  const name = f.data?.name;
+  const parameters = f.data?.parameters;
+  const controlId = f.control_id;
+  if (typeof name !== "string" || parameters === void 0 || typeof controlId !== "string") return null;
+  return { controlId, toolName: name, parameters };
+}
+
+// src/genui/style.ts
+import { z } from "zod";
+var TONES = ["default", "muted", "primary", "success", "warning", "danger"];
+var SIZES = ["sm", "md", "lg"];
+var EMPHASES = ["low", "medium", "high"];
+var ALIGNS = ["start", "center", "end"];
+var DENSITIES = ["compact", "comfortable"];
+var styleSchemaShape = {
+  tone: z.enum(TONES).optional(),
+  size: z.enum(SIZES).optional(),
+  emphasis: z.enum(EMPHASES).optional(),
+  align: z.enum(ALIGNS).optional(),
+  density: z.enum(DENSITIES).optional()
+};
+
+// src/genui/registry.ts
+function resolveComponent(manifest, name) {
+  if (!name || typeof name !== "string") return null;
+  return manifest.components[name] ?? null;
+}
+
+// src/genui/catalog.ts
+import { z as z2 } from "zod";
+var CORE_CATALOG_ID = "https://alquimia.ai/catalogs/core/v1/catalog.json";
+var def = (name, own, opts) => ({
+  name,
+  schema: z2.object({
+    ...styleSchemaShape,
+    ...opts?.variant ? { variant: z2.enum(opts.variant).optional() } : {},
+    ...own
+  }).passthrough(),
+  allowedActions: opts?.allowedActions
+});
+var option = z2.object({ label: z2.string(), value: z2.union([z2.string(), z2.number()]) });
+var coreCatalog = {
+  id: CORE_CATALOG_ID,
+  components: {
+    // ---- layout ----
+    Stack: def("Stack", {
+      direction: z2.enum(["vertical", "horizontal"]).optional(),
+      gap: z2.enum(["sm", "md", "lg"]).optional()
+    }),
+    Grid: def("Grid", {
+      columns: z2.number().int().min(1).max(6).optional(),
+      gap: z2.enum(["sm", "md", "lg"]).optional()
+    }),
+    Row: def("Row", { gap: z2.enum(["sm", "md", "lg"]).optional(), wrap: z2.boolean().optional() }),
+    Column: def("Column", { gap: z2.enum(["sm", "md", "lg"]).optional() }),
+    Divider: def("Divider", { label: z2.string().optional() }),
+    Spacer: def("Spacer", { size: z2.enum(["sm", "md", "lg"]).optional() }),
+    Card: def("Card", { title: z2.string().optional(), description: z2.string().optional() }, {
+      variant: ["elevated", "outline", "ghost"]
+    }),
+    Accordion: def("Accordion", {
+      items: z2.array(z2.object({ title: z2.string(), value: z2.string() })).optional()
+    }),
+    Tabs: def("Tabs", { tabs: z2.array(z2.object({ label: z2.string(), value: z2.string() })).min(1) }),
+    // ---- content ----
+    Text: def("Text", { text: z2.string() }, { variant: ["body", "muted", "caption", "lead"] }),
+    Heading: def("Heading", { text: z2.string(), level: z2.number().int().min(1).max(4).optional() }),
+    Markdown: def("Markdown", { text: z2.string() }),
+    Image: def("Image", { src: z2.string(), alt: z2.string().optional() }),
+    Icon: def("Icon", { name: z2.string() }),
+    Badge: def("Badge", { text: z2.string() }, { variant: ["solid", "outline", "subtle"] }),
+    Avatar: def("Avatar", { src: z2.string().optional(), fallback: z2.string().optional() }),
+    Alert: def("Alert", { text: z2.string(), title: z2.string().optional() }, {
+      variant: ["info", "success", "warning", "danger"]
+    }),
+    Stat: def("Stat", { label: z2.string(), value: z2.union([z2.string(), z2.number()]), delta: z2.string().optional() }),
+    KeyValue: def("KeyValue", {}),
+    List: def("List", { ordered: z2.boolean().optional() }),
+    Quote: def("Quote", { text: z2.string(), cite: z2.string().optional() }),
+    // ---- inputs ----
+    TextField: def("TextField", { label: z2.string().optional(), placeholder: z2.string().optional() }),
+    TextArea: def("TextArea", {
+      label: z2.string().optional(),
+      placeholder: z2.string().optional(),
+      rows: z2.number().int().optional()
+    }),
+    NumberField: def("NumberField", {
+      label: z2.string().optional(),
+      min: z2.number().optional(),
+      max: z2.number().optional(),
+      step: z2.number().optional()
+    }),
+    Select: def("Select", {
+      label: z2.string().optional(),
+      placeholder: z2.string().optional(),
+      options: z2.array(option).min(1)
+    }),
+    MultiSelect: def("MultiSelect", { label: z2.string().optional(), options: z2.array(option).min(1) }),
+    Combobox: def("Combobox", {
+      label: z2.string().optional(),
+      placeholder: z2.string().optional(),
+      options: z2.array(option).min(1)
+    }),
+    Checkbox: def("Checkbox", { label: z2.string().optional() }),
+    CheckboxGroup: def("CheckboxGroup", { label: z2.string().optional(), options: z2.array(option).min(1) }),
+    Radio: def("Radio", { label: z2.string().optional(), options: z2.array(option).min(1) }),
+    Switch: def("Switch", { label: z2.string().optional() }),
+    Slider: def("Slider", {
+      label: z2.string().optional(),
+      min: z2.number().optional(),
+      max: z2.number().optional(),
+      step: z2.number().optional()
+    }),
+    DatePicker: def("DatePicker", { label: z2.string().optional() }),
+    DateRange: def("DateRange", { label: z2.string().optional() }),
+    FileUpload: def("FileUpload", {
+      label: z2.string().optional(),
+      accept: z2.string().optional(),
+      multiple: z2.boolean().optional()
+    }),
+    Rating: def("Rating", { label: z2.string().optional(), max: z2.number().int().optional() }),
+    // ---- data ----
+    Table: def("Table", {
+      columns: z2.array(z2.object({ key: z2.string(), header: z2.string().optional() })).min(1),
+      sortable: z2.boolean().optional()
+    }, { allowedActions: ["sort", "filter"] }),
+    Chart: def("Chart", {
+      kind: z2.enum(["bar", "line", "area", "pie"]),
+      x: z2.string().optional(),
+      series: z2.array(z2.object({ key: z2.string(), label: z2.string().optional() })).min(1),
+      title: z2.string().optional()
+    }),
+    Progress: def("Progress", { value: z2.number(), max: z2.number().optional(), label: z2.string().optional() }),
+    Timeline: def("Timeline", {
+      items: z2.array(z2.object({ title: z2.string(), description: z2.string().optional(), timestamp: z2.string().optional() })).min(1)
+    }),
+    // ---- actions ----
+    Button: def("Button", { text: z2.string() }, {
+      variant: ["solid", "outline", "ghost", "link"],
+      allowedActions: ["submit", "cancel", "reset", "select", "confirm"]
+    }),
+    ButtonGroup: def("ButtonGroup", {}),
+    Link: def("Link", { text: z2.string(), href: z2.string().optional() })
+  }
+};
+
+// src/genui/actions.ts
+var URL_LIKE = /^\s*([a-z][a-z0-9+.-]*:|\/\/)/i;
+function assertSafeActionName(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("action.name must be a non-empty string");
+  }
+  if (URL_LIKE.test(name)) {
+    throw new Error(`action.name must be a semantic name, not a URL: ${name}`);
+  }
+}
+
+// src/genui/validate.ts
+import { z as z3 } from "zod";
+var surfaceShape = z3.object({
+  surfaceId: z3.string().min(1),
+  // Tier 2 canonical id (versioned URI); `catalog` is the legacy alias. Both optional on the
+  // wire — the SDK stamps `catalogId` if the agent omits it.
+  catalogId: z3.string().min(1).optional(),
+  catalog: z3.string().min(1).optional(),
+  // Legacy explicit root. A2UI uses the component with id "root"; kept optional for back-compat.
+  root: z3.string().min(1).optional(),
+  components: z3.array(
+    z3.object({
+      id: z3.string().min(1),
+      component: z3.string().min(1),
+      children: z3.array(z3.string()).optional(),
+      child: z3.string().optional(),
+      binding: z3.string().optional(),
+      action: z3.object({ name: z3.string(), wantResponse: z3.boolean().optional() }).optional()
+    }).passthrough()
+  ),
+  dataModel: z3.record(z3.unknown()).optional()
+});
+var UAX31_ID = /^[\p{XID_Start}_][\p{XID_Continue}]*$/u;
+function validateProps(node, def2) {
+  const { id, component, children, child, binding, action, ...props } = node;
+  const parsed = def2.schema.safeParse(props);
+  if (parsed.success) return { ok: true, value: parsed.data, errors: [] };
+  return {
+    ok: false,
+    errors: parsed.error.issues.map((i) => ({ path: `${id}.${i.path.join(".")}`, message: i.message }))
+  };
+}
+function validateSurface(input, manifest) {
+  const shape = surfaceShape.safeParse(input);
+  if (!shape.success) {
+    return { ok: false, errors: shape.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })) };
+  }
+  const surface = shape.data;
+  const errors = [];
+  const warnings = [];
+  const ids = new Set(surface.components.map((c) => c.id));
+  const rootId = ids.has("root") ? "root" : surface.root;
+  if (!rootId || !ids.has(rootId)) {
+    errors.push({ path: "root", message: `no root component (expected a component with id "root")` });
+  }
+  if (!surface.catalogId && !surface.catalog) {
+    warnings.push({ path: "catalogId", message: "surface has no catalogId (SDK will stamp the active catalog)" });
+  }
+  for (const node of surface.components) {
+    if (!UAX31_ID.test(node.id)) {
+      warnings.push({ path: node.id, message: `id "${node.id}" is not a valid UAX#31 identifier` });
+    }
+    const def2 = resolveComponent(manifest, node.component);
+    if (!def2) {
+      warnings.push({ path: node.id, message: `unknown component "${node.component}" (renders as text)` });
+      continue;
+    }
+    warnings.push(...validateProps(node, def2).errors);
+    for (const childId of node.children ?? []) {
+      if (!ids.has(childId)) {
+        warnings.push({ path: node.id, message: `child "${childId}" does not exist (skipped)` });
+      }
+    }
+    if (node.child && !ids.has(node.child)) {
+      warnings.push({ path: node.id, message: `child "${node.child}" does not exist (skipped)` });
+    }
+    if (node.action) {
+      try {
+        assertSafeActionName(node.action.name);
+      } catch (e) {
+        errors.push({ path: `${node.id}.action`, message: e.message });
+      }
+    }
+  }
+  return errors.length === 0 ? { ok: true, value: surface, errors: [], warnings } : { ok: false, errors, warnings };
+}
+
+// src/genui/tool-schema.ts
+var DESCRIPTION = 'Render a UI using A2UI. The arguments are a UI surface, NOT free-form. Shape: { surfaceId, root, components, dataModel? }. `components` is a FLAT array; every item is { id, component, children?, ...props } where `component` is one of the allowed names (use `component`, never `type`) and `children` is an array of string ids referencing other items (never nested objects). Inputs bind to the data model via `binding` (a JSON Pointer like "/name"). To collect input, include a Button with action { name, wantResponse: true } \u2014 its result (the data model) is returned to you; a surface with no such button is display-only. Example: { "surfaceId": "signup", "root": "root", "components": [ { "id": "root", "component": "Stack", "children": ["name", "desc", "submit"] }, { "id": "name", "component": "TextField", "label": "Username", "binding": "/name" }, { "id": "desc", "component": "TextField", "label": "Description", "binding": "/description" }, { "id": "submit", "component": "Button", "text": "Save", "action": { "name": "save", "wantResponse": true } } ], "dataModel": { "name": "", "description": "" } }. IMPORTANT: when you call render_ui, the rendered surface IS your reply \u2014 do NOT also reproduce its content as text, markdown, or ASCII. Any accompanying message must be a brief one-line intro at most, never a duplicate of the UI.';
+function buildRenderUiSchema(manifest, allowlist) {
+  const allowed = allowlist.filter((name) => name in manifest.components);
+  return {
+    title: "render_ui",
+    name: "render_ui",
+    description: DESCRIPTION,
+    type: "object",
+    properties: {
+      surfaceId: { type: "string" },
+      // A2UI catalog id — a versioned URI. `const` nudges the model to echo it; the SDK
+      // also stamps it if omitted, so the client always knows which catalog version to render.
+      catalogId: { type: "string", const: manifest.id },
+      catalog: { type: "string" },
+      // legacy alias (accepted, ignored)
+      root: { type: "string" },
+      // legacy explicit root (accepted; A2UI uses the id:"root" component)
+      components: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            id: { type: "string" },
+            component: { type: "string", enum: allowed },
+            children: { type: "array", items: { type: "string" } },
+            child: { type: "string" },
+            binding: { type: "string" },
+            action: {
+              type: "object",
+              properties: {
+                name: { type: "string" },
+                wantResponse: { type: "boolean" }
+              },
+              required: ["name"]
+            },
+            tone: { type: "string", enum: [...TONES] },
+            size: { type: "string", enum: [...SIZES] },
+            emphasis: { type: "string", enum: [...EMPHASES] },
+            align: { type: "string", enum: [...ALIGNS] },
+            density: { type: "string", enum: [...DENSITIES] },
+            variant: { type: "string" },
+            text: { type: "string" },
+            label: { type: "string" },
+            placeholder: { type: "string" },
+            title: { type: "string" },
+            direction: { type: "string" },
+            gap: { type: "string" },
+            // Data props for data components. Several are legitimately polymorphic across
+            // components — type them as their real unions so the runtime doesn't reject
+            // valid output (adapters normalize each shape):
+            //   data:    array (Chart/Table rows) | object (KeyValue)
+            //   rows:    array (Table)            | number (TextArea row count)
+            //   columns: array (Table col defs)   | number (Grid column count)
+            data: { type: ["array", "object"] },
+            rows: { type: ["array", "number"] },
+            items: { type: "array" },
+            // Accept string OR object items — models routinely emit the terse string
+            // form (e.g. series:["revenue"], options:["A","B"]); adapters normalize.
+            columns: { type: ["array", "number"], items: { type: ["object", "string"] } },
+            series: { type: "array", items: { type: ["object", "string"] } },
+            options: { type: "array", items: { type: ["object", "string"] } },
+            kind: { type: "string" },
+            x: { type: "string" },
+            value: {}
+          },
+          required: ["id", "component"]
+        }
+      },
+      dataModel: { type: "object" }
+    },
+    required: ["surfaceId", "root", "components"],
+    additionalProperties: false
+  };
+}
+
+// src/genui/clause.ts
+function buildGenuiClause(manifest, allowlist) {
+  const names = allowlist.filter((n) => n in manifest.components);
+  return [
+    "You can render UI by calling render_ui with an A2UI surface (a flat components array; each item is { id, component, children?, ...props }; component is one of the allowed names; children are string ids referencing other items).",
+    `Components: ${names.join(", ")}.`,
+    `Style each component via the semantic vocabulary (never CSS, colors, or HTML): tone (${TONES.join("/")}), size (${SIZES.join("/")}), emphasis (low/medium/high), align (start/center/end), density (compact/comfortable), plus a component-specific variant where offered.`,
+    "Data components MUST carry their data: Chart takes `data` (an array of row objects) + `series` (keys to plot) + `x` (the category key); Table takes `rows` (array of row objects) + `columns` ([{ key, header }] matching the row keys); List takes `items` (array); Stat takes `label`+`value`; KeyValue takes `data` (an object). Put the data inline on the component (or in dataModel referenced via `binding`).",
+    "To collect input, add a Button with an action { name, wantResponse: true }; its result (the data model) is returned to you. A surface with no such button is display-only.",
+    "IMPORTANT: the rendered surface IS your reply \u2014 do NOT reproduce its content as text, markdown, or ASCII; a one-line intro at most.",
+    "Prefer plain text for simple replies."
+  ].join(" ");
+}
+
+// src/genui/emit.ts
+import { zodToJsonSchema } from "zod-to-json-schema";
+
 // src/hooks/alquimia.hook.tsx
 function useAlquimia(config) {
   const sdk = useMemo(() => {
@@ -474,6 +835,15 @@ function useAlquimia(config) {
     if (config.providers?.logger) instance.withLoggerProvider(config.providers.logger);
     if (config.options?.userId) instance.withUserId(config.options.userId);
     if (config.options?.extraInstructions) instance.withExtraInstructions(config.options.extraInstructions);
+    if (config.genui && (config.genui.source ?? "client") === "client") {
+      const cat = config.genui.catalog ?? coreCatalog;
+      const allow = resolveGenuiAllow(cat, config.genui.allow);
+      instance.withTools([buildRenderUiSchema(cat, allow)]);
+      instance.withExtraInstructions({
+        ...config.options?.extraInstructions ?? {},
+        genui: buildGenuiClause(cat, allow)
+      });
+    }
     return instance;
   }, [config.assistantId, config.adapter]);
   const [input, setInput] = useState("");
@@ -495,6 +865,23 @@ function useAlquimia(config) {
   );
   const [attachments, setAttachments] = useState([]);
   const [isUploadingAttachments, setIsUploadingAttachments] = useState(false);
+  const [pendingClientTool, setPendingClientTool] = useState(null);
+  const completedToolsRef = useRef(/* @__PURE__ */ new Set());
+  const genuiCatalog = config.genui?.catalog ?? coreCatalog;
+  const [genuiSurfaces, setGenuiSurfaces] = useState([]);
+  const messagesLenRef = useRef(0);
+  messagesLenRef.current = messages.length;
+  const genuiAnchorRef = useRef(0);
+  {
+    let anchor = messages.length;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i].role === "user") {
+        anchor = i + 1;
+        break;
+      }
+    }
+    genuiAnchorRef.current = anchor;
+  }
   const isLoading = isMessageLoading || isStreamingLoading || isUploadingAttachments;
   function cleanMessages() {
     setMessages([]);
@@ -762,6 +1149,11 @@ function useAlquimia(config) {
     if (worklogEnabled) {
       setWorklog((prev) => reduceWorklog(prev ?? initialWorklogState(), frameToRecord(data)));
     }
+    const pending = extractPendingClientTool(data);
+    if (pending) {
+      setPendingClientTool(pending);
+      return;
+    }
     const eventTaskId = data.taskid || "";
     if (data.errors?.length) {
       for (const error of data.errors) {
@@ -791,9 +1183,77 @@ function useAlquimia(config) {
       cleanup(false, eventSource);
     }
   }
+  const completeToolExecution = useCallback2(
+    async (controlId, result) => {
+      if (completedToolsRef.current.has(controlId)) return;
+      completedToolsRef.current.add(controlId);
+      try {
+        await sdk.submitToolResult({ ...result, control_id: controlId });
+        setPendingClientTool((cur) => cur?.controlId === controlId ? null : cur);
+      } catch (err) {
+        completedToolsRef.current.delete(controlId);
+        throw err;
+      }
+    },
+    [sdk]
+  );
+  useEffect(() => {
+    if (!config.genui) return;
+    if (!pendingClientTool || pendingClientTool.toolName !== "render_ui") return;
+    const { controlId } = pendingClientTool;
+    const parameters = pendingClientTool.parameters && typeof pendingClientTool.parameters === "object" ? { catalogId: genuiCatalog.id, ...pendingClientTool.parameters } : pendingClientTool.parameters;
+    const res = validateSurface(parameters, genuiCatalog);
+    if (!res.ok || !res.value) {
+      void completeToolExecution(controlId, {
+        control_id: controlId,
+        tool_name: "render_ui",
+        status: "error",
+        message: "Surface failed client validation: " + res.errors.map((e) => `${e.path} ${e.message}`).join("; "),
+        result: { errors: res.errors }
+      });
+      return;
+    }
+    const surface = res.value;
+    setGenuiSurfaces(
+      (prev) => prev.some((s) => s.controlId === controlId) ? prev : [...prev, { controlId, surface, afterCount: genuiAnchorRef.current }]
+    );
+    const interactive = surface.components.some((c) => c.action?.wantResponse === true);
+    if (!interactive) {
+      void completeToolExecution(controlId, {
+        control_id: controlId,
+        tool_name: "render_ui",
+        status: "success",
+        result: {
+          shown: true,
+          instruction: "The UI is rendered and visible to the user. Do NOT restate it as text/markdown/ASCII; reply with at most one short sentence."
+        }
+      });
+    }
+  }, [pendingClientTool, completeToolExecution, config.genui]);
+  const genuiOnAgentAction = useCallback2(
+    (controlId) => (action) => {
+      setGenuiSurfaces(
+        (prev) => prev.map((s) => s.controlId === controlId ? { ...s, submitted: true } : s)
+      );
+      void completeToolExecution(controlId, {
+        control_id: controlId,
+        tool_name: "render_ui",
+        status: "success",
+        result: { action: action.action, surfaceId: action.surfaceId, data: action.payload }
+      });
+    },
+    [completeToolExecution]
+  );
+  const genuiAwaitingUser = !!(pendingClientTool && pendingClientTool.toolName === "render_ui" && genuiSurfaces.some(
+    (s) => s.controlId === pendingClientTool.controlId && s.surface.components.some((c) => c.action?.wantResponse === true)
+  ));
+  const genui = config.genui ? { surfaces: genuiSurfaces, onAgentAction: genuiOnAgentAction, awaitingUser: genuiAwaitingUser } : void 0;
   return {
     sdk,
     activeTool,
+    pendingClientTool,
+    completeToolExecution,
+    genui,
     cleanMessages,
     createMessageId,
     handleInputChange,