teapot-coding-agent 0.28.0 → 0.28.2

package/dist/index.js

@@ -5,8 +5,9 @@
  * Config may also come from TEAPOT_* env vars (see src/master.ts).
  * First run (no config file): boot anyway and finish setup in the web UI.
  */
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { createServer } from "node:net";
+import { fileURLToPath } from "node:url";
 import { loadConfig, resolveConfigPath, Master } from "./master.js";
 import { buildApp, serveApp } from "./server/api.js";
 /**
@@ -259,10 +260,35 @@ async function main() {
 // test importing it and sat at 48% branch coverage. The check is the standard
 // ESM "am I the entry point" test, and `node --experimental-strip-types src/index.ts`
 // and `node dist/index.js` both still take this branch.
-const isEntry = process.argv[1] !== undefined &&
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (process.argv[1] === new URL(import.meta.url).pathname ||
-        process.argv[1].endsWith("/index.js") ||
-        process.argv[1].endsWith("/index.ts"));
-if (isEntry)
+function isEntryPoint() {
+    const arg = process.argv[1];
+    if (!arg)
+        return false;
+    // `npm i -g teapot-coding-agent` puts a SYMLINK at node_modules/.bin/teapot, and
+    // npm invokes the target THROUGH it. So `process.argv[1]` is the symlink path
+    // (…/node_modules/.bin/teapot), NOT the file it points at — which matched none
+    // of the checks below, `main()` never ran, and the installed command exited 0
+    // in silence. Reporting `teapot` did nothing and needing `node dist/index.js`
+    // was the only symptom. `realpathSync` is what resolves it.
+    try {
+        const self = realpathSync(fileURLToPath(import.meta.url));
+        const entry = realpathSync(arg);
+        if (self === entry)
+            return true;
+        // `self === entry` is the ONLY correct test: it is the definition of being the
+        // entry point. The suffix checks that used to follow were a fallback for the
+        // symlink case, and they were far too loose — `endsWith("/index.ts")` is true
+        // for EVERY test file that imports this module, so importing it booted a real
+        // server on port 7788 and `cli-args.test.ts` failed with EADDRINUSE.
+        //
+        // Keep a basename check as a safety net for a bundler that rewrites paths, but
+        // require BOTH that we are the module AND that nothing else is: an argv[1] that
+        // resolves to a DIFFERENT file is by definition not this module's entry.
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryPoint())
     void main();

package/dist/master.js

@@ -3,7 +3,7 @@
  * Agents are in-process async loops (I/O bound only); all CPU-heavy work is
  * delegated to subprocesses managed by the bash tool with hard timeouts.
  */
