teapot-coding-agent 0.23.0 → 0.24.1

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) {
@@ -1629,18 +1864,37 @@ export class Agent {
                     const text = String(res.message.content ?? "");
                     const approved = /^APPROVED\b/i.test(text.trim());
                     const feedback = text.replace(/^(APPROVED|CHANGES-REQUIRED)\s*[:—-]?\s*/i, "").trim();
-                    await this.setGoalAudit(approved ? "approved" : "changes-required", feedback || "(no detail)");
+                    // #51: storing the literal "(no detail)" made the UI draw a card
+                    // whose whole content was the absence of a reason, and that same
+                    // string landed in goal.md for the right panel. An empty string is
+                    // the honest value: the auditor returned a verdict and no reason,
+                    // which every consumer can already render as "label only".
+                    await this.setGoalAudit(approved ? "approved" : "changes-required", feedback);
+                    // `operatorFacing: true` — the verdict is written for the TIMELINE
+                    // only. The audit ran in its own side conversation (a tools-less call
+                    // over buildMessages() + an audit prompt), so it was never in
+                    // `this.messages` and must not come back through a restore: doing so
+                    // injected an assistant turn that answers nothing into the model's
+                    // context, which providers answer with a 200 and no choices (#50).
+                    // The rejection feedback reaches the agent as a real prompt below.
                     await this.log.append("message", this.currentSession, this.currentBranch, {
                         role: "assistant",
+                        operatorFacing: true,
                         content: approved
                             ? `✅ completion audit: APPROVED — ${feedback}`
                             : `🔍 completion audit: CHANGES REQUIRED — ${feedback}`,
                     });
                     if (!approved) {
-                        // hand the gaps back to the worker as its next instruction
+                        // hand the gaps back to the worker as its next instruction.
+                        // #51: with the "(no detail)" placeholder gone, an empty verdict
+                        // would leave this prompt saying "address these gaps" and then
+                        // naming none — so restate the contract as the thing to re-check.
+                        const gaps = feedback.trim()
+                            ? feedback.slice(0, 2000)
+                            : `The auditor returned no specific gaps. Re-read the verification contract above and re-run it yourself, item by item, before finishing again:\n\n${this.goal.verify?.slice(0, 2000) || this.goal.text.slice(0, 2000)}`;
                         this.pendingPrompts.push({
                             source: "harness",
-                            text: `[harness] The completion audit REJECTED this finish. Address these gaps, then finish again with goalComplete=true:\n\n${feedback.slice(0, 2000)}`,
+                            text: `[harness] The completion audit REJECTED this finish. Address these gaps, then finish again with goalComplete=true:\n\n${gaps}`,
                         });
                     }
                 }
@@ -1675,7 +1929,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 +1951,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 +2195,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;
@@ -2435,13 +2705,28 @@ function rebuildMessagesFrom(list) {
                 msgs.push(mk());
         }
         else if (e.type === "message") {
-            // final summaries are operator-facing only — the live loop never puts
-            // them in model history, so restores must skip them too
-            if (d.final === true)
+            // Operator-facing rows are TIMELINE content, not conversation: the live
+            // loop never put them in `messages`, so a restore must not either.
+            // `final` is the finish() summary; `operatorFacing` covers harness notes
+            // such as the completion audit verdict. Replaying either produced a
+            // history shape no live run emits, and a provider given that answers
+            // 200 with zero choices (#50).
+            if (d.final === true || d.operatorFacing === true)
                 continue;
             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) {
+            const content = typeof d.content === "string" ? d.content : "";
+            const hasCalls = Array.isArray(d.toolCalls) && d.toolCalls.length > 0;
+            // A blank assistant turn that issued NO tool calls is an artefact of a
+            // kill mid-stream: the model streamed nothing, so the live run never had
+            // this turn, yet the restore replays it as a real utterance. sanitize()
+            // then rewrites blank assistant content to the literal "(no content)",
+            // so the agent is told it previously said a sentence it never said — a
+            // history shape no live run produces (#50). A blank turn that DID call
+            // tools is legitimate and must stay, or its results are orphaned.
+            if (role === "assistant" && !content && !hasCalls)
+                continue;
+            const m = { role, content };
+            if (hasCalls) {
                 m.tool_calls = d.toolCalls.map((c) => ({
                     id: c.id,
                     type: "function",

package/dist/agent/llm.js

@@ -7,6 +7,37 @@
  */
 import OpenAI from "openai";
 const clients = new WeakMap();
+/**
+ * Reasoning effort for a request body (#47).
+ *
+ * Kept local and deliberately conservative: the setting is only honoured when
+ * the endpoint is OpenRouter, the value is one OpenRouter documents, and the
+ * catalogue says this model advertises `reasoning_effort`. Support is far from
+ * universal (verified against the live /models endpoint: 196 of 462 models),
+ * so an unsent field is much safer than a wrong one.
+ *
+ * Implemented here rather than via model-meta to avoid an import cycle —
+ * model-meta already imports providerHeaders from this file.
+ */
+export function effortForRequest(cfg, supported = cfg.supportedParameters) {
+    const e = cfg.reasoningEffort;
+    if (!e || !REASONING_EFFORTS.includes(e))
+        return {};
+    if (!isOpenRouterEndpoint(cfg.baseUrl))
+        return {};
+    if (!supported?.includes("reasoning_effort"))
+        return {};
+    return { reasoning_effort: e };
+}
+function isOpenRouterEndpoint(baseUrl) {
+    try {
+        return /(^|\.)openrouter\.ai$/i.test(new URL(String(baseUrl ?? "")).host);
+    }
+    catch {
+        return false;
+    }
+}
+const REASONING_EFFORTS = ["minimal", "low", "medium", "high"];
 /**
  * OpenRouter app attribution (https://openrouter.ai/docs/app-attribution):
  * `HTTP-Referer` is the required identifier that puts teapot's usage on the
@@ -103,6 +134,7 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
             model: cfg.model,
             messages: sanitize(messages),
             ...(tools.length ? { tools } : {}),
+            ...effortForRequest(cfg),
         }, { signal });
         const raw = res.choices?.[0];
         const rm = raw?.message;
@@ -188,6 +220,7 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
             model: cfg.model,
             messages: sanitize(messages),
             ...(tools.length ? { tools } : {}),
+            ...effortForRequest(cfg),
             stream: true,
             // ask providers to include the final usage chunk in streaming mode
             // (OpenAI-compatible; harmless where unsupported)