teapot-coding-agent 0.22.13 → 0.23.0

package/README.md

@@ -4,6 +4,8 @@
 
 > Try it in 5 minutes → [Quick start](#-quick-start) · Details live in the [Reference](#-reference) section
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/akku1139/teapot)
+
 [日本語版はこちら](README.ja.md)
 
 ---
@@ -204,6 +206,33 @@ Lookup order: CLI arg → `$TEAPOT_CONFIG` → `~/.config/teapot-coding-agent/co
 
 </details>
 
+<details>
+<summary><b>Several model presets on one API key</b></summary>
+
+A provider entry is just `{ baseUrl, apiKey, model }`, so "one key, many
+models" is one entry per model — repeat the same `baseUrl`/`apiKey` and vary
+`model`. Each agent then names the preset it wants:
+
+```json
+{
+  "providers": {
+    "or-sonnet": { "baseUrl": "https://openrouter.ai/api/v1", "apiKey": "sk-or-...", "model": "anthropic/claude-sonnet-4" },
+    "or-opus":   { "baseUrl": "https://openrouter.ai/api/v1", "apiKey": "sk-or-...", "model": "anthropic/claude-opus-4" },
+    "or-haiku":  { "baseUrl": "https://openrouter.ai/api/v1", "apiKey": "sk-or-...", "model": "anthropic/claude-haiku-4" }
+  },
+  "defaultProvider": "or-sonnet",
+  "agents": [
+    { "id": "main", "workspace": "~/proj", "provider": "or-sonnet" },
+    { "id": "deep", "workspace": "~/proj", "provider": "or-opus" }
+  ]
+}
+```
+
+Switching an agent's model in the right panel never disturbs the others, and
+an agent may still pin its own `model` to override the preset's.
+
+</details>
+
 <details>
 <summary><b>Mixing providers</b></summary>
 

package/dist/agent/agent.js

@@ -11,6 +11,7 @@ import path from "node:path";
 import { EventLog, readEvents } from "../log/events.js";
 import { chat, chatStream } from "./llm.js";
 import { executeTool, toolSpecs, currentSkills, safeJoin, isContextOverflow, hasRunningBgShells } from "./tools.js";
+import { skillRootsFingerprint } from "./skills.js";
 import { bus } from "../bus.js";
 /**
  * SYSTEM_TEMPLATE must stay byte-identical across every request of a session:
@@ -21,7 +22,7 @@ import { bus } from "../bus.js";
  */
 const SYSTEM_TEMPLATE = `You are a coding agent working autonomously inside a workspace.
 
-Session state is not injected into prompts — fetch it with tools instead:
+Most session state is not injected into prompts — fetch it with tools instead:
 - get_goal() → current objective + status. Call at session start, after a
   compaction notice, or whenever you lose the thread.
 - set_goal(text) → change the objective itself (not routine updates).
@@ -35,10 +36,11 @@ Session state is not injected into prompts — fetch it with tools instead:
 - Log significant choices with record_decision(decision, rationale,
   alternatives?) — compaction forgets reasoning, decisions.md doesn't.
 - list_skills() / load_skill(name) / save_skill(...) → reusable playbooks.
-- AGENTS.md in the workspace root (optional) holds project knowledge — read it
-  with read_file at session start when present, keep it current.
 
 ## Rules
