agent-from-zero 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# mini-agent
+
+用 DeepSeek API 从零手写一个类 Claude Code 的命令行 Agent,TypeScript 实现。
+
+10 天,每天一个 commit。**commit 历史就是课程目录**:`git log --oneline` 看大纲,`git checkout dayN` 拿到第 N 天收工时的完整代码。
+
+> 代码、注释、commit message 用英文——模型的工具调用主要在英文数据上训练,英文指令引导更稳,也方便国际读者;配套教程是中文。
+
+## 快速开始
+
+最简方式(npm 包,包名 `agent-from-zero`,装完命令叫 `mini-agent`):
+
+```bash
+echo 'DEEPSEEK_API_KEY=sk-你的key' > .env   # key 在 platform.deepseek.com 获取
+npx agent-from-zero
+```
+
+从源码跑:
+
+```bash
+git clone https://github.com/Michael-crazyman/mini-agent.git && cd mini-agent
+npm install
+cp .env.example .env   # 填入你的 DeepSeek API Key
+npm start              # 跑最新版
+npm run eval           # 10 道题的回归考试
+```
+
+## 换个模型用
+
+默认 DeepSeek,但任何 **OpenAI 兼容接口**都能跑,三个环境变量搞定:
+
+```bash
+MINI_AGENT_API_KEY=sk-...
+MINI_AGENT_BASE_URL=https://api.openai.com/v1   # OpenAI / Kimi / Qwen / GLM / OpenRouter / Ollama 均可
+MINI_AGENT_MODEL=gpt-4.1-mini
+```
+
+各家 base URL 见 [.env.example](.env.example)。两个注意:模型必须支持 function calling;窗口比 DeepSeek 小的话设 `MINI_AGENT_CONTEXT_WINDOW`(单位 token)。换完跑一遍 `npm run eval`——同样 10 道题,正好当模型横评。
+
+## 进度
+
+| Tag | 内容 |
+|---|---|
+| `day1` | ~50 行 raw tool-calling loop:一个工具、一个循环、两条保险 |
+| `day2` | 工具五件套(read/write/edit/search/bash):编辑前必须先读、old_string 唯一性、永不抛异常的 dispatch、四要素工具说明书 |
+| `day3` | 主循环状态机:错误分类、指数退避(带抖动)、双重重试预算、熔断器,8 种终态各配人话提示,Ctrl+C 体面退出 |
+| `day4` | 权限系统(allow/ask/deny):禁飞区硬拦(.git/.ssh/.env)、deny 永远赢(bypass 也压不过)、非交互 fail closed、bash 按输入定危险等级、秘密文件不进上下文 |
+| `day5` | 上下文管理:token 估算(字节法,宁多勿少)、80% 触发线、6 段结构化摘要(双保险禁工具)、文件恢复(最近 5 个,从磁盘重读)、主动+被动压缩、压缩熔断 |
+| `day6` | 多轮 REPL(行队列输入、/clear、Ctrl+C 三态语义)、system prompt 宪法(数字锚/反面禁令/防虚报)、AGENT.md 项目记忆、流式输出 + 双重看门狗(90s 断流/30s 只警告) |
+| `day7` | 子 agent(task 工具:独立上下文、一层分身不套娃、报告是材料不是结论、文件状态快照隔离)+ 最小 eval(10 道固定题、物证判分、8/10 及格线,`npm run eval`) |
+| `day8` | 封装发布:`bin` 入口 + tsc 构建,npx 一行启动(包名 `agent-from-zero`);内置 .env 加载;缺 key 人话报错 |
+| `day9` | 教程本身:11 章中文教程开源进 [docs/](docs/README.md) |
+
+## 📖 配套教程(免费开源)
+
+**[完整教程在 docs/ 目录](docs/README.md)**——11 章,每章对应一个 tag:为什么这么写、Claude Code 原版怎么做、你会踩的坑。每章五段结构:做完长什么样 → 跟着写 → 为什么 → 坑 → 小结。
+
+如果这个项目帮你搞懂了 agent,点个 ⭐ 就是最大的支持。

package/dist/agent.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import OpenAI from "openai"; // the API client
+import chalk from "chalk"; // terminal colors
+import readline from "node:readline/promises"; // promise-based terminal input
+import { CONFIG, requireApiKey } from "./config.js"; // provider-agnostic settings (.env loaded there)
+import { runLoop, TerminateReason, MAX_ROUNDS, MAX_RETRIES } from "./loop.js"; // the state machine
+import { buildSystemMessage } from "./prompt.js"; // the constitution + optional AGENT.md project memory
+import { forgetFilesExcept } from "./tools.js"; // to reset file state on /clear
+requireApiKey(); // fail fast with instructions, not a stack trace from inside the SDK
+// Build the API client once, for the whole session.
+const client = new OpenAI({
+    baseURL: CONFIG.baseURL, // DeepSeek by default; any OpenAI-compatible endpoint via MINI_AGENT_BASE_URL
+    apiKey: CONFIG.apiKey, // from .env or the shell
+    maxRetries: 0, // we own the retry policy — never let the SDK retry underneath us
+});
+// What we tell the user for every way a query can end. No raw stack traces.
+const EXIT_NOTES = {
+    [TerminateReason.RoundCap]: `Hit the ${MAX_ROUNDS}-round cap. The task may be too big for one go — try splitting it.`,
+    [TerminateReason.CircuitBreaker]: "3 API failures in a row — stopping here instead of burning money.",
+    [TerminateReason.RetryBudgetExhausted]: `${MAX_RETRIES} failed API calls in this query — giving up. Check your network and try again.`,
+    [TerminateReason.RateLimitBudgetExhausted]: "DeepSeek keeps rate-limiting us. Wait a minute, then try again.",
+    [TerminateReason.ContextTooLong]: "The conversation no longer fits the model's context window, and compaction could not shrink it enough. Use /clear to start fresh.",
+    [TerminateReason.CompactionFailed]: "Automatic compaction kept failing — stopping instead of looping. Use /clear to start fresh.",
+    [TerminateReason.FatalApiError]: "Unrecoverable API error — retrying would not help. Check your API key and request.",
+    [TerminateReason.UserInterrupt]: "Interrupted — back at the prompt.",
+};
+async function main() {
+    // The banner: who am I, which model and host am I on, and the three things worth knowing.
+    console.log(chalk.bold("mini-agent") +
+        chalk.dim(` — ${CONFIG.model} @ ${new URL(CONFIG.baseURL).host} | "exit" to quit · "/clear" to reset · Ctrl+C interrupts a running task`));
+    // ONE readline interface for the whole session — the task prompt and the
+    // permission prompts share it. Two interfaces on one stdin fight each other.
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    // Input plumbing: a line QUEUE instead of rl.question(). With piped stdin
+    // all lines arrive at once — question() would catch the first and lose the
+    // rest. The queue catches every line; asking pops one (or waits for one).
+    // Bonus: in a terminal, lines typed while a task runs queue up as the next
+    // commands instead of vanishing.
+    const pendingLines = []; // lines that arrived before anyone asked
+    const lineWaiters = []; // askers waiting for a line
+    let stdinDone = false; // has stdin ended?
+    rl.on("line", (line) => {
+        const waiter = lineWaiters.shift(); // is somebody waiting?
+        if (waiter)
+            waiter(line); // hand the line over directly
+        else
+            pendingLines.push(line); // nobody waiting — queue it
+    });
+    rl.on("close", () => {
+        stdinDone = true; // no more input will ever come
+        while (lineWaiters.length)
+            lineWaiters.shift()("exit"); // wake every waiter with a polite "exit"
+    });
+    // Get the next line of user input, showing a prompt if we have to wait.
+    const readUserLine = (prompt) => {
+        if (pendingLines.length)
+            return Promise.resolve(pendingLines.shift()); // typed-ahead (or piped) line — use it
+        if (stdinDone)
+            return Promise.resolve("exit"); // stdin is gone — leave politely
+        rl.setPrompt(prompt); // show the prompt the redraw-safe way
+        rl.prompt();
+        return new Promise((resolve) => lineWaiters.push(resolve)); // wait for the next line
+    };
+    // The system message is built ONCE per session: stable prefix = cache hits
+    // on every request. Nothing session-specific may sneak into it later.
+    const systemMessage = buildSystemMessage();
+    let messages = [{ role: "system", content: systemMessage }]; // the whole conversation lives here, across turns
+    // Per-task interrupt state. `running` decides what Ctrl+C means right now.
+    let running = false; // is a task currently executing?
+    let interrupted = false; // has the current task been interrupted?
+    let controller = new AbortController(); // aborts the in-flight API request
+    // Ctrl+C semantics, by state:
+    // - at the prompt: exit the session (standard REPL behavior)
+    // - while running: first press interrupts the task, second press force-quits
+    const onSigint = () => {
+        if (!running) {
+            console.log(); // end the prompt line cleanly
+            process.exit(0); // at the prompt, Ctrl+C = goodbye
+        }
+        if (interrupted)
+            process.exit(130); // second press while running: force quit (130 = killed by SIGINT)
+        interrupted = true; // first press: raise the flag...
+        controller.abort(); // ...and cancel the in-flight API request
+        console.log(chalk.yellow("\n(interrupt — finishing up, Ctrl+C again to force quit)")); // tell the user we heard them
+    };
+    process.on("SIGINT", onSigint); // covers non-TTY runs
+    rl.on("SIGINT", onSigint); // covers TTY raw mode, where readline swallows the signal itself
+    // Ask the human to approve a dangerous action — shares the session readline.
+    // Fail closed: in a non-interactive session nobody can say yes, so the
+    // answer is no. MINI_AGENT_AUTO_APPROVE=1 bypasses the QUESTION, but hard
+    // denies were already enforced in permissions.ts before we get here.
+    const confirm = async (question) => {
+        console.log(chalk.yellow(`\n⚠️ approval needed — ${question}`)); // always show what is being asked
+        if (process.env.MINI_AGENT_AUTO_APPROVE === "1") {
+            console.log(chalk.dim("  auto-approved (MINI_AGENT_AUTO_APPROVE=1)")); // bypass mode — say so out loud
+            return true; // approve without asking
+        }
+        if (!process.stdin.isTTY) {
+            console.log(chalk.dim("  non-interactive session — denied by default (fail closed)")); // nobody can answer — refuse
+            return false; // fail closed
+        }
+        const answer = await readUserLine("  Allow? [y/N] "); // wait for the human (shares the line queue)
+        return /^y(es)?$/i.test(answer.trim()); // anything but y/yes means no
+    };
+    // The session loop: ask → run → render → ask again. This is what makes it
+    // a conversation instead of a one-shot command.
+    while (true) {
+        const line = (await readUserLine(chalk.green("\n> "))).trim(); // next input, or "exit" on EOF
+        if (!line)
+            continue; // empty line — just re-prompt
+        if (line === "exit" || line === "quit")
+            break; // explicit goodbye
+        if (line === "/clear") {
+            messages = [{ role: "system", content: systemMessage }]; // drop everything but the constitution
+            forgetFilesExcept([]); // the file read-state belongs to the conversation — clear it too
+            console.log(chalk.dim("(history cleared)")); // confirm the reset
+            continue;
+        }
+        messages.push({ role: "user", content: line }); // the new turn joins the shared history
+        running = true; // Ctrl+C now means "interrupt the task"
+        interrupted = false; // fresh interrupt state for this task
+        controller = new AbortController(); // fresh abort signal for this task
+        const result = await runLoop(messages, {
+            client, // the configured API client
+            model: CONFIG.model, // whatever the user configured — must support function calling
+            signal: controller.signal, // for aborting requests
+            isInterrupted: () => interrupted, // for stopping between steps
+            confirm, // for permission prompts
+        });
+        running = false; // back at the prompt — Ctrl+C means "exit" again
+        // Done already streamed its answer to the screen; everything else gets a
+        // one-line human explanation. The session continues either way — except a
+        // fatal API error, which no amount of chatting will fix.
+        if (result.reason !== TerminateReason.Done) {
+            console.log(chalk.yellow(`\n⚠️ ${EXIT_NOTES[result.reason]}`)); // the human explanation
+            if (result.detail)
+                console.log(chalk.dim(`   ${result.detail.slice(0, 300)}`)); // raw detail for the curious
+            if (result.reason === TerminateReason.FatalApiError)
+                break; // a bad key won't fix itself mid-session
+        }
+    }
+    rl.close(); // release stdin
+    console.log(chalk.dim("bye.")); // a clean goodbye
+}
+main(); // kick everything off

