teapot-coding-agent 0.23.0 → 0.24.0

package/dist/acp/adapter.js

@@ -0,0 +1,198 @@
+import { readEvents } from "../log/events.js";
+import path from "node:path";
+export const ACP_PROTOCOL_VERSION = 1;
+/** JSON-RPC error codes we use (the standard set plus JSON-RPC's own). */
+const PARSE_ERROR = -32700;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+/**
+ * Run the ACP adapter until stdin closes.
+ *
+ * Kept as a class rather than free functions so the session map and the pending
+ * request bookkeeping have somewhere to live, and so it is directly testable
+ * with an in-memory stream pair.
+ */
+export class AcpAdapter {
+    master;
+    input;
+    output;
+    defaultCwd;
+    sessions = new Map();
+    /** id -> notification params, so a prompt turn can stream updates */
+    turnUpdates = new Map();
+    buffer = "";
+    nextSession = 1;
+    initialized = false;
+    constructor(opts) {
+        this.master = opts.master;
+        this.input = opts.input ?? process.stdin;
+        this.output = opts.output ?? process.stdout;
+        this.defaultCwd = opts.defaultCwd ?? process.cwd();
+    }
+    /** Attach to the stream. Resolves when stdin ends. */
+    listen() {
+        return new Promise((resolve) => {
+            this.input.on("data", (chunk) => this.onData(String(chunk)));
+            this.input.on("end", () => resolve());
+            this.input.on("error", () => resolve());
+            if (typeof this.input.resume === "function")
+                this.input.resume();
+        });
+    }
+    /* ---------- transport ---------- */
+    onData(chunk) {
+        this.buffer += chunk;
+        // NDJSON: one JSON object per line
+        let nl;
+        while ((nl = this.buffer.indexOf("\n")) >= 0) {
+            const line = this.buffer.slice(0, nl).trim();
+            this.buffer = this.buffer.slice(nl + 1);
+            if (line)
+                this.handleLine(line);
+        }
+    }
+    handleLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            // a parse error has no id to answer
+            this.send({ jsonrpc: "2.0", id: null, error: { code: PARSE_ERROR, message: "invalid JSON" } });
+            return;
+        }
+        void this.dispatch(msg);
+    }
+    send(res) {
+        this.output.write(JSON.stringify(res) + "\n");
+    }
+    notify(method, params) {
+        this.send({ jsonrpc: "2.0", method, params });
+    }
+    ok(id, result) {
+        this.send({ jsonrpc: "2.0", id, result });
+    }
+    fail(id, code, message) {
+        this.send({ jsonrpc: "2.0", id, error: { code, message } });
+    }
+    /* ---------- dispatch ---------- */
+    async dispatch(msg) {
+        const { method, id, params } = msg;
+        const isNotification = id === undefined || id === null;
+        try {
+            switch (method) {
+                case "initialize":
+                    return this.ok(id ?? null, this.initialize());
+                case "authenticate":
+                    return this.ok(id ?? null, {});
+                case "session/new":
+                    return this.ok(id ?? null, await this.newSession(params));
+                case "session/load":
+                    return this.ok(id ?? null, await this.loadSession(params));
+                case "session/prompt":
+                    return await this.prompt(id ?? null, params);
+                case "session/cancel":
+                    this.cancel(params);
+                    if (!isNotification)
+                        return this.ok(id ?? null, {});
+                    return;
+                default:
+                    // notifications for unknown methods get NO response at all
+                    if (isNotification)
+                        return;
+                    return this.fail(id ?? null, METHOD_NOT_FOUND, `unknown method: ${method}`);
+            }
+        }
+        catch (err) {
+            if (isNotification)
+                return; // never answer a notification
+            return this.fail(id ?? null, INTERNAL_ERROR, err.message);
+        }
+    }
+    initialize() {
+        this.initialized = true;
+        return {
+            protocolVersion: ACP_PROTOCOL_VERSION,
+            // Only capabilities we actually implement. Terminal/fs are deliberately
+            // absent: a client calls what we advertise, and a partial implementation
+            // would be worse than an honest omission.
+            agentCapabilities: { loadSession: true, promptCapabilities: { image: false, audio: false } },
+            authMethods: [],
+        };
+    }
+    /* ---------- sessions ---------- */
+    async newSession(params) {
+        const p = (params ?? {});
+        const cwd = p.cwd ? path.resolve(String(p.cwd)) : this.defaultCwd;
+        const id = `acp-${this.nextSession++}`;
+        const agent = await this.master.addAgent({ id, workspace: cwd }, { persist: false, fresh: true });
+        this.sessions.set(id, { id, cwd, agent });
+        return { sessionId: id };
+    }
+    async loadSession(params) {
+        const p = (params ?? {});
+        const id = String(p.sessionId ?? "");
+        const existing = this.sessions.get(id);
+        if (existing)
+            return null; // already live
+        const cwd = p.cwd ? path.resolve(String(p.cwd)) : this.defaultCwd;
+        // resuming means the agent's own log is restored, not a fresh session
+        const agent = await this.master.addAgent({ id, workspace: cwd }, { persist: false, fresh: false });
+        this.sessions.set(id, { id, cwd, agent });
+        return null;
+    }
+    cancel(params) {
+        const p = (params ?? {});
+        const s = p.sessionId ? this.sessions.get(String(p.sessionId)) : undefined;
+        s?.agent.stop("cancelled via ACP");
+    }
+    /* ---------- prompt turn ---------- */
+    async prompt(id, params) {
+        const p = (params ?? {});
+        const s = p.sessionId ? this.sessions.get(String(p.sessionId)) : undefined;
+        if (!s)
+            return this.fail(id, INVALID_PARAMS, `unknown session: ${String(p.sessionId)}`);
+        const text = (p.prompt ?? [])
+            .map((c) => String(c?.text ?? ""))
+            .join("\n")
+            .trim();
+        if (!text)
+            return this.fail(id, INVALID_PARAMS, "prompt must contain text");
+        this.turnUpdates.set(id, { sessionId: s.id });
+        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 });
+        }
+        finally {
+            this.turnUpdates.delete(id);
+        }
+    }
+    /** Stream a session's events to the client as session/update notifications. */
+    async drainOnce(sessionId, afterSeq = 0) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            return afterSeq;
+        const events = await readEvents(s.agent.log.filePath).catch(() => []);
+        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 max = events.reduce((m, e) => Math.max(m, e.seq), afterSeq);
+        return max;
+    }
+    get initialized_() {
+        return this.initialized;
+    }
+}

