signalwire-agents 0.1.0

package/dist/skills/builtin/api_ninjas_trivia.js

@@ -0,0 +1,161 @@
+/**
+ * API Ninjas Trivia Skill - Fetches trivia questions from the API Ninjas service.
+ *
+ * Tier 2 built-in skill: requires API_NINJAS_KEY environment variable.
+ * Uses the API Ninjas Trivia endpoint to retrieve random trivia questions
+ * with optional category filtering.
+ */
+import { SkillBase } from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+const VALID_CATEGORIES = [
+    'artliterature',
+    'language',
+    'sciencenature',
+    'general',
+    'fooddrink',
+    'peopleplaces',
+    'geography',
+    'historyholidays',
+    'entertainment',
+    'toysgames',
+    'music',
+    'mathematics',
+    'religionmythology',
+    'sportsleisure',
+];
+/**
+ * Fetches trivia questions from the API Ninjas service.
+ *
+ * Tier 2 built-in skill. Requires the `API_NINJAS_KEY` environment variable.
+ * Supports optional `default_category` and `reveal_answer` config options.
+ */
+export class ApiNinjasTriviaSkill extends SkillBase {
+    /**
+     * @param config - Optional configuration; supports `default_category` and `reveal_answer`.
+     */
+    constructor(config) {
+        super('api_ninjas_trivia', config);
+    }
+    /** @returns Manifest declaring API_NINJAS_KEY as required and config schema for category/reveal. */
+    getManifest() {
+        return {
+            name: 'api_ninjas_trivia',
+            description: 'Fetches trivia questions from the API Ninjas service. Supports multiple categories for varied trivia topics.',
+            version: '1.0.0',
+            author: 'SignalWire',
+            tags: ['trivia', 'api', 'entertainment', 'quiz', 'external'],
+            requiredEnvVars: ['API_NINJAS_KEY'],
+            configSchema: {
+                default_category: {
+                    type: 'string',
+                    description: 'Default trivia category if none is specified by the user.',
+                },
+                reveal_answer: {
+                    type: 'boolean',
+                    description: 'Whether to include the answer in the response. Defaults to false so the AI can quiz the user.',
+                    default: false,
+                },
+            },
+        };
+    }
+    /** @returns A single `get_trivia` tool that fetches a random trivia question with optional category. */
+    getTools() {
+        const defaultCategory = this.getConfig('default_category', undefined);
+        const revealAnswer = this.getConfig('reveal_answer', false);
+        return [
+            {
+                name: 'get_trivia',
+                description: 'Get a random trivia question. Optionally specify a category to narrow the topic.',
+                parameters: {
+                    category: {
+                        type: 'string',
+                        description: 'Trivia category. Available categories: ' +
+                            VALID_CATEGORIES.join(', ') +
+                            '. If not specified, a random category is used.',
+                    },
+                },
+                handler: async (args) => {
+                    const apiKey = process.env['API_NINJAS_KEY'];
+                    if (!apiKey) {
+                        return new SwaigFunctionResult('Trivia service is not configured. The API_NINJAS_KEY environment variable is missing.');
+                    }
+                    let category = args.category ?? defaultCategory;
+                    // Validate category if provided
+                    if (category && typeof category === 'string') {
+                        const normalized = category.toLowerCase().trim().replace(/[\s_-]/g, '');
+                        if (!VALID_CATEGORIES.includes(normalized)) {
+                            return new SwaigFunctionResult(`Unknown trivia category "${category}". Available categories: ${VALID_CATEGORIES.join(', ')}.`);
+                        }
+                        category = normalized;
+                    }
+                    try {
+                        const url = category
+                            ? `https://api.api-ninjas.com/v1/trivia?category=${encodeURIComponent(category)}`
+                            : 'https://api.api-ninjas.com/v1/trivia';
+                        const response = await fetch(url, {
+                            headers: {
+                                'X-Api-Key': apiKey,
+                            },
+                        });
+                        if (!response.ok) {
+                            return new SwaigFunctionResult(`Failed to fetch trivia: HTTP ${response.status} ${response.statusText}. Please try again later.`);
+                        }
+                        const data = (await response.json());
+                        if (!Array.isArray(data) || data.length === 0) {
+                            return new SwaigFunctionResult('No trivia questions were returned. Please try again or try a different category.');
+                        }
+                        const trivia = data[0];
+                        if (revealAnswer) {
+                            return new SwaigFunctionResult(`Trivia (${trivia.category}): ${trivia.question} Answer: ${trivia.answer}`);
+                        }
+                        // When not revealing the answer, provide it in a structured way
+                        // so the AI knows the answer but can quiz the user
+                        return new SwaigFunctionResult(`Here is a trivia question from the "${trivia.category}" category. ` +
+                            `Question: ${trivia.question} ` +
+                            `[The correct answer is: ${trivia.answer}. Do not reveal this unless the user attempts an answer or asks for it.]`);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        return new SwaigFunctionResult(`Failed to fetch trivia question: ${message}`);
+                    }
+                },
+            },
+        ];
+    }
+    /** @returns Prompt section describing trivia capabilities and quiz behavior. */
+    getPromptSections() {
+        const revealAnswer = this.getConfig('reveal_answer', false);
+        const bullets = [
+            'Use the get_trivia tool to fetch a random trivia question.',
+            `Available categories: ${VALID_CATEGORIES.join(', ')}.`,
+            'If no category is specified, a random category will be selected.',
+        ];
+        if (!revealAnswer) {
+            bullets.push('When you receive a trivia question, ask it to the user and let them try to answer before revealing the correct answer.', 'If the user gets it wrong, give them a hint or tell them the correct answer.');
+        }
+        else {
+            bullets.push('Trivia answers are included in the response. Share the question and answer with the user.');
+        }
+        bullets.push('Keep trivia fun and engaging. Encourage the user to try more questions.');
+        return [
+            {
+                title: 'Trivia Questions',
+                body: 'You can fetch and ask trivia questions from a wide range of categories.',
+                bullets,
+            },
+        ];
+    }
+    /** @returns Speech recognition hints for trivia-related keywords. */
+    getHints() {
+        return ['trivia', 'quiz', 'question', 'fun fact'];
+    }
+}
+/**
+ * Factory function for creating ApiNinjasTriviaSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new ApiNinjasTriviaSkill instance.
+ */
+export function createSkill(config) {
+    return new ApiNinjasTriviaSkill(config);
+}
+//# sourceMappingURL=api_ninjas_trivia.js.map

