@lleverage-ai/agent-sdk 0.0.1

package/dist/tools/user-interaction.d.ts

@@ -0,0 +1,116 @@
+/**
+ * User interaction tools for agent-user communication.
+ *
+ * These tools allow agents to ask clarifying questions and get user input
+ * during execution. This enables interactive workflows where the agent
+ * needs additional information from the user to proceed.
+ *
+ * @packageDocumentation
+ */
+/**
+ * An option for a multiple-choice question.
+ */
+export interface QuestionOption {
+    /** Display label for this option */
+    label: string;
+    /** Description of what this option means or what will happen if chosen */
+    description?: string;
+    /** Value to return if this option is selected */
+    value: string;
+}
+/**
+ * Callback function to prompt the user for input.
+ *
+ * @param question - The question to ask the user
+ * @param options - Available answer options
+ * @param multiSelect - Whether the user can select multiple options
+ * @returns The selected option value(s) as string or string array
+ */
+export type AskUserCallback = (question: string, options: QuestionOption[], multiSelect: boolean) => Promise<string | string[]>;
+/**
+ * Creates a tool for asking the user clarifying questions.
+ *
+ * This tool allows agents to request additional information from users
+ * during execution. It supports both single-select and multi-select
+ * questions with multiple choice options.
+ *
+ * The tool requires a callback function that handles the actual UI
+ * interaction with the user. The callback receives the question and
+ * options, prompts the user, and returns their selection.
+ *
+ * @param onAskUser - Callback function to handle user prompts
+ * @returns An AI SDK compatible tool for asking questions
+ *
+ * @example
+ * Single-select question
+ * ```typescript
+ * import { createAskUserQuestionTool } from "@lleverage-ai/agent-sdk";
+ *
+ * const askUserQuestion = createAskUserQuestionTool(
+ *   async (question, options, multiSelect) => {
+ *     console.log(question);
+ *     options.forEach((opt, i) => {
+ *       console.log(`${i + 1}. ${opt.label}: ${opt.description}`);
+ *     });
+ *     const answer = await getUserInput(); // Your UI logic
+ *     return options[answer - 1].value;
+ *   }
+ * );
+ *
+ * const agent = createAgent({
+ *   model,
+ *   tools: { askUserQuestion },
+ * });
+ * ```
+ *
+ * @example
+ * Multi-select question
+ * ```typescript
+ * const askUserQuestion = createAskUserQuestionTool(
+ *   async (question, options, multiSelect) => {
+ *     if (multiSelect) {
+ *       // Show checkboxes, allow multiple selections
+ *       const selected = await getUserMultipleChoices();
+ *       return selected.map(i => options[i].value);
+ *     }
+ *     // Single select logic
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * Integration with UI framework
+ * ```typescript
+ * // React example
+ * const askUserQuestion = createAskUserQuestionTool(
+ *   async (question, options, multiSelect) => {
+ *     return new Promise((resolve) => {
+ *       setQuestion({ question, options, multiSelect, resolve });
+ *     });
+ *   }
+ * );
+ *
+ * // In your React component:
+ * function QuestionDialog({ question, options, multiSelect, resolve }) {
+ *   const [selected, setSelected] = useState([]);
+ *
+ *   const handleSubmit = () => {
+ *     if (multiSelect) {
+ *       resolve(selected);
+ *     } else {
+ *       resolve(selected[0]);
+ *     }
+ *   };
+ *
+ *   // Render question UI...
+ * }
+ * ```
+ *
+ * @category Tools
+ */
+export declare function createAskUserQuestionTool(onAskUser: AskUserCallback): import("ai").Tool<{
+    question: string;
+    options: QuestionOption[];
+    multiSelect?: boolean;
+}, string>;
+//# sourceMappingURL=user-interaction.d.ts.map

package/dist/tools/user-interaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-interaction.d.ts","sourceRoot":"","sources":["../../src/tools/user-interaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EAAE,EACzB,WAAW,EAAE,OAAO,KACjB,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AAMhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,eAAe;cA+BpD,MAAM;aACP,cAAc,EAAE;kBACX,OAAO;WAkC1B"}

