@alquimia-ai/tools 2.7.0 → 2.8.0

package/dist/hooks/index.d.ts

@@ -1,11 +1,13 @@
 import * as react from 'react';
 import { AlquimiaSDK } from '../sdk/index.js';
 import { AlquimiaAdapter } from '../adapters/index.js';
-import { W as WhisperProvider, S as StableDiffusionProvider, C as CharacterizationProvider, R as RatingsProvider, L as LoggerProvider } from '../providers-mx21gNgZ.js';
-import { G as GenuiSurfaceItem, e as AlquimiaMessage, F as ToolEvent, a as AIMessageChunk, R as RatingData } from '../type-D-JaSMkV.js';
-import { T as ToolExecutionResponse } from '../types-CMVbyEv8.js';
-import { a as WorklogState } from '../types-lOliroPw.js';
+import { W as WhisperProvider, S as StableDiffusionProvider, C as CharacterizationProvider, R as RatingsProvider, L as LoggerProvider } from '../providers-J_Z9rQ3Q.js';
+import { G as GenuiSurfaceItem, a as AlquimiaMessage, b as ToolEvent, c as AIMessageChunk, R as RatingData } from '../type-BFtGEEb4.js';
+import { ToolApprovalResult } from '../types/index.js';
 import { createMessageId } from '../utils/index.js';
+import { a as WorklogState } from '../types-lOliroPw.js';
+import { A as ApprovalRequest } from '../approvals-CcnmqUkQ.js';
+import { T as ToolExecutionResponse } from '../types-CMVbyEv8.js';
 import { C as CatalogManifest } from '../registry-Bcu_ZYL1.js';
 import { U as UIAction } from '../actions-CP1d4Ye1.js';
 import '@elastic/apm-rum';
@@ -40,11 +42,40 @@ interface UseAlquimiaConfig {
         source?: 'client' | 'agent';
     };
 }
