@alquimia-ai/tools 2.7.0 → 2.8.0

package/README.md

@@ -21,6 +21,7 @@ It ships no UI. Pair it with [`@alquimia-ai/ui`](../ui) for the component librar
 - [Multimodal and audio input](#multimodal-and-audio-input)
 - [Attachments and blobs](#attachments-and-blobs)
 - [Client tools and GenUI](#client-tools-and-genui)
+- [Human approval](#human-approval)
 - [Worklog](#worklog)
 - [Providers](#providers)
 - [Server proxy](#server-proxy)
@@ -62,11 +63,12 @@ useAlquimia / AlquimiaSDK
   └─ adapter.resolveStreamUrl() ─→ handleStream ───────────────→ GET  /event/stream/{taskId}
   └─ adapter.resolveBlobUploadUrl() → handleBlobUpload ────────→ POST /context/blob/upload
   └─ adapter.resolveToolCompletionUrl() → handleToolCompletion → POST /event/tool-completion
+  └─ adapter.resolveToolApprovalUrl() ──→ handleToolApproval ───→ POST /event/tool-approval
                                    ↑
                           Authorization: Bearer <apiKey>
 ```
 
-The proxy exists for two reasons. The obvious one is that the API key must not reach the browser. The load-bearing one is that the stream leg uses `EventSource`, and **`EventSource` cannot set request headers** — so `getHeaders()` is honoured on infer, blob upload and tool-completion (all axios POSTs) and silently ignored on the stream. If your runtime or its gateway requires auth on every request, a server hop on the stream is not optional.
+The proxy exists for two reasons. The obvious one is that the API key must not reach the browser. The load-bearing one is that the stream leg uses `EventSource`, and **`EventSource` cannot set request headers** — so `getHeaders()` is honoured on infer, blob upload, tool-completion and tool-approval (all axios POSTs) and silently ignored on the stream. If your runtime or its gateway requires auth on every request, a server hop on the stream is not optional.
 
 Three supported topologies:
 
@@ -82,7 +84,7 @@ Three supported topologies:
 
 ### Next.js App Router
 
-Four route files, five lines each:
+Five route files, five lines each:
 
 ```ts
 // app/api/chat/[...path]/route.ts
@@ -100,9 +102,10 @@ export const POST = handlers.handleInfer;
 // app/api/stream/[...path]/route.ts  → export const GET = handlers.handleStream;
 // app/api/blob/upload/route.ts       → export const POST = handlers.handleBlobUpload;
 // app/api/tool-completion/route.ts   → export const POST = handlers.handleToolCompletion;
+// app/api/tool-approval/route.ts     → export const POST = handlers.handleToolApproval;
 ```
 
-The last two take no `[...path]` segment: identity travels in headers, and the pending tool call is correlated by `control_id` in the body.
+The last three take no `[...path]` segment: identity travels in headers, and the pending tool call or approval is correlated by `control_id` in the body.
 
 ```tsx
 'use client';
@@ -138,6 +141,7 @@ app.post('/chat/:path{.+}', (c) => handler.handleInfer(c.req.raw, c.req.param('p
 app.get('/stream/:path{.+}', (c) => handler.handleStream(c.req.raw, c.req.param('path')));
 app.post('/blob/upload', (c) => handler.handleBlobUpload(c.req.raw));
 app.post('/tool-completion', (c) => handler.handleToolCompletion(c.req.raw));
+app.post('/tool-approval', (c) => handler.handleToolApproval(c.req.raw));
 ```
 
 The handlers speak the Web Fetch API (`Request` → `Response`), so any modern runtime works.
@@ -159,6 +163,7 @@ const adapter: AlquimiaAdapter = {
   resolveStreamUrl: (taskId) => `${STREAM_PROXY}/event/stream/${taskId}`,
   resolveBlobUploadUrl: () => `${BACKEND}/context/blob/upload`,
   resolveToolCompletionUrl: () => `${BACKEND}/event/tool-completion`,
+  resolveToolApprovalUrl: () => `${BACKEND}/event/tool-approval`,
   getHeaders: () => ({ Authorization: `Bearer ${API_KEY}` }),
 };
 ```
@@ -232,6 +237,10 @@ const alquimia = useAlquimia({
 
 `activeTool`, `setActiveTool`, `pendingClientTool`, `completeToolExecution`, `genui`.
 
+**Human approval**
+
+`toolApprovals`, `pendingApprovals`, `approveTool` — see [Human approval](#human-approval).
+
 **Trace**
 
 `worklog` — a `WorklogState`, or `undefined` unless `options.worklog` is on.
@@ -279,7 +288,9 @@ const streamUrl = sdk.getUrlStream();
 | `getUrlStream()` | SSE URL for the task, with the traceparent appended as a query param |
 | `getStreamId()` / `getTaskId()` | the runtime `taskid` |
 | `getVersionTag()` | the registry version the runtime resolved |
+| `getAgentspaceId()` | the agentspace the runtime resolved |
 | `submitToolResult(response)` | POST tool-completion for a pending client tool |
+| `submitToolApproval(controlId, approved, message?)` → `ToolApprovalResult` | POST tool-approval for a pending human-approval gate |
 
 ### Side channels
 
@@ -301,7 +312,7 @@ const streamUrl = sdk.getUrlStream();
 1. POST /event/infer/{assistantId}
      body    { query, session_id, user_id, ... }
      headers assistant-id, session-id, user-id, task-id, x-trace-parent
-     →       CommonAttributes { taskid, versiontag, attachments }
+     →       CommonAttributes { taskid, agentspaceid, versiontag, attachments }
 
 2. GET /event/stream/{taskid}          (EventSource)
      ← assistant deltas, thinkings, tool events
@@ -309,8 +320,13 @@ const streamUrl = sdk.getUrlStream();
 
 3. POST /event/tool-completion          (only if the agent called a client tool)
      body    ToolExecutionResponse { control_id, tool_name, status, result }
-     headers taskid, sessionid, userid, assistantid, versiontag
+     headers taskid, sessionid, userid, assistantid, agentspaceid, versiontag
      → the run resumes on the same stream
+
+4. POST /event/tool-approval            (only if a tool call needs human approval)
+     body    ToolApprovalEvent { control_id, result, message? }
+     headers same as step 3
+     → the parked call runs (approved) or fails back to the agent (rejected)
 ```
 
 Step 3 is what makes client tools and GenUI work: the runtime parks the task, the browser answers, the run continues. The correlation headers are not decoration — the runtime looks the parked task up by them, and rejects a completion whose `control_id` it is not awaiting with a `409`.
@@ -416,6 +432,64 @@ Components come from `@alquimia-ai/ui/components/genui` (`A2uiRenderer`, `coreUi
 
 ---
 
+## Human approval
+
+When the runtime's authorization policy resolves a tool call to `REQUIRE_APPROVAL` — an operation classified `destructive`, or one with `approval_required` set — the run parks and the stream carries a `HumanApprovalRequired` instead of the tool execution. Nothing resumes it until someone answers `POST /event/tool-approval`. The hook tracks these gates always, not only with `options.worklog`, because an unanswered gate hangs the conversation.
+
+```tsx
+const alquimia = useAlquimia({ assistantId, adapter });
+
+alquimia.pendingApprovals.map((a) => (
+  <div key={a.controlId}>
+    Run <code>{a.toolName}</code> with <pre>{JSON.stringify(a.arguments, null, 2)}</pre>
+    {a.canAnswer && (
+      <>
+        <button onClick={() => alquimia.approveTool(a.controlId, true)}>Approve</button>
+        <button onClick={() => alquimia.approveTool(a.controlId, false, 'not now')}>Reject</button>
+      </>
+    )}
+  </div>
+));
+```
+
+`@alquimia-ai/ui` ships this as `ToolApprovalCard`, and `AssistantChat` renders it in place when you pass the whole hook return.
+
+Each `ToolApproval` in `toolApprovals` (all gates) and `pendingApprovals` (undecided ones) carries:
+
+| Field | Meaning |
+|---|---|
+| `controlId` | the gate's id — what `approveTool` takes. Not the parked tool call's id (`toolCallId`). |
+| `toolName`, `arguments` | what is being approved. Show them: approving a call blind is not approval. |
+| `status` | `pending` → `submitting` → `approved` / `rejected` |
+| `decision` | the decision **as the worklog records it**, or `null` |
+| `reason` | the rejection reason, if one was given |
+| `decidedHere` | this client made the accepted decision |
+| `canAnswer` | offering buttons can still work — `false` for a channel-owned gate or after a terminal refusal |
+| `lastResult` | the runtime's answer to this client's last submission |
+| `afterCount` | message count the gate was raised after, for anchoring it in the chat |
+
+A gate settles when its `HumanApprovalRequiredResponse` arrives on the stream, whoever made the decision — another operator, or the channel the conversation came from. `approveTool` shows an accepted local decision right away, but `decision` only ever comes from the stream. The worklog records the decision and its reason, not the approver: the runtime keeps that in its audit trail.
+
+`approveTool` never throws for a refusal. It resolves to a `ToolApprovalResult` whose `outcome` tells the cases apart, since the runtime answers most of them with a `409` and a different `detail`:
+
+| `outcome` | Runtime answer | What to do |
+|---|---|---|
+| `accepted` | 200 | nothing — the stream will confirm |
+| `already-decided` | 409, a decision is already recorded | someone else answered; wait for the stream |
+| `wrong-channel` | 409, must be answered through its original channel | remove the buttons and say where to answer |
+| `not-pending` | 409, no pending approval for this control id | stale; nothing to answer |
+| `forbidden` | 401 / 403 | the caller lacks an approver role (`TOOL_APPROVAL_ROLES`, default `editor,operator`; platform and org admins always pass) or is not bound to the agentspace |
+| `not-found` | 404 | the task finished or expired |
+| `error` | anything else | retryable — `canAnswer` stays `true` |
+
+The runtime authorizes the approver, not the app: a static API token in the proxy maps to `API_TOKEN_ROLES` (default `platform-admin`) and passes unless that was narrowed. If your proxy forwards an end-user token instead, that user needs an approver role. The SDK sends the `agentspaceid` the runtime returned on infer, which a non-admin caller is checked against.
+
+A gate whose MCP server runs its own approval over the originating channel (the `mcp_approval` runtime extension) is flagged `channelOwned` from the request itself, so buttons are never offered for it.
+
+Outside the hook, `foldApprovals` / `reduceApprovals` / `pendingApprovals` in `/worklog` derive the same state from any list of worklog records, and `sdk.submitToolApproval()` posts the decision.
+
+---
+
 ## Worklog
 
 The worklog is the agent's execution trace, normalized into a tree you can render as "show your work".
@@ -434,7 +508,7 @@ Each runtime event class maps to an interpreter that says which bucket it belong
 | `answer` | `AssistantInference(+Response)` — the run envelope |
 | `safeguard` | `ShieldInference(+Response)`, `ShieldBlockedResponse` |
 | `reasoning` | `ResponseInference(+Response)` |
-| `tool` | `ServerToolExecution`, `BuiltinToolExecution`, `ClientToolExecution`, `UnknownToolExecution`, `ToolSchema`, `HumanApprovalRequired`, and their responses |
+| `tool` | `ServerToolExecution`, `BuiltinToolExecution`, `ClientToolExecution`, `UnknownToolExecution`, `ToolSchema`, `HumanApprovalRequired` (titled with the tool awaiting approval), and their responses |
 | `a2a` | `A2AInference`, `AgentDiscovery(+Response)` |
 | `memory` | `ContextPersistence`, `ContextFlush(+Response)` |
 | `knowledge` | `KnowledgeRetrieval(+Response)` |
@@ -481,15 +555,17 @@ createAlquimiaProxyHandler({
   streamRoute: 'event/stream',
   blobUploadRoute: 'context/blob/upload',
   toolCompletionRoute: 'event/tool-completion',
+  toolApprovalRoute: 'event/tool-approval',
 })
 ```
 
-Returns `handleInfer`, `handleStream`, `handleBlobUpload`, `handleToolCompletion`.
+Returns `handleInfer`, `handleStream`, `handleBlobUpload`, `handleToolCompletion`, `handleToolApproval`.
 
 What it does beyond adding the bearer token:
 
 - Forwards identity headers on infer/stream/blob upload: `session-id`, `user-id`, `assistant-id`, `task-id`, `parent-task-id`, `agentspace-id`, `channel-id`, `depth`.
-- Forwards correlation headers on tool-completion: `taskid`, `sessionid`, `userid`, `assistantid`, `parenttaskid`, `agentspaceid`, `channelid`, `depth`, `versiontag`.
+- Forwards correlation headers on tool-completion and tool-approval: `taskid`, `sessionid`, `userid`, `assistantid`, `parenttaskid`, `agentspaceid`, `channelid`, `depth`, `versiontag`.
+- Passes the runtime's status and body through on tool-completion and tool-approval, so a `409`'s `detail` reaches the SDK intact.
 - Preserves the infer query string, so `?version_tag=` and `?agentspace_id=` survive the hop.
 - Streams the SSE body through untouched.
 - Turns the stream's `?trace_parent=` query param back into an `x-trace-parent` header, and does not pass the param upstream.
@@ -508,7 +584,7 @@ Infer and stream are two HTTP calls that must land in **one** trace, and `EventS
 
 `@alquimia-ai/tools/types` covers both the wire and the view model.
 
-**Wire:** `CommonAttributes` (with `versiontag`), `InferInitResponse`, `Content` / `ContentPart` / `TextContentPart` / `ImageContentPart` / `NonStandardContentPart`, `RuntimeBlob`, `AttachmentPayload`, `NativeToolsEvaluationStrategy`, `RuntimeEvent` and the `/event/*` payload union, `TTSResult`, `RatingData`.
+**Wire:** `CommonAttributes` (with `versiontag`), `InferInitResponse`, `ToolApprovalEvent`, `ToolApprovalResult` / `ToolApprovalOutcome`, `Content` / `ContentPart` / `TextContentPart` / `ImageContentPart` / `NonStandardContentPart`, `RuntimeBlob`, `AttachmentPayload`, `NativeToolsEvaluationStrategy`, `RuntimeEvent` and the `/event/*` payload union, `TTSResult`, `RatingData`.
 
 **View:** `AlquimiaMessage`, `AlquimiaEventData`, `AIMessageChunk`, `AssistantInferenceResponse`, `ToolEvent`, `Tooler`, `ThinkingsInferenceResponse`, `GenuiSurfaceItem`, `ActionResponse`.
 
@@ -522,13 +598,13 @@ Infer and stream are two HTTP calls that must land in **one** trace, and `EventS
 | `/adapters/next` | `createNextJsAdapter` |
 | `/adapters/fetch` | `createFetchAdapter` |
 | `/sdk` | `AlquimiaSDK` |
-| `/hooks` | `useAlquimia`, `useRatings` |
+| `/hooks` | `useAlquimia`, `useRatings`, `ToolApproval` |
 | `/proxy` | `createAlquimiaProxyHandler`, `ProxyConfig` |
-| `/next` | `createNextJsRouteHandlers`, `handleChatRequest`, `handleStreamRequest`, `initConversation` |
+| `/next` | `createNextJsRouteHandlers` (incl. `handleToolApproval`), `handleChatRequest`, `handleStreamRequest`, `initConversation` |
 | `/providers` | provider base classes and implementations |
 | `/providers/elastic` | `ElasticLoggerProvider` |
 | `/genui` | the GenUI protocol |
-| `/worklog` | reducer, registry, types, `useWorklog` |
+| `/worklog` | reducer, registry, types, `useWorklog`, approval derivation (`foldApprovals`, `pendingApprovals`) |
 | `/actions` | `initConversation`, CRUD helpers, `handleApmRequest` |
 | `/services` | Elastic APM RUM |
 | `/types` | wire + view types |

package/dist/actions/index.d.mts

@@ -1,4 +1,4 @@
-import { B as BaseAPIConfig } from '../type-61gaZga-.mjs';
+import { B as BaseAPIConfig } from '../type-C_sKpIM1.mjs';
 export { i as initConversation } from '../session.action-DirvOWt0.mjs';
 import '@elastic/apm-rum';
 import 'ai';

package/dist/actions/index.d.ts

@@ -1,4 +1,4 @@
-import { B as BaseAPIConfig } from '../type-D-JaSMkV.js';
+import { B as BaseAPIConfig } from '../type-BFtGEEb4.js';
 export { i as initConversation } from '../session.action-DirvOWt0.js';
 import '@elastic/apm-rum';
 import 'ai';

package/dist/adapters/fetch.d.mts

@@ -7,6 +7,7 @@ interface FetchAdapterOptions {
     streamPath?: string;
     blobUploadPath?: string;
     toolCompletionPath?: string;
+    toolApprovalPath?: string;
     busMode?: boolean;
 }
 declare function createFetchAdapter(options: FetchAdapterOptions): AlquimiaAdapter;

package/dist/adapters/fetch.d.ts

@@ -7,6 +7,7 @@ interface FetchAdapterOptions {
     streamPath?: string;
     blobUploadPath?: string;
     toolCompletionPath?: string;
+    toolApprovalPath?: string;
     busMode?: boolean;
 }
 declare function createFetchAdapter(options: FetchAdapterOptions): AlquimiaAdapter;

package/dist/adapters/fetch.js

@@ -28,6 +28,7 @@ function createFetchAdapter(options) {
   const streamPath = options.streamPath ?? "/stream";
   const blobUploadPath = options.blobUploadPath ?? "/blob/upload";
   const toolCompletionPath = options.toolCompletionPath ?? "/tool-completion";
+  const toolApprovalPath = options.toolApprovalPath ?? "/tool-approval";
   const busMode = options.busMode ?? false;
   const baseUrl = options.baseUrl.replace(/\/$/, "");
   return {
@@ -44,6 +45,9 @@ function createFetchAdapter(options) {
     resolveToolCompletionUrl() {
       return `${baseUrl}${toolCompletionPath}`;
     },
+    resolveToolApprovalUrl() {
+      return `${baseUrl}${toolApprovalPath}`;
+    },
     getHeaders: options.getHeaders
   };
 }

package/dist/adapters/fetch.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/fetch.ts"],"sourcesContent":["import type { AlquimiaAdapter } from './index';\n\nexport interface FetchAdapterOptions {\n  baseUrl: string;\n  getHeaders?: () => Record<string, string>;\n  inferPath?: string;             // default: '/chat'\n  streamPath?: string;            // default: '/stream'\n  blobUploadPath?: string;        // default: '/blob/upload'\n  toolCompletionPath?: string;    // default: '/tool-completion'\n  busMode?: boolean;              // default: false\n}\n\nexport function createFetchAdapter(options: FetchAdapterOptions): AlquimiaAdapter {\n  const inferPath = options.inferPath ?? '/chat';\n  const streamPath = options.streamPath ?? '/stream';\n  const blobUploadPath = options.blobUploadPath ?? '/blob/upload';\n  const toolCompletionPath = options.toolCompletionPath ?? '/tool-completion';\n  const busMode = options.busMode ?? false;\n  const baseUrl = options.baseUrl.replace(/\\/$/, '');\n\n  return {\n    resolveInferUrl(assistantId: string): string {\n      return `${baseUrl}${inferPath}/${assistantId}`;\n    },\n    resolveStreamUrl(streamId: string): string {\n      const url = `${baseUrl}${streamPath}/${streamId}`;\n      return busMode ? `${url}${url.includes('?') ? '&' : '?'}bus_mode=true` : url;\n    },\n    resolveBlobUploadUrl(): string {\n      return `${baseUrl}${blobUploadPath}`;\n    },\n    resolveToolCompletionUrl(): string {\n      return `${baseUrl}${toolCompletionPath}`;\n    },\n    getHeaders: options.getHeaders,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAYO,SAAS,mBAAmB,SAA+C;AAChF,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,iBAAiB,QAAQ,kBAAkB;AACjD,QAAM,qBAAqB,QAAQ,sBAAsB;AACzD,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,UAAU,QAAQ,QAAQ,QAAQ,OAAO,EAAE;AAEjD,SAAO;AAAA,IACL,gBAAgB,aAA6B;AAC3C,aAAO,GAAG,OAAO,GAAG,SAAS,IAAI,WAAW;AAAA,IAC9C;AAAA,IACA,iBAAiB,UAA0B;AACzC,YAAM,MAAM,GAAG,OAAO,GAAG,UAAU,IAAI,QAAQ;AAC/C,aAAO,UAAU,GAAG,GAAG,GAAG,IAAI,SAAS,GAAG,IAAI,MAAM,GAAG,kBAAkB;AAAA,IAC3E;AAAA,IACA,uBAA+B;AAC7B,aAAO,GAAG,OAAO,GAAG,cAAc;AAAA,IACpC;AAAA,IACA,2BAAmC;AACjC,aAAO,GAAG,OAAO,GAAG,kBAAkB;AAAA,IACxC;AAAA,IACA,YAAY,QAAQ;AAAA,EACtB;AACF;","names":[]}
+{"version":3,"sources":["../../src/adapters/fetch.ts"],"sourcesContent":["import type { AlquimiaAdapter } from './index';\n\nexport interface FetchAdapterOptions {\n  baseUrl: string;\n  getHeaders?: () => Record<string, string>;\n  inferPath?: string;             // default: '/chat'\n  streamPath?: string;            // default: '/stream'\n  blobUploadPath?: string;        // default: '/blob/upload'\n  toolCompletionPath?: string;    // default: '/tool-completion'\n  toolApprovalPath?: string;      // default: '/tool-approval'\n  busMode?: boolean;              // default: false\n}\n\nexport function createFetchAdapter(options: FetchAdapterOptions): AlquimiaAdapter {\n  const inferPath = options.inferPath ?? '/chat';\n  const streamPath = options.streamPath ?? '/stream';\n  const blobUploadPath = options.blobUploadPath ?? '/blob/upload';\n  const toolCompletionPath = options.toolCompletionPath ?? '/tool-completion';\n  const toolApprovalPath = options.toolApprovalPath ?? '/tool-approval';\n  const busMode = options.busMode ?? false;\n  const baseUrl = options.baseUrl.replace(/\\/$/, '');\n\n  return {\n    resolveInferUrl(assistantId: string): string {\n      return `${baseUrl}${inferPath}/${assistantId}`;\n    },\n    resolveStreamUrl(streamId: string): string {\n      const url = `${baseUrl}${streamPath}/${streamId}`;\n      return busMode ? `${url}${url.includes('?') ? '&' : '?'}bus_mode=true` : url;\n    },\n    resolveBlobUploadUrl(): string {\n      return `${baseUrl}${blobUploadPath}`;\n    },\n    resolveToolCompletionUrl(): string {\n      return `${baseUrl}${toolCompletionPath}`;\n    },\n    resolveToolApprovalUrl(): string {\n      return `${baseUrl}${toolApprovalPath}`;\n    },\n    getHeaders: options.getHeaders,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAaO,SAAS,mBAAmB,SAA+C;AAChF,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,iBAAiB,QAAQ,kBAAkB;AACjD,QAAM,qBAAqB,QAAQ,sBAAsB;AACzD,QAAM,mBAAmB,QAAQ,oBAAoB;AACrD,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,UAAU,QAAQ,QAAQ,QAAQ,OAAO,EAAE;AAEjD,SAAO;AAAA,IACL,gBAAgB,aAA6B;AAC3C,aAAO,GAAG,OAAO,GAAG,SAAS,IAAI,WAAW;AAAA,IAC9C;AAAA,IACA,iBAAiB,UAA0B;AACzC,YAAM,MAAM,GAAG,OAAO,GAAG,UAAU,IAAI,QAAQ;AAC/C,aAAO,UAAU,GAAG,GAAG,GAAG,IAAI,SAAS,GAAG,IAAI,MAAM,GAAG,kBAAkB;AAAA,IAC3E;AAAA,IACA,uBAA+B;AAC7B,aAAO,GAAG,OAAO,GAAG,cAAc;AAAA,IACpC;AAAA,IACA,2BAAmC;AACjC,aAAO,GAAG,OAAO,GAAG,kBAAkB;AAAA,IACxC;AAAA,IACA,yBAAiC;AAC/B,aAAO,GAAG,OAAO,GAAG,gBAAgB;AAAA,IACtC;AAAA,IACA,YAAY,QAAQ;AAAA,EACtB;AACF;","names":[]}

package/dist/adapters/fetch.mjs

@@ -4,6 +4,7 @@ function createFetchAdapter(options) {
   const streamPath = options.streamPath ?? "/stream";
   const blobUploadPath = options.blobUploadPath ?? "/blob/upload";
   const toolCompletionPath = options.toolCompletionPath ?? "/tool-completion";
+  const toolApprovalPath = options.toolApprovalPath ?? "/tool-approval";
   const busMode = options.busMode ?? false;
   const baseUrl = options.baseUrl.replace(/\/$/, "");
   return {
@@ -20,6 +21,9 @@ function createFetchAdapter(options) {
     resolveToolCompletionUrl() {
       return `${baseUrl}${toolCompletionPath}`;
     },
+    resolveToolApprovalUrl() {
+      return `${baseUrl}${toolApprovalPath}`;
+    },
     getHeaders: options.getHeaders
   };
 }

package/dist/adapters/fetch.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/fetch.ts"],"sourcesContent":["import type { AlquimiaAdapter } from './index';\n\nexport interface FetchAdapterOptions {\n  baseUrl: string;\n  getHeaders?: () => Record<string, string>;\n  inferPath?: string;             // default: '/chat'\n  streamPath?: string;            // default: '/stream'\n  blobUploadPath?: string;        // default: '/blob/upload'\n  toolCompletionPath?: string;    // default: '/tool-completion'\n  busMode?: boolean;              // default: false\n}\n\nexport function createFetchAdapter(options: FetchAdapterOptions): AlquimiaAdapter {\n  const inferPath = options.inferPath ?? '/chat';\n  const streamPath = options.streamPath ?? '/stream';\n  const blobUploadPath = options.blobUploadPath ?? '/blob/upload';\n  const toolCompletionPath = options.toolCompletionPath ?? '/tool-completion';\n  const busMode = options.busMode ?? false;\n  const baseUrl = options.baseUrl.replace(/\\/$/, '');\n\n  return {\n    resolveInferUrl(assistantId: string): string {\n      return `${baseUrl}${inferPath}/${assistantId}`;\n    },\n    resolveStreamUrl(streamId: string): string {\n      const url = `${baseUrl}${streamPath}/${streamId}`;\n      return busMode ? `${url}${url.includes('?') ? '&' : '?'}bus_mode=true` : url;\n    },\n    resolveBlobUploadUrl(): string {\n      return `${baseUrl}${blobUploadPath}`;\n    },\n    resolveToolCompletionUrl(): string {\n      return `${baseUrl}${toolCompletionPath}`;\n    },\n    getHeaders: options.getHeaders,\n  };\n}\n"],"mappings":";AAYO,SAAS,mBAAmB,SAA+C;AAChF,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,iBAAiB,QAAQ,kBAAkB;AACjD,QAAM,qBAAqB,QAAQ,sBAAsB;AACzD,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,UAAU,QAAQ,QAAQ,QAAQ,OAAO,EAAE;AAEjD,SAAO;AAAA,IACL,gBAAgB,aAA6B;AAC3C,aAAO,GAAG,OAAO,GAAG,SAAS,IAAI,WAAW;AAAA,IAC9C;AAAA,IACA,iBAAiB,UAA0B;AACzC,YAAM,MAAM,GAAG,OAAO,GAAG,UAAU,IAAI,QAAQ;AAC/C,aAAO,UAAU,GAAG,GAAG,GAAG,IAAI,SAAS,GAAG,IAAI,MAAM,GAAG,kBAAkB;AAAA,IAC3E;AAAA,IACA,uBAA+B;AAC7B,aAAO,GAAG,OAAO,GAAG,cAAc;AAAA,IACpC;AAAA,IACA,2BAAmC;AACjC,aAAO,GAAG,OAAO,GAAG,kBAAkB;AAAA,IACxC;AAAA,IACA,YAAY,QAAQ;AAAA,EACtB;AACF;","names":[]}
+{"version":3,"sources":["../../src/adapters/fetch.ts"],"sourcesContent":["import type { AlquimiaAdapter } from './index';\n\nexport interface FetchAdapterOptions {\n  baseUrl: string;\n  getHeaders?: () => Record<string, string>;\n  inferPath?: string;             // default: '/chat'\n  streamPath?: string;            // default: '/stream'\n  blobUploadPath?: string;        // default: '/blob/upload'\n  toolCompletionPath?: string;    // default: '/tool-completion'\n  toolApprovalPath?: string;      // default: '/tool-approval'\n  busMode?: boolean;              // default: false\n}\n\nexport function createFetchAdapter(options: FetchAdapterOptions): AlquimiaAdapter {\n  const inferPath = options.inferPath ?? '/chat';\n  const streamPath = options.streamPath ?? '/stream';\n  const blobUploadPath = options.blobUploadPath ?? '/blob/upload';\n  const toolCompletionPath = options.toolCompletionPath ?? '/tool-completion';\n  const toolApprovalPath = options.toolApprovalPath ?? '/tool-approval';\n  const busMode = options.busMode ?? false;\n  const baseUrl = options.baseUrl.replace(/\\/$/, '');\n\n  return {\n    resolveInferUrl(assistantId: string): string {\n      return `${baseUrl}${inferPath}/${assistantId}`;\n    },\n    resolveStreamUrl(streamId: string): string {\n      const url = `${baseUrl}${streamPath}/${streamId}`;\n      return busMode ? `${url}${url.includes('?') ? '&' : '?'}bus_mode=true` : url;\n    },\n    resolveBlobUploadUrl(): string {\n      return `${baseUrl}${blobUploadPath}`;\n    },\n    resolveToolCompletionUrl(): string {\n      return `${baseUrl}${toolCompletionPath}`;\n    },\n    resolveToolApprovalUrl(): string {\n      return `${baseUrl}${toolApprovalPath}`;\n    },\n    getHeaders: options.getHeaders,\n  };\n}\n"],"mappings":";AAaO,SAAS,mBAAmB,SAA+C;AAChF,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,iBAAiB,QAAQ,kBAAkB;AACjD,QAAM,qBAAqB,QAAQ,sBAAsB;AACzD,QAAM,mBAAmB,QAAQ,oBAAoB;AACrD,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,UAAU,QAAQ,QAAQ,QAAQ,OAAO,EAAE;AAEjD,SAAO;AAAA,IACL,gBAAgB,aAA6B;AAC3C,aAAO,GAAG,OAAO,GAAG,SAAS,IAAI,WAAW;AAAA,IAC9C;AAAA,IACA,iBAAiB,UAA0B;AACzC,YAAM,MAAM,GAAG,OAAO,GAAG,UAAU,IAAI,QAAQ;AAC/C,aAAO,UAAU,GAAG,GAAG,GAAG,IAAI,SAAS,GAAG,IAAI,MAAM,GAAG,kBAAkB;AAAA,IAC3E;AAAA,IACA,uBAA+B;AAC7B,aAAO,GAAG,OAAO,GAAG,cAAc;AAAA,IACpC;AAAA,IACA,2BAAmC;AACjC,aAAO,GAAG,OAAO,GAAG,kBAAkB;AAAA,IACxC;AAAA,IACA,yBAAiC;AAC/B,aAAO,GAAG,OAAO,GAAG,gBAAgB;AAAA,IACtC;AAAA,IACA,YAAY,QAAQ;AAAA,EACtB;AACF;","names":[]}

package/dist/adapters/index.d.mts

@@ -3,6 +3,7 @@ interface AlquimiaAdapter {
     resolveStreamUrl(_streamId: string): string;
     resolveBlobUploadUrl(): string;
     resolveToolCompletionUrl?(): string;
+    resolveToolApprovalUrl?(): string;
     getHeaders?(): Record<string, string>;
 }
 interface AlquimiaSDKOptions {

package/dist/adapters/index.d.ts

@@ -3,6 +3,7 @@ interface AlquimiaAdapter {
     resolveStreamUrl(_streamId: string): string;
     resolveBlobUploadUrl(): string;
     resolveToolCompletionUrl?(): string;
+    resolveToolApprovalUrl?(): string;
     getHeaders?(): Record<string, string>;
 }
 interface AlquimiaSDKOptions {

package/dist/adapters/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/index.ts"],"sourcesContent":["export interface AlquimiaAdapter {\n  resolveInferUrl(_assistantId: string): string;\n  resolveStreamUrl(_streamId: string): string;\n  resolveBlobUploadUrl(): string;\n  resolveToolCompletionUrl?(): string;\n  getHeaders?(): Record<string, string>;\n}\n\nexport interface AlquimiaSDKOptions {\n  enforceCharacterization?: boolean;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/adapters/index.ts"],"sourcesContent":["export interface AlquimiaAdapter {\n  resolveInferUrl(_assistantId: string): string;\n  resolveStreamUrl(_streamId: string): string;\n  resolveBlobUploadUrl(): string;\n  resolveToolCompletionUrl?(): string;\n  resolveToolApprovalUrl?(): string;\n  getHeaders?(): Record<string, string>;\n}\n\nexport interface AlquimiaSDKOptions {\n  enforceCharacterization?: boolean;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/adapters/next.d.mts

@@ -5,6 +5,7 @@ interface NextJsAdapterOptions {
     streamRoute?: string;
     blobUploadRoute?: string;
     toolCompletionRoute?: string;
+    toolApprovalRoute?: string;
     busMode?: boolean;
 }
 declare function createNextJsAdapter(options?: NextJsAdapterOptions): AlquimiaAdapter;

package/dist/adapters/next.d.ts

@@ -5,6 +5,7 @@ interface NextJsAdapterOptions {
     streamRoute?: string;
     blobUploadRoute?: string;
     toolCompletionRoute?: string;
+    toolApprovalRoute?: string;
     busMode?: boolean;
 }
 declare function createNextJsAdapter(options?: NextJsAdapterOptions): AlquimiaAdapter;

package/dist/adapters/next.js

@@ -28,6 +28,7 @@ function createNextJsAdapter(options) {
   const streamRoute = options?.streamRoute ?? "/api/stream";
   const blobUploadRoute = options?.blobUploadRoute ?? "/api/blob/upload";
   const toolCompletionRoute = options?.toolCompletionRoute ?? "/api/tool-completion";
+  const toolApprovalRoute = options?.toolApprovalRoute ?? "/api/tool-approval";
   const busMode = options?.busMode ?? false;
   return {
     resolveInferUrl(assistantId) {
@@ -42,6 +43,9 @@ function createNextJsAdapter(options) {
     },
     resolveToolCompletionUrl() {
       return toolCompletionRoute;
+    },
+    resolveToolApprovalUrl() {
+      return toolApprovalRoute;
     }
   };
 }

package/dist/adapters/next.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/next.ts"],"sourcesContent":["import type { AlquimiaAdapter } from './index';\n\nexport interface NextJsAdapterOptions {\n  inferRoute?: string;            // default: '/api/chat'\n  streamRoute?: string;           // default: '/api/stream'\n  blobUploadRoute?: string;       // default: '/api/blob/upload'\n  toolCompletionRoute?: string;   // default: '/api/tool-completion'\n  busMode?: boolean;              // default: false\n}\n\nexport function createNextJsAdapter(options?: NextJsAdapterOptions): AlquimiaAdapter {\n  const inferRoute = options?.inferRoute ?? '/api/chat';\n  const streamRoute = options?.streamRoute ?? '/api/stream';\n  const blobUploadRoute = options?.blobUploadRoute ?? '/api/blob/upload';\n  const toolCompletionRoute = options?.toolCompletionRoute ?? '/api/tool-completion';\n  const busMode = options?.busMode ?? false;\n\n  return {\n    resolveInferUrl(assistantId: string): string {\n      return `${inferRoute.replace(/\\/$/, '')}/${encodeURIComponent(assistantId)}`;\n    },\n    resolveStreamUrl(streamId: string): string {\n      const url = `${streamRoute}/${streamId}`;\n      return busMode ? `${url}${url.includes('?') ? '&' : '?'}bus_mode=true` : url;\n    },\n    resolveBlobUploadUrl(): string {\n      return blobUploadRoute;\n    },\n    resolveToolCompletionUrl(): string {\n      return toolCompletionRoute;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,SAAS,oBAAoB,SAAiD;AACnF,QAAM,aAAa,SAAS,cAAc;AAC1C,QAAM,cAAc,SAAS,eAAe;AAC5C,QAAM,kBAAkB,SAAS,mBAAmB;AACpD,QAAM,sBAAsB,SAAS,uBAAuB;AAC5D,QAAM,UAAU,SAAS,WAAW;AAEpC,SAAO;AAAA,IACL,gBAAgB,aAA6B;AAC3C,aAAO,GAAG,WAAW,QAAQ,OAAO,EAAE,CAAC,IAAI,mBAAmB,WAAW,CAAC;AAAA,IAC5E;AAAA,IACA,iBAAiB,UAA0B;AACzC,YAAM,MAAM,GAAG,WAAW,IAAI,QAAQ;AACtC,aAAO,UAAU,GAAG,GAAG,GAAG,IAAI,SAAS,GAAG,IAAI,MAAM,GAAG,kBAAkB;AAAA,IAC3E;AAAA,IACA,uBAA+B;AAC7B,aAAO;AAAA,IACT;AAAA,IACA,2BAAmC;AACjC,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/adapters/next.ts"],"sourcesContent":["import type { AlquimiaAdapter } from './index';\n\nexport interface NextJsAdapterOptions {\n  inferRoute?: string;            // default: '/api/chat'\n  streamRoute?: string;           // default: '/api/stream'\n  blobUploadRoute?: string;       // default: '/api/blob/upload'\n  toolCompletionRoute?: string;   // default: '/api/tool-completion'\n  toolApprovalRoute?: string;     // default: '/api/tool-approval'\n  busMode?: boolean;              // default: false\n}\n\nexport function createNextJsAdapter(options?: NextJsAdapterOptions): AlquimiaAdapter {\n  const inferRoute = options?.inferRoute ?? '/api/chat';\n  const streamRoute = options?.streamRoute ?? '/api/stream';\n  const blobUploadRoute = options?.blobUploadRoute ?? '/api/blob/upload';\n  const toolCompletionRoute = options?.toolCompletionRoute ?? '/api/tool-completion';\n  const toolApprovalRoute = options?.toolApprovalRoute ?? '/api/tool-approval';\n  const busMode = options?.busMode ?? false;\n\n  return {\n    resolveInferUrl(assistantId: string): string {\n      return `${inferRoute.replace(/\\/$/, '')}/${encodeURIComponent(assistantId)}`;\n    },\n    resolveStreamUrl(streamId: string): string {\n      const url = `${streamRoute}/${streamId}`;\n      return busMode ? `${url}${url.includes('?') ? '&' : '?'}bus_mode=true` : url;\n    },\n    resolveBlobUploadUrl(): string {\n      return blobUploadRoute;\n    },\n    resolveToolCompletionUrl(): string {\n      return toolCompletionRoute;\n    },\n    resolveToolApprovalUrl(): string {\n      return toolApprovalRoute;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAWO,SAAS,oBAAoB,SAAiD;AACnF,QAAM,aAAa,SAAS,cAAc;AAC1C,QAAM,cAAc,SAAS,eAAe;AAC5C,QAAM,kBAAkB,SAAS,mBAAmB;AACpD,QAAM,sBAAsB,SAAS,uBAAuB;AAC5D,QAAM,oBAAoB,SAAS,qBAAqB;AACxD,QAAM,UAAU,SAAS,WAAW;AAEpC,SAAO;AAAA,IACL,gBAAgB,aAA6B;AAC3C,aAAO,GAAG,WAAW,QAAQ,OAAO,EAAE,CAAC,IAAI,mBAAmB,WAAW,CAAC;AAAA,IAC5E;AAAA,IACA,iBAAiB,UAA0B;AACzC,YAAM,MAAM,GAAG,WAAW,IAAI,QAAQ;AACtC,aAAO,UAAU,GAAG,GAAG,GAAG,IAAI,SAAS,GAAG,IAAI,MAAM,GAAG,kBAAkB;AAAA,IAC3E;AAAA,IACA,uBAA+B;AAC7B,aAAO;AAAA,IACT;AAAA,IACA,2BAAmC;AACjC,aAAO;AAAA,IACT;AAAA,IACA,yBAAiC;AAC/B,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}

package/dist/adapters/next.mjs

@@ -4,6 +4,7 @@ function createNextJsAdapter(options) {
   const streamRoute = options?.streamRoute ?? "/api/stream";
   const blobUploadRoute = options?.blobUploadRoute ?? "/api/blob/upload";
   const toolCompletionRoute = options?.toolCompletionRoute ?? "/api/tool-completion";
+  const toolApprovalRoute = options?.toolApprovalRoute ?? "/api/tool-approval";
   const busMode = options?.busMode ?? false;
   return {
     resolveInferUrl(assistantId) {
@@ -18,6 +19,9 @@ function createNextJsAdapter(options) {
     },
     resolveToolCompletionUrl() {
       return toolCompletionRoute;
+    },
+    resolveToolApprovalUrl() {
+      return toolApprovalRoute;
     }
   };
 }

package/dist/adapters/next.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/next.ts"],"sourcesContent":["import type { AlquimiaAdapter } from './index';\n\nexport interface NextJsAdapterOptions {\n  inferRoute?: string;            // default: '/api/chat'\n  streamRoute?: string;           // default: '/api/stream'\n  blobUploadRoute?: string;       // default: '/api/blob/upload'\n  toolCompletionRoute?: string;   // default: '/api/tool-completion'\n  busMode?: boolean;              // default: false\n}\n\nexport function createNextJsAdapter(options?: NextJsAdapterOptions): AlquimiaAdapter {\n  const inferRoute = options?.inferRoute ?? '/api/chat';\n  const streamRoute = options?.streamRoute ?? '/api/stream';\n  const blobUploadRoute = options?.blobUploadRoute ?? '/api/blob/upload';\n  const toolCompletionRoute = options?.toolCompletionRoute ?? '/api/tool-completion';\n  const busMode = options?.busMode ?? false;\n\n  return {\n    resolveInferUrl(assistantId: string): string {\n      return `${inferRoute.replace(/\\/$/, '')}/${encodeURIComponent(assistantId)}`;\n    },\n    resolveStreamUrl(streamId: string): string {\n      const url = `${streamRoute}/${streamId}`;\n      return busMode ? `${url}${url.includes('?') ? '&' : '?'}bus_mode=true` : url;\n    },\n    resolveBlobUploadUrl(): string {\n      return blobUploadRoute;\n    },\n    resolveToolCompletionUrl(): string {\n      return toolCompletionRoute;\n    },\n  };\n}\n"],"mappings":";AAUO,SAAS,oBAAoB,SAAiD;AACnF,QAAM,aAAa,SAAS,cAAc;AAC1C,QAAM,cAAc,SAAS,eAAe;AAC5C,QAAM,kBAAkB,SAAS,mBAAmB;AACpD,QAAM,sBAAsB,SAAS,uBAAuB;AAC5D,QAAM,UAAU,SAAS,WAAW;AAEpC,SAAO;AAAA,IACL,gBAAgB,aAA6B;AAC3C,aAAO,GAAG,WAAW,QAAQ,OAAO,EAAE,CAAC,IAAI,mBAAmB,WAAW,CAAC;AAAA,IAC5E;AAAA,IACA,iBAAiB,UAA0B;AACzC,YAAM,MAAM,GAAG,WAAW,IAAI,QAAQ;AACtC,aAAO,UAAU,GAAG,GAAG,GAAG,IAAI,SAAS,GAAG,IAAI,MAAM,GAAG,kBAAkB;AAAA,IAC3E;AAAA,IACA,uBAA+B;AAC7B,aAAO;AAAA,IACT;AAAA,IACA,2BAAmC;AACjC,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/adapters/next.ts"],"sourcesContent":["import type { AlquimiaAdapter } from './index';\n\nexport interface NextJsAdapterOptions {\n  inferRoute?: string;            // default: '/api/chat'\n  streamRoute?: string;           // default: '/api/stream'\n  blobUploadRoute?: string;       // default: '/api/blob/upload'\n  toolCompletionRoute?: string;   // default: '/api/tool-completion'\n  toolApprovalRoute?: string;     // default: '/api/tool-approval'\n  busMode?: boolean;              // default: false\n}\n\nexport function createNextJsAdapter(options?: NextJsAdapterOptions): AlquimiaAdapter {\n  const inferRoute = options?.inferRoute ?? '/api/chat';\n  const streamRoute = options?.streamRoute ?? '/api/stream';\n  const blobUploadRoute = options?.blobUploadRoute ?? '/api/blob/upload';\n  const toolCompletionRoute = options?.toolCompletionRoute ?? '/api/tool-completion';\n  const toolApprovalRoute = options?.toolApprovalRoute ?? '/api/tool-approval';\n  const busMode = options?.busMode ?? false;\n\n  return {\n    resolveInferUrl(assistantId: string): string {\n      return `${inferRoute.replace(/\\/$/, '')}/${encodeURIComponent(assistantId)}`;\n    },\n    resolveStreamUrl(streamId: string): string {\n      const url = `${streamRoute}/${streamId}`;\n      return busMode ? `${url}${url.includes('?') ? '&' : '?'}bus_mode=true` : url;\n    },\n    resolveBlobUploadUrl(): string {\n      return blobUploadRoute;\n    },\n    resolveToolCompletionUrl(): string {\n      return toolCompletionRoute;\n    },\n    resolveToolApprovalUrl(): string {\n      return toolApprovalRoute;\n    },\n  };\n}\n"],"mappings":";AAWO,SAAS,oBAAoB,SAAiD;AACnF,QAAM,aAAa,SAAS,cAAc;AAC1C,QAAM,cAAc,SAAS,eAAe;AAC5C,QAAM,kBAAkB,SAAS,mBAAmB;AACpD,QAAM,sBAAsB,SAAS,uBAAuB;AAC5D,QAAM,oBAAoB,SAAS,qBAAqB;AACxD,QAAM,UAAU,SAAS,WAAW;AAEpC,SAAO;AAAA,IACL,gBAAgB,aAA6B;AAC3C,aAAO,GAAG,WAAW,QAAQ,OAAO,EAAE,CAAC,IAAI,mBAAmB,WAAW,CAAC;AAAA,IAC5E;AAAA,IACA,iBAAiB,UAA0B;AACzC,YAAM,MAAM,GAAG,WAAW,IAAI,QAAQ;AACtC,aAAO,UAAU,GAAG,GAAG,GAAG,IAAI,SAAS,GAAG,IAAI,MAAM,GAAG,kBAAkB;AAAA,IAC3E;AAAA,IACA,uBAA+B;AAC7B,aAAO;AAAA,IACT;AAAA,IACA,2BAAmC;AACjC,aAAO;AAAA,IACT;AAAA,IACA,yBAAiC;AAC/B,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}

package/dist/approvals-CcnmqUkQ.d.ts

@@ -0,0 +1,59 @@
+import { W as WorklogRecord } from './types-lOliroPw.js';
+
+/**
+ * Human-approval gates, derived from the worklog.
+ *
+ * When the runtime's authz policy resolves a tool call to `REQUIRE_APPROVAL`,
+ * core parks the call and records a `HumanApprovalRequired` whose `data` is the
+ * command minus its conversation: `{ parameters: <the tool execution> }`. The
+ * gate closes with a `HumanApprovalRequiredResponse` under the same
+ * `control_id`, whichever channel the decision came through — so the stream,
+ * not the local submit, is the source of truth for "settled".
+ */
+/** A decision as the worklog records it. */
+interface ApprovalDecision {
+    approved: boolean;
+    /**
+     * Rejection reason. Core records `result or message` as the response data,
+     * so an approval never carries one and a rejection carries the reason when
+     * the approver gave it.
+     */
+    reason: string | null;
+    decidedAt: string;
+}
+/** One approval gate, pending or settled. */
+interface ApprovalRequest {
+    /** The `HumanApprovalRequired` control id — the one `/event/tool-approval` expects. */
+    controlId: string;
+    /** Name of the parked tool call; `null` until the request record is seen. */
+    toolName: string | null;
+    /** Control id of the parked tool execution itself (distinct from `controlId`). */
+    toolCallId: string | null;
+    /** Arguments the tool would be called with. What is actually being approved. */
+    arguments: unknown;
+    /**
+     * The gate belongs to an MCP server that runs its own approval over the
+     * task's originating channel (the `mcp_approval` runtime extension). The
+     * runtime refuses an HTTP decision for it with a 409, so offering buttons
+     * would be a lie.
+     */
+    channelOwned: boolean;
+    requestedAt: string | null;
+    /** `null` while pending. */
+    decision: ApprovalDecision | null;
+}
+interface ApprovalsState {
+    /** Gates in the order they were first seen. */
+    order: string[];
+    byId: Record<string, ApprovalRequest>;
+}
+declare function initialApprovalsState(): ApprovalsState;
+/** Fold one worklog record into the approvals state. Records of other classes are a no-op. */
+declare function reduceApprovals(state: ApprovalsState, record: WorklogRecord): ApprovalsState;
+declare function foldApprovals(records: WorklogRecord[]): ApprovalsState;
+/** All gates, in first-seen order. */
+declare function listApprovals(state: ApprovalsState): ApprovalRequest[];
+/** Gates with no recorded decision yet. */
+declare function pendingApprovals(state: ApprovalsState): ApprovalRequest[];
+
+export { type ApprovalRequest as A, type ApprovalDecision as a, type ApprovalsState as b, foldApprovals as f, initialApprovalsState as i, listApprovals as l, pendingApprovals as p, reduceApprovals as r };

package/dist/approvals-dn4sd_Ot.d.mts

@@ -0,0 +1,59 @@
+import { W as WorklogRecord } from './types-lOliroPw.mjs';
+
+/**
+ * Human-approval gates, derived from the worklog.
+ *
+ * When the runtime's authz policy resolves a tool call to `REQUIRE_APPROVAL`,
+ * core parks the call and records a `HumanApprovalRequired` whose `data` is the
+ * command minus its conversation: `{ parameters: <the tool execution> }`. The
+ * gate closes with a `HumanApprovalRequiredResponse` under the same
+ * `control_id`, whichever channel the decision came through — so the stream,
+ * not the local submit, is the source of truth for "settled".
+ */
+/** A decision as the worklog records it. */
+interface ApprovalDecision {
+    approved: boolean;
+    /**
+     * Rejection reason. Core records `result or message` as the response data,
+     * so an approval never carries one and a rejection carries the reason when
+     * the approver gave it.
+     */
+    reason: string | null;
+    decidedAt: string;
+}
+/** One approval gate, pending or settled. */
+interface ApprovalRequest {
+    /** The `HumanApprovalRequired` control id — the one `/event/tool-approval` expects. */
+    controlId: string;
+    /** Name of the parked tool call; `null` until the request record is seen. */
+    toolName: string | null;
+    /** Control id of the parked tool execution itself (distinct from `controlId`). */
+    toolCallId: string | null;
+    /** Arguments the tool would be called with. What is actually being approved. */
+    arguments: unknown;
+    /**
+     * The gate belongs to an MCP server that runs its own approval over the
+     * task's originating channel (the `mcp_approval` runtime extension). The
+     * runtime refuses an HTTP decision for it with a 409, so offering buttons
+     * would be a lie.
+     */
+    channelOwned: boolean;
+    requestedAt: string | null;
+    /** `null` while pending. */
+    decision: ApprovalDecision | null;
+}
+interface ApprovalsState {
+    /** Gates in the order they were first seen. */
+    order: string[];
+    byId: Record<string, ApprovalRequest>;
+}
+declare function initialApprovalsState(): ApprovalsState;
+/** Fold one worklog record into the approvals state. Records of other classes are a no-op. */
+declare function reduceApprovals(state: ApprovalsState, record: WorklogRecord): ApprovalsState;
+declare function foldApprovals(records: WorklogRecord[]): ApprovalsState;
+/** All gates, in first-seen order. */
+declare function listApprovals(state: ApprovalsState): ApprovalRequest[];
+/** Gates with no recorded decision yet. */
+declare function pendingApprovals(state: ApprovalsState): ApprovalRequest[];
+
+export { type ApprovalRequest as A, type ApprovalDecision as a, type ApprovalsState as b, foldApprovals as f, initialApprovalsState as i, listApprovals as l, pendingApprovals as p, reduceApprovals as r };

package/dist/hooks/index.d.mts

@@ -1,11 +1,13 @@
 import * as react from 'react';
 import { AlquimiaSDK } from '../sdk/index.mjs';
 import { AlquimiaAdapter } from '../adapters/index.mjs';
-import { W as WhisperProvider, S as StableDiffusionProvider, C as CharacterizationProvider, R as RatingsProvider, L as LoggerProvider } from '../providers-B4IOiGfr.mjs';
-import { G as GenuiSurfaceItem, e as AlquimiaMessage, F as ToolEvent, a as AIMessageChunk, R as RatingData } from '../type-61gaZga-.mjs';
-import { T as ToolExecutionResponse } from '../types-CMVbyEv8.mjs';
-import { a as WorklogState } from '../types-lOliroPw.mjs';
+import { W as WhisperProvider, S as StableDiffusionProvider, C as CharacterizationProvider, R as RatingsProvider, L as LoggerProvider } from '../providers-YKiEag2L.mjs';
+import { G as GenuiSurfaceItem, a as AlquimiaMessage, b as ToolEvent, c as AIMessageChunk, R as RatingData } from '../type-C_sKpIM1.mjs';
+import { ToolApprovalResult } from '../types/index.mjs';
 import { createMessageId } from '../utils/index.mjs';
+import { a as WorklogState } from '../types-lOliroPw.mjs';
+import { A as ApprovalRequest } from '../approvals-dn4sd_Ot.mjs';
+import { T as ToolExecutionResponse } from '../types-CMVbyEv8.mjs';
 import { C as CatalogManifest } from '../registry-Bcu_ZYL1.mjs';
 import { U as UIAction } from '../actions-BjDPJdyA.mjs';
 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 };