-import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync, renameSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync, renameSync, unlinkSync, openSync, closeSync, fsyncSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import os from "node:os";
@@ -109,7 +109,18 @@ const DATA_DIR = process.env.TEAPOT_DATA_DIR ??
     path.join(os.homedir(), ".local", "share", "teapot-coding-agent");
 const DEFAULT_CONFIG = {
     port: Number(process.env.TEAPOT_PORT ?? 7788),
-    host: process.env.TEAPOT_HOST,
+    // #140: this was `process.env.TEAPOT_HOST`, i.e. UNDEFINED when unset — and an
+    // undefined hostname makes `@hono/node-server` bind every interface. So the
+    // default was the opposite of the documented one: `--help` says
+    // "127.0.0.1 (default) · 0.0.0.0 exposes the UI to your network", and yet the
+    // default WAS "expose to your network".
+    //
+    // Measured: with no --host the server answered on the machine's LAN address as
+    // well as loopback.
+    //
+    // Loopback is the right default for something holding API tokens and agent
+    // workspaces; exposing it has to be a deliberate act.
+    host: process.env.TEAPOT_HOST ?? "127.0.0.1",
     dataDir: DATA_DIR,
     llm: {
         baseUrl: process.env.TEAPOT_BASE_URL ?? "https://openrouter.ai/api/v1",
@@ -157,6 +168,24 @@ export function loadConfig(configPath) {
     };
 }
 /** Raw parsed user config (for lossless persistence of web edits). */
+/**
+ * Can this path be replaced by an atomic rename?
+ *
+ * #144: `/dev/null`, a fifo, or a directory are all legitimate values for
+ * `configPath`, and `rename` over them either fails outright (EACCES for a temp
+ * beside `/dev/null`) or is not what the caller wants. Only a regular file gets
+ * the write-temp-then-rename treatment.
+ */
+function isRegularFileTarget(p) {
+    try {
+        const st = statSync(p);
+        return st.isFile();
+    }
+    catch {
+        // does not exist yet — the parent decides; a real config path will be created
+        return true;
+    }
+}
 export function loadedRaw() {
     return masterRawConfig;
 }
@@ -278,8 +307,30 @@ export class Master {
         this.config = config;
         this.configPath = configPath;
     }
-    /** Persist current logical config back to disk (lossless via raw user config). */
+    /**
+     * Persist current logical config back to disk (lossless via raw user config).
+     *
+     * #144: this was a bare `writeFileSync`, which TRUNCATES the target before it
+     * writes. config.json holds every agent, provider and scheduled task, so any
+     * interruption during the write — SIGINT, a crash, a full disk — left a ZERO-LENGTH
+     * file, and the next boot read `{}` and came up empty.
+     *
+     * Boot made this far more likely than it sounds: every agent that mints a
+     * session calls `recordSession` → `saveConfig`, so a machine with 30 configured
+     * agents rewrites the whole file 30 times before the server listens. A user
+     * pressing Ctrl-C during that window lost the lot.
+     *
+     * Now: write a sibling temp file, fsync it, then `rename` over the target.
+     * `rename` is atomic within a filesystem, so the file is either the old content
+     * or the new — never empty. A crash mid-write leaves the temp file behind and
+     * the real config untouched.
+     */
     saveConfig() {
+        // #144: during boot, mark dirty instead of writing; flushed once at the end
+        if (this.deferConfigWrites) {
+            this.configDirty = true;
+            return;
+        }
         this.raw.agents = this.config.agents;
         this.raw.providers = this.config.providers;
         this.raw.defaultProvider = this.config.defaultProvider;
@@ -288,7 +339,75 @@ export class Master {
             this.raw.progressIntervalMs = this.config.progressIntervalMs;
         if (this.raw.progressMinChars === undefined && this.config.progressMinChars !== undefined)
             this.raw.progressMinChars = this.config.progressMinChars;
-        writeFileSync(this.configPath, JSON.stringify(this.raw, null, 2) + "\n");
+        this.writeConfigAtomic(JSON.stringify(this.raw, null, 2) + "\n");
+    }
+    /**
+     * Coalesce config writes. #144.
+     *
+     * Boot calls `addAgent` for every configured agent, and any agent whose recorded
+     * session is gone mints a new one — which calls `recordSession` → `saveConfig`.
+     * A machine with 30 agents therefore rewrote the whole file 30 times before the
+     * server listened, and each was a window in which the file could be truncated.
+     *
+     * With the write now atomic that is no longer dangerous, but it is still 30
+     * unnecessary writes of a 148KB file. During boot, saves are marked dirty and
+     * flushed ONCE at the end. Outside boot (an edit, a spawn, a rename) behaviour is
+     * unchanged: synchronous and immediate.
+     */
+    deferConfigWrites = false;
+    configDirty = false;
+    /** write once and clear the dirty flag — used at the end of a batched section */
+    flushConfig() {
+        this.configDirty = false;
+        this.saveConfig();
+    }
+    /** write-and-rename, so config.json is never observed empty or half-written */
+    writeConfigAtomic(body) {
+        // #144: `/dev/null` is a real, intentional value here — many callers (and
+        // every test that does not care about persistence) pass it as "no config
+        // file". The old `writeFileSync("/dev/null", …)` succeeded and discarded.
+        //
+        // Atomic writing cannot honour that: the temp file would be
+        // `/dev/.config.json.tmp-…`, which is EACCES for a normal user, so 22 tests
+        // failed with a bare 400 from POST /api/agents. Keep the old behaviour for a
+        // non-regular target, and only do write-rename where rename means something.
+        if (!isRegularFileTarget(this.configPath)) {
+            writeFileSync(this.configPath, body);
+            return;
+        }
+        const dir = path.dirname(this.configPath);
+        // same directory as the target, so rename() stays within one filesystem
+        const tmp = path.join(dir, `.config.json.tmp-${process.pid}-${Date.now()}`);
+        let fd;
+        try {
+            fd = openSync(tmp, "w");
+            writeFileSync(fd, body);
+            // fsync BEFORE the rename: without it the rename can land while the data is
+            // still in the page cache, which is the same data-loss window on a crash
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            renameSync(tmp, this.configPath);
+        }
+        catch (err) {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    /* already closed */
+                }
+            }
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                /* nothing to clean up */
+            }
+            // Losing the new state is survivable; losing the file is not, so rethrow
+            // rather than pretending the save succeeded
+            throw err;
+        }
     }
     raw = loadedRaw();
     /** Apply partial config edits from the web UI and persist them. */