+/**
+ * A human-approval gate as the hook exposes it: what the worklog says, overlaid
+ * with this client's own submission.
+ */
+interface ToolApproval extends ApprovalRequest {
+    /**
+     * `pending` until someone decides; `submitting` while this client's call is
+     * in flight; `approved`/`rejected` once the runtime accepted a decision —
+     * this client's (optimistically, before the stream confirms) or anyone's.
+     */
+    status: 'pending' | 'submitting' | 'approved' | 'rejected';
+    /** Rejection reason, from the worklog or from this client's submission. */
+    reason: string | null;
+    /** `true` when the accepted decision was made from this client. */
+    decidedHere: boolean;
+    /**
+     * Whether offering Approve / Reject here can still work. `false` for a
+     * channel-owned gate, and after the runtime refused this client with a 409,
+     * 403 or 404 — retrying those can only fail the same way.
+     */
+    canAnswer: boolean;
+    /** The runtime's answer to this client's last submission, if any. */
+    lastResult: ToolApprovalResult | null;
+    /** Message count the gate was raised after, for anchoring it in the chat. */
+    afterCount: number;
+}
 declare function useAlquimia(config: UseAlquimiaConfig): {
     sdk: AlquimiaSDK;
     activeTool: any;
     pendingClientTool: PendingClientTool | null;
     completeToolExecution: (controlId: string, result: ToolExecutionResponse) => Promise<void>;
+    toolApprovals: ToolApproval[];
+    pendingApprovals: ToolApproval[];
+    approveTool: (controlId: string, approved: boolean, message?: string) => Promise<ToolApprovalResult>;
     genui: {
         surfaces: GenuiSurfaceItem[];
         onAgentAction: (controlId: string) => (action: UIAction) => void;
@@ -105,4 +136,4 @@ declare function useRatings({ assistantId, sendRating, topicId, onError }: UseRa
     hasReviewed: boolean;
 };
 
-export { useAlquimia, useRatings };
+export { type ToolApproval, type UseAlquimiaConfig, useAlquimia, useRatings };

package/dist/hooks/index.js

@@ -51,6 +51,9 @@ var AlquimiaSDK = class {
     // Registry version tag resolved by the runtime for this task (v0.5.1), so
     // the tool-completion half of the turn lands on the same agentspace version.
     this.versionTag = null;
+    // Agentspace the runtime resolved for this task. Tool completion and
+    // approval authorize a non-admin caller against it, so it is echoed back.
+    this.agentspaceId = null;
     this.tools = [];
     this.extraInstructions = null;
     this.assistantConfig = null;
@@ -202,6 +205,7 @@ var AlquimiaSDK = class {
     this.traceParent = opts.traceParent ?? null;
     this.streamId = result.taskid ?? null;
     this.versionTag = result.versiontag ?? this.versionTag;
+    this.agentspaceId = result.agentspaceid ?? null;
     this.attachmentResponses = result.attachments ?? [];
     this.attachments = [];
     return this;
@@ -221,17 +225,37 @@ var AlquimiaSDK = class {
         "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 },
-      ...this.versionTag && { versiontag: this.versionTag },
-      ...adapterHeaders
+    await this.axiosInstance.post(url, response, { headers: this.buildDecisionHeaders() });
+  }
+  /**
+   * Answer a `HumanApprovalRequired` gate: POSTs a {@link ToolApprovalEvent} to
+   * the runtime's `/event/tool-approval`. `controlId` is the gate's own control
+   * id (the `HumanApprovalRequired` record's), not the parked tool call's.
+   *
+   * Never throws for a runtime refusal — each 409 means something different to
+   * the UI, so the answer comes back classified as a {@link ToolApprovalResult}.
+   * It does throw when the adapter has no approval route, which is a wiring bug
+   * rather than a runtime answer.
+   */
+  async submitToolApproval(controlId, approved, message) {
+    const url = this.adapter.resolveToolApprovalUrl?.();
+    if (!url) {
+      throw new Error(
+        "AlquimiaSDK: adapter does not support tool approval (resolveToolApprovalUrl missing)"
+      );
+    }
+    const event = {
+      event_class: "ToolApprovalEvent",
+      control_id: controlId,
+      result: approved,
+      ...message && { message }
     };
-    await this.axiosInstance.post(url, response, { headers });
+    try {
+      await this.axiosInstance.post(url, event, { headers: this.buildDecisionHeaders() });
+      return { outcome: "accepted" };
+    } catch (error) {
+      return classifyApprovalError(error);
+    }
   }
   async generateImage(query) {
     if (!this.stableDiffusionProvider) {
@@ -302,6 +326,23 @@ var AlquimiaSDK = class {
     if (this.streamId) headers["task-id"] = this.streamId;
     return headers;
   }
+  /**
+   * Correlation headers for tool-completion and tool-approval: the runtime's
+   * `CommonAttributes` header aliases, with no separator. Not interchangeable
+   * with the kebab-case set in {@link buildIdentityHeaders}.
+   */
+  buildDecisionHeaders() {
+    return {
+      "Content-Type": "application/json",
+      assistantid: this.assistantId,
+      ...this.streamId && { taskid: this.streamId },
+      ...this.conversationId && { sessionid: this.conversationId },
+      ...this.userId && { userid: this.userId },
+      ...this.agentspaceId && { agentspaceid: this.agentspaceId },
+      ...this.versionTag && { versiontag: this.versionTag },
+      ...this.adapter.getHeaders?.() ?? {}
+    };
+  }
   getUrlStream() {
     if (!this.streamId) {
       throw new Error("Stream ID not initialized. Call sendMessage() first");
@@ -322,7 +363,29 @@ var AlquimiaSDK = class {
   getVersionTag() {
     return this.versionTag;
   }
+  /** Agentspace the runtime resolved for the current task, if any. */
+  getAgentspaceId() {
+    return this.agentspaceId;
+  }
 };
+function classifyApprovalError(error) {
+  const response = error?.response;
+  const status = response?.status;
+  const data = response?.data;
+  const rawDetail = typeof data === "string" ? data : data?.detail ?? data?.error ?? error?.message;
+  const detail = typeof rawDetail === "string" ? rawDetail : JSON.stringify(rawDetail ?? "");
+  let outcome = "error";
+  if (status === 409) {
+    if (/original channel/i.test(detail)) outcome = "wrong-channel";
+    else if (/already been recorded/i.test(detail)) outcome = "already-decided";
+    else if (/no pending approval/i.test(detail)) outcome = "not-pending";
+  } else if (status === 401 || status === 403) {
+    outcome = "forbidden";
+  } else if (status === 404) {
+    outcome = "not-found";
+  }
+  return { outcome, ...status !== void 0 && { status }, detail };
+}
 var alquimia_sdk_default = AlquimiaSDK;
 
 // src/utils/utils.ts
@@ -426,6 +489,10 @@ var agentTitle = (r) => {
   return typeof name === "string" && name.length > 0 ? `Agent: ${name}` : "Agent-to-agent";
 };
 var constTitle = (label) => () => label;
+var approvalTitle = (r) => {
+  const name = asRecord(asRecord(r.data).parameters).name;
+  return typeof name === "string" && name.length > 0 ? `Approval required: ${name}` : "Human approval required";
+};
 var shieldBlockTitle = (r) => {
   const id = asRecord(r.data).shield_id;
   return typeof id === "string" && id.length > 0 ? `Blocked by ${id}` : "Blocked by safeguard";
@@ -477,7 +544,7 @@ var EVENT_REGISTRY = {
   HumanApprovalRequired: {
     kind: "tool",
     role: "open",
-    title: constTitle("Human approval required"),
+    title: approvalTitle,
     pending: true
   },
   HumanApprovalRequiredResponse: { kind: "tool", role: "close", title: constTitle("Human approval") }
@@ -566,7 +633,12 @@ function reduceWorklog(state, record) {
   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] };
+    next.nodes[pos] = {
+      ...existing,
+      command: existing.command ?? record.data,
+      title: existing.command === void 0 ? interp.title(record) : existing.title,
+      raw: [...existing.raw, record]
+    };
   } else {
     next.index[key] = next.nodes.length;
     next.nodes.push(makeOpenNode(record, interp, key));
@@ -591,6 +663,59 @@ function frameToRecord(frame) {
   };
 }
 
+// src/worklog/approvals.ts
+function initialApprovalsState() {
+  return { order: [], byId: {} };
+}
+var asObject = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : null;
+var MCP_APPROVAL_EXTENSION = "mcp_approval";
+function describeRequest(record) {
+  const execution = asObject(asObject(record.data)?.parameters) ?? {};
+  const name = execution.name;
+  const callId = execution.control_id;
+  const args = execution.tool_call_parameters !== void 0 && execution.tool_call_parameters !== null ? execution.tool_call_parameters : execution.parameters;
+  const extensions = asObject(execution.parameters)?.runtime_extensions;
+  return {
+    toolName: typeof name === "string" && name.length > 0 ? name : null,
+    toolCallId: typeof callId === "string" ? callId : null,
+    arguments: args ?? null,
+    channelOwned: Array.isArray(extensions) && extensions.includes(MCP_APPROVAL_EXTENSION)
+  };
+}
+function describeDecision(record) {
+  const approved = record.data === true;
+  return {
+    approved,
+    reason: !approved && typeof record.data === "string" && record.data.length > 0 ? record.data : null,
+    decidedAt: record.date_submitted
+  };
+}
+var blank = (controlId) => ({
+  controlId,
+  toolName: null,
+  toolCallId: null,
+  arguments: null,
+  channelOwned: false,
+  requestedAt: null,
+  decision: null
+});
+function reduceApprovals(state, record) {
+  const isRequest = record.event_class === "HumanApprovalRequired";
+  const isResponse = record.event_class === "HumanApprovalRequiredResponse";
+  if (!isRequest && !isResponse || !record.control_id) return state;
+  const id = record.control_id;
+  const known = state.byId[id];
+  const current = known ?? blank(id);
+  const next = isRequest ? { ...current, ...describeRequest(record), requestedAt: record.date_submitted } : { ...current, decision: current.decision ?? describeDecision(record) };
+  return {
+    order: known ? state.order : [...state.order, id],
+    byId: { ...state.byId, [id]: next }
+  };
+}
+function listApprovals(state) {
+  return state.order.map((id) => state.byId[id]);
+}
+
 // src/hooks/pending-client-tool.ts
 function extractPendingClientTool(frame) {
   if (!frame || typeof frame !== "object") return null;
@@ -953,6 +1078,7 @@ function buildGenuiClause(manifest, allowlist) {
 var import_zod_to_json_schema = require("zod-to-json-schema");
 
 // src/hooks/alquimia.hook.tsx
+var TERMINAL_REFUSALS = /* @__PURE__ */ new Set(["already-decided", "wrong-channel", "not-pending", "not-found", "forbidden"]);
 function useAlquimia(config) {
   const sdk = (0, import_react2.useMemo)(() => {
     const instance = new alquimia_sdk_default(config.assistantId, config.adapter, {
@@ -997,6 +1123,12 @@ function useAlquimia(config) {
   const [isUploadingAttachments, setIsUploadingAttachments] = (0, import_react2.useState)(false);
   const [pendingClientTool, setPendingClientTool] = (0, import_react2.useState)(null);
   const completedToolsRef = (0, import_react2.useRef)(/* @__PURE__ */ new Set());
+  const [approvalsState, setApprovalsState] = (0, import_react2.useState)(initialApprovalsState);
+  const approvalsStateRef = (0, import_react2.useRef)(approvalsState);
+  approvalsStateRef.current = approvalsState;
+  const [approvalSubmissions, setApprovalSubmissions] = (0, import_react2.useState)({});
+  const approvalCallsRef = (0, import_react2.useRef)(/* @__PURE__ */ new Map());
+  const approvalAnchorsRef = (0, import_react2.useRef)({});
   const genuiCatalog = config.genui?.catalog ?? coreCatalog;
   const [genuiSurfaces, setGenuiSurfaces] = (0, import_react2.useState)([]);
   const messagesLenRef = (0, import_react2.useRef)(0);
@@ -1279,6 +1411,14 @@ function useAlquimia(config) {
     if (worklogEnabled) {
       setWorklog((prev) => reduceWorklog(prev ?? initialWorklogState(), frameToRecord(data)));
     }
+    if ((data.event_class === "HumanApprovalRequired" || data.event_class === "HumanApprovalRequiredResponse") && data.control_id) {
+      if (!(data.control_id in approvalAnchorsRef.current)) {
+        approvalAnchorsRef.current[data.control_id] = genuiAnchorRef.current;
+      }
+      const record = frameToRecord(data);
+      setApprovalsState((prev) => reduceApprovals(prev, record));
+      return;
+    }
     const pending = extractPendingClientTool(data);
     if (pending) {
       setPendingClientTool(pending);
@@ -1327,6 +1467,59 @@ function useAlquimia(config) {
     },
     [sdk]
   );
+  const approveTool = (0, import_react2.useCallback)(
+    (controlId, approved, message) => {
+      const existing = approvalCallsRef.current.get(controlId);
+      if (existing) return existing;
+      if (approvalsStateRef.current.byId[controlId]?.decision) {
+        return Promise.resolve({ outcome: "already-decided" });
+      }
+      const reason = message?.trim() || null;
+      setApprovalSubmissions((prev) => ({
+        ...prev,
+        [controlId]: { inFlight: true, approved, reason, result: prev[controlId]?.result ?? null }
+      }));
+      const call = sdk.submitToolApproval(controlId, approved, reason ?? void 0).catch((error) => ({
+        outcome: "error",
+        detail: error instanceof Error ? error.message : String(error)
+      })).then((result) => {
+        if (result.outcome !== "accepted") approvalCallsRef.current.delete(controlId);
+        setApprovalSubmissions((prev) => ({
+          ...prev,
+          [controlId]: { inFlight: false, approved, reason, result }
+        }));
+        return result;
+      });
+      approvalCallsRef.current.set(controlId, call);
+      return call;
+    },
+    [sdk]
+  );
+  const toolApprovals = (0, import_react2.useMemo)(
+    () => listApprovals(approvalsState).map((gate) => {
+      const sub = approvalSubmissions[gate.controlId];
+      const acceptedHere = sub?.result?.outcome === "accepted";
+      const refused = !!sub?.result && TERMINAL_REFUSALS.has(sub.result.outcome);
+      let status = "pending";
+      if (gate.decision) status = gate.decision.approved ? "approved" : "rejected";
+      else if (sub?.inFlight) status = "submitting";
+      else if (acceptedHere) status = sub.approved ? "approved" : "rejected";
+      return {
+        ...gate,
+        status,
+        reason: gate.decision?.reason ?? (acceptedHere && !sub.approved ? sub.reason : null),
+        decidedHere: acceptedHere && (gate.decision ? gate.decision.approved === sub.approved : true),
+        canAnswer: status === "pending" && !gate.channelOwned && !refused,
+        lastResult: sub?.result ?? null,
+        afterCount: approvalAnchorsRef.current[gate.controlId] ?? 0
+      };
+    }),
+    [approvalsState, approvalSubmissions]
+  );
+  const pendingApprovals2 = (0, import_react2.useMemo)(
+    () => toolApprovals.filter((a) => a.status === "pending" || a.status === "submitting"),
+    [toolApprovals]
+  );
   (0, import_react2.useEffect)(() => {
     if (!config.genui) return;
     if (!pendingClientTool || pendingClientTool.toolName !== "render_ui") return;
@@ -1412,6 +1605,9 @@ function useAlquimia(config) {
     activeTool,
     pendingClientTool,
     completeToolExecution,
+    toolApprovals,
+    pendingApprovals: pendingApprovals2,
+    approveTool,
     genui,
     cleanMessages,
     createMessageId,