@bowenqt/qiniu-ai-sdk 0.10.0 → 0.13.0

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

@@ -0,0 +1,91 @@
+/**
+ * MCP (Model Context Protocol) Client types.
+ * Phase 1: stdio transport + Bearer token
+ * Phase 3: HTTP transport + OAuth 2.0
+ */
+import type { ToolParameters } from '../../lib/tool-registry';
+/** MCP transport type */
+export type MCPTransport = 'stdio' | 'http';
+/** OAuth 2.0 configuration for HTTP transport */
+export interface MCPOAuthConfig {
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret (optional for public clients) */
+    clientSecret?: string;
+    /** Requested scopes */
+    scopes: string[];
+    /** Authorization endpoint URL (auto-discovered if not set) */
+    authorizationUrl?: string;
+    /** Token endpoint URL (auto-discovered if not set) */
+    tokenUrl?: string;
+    /** Device code endpoint for headless auth (optional) */
+    deviceCodeUrl?: string;
+    /** Redirect URI for auth code flow (default: random localhost port) */
+    redirectUri?: string;
+}
+/** Base MCP server configuration */
+export interface MCPServerConfigBase {
+    /** Server name (unique identifier) */
+    name: string;
+    /** Bearer token for authentication (legacy) */
+    token?: string;
+}
+/** Stdio transport configuration */
+export interface MCPStdioServerConfig extends MCPServerConfigBase {
+    transport: 'stdio';
+    /** Command to execute */
+    command: string;
+    /** Command arguments */
+    args?: string[];
+    /** Environment variables */
+    env?: Record<string, string>;
+}
+/** HTTP transport configuration */
+export interface MCPHttpServerConfig extends MCPServerConfigBase {
+    transport: 'http';
+    /** MCP server URL (e.g., https://mcp.example.com/mcp) */
+    url: string;
+    /** Static bearer token for authentication */
+    token?: string;
+    /** Dynamic token provider (e.g., from TokenManager) */
+    tokenProvider?: () => Promise<string>;
+    /** OAuth configuration (for reference, use with TokenManager) */
+    oauth?: MCPOAuthConfig;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/** Union type for server configuration */
+export type MCPServerConfig = MCPStdioServerConfig | MCPHttpServerConfig;
+/** MCP tool definition from server */
+export interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: ToolParameters;
+}
+/** MCP client configuration */
+export interface MCPClientConfig {
+    /** Servers to connect */
+    servers: MCPServerConfig[];
+    /** Connection timeout in ms */
+    connectionTimeout?: number;
+}
+/** MCP tool execution result */
+export interface MCPToolResult {
+    content: Array<{
+        type: 'text' | 'image' | 'resource';
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+}
+/** MCP server connection state */
+export type MCPConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** Default configuration */
+export declare const DEFAULT_MCP_CONFIG: {
+    readonly connectionTimeout: 30000;
+    readonly httpTimeout: 30000;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,yBAAyB;AACzB,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;AAE5C,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC3B,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IAChC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oCAAoC;AACpC,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC7D,SAAS,EAAE,OAAO,CAAC;IACnB,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,mCAAmC;AACnC,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,iEAAiE;IACjE,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0CAA0C;AAC1C,MAAM,MAAM,eAAe,GAAG,oBAAoB,GAAG,mBAAmB,CAAC;AAEzE,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,cAAc,CAAC;CAC/B;AAED,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC5B,yBAAyB;IACzB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,+BAA+B;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gCAAgC;AAChC,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;QACpC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,kCAAkC;AAClC,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAEvF,4BAA4B;AAC5B,eAAO,MAAM,kBAAkB;;;CAGrB,CAAC"}

package/dist/modules/mcp/types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * MCP (Model Context Protocol) Client types.
+ * Phase 1: stdio transport + Bearer token
+ * Phase 3: HTTP transport + OAuth 2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MCP_CONFIG = void 0;
+/** Default configuration */
+exports.DEFAULT_MCP_CONFIG = {
+    connectionTimeout: 30000, // 30s
+    httpTimeout: 30000, // 30s per request
+};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/mcp/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AA6FH,4BAA4B;AACf,QAAA,kBAAkB,GAAG;IAC9B,iBAAiB,EAAE,KAAK,EAAE,MAAM;IAChC,WAAW,EAAE,KAAK,EAAE,kBAAkB;CAChC,CAAC"}

package/dist/modules/mcp/types.mjs

@@ -0,0 +1,11 @@
+/**
+ * MCP (Model Context Protocol) Client types.
+ * Phase 1: stdio transport + Bearer token
+ * Phase 3: HTTP transport + OAuth 2.0
+ */
+/** Default configuration */
+export const DEFAULT_MCP_CONFIG = {
+    connectionTimeout: 30000, // 30s
+    httpTimeout: 30000, // 30s per request
+};
+//# sourceMappingURL=types.js.map

package/dist/modules/skills/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Skills module public exports.
+ */
+export { SkillLoader, SkillSecurityError, SkillNotFoundError } from './loader';
+export type { Skill, SkillLoaderConfig, SkillReference, SkillInjectionConfig, SkillInjectionPosition, SkillBudget, } from './types';
+export { DEFAULT_SKILL_CONFIG, DEFAULT_SKILL_BUDGET } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/skills/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC/E,YAAY,EACR,KAAK,EACL,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC"}

package/dist/modules/skills/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Skills module public exports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SKILL_BUDGET = exports.DEFAULT_SKILL_CONFIG = exports.SkillNotFoundError = exports.SkillSecurityError = exports.SkillLoader = void 0;
+var loader_1 = require("./loader");
+Object.defineProperty(exports, "SkillLoader", { enumerable: true, get: function () { return loader_1.SkillLoader; } });
+Object.defineProperty(exports, "SkillSecurityError", { enumerable: true, get: function () { return loader_1.SkillSecurityError; } });
+Object.defineProperty(exports, "SkillNotFoundError", { enumerable: true, get: function () { return loader_1.SkillNotFoundError; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "DEFAULT_SKILL_CONFIG", { enumerable: true, get: function () { return types_1.DEFAULT_SKILL_CONFIG; } });
+Object.defineProperty(exports, "DEFAULT_SKILL_BUDGET", { enumerable: true, get: function () { return types_1.DEFAULT_SKILL_BUDGET; } });
+//# sourceMappingURL=index.js.map

package/dist/modules/skills/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/skills/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,mCAA+E;AAAtE,qGAAA,WAAW,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAS5D,iCAAqE;AAA5D,6GAAA,oBAAoB,OAAA;AAAE,6GAAA,oBAAoB,OAAA"}

package/dist/modules/skills/index.mjs

@@ -0,0 +1,6 @@
+/**
+ * Skills module public exports.
+ */
+export { SkillLoader, SkillSecurityError, SkillNotFoundError } from './loader.mjs';
+export { DEFAULT_SKILL_CONFIG, DEFAULT_SKILL_BUDGET } from './types.mjs';
+//# sourceMappingURL=index.js.map

package/dist/modules/skills/loader.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Skill Loader with security-first file validation.
+ * - Only relative paths allowed
+ * - realpath + root check for each reference
+ * - Size limits enforced
+ */
+import type { Skill, SkillLoaderConfig } from './types';
+/** Security error for path/file violations */
+export declare class SkillSecurityError extends Error {
+    readonly path?: string | undefined;
+    constructor(message: string, path?: string | undefined);
+}
+/** Skill not found error */
+export declare class SkillNotFoundError extends Error {
+    constructor(skillName: string);
+}
+/**
+ * Skill Loader loads and validates skill files.
+ */
+export declare class SkillLoader {
+    private readonly config;
+    private readonly resolvedSkillsDir;
+    constructor(config: SkillLoaderConfig);
+    /**
+     * Load a skill by name.
+     */
+    load(skillName: string): Promise<Skill>;
+    /**
+     * Load all skills from the skills directory.
+     */
+    loadAll(): Promise<Skill[]>;
+    /**
+     * Read a file with security validation.
+     */
+    private readFileSecure;
+    /**
+     * Parse and load references from content.
+     * Only relative paths are allowed.
+     */
+    private loadReferences;
+    /**
+     * Estimate token count using unified token-estimator.
+     */
+    private estimateTokens;
+    /**
+     * Safe boundary check for path containment.
+     * Uses path.relative to avoid prefix bypass attacks.
+     */
+    private isWithinRoot;
+}
+//# sourceMappingURL=loader.d.ts.map

package/dist/modules/skills/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAkB,MAAM,SAAS,CAAC;AAIxE,8CAA8C;AAC9C,qBAAa,kBAAmB,SAAQ,KAAK;aACI,IAAI,CAAC,EAAE,MAAM;gBAA9C,OAAO,EAAE,MAAM,EAAkB,IAAI,CAAC,EAAE,MAAM,YAAA;CAI7D;AAED,4BAA4B;AAC5B,qBAAa,kBAAmB,SAAQ,KAAK;gBAC7B,SAAS,EAAE,MAAM;CAIhC;AAED;;GAEG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAE/B,MAAM,EAAE,iBAAiB;IAerC;;OAEG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IA0C7C;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IA0BjC;;OAEG;YACW,cAAc;IAgC5B;;;OAGG;YACW,cAAc;IAmD5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;;OAGG;IACH,OAAO,CAAC,YAAY;CAcvB"}

package/dist/modules/skills/loader.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * Skill Loader with security-first file validation.
+ * - Only relative paths allowed
+ * - realpath + root check for each reference
+ * - Size limits enforced
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillLoader = exports.SkillNotFoundError = exports.SkillSecurityError = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const types_1 = require("./types");
+const token_estimator_1 = require("../../lib/token-estimator");
+/** Security error for path/file violations */
+class SkillSecurityError extends Error {
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'SkillSecurityError';
+    }
+}
+exports.SkillSecurityError = SkillSecurityError;
+/** Skill not found error */
+class SkillNotFoundError extends Error {
+    constructor(skillName) {
+        super(`Skill not found: ${skillName}`);
+        this.name = 'SkillNotFoundError';
+    }
+}
+exports.SkillNotFoundError = SkillNotFoundError;
+/**
+ * Skill Loader loads and validates skill files.
+ */
+class SkillLoader {
+    constructor(config) {
+        this.config = {
+            skillsDir: config.skillsDir,
+            allowedExtensions: config.allowedExtensions ?? [...types_1.DEFAULT_SKILL_CONFIG.allowedExtensions],
+            maxFileSize: config.maxFileSize ?? types_1.DEFAULT_SKILL_CONFIG.maxFileSize,
+            maxReferenceDepth: config.maxReferenceDepth ?? types_1.DEFAULT_SKILL_CONFIG.maxReferenceDepth,
+        };
+        // Resolve and validate skills directory
+        if (!fs.existsSync(config.skillsDir)) {
+            throw new SkillSecurityError(`Skills directory not found: ${config.skillsDir}`);
+        }
+        this.resolvedSkillsDir = fs.realpathSync(config.skillsDir);
+    }
+    /**
+     * Load a skill by name.
+     */
+    async load(skillName) {
+        // Validate skill name (no path separators)
+        if (skillName.includes('/') || skillName.includes('\\') || skillName.includes('..')) {
+            throw new SkillSecurityError('Invalid skill name: path separators not allowed', skillName);
+        }
+        const skillDir = path.join(this.resolvedSkillsDir, skillName);
+        // Check skill directory exists
+        if (!fs.existsSync(skillDir)) {
+            throw new SkillNotFoundError(skillName);
+        }
+        // Validate skill directory is within root using safe boundary check
+        const resolvedSkillDir = fs.realpathSync(skillDir);
+        if (!this.isWithinRoot(resolvedSkillDir, this.resolvedSkillsDir)) {
+            throw new SkillSecurityError('Skill directory escape detected', skillName);
+        }
+        // Load SKILL.md
+        const skillMdPath = path.join(resolvedSkillDir, 'SKILL.md');
+        if (!fs.existsSync(skillMdPath)) {
+            throw new SkillNotFoundError(`${skillName}/SKILL.md`);
+        }
+        const content = await this.readFileSecure(skillMdPath, resolvedSkillDir);
+        // Parse and load references
+        const references = await this.loadReferences(content, resolvedSkillDir, 0);
+        // Estimate token count
+        const totalContent = content + references.map(r => r.content).join('\n');
+        const tokenCount = this.estimateTokens(totalContent);
+        return {
+            name: skillName,
+            content,
+            references,
+            tokenCount,
+        };
+    }
+    /**
+     * Load all skills from the skills directory.
+     */
+    async loadAll() {
+        const entries = fs.readdirSync(this.resolvedSkillsDir, { withFileTypes: true });
+        const skills = [];
+        // Sort for deterministic order
+        const dirs = entries
+            .filter(e => e.isDirectory())
+            .map(e => e.name)
+            .sort();
+        for (const dir of dirs) {
+            try {
+                const skill = await this.load(dir);
+                skills.push(skill);
+            }
+            catch (e) {
+                // Skip invalid skills
+                if (e instanceof SkillNotFoundError) {
+                    continue;
+                }
+                throw e;
+            }
+        }
+        return skills;
+    }
+    /**
+     * Read a file with security validation.
+     */
+    async readFileSecure(filePath, rootDir) {
+        // Resolve real path
+        let resolvedPath;
+        try {
+            resolvedPath = fs.realpathSync(filePath);
+        }
+        catch {
+            throw new SkillSecurityError(`File not found: ${filePath}`, filePath);
+        }
+        // Root check using safe boundary
+        if (!this.isWithinRoot(resolvedPath, rootDir)) {
+            throw new SkillSecurityError('Path escape detected', filePath);
+        }
+        // Extension check
+        const ext = path.extname(resolvedPath).toLowerCase();
+        if (!this.config.allowedExtensions.includes(ext)) {
+            throw new SkillSecurityError(`Extension not allowed: ${ext}`, filePath);
+        }
+        // Size check
+        const stat = fs.statSync(resolvedPath);
+        if (stat.size > this.config.maxFileSize) {
+            throw new SkillSecurityError(`File exceeds size limit: ${stat.size} > ${this.config.maxFileSize}`, filePath);
+        }
+        return fs.readFileSync(resolvedPath, 'utf-8');
+    }
+    /**
+     * Parse and load references from content.
+     * Only relative paths are allowed.
+     */
+    async loadReferences(content, rootDir, depth) {
+        if (depth >= this.config.maxReferenceDepth) {
+            return [];
+        }
+        const references = [];
+        // Match markdown-style references: [text](path)
+        const refPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+        let match;
+        while ((match = refPattern.exec(content)) !== null) {
+            const refPath = match[2];
+            // Skip URLs
+            if (refPath.startsWith('http://') || refPath.startsWith('https://')) {
+                continue;
+            }
+            // Only allow relative paths
+            if (path.isAbsolute(refPath)) {
+                throw new SkillSecurityError('Absolute paths not allowed in references', refPath);
+            }
+            // Skip if not an allowed extension
+            const ext = path.extname(refPath).toLowerCase();
+            if (!this.config.allowedExtensions.includes(ext)) {
+                continue;
+            }
+            const fullPath = path.join(rootDir, refPath);
+            try {
+                const refContent = await this.readFileSecure(fullPath, rootDir);
+                references.push({
+                    path: refPath,
+                    content: refContent,
+                });
+            }
+            catch {
+                // Skip invalid references
+                continue;
+            }
+        }
+        return references;
+    }
+    /**
+     * Estimate token count using unified token-estimator.
+     */
+    estimateTokens(text) {
+        return (0, token_estimator_1.defaultContentEstimator)(text);
+    }
+    /**
+     * Safe boundary check for path containment.
+     * Uses path.relative to avoid prefix bypass attacks.
+     */
+    isWithinRoot(targetPath, rootDir) {
+        // Ensure both paths are normalized and absolute
+        const normalizedRoot = path.resolve(rootDir) + path.sep;
+        const normalizedTarget = path.resolve(targetPath);
+        // Check if target starts with root + separator
+        // This prevents /root-malicious from matching /root
+        if (normalizedTarget === path.resolve(rootDir)) {
+            return true;
+        }
+        // Use startsWith with separator boundary
+        return normalizedTarget.startsWith(normalizedRoot);
+    }
+}
+exports.SkillLoader = SkillLoader;
+//# sourceMappingURL=loader.js.map

package/dist/modules/skills/loader.js.map

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

package/dist/modules/skills/loader.mjs

@@ -0,0 +1,198 @@
+/**
+ * Skill Loader with security-first file validation.
+ * - Only relative paths allowed
+ * - realpath + root check for each reference
+ * - Size limits enforced
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { DEFAULT_SKILL_CONFIG } from './types.mjs';
+import { defaultContentEstimator } from '../../lib/token-estimator.mjs';
+/** Security error for path/file violations */
+export class SkillSecurityError extends Error {
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'SkillSecurityError';
+    }
+}
+/** Skill not found error */
+export class SkillNotFoundError extends Error {
+    constructor(skillName) {
+        super(`Skill not found: ${skillName}`);
+        this.name = 'SkillNotFoundError';
+    }
+}
+/**
+ * Skill Loader loads and validates skill files.
+ */
+export class SkillLoader {
+    constructor(config) {
+        this.config = {
+            skillsDir: config.skillsDir,
+            allowedExtensions: config.allowedExtensions ?? [...DEFAULT_SKILL_CONFIG.allowedExtensions],
+            maxFileSize: config.maxFileSize ?? DEFAULT_SKILL_CONFIG.maxFileSize,
+            maxReferenceDepth: config.maxReferenceDepth ?? DEFAULT_SKILL_CONFIG.maxReferenceDepth,
+        };
+        // Resolve and validate skills directory
+        if (!fs.existsSync(config.skillsDir)) {
+            throw new SkillSecurityError(`Skills directory not found: ${config.skillsDir}`);
+        }
+        this.resolvedSkillsDir = fs.realpathSync(config.skillsDir);
+    }
+    /**
+     * Load a skill by name.
+     */
+    async load(skillName) {
+        // Validate skill name (no path separators)
+        if (skillName.includes('/') || skillName.includes('\\') || skillName.includes('..')) {
+            throw new SkillSecurityError('Invalid skill name: path separators not allowed', skillName);
+        }
+        const skillDir = path.join(this.resolvedSkillsDir, skillName);
+        // Check skill directory exists
+        if (!fs.existsSync(skillDir)) {
+            throw new SkillNotFoundError(skillName);
+        }
+        // Validate skill directory is within root using safe boundary check
+        const resolvedSkillDir = fs.realpathSync(skillDir);
+        if (!this.isWithinRoot(resolvedSkillDir, this.resolvedSkillsDir)) {
+            throw new SkillSecurityError('Skill directory escape detected', skillName);
+        }
+        // Load SKILL.md
+        const skillMdPath = path.join(resolvedSkillDir, 'SKILL.md');
+        if (!fs.existsSync(skillMdPath)) {
+            throw new SkillNotFoundError(`${skillName}/SKILL.md`);
+        }
+        const content = await this.readFileSecure(skillMdPath, resolvedSkillDir);
+        // Parse and load references
+        const references = await this.loadReferences(content, resolvedSkillDir, 0);
+        // Estimate token count
+        const totalContent = content + references.map(r => r.content).join('\n');
+        const tokenCount = this.estimateTokens(totalContent);
+        return {
+            name: skillName,
+            content,
+            references,
+            tokenCount,
+        };
+    }
+    /**
+     * Load all skills from the skills directory.
+     */
+    async loadAll() {
+        const entries = fs.readdirSync(this.resolvedSkillsDir, { withFileTypes: true });
+        const skills = [];
+        // Sort for deterministic order
+        const dirs = entries
+            .filter(e => e.isDirectory())
+            .map(e => e.name)
+            .sort();
+        for (const dir of dirs) {
+            try {
+                const skill = await this.load(dir);
+                skills.push(skill);
+            }
+            catch (e) {
+                // Skip invalid skills
+                if (e instanceof SkillNotFoundError) {
+                    continue;
+                }
+                throw e;
+            }
+        }
+        return skills;
+    }
+    /**
+     * Read a file with security validation.
+     */
+    async readFileSecure(filePath, rootDir) {
+        // Resolve real path
+        let resolvedPath;
+        try {
+            resolvedPath = fs.realpathSync(filePath);
+        }
+        catch {
+            throw new SkillSecurityError(`File not found: ${filePath}`, filePath);
+        }
+        // Root check using safe boundary
+        if (!this.isWithinRoot(resolvedPath, rootDir)) {
+            throw new SkillSecurityError('Path escape detected', filePath);
+        }
+        // Extension check
+        const ext = path.extname(resolvedPath).toLowerCase();
+        if (!this.config.allowedExtensions.includes(ext)) {
+            throw new SkillSecurityError(`Extension not allowed: ${ext}`, filePath);
+        }
+        // Size check
+        const stat = fs.statSync(resolvedPath);
+        if (stat.size > this.config.maxFileSize) {
+            throw new SkillSecurityError(`File exceeds size limit: ${stat.size} > ${this.config.maxFileSize}`, filePath);
+        }
+        return fs.readFileSync(resolvedPath, 'utf-8');
+    }
+    /**
+     * Parse and load references from content.
+     * Only relative paths are allowed.
+     */
+    async loadReferences(content, rootDir, depth) {
+        if (depth >= this.config.maxReferenceDepth) {
+            return [];
+        }
+        const references = [];
+        // Match markdown-style references: [text](path)
+        const refPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+        let match;
+        while ((match = refPattern.exec(content)) !== null) {
+            const refPath = match[2];
+            // Skip URLs
+            if (refPath.startsWith('http://') || refPath.startsWith('https://')) {
+                continue;
+            }
+            // Only allow relative paths
+            if (path.isAbsolute(refPath)) {
+                throw new SkillSecurityError('Absolute paths not allowed in references', refPath);
+            }
+            // Skip if not an allowed extension
+            const ext = path.extname(refPath).toLowerCase();
+            if (!this.config.allowedExtensions.includes(ext)) {
+                continue;
+            }
+            const fullPath = path.join(rootDir, refPath);
+            try {
+                const refContent = await this.readFileSecure(fullPath, rootDir);
+                references.push({
+                    path: refPath,
+                    content: refContent,
+                });
+            }
+            catch {
+                // Skip invalid references
+                continue;
+            }
+        }
+        return references;
+    }
+    /**
+     * Estimate token count using unified token-estimator.
+     */
+    estimateTokens(text) {
+        return defaultContentEstimator(text);
+    }
+    /**
+     * Safe boundary check for path containment.
+     * Uses path.relative to avoid prefix bypass attacks.
+     */
+    isWithinRoot(targetPath, rootDir) {
+        // Ensure both paths are normalized and absolute
+        const normalizedRoot = path.resolve(rootDir) + path.sep;
+        const normalizedTarget = path.resolve(targetPath);
+        // Check if target starts with root + separator
+        // This prevents /root-malicious from matching /root
+        if (normalizedTarget === path.resolve(rootDir)) {
+            return true;
+        }
+        // Use startsWith with separator boundary
+        return normalizedTarget.startsWith(normalizedRoot);
+    }
+}
+//# sourceMappingURL=loader.js.map