package/dist/agent/agent.js

@@ -11,8 +11,38 @@ import path from "node:path";
 import { EventLog, readEvents } from "../log/events.js";
 import { chat, chatStream } from "./llm.js";
 import { executeTool, toolSpecs, currentSkills, safeJoin, isContextOverflow, hasRunningBgShells } from "./tools.js";
-import { skillRootsFingerprint } from "./skills.js";
+import { skillRootsFingerprint, foreignSkillRoots } from "./skills.js";
 import { bus } from "../bus.js";
+/**
+ * Harness nudges, named and exported so they can be asserted on directly.
+ *
+ * Both were fixed for a reason invisible in the prose:
+ *
+ *  - AUTO_CONTINUE_NUDGE (#43) used to say only "continue working". The model
+ *    was never told HOW TO STOP, so it worked forever: it replied in prose, the
+ *    loop saw an active goal and no finish(), and nudged again. The sub-agent
+ *    variant already named finish() — the ROOT one did not.
+ *  - PROGRESS_REQUEST (#45) used to DESCRIBE the report instead of asking for
+ *    the tool, so the model answered in prose, then — not knowing that had
+ *    satisfied the request — sent a voluntary report_progress right after, and
+ *    every requested report appeared TWICE on the timeline.
+ */
+export const AUTO_CONTINUE_NUDGE = "Continue working toward the current goal. If you are blocked, explain why briefly. " +
+    // name the tool explicitly, the way the sub-agent nudge already does
+    "When the goal is genuinely met — or truly blocked — call finish() " +
+    "(finish(goalComplete=true) when met, finish(goalComplete=false) when blocked) " +
+    "instead of replying in prose; prose here does not stop the loop.";
+export const PROGRESS_REQUEST = 
+// The leading sentence is kept VERBATIM: it is what existing harness prompts,
+// tests and any operator muscle-memory key off. #45 changed the INSTRUCTION
+// (call the tool, don't answer in prose), not the identification of the 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. " +
+    // ask for the TOOL, not prose — a prose answer left the model unsure whether it
+    // had satisfied the request, so it sent a voluntary report_progress right after
+    // and every requested report appeared TWICE on the timeline (#45)
+    "Record it with the report_progress TOOL (doing, goalStatus, recent, problems, next) — " +
+    "call that tool; do NOT answer in prose, which would just duplicate this request.";
 /**
  * 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
@@ -114,6 +144,14 @@ export class Agent {
     modelPricing;
     /** messages.length right after the last successful compaction */
     compactedAtLen = 0;
