agent-from-zero 0.35.5 → 0.35.7

package/README.md

@@ -133,17 +133,47 @@ export MINI_AGENT_MODEL=gpt-4.1-mini
 
 所有数据都存在 `~/.config/mini-agent/sessions/` 下，只在本机，不经过网络。
 
+### 目标模式 /goal
+
+普通对话里，模型觉得做完了就停。`/goal` 把"做完没有"的判断从模型手里拿走：只要目标还没验证完成，模型每次停下，mini-agent 都会自动开下一轮让它接着干。
+
+```
+/goal 让 npm test 全部通过 --check "npm test"
+```
+
+- 模型只能用 `update_goal` 工具结束目标：`blocked` 表示需要你介入，`complete` 表示宣布完成。宣布完成要过两关：先跑你写的 `--check` 命令，退出码必须是 0，这条命令模型改不了；再由一次独立的模型调用对照最近的工具输出核对它的说法，拿不准就算没完成。
+- 不设费用上限，靠"有没有进展"兜底：一轮目标回合里一个工具都没调，立刻暂停；连续 3 轮工作区毫无变化，也暂停。按 Esc 同样会暂停。
+- 你随时可以插话，你的消息永远优先，处理完目标再继续。plan 模式下不会自动续跑。
+- `/goal` 查看状态，`/goal pause`、`/goal resume`、`/goal clear` 管理生命周期。
+- 目标存在会话文件里，`--resume` 或 `/resume` 回来以后，没做完的目标会接着跑。
+
 ### 非交互模式
 
 ```bash
 npx agent-from-zero -p "总结当前改动"
 cat error.log | npx agent-from-zero -p "分析这份日志"
 npx agent-from-zero -p "总结当前改动" --output-format json
+npx agent-from-zero -p "修一下这个 bug" --output-format stream-json
 ```
 
+`stream-json` 和 `claude -p --output-format stream-json` 同一格式：每行一个 JSON 事件，依次是 `system/init`、`assistant`（text / thinking / tool_use 块）、`user`（tool_result）、最后一行 `result`。为了兼容 Claude 的脚本，`--verbose` 也能传，不影响输出。
+
+### 让别的程序来驱动交互会话
+
+编排器（比如 orca）可以把交互式的 mini-agent 放在终端里跑，用 hooks 看它的状态、替你审批：
+
+- `MINI_AGENT_HOOKS_FILE=<文件>`：再加一层 hooks，格式和 settings.json 里的 `hooks` 一样，只对这一个进程生效，不改你的设置文件，也放宽不了权限。
+- `--session-id <id>`：这个 id 的会话存在就接着聊，不存在就用它开新会话。
+- 每个 hook 的输入都带 Claude Code 同名的字段：`session_id`、`transcript_path`（会话文件的绝对路径）、`cwd`、`hook_event_name`、这一轮的 `prompt_id`，工具事件另有 `tool_name`、`tool_input`。原来的字段照旧。
+- `PermissionRequest`：一次工具调用要问你之前先问 hook。输出 `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}` 就放行，`"behavior":"deny"` 加 `message` 或者退出码 2 就拒绝；没输出、超时、出错都算没决定，照常问你。规则要求必须由人决定的调用，hook 只能拒绝，放行还得你点。
+- `Notification`：审批菜单弹出来时触发，`notification_type` 是 `permission_prompt`。
+- `TurnEnd`：每一轮结束、会话存盘之后触发，被 Esc 打断或出错也会触发，带 `reason` 和 `last_assistant_message`。`Stop` 在存盘之前触发，打断时不触发，要知道"这一轮真的完了"就看 `TurnEnd`。
+
+输入框里 `Ctrl+U` 删除光标前的这一行，行首再按会并到上一行，连按可以清空多行草稿。
+
 ## 常用命令
 
-在会话里输入 `/help` 可以看到全部命令，比较常用的有：`/model` `/effort` `/plan` `/auto` `/skills` `/mcp` `/peers` `/memory` `/compact` `/diff` `/undo` `/resume` `/status` `/cost`。
+在会话里输入 `/help` 可以看到全部命令，比较常用的有：`/goal` `/model` `/effort` `/plan` `/auto` `/skills` `/mcp` `/peers` `/memory` `/compact` `/diff` `/undo` `/resume` `/status` `/cost`。
 
 ## 开发
 

package/dist/agent.js

@@ -5,7 +5,7 @@ import chalk from "chalk"; // terminal colors
 import readline from "node:readline/promises"; // promise-based terminal input
 import { createRequire } from "node:module"; // to read package.json for --version
 import { CONFIG, requireApiKey, saveGlobalSetting, PROJECT_SETTINGS_PATH, GLOBAL_SETTINGS_PATH } from "./config.js"; // provider-agnostic settings (.env loaded there)
