teapot-coding-agent 0.24.2 → 0.25.0

package/dist/acp/adapter.js

@@ -1,6 +1,16 @@
 import { readEvents } from "../log/events.js";
 import path from "node:path";
 export const ACP_PROTOCOL_VERSION = 1;
+/**
+ * How often a running turn is drained for new events.
+ *
+ * The web UI gets a WebSocket push; ACP has no such channel here, so the turn
+ * is streamed by polling the agent's own log. 150ms is well under the ~60ms
+ * render tick a human notices, and the read is a tail of a file this process
+ * is already appending to — cheap enough to be invisible next to an LLM call.
+ */
+const STREAM_POLL_MS = 150;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** JSON-RPC error codes we use (the standard set plus JSON-RPC's own). */
 const PARSE_ERROR = -32700;
 const METHOD_NOT_FOUND = -32601;
@@ -13,6 +23,125 @@ const INTERNAL_ERROR = -32603;
  * request bookkeeping have somewhere to live, and so it is directly testable
  * with an in-memory stream pair.
  */
+/* ---------- streaming: log events → session/update notifications ---------- */
+/**
+ * ACP `ToolCall.kind` for a teapot tool name.
+ *
+ * The schema's own enum (verified against schema/v1/schema.json, not memory):
+ * read, edit, delete, move, search, execute, fetch, think, switch_mode, other,
+ * description. Editors use this to pick an icon and to decide whether the call
+ * mutates anything, so mapping our tools onto it is worth doing properly.
+ */
+const TOOL_KINDS = {
+    read_file: "read",
+    list_dir: "read",
+    glob: "search",
+    grep: "search",
+    bash: "execute",
+    bash_output: "execute",
+    read_url: "fetch",
+    web_fetch: "fetch",
+    edit_file: "edit",
+    write_file: "edit",
+    apply_patch: "edit",
+    file_edit: "edit",
+    memory: "edit",
+    get_memory: "read",
+};
+/** Filesystem tools whose `path` argument is worth surfacing as a location. */
+const LOCATED_TOOLS = new Set([
+    "read_file",
+    "edit_file",
+    "write_file",
+    "apply_patch",
+    "file_edit",
+    "list_dir",
+]);
+/** a one-line title for a tool call, the way an editor shows it in a list */
+function toolTitle(name, args) {
+    const first = (k) => {
+        const v = args[k];
+        return typeof v === "string" && v ? v : undefined;
+    };
+    if (name === "bash")
+        return first("command") ?? "bash";
+    if (name === "grep")
+        return first("pattern") ? `grep /${first("pattern")}/` : "grep";
+    return first("path") ?? name;
+}
+/** Absolute path for a tool's location, so an editor can open the file. */
+function toolLocation(name, args, workspace) {
+    if (!LOCATED_TOOLS.has(name))
+        return [];
+    const p = args.path;
+    if (typeof p !== "string" || !p)
+        return [];
+    const abs = path.isAbsolute(p) ? p : path.resolve(workspace, p);
+    const line = Number(args.line ?? args.line_number ?? NaN);
+    return [{ path: abs, ...(Number.isFinite(line) && line > 0 ? { line } : {}) }];
+}
+/**
+ * Turn one logged event into the session/update payload for it, or null when
+ * the event has no ACP equivalent (and must therefore NOT be invented into
+ * one).
+ *
+ * Pure and exported so the mapping is testable without a transport, which is
+ * how the previous scaffold went unverified: `drainOnce` existed, was never
+ * called, and nothing noticed.
+ */
+export function updateForEvent(e, opts) {
+    const d = (e.data ?? {});
+    switch (e.type) {
+        case "message": {
+            // The completion AUDIT's verdict and the operator-facing summary are
+            // timeline content, not something the agent said to the model. They are
+            // marked precisely so the web feed can skip them; an editor must not be
+            // shown an agent speaking a harness message.
+            if (d.final === true || d.operatorFacing === true)
+                return null;
+            const text = String(d.content ?? "");
+            if (!text.trim())
+                return null;
+            return {
+                sessionUpdate: "agent_message_chunk",
+                content: { type: "text", text },
+            };
+        }
+        case "tool_call": {
+            const name = String(d.name ?? "tool");
+            const args = (d.args ?? {});
+            return {
+                sessionUpdate: "tool_call",
+                toolCallId: String(d.callId ?? e.type),
+                title: toolTitle(name, args),
+                name,
+                kind: TOOL_KINDS[name] ?? "other",
+                status: "in_progress",
+                rawInput: args,
+                locations: toolLocation(name, args, opts.workspace),
+            };
+        }
+        case "tool_result": {
+            const name = String(d.name ?? "tool");
+            return {
+                sessionUpdate: "tool_call_update",
+                toolCallId: String(d.callId ?? e.type),
+                status: d.ok === false ? "failed" : "completed",
+                content: [
+                    {
+                        type: "content",
+                        content: { type: "text", text: String(d.result ?? "").slice(0, 20_000) },
+                    },
+                ],
+            };
+        }
+        default:
+            // state transitions, goals, todos, compactions, notes: all internal. The
+            // schema HAS update kinds for some of this (plan, usage_update), but
+            // emitting them with guessed payloads would be worse than silence.
+            return null;
+    }
+}
 export class AcpAdapter {
     master;
     input;
@@ -21,6 +150,8 @@ export class AcpAdapter {
     sessions = new Map();
     /** id -> notification params, so a prompt turn can stream updates */
     turnUpdates = new Map();
+    /** sessions cancelled during the CURRENT turn, cleared when it starts (#15) */
+    cancelled = new Set();
     buffer = "";
     nextSession = 1;
     initialized = false;
@@ -145,7 +276,13 @@ export class AcpAdapter {
     cancel(params) {
         const p = (params ?? {});
         const s = p.sessionId ? this.sessions.get(String(p.sessionId)) : undefined;
-        s?.agent.stop("cancelled via ACP");
+        if (!s)
+            return;
+        // Remember it HERE rather than asking the Agent whether it was stopped:
+        // the flag that says so is private, and the adapter already knows — it is
+        // the component that answered the cancel notification.
+        this.cancelled.add(s.id);
+        s.agent.stop("cancelled via ACP");
     }
     /* ---------- prompt turn ---------- */
     async prompt(id, params) {
@@ -160,15 +297,30 @@ export class AcpAdapter {
         if (!text)
             return this.fail(id, INVALID_PARAMS, "prompt must contain text");
         this.turnUpdates.set(id, { sessionId: s.id });
+        this.cancelled.delete(s.id); // a cancel is per-turn, not per-session
+        // Stream the turn as it happens. The editor shows the reply and each tool
+        // call appear as they happen; without this the client sees NOTHING until
+        // the whole turn finishes, which is the difference between a usable agent
+        // and a black box that eventually prints an answer.
+        const abort = new AbortController();
+        const stream = this.streamTurn(s.id, abort.signal).catch(() => { });
         try {
             s.agent.enqueuePrompt(text, "user");
             if (s.agent.status !== "running")
                 s.agent.start("acp prompt");
             await s.agent.settled();
-            const stopReason = s.agent.goal.status === "done" ? "end_turn" : "end_turn";
-            return this.ok(id, { stopReason });
+            // One last drain, or the final tool result and closing message can be
+            // missed: `settled()` resolves the moment the agent stops, and the last
+            // append may not have landed yet.
+            abort.abort();
+            await stream; // resolves after its own final drain
+            return this.ok(id, { stopReason: this.cancelled.has(s.id) ? "cancelled" : "end_turn" });
+        }
+        catch (err) {
+            return this.fail(id, INTERNAL_ERROR, err.message);
         }
         finally {
+            abort.abort();
             this.turnUpdates.delete(id);
         }
     }
@@ -181,16 +333,49 @@ export class AcpAdapter {
         for (const e of events) {
             if (e.seq <= afterSeq)
                 continue;
-            this.notify("session/update", {
-                sessionId,
-                update: {
-                    sessionUpdate: e.type === "message" ? "agent_message_chunk" : "tool_call",
-                    content: { type: "text", text: String(e.data?.content ?? "") },
-                },
-            });
+            const update = updateForEvent(e, { workspace: s.cwd });
+            // null means "no ACP equivalent" — state flips, goals, notes. Staying
+            // silent is correct; the old code invented a tool_call for every one.
+            if (update)
+                this.notify("session/update", { sessionId, update });
         }
-        const max = events.reduce((m, e) => Math.max(m, e.seq), afterSeq);
-        return max;
+        // Advance past EVERY event we read, including the ones we did not emit, so
+        // an un-emitted event is not reconsidered on the next poll.
+        return events.reduce((m, e) => Math.max(m, e.seq), afterSeq);
+    }
+    /**
+     * Poll one session until it settles, streaming each batch as it appears.
+     *
+     * Polling the JSONL rather than subscribing to the bus is deliberate: the log
+     * is the agent's own record, so a listener attached at the wrong moment can
+     * miss the start of a reply, and a crash mid-turn leaves the file as the one
+     * complete account of what happened. It also means a resumed session replays
+     * exactly the same updates.
+     */
+    async streamTurn(sessionId, signal) {
+        // Start from the CURRENT tail: everything before this prompt belongs to
+        // earlier turns, and a resumed session has already been replayed.
+        let cursor = await this.logTail(sessionId);
+        // NOTE the drain happens BEFORE the abort check, not after it. A short
+        // turn — a cached model, a tiny task, a failing endpoint that gives up
+        // quickly — can finish inside one poll interval, so a loop that slept and
+        // then bailed on `signal.aborted` would exit having drained NOTHING. That
+        // is exactly what happened: every turn raced the first tick and the
+        // editor received silence.
+        for (;;) {
+            cursor = await this.drainOnce(sessionId, cursor);
+            if (signal.aborted)
+                return;
+            await sleep(STREAM_POLL_MS);
+        }
+    }
+    /** highest seq currently in a session's log, or 0 */
+    async logTail(sessionId) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            return 0;
+        const events = await readEvents(s.agent.log.filePath).catch(() => []);
+        return events.reduce((m, e) => Math.max(m, e.seq), 0);
     }
     get initialized_() {
         return this.initialized;

package/dist/agent/agent.js

@@ -1760,6 +1760,39 @@ export class Agent {
         const head = [{ role: "system", content: sys }];
         return hasSystem ? [...head, ...this.messages.slice(1)] : [...head, ...this.messages];
     }
+    /**
+     * Re-read AGENTS.md and adopt it if it changed. Returns the new text when it
+     * did, or null when there is nothing to do.
+     *
+     * Called on compaction (#64 follow-up) and nowhere else. The one-shot capture
+     * in systemPrompt() exists to keep the system prompt byte-identical for the
+     * session so the provider's prefix cache survives; this is the single point
+     * where breaking that identity is free, because compaction has just rewritten
+     * the history underneath it.
+     *
+     * Failure is deliberately non-destructive: a read error, or a file that
+     * vanished, leaves the previous content in place. Dropping the instructions
+     * because of a transient error would be far worse than running one compaction
+     * on slightly stale rules.
+     */
+    reloadAgentsMd() {
+        if (!this.agentsMdLoaded)
+            return null; // nothing captured yet; nothing to update
+        let fresh;
+        try {
+            const p = path.join(this.opts.workspace, "AGENTS.md");
+            if (!existsSync(p))
+                return null; // deleted → keep the last known rules
+            fresh = readFileSync(p, "utf8").slice(0, 12_000);
+        }
+        catch {
+            return null; // unreadable → keep what we have
+        }
+        if (fresh === this.agentsMd)
+            return null;
+        this.agentsMd = fresh;
+        return fresh;
+    }
     /** AGENTS.md content cached for the session (empty string = none/read-failed) */
     agentsMd = "";
     /** captured once, with the rest of the session-frozen context */
@@ -2303,6 +2336,32 @@ export class Agent {
                 this.recentReads = this.recentReads.slice(0, restored.length); // keep order, drop misses
             }
         }
+        // #64 follow-up: compaction is the ONE point in a session where re-reading
+        // AGENTS.md is both safe and expected.
+        //
+        // It is expected because compaction exists precisely to summarise work
+        // against the CURRENT instructions: an agent that spent an hour under one
+        // set of project rules, then compacted, would otherwise carry the old rules
+        // over the summary and never see the edit.
+        //
+        // It is safe because the prefix-cache concern that motivates freezing the
+        // prompt does not apply here. That concern is about a prompt changing
+        // mid-turn, re-pricing the whole prefix on every call. A compaction
+        // ALREADY rewrote the history the prompt sits on top of, so the cache is
+        // being re-priced regardless — one more changed block costs nothing extra.
+        //
+        // Only AGENTS.md is re-read, deliberately. The workspace listing and the
+        // skills catalogue stay frozen: both are a snapshot of the workspace as it
+        // was, and re-listing mid-session would contradict the instruction to
+        // "not list again what is already here". AGENTS.md is different — it is
+        // instructions, not a listing, and a stale copy is actively misleading.
+        const refreshed = this.reloadAgentsMd();
+        if (refreshed) {
+            await this.log.append("system_note", this.currentSession, this.currentBranch, {
+                event: "agents-md-reloaded",
+                bytes: refreshed.length,
+            });
+        }
         // the operator can inspect WHAT was remembered — a dedicated typed event
         // (not an agent message) keeps it out of the model's own voice
         await this.log.append("compaction", this.currentSession, this.currentBranch, {

package/dist/index.js

@@ -35,6 +35,61 @@ async function waitForPortFree(port, host, timeoutMs) {
     }
     return false;
 }
+/* ---------- live-update handover: keeping the operator's terminal (#35) ---------- */
+/**
+ * The pid of the process that replaced US, or null if we are the server.
+ *
+ * `Master.restartServer()` spawns the replacement and records its pid here, so
+ * the outgoing process can supervise its own successor instead of exiting and
+ * handing the shell a prompt. A field on the master rather than an env var: both
+ * processes are separate, but this value is written and read in the SAME
+ * process, so there is no environment for the two of them to disagree over.
+ */
+/** is `pid` still running? (EPERM means alive but not ours to signal) */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/**
+ * Watch the replacement on the operator's behalf.
+ *
+ * The terminal is still wired to THIS process, so their Ctrl-C arrives here
+ * first. Two things must happen, and the old one-shot shutdown() could do
+ * neither:
+ *
+ *  1. forward the signal, so the replacement actually stops; and
+ *  2. when the replacement does exit, leave too — otherwise the shell waits on
+ *     a supervisor with nothing left to supervise and Ctrl-C looks broken.
+ *
+ * The original shutdown() cannot be reused for this: its `shuttingDown` latch
+ * is already set by the SIGTERM that started the handover, so a later Ctrl-C
+ * would be swallowed and this process would never exit.
+ */
+function supervise(pid) {
+    let signalled = false;
+    const forward = (sig) => {
+        // Once the replacement is on its way out, stop bouncing signals: a second
+        // SIGINT arriving during its shutdown would re-raise the same failure and
+        // the operator would have to press Ctrl-C several times to be heard.
+        if (signalled)
+            return;
+        signalled = true;
+        try {
+            process.kill(pid, sig);
+        }
+        catch {
+            /* already gone — the poll loop below notices and exits */
+        }
+    };
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+        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]
     let cfgArg;
@@ -114,7 +169,7 @@ async function main() {
         return;
     }
     const app = buildApp(master);
-    serveApp(app, config.port, config.host);
+    const server = serveApp(app, config.port, config.host);
     // agent crash isolation: an agent error never escapes its own loop; here we
     // also make sure the process survives unexpected rejections.
     process.on("uncaughtException", (err) => {
@@ -128,6 +183,37 @@ async function main() {
         if (shuttingDown)
             return;
         shuttingDown = true;
+        // SUPERVISOR MODE. When a live update replaced us, we are no longer the
+        // server — but we are still the process the SHELL is waiting on, and it
+        // is still this process group that owns the terminal. Exiting here ended
+        // the shell's foreground job, so the operator was dumped back to the
+        // prompt mid-session while the new server kept running in the background
+        // ("teapot live restart returns to the shell", #35).
+        //
+        // So instead of exiting we hand over: keep the job slot, forward signals
+        // to the replacement, and only leave once it is gone. The operator's
+        // terminal — and their Ctrl-C — follow the server across the restart.
+        //
+        // The replacement is the child we spawned ourselves, so we hold it directly:
+        // no pid passed through the environment, and no way for the two processes
+        // to disagree about who supervises whom.
+        if (master.replacementPid !== null) {
+            const replacement = master.replacementPid;
+            console.log(`[teapot] handing the terminal to the new server (pid ${replacement})...`);
+            // Release the port FIRST. The replacement is blocked in waitForPortFree
+            // waiting for exactly this, and it will SIGTERM us again if we do not go
+            // — but the difference now is that we stop SERVING rather than exiting,
+            // so the shell's foreground job survives the handover.
+            await server.close();
+            console.log("[teapot] port released; supervising the new server");
+            supervise(replacement);
+            // Stay attached until the replacement exits. The shell is still waiting
+            // on US, so leaving early is exactly the bug.
+            while (pidAlive(replacement))
+                await sleep(500);
+            console.log("[teapot] new server exited; releasing the terminal");
+            process.exit(0);
+        }
         console.log(`\n[teapot] shutting down${signal ? ` (${signal})` : ""}...`);
         await Promise.allSettled([...master.agents.values()].map((a) => a.dispose()));
         // During a live update the replacement SIGTERMs us to take the port. Linger

package/dist/master.js

@@ -231,6 +231,13 @@ function printAgentEvent(e) {
 }
 export class Master {
     agents = new Map();
+    /**
+     * pid of the process that replaced us in a live update, or null while we are
+     * still the server. `restartServer()` sets it; `index.ts` reads it to keep
+     * supervising the replacement instead of exiting and dropping the operator
+     * back at the shell prompt (#35).
+     */
+    replacementPid = null;
     tasks = [];
     childWaiters = new Map();
     startedAt = Date.now();
@@ -783,14 +790,29 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
         else if (e.type === "error") {
             parent.enqueuePrompt(`[harness] Sub-agent ${ac.id} hit an error: ${String(e.data.message ?? "").slice(0, 500)}`, "harness");
         }
-        // mirror feed-worthy activity; nested subs keep their original actor id
-        const MIRROR = new Set(["prompt", "message", "tool_call", "tool_result", "progress", "error", "question", "state"]);
-        if (!MIRROR.has(e.type))
-            return;
-        const inner = e.type === "sub" ? e.data : null;
-        const actor = inner?.sub ?? ac.id;
-        const payload = inner ? { sub: actor, type: inner.type, data: inner.data } : { sub: ac.id, type: e.type, data: e.data };
-        void parent.log.append("sub", parent.currentSession, parent.currentBranch, payload);
+        // #63: a child's activity is NOT mirrored into the parent's log.
+        //
+        // This used to write a `sub` row per child prompt/message/tool_call/…, so
+        // the parent's timeline filled with the child's entire transcript. Two
+        // problems, in order of discovery:
+        //
+        //  1. The rows were invisible, because `"sub"` was never in the web UI's
+        //     FEED_TYPES — so the filter dropped them and the feature did nothing
+        //     for as long as it existed (#40).
+        //  2. Once it was made to work (#40), the parent's timeline was flooded:
+        //     the operator reads a delegation as "what is this chat doing", not as
+        //     a firehose of a child's work.
+        //
+        // The mirroring bought nothing. `sub` rows are display-only:
+        // `rebuildMessagesFrom` never reads them, so the model never saw them and
+        // the child's own history was never duplicated into the parent's context.
+        // What the parent actually needs — the child's report — already arrives as
+        // a harness prompt above, which is the channel the model reads.
+        //
+        // So the right fix is to stop writing them. A chat's timeline is its own.
+        // If per-child detail is wanted in the UI later, it belongs behind an
+        // explicit filter ("show sub-agent activity"), reading each child's own log
+        // rather than interleaving a copy into the parent's.
     }
     /** sessions root + helpers */
     sessionsRoot() {
@@ -1246,6 +1268,11 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
         // process SIGTERMs us the instant it binds the port and the browser sees a
         // dropped connection instead of {ok:true} (#35).
         process.env.TEAPOT_RESTART_FROM = String(process.pid);
+        // #35: remember the replacement so this process can hand the operator's
+        // terminal over to it. Without that, the old process exited, the shell's
+        // foreground job ended, and the operator was dumped back at the prompt while
+        // the new server ran on in the background.
+        this.replacementPid = null; // cleared below, once the pid is known
         const child = spawn(execPath, args, {
             // NOT detached, and NOT stdio:"ignore" (#35). Both made the live update
             // silently daemonize: the replacement inherited nothing from this
@@ -1257,6 +1284,7 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
             stdio: "inherit",
             env,
         });
+        this.replacementPid = child.pid ?? null;
         await new Promise((r) => setTimeout(r, 1_500));
         void child; // deliberately not unref()'d — see above
     }

package/dist/server/api.js

@@ -1130,10 +1130,37 @@ export function buildApp(master) {
     });
     return app;
 }
+/**
+ * Serve the app, returning a handle that can release the listening socket.
+ *
+ * #35: the live-update handover needs to give the port up WITHOUT exiting —
+ * the outgoing process stays attached to the operator's terminal and supervises
+ * its replacement, so it must not still be holding the port the replacement is
+ * waiting to bind. Returning the server is what makes "stop serving, keep
+ * running" expressible; previously the handle was dropped here and the only way
+ * to release the port was process.exit().
+ */
 export function serveApp(app, port, host) {
     const wss = new WebSocketServer({ noServer: true });
-    serve({ fetch: app.fetch, port, hostname: host, websocket: { server: wss } }, (info) => {
-        const shown = host && host !== "0.0.0.0" && host !== "::" ? `http://${host}:${info.port}` : `http://localhost:${info.port} (all interfaces)`;
+    const server = serve({ fetch: app.fetch, port, hostname: host, websocket: { server: wss } }, (info) => {
+        const shown = host && host !== "0.0.0.0" && host !== "::"
+            ? `http://${host}:${info.port}`
+            : `http://localhost:${info.port} (all interfaces)`;
         console.log(`[teapot] master listening on ${shown}`);
     });
+    return {
+        close: async () => {
+            // WebSocket clients hold the server open; without this the close would
+            // hang on a live terminal and the handover would stall.
+            for (const c of wss.clients)
+                c.terminate();
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                // A keep-alive connection can keep the socket open indefinitely; the
+                // handover must not wait on that, so force it and report the port free
+                // rather than blocking the replacement forever.
+                setTimeout(resolve, 2_000);
+            });
+        },
+    };
 }

package/package.json

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