agent-from-zero 0.37.0 → 0.39.1

package/dist/mcp.js

@@ -37,6 +37,10 @@ import { emit } from "./telemetry.js"; // observability
 const INIT_TIMEOUT_MS = 15_000; // a server that doesn't initialize in 15s is skipped
 const CALL_TIMEOUT_MS = 60_000; // a single tool call may take this long
 const OAUTH_CALLBACK_TIMEOUT_MS = 5 * 60_000; // how long the local callback waits for the browser
+// A startup connect that dies on the network (a dropped TLS handshake through a
+// proxy, a timeout, a blip) is retried after these pauses before the server is
+// marked failed; it shows as "connecting…" meanwhile. Mutable for the tests.
+export const MCP_CONNECT_RETRY = { delaysMs: [2_000, 5_000, 10_000] };
 const PROTOCOL_VERSION = "2024-11-05"; // the MCP revision we speak in the handshake
 const CLIENT_INFO = { name: "mini-agent", version: "0" }; // who we say we are in the handshake
 // Thrown when an HTTP MCP server answers 401 — the caller marks the server as
@@ -59,6 +63,15 @@ export class NeedsAuthError extends Error {
         }
     }
 }
+// The request never reached the server or its answer never came back: no
+// connection, a dropped TLS handshake, a timeout. Unlike an error the server
+// returns, trying again later can succeed.
+export class McpNetworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpNetworkError";
+    }
+}
 // ---- stdio transport: one JSON object per line, to a subprocess --------------
 class StdioTransport {
     child;
@@ -268,7 +281,11 @@ class HttpTransport {
         catch (err) {
             if (err instanceof NeedsAuthError)
                 throw err; // propagate so the registry can mark needs-auth
-            return { id: payload.id, error: { message: `MCP HTTP request '${payload.method}' failed: ${err.message}` } };
+            // fetch says only "fetch failed"; the reason (UND_ERR_CONNECT_TIMEOUT,
+            // ECONNRESET, ENOTFOUND…) is on its cause, and it is what you need to know.
+            const cause = err.cause;
+            const why = cause?.code ?? cause?.message;
+            return { id: payload.id, error: { message: `MCP HTTP request '${payload.method}' failed: ${err.message}${why ? ` (${why})` : ""}`, network: true } };
         }
     }
     notify(method, params) {
@@ -312,7 +329,7 @@ class McpClient {
     async start() {
         const init = await this.request("initialize", { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO }, INIT_TIMEOUT_MS);
         if (init.error)
-            throw new Error(init.error.message); // server refused to initialize
+            throw init.error.network ? new McpNetworkError(init.error.message) : new Error(init.error.message); // unreachable, or the server refused to initialize
         this.protocolVersion = init.result?.protocolVersion;
         this.capabilities = Object.keys(init.result?.capabilities ?? {});
         this.transport.notify("notifications/initialized", {}); // tell the server we're ready
@@ -325,7 +342,7 @@ class McpClient {
     async listTools() {
         const list = await this.request("tools/list", {}, INIT_TIMEOUT_MS);
         if (list.error)
-            throw new Error(list.error.message);
+            throw list.error.network ? new McpNetworkError(list.error.message) : new Error(list.error.message);
         return list.result?.tools ?? [];
     }
     // Invoke one tool and flatten its content into plain text for the model.
@@ -355,9 +372,17 @@ const registry = new Map();
 // scratch path so a fake server's tokens never land in the real store).
 const OAUTH_STORE_PATH = process.env.MINI_AGENT_OAUTH_STORE || path.join(os.homedir(), ".config", "mini-agent", "mcp-oauth.json");
 const expiryFrom = (t) => (typeof t.expires_in === "number" ? Date.now() + t.expires_in * 1000 : undefined);
+// The file holds bearer tokens, so only its owner may read it (0600): set on
+// every write, and tightened on read for a store created before this rule or
+// copied over from another machine.
 function readOAuthStore() {
     try {
-        return JSON.parse(fs.readFileSync(OAUTH_STORE_PATH, "utf8"));
+        const store = JSON.parse(fs.readFileSync(OAUTH_STORE_PATH, "utf8"));
+        try {
+            fs.chmodSync(OAUTH_STORE_PATH, 0o600);
+        }
+        catch { /* not ours to fix (read-only mount) — still usable */ }
+        return store;
     }
     catch {
         return {};
@@ -365,7 +390,8 @@ function readOAuthStore() {
 }
 function writeOAuthStore(store) {
     fs.mkdirSync(path.dirname(OAUTH_STORE_PATH), { recursive: true });
-    fs.writeFileSync(OAUTH_STORE_PATH, JSON.stringify(store, null, 2) + "\n");
+    fs.writeFileSync(OAUTH_STORE_PATH, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
+    fs.chmodSync(OAUTH_STORE_PATH, 0o600); // mode applies only when the file is created
 }
 const oauthStore = readOAuthStore();
 function base64url(input) {
@@ -475,8 +501,48 @@ export async function discoverOAuth(serverUrl, challenge = {}) {
 // DCR case, where we register whatever we got); a fixed port is what a
 // pre-registered client demands. The code promise is armed on creation, BEFORE
 // the browser opens, so a fast callback can't race us.
+// Logins waiting for their browser redirect, by OAuth state. The loopback
+// listener is one way in; a pasted redirect address is the other, for a browser
+// on another machine (SSH, a remote box) whose "localhost" is not this one.
+const waitingLogins = new Map();
+export const oauthLoginPending = () => waitingLogins.size > 0;
+// Esc while a login waits: give up on it (the flow rejects, its listener closes).
+export function cancelOAuthLogins() {
+    for (const login of [...waitingLogins.values()])
+        login.cancel();
+}
+// The user pasted the address the browser landed on — on its own, or inside a
+// sentence ("curl this: http://localhost:37831/callback?code=…"). Hand it to the
+// login waiting for its state, exactly as if the browser had reached us.
+// "stale": a callback address no waiting login owns (an older attempt, a typo);
+// "none": no callback address in the text at all.
+export function deliverOAuthRedirect(text) {
+    const found = /(?:https?:\/\/)?(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?\/callback\?[^\s"'<>]+/.exec(text);
+    if (!found)
+        return "none";
+    let url;
+    try {
+        url = new URL(found[0].replace(/[)\]}。，、；,;!！?？]+$/, "").replace(/^(?!https?:\/\/)/, "http://")); // trailing sentence punctuation is not part of it
+    }
+    catch {
+        return "none";
+    }
+    const login = waitingLogins.get(url.searchParams.get("state") ?? "");
+    if (!login)
+        return "stale";
+    login.accept(url);
+    return "delivered";
+}
 async function listenForCallback(port, state) {
     let settle;
+    // The redirect's verdict, however it arrives (the browser, or a pasted address).
+    const accept = (url) => {
+        const code = url.searchParams.get("code");
+        if (code)
+            settle?.resolve(code);
+        else
+            settle?.reject(new Error(`OAuth callback did not include a code: ${url.searchParams.get("error_description") ?? url.searchParams.get("error") ?? "unknown error"}`));
+    };
     const handler = (req, res) => {
         const url = new URL(req.url ?? "/", "http://localhost");
         res.setHeader("connection", "close"); // one-shot listener: a kept-alive socket would deliver a LATER flow's callback (same fixed port) to this dead handler
@@ -486,13 +552,7 @@ async function listenForCallback(port, state) {
         res.end("<h1>Connected</h1><p>You can close this window and return to the terminal.</p>");
         // Settle only once the page has been flushed: settling tears the servers
         // down, and tearing down before the write lands would blank the browser tab.
-        res.once("finish", () => {
-            const code = url.searchParams.get("code");
-            if (code)
-                settle?.resolve(code);
-            else
-                settle?.reject(new Error(`OAuth callback did not include a code: ${url.searchParams.get("error_description") ?? url.searchParams.get("error") ?? "unknown error"}`));
-        });
+        res.once("finish", () => accept(url));
     };
     const v4 = createServer(handler);
     const bound = await new Promise((resolve, reject) => {
@@ -508,6 +568,7 @@ async function listenForCallback(port, state) {
         v6.listen(bound, "::1", () => resolve());
     });
     const close = () => {
+        waitingLogins.delete(state);
         // Release the port for real: close() alone leaves open sockets alive, and a
         // pre-registered client's next flow needs the SAME port back immediately.
         for (const s of [v4, v6]) {
@@ -525,6 +586,7 @@ async function listenForCallback(port, state) {
             reject: (e) => (clearTimeout(timer), close(), reject(e)),
         };
     });
+    waitingLogins.set(state, { accept, cancel: () => settle?.reject(new Error("Authorization cancelled")) });
     return { port: bound, close, code };
 }
 // Run the OAuth authorization-code flow for an HTTP server: PKCE always;
@@ -688,8 +750,10 @@ function markNeedsAuth(name, challenge) {
 }
 // Connect a single configured server and register its tools. Updates the
 // registry with the live status. Used by connectMcpServers() at startup and by
-// /mcp reconnect / enable / auth.
-async function connectOne(name, retried = false, quiet = false) {
+// /mcp reconnect / enable / auth. `retryDelays`: pauses before retrying a
+// network failure (background startup only — an explicit /mcp action answers
+// at once, and its user can simply run it again).
+async function connectOne(name, retried = false, quiet = false, retryDelays = []) {
     const entry = entryFor(name);
     const attempt = {}; // this connect's identity (see the guard after the handshake)
     entry.attempt = attempt;
@@ -735,6 +799,17 @@ async function connectOne(name, retried = false, quiet = false) {
                 return connectOne(name, true, quiet);
             markNeedsAuth(name, err);
         }
+        else if (err instanceof McpNetworkError && retryDelays.length) {
+            // Unreachable this time: stay "connecting" and try again shortly, unless
+            // the user disabled or reconnected it meanwhile (a newer attempt).
+            entry.status = "pending";
+            entry.error = err.message;
+            await new Promise((resolve) => setTimeout(resolve, retryDelays[0]).unref());
+            const now = registry.get(name); // re-read: /mcp may have changed it while we waited
+            if (now !== entry || now.attempt !== attempt || now.status === "disabled")
+                return;
+            return connectOne(name, retried, quiet, retryDelays.slice(1));
+        }
         else {
             entry.status = "failed";
             entry.error = err.message;
@@ -800,7 +875,7 @@ export async function connectMcpServers(options = {}) {
         for (const name of entries)
             entryFor(name).status = "pending";
         for (const name of entries)
-            void connectOne(name, false, true); // fire and forget; connectOne never throws
+            void connectOne(name, false, true, MCP_CONNECT_RETRY.delaysMs); // fire and forget; connectOne never throws
     }
     else {
         for (const name of entries)

package/dist/menu.js

@@ -2,7 +2,7 @@ import readline from "node:readline"; // raw-mode keypress events + the interfac
 import chalk from "chalk";
 import { reduceEditor, truncateToWidth } from "./editor.js";
 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
+import { initFormState, reduceForm, renderForm, collectAnswers, onTypedRow } from "./form.js"; // the multi-question form
 // Navigation owns arrows; printable text belongs to this editor. Sending a
 // follow-up cancels the pending choice, never implicitly approves it.
 function promptDraft(submit, redraw, cancel) {
@@ -10,6 +10,7 @@ function promptDraft(submit, redraw, cancel) {
     let sending = false;
     let error = "";
     return {
+        hasText: () => state.buffer.length > 0,
         render: () => submit ? `\n${truncateToWidth(`Follow-up ❯ ${state.buffer.slice(0, state.cursor)}${chalk.inverse(state.buffer[state.cursor] ?? " ")}${state.buffer.slice(state.cursor + 1)}`, Math.max(10, (process.stdout.columns || 80) - 1))}\n${truncateToWidth(error || "Type a follow-up · Enter sends text; empty input selects", Math.max(10, (process.stdout.columns || 80) - 1))}` : "",
         handle(str, key) {
             if (sending)
@@ -126,19 +127,27 @@ onFollowUp) {
 // 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.
+// Keys: ↑/↓ rows, ←/→ or Tab questions, Enter chooses, Esc cancels. On a "Type
+// something" row the typed keys edit the answer; anywhere else they start a
+// follow-up, which (like promptSelect) cancels the form when sent.
+// Returns the answers, "chat" (talk instead of answering), or null if
+// cancelled / not a TTY.
 export function promptForm(rl, questions, input = process.stdin, onFollowUp) {
     return new Promise((resolve) => {
         if (!input.isTTY || !questions.length)
             return resolve(null); // no form without a terminal or questions
         let state = initFormState(questions);
+        let answer = { buffer: "", cursor: 0 }; // the "Type something" editor
         let done = false;
         const wasRaw = input.isRaw === true; // restore this on exit, not false (see promptSelect)
-        const lineCount = renderForm(questions, state).split("\n").length + (onFollowUp ? 2 : 0);
+        let lineCount = 0; // tabs differ in height: redraw over whatever the last frame was
         const draw = (first) => {
+            const typing = onTypedRow(questions, state);
+            const frame = `${renderForm(questions, state, typing ? answer.buffer : undefined)}${typing ? "" : draft.render()}`;
             if (!first)
-                process.stdout.write(`\x1b[${lineCount}A`); // up over the whole form
-            process.stdout.write(`\x1b[J${renderForm(questions, state)}${draft.render()}\n`);
+                process.stdout.write(`\x1b[${lineCount}A`); // up over the previous frame
+            process.stdout.write(`\x1b[J${frame}\n`);
+            lineCount = frame.split("\n").length;
         };
         const finish = (result) => {
             if (done)
@@ -154,31 +163,60 @@ export function promptForm(rl, questions, input = process.stdin, onFollowUp) {
             rl.resume();
             resolve(result);
         };
+        // Apply one action. The answer editor travels with it while on a typed row,
+        // and follows the cursor: loaded on arrival, cleared on departure.
+        const act = (action) => {
+            const typing = onTypedRow(questions, state);
+            const next = reduceForm(questions, state, action, typing ? answer.buffer : undefined);
+            const arriving = onTypedRow(questions, next.state) && (!typing || next.state.tab !== state.tab || next.state.cursor !== state.cursor);
+            state = next.state;
+            if (next.outcome === "submit")
+                return finish(collectAnswers(questions, state));
+            if (next.outcome === "chat")
+                return finish("chat");
+            if (next.outcome === "cancel")
+                return finish(null);
+            if (arriving) {
+                const text = state.typed[state.tab];
+                answer = { buffer: text, cursor: text.length };
+            }
+            else if (!onTypedRow(questions, state))
+                answer = { buffer: "", cursor: 0 };
+            draw(false);
+        };
         const draft = promptDraft(onFollowUp, () => draw(false), () => finish(null));
         const onKey = (str, key) => {
             if (!key || done)
                 return;
-            if (draft.handle(str, key))
+            if (key.name === "escape" || (key.ctrl && key.name === "c"))
+                return act("escape");
+            const typing = onTypedRow(questions, state);
+            if (key.name === "up")
+                return act("up");
+            if (key.name === "down")
+                return act("down");
+            if (key.name === "tab")
+                return act(key.shift ? "left" : "right");
+            // ←/→ switch questions, unless there is text to move the caret through.
+            if ((key.name === "left" || key.name === "right") && !(typing ? answer.buffer : draft.hasText()))
+                return act(key.name);
+            if (key.name === "return" || key.name === "enter") {
+                if (typing || !draft.handle(str, key))
+                    act("enter"); // a drafted follow-up is sent by its own editor
                 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
+            if (typing) {
+                const next = reduceEditor(answer, str, key);
+                if (next.action === "edit") {
+                    answer = next.state;
                     draw(false);
+                }
+                return;
             }
-            else if (key.name === "escape" || (key.ctrl && key.name === "c")) {
-                finish(null); // cancel
-            }
+            if (draft.handle(str, key))
+                return;
+            if (key.name === "space")
+                act("enter"); // space toggles / chooses too
         };
         try {
             rl.pause();

package/dist/permissions.js

@@ -2,7 +2,7 @@ import path from "node:path"; // used to resolve and split file paths
 import fs from "node:fs"; // resolve symlinks before auto mode grants file access
 import os from "node:os"; // `cd ~` in the recoverable-shell analyzer
 import { execFileSync } from "node:child_process"; // ask git whether a deletion target is disposable
-import { CONFIG } from "./config.js"; // user-configured allow/deny rules from settings files
+import { CONFIG, GLOBAL_SETTINGS_PATH } from "./config.js"; // user-configured allow/deny rules from settings files
 import { emit } from "./telemetry.js"; // a bypassed approval leaves an audit row, not silence
 // ---- The no-fly zone --------------------------------------------------------
 // Writes here are never OK, in any mode. .git can destroy history, shell rc
@@ -216,6 +216,27 @@ export function gitWorkTree(target) {
     }
     return topLevels.get(dir);
 }
+// Trusted ground outside any work tree: autoMode.trustedDirs from global
+// settings, plus directories trusted from the approval menu this session.
+// Home and / never count, for the same reason as above. Nor does the global
+// settings file: it holds this very list, and an agent that could edit it
+// unasked could widen its own reach.
+const tooBroadToTrust = (dir) => dir === os.homedir() || dir === resolveFileTarget(os.homedir()) || dir === path.parse(dir).root;
+const settingsFile = () => resolveFileTarget(GLOBAL_SETTINGS_PATH);
+function trustedDir(target) {
+    if (target === settingsFile())
+        return false;
+    return CONFIG.autoMode.trustedDirs.some((dir) => {
+        let root;
+        try {
+            root = resolveFileTarget(dir);
+        }
+        catch {
+            return false;
+        }
+        return !tooBroadToTrust(root) && inside(root, target);
+    });
+}
 // A deletion is recoverable when the target is scratch (inside a temp dir) or
 // git calls it disposable in its own repo: ignored (build output, caches) with
 // nothing tracked beneath it. Symlinks are left to review: `rm -r link/`
@@ -595,9 +616,13 @@ function basePermission(toolName, argsJson, auto) {
                 return { decision: "deny", reason, summary: args.path };
             const relative = path.relative(fs.realpathSync(process.cwd()), resolved);
             // Outside the start directory is still recoverable in another git work
-            // tree or a temp dir (git, /undo); anywhere else a human decides.
-            if (toolName !== "read_file" && (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) && !inTempDir(resolved) && !gitWorkTree(resolved)) {
-                return { decision: "ask", requiresHuman: true, reason: "resolved write target is outside the project", summary: `${args.path} → ${resolved}` };
+            // tree or a temp dir (git, /undo), and a trusted directory is one the
+            // user vouched for; anywhere else a human decides, and may trust the
+            // file's directory for the session rather than approve every write.
+            if (toolName !== "read_file" && (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) && !inTempDir(resolved) && !gitWorkTree(resolved) && !trustedDir(resolved)) {
+                const dir = path.dirname(resolved);
+                return { decision: "ask", requiresHuman: true, reason: "resolved write target is outside the project", summary: `${args.path} → ${resolved}`,
+                    ...(resolved === settingsFile() || tooBroadToTrust(dir) ? {} : { trustDir: dir }) };
             }
         }
         catch {
@@ -747,3 +772,30 @@ function resolveFileTarget(target) {
     }
     return path.join(fs.realpathSync(current), ...missing);
 }
+// ---- The approval menu ----------------------------------------------------------
+// Both frontends (readline and Ink) offer the same choices and apply the same
+// session grant, so the menu lives next to the rules it widens. Outside auto
+// mode the grant is "don't ask again for this tool"; in auto mode it is "trust
+// this directory", offered only for an outside write. The last option is always
+// "No", and so is -1 (Esc). `granted` is the note to show after a grant.
+export function approvalMenu(auto, toolName, trustDir) {
+    const grant = auto
+        ? (trustDir ? `Yes, and trust ${trustDir}/ for this session` : null)
+        : (toolName ? `Yes, and don't ask again for ${toolName} this session` : "Yes, and don't ask again this session");
+    const options = [auto ? "Yes, once" : "Yes", ...(grant ? [grant] : []), "No — let me tell the agent what to do instead"];
+    const choose = (i) => {
+        if (i < 0 || i >= options.length - 1)
+            return { approved: false };
+        if (i === 0)
+            return { approved: true };
+        if (auto && trustDir) {
+            CONFIG.autoMode.trustedDirs.push(trustDir);
+            return { approved: true, granted: `trusting ${trustDir}/ for this session` };
+        }
+        if (!toolName)
+            return { approved: true };
+        CONFIG.permissions.allow.push(`tool:${toolName}`); // "don't ask again" → session allowlist
+        return { approved: true, granted: `won't ask again for ${toolName} this session` };
+    };
+    return { options, choose };
+}

package/dist/prompt.js

@@ -21,7 +21,7 @@ Behavior rules:
 - You support SKILLS — reusable, named procedures saved as Markdown under .mini-agent/skills/ in the project (or ~/.config/mini-agent/skills/ globally). When a request matches one of the skills listed in the \`skill\` tool, call \`skill\` with its name to load the steps, then carry them out. If there is no \`skill\` tool in this session, none are loaded in this project yet — the capability still exists: the user adds one at .mini-agent/skills/<name>/SKILL.md, runs any with "/skill <name>", and lists them with "/skills". So when asked whether you support skills, the answer is yes — describe this mechanism (and which skills, if any, are currently loaded); never claim your toolset is fixed.
 - Report results accurately. If a test fails, say it failed. Don't claim success when you're not sure. Don't be overly self-doubting either — distinguish "verified working" from "I think it works".
 - Never add comments to code you did not change. Never reformat code you did not change.
-- Keep final answers under 150 words unless the task genuinely requires more.
+- End every turn with a final message the user can take in at a glance. First line: the outcome (done, failed, found X, nothing to report). If that says it all, stop there, e.g. "No alerts — all normal." Otherwise follow it with short sections, each a bold label over bullet points: what you did, what you found (each problem: what, where, impact), what needs the user's decision. One fact per bullet; no filler, no restating the request. Under 150 words unless the task genuinely requires more. Write in the language the user writes in.
 - Between tool calls, write at most one short sentence — usually nothing.
 - A [permission] denial is a hard boundary. Do not attempt workarounds — explain and ask the user.
 - If the task is ambiguous, ask one clarifying question instead of guessing.`;

package/dist/title.js

@@ -41,8 +41,9 @@ export function setTerminalTitle(title) {
 }
 export const refreshTerminalTitle = () => setTerminalTitle(lastTitle);
 // "Which window is this?" — another session asked. Ring the bell and blink the
-// tab title for a few seconds, then put the real title back.
-export function flashTerminalTitle(ms = 6000) {
+// tab title for a few seconds, then put the real title back. A finished cron run
+// uses it too, blinking its own label ("⏰ cron_1 done") instead.
+export function flashTerminalTitle(ms = 6000, label) {
     if (!process.stdout.isTTY)
         return;
     process.stdout.write("\x07");
@@ -59,7 +60,7 @@ export function flashTerminalTitle(ms = 6000) {
             process.stdout.write(terminalTitleSequence(tabTitle(lastTitle)));
             return;
         }
-        process.stdout.write(terminalTitleSequence(on ? `👋 ${name} — HERE 👋` : tabTitle(lastTitle)));
+        process.stdout.write(terminalTitleSequence(on ? label ?? `👋 ${name} — HERE 👋` : tabTitle(lastTitle)));
     }, 500);
     flashing.unref();
 }

package/dist/tools.js

@@ -23,7 +23,8 @@ const TOOL_RESULT_LIMIT = 4000; // cap (chars) for a normal tool result entering
 const READ_LIMIT = 16000; // read_file gets a larger cap of its own
 const SEARCH_MAX_MATCHES = 50; // max matches returned by search
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build"]); // directories search never enters
-const BASH_TIMEOUT_MS = 30_000; // a single command may run this long before we kill it
+const BASH_TIMEOUT_MS = 120_000; // a single command may run this long before we kill it (Claude Code's 2 minutes)
+const BASH_MAX_TIMEOUT_MS = 600_000; // the most a command may ask for; anything longer belongs in the background
 const BASH_OUTPUT_LIMIT = 8_000; // chars of command output kept inline; beyond this we spill to a file
 const SPILL_NOTE_SLACK = 400; // room for the "[...saved to FILE]" note so dispatch's cap never eats it
 // Errors are not exceptions — they are text that tells the model what to do next.
@@ -189,17 +190,27 @@ function spillIfHuge(out, what) {
     const head = out.slice(0, BASH_OUTPUT_LIMIT); // a generous preview
     return `${head}\n\n[...${what} truncated: ${out.length} chars total. Full output saved to ${file} — use read_file to inspect more.]`;
 }
+// The watchdog for one run_bash call: the model may ask for more (or less) than
+// the default, never past the maximum. Anything that isn't a positive number of
+// seconds — missing, "", garbage — gets the default.
+export function bashTimeoutMs(seconds) {
+    const s = Number(seconds);
+    return Number.isFinite(s) && s > 0 ? Math.min(Math.round(s * 1000), BASH_MAX_TIMEOUT_MS) : BASH_TIMEOUT_MS;
+}
 const runBash = {
-    definition: def("run_bash", `Run a bash command on the user's machine (30s timeout) and return its output.
+    definition: def("run_bash", `Run a bash command on the user's machine and return its output. It is killed after 2 minutes unless you pass a longer timeout (up to 600 seconds) — set one when you expect a slow command (a full test suite, a build). Longer, or work you don't need to wait for: run_bash_background.
 Boundaries: only for things that truly need execution — installing dependencies, running tests/scripts, git operations.
 To read files use read_file (not cat), to search use search (not grep/find), to edit files use edit_file (not sed/redirection).
 Dangerous commands require user approval; some are denied outright. A [permission] result is a hard boundary — never try to work around it.
-On error: failures return the error output — analyze it and try a different approach; do not resend the same command unchanged.`, { command: { type: "string", description: "The bash command to run" } }, ["command"]),
+On error: failures return the error output — analyze it and try a different approach; do not resend the same command unchanged.`, {
+        command: { type: "string", description: "The bash command to run" },
+        timeout: { type: "number", description: "Optional: seconds before the command is killed (default 120, max 600)" },
+    }, ["command"]),
     // Async + spawn: the event loop stays responsive while the command runs, so
     // the spinner keeps spinning and Ctrl+C is heard. execSync would freeze
     // everything — the whole process, the UI, the signal handler — until it
     // returned. The AbortSignal lets the loop kill the child on interruption
-    // instead of waiting out the 30s timeout.
+    // instead of waiting out the timeout.
     run: (args, signal) => new Promise((resolve) => {
         const child = spawn(args.command, { shell: true, stdio: ["ignore", "pipe", "pipe"], env: childEnv() }); // shell:true → bash semantics
         let stdout = ""; // captured stdout
@@ -214,10 +225,12 @@ On error: failures return the error output — analyze it and try a different ap
             resolve(text); // hand the result back
         };
         // Hard timeout: SIGKILL the whole process group, never hang the agent.
+        const timeoutMs = bashTimeoutMs(args.timeout);
         const timer = setTimeout(() => {
             child.kill("SIGKILL");
-            done(fail(`Command timed out after ${BASH_TIMEOUT_MS / 1000}s and was killed.${stdout ? `\npartial stdout:\n${stdout.slice(0, 2000)}` : ""}`));
-        }, BASH_TIMEOUT_MS);
+            const hint = timeoutMs < BASH_MAX_TIMEOUT_MS ? ` If it needs longer, rerun with a larger timeout (max ${BASH_MAX_TIMEOUT_MS / 1000}) or use run_bash_background.` : " Use run_bash_background for anything this long.";
+            done(fail(`Command timed out after ${timeoutMs / 1000}s and was killed.${hint}${stdout ? `\npartial stdout:\n${stdout.slice(0, 2000)}` : ""}`));
+        }, timeoutMs);
         // Ctrl+C while a command runs: kill the child immediately.
         const onAbort = () => {
             child.kill("SIGKILL");
@@ -240,17 +253,19 @@ On error: failures return the error output — analyze it and try a different ap
     }),
 };
 // ============ run_bash_background (Day 37) ============
-// run_bash blocks and dies at its 30s watchdog — useless for anything truly
-// slow. This is its asynchronous twin: it spawns the command and returns a task
-// id IMMEDIATELY, so the agent keeps reasoning while the work happens. The loop
-// injects a <task_notification> when the command finishes (background.ts). Use
-// it for installs, builds, full test runs, or servers that never exit — exactly
-// the keywords that signal a slow operation. The command goes through the SAME
-// permission gate as run_bash (see permissions.ts), so the danger rules are
-// identical; only the blocking behavior differs.
+// run_bash blocks, and dies at its watchdog (2 minutes, 10 at most) — useless
+// for anything truly slow. This is its asynchronous twin: it spawns the command
+// and returns a task id IMMEDIATELY, so the agent keeps reasoning while the work
+// happens. The loop injects a <task_notification> when the command finishes
+// (background.ts); if the agent is idle by then, the frontend wakes it with one
+// (loop.ts, takeFinishedWork). Use it for installs, builds, full test runs, or
+// servers that never exit — exactly the keywords that signal a slow operation.
+// The command goes through the SAME permission gate as run_bash (see
+// permissions.ts), so the danger rules are identical; only the blocking
+// behavior differs.
 const runBashBackground = {
     definition: def("run_bash_background", `Run a slow bash command in the BACKGROUND and return immediately with a task id (e.g. bg_1) — do NOT wait for it.
-When to use: anything that would exceed run_bash's 30s limit or block you — installing dependencies (npm/pip install), builds (npm run build, cargo build, make), full test suites (pytest, npm test), deploys, or long-running servers (npm run dev) that never exit.
+When to use: anything that could outlast run_bash's timeout (10 minutes at most) or that you don't need to wait for — installing dependencies (npm/pip install), builds (npm run build, cargo build, make), full test suites (pytest, npm test), deploys, or long-running servers (npm run dev) that never exit.
 What you get back: just the task id. The command keeps running. When it finishes you'll receive a <task_notification> with its status and output tail — react to that. For a server or a job still running, poll it with bash_output.
 Boundaries & permissions are identical to run_bash (dangerous commands are still gated or denied). For quick commands use run_bash instead — waiting on a one-off background job wastes a turn.`, { command: { type: "string", description: "The bash command to run in the background" } }, ["command"]),
     // Fire-and-return: start the process, hand back the id. The output is captured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-from-zero",
-  "version": "0.37.0",
+  "version": "0.39.1",
   "type": "module",
   "bin": {
     "mini-agent": "dist/agent.js"