@alquimia-ai/tools 2.1.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,501 @@ 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) {
+  return { taskId, status: "idle", answer: null, nodes: [], index: {}, raw: [] };
+}
+
+// src/worklog/registry.ts
+var asRecord = (data) => data && typeof data === "object" ? data : {};
+var toolTitle = (r) => {
+  const name = asRecord(r.data).name;
+  return typeof name === "string" && name.length > 0 ? `Tool: ${name}` : "Tool";
+};
+var agentTitle = (r) => {
+  const name = asRecord(r.data).name;
+  return typeof name === "string" && name.length > 0 ? `Agent: ${name}` : "Agent-to-agent";
+};
+var constTitle = (label) => () => label;
+var EVENT_REGISTRY = {
+  // Run envelope
+  AssistantInference: { kind: "answer", role: "run-open", title: constTitle("Inference started") },
+  AssistantInferenceResponse: { kind: "answer", role: "run-close", title: constTitle("Answer") },
+  // Safeguard
+  ShieldInference: { kind: "safeguard", role: "open", title: constTitle("Safeguard") },
+  ShieldInferenceResponse: { kind: "safeguard", role: "close", title: constTitle("Safeguard") },
+  // Reasoning
+  ResponseInference: { kind: "reasoning", role: "open", title: constTitle("Reasoning") },
+  ResponseInferenceResponse: { kind: "reasoning", role: "close", title: constTitle("Reasoning") },
+  // Tools (server + subclasses) and their responses
+  ServerToolExecution: { kind: "tool", role: "open", title: toolTitle },
+  BuiltinToolExecution: { kind: "tool", role: "open", title: toolTitle },
+  UnknownToolExecution: { kind: "tool", role: "open", title: toolTitle },
+  ClientToolExecution: { kind: "tool", role: "open", title: toolTitle, pending: true },
+  ToolExecutionResponse: { kind: "tool", role: "close", title: toolTitle },
+  BuiltinToolExecutionResponse: { kind: "tool", role: "close", title: toolTitle },
+  // Tool schema discovery
+  ToolSchema: { kind: "tool", role: "open", title: constTitle("Tool schema") },
+  ToolSchemaResponse: { kind: "tool", role: "close", title: constTitle("Tool schema") },
+  // Agent-to-agent
+  A2AInference: { kind: "a2a", role: "open", title: agentTitle },
+  AgentDiscovery: { kind: "a2a", role: "open", title: constTitle("Agent discovery") },
+  AgentDiscoveryResponse: { kind: "a2a", role: "close", title: constTitle("Agent discovery") },
+  // Memory / persistence
+  ContextPersistence: { kind: "memory", role: "open", title: constTitle("Memory persistence") },
+  ContextFlush: { kind: "memory", role: "open", title: constTitle("Memory flush") },
+  ContextFlushResponse: { kind: "memory", role: "close", title: constTitle("Memory flush") },
+  // Human approval
+  HumanApprovalRequired: {
+    kind: "tool",
+    role: "open",
+    title: constTitle("Human approval required"),
+    pending: true
+  },
+  HumanApprovalRequiredResponse: { kind: "tool", role: "close", title: constTitle("Human approval") }
+};
+function resolveInterpreter(eventClass) {
+  if (Object.prototype.hasOwnProperty.call(EVENT_REGISTRY, eventClass)) {
+    return EVENT_REGISTRY[eventClass];
+  }
+  return {
+    kind: "unknown",
+    role: "open",
+    title: (r) => r.event_class
+  };
+}
+
+// src/worklog/reducer.ts
+var asString = (v) => typeof v === "string" ? v : v == null ? "" : JSON.stringify(v);
+var nodeDepth = (record) => {
+  const d = record.data && typeof record.data === "object" ? record.data.depth : void 0;
+  return typeof d === "number" ? d : 0;
+};
+var makeOpenNode = (record, interp, id) => ({
+  id,
+  kind: interp.kind,
+  eventClass: record.event_class,
+  status: interp.pending ? "pending" : "running",
+  title: interp.title(record),
+  startedAt: record.date_submitted,
+  depth: nodeDepth(record),
+  children: [],
+  command: record.data,
+  raw: [record]
+});
+var makeClosedNode = (record, interp, id) => ({
+  id,
+  kind: interp.kind,
+  eventClass: record.event_class,
+  status: record.status === "error" ? "failed" : "completed",
+  title: interp.title(record),
+  startedAt: record.date_submitted,
+  endedAt: record.date_submitted,
+  depth: nodeDepth(record),
+  children: [],
+  response: record.data,
+  error: record.status === "error" ? asString(record.data) : void 0,
+  raw: [record]
+});
+function reduceWorklog(state, record) {
+  const interp = resolveInterpreter(record.event_class);
+  const next = {
+    ...state,
+    nodes: state.nodes.slice(),
+    index: { ...state.index },
+    raw: [...state.raw, record]
+  };
+  if (interp.role === "ignore") return next;
+  if (interp.role === "run-open") {
+    next.status = "running";
+    return next;
+  }
+  if (interp.role === "run-close") {
+    next.answer = asString(record.data) || null;
+    next.status = record.status === "error" ? "error" : "success";
+    return next;
+  }
+  const key = record.control_id ?? `${record.event_class}-${next.raw.length}`;
+  if (interp.role === "close") {
+    const pos2 = Object.prototype.hasOwnProperty.call(next.index, key) ? next.index[key] : void 0;
+    if (pos2 != null) {
+      const existing = next.nodes[pos2];
+      next.nodes[pos2] = {
+        ...existing,
+        status: record.status === "error" ? "failed" : "completed",
+        endedAt: record.date_submitted,
+        response: record.data,
+        error: record.status === "error" ? asString(record.data) : existing.error,
+        raw: [...existing.raw, record]
+      };
+    } else {
+      next.index[key] = next.nodes.length;
+      next.nodes.push(makeClosedNode(record, interp, key));
+    }
+    if (record.status === "error") next.status = "error";
+    return next;
+  }
+  const pos = Object.prototype.hasOwnProperty.call(next.index, key) ? next.index[key] : void 0;
+  if (pos != null) {
+    const existing = next.nodes[pos];
+    next.nodes[pos] = { ...existing, raw: [...existing.raw, record] };
+  } else {
+    next.index[key] = next.nodes.length;
+    next.nodes.push(makeOpenNode(record, interp, key));
+  }
+  return next;
+}
+
+// src/worklog/use-worklog.ts
+import { useCallback, useReducer } from "react";
+
+// src/worklog/from-frame.ts
+function frameToRecord(frame) {
+  const status = frame.status === "success" || frame.status === "error" ? frame.status : null;
+  return {
+    event_class: typeof frame.event_class === "string" && frame.event_class.length > 0 ? frame.event_class : "Unknown",
+    control_id: frame.control_id ?? null,
+    data: frame.data,
+    status,
+    date_submitted: typeof frame.date_submitted === "string" ? frame.date_submitted : ""
+  };
+}
+
+// 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) {
@@ -314,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("");
@@ -329,8 +859,29 @@ function useAlquimia(config) {
   const [activeTool, setActiveTool] = useState(null);
   const [lastRequest, setLastRequest] = useState(null);
   const [hasThinkings, setHasThinkings] = useState(false);
+  const worklogEnabled = config.options?.worklog ?? false;
+  const [worklog, setWorklog] = useState(
+    worklogEnabled ? initialWorklogState() : void 0
+  );
   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([]);
@@ -534,6 +1085,7 @@ function useAlquimia(config) {
         lastMessageAt: null,
         closedByClient: false
       };
+      if (worklogEnabled) setWorklog(initialWorklogState());
       const eventSource = new EventSource(streamUrl);
       eventSourceRef.current = eventSource;
       eventSource.onopen = () => {
@@ -594,6 +1146,14 @@ function useAlquimia(config) {
   }
   function handleMessageEvent(event, callBack, eventSource, streamState) {
     const data = JSON.parse(event.data);
+    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) {
@@ -623,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,
@@ -651,6 +1279,7 @@ function useAlquimia(config) {
     setLastRequest,
     setIsAudioRecording,
     hasThinkings,
+    worklog,
     attachments,
     addAttachment,
     addAttachments,
@@ -661,7 +1290,7 @@ function useAlquimia(config) {
 }
 
 // src/hooks/useRatings.ts
-import { useState as useState2, useReducer } from "react";
+import { useState as useState2, useReducer as useReducer2 } from "react";
 var initialState = {
   ratingStars: 0,
   ratingThumbs: "",
@@ -682,7 +1311,7 @@ function ratingReducer(state, action) {
 function useRatings({ assistantId, sendRating, topicId }) {
   const [isLoading, setIsLoading] = useState2(false);
   const [hasReviewed, setHasReviewed] = useState2(false);
-  const [state, dispatch] = useReducer(ratingReducer, initialState);
+  const [state, dispatch] = useReducer2(ratingReducer, initialState);
   const setRatingStars = (rating) => {
     dispatch({ type: "SET_RATING_STARS", payload: rating });
   };