package/dist/tools/user-interaction.js

@@ -0,0 +1,147 @@
+/**
+ * User interaction tools for agent-user communication.
+ *
+ * These tools allow agents to ask clarifying questions and get user input
+ * during execution. This enables interactive workflows where the agent
+ * needs additional information from the user to proceed.
+ *
+ * @packageDocumentation
+ */
+import { tool } from "ai";
+import { z } from "zod";
+// =============================================================================
+// AskUserQuestion Tool
+// =============================================================================
+/**
+ * Creates a tool for asking the user clarifying questions.
+ *
+ * This tool allows agents to request additional information from users
+ * during execution. It supports both single-select and multi-select
+ * questions with multiple choice options.
+ *
+ * The tool requires a callback function that handles the actual UI
+ * interaction with the user. The callback receives the question and
+ * options, prompts the user, and returns their selection.
+ *
+ * @param onAskUser - Callback function to handle user prompts
+ * @returns An AI SDK compatible tool for asking questions
+ *
+ * @example
+ * Single-select question
+ * ```typescript
+ * import { createAskUserQuestionTool } from "@lleverage-ai/agent-sdk";
+ *
+ * const askUserQuestion = createAskUserQuestionTool(
+ *   async (question, options, multiSelect) => {
+ *     console.log(question);
+ *     options.forEach((opt, i) => {
+ *       console.log(`${i + 1}. ${opt.label}: ${opt.description}`);
+ *     });
+ *     const answer = await getUserInput(); // Your UI logic
+ *     return options[answer - 1].value;
+ *   }
+ * );
+ *
+ * const agent = createAgent({
+ *   model,
+ *   tools: { askUserQuestion },
+ * });
+ * ```
+ *
+ * @example
+ * Multi-select question
+ * ```typescript
+ * const askUserQuestion = createAskUserQuestionTool(
+ *   async (question, options, multiSelect) => {
+ *     if (multiSelect) {
+ *       // Show checkboxes, allow multiple selections
+ *       const selected = await getUserMultipleChoices();
+ *       return selected.map(i => options[i].value);
+ *     }
+ *     // Single select logic
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * Integration with UI framework
+ * ```typescript
+ * // React example
+ * const askUserQuestion = createAskUserQuestionTool(
+ *   async (question, options, multiSelect) => {
+ *     return new Promise((resolve) => {
+ *       setQuestion({ question, options, multiSelect, resolve });
+ *     });
+ *   }
+ * );
+ *
+ * // In your React component:
+ * function QuestionDialog({ question, options, multiSelect, resolve }) {
+ *   const [selected, setSelected] = useState([]);
+ *
+ *   const handleSubmit = () => {
+ *     if (multiSelect) {
+ *       resolve(selected);
+ *     } else {
+ *       resolve(selected[0]);
+ *     }
+ *   };
+ *
+ *   // Render question UI...
+ * }
+ * ```
+ *
+ * @category Tools
+ */
+export function createAskUserQuestionTool(onAskUser) {
+    return tool({
+        description: "Ask the user a clarifying question with multiple choice options. Use this when you need additional information from the user to proceed.",
+        inputSchema: z.object({
+            question: z.string().describe("The question to ask the user. Should be clear and specific."),
+            options: z
+                .array(z.object({
+                label: z.string().describe("Display text for this option (concise, 1-5 words)"),
+                description: z
+                    .string()
+                    .optional()
+                    .describe("Explanation of what this option means or what will happen"),
+                value: z.string().describe("Value to return if selected (can be same as label)"),
+            }))
+                .min(2)
+                .max(10)
+                .describe("Available answer options (2-10 options)"),
+            multiSelect: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Whether the user can select multiple options (default: false)"),
+        }),
+        execute: async ({ question, options, multiSelect = false, }) => {
+            // Validate options
+            if (options.length < 2) {
+                return "Error: At least 2 options are required for a question.";
+            }
+            if (options.length > 10) {
+                return "Error: Maximum 10 options allowed per question.";
+            }
+            // Call the user-provided callback to handle the interaction
+            const result = await onAskUser(question, options, multiSelect);
+            // Format the response
+            if (multiSelect && Array.isArray(result)) {
+                const selectedLabels = result
+                    .map((value) => {
+                    const option = options.find((opt) => opt.value === value);
+                    return option?.label || value;
+                })
+                    .join(", ");
+                return `User selected: ${selectedLabels}`;
+            }
+            if (typeof result === "string") {
+                const option = options.find((opt) => opt.value === result);
+                return `User selected: ${option?.label || result}`;
+            }
+            return `User selected: ${String(result)}`;
+        },
+    });
+}
+//# sourceMappingURL=user-interaction.js.map

