@alquimia-ai/tools 2.5.0 → 2.8.0

package/dist/hooks/index.mjs

@@ -11,6 +11,12 @@ var AlquimiaSDK = class {
     this.streamId = null;
     // W3C traceparent for the current turn, so infer and stream share one trace.
     this.traceParent = null;
+    // 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;
@@ -91,6 +97,19 @@ var AlquimiaSDK = class {
     this.userId = userId;
     return this;
   }
+  /**
+   * Pin inference to a cached registry version. Sent as the `version_tag`
+   * query parameter, which `POST /event/infer/{assistant_id}` accepts from
+   * **runtime v0.5.2** onward; older runtimes ignore it.
+   *
+   * Works on every version: pass a versioned assistant ref
+   * (`<agentspace>/<assistant>[:<tag>]`) as the `assistantId` instead — the
+   * runtime parses the tag out of the path itself.
+   */
+  withVersionTag(versionTag) {
+    this.versionTag = versionTag;
+    return this;
+  }
   getEnforceCharacterization() {
     return this.enforceCharacterization ?? true;
   }
@@ -106,19 +125,29 @@ var AlquimiaSDK = class {
     }
     return this.whisperProvider.speechToText(audio);
   }
-  async sendMessage(query, traceParent) {
+  async sendMessage(query, options = {}) {
     if (!this.conversationId) {
       throw new Error(
         "Conversation not initialized. Call withConversationId() before sendMessage()"
       );
     }
-    const inferUrl = this.adapter.resolveInferUrl(this.assistantId);
+    const opts = typeof options === "string" ? { traceParent: options } : options;
+    if (query === void 0 && !opts.inputAudio) {
+      throw new Error(
+        "AlquimiaSDK: sendMessage needs a query, an inputAudio blob, or both"
+      );
+    }
+    const baseInferUrl = this.adapter.resolveInferUrl(this.assistantId);
+    const inferUrl = this.versionTag ? `${baseInferUrl}${baseInferUrl.includes("?") ? "&" : "?"}version_tag=${encodeURIComponent(this.versionTag)}` : baseInferUrl;
     const adapterHeaders = this.adapter.getHeaders?.() ?? {};
     const hasClientTools = Array.isArray(this.tools) && this.tools.length > 0;
     const initMessage = {
-      query,
+      ...query !== void 0 && { query },
       session_id: this.conversationId,
       user_id: this.userId,
+      ...opts.inputAudio && { input_audio: opts.inputAudio },
+      // Only sent when set: the runtime defaults `output_audio` to true.
+      ...opts.outputAudio !== void 0 && { output_audio: opts.outputAudio },
       ...this.extraInstructions && { extra_instructions: this.extraInstructions },
       ...this.assistantConfig && { config: this.assistantConfig },
       ...hasClientTools && {
@@ -131,13 +160,15 @@ var AlquimiaSDK = class {
     const result = (await this.axiosInstance.post(inferUrl, initMessage, {
       headers: {
         "Content-Type": "application/json",
-        ...traceParent && { "x-trace-parent": traceParent },
+        ...opts.traceParent && { "x-trace-parent": opts.traceParent },
         ...adapterHeaders,
         ...this.buildIdentityHeaders()
       }
     })).data;
-    this.traceParent = traceParent ?? null;
+    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;
@@ -157,16 +188,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 },
-      ...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) {
@@ -206,18 +258,23 @@ var AlquimiaSDK = class {
   getAttachmentResponses() {
     return this.attachmentResponses;
   }
+  /**
+   * Upload a file into the session context. Returns the runtime {@link RuntimeBlob},
+   * which is what `sendMessage`'s `inputAudio` expects for audio inference.
+   */
   async uploadAttachment(file, _attachmentId) {
     const url = this.adapter.resolveBlobUploadUrl();
     const adapterHeaders = this.adapter.getHeaders?.() ?? {};
     const formData = new FormData();
     formData.append("file", file);
-    await this.axiosInstance.post(url, formData, {
+    const response = await this.axiosInstance.post(url, formData, {
       headers: {
         "Content-Type": "multipart/form-data",
         ...adapterHeaders,
         ...this.buildIdentityHeaders()
       }
     });
+    return response.data;
   }
   /**
    * Identity headers (kebab-case) required by `/context/blob/upload` and
@@ -232,6 +289,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");
@@ -248,7 +322,33 @@ var AlquimiaSDK = class {
   getTaskId() {
     return this.streamId;
   }
+  /** Registry version tag resolved by the runtime for the current task, if any. */
+  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
@@ -352,6 +452,18 @@ 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";
+};
+var knowledgeTitle = (r) => {
+  const query = asRecord(r.data).query;
+  return typeof query === "string" && query.length > 0 ? `Knowledge: ${query}` : "Knowledge retrieval";
+};
 var EVENT_REGISTRY = {
   // Run envelope
   AssistantInference: { kind: "answer", role: "run-open", title: constTitle("Inference started") },
@@ -359,6 +471,9 @@ var EVENT_REGISTRY = {
   // Safeguard
   ShieldInference: { kind: "safeguard", role: "open", title: constTitle("Safeguard") },
   ShieldInferenceResponse: { kind: "safeguard", role: "close", title: constTitle("Safeguard") },
+  // Emitted when a shield enforcement decision blocks the request (core 0.5.x).
+  // Response-only: the reducer opens it already closed when no command matched.
+  ShieldBlockedResponse: { kind: "safeguard", role: "close", title: shieldBlockTitle },
   // Reasoning
   ResponseInference: { kind: "reasoning", role: "open", title: constTitle("Reasoning") },
   ResponseInferenceResponse: { kind: "reasoning", role: "close", title: constTitle("Reasoning") },
@@ -376,6 +491,14 @@ var EVENT_REGISTRY = {
   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") },
+  // Knowledge retrieval (RAG) — core 0.5.x
+  KnowledgeRetrieval: { kind: "knowledge", role: "open", title: knowledgeTitle },
+  KnowledgeRetrievalResponse: { kind: "knowledge", role: "close", title: knowledgeTitle },
+  // Speech pipeline — core 0.5.x
+  SpeechTranscription: { kind: "speech", role: "open", title: constTitle("Speech-to-text") },
+  SpeechTranscriptionResponse: { kind: "speech", role: "close", title: constTitle("Speech-to-text") },
+  SpeechSynthesis: { kind: "speech", role: "open", title: constTitle("Text-to-speech") },
+  SpeechSynthesisResponse: { kind: "speech", role: "close", title: constTitle("Text-to-speech") },
   // Memory / persistence
   ContextPersistence: { kind: "memory", role: "open", title: constTitle("Memory persistence") },
   ContextFlush: { kind: "memory", role: "open", title: constTitle("Memory flush") },
@@ -384,7 +507,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") }
@@ -473,7 +596,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));
@@ -498,6 +626,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;
@@ -860,6 +1041,7 @@ function buildGenuiClause(manifest, allowlist) {
 import { zodToJsonSchema } from "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 = useMemo(() => {
     const instance = new alquimia_sdk_default(config.assistantId, config.adapter, {
@@ -904,6 +1086,12 @@ function useAlquimia(config) {
   const [isUploadingAttachments, setIsUploadingAttachments] = useState(false);
   const [pendingClientTool, setPendingClientTool] = useState(null);
   const completedToolsRef = useRef(/* @__PURE__ */ new Set());
+  const [approvalsState, setApprovalsState] = useState(initialApprovalsState);
+  const approvalsStateRef = useRef(approvalsState);
+  approvalsStateRef.current = approvalsState;
+  const [approvalSubmissions, setApprovalSubmissions] = useState({});
+  const approvalCallsRef = useRef(/* @__PURE__ */ new Map());
+  const approvalAnchorsRef = useRef({});
   const genuiCatalog = config.genui?.catalog ?? coreCatalog;
   const [genuiSurfaces, setGenuiSurfaces] = useState([]);
   const messagesLenRef = useRef(0);
@@ -1186,6 +1374,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);
@@ -1234,6 +1430,59 @@ function useAlquimia(config) {
     },
     [sdk]
   );
+  const approveTool = useCallback2(
+    (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 = 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 = useMemo(
+    () => toolApprovals.filter((a) => a.status === "pending" || a.status === "submitting"),
+    [toolApprovals]
+  );
   useEffect(() => {
     if (!config.genui) return;
     if (!pendingClientTool || pendingClientTool.toolName !== "render_ui") return;
@@ -1319,6 +1568,9 @@ function useAlquimia(config) {
     activeTool,
     pendingClientTool,
     completeToolExecution,
+    toolApprovals,
+    pendingApprovals: pendingApprovals2,
+    approveTool,
     genui,
     cleanMessages,
     createMessageId,