teapot-coding-agent 0.9.0 → 0.11.0

package/README.md

@@ -133,6 +133,11 @@ master (Hono server, src/master.ts + src/server/api.ts)
   through tools (`get_goal` / `set_goal` / `read_memory` / `set_memory`);
   `AGENTS.md` is optional project knowledge in the workspace root that agents
   are told to read at session start. Nothing is seeded into your project.
+- **Task list** — `todo.md` in the session dir, editable by BOTH sides:
+  humans write it from the web UI (✅ tasks panel) or
+  `POST /api/agents/:id/todo {text, notify?}`, the agent reads and updates it
+  via `get_todo` / `set_todo`. Saving with notify queues a harness prompt so
+  the agent picks up changes at the next turn boundary.
 
 ### Web UI
 
@@ -173,8 +178,10 @@ description: Steps to cut a release safely
 - The system prompt lists every discovered skill (name + description);
   workspace skills override same-named global ones.
 - The agent calls `load_skill(name)` when a task matches and follows it.
-- The agent calls `save_skill(name, description, content)` to distill a
-  reusable procedure it developed — available from the next turn, forever.
+- The agent calls `save_skill(name, description, content, files?)` to distill a
+  reusable procedure — `files` bundles helper scripts next to `SKILL.md`
+  (made executable automatically), and `load_skill` lists them as runnable
+  workspace paths. Available from the next turn, forever.
 
 ### Session log format (JSONL)
 
@@ -218,10 +225,13 @@ GET  /api/agents                     list snapshots
 GET  /api/agents/:id                 one snapshot
 POST /api/agents/:id/prompt          {text, start?}
 POST /api/agents/:id/start | /stop
-POST /api/agents/:id/goal            {text} or {status}
+POST /api/agents/:id/load            lazy session restore (stopped → idle)
+POST /api/agents/:id/goal            {text, notify?} or {status}
 POST /api/agents/:id/fork            {} → new branch, same session log
+POST /api/agents/:id/edit-prompt     {eventId, text, tail: "discard"|"summarize"} → fork & resend
 GET  /api/agents/:id/events?limit&branch&session
 GET  /api/agents/:id/branches
+GET  /api/tasks                      scheduled tasks with computed next-fire times
 GET  /api/metrics                    master rss/heap/load + per-agent stats
 GET  /api/events                     SSE updates (push, no polling)
 GET  /brew                           418 I'm a teapot (RFC 2324)

package/dist/agent/agent.js

@@ -27,6 +27,8 @@ Session state is not injected into prompts — fetch it with tools instead:
 - set_goal(text) → change the objective itself (not routine updates).
 - finish(goalComplete=true, summary) → goal fully achieved.
 - read_memory() / set_memory(content) → your durable notes (memory.md).
+- get_todo() / set_todo(content) → the operator-maintained task list
+  (todo.md); check it when picking up work, keep it current as you go.
 - 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.
@@ -40,6 +42,10 @@ Session state is not injected into prompts — fetch it with tools instead:
   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.