+- Project instructions from AGENTS.md (workspace root) are EMBEDDED in this
+  prompt below when present — read them here, don't re-read_file it. Keep the
+  file current by editing it when it goes stale.
 - Work step by step with tools. Verify results (run tests/builds) before claiming progress.
 - File changes — pick by scope: write_file (one new file / full rewrite) ·
   edit_file (exactly one small unique replacement) · apply_patch (several
@@ -179,10 +181,24 @@ export class Agent {
     }
     skillRoots;
     skillsCache = [];
-    /** Rescan skill roots (cheap: a readdir per root, done once per turn). */
+    /** fingerprint of the roots that produced skillsCache ("" = not scanned yet) */
+    skillsStamp = "";
+    /**
+     * Rescan skill roots — but only when something actually changed (#14).
+     * This used to run a readdir per root plus a read of every SKILL.md at the
+     * top of EVERY turn; the cache is only ever read by list_skills, so that
+     * was pure I/O on the hot path. A cheap stat fingerprint of the roots and
+     * their SKILL.md files gates the real scan, so a turn only pays when a
+     * skill was added, edited or removed (save_skill writes one, so a
+     * self-created skill still shows up on the very next turn).
+     */
     async refreshSkills() {
         try {
+            const stamp = await skillRootsFingerprint(this.skillRoots);
+            if (stamp === this.skillsStamp)
+                return; // unchanged → reuse the cache
             this.skillsCache = await currentSkills(this.toolCtx);
+            this.skillsStamp = stamp;
         }
         catch {
             /* keep previous cache */

package/dist/agent/skills.js

@@ -19,6 +19,53 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 export const SKILL_FILE = "SKILL.md";
+/**
+ * Cheap change-detector for a set of skill roots. Returns a stable string
+ * that changes whenever a root is added, removed, or modified — so callers
+ * can skip a full rescan (a readdir per root plus a read of every SKILL.md)
+ * on the overwhelmingly common "nothing changed" path.
+ *
+ * The fingerprint covers each root's own mtime/size AND the mtime/size of
+ * every SKILL.md one level down, because writing SKILL.md does not bump the
+ * parent directory's mtime. Helper scripts edited in place are covered by
+ * the SKILL.md stat only in aggregate; a rewritten SKILL.md always lands
+ * here too (saveSkill rewrites it), so bundled-file edits ride along with
+ * the next skill write rather than triggering their own rescan.
+ */
+export async function skillRootsFingerprint(roots) {
+    const parts = [];
+    for (const root of roots) {
+        parts.push(root.dir);
+        let st = null;
+        try {
+            st = await fs.stat(root.dir);
+        }
+        catch {
+            parts.push("-"); // root missing → no skills here (same as discoverSkills)
+            continue;
+        }
+        parts.push(`${st.mtimeMs}:${st.size}`);
+        let entries;
+        try {
+            entries = await fs.readdir(root.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || e.name.startsWith("."))
+                continue;
+            try {
+                const s = await fs.stat(path.join(root.dir, e.name, SKILL_FILE));
+                parts.push(`${e.name}=${s.mtimeMs}:${s.size}`);
+            }
+            catch {
+                parts.push(`${e.name}=none`);
+            }
+        }
+    }
+    return parts.join("|");
+}
 export function isValidSkillName(name) {
     return /^[a-z0-9][a-z0-9._-]{0,63}$/.test(name);
 }

package/dist/agent/tools.js

@@ -16,6 +16,38 @@ function clip(s, max) {
 async function readText(p) {
     return fs.readFile(p, "utf8");
 }
+/**
+ * Optimistic-concurrency guard (#5). The model reads a file, thinks, then
+ * writes — and in between, a sub-agent, a background job or the operator may
+ * have changed it. Anchored edits usually fail safe (old_text is gone, so the
+ * call errors), but two paths silently clobber work nobody looked at:
+ * `replace_all` rewrites every occurrence present NOW, including ones that
+ * appeared after the model formed its plan, and write_file/apply_patch replace
+ * whole files unconditionally.
+ *
+ * A caller that passes `base_content` (the bytes it actually read) therefore
+ * gets a refusal instead of a lost update — the same contract the web file
+ * editor already enforces (see api.ts PUT /file). The check is advisory by
+ * design: omitting the parameter keeps today's behaviour, so this can never
+ * break a working agent loop that does not use it.
+ */
+function staleGuard(pathArg, base, current) {
+    if (typeof base !== "string")
+        return null; // not supplied → no check
+    if (base === current)
+        return null; // unchanged → proceed
+    const rel = pathArg;
+    return {
+        ok: false,
+        result: `${rel} changed on disk since you read it — nothing was written.\n` +
+            `your base_content: ${base.length} bytes, on disk now: ${current === null ? "(deleted)" : `${current.length} bytes`}.\n` +
+            `Re-read ${rel}, redo the edit against the current content, and pass the fresh text as base_content.`,
+    };
+}
+/** Read the file for a guarded write, or null when it does not exist. */
+async function currentOrNull(p) {
+    return fs.readFile(p, "utf8").catch(() => null);
+}
 /** Resolve a path inside the workspace; reject escapes (incl. symlink targets).
  *  KNOWN LIMIT (review finding, accepted): the check-then-open pattern has a
  *  TOCTOU window — a symlink swapped in between safeJoin() and fs.open() could
@@ -83,14 +115,31 @@ function startBackgroundShell(cmd, ctx) {
     };
     child.stdout?.on("data", collect);
     child.stderr?.on("data", collect);
-    child.on("close", (code) => {
+    // "exit" (process gone) and "close" (all stdio drained) are DIFFERENT events.
+    // A backgrounded grandchild that inherits stdout — `npm run dev &`,
+    // `docker compose up &`, a script that forks a watcher — keeps the pipe open,
+    // so "close" can stay pending long after the shell itself is dead. Keying
+    // the exit state off "close" alone left such jobs marked running FOREVER:
+    // hasRunningBgShells() said yes, the auto-continue loop kept breaking out on
+    // "background job still running", and the agent sat in "running" with the
+    // job long dead and no notification ever delivered (#23).
+    //
+    // So: "exit" is authoritative for state and for the completion
+    // notification; "close" only means "output finally drained" and is used to
+    // capture the tail. The notify() helper keeps this exactly-once.
+    let exitNotified = false;
+    const notify = (code) => {
         sh.exited = true;
-        sh.code = code;
+        if (code !== null)
+            sh.code = code;
+        if (exitNotified)
+            return;
+        exitNotified = true;
         // tell the harness so the agent learns the outcome WITHOUT polling
         try {
             ctx.onBackgroundExit?.({
                 id,
-                code,
+                code: sh.code,
                 cmd,
                 durationMs: Date.now() - sh.startedAt,
                 outputTail: sh.out.slice(-2000),
@@ -99,7 +148,9 @@ function startBackgroundShell(cmd, ctx) {
         catch {
             /* notification is best-effort */
         }
-    });
+    };
+    child.on("exit", (code) => notify(code));
+    child.on("close", (code) => notify(code));
     map.set(id, sh);
     return id;
 }
