teapot-coding-agent 0.26.13 → 0.27.0

package/README.md

@@ -6,8 +6,6 @@
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/akku1139/teapot)
 
-[日本語版はこちら](README.ja.md)
-
 ---
 
 ## 🚀 Quick start
@@ -167,7 +165,7 @@ Agents can run `bash` and rewrite files — including `rm` and `npm install`.
 
 - Designed to run under a **dedicated Linux user**
 - `git commit` before handing over a repo you care about
-- File operations outside the workspace are rejected (`safeJoin`)
+- File operations outside the workspace are rejected (`safeJoin`), but agents can use `bash` outside of the worktree
 - teapot listens on localhost only by default. If you expose it, set **both** `--host 0.0.0.0` and an API token (`TEAPOT_API_TOKEN` env or config `password`):
 
 ```sh

package/dist/agent/agent.js

@@ -1227,23 +1227,48 @@ export class Agent {
             }
             if (p.source === "user") {
                 const id = p.id ?? `u${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
-                this.deliveredPrompts.push(id);
-                // cap: UI only needs recent confirmations
-                if (this.deliveredPrompts.length > 64)
-                    this.deliveredPrompts.shift();
-                void this.log
-                    .append("system_note", this.currentSession, this.currentBranch, {
-                    event: "prompt-delivered",
-                    promptId: id,
-                    preview: p.text.slice(0, 80),
-                })
-                    .then(() => bus.emit("update", { kind: "agent-update", agentId: this.opts.id }))
-                    .catch(() => { });
+                // #37: queued here, MARKED at the request boundary instead — see
+                // markDeliveredPrompts(). Text is kept so the marker can carry the same
+                // preview the UI shows.
+                this.undeliveredPrompts.push({ id, preview: p.text.slice(0, 80) });
             }
         }
     }
     /** ids of user prompts that have entered an LLM call payload (recent first-capped) */
     deliveredPrompts = [];
+    /**
+     * User prompts consumed from the queue but not yet MARKED as delivered (#37).
+     *
+     * They are drained at a turn boundary, but the `prompt-delivered` marker must
+     * wait until the request that carries them actually starts — which is later,
+     * and after `maybeCompact()`, which can itself call the LLM.
+     */
+    undeliveredPrompts = [];
+    /**
+     * Log `prompt-delivered` for every prompt whose outbound request is starting.
+     *
+     * #37: the marker's meaning is "the request carrying this prompt has begun".
+     * It used to fire in drainPendingPrompts, i.e. before the request, so the
+     * timeline reordered by a moment the API never saw.
+     */
+    async markDeliveredPrompts() {
+        if (this.undeliveredPrompts.length === 0)
+            return;
+        const pending = this.undeliveredPrompts;
+        this.undeliveredPrompts = [];
+        for (const { id, preview } of pending) {
+            this.deliveredPrompts.push(id);
+            // cap: the UI only needs recent confirmations
+            if (this.deliveredPrompts.length > 64)
+                this.deliveredPrompts.shift();
+            await this.log.append("system_note", this.currentSession, this.currentBranch, {
+                event: "prompt-delivered",
+                promptId: id,
+                preview,
+            });
+        }
+        bus.emit("update", { kind: "agent-update", agentId: this.opts.id });
+    }
     /**
      * Background jobs that exited since the last LLM call. Their outcomes are
      * folded into ONE harness message at the turn boundary — the agent learns
@@ -1366,9 +1391,25 @@ export class Agent {
     stopSeq = 0;
     /** #95: set when this round already injected a harness progress request */
     progressRequestedThisRound = false;
