agent-from-zero 0.1.0 → 0.27.0

package/dist/permissions.js

@@ -1,4 +1,5 @@
 import path from "node:path"; // used to resolve and split file paths
+import { CONFIG } from "./config.js"; // user-configured allow/deny rules from settings files
 // ---- The no-fly zone --------------------------------------------------------
 // Writes here are never OK, in any mode. .git can destroy history, shell rc
 // files inject code into every future terminal, .ssh/.env leak credentials.
@@ -43,13 +44,26 @@ const BASH_ASK = [
 // Single, read-only-ish commands that run without asking.
 const BASH_ALLOW = new Set(["ls", "pwd", "echo", "wc", "which", "date", "node", "npm", "npx", "cat", "head", "tail"]);
 const GIT_READONLY = new Set(["status", "log", "diff", "show", "branch", "remote", "tag"]); // git subcommands that only read
+// User rules from settings files, split by kind. Computed per call (not cached)
+// so the test suite can mutate CONFIG.permissions and see the effect.
+function userBashRules() {
+    return {
+        allow: CONFIG.permissions.allow.filter((r) => !r.startsWith("tool:")), // bash first-words to trust
+        deny: CONFIG.permissions.deny.filter((r) => !r.startsWith("tool:")), // command substrings to block
+    };
+}
 // Decide what a bash command deserves: deny, ask, or allow.
 function checkBash(command) {
     const summary = command.trim(); // what the user will see in the prompt
-    // Order is the security model: deny first, ask second, allow last.
+    const user = userBashRules(); // the user's configured additions
+    // Order is the security model: built-in deny, then user deny, then ask,
+    // then allow. A user allow can never jump this queue — allow is checked last.
     for (const [re, why] of BASH_DENY)
         if (re.test(command))
             return { decision: "deny", reason: why, summary };
+    for (const d of user.deny)
+        if (command.toLowerCase().includes(d.toLowerCase()))
+            return { decision: "deny", reason: `denied by your settings ("${d}")`, summary };
     for (const [re, why] of BASH_ASK)
         if (re.test(command))
             return { decision: "ask", reason: why, summary };
@@ -61,12 +75,60 @@ function checkBash(command) {
         return { decision: "allow", reason: "read-only git", summary }; // safe git subcommands
     if (BASH_ALLOW.has(words[0]))
         return { decision: "allow", reason: "safe command", summary }; // known-harmless single command
+    if (user.allow.includes(words[0]))
+        return { decision: "allow", reason: "allowed by your settings", summary }; // the user vouched for this 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 "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 "exit_plan_mode": // the way OUT of plan mode must never be blocked by plan mode
+            return true;
+        case "run_bash":
+            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 };
+    }
     let args; // the parsed tool arguments
     try {
         args = JSON.parse(argsJson); // arguments arrive as a raw JSON string from the model
@@ -82,6 +144,14 @@ 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 "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 "read_file": {
             const p = args.path ?? ""; // the file the model wants to read
             if (SECRET_FILE_RE.test(path.resolve(p))) {
@@ -95,12 +165,40 @@ export function checkPermission(toolName, argsJson) {
             const hit = noFlyHit(p); // is it in the no-fly zone?
             if (hit)
                 return { decision: "deny", reason: hit, summary: p }; // hard stop — deny always wins
+            // The user may pre-approve write tools ("tool:edit_file") to skip the
+            // prompt — note this runs AFTER the no-fly check, so it widens "ask",
+            // never "deny".
+            if (CONFIG.permissions.allow.includes(`tool:${toolName}`)) {
+                return { decision: "allow", reason: "pre-approved by your settings", summary: p };
+            }
             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": {
+            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.
+            if (verdict.decision === "ask" && CONFIG.permissions.allow.includes("tool:run_bash")) {
+                return { decision: "allow", reason: "bash pre-approved for this session", summary: verdict.summary };
+            }
+            return verdict;
+        }
+        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
@@ -37,17 +38,21 @@ Rules:
 // 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

@@ -0,0 +1,103 @@
+import fs from "node:fs"; // session files live on disk
+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.
+// 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() {
+    return new Date().toISOString().replace(/[:.]/g, "-"); // 2026-06-12T10-30-00-000Z
+}
+// Persist the conversation. Full snapshot, atomically (tmp + rename): the
+// history is not append-only — compaction rewrites it — so a snapshot is the
+// only representation that is always correct. Crash mid-write leaves the
+// previous snapshot intact.
+export function saveSession(id, model, messages) {
+    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,
+        startedAt: existing?.startedAt ?? new Date().toISOString(), // first save stamps it, later saves keep it
+        savedAt: new Date().toISOString(), // always refreshed
+        model, // informational — resume does not force the same model
+        messages: messages.filter((m) => m.role !== "system"), // the constitution is rebuilt fresh on resume (AGENT.md may have changed)
+    };
+    const tmp = `${file}.tmp`; // write next to the destination (same filesystem → rename is atomic)
+    fs.writeFileSync(tmp, JSON.stringify(data)); // the new snapshot
+    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() {
+    const files = sessionFilesNewestFirst();
+    if (!files.length)
+        return null; // empty directory
+    try {
+        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 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);
+        },
+    };
+}