package/dist/skills/builtin/api_ninjas_trivia.js.map

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

package/dist/skills/builtin/claude_skills.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Claude Skills - Provides access to Anthropic's Claude AI for sub-queries.
+ *
+ * Tier 3 built-in skill: requires ANTHROPIC_API_KEY environment variable.
+ * Allows the agent to send prompts to Claude for complex reasoning,
+ * analysis, or sub-tasks that benefit from a dedicated AI query.
+ */
+import { SkillBase } from '../SkillBase.js';
+import type { SkillManifest, SkillToolDefinition, SkillPromptSection, SkillConfig } from '../SkillBase.js';
+/**
+ * Provides access to Anthropic's Claude AI for sub-queries and complex reasoning.
+ *
+ * Tier 3 built-in skill. Requires the `ANTHROPIC_API_KEY` environment variable.
+ * Supports `model` and `max_tokens` config options to control which Claude model
+ * is used and the maximum response length.
+ */
+export declare class ClaudeSkill extends SkillBase {
+    /**
+     * @param config - Optional configuration; supports `model` and `max_tokens`.
+     */
+    constructor(config?: SkillConfig);
+    /** @returns Manifest declaring ANTHROPIC_API_KEY as required and config schema for model/max_tokens. */
+    getManifest(): SkillManifest;
+    /** @returns A single `ask_claude` tool that sends prompts to the Claude API. */
+    getTools(): SkillToolDefinition[];
+    /** @returns Prompt section describing Claude AI delegation capabilities. */
+    getPromptSections(): SkillPromptSection[];
+}
+/**
+ * Factory function for creating ClaudeSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new ClaudeSkill instance.
+ */
+export declare function createSkill(config?: SkillConfig): ClaudeSkill;

package/dist/skills/builtin/claude_skills.js

