teapot-coding-agent 0.8.0 → 0.10.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
@@ -168,8 +173,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)
 
@@ -213,10 +220,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

@@ -33,7 +33,17 @@ Session state is not injected into prompts — fetch it with tools instead:
 
 ## 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.
+- 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 {
@@ -46,6 +56,8 @@ export class Agent {
     currentBranch = "br0";
     goal = { text: "", status: "active", updatedAt: new Date().toISOString() };
     latestProgress = null;
+    /** set once the conversation has been restored (lazy: on first interaction) */
+    readyPromise = null;
     stats = {
         turns: 0,
         toolCalls: 0,
@@ -56,19 +68,34 @@ 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();
+    /** 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: "",
@@ -84,6 +111,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);
@@ -127,9 +155,35 @@ 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();
         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() {
@@ -179,83 +233,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 = [];
-        for (const e of lineage) {
-            const d = e.data;
-            if (e.type === "prompt" && typeof d.text === "string") {
-                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: "{}" },
-                    }));
-                }
-                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 : ""}`,
-                });
-            }
-            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" });
-                        }
-                    }
-                }
-            }
-        }
-        // 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++;
-                    }
-                }
-            }
-        }
+        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;
@@ -266,6 +248,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)];
@@ -316,14 +353,35 @@ 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,
         };
     }
-    /** 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. 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") {
-        return this.enqueue(async () => {
-            await this.log.append("prompt", this.currentSession, this.currentBranch, { source, text });
-            this.messages.push({ role: "user", content: 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(() => { });
+    }
+    /** 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() {
@@ -340,6 +398,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();
         });
@@ -372,9 +431,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);
@@ -458,6 +524,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)
@@ -471,14 +539,40 @@ 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.outputTokens += res.usage.outputTokens ?? 0;
@@ -492,6 +586,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) {
@@ -608,9 +704,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
@@ -746,6 +847,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 });
     }
@@ -764,6 +869,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();
     }
@@ -890,3 +998,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",
+    ]);
+    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;
+}

package/dist/agent/llm.js

@@ -96,6 +96,9 @@ export async function chat(cfg, messages, tools, signal) {
  */
 export async function chatStream(cfg, messages, tools, signal, onDelta) {
     let gotChunk = false;
+    // hoisted so the abort handler below can attach whatever streamed so far
+    let text = "";
+    let reasoning = "";
     try {
         const stream = await client(cfg).chat.completions.create({
             model: cfg.model,
@@ -103,8 +106,6 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
             ...(tools.length ? { tools } : {}),
             stream: true,
         }, { signal });
-        let text = "";
-        let reasoning = "";
         const calls = {};
         let finishReason;
         let usage;
@@ -155,6 +156,11 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
         // provider may not support streaming at all — one clean fallback
         if (!gotChunk && !signal?.aborted)
             return chat(cfg, messages, tools, signal);
+        // user interrupt: hand back whatever streamed so far so the harness can
+        // keep the partial output visible instead of losing it
+        if (signal?.aborted && (text || reasoning)) {
+            err.partial = { text, reasoning };
+        }
         throw err;
     }
 }

package/dist/agent/skills.js

@@ -64,11 +64,24 @@ export async function discoverSkills(roots) {
             const name = parsed.meta.name || e.name;
             if (byName.has(name))
                 continue; // higher-priority root already defined it
+            // collect bundled files (helper scripts, templates, ...) next to SKILL.md
+            let files = [];
+            try {
+                const siblings = await fs.readdir(path.join(root.dir, e.name), { withFileTypes: true });
+                files = siblings
+                    .filter((f) => f.isFile() && f.name !== SKILL_FILE && !f.name.startsWith("."))
+                    .map((f) => f.name)
+                    .sort();
+            }
+            catch {
+                /* unreadable dir → no bundled files */
+            }
             byName.set(name, {
                 name,
                 description: parsed.meta.description || "",
                 source: root.source,
                 filePath,
+                files,
             });
         }
     }