@alquimia-ai/tools 2.3.0 → 2.4.0

package/dist/actions-B0hfoYRd.d.ts

@@ -0,0 +1,57 @@
+import { S as SurfaceAction } from './types-DnfWUE9V.js';
+
+type UIActionKind = "agent-bound" | "local";
+interface UIAction {
+    surfaceId: string;
+    componentId: string;
+    action: string;
+    kind: UIActionKind;
+    payload?: Record<string, unknown>;
+}
+/**
+ * The `result` body posted to /event/tool-completion for an agent-bound action.
+ * Shape is part of the agent-facing contract — the prompt clause describes it.
+ */
+interface SurfaceResult {
+    /** The action's semantic name. */
+    action: string;
+    /** Which surface it came from. */
+    surfaceId: string;
+    /**
+     * The id of the component that was acted on. This is what lets the agent tell WHICH
+     * element fired when several share one action name — e.g. a grid of option cards that
+     * all use `selectFlight`. Without it the agent has to ask the user what they just
+     * clicked, which reads as a broken assistant.
+     */
+    componentId: string;
+    /** The surface's collected data model (empty object when the surface binds no fields). */
+    data: Record<string, unknown>;
+    /**
+     * Present only when the user declined the surface and answered in words instead
+     * (see `buildDismissResult`). Absent on a normal submit or selection.
+     */
+    userMessage?: string;
+}
+/**
+ * Action name reported when the user dismisses an interactive surface rather than using it.
+ * Kept distinct from any model-authored action so the agent can tell the two apart.
+ */
+declare const DISMISS_ACTION = "userDismissedSurface";
+/**
+ * Complete a pending interactive surface *negatively*, optionally carrying the natural-language
+ * reply the user typed instead of interacting.
+ *
+ * Why this exists: an interactive surface parks the inference until a tool result arrives. If
+ * the UI is the only way to answer, a user who doesn't want any of the offered options is stuck
+ * — they cannot type, and the task never resumes. Completing with this result unparks the
+ * conversation and hands the agent the user's actual words, so it can respond to them.
+ */
+declare function buildDismissResult(surfaceId: string, userMessage?: string): SurfaceResult;
+/** Build the tool-completion `result` for an agent-bound action. */
+declare function buildSurfaceResult(action: UIAction): SurfaceResult;
+/** Agent-bound actions (wantResponse) return their payload to the agent; others stay local. */
+declare function classifyAction(action: SurfaceAction): UIActionKind;
+/** Actions are semantic names, never URLs. Reject anything scheme- or protocol-relative. */
+declare function assertSafeActionName(name: string): void;
+
+export { DISMISS_ACTION as D, type SurfaceResult as S, type UIAction as U, type UIActionKind as a, assertSafeActionName as b, buildDismissResult as c, buildSurfaceResult as d, classifyAction as e };

package/dist/actions-CZU_GRy5.d.mts

@@ -0,0 +1,57 @@
+import { S as SurfaceAction } from './types-DnfWUE9V.mjs';
+
+type UIActionKind = "agent-bound" | "local";
+interface UIAction {
+    surfaceId: string;
+    componentId: string;
+    action: string;
+    kind: UIActionKind;
+    payload?: Record<string, unknown>;
+}
+/**
+ * The `result` body posted to /event/tool-completion for an agent-bound action.
+ * Shape is part of the agent-facing contract — the prompt clause describes it.
+ */
+interface SurfaceResult {
+    /** The action's semantic name. */
+    action: string;
+    /** Which surface it came from. */
+    surfaceId: string;
+    /**
+     * The id of the component that was acted on. This is what lets the agent tell WHICH
+     * element fired when several share one action name — e.g. a grid of option cards that
+     * all use `selectFlight`. Without it the agent has to ask the user what they just
+     * clicked, which reads as a broken assistant.
+     */
+    componentId: string;
+    /** The surface's collected data model (empty object when the surface binds no fields). */
+    data: Record<string, unknown>;
+    /**
+     * Present only when the user declined the surface and answered in words instead
+     * (see `buildDismissResult`). Absent on a normal submit or selection.
+     */
+    userMessage?: string;
+}
+/**
+ * Action name reported when the user dismisses an interactive surface rather than using it.
+ * Kept distinct from any model-authored action so the agent can tell the two apart.
+ */
+declare const DISMISS_ACTION = "userDismissedSurface";
+/**
+ * Complete a pending interactive surface *negatively*, optionally carrying the natural-language
+ * reply the user typed instead of interacting.
+ *
+ * Why this exists: an interactive surface parks the inference until a tool result arrives. If
+ * the UI is the only way to answer, a user who doesn't want any of the offered options is stuck
+ * — they cannot type, and the task never resumes. Completing with this result unparks the
+ * conversation and hands the agent the user's actual words, so it can respond to them.
+ */
+declare function buildDismissResult(surfaceId: string, userMessage?: string): SurfaceResult;
+/** Build the tool-completion `result` for an agent-bound action. */
+declare function buildSurfaceResult(action: UIAction): SurfaceResult;
+/** Agent-bound actions (wantResponse) return their payload to the agent; others stay local. */
+declare function classifyAction(action: SurfaceAction): UIActionKind;
+/** Actions are semantic names, never URLs. Reject anything scheme- or protocol-relative. */
+declare function assertSafeActionName(name: string): void;
+
+export { DISMISS_ACTION as D, type SurfaceResult as S, type UIAction as U, type UIActionKind as a, assertSafeActionName as b, buildDismissResult as c, buildSurfaceResult as d, classifyAction as e };

