teapot-coding-agent 0.7.0 → 0.9.0

package/README.md

@@ -108,12 +108,17 @@ master (Hono server, src/master.ts + src/server/api.ts)
 - **LLM** (`src/agent/llm.ts`): official `openai` npm client against any
   OpenAI-compatible endpoint (OpenRouter, vLLM, Ollama...). Model is config,
   never hard-coded.
-- **Tools** (`src/agent/tools.ts`): provider-agnostic JSON-schema function
-  specs — `read_file`, `write_file`, `edit_file`, `list_dir`, `bash` (git goes
-  through bash), plus meta tools `finish` / `report_progress` / `get_goal` /
-  `set_goal` / `read_memory` / `set_memory` / `list_skills`. Paths are
-  confined to the workspace; bash runs detached in its own process group and
-  the whole group is SIGKILLed on timeout.
+- **Tools** (`src/agent/tools.ts`): provider-agnostic JSON-schema function specs —
+  file work via `read_file` (numbered lines, grep-style `pattern` mode, negative
+  offsets), `write_file`, `edit_file` (unique replacement, `replace_all`,
+  whitespace-tolerant fallbacks with recovery hints), `apply_patch`
+  (Codex-style multi-file add/update/rename/delete patches, validated
+  atomically before writing) and `list_dir`; `bash` for git/builds/tests and
+  quick bulk transforms; `read_url` fetches a web page's readable content
+  (Mozilla Readability + happy-dom); plus meta tools `finish` /
+  `report_progress` / `get_goal` / `set_goal` / `read_memory` / `set_memory` /
+  `list_skills`. Paths are confined to the workspace; bash runs detached in its
+  own process group and the whole group is SIGKILLed on timeout or shutdown.
 - **Cache-friendly prompt design** — the system prompt is byte-identical on
   every turn; session state (goal, memory, skills) is fetched via tools, never
   injected. Combined with the append-only message history this keeps provider
@@ -227,7 +232,14 @@ GET  /brew                           418 I'm a teapot (RFC 2324)
 Designed for a dedicated agent Linux user; workspaces are path-confined,
 subprocesses run in killable process groups with hard timeouts, and resource
 limits (RLIMIT_* / cgroups) have a natural insertion point in
-`src/agent/tools.ts:runShell`. The master survives agent crashes by
+`src/agent/tools.ts:runShell`.
+
+**LAN exposure**: the API has no auth by default (localhost-first tool). To
+expose it beyond localhost, set `TEAPOT_API_TOKEN=<secret>` — every `/api/*`
+route then requires `Authorization: Bearer <secret>` (WebSocket handshakes
+accept `?token=<secret>`). In the web UI, open
+`http://host:7788/#token=<secret>` once; the token is stored locally and
+attached automatically. The master survives agent crashes by
 construction: agent errors never escape their own loop, and global handlers
 keep the process alive.
 

package/dist/agent/agent.js

@@ -12,32 +12,33 @@ import { EventLog, readEvents } from "../log/events.js";
 import { chat, chatStream } from "./llm.js";
 import { executeTool, toolSpecs, currentSkills } from "./tools.js";
 import { bus } from "../bus.js";
