agent-from-zero 0.5.0 → 0.28.0

package/dist/menu.js

@@ -0,0 +1,154 @@
+import readline from "node:readline"; // raw-mode keypress events + the interface to pause
+import { renderMenu, MENU_HINT } from "./ui.js"; // the pure drawing + the footer hint
+import { initFormState, reduceForm, renderForm, collectAnswers } from "./form.js"; // the multi-question form
+// An arrow-key selection menu. The whole point: an approval is one keystroke
+// (↑/↓ then Enter), not "type y, then N, then realize you meant the other".
+// Selecting costs the user less than typing.
+//
+// Coordinating with the session's readline (which owns stdin) is the tricky
+// part: we pause it, switch stdin to raw mode, read keypresses ourselves, then
+// hand stdin back exactly as we found it. The `input` parameter is injected so
+// tests can drive it with a fake stream instead of a real terminal.
+//
+// Returns the chosen index, or -1 if cancelled (Esc / Ctrl+C) or not a TTY —
+// callers treat -1 as "no" (fail closed for an approval).
+export function promptSelect(rl, // the session's line reader, paused while we own the keys
+options, // the choices, top to bottom
+input = process.stdin) {
+    return new Promise((resolve) => {
+        if (!input.isTTY)
+            return resolve(-1); // no interactive selection without a terminal — caller falls back
+        let selected = 0;
+        let done = false;
+        const wasRaw = input.isRaw === true; // the session's readline keeps stdin raw — restore THIS, don't force false
+        // Redraw the menu in place: move the cursor back up over the previous
+        // render (options + the one footer line), clear downward, reprint. The
+        // question above the menu stays put.
+        const lineCount = options.length + 1; // options, plus the hint footer
+        const draw = (first) => {
+            if (!first)
+                process.stdout.write(`\x1b[${lineCount}A`); // up to the menu's top
+            process.stdout.write(`\x1b[J${renderMenu(options, selected)}\n${MENU_HINT}\n`); // clear down, repaint + hint
+        };
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            input.off("keypress", onKey); // stop listening
+            try {
+                input.setRawMode(wasRaw); // restore the prior mode — forcing false breaks the live readline → it closes → the REPL exits
+            }
+            catch {
+                /* not all streams support it; ignore */
+            }
+            rl.resume(); // the line reader takes over again
+            resolve(result);
+        };
+        const onKey = (_str, key) => {
+            if (!key || done)
+                return;
+            switch (key.name) {
+                case "up":
+                case "k":
+                    selected = (selected - 1 + options.length) % options.length; // wrap around the top
+                    draw(false);
+                    break;
+                case "down":
+                case "j":
+                    selected = (selected + 1) % options.length; // wrap around the bottom
+                    draw(false);
+                    break;
+                case "return":
+                case "enter":
+                    finish(selected); // commit the choice
+                    break;
+                case "escape":
+                    finish(-1); // bail
+                    break;
+                default:
+                    if (key.ctrl && key.name === "c")
+                        finish(-1); // Ctrl+C in raw mode arrives as a keypress, not a signal
+            }
+        };
+        try {
+            rl.pause(); // stop the line reader from turning our keystrokes into lines
+            if (input === process.stdin)
+                readline.emitKeypressEvents(input); // turn raw bytes into named keys (real stdin only)
+            input.setRawMode(true); // keys arrive immediately, no Enter needed
+            input.resume(); // CRUCIAL: rl.pause() paused the stream — resume it or no keypresses reach us (menu hangs)
+            input.on("keypress", onKey);
+            draw(true); // first paint
+        }
+        catch {
+            finish(-1); // anything unexpected in setup → cancel, caller falls back to typing
+        }
+    });
+}
+// The multi-question form (Day 30): the agent asks several questions at once,
+// the user answers each and submits, and we hand back organized answers. Same
+// raw-mode borrow/return dance as promptSelect; the state machine is in form.ts.
+// Returns the answers, or null if cancelled / not a TTY.
+export function promptForm(rl, questions, input = process.stdin) {
+    return new Promise((resolve) => {
+        if (!input.isTTY || !questions.length)
+            return resolve(null); // no form without a terminal or questions
+        let state = initFormState(questions);
+        let done = false;
+        const wasRaw = input.isRaw === true; // restore this on exit, not false (see promptSelect)
+        const lineCount = renderForm(questions, state).split("\n").length; // constant for these questions
+        const draw = (first) => {
+            if (!first)
+                process.stdout.write(`\x1b[${lineCount}A`); // up over the whole form
+            process.stdout.write(`\x1b[J${renderForm(questions, state)}\n`); // clear down, repaint
+        };
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            input.off("keypress", onKey);
+            try {
+                input.setRawMode(wasRaw); // restore prior mode; forcing false breaks the live readline → REPL exits
+            }
+            catch {
+                /* ignore */
+            }
+            rl.resume();
+            resolve(result);
+        };
+        const onKey = (_str, key) => {
+            if (!key || done)
+                return;
+            if (key.name === "up" || key.name === "k") {
+                state = reduceForm(questions, state, "up").state;
+                draw(false);
+            }
+            else if (key.name === "down" || key.name === "j" || key.name === "tab") {
+                state = reduceForm(questions, state, "down").state;
+                draw(false);
+            }
+            else if (key.name === "return" || key.name === "enter" || key.name === "space") {
+                const next = reduceForm(questions, state, "select");
+                state = next.state;
+                if (next.done)
+                    finish(collectAnswers(questions, state)); // submitted with all answered
+                else
+                    draw(false);
+            }
+            else if (key.name === "escape" || (key.ctrl && key.name === "c")) {
+                finish(null); // cancel
+            }
+        };
+        try {
+            rl.pause();
+            if (input === process.stdin)
+                readline.emitKeypressEvents(input);
+            input.setRawMode(true);
+            input.resume(); // resume the stream rl.pause() paused, or no keypresses reach the form
+            input.on("keypress", onKey);
+            draw(true);
+        }
+        catch {
+            finish(null);
+        }
+    });
+}