package/dist/config.js

@@ -0,0 +1,41 @@
+import fs from "node:fs"; // for the minimal .env loader
+import chalk from "chalk"; // colored error output
+// Minimal .env loader: lets `npx mini-agent` work in any directory that has a
+// .env file — no dotenv dependency, no --env-file flag to remember.
+// Lives here (not in agent.ts) so the eval harness gets it for free too.
+try {
+    for (const line of fs.readFileSync(".env", "utf8").split("\n")) {
+        const m = line.match(/^([A-Za-z0-9_]+)=(.*)$/); // KEY=value, nothing fancier
+        if (m && !process.env[m[1]])
+            process.env[m[1]] = m[2]; // real env vars always win over the file
+    }
+}
+catch {
+    /* no .env here — the variables may come from the shell instead */
+}
+// Provider-agnostic configuration. mini-agent talks the OpenAI wire protocol,
+// so ANY compatible endpoint works — DeepSeek, OpenAI, Kimi, Qwen, GLM,
+// OpenRouter, a local Ollama... three variables and you're on a new model.
+//
+// Resolution order, most specific wins:
+//   MINI_AGENT_* (generic)  >  DEEPSEEK_* (back-compat)  >  DeepSeek defaults
+export const CONFIG = {
+    baseURL: process.env.MINI_AGENT_BASE_URL || // bring your own provider...
+        process.env.DEEPSEEK_BASE_URL || // ...or the original DeepSeek override (kept for back-compat and tests)
+        "https://api.deepseek.com", // the default provider
+    apiKey: process.env.MINI_AGENT_API_KEY || // generic key wins...
+        process.env.DEEPSEEK_API_KEY || // ...over the back-compat one
+        "", // empty = missing; requireApiKey() turns that into a helpful error
+    model: process.env.MINI_AGENT_MODEL || "deepseek-chat", // must support function calling
+};
+// No key, no point: fail with instructions instead of a stack trace later.
+export function requireApiKey() {
+    if (CONFIG.apiKey)
+        return; // all good
+    console.error(chalk.red("Missing API key."));
+    console.error("mini-agent works with any OpenAI-compatible provider. Either:");
+    console.error("  echo 'DEEPSEEK_API_KEY=sk-...' > .env              (DeepSeek, the default)");
+    console.error("  or set MINI_AGENT_API_KEY / MINI_AGENT_BASE_URL / MINI_AGENT_MODEL");
+    console.error("     to use OpenAI, Kimi, Qwen, GLM, OpenRouter, Ollama... (see .env.example)");
+    process.exit(1);
+}

package/dist/context.js

