feat: improve hitl calling code from real-world usage

.changeset/rude-maps-add.md

@@ -0,0 +1,5 @@
+---
+"@knocklabs/agent-toolkit": patch
+---
+
+feat: improve hitl methods based on real usage

package.json

@@ -52,8 +52,8 @@
     "dist"
   ],
   "dependencies": {
-    "@knocklabs/mgmt": "^0.1.0-rc.0",
-    "@knocklabs/node": "^0.6.18",
+    "@knocklabs/mgmt": "^0.1.0",
+    "@knocklabs/node": "^0.6.19",
     "@modelcontextprotocol/sdk": "^1.7.0",
     "json-schema-to-zod": "^2.6.1",
     "uuid": "^11.1.0",

src/ai-sdk/index.ts

@@ -129,6 +129,7 @@ const createKnockToolkit = async (
           description: wrapToolDescription(toolToWrap.description ?? ""),
           execute: async (input: any, options: ToolExecutionOptions) => {
             const toolExecution = {
+              id: options.toolCallId,
               method,
               args: input,
               extra: {

src/lib/human-in-the-loop/index.ts

@@ -1,3 +1,5 @@
+import { Recipient } from "@knocklabs/node";
+
 import { Config } from "@/types";
 
 import { KnockClient } from "../knock-client";
@@ -34,17 +36,25 @@ async function triggerHumanInTheLoopWorkflow({
 }) {
   const knock = await knockClient.publicApi(config.environment);
 
+  if (inputConfig.onBeforeCallKnock) {
+    await inputConfig.onBeforeCallKnock(toolCall);
+  }
+
   const result = await knock.workflows.trigger(inputConfig.workflow, {
     data: {
       type: "deferred_tool_call",
       tool_call: toolCall,
       metadata: inputConfig.metadata,
     } as DeferredToolCallWorkflowData,
-    recipients: inputConfig.recipients,
+    recipients: inputConfig.recipients as Recipient[],
     tenant: inputConfig.tenant,
-    actor: inputConfig.actor,
+    actor: inputConfig.actor as Recipient,
   });
 
+  if (inputConfig.onAfterCallKnock) {
+    await inputConfig.onAfterCallKnock(toolCall, result);
+  }
+
   return result;
 }
 
@@ -77,6 +87,7 @@ function handleMessageInteraction(
     workflow: message.source.key,
     interaction: event.event_data,
     toolCall: {
+      id: messageData.tool_call.id,
       method: messageData.tool_call.method,
       args: messageData.tool_call.args,
       extra: messageData.tool_call.extra,

src/lib/human-in-the-loop/types.ts

@@ -1,4 +1,5 @@
 import { Message } from "@knocklabs/node/dist/src/resources/messages/interfaces";
+import { WorkflowRun } from "@knocklabs/node/dist/src/resources/workflows/interfaces";
 
 type Metadata = Record<string, unknown> | undefined;
 
@@ -22,7 +23,7 @@ export interface DeferredToolCallConfig {
   /**
    * The recipients to trigger the workflow for.
    */
-  recipients: string[];
+  recipients: string[] | Record<string, unknown>[];
   /**
    * Any extra data to pass to the workflow as context.
    */
@@ -34,10 +35,28 @@ export interface DeferredToolCallConfig {
   /**
    * The actor to trigger the workflow for.
    */
-  actor?: string;
+  actor?: string | Record<string, unknown>;
+
+  /**
+   * A function to call before calling the Knock API.
+   */
+  onBeforeCallKnock?: (toolCall: DeferredToolCall) => Promise<void>;
+
+  /**
+   * A function to call after calling the Knock API.
+   */
+  onAfterCallKnock?: (
+    toolCall: DeferredToolCall,
+    result: WorkflowRun
+  ) => Promise<void>;
 }
 
 export type DeferredToolCall = {
+  /**
+   * The ID of the tool call. Should be automatically generated by the SDK.
+   */
+  id: string;
+
   /**
    * The method of the tool that was called.
    */