agent-from-zero 0.32.4 → 0.34.0

package/dist/permissions.js

@@ -111,6 +111,7 @@ function planSafe(toolName, verdict) {
         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 "list_crons": // listing cron jobs is read-only
         case "exit_plan_mode": // the way OUT of plan mode must never be blocked by plan mode
             return true;
         case "run_bash":
@@ -231,6 +232,16 @@ function basePermission(toolName, argsJson) {
             // 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 "schedule_cron":
+            // Scheduling a cron job writes to .mini-agent/scheduled_tasks.json and
+            // drives future work — worth a confirmation prompt.
+            return { decision: "ask", reason: "schedules a recurring task", summary: `${args.cron ?? ""} → ${args.prompt ?? ""}` };
+        case "list_crons":
+            // Listing cron jobs reads in-memory state only — no side effects.
+            return { decision: "allow", reason: "read-only, no side effects", summary: "list_crons" };
+        case "cancel_cron":
+            // Cancelling a cron job modifies internal state and may write to disk.
+            return { decision: "ask", reason: "cancels a scheduled task", summary: args.id ?? "cancel_cron" };
         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

package/dist/session.js

@@ -15,16 +15,17 @@ export function newSessionId() {
 // 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) {
+export function saveSession(id, model, messages, title) {
     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 existing = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null; // to preserve startedAt + title
     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
+        title: title ?? existing?.title, // a generated title sticks across saves
         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)
@@ -32,6 +33,23 @@ export function saveSession(id, model, messages) {
     fs.renameSync(tmp, file); // atomic swap
     prune(); // keep the directory bounded
 }
+// Overwrite just the title of an existing session. Used when the title model
+// finishes AFTER the first save — the next saveSession would otherwise drop it.
+export function setSessionTitle(id, title) {
+    const file = path.join(sessionsDir(), `${id}.json`);
+    let s;
+    try {
+        s = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return; // the session hasn't been saved yet — the title will land on the next save
+    }
+    s.title = title;
+    s.savedAt = new Date().toISOString(); // a title is a change; keep the list ordering honest
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(s)); // atomic, same as saveSession
+    fs.renameSync(tmp, file);
+}
 // Session files on disk, newest (most recently saved) first. Shared by every
 // reader below. Skips tmp files and strangers.
 function sessionFilesNewestFirst() {
@@ -69,7 +87,8 @@ export function loadSession(id) {
 // 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.
+// pickable instead of a wall of timestamps. It's the FALLBACK when no concise
+// generated title has been stored (see saveSession title + setSessionTitle).
 export function sessionTitle(messages) {
     const firstUser = messages.find((m) => m.role === "user");
     let text = typeof firstUser?.content === "string" ? firstUser.content : "";
@@ -86,7 +105,7 @@ export function listSessions(limit = 10) {
             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) });
+            out.push({ id: s.id, savedAt: s.savedAt, model: s.model, messageCount: s.messages.length, title: s.title ?? sessionTitle(s.messages) });
         }
         catch {
             /* skip a corrupt file */

package/dist/title.js

@@ -0,0 +1,49 @@
+// One cheap model call that turns the user's first prompt into a short,
+// pickable session name — the same idea Claude Code uses (a Haiku-tier call
+// producing a 3-7 word sentence-case title, stored as the session's aiTitle).
+// It runs once, fire-and-forget, after the first real user message, so it never
+// blocks the turn and a failure silently falls back to the raw first prompt.
+const TITLE_SYSTEM = `Generate a concise, sentence-case title (3-7 words) that captures the main topic or goal of the user's request. The title should be clear enough that the user recognizes the session in a list. Use sentence case: capitalize only the first word and proper nouns.
+Return ONLY the title — no quotes, no leading/trailing punctuation, no explanation.
+
+Good examples:
+Fix login button on mobile
+Add OAuth authentication
+Debug failing CI tests
+Refactor API client error handling
+
+Bad (too vague): Code changes
+Bad (too long): Investigate and fix the issue where the login button does not respond on mobile devices
+Bad (wrong case): Fix Login Button On Mobile`;
+// Strip the model's inevitable chatter: surrounding quotes, trailing periods,
+// markdown fences, and any multi-line prose. Pure + lenient on purpose.
+export function cleanSessionTitle(text) {
+    let t = text.replace(/^```[^\n]*\n?|\n?```$/g, ""); // drop a markdown fence if present
+    t = t.split("\n")[0] ?? ""; // first line only
+    t = t.replace(/^[\s"'“”‘’]+|[\s"'“”‘’.。]+$/g, "").trim(); // strip quotes + trailing punctuation
+    return t.replace(/\s+/g, " ").trim();
+}
+// Generate a session title from the first user message. Returns null on any
+// failure (bad model response, network error) — callers fall back to the prompt.
+export async function generateSessionTitle(client, model, firstPrompt) {
+    const trimmed = firstPrompt.replace(/\s+/g, " ").trim();
+    if (!trimmed)
+        return null;
+    let text = "";
+    try {
+        const res = await client.chat.completions.create({
+            model,
+            messages: [
+                { role: "system", content: TITLE_SYSTEM },
+                { role: "user", content: trimmed },
+            ],
+            stream: false,
+        });
+        text = res.choices?.[0]?.message?.content ?? "";
+    }
+    catch {
+        return null; // a failed title must never surface or break the session
+    }
+    const title = cleanSessionTitle(text);
+    return title || null;
+}

package/dist/tools.js

@@ -7,6 +7,7 @@ import { setPlanMode } from "./permissions.js"; // plan mode (Day 20): exit_plan
 import { recordMutation } from "./undo.js"; // capture the before-state so /undo (Day 22) can restore it
 import { parseTodos, setTodos, summarizeTodos } from "./todos.js"; // the agent's own checklist (Day 36)
 import { startBackground, readBackground } from "./background.js"; // long-running commands that outlive the turn (Day 37)
+import { scheduleJob, cancelJob, listJobs } from "./cron.js"; // cron scheduler (Day s14): scheduled, recurring work
 // ============ Session state ============
 // The foundation of "read before edit": which files has this session actually read?
 // Files that were never read must not be edited — otherwise the model edits from
@@ -264,6 +265,59 @@ Boundaries & permissions are identical to run_bash (dangerous commands are still
 // runs forever (npm run dev) never "finishes", so the only way to see "ready on
 // :3000" is to read its output. Reading advances a per-task cursor, so repeated
 // polls show only what's new, not the whole log every time.
+// ============ schedule_cron (Day s14) ============
+const scheduleCron = {
+    definition: def("schedule_cron", `Schedule a recurring or one-shot task using a 5-field cron expression. When it fires, YOU are woken with the prompt below, you do the task, and you report the result to the user — even while they're idle. This is the RIGHT tool for "every morning at 9 run the tests", "every 5 minutes check CI", "every minute print X" — anything that should run on a schedule AND report back. Prefer it over run_bash_background for such requests: a background job's output is captured, not shown, so the user won't see it.
+Boundaries: max 50 jobs; the scheduler checks every second and delivers the prompt when the cron matches.
+GRANULARITY: cron's finest interval is ONE MINUTE. Sub-minute schedules ("every 10 seconds") are NOT possible — tell the user that, and offer the nearest option (every minute) or, if they truly need higher frequency to watch live, suggest they run a foreground loop in their own shell.
+Cron format: minute hour day-of-month month day-of-week. Supports *, */N, N, N-M, N,M,….
+Examples: "* * * * *" = every minute; "0 9 * * *" = every day at 9:00; "*/5 * * * *" = every 5 minutes; "0 9 * * 1-5" = weekdays at 9:00.
+
+IMPORTANT — the "prompt" parameter is what you (the agent) will receive when the job fires.
+Put the user's FULL INTENT here — a complete self-contained instruction that tells you what to do.
+Do NOT just repeat the cron expression — describe the actual task in natural language, as if the user
+was saying it to you directly. Include what to execute, what to check, and how to report back.
+
+Examples of good prompts:
+  "Print 'ftfw' to the terminal by running echo ftfw, then report the output."
+  "Run 'npm test' and report how many tests passed/failed."
+  "Check if the dev server on :3000 is reachable via curl, report UP or DOWN."
+  "Check disk usage with df -h, report the / partition usage percentage."`, {
+        cron: { type: "string", description: '5-field cron expression: "0 9 * * *" = daily at 9am, "*/5 * * * *" = every 5 min' },
+        prompt: { type: "string", description: "The FULL task instruction you will receive when this fires — a self-contained description of what to do and how to report results" },
+        recurring: { type: "string", description: '"true" (default) = repeat, "false" = one-shot' },
+        durable: { type: "string", description: '"true" (default) = persist to disk, "false" = session-only' },
+    }, ["cron", "prompt"]),
+    run: (args) => {
+        const recurring = args.recurring !== "false";
+        const durable = args.durable !== "false";
+        const result = scheduleJob(args.cron, args.prompt, recurring, durable);
+        if (typeof result === "string") {
+            return `Scheduled cron job ${result}: "${args.cron}" → "${args.prompt}"${recurring ? " (recurring)" : " (one-shot)"}${durable ? " (durable)" : " (session-only)"}`;
+        }
+        return fail(result.error);
+    },
+};
+// ============ list_crons (Day s14) ============
+const listCrons = {
+    definition: def("list_crons", "List all currently scheduled cron jobs (both durable and session-only). Returns id, cron expression, prompt, and flags.", {}, []),
+    run: () => {
+        const jobs = listJobs();
+        if (!jobs.length)
+            return "No cron jobs scheduled.";
+        return jobs
+            .map((j) => `${j.id}: "${j.cron}" → "${j.prompt}"${j.recurring ? " (recurring)" : " (one-shot)"}${j.durable ? " (durable)" : " (session-only)"}`)
+            .join("\n");
+    },
+};
+// ============ cancel_cron (Day s14) ============
+const cancelCron = {
+    definition: def("cancel_cron", "Cancel a scheduled cron job by its id (from list_crons). Returns whether the job was found and removed.", { id: { type: "string", description: "The cron job id to cancel, e.g. 'cron_1'" } }, ["id"]),
+    run: (args) => {
+        const ok = cancelJob(args.id);
+        return ok ? `Cancelled cron job ${args.id}.` : fail(`Cron job not found: ${args.id}. Use list_crons to see scheduled jobs.`);
+    },
+};
 const bashOutput = {
     definition: def("bash_output", `Check on a background task started with run_bash_background: returns its status and any NEW output since you last checked.
 When to use: to see if a long job is done, or to read a long-running server's output (e.g. confirm "listening on :3000"). A finished task also sends you a <task_notification> automatically — you don't need to poll just to learn it ended.
@@ -346,6 +400,9 @@ export const tools = {
     run_bash: runBash,
     run_bash_background: runBashBackground,
     bash_output: bashOutput,
+    schedule_cron: scheduleCron,
+    list_crons: listCrons,
+    cancel_cron: cancelCron,
     exit_plan_mode: exitPlanMode,
     todo_write: todoWrite,
 };
@@ -355,6 +412,11 @@ export const tools = {
 export function registerExternalTool(tool) {
     tools[tool.definition.function.name] = tool;
 }
+// Remove an external tool by name (used when an MCP server is disconnected or
+// reconnected — its stale tools must never stay registered under the same name).
+export function unregisterExternalTool(name) {
+    delete tools[name];
+}
 // The manuals sent to the model. A function (not a const) since Day 15: MCP
 // tools register after module load, so the list must be computed when asked.
 export function toolDefinitions() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-from-zero",
-  "version": "0.32.4",
+  "version": "0.34.0",
   "description": "Build a Claude Code-style CLI agent from scratch, with AI as your pair programmer — companion code for a 10-day tutorial (DeepSeek by default, any OpenAI-compatible model)",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "eval": "tsx --env-file=.env eval/run.ts",
     "build": "tsc -p tsconfig.build.json",
     "prepare": "npm run build",
-    "test": "tsx tests/tools.test.ts && tsx tests/permissions.test.ts && tsx tests/context.test.ts && tsx tests/hooks.test.ts && tsx tests/mcp.test.ts && tsx tests/judge.test.ts && tsx tests/memory.test.ts && tsx tests/cost.test.ts && tsx tests/validate.test.ts && tsx tests/plan.test.ts && tsx tests/diff.test.ts && tsx tests/undo.test.ts && tsx tests/tiering.test.ts && tsx tests/mcp-http.test.ts && tsx tests/changes.test.ts && tsx tests/mentions.test.ts && tsx tests/session.test.ts && tsx tests/ui.test.ts && tsx tests/approval.test.ts && tsx tests/form.test.ts && tsx tests/model.test.ts && tsx tests/reasoning.test.ts && tsx tests/skills.test.ts && tsx tests/markdown.test.ts && tsx tests/editor.test.ts && tsx tests/todos.test.ts && tsx tests/background.test.ts && tsx tests/team.test.ts && tsx tests/board.test.ts && tsx tests/drop.test.ts && tsx tests/editline.test.ts"
+    "test": "tsx tests/tools.test.ts && tsx tests/permissions.test.ts && tsx tests/context.test.ts && tsx tests/hooks.test.ts && tsx tests/mcp.test.ts && tsx tests/judge.test.ts && tsx tests/memory.test.ts && tsx tests/cost.test.ts && tsx tests/validate.test.ts && tsx tests/plan.test.ts && tsx tests/diff.test.ts && tsx tests/undo.test.ts && tsx tests/tiering.test.ts && tsx tests/mcp-http.test.ts && tsx tests/mcp-oauth.test.ts && tsx tests/changes.test.ts && tsx tests/mentions.test.ts && tsx tests/session.test.ts && tsx tests/ui.test.ts && tsx tests/approval.test.ts && tsx tests/form.test.ts && tsx tests/model.test.ts && tsx tests/reasoning.test.ts && tsx tests/skills.test.ts && tsx tests/markdown.test.ts && tsx tests/editor.test.ts && tsx tests/todos.test.ts && tsx tests/background.test.ts && tsx tests/team.test.ts && tsx tests/board.test.ts && tsx tests/drop.test.ts && tsx tests/editline.test.ts && tsx tests/cron.test.ts"
   },
   "engines": {
     "node": ">=20.6"