@quilltap/plugin-types 1.8.1 → 1.9.0

package/dist/index.d.mts

@@ -67,6 +67,10 @@ interface ToolExecutionResult {
 /**
  * Tool Plugin Interface
  *
+ * All tool plugins use the multi-tool pattern, providing an array of tools
+ * (even if it's just one tool). This standardized approach makes it easy
+ * to extend plugins with additional tools over time.
+ *
  * Plugins implementing this interface can be dynamically loaded and used
  * by Quilltap to provide custom tools for LLM interactions.
  *
@@ -74,22 +78,24 @@ interface ToolExecutionResult {
  * ```typescript
  * import type { ToolPlugin, UniversalTool, ToolExecutionContext, ToolExecutionResult } from '@quilltap/plugin-types';
  *
+ * const curlToolDefinition: UniversalTool = {
+ *   type: 'function',
+ *   function: {
+ *     name: 'curl',
+ *     description: 'Make HTTP requests...',
+ *     parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] }
+ *   }
+ * };
+ *
  * const curlPlugin: ToolPlugin = {
  *   metadata: {
  *     toolName: 'curl',
  *     displayName: 'curl',
  *     description: 'Make HTTP requests to fetch web content',
  *   },
- *   getToolDefinition: () => ({
- *     type: 'function',
- *     function: {
- *       name: 'curl',
- *       description: 'Make HTTP requests...',
- *       parameters: { ... }
- *     }
- *   }),
+ *   getToolDefinitions: async () => [curlToolDefinition],
  *   validateInput: (input) => typeof input === 'object' && input !== null && 'url' in input,
- *   execute: async (input, context) => {
+ *   executeByName: async (toolName, input, context) => {
  *     // Implementation
  *     return { success: true, result: { ... } };
  *   },
@@ -105,35 +111,40 @@ interface ToolPlugin {
      */
     metadata: ToolMetadata;
     /**
-     * Get the tool definition in universal (OpenAI) format
+     * Get tool definitions in universal (OpenAI) format
+     *
+     * Returns an array of tool definitions that will be sent to LLMs.
+     * Even single-tool plugins return an array (with one element).
+     *
+     * This method is async to allow plugins to perform initialization
+     * or network requests during tool discovery (e.g., MCP servers).
+     *
+     * @param config User configuration for this plugin
+     * @returns Promise resolving to array of tool definitions in universal format
+     */
+    getToolDefinitions: (config: Record<string, unknown>) => Promise<UniversalTool[]>;
+    /**
+     * Execute a tool by name
      *
-     * Returns the tool's schema that will be sent to LLMs.
-     * This is called when building tool arrays for LLM requests.
+     * The registry routes execution to this method based on the tool name.
+     * For single-tool plugins, the toolName will match metadata.toolName.
      *
-     * @returns Tool definition in universal format
+     * @param toolName The name of the tool to execute
+     * @param input The input arguments from the LLM
+     * @param context Execution context with user/chat info and config
+     * @returns Promise resolving to the execution result
      */
-    getToolDefinition: () => UniversalTool;
+    executeByName: (toolName: string, input: Record<string, unknown>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
     /**
      * Validate input arguments before execution
      *
      * Checks whether the provided input matches the expected schema.
-     * Called before execute() to ensure valid inputs.
+     * Called before executeByName() to ensure valid inputs.
      *
      * @param input The input arguments to validate
      * @returns true if valid, false otherwise
      */
     validateInput: (input: unknown) => boolean;
-    /**
-     * Execute the tool with the given input and context
-     *
-     * This is the main tool execution logic. It receives the parsed
-     * arguments from the LLM and returns the result.
-     *
-     * @param input The input arguments from the LLM
-     * @param context Execution context with user/chat info and config
-     * @returns Promise resolving to the execution result
-     */
-    execute: (input: Record<string, unknown>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
     /**
      * Format results for LLM consumption
      *
@@ -175,32 +186,6 @@ interface ToolPlugin {
     renderIcon?: (props: {
         className?: string;
     }) => React.ReactNode;
-    /**
-     * Get multiple tool definitions (optional)
-     *
-     * For plugins that provide multiple tools dynamically (e.g., MCP connector).
-     * When implemented, the registry will call this at request time (not startup)
-     * to get the current list of tools based on configuration.
-     *
-     * This allows plugins to discover tools dynamically based on user config
-     * (e.g., MCP servers to connect to).
-     *
-     * @param config User configuration for this plugin
-     * @returns Array of tool definitions in universal format
-     */
-    getMultipleToolDefinitions?: (config: Record<string, unknown>) => UniversalTool[];
-    /**
-     * Execute a specific tool by name (optional)
-     *
-     * Required when getMultipleToolDefinitions is implemented.
-     * The registry routes execution to this method based on the tool name.
-     *
-     * @param toolName The name of the tool to execute (as returned by getMultipleToolDefinitions)
-     * @param input The input arguments from the LLM
-     * @param context Execution context with user/chat info and config
-     * @returns Promise resolving to the execution result
-     */
-    executeByName?: (toolName: string, input: Record<string, unknown>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
     /**
      * Called when configuration changes (optional)
      *
@@ -210,6 +195,21 @@ interface ToolPlugin {
      * @param config The updated user configuration
      */
     onConfigurationChange?: (config: Record<string, unknown>) => Promise<void>;
+    /**
+     * @deprecated Use getToolDefinitions instead. This method is for backwards
+     * compatibility only and will be removed in a future version.
+     */
+    getToolDefinition?: () => UniversalTool;
+    /**
+     * @deprecated Use executeByName instead. This method is for backwards
+     * compatibility only and will be removed in a future version.
+     */
+    execute?: (input: Record<string, unknown>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
+    /**
+     * @deprecated Use getToolDefinitions instead. This method is for backwards
+     * compatibility only and will be removed in a future version.
+     */
+    getMultipleToolDefinitions?: (config: Record<string, unknown>) => Promise<UniversalTool[]>;
 }
 /**
  * Standard export type for tool plugins

package/dist/index.d.ts

@@ -67,6 +67,10 @@ interface ToolExecutionResult {
 /**
  * Tool Plugin Interface
  *
+ * All tool plugins use the multi-tool pattern, providing an array of tools
+ * (even if it's just one tool). This standardized approach makes it easy
+ * to extend plugins with additional tools over time.
+ *
  * Plugins implementing this interface can be dynamically loaded and used
  * by Quilltap to provide custom tools for LLM interactions.
  *
@@ -74,22 +78,24 @@ interface ToolExecutionResult {
  * ```typescript
  * import type { ToolPlugin, UniversalTool, ToolExecutionContext, ToolExecutionResult } from '@quilltap/plugin-types';
  *
+ * const curlToolDefinition: UniversalTool = {
+ *   type: 'function',
+ *   function: {
+ *     name: 'curl',
+ *     description: 'Make HTTP requests...',
+ *     parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] }
+ *   }
+ * };
+ *
  * const curlPlugin: ToolPlugin = {
  *   metadata: {
  *     toolName: 'curl',
  *     displayName: 'curl',
  *     description: 'Make HTTP requests to fetch web content',
  *   },
- *   getToolDefinition: () => ({
- *     type: 'function',
- *     function: {
- *       name: 'curl',
- *       description: 'Make HTTP requests...',
- *       parameters: { ... }
- *     }
- *   }),
+ *   getToolDefinitions: async () => [curlToolDefinition],
  *   validateInput: (input) => typeof input === 'object' && input !== null && 'url' in input,
- *   execute: async (input, context) => {
+ *   executeByName: async (toolName, input, context) => {
  *     // Implementation
  *     return { success: true, result: { ... } };
  *   },
@@ -105,35 +111,40 @@ interface ToolPlugin {
      */
     metadata: ToolMetadata;
     /**
-     * Get the tool definition in universal (OpenAI) format
+     * Get tool definitions in universal (OpenAI) format
+     *
+     * Returns an array of tool definitions that will be sent to LLMs.
+     * Even single-tool plugins return an array (with one element).
+     *
+     * This method is async to allow plugins to perform initialization
+     * or network requests during tool discovery (e.g., MCP servers).
+     *
+     * @param config User configuration for this plugin
+     * @returns Promise resolving to array of tool definitions in universal format
+     */
+    getToolDefinitions: (config: Record<string, unknown>) => Promise<UniversalTool[]>;
+    /**
+     * Execute a tool by name
      *
-     * Returns the tool's schema that will be sent to LLMs.
-     * This is called when building tool arrays for LLM requests.
+     * The registry routes execution to this method based on the tool name.
+     * For single-tool plugins, the toolName will match metadata.toolName.
      *
-     * @returns Tool definition in universal format
+     * @param toolName The name of the tool to execute
+     * @param input The input arguments from the LLM
+     * @param context Execution context with user/chat info and config
+     * @returns Promise resolving to the execution result
      */
-    getToolDefinition: () => UniversalTool;
+    executeByName: (toolName: string, input: Record<string, unknown>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
     /**
      * Validate input arguments before execution
      *
      * Checks whether the provided input matches the expected schema.
-     * Called before execute() to ensure valid inputs.
+     * Called before executeByName() to ensure valid inputs.
      *
      * @param input The input arguments to validate
      * @returns true if valid, false otherwise
      */
     validateInput: (input: unknown) => boolean;
-    /**
-     * Execute the tool with the given input and context
-     *
-     * This is the main tool execution logic. It receives the parsed
-     * arguments from the LLM and returns the result.
-     *
-     * @param input The input arguments from the LLM
-     * @param context Execution context with user/chat info and config
-     * @returns Promise resolving to the execution result
-     */
-    execute: (input: Record<string, unknown>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
     /**
      * Format results for LLM consumption
      *
@@ -175,32 +186,6 @@ interface ToolPlugin {
     renderIcon?: (props: {
         className?: string;
     }) => React.ReactNode;
-    /**
-     * Get multiple tool definitions (optional)
-     *
-     * For plugins that provide multiple tools dynamically (e.g., MCP connector).
-     * When implemented, the registry will call this at request time (not startup)
-     * to get the current list of tools based on configuration.
-     *
-     * This allows plugins to discover tools dynamically based on user config
-     * (e.g., MCP servers to connect to).
-     *
-     * @param config User configuration for this plugin
-     * @returns Array of tool definitions in universal format
-     */
-    getMultipleToolDefinitions?: (config: Record<string, unknown>) => UniversalTool[];
-    /**
-     * Execute a specific tool by name (optional)
-     *
-     * Required when getMultipleToolDefinitions is implemented.
-     * The registry routes execution to this method based on the tool name.
-     *
-     * @param toolName The name of the tool to execute (as returned by getMultipleToolDefinitions)
-     * @param input The input arguments from the LLM
-     * @param context Execution context with user/chat info and config
-     * @returns Promise resolving to the execution result
-     */
-    executeByName?: (toolName: string, input: Record<string, unknown>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
     /**
      * Called when configuration changes (optional)
      *
@@ -210,6 +195,21 @@ interface ToolPlugin {
      * @param config The updated user configuration
      */
     onConfigurationChange?: (config: Record<string, unknown>) => Promise<void>;
+    /**
+     * @deprecated Use getToolDefinitions instead. This method is for backwards
+     * compatibility only and will be removed in a future version.
+     */
+    getToolDefinition?: () => UniversalTool;
+    /**
+     * @deprecated Use executeByName instead. This method is for backwards
+     * compatibility only and will be removed in a future version.
+     */
+    execute?: (input: Record<string, unknown>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
+    /**
+     * @deprecated Use getToolDefinitions instead. This method is for backwards
+     * compatibility only and will be removed in a future version.
+     */
+    getMultipleToolDefinitions?: (config: Record<string, unknown>) => Promise<UniversalTool[]>;
 }
 /**
  * Standard export type for tool plugins

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quilltap/plugin-types",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Type definitions for Quilltap plugin development",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",