package/dist/tools/user-interaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-interaction.js","sourceRoot":"","sources":["../../src/tools/user-interaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC1B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAA0B;IAClE,OAAO,IAAI,CAAC;QACV,WAAW,EACT,0IAA0I;QAC5I,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6DAA6D,CAAC;YAC5F,OAAO,EAAE,CAAC;iBACP,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;gBACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;gBAC/E,WAAW,EAAE,CAAC;qBACX,MAAM,EAAE;qBACR,QAAQ,EAAE;qBACV,QAAQ,CAAC,2DAA2D,CAAC;gBACxE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;aACjF,CAAC,CACH;iBACA,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,EAAE,CAAC;iBACP,QAAQ,CAAC,yCAAyC,CAAC;YACtD,WAAW,EAAE,CAAC;iBACX,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,OAAO,CAAC,KAAK,CAAC;iBACd,QAAQ,CAAC,+DAA+D,CAAC;SAC7E,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,EACd,QAAQ,EACR,OAAO,EACP,WAAW,GAAG,KAAK,GAKpB,EAAE,EAAE;YACH,mBAAmB;YACnB,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,OAAO,wDAAwD,CAAC;YAClE,CAAC;YAED,IAAI,OAAO,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;gBACxB,OAAO,iDAAiD,CAAC;YAC3D,CAAC;YAED,4DAA4D;YAC5D,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;YAE/D,sBAAsB;YACtB,IAAI,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBACzC,MAAM,cAAc,GAAG,MAAM;qBAC1B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;oBACb,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;oBAC1D,OAAO,MAAM,EAAE,KAAK,IAAI,KAAK,CAAC;gBAChC,CAAC,CAAC;qBACD,IAAI,CAAC,IAAI,CAAC,CAAC;gBAEd,OAAO,kBAAkB,cAAc,EAAE,CAAC;YAC5C,CAAC;YAED,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC;gBAC3D,OAAO,kBAAkB,MAAM,EAAE,KAAK,IAAI,MAAM,EAAE,CAAC;YACrD,CAAC;YAED,OAAO,kBAAkB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/utils.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Tool utilities for improved developer experience.
+ *
+ * Provides helpers for working with tool names, especially for MCP tools
+ * which have verbose prefixed names.
+ *
+ * @packageDocumentation
+ */
+import type { Tool, ToolSet } from "ai";
+import type { PluginOptions } from "../types.js";
+/**
+ * A reference to a tool that can be resolved to a tool name.
+ *
+ * Can be:
+ * - A string (tool name directly)
+ * - A Tool object (name extracted from key when in a ToolSet)
+ * - A Plugin (all tool names extracted, or MCP tool names generated)
+ * - A ToolSet record (all keys extracted as tool names)
+ *
+ * @category Tools
+ */
+export type ToolReference = string | Tool | PluginOptions | ToolSet | ToolReference[];
+/**
+ * Creates a helper for generating MCP tool names for a specific plugin.
+ *
+ * MCP tools are prefixed with `mcp__<plugin-name>__<tool-name>`. This helper
+ * makes it easier to reference these tools without typing the full name.
+ *
+ * @param pluginName - The MCP plugin name (e.g., "web-search")
+ * @returns A function that generates full MCP tool names
+ *
+ * @example
+ * ```typescript
+ * const webSearch = mcpTools("web-search");
+ *
+ * const subagent = createSubagent(parent, {
+ *   allowedTools: [webSearch("search"), webSearch("extract")],
+ *   // Equivalent to: ["mcp__web-search__search", "mcp__web-search__extract"]
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export declare function mcpTools(pluginName: string): (toolName: string) => string;
+/**
+ * Creates a helper for a specific MCP plugin with known tools.
+ *
+ * Returns an object with tool name properties for better IDE autocomplete.
+ *
+ * @param pluginName - The MCP plugin name
+ * @param toolNames - Array of tool names provided by the plugin
+ * @returns An object mapping tool names to their full MCP names
+ *
+ * @example
+ * ```typescript
+ * const webSearch = mcpToolsFor("web-search", ["search", "extract"] as const);
+ *
+ * // Now you get autocomplete:
+ * webSearch.search  // "mcp__web-search__search"
+ * webSearch.extract // "mcp__web-search__extract"
+ *
+ * const subagent = createSubagent(parent, {
+ *   allowedTools: [webSearch.search, webSearch.extract],
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export declare function mcpToolsFor<T extends readonly string[]>(pluginName: string, toolNames: T): {
+    [K in T[number]]: string;
+};
+/**
+ * Extracts tool names from a plugin.
+ *
+ * For regular plugins, extracts tool names from the tools property.
+ * For MCP plugins, generates tool names based on the plugin name and
+ * optionally specified tool names.
+ *
+ * @param plugin - The plugin to extract tool names from
+ * @param mcpToolNames - For MCP plugins, the specific tool names to include
+ * @returns Array of tool name strings
+ *
+ * @example
+ * ```typescript
+ * // Regular plugin with tools
+ * const names = toolsFromPlugin(myPlugin);
+ * // Returns: ["tool1", "tool2", ...]
+ *
+ * // MCP plugin with specific tools
+ * const names = toolsFromPlugin(webSearchPlugin, ["search", "extract"]);
+ * // Returns: ["mcp__web-search__search", "mcp__web-search__extract"]
+ * ```
+ *
+ * @category Tools
+ */
+export declare function toolsFromPlugin(plugin: PluginOptions, mcpToolNames?: string[]): string[];
+/**
+ * Extracts tool names from various sources.
+ *
+ * Accepts strings, plugins, tool sets, or arrays of these and returns
+ * a flat array of tool name strings.
+ *
+ * @param refs - Tool references to extract names from
+ * @returns Array of tool name strings
+ *
+ * @example
+ * ```typescript
+ * // Mix of different reference types
+ * const tools = toolsFrom(
+ *   "read",                           // String
+ *   "write",
+ *   myPlugin,                         // Plugin (extracts tool names)
+ *   { custom: customTool },           // ToolSet (extracts keys)
+ * );
+ *
+ * const subagent = createSubagent(parent, {
+ *   allowedTools: tools,
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export declare function toolsFrom(...refs: ToolReference[]): string[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/tools/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,IAAI,GAAG,aAAa,GAAG,OAAO,GAAG,aAAa,EAAE,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAEzE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,EACrD,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,CAAC,GACX;KAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,MAAM;CAAE,CAM9B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAyBxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,GAAG,IAAI,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CA0B5D"}

package/dist/tools/utils.js

@@ -0,0 +1,189 @@
+/**
+ * Tool utilities for improved developer experience.
+ *
+ * Provides helpers for working with tool names, especially for MCP tools
+ * which have verbose prefixed names.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Creates a helper for generating MCP tool names for a specific plugin.
+ *
+ * MCP tools are prefixed with `mcp__<plugin-name>__<tool-name>`. This helper
+ * makes it easier to reference these tools without typing the full name.
+ *
+ * @param pluginName - The MCP plugin name (e.g., "web-search")
+ * @returns A function that generates full MCP tool names
+ *
+ * @example
+ * ```typescript
+ * const webSearch = mcpTools("web-search");
+ *
+ * const subagent = createSubagent(parent, {
+ *   allowedTools: [webSearch("search"), webSearch("extract")],
+ *   // Equivalent to: ["mcp__web-search__search", "mcp__web-search__extract"]
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function mcpTools(pluginName) {
+    return (toolName) => `mcp__${pluginName}__${toolName}`;
+}
+/**
+ * Creates a helper for a specific MCP plugin with known tools.
+ *
+ * Returns an object with tool name properties for better IDE autocomplete.
+ *
+ * @param pluginName - The MCP plugin name
+ * @param toolNames - Array of tool names provided by the plugin
+ * @returns An object mapping tool names to their full MCP names
+ *
+ * @example
+ * ```typescript
+ * const webSearch = mcpToolsFor("web-search", ["search", "extract"] as const);
+ *
+ * // Now you get autocomplete:
+ * webSearch.search  // "mcp__web-search__search"
+ * webSearch.extract // "mcp__web-search__extract"
+ *
+ * const subagent = createSubagent(parent, {
+ *   allowedTools: [webSearch.search, webSearch.extract],
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function mcpToolsFor(pluginName, toolNames) {
+    const result = {};
+    for (const name of toolNames) {
+        result[name] = `mcp__${pluginName}__${name}`;
+    }
+    return result;
+}
+/**
+ * Extracts tool names from a plugin.
+ *
+ * For regular plugins, extracts tool names from the tools property.
+ * For MCP plugins, generates tool names based on the plugin name and
+ * optionally specified tool names.
+ *
+ * @param plugin - The plugin to extract tool names from
+ * @param mcpToolNames - For MCP plugins, the specific tool names to include
+ * @returns Array of tool name strings
+ *
+ * @example
+ * ```typescript
+ * // Regular plugin with tools
+ * const names = toolsFromPlugin(myPlugin);
+ * // Returns: ["tool1", "tool2", ...]
+ *
+ * // MCP plugin with specific tools
+ * const names = toolsFromPlugin(webSearchPlugin, ["search", "extract"]);
+ * // Returns: ["mcp__web-search__search", "mcp__web-search__extract"]
+ * ```
+ *
+ * @category Tools
+ */
+export function toolsFromPlugin(plugin, mcpToolNames) {
+    // If it's an MCP plugin
+    if (plugin.mcpServer) {
+        if (!mcpToolNames || mcpToolNames.length === 0) {
+            throw new Error(`MCP plugin "${plugin.name}" requires explicit tool names. ` +
+                `Use toolsFromPlugin(plugin, ["toolName1", "toolName2"]) or mcpTools("${plugin.name}")("toolName").`);
+        }
+        const helper = mcpTools(plugin.name);
+        return mcpToolNames.map(helper);
+    }
+    // Regular plugin with tools
+    if (plugin.tools) {
+        if (typeof plugin.tools === "function") {
+            throw new Error(`Plugin "${plugin.name}" uses dynamic tools (StreamingToolsFactory). ` +
+                `Tool names cannot be extracted statically. Use string tool names instead.`);
+        }
+        return Object.keys(plugin.tools);
+    }
+    return [];
+}
+/**
+ * Extracts tool names from various sources.
+ *
+ * Accepts strings, plugins, tool sets, or arrays of these and returns
+ * a flat array of tool name strings.
+ *
+ * @param refs - Tool references to extract names from
+ * @returns Array of tool name strings
+ *
+ * @example
+ * ```typescript
+ * // Mix of different reference types
+ * const tools = toolsFrom(
+ *   "read",                           // String
+ *   "write",
+ *   myPlugin,                         // Plugin (extracts tool names)
+ *   { custom: customTool },           // ToolSet (extracts keys)
+ * );
+ *
+ * const subagent = createSubagent(parent, {
+ *   allowedTools: tools,
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function toolsFrom(...refs) {
+    const names = [];
+    for (const ref of refs) {
+        if (typeof ref === "string") {
+            names.push(ref);
+        }
+        else if (Array.isArray(ref)) {
+            names.push(...toolsFrom(...ref));
+        }
+        else if (isPlugin(ref)) {
+            // For plugins, extract tool names (throws for MCP without explicit names)
+            try {
+                names.push(...toolsFromPlugin(ref));
+            }
+            catch {
+                // MCP plugin without tool names - skip with warning
+                console.warn(`Skipping MCP plugin "${ref.name}" in toolsFrom(). ` +
+                    `Use toolsFromPlugin(plugin, ["tool1", "tool2"]) for MCP plugins.`);
+            }
+        }
+        else if (isToolSet(ref)) {
+            names.push(...Object.keys(ref));
+        }
+        // Tool objects without names are skipped - they need to be in a ToolSet
+    }
+    return names;
+}
+/**
+ * Type guard to check if a value is a Plugin.
+ * @internal
+ */
+function isPlugin(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "name" in value &&
+        typeof value.name === "string");
+}
+/**
+ * Type guard to check if a value is a ToolSet.
+ * @internal
+ */
+function isToolSet(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    // A ToolSet is a Record<string, Tool>
+    // Check that it's not a Plugin (which also has string keys)
+    if ("name" in value && typeof value.name === "string") {
+        return false;
+    }
+    // Check if all values look like tools (have execute function)
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return false;
+    return entries.every(([, v]) => typeof v === "object" && v !== null && "execute" in v);
+}
+//# sourceMappingURL=utils.js.map