+- Turn proven procedures into skills: once something non-trivial worked well,
+  save_skill(name, description, content, files=[{name, content}]) so future
+  sessions can load_skill them — helper scripts go through files and are made
+  executable automatically.
 - When you make meaningful progress, call report_progress.
 - Be frugal: prefer small precise edits, avoid runaway loops.`;
 export class Agent {
@@ -52,10 +58,15 @@ export class Agent {
     currentBranch = "br0";
     goal = { text: "", status: "active", updatedAt: new Date().toISOString() };
     latestProgress = null;
+    /** operator-maintained task list (todo.md) — humans edit, agent reads */
+    todo = "";
+    /** set once the conversation has been restored (lazy: on first interaction) */
+    readyPromise = null;
     stats = {
         turns: 0,
         toolCalls: 0,
         inputTokens: 0,
+        cachedInputTokens: 0,
         outputTokens: 0,
         compactions: 0,
         startedAt: null,
@@ -76,19 +87,31 @@ export class Agent {
     toolAbort = new AbortController();
     runChain = Promise.resolve();
     lastProgressAt = Date.now();
+    /** real assistant output since the last progress report (chars / turns) */
+    activityChars = 0;
+    turnsSinceProgress = 0;
     consecutiveToolErrors = 0;
     constructor(opts) {
         this.opts = {
             progressIntervalMs: 10 * 60_000,
+            progressMinChars: 4_000,
+            progressMaxQuietTurns: 40,
             autoContinue: true,
             continueDelayMs: 15_000,
             maxConsecutiveToolErrors: 5,
             contextTokenBudget: 96_000,
+            contextWindowTokens: 0,
             restoreSession: true,
             globalSkillsDir: "",
             provider: "",
             ...opts,
         };
+        // a declared window implies its own budget: compact at ~75% of the
+        // model's real context unless the config set an explicit one (the 96k
+        // default only makes sense for unknown-window models)
+        if (this.opts.contextWindowTokens && !opts.contextTokenBudget) {
+            this.opts.contextTokenBudget = Math.round(this.opts.contextWindowTokens * 0.75);
+        }
         this.log = new EventLog(path.join(opts.sessionDir, "chat.jsonl"), opts.id);
         this.skillRoots = [
             { dir: path.join(opts.workspace, "skills"), source: "workspace" },
@@ -143,9 +166,37 @@ export class Agent {
         await this.migrateGoalFromWorkspace();
         const stored = await this.readGoalStore();
         this.goal = stored ?? { text: "", status: "active", updatedAt: new Date().toISOString() };
-        if (this.opts.restoreSession)
-            await this.restoreFromLog();
+        // operator-maintained task list lives beside goal.md
+        this.todo = await fs.readFile(this.todoFile, "utf8").catch(() => "");
         await this.refreshSkills();
+        // the conversation is NOT restored here: boot cost stays O(agents), not
+        // O(history). It is rebuilt lazily by ensureReady() on first interaction.
+        if (this.opts.restoreSession) {
+            this.status = "stopped";
+            this.statusReason = "session not loaded — select it or send a prompt";
+            bus.emit("update", { kind: "agent-update", agentId: this.opts.id });
+        }
+    }
+    /**
+     * Restore the conversation from the JSONL log exactly once, on demand.
+     * Everything that touches history (prompts, start, fork, UI selection)
+     * funnels through here; boot stays cheap no matter how many sessions exist.
+     */
+    ensureReady() {
+        if (!this.readyPromise) {
+            this.readyPromise = (async () => {
+                if (this.opts.restoreSession) {
+                    await this.restoreFromLog();
+                    if (this.status === "stopped")
+                        this.setStatus("idle", "session loaded");
+                }
+            })();
+        }
+        return this.readyPromise;
+    }
+    /** Explicit load (e.g. the user clicked the agent in the UI): stopped → idle. */
+    async load() {
+        await this.ensureReady();
     }
     /** harness-managed files inside the session directory */
     get goalFile() {
@@ -154,6 +205,9 @@ export class Agent {
     get memoryFile() {
         return path.join(this.opts.sessionDir, "memory.md");
     }
+    get todoFile() {
+        return path.join(this.opts.sessionDir, "todo.md");
+    }
     async readGoalStoreRaw() {
         return fs.readFile(this.goalFile, "utf8").catch(() => null);
     }
@@ -195,114 +249,11 @@ export class Agent {
         const events = await readEvents(this.log.filePath);
         if (events.length === 0)
             return;
-        const byId = new Map(events.map((e) => [e.id, e]));
-        let last = events[events.length - 1];
-        // walk backwards to the root via parent links (fork-safe)
-        const lineage = [];
-        const seen = new Set();
-        for (let cur = last; cur; cur = cur.parent ? byId.get(cur.parent) : undefined) {
-            if (seen.has(cur.id))
-                break;
-            seen.add(cur.id);
-            lineage.push(cur);
-        }
-        lineage.reverse();
-        // skip the trailing fork event itself (it is bookkeeping, not conversation)
-        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") {
-                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";
-                const m = { role, content: typeof d.content === "string" ? d.content : "" };
-                if (Array.isArray(d.toolCalls) && d.toolCalls.length > 0) {
-                    m.tool_calls = d.toolCalls.map((c) => ({
-                        id: c.id,
-                        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);
-            }
-            else if (e.type === "tool_call") {
-                // enrich the preceding assistant tool_calls with real arguments
-                const prev = [...msgs].reverse().find((x) => x.role === "assistant" && x.tool_calls?.some((t) => t.id === d.callId));
-                const tc = prev?.tool_calls?.find((t) => t.id === d.callId);
-                if (tc)
-                    tc.function.arguments = JSON.stringify(d.args ?? {});
-            }
-            else if (e.type === "tool_result") {
-                msgs.push({
-                    role: "tool",
-                    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
-                // has no logged tool result — patch it in when present
-                const lastAssistant = [...msgs].reverse().find((x) => x.role === "assistant" && x.tool_calls?.length);
-                if (lastAssistant?.tool_calls?.some((t) => t.function.name === "report_progress")) {
-                    for (const t of lastAssistant.tool_calls) {
-                        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();
-                }
-            }
-        }
-        // every assistant tool_call must be answered by a tool message, or the
-        // API rejects the sequence — close any holes left by meta tools (finish)
-        for (let i = 0; i < msgs.length; i++) {
-            const m = msgs[i];
-            if (m.role === "assistant" && m.tool_calls?.length) {
-                for (const t of m.tool_calls) {
-                    if (!msgs.slice(i + 1).some((x) => x.role === "tool" && x.tool_call_id === t.id)) {
-                        msgs.splice(i + 1, 0, {
-                            role: "tool",
-                            tool_call_id: t.id,
-                            content: t.function.name === "finish" ? `(round ended: ${m.content || "finished"})` : "(no result recorded)",
-                        });
-                        i++;
-                    }
-                }
-            }
-        }
-        // 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 });
+        const lineage = lineageOf(events);
+        if (!lineage.length)
+            return;
+        const last = lineage[lineage.length - 1];
+        const msgs = rebuildMessagesFrom(lineage);
         if (msgs.length > 0) {
             this.messages = msgs;
             this.currentBranch = last.branch;
@@ -313,6 +264,61 @@ export class Agent {
             });
         }
     }
+    /**
+     * Edit a previously-sent prompt: fork the conversation at that point,
+     * replace its text, and optionally fold everything that happened after it
+     * into a summary note on the new branch (ChatGPT-edit style). The agent
+     * must not be running — editing under a live loop would race its history.
+     */
+    async editPromptAt(eventId, text, tail) {
+        if (this.status === "running")
+            throw new Error("agent is running — stop it before editing history");
+        const all = await readEvents(this.log.filePath);
+        const target = all.find((e) => e.id === eventId);
+        if (!target || target.type !== "prompt")
+            throw new Error("event not found on this session (or not a prompt)");
+        const lineage = lineageOf(all);
+        const tIdx = lineage.findIndex((e) => e.id === eventId);
+        if (tIdx === -1)
+            throw new Error("prompt is not on this agent's current lineage");
+        const kept = lineage.slice(0, tIdx);
+        const dropped = lineage.slice(tIdx); // includes the original prompt itself
+        const msgs = rebuildMessagesFrom(kept);
+        if (tail === "summarize" && dropped.length > 0) {
+            try {
+                const droppedMsgs = rebuildMessagesFrom(dropped);
+                if (droppedMsgs.length) {
+                    const summary = await this.summarize(droppedMsgs);
+                    if (summary.trim()) {
+                        msgs.push({
+                            role: "user",
+                            content: "[harness] The conversation continued past this point on another timeline. " +
+                                `Notes from what happened there:\n\n${summary}`,
+                        });
+                    }
+                }
+            }
+            catch {
+                // summarization is best-effort; the fork proceeds without notes
+            }
+        }
+        msgs.push({ role: "user", content: text });
+        const newBranch = `br${this.branchCount()}${Date.now().toString(36).slice(-4)}`;
+        await this.log.append("fork", this.currentSession, newBranch, {
+            fromSession: this.currentSession,
+            fromBranch: this.currentBranch,
+            fromEvent: kept.at(-1)?.id ?? null,
+            newBranch,
+            reason: "prompt-edited",
+            droppedEvents: dropped.length,
+            tailMode: tail,
+        });
+        this.currentBranch = newBranch;
+        this.messages = msgs;
+        await this.log.append("prompt", this.currentSession, this.currentBranch, { source: "user", text });
+        bus.emit("update", { kind: "agent-update", agentId: this.opts.id });
+        return { droppedEvents: dropped.length, branch: newBranch };
+    }
     parseGoalFile(text) {
         // humans and agents may append their own status lines — latest wins
         const all = [...text.matchAll(/status:\s*(\w+)/gi)];
@@ -344,6 +350,12 @@ export class Agent {
         await this.writeGoalFile();
         await this.log.append("goal", this.currentSession, this.currentBranch, { event: "set", text });
     }
+    /** Persist the operator-maintained task list (todo.md). */
+    async setTodo(text, by = "human") {
+        this.todo = text;
+        await fs.writeFile(this.todoFile, text, "utf8");
+        await this.log.append("todo", this.currentSession, this.currentBranch, { event: "set", by });
+    }
     async setGoalStatus(status) {
         this.goal = { ...this.goal, status, updatedAt: new Date().toISOString() };
         await this.writeGoalFile();
@@ -363,19 +375,28 @@ export class Agent {
             model: this.opts.llm.model,
             provider: this.opts.provider,
             sessionDir: this.opts.sessionDir,
+            ctx: {
+                usedTokens: this.estimateTokens(),
+                compactAt: this.opts.contextTokenBudget,
+                window: this.opts.contextWindowTokens || 0,
+            },
             pendingPrompts: this.pendingPrompts.length,
+            todo: this.todo.slice(0, 32_000), // match set_todo's cap — no silent truncation
         };
     }
     /**
      * 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.
+     * the running loop. The very first prompt on a fresh boot also triggers the
+     * lazy session restore (before the mailbox is filled, so no duplicates).
      */
     enqueuePrompt(text, source = "user") {
-        this.pendingPrompts.push({ source, text });
-        void this.log
-            .append("prompt", this.currentSession, this.currentBranch, { source, text })
+        void this.ensureReady()
+            .then(() => {
+            this.pendingPrompts.push({ source, text });
+            return this.log.append("prompt", this.currentSession, this.currentBranch, { source, text });
+        })
             .then(() => bus.emit("update", { kind: "agent-update", agentId: this.opts.id }))
             .catch(() => { });
     }
@@ -400,6 +421,7 @@ export class Agent {
             return;
         this.stopRequested = false;
         void this.enqueue(async () => {
+            await this.ensureReady(); // lazy restore before the loop touches history
             this.setStatus("running", reason);
             this.stats.startedAt ??= new Date().toISOString();
         });
@@ -540,16 +562,43 @@ export class Agent {
                 turn: ++this.stats.turns,
             });
             // stream the assistant reply live to connected clients
-            const res = await this.llmCall(this.buildMessages(), allToolSpecs(), (s) => {
-                bus.emit("update", {
-                    kind: "llm-delta",
-                    agentId: this.opts.id,
-                    text: s.text,
-                    reasoning: s.reasoning,
+            let res;
+            try {
+                res = await this.llmCall(this.buildMessages(), allToolSpecs(), (s) => {
+                    bus.emit("update", {
+                        kind: "llm-delta",
+                        agentId: this.opts.id,
+                        text: s.text,
+                        reasoning: s.reasoning,
+                    });
                 });
-            });
+            }
+            catch (err) {
+                // user stop mid-stream: persist the partial output so the timeline
+                // keeps what was already visible (otherwise it silently vanishes)
+                const partial = err.partial;
+                if (this.stopRequested && partial && (partial.text || partial.reasoning)) {
+                    await this.log.append("message", this.currentSession, this.currentBranch, {
+                        role: "assistant",
+                        content: partial.text ?? "",
+                        reasoning: partial.reasoning,
+                        interrupted: true,
+                    });
+                    this.messages.push({ role: "assistant", content: partial.text ?? "" });
+                }
+                else if (this.stopRequested) {
+                    // nothing had streamed — leave an explicit marker so the log shows
+                    // why this prompt has no reply
+                    await this.log.append("system_note", this.currentSession, this.currentBranch, {
+                        event: "turn-interrupted",
+                        detail: "stopped before any output arrived",
+                    });
+                }
+                throw err;
+            }
             if (res.usage) {
                 this.stats.inputTokens += res.usage.inputTokens ?? 0;
+                this.stats.cachedInputTokens += res.usage.cachedInputTokens ?? 0;
                 this.stats.outputTokens += res.usage.outputTokens ?? 0;
                 await this.log.append("usage", this.currentSession, this.currentBranch, res.usage);
             }
@@ -561,6 +610,8 @@ export class Agent {
                 reasoning: res.reasoning,
             });
             this.messages.push(m);
+            this.turnsSinceProgress++;
+            this.activityChars += m.content?.length ?? 0;
             if (!m.tool_calls?.length)
                 return finished;
             for (const call of m.tool_calls) {
@@ -606,6 +657,25 @@ export class Agent {
                     });
                     continue;
                 }
+                if (call.function.name === "get_todo") {
+                    this.messages.push({
+                        role: "tool",
+                        tool_call_id: call.id,
+                        content: this.todo.trim() || "(todo.md is empty — no task list yet)",
+                    });
+                    continue;
+                }
+                if (call.function.name === "set_todo") {
+                    const a = safeParse(call.function.arguments);
+                    const content = String(a.content ?? "").slice(0, 32_000);
+                    await this.setTodo(content, "agent");
+                    this.messages.push({
+                        role: "tool",
+                        tool_call_id: call.id,
+                        content: "task list updated (visible to the operator)",
+                    });
+                    continue;
+                }
                 if (call.function.name === "read_memory") {
                     const mem = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
                     this.messages.push({
@@ -677,9 +747,14 @@ export class Agent {
         });
     }
     async maybeRequestProgress() {
-        if (Date.now() - this.lastProgressAt < this.opts.progressIntervalMs)
-            return;
+        const elapsedOk = Date.now() - this.lastProgressAt >= this.opts.progressIntervalMs;
+        const activityOk = this.activityChars >= this.opts.progressMinChars ||
+            this.turnsSinceProgress >= this.opts.progressMaxQuietTurns;
+        if (!elapsedOk || !activityOk)
+            return; // stalling provider → don't waste a turn asking
         this.lastProgressAt = Date.now();
+        this.activityChars = 0;
+        this.turnsSinceProgress = 0;
         const request = "[harness] Please give a brief progress report now: what you are doing, goal progress, " +
             "what you recently tried, any problems, and your next step. Keep it under 10 lines.";
         // log both sides so a session restore replays this exchange faithfully
@@ -815,6 +890,10 @@ export class Agent {
             next: str(a.next) || undefined,
             ts: new Date().toISOString(),
         };
+        // a report (voluntary or requested) restarts the progress gates
+        this.lastProgressAt = Date.now();
+        this.activityChars = 0;
+        this.turnsSinceProgress = 0;
         await this.log.append("progress", this.currentSession, this.currentBranch, this.latestProgress);
         bus.emit("update", { kind: "agent-update", agentId: this.opts.id });
     }
@@ -921,6 +1000,26 @@ function allToolSpecs() {
                 parameters: { type: "object", properties: {} },
             },
         },
+        {
+            type: "function",
+            function: {
+                name: "get_todo",
+                description: "Fetch the operator-maintained task list (todo.md). Check it when picking up work or when unsure what to do next.",
+                parameters: { type: "object", properties: {} },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "set_todo",
+                description: "Replace the operator-visible task list (todo.md) — e.g. check off finished items or restate what remains. Keep it terse.",
+                parameters: {
+                    type: "object",
+                    properties: { content: { type: "string" } },
+                    required: ["content"],
+                },
+            },
+        },
         {
             type: "function",
             function: {
@@ -962,3 +1061,120 @@ function safeParse(json) {
         return {};
     }
 }
+/** Walk parent links backwards from the newest event, then flip forward. */
+function lineageOf(events) {
+    if (events.length === 0)
+        return [];
+    const byId = new Map(events.map((e) => [e.id, e]));
+    const last = events[events.length - 1];
+    const lineage = [];
+    const seen = new Set();
+    for (let cur = last; cur; cur = cur.parent ? byId.get(cur.parent) : undefined) {
+        if (seen.has(cur.id))
+            break;
+        seen.add(cur.id);
+        lineage.push(cur);
+    }
+    lineage.reverse();
+    // the trailing fork event itself is bookkeeping, not conversation
+    while (lineage.length && lineage[0].type === "fork")
+        lineage.shift();
+    return lineage;
+}
+/**
+ * Replay ordered events into ChatMessages (shared by session restore and
+ * prompt-edit forks). Prompts logged inside an open tool batch are buffered
+ * until it closes, so user messages never split a tool_call/tool_result pair.
+ */
+function rebuildMessagesFrom(list) {
+    const msgs = [];
+    const META_TOOLS = new Set([
+        "finish", "report_progress", "set_goal", "get_goal",
+        "read_memory", "set_memory", "list_skills", "get_todo", "set_todo",
+    ]);
+    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 list) {
+        const d = e.data;
+        if (e.type === "prompt" && typeof d.text === "string") {
+            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";
+            const m = { role, content: typeof d.content === "string" ? d.content : "" };
+            if (Array.isArray(d.toolCalls) && d.toolCalls.length > 0) {
+                m.tool_calls = d.toolCalls.map((c) => ({
+                    id: c.id,
+                    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);
+        }
+        else if (e.type === "tool_call") {
+            // enrich the preceding assistant tool_calls with real arguments
+            const prev = [...msgs].reverse().find((x) => x.role === "assistant" && x.tool_calls?.some((t) => t.id === d.callId));
+            const tc = prev?.tool_calls?.find((t) => t.id === d.callId);
+            if (tc)
+                tc.function.arguments = JSON.stringify(d.args ?? {});
+        }
+        else if (e.type === "tool_result") {
+            msgs.push({
+                role: "tool",
+                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
+            // has no logged tool result — patch it in when present
+            const lastAssistant = [...msgs].reverse().find((x) => x.role === "assistant" && x.tool_calls?.length);
+            if (lastAssistant?.tool_calls?.some((t) => t.function.name === "report_progress")) {
+                for (const t of lastAssistant.tool_calls) {
+                    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();
+            }
+        }
+    }
+    // every assistant tool_call must be answered by a tool message, or the
+    // API rejects the sequence — close any holes left by meta tools (finish)
+    for (let i = 0; i < msgs.length; i++) {
+        const m = msgs[i];
+        if (m.role === "assistant" && m.tool_calls?.length) {
+            for (const t of m.tool_calls) {
+                if (!msgs.slice(i + 1).some((x) => x.role === "tool" && x.tool_call_id === t.id)) {
+                    msgs.splice(i + 1, 0, {
+                        role: "tool",
+                        tool_call_id: t.id,
+                        content: t.function.name === "finish" ? `(round ended: ${m.content || "finished"})` : "(no result recorded)",
+                    });
+                    i++;
+                }
+            }
+        }
+    }
+    // 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 });
+    return msgs;
+}