+    /**
+     * A sub-agent's latest bare text turn, held back until the round ends.
+     * Models usually end a sub-agent task with a plain message instead of calling
+     * finish(); only finish() forwards a report to the parent, so without this the
+     * parent got nothing (#42). Held (not sent immediately) so a mid-task
+     * narration never pre-empts a real finish() summary.
+     */
+    pendingSubReport = "";
     /** live compaction phase for UI progress ("summarizing"/"harvesting") */
     compactPhase = "";
     /** set by ask_user: the loop is parked until the operator replies */
@@ -132,6 +170,10 @@ export class Agent {
             autoContinue: true,
             continueDelayMs: 15_000,
             autoCompact: true,
+            // #47: no effort and no catalogue entry means "provider default" — the
+            // effort field is then never sent, which is the safe default
+            reasoningEffort: "",
+            supportedParameters: [],
             maxConsecutiveToolErrors: 5,
             maxTurnsPerRound: 200,
             onError: "stop",
@@ -160,6 +202,13 @@ export class Agent {
         this.skillRoots = [
             { dir: path.join(opts.workspace, "skills"), source: "workspace" },
             ...(opts.globalSkillsDir ? [{ dir: opts.globalSkillsDir, source: "global" }] : []),
+            // OTHER HARNESSES' skill directories (#28). The SKILL.md format is shared,
+            // so these are readable as-is — verified against real third-party skills
+            // (terminalskills/skills, trailofbits/skills, …). They sit below the
+            // workspace and teapot's own global dir so a project always wins, and
+            // missing directories are skipped silently. Paths are the documented
+            // native locations plus the cross-tool ones several tools also read.
+            ...foreignSkillRoots(opts.workspace),
             // shipped-with-package skills: lowest priority, always discoverable
             ...(opts.bundledSkillsDir ? [{ dir: opts.bundledSkillsDir, source: "bundled" }] : []),
         ];
@@ -192,6 +241,24 @@ export class Agent {
      * skill was added, edited or removed (save_skill writes one, so a
      * self-created skill still shows up on the very next turn).
      */
+    /**
+     * Render the skill catalogue for the system prompt (#31).
+     *
+     * Name + description only, one line each — the full SKILL.md is what
+     * load_skill() is for, and this block goes into EVERY request of the session,
+     * so it has to stay small. The description is what the model matches its task
+     * against, so a skill with a poor description is effectively undiscoverable;
+     * that is worth knowing when authoring one.
+     */
+    skillCatalogueText() {
+        if (!this.skillsCache.length)
+            return "";
+        const lines = this.skillsCache.map((s) => {
+            const desc = (s.description || "(no description)").replace(/\s+/g, " ").slice(0, 200);
+            return `- ${s.name}: ${desc}`;
+        });
+        return lines.join("\n");
+    }
     async refreshSkills() {
         try {
             const stamp = await skillRootsFingerprint(this.skillRoots);
@@ -206,7 +273,16 @@ export class Agent {
     }
     callLlm(messages, tools, onDelta) {
         const fn = this.opts.chatFn ?? chatStream;
-        return fn(this.opts.llm, messages, tools, this.abort?.signal, onDelta);
+        // #47: carry the effort setting + the model's advertised capabilities into
+        // the request config. chat() applies effortForRequest(), which sends the
+        // field ONLY for OpenRouter endpoints whose catalogue lists support.
+        return fn({
+            ...this.opts.llm,
+            ...(this.opts.reasoningEffort ? { reasoningEffort: this.opts.reasoningEffort } : {}),
+            ...(this.opts.supportedParameters
+                ? { supportedParameters: this.opts.supportedParameters }
+                : {}),
+        }, messages, tools, this.abort?.signal, onDelta);
     }
     /** expose id for metrics */
     opts_id() {
@@ -566,7 +642,13 @@ export class Agent {
      * must not be running — editing under a live loop would race its history.
      */
     async editPromptAt(eventId, text, tail) {
-        if (this.status === "running")
+        // "running" is not the only live state: parkForTool() rewrites the status to
+        // "idle" while the loop is still very much alive inside a parked tool
+        // (wait_children does this), and queued prompts have not been consumed yet.
+        // Editing underneath either of those replaces the very `messages` array the
+        // agent is about to resume into, so its old-branch work kept running
+        // against the new branch (#38).
+        if (this.status === "running" || this.parkedByTool || this.pendingPrompts.length)
             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);
@@ -599,7 +681,17 @@ export class Agent {
         }
         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, {
+        // Quiesce BEFORE rewriting history: an in-flight LLM call, a parked tool or
+        // a queued prompt would otherwise resume into the NEW messages array and
+        // keep running the old branch's work here (#38). Mirrors stop(), which is
+        // the only other place that cancels this state.
+        await this.quiesceForHistoryEdit();
+        // The fork event must be appended while currentBranch is still the OLD
+        // one. EventLog links parents PER BRANCH (lastByBranch), so appending it
+        // under the new branch gave it parent:null — severing the chain, and
+        // lineageOf() then returned only the post-fork events, so a restart rebuilt
+        // the history with none of the pre-edit context (#38).
+        await this.log.append("fork", this.currentSession, this.currentBranch, {
             fromSession: this.currentSession,
             fromBranch: this.currentBranch,
             fromEvent: kept.at(-1)?.id ?? null,
@@ -608,12 +700,49 @@ export class Agent {
             droppedEvents: dropped.length,
             tailMode: tail,
         });
+        // Seed the new branch's parent link to the fork event just written, so its
+        // first event chains across instead of starting a disconnected parent:null
+        // history (#38).
+        this.log.seedBranch(newBranch, this.log.lastEventId(this.currentBranch));
         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 };
     }
+    /**
+     * Cancel everything that could resume against the history we are about to
+     * replace, then wait for the loop to actually stop.
+     *
+     * An edit rewinds the conversation, so any work still in flight belongs to
+     * the branch being discarded: an LLM call whose result would append to the
+     * new messages, a parked tool, and queued prompts that were never delivered
+     * (#38). stopRequested is set and cleared around the wait so the agent is
+     * usable again once the edit lands.
+     */
+    async quiesceForHistoryEdit() {
+        if (!this.stopRequested) {
+            this.stopRequested = true;
+            this.abort?.abort(); // interrupt an in-flight LLM call
+            this.toolAbort.abort(); // kill subprocesses / interrupt a parked tool
+            this.wake?.(); // release wait_children
+            try {
+                await this.settled();
+            }
+            catch {
+                /* the loop is being abandoned; its errors are not ours to report */
+            }
+            this.parkedByTool = false;
+            this.pendingPrompts = []; // undelivered prompts belong to the old branch
+            this.stopRequested = false;
+            // a fresh signal: toolCtx holds a copy of the reference, so republish
+            if (this.toolAbort.signal.aborted) {
+                this.toolAbort = new AbortController();
+                this.toolCtx.signal = this.toolAbort.signal;
+            }
+            this.bgExits = []; // old-branch job exits must not be folded in
+        }
+    }
     parseGoalFile(text) {
         // humans and agents may append their own status lines — latest wins
         const all = [...text.matchAll(/status:\s*(\w+)/gi)];
@@ -761,6 +890,9 @@ export class Agent {
             stats: { ...this.stats, costUsd: this.modelPricing ? this.stats.costUsd : undefined },
             model: this.opts.llm.model,
             provider: this.opts.provider,
+            // #47: the effort in force, and whether this model can take one at all
+            ...(this.opts.reasoningEffort ? { reasoningEffort: this.opts.reasoningEffort } : {}),
+            effortSupported: (this.opts.supportedParameters ?? []).includes("reasoning_effort"),
             sessionDir: this.opts.sessionDir,
             ctx: {
                 usedTokens: this.lastUsage?.input ?? this.estimateTokens(),
@@ -904,8 +1036,22 @@ export class Agent {
         // suppressed while bg jobs are alive) — its exit IS the wake-up call.
         // Without this the report would sit unread until the operator poked
         // the agent. Stopped agents stay stopped (a deliberate human stop).
-        if (this.status === "idle" && !this.stopRequested) {
-            this.start(`background job ${info.id} finished`);
+        //
+        // Checking status once is NOT enough: the exit can land in the window
+        // between the loop's hasRunningBgShells() check (which breaks the round
+        // out) and the loop actually flipping to idle. The callback then sees
+        // "running", skips start(), and the agent goes idle with the report
+        // unread — wedged until a human pokes it. So remember that the loop was
+        // still winding down, and re-check once it has settled.
+        const windingDown = this.status === "running";
+        if (!this.stopRequested && (this.status === "idle" || windingDown)) {
+            // park the decision until the in-flight round has actually settled
+            void this.enqueue(async () => {
+                if (this.stopRequested)
+                    return; // a stop raced us — respect it
+                if (this.status === "idle")
+                    this.start(`background job ${info.id} finished`);
+            });
         }
     }
     /** fold queued background-exit reports into the next LLM call (once each) */
@@ -1030,6 +1176,18 @@ export class Agent {
                     });
                     break;
                 }
+                // A SUB-AGENT that ended its round on a bare message (no finish call)
+                // still owes the parent a report — nothing else will carry it (#42).
+                // Emitted HERE, after the loop, so a real finish() on a later turn
+                // always wins and this never pre-empts a better summary.
+                if (this.pendingSubReport) {
+                    const report = this.pendingSubReport;
+                    this.pendingSubReport = "";
+                    if (!finished) {
+                        await this.handleFinish(JSON.stringify({ goalComplete: true, summary: report }));
+                        finished = true; // it IS finished now — don't auto-nudge a reporter
+                    }
+                }
                 // auto-continue only makes sense with an active goal to continue toward
                 if (finished ||
                     !this.opts.autoContinue ||
@@ -1047,7 +1205,7 @@ export class Agent {
                 const isSub = !!this.opts.parent;
                 const nudge = isSub
                     ? `[harness] Auto-nudge. Re-anchor on YOUR task — and only that:\n\n${this.goal.text.slice(0, 1500)}\n\nThe inherited conversation is reference only; other agents own any older tasks in it. If your task is complete, call finish() now instead of continuing. If blocked, explain why briefly and finish().`
-                    : "Continue working toward the current goal. If you are blocked, explain why briefly.";
+                    : AUTO_CONTINUE_NUDGE;
                 await this.log.append("prompt", this.currentSession, this.currentBranch, {
                     source: "harness",
                     text: nudge,
@@ -1261,12 +1419,63 @@ export class Agent {
             this.messages.push(m);
             this.turnsSinceProgress++;
             this.activityChars += m.content?.length ?? 0;
-            if (!m.tool_calls?.length)
+            // A round that ends with a plain assistant message and NO tool calls is
+            // the end of the agent's work. For a ROOT agent that is just "done" — but
+            // for a SUB-AGENT it means the work is over and the parent is waiting.
+            //
+            // Models overwhelmingly prefer writing their report as the final message
+            // over calling finish(), and only handleFinish() emits the `final: true`
+            // event that onChildEvent() forwards to the parent. So that habit silently
+            // cost the parent the ENTIRE result (#42) — the report existed only in the
+            // child's own log, which the parent's model context never replays.
+            // Harvest it here so both paths share one code path.
+            if (!m.tool_calls?.length) {
+                // A turn with no tool calls and real text is how models overwhelmingly
+                // signal "I'm done" — far more often than by calling finish(), which
+                // the spawn directive asks for but they routinely ignore.
+                //
+                // Two things were wrong (#42):
+                //  1. only handleFinish() emits the `final: true` event that
+                //     onChildEvent() forwards to the parent, so a sub-agent that ended
+                //     with a plain message sent the parent NOTHING — the report lived
+                //     only in the child's log, which the parent's context never
+                //     replays;
+                //  2. the round then returned "not finished" with an active goal, so
+                //     auto-continue re-nudged and the child looped forever (measured:
+                //     257 consecutive turns) re-reporting the same text.
+                //
+                // A bare message might be a mid-task narration though — sub-agents
+                // often say "here's what I found so far…" and call finish() later with
+                // a better summary. So do NOT report yet: remember it and give the child
+                // ONE more turn to call finish() properly. The harness nudge makes that
+                // turn explicit, so a child that just wanted to narrate ends here (and
+                // its held report is forwarded by the loop's end-of-round path), while
+                // a child that has a real summary delivers it instead. A real finish()
+                // clears the held note, so it is forwarded exactly once (#42).
+                if (this.opts.parent) {
+                    if (this.pendingSubReport) {
+                        // already offered a turn after a bare message — take the held report
+                        this.messages.push({
+                            role: "user",
+                            content: "[harness] Report delivered. If this IS your final answer, call finish() now with a summary for your parent; otherwise continue the task.",
+                        });
+                    }
+                    else {
+                        this.pendingSubReport = (m.content ?? "").trim();
+                        this.messages.push({
+                            role: "user",
+                            content: "[harness] If you are done, call finish() with a summary for your parent so it receives your report. Otherwise continue the task.",
+                        });
+                    }
+                    continue; // one more turn before we treat the message as final
+                }
                 return finished;
+            }
             for (const call of m.tool_calls) {
                 if (this.stopRequested)
                     return finished;
                 if (call.function.name === "finish") {
+                    this.pendingSubReport = ""; // the real summary supersedes it
                     await this.handleFinish(call.function.arguments);
                     // surface still-running children so the operator knows work may
                     // continue after this agent goes idle
@@ -1520,9 +1729,16 @@ export class Agent {
     }
     /** AGENTS.md content cached for the session (empty string = none/read-failed) */
     agentsMd = "";
+    /** captured once, with the rest of the session-frozen context */
     agentsMdLoaded = false;
     /** one-time workspace listing injected with the system prompt */
     wsSnapshot = "";
+    /**
+     * one-time catalogue of available skills, injected with the system prompt
+     * (#31). Built once alongside wsSnapshot so the prompt stays byte-identical
+     * for the session and the provider prefix cache survives.
+     */
+    skillCatalogue = "";
     systemPrompt() {
         if (!this.agentsMdLoaded) {
             this.agentsMdLoaded = true;
@@ -1593,6 +1809,9 @@ export class Agent {
                     this.agentsMd = "";
                 }
             }
+            // #31: capture the skill catalogue in the SAME one-shot block, so the
+            // system prompt stays byte-identical for the session (prefix cache).
+            this.skillCatalogue = this.skillCatalogueText();
         }
         let sys = SYSTEM_TEMPLATE;
         if (this.agentsMd.trim()) {
@@ -1601,6 +1820,22 @@ export class Agent {
         if (this.wsSnapshot) {
             sys += `\n\n## Workspace snapshot (top level)\n${this.wsSnapshot}\nUse list_dir/read_file for anything deeper — do NOT list again what is already here.`;
         }
+        // #31: the catalogue of AVAILABLE SKILLS. The prompt previously named the
+        // skill TOOLS but never the skills themselves, so the only way to discover
+        // one was to spend a tool call on list_skills() — and a model that does not
+        // know a skill exists will never think to look.
+        //
+        // Appended ONCE, in the same one-shot block as AGENTS.md and the workspace
+        // snapshot, so SYSTEM_TEMPLATE stays byte-identical for the session and the
+        // provider prefix cache survives (#14's constraint). list_skills() remains
+        // for the full detail (a skill saved mid-session shows up there).
+        if (this.skillCatalogue) {
+            sys +=
+                `\n\n## Skills available in this workspace\n${this.skillCatalogue}\n` +
+                    `Load one with load_skill(name, instructions) when its description matches your task — ` +
+                    `pass what you want done so the instructions arrive with the playbook. ` +
+                    `list_skills() shows the full detail.`;
+        }
         return sys;
     }
     async handleFinish(argsJson) {
@@ -1675,7 +1910,11 @@ export class Agent {
                 // the raw content is what matters here, and cap hard: these can be huge
                 line = `[${who}] ${(m.content ?? "").trim().slice(0, 1200)}`;
             }
-            recent.unshift(line.slice(0, 1500));
+            // A generous cap, but not unbounded: one runaway turn must not blow up
+            // the parent's context. The old 1500 char clip cut findings in half —
+            // a review's conclusions routinely live past that mark (#42) — and this
+            // text is bounded by 6 turns, so the worst case is ~120k chars.
+            recent.unshift(line.slice(0, 20_000));
         }
         await this.log.append("message", this.currentSession, this.currentBranch, {
             role: "assistant",
@@ -1693,8 +1932,7 @@ export class Agent {
         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.";
+        const request = PROGRESS_REQUEST;
         // log both sides so a session restore replays this exchange faithfully
         await this.log.append("prompt", this.currentSession, this.currentBranch, {
             source: "harness",
@@ -1938,8 +2176,21 @@ export class Agent {
             // fallback: drop the oldest half without LLM help so work can continue
             mode = "truncate";
             summarizedCount = 0;
-            const halfCut = this.safeCut(Math.floor(oldCount / 2));
+            // Cut at a safe boundary, but never at index 0 — that would drop the
+            // ENTIRE history (including the prompt just delivered) and leave the agent
+            // with nothing. On a short history floor(oldCount/2) can round to 0, and
+            // the old code then bailed out silently: compaction "ran", reported
+            // nothing, and the context stayed over budget, so the very next provider
+            // call overflowed — the "unstable after compact" report (#8). Always drop
+            // at least one message, and say so.
+            const halfCut = this.safeCut(Math.max(1, Math.floor(oldCount / 2)));
             if (halfCut <= 0) {
+                // nothing in the prefix is safe to drop (e.g. it is all tool results).
+                // Report it instead of pretending compaction happened.
+                await this.log.append("system_note", this.currentSession, this.currentBranch, {
+                    event: "context-compaction-skipped",
+                    reason: "summarize failed and no safe prefix to truncate",
+                });
                 this.compactPhase = "";
                 bus.emit("update", { kind: "compaction-progress", agentId: this.opts.id, phase: "done" });
                 return;