@@ -0,0 +1,106 @@
+import fs from "node:fs"; // re-reading files from disk during recovery
+import chalk from "chalk"; // status lines
+import { recentFiles, forgetFilesExcept } from "./tools.js"; // session file state (what was read/edited, and when)
+// ---- The context window ------------------------------------------------------
+// 1,048,565 came from a real API error message, not from documentation.
+// Trust what the API tells you over what you remember reading.
+export const CONTEXT_WINDOW = Number(process.env.MINI_AGENT_CONTEXT_WINDOW || 1_048_565); // overridable for other models
+// Compact well before the hard limit: estimation is approximate and the summary
+// itself needs room. 80% is deliberately conservative.
+export const COMPACT_AT = Number(process.env.MINI_AGENT_COMPACT_AT || Math.floor(CONTEXT_WINDOW * 0.8)); // overridable so tests can trigger compaction cheaply
+// How many times one query may compact / fail to compact before we give up.
+export const MAX_COMPACTIONS_PER_QUERY = 4; // a query that needs more is too big — stop, don't loop
+export const MAX_COMPACT_FAILURES = 3; // the compaction circuit breaker
+// ---- Token estimation ---------------------------------------------------------
+// Estimation is a safety mechanism, not an optimization: overestimating costs
+// one early compaction; underestimating costs a failed request. Always round up.
+export function estimateTokens(text, dense = false) {
+    const bytes = Buffer.byteLength(text, "utf8"); // Chinese/emoji take multiple bytes — count bytes, not chars
+    return Math.ceil(bytes / (dense ? 2 : 4)); // JSON-ish text packs ~2 bytes/token, prose/code ~4 — and we round UP
+}
+// Estimate the whole conversation, message by message.
+export function estimateHistoryTokens(messages) {
+    let total = 0; // running sum
+    for (const m of messages) {
+        const content = typeof m.content === "string" ? m.content : JSON.stringify(m.content ?? ""); // content can be structured — serialize it
+        const isDense = m.role === "tool"; // tool results are JSON-ish → denser tokens
+        total += estimateTokens(content, isDense) + 8; // +8 per message for role/formatting overhead
+        if ("tool_calls" in m && m.tool_calls)
+            total += estimateTokens(JSON.stringify(m.tool_calls), true); // count the call arguments too
+    }
+    return total;
+}
+// ---- The summary prompt ---------------------------------------------------------
+// Six numbered sections. Each exists because losing that piece of information
+// causes a specific, real failure mode after compaction (e.g. losing section 4
+// means the agent re-tries approaches that already failed).
+const SUMMARY_PROMPT = `You are about to lose your conversation history. Summarize it so the work can continue seamlessly in a fresh context.
+CRITICAL: Respond with TEXT ONLY. Do NOT call any tools. Tool calls will be REJECTED and will waste your only turn.
+
+Write exactly these 6 sections:
+1. Primary request and intent — what the user originally asked for, as precisely as possible
+2. Key technical context — languages, paths, commands, constraints that matter
+3. Files read or edited — exact paths, and what was changed in each
+4. Errors and fixes — every error hit so far and how it was (or was not) resolved
+5. Current state — what has just been done, what is in progress
+6. Next step — the single most likely next action
+
+CRITICAL: TEXT ONLY. No tool calls.`;
+// ---- Post-compaction file recovery ------------------------------------------------
+const RECOVER_MAX_FILES = 5; // restore at most this many recently-used files
+const RECOVER_FILE_CHARS = 4000; // per-file cap
+const RECOVER_TOTAL_CHARS = 16000; // total cap across all recovered files
+// Compaction may forget the conversation, but it must not forget which files
+// were being worked on. Restore the most recent ones — re-read FROM DISK,
+// never from memory: another process may have changed them since we last looked.
+export function recoverFileState() {
+    const candidates = recentFiles(RECOVER_MAX_FILES); // most recently touched first
+    const blocks = []; // formatted file blocks for the model
+    const recovered = []; // paths that actually made it in
+    let total = 0; // chars used so far
+    for (const p of candidates) {
+        if (!fs.existsSync(p))
+            continue; // the file may have been deleted — trust the disk
+        const content = fs.readFileSync(p, "utf8").slice(0, RECOVER_FILE_CHARS); // fresh from disk, capped
+        if (total + content.length > RECOVER_TOTAL_CHARS)
+            break; // budget exhausted — stop here
+        total += content.length; // account for it
+        recovered.push(p); // this one made it in
+        blocks.push(`--- ${p} (re-read from disk, may be truncated) ---\n${content}`); // format the block
+    }
+    forgetFilesExcept(recovered); // files NOT recovered must be re-read before any future edit
+    if (!blocks.length)
+        return null; // nothing worth recovering
+    return `[Recovered file state after compaction — most recently used files, re-read fresh from disk:]\n\n${blocks.join("\n\n")}`;
+}
+// ---- Compaction itself -----------------------------------------------------------
+// Replace the whole history with a structured summary + recovered file state.
+// Throws on failure — the loop decides what a failure means.
+export async function compactHistory(messages, // the history, mutated in place
+client, // the same client the loop uses
+model, // the same model summarizes its own conversation
+signal) {
+    const before = estimateHistoryTokens(messages); // for the log line
+    console.log(chalk.magenta(`📦 compacting context (~${before} tokens)...`)); // automatic behavior must be visible
+    const res = await client.chat.completions.create({
+        model, // same model — no need for a fancier one to summarize
+        messages: [...messages, { role: "user", content: SUMMARY_PROMPT }], // full history + the summary instruction
+        // Deliberately NO `tools` parameter: with no tools declared, the API
+        // cannot accept a tool call — that is the hard guarantee. The CRITICAL
+        // lines in the prompt are the soft second layer of the same defense.
+    }, { signal });
+    const summary = res.choices[0].message.content ?? ""; // the structured summary text
+    if (!summary.trim())
+        throw new Error("compaction returned an empty summary"); // empty summary = failed compaction
+    // The constitution survives compaction: keep the leading system message and
+    // drop everything else. Losing the system prompt would silently change the
+    // agent's behavior mid-session.
+    const system = messages[0]?.role === "system" ? [messages[0]] : []; // there is at most one, at index 0
+    messages.length = 0; // drop the old history entirely
+    messages.push(...system); // the constitution goes back first
+    messages.push({ role: "user", content: `[Context was compacted. Summary of the conversation so far:]\n\n${summary}` }); // the summary becomes the new history
+    const recoveredNote = recoverFileState(); // restore working-file contents from disk
+    if (recoveredNote)
+        messages.push({ role: "user", content: recoveredNote }); // attach as a second message
+    console.log(chalk.magenta(`📦 compacted: ~${before} → ~${estimateHistoryTokens(messages)} tokens`)); // report the result
+}

package/dist/errors.js

@@ -0,0 +1,53 @@
+import OpenAI from "openai"; // imported for its typed error classes (APIError and friends)
+// Every failure gets a named kind, because every kind has a different recovery
+// strategy and a different retry budget. "Error rate is up" takes hours to
+// debug; "rate_limited jumped from 0 to 5%" takes minutes.
+export var ApiErrorKind;
+(function (ApiErrorKind) {
+    ApiErrorKind["Network"] = "network";
+    ApiErrorKind["Timeout"] = "timeout";
+    ApiErrorKind["RateLimited"] = "rate_limited";
+    ApiErrorKind["ServerError"] = "server_error";
+    ApiErrorKind["ContextTooLong"] = "context_too_long";
+    ApiErrorKind["AuthFailed"] = "auth_failed";
+    ApiErrorKind["BadRequest"] = "bad_request";
+    ApiErrorKind["Aborted"] = "aborted";
+    ApiErrorKind["Unknown"] = "unknown";
+})(ApiErrorKind || (ApiErrorKind = {}));
+// Providers phrase "your input is too big" in many ways — match loosely.
+const CONTEXT_TOO_LONG_RE = /context.*length|maximum.*(context|length|tokens)|too (long|large)|exceed/i;
+// Translate whatever the SDK throws into exactly one ClassifiedError.
+export function classifyError(err) {
+    const message = err instanceof Error ? err.message : String(err); // normalize: not everything thrown is an Error
+    // User cancellation. The SDK has a dedicated class for it, but an aborted
+    // fetch can also surface as a plain Error named "AbortError" — catch both.
+    if (err instanceof OpenAI.APIUserAbortError || (err instanceof Error && err.name === "AbortError")) {
+        return { kind: ApiErrorKind.Aborted, retryable: false, message }; // not an error to recover from
+    }
+    // Timeout is checked before Network because it is a subclass of it.
+    if (err instanceof OpenAI.APIConnectionTimeoutError) {
+        return { kind: ApiErrorKind.Timeout, retryable: true, message }; // slow network — try again
+    }
+    // Could not reach the server at all (DNS, connection refused, reset...).
+    if (err instanceof OpenAI.APIConnectionError) {
+        return { kind: ApiErrorKind.Network, retryable: true, message }; // transient — try again
+    }
+    // The server answered with an error — classify by HTTP status code.
+    if (err instanceof OpenAI.APIError) {
+        const status = err.status ?? 0; // some APIError instances carry no status — treat as 0
+        if (status === 429)
+            return { kind: ApiErrorKind.RateLimited, retryable: true, message }; // server says: back off
+        if (status === 401 || status === 403)
+            return { kind: ApiErrorKind.AuthFailed, retryable: false, message }; // bad key — retries are useless
+        if (status === 400 && CONTEXT_TOO_LONG_RE.test(message)) {
+            return { kind: ApiErrorKind.ContextTooLong, retryable: false, message }; // needs compaction, not retries
+        }
+        if (status >= 500)
+            return { kind: ApiErrorKind.ServerError, retryable: true, message }; // their side broke — retry
+        if (status >= 400)
+            return { kind: ApiErrorKind.BadRequest, retryable: false, message }; // our request is wrong — don't
+    }
+    // Default for the unknown: retry, but it still consumes the budgets —
+    // an unknown error that keeps happening will trip the circuit breaker.
+    return { kind: ApiErrorKind.Unknown, retryable: true, message };
+}