package/dist/tools/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Skill definition helpers.
+ *
+ * Tools should be defined using AI SDK's `tool()` function directly.
+ * This module provides helpers for skills which provide contextual
+ * instructions and guidance for agents.
+ *
+ * @packageDocumentation
+ */
+import type { SkillDefinition, SkillOptions, ToolSet } from "./types.js";
+/**
+ * Creates a skill definition for providing contextual instructions to agents.
+ *
+ * Skills serve multiple purposes:
+ * - **Tool guidance**: Bundle with plugin tools to explain how to use them
+ * - **Instructions only**: Load dynamic instructions without tools
+ * - **Progressive disclosure**: Include tools that load on-demand
+ *
+ * @param options - Configuration options for the skill
+ * @returns A skill definition object
+ *
+ * @example
+ * ```typescript
+ * import { defineSkill, definePlugin } from "@lleverage-ai/agent-sdk";
+ *
+ * // Skill that provides guidance for using plugin tools
+ * const dataSkill = defineSkill({
+ *   name: "data-exploration",
+ *   description: "Query and visualize data",
+ *   prompt: `You have access to data exploration tools.
+ * Available tables: products, users, sales.
+ * Always use getSchema first to see column types.`,
+ * });
+ *
+ * // Bundle skill with tools in a plugin
+ * const dataPlugin = definePlugin({
+ *   name: "data-explorer",
+ *   tools: { getSchema, queryData },
+ *   skills: [dataSkill],
+ * });
+ *
+ * // Skill with no tools - just loads instructions
+ * const guidelinesSkill = defineSkill({
+ *   name: "guidelines",
+ *   description: "Project coding standards",
+ *   prompt: "Follow TypeScript strict mode and use named exports.",
+ * });
+ *
+ * // Skill with tools for progressive disclosure
+ * const analyzeSkill = defineSkill({
+ *   name: "analyze",
+ *   description: "Deep code analysis",
+ *   prompt: "Perform detailed code analysis.",
+ *   tools: {
+ *     lint: tool({
+ *       description: "Run linter",
+ *       inputSchema: z.object({ path: z.string() }),
+ *       execute: async ({ path }) => runLinter(path),
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export declare function defineSkill(options: SkillOptions): SkillDefinition;
+/**
+ * Helper type for tools that can be provided to skills.
+ * Re-exported from AI SDK for convenience.
+ *
+ * @category Tools
+ */
+export type { ToolSet };
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,eAAe,CAOlE;AAED;;;;;GAKG;AACH,YAAY,EAAE,OAAO,EAAE,CAAC"}