package/dist/genui/index.d.mts

@@ -3,7 +3,7 @@ export { S as SurfaceAction, T as ToolExecutionResponse } from '../types-DnfWUE9
 import { z } from 'zod';
 import { C as CatalogManifest, U as UIComponentDefinition } from '../registry-Bcu_ZYL1.mjs';
 export { a as UNKNOWN_COMPONENT, r as resolveComponent } from '../registry-Bcu_ZYL1.mjs';
-export { U as UIAction, a as UIActionKind, b as assertSafeActionName, c as classifyAction } from '../actions-Ca3ro-hX.mjs';
+export { D as DISMISS_ACTION, S as SurfaceResult, U as UIAction, a as UIActionKind, b as assertSafeActionName, c as buildDismissResult, d as buildSurfaceResult, e as classifyAction } from '../actions-CZU_GRy5.mjs';
 
 /**
  * The agent-facing "style vocabulary" — enum-constrained semantic props that let

package/dist/genui/index.d.ts

@@ -3,7 +3,7 @@ export { S as SurfaceAction, T as ToolExecutionResponse } from '../types-DnfWUE9
 import { z } from 'zod';
 import { C as CatalogManifest, U as UIComponentDefinition } from '../registry-Bcu_ZYL1.js';
 export { a as UNKNOWN_COMPONENT, r as resolveComponent } from '../registry-Bcu_ZYL1.js';
-export { U as UIAction, a as UIActionKind, b as assertSafeActionName, c as classifyAction } from '../actions-BebMyGqF.js';
+export { D as DISMISS_ACTION, S as SurfaceResult, U as UIAction, a as UIActionKind, b as assertSafeActionName, c as buildDismissResult, d as buildSurfaceResult, e as classifyAction } from '../actions-B0hfoYRd.js';
 
 /**
  * The agent-facing "style vocabulary" — enum-constrained semantic props that let

package/dist/genui/index.js

@@ -23,13 +23,16 @@ __export(genui_exports, {
   ALIGNS: () => ALIGNS,
   CORE_CATALOG_ID: () => CORE_CATALOG_ID,
   DENSITIES: () => DENSITIES,
+  DISMISS_ACTION: () => DISMISS_ACTION,
   EMPHASES: () => EMPHASES,
   SIZES: () => SIZES,
   TONES: () => TONES,
   UNKNOWN_COMPONENT: () => UNKNOWN_COMPONENT,
   assertSafeActionName: () => assertSafeActionName,
+  buildDismissResult: () => buildDismissResult,
   buildGenuiClause: () => buildGenuiClause,
   buildRenderUiSchema: () => buildRenderUiSchema,
+  buildSurfaceResult: () => buildSurfaceResult,
   classifyAction: () => classifyAction,
   coreCatalog: () => coreCatalog,
   coreCatalogJson: () => core_v1_catalog_default,
@@ -219,6 +222,25 @@ function setPointer(model, pointer, value) {
 }
 
 // src/genui/actions.ts
+var DISMISS_ACTION = "userDismissedSurface";
+function buildDismissResult(surfaceId, userMessage) {
+  const said = typeof userMessage === "string" ? userMessage.trim() : "";
+  return {
+    action: DISMISS_ACTION,
+    surfaceId,
+    componentId: "",
+    data: {},
+    ...said ? { userMessage: said } : {}
+  };
+}
+function buildSurfaceResult(action) {
+  return {
+    action: action.action,
+    surfaceId: action.surfaceId,
+    componentId: action.componentId,
+    data: action.payload ?? {}
+  };
+}
 function classifyAction(action) {
   return action.wantResponse === true ? "agent-bound" : "local";
 }
@@ -393,7 +415,9 @@ function buildGenuiClause(manifest, allowlist) {
     `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.",
+    "To collect input, add a Button with an action { name, wantResponse: true }. You get back { action, surfaceId, componentId, data } \u2014 `data` is the collected data model and `componentId` is the id of the component that was acted on. A surface with no such button is display-only.",
+    "When you render several options to choose from (a grid of cards, each with its own button), give every option component a MEANINGFUL id (e.g. flight-NH107, hotel-memmo-alfama): `componentId` tells you which one the user picked, so never ask them to repeat a choice they already made.",
+    'The user may ignore an interactive surface and just type instead. You then receive action "userDismissedSurface" with their words in `userMessage` \u2014 treat it as their reply, answer it directly, and do not re-render the same surface or scold them for not using it.',
     "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(" ");