-import { runLoop, TerminateReason, MAX_RETRIES, killAllSubAgents } from "./loop.js"; // the state machine
+import { runLoop, TerminateReason, MAX_RETRIES, killAllSubAgents, topLevelToolNames } from "./loop.js"; // the state machine
 import { buildSystemMessage, readProjectInstructions } from "./prompt.js"; // the constitution + optional AGENT.md project memory
 import { forgetFilesExcept, registerExternalTool } from "./tools.js"; // file-state reset + tool registration
 import { compactHistory, compactThreshold, contextPercent, contextWindowFor } from "./context.js"; // /compact, /model info, the ctx % in the status line
@@ -18,7 +18,7 @@ import { Judge } from "./judge.js"; // optional LLM permission classifier
 import { AutoMode } from "./auto.js";
 import { effortMenu, setEffort, selectedEffort } from "./effort.js";
 import { parseCli, applyCliOptions, readPrintPrompt, CliUsageError } from "./cli.js";
-import { reservePrintOutput, formatPrintResult } from "./print.js";
+import { reservePrintOutput, formatPrintResult, streamJsonInit, streamJsonMessage } from "./print.js";
 import { FollowUpQueue } from "./follow-up.js";
 import { reviewDebugCommand } from "./auto-debug.js";
 import { isPlanMode, setPlanMode } from "./permissions.js"; // plan mode: research-only until the user approves a plan
@@ -41,6 +41,7 @@ import { launchInk } from "./ink/launch.js"; // the Ink REPL — the default fro
 import { listBackground, hasRunningBackground, killAllBackground } from "./background.js"; // background tasks: /bg view + kill-on-exit (Day 37)
 import { listTeam, resetTeam } from "./team.js"; // agent teams: /team view + reset on clear/resume (Day 38)
 import { boardSummary, resetBoard } from "./board.js"; // task board: /tasks view + reset on clear/resume (Day 40)
+import { goalCommand, getGoal, restoreGoal, clearGoal, startGoalTurn, settleGoalTurn } from "./goal.js"; // /goal (Day 41): keep working until the goal is verified done
 import { loadDurableJobs, startCronScheduler, stopCronScheduler, listJobs } from "./cron.js"; // cron scheduler (Day s14)
 // package.json sits one level above both src/ (dev) and dist/ (built) — same path either way.
 const pkg = createRequire(import.meta.url)("../package.json");
@@ -51,6 +52,7 @@ const USAGE = `mini-agent ${pkg.version} — a Claude Code-style CLI agent (any
 Usage:
   mini-agent                 interactive session (REPL)
   mini-agent -r | --resume   continue the most recent session in this directory
+  mini-agent --session-id <id>  continue that session, or start a new one with that id
   mini-agent -p "<task>"     one-shot: run a single task, print the result, exit
   mini-agent exec "<task>"   alias for non-interactive print mode
   cat file | mini-agent -p "<task>"  append piped text to the prompt
@@ -59,7 +61,7 @@ Usage:
   --effort <level>           supported effort for this model, or default
   --permission-mode <mode>  default | auto | bypassPermissions (this run only)
   --dangerously-skip-permissions  alias for --permission-mode bypassPermissions
-  --output-format text|json  final answer or a JSON result (print mode only)
+  --output-format text|json|stream-json  final answer, a JSON result, or Claude-style NDJSON events (print mode only)
   mini-agent --auto          review tool actions automatically (Jev or your current vendor)
   mini-agent -v | --version  print the version
   mini-agent -h | --help     this text
@@ -108,6 +110,7 @@ const SESSION_HELP = `commands:
   /bg        list background tasks this session (run_bash_background) and their status
   /team      list the agent team (spawn_teammate): each teammate's role, status, and pending inbox
   /tasks     show the shared task board (create_task/claim_task): each task's status, owner, and dependencies
+  /goal <objective> [--check <cmd>]  keep working, turn after turn, until the goal is verified done (/goal alone shows it; pause | resume | clear)
   /cron      list scheduled cron jobs (schedule_cron) and their expressions
   /peers     list other mini-agent sessions on this machine (the agent can message them with send_message)
   /rename <name>  rename this session — the name other sessions use to reach it
