teapot-coding-agent 0.27.1 → 0.28.0

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
@@ -439,7 +463,26 @@ export class Agent {
      * (#59) — the same trap #38 documented for editing history.
      */
     isLive() {
-        return this.status === "running" || this.parkedByTool || this.pendingPrompts.length > 0;
+        // #127: a MANUAL compaction on an idle agent was rewriting `messages` — a
+        // large, non-cancellable operation — while `isLive()` reported false, so the
+        // UI offered "start".
+        //
+        // #133: and the reverse — after a STOP with prompts still queued, `live` stayed
+        // true forever, so the controls kept offering "stop" for an agent that was
+        // already stopped, and no amount of reloading helped. Measured:
+        //
+        //   after stop : status = stopped   live = true   pendingPrompts = 1
+        //
+        // A queued prompt is not work in progress: it is waiting for the operator to
+        // press start. #9 settled that a stop must neither deliver nor silently
+        // DISCARD those prompts, so they are kept — but keeping them must not make the
+        // agent read as running. A stop outranks them.
+        if (this.stopRequested)
+            return false;
+        return (this.status === "running" ||
+            this.parkedByTool ||
+            this.pendingPrompts.length > 0 ||
+            this.compactPhase !== "");
     }
     /**
      * A background shell (bash background=true) finished. Two channels:
@@ -1567,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,
@@ -1613,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
@@ -2927,14 +2969,40 @@ export class Agent {
     }
     /** Ask the model for dense continuation notes over the compacted range. */
     async summarize(old, onDelta) {
-        const transcript = old
+        const full = old
             .map((m) => {
             const who = m.role === "tool" ? "tool" : m.role;
             const tc = m.tool_calls?.map((t) => `\n[calls ${t.function.name}(${t.function.arguments})]`).join("");
             return `${who}: ${m.content ?? ""}${tc}`;
         })
-            .join("\n\n")
-            .slice(-120_000);
+            .join("\n\n");
+        // #127: this was a bare `.slice(-120_000)` — the TAIL only.
+        //
+        // The question the issue raises is the right one: when a compaction starts,
+        // the context window opens dramatically, and the summarizer saw only the last
+        // 120k characters of what it was asked to summarise. Anything older was not
+        // summarised and not kept — it was silently DISCARDED. So the original user
+        // requirement, which sits at the very front of the history, was the single
+        // most likely thing to be lost, and losing it is the one failure compaction
+        // cannot recover from: the summary is now the only record.
+        //
+        // Head + tail, with the seam marked so the model can tell a gap from a
+        // boundary. The head is where the goal, the constraints and the original ask
+        // live; the tail is where the recent state and any in-flight error do.
+        const BUDGET = 120_000;
+        const HEAD = Math.floor(BUDGET * 0.35);
+        const TAIL = BUDGET - HEAD;
+        let transcript;
+        if (full.length <= BUDGET) {
+            transcript = full;
+        }
+        else {
+            transcript = [
+                full.slice(0, HEAD),
+                `\n\n[... ${full.length - BUDGET} characters elided from the middle of this history ...]\n\n`,
+                full.slice(full.length - TAIL),
+            ].join("");
+        }
         const fn = this.opts.chatFn ?? chat;
         // Structured sections (Claude Code style): fixed headings survive MULTIPLE
         // successive compactions far better than free-form prose — each pass knows

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

@@ -90,24 +90,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 +254,15 @@ 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.
+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)
+    void main();

package/dist/master.js

@@ -568,8 +568,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))

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.1",
+  "version": "0.28.0",
   "description": "A lightweight, always-on multi-agent harness for AI coding agents",
   "type": "module",
   "license": "AGPL-3.0-or-later",