package/dist/loop.js

@@ -0,0 +1,311 @@
+import chalk from "chalk"; // terminal colors for status lines
+import ora from "ora"; // the "thinking..." spinner while waiting for the first token
+import { toolDefinitions, dispatch, snapshotFileState, restoreFileState } from "./tools.js"; // the tool manuals + the executor + file-state isolation
+import { classifyError, ApiErrorKind } from "./errors.js"; // failure taxonomy
+import { checkPermission } from "./permissions.js"; // the allow/ask/deny gate
+import { estimateHistoryTokens, compactHistory, COMPACT_AT, MAX_COMPACTIONS_PER_QUERY, MAX_COMPACT_FAILURES } from "./context.js"; // context management
+import { SUB_AGENT_PROMPT } from "./prompt.js"; // the sub-agent's own constitution
+export const MAX_ROUNDS = 15; // model→tool round cap per query
+export const MAX_RETRIES = 10; // total failed API calls per query, across all rounds
+export const MAX_RATE_LIMIT_RETRIES = 3; // 429s get their own, much smaller budget
+export const MAX_CONSECUTIVE_FAILURES = 3; // the circuit breaker
+const BACKOFF_BASE_MS = 500; // first retry waits ~this long
+const BACKOFF_CAP_MS = 15_000; // no single wait longer than this
+const IDLE_TIMEOUT_MS = 90_000; // no stream events AT ALL for this long → the stream is dead, cut it
+const STALL_WARN_MS = 30_000; // events arriving slowly → log only. Slow is not dead — cutting a live stream wastes every token already paid for
+// A query has many ways to die. Name every one of them — each gets its own
+// user-facing explanation and exit code, instead of a generic "error".
+export var TerminateReason;
+(function (TerminateReason) {
+    TerminateReason["Done"] = "done";
+    TerminateReason["RoundCap"] = "round_cap";
+    TerminateReason["CircuitBreaker"] = "circuit_breaker";
+    TerminateReason["RetryBudgetExhausted"] = "retry_budget_exhausted";
+    TerminateReason["RateLimitBudgetExhausted"] = "rate_limit_budget_exhausted";
+    TerminateReason["ContextTooLong"] = "context_too_long";
+    TerminateReason["CompactionFailed"] = "compaction_failed";
+    TerminateReason["FatalApiError"] = "fatal_api_error";
+    TerminateReason["UserInterrupt"] = "user_interrupt";
+})(TerminateReason || (TerminateReason = {}));
+// The task tool: the parent's handle on sub-agents. Defined here (not in
+// tools.ts) because running it needs the loop itself — it IS a loop.
+const taskTool = {
+    type: "function",
+    function: {
+        name: "task",
+        description: `Delegate one self-contained subtask to a sub-agent that works in a FRESH context.
+The sub-agent has the same tools (except task) but knows NOTHING about this conversation — put every detail it needs into the description.
+Use it for exploration that would flood your context: reading many files, broad searches, summarizing a directory.
+The sub-agent's report is INPUT MATERIAL, not verified truth — re-check key claims yourself before acting on them.
+On error: a failed sub-agent returns [sub-agent failed: reason] — retry with a clearer description, or do the work yourself.`,
+        parameters: {
+            type: "object",
+            properties: {
+                description: { type: "string", description: "The complete, self-contained task for the sub-agent" },
+            },
+            required: ["description"],
+        },
+    },
+};
+// Run one sub-agent: a fresh conversation, same tools minus task, same
+// permission gate, and the parent's file read-state protected by a snapshot.
+async function runSubAgent(description, opts) {
+    if (!opts.quiet)
+        console.log(chalk.blue(`  ⎿ sub-agent started: ${description.slice(0, 100)}`)); // show the delegation
+    const snapshot = snapshotFileState(); // what the sub-agent reads, the parent has NOT seen
+    try {
+        const subMessages = [
+            { role: "system", content: SUB_AGENT_PROMPT }, // its own, smaller constitution
+            { role: "user", content: description }, // the task is its entire world
+        ];
+        const result = await runLoop(subMessages, { ...opts, subAgent: true }); // recurse, flagged as sub-agent
+        if (result.reason === TerminateReason.Done && result.finalText?.trim()) {
+            // The framing matters: the parent must treat this as material to verify,
+            // not as conclusions to copy — the most common multi-agent failure mode.
+            return `Sub-agent report (INPUT MATERIAL — verify key claims before acting on them):\n${result.finalText}`;
+        }
+        return `[sub-agent failed: ${result.reason}]`; // any non-Done ending, compressed to one line
+    }
+    finally {
+        restoreFileState(snapshot); // the parent's read-before-edit state, exactly as it was
+        if (!opts.quiet)
+            console.log(chalk.blue("  ⎿ sub-agent done")); // close the bracket
+    }
+}
+// Exponential backoff with jitter: 500ms, 1s, 2s, ... ±25%, capped.
+// Without jitter, every client that failed at the same second retries at the
+// same second — a thundering herd against an already-struggling server.
+function backoffMs(consecutiveFailures) {
+    const base = Math.min(BACKOFF_BASE_MS * 2 ** (consecutiveFailures - 1), BACKOFF_CAP_MS); // grow exponentially, then cap
+    return Math.round(base * (1 + Math.random() * 0.25)); // add 0–25% random jitter
+}
+// Sleep in small slices so Ctrl+C never has to wait out a long backoff.
+async function interruptibleSleep(ms, isInterrupted) {
+    const SLICE = 200; // check for interruption every 200ms
+    for (let waited = 0; waited < ms && !isInterrupted(); waited += SLICE) {
+        await new Promise((r) => setTimeout(r, Math.min(SLICE, ms - waited))); // sleep one slice (or the remainder)
+    }
+}
+// One streaming model call: prints text as it arrives, assembles tool calls
+// from their deltas, and guards the stream with a two-level watchdog.
+async function streamModelCall(messages, // the full history to send
+opts) {
+    const idleAbort = new AbortController(); // the watchdog's own kill switch
+    const signal = AbortSignal.any([opts.signal, idleAbort.signal]); // either the user or the watchdog can abort
+    const spinner = opts.quiet
+        ? null // the eval harness wants silence
+        : ora({ text: opts.subAgent ? "sub-agent working..." : "thinking...", discardStdin: false }).start(); // discardStdin:false — ora would otherwise eat Ctrl+C
+    let lastEvent = Date.now(); // when did we last hear ANYTHING from the stream?
+    let stallWarned = false; // only warn once per quiet stretch
+    // The two-level watchdog, checked once per second:
+    // - idle (nothing at all for 90s) → cut the stream, let the retry layer handle it
+    // - stall (slow but alive for 30s) → log it and keep waiting
+    const watchdog = setInterval(() => {
+        const quietMs = Date.now() - lastEvent; // ms since the last event
+        if (quietMs > IDLE_TIMEOUT_MS)
+            idleAbort.abort(); // dead — cut it
+        else if (quietMs > STALL_WARN_MS && !stallWarned) {
+            stallWarned = true; // don't repeat the warning every second
+            console.log(chalk.dim(`  [watchdog] stream quiet for ${Math.round(quietMs / 1000)}s — still waiting (slow ≠ dead)`));
+        }
+    }, 1000);
+    try {
+        const stream = await opts.client.chat.completions.create(
+        // Sub-agents do NOT get the task tool: one level of delegation only.
+        // Nested spawning means orphan processes and debugging hell.
+        { model: opts.model, messages, tools: opts.subAgent ? toolDefinitions : [...toolDefinitions, taskTool], stream: true }, { signal });
+        let content = ""; // accumulated answer text
+        let printedPrefix = false; // have we printed the 🤖 prefix yet?
+        const calls = []; // tool calls under assembly, indexed by delta.index
+        for await (const chunk of stream) {
+            lastEvent = Date.now(); // feed the watchdog
+            stallWarned = false; // the stream spoke — reset the stall warning
+            const delta = chunk.choices[0]?.delta; // this chunk's increment
+            if (!delta)
+                continue; // keep-alive or usage chunk — nothing to do
+            if (delta.content) {
+                if (spinner?.isSpinning)
+                    spinner.stop(); // first token: replace the spinner with real output
+                if (!opts.quiet && !opts.subAgent) {
+                    // Only the top-level agent streams to the screen — a sub-agent's
+                    // inner monologue would be mistaken for the answer.
+                    if (!printedPrefix) {
+                        process.stdout.write("\n🤖 "); // prefix once, then stream raw
+                        printedPrefix = true;
+                    }
+                    process.stdout.write(delta.content); // print the token immediately — this IS the streaming UX
+                }
+                content += delta.content; // always keep it for the history
+            }
+            for (const tc of delta.tool_calls ?? []) {
+                if (spinner?.isSpinning)
+                    spinner.stop(); // tool call starting — spinner served its purpose
+                const slot = (calls[tc.index] ??= { id: "", name: "", args: "" }); // create the slot on first fragment
+                if (tc.id)
+                    slot.id = tc.id; // id arrives once
+                if (tc.function?.name)
+                    slot.name += tc.function.name; // name usually arrives whole; += is safe either way
+                if (tc.function?.arguments)
+                    slot.args += tc.function.arguments; // arguments stream in fragments — concatenate
+            }
+        }
+        if (printedPrefix)
+            process.stdout.write("\n"); // end the streamed line cleanly
+        return { content, toolCalls: calls.filter(Boolean) }; // sparse array → dense
+    }
+    finally {
+        clearInterval(watchdog); // always stop the timer
+        if (spinner?.isSpinning)
+            spinner.stop(); // and never leave a zombie spinner
+    }
+}
+// Execute one approved tool call. The task tool is special — it is not in the
+// registry because running it needs the loop itself (it IS a loop).
+async function execute(call, opts) {
+    if (call.name !== "task")
+        return dispatch(call.name, call.args); // ordinary tools go through the registry
+    if (opts.subAgent)
+        return "[error] Sub-agents cannot spawn sub-agents. Do the work yourself."; // one level of delegation only
+    let description = ""; // the sub-task text
+    try {
+        description = JSON.parse(call.args).description ?? ""; // arguments arrive as JSON
+    }
+    catch {
+        /* fall through to the error below */
+    }
+    if (!description)
+        return "[error] task requires a non-empty description argument.";
+    return runSubAgent(description, opts); // spawn the worker
+}
+// Run one compaction attempt and keep score. Returns true on success.
+// Every automatic behavior keeps a failure count — that is what lets the
+// caller stop a hot failure loop instead of compacting forever.
+async function tryCompact(messages, // history to compact (mutated in place)
+opts, // for client/model/signal
+compaction) {
+    try {
+        await compactHistory(messages, opts.client, opts.model, opts.signal); // do the actual work
+        compaction.count++; // one more successful compaction this query
+        compaction.failures = 0; // success resets the failure streak
+        return true;
+    }
+    catch {
+        compaction.failures++; // failed — count it against the breaker
+        return false;
+    }
+}
+// The agent main loop, as a state machine: every iteration either continues
+// for a named reason or terminates for a named reason — nothing implicit.
+export async function runLoop(messages, // conversation history (mutated in place)
+opts) {
+    // The loop's mutable state: budgets and counters, rewritten every iteration.
+    const attempts = { total: 0, rateLimited: 0, consecutive: 0 };
+    const compaction = { count: 0, failures: 0 }; // compaction score card for this query
+    for (let round = 1; round <= MAX_ROUNDS; round++) {
+        // One round = one successful model call + its tool results.
+        // The inner loop retries the model call until it succeeds or a budget dies.
+        while (true) {
+            if (opts.isInterrupted())
+                return { reason: TerminateReason.UserInterrupt }; // user asked us to stop — obey before spending money
+            // Proactive compaction: act BEFORE the API rejects us. Waiting for the
+            // hard limit means the failure already happened.
+            if (estimateHistoryTokens(messages) > COMPACT_AT) {
+                if (compaction.count >= MAX_COMPACTIONS_PER_QUERY)
+                    return { reason: TerminateReason.CompactionFailed, detail: `already compacted ${compaction.count}x this query — the task is too big for one session` };
+                const ok = await tryCompact(messages, opts, compaction); // shrink the history
+                if (!ok && compaction.failures >= MAX_COMPACT_FAILURES)
+                    return { reason: TerminateReason.CompactionFailed, detail: `${compaction.failures} consecutive compaction failures` }; // the compaction circuit breaker
+            }
+            let out; // the assembled reply for this round
+            try {
+                out = await streamModelCall(messages, opts); // streaming call with spinner + watchdog
+            }
+            catch (err) {
+                // Interrupt first: an aborted request can surface as all kinds of
+                // errors, and none of them deserve a retry line.
+                if (opts.isInterrupted())
+                    return { reason: TerminateReason.UserInterrupt };
+                let e = classifyError(err); // turn the raw exception into a named kind
+                if (e.kind === ApiErrorKind.Aborted) {
+                    // The user did NOT press Ctrl+C (checked above), so this abort came
+                    // from the idle watchdog — treat it as a retryable timeout.
+                    e = { kind: ApiErrorKind.Timeout, retryable: true, message: "stream went silent for 90s — cut by the idle watchdog" };
+                }
+                if (e.kind === ApiErrorKind.ContextTooLong) {
+                    // Reactive compaction: the API just told us we're too big — our
+                    // estimate was wrong. Compact and retry instead of giving up.
+                    if (compaction.count < MAX_COMPACTIONS_PER_QUERY && (await tryCompact(messages, opts, compaction)))
+                        continue; // history is smaller now — retry the same round
+                    return { reason: TerminateReason.ContextTooLong, detail: e.message }; // compaction could not save us
+                }
+                if (!e.retryable)
+                    return { reason: TerminateReason.FatalApiError, detail: `${e.kind}: ${e.message}` }; // bad key etc. — stop now
+                attempts.total++; // every failure consumes the overall budget
+                attempts.consecutive++; // ...and the breaker counter
+                if (e.kind === ApiErrorKind.RateLimited)
+                    attempts.rateLimited++; // 429s also consume their own budget
+                // Order matters: the breaker fires first (hot failure loop), then the
+                // specific 429 budget, then the overall budget.
+                if (attempts.consecutive >= MAX_CONSECUTIVE_FAILURES)
+                    return { reason: TerminateReason.CircuitBreaker, detail: `${e.kind}: ${e.message}` };
+                if (attempts.rateLimited >= MAX_RATE_LIMIT_RETRIES)
+                    return { reason: TerminateReason.RateLimitBudgetExhausted, detail: e.message };
+                if (attempts.total >= MAX_RETRIES)
+                    return { reason: TerminateReason.RetryBudgetExhausted, detail: `${e.kind}: ${e.message}` };
+                const wait = backoffMs(attempts.consecutive); // how long to back off this time
+                console.log(chalk.dim(`  [retry] ${e.kind} — attempt ${attempts.total}/${MAX_RETRIES}, waiting ${wait}ms`)); // retries must be visible, or the app just looks frozen
+                await interruptibleSleep(wait, opts.isInterrupted); // wait, but stay responsive to Ctrl+C
+                continue; // retry the same round
+            }
+            // An aborted stream does not always throw — sometimes it just ends
+            // early and looks like success. Check the flag explicitly, and keep the
+            // partial text in history (clearly marked) so the next turn makes sense.
+            if (opts.isInterrupted()) {
+                if (out.content)
+                    messages.push({ role: "assistant", content: out.content + "\n[interrupted by user]" }); // text only — partial tool calls must NOT go in (they would need paired results)
+                return { reason: TerminateReason.UserInterrupt };
+            }
+            attempts.consecutive = 0; // success resets the breaker — but never the total budget
+            // Rebuild the assistant message from the assembled stream and add it to
+            // history — tool results must stay paired with their calls.
+            messages.push({
+                role: "assistant", // the model's turn
+                content: out.content || null, // null when the turn was tool calls only
+                ...(out.toolCalls.length
+                    ? { tool_calls: out.toolCalls.map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: c.args } })) }
+                    : {}), // omit the field entirely when there were no calls
+            });
+            if (!out.toolCalls.length) {
+                return { reason: TerminateReason.Done, finalText: out.content }; // no tool calls = final answer (already streamed to the screen)
+            }
+            // Execute every tool call, each behind the permission gate.
+            for (const call of out.toolCalls) {
+                const indent = opts.subAgent ? chalk.blue("  ⎿ ") : ""; // sub-agent activity is visually nested
+                if (!opts.quiet)
+                    console.log(indent + chalk.cyan(`🔧 ${call.name}`) + chalk.dim(` ${call.args.slice(0, 120)}`)); // show what the model wants to do
+                // The permission gate sits between the model's intent and execution.
+                const v = checkPermission(call.name, call.args);
+                let content; // what goes back to the model as the tool result
+                if (v.decision === "deny") {
+                    if (!opts.quiet)
+                        console.log(chalk.red(`  ⛔ denied: ${v.reason}`)); // tell the user we blocked it
+                    content = `[permission] Denied: ${v.reason}. This is a hard rule — do not try to work around it; pick a different approach or ask the user.`; // teach the model the boundary
+                }
+                else if (v.decision === "ask") {
+                    const ok = await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`); // pause and ask the human
+                    if (!ok && !opts.quiet)
+                        console.log(chalk.yellow("  ✋ declined")); // make the refusal visible
+                    content = ok
+                        ? await execute(call, opts) // approved — actually run it
+                        : `[permission] The user declined this action. Ask them how to proceed, or choose a safer alternative.`; // declined — tell the model
+                }
+                else {
+                    content = await execute(call, opts); // allow — run without ceremony
+                }
+                messages.push({ role: "tool", tool_call_id: call.id, content }); // feed the result back, paired by id
+            }
+            break; // round complete, move to the next one
+        }
+    }
+    return { reason: TerminateReason.RoundCap }; // ran out of rounds before a final answer
+}

package/dist/permissions.js

@@ -0,0 +1,106 @@
+import path from "node:path"; // used to resolve and split file paths
+// ---- 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.
+const NO_FLY_DIRS = new Set([".git", ".ssh", ".claude"]); // directory names that must never be written into
+const NO_FLY_FILES = new Set([".env", ".bashrc", ".zshrc", ".gitconfig", ".mcp.json"]); // file names that must never be written
+// Files whose CONTENT must never enter the model's context: once a secret is
+// in the conversation, it is in every later API request (and maybe in logs).
+const SECRET_FILE_RE = /(^|\/)(\.env[^/]*|id_rsa[^/]*|[^/]+\.(pem|key))$/;
+// Does this path touch the no-fly zone? Returns the reason, or null if clean.
+function noFlyHit(p) {
+    const abs = path.resolve(p); // normalize to an absolute path first
+    for (const part of abs.split(path.sep)) {
+        // match whole path segments — ".github" must NOT be caught by ".git"
+        if (NO_FLY_DIRS.has(part))
+            return `${part}/ is a no-fly zone`;
+    }
+    if (NO_FLY_FILES.has(path.basename(abs)))
+        return `${path.basename(abs)} is a no-fly zone file`; // exact file-name match
+    return null; // not in the zone
+}
+// ---- Bash command analysis --------------------------------------------------
+// Input-aware safety: run_bash is not one tool, it is a thousand tools wearing
+// a coat. "ls" and "rm -rf" deserve different treatment, so we look at the input.
+// Hard stops. Not a question — these never run.
+const BASH_DENY = [
+    [/\brm\s+(-[a-zA-Z]+\s+)*['"]?(\/|~)['"]?(\s|$)/, "rm targeting / or ~ — catastrophic"], // rm -rf / and rm -rf ~
+    [/(^|[\s;&|/])\.git(\/|\s|$)/, "touches the .git directory"], // any command naming .git — the / in the prefix class catches absolute paths like /repo/.git
+    [/(^|[\s;&|/])\.env(\s|$|[;&|])/, ".env holds secrets"], // any command that names .env
+    [/(^|[\s;&|/])\.ssh(\/|\s|$)/, ".ssh holds credentials"], // any command that names .ssh — same / fix
+];
+// Dangerous but sometimes legitimate — stop and ask the human.
+const BASH_ASK = [
+    [/\brm\b.*-[a-zA-Z]*r/, "recursive delete"], // rm -r / -rf — deletes whole trees
+    [/\brm\b/, "deletes files"], // plain rm — still destructive
+    [/\bsudo\b/, "runs as root"], // privilege escalation
+    [/\bdrop\s+(table|database)\b/i, "destroys database objects"], // SQL drop
+    [/\b(curl|wget)\b[^|;&]*\|\s*(ba|z)?sh\b/, "pipes the internet into a shell"], // curl ... | sh
+    [/\bgit\s+push\b.*(--force|\s-f\b)/, "force-push rewrites remote history"], // git push --force
+    [/\bgit\s+(reset\s+--hard|clean\b)/, "discards local changes"], // git reset --hard / git clean
+    [/\bchmod\b/, "changes file permissions"], // permission changes
+];
+// 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
+// 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.
+    for (const [re, why] of BASH_DENY)
+        if (re.test(command))
+            return { decision: "deny", reason: why, summary };
+    for (const [re, why] of BASH_ASK)
+        if (re.test(command))
+            return { decision: "ask", reason: why, summary };
+    // Compound commands (&&, ;, |, $(), ``) are too hard to reason about — ask.
+    if (/[;&|]|\$\(|`/.test(command))
+        return { decision: "ask", reason: "compound command", summary };
+    const words = summary.split(/\s+/); // tokenize to inspect the first word
+    if (words[0] === "git" && GIT_READONLY.has(words[1] ?? ""))
+        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
+    // Fail closed: a command we don't recognize is a question for the human.
+    return { decision: "ask", reason: "unrecognized command", summary };
+}
+// ---- The single entry point ---------------------------------------------------
+// Called by the loop for EVERY tool call, before anything executes.
+export function checkPermission(toolName, argsJson) {
+    let args; // the parsed tool arguments
+    try {
+        args = JSON.parse(argsJson); // arguments arrive as a raw JSON string from the model
+    }
+    catch {
+        // Let dispatch produce the proper JSON error for the model.
+        return { decision: "allow", reason: "unparseable args", summary: toolName };
+    }
+    switch (toolName) {
+        case "search":
+            return { decision: "allow", reason: "read-only", summary: "search" }; // searching never mutates anything
+        case "task":
+            // 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 "read_file": {
+            const p = args.path ?? ""; // the file the model wants to read
+            if (SECRET_FILE_RE.test(path.resolve(p))) {
+                return { decision: "deny", reason: "secret files must never enter the model's context", summary: p }; // keys stay out of the conversation
+            }
+            return { decision: "allow", reason: "read-only", summary: p }; // normal reads are free
+        }
+        case "write_file":
+        case "edit_file": {
+            const p = args.path ?? ""; // the file the model wants to change
+            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
+            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
+        default:
+            // A tool we don't know gets the most suspicious treatment, not the least.
+            return { decision: "ask", reason: "unknown tool", summary: toolName };
+    }
+}