@@ -152,7 +155,7 @@ async function main() {
     // MINI_AGENT_NO_INK=1 to use the readline REPL below instead (a simpler
     // reference front-end, and an escape hatch for terminals Ink misbehaves in).
     if (printTask === null && process.env.MINI_AGENT_NO_INK !== "1") {
-        await launchInk({ resume: cli.resume });
+        await launchInk({ resume: cli.resume, sessionId: cli.sessionId });
         return;
     }
     requireApiKey(); // fail fast with instructions, not a stack trace from inside the SDK
@@ -181,6 +184,8 @@ async function main() {
             sessionId = prev.id; // keep appending to the same session file
             initialTitle = prev.title;
             console.log(chalk.dim(`(resumed session ${prev.id} — ${prev.messages.length} messages; files must be re-read before editing)`));
+            if (printTask === null)
+                restoreGoal(prev.goal); // Day 41: the goal comes back with its session (print mode doesn't run goals)
         }
         else {
             console.log(chalk.dim("(no previous session here — starting fresh)")); // resume with nothing to resume is not an error
@@ -216,6 +221,15 @@ async function main() {
     // The optional LLM permission judge, built once if a settings file enabled it.
     const judge = CONFIG.judge.enabled && !CONFIG.bypassPermissions ? new Judge(client, CONFIG.judge.model || CONFIG.model) : undefined;
     const autoMode = new AutoMode(client, { projectInstructions });
+    // A restored ACTIVE goal (Day 41) starts running before the first prompt —
+    // say so loudly. Its /goal line was a genuine human request: auto mode re-learns it.
+    const restoredGoal = getGoal();
+    if (restoredGoal?.status === "active") {
+        autoMode.recordRequest(`/goal ${restoredGoal.objective}`);
+        console.log(chalk.cyan(`(◎ resumed an ACTIVE goal — the agent continues it now; Esc pauses: ${restoredGoal.objective.slice(0, 80)})`));
+    }
+    else if (restoredGoal)
+        console.log(chalk.dim(`(◎ goal restored [${restoredGoal.status}] — /goal to see it, /goal resume to continue)`));
     for (const notice of autoMode.startupNotices())
         console.log(chalk.dim(notice));
     if (judge)
@@ -264,7 +278,21 @@ async function main() {
         });
         messages.push({ role: "user", content: printTask }); // the single task
         autoMode.recordRequest(printTask);
+        // stream-json: an init line now (MCP is connected, so statuses are real),
+        // then every assistant turn / tool result as it enters history.
+        const streaming = cli.outputFormat === "stream-json";
+        const startedAt = Date.now();
+        let numTurns = 0;
+        if (streaming)
+            printOutput.write(streamJsonInit({ sessionId, model: CONFIG.model, tools: topLevelToolNames(),
+                mcpServers: listMcpServers().map((s) => ({ name: s.name, status: s.status })),
+                permissionMode: CONFIG.bypassPermissions ? "bypassPermissions" : CONFIG.autoMode.enabled ? "auto" : "default" }));
         const result = await runLoop(messages, {
+            onMessage: streaming ? (m) => {
+                if (m.role === "assistant")
+                    numTurns++;
+                printOutput.write(streamJsonMessage(sessionId, CONFIG.model, m));
+            } : undefined,
             client,
             model: CONFIG.model,
             quiet: true, // final result only; no spinner, reasoning or intermediate prose
@@ -289,6 +317,7 @@ async function main() {
         emit("agent_session_end"); // close the books
         printOutput.write(formatPrintResult(cli.outputFormat, {
             sessionId, model: CONFIG.model, effort: selectedEffort(CONFIG.model), result, usage: costMeter.snapshot(),
+            durationMs: Date.now() - startedAt, numTurns,
         }));
         if (result.reason !== TerminateReason.Done) {
             console.error(chalk.yellow(EXIT_NOTES[result.reason])); // human note on stderr
@@ -569,6 +598,13 @@ async function main() {
             console.log(await statusCommand(line, costMeter));
             return true;
         }
+        if (line === "/goal" || line.startsWith("/goal ")) {
+            const { message, request } = goalCommand(line.slice(5));
+            if (request)
+                autoMode.recordRequest(request); // the /goal you typed is the authorization; automatic goal turns never are
+            console.log(chalk.cyan(message)); // setting or resuming: the goal turns start before the next prompt
+            return true;
+        }
         if (line.startsWith("/skills "))
             line = `/skill ${line.slice(8).trim()}`;
         if (line === "/effort" || line.startsWith("/effort ")) {
@@ -662,6 +698,7 @@ async function main() {
                 return true;
             case "/clear":
                 autoMode.clearRequests();
+                clearGoal(); // the goal belonged to the old conversation (Day 41)
                 messages = [{ role: "system", content: systemMessage }]; // drop everything but the constitution
                 forgetFilesExcept([]); // the file read-state belongs to the conversation — clear it too
                 clearUndo(); // a fresh conversation should not undo the previous one's writes
@@ -805,6 +842,15 @@ async function main() {
                 resetTeam(); // a resumed conversation starts with no live team
                 resetBoard(); // ...and an empty task board (Day 40)
                 console.log(chalk.dim(`(resumed ${chosen.id} — ${chosen.messages.length} messages; files must be re-read before editing)`));
+                // Unlike the todos and the board, the goal comes BACK with its session (Day 41).
+                restoreGoal(chosen.goal);
+                const goal = getGoal();
+                if (goal?.status === "active") {
+                    autoMode.recordRequest(`/goal ${goal.objective}`);
+                    console.log(chalk.cyan(`◎ resumed an ACTIVE goal — the agent continues it now (Esc pauses): ${goal.objective.slice(0, 80)}`));
+                }
+                else if (goal)
+                    console.log(chalk.dim(`(◎ goal restored [${goal.status}] — /goal to see it, /goal resume to continue)`));
                 return true;
             }
             case "/diff": {
@@ -884,7 +930,46 @@ async function main() {
             }
         });
     }
+    // /goal (Day 41): the readline prompt blocks on your input, so it can't poll
+    // like the Ink REPL's idle processor. Instead, goal turns run HERE, before each
+    // prompt, one after another until the goal stops being active — verified
+    // complete, blocked, or paused by Esc / a failed turn / no progress. Plan mode
+    // never continues a goal: plan-only work can't move it forward.
+    const runGoalTurns = async () => {
+        for (let content = isPlanMode() ? null : startGoalTurn(); content; content = isPlanMode() ? null : startGoalTurn()) {
+            console.log(chalk.cyan(`\n◎ goal · turn ${getGoal().continuations}: ${getGoal().objective.slice(0, 70)}`));
+            messages.push({ role: "user", content }); // the goal turn (restates the objective — it survives compaction)
+            clearReasoning();
+            clearToolCalls();
+            running = true;
+            interrupted = false;
+            controller = new AbortController();
+            setSessionState("busy", CONFIG.model);
+            let reason = "error";
+            try {
+                const result = await runLoop(messages, {
+                    client, model: CONFIG.model, signal: controller.signal, isInterrupted: () => interrupted, confirm, askUser, followUps,
+                    onFollowUp: (text) => console.log(sentMessage(text)), subAgentModel: CONFIG.subAgentModel, judge, autoMode, canPrompt: !!process.stdin.isTTY,
+                });
+                reason = result.reason;
+                if (result.reason !== TerminateReason.Done)
+                    console.log(chalk.yellow(`\n⚠️ ${EXIT_NOTES[result.reason]}`));
+            }
+            catch (err) {
+                console.log(chalk.red(`[error] ${err.message}`));
+            }
+            finally {
+                running = false;
+                setSessionState("idle");
+            }
+            const goalNote = settleGoalTurn(reason, true);
+            if (goalNote)
+                console.log(chalk.yellow(goalNote));
+            saveSession(sessionId, CONFIG.model, messages, pendingTitle); // the goal's progress is saved turn by turn
+        }
+    };
     while (true) {
+        await runGoalTurns(); // an active /goal keeps going before you're asked for input
         // The input area: a blank line for breathing room, the "❯" you type on, then
         // a single status line (model · 📁 dir · 🌿 branch · ctx% · $ · time) pinned
         // BELOW the input. We dropped the old top/bottom horizontal rules — two bare
@@ -985,6 +1070,9 @@ async function main() {
         });
         running = false; // back at the prompt — Ctrl+C means "exit" again
         setSessionState("idle"); // other sessions see this one as free again
+        const goalNote = settleGoalTurn(result.reason, false); // Day 41: Esc on your own turn pauses an active goal too
+        if (goalNote)
+            console.log(chalk.yellow(goalNote));
         saveSession(sessionId, CONFIG.model, messages, pendingTitle); // snapshot after every turn — crash-safe by construction
         // Auto-extract memories (opt-in: settings.memory.autoExtract). A cheap pass
         // that saves durable facts — especially user corrections — so memory

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { parseArgs } from "node:util";
 import { CONFIG } from "./config.js";
 import { effortMenu, setEffort } from "./effort.js";
+import { isValidSessionId } from "./session.js"; // --session-id becomes a file name
 export class CliUsageError extends Error {
 }
 // -p is a mode, not a boundary after which flags turn into task text. Node's
@@ -18,9 +19,11 @@ export function parseCli(args) {
                 "permission-mode": { type: "string" },
                 "dangerously-skip-permissions": { type: "boolean" },
                 resume: { type: "boolean", short: "r" },
+                "session-id": { type: "string" },
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
                 "output-format": { type: "string" },
+                verbose: { type: "boolean" }, // accepted for Claude compatibility: its stream-json requires --verbose; ours always streams
             } });
     }
     catch (error) {
@@ -35,20 +38,25 @@ export function parseCli(args) {
     // Match Claude's precedence: the explicit skip flag wins over a mode flag.
     const permissionMode = values["dangerously-skip-permissions"] ? "bypassPermissions" : requestedMode;
     const outputFormat = values["output-format"] ?? "text";
-    if (outputFormat !== "text" && outputFormat !== "json")
-        throw new CliUsageError("--output-format must be text or json");
+    if (outputFormat !== "text" && outputFormat !== "json" && outputFormat !== "stream-json")
+        throw new CliUsageError("--output-format must be text, json, or stream-json");
     for (const flag of ["model", "effort", "prompt"]) {
         if (typeof values[flag] === "string" && !values[flag].trim())
             throw new CliUsageError(`--${flag} cannot be empty`);
     }
     if (values.prompt !== undefined && positionals.length)
         throw new CliUsageError("Use either a positional prompt or --prompt, not both");
+    const sessionId = typeof values["session-id"] === "string" ? values["session-id"] : undefined;
+    if (sessionId !== undefined && !isValidSessionId(sessionId))
+        throw new CliUsageError("--session-id may only contain letters, digits, '.', '_' and '-'");
+    if (sessionId !== undefined && values.resume)
+        throw new CliUsageError("Use either --resume or --session-id, not both");
     const prompt = typeof values.prompt === "string" ? values.prompt : positionals.join(" ");
     if (!print && (prompt || values["output-format"] !== undefined))
         throw new CliUsageError("Use -p / --print or exec with a prompt or --output-format");
     return { print, prompt, outputFormat, permissionMode, model: typeof values.model === "string" ? values.model : undefined,
         effort: typeof values.effort === "string" ? values.effort : undefined, auto: values.auto === true,
-        resume: values.resume === true, help: values.help === true, version: values.version === true };
+        resume: values.resume === true, sessionId, help: values.help === true, version: values.version === true };
 }
 // CLI overrides live only in this process; never save them to user settings.
 // Validate against the selected model/endpoint before any request is started.

package/dist/completion.js

@@ -19,6 +19,7 @@ export const COMMANDS = [
     { value: "/bg", description: "Show background tasks" },
     { value: "/team", description: "Show teammates and status" },
     { value: "/tasks", description: "Show the shared task board" },
+    { value: "/goal", description: "Keep working until a goal is verified done", children: true },
     { value: "/cron", description: "Show scheduled jobs" },
     { value: "/peers", description: "Talk to another mini-agent session, or find its window" },
     { value: "/rename", description: "Rename this session for other sessions", children: true },

package/dist/config.js

@@ -40,6 +40,12 @@ function readSettings(p) {
 }
 const globalSettings = readSettings(GLOBAL_SETTINGS_PATH); // the user's defaults
 const projectSettings = readSettings(PROJECT_SETTINGS_PATH); // this project's rules
+// A third, per-process layer of HOOKS only: MINI_AGENT_HOOKS_FILE points at a
+// settings-shaped file ({"hooks": {...}}) whose hooks join the other two. It
+// lets a program that launches the agent (an orchestrator such as orca) watch
+// and steer this one process without editing the user's settings. Only hooks
+// are read from it — it cannot loosen permissions.
+const processHooks = process.env.MINI_AGENT_HOOKS_FILE ? readSettings(process.env.MINI_AGENT_HOOKS_FILE).hooks : undefined;
 // Re-read ONLY the mcpServers map from both layers, mid-session (the MCP hot
 // reload in mcp.ts). Unlike startup, a file that won't parse is NOT fatal here:
 // an editor saving in two steps can leave half-written JSON for a moment, and
@@ -110,7 +116,7 @@ export const CONFIG = {
     // a generic union so adding a new event needs no edit here.
     hooks: (() => {
         const merged = {};
-        for (const src of [globalSettings.hooks, projectSettings.hooks]) {
+        for (const src of [globalSettings.hooks, projectSettings.hooks, processHooks]) {
             for (const [event, defs] of Object.entries(src ?? {}))
                 merged[event] = [...(merged[event] ?? []), ...(defs ?? [])];
         }