@@ -0,0 +1,156 @@
+/**
+ * Claude Skills - Provides access to Anthropic's Claude AI for sub-queries.
+ *
+ * Tier 3 built-in skill: requires ANTHROPIC_API_KEY environment variable.
+ * Allows the agent to send prompts to Claude for complex reasoning,
+ * analysis, or sub-tasks that benefit from a dedicated AI query.
+ */
+import { SkillBase } from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+/**
+ * Provides access to Anthropic's Claude AI for sub-queries and complex reasoning.
+ *
+ * Tier 3 built-in skill. Requires the `ANTHROPIC_API_KEY` environment variable.
+ * Supports `model` and `max_tokens` config options to control which Claude model
+ * is used and the maximum response length.
+ */
+export class ClaudeSkill extends SkillBase {
+    /**
+     * @param config - Optional configuration; supports `model` and `max_tokens`.
+     */
+    constructor(config) {
+        super('claude_skills', config);
+    }
+    /** @returns Manifest declaring ANTHROPIC_API_KEY as required and config schema for model/max_tokens. */
+    getManifest() {
+        return {
+            name: 'claude_skills',
+            description: 'Provides access to Anthropic Claude AI for complex reasoning, analysis, and sub-queries.',
+            version: '1.0.0',
+            author: 'SignalWire',
+            tags: ['ai', 'claude', 'anthropic', 'reasoning', 'analysis', 'external'],
+            requiredEnvVars: ['ANTHROPIC_API_KEY'],
+            configSchema: {
+                model: {
+                    type: 'string',
+                    description: 'The Claude model to use. Defaults to "claude-sonnet-4-5-20250929".',
+                    default: 'claude-sonnet-4-5-20250929',
+                },
+                max_tokens: {
+                    type: 'number',
+                    description: 'Maximum tokens in the response. Defaults to 1024.',
+                    default: 1024,
+                },
+            },
+        };
+    }
+    /** @returns A single `ask_claude` tool that sends prompts to the Claude API. */
+    getTools() {
+        const model = this.getConfig('model', 'claude-sonnet-4-5-20250929');
+        const maxTokens = this.getConfig('max_tokens', 1024);
+        return [
+            {
+                name: 'ask_claude',
+                description: 'Send a prompt to Claude AI for complex reasoning, analysis, summarization, or any task that benefits from dedicated AI processing. Returns Claude\'s response.',
+                parameters: {
+                    prompt: {
+                        type: 'string',
+                        description: 'The prompt or question to send to Claude.',
+                    },
+                    system_prompt: {
+                        type: 'string',
+                        description: 'Optional system prompt to set context or instructions for Claude.',
+                    },
+                },
+                required: ['prompt'],
+                handler: async (args) => {
+                    const prompt = args.prompt;
+                    const systemPrompt = args.system_prompt;
+                    if (!prompt || typeof prompt !== 'string' || prompt.trim().length === 0) {
+                        return new SwaigFunctionResult('Please provide a prompt for Claude.');
+                    }
+                    const apiKey = process.env['ANTHROPIC_API_KEY'];
+                    if (!apiKey) {
+                        return new SwaigFunctionResult('Claude AI is not configured. The ANTHROPIC_API_KEY environment variable is required.');
+                    }
+                    try {
+                        const messages = [
+                            { role: 'user', content: prompt.trim() },
+                        ];
+                        const requestBody = {
+                            model,
+                            max_tokens: maxTokens,
+                            messages,
+                        };
+                        if (systemPrompt && typeof systemPrompt === 'string' && systemPrompt.trim().length > 0) {
+                            requestBody['system'] = systemPrompt.trim();
+                        }
+                        const response = await fetch('https://api.anthropic.com/v1/messages', {
+                            method: 'POST',
+                            headers: {
+                                'Content-Type': 'application/json',
+                                'x-api-key': apiKey,
+                                'anthropic-version': '2023-06-01',
+                            },
+                            body: JSON.stringify(requestBody),
+                        });
+                        if (!response.ok) {
+                            const errorText = await response.text();
+                            let errorMsg;
+                            try {
+                                const errorData = JSON.parse(errorText);
+                                errorMsg = errorData.error?.message ?? `HTTP ${response.status}`;
+                            }
+                            catch {
+                                errorMsg = `HTTP ${response.status}: ${errorText.slice(0, 300)}`;
+                            }
+                            return new SwaigFunctionResult(`Claude API request failed: ${errorMsg}`);
+                        }
+                        const data = (await response.json());
+                        if (data.error) {
+                            return new SwaigFunctionResult(`Claude returned an error: ${data.error.message}`);
+                        }
+                        // Extract text content from the response
+                        const textParts = data.content
+                            .filter((block) => block.type === 'text' && block.text)
+                            .map((block) => block.text);
+                        if (textParts.length === 0) {
+                            return new SwaigFunctionResult('Claude returned an empty response. Try rephrasing your prompt.');
+                        }
+                        const responseText = textParts.join('\n\n');
+                        return new SwaigFunctionResult(responseText);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        return new SwaigFunctionResult(`Failed to query Claude AI: ${message}`);
+                    }
+                },
+            },
+        ];
+    }
+    /** @returns Prompt section describing Claude AI delegation capabilities. */
+    getPromptSections() {
+        return [
+            {
+                title: 'Claude AI Assistant',
+                body: 'You can delegate complex reasoning or analysis tasks to Claude AI.',
+                bullets: [
+                    'Use the ask_claude tool for tasks requiring detailed analysis, summarization, or complex reasoning.',
+                    'You can provide an optional system prompt to set specific instructions or context.',
+                    'This is useful for tasks like: detailed explanations, code analysis, text summarization, creative writing, or multi-step reasoning.',
+                    'Do not use this tool for simple factual questions you already know the answer to.',
+                    'Summarize or relay Claude\'s response naturally to the user.',
+                ],
+            },
+        ];
+    }
+}
+/**
+ * Factory function for creating ClaudeSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new ClaudeSkill instance.
+ */
+export function createSkill(config) {
+    return new ClaudeSkill(config);
+}
+//# sourceMappingURL=claude_skills.js.map