+/**
+ * SYSTEM_TEMPLATE must stay byte-identical across every request of a session:
+ * provider prefix caches key on it, so changing it (or injecting per-turn
+ * state) re-prices the whole context. That is why session state lives behind
+ * meta tools instead. The cache rationale itself stays HERE in a comment —
+ * the model does not need our cost-engineering notes every turn.
+ */
 const SYSTEM_TEMPLATE = `You are a coding agent working autonomously inside a workspace.
 
-This system prompt is intentionally STATIC — session state is never injected
-into it, so API prompt caches stay hot across turns. Fetch state with tools
-instead; they are cheap and always current.
-
-## Goal (harness-managed)
-- get_goal() → current objective + status. Call it at session start, after a
+Session state is not injected into prompts — fetch it with tools instead:
+- get_goal() → current objective + status. Call at session start, after a
   compaction notice, or whenever you lose the thread.
 - set_goal(text) → change the objective itself (not routine updates).
 - finish(goalComplete=true, summary) → goal fully achieved.
-
-## Your notes (memory.md, harness-managed)
-- read_memory() / set_memory(content) → durable notes injected nowhere else.
-  Keep them terse: decisions, gotchas, where you left off.
-
-## Skills (reusable playbooks)
-- list_skills() → what exists. load_skill(name) → full playbook.
-- save_skill(name, description, content) → distill a reusable procedure.
-
-## Project knowledge
-- AGENTS.md in the workspace root (optional): conventions & commands. Read it
+- read_memory() / set_memory(content) → your durable notes (memory.md).
+- list_skills() / load_skill(name) / save_skill(...) → reusable playbooks.
+- AGENTS.md in the workspace root (optional) holds project knowledge — read it
   with read_file at session start when present, keep it current.
 
 ## Rules
 - Work step by step with tools. Verify results (run tests/builds) before claiming progress.
+- File changes — pick by scope: write_file (one new file / full rewrite) ·
+  edit_file (exactly one small unique replacement) · apply_patch (several
+  edits, renames or deletes across one or more files, applied atomically).
+  read_file numbers lines and can grep via its pattern option. bash
+  text-munging (sed/awk/heredoc) remains available for quick bulk transforms
+  when that is genuinely faster.
 - When a loaded skill matches your task, follow its playbook.
 - When you make meaningful progress, call report_progress.
 - Be frugal: prefer small precise edits, avoid runaway loops.`;
@@ -61,9 +62,18 @@ export class Agent {
     };
     opts;
     messages = [];
+    /**
+     * User prompts waiting for the next turn boundary. Deliberately NOT queued
+     * on runChain: that chain holds the long-running loop, so queueing behind
+     * it would delay both the log entry (UI) and delivery until the round —
+     * sometimes the whole goal — finished.
+     */
+    pendingPrompts = [];
     stopRequested = false;
     wake = null;
     abort = null;
+    /** aborted only by dispose(): kills in-flight subprocess groups instantly */
+    toolAbort = new AbortController();
     runChain = Promise.resolve();
     lastProgressAt = Date.now();
     consecutiveToolErrors = 0;
@@ -89,6 +99,7 @@ export class Agent {
             defaultTimeoutMs: 120_000,
             maxOutputBytes: 60_000,
             skillRoots: this.skillRoots,
+            signal: this.toolAbort.signal,
         };
         // the session id IS the directory name — one directory per incarnation
         this.mainSession = path.basename(opts.sessionDir);
@@ -200,10 +211,29 @@ export class Agent {
         while (lineage.length && lineage[0].type === "fork")
             lineage.shift();
         const msgs = [];
+        // Prompts are logged the moment the user hits send — which can be while a
+        // tool batch is still open. Replaying them verbatim would slot a user
+        // message BETWEEN an assistant tool_call and its tool_result (API-invalid),
+        // so hold them until the open batch is answered, like live delivery does.
+        const META_TOOLS = new Set([
+            "finish", "report_progress", "set_goal", "get_goal",
+            "read_memory", "set_memory", "list_skills",
+        ]);
+        const openCalls = new Map(); // real tool_call id -> name
+        const bufferedUsers = [];
+        const flushUsers = () => {
+            if (openCalls.size === 0) {
+                for (const text of bufferedUsers.splice(0))
+                    msgs.push({ role: "user", content: text });
+            }
+        };
         for (const e of lineage) {
             const d = e.data;
             if (e.type === "prompt" && typeof d.text === "string") {
-                msgs.push({ role: "user", content: d.text });
+                if (openCalls.size > 0)
+                    bufferedUsers.push(d.text);
+                else
+                    msgs.push({ role: "user", content: d.text });
             }
             else if (e.type === "message") {
                 const role = d.role === "assistant" ? "assistant" : "user";
@@ -214,6 +244,11 @@ export class Agent {
                         type: "function",
                         function: { name: c.name, arguments: "{}" },
                     }));
+                    // meta tools are answered inline by the harness (no logged result);
+                    // the hole-filling pass below synthesizes theirs where they belong
+                    for (const t of m.tool_calls)
+                        if (!META_TOOLS.has(t.function.name))
+                            openCalls.set(t.id, t.function.name);
                 }
                 msgs.push(m);
             }
