@knocklabs/agent-toolkit 0.1.9 → 0.1.10

package/README.md

@@ -11,6 +11,7 @@
   - [Model Context Protocol (MCP)](#model-context-protocol-mcp)
   - [AI SDK](#ai-sdk)
   - [OpenAI](#openai)
+  - [Langchain](#langchain)
 
 ## Getting started
 
@@ -23,6 +24,7 @@ Using the Knock agent toolkit allows you to build powerful agent systems that ar
 The Knock Agent Toolkit provides three main entry points:
 
 - `@knocklabs/agent-toolkit/ai-sdk`: Helpers for integrating with Vercel's AI SDK.
+- `@knocklabs/agent-tookkit/langchain`: Helpers for integrating with [Langchain's JS SDK](https://github.com/langchain-ai/langchainjs).
 - `@knocklabs/agent-toolkit/openai`: Helpers for integrating with the OpenAI SDK.
 - `@knocklabs/agent-toolkit/modelcontextprotocol`: Low level helpers for integrating with the Model Context Protocol (MCP).
 
@@ -66,6 +68,12 @@ npx -y @knocklabs/agent-toolkit -p local-mcp --tools "workflows.*"
 npx -y @knocklabs/agent-toolkit -p local-mcp --tools "workflows.triggerWorkflow"
 ```
 
+If you wish to enable workflows-as-tools within the MCP server, you must set the `--workflows` flag to pass in a list of approved workflow keys to expose. This ensures that you keep the number of tools exposed to your MCP client to a minimum.
+
+```
+npx -y @knocklabs/agent-toolkit -p local-mcp --workflows comment-created activate-account
+```
+
 It's also possible to pass `environment`, `userId`, and `tenant` to the local MCP server to set default values. Use the `--help` flag to view additional server options.
 
 ### AI SDK
@@ -84,7 +92,6 @@ npm install @knocklabs/agent-toolkit
 import { createKnockToolkit } from "@knocklabs/agent-toolkit/ai-sdk";
 import { openai } from "@ai-sdk/openai";
 import { streamText } from "ai";
-import { auth } from "@clerk/nextjs/server";
 import { systemPrompt } from "@/lib/ai/prompts";
 
 export const maxDuration = 30;
@@ -132,25 +139,89 @@ import OpenAI from "openai";
 
 const openai = new OpenAI();
 
-const toolkit = await createKnockToolkit({
-  serviceToken: "kst_12345",
-  permissions: {
-    // Set the permissions of the tools to expose
-    workflows: { read: true, run: true, manage: true },
-  },
-});
-
-const completion = await openai.chat.completions.create({
-  model: "gpt-4o",
-  messages,
-  // The tools given here are determined by the `permissions`
-  // list above in the configuration. For instance, here we're only
-  // allowing the workflows
-  tools: toolkit.getAllTools(),
-});
-
-// Execute the tool calls
-const toolMessages = await Promise.all(
-  message.tool_calls.map((tc) => toolkit.handleToolCall(tc))
-);
+async function main() {
+  const toolkit = await createKnockToolkit({
+    serviceToken: "kst_12345",
+    permissions: {
+      // Set the permissions of the tools to expose
+      workflows: { read: true, run: true, manage: true },
+    },
+  });
+
+  const completion = await openai.chat.completions.create({
+    model: "gpt-4o",
+    messages,
+    // The tools given here are determined by the `permissions`
+    // list above in the configuration. For instance, here we're only
+    // allowing the workflows
+    tools: toolkit.getAllTools(),
+  });
+
+  // Execute the tool calls
+  const toolMessages = await Promise.all(
+    message.tool_calls.map((tc) => toolkit.handleToolCall(tc))
+  );
+}
+
+main();
+```
+
+### Langchain
+
+The agent toolkit provides a `createKnockToolkit` under the `/langchain` path for easily integrating into the Lanchain JS SDK and returning tools ready for use.
+
+1. Install the package:
+
+```
+npm install @knocklabs/agent-toolkit
+```
+
+2. Import the `createKnockToolkit` helper, configure it, and use it in your LLM calling:
+
+```typescript
+import { createKnockToolkit } from "@knocklabs/agent-toolkit/langchain";
+import { ChatOpenAI } from "@langchain/openai";
+import { HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { LangChainAdapter } from "ai";
+
+const systemPrompt = `You are a helpful assistant.`;
+
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { prompt } = await req.json();
+  // Optional - get the auth context from the request
+  const authContext = await auth.protect();
+
+  // Instantiate a new Knock toolkit
+  const toolkit = await createKnockToolkit({
+    serviceToken: "kst_12345",
+    permissions: {
+      // (optional but recommended): Set the permissions of the tools to expose
+      workflows: { read: true, run: true, manage: true },
+    },
+  });
+
+  const model = new ChatOpenAI({ model: "gpt-4o", temperature: 0 });
+
+  const modelWithTools = model.bindTools(toolkit.getAllTools());
+
+  const messages = [new SystemMessage(systemPrompt), new HumanMessage(prompt)];
+  const aiMessage = await modelWithTools.invoke(messages);
+  messages.push(aiMessage);
+
+  for (const toolCall of aiMessage.tool_calls || []) {
+    // Call the selected tool by its `name`
+    const selectedTool = toolkit.getToolMap()[toolCall.name];
+    const toolMessage = await selectedTool.invoke(toolCall);
+
+    messages.push(toolMessage);
+  }
+
+  // To simplify the setup, this example uses the ai-sdk langchain adapter
+  // to stream the results back to the /langchain page.
+  // For more details, see: https://sdk.vercel.ai/providers/adapters/langchain
+  const stream = await modelWithTools.stream(messages);
+  return LangChainAdapter.toDataStreamResponse(stream);
+}
 ```

package/dist/ai-sdk/index.d.ts

@@ -1,6 +1,28 @@
 import { ToolSet, Tool } from 'ai';
-import { T as ToolkitConfig, a as ToolCategory } from '../types-BJFe1DAl.js';
+import { a as DeferredToolCall, b as DeferredToolCallConfig, K as KnockOutboundWebhookEvent, D as DeferredToolCallInteractionResult } from '../types-CrTRlRnE.js';
+import { ToolkitConfig, ToolCategory } from '../types.js';
+import { ToolInvocation } from '@ai-sdk/ui-utils';
+import '@knocklabs/node/dist/src/resources/messages/interfaces';
 
+/**
+ * Convert a deferred tool call to a tool invocation. Useful when building an assistant
+ * response from a deferred tool call.
+ *
+ * @param deferredToolCall - The deferred tool call to convert.
+ * @param result - The result of the tool call.
+ * @returns The tool invocation.
+ */
+declare function deferredToolCallToToolInvocation(deferredToolCall: DeferredToolCall, result: unknown): ToolInvocation;
+
+type KnockToolkit = {
+    getAllTools: () => ToolSet;
+    getTools: (category: ToolCategory) => ToolSet;
+    getToolMap: () => Record<string, Tool>;
+    requireHumanInput: (toolsToWrap: ToolSet, inputConfig: DeferredToolCallConfig) => ToolSet;
+    resumeToolExecution: (toolInteraction: DeferredToolCall) => Promise<unknown>;
+    wrappedToolsRequiringInput: () => Map<string, Tool>;
+    handleMessageInteraction: (event: KnockOutboundWebhookEvent) => DeferredToolCallInteractionResult | null;
+};
 /**
  * Creates a Knock toolkit for use with the AI SDK.
  *
@@ -24,29 +46,6 @@ import { T as ToolkitConfig, a as ToolCategory } from '../types-BJFe1DAl.js';
  * @param config - The configuration to use for the toolkit
  * @returns A toolkit for use with the AI SDK
  */
-declare const createKnockToolkit: (config: ToolkitConfig) => Promise<{
-    /**
-     * Get all tools for all categories. When the `config.permissions.workflows.run` is set, then workflow triggers for
-     * the specified workflows will be included in the returned tools.
-     *
-     * @returns A promise that resolves to a set of tools
-     */
-    getAllTools: () => Promise<ToolSet>;
-    /**
-     * Get all tools for a specific category. When trying to get tools for the `workflows` category and the run permission is set,
-     * the workflow triggers for the specified workflows will be included in the returned tools.
-     *
-     * @param category - The category of tools to get
-     * @returns An array of tools for the given category
-     */
-    getTools: (category: ToolCategory) => Promise<ToolSet>;
-    /**
-     * Get a map of all tools by method name. When the `config.permissions.workflows.run` is set, then workflow triggers for
-     * the specified workflows will be included in the returned tools.
-     *
-     * @returns A map of all tools by method name
-     */
-    getToolMap: () => Promise<Record<string, Tool>>;
-}>;
+declare const createKnockToolkit: (config: ToolkitConfig) => Promise<KnockToolkit>;
 
-export { createKnockToolkit };
+export { createKnockToolkit, deferredToolCallToToolInvocation };

package/dist/ai-sdk/index.js

@@ -1,10 +1,16 @@
+import {
+  handleMessageInteraction,
+  triggerHumanInTheLoopWorkflow,
+  wrapToolDescription
+} from "../chunk-6O7VMHBN.js";
 import {
   createKnockClient
 } from "../chunk-OMZBTWDH.js";
 import {
   getToolMap,
   getToolsByPermissionsInCategories
-} from "../chunk-6UHXLKAV.js";
+} from "../chunk-25NTCHCG.js";
+import "../chunk-G3PMV62Z.js";
 
 // src/ai-sdk/tool-converter.ts
 import { tool } from "ai";
@@ -26,6 +32,18 @@ var knockToolsToToolSet = (knockClient, config, knockTools) => {
   );
 };
 
+// src/ai-sdk/helpers.ts
+function deferredToolCallToToolInvocation(deferredToolCall, result) {
+  return {
+    args: deferredToolCall.args,
+    toolName: deferredToolCall.method,
+    toolCallId: deferredToolCall.extra?.toolCallId,
+    state: "result",
+    step: 0,
+    result
+  };
+}
+
 // src/ai-sdk/index.ts
 var createKnockToolkit = async (config) => {
   const knockClient = createKnockClient(config);
@@ -35,14 +53,15 @@ var createKnockToolkit = async (config) => {
   );
   const allTools = Object.values(allowedToolsByCategory).flat();
   const toolsByMethod = getToolMap(allTools);
-  return {
+  const wrappedToolsRequiringInput = /* @__PURE__ */ new Map();
+  return Promise.resolve({
     /**
      * Get all tools for all categories. When the `config.permissions.workflows.run` is set, then workflow triggers for
      * the specified workflows will be included in the returned tools.
      *
      * @returns A promise that resolves to a set of tools
      */
-    getAllTools: async () => {
+    getAllTools: () => {
       return knockToolsToToolSet(knockClient, config, allTools);
     },
     /**
@@ -52,7 +71,7 @@ var createKnockToolkit = async (config) => {
      * @param category - The category of tools to get
      * @returns An array of tools for the given category
      */
-    getTools: async (category) => {
+    getTools: (category) => {
       return knockToolsToToolSet(
         knockClient,
         config,
@@ -65,7 +84,7 @@ var createKnockToolkit = async (config) => {
      *
      * @returns A map of all tools by method name
      */
-    getToolMap: async () => {
+    getToolMap: () => {
       return Object.entries(toolsByMethod).reduce(
         (acc, [method, tool2]) => ({
           ...acc,
@@ -73,10 +92,89 @@ var createKnockToolkit = async (config) => {
         }),
         {}
       );
-    }
-  };
+    },
+    /**
+     * Wraps one or more tools to require human input.
+     *
+     * @param toolsToWrap - The tools to wrap
+     * @param inputConfig - The configuration to use for the HITL request
+     */
+    requireHumanInput: (toolsToWrap, inputConfig) => {
+      const wrappedTools = {};
+      for (const [method, toolToWrap] of Object.entries(toolsToWrap)) {
+        wrappedToolsRequiringInput.set(method, { ...toolToWrap });
+        const wrappedTool = {
+          ...toolToWrap,
+          description: wrapToolDescription(toolToWrap.description ?? ""),
+          execute: async (input, options) => {
+            const toolExecution = {
+              method,
+              args: input,
+              extra: {
+                toolCallId: options.toolCallId
+              }
+            };
+            await triggerHumanInTheLoopWorkflow({
+              knockClient,
+              config,
+              toolCall: toolExecution,
+              inputConfig
+            });
+            return {
+              type: "tool-status",
+              status: "pending-input",
+              toolCallId: options.toolCallId
+            };
+          }
+        };
+        wrappedTools[method] = wrappedTool;
+      }
+      return wrappedTools;
+    },
+    /**
+     * Returns any tools that were wrapped with `requireHumanInput`.
+     *
+     * @returns A map of wrapped tools that require human input
+     */
+    wrappedToolsRequiringInput: () => wrappedToolsRequiringInput,
+    /**
+     * Resumes the execution of a tool that required human input.
+     *
+     * @param toolInteraction - The tool interaction to resume
+     * @returns A promise that resolves to the result of the tool execution
+     */
+    resumeToolExecution: async (toolInteraction) => {
+      const tool2 = wrappedToolsRequiringInput.get(toolInteraction.method);
+      if (!tool2) {
+        throw new Error(
+          `Tool "${toolInteraction.method}" not found. Did you forget to wrap the tool with requireHumanInput?`
+        );
+      }
+      if (!tool2.execute) {
+        throw new Error(
+          `Tool "${toolInteraction.method}" does not have an execute method. Nothing to resume.`
+        );
+      }
+      const options = toolInteraction.extra;
+      const result = await tool2.execute(toolInteraction.args, options);
+      return {
+        type: "tool-status",
+        status: "completed",
+        toolCallId: options.toolCallId,
+        result
+      };
+    },
+    /**
+     * Handles a message interaction event by parsing it into a well-known format.
+     *
+     * @param event - The message interaction event
+     * @returns An deferred tool call, or null if the event is not a message interaction
+     */
+    handleMessageInteraction
+  });
 };
 export {
-  createKnockToolkit
+  createKnockToolkit,
+  deferredToolCallToToolInvocation
 };
 //# sourceMappingURL=index.js.map

package/dist/ai-sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ai-sdk/tool-converter.ts","../../src/ai-sdk/index.ts"],"sourcesContent":["import type { Tool } from \"ai\";\nimport { tool } from \"ai\";\nimport { z } from \"zod\";\n\nimport { KnockClient } from \"../lib/knock-client.js\";\nimport { KnockTool } from \"../lib/knock-tool.js\";\nimport { Config } from \"../types.js\";\n\n/**\n * Convert a KnockTool to an AI Tool, ready to pass to the AI SDK.\n */\nconst knockToolToAiTool = (\n  knockClient: KnockClient,\n  config: Config,\n  knockTool: KnockTool\n): Tool => {\n  return tool({\n    description: knockTool.description,\n    parameters: knockTool.parameters ?? z.object({}),\n    execute: knockTool.bindExecute(knockClient, config),\n  });\n};\n\n/**\n * Convert a list of KnockTools to an AI ToolSet, ready to pass to the AI SDK.\n */\nconst knockToolsToToolSet = (\n  knockClient: KnockClient,\n  config: Config,\n  knockTools: KnockTool[]\n) => {\n  return knockTools.reduce(\n    (acc, tool) => {\n      acc[tool.method] = knockToolToAiTool(knockClient, config, tool);\n      return acc;\n    },\n    {} as Record<string, Tool>\n  );\n};\n\nexport { knockToolToAiTool, knockToolsToToolSet };\n","import { Tool, ToolSet } from \"ai\";\n\nimport { createKnockClient } from \"../lib/knock-client.js\";\nimport { getToolMap, getToolsByPermissionsInCategories } from \"../lib/utils.js\";\nimport { ToolCategory, ToolkitConfig } from \"../types.js\";\n\nimport { knockToolsToToolSet, knockToolToAiTool } from \"./tool-converter.js\";\n\n/**\n * Creates a Knock toolkit for use with the AI SDK.\n *\n * You can filter the set of tools that are available by setting the `config.permissions` property.\n *\n * When the `config.permissions.workflows.run` is set, then workflow triggers for\n * the specified workflows will be included in the returned tools.\n *\n * You can also specify a list of workflow keys to include in the returned tools, should you wish to\n * limit the set of workflows that are available.\n *\n * @example\n * ```ts\n * const toolkit = await createKnockToolkit({\n *   permissions: {\n *     workflows: { read: true },\n *   },\n * });\n * ```\n *\n * @param config - The configuration to use for the toolkit\n * @returns A toolkit for use with the AI SDK\n */\nconst createKnockToolkit = async (config: ToolkitConfig) => {\n  const knockClient = createKnockClient(config);\n  const allowedToolsByCategory = await getToolsByPermissionsInCategories(\n    knockClient,\n    config\n  );\n  const allTools = Object.values(allowedToolsByCategory).flat();\n  const toolsByMethod = getToolMap(allTools);\n\n  return {\n    /**\n     * Get all tools for all categories. When the `config.permissions.workflows.run` is set, then workflow triggers for\n     * the specified workflows will be included in the returned tools.\n     *\n     * @returns A promise that resolves to a set of tools\n     */\n    getAllTools: async (): Promise<ToolSet> => {\n      return knockToolsToToolSet(knockClient, config, allTools);\n    },\n\n    /**\n     * Get all tools for a specific category. When trying to get tools for the `workflows` category and the run permission is set,\n     * the workflow triggers for the specified workflows will be included in the returned tools.\n     *\n     * @param category - The category of tools to get\n     * @returns An array of tools for the given category\n     */\n    getTools: async (category: ToolCategory): Promise<ToolSet> => {\n      return knockToolsToToolSet(\n        knockClient,\n        config,\n        allowedToolsByCategory[category]\n      );\n    },\n\n    /**\n     * Get a map of all tools by method name. When the `config.permissions.workflows.run` is set, then workflow triggers for\n     * the specified workflows will be included in the returned tools.\n     *\n     * @returns A map of all tools by method name\n     */\n    getToolMap: async (): Promise<Record<string, Tool>> => {\n      return Object.entries(toolsByMethod).reduce(\n        (acc, [method, tool]) => ({\n          ...acc,\n          [method]: knockToolToAiTool(knockClient, config, tool),\n        }),\n        {} as Record<string, Tool>\n      );\n    },\n  };\n};\n\nexport { createKnockToolkit };\n"],"mappings":";;;;;;;;;AACA,SAAS,YAAY;AACrB,SAAS,SAAS;AASlB,IAAM,oBAAoB,CACxB,aACA,QACA,cACS;AACT,SAAO,KAAK;AAAA,IACV,aAAa,UAAU;AAAA,IACvB,YAAY,UAAU,cAAc,EAAE,OAAO,CAAC,CAAC;AAAA,IAC/C,SAAS,UAAU,YAAY,aAAa,MAAM;AAAA,EACpD,CAAC;AACH;AAKA,IAAM,sBAAsB,CAC1B,aACA,QACA,eACG;AACH,SAAO,WAAW;AAAA,IAChB,CAAC,KAAKA,UAAS;AACb,UAAIA,MAAK,MAAM,IAAI,kBAAkB,aAAa,QAAQA,KAAI;AAC9D,aAAO;AAAA,IACT;AAAA,IACA,CAAC;AAAA,EACH;AACF;;;ACPA,IAAM,qBAAqB,OAAO,WAA0B;AAC1D,QAAM,cAAc,kBAAkB,MAAM;AAC5C,QAAM,yBAAyB,MAAM;AAAA,IACnC;AAAA,IACA;AAAA,EACF;AACA,QAAM,WAAW,OAAO,OAAO,sBAAsB,EAAE,KAAK;AAC5D,QAAM,gBAAgB,WAAW,QAAQ;AAEzC,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOL,aAAa,YAA8B;AACzC,aAAO,oBAAoB,aAAa,QAAQ,QAAQ;AAAA,IAC1D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IASA,UAAU,OAAO,aAA6C;AAC5D,aAAO;AAAA,QACL;AAAA,QACA;AAAA,QACA,uBAAuB,QAAQ;AAAA,MACjC;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQA,YAAY,YAA2C;AACrD,aAAO,OAAO,QAAQ,aAAa,EAAE;AAAA,QACnC,CAAC,KAAK,CAAC,QAAQC,KAAI,OAAO;AAAA,UACxB,GAAG;AAAA,UACH,CAAC,MAAM,GAAG,kBAAkB,aAAa,QAAQA,KAAI;AAAA,QACvD;AAAA,QACA,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AACF;","names":["tool","tool"]}
+{"version":3,"sources":["../../src/ai-sdk/tool-converter.ts","../../src/ai-sdk/helpers.ts","../../src/ai-sdk/index.ts"],"sourcesContent":["import type { Tool } from \"ai\";\nimport { tool } from \"ai\";\nimport { z } from \"zod\";\n\nimport { KnockClient } from \"../lib/knock-client.js\";\nimport { KnockTool } from \"../lib/knock-tool.js\";\nimport { Config } from \"../types.js\";\n\n/**\n * Convert a KnockTool to an AI Tool, ready to pass to the AI SDK.\n */\nconst knockToolToAiTool = (\n  knockClient: KnockClient,\n  config: Config,\n  knockTool: KnockTool\n): Tool => {\n  return tool({\n    description: knockTool.description,\n    parameters: knockTool.parameters ?? z.object({}),\n    execute: knockTool.bindExecute(knockClient, config),\n  });\n};\n\n/**\n * Convert a list of KnockTools to an AI ToolSet, ready to pass to the AI SDK.\n */\nconst knockToolsToToolSet = (\n  knockClient: KnockClient,\n  config: Config,\n  knockTools: KnockTool[]\n) => {\n  return knockTools.reduce(\n    (acc, tool) => {\n      acc[tool.method] = knockToolToAiTool(knockClient, config, tool);\n      return acc;\n    },\n    {} as Record<string, Tool>\n  );\n};\n\nexport { knockToolToAiTool, knockToolsToToolSet };\n","import { ToolInvocation } from \"@ai-sdk/ui-utils\";\n\nimport { DeferredToolCall } from \"@/lib/human-in-the-loop/types\";\n\n/**\n * Convert a deferred tool call to a tool invocation. Useful when building an assistant\n * response from a deferred tool call.\n *\n * @param deferredToolCall - The deferred tool call to convert.\n * @param result - The result of the tool call.\n * @returns The tool invocation.\n */\nfunction deferredToolCallToToolInvocation(\n  deferredToolCall: DeferredToolCall,\n  result: unknown\n): ToolInvocation {\n  return {\n    args: deferredToolCall.args,\n    toolName: deferredToolCall.method,\n    toolCallId: deferredToolCall.extra?.toolCallId as string,\n    state: \"result\",\n    step: 0,\n    result,\n  };\n}\n\nexport { deferredToolCallToToolInvocation };\n","import { Tool, ToolExecutionOptions, ToolSet } from \"ai\";\n\nimport {\n  handleMessageInteraction,\n  triggerHumanInTheLoopWorkflow,\n  wrapToolDescription,\n} from \"../lib/human-in-the-loop/index.js\";\nimport {\n  DeferredToolCall,\n  DeferredToolCallConfig,\n  KnockOutboundWebhookEvent,\n  DeferredToolCallInteractionResult,\n} from \"../lib/human-in-the-loop/types.js\";\nimport { createKnockClient } from \"../lib/knock-client.js\";\nimport { getToolMap, getToolsByPermissionsInCategories } from \"../lib/utils.js\";\nimport { ToolCategory, ToolkitConfig } from \"../types.js\";\n\nimport { knockToolsToToolSet, knockToolToAiTool } from \"./tool-converter.js\";\n\ntype KnockToolkit = {\n  getAllTools: () => ToolSet;\n  getTools: (category: ToolCategory) => ToolSet;\n  getToolMap: () => Record<string, Tool>;\n  requireHumanInput: (\n    toolsToWrap: ToolSet,\n    inputConfig: DeferredToolCallConfig\n  ) => ToolSet;\n  resumeToolExecution: (toolInteraction: DeferredToolCall) => Promise<unknown>;\n  wrappedToolsRequiringInput: () => Map<string, Tool>;\n  handleMessageInteraction: (\n    event: KnockOutboundWebhookEvent\n  ) => DeferredToolCallInteractionResult | null;\n};\n\n/**\n * Creates a Knock toolkit for use with the AI SDK.\n *\n * You can filter the set of tools that are available by setting the `config.permissions` property.\n *\n * When the `config.permissions.workflows.run` is set, then workflow triggers for\n * the specified workflows will be included in the returned tools.\n *\n * You can also specify a list of workflow keys to include in the returned tools, should you wish to\n * limit the set of workflows that are available.\n *\n * @example\n * ```ts\n * const toolkit = await createKnockToolkit({\n *   permissions: {\n *     workflows: { read: true },\n *   },\n * });\n * ```\n *\n * @param config - The configuration to use for the toolkit\n * @returns A toolkit for use with the AI SDK\n */\nconst createKnockToolkit = async (\n  config: ToolkitConfig\n): Promise<KnockToolkit> => {\n  const knockClient = createKnockClient(config);\n  const allowedToolsByCategory = await getToolsByPermissionsInCategories(\n    knockClient,\n    config\n  );\n  const allTools = Object.values(allowedToolsByCategory).flat();\n  const toolsByMethod = getToolMap(allTools);\n\n  const wrappedToolsRequiringInput = new Map<string, Tool>();\n\n  return Promise.resolve({\n    /**\n     * Get all tools for all categories. When the `config.permissions.workflows.run` is set, then workflow triggers for\n     * the specified workflows will be included in the returned tools.\n     *\n     * @returns A promise that resolves to a set of tools\n     */\n    getAllTools: (): ToolSet => {\n      return knockToolsToToolSet(knockClient, config, allTools);\n    },\n\n    /**\n     * Get all tools for a specific category. When trying to get tools for the `workflows` category and the run permission is set,\n     * the workflow triggers for the specified workflows will be included in the returned tools.\n     *\n     * @param category - The category of tools to get\n     * @returns An array of tools for the given category\n     */\n    getTools: (category: ToolCategory): ToolSet => {\n      return knockToolsToToolSet(\n        knockClient,\n        config,\n        allowedToolsByCategory[category]\n      );\n    },\n\n    /**\n     * Get a map of all tools by method name. When the `config.permissions.workflows.run` is set, then workflow triggers for\n     * the specified workflows will be included in the returned tools.\n     *\n     * @returns A map of all tools by method name\n     */\n    getToolMap: (): Record<string, Tool> => {\n      return Object.entries(toolsByMethod).reduce(\n        (acc, [method, tool]) => ({\n          ...acc,\n          [method]: knockToolToAiTool(knockClient, config, tool),\n        }),\n        {} as Record<string, Tool>\n      );\n    },\n\n    /**\n     * Wraps one or more tools to require human input.\n     *\n     * @param toolsToWrap - The tools to wrap\n     * @param inputConfig - The configuration to use for the HITL request\n     */\n    requireHumanInput: (\n      toolsToWrap: ToolSet,\n      inputConfig: DeferredToolCallConfig\n    ): ToolSet => {\n      const wrappedTools: Record<string, Tool> = {};\n\n      for (const [method, toolToWrap] of Object.entries(toolsToWrap)) {\n        // Keep a reference to the original tool so we can use it later\n        wrappedToolsRequiringInput.set(method, { ...toolToWrap });\n\n        const wrappedTool = {\n          ...toolToWrap,\n          description: wrapToolDescription(toolToWrap.description ?? \"\"),\n          execute: async (input: any, options: ToolExecutionOptions) => {\n            const toolExecution = {\n              method,\n              args: input,\n              extra: {\n                toolCallId: options.toolCallId,\n              },\n            };\n\n            await triggerHumanInTheLoopWorkflow({\n              knockClient,\n              config,\n              toolCall: toolExecution,\n              inputConfig,\n            });\n\n            // TODO: Consider injecting a hook here to allow the AI SDK to react to the tool call being deferred\n            return {\n              type: \"tool-status\",\n              status: \"pending-input\",\n              toolCallId: options.toolCallId,\n            };\n          },\n        };\n\n        wrappedTools[method] = wrappedTool;\n      }\n\n      return wrappedTools;\n    },\n\n    /**\n     * Returns any tools that were wrapped with `requireHumanInput`.\n     *\n     * @returns A map of wrapped tools that require human input\n     */\n    wrappedToolsRequiringInput: () => wrappedToolsRequiringInput,\n\n    /**\n     * Resumes the execution of a tool that required human input.\n     *\n     * @param toolInteraction - The tool interaction to resume\n     * @returns A promise that resolves to the result of the tool execution\n     */\n    resumeToolExecution: async (toolInteraction: DeferredToolCall) => {\n      const tool = wrappedToolsRequiringInput.get(toolInteraction.method);\n\n      if (!tool) {\n        throw new Error(\n          `Tool \"${toolInteraction.method}\" not found. Did you forget to wrap the tool with requireHumanInput?`\n        );\n      }\n\n      if (!tool.execute) {\n        throw new Error(\n          `Tool \"${toolInteraction.method}\" does not have an execute method. Nothing to resume.`\n        );\n      }\n\n      const options = toolInteraction.extra as unknown as ToolExecutionOptions;\n      const result = await tool.execute(toolInteraction.args, options);\n\n      // Return two message objects to represent the tool call and the call result having\n      // finished. Note: this can result in duplicate tool call IDs being present in the message history.\n      return {\n        type: \"tool-status\",\n        status: \"completed\",\n        toolCallId: options.toolCallId,\n        result,\n      };\n    },\n\n    /**\n     * Handles a message interaction event by parsing it into a well-known format.\n     *\n     * @param event - The message interaction event\n     * @returns An deferred tool call, or null if the event is not a message interaction\n     */\n    handleMessageInteraction,\n  });\n};\n\nexport * from \"./helpers.js\";\nexport { createKnockToolkit };\n"],"mappings":"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","names":["tool","tool"]}