package/dist/telemetry.js

@@ -0,0 +1,43 @@
+import fs from "node:fs"; // the event log lives on disk
+import path from "node:path"; // path joining
+// LOCAL-ONLY telemetry. Events go to .mini-agent/telemetry.jsonl in the
+// project directory and NOWHERE else — nothing leaves the machine, ever.
+// It exists because "no data" means every optimization is a guess: which
+// errors actually happen, how often compaction fires, which tools get denied.
+// Opt out entirely with MINI_AGENT_NO_TELEMETRY=1.
+//
+// Naming follows the unified-prefix convention (agent_<domain>_<action>) so
+// the log stays greppable: `grep agent_api_error telemetry.jsonl | wc -l`.
+const TELEMETRY_FILE = path.resolve(".mini-agent", "telemetry.jsonl");
+let sessionId = null; // set by initTelemetry; emit() is a no-op before that
+const tallies = new Map(); // per-session event counts, for /stats
+// Arm telemetry for this session. Tests and the eval harness never call this,
+// so library use stays silent — only the real CLI writes events.
+export function initTelemetry(id) {
+    if (process.env.MINI_AGENT_NO_TELEMETRY === "1")
+        return; // the user opted out — stay disarmed
+    sessionId = id; // armed
+}
+// Record one event. Never throws: a telemetry failure must never break work.
+export function emit(event, fields = {}) {
+    const key = event + (fields.tool ? `:${fields.tool}` : ""); // tool events tally per tool name
+    tallies.set(key, (tallies.get(key) ?? 0) + 1); // /stats counts even when disarmed
+    if (!sessionId)
+        return; // disarmed — counters only, no file
+    try {
+        fs.mkdirSync(path.dirname(TELEMETRY_FILE), { recursive: true }); // ensure the directory
+        fs.appendFileSync(TELEMETRY_FILE, JSON.stringify({ ts: new Date().toISOString(), session: sessionId, event, ...fields }) + "\n"); // one JSON object per line
+    }
+    catch {
+        /* a full disk or a read-only checkout is not our problem to escalate */
+    }
+}
+// The per-session tallies, sorted by count — the data behind /stats.
+export function statsReport() {
+    if (!tallies.size)
+        return "(no events this session yet)"; // nothing happened
+    const lines = [...tallies.entries()]
+        .sort((a, b) => b[1] - a[1]) // busiest first
+        .map(([k, n]) => `  ${String(n).padStart(5)}  ${k}`); // aligned counts
+    return ["events this session:", ...lines, `\nfull log: ${TELEMETRY_FILE} (local only — nothing leaves this machine)`].join("\n");
+}