kagent-ts 0.1.0

package/dist/session/session-manager.js

@@ -0,0 +1,156 @@
+"use strict";
+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.SessionManager = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Manages session state persistence to disk.
+ *
+ * Each session is stored as a single JSON file in the configured directory.
+ * Sessions are self-contained (messages are inline) so they survive any
+ * memory/component lifecycle and can be resumed after process restarts.
+ */
+class SessionManager {
+    sessionId;
+    sessionDir;
+    constructor(config) {
+        this.sessionId =
+            config?.sessionId ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.sessionDir = path.resolve(config?.sessionDir ?? ".kagent-sessions");
+        fs.mkdirSync(this.sessionDir, { recursive: true });
+    }
+    // ─── Identity ──────────────────────────────────────────────────────────
+    getSessionId() {
+        return this.sessionId;
+    }
+    getSessionDir() {
+        return this.sessionDir;
+    }
+    /**
+     * Set the session ID (used during resume to match the restored session).
+     */
+    setSessionId(id) {
+        this.sessionId = id;
+    }
+    // ─── Persistence ───────────────────────────────────────────────────────
+    /**
+     * Get the file path for the current session.
+     */
+    filePath() {
+        return path.join(this.sessionDir, `${this.sessionId}.json`);
+    }
+    /**
+     * Save a session checkpoint to disk.
+     *
+     * Preserves the original `createdAt` timestamp so resuming a session
+     * retains the original creation time. Updates `updatedAt` to now.
+     */
+    saveCheckpoint(state) {
+        // Preserve the original createdAt (don't overwrite with a later timestamp)
+        const existing = this.loadSession(this.sessionId);
+        const stateToSave = {
+            ...state,
+            createdAt: existing?.createdAt ?? state.createdAt,
+            updatedAt: new Date().toISOString(),
+        };
+        fs.writeFileSync(this.filePath(), JSON.stringify(stateToSave, null, 2), "utf-8");
+    }
+    /**
+     * Load a session by ID. Returns null if the file is missing or corrupt.
+     */
+    loadSession(sessionId) {
+        const filePath = path.join(this.sessionDir, `${sessionId}.json`);
+        try {
+            const raw = fs.readFileSync(filePath, "utf-8");
+            const parsed = JSON.parse(raw);
+            // Basic structural validation
+            if (!parsed.sessionId || !parsed.agentType || !parsed.messages) {
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Return all persisted session states, sorted by `updatedAt` descending.
+     */
+    listSessions() {
+        const sessions = [];
+        try {
+            const files = fs.readdirSync(this.sessionDir);
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const sessionId = file.slice(0, -".json".length);
+                const state = this.loadSession(sessionId);
+                if (state)
+                    sessions.push(state);
+            }
+        }
+        catch {
+            // Directory doesn't exist or can't be read
+        }
+        sessions.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+        return sessions;
+    }
+    /**
+     * Delete a session file from disk.
+     */
+    deleteSession(sessionId) {
+        const filePath = path.join(this.sessionDir, `${sessionId}.json`);
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch {
+            // File doesn't exist — that's fine
+        }
+    }
+    /**
+     * Update the status and timestamp of a session in-place.
+     */
+    markStatus(sessionId, status) {
+        const state = this.loadSession(sessionId);
+        if (state) {
+            state.status = status;
+            state.updatedAt = new Date().toISOString();
+            this.saveCheckpoint(state);
+        }
+    }
+}
+exports.SessionManager = SessionManager;
+//# sourceMappingURL=session-manager.js.map

package/dist/session/session-manager.js.map

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

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

@@ -0,0 +1,51 @@
+import { MessageData } from "../messages/types";
+/**
+ * Which agent paradigm the session belongs to.
+ */
+export type AgentType = "react" | "plan-solve";
+/**
+ * Lifecycle status of a persisted session.
+ * - "active":   Session is in progress, checkpoint was saved mid-run.
+ * - "interrupted": Session was interrupted by a network error, ready for resume.
+ * - "completed":  Session finished normally.
+ */
+export type SessionStatus = "active" | "interrupted" | "completed";
+/**
+ * Serializable plan state for PlanSolveAgent sessions.
+ */
+export interface PlanSolveSessionState {
+    currentPlan: string[];
+    hasPlan: boolean;
+    completedSteps: number;
+    consecutiveFailures: number;
+}
+/**
+ * Full session state snapshot.
+ *
+ * This is the serialised form of everything needed to reconstruct an agent
+ * and resume execution after an interruption (e.g. network outage).
+ *
+ * Messages are stored inline — not referenced via MediumTermMemory — so the
+ * checkpoint is self-contained regardless of memory configuration.
+ */
+export interface SessionState {
+    /** Unique identifier for this session (e.g. "session-1748234567890"). */
+    sessionId: string;
+    /** Which agent type created this session. */
+    agentType: AgentType;
+    /** The core system prompt used by the agent. */
+    systemPrompt: string;
+    /** Full message history at checkpoint time. */
+    messages: MessageData[];
+    /** Plan-Solve specific state (only present for plan-solve agents). */
+    planState?: PlanSolveSessionState;
+    /** ISO-8601 timestamp of session creation (stable across saves). */
+    createdAt: string;
+    /** ISO-8601 timestamp of last checkpoint save. */
+    updatedAt: string;
+    /** Current lifecycle status. */
+    status: SessionStatus;
+    /** Optional metadata (model name, token counts, etc.). */
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=session-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-types.d.ts","sourceRoot":"","sources":["../../src/session/session-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,YAAY,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAElB,6CAA6C;IAC7C,SAAS,EAAE,SAAS,CAAC;IAErB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IAErB,+CAA+C;IAC/C,QAAQ,EAAE,WAAW,EAAE,CAAC;IAExB,sEAAsE;IACtE,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAElC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAElB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAElB,gCAAgC;IAChC,MAAM,EAAE,aAAa,CAAC;IAEtB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC"}

package/dist/session/session-types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=session-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-types.js","sourceRoot":"","sources":["../../src/session/session-types.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,88 @@
+import { Skill } from "./types";
+import { Tool } from "../tools/types";
+/**
+ * Parse YAML-like frontmatter from a Markdown file.
+ *
+ * Expects content between `---` delimiters at the start of the file:
+ * ```
+ * ---
+ * key: value
+ * ---
+ * body content...
+ * ```
+ *
+ * Lines starting with `#` inside frontmatter are treated as comments.
+ * Returns empty frontmatter and full content as body when no `---` markers
+ * are found.
+ */
+export declare function parseFrontmatter(raw: string): {
+    frontmatter: Record<string, string>;
+    body: string;
+};
+/**
+ * Parse a comma-separated keywords string into an array.
+ * Returns `undefined` when the input is empty or absent.
+ */
+export declare function parseKeywords(raw?: string): string[] | undefined;
+/**
+ * Loads skill definitions from a directory on disk.
+ *
+ * Expected directory structure:
+ * ```
+ * skills/
+ * ├── <skill-name>/
+ * │   ├── SKILL.md          # Frontmatter (metadata) + body (system prompt)
+ * │   ├── reference/        # Optional reference docs (*.md, *.txt)
+ * │   └── scripts/          # Optional executable scripts
+ * ├── <another-skill>/
+ * │   └── ...
+ * ```
+ *
+ * Loading is two-phase:
+ * 1. `scan()` — reads only frontmatter, returns metadata-only `Skill[]`
+ * 2. `loadSystemPrompt()` / `loadScriptsAsTools()` — full content, called
+ *    lazily on activation.
+ */
+export declare class FileSkillLoader {
+    private directory;
+    /**
+     * @param directory Path to the skills root directory (default: `./skills`).
+     */
+    constructor(directory?: string);
+    /**
+     * Get the root directory path.
+     */
+    getDirectory(): string;
+    /**
+     * Get the absolute path to a named skill's subdirectory.
+     */
+    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.
+     *
+     * Subdirectories without a valid SKILL.md (or without a `name` in
+     * frontmatter) are skipped with a warning.
+     */
+    scan(): Skill[];
+    /**
+     * Fully load the system prompt for a skill:
+     * 1. SKILL.md body (the content after frontmatter)
+     * 2. All reference/*.md and reference/*.txt files (concatenated with headers)
+     *
+     * 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

@@ -0,0 +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"}

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

@@ -0,0 +1,365 @@
+"use strict";
+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.FileSkillLoader = void 0;
+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.
+ *
+ * Expects content between `---` delimiters at the start of the file:
+ * ```
+ * ---
+ * key: value
+ * ---
+ * body content...
+ * ```
+ *
+ * Lines starting with `#` inside frontmatter are treated as comments.
+ * Returns empty frontmatter and full content as body when no `---` markers
+ * are found.
+ */
+function parseFrontmatter(raw) {
+    const match = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+    if (!match) {
+        return { frontmatter: {}, body: raw.trim() };
+    }
+    const frontmatter = {};
+    for (const line of match[1].split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const colonIdx = trimmed.indexOf(":");
+        if (colonIdx <= 0)
+            continue;
+        const key = trimmed.slice(0, colonIdx).trim();
+        const value = trimmed.slice(colonIdx + 1).trim();
+        if (key)
+            frontmatter[key] = value;
+    }
+    return { frontmatter, body: match[2].trim() };
+}
+/**
+ * Parse a comma-separated keywords string into an array.
+ * Returns `undefined` when the input is empty or absent.
+ */
+function parseKeywords(raw) {
+    if (!raw)
+        return undefined;
+    const keywords = raw
+        .split(",")
+        .map((k) => k.trim())
+        .filter(Boolean);
+    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.
+ */
+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;
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    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 ───────────────────────────────────────────────────────
+/**
+ * Loads skill definitions from a directory on disk.
+ *
+ * Expected directory structure:
+ * ```
+ * skills/
+ * ├── <skill-name>/
+ * │   ├── SKILL.md          # Frontmatter (metadata) + body (system prompt)
+ * │   ├── reference/        # Optional reference docs (*.md, *.txt)
+ * │   └── scripts/          # Optional executable scripts
+ * ├── <another-skill>/
+ * │   └── ...
+ * ```
+ *
+ * Loading is two-phase:
+ * 1. `scan()` — reads only frontmatter, returns metadata-only `Skill[]`
+ * 2. `loadSystemPrompt()` / `loadScriptsAsTools()` — full content, called
+ *    lazily on activation.
+ */
+class FileSkillLoader {
+    directory;
+    /**
+     * @param directory Path to the skills root directory (default: `./skills`).
+     */
+    constructor(directory) {
+        this.directory = path.resolve(directory || "./skills");
+    }
+    /**
+     * Get the root directory path.
+     */
+    getDirectory() {
+        return this.directory;
+    }
+    /**
+     * Get the absolute path to a named skill's subdirectory.
+     */
+    getSkillDir(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.
+     *
+     * Subdirectories without a valid SKILL.md (or without a `name` in
+     * frontmatter) are skipped with a warning.
+     */
+    scan() {
+        const skills = [];
+        let entries;
+        try {
+            entries = fs.readdirSync(this.directory, { withFileTypes: true });
+        }
+        catch {
+            // Directory doesn't exist or can't be read — return empty
+            return [];
+        }
+        for (const entry of entries) {
+            // Skip non-directories, dotfiles, and symlinks
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith("."))
+                continue;
+            const skillPath = path.join(this.directory, entry.name);
+            const skillMdPath = path.join(skillPath, "SKILL.md");
+            let raw;
+            try {
+                raw = fs.readFileSync(skillMdPath, "utf-8");
+            }
+            catch {
+                console.warn(`[Skills] Skipping "${entry.name}": no SKILL.md found in ${skillPath}`);
+                continue;
+            }
+            const { frontmatter, body } = parseFrontmatter(raw);
+            const name = frontmatter.name?.trim();
+            if (!name) {
+                console.warn(`[Skills] Skipping "${entry.name}": SKILL.md has no "name" in frontmatter`);
+                continue;
+            }
+            skills.push({
+                name,
+                description: frontmatter.description?.trim() ?? "",
+                systemPrompt: "", // Loaded lazily on activation
+                keywords: parseKeywords(frontmatter.keywords),
+                tools: [], // Loaded lazily on activation
+            });
+        }
+        return skills;
+    }
+    /**
+     * Fully load the system prompt for a skill:
+     * 1. SKILL.md body (the content after frontmatter)
+     * 2. All reference/*.md and reference/*.txt files (concatenated with headers)
+     *
+     * Throws if the skill directory does not exist.
+     */
+    loadSystemPrompt(name) {
+        const skillDir = this.getSkillDir(name);
+        const skillMdPath = path.join(skillDir, "SKILL.md");
+        // Read SKILL.md body
+        const raw = fs.readFileSync(skillMdPath, "utf-8");
+        const { body } = parseFrontmatter(raw);
+        const parts = [body];
+        // Append reference docs
+        const refDir = path.join(skillDir, "reference");
+        try {
+            const refFiles = fs
+                .readdirSync(refDir, { withFileTypes: true })
+                .filter((f) => f.isFile() &&
+                REFERENCE_EXTENSIONS.has(path.extname(f.name).toLowerCase()))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            if (refFiles.length > 0) {
+                parts.push("\n\n---\n### Reference Documents\n");
+                for (const ref of refFiles) {
+                    const refContent = fs.readFileSync(path.join(refDir, ref.name), "utf-8");
+                    parts.push(`\n**${ref.name}**\n${refContent.trim()}\n`);
+                }
+            }
+        }
+        catch {
+            // No reference/ directory — skip silently
+        }
+        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