package/dist/permissions.js

@@ -80,9 +80,64 @@ function checkBash(command) {
     // Fail closed: a command we don't recognize is a question for the human.
     return { decision: "ask", reason: "unrecognized command", summary };
 }
+// ---- Plan mode (Day 20) ------------------------------------------------------
+// A research-only mode. While it is on, the agent may observe — read files,
+// search, run safe read-only shell — but every tool that mutates the world is
+// blocked, until it presents a plan and the user approves it. The state lives
+// here because the gate is what enforces it; the REPL toggles it with /plan, and
+// the exit_plan_mode tool turns it off once the user approves a plan.
+let planMode = false; // off by default — most sessions never touch it
+export const isPlanMode = () => planMode; // the REPL reads this to mark its prompt
+export const setPlanMode = (on) => { planMode = on; }; // /plan and exit_plan_mode flip it
+// In plan mode, is this call safe — i.e. does it only observe, never mutate?
+// run_bash is decided by its own classifier: a command the gate already rated
+// "allow" (ls, cat, git status) observes; "ask"/"deny" ones (rm, sudo) mutate.
+function planSafe(toolName, verdict) {
+    switch (toolName) {
+        case "read_file":
+        case "search":
+        case "task": // the sub-agent's own calls hit this same gate, still in plan mode
+        case "spawn_teammate": // a teammate's own calls hit this same gate (plan mode still blocks their writes)
+        case "send_message": // coordination only — changes nothing on disk
+        case "request_shutdown": // team protocol (Day 39): coordination, no side effects
+        case "request_plan":
+        case "review_plan":
+        case "submit_plan":
+        case "create_task": // task board (Day 40): touches the internal board, not the user's project
+        case "list_tasks":
+        case "claim_task":
+        case "complete_task":
+        case "ask_user": // asking the user a question is safe in plan mode — it doesn't change anything
+        case "skill": // loading a skill's instructions is read-only; what it does is gated per-call
+        case "todo_write": // planning is exactly what plan mode is FOR — never block it
+        case "bash_output": // reading a background task's output observes, never mutates
+        case "exit_plan_mode": // the way OUT of plan mode must never be blocked by plan mode
+            return true;
+        case "run_bash":
+        case "run_bash_background":
+            return verdict.decision === "allow"; // only the read-only commands the classifier cleared
+        default:
+            return false; // write_file, edit_file, MCP and unknown tools: all mutate-or-unknown
+    }
+}
 // ---- The single entry point ---------------------------------------------------