@@ -336,28 +455,48 @@ export class Master {
     }
     async start() {
         mkdirSync(this.config.dataDir, { recursive: true });
-        for (const ac of this.config.agents) {
-            try {
-                await this.addAgent(ac);
+        // #144: ONE config write for the whole boot instead of one per agent.
+        //
+        // Every agent whose recorded session is gone mints a new one, and minting
+        // calls recordSession → saveConfig. With ~30 configured agents the user's log
+        // showed ~30 "session … is gone" lines, and therefore ~30 full rewrites of a
+        // 148KB config.json — all before the server ever listened. That is the window
+        // in which Ctrl-C emptied the file.
+        //
+        // `finally` so a throw mid-boot still flushes what it already changed: a
+        // deferred write that never flushes would leave config.json describing the PREVIOUS
+        // boot, which is its own silent data loss.
+        this.deferConfigWrites = true;
+        this.configDirty = false;
+        try {
+            for (const ac of this.config.agents) {
+                try {
+                    await this.addAgent(ac);
+                }
+                catch (err) {
+                    // one bad entry (duplicate id, unknown provider, …) must not take the
+                    // whole master down — skip it loudly and keep serving the rest
+                    console.error(`[teapot] skipping agent "${ac.id}": ${err.message}`);
+                }
             }
-            catch (err) {
-                // one bad entry (duplicate id, unknown provider, …) must not take the
-                // whole master down — skip it loudly and keep serving the rest
-                console.error(`[teapot] skipping agent "${ac.id}": ${err.message}`);
+            for (const t of this.config.tasks ?? []) {
+                try {
+                    this.tasks.push({
+                        task: t,
+                        schedule: parseSchedule(t.schedule),
+                        lastRunMin: t.lastRunMin ?? -1,
+                    });
+                }
+                catch (err) {
+                    // a hand-edited schedule typo must not stop the server from listening
+                    console.error(`[teapot] skipping task "${t.id}": ${err.message}`);
+                }
             }
         }
-        for (const t of this.config.tasks ?? []) {
-            try {
-                this.tasks.push({
-                    task: t,
-                    schedule: parseSchedule(t.schedule),
-                    lastRunMin: t.lastRunMin ?? -1,
-                });
-            }
-            catch (err) {
-                // a hand-edited schedule typo must not stop the server from listening
-                console.error(`[teapot] skipping task "${t.id}": ${err.message}`);
-            }
+        finally {
+            this.deferConfigWrites = false;
+            if (this.configDirty)
+                this.flushConfig();
         }
         // single low-frequency tick for everything periodic (idle cost ≈ 0)
         setInterval(() => void this.tick(), 15_000).unref();
@@ -764,29 +903,42 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
     /** Stop direct children (and their descendants by default) of an agent. */
     async stopChildrenFor(parentId, ids) {
         const stopped = [];
-        const walk = (pid) => {
+        // `inScope` is true once we are INSIDE a subtree we were asked to stop, and
+        // stays true all the way down.
+        //
+        // #142: the old walk passed `ids` down unchanged, so after matching an
+        // explicit id every DESCENDANT failed `ids.includes(id)` and was skipped —
+        // which is why the explicit branch hand-rolled its own one-level loop, and
+        // why that loop could not reach a great-grandchild.
+        const walk = (pid, inScope) => {
             for (const { id, agent } of this.childrenOf(pid)) {
-                if (ids && !ids.includes(id)) {
-                    // still descend: stopping a parent implies stopping its subtree
-                    walk(id);
+                const take = inScope || !ids || ids.includes(id);
+                if (!take) {
+                    // out of scope, but its own subtree may hold something in scope
+                    walk(id, false);
                     continue;
                 }
                 agent.stop("stopped by parent agent");
                 stopped.push(id);
-                if (ids) {
-                    // explicit id → also take its subtree
-                    const sub = this.childrenOf(id);
-                    for (const { id: gid, agent: g } of sub) {
-                        g.stop("stopped with parent");
-                        stopped.push(gid);
-                    }
-                }
-                else {
-                    walk(id); // full-subtree default
-                }
+                // #142: RECURSE for both modes.
+                //
+                // The explicit-id branch used to iterate `childrenOf(id)` exactly once, so
+                // a great-grandchild was never reached — stopping a child left its
+                // grandchild's child running, indefinitely, still holding a model
+                // connection and billing tokens:
+                //
+                //     root-sub           stopped
+                //     root-sub-sub       stopped
+                //     root-sub-sub-sub   running     <-- orphaned
+                //
+                // `walk` already means "this subtree", and it stops every node it visits,
+                // so one code path serves both cases. The only difference between the two
+                // modes is the `ids && !ids.includes(id)` test at the top, which decides
+                // whether a node is in scope — not how deep the walk goes.
+                walk(id, true);
             }
         };
-        walk(parentId);
+        walk(parentId, false);
         return { stopped };
     }
     /** Deliver a parent's message into a child's mailbox (and wake it). */

package/package.json

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