@@ -511,15 +562,80 @@ async function applyPatch(patch, ctx) {
     catch (e) {
         return { ok: false, result: `patch validation failed: ${e.message}` };
     }
-    // phase 2 — commit
-    for (const w of writes) {
-        await fs.mkdir(path.dirname(w.abs), { recursive: true });
-        await fs.writeFile(w.abs, w.content, "utf8");
+    // phase 2 — commit.
+    //
+    // Phase 1 validates every hunk in memory, so a CONTENT mismatch never
+    // lands halfway. An I/O failure still could: the old loop wrote straight
+    // to the final paths, so a failure on write k of n left writes 1..k-1
+    // already on disk while the tool reported "patch failed". apply_patch is
+    // documented as atomic, so make the commit phase live up to it:
+    //   1. back up the current bytes of every path we are about to change
+    //   2. write each new file to a sibling temp file, then rename() over the
+    //      target (rename within a directory is atomic, so a reader never
+    //      observes a half-written file)
+    //   3. on ANY failure, restore the backups and remove temp files
+    // Deletes are only performed once every write has landed, and a failed
+    // delete is now reported instead of silently swallowed.
+    const backups = new Map();
+    const temps = [];
+    try {
+        for (const w of writes) {
+            if (!backups.has(w.abs))
+                backups.set(w.abs, await fs.readFile(w.abs, "utf8").catch(() => null));
+            await fs.mkdir(path.dirname(w.abs), { recursive: true });
+            const tmp = `${w.abs}.teapot-patch-${process.pid}-${temps.length}.tmp`;
+            temps.push(tmp);
+            await fs.writeFile(tmp, w.content, "utf8");
+            await fs.rename(tmp, w.abs);
+        }
+    }
+    catch (e) {
+        await rollbackWrites(backups, temps);
+        return {
+            ok: false,
+            result: `patch commit failed and was rolled back (no files changed): ${e.message}\n` +
+                "re-read the files and regenerate the patch",
+        };
+    }
+    // writes are in — now the deletes. A delete that fails is a real, visible
+    // inconsistency (the old content moved/updated but the source survived),
+    // so roll the whole patch back rather than report a false success.
+    const removed = [];
+    try {
+        for (const d of deletes) {
+            await fs.rm(d);
+            removed.push(d);
+        }
+    }
+    catch (e) {
+        for (const d of removed) {
+            const orig = await fs.readFile(d, "utf8").catch(() => null);
+            if (orig !== null)
+                await fs.writeFile(d, orig, "utf8").catch(() => { });
+        }
+        await rollbackWrites(backups, temps);
+        return {
+            ok: false,
+            result: `patch commit failed and was rolled back (no files changed): ${e.message}`,
+        };
     }
-    for (const d of deletes)
-        await fs.rm(d).catch(() => { });
     return { ok: true, result: `patch applied:\n${summary.join("\n")}` };
 }
+/**
+ * Undo a partially committed patch: restore each target's original bytes
+ * (null = it did not exist before, so remove the file we created) and clean
+ * up any temp file that never made it through its rename.
+ */
+async function rollbackWrites(backups, temps) {
+    for (const t of temps)
+        await fs.rm(t, { force: true }).catch(() => { });
+    for (const [abs, orig] of backups) {
+        if (orig === null)
+            await fs.rm(abs, { force: true }).catch(() => { });
+        else
+            await fs.writeFile(abs, orig, "utf8").catch(() => { });
+    }
+}
 export const TOOLS = [
     {
         name: "read_file",
@@ -588,12 +704,17 @@ export const TOOLS = [
         name: "write_file",
         description: "Create ONE new file, or replace a file's entire content (parent dirs auto-created). " +
             "Creating files as part of a larger batch of edits → one apply_patch instead. " +
-            "Partial changes to an existing file → edit_file.",
+            "Partial changes to an existing file → edit_file. " +
+            "Pass base_content (the bytes you read) when rewriting a file that may have changed under you — the write is refused rather than clobbering a concurrent edit.",
         parameters: {
             type: "object",
             properties: {
                 path: { type: "string" },
                 content: { type: "string" },
+                base_content: {
+                    type: "string",
+                    description: "Optional: the exact bytes you read before writing. The write is REFUSED if the file changed since — re-read and retry instead of clobbering someone else's edit.",
+                },
             },
             required: ["path", "content"],
         },
@@ -610,6 +731,9 @@ export const TOOLS = [
                 };
             }
             const p = safeJoin(ctx.cwd, str(args.path));
+            const stale = staleGuard(str(args.path), args.base_content, await currentOrNull(p));
+            if (stale)
+                return stale;
             await fs.mkdir(path.dirname(p), { recursive: true });
             await fs.writeFile(p, args.content, "utf8");
             return { ok: true, result: `wrote ${p} (${args.content.length} bytes)` };
@@ -620,7 +744,8 @@ export const TOOLS = [
         description: "Make exactly ONE small, unique replacement in one existing file — the cheapest tool for a single spot change. " +
             "Copy old_text from the file contents (NOT from read_file's `N| ` prefixed display); it must appear exactly once — " +
             "if it matches several places, add surrounding lines or pass replace_all=true. " +
-            "Two or more changes (or a rename/delete) → use apply_patch instead.",
+            "Two or more changes (or a rename/delete) → use apply_patch instead. " +
+            "Pass base_content (the bytes you read) whenever the file may have changed under you — especially with replace_all, which otherwise rewrites occurrences that appeared after you read.",
         parameters: {
             type: "object",
             properties: {
@@ -628,12 +753,19 @@ export const TOOLS = [
                 old_text: { type: "string" },
                 new_text: { type: "string" },
                 replace_all: { type: "boolean", description: "replace every occurrence instead of requiring uniqueness" },
+                base_content: {
+                    type: "string",
+                    description: "Optional: the exact bytes you read before editing. Refuses the edit if the file changed since — important with replace_all, which otherwise rewrites occurrences that appeared after you read.",
+                },
             },
             required: ["path", "old_text", "new_text"],
         },
         async run(args, ctx) {
             const p = safeJoin(ctx.cwd, str(args.path));
             let text = await readText(p);
+            const stale = staleGuard(str(args.path), args.base_content, text);
+            if (stale)
+                return stale;
             const oldText = str(args.old_text);
             const newText = str(args.new_text);
             if (!oldText)

package/dist/master.js

@@ -651,8 +651,18 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
         if (owned)
             targetId = owned.agentId;
         const cfg = this.config.agents.find((a) => a.id === targetId);
-        if (!cfg || cfg.parent !== parentId)
-            throw new Error(`not your sub-agent: ${childId}`);
+        if (!cfg || cfg.parent !== parentId) {
+            // Scoping is correct — only the DIRECT parent may message a child, so a
+            // grandchild is rightly refused. But "not your sub-agent: <id>" reads
+            // like a bug when the agent simply guessed the wrong level of the tree.
+            // Name the real owner so the model can re-address the message (#11).
+            const actual = cfg?.parent;
+            const live = actual ? this.agents.get(actual) : undefined;
+            const detail = actual
+                ? ` its parent is @${actual}${live ? ` (message @${actual} instead, or spawn your own sub-agent for it)` : ""}.`
+                : " no such sub-agent exists.";
+            throw new Error(`not your sub-agent: ${childId}.${detail}`);
+        }
         const child = this.agents.get(targetId);
         if (!child)
             throw new Error(`sub-agent not running: ${targetId}`);

package/dist/server/api.js

@@ -10,6 +10,7 @@ import { spawn } from "node:child_process";
 import { promises as fs } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { parseSchedule } from "../scheduler/cron.js";
+import { TermSizeTracker } from "./term-size.js";
 import { SUB_PERSONAS } from "../master.js";
 import { ConfigPatchSchema, formatZodError } from "../config-schema.js";
 import { providerHeaders } from "../agent/llm.js";
@@ -105,6 +106,14 @@ export function buildApp(master) {
         });
     // per-agent terminal spawn guard
     const termCounts = new Map();
+    // keyed by CHILD, not agent: one agent may have up to 10 concurrent
+    // terminals, each with its own size and its own foreground program
+    const termSizes = new TermSizeTracker();
+    const setTermSize = (child, rows, cols) => termSizes.request(child, rows, cols, (r, c) => {
+        if (!child.stdin?.writable)
+            return;
+        child.stdin.write(`stty rows ${r} cols ${c} >/dev/null 2>&1\n`);
+    });
     // ---- realtime events over WebSocket (replaces SSE for the web UI) ----
     app.get("/api/ws", upgradeWebSocket(() => {
         let onUpdate = null;
@@ -201,8 +210,14 @@ export function buildApp(master) {
                     ? spawn("script", ["-qec", shell, "/dev/null"], { cwd: agent.workspace, env })
                     : spawn(shell, [], { cwd: agent.workspace, env: { ...env, TERM: "dumb" } });
                 console.log(`[teapot] ⌨ terminal open: ${agentId} @ ${agent.workspace} (${hasScript ? "pty" : "pipe"})`);
-                child.stdout?.on("data", (b) => send({ kind: "data", data: b.toString("utf8") }));
-                child.stderr?.on("data", (b) => send({ kind: "data", data: b.toString("utf8") }));
+                child.stdout?.on("data", (b) => {
+                    termSizes.markBusy(child);
+                    send({ kind: "data", data: b.toString("utf8") });
+                });
+                child.stderr?.on("data", (b) => {
+                    termSizes.markBusy(child);
+                    send({ kind: "data", data: b.toString("utf8") });
+                });
                 child.on("close", (code) => {
                     send({ kind: "exit", code });
                     console.log(`[teapot] ⌨ terminal exit: ${agentId} (${code ?? "signal"})`);
@@ -225,10 +240,15 @@ export function buildApp(master) {
                     const r = Number(m.rows) | 0;
                     const cl = Number(m.cols) | 0;
                     if (r > 0 && cl > 0)
-                        child.stdin.write(`stty rows ${r} cols ${cl} >/dev/null 2>&1\n`);
+                        setTermSize(child, r, cl);
                 }
             },
             onClose() {
+                // capture BEFORE cleanup() nulls the child out
+                const dead = child;
+                // drop the pending resize timer so we can't write into a dead child
+                if (dead)
+                    termSizes.forget(dead);
                 cleanup();
                 const n = (termCounts.get(agentId) ?? 1) - 1;
                 if (n <= 0)

package/dist/server/term-size.js

@@ -0,0 +1,62 @@
+/** debounce window: long enough to collapse a drag, short enough to feel instant */
+export const TERM_RESIZE_DEBOUNCE_MS = 250;
+/** how long after output a terminal counts as "a program is running" */
+export const TERM_BUSY_MS = 400;
+export class TermSizeTracker {
+    states = new Map();
+    /**
+     * Request a resize. Returns the number of `stty` lines that will actually
+     * be written for this call (0 while a burst is still collapsing) — exposed
+     * for tests and diagnostics.
+     */
+    request(child, rows, cols, write) {
+        const st = this.states.get(child) ?? { rows: 0, cols: 0, timer: null, busyUntil: 0 };
+        this.states.set(child, st);
+        if (st.timer) {
+            clearTimeout(st.timer);
+            st.timer = null;
+        }
+        // already the applied size → nothing a shell could act on
+        if (st.rows === rows && st.cols === cols)
+            return;
+        const wait = Math.max(0, st.busyUntil - Date.now());
+        st.timer = setTimeout(() => {
+            st.timer = null;
+            st.rows = rows;
+            st.cols = cols;
+            try {
+                write(rows, cols);
+            }
+            catch {
+                /* child exited mid-debounce */
+            }
+        }, wait > 0 ? wait : TERM_RESIZE_DEBOUNCE_MS);
+    }
+    /** a child produced output — defer resizes so we never type into it */
+    markBusy(child, ms = TERM_BUSY_MS) {
+        // create the entry if absent: output usually arrives long before the first
+        // resize, and dropping the signal then let the resize land in the program
+        const st = this.states.get(child) ?? { rows: 0, cols: 0, timer: null, busyUntil: 0 };
+        this.states.set(child, st);
+        st.busyUntil = Date.now() + ms;
+    }
+    /** forget a child; cancels its pending resize so we can't write to a corpse */
+    forget(child) {
+        const st = this.states.get(child);
+        if (st?.timer)
+            clearTimeout(st.timer);
+        this.states.delete(child);
+    }
+    /** test/diagnostic: the size currently applied for a child */
+    applied(child) {
+        const st = this.states.get(child);
+        return st ? { rows: st.rows, cols: st.cols } : null;
+    }
+    /** test: cancel everything (keeps suites from leaking timers) */
+    disposeAll() {
+        for (const st of this.states.values())
+            if (st.timer)
+                clearTimeout(st.timer);
+        this.states.clear();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teapot-coding-agent",
-  "version": "0.22.13",
+  "version": "0.23.0",
   "description": "A lightweight, always-on multi-agent harness for AI coding agents",
   "type": "module",
   "license": "AGPL-3.0-or-later",