kagent-ts 0.1.3 → 0.1.4

package/dist/mcp/mcp-client-manager.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpClientManager = void 0;
+const mcp_types_1 = require("./mcp-types");
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+// ─── Config resolver ────────────────────────────────────────────────────────
+function resolveTransportConfig(config) {
+    if (config.command && config.url) {
+        throw new mcp_types_1.McpConnectionError("MCP server config must specify either 'command' (stdio) or 'url' (SSE), not both.");
+    }
+    if (config.command) {
+        return { type: "stdio", command: config.command, args: config.args, env: config.env };
+    }
+    if (config.url) {
+        return { type: "sse", url: config.url };
+    }
+    throw new mcp_types_1.McpConnectionError("MCP server config must specify either 'command' (stdio) or 'url' (SSE).");
+}
+/**
+ * Manages connections to MCP (Model Context Protocol) servers.
+ *
+ * Lifecycle:
+ * 1. `connectToServer()` / `connectAll()` — connect, discover tools,
+ *    register adapted tools in ToolRegistry
+ * 2. Tools execute via the adapted `Tool` wrapper (delegates to MCP client)
+ * 3. `disconnect()` / `disconnectAll()` — unregister tools, close connections
+ */
+class McpClientManager {
+    /** Active connections keyed by server name. */
+    connections = new Map();
+    /** The ToolRegistry where adapted tools are registered. */
+    toolRegistry;
+    constructor(toolRegistry) {
+        this.toolRegistry = toolRegistry;
+    }
+    // ─── Connection Management ────────────────────────────────────────────────
+    /**
+     * Connect to a single MCP server, discover its tools, and register them
+     * in the ToolRegistry with a `{serverName}_` prefix.
+     *
+     * @throws McpConnectionError if the config is invalid or the
+     *         connection/tool-discovery fails.
+     */
+    async connectToServer(serverName, config) {
+        if (this.connections.has(serverName)) {
+            throw new mcp_types_1.McpConnectionError(`MCP server "${serverName}" is already connected.`);
+        }
+        const transportConfig = resolveTransportConfig(config);
+        // Build transport
+        let transport;
+        if (transportConfig.type === "stdio") {
+            transport = new stdio_js_1.StdioClientTransport({
+                command: transportConfig.command,
+                args: transportConfig.args,
+                env: transportConfig.env,
+            });
+        }
+        else {
+            transport = new sse_js_1.SSEClientTransport(new URL(transportConfig.url));
+        }
+        // Create client and connect
+        const client = new index_js_1.Client({ name: "kagent-ts", version: "0.1.3" }, { capabilities: {} });
+        try {
+            await client.connect(transport);
+        }
+        catch (err) {
+            throw new mcp_types_1.McpConnectionError(`Failed to connect to MCP server "${serverName}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Discover tools
+        let mcpToolDescriptors;
+        try {
+            const result = await client.listTools();
+            mcpToolDescriptors = result.tools;
+        }
+        catch (err) {
+            await client.close().catch(() => { });
+            throw new mcp_types_1.McpConnectionError(`Failed to list tools from MCP server "${serverName}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Adapt and register tools
+        const adaptedTools = [];
+        for (const mcpTool of mcpToolDescriptors) {
+            const adapted = this.adaptTool(serverName, mcpTool, client);
+            if (this.toolRegistry.has(adapted.name)) {
+                console.warn(`[MCP] Tool "${adapted.name}" is already registered. ` +
+                    `Skipping MCP tool "${serverName}/${mcpTool.name}".`);
+                continue;
+            }
+            adaptedTools.push(adapted);
+        }
+        if (adaptedTools.length === 0) {
+            console.warn(`[MCP] Server "${serverName}" exposed no usable tools.`);
+        }
+        else {
+            this.toolRegistry.registerMany(adaptedTools);
+            console.log(`[MCP] Registered ${adaptedTools.length} tool(s) from server "${serverName}".`);
+        }
+        this.connections.set(serverName, { serverName, client, tools: adaptedTools });
+    }
+    /**
+     * Connect to multiple MCP servers. Failures for individual servers are
+     * collected and logged; other servers still connect.
+     *
+     * @returns An array of connection error reports (empty if all succeeded).
+     */
+    async connectAll(servers) {
+        const errors = [];
+        await Promise.allSettled(Object.entries(servers).map(async ([name, config]) => {
+            try {
+                await this.connectToServer(name, config);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                errors.push({ serverName: name, error: message });
+                console.error(`[MCP] Failed to connect to server "${name}": ${message}`);
+            }
+        }));
+        return errors;
+    }
+    /**
+     * Disconnect from a single server and unregister its tools.
+     */
+    async disconnect(serverName) {
+        const conn = this.connections.get(serverName);
+        if (!conn)
+            return;
+        // Unregister tools
+        for (const tool of conn.tools) {
+            this.toolRegistry.remove(tool.name);
+        }
+        // Close the client
+        try {
+            await conn.client.close();
+        }
+        catch (err) {
+            console.warn(`[MCP] Error while closing connection to "${serverName}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        this.connections.delete(serverName);
+        console.log(`[MCP] Disconnected from server "${serverName}".`);
+    }
+    /**
+     * Disconnect from all MCP servers and unregister all MCP-provided tools.
+     */
+    async disconnectAll() {
+        const names = Array.from(this.connections.keys());
+        await Promise.allSettled(names.map((name) => this.disconnect(name)));
+    }
+    // ─── Queries ──────────────────────────────────────────────────────────────
+    /**
+     * Get connection status for all servers.
+     */
+    getStatus() {
+        return Array.from(this.connections.entries()).map(([name, conn]) => ({
+            serverName: name,
+            connected: true,
+            toolCount: conn.tools.length,
+        }));
+    }
+    /**
+     * Whether at least one server is connected.
+     */
+    get isConnected() {
+        return this.connections.size > 0;
+    }
+    /**
+     * Get the number of connected servers.
+     */
+    get connectedCount() {
+        return this.connections.size;
+    }
+    // ─── Tool Adapter ─────────────────────────────────────────────────────────
+    /**
+     * Adapt an MCP SDK tool descriptor into the framework's Tool interface.
+     *
+     * The adapted tool's name is `{serverName}_{mcpToolName}` to avoid
+     * collisions between servers and with locally-registered tools.
+     *
+     * The `execute` function closes over the client instance and handles
+     * result content parsing (extracting text from MCP's Content[] array).
+     */
+    adaptTool(serverName, mcpTool, client) {
+        const prefixedName = `${serverName}_${mcpTool.name}`;
+        return {
+            name: prefixedName,
+            description: mcpTool.description ?? "",
+            parameters: (mcpTool.inputSchema ?? { type: "object", properties: {} }),
+            execute: async (args) => {
+                // Check connection is still alive
+                if (!this.connections.has(serverName)) {
+                    return `Error: MCP server "${serverName}" is no longer connected. Tool "${prefixedName}" is unavailable.`;
+                }
+                try {
+                    const result = await client.callTool({
+                        name: mcpTool.name,
+                        arguments: args,
+                    });
+                    // MCP results carry an array of content items (text, image, etc.)
+                    let output = "(MCP tool returned no content)";
+                    if (result.content && Array.isArray(result.content)) {
+                        const textParts = result.content
+                            .map((c) => (c.text ? c.text : JSON.stringify(c)))
+                            .filter(Boolean);
+                        if (textParts.length > 0) {
+                            output = textParts.join("\n");
+                        }
+                    }
+                    // Prefix with "Error:" so the framework's circuit-breaker /
+                    // retry-guidance path handles it correctly.
+                    if (result.isError) {
+                        return `Error: ${output}`;
+                    }
+                    return output;
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return `Error executing MCP tool "${serverName}/${mcpTool.name}": ${message}`;
+                }
+            },
+        };
+    }
+}
+exports.McpClientManager = McpClientManager;
+//# sourceMappingURL=mcp-client-manager.js.map

package/dist/mcp/mcp-client-manager.js.map

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

package/dist/mcp/mcp-types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * MCP (Model Context Protocol) type definitions.
+ *
+ * Users define MCP servers via `McpServerConfig`. The framework
+ * connects, discovers tools, adapts them, and registers with ToolRegistry.
+ */
+/**
+ * Configuration for connecting to an MCP server.
+ *
+ * Two mutually exclusive modes:
+ * - stdio: set `command` (optionally `args` and `env`)
+ * - SSE:   set `url`
+ *
+ * @example
+ * ```ts
+ * // stdio: local filesystem server
+ * { command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "."] }
+ *
+ * // SSE: remote server
+ * { url: "http://localhost:3001/sse" }
+ * ```
+ */
+export interface McpServerConfig {
+    /** Command for stdio transport (e.g., "npx", "uvx"). Exclusive with `url`. */
+    command?: string;
+    /** Arguments passed to the stdio command. */
+    args?: string[];
+    /** Environment variables injected into the stdio process. */
+    env?: Record<string, string>;
+    /**
+     * URL for SSE transport (e.g., "http://localhost:3000/sse").
+     * Exclusive with `command`.
+     */
+    url?: string;
+}
+/**
+ * Snapshot of a single MCP server's connection state.
+ */
+export interface McpConnectionStatus {
+    serverName: string;
+    connected: boolean;
+    toolCount: number;
+    error?: string;
+}
+/**
+ * Report from a failed connection attempt.
+ */
+export interface McpConnectionErrorReport {
+    serverName: string;
+    error: string;
+}
+/**
+ * Specialized error for MCP connection/issues.
+ */
+export declare class McpConnectionError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=mcp-types.d.ts.map

package/dist/mcp/mcp-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-types.d.ts","sourceRoot":"","sources":["../../src/mcp/mcp-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/mcp/mcp-types.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * MCP (Model Context Protocol) type definitions.
+ *
+ * Users define MCP servers via `McpServerConfig`. The framework
+ * connects, discovers tools, adapts them, and registers with ToolRegistry.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpConnectionError = void 0;
+/**
+ * Specialized error for MCP connection/issues.
+ */
+class McpConnectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpConnectionError";
+    }
+}
+exports.McpConnectionError = McpConnectionError;
+//# sourceMappingURL=mcp-types.js.map

package/dist/mcp/mcp-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-types.js","sourceRoot":"","sources":["../../src/mcp/mcp-types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAkDH;;GAEG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC"}

package/dist/skills/file-skill-loader.d.ts

@@ -1,5 +1,4 @@
 import { Skill } from "./types";
-import { Tool } from "../tools/types";
 /**
  * Parse YAML-like frontmatter from a Markdown file.
  *
@@ -32,15 +31,14 @@ export declare function parseKeywords(raw?: string): string[] | undefined;
  * skills/
  * ├── <skill-name>/
  * │   ├── SKILL.md          # Frontmatter (metadata) + body (system prompt)
- * │   ├── reference/        # Optional reference docs (*.md, *.txt)
- * │   └── scripts/          # Optional executable scripts
+ * │   └── reference/        # Optional reference docs (*.md, *.txt)
  * ├── <another-skill>/
  * │   └── ...
  * ```
  *
  * Loading is two-phase:
  * 1. `scan()` — reads only frontmatter, returns metadata-only `Skill[]`
- * 2. `loadSystemPrompt()` / `loadScriptsAsTools()` — full content, called
+ * 2. `loadSystemPrompt()` — full content (body + reference docs), called
  *    lazily on activation.
  */
 export declare class FileSkillLoader {
@@ -55,14 +53,15 @@ export declare class FileSkillLoader {
     getDirectory(): string;
     /**
      * Get the absolute path to a named skill's subdirectory.
+     * Throws if the skill name contains path traversal characters.
      */
     getSkillDir(name: string): string;
     /**
      * Scan the skills directory and return metadata-only Skill objects.
      *
      * Reads only the frontmatter from each SKILL.md — the body (systemPrompt)
-     * and scripts are NOT loaded at this stage. They are loaded lazily when
-     * the skill is activated.
+     * is NOT loaded at this stage. It is loaded lazily when the skill is
+     * activated.
      *
      * Subdirectories without a valid SKILL.md (or without a `name` in
      * frontmatter) are skipped with a warning.
@@ -76,13 +75,5 @@ export declare class FileSkillLoader {
      * Throws if the skill directory does not exist.
      */
     loadSystemPrompt(name: string): string;
-    /**
-     * Create Tool objects from scripts in the scripts/ subdirectory.
-     *
-     * Each recognized script file becomes a Tool named `{skillName}_{scriptName}`.
-     *
-     * Returns an empty array if the scripts/ directory is missing or empty.
-     */
-    loadScriptsAsTools(name: string): Tool[];
 }
 //# sourceMappingURL=file-skill-loader.d.ts.map

package/dist/skills/file-skill-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-skill-loader.d.ts","sourceRoot":"","sources":["../../src/skills/file-skill-loader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAItC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC7C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd,CAkBA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAOhE;AAiFD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;gBACS,SAAS,CAAC,EAAE,MAAM;IAI9B;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIjC;;;;;;;;;OASG;IACH,IAAI,IAAI,KAAK,EAAE;IAmDf;;;;;;OAMG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAsCtC;;;;;;OAMG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE;CAgFzC"}
+{"version":3,"file":"file-skill-loader.d.ts","sourceRoot":"","sources":["../../src/skills/file-skill-loader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIhC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC7C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd,CAuBA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAOhE;AAwBD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;gBACS,SAAS,CAAC,EAAE,MAAM;IAI9B;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAKjC;;;;;;;;;OASG;IACH,IAAI,IAAI,KAAK,EAAE;IA0Df;;;;;;OAMG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAsCvC"}

package/dist/skills/file-skill-loader.js

@@ -38,7 +38,6 @@ exports.parseFrontmatter = parseFrontmatter;
 exports.parseKeywords = parseKeywords;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
 // ─── Frontmatter Parsing ───────────────────────────────────────────────────
 /**
  * Parse YAML-like frontmatter from a Markdown file.
@@ -69,7 +68,12 @@ function parseFrontmatter(raw) {
         if (colonIdx <= 0)
             continue;
         const key = trimmed.slice(0, colonIdx).trim();
-        const value = trimmed.slice(colonIdx + 1).trim();
+        let value = trimmed.slice(colonIdx + 1).trim();
+        // Strip surrounding quotes if both ends match
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1).trim();
+        }
         if (key)
             frontmatter[key] = value;
     }
@@ -89,78 +93,19 @@ function parseKeywords(raw) {
     return keywords.length > 0 ? keywords : undefined;
 }
 // ─── Script Execution ──────────────────────────────────────────────────────
-const SUPPORTED_SCRIPT_EXTENSIONS = new Set([
-    ".sh",
-    ".bat",
-    ".cmd",
-    ".ps1",
-    ".js",
-    ".py",
-]);
 const REFERENCE_EXTENSIONS = new Set([".md", ".txt"]);
 /**
- * Determine the interpreter and arguments needed to run a script file.
- * Returns `null` if the file extension is not supported.
- */
-function getInterpreter(filePath) {
-    const ext = path.extname(filePath).toLowerCase();
-    switch (ext) {
-        case ".sh":
-            return ["bash", filePath];
-        case ".bat":
-        case ".cmd":
-            return ["cmd.exe", "/c", filePath];
-        case ".ps1":
-            return ["powershell.exe", "-File", filePath];
-        case ".js":
-            return ["node", filePath];
-        case ".py":
-            // Try python3 first, fall back to python
-            try {
-                (0, child_process_1.execFileSync)("python3", ["--version"], { timeout: 5000, stdio: "ignore" });
-                return ["python3", filePath];
-            }
-            catch {
-                return ["python", filePath];
-            }
-        default:
-            return null;
-    }
-}
-/**
- * Extract a description for a script tool from the first comment/line
- * of the file, or fall back to a generic description.
+ * Validate a skill name to prevent path traversal.
+ * Only allows alphanumeric characters, hyphens, underscores, and dots.
  */
-function getScriptDescription(filePath) {
-    try {
-        const content = fs.readFileSync(filePath, "utf-8");
-        const firstLine = content.split("\n")[0]?.trim();
-        if (firstLine) {
-            // Strip common comment markers and shebang
-            const clean = firstLine
-                .replace(/^#!\s*/, "")
-                .replace(/^#\s*/, "")
-                .replace(/^\/\/\s*/, "")
-                .replace(/^--\s*/, "")
-                .trim();
-            if (clean && !clean.startsWith("/"))
-                return clean;
-        }
+function validateSkillName(name) {
+    if (!name) {
+        throw new Error(`Skill name must not be empty.`);
     }
-    catch {
-        // Ignore read errors
+    // Prevent path traversal: reject names with slashes, backslashes, "..", or null bytes
+    if (/[/\\]|\.\.|\0/.test(name)) {
+        throw new Error(`Invalid skill name "${name}": contains path traversal characters.`);
     }
-    return `Execute the ${path.basename(filePath)} script`;
-}
-/**
- * Sanitize a string for use as a tool name (alphanumeric + underscores only).
- */
-function sanitizeToolName(name) {
-    return name
-        .toLowerCase()
-        .replace(/[^a-z0-9_]/g, "_")
-        .replace(/_+/g, "_")
-        .replace(/^_|_$/g, "");
 }
 // ─── FileSkillLoader ───────────────────────────────────────────────────────
 /**
@@ -171,15 +116,14 @@ function sanitizeToolName(name) {
  * skills/
  * ├── <skill-name>/
  * │   ├── SKILL.md          # Frontmatter (metadata) + body (system prompt)
- * │   ├── reference/        # Optional reference docs (*.md, *.txt)
- * │   └── scripts/          # Optional executable scripts
+ * │   └── reference/        # Optional reference docs (*.md, *.txt)
  * ├── <another-skill>/
  * │   └── ...
  * ```
  *
  * Loading is two-phase:
  * 1. `scan()` — reads only frontmatter, returns metadata-only `Skill[]`
- * 2. `loadSystemPrompt()` / `loadScriptsAsTools()` — full content, called
+ * 2. `loadSystemPrompt()` — full content (body + reference docs), called
  *    lazily on activation.
  */
 class FileSkillLoader {
@@ -198,16 +142,18 @@ class FileSkillLoader {
     }
     /**
      * Get the absolute path to a named skill's subdirectory.
+     * Throws if the skill name contains path traversal characters.
      */
     getSkillDir(name) {
+        validateSkillName(name);
         return path.join(this.directory, name);
     }
     /**
      * Scan the skills directory and return metadata-only Skill objects.
      *
      * Reads only the frontmatter from each SKILL.md — the body (systemPrompt)
-     * and scripts are NOT loaded at this stage. They are loaded lazily when
-     * the skill is activated.
+     * is NOT loaded at this stage. It is loaded lazily when the skill is
+     * activated.
      *
      * Subdirectories without a valid SKILL.md (or without a `name` in
      * frontmatter) are skipped with a warning.
@@ -244,12 +190,19 @@ class FileSkillLoader {
                 console.warn(`[Skills] Skipping "${entry.name}": SKILL.md has no "name" in frontmatter`);
                 continue;
             }
+            try {
+                validateSkillName(name);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.warn(`[Skills] Skipping "${entry.name}": ${message}`);
+                continue;
+            }
             skills.push({
                 name,
                 description: frontmatter.description?.trim() ?? "",
                 systemPrompt: "", // Loaded lazily on activation
                 keywords: parseKeywords(frontmatter.keywords),
-                tools: [], // Loaded lazily on activation
             });
         }
         return skills;
@@ -289,77 +242,6 @@ class FileSkillLoader {
         }
         return parts.join("").trim();
     }
-    /**
-     * Create Tool objects from scripts in the scripts/ subdirectory.
-     *
-     * Each recognized script file becomes a Tool named `{skillName}_{scriptName}`.
-     *
-     * Returns an empty array if the scripts/ directory is missing or empty.
-     */
-    loadScriptsAsTools(name) {
-        const scriptsDir = path.join(this.getSkillDir(name), "scripts");
-        const tools = [];
-        let entries;
-        try {
-            entries = fs.readdirSync(scriptsDir, { withFileTypes: true });
-        }
-        catch {
-            // No scripts/ directory — return empty
-            return [];
-        }
-        for (const entry of entries) {
-            if (!entry.isFile())
-                continue;
-            const ext = path.extname(entry.name).toLowerCase();
-            if (!SUPPORTED_SCRIPT_EXTENSIONS.has(ext))
-                continue;
-            const scriptPath = path.join(scriptsDir, entry.name);
-            const scriptName = path.basename(entry.name, ext);
-            const toolName = sanitizeToolName(`${name}_${scriptName}`);
-            const toolDescription = getScriptDescription(scriptPath);
-            const tool = {
-                name: toolName,
-                description: toolDescription,
-                parameters: {
-                    type: "object",
-                    properties: {
-                        args: {
-                            type: "string",
-                            description: `Arguments to pass to the ${entry.name} script. ` +
-                                `Use shell-style syntax (space-separated).`,
-                        },
-                    },
-                    required: ["args"],
-                },
-                async execute(params) {
-                    const argsStr = String(params.args ?? "");
-                    const interpreter = getInterpreter(scriptPath);
-                    if (!interpreter) {
-                        return `Error: Unsupported script type "${ext}" for ${entry.name}`;
-                    }
-                    const [cmd, ...cmdArgs] = interpreter;
-                    // Append the script argument after the interpreter args
-                    const allArgs = argsStr
-                        ? [...cmdArgs, ...argsStr.split(/\s+/).filter(Boolean)]
-                        : cmdArgs;
-                    return new Promise((resolve) => {
-                        const child = (0, child_process_1.execFile)(cmd, allArgs, { timeout: 30000, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
-                            if (err) {
-                                const details = stderr
-                                    ? `\nstderr:\n${stderr.trim()}`
-                                    : "";
-                                resolve(`Error executing ${entry.name}: ${err.message}${details}`);
-                                return;
-                            }
-                            resolve(stdout.trim() || "(no output)");
-                        });
-                    });
-                },
-            };
-            tools.push(tool);
-        }
-        return tools;
-    }
 }
 exports.FileSkillLoader = FileSkillLoader;
 //# sourceMappingURL=file-skill-loader.js.map