teapot-coding-agent 0.27.2 → 0.28.1

package/dist/agent/agent.js

@@ -27,11 +27,35 @@ import { bus } from "../bus.js";
  *    satisfied the request — sent a voluntary report_progress right after, and
  *    every requested report appeared TWICE on the timeline.
  */
-export const AUTO_CONTINUE_NUDGE = "Continue working toward the current goal. If you are blocked, explain why briefly. " +
+export const AUTO_CONTINUE_NUDGE = 
+// #136: the prefix marks this as harness text, not something the operator typed.
+// Unprefixed, the model read it as a request to reply — and prose ends the round
+// without finishing, which starts the next one.
+"[harness] " +
+    "Continue working toward the current goal. If you are blocked, explain why briefly. " +
     // name the tool explicitly, the way the sub-agent nudge already does
     "When the goal is genuinely met — or truly blocked — call finish() " +
     "(finish(goalComplete=true) when met, finish(goalComplete=false) when blocked) " +
     "instead of replying in prose; prose here does not stop the loop.";
+/**
+ * The auto-continue nudge with the CURRENT GOAL restated.
+ *
+ * #136: the nudge said "the current goal" and never said what it was. The sub-agent
+ * variant has always included its task text for exactly this reason — a forked
+ * child otherwise drifts back into the inherited conversation and keeps going
+ * forever (#106) — but the ROOT nudge had no such reminder, so a root agent that
+ * had lost the thread had nothing to re-anchor on and simply continued until the
+ * `maxConsecutiveIdleRounds` valve tripped.
+ *
+ * The goal is clipped like the sub-agent's: a 20k-character goal would otherwise
+ * re-enter the context on EVERY round.
+ */
+export function autoContinueNudge(goalText) {
+    const goal = goalText.trim();
+    if (!goal)
+        return AUTO_CONTINUE_NUDGE;
+    return `${AUTO_CONTINUE_NUDGE}\nCurrent goal:\n=====\n${goal.slice(0, 1500)}\n=====`;
+}
 export const PROGRESS_REQUEST = 
 // The leading sentence is kept VERBATIM: it is what existing harness prompts,
 // tests and any operator muscle-memory key off. #45 changed the INSTRUCTION
@@ -1586,9 +1610,13 @@ export class Agent {
                     break;
                 }
                 const isSub = !!this.opts.parent;
+                // #136: the ROOT nudge now restates the goal too, exactly as the sub-agent
+                // one always has. Both branches need it — a child drifts back into the
+                // inherited conversation, a root agent loses the thread, and in both cases
+                // "continue toward the current goal" is unactionable without the goal text.
                 const nudge = isSub
                     ? `[harness] Auto-nudge. Re-anchor on YOUR task — and only that:\n\n${this.goal.text.slice(0, 1500)}\n\nThe inherited conversation is reference only; other agents own any older tasks in it. If your task is complete, call finish() now instead of continuing. If blocked, explain why briefly and finish().`