-// Called by the loop for EVERY tool call, before anything executes.
+// Called by the loop for EVERY tool call, before anything executes. Plan mode is
+// applied as an outer filter: it can only TIGHTEN the base decision (downgrade a
+// mutating allow/ask to deny), never loosen one — a base "deny" keeps its more
+// specific reason, because deny always wins.
 export function checkPermission(toolName, argsJson) {
+    const base = basePermission(toolName, argsJson);
+    if (planMode && base.decision !== "deny" && !planSafe(toolName, base)) {
+        return {
+            decision: "deny",
+            reason: "plan mode is on — investigate with read-only tools, then call exit_plan_mode to present a plan for the user to approve before you change anything",
+            summary: base.summary,
+        };
+    }
+    return base;
+}
+// The underlying rules, plan-mode-agnostic. Wrapped by checkPermission above.
+function basePermission(toolName, argsJson) {
     // A user-configured tool block beats everything, including built-in allows.
     if (CONFIG.permissions.deny.includes(`tool:${toolName}`)) {
         return { decision: "deny", reason: `tool blocked by your settings ("tool:${toolName}")`, summary: toolName };
@@ -102,6 +157,40 @@ export function checkPermission(toolName, argsJson) {
             // Spawning a sub-agent is orchestration, not action: every tool the
             // sub-agent uses goes through this same gate individually.
             return { decision: "allow", reason: "sub-agent tools are gated individually", summary: "task" };
+        case "spawn_teammate":
+            // Same as task: spawning is orchestration. Each teammate's own tool calls
+            // pass through this gate; a teammate's non-interactive policy auto-proceeds
+            // on writes but a hard DENY here still stands (deny always wins).
+            return { decision: "allow", reason: "teammate tools are gated individually", summary: "spawn_teammate" };
+        case "send_message":
+            // Dropping a message in another agent's mailbox has no filesystem effect on
+            // the user's project — it is pure team coordination.
+            return { decision: "allow", reason: "team coordination, no side effects", summary: "send_message" };
+        case "request_shutdown":
+        case "request_plan":
+        case "review_plan":
+        case "submit_plan":
+            // Team protocol messages (Day 39) — request/response coordination over the
+            // mailbox. No filesystem effect; the work they gate still passes the gate.
+            return { decision: "allow", reason: "team protocol, no side effects", summary: toolName };
+        case "create_task":
+        case "list_tasks":
+        case "claim_task":
+        case "complete_task":
+            // Task board (Day 40) — bookkeeping on the internal board, not the user's
+            // project. The actual work a claimed task drives still passes this gate.
+            return { decision: "allow", reason: "task board, no project side effects", summary: toolName };
+        case "ask_user":
+            // Asking the user a question has no side effects — it's the safest thing
+            // the model can do. Never gate it behind an approval prompt.
+            return { decision: "allow", reason: "asks the user, no side effects", summary: "ask_user" };
+        case "skill":
+            // Loading a skill just returns instructions; whatever the skill then DOES
+            // goes through this same gate, call by call. Loading itself is free.
+            return { decision: "allow", reason: "loads instructions, no side effects", summary: "skill" };
+        case "todo_write":
+            // Writing the plan touches nothing but in-memory state and the screen.
+            return { decision: "allow", reason: "updates the plan, no side effects", summary: "todo_write" };
         case "read_file": {
             const p = args.path ?? ""; // the file the model wants to read
             if (SECRET_FILE_RE.test(path.resolve(p))) {
@@ -124,9 +213,40 @@ export function checkPermission(toolName, argsJson) {
             return { decision: "ask", reason: "writes to your filesystem", summary: p }; // normal writes need a human yes
         }
         case "run_bash":
-            return checkBash(args.command ?? ""); // bash gets input-aware analysis
+        case "run_bash_background": {
+            // Backgrounding changes WHEN output comes back, never WHAT runs — so a
+            // background command gets the exact same input-aware analysis as a
+            // foreground one. The danger is in the command, not the blocking.
+            const verdict = checkBash(args.command ?? ""); // bash gets input-aware analysis
+            // "Don't ask again for run_bash this session" (chosen in the approval menu)
+            // upgrades an ASK to ALLOW — but a hard DENY (rm -rf /, .git, .env…) always
+            // stands. Convenience never overrides the no-fly rules. A grant for either
+            // shell tool covers the other: the command is what was vouched for.
+            if (verdict.decision === "ask" && (CONFIG.permissions.allow.includes(`tool:${toolName}`) || CONFIG.permissions.allow.includes("tool:run_bash"))) {
+                return { decision: "allow", reason: "bash pre-approved for this session", summary: verdict.summary };
+            }
+            return verdict;
+        }
+        case "bash_output":
+            // Polling a background task only reads its captured output and status —
+            // it touches nothing on the user's filesystem. Always safe.
+            return { decision: "allow", reason: "reads background task output, no side effects", summary: args.task_id ?? "bash_output" };
+        case "exit_plan_mode": {
+            // Outside plan mode this tool does nothing — let it through silently. In
+            // plan mode it is the approval gate: ask the human, showing the plan, and
+            // only on yes does the tool run and flip plan mode off.
+            if (!planMode)
+                return { decision: "allow", reason: "not in plan mode (no-op)", summary: "exit_plan_mode" };
+            return { decision: "ask", reason: "leave plan mode and start implementing", summary: args.plan ?? "(no plan provided)" };
+        }
         default:
-            // A tool we don't know gets the most suspicious treatment, not the least.
-            return { decision: "ask", reason: "unknown tool", summary: toolName };
+            // Everything else — unknown tools and MCP tools (mcp__server__tool) —
+            // gets the most suspicious treatment, not the least: ask. The user can
+            // pre-approve a trusted MCP tool with "tool:mcp__server__tool" in
+            // settings, or block one with "tool:..." in deny (checked at the top).
+            if (CONFIG.permissions.allow.includes(`tool:${toolName}`)) {
+                return { decision: "allow", reason: "pre-approved by your settings", summary: toolName };
+            }
+            return { decision: "ask", reason: toolName.startsWith("mcp__") ? "external MCP tool" : "unknown tool", summary: toolName };
     }
 }

package/dist/prompt.js

@@ -1,5 +1,6 @@
 import fs from "node:fs"; // to load the optional AGENT.md project memory
 import path from "node:path"; // to resolve it from the current directory
+import { memoryContext } from "./memory.js"; // long-term cross-session memory block
 // The static constitution: identical for every session, every user, every day.
 // NOTHING session-specific belongs here — DeepSeek caches by prefix, and a
 // single changed byte (a date, a username, a cwd) would break the cache for
@@ -33,21 +34,41 @@ Rules:
 - Use your tools to do the work. Verify what you claim — do not guess.
 - Your FINAL message is returned to the parent verbatim. Make it a compact, factual report: findings, exact paths, numbers, code snippets. No greetings, no questions back.
 - You cannot talk to the user. If the task cannot be completed, report precisely what is missing.`;
+// The teammate constitution (Day 38, extended Day 39). Unlike a sub-agent, a
+// teammate is persistent and CONNECTED: it works across many rounds, talks to
+// the team through mailboxes, and coordinates through explicit PROTOCOLS rather
+// than guessing. Load-bearing rules: keep the lead informed; propose-before-act
+// on risky work (submit_plan); and don't exit on your own — report, then idle
+// until the lead shuts you down. {name}/{role} are filled in at spawn time.
+export const TEAMMATE_PROMPT = `You are {name}, a teammate on an agent team. Your role: {role}.
+
+How a team works:
+- You work alongside other teammates, coordinated by the "lead". You all run at the same time.
+- There is a shared TASK BOARD. When you're idle you're automatically offered the next ready task ("You claimed task ..."). Just do it, then call complete_task — you'll be offered the next one. You can also list_tasks to see the board, claim_task a specific one, or create_task to add work you discover.
+- Use send_message to coordinate: report progress or findings to "lead" as you go, or ask a specific teammate something. Messages you receive appear as "[message from X]" — read them and act.
+- Before any RISKY or far-reaching change (refactoring auth, migrating a schema, deleting/rewriting many files), call submit_plan FIRST and wait for the lead's approval. Only start once it's approved; if rejected, revise and submit again.
+- You CANNOT talk to the human and you CANNOT spawn teammates. Decide within your role; if you're blocked, message the lead and say precisely what you need.
+- Use your tools (read_file, edit_file, write_file, search, run_bash) to do real work. Verify what you claim — do not guess.
+- When your current task is done, complete_task it and report to the lead, then STOP. You'll idle and be offered more board work, or follow-up messages. Do NOT decide on your own that the whole job is over — the lead ends your run by requesting shutdown, and you'll exit cleanly then.`;
 // Project memory: an optional AGENT.md in the current directory — the
 // equivalent of Claude Code's CLAUDE.md. Loaded once per session: stable
 // within a session (cache-friendly), different across projects (by design).
 const MEMORY_CAP_CHARS = 8000; // hard cap — a runaway memory file dilutes attention
-// Build the complete system message for this session.
+// Build the complete system message for this session: the constitution, then
+// optional AGENT.md instructions, then optional long-term memory. All three are
+// resolved once per session for a stable, cacheable prefix.
 export function buildSystemMessage() {
+    let msg = SYSTEM_PROMPT;
     const p = path.join(process.cwd(), "AGENT.md"); // only the current directory — V1 keeps lookup simple
-    if (!fs.existsSync(p))
-        return SYSTEM_PROMPT; // no project memory — constitution only
-    const memory = fs.readFileSync(p, "utf8").slice(0, MEMORY_CAP_CHARS); // read and cap
-    // The OVERRIDE/MUST wrapper is deliberate: advisory phrasing gets partial
-    // compliance; imperative wrappers measurably do better.
-    return `${SYSTEM_PROMPT}
-
-The user's project instructions from AGENT.md. These OVERRIDE any default behavior and you MUST follow them exactly as written:
-
-${memory}`;
+    if (fs.existsSync(p)) {
+        const agentMd = fs.readFileSync(p, "utf8").slice(0, MEMORY_CAP_CHARS); // read and cap
+        // The OVERRIDE/MUST wrapper is deliberate: advisory phrasing gets partial
+        // compliance; imperative wrappers measurably do better.
+        msg += `\n\nThe user's project instructions from AGENT.md. These OVERRIDE any default behavior and you MUST follow them exactly as written:\n\n${agentMd}`;
+    }
+    // Long-term memory is BACKGROUND, not an override: facts you established
+    // earlier, to be verified against the code — not hard rules. The different
+    // framing matters (see memory.ts).
+    msg += memoryContext();
+    return msg;
 }

package/dist/session.js

@@ -3,7 +3,9 @@ import path from "node:path"; // path joining
 // Sessions are project-local: .mini-agent/sessions/<id>.json under the cwd.
 // Project-local (not global) because a conversation is about a codebase —
 // resuming a refactor of project A from inside project B makes no sense.
-const SESSIONS_DIR = path.resolve(".mini-agent", "sessions");
+// Resolved lazily (a function, not a const) so it always reflects the current
+// working directory — and so tests can chdir into a scratch dir.
+const sessionsDir = () => path.resolve(".mini-agent", "sessions");
 const KEEP_SESSIONS = 20; // how many session files survive pruning
 // A fresh, filename-safe session id derived from the wall clock.
 export function newSessionId() {
@@ -14,8 +16,9 @@ export function newSessionId() {
 // only representation that is always correct. Crash mid-write leaves the
 // previous snapshot intact.
 export function saveSession(id, model, messages) {
-    fs.mkdirSync(SESSIONS_DIR, { recursive: true }); // first save creates the directory
-    const file = path.join(SESSIONS_DIR, `${id}.json`); // the real destination
+    const dir = sessionsDir();
+    fs.mkdirSync(dir, { recursive: true }); // first save creates the directory
+    const file = path.join(dir, `${id}.json`); // the real destination
     const existing = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null; // to preserve startedAt
     const data = {
         id,
@@ -29,33 +32,72 @@ export function saveSession(id, model, messages) {
     fs.renameSync(tmp, file); // atomic swap
     prune(); // keep the directory bounded
 }
+// Session files on disk, newest (most recently saved) first. Shared by every
+// reader below. Skips tmp files and strangers.
+function sessionFilesNewestFirst() {
+    const dir = sessionsDir();
+    if (!fs.existsSync(dir))
+        return []; // nothing ever saved here
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json")) // ignore tmp files and strangers
+        .map((f) => ({ f, mtime: fs.statSync(path.join(dir, f)).mtimeMs })) // newest by modification time
+        .sort((a, b) => b.mtime - a.mtime);
+}
 // Load the most recent session, or null if there is none (or it is unreadable —
 // a corrupt session file should not kill the CLI, just start fresh).
 export function latestSession() {
-    if (!fs.existsSync(SESSIONS_DIR))
-        return null; // nothing ever saved here
-    const files = fs
-        .readdirSync(SESSIONS_DIR)
-        .filter((f) => f.endsWith(".json")) // ignore tmp files and strangers
-        .map((f) => ({ f, mtime: fs.statSync(path.join(SESSIONS_DIR, f)).mtimeMs })) // newest by modification time
-        .sort((a, b) => b.mtime - a.mtime);
+    const files = sessionFilesNewestFirst();
     if (!files.length)
         return null; // empty directory
     try {
-        return JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, files[0].f), "utf8")); // the newest snapshot
+        return JSON.parse(fs.readFileSync(path.join(sessionsDir(), files[0].f), "utf8")); // the newest snapshot
     }
     catch {
         return null; // unreadable — treat as absent, never crash on resume
     }
 }
+// Load one session by id, or null if missing/corrupt.
+export function loadSession(id) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(sessionsDir(), `${id}.json`), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+// A one-line, human-readable title for a session: the first thing the user
+// actually typed, with any @file attachment block stripped off and the text
+// flattened to a single trimmed line. This is what makes a session list
+// pickable instead of a wall of timestamps.
+export function sessionTitle(messages) {
+    const firstUser = messages.find((m) => m.role === "user");
+    let text = typeof firstUser?.content === "string" ? firstUser.content : "";
+    text = text.split("\n\n[Referenced files")[0]; // drop the @file attachment the REPL appended (Day 26)
+    const line = text.replace(/\s+/g, " ").trim(); // flatten to one line
+    return line || "(no prompt)";
+}
+// Recent sessions, newest first, summarized for a picker. Unreadable files are
+// skipped, never fatal.
+export function listSessions(limit = 10) {
+    const out = [];
+    for (const { f } of sessionFilesNewestFirst()) {
+        if (out.length >= limit)
+            break;
+        try {
+            const s = JSON.parse(fs.readFileSync(path.join(sessionsDir(), f), "utf8"));
+            out.push({ id: s.id, savedAt: s.savedAt, model: s.model, messageCount: s.messages.length, title: sessionTitle(s.messages) });
+        }
+        catch {
+            /* skip a corrupt file */
+        }
+    }
+    return out;
+}
 // Delete everything beyond the newest KEEP_SESSIONS files. A CLI that quietly
 // accumulates unbounded state in every project directory is not industrial.
 function prune() {
-    const files = fs
-        .readdirSync(SESSIONS_DIR)
-        .filter((f) => f.endsWith(".json"))
-        .map((f) => ({ f, mtime: fs.statSync(path.join(SESSIONS_DIR, f)).mtimeMs }))
-        .sort((a, b) => b.mtime - a.mtime); // newest first
-    for (const { f } of files.slice(KEEP_SESSIONS))
-        fs.rmSync(path.join(SESSIONS_DIR, f)); // drop the tail
+    const dir = sessionsDir();
+    for (const { f } of sessionFilesNewestFirst().slice(KEEP_SESSIONS))
+        fs.rmSync(path.join(dir, f)); // drop the tail beyond KEEP_SESSIONS
 }

package/dist/skills.js

@@ -0,0 +1,128 @@
+import fs from "node:fs"; // discover and read SKILL.md files
+import os from "node:os"; // the global skills dir
+import path from "node:path"; // path resolution
+// Project skills win over global ones with the same name.
+function skillDirs() {
+    return [path.resolve(".mini-agent", "skills"), path.join(os.homedir(), ".config", "mini-agent", "skills")];
+}
+// Parse one SKILL.md into a Skill. Pure — no filesystem — so the (fiddly)
+// frontmatter parsing is unit-testable. A tiny YAML subset: `key: value` lines.
+export function parseSkill(raw, fallbackName, filePath = "") {
+    const fm = {};
+    let body = raw.trim();
+    const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/); // frontmatter between --- fences
+    if (m) {
+        body = m[2].trim();
+        for (const line of m[1].split(/\r?\n/)) {
+            const i = line.indexOf(":");
+            if (i < 0)
+                continue;
+            const k = line.slice(0, i).trim();
+            const v = line.slice(i + 1).trim().replace(/^["']|["']$/g, ""); // strip surrounding quotes
+            if (k)
+                fm[k] = v;
+        }
+    }
+    return {
+        name: fm.name || fallbackName,
+        description: fm.description || "",
+        whenToUse: fm.when_to_use || fm.whenToUse || fm.description || "",
+        allowedTools: (fm["allowed-tools"] || fm.allowedTools || "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean),
+        disableModelInvocation: /^true$/i.test(fm.disableModelInvocation || fm["disable-model-invocation"] || ""),
+        body,
+        path: filePath,
+    };
+}
+// Discover skills under the skill dirs (project first, then global). A bad file
+// is skipped, never fatal. `dirs` is injectable for tests.
+export function loadSkills(dirs = skillDirs()) {
+    const out = [];
+    const seen = new Set();
+    for (const dir of dirs) {
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            continue; // dir doesn't exist — fine
+        }
+        for (const entry of entries) {
+            const file = path.join(dir, entry, "SKILL.md");
+            try {
+                const skill = parseSkill(fs.readFileSync(file, "utf8"), entry, file);
+                if (seen.has(skill.name))
+                    continue; // first wins → project overrides global
+                seen.add(skill.name);
+                out.push(skill);
+            }
+            catch {
+                /* not a skill folder — skip */
+            }
+        }
+    }
+    return out;
+}
+export function findSkill(skills, name) {
+    const n = name.trim().toLowerCase();
+    return skills.find((s) => s.name.toLowerCase() === n);
+}
+const MAX_DESC = 250; // cap each skill's listing line (handbook MAX_LISTING_DESC_CHARS)
+const LIST_BUDGET = 8000; // cap the whole listing (handbook DEFAULT_CHAR_BUDGET)
+// The one-line-per-skill listing the model sees (name + when-to-use), budget
+// capped. This is the "progressive disclosure" surface: enough to decide whether
+// to invoke, not the full body.
+export function skillListing(skills) {
+    const lines = [];
+    let used = 0;
+    for (const s of skills) {
+        const desc = (s.whenToUse || s.description).replace(/\s+/g, " ").slice(0, MAX_DESC);
+        const line = `- ${s.name}: ${desc}`;
+        if (used + line.length > LIST_BUDGET)
+            break; // out of budget — stop listing
+        used += line.length;
+        lines.push(line);
+    }
+    return lines.join("\n");
+}
+// What gets handed back when a skill is invoked: the body, plus a reminder of
+// its allowed tools (least-privilege is advisory here — the permission gate
+// still governs every actual call).
+export function skillInstructions(s) {
+    const tools = s.allowedTools.length ? `\n\n[This skill should use only these tools: ${s.allowedTools.join(", ")}. Other actions still go through the normal permission gate.]` : "";
+    return `# Skill: ${s.name}\n\nFollow these steps:\n\n${s.body}${tools}`;
+}
+// Build the `skill` tool from the model-invocable skills. The tool's description
+// IS the listing, so the model learns what skills exist and when to use them;
+// calling it with a name returns that skill's full instructions.
+export function buildSkillTool(skills) {
+    const invokable = skills.filter((s) => !s.disableModelInvocation);
+    const listing = skillListing(invokable) || "(none)";
+    return {
+        definition: {
+            type: "function",
+            function: {
+                name: "skill",
+                description: `Load and follow a reusable skill — a saved, named procedure. Call this when the user's request matches one of the skills below; it returns step-by-step instructions you then carry out yourself.
+Available skills:
+${listing}
+Pass the exact skill name. If nothing matches, do not call this — just answer normally.`,
+                parameters: {
+                    type: "object",
+                    properties: { name: { type: "string", description: "The exact skill name to load" } },
+                    required: ["name"],
+                },
+            },
+        },
+        run: (args) => {
+            const s = findSkill(skills, args.name ?? "");
+            if (!s)
+                return `[error] No skill named "${args.name}". Available: ${invokable.map((x) => x.name).join(", ") || "none"}.`;
+            if (s.disableModelInvocation)
+                return `[error] Skill "${s.name}" can only be invoked by the user, not by you.`;
+            return skillInstructions(s);
+        },
+    };
+}