package/dist/prompt.js

@@ -0,0 +1,53 @@
+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
+// 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
+// the entire system prompt on every single request.
+//
+// Style notes, learned from Claude Code's own prompt:
+// - Numeric anchors ("under 150 words"), not adjectives ("be concise") —
+//   adjectives make the model guess a different size every time.
+// - Negative rules ("never add comments to code you did not change") — their
+//   boundaries are binary and checkable; positive virtues are not.
+// - The accuracy paragraph is False-Claim mitigation. The "don't be overly
+//   self-doubting" half is load-bearing: without it the model swings to the
+//   other extreme and hedges everything.
+export const SYSTEM_PROMPT = `You are mini-agent, a coding agent that works in the user's terminal.
+
+Behavior rules:
+- Use the dedicated tools for file work: read_file, edit_file, write_file, search. Use run_bash only for things that truly need execution.
+- 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.
+- 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.`;
+// The sub-agent constitution: a worker with a fresh context and one job.
+// Key line: its FINAL message is the entire deliverable — the parent sees
+// nothing else of what it did.
+export const SUB_AGENT_PROMPT = `You are a sub-agent: a worker spawned by a parent agent to complete one self-contained task.
+
+Rules:
+- You know nothing about the parent's conversation. Work only from the task description.
+- Use your tools to do the work. Verify what you claim — do not guess.
+- Your FINAL message is returned to the parent verbatim. Make it a compact, factual report: findings, exact paths, numbers, code snippets. No greetings, no questions back.
+- You cannot talk to the user. If the task cannot be completed, report precisely what is missing.`;
+// Project memory: an optional AGENT.md in the current directory — the
+// 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.
+export function buildSystemMessage() {
+    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}`;
+}

package/dist/raw-loop.js

@@ -0,0 +1,75 @@
+import OpenAI from "openai"; // the official OpenAI SDK — DeepSeek is compatible with it
+import { execSync } from "node:child_process"; // runs a shell command and waits for it to finish
+import readline from "node:readline/promises"; // promise-based terminal input (for the question prompt)
+// Create the API client. DeepSeek speaks the OpenAI wire protocol,
+// so the only DeepSeek-specific thing here is the base URL.
+const client = new OpenAI({
+    baseURL: "https://api.deepseek.com", // point the SDK at DeepSeek instead of OpenAI
+    apiKey: process.env.DEEPSEEK_API_KEY, // never hardcode keys — read from the environment
+});
+// Our first (and only) tool. This is NOT code the model runs — it is a
+// machine-readable manual telling the model that a tool called "run_bash"
+// exists and what arguments it takes.
+const tools = [
+    {
+        type: "function", // the only tool type the chat API supports
+        function: {
+            name: "run_bash", // the name the model will call us by
+            description: "Run a bash command on the user's machine and return its output.", // when/why to use it
+            parameters: {
+                type: "object", // arguments always arrive as one JSON object
+                properties: {
+                    command: { type: "string", description: "The bash command to run" }, // the single argument
+                },
+                required: ["command"], // the model must always provide it
+            },
+        },
+    },
+];
+// The real implementation of the tool — plain TypeScript, invoked by US
+// after the model asks for it. The model never executes anything itself.
+function runBash(command) {
+    console.log(`\n🔧 running: ${command}`); // show the user what is about to run
+    try {
+        const out = execSync(command, { encoding: "utf8", timeout: 30_000 }); // run it, 30s time limit
+        return out || "(command succeeded, no output)"; // the API rejects empty strings — always return something
+    }
+    catch (err) {
+        return `Command failed: ${err.message}`; // don't crash — feed the error back to the model
+    }
+}
+async function main() {
+    // Ask the user for a task, once, via stdin.
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); // wire up terminal I/O
+    const task = await rl.question("What should the AI do?\n> "); // block until the user answers
+    rl.close(); // release stdin so the process can exit cleanly later
+    // The conversation history. This array IS the model's entire memory —
+    // it re-reads the whole thing on every call and remembers nothing else.
+    const messages = [{ role: "user", content: task }];
+    // The essence of an agent is this loop: model → tool → model → … → final state.
+    // The hard cap is a safety net: never loop (and never burn money) forever.
+    for (let round = 1; round <= 10; round++) {
+        // One API call: send the full history plus the tool manual.
+        const res = await client.chat.completions.create({ model: "deepseek-chat", messages, tools });
+        const msg = res.choices[0].message; // the model's reply for this round
+        messages.push(msg); // the reply must go into history, or tool results would be orphaned
+        // No tool calls = the model considers the task done. That is the final state.
+        if (!msg.tool_calls?.length) {
+            console.log(`\n🤖 ${msg.content}`); // print the model's final answer
+            return; // normal exit
+        }
+        // Otherwise: execute every tool call and feed each result back.
+        for (const call of msg.tool_calls) {
+            if (call.type !== "function")
+                continue; // ignore non-function call types
+            const args = JSON.parse(call.function.arguments); // arguments arrive as a JSON string
+            messages.push({
+                role: "tool", // a special message role: "here is what your tool returned"
+                tool_call_id: call.id, // must match the call — the API enforces this pairing
+                content: runBash(args.command).slice(0, 4000), // crude cap so huge outputs don't blow up the context
+            });
+        }
+    }
+    console.log("\n⚠️ Hit the 10-round cap, stopping."); // loop guard: stop at the cap, tell the user why
+}
+main(); // kick everything off

package/dist/tools.js

@@ -0,0 +1,246 @@
+import fs from "node:fs"; // filesystem reads and writes
+import path from "node:path"; // path resolution and joining
+import { execSync } from "node:child_process"; // runs a shell command and waits for it
+// ============ 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
+// (possibly stale) memory and wrecks the file.
+// A Map instead of a Set since Day 5: the touch order ranks files for recovery
+// after compaction (most recently touched = most likely needed next).
+// A monotonic counter, not Date.now(): two reads in the same millisecond would
+// get identical wall-clock stamps and the ordering would be arbitrary.
+let touchCounter = 0; // increments on every read/write — strictly ordered
+const readFiles = new Map(); // absolute path → touch sequence number
+const TOOL_RESULT_LIMIT = 4000; // cap (chars) for a normal tool result entering the context
+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
+// Errors are not exceptions — they are text that tells the model what to do next.
+const fail = (msg) => `[error] ${msg}`;
+// Small helper to build a tool definition without repeating boilerplate.
+function def(name, // tool name the model calls
+description, // the manual: what / boundaries / preconditions / on error
+properties, // parameter schema
+required) {
+    return {
+        type: "function", // the only tool type the chat API supports
+        function: { name, description, parameters: { type: "object", properties, required } },
+    };
+}
+// ============ read_file ============
+const readFile = {
+    definition: def("read_file", `Read the full content of a text file.
+Boundaries: text files only; content beyond ${READ_LIMIT} chars is truncated; do not use it on binaries like images.
+Precondition: before editing a file (edit_file) or overwriting an existing one (write_file), you MUST read it with this tool first.
+On error: a missing file returns an error — check the path and retry.
+ALWAYS use this tool to read files. NEVER run cat/head/tail via run_bash.`, { path: { type: "string", description: "File path (absolute or relative)" } }, ["path"]),
+    run: (args) => {
+        const p = path.resolve(args.path); // normalize to an absolute path
+        if (!fs.existsSync(p))
+            return fail(`File not found: ${p}. Check the path — you can locate files with search.`); // wrong path → tell the model how to find it
+        if (!fs.statSync(p).isFile())
+            return fail(`${p} is a directory, not a file.`); // directories are not readable
+        const content = fs.readFileSync(p, "utf8"); // read the whole file as text
+        readFiles.set(p, ++touchCounter); // remember: this session has read this file (unlocks edit/overwrite)
+        if (content.length > READ_LIMIT) {
+            return content.slice(0, READ_LIMIT) + `\n... (file is ${content.length} chars, truncated)`; // cap huge files, but say so
+        }
+        return content || "(empty file)"; // the API rejects empty strings — always return something
+    },
+};
+// ============ write_file ============
+const writeFile = {
+    definition: def("write_file", `Create a new file, or fully overwrite an existing one.
+Boundaries: the whole file is replaced by content; to change a small part of a file use edit_file instead — do not rewrite whole files.
+Precondition: overwriting an existing file requires reading it with read_file first. Writes may require user approval.
+On error: follow the error message — read the file first, then retry.`, {
+        path: { type: "string", description: "File path; parent directories are created automatically" },
+        content: { type: "string", description: "The complete new content of the file" },
+    }, ["path", "content"]),
+    run: (args) => {
+        const p = path.resolve(args.path); // normalize to an absolute path
+        if (fs.existsSync(p) && !readFiles.has(p)) {
+            return fail(`${p} already exists but you have not read it. Use read_file to check its current content before overwriting.`); // no blind overwrites
+        }
+        fs.mkdirSync(path.dirname(p), { recursive: true }); // create parent directories as needed
+        fs.writeFileSync(p, args.content, "utf8"); // write the new content
+        readFiles.set(p, ++touchCounter); // you wrote it, so you know its content — counts as read
+        return `Wrote ${p} (${args.content.length} chars)`; // confirm with the size as a sanity check
+    },
+};
+// ============ edit_file ============
+const editFile = {
+    definition: def("edit_file", `Replace one exact string in a file: old_string → new_string.
+Boundaries: old_string must match the file content exactly (including whitespace and indentation) and must be unique in the file; if it is not unique, include a few surrounding lines as context.
+Precondition: you MUST have read the file with read_file first. Edits may require user approval.
+On error: "not found" means old_string does not match the file — re-read and copy it exactly; "not unique" means include more surrounding context.
+ALWAYS use this tool to edit files. NEVER use sed/awk or shell redirection via run_bash.`, {
+        path: { type: "string", description: "Path of the file to edit" },
+        old_string: { type: "string", description: "The exact text to replace (must be unique)" },
+        new_string: { type: "string", description: "The replacement text" },
+    }, ["path", "old_string", "new_string"]),
+    run: (args) => {
+        const p = path.resolve(args.path); // normalize to an absolute path
+        if (!fs.existsSync(p))
+            return fail(`File not found: ${p}`); // can't edit what isn't there
+        if (!readFiles.has(p)) {
+            return fail(`You have not read ${p} yet. Use read_file first and edit based on its real content.`); // the read-before-edit rule
+        }
+        if (args.old_string === args.new_string)
+            return fail(`old_string and new_string are identical — nothing to change.`); // pointless edit, don't waste a round
+        const content = fs.readFileSync(p, "utf8"); // current file content
+        const count = content.split(args.old_string).length - 1; // how many times old_string occurs
+        if (count === 0) {
+            return fail(`old_string not found in the file. It must match exactly (including whitespace and indentation) — re-read the file and copy it precisely.`); // model's memory is stale → re-read
+        }
+        if (count > 1) {
+            return fail(`old_string appears ${count} times — ambiguous. Include a few surrounding lines to make it unique.`); // refuse to guess which one
+        }
+        // Note: content.replace(old, newStr) would expand $& $' etc. in newStr as special
+        // replacement patterns — pass a function so the replacement is taken literally.
+        fs.writeFileSync(p, content.replace(args.old_string, () => args.new_string), "utf8"); // apply the single replacement
+        return `Edited ${p}: 1 replacement made.`; // confirm exactly what happened
+    },
+};
+// ============ search ============
+// Convert a shell-style glob (*.ts) into a regex for file-name filtering.
+function globToRegex(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*"); // escape regex chars, then * → .*
+    return new RegExp(`^${escaped}$`); // anchor so the whole name must match
+}
+// Recursively yield every file under dir, skipping junk and hidden entries.
+function* walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith("."))
+                yield* walk(path.join(dir, entry.name)); // recurse, but never into node_modules/.git/hidden dirs
+        }
+        else if (entry.isFile() && !entry.name.startsWith(".")) {
+            // dotfiles (.env and friends) often hold secrets — search never surfaces them
+            yield path.join(dir, entry.name);
+        }
+    }
+}
+const search = {
+    definition: def("search", `Search file contents under a directory with a regex. Returns a list of "file:line: content" matches.
+Boundaries: skips node_modules/.git/hidden dirs/binary files; returns at most ${SEARCH_MAX_MATCHES} matches; results are locations only — use read_file to see full content.
+On error: an invalid regex returns an error; on "no matches", loosen the pattern or widen the directory and retry.
+ALWAYS use this tool to search. NEVER run grep/rg/find via run_bash.`, {
+        pattern: { type: "string", description: "The regex to search for" },
+        path: { type: "string", description: "Directory to start from, defaults to the current directory" },
+        file_glob: { type: "string", description: "Only search files whose name matches, e.g. *.ts (optional)" },
+    }, ["pattern"]),
+    run: (args) => {
+        const dir = path.resolve(args.path || "."); // default to the current directory
+        if (!fs.existsSync(dir))
+            return fail(`Directory not found: ${dir}`); // bad starting point
+        let regex; // the compiled search pattern
+        try {
+            regex = new RegExp(args.pattern); // compile the model's pattern
+        }
+        catch (e) {
+            return fail(`Invalid regex: ${e.message}`); // bad pattern → tell the model to fix it
+        }
+        const nameFilter = args.file_glob ? globToRegex(args.file_glob) : null; // optional file-name filter
+        const matches = []; // accumulated "file:line: content" lines
+        for (const file of walk(dir)) {
+            if (nameFilter && !nameFilter.test(path.basename(file)))
+                continue; // skip files the glob excludes
+            if (fs.statSync(file).size > 1_000_000)
+                continue; // skip huge files (logs, bundles)
+            const text = fs.readFileSync(file, "utf8"); // read the candidate file
+            if (text.includes("\0"))
+                continue; // skip binaries (NUL byte = not text)
+            const lines = text.split("\n"); // search line by line
+            for (let i = 0; i < lines.length; i++) {
+                if (regex.test(lines[i])) {
+                    matches.push(`${path.relative(dir, file)}:${i + 1}: ${lines[i].trim()}`); // record location + the matching line
+                    if (matches.length >= SEARCH_MAX_MATCHES) {
+                        return matches.join("\n") + `\n... (hit the ${SEARCH_MAX_MATCHES}-match cap, narrow your pattern)`; // stop early, tell the model why
+                    }
+                }
+            }
+        }
+        return matches.length ? matches.join("\n") : "No matches. Loosen the pattern or try another directory."; // empty result still guides the next step
+    },
+};
+// ============ run_bash ============
+const runBash = {
+    definition: def("run_bash", `Run a bash command on the user's machine (30s timeout) and return its output.
+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"]),
+    run: (args) => {
+        try {
+            // stderr is piped (not inherited): it belongs in the tool result for the
+            // model to read, not splattered onto the user's terminal.
+            const out = execSync(args.command, { encoding: "utf8", timeout: 30_000, stdio: ["ignore", "pipe", "pipe"] });
+            return out || "(command succeeded, no output)"; // never return an empty string
+        }
+        catch (err) {
+            const e = err; // execSync attaches the captured stderr on failure
+            return fail(`Command failed: ${e.message}${e.stderr ? `\nstderr: ${e.stderr.slice(0, 1000)}` : ""}`); // failure becomes guidance, not a crash
+        }
+    },
+};
+// ============ Registry & dispatch ============
+// One place that knows every tool. Adding a tool = adding one entry here.
+export const tools = {
+    read_file: readFile,
+    write_file: writeFile,
+    edit_file: editFile,
+    search,
+    run_bash: runBash,
+};
+// The list of manuals sent to the model on every API call.
+export const toolDefinitions = Object.values(tools).map((t) => t.definition);
+// Single entry point: every failure becomes text fed back to the model.
+// It never throws — the main loop must never die because of a tool.
+export function dispatch(name, argsJson) {
+    const tool = tools[name]; // look the tool up by name
+    if (!tool)
+        return fail(`Unknown tool: ${name}. Available tools: ${Object.keys(tools).join(", ")}`); // model hallucinated a tool → list the real ones
+    let args; // the parsed arguments
+    try {
+        args = JSON.parse(argsJson); // arguments arrive as a raw JSON string
+    }
+    catch {
+        return fail(`Arguments are not valid JSON: ${argsJson.slice(0, 200)}`); // malformed JSON → show what we got
+    }
+    try {
+        return tool.run(args).slice(0, name === "read_file" ? READ_LIMIT + 100 : TOOL_RESULT_LIMIT); // run it, cap the result size
+    }
+    catch (err) {
+        return fail(`Tool crashed: ${err.message}`); // even a crashing tool becomes a readable result
+    }
+}
+// ============ File-state queries (used by compaction recovery) ============
+// The most recently touched files, newest first.
+export function recentFiles(limit) {
+    return [...readFiles.entries()] // [path, sequence] pairs
+        .sort((a, b) => b[1] - a[1]) // newest first
+        .slice(0, limit) // top N only
+        .map(([p]) => p); // just the paths
+}
+// Evict everything except the given paths. After compaction, a file the model
+// can no longer see must also lose its "already read" status — otherwise the
+// model could edit it based on content that is no longer in the conversation.
+export function forgetFilesExcept(keep) {
+    const keepSet = new Set(keep); // for O(1) lookup
+    for (const p of [...readFiles.keys()])
+        if (!keepSet.has(p))
+            readFiles.delete(p); // drop the rest
+}
+// Snapshot / restore the read-state around a sub-agent run. The sub-agent
+// shares this module's state, but what IT read was never seen by the parent's
+// conversation — restoring the snapshot keeps read-before-edit honest across
+// agent boundaries.
+export function snapshotFileState() {
+    return new Map(readFiles); // shallow copy is enough — values are numbers
+}
+export function restoreFileState(snapshot) {
+    readFiles.clear(); // drop whatever the sub-agent read or wrote
+    for (const [p, seq] of snapshot)
+        readFiles.set(p, seq); // bring back the parent's view
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "agent-from-zero",
+  "version": "0.1.0",
+  "description": "A Claude Code-style CLI agent built from scratch with the DeepSeek API — companion code for a 10-day tutorial",
+  "type": "module",
+  "bin": {
+    "mini-agent": "dist/agent.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "tsx --env-file=.env src/agent.ts",
+    "typecheck": "tsc --noEmit",
+    "eval": "tsx --env-file=.env eval/run.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=20.6"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "openai": "^6.42.0",
+    "ora": "^9.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}