-                    : AUTO_CONTINUE_NUDGE;
+                    : autoContinueNudge(this.goal.text);
                 await this.log.append("prompt", this.currentSession, this.currentBranch, {
                     source: "harness",
                     text: nudge,
@@ -1632,11 +1660,6 @@ export class Agent {
         if (!this.stopRequested && !this.awaitingUser)
             this.setStatus("idle", "round complete");
     }
-    /**
-     * One LLM call with a fresh abort controller so stop() can interrupt it
-     * immediately, plus loop-level retries for provider flakiness (the SDK
-     * already backsoff 429/5xx; this covers exhausted rate limits and 400s).
-     */
     /**
      * One LLM call with a fresh abort controller so stop() can interrupt it
      * immediately, plus loop-level retries for provider flakiness (the SDK

package/dist/agent/tools.js

@@ -1195,7 +1195,8 @@ export const TOOLS = [
             // #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),
+            // the pattern master.ts uses for "not your sub-agent" (its
+            // `messageChild`),
             // which turned a confusing refusal into a re-addressable one.
             if (!oldText)
                 return {

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";
 /**
@@ -90,24 +91,49 @@ function supervise(pid) {
         process.on(sig, () => forward(sig));
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-async function main() {
-    // CLI: teapot [--port N] [-p N] [--config file] [-c file] [config.json]
+/**
+ * Parse `teapot [--port N] [-p N] [--host addr] [--config file] [config.json]`.
+ *
+ * Extracted from main() and exported so it can be tested. It was inline before,
+ * which left `index.ts` at 48% branch coverage with NO test importing it at all —
+ * the parser decides which config file is read and which port is bound, so a
+ * regression here starts the wrong server on the wrong port with no error anyone
+ * would read.
+ *
+ * The bare-word rule keeps the FIRST positional as the config path: a later bare
+ * word is a stray argument, not an override, and silently replacing the config
+ * with it would be worse than ignoring it.
+ */
+export function parseArgs(argv) {
     let cfgArg;
     let portOverride;
     let hostOverride;
-    const args = process.argv.slice(2);
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (a === "--port" || a === "-p")
-            portOverride = Number(args[++i]);
-        else if (a === "--host")
-            hostOverride = args[++i];
-        else if (a === "--config" || a === "-c")
-            cfgArg = args[++i];
-        else if (!cfgArg && !a.startsWith("-"))
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--port" || a === "-p") {
+            const raw = argv[++i];
+            const n = Number(raw);
+            // NaN is dropped rather than applied: `config.port = NaN` would fall through
+            // to the listen call and produce a far more confusing failure than ignoring
+            // a mistyped flag
+            if (!Number.isNaN(n))
+                portOverride = n;
+        }
+        else if (a === "--host") {
+            hostOverride = argv[++i];
+        }
+        else if (a === "--config" || a === "-c") {
+            cfgArg = argv[++i];
+        }
+        else if (!a.startsWith("-") && cfgArg === undefined) {
             cfgArg = a;
+        }
     }
-    if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    return { cfgArg, portOverride, hostOverride, help: argv.includes("--help") || argv.includes("-h") };
+}
+async function main() {
+    const { cfgArg, portOverride, hostOverride, help } = parseArgs(process.argv.slice(2));
+    if (help) {
         console.log("teapot [--port N] [--host addr] [--config file.json] [config.json]");
         console.log("  --host 127.0.0.1 (default) · 0.0.0.0 exposes the UI to your network");
         console.log("  --acp  speak the Agent Client Protocol on stdio instead of serving HTTP (#15)");
@@ -229,4 +255,40 @@ async function main() {
     process.on("SIGINT", () => void shutdown("SIGINT"));
     process.on("SIGTERM", () => void shutdown("SIGTERM"));
 }
-void main();
+// Only when RUN, not when imported. `void main()` at module scope meant importing
+// this file for `parseArgs` started a whole server — which is why index.ts had no
+// 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.
+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

@@ -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",
@@ -568,8 +579,30 @@ export class Master {
             // #130: a spawned child is `idle` until start() runs, and that lazy-load
             // flip is its FIRST transition — so requiring a prior `running` is what stops
             // the parent being told the child settled before it began.
+            // #135: reworded, because the old line was wrong in two ways.
+            //
+            // "Continue your task, or finish() if the work is done" was addressed to the
+            // PARENT — but the parent did not spawn this child for its own sake, and
+            // when the child DID call finish() the parent already receives a proper
+            // "Sub-agent X finished. Final report: …" (the `finished. Final report:`
+            // prompt below). So the nudge
+            // restated as an instruction what the report already stated as fact, and
+            // invited the parent to `finish()` ITS OWN goal over a child's status.
+            //
+            // The new wording says what happened and what to do about it, and points at
+            // the report when there is one:
+            //
+            //   child gave a summary  -> "…returned without calling finish(); its final
+            //                             message follows." (the report arrives separately)
+            //   child said nothing     -> "…went idle without reporting. If that is
+            //                             unexpected, message it or re-spawn it."
             if (this.reportedRunning.has(agentId) && SETTLED.has(status))
-                parent.enqueuePrompt(`[harness] @${agentId} is now ${status}. Continue your task, or finish() if the work is done.`, "harness");
+                parent.enqueuePrompt(`[harness] Sub-agent @${agentId} is now ${status} without having called finish(), so it has not reported a result.` +
+                    (status === "error"
+                        ? ` Check its last output before deciding whether to re-spawn it.`
+                        : status === "stopped"
+                            ? ` It may have been stopped mid-task; message it to resume, or re-spawn it.`
+                            : ` If you expected a result, message it or re-spawn it.`), "harness");
             if (status === "running")
                 this.reportedRunning.add(agentId);
             else if (SETTLED.has(status))
@@ -742,29 +775,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/dist/server/api.js

@@ -1134,6 +1134,30 @@ export function buildApp(master) {
         // only used for the "load older" affordance, where approximate is fine.
         const branch = c.req.query("branch");
         const before = c.req.query("before");
+        // #54: `?after=<id>` returns only what landed AFTER that event.
+        //
+        // This is the cursor the reconnect path was missing. Without it a dropped
+        // socket is recovered by re-fetching the whole tail — 2,000 events by default
+        // — and throwing away all but the few that are new. That is what makes the
+        // architecture REST-authoritative: the frontend can only learn "something
+        // changed" and must re-read to find out what.
+        //
+        // It is also the only cursor that can be cheap here: the tail path scans
+        // backwards from EOF, so an `after` lookup that lands near the end reads a
+        // small window instead of parsing the whole log.
+        const after = c.req.query("after");
+        if (after && !before && !branch) {
+            const all = await readEventsCached(filePath);
+            const idx = all.findIndex((e) => e.id === after);
+            // an unknown cursor means the client's view is not a prefix of ours (a
+            // compacted or rotated log), so a full tail is the only safe answer
+            if (idx === -1) {
+                const tail = await readEventsTail(filePath, limit);
+                return c.json({ events: tail.events, total: tail.total, partial: tail.truncated, gap: true });
+            }
+            const events = all.slice(idx + 1);
+            return c.json({ events, total: all.length, appended: events.length > 0 });
+        }
         if (!before && !branch) {
             const tail = await readEventsTail(filePath, limit);
             return c.json({ events: tail.events, total: tail.total, partial: tail.truncated });

package/package.json

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