package/dist/skills/builtin/claude_skills.js.map

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

package/dist/skills/builtin/custom_skills.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Custom Skills - A meta-skill that registers user-defined tools from configuration.
+ *
+ * Tier 2 built-in skill: no external dependencies required.
+ * Allows users to define arbitrary tools via config without writing skill classes.
+ * Each tool definition in the config specifies its name, description, parameters,
+ * and a handler function body (executed via Function constructor).
+ *
+ * This is useful for rapid prototyping, simple integrations, and cases where
+ * creating a full skill class would be overkill.
+ */
+import { SkillBase } from '../SkillBase.js';
+import type { SkillManifest, SkillToolDefinition, SkillPromptSection, SkillConfig } from '../SkillBase.js';
+/**
+ * A meta-skill that registers user-defined tools from configuration.
+ *
+ * Tier 2 built-in skill with no external dependencies. Allows users to define
+ * arbitrary tools via config without writing skill classes. Each tool definition
+ * specifies a name, description, parameters, and a JavaScript handler function
+ * body that is compiled via the Function constructor at instantiation time.
+ */
+export declare class CustomSkillsSkill extends SkillBase {
+    private _compiledHandlers;
+    private _compilationErrors;
+    /**
+     * @param config - Configuration object containing a `tools` array of custom tool definitions.
+     */
+    constructor(config?: SkillConfig);
+    /** @returns Manifest with config schema describing the tools array format. */
+    getManifest(): SkillManifest;
+    /**
+     * Pre-compile handler code into functions during construction.
+     * This catches syntax errors early and avoids re-compilation on each call.
+     */
+    private _compileHandlers;
+    /**
+     * Get the raw tool definitions from config.
+     */
+    private _getToolDefs;
+    /** @returns Array of dynamically generated tools from the configuration, with compiled handlers. */
+    getTools(): SkillToolDefinition[];
+    /** @returns Prompt section listing all custom tools and their descriptions. */
+    getPromptSections(): SkillPromptSection[];
+    /**
+     * Build tool parameters from the custom tool definition.
+     */
+    private _buildParameters;
+    /**
+     * Get handler compilation errors for diagnostic purposes.
+     * @returns A copy of the map from tool name to error message.
+     */
+    getCompilationErrors(): Map<string, string>;
+}
+/**
+ * Factory function for creating CustomSkillsSkill instances.
+ * @param config - Configuration containing a `tools` array of custom tool definitions.
+ * @returns A new CustomSkillsSkill instance.
+ */
+export declare function createSkill(config?: SkillConfig): CustomSkillsSkill;