+    /**
+     * CONTROL PLANE: fired on every status change, immediately, independent of the
+     * log.
+     *
+     * #126: `wait_children` wakeups used to ride `EventLog.onEvent`, so a status
+     * change reached the parent only AFTER the write completed. After the
+     * write-before-notify fix that meant a FAILED or slow write left a parked parent
+     * waiting forever — persistence latency became control flow. Measured with every
+     * write failing: `onEvent fired: 0`, so no wakeup at all.
+     *
+     * Control flow must not depend on durability, so this is separate from the
+     * event pipeline. The log's `onEvent` now means "persisted, tell the world";
+     * this means "my state changed, react now".
+     */
+    onControlStatusChange = null;
     setStatus(s, reason = "") {
-        // Update the field FIRST. log.append fires onEvent synchronously, and the
-        // master's child-event hook wakes parked wait_children callers — those
+        // Update the field FIRST. The control-plane hook fires synchronously below
+        // (see onControlStatusChange), and it is what wakes parked wait_children
+        // callers — those
         // re-check agent.status at that instant. Updating after the append made
         // every waiter observe the OLD status ("running"), conclude "someone is
         // still working", and stay parked until timeout even though the child had
@@ -1377,6 +1418,15 @@ export class Agent {
         this.status = s;
         this.statusReason = reason;
         if (prev !== s) {
+            // #126: control plane FIRST, and not via the log. A parent's wait_children
+            // must wake on the status change itself, not on the durability of the write
+            // that records it.
+            try {
+                this.onControlStatusChange?.(this.opts.id, s);
+            }
+            catch {
+                /* a control-plane listener must never break a status change */
+            }
             void this.log.append("state", this.currentSession, this.currentBranch, {
                 from: prev,
                 to: s,
@@ -1591,6 +1641,27 @@ export class Agent {
                     text: "",
                     reasoning: "",
                 });
+            // #37: `prompt-delivered` must mean "the outbound request CARRYING this
+            // prompt has started", not "the prompt moved from the queue into
+            // `this.messages`".
+            //
+            // It used to be logged in drainPendingPrompts, which runs BEFORE
+            // refreshSkills, maybeRequestProgress and — critically — maybeCompact. So
+            // the marker preceded the request, and `maybeCompact()` can itself make an
+            // LLM call, which meant the timeline claimed a delivery order the API never
+            // saw. Measured before the fix:
+            //
+            //     LLM CALL #1
+            //       seq=5  prompt-delivered("first prompt")
+            //       seq=6  llm turn start
+            //
+            // The UI reorders by this marker (resequenceToDelivery), so the semantics
+            // were the bug — not timeline-order.ts.
+            //
+            // Emitted ONCE per request, not per attempt: a retry sends the same payload,
+            // so re-emitting would move the marker after a later event on each try.
+            if (attempt === 1)
+                await this.markDeliveredPrompts();
             try {
                 return await this.callLlm(messages, tools, onDelta);
             }

package/dist/agent/kill.js

@@ -0,0 +1,70 @@
+/** can this platform kill a whole process group? */
+export function canKillProcessGroup(platform = process.platform) {
+    return platform !== "win32";
+}
+/**
+ * Kill a spawned child, and its whole group where the platform allows it.
+ *
+ * Deliberately does NOT throw: callers are timeouts and abort handlers, where a
+ * throw would replace the real message with a secondary failure.
+ */
+export function killTree(child, platform = process.platform) {
+    if (!child?.pid)
+        return { killed: false, wholeTree: false, reason: "no-pid" };
+    if (!canKillProcessGroup(platform)) {
+        // Windows: no group kill. Try the direct child so at least THAT stops, and
+        // report that the tree is not covered rather than implying it is.
+        try {
+            process.kill(child.pid, "SIGKILL");
+            return { killed: true, wholeTree: false };
+        }
+        catch (err) {
+            const code = err.code;
+            return {
+                killed: false,
+                wholeTree: false,
+                reason: code === "ESRCH" ? "already-gone" : "error",
+            };
+        }
+    }
+    try {
+        process.kill(-child.pid, "SIGKILL"); // whole group
+        return { killed: true, wholeTree: true };
+    }
+    catch (err) {
+        const code = err.code;
+        // EPERM on the group can still mean the child is killable directly, and
+        // EPERM is what a partially-privileged tree produces.
+        if (code === "EPERM") {
+            try {
+                process.kill(child.pid, "SIGKILL");
+                return { killed: true, wholeTree: false };
+            }
+            catch {
+                return { killed: false, wholeTree: false, reason: "error" };
+            }
+        }
+        if (code === "ESRCH")
+            return { killed: false, wholeTree: false, reason: "already-gone" };
+        return { killed: false, wholeTree: false, reason: "error" };
+    }
+}
+/** a sentence for the tool result, so a partial kill is never silent */
+export function describeKill(outcome) {
+    if (outcome.killed && outcome.wholeTree)
+        return "killed (whole process group)";
+    if (outcome.killed) {
+        return ("killed the process, but this platform has no process groups — any " +
+            "background children it started may still be running");
+    }
+    switch (outcome.reason) {
+        case "no-pid":
+            return "no process handle to kill";
+        case "already-gone":
+            return "already exited";
+        case "group-unsupported":
+            return "process groups are not supported on this platform";
+        default:
+            return "could not be killed";
+    }
+}

package/dist/agent/skills.js

@@ -18,6 +18,7 @@
  */
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { homeDir } from "../home.js";
 export const SKILL_FILE = "SKILL.md";
 /**
  * Cheap change-detector for a set of skill roots. Returns a stable string
@@ -148,7 +149,9 @@ function unquote(v) {
  * directories are skipped silently, and nothing is read unless it exists.
  */
 export function foreignSkillRoots(workspace) {
-    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    // #110: the shared helper also covers HOMEDRIVE/HOMEPATH, which is how
+    // Windows reports a home when USERPROFILE is absent.
+    const home = homeDir();
     const out = [];
     const add = (dir) => {
         if (dir && !out.some((r) => r.dir === dir))

package/dist/agent/tools.js

@@ -7,6 +7,7 @@ import { existsSync, promises as fs, readlinkSync, realpathSync } from "node:fs"
 import path from "node:path";
 import { discoverSkills, isValidSkillName, readSkillFile, saveSkill, SKILL_FILE, } from "./skills.js";
 import { isReasoningEffort } from "../model-meta.js";
+import { killTree, describeKill } from "./kill.js";
 const str = (v, fallback = "") => (typeof v === "string" ? v : fallback);
 const num = (v, fallback) => (typeof v === "number" ? v : fallback);
 function clip(s, max) {
@@ -322,23 +323,18 @@ function runShell(cmd, ctx, timeoutMs) {
         };
         child.stdout.on("data", collect);
         child.stderr.on("data", collect);
-        const killGroup = () => {
-            try {
-                if (child.pid)
-                    process.kill(-child.pid, "SIGKILL"); // whole group
-            }
-            catch {
-                /* already gone */
-            }
-        };
+        // #110: the kill REPORTS whether it worked. It used to swallow every failure
+        // as "already gone", and on Windows a group kill throws ALWAYS — so a timeout
+        // would report `TIMEOUT after …ms` for a process that was still running, and
+        // shutdown would leave it alive. A timeout that claims success is worse than
+        // a crash, because nothing afterwards looks wrong.
+        const killGroup = () => killTree(child);
         const timer = setTimeout(() => {
-            killReason = `TIMEOUT after ${timeoutMs}ms`;
-            killGroup();
+            killReason = `TIMEOUT after ${timeoutMs}ms — ${describeKill(killGroup())}`;
         }, timeoutMs);
         // harness shutdown must not wait out a long-running command
         const onAbort = () => {
-            killReason = "ABORTED (harness shutdown)";
-            killGroup();
+            killReason = `ABORTED (harness shutdown) — ${describeKill(killGroup())}`;
         };
         if (ctx.signal) {
             if (ctx.signal.aborted)
@@ -1196,8 +1192,18 @@ export const TOOLS = [
                 return stale;
             let oldText = str(args.old_text);
             const newText = str(args.new_text);
+            // #126: the single most common edit_file failure in the real logs (22
+            // occurrences) said only "old_text is required", while the tool's own
+            // schema already documents the better form. Name it and say what to do —
+            // the pattern master.ts uses for "not your sub-agent" (master.ts:979),
+            // which turned a confusing refusal into a re-addressable one.
             if (!oldText)
-                return { ok: false, result: "old_text is required" };
+                return {
+                    ok: false,
+                    result: "old_text is required — pass the exact text to replace, or read with " +
+                        '`read_file({line_ids:"hash"})` and pass that block VERBATIM as old_text. ' +
+                        "Do NOT copy read_file's `N| ` line-number prefixes.",
+                };
             const replaceAll = args.replace_all === true;
             // #7/#4: accept a block copied straight out of read_file's hashline
             // output. When the anchors do not verify we FAIL with the specific reason
@@ -1422,14 +1428,9 @@ export const TOOLS = [
                         `jobs are per-workspace and forgotten on harness restart`,
                 };
             if (str(args.action) === "kill") {
-                if (!sh.exited) {
-                    try {
-                        if (sh.child.pid)
-                            process.kill(-sh.child.pid, "SIGKILL");
-                    }
-                    catch { /* already gone */ }
-                }
-                const note = sh.exited ? "(already exited)" : "killed";
+                // #110: same swallowed-kill bug — this reported "killed" and dropped the
+                // job from the map while the process kept running, now untrackable.
+                const note = sh.exited ? "(already exited)" : describeKill(killTree(sh.child));
                 map.delete(sh.id);
                 return { ok: true, result: `job ${sh.id} ${note}. Output so far:\n${clip(sh.out, 4000)}` };
             }

package/dist/home.js

@@ -0,0 +1,51 @@
+/**
+ * The user's home directory, on every platform.
+ *
+ * #110: `process.env.HOME` is a POSIX convention and is normally UNSET on
+ * Windows. Code that expanded `~` with `process.env.HOME ?? "~"` therefore got
+ * the LITERAL string "~" back on Windows — and since the result was then passed
+ * to `path.resolve(base, …)` and `mkdirSync`, teapot created a directory named
+ * `~`. That is the reported symptom.
+ *
+ * `os.homedir()` is the answer: on Windows Node resolves it from `USERPROFILE`,
+ * on POSIX from `HOME`, so it is never the literal `~`. The env lookups are kept
+ * only so a test can drive the Windows shape deterministically — `os.homedir()`
+ * on a Linux CI box would report `/root` and hide the very condition under test.
+ *
+ * Returns "" only when nothing at all is known, which callers treat as "leave the
+ * `~` alone" rather than inventing a path.
+ */
+export function homeDir(env = process.env) {
+    if (env.HOME)
+        return env.HOME;
+    if (env.USERPROFILE)
+        return env.USERPROFILE;
+    // Windows also reports a home as HOMEDRIVE + HOMEPATH. Concatenate
+    // defensively: `drive.replace(...) + path` yields the STRING "undefined"
+    // rather than undefined when either part is missing, which is exactly the
+    // class of bug this helper exists to remove.
+    const drive = env.HOMEDRIVE;
+    const rest = env.HOMEPATH;
+    if (drive && rest)
+        return drive.replace(/\\+$/, "") + rest;
+    if (drive)
+        return drive;
+    return "";
+}
+/**
+ * Expand a leading `~` to the home directory.
+ *
+ * Kept in one place so the Windows case cannot be got wrong a second time — the
+ * bug existed in three separate places before this helper (#110).
+ */
+export function expandTilde(input, env = process.env) {
+    // #110: on Windows a path can be `~\foo`, hence the backslash in the lookahead.
+    if (!/^~(?=$|[/\\])/.test(input))
+        return input;
+    const home = homeDir(env);
+    // With no home known, returning the input untouched is more honest than
+    // substituting a literal that would become a real directory.
+    if (!home)
+        return input;
+    return input.replace(/^~(?=$|[/\\])/, home);
+}

package/dist/log/events.js

@@ -89,12 +89,25 @@ export class EventLog {
             data,
         };
         this.lastByBranch.set(branch, evt.id);
-        try {
-            this.onEvent?.(evt);
-        }
-        catch {
-            /* observer must never break the log */
-        }
+        // #54: WRITE FIRST, then notify.
+        //
+        // The observer used to fire BEFORE the write. The frontend receives a
+        // `kind:"event"` frame and — by design — treats it as "something changed"
+        // and re-reads `/events`. So the reload could read the log BEFORE this
+        // event reached disk, and the reload would simply not contain it.
+        //
+        // Measured against a real EventLog, reloading on every notification:
+        //
+        //     appends: 30   WS-triggered reloads that MISSED the event: 30
+        //
+        // The 120ms debounce usually hides this, which is exactly why #54 felt
+        // random: a slow write misses, a fast one lands. Notifying after the write
+        // makes the event visible to any reader the observer triggers.
+        // `written` distinguishes a REAL write from the post-close drop path, which
+        // also resolves. #54: announcing a dropped event would tell the frontend to
+        // reload for something that will never appear — the row would flicker in and
+        // straight back out.
+        let written = false;
         const p = new Promise((resolve, reject) => {
             this.chain = this.chain.then(() => {
                 if (!this.stream) {
@@ -103,10 +116,31 @@ export class EventLog {
                     console.error(`[teapot] event dropped after log close (${this.agentId}): ${type}`);
                     return resolve(evt);
                 }
-                this.stream.write(JSON.stringify(evt) + "\n", "utf8", (err) => err ? reject(err) : resolve(evt));
+                this.stream.write(JSON.stringify(evt) + "\n", "utf8", (err) => {
+                    if (err)
+                        return reject(err);
+                    written = true;
+                    resolve(evt);
+                });
             }, () => resolve(evt));
         });
         this.chain = this.chain.then(() => { }, () => { });
+        // notify once the write is handed to the OS, so a reload the observer
+        // triggers can actually see this event
+        void p
+            .then(() => {
+            if (!written)
+                return; // dropped after close: nothing on disk to announce
+            try {
+                this.onEvent?.(evt);
+            }
+            catch {
+                /* observer must never break the log */
+            }
+        })
+            .catch(() => {
+            /* a failed write must not notify — the event is not on disk */
+        });
         return p;
     }
     lastEventId(branch) {

package/dist/master.js

@@ -7,6 +7,7 @@ import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSy
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import os from "node:os";
+import { expandTilde } from "./home.js";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { Agent } from "./agent/agent.js";
@@ -64,7 +65,9 @@ function readAppVersion() {
  * `~` is expanded for both forms; absolute paths pass through untouched.
  */
 export function resolveWorkspace(input, base) {
-    const expanded = input.trim().replace(/^~(?=$|\/|\\)/, process.env.HOME ?? "~");
+    // #110: `~` must not expand to the LITERAL "~" — that is how a directory named
+    // `~` got created on Windows, where process.env.HOME is unset. See src/home.ts.
+    const expanded = expandTilde(input.trim());
     if (path.isAbsolute(expanded))
         return path.normalize(expanded);
     return path.resolve(base, expanded);
@@ -521,6 +524,28 @@ export class Master {
             bus.emit("update", { kind: "event", agentId: e.agent, event: e });
             this.onChildEvent(ac, e);
         };
+        // #126: the CONTROL PLANE, separate from the event pipeline above.
+        //
+        // `onChildEvent` used to be what woke a parent's `wait_children`, and it runs
+        // after the event is persisted. So a failed or slow write left the parent
+        // parked forever — measured with every write failing, the wake never fired.
+        //
+        // A status change is CONTROL FLOW, not an observation, so it gets its own
+        // immediate path. `onChildEvent` keeps its other job (mirroring the child's
+        // activity into the parent's timeline, forwarding its final report), which
+        // legitimately belongs to the event stream.
+        agent.onControlStatusChange = (agentId, status) => {
+            if (!ac.parent)
+                return;
+            const parent = this.agents.get(ac.parent);
+            if (!parent)
+                return;
+            // the waiter re-checks whether ITS targets are all settled, so waking on
+            // every movement is correct and cheap
+            this.wakeParentWaiters(ac.parent);
+            if (status === "idle" || status === "stopped" || status === "waiting" || status === "error")
+                parent.enqueuePrompt(`[harness] @${agentId} is now ${status}. Continue your task, or finish() if the work is done.`, "harness");
+        };
         // sub-agent management hooks — only when this agent can legally spawn
         if (myDepth < this.maxSpawnDepth()) {
             const self = agent;
@@ -839,9 +864,18 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
             // silently dropped exactly the details the operator spawned the sub
             // to gather. Context management is compaction's job, not the pipe's.
             `[harness] Sub-agent ${ac.id} finished. Final report:\n${report || "(no summary)"}`, "harness");
+            // #123: a parent's report is delivered INTO a live agent — queueing it is
+            // not enough. If the parent is idle (finished, or parked) the report sat in
+            // the queue until something else started the loop, so the operator saw a
+            // finished sub-agent and a parent that never reacted.
+            if (parent.status !== "running")
+                parent.start(`sub-agent ${ac.id} finished`);
         }
         else if (e.type === "error") {
             parent.enqueuePrompt(`[harness] Sub-agent ${ac.id} hit an error: ${String(e.data.message ?? "").slice(0, 500)}`, "harness");
+            // #123: same for an error report
+            if (parent.status !== "running")
+                parent.start(`sub-agent ${ac.id} error`);
         }
         // #63: a child's activity is NOT mirrored into the parent's log.
         //