agent-from-zero 0.35.1 → 0.35.3

package/dist/skills.js

@@ -1,6 +1,8 @@
 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
+import { CONFIG, saveGlobalSetting } from "./config.js"; // the listing budget + /skills on/off choices
+import { registerExternalTool, tools, unregisterExternalTool } from "./tools.js"; // a skill is exposed to the model as a tool
 // 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")];
@@ -23,17 +25,22 @@ export function parseSkill(raw, fallbackName, filePath = "") {
                 fm[k] = v;
         }
     }
+    // No description? Claude Code falls back to the body's first line — something beats nothing in the listing.
+    const firstLine = body.split("\n").find((l) => l.trim())?.replace(/^#+\s*/, "").trim() ?? "";
     return {
         name: fm.name || fallbackName,
-        description: fm.description || "",
-        whenToUse: fm.when_to_use || fm.whenToUse || fm.description || "",
+        description: fm.description || firstLine,
+        whenToUse: fm.when_to_use || fm.whenToUse || "",
         allowedTools: (fm["allowed-tools"] || fm.allowedTools || "")
             .split(",")
             .map((s) => s.trim())
             .filter(Boolean),
         disableModelInvocation: /^true$/i.test(fm.disableModelInvocation || fm["disable-model-invocation"] || ""),
+        argumentHint: fm["argument-hint"] || "",
+        argNames: (fm.arguments || "").replace(/^\[|\]$/g, "").split(/[\s,]+/).map((a) => a.replace(/^["']|["']$/g, "")).filter(Boolean), // "a, b" or "[a, b]"
         body,
         path: filePath,
+        dir: filePath ? path.dirname(filePath) : "",
     };
 }
 // Discover skills under the skill dirs (project first, then global). A bad file
@@ -65,64 +72,298 @@ export function loadSkills(dirs = skillDirs()) {
     }
     return out;
 }
+// ---- hot reload -------------------------------------------------------------------
+// Claude Code runs a chokidar watcher over its skill dirs. We get the same
+// effect with no watcher at all: before every model call (and whenever the UI
+// asks), stat the SKILL.md files and compare a fingerprint — every path with its
+// mtime and size. A few readdir + stat calls per round is nothing next to a
+// model call, and there is no timer to leak, debounce, or race.
+let cache;
+function fingerprint(dirs) {
+    const parts = [];
+    for (const dir of dirs) {
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.sort()) {
+            try {
+                const st = fs.statSync(path.join(dir, entry, "SKILL.md"));
+                parts.push(`${dir}/${entry}:${st.mtimeMs}:${st.size}`);
+            }
+            catch {
+                /* no SKILL.md here */
+            }
+        }
+    }
+    return parts.join("|");
+}
+// Every skill on disk, whatever its /skills setting: reloaded only when a
+// SKILL.md was added, edited, or removed since the last call. `dirs` is
+// injectable for tests. The /skills panel lists these.
+export function allSkills(dirs = skillDirs()) {
+    const key = dirs.join("\n");
+    const fp = fingerprint(dirs);
+    if (!cache || cache.key !== key || cache.fingerprint !== fp)
+        cache = { key, fingerprint: fp, skills: loadSkills(dirs) };
+    return cache.skills;
+}
+// The skills in effect — what the listing, the skill tool and /skill see.
+// The /skills choices apply here: "off" skills vanish entirely, "user-only"
+// ones stay runnable by the user but are hidden from the model.
+export function currentSkills(dirs = skillDirs()) {
+    return allSkills(dirs)
+        .filter((s) => skillMode(s) !== "off")
+        .map((s) => (skillMode(s) === "user-only" && !s.disableModelInvocation ? { ...s, disableModelInvocation: true } : s));
+}
+export const skillLocked = (s) => s.disableModelInvocation;
+export function skillMode(s) {
+    if (skillLocked(s))
+        return "user-only";
+    return CONFIG.skillOverrides[s.name] ?? "on";
+}
+// Enter/space in the panel: on → user-only → off → on.
+export const nextSkillMode = (m) => (m === "on" ? "user-only" : m === "user-only" ? "off" : "on");
+// Apply and persist a choice. "on" is the default, so it removes the entry
+// rather than storing it — the settings file only lists exceptions.
+export function setSkillMode(name, mode, persist = true) {
+    const next = { ...CONFIG.skillOverrides };
+    if (mode === "on")
+        delete next[name];
+    else
+        next[name] = mode;
+    CONFIG.skillOverrides = next;
+    if (persist)
+        saveGlobalSetting("skillOverrides", next);
+}
+// One panel row's facts: where it lives and what it costs the model to know
+// about it (its listing line, ~4 bytes per token — the same estimate as context.ts).
+export function skillSource(s) {
+    return s.path.startsWith(path.resolve(".mini-agent", "skills")) ? "project" : "user";
+}
+export const skillListingTokens = (s) => Math.ceil(Buffer.byteLength(listingEntry(s)) / 4);
+export const nextSkillSort = (s) => (s === "name" ? "tokens" : s === "tokens" ? "source" : "name");
+// The panel's list: filtered by the search box, sorted.
+// Matching is about the NAME: any part of it ("pul" finds co_dev_pulse). The
+// description only counts for a real word — 3+ characters that start one of
+// its words ("standup", "pulse") — and those rows come after the name matches.
+// A plain substring over descriptions matched everything: a single "a" is in
+// almost every sentence.
+export function skillPanelRows(skills, query, sort) {
+    const q = query.trim().toLowerCase();
+    const byName = (a, b) => a.name.localeCompare(b.name);
+    const order = (rows) => sort === "tokens" ? rows.sort((a, b) => skillListingTokens(b) - skillListingTokens(a) || byName(a, b))
+        : sort === "source" ? rows.sort((a, b) => skillSource(a).localeCompare(skillSource(b)) || byName(a, b))
+            : rows.sort(byName);
+    if (!q)
+        return order([...skills]);
+    const inName = skills.filter((s) => s.name.toLowerCase().includes(q));
+    const inWords = q.length >= 3 ? skills.filter((s) => !inName.includes(s) && s.description.toLowerCase().split(/[^a-z0-9]+/).some((w) => w.startsWith(q))) : [];
+    return [...order(inName), ...order(inWords)];
+}
 export function findSkill(skills, name) {
-    const n = name.trim().toLowerCase();
+    const n = name.trim().replace(/^\//, "").toLowerCase(); // "/deploy" and "deploy" both work, like Claude Code
     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);
+// ---- usage: what the "/" typeahead puts first -----------------------------------------
+// Claude Code ranks a bare "/" by how much you use each skill: every run you
+// start yourself (/name or /skill name) counts, and old use fades — the score
+// halves every 7 days, never below a tenth. Kept in its own small file (not in
+// settings.json, which is for choices, not counters).
+// MINI_AGENT_SKILL_USAGE relocates it (tests point it at a scratch file).
+const usagePath = () => process.env.MINI_AGENT_SKILL_USAGE || path.join(os.homedir(), ".config", "mini-agent", "skill-usage.json");
+function readUsage() {
+    try {
+        return JSON.parse(fs.readFileSync(usagePath(), "utf8"));
+    }
+    catch {
+        return {}; // none yet, or unreadable — ranking just falls back to groups + names
     }
-    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) {
+export function recordSkillUsage(name, now = Date.now()) {
+    const usage = readUsage();
+    usage[name] = { usageCount: (usage[name]?.usageCount ?? 0) + 1, lastUsedAt: now };
+    try {
+        fs.mkdirSync(path.dirname(usagePath()), { recursive: true });
+        fs.writeFileSync(usagePath(), JSON.stringify(usage, null, 2) + "\n");
+    }
+    catch {
+        /* a counter is never worth failing a skill run over */
+    }
+}
+// One read of the usage file, scored per name — for the typeahead, which asks about every skill per keystroke.
+export function skillUsageScores(now = Date.now()) {
+    const usage = readUsage();
+    return (name) => skillUsageScore(name, now, usage);
+}
+export function skillUsageScore(name, now = Date.now(), usage = readUsage()) {
+    const u = usage[name];
+    if (!u)
+        return 0;
+    const days = (now - u.lastUsedAt) / 86_400_000;
+    return u.usageCount * Math.max(0.5 ** (days / 7), 0.1);
+}
+// ---- the listing, as a <system-reminder> ------------------------------------------
+export const wrapInSystemReminder = (content) => `<system-reminder>\n${content}\n</system-reminder>`;
+const LISTING_HEADER = "The following skills are available for use with the skill tool:"; // Claude Code's wording, our tool name
+const MAX_ENTRY = 250; // cap each skill's line (Claude Code: MAX_LISTING_DESC_CHARS)
+const MIN_DESC = 20; // below this, a truncated description is noise — list the bare name
+// One line per skill: "- name: description - when to use", as Claude Code formats it.
+function listingEntry(s, maxDesc = MAX_ENTRY) {
+    const desc = (s.whenToUse ? `${s.description} - ${s.whenToUse}` : s.description).replace(/\s+/g, " ").trim();
+    if (maxDesc < MIN_DESC)
+        return `- ${s.name}`;
+    return `- ${s.name}: ${desc.length > maxDesc ? desc.slice(0, maxDesc - 1) + "…" : desc}`;
+}
+// The listing lines for a set of skills, fit into a character budget: 1% of the
+// context window at ~4 chars/token (Claude Code's formula). Over budget, every
+// description is shortened evenly rather than dropping skills off the end — a
+// skill the model never hears about can never be used.
+export function skillListing(skills, budget = Math.floor(CONFIG.contextWindow * 4 * 0.01)) {
+    let lines = skills.map((s) => listingEntry(s));
+    const total = lines.reduce((n, l) => n + l.length + 1, 0);
+    if (total > budget && skills.length) {
+        const nameCost = skills.reduce((n, s) => n + s.name.length + 5, 0); // "- " + name + ": " + "\n"
+        const maxDesc = Math.floor((budget - nameCost) / skills.length);
+        lines = skills.map((s) => listingEntry(s, maxDesc));
+    }
+    return lines;
+}
+// Which listing lines has THIS conversation already received? Read it back
+// from the history itself instead of keeping a side table: /clear, --resume,
+// and compaction all just work — whatever the model can still see counts as
+// sent, and nothing else does. (Claude Code keeps a per-agent "sent names" set
+// and resets it on reload; deriving it from history gives the same answer and
+// also re-lists after compaction drops the old reminder.)
+function sentListingLines(messages) {
+    const sent = new Set();
+    const prefix = wrapInSystemReminder(LISTING_HEADER).split("\n").slice(0, 2).join("\n");
+    for (const m of messages) {
+        if (m.role !== "user" || typeof m.content !== "string" || !m.content.startsWith(prefix))
+            continue;
+        for (const line of m.content.split("\n"))
+            if (line.startsWith("- "))
+                sent.add(line);
+    }
+    return sent;
+}
+// The reminder to send before the next model call, or null if the model is up
+// to date. Only new or changed lines go out (the delta) — the first call of a
+// conversation gets the whole listing, an edited skill gets its fresh line.
+export function skillListingReminder(messages, skills) {
+    const sent = sentListingLines(messages);
+    const fresh = skillListing(skills.filter((s) => !s.disableModelInvocation)).filter((l) => !sent.has(l));
+    return fresh.length ? wrapInSystemReminder(`${LISTING_HEADER}\n\n${fresh.join("\n")}`) : null;
+}
+// ---- the body, as its own user message ----------------------------------------------
+// Argument substitution, Claude Code's order: $ARGUMENTS[n] / $n (shell-style
+// split), then $ARGUMENTS whole. A body with no placeholder still gets the
+// arguments — appended, so they are never silently dropped.
+export function substituteArguments(body, args) {
+    const parts = args.trim() ? args.trim().split(/\s+/) : [];
+    let out = body
+        .replace(/\$ARGUMENTS\[(\d+)\]/g, (_m, i) => parts[Number(i)] ?? "")
+        .replace(/\$(\d+)(?!\d)/g, (_m, i) => parts[Number(i)] ?? "")
+        .replace(/\$ARGUMENTS/g, args);
+    if (out === body && args.trim())
+        out += `\n\nARGUMENTS: ${args}`;
+    return out;
+}
+// What the model reads once a skill is invoked (by it or by the user):
+// "Base directory for this skill: …" so relative paths in the body resolve,
+// then the body with arguments filled in.
+export function skillBody(s, args = "") {
+    const body = substituteArguments(s.body, args).replaceAll("${CLAUDE_SKILL_DIR}", s.dir).replaceAll("${SKILL_DIR}", s.dir); // a copied Claude Code skill keeps working
     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 `Base directory for this skill: ${s.dir}\n\n${body}${tools}`;
+}
+// The user typed /skill <name> [args]: the two messages Claude Code produces —
+// a <command-name> marker (so the model knows the skill is ALREADY loaded and
+// must not call the tool again), then the body.
+export function userSkillMessages(s, args) {
+    const argsTag = args.trim() ? `\n<command-args>${args.trim()}</command-args>` : "";
+    return [`<command-message>${s.name}</command-message>\n<command-name>/${s.name}</command-name>${argsTag}`, skillBody(s, args)];
+}
+// ---- the skill tool -----------------------------------------------------------------
+const LAUNCHED = "Launching skill: "; // the tool result that tells the loop a body must follow
+// The tool's manual is static — what skills exist arrives through the listing
+// reminders, so a new skill never changes the tool list.
+export const SKILL_TOOL_DESCRIPTION = `Execute a skill within the main conversation.
+
+When users ask you to perform tasks, check if any of the available skills match. Skills provide specialized capabilities and domain knowledge.
+
+How to invoke:
+- Use this tool with the skill name and optional arguments
+- Example: skill: "pdf" — invoke the pdf skill
+- Example: skill: "commit", args: "-m 'Fix bug'" — invoke with arguments
+
+Important:
+- Available skills are listed in system-reminder messages in the conversation
+- When a skill matches the user's request, invoke it BEFORE generating any other response about the task
+- Do not invoke a skill that is already running
+- If you see a <command-name> tag in the current conversation turn, the skill has ALREADY been loaded — follow the instructions directly instead of calling this tool again`;
+export function buildSkillTool(getSkills = currentSkills) {
     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.`,
+                description: SKILL_TOOL_DESCRIPTION,
                 parameters: {
                     type: "object",
-                    properties: { name: { type: "string", description: "The exact skill name to load" } },
-                    required: ["name"],
+                    properties: {
+                        skill: { type: "string", description: 'The skill name. E.g., "commit", "review-pr", or "pdf"' },
+                        args: { type: "string", description: "Optional arguments for the skill" },
+                    },
+                    required: ["skill"],
                 },
             },
         },
         run: (args) => {
-            const s = findSkill(skills, args.name ?? "");
+            const skills = getSkills();
+            const s = findSkill(skills, args.skill ?? "");
             if (!s)
-                return `[error] No skill named "${args.name}". Available: ${invokable.map((x) => x.name).join(", ") || "none"}.`;
+                return `[error] Unknown skill: ${args.skill}. Available: ${skills.filter((x) => !x.disableModelInvocation).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);
+                return `[error] Skill ${s.name} cannot be used with the skill tool due to disable-model-invocation — only the user can run it.`;
+            return `${LAUNCHED}${s.name}`; // the body follows as its own message (skillBodyMessages)
         },
     };
 }
+// After a round's tool results are in: one body message per skill the model
+// launched. They MUST come after all of the round's tool messages — the API
+// requires every tool result of an assistant turn before any other message.
+export function skillBodyMessages(calls, messages, skills = currentSkills()) {
+    const out = [];
+    for (const call of calls) {
+        if (call.name !== "skill")
+            continue;
+        const result = messages.find((m) => m.role === "tool" && m.tool_call_id === call.id);
+        if (!result || typeof result.content !== "string" || !result.content.startsWith(LAUNCHED))
+            continue; // refused, errored, or never ran
+        let args = {};
+        try {
+            args = JSON.parse(call.args);
+        }
+        catch {
+            continue;
+        }
+        const s = findSkill(skills, args.skill ?? "");
+        if (s)
+            out.push(skillBody(s, args.args ?? ""));
+    }
+    return out;
+}
+// Keep the tool list in step with the skill set: the `skill` tool exists while
+// at least one model-invocable skill does. Called before every model call, so
+// the first skill dropped into a folder mid-session brings the tool with it.
+export function syncSkillTool(skills) {
+    const wanted = skills.some((s) => !s.disableModelInvocation);
+    if (wanted && !tools.skill)
+        registerExternalTool(buildSkillTool());
+    if (!wanted && tools.skill)
+        unregisterExternalTool("skill");
+}

package/dist/ui.js

@@ -102,11 +102,18 @@ export function formatElapsed(ms) {
 }
 // Live activity, elapsed time and streamed tokens. The persistent status line
 // owns the model name, so each animation need not repeat it.
-export function spinnerText(word, elapsedSec, subAgent, tokens) {
+//
+// Everything that changes lives INSIDE the parentheses, after the verb. The verb
+// must never move: a prefix that comes and goes (the old "💭 " while reasoning)
+// shoves the whole line sideways every time it toggles. Reasoning is shown the
+// way Claude Code does it — "thinking" while it streams, "thought for Ns" after.
+export function spinnerText(word, elapsedSec, subAgent, tokens, thinking) {
     const head = subAgent ? "sub-agent" : word;
     const bits = [`${elapsedSec}s`];
     if (tokens && tokens > 0)
         bits.push(`↓ ${formatTokens(tokens)} tokens`);
+    if (thinking)
+        bits.push(thinking.active ? "thinking" : `thought for ${Math.max(1, Math.round(thinking.ms / 1000))}s`);
     bits.push("Ctrl+C to interrupt");
     return `${head}… ${chalk.dim(`(${bits.join(" · ")})`)}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-from-zero",
-  "version": "0.35.1",
+  "version": "0.35.3",
   "type": "module",
   "bin": {
     "mini-agent": "dist/agent.js"
@@ -26,6 +26,7 @@
   "dependencies": {
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
+    "fuse.js": "^7.5.0",
     "ink": "^5.2.1",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",