package/dist/skills/builtin/custom_skills.js

@@ -0,0 +1,231 @@
+/**
+ * Custom Skills - A meta-skill that registers user-defined tools from configuration.
+ *
+ * Tier 2 built-in skill: no external dependencies required.
+ * Allows users to define arbitrary tools via config without writing skill classes.
+ * Each tool definition in the config specifies its name, description, parameters,
+ * and a handler function body (executed via Function constructor).
+ *
+ * This is useful for rapid prototyping, simple integrations, and cases where
+ * creating a full skill class would be overkill.
+ */
+import { SkillBase } from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+/**
+ * A meta-skill that registers user-defined tools from configuration.
+ *
+ * Tier 2 built-in skill with no external dependencies. Allows users to define
+ * arbitrary tools via config without writing skill classes. Each tool definition
+ * specifies a name, description, parameters, and a JavaScript handler function
+ * body that is compiled via the Function constructor at instantiation time.
+ */
+export class CustomSkillsSkill extends SkillBase {
+    _compiledHandlers = new Map();
+    _compilationErrors = new Map();
+    /**
+     * @param config - Configuration object containing a `tools` array of custom tool definitions.
+     */
+    constructor(config) {
+        super('custom_skills', config);
+        this._compileHandlers();
+    }
+    /** @returns Manifest with config schema describing the tools array format. */
+    getManifest() {
+        return {
+            name: 'custom_skills',
+            description: 'A meta-skill that registers user-defined tools from configuration. Define tools with names, descriptions, parameters, and handler code.',
+            version: '1.0.0',
+            author: 'SignalWire',
+            tags: ['meta', 'custom', 'extensible', 'dynamic'],
+            configSchema: {
+                tools: {
+                    type: 'array',
+                    description: 'Array of custom tool definitions: { name, description, parameters?, handler_code, required?, prompt_description?, secure?, fillers? }.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string', description: 'Tool name (must be unique).' },
+                            description: { type: 'string', description: 'Tool description for the AI.' },
+                            parameters: {
+                                type: 'array',
+                                description: 'Tool parameters: [{ name, type, description, required? }].',
+                            },
+                            handler_code: {
+                                type: 'string',
+                                description: 'JavaScript function body. Receives (args, rawData, SwaigFunctionResult) as arguments. Must return a SwaigFunctionResult, string, or object.',
+                            },
+                            required: {
+                                type: 'array',
+                                description: 'Array of required parameter names.',
+                            },
+                            prompt_description: {
+                                type: 'string',
+                                description: 'Description to include in the prompt section for this tool.',
+                            },
+                            secure: { type: 'boolean', description: 'Whether to mark the tool as secure.' },
+                            fillers: {
+                                type: 'object',
+                                description: 'Filler phrases for the tool.',
+                            },
+                        },
+                        required: ['name', 'description', 'handler_code'],
+                    },
+                },
+                prompt_title: {
+                    type: 'string',
+                    description: 'Custom title for the prompt section. Defaults to "Custom Tools".',
+                },
+                prompt_body: {
+                    type: 'string',
+                    description: 'Custom body text for the prompt section.',
+                },
+            },
+        };
+    }
+    /**
+     * Pre-compile handler code into functions during construction.
+     * This catches syntax errors early and avoids re-compilation on each call.
+     */
+    _compileHandlers() {
+        const toolDefs = this._getToolDefs();
+        for (const toolDef of toolDefs) {
+            try {
+                // The handler code receives: args, rawData, SwaigFunctionResult
+                // It should return a SwaigFunctionResult, string, or plain object
+                const handler = new Function('args', 'rawData', 'SwaigFunctionResult', toolDef.handler_code);
+                this._compiledHandlers.set(toolDef.name, handler);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                this._compilationErrors.set(toolDef.name, message);
+            }
+        }
+    }
+    /**
+     * Get the raw tool definitions from config.
+     */
+    _getToolDefs() {
+        const configData = this.config;
+        return configData.tools ?? [];
+    }
+    /** @returns Array of dynamically generated tools from the configuration, with compiled handlers. */
+    getTools() {
+        const toolDefs = this._getToolDefs();
+        const tools = [];
+        for (const toolDef of toolDefs) {
+            // Check for compilation errors
+            const compError = this._compilationErrors.get(toolDef.name);
+            if (compError) {
+                // Still register the tool but with an error handler
+                tools.push({
+                    name: toolDef.name,
+                    description: toolDef.description,
+                    parameters: this._buildParameters(toolDef),
+                    required: toolDef.required,
+                    secure: toolDef.secure,
+                    fillers: toolDef.fillers,
+                    handler: () => {
+                        return new SwaigFunctionResult(`Custom tool "${toolDef.name}" has a compilation error in its handler code: ${compError}. Please fix the handler_code configuration.`);
+                    },
+                });
+                continue;
+            }
+            const compiledHandler = this._compiledHandlers.get(toolDef.name);
+            if (!compiledHandler) {
+                continue;
+            }
+            tools.push({
+                name: toolDef.name,
+                description: toolDef.description,
+                parameters: this._buildParameters(toolDef),
+                required: toolDef.required,
+                secure: toolDef.secure,
+                fillers: toolDef.fillers,
+                handler: async (args, rawData) => {
+                    try {
+                        const result = await compiledHandler(args, rawData, SwaigFunctionResult);
+                        // Normalize the result
+                        if (result instanceof SwaigFunctionResult) {
+                            return result;
+                        }
+                        if (typeof result === 'string') {
+                            return new SwaigFunctionResult(result);
+                        }
+                        if (result && typeof result === 'object') {
+                            return result;
+                        }
+                        return new SwaigFunctionResult('Action completed.');
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        return new SwaigFunctionResult(`Custom tool "${toolDef.name}" encountered a runtime error: ${message}`);
+                    }
+                },
+            });
+        }
+        return tools;
+    }
+    /** @returns Prompt section listing all custom tools and their descriptions. */
+    getPromptSections() {
+        const toolDefs = this._getToolDefs();
+        const configData = this.config;
+        if (toolDefs.length === 0) {
+            return [];
+        }
+        const title = configData.prompt_title ?? 'Custom Tools';
+        const body = configData.prompt_body ??
+            'The following custom tools are available for use.';
+        const bullets = [];
+        for (const toolDef of toolDefs) {
+            const compError = this._compilationErrors.get(toolDef.name);
+            if (compError) {
+                bullets.push(`${toolDef.name}: [ERROR - handler compilation failed] ${toolDef.description}`);
+            }
+            else if (toolDef.prompt_description) {
+                bullets.push(`${toolDef.name}: ${toolDef.prompt_description}`);
+            }
+            else {
+                bullets.push(`${toolDef.name}: ${toolDef.description}`);
+            }
+        }
+        return [
+            {
+                title,
+                body,
+                bullets,
+            },
+        ];
+    }
+    /**
+     * Build tool parameters from the custom tool definition.
+     */
+    _buildParameters(toolDef) {
+        if (!toolDef.parameters || toolDef.parameters.length === 0) {
+            return {};
+        }
+        const params = {};
+        for (const param of toolDef.parameters) {
+            params[param.name] = {
+                type: param.type,
+                description: param.description,
+            };
+        }
+        return params;
+    }
+    /**
+     * Get handler compilation errors for diagnostic purposes.
+     * @returns A copy of the map from tool name to error message.
+     */
+    getCompilationErrors() {
+        return new Map(this._compilationErrors);
+    }
+}
+/**
+ * Factory function for creating CustomSkillsSkill instances.
+ * @param config - Configuration containing a `tools` array of custom tool definitions.
+ * @returns A new CustomSkillsSkill instance.
+ */
+export function createSkill(config) {
+    return new CustomSkillsSkill(config);
+}
+//# sourceMappingURL=custom_skills.js.map