@@ -230,6 +265,8 @@ export class Agent {
                     tool_call_id: String(d.callId ?? ""),
                     content: `${d.ok === false ? "(failed) " : ""}${typeof d.result === "string" ? d.result : ""}`,
                 });
+                openCalls.delete(String(d.callId ?? ""));
+                flushUsers();
             }
             else if (e.type === "progress") {
                 // progress events may follow an assistant report_progress call that
@@ -240,7 +277,9 @@ export class Agent {
                         if (!msgs.some((x) => x.role === "tool" && x.tool_call_id === t.id)) {
                             msgs.push({ role: "tool", tool_call_id: t.id, content: "progress recorded" });
                         }
+                        openCalls.delete(t.id);
                     }
+                    flushUsers();
                 }
             }
         }
@@ -261,6 +300,9 @@ export class Agent {
                 }
             }
         }
+        // prompts that were still waiting on a hole-filled tail land here
+        for (const text of bufferedUsers.splice(0))
+            msgs.push({ role: "user", content: text });
         if (msgs.length > 0) {
             this.messages = msgs;
             this.currentBranch = last.branch;
@@ -321,14 +363,27 @@ export class Agent {
             model: this.opts.llm.model,
             provider: this.opts.provider,
             sessionDir: this.opts.sessionDir,
+            pendingPrompts: this.pendingPrompts.length,
         };
     }
-    /** Queue a user prompt; wakes the loop if needed. Returns immediately. */
+    /**
+     * Queue a user prompt. Returns immediately: the event is logged right away
+     * (so every connected UI sees it instantly) and the text is handed to the
+     * model at the next turn boundary — never mid-turn, and never blocked by
+     * the running loop.
+     */
     enqueuePrompt(text, source = "user") {
-        return this.enqueue(async () => {
-            await this.log.append("prompt", this.currentSession, this.currentBranch, { source, text });
-            this.messages.push({ role: "user", content: text });
-        });
+        this.pendingPrompts.push({ source, text });
+        void this.log
+            .append("prompt", this.currentSession, this.currentBranch, { source, text })
+            .then(() => bus.emit("update", { kind: "agent-update", agentId: this.opts.id }))
+            .catch(() => { });
+    }
+    /** Hand queued user prompts to the model at a turn boundary. */
+    drainPendingPrompts() {
+        for (const p of this.pendingPrompts.splice(0)) {
+            this.messages.push({ role: "user", content: p.text });
+        }
     }
     /** Resolves when all queued work (including a running loop) has settled. */
     settled() {
@@ -377,9 +432,16 @@ export class Agent {
         while (!this.stopRequested) {
             try {
                 const finished = await this.runTurnsUntilIdle();
-                if (finished || this.stopRequested)
+                if (this.stopRequested)
                     break;
-                if (!this.opts.autoContinue || this.goal.status !== "active")
+                // fresh user input arrived while we were finishing up — another round now
+                if (this.pendingPrompts.length)
+                    continue;
+                // auto-continue only makes sense with an active goal to continue toward
+                if (finished ||
+                    !this.opts.autoContinue ||
+                    this.goal.status !== "active" ||
+                    !this.goal.text.trim())
                     break;
                 // auto-continue: wait quietly, then nudge with a fresh round
                 await this.sleepInterruptible(this.opts.continueDelayMs);
@@ -463,6 +525,8 @@ export class Agent {
         for (let guard = 0; guard < 200; guard++) {
             if (this.stopRequested)
                 return finished;
+            // deliver prompts queued while the previous turn was running
+            this.drainPendingPrompts();
             // skills may have been created last turn — refresh the prompt listing
             await this.refreshSkills();
             // periodic progress report at turn boundary (no mid-turn interruption)
@@ -769,6 +833,9 @@ export class Agent {
     }
     async dispose() {
         this.stop("disposed");
+        // kill any in-flight subprocess group NOW so shutdown never waits out a
+        // long-running command (up to 10 min otherwise)
+        this.toolAbort.abort();
         await this.runChain.catch(() => { });
         await this.log.close();
     }