teapot-coding-agent 0.20.3 → 0.21.0

package/dist/agent/agent.js

@@ -6,7 +6,7 @@
  * periodic behaviour (progress reports, scheduled tasks) is driven by the
  * master's single low-frequency scheduler tick or by turn boundaries.
  */
-import { promises as fs } from "node:fs";
+import { promises as fs, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { EventLog, readEvents } from "../log/events.js";
 import { chat, chatStream } from "./llm.js";
@@ -170,6 +170,7 @@ export class Agent {
             readOnly: this.opts.readOnlyTools,
             onIdlePark: (reason) => this.parkForTool(reason),
             onIdleUnpark: () => this.unparkFromTool(),
+            onBackgroundExit: (info) => void this.onBackgroundJobExit(info),
         };
         // the session id IS the directory name — one directory per incarnation
         this.mainSession = path.basename(opts.sessionDir);
@@ -256,6 +257,28 @@ export class Agent {
      * operator isn't staring at a running spinner for minutes. The run chain is
      * still parked inside the tool — but any prompt/stop wakes it immediately.
      */
+    /**
+     * A background shell (bash background=true) finished. Two channels:
+     * 1. a system_note row in the timeline — the operator sees the outcome
+     *    without opening anything;
+     * 2. a queued harness prompt, delivered at the next turn boundary — the
+     *    agent learns exit code + output tail WITHOUT having to poll
+     *    bash_output blindly. Failed jobs say so loudly so the model reacts.
+     */
+    onBackgroundJobExit(info) {
+        const ok = info.code === 0;
+        const one = info.cmd.replace(/\s+/g, " ").slice(0, 80);
+        void this.log.append("system_note", this.currentSession, this.currentBranch, {
+            event: "background-exit",
+            jobId: info.id,
+            code: info.code,
+            durationMs: info.durationMs,
+            cmd: one,
+            failed: !ok,
+        });
+        // queue the report for the next turn boundary (agent-visible channel)
+        this.onBackgroundJobExitQueued(info);
+    }
     parkForTool(reason) {
         if (this.parkedByTool || this.status !== "running")
             return;
@@ -808,6 +831,7 @@ export class Agent {
      * call payload — not merely when it was logged.
      */
     drainPendingPrompts() {
+        this.drainBackgroundExits();
         for (const p of this.pendingPrompts.splice(0)) {
             // multimodal: images ride as OpenAI content parts (text first, then
             // images); plain prompts keep the string form for cache friendliness
@@ -843,6 +867,34 @@ export class Agent {
     }
     /** ids of user prompts that have entered an LLM call payload (recent first-capped) */
     deliveredPrompts = [];
+    /**
+     * Background jobs that exited since the last LLM call. Their outcomes are
+     * folded into ONE harness message at the turn boundary — the agent learns
+     * exit codes and output tails without polling bash_output.
+     */
+    bgExits = [];
+    onBackgroundJobExitQueued(info) {
+        this.bgExits.push(info);
+        if (this.bgExits.length > 32)
+            this.bgExits.shift(); // cap runaway spam
+        bus.emit("update", { kind: "agent-update", agentId: this.opts.id });
+    }
+    /** fold queued background-exit reports into the next LLM call (once each) */
+    drainBackgroundExits() {
+        if (!this.bgExits.length)
+            return;
+        const exits = this.bgExits.splice(0);
+        const lines = exits.map((e) => {
+            const status = e.code === 0 ? "finished OK" : `FAILED with exit code ${e.code ?? "?"}`;
+            const tail = e.outputTail.trim();
+            return (`- job ${e.id}: ${status} after ${(e.durationMs / 1000).toFixed(1)}s — ${e.cmd.slice(0, 100)}` +
+                (tail ? `\n  output tail:\n${tail.split("\n").slice(-8).map((l) => "  | " + l).join("\n")}` : ""));
+        });
+        const text = `[harness] Background job report:\n${lines.join("\n")}\n\n` +
+            "React to failures now if needed. Full output stays available via bash_output(job_id).";
+        this.messages.push({ role: "user", content: text });
+        void this.log.append("prompt", this.currentSession, this.currentBranch, { source: "harness", text }).catch(() => { });
+    }
     /** Resolves when all queued work (including a running loop) has settled. */
     settled() {
         return this.runChain.catch(() => { });
@@ -1418,11 +1470,100 @@ export class Agent {
         return finished;
     }
     buildMessages() {
-        // deliberately static: [system] + append-only history keeps prefix caches hot
+        // deliberately static: [system] + append-only history keeps prefix caches hot.
+        // The workspace context block (AGENTS.md + ls snapshot) is appended to the
+        // system message ONCE per session — changing it mid-session would re-price
+        // the whole prefix cache, so it is captured at first use and frozen.
+        const sys = this.systemPrompt();
         const hasSystem = this.messages[0]?.role === "system";
-        const head = [{ role: "system", content: SYSTEM_TEMPLATE }];
+        const head = [{ role: "system", content: sys }];
         return hasSystem ? [...head, ...this.messages.slice(1)] : [...head, ...this.messages];
     }
+    /** AGENTS.md content cached for the session (empty string = none/read-failed) */
+    agentsMd = "";
+    agentsMdLoaded = false;
+    /** one-time workspace listing injected with the system prompt */
+    wsSnapshot = "";
+    systemPrompt() {
+        if (!this.agentsMdLoaded) {
+            this.agentsMdLoaded = true;
+            // AGENTS.md + workspace listing are captured ONCE and PERSISTED to the
+            // session dir, so a restart re-issues the identical system prompt (the
+            // prefix cache survives; the snapshot is a session artifact, not live
+            // truth — list_dir shows current state).
+            const snapPath = path.join(this.opts.sessionDir, "workspace-snapshot.txt");
+            try {
+                // a previous incarnation already froze a snapshot → reuse it verbatim.
+                // The sentinel covers EMPTY workspaces too ("" would look like "no
+                // file" and make the restart re-list, breaking prefix-cache identity).
+                this.wsSnapshot = readFileSync(snapPath, "utf8");
+            }
+            catch {
+                this.wsSnapshot = "";
+            }
+            if (this.wsSnapshot === "" && existsSync(snapPath)) {
+                this.wsSnapshot = "(empty workspace)"; // the file exists but was empty
+            }
+            if (!this.wsSnapshot) {
+                try {
+                    this.agentsMd = existsSync(path.join(this.opts.workspace, "AGENTS.md"))
+                        ? readFileSync(path.join(this.opts.workspace, "AGENTS.md"), "utf8").slice(0, 12_000)
+                        : "";
+                }
+                catch {
+                    this.agentsMd = "";
+                }
+                try {
+                    const entries = readdirSync(this.opts.workspace, { withFileTypes: true });
+                    const lines = [];
+                    for (const e of entries.slice(0, 60)) {
+                        if (e.name.startsWith("."))
+                            continue;
+                        let size = "";
+                        if (!e.isDirectory()) {
+                            try {
+                                size = `${(statSync(path.join(this.opts.workspace, e.name)).size / 1024).toFixed(1)}K`;
+                            }
+                            catch {
+                                /* vanished */
+                            }
+                        }
+                        lines.push(e.isDirectory() ? `${e.name}/` : `${e.name} (${size})`);
+                    }
+                    this.wsSnapshot = lines.join("\n");
+                    if (!this.wsSnapshot)
+                        this.wsSnapshot = "(empty workspace)";
+                    try {
+                        void fs.writeFile(snapPath, this.wsSnapshot, "utf8");
+                    }
+                    catch {
+                        /* best-effort persistence */
+                    }
+                }
+                catch {
+                    this.wsSnapshot = "(workspace not readable)";
+                }
+            }
+            else {
+                try {
+                    this.agentsMd = existsSync(path.join(this.opts.workspace, "AGENTS.md"))
+                        ? readFileSync(path.join(this.opts.workspace, "AGENTS.md"), "utf8").slice(0, 12_000)
+                        : "";
+                }
+                catch {
+                    this.agentsMd = "";
+                }
+            }
+        }
+        let sys = SYSTEM_TEMPLATE;
+        if (this.agentsMd.trim()) {
+            sys += `\n\n## Project instructions (AGENTS.md)\n\n${this.agentsMd}`;
+        }
+        if (this.wsSnapshot) {
+            sys += `\n\n## Workspace snapshot (top level)\n${this.wsSnapshot}\nUse list_dir/read_file for anything deeper — do NOT list again what is already here.`;
+        }
+        return sys;
+    }
     async handleFinish(argsJson) {
         const args = safeParse(argsJson);
         if (args.goalComplete === true && this.goal.status !== "done") {

package/dist/agent/tools.js

@@ -83,7 +83,23 @@ function startBackgroundShell(cmd, ctx) {
     };
     child.stdout?.on("data", collect);
     child.stderr?.on("data", collect);
-    child.on("close", (code) => { sh.exited = true; sh.code = code; });
+    child.on("close", (code) => {
+        sh.exited = true;
+        sh.code = code;
+        // tell the harness so the agent learns the outcome WITHOUT polling
+        try {
+            ctx.onBackgroundExit?.({
+                id,
+                code,
+                cmd,
+                durationMs: Date.now() - sh.startedAt,
+                outputTail: sh.out.slice(-2000),
+            });
+        }
+        catch {
+            /* notification is best-effort */
+        }
+    });
     map.set(id, sh);
     return id;
 }
@@ -709,8 +725,9 @@ export const TOOLS = [
                 timeout_ms: { type: "number", description: `default ${DEFAULT_TIMEOUT_MS}` },
                 background: {
                     type: "boolean",
-                    description: "true = start the command and return IMMEDIATELY with a job id. Poll its output later via " +
-                        "bash_output. Use for dev servers, watchers, long builds — anything you don't need to wait for.",
+                    description: "true = start the command and return IMMEDIATELY with a job id. You are NOTIFIED at your " +
+                        "next turn boundary when it exits (exit code + output tail) — no polling needed. " +
+                        "Use bash_output only to fetch FULL output mid-run or after. Use for dev servers, watchers, long builds.",
                 },
             },
             required: ["command"],
@@ -720,8 +737,9 @@ export const TOOLS = [
                 const id = startBackgroundShell(str(args.command), ctx);
                 return {
                     ok: true,
-                    result: `started in background (job ${id}). Continue with other work; read its output with ` +
-                        `bash_output(job_id="${id}"). Kill it with bash_output(job_id="${id}", action="kill").`,
+                    result: `started in background (job ${id}). It runs while you work — you'll be notified here ` +
+                        `when it exits (exit code + output tail). Full output: bash_output(job_id="${id}"). ` +
+                        `Kill: bash_output(job_id="${id}", action="kill").`,
                 };
             }
             return runShell(str(args.command), ctx, Math.min(num(args.timeout_ms, ctx.defaultTimeoutMs), 600_000));

package/package.json

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