teapot-coding-agent 0.29.7 → 0.29.9

package/dist/acp/adapter.js

@@ -4,10 +4,9 @@ export const ACP_PROTOCOL_VERSION = 1;
 /**
  * How often a running turn is drained for new events.
  *
- * The web UI gets a WebSocket push; ACP has no such channel here, so the turn
- * is streamed by polling the agent's own log. 150ms is well under the ~60ms
- * render tick a human notices, and the read is a tail of a file this process
- * is already appending to — cheap enough to be invisible next to an LLM call.
+ * ACP has no push channel, so the turn is streamed by polling the agent's own
+ * log. 150ms is well under the ~60ms render tick a human notices, and the read is
+ * a tail of a file this process is already appending to.
  */
 const STREAM_POLL_MS = 150;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -16,18 +15,11 @@ 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.
- */
 /* ---------- streaming: log events → session/update notifications ---------- */
 /**
  * ACP `ToolCall.kind` for a teapot tool name.
  *
- * The schema's own enum (verified against schema/v1/schema.json, not memory):
+ * The schema's own enum (verified against schema/v1/schema.json):
  * read, edit, delete, move, search, execute, fetch, think, switch_mode, other,
  * description. Editors use this to pick an icon and to decide whether the call
  * mutates anything, so mapping our tools onto it is worth doing properly.
@@ -81,22 +73,18 @@ function toolLocation(name, args, workspace) {
     return [{ path: abs, ...(Number.isFinite(line) && line > 0 ? { line } : {}) }];
 }
 /**
- * Turn one logged event into the session/update payload for it, or null when
- * the event has no ACP equivalent (and must therefore NOT be invented into
- * one).
+ * Turn one logged event into the session/update payload for it, or null when the
+ * event has no ACP equivalent (and must therefore NOT be invented into one).
  *
- * Pure and exported so the mapping is testable without a transport, which is
- * how the previous scaffold went unverified: `drainOnce` existed, was never
- * called, and nothing noticed.
+ * Exported so the mapping is testable without a transport.
  */
 export function updateForEvent(e, opts) {
     const d = (e.data ?? {});
     switch (e.type) {
         case "message": {
             // The completion AUDIT's verdict and the operator-facing summary are
-            // timeline content, not something the agent said to the model. They are
-            // marked precisely so the web feed can skip them; an editor must not be
-            // shown an agent speaking a harness message.
+            // timeline content, not something the agent said to the model; an editor
+            // must not be shown an agent speaking a harness message.
             if (d.final === true || d.operatorFacing === true)
                 return null;
             const text = String(d.content ?? "");
@@ -245,9 +233,8 @@ export class AcpAdapter {
         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.
+            // Only capabilities we actually implement: a client calls what we
+            // advertise, so a partial implementation would be worse than omission.
             agentCapabilities: { loadSession: true, promptCapabilities: { image: false, audio: false } },
             authMethods: [],
         };
@@ -278,9 +265,8 @@ export class AcpAdapter {
         const s = p.sessionId ? this.sessions.get(String(p.sessionId)) : undefined;
         if (!s)
             return;
-        // Remember it HERE rather than asking the Agent whether it was stopped:
-        // the flag that says so is private, and the adapter already knows — it is
-        // the component that answered the cancel notification.
+        // The Agent's own "stopped" flag is private, and this adapter is the
+        // component that answered the cancel notification anyway.
         this.cancelled.add(s.id);
         s.agent.stop("cancelled via ACP");
     }
@@ -298,10 +284,7 @@ export class AcpAdapter {
             return this.fail(id, INVALID_PARAMS, "prompt must contain text");
         this.turnUpdates.set(id, { sessionId: s.id });
         this.cancelled.delete(s.id); // a cancel is per-turn, not per-session
-        // Stream the turn as it happens. The editor shows the reply and each tool
-        // call appear as they happen; without this the client sees NOTHING until
-        // the whole turn finishes, which is the difference between a usable agent
-        // and a black box that eventually prints an answer.
+        // Without streaming, the client sees NOTHING until the whole turn finishes.
         const abort = new AbortController();
         const stream = this.streamTurn(s.id, abort.signal).catch(() => { });
         try {
@@ -324,7 +307,7 @@ export class AcpAdapter {
             this.turnUpdates.delete(id);
         }
     }
-    /** Stream a session's events to the client as session/update notifications. */
+    /** drain a session's log tail into session/update notifications */
     async drainOnce(sessionId, afterSeq = 0) {
         const s = this.sessions.get(sessionId);
         if (!s)
@@ -334,34 +317,28 @@ export class AcpAdapter {
             if (e.seq <= afterSeq)
                 continue;
             const update = updateForEvent(e, { workspace: s.cwd });
-            // null means "no ACP equivalent" — state flips, goals, notes. Staying
-            // silent is correct; the old code invented a tool_call for every one.
+            // null means "no ACP equivalent" — state flips, goals, notes
             if (update)
                 this.notify("session/update", { sessionId, update });
         }
-        // Advance past EVERY event we read, including the ones we did not emit, so
-        // an un-emitted event is not reconsidered on the next poll.
+        // Advance past EVERY event read, emitted or not, so nothing is reconsidered
+        // on the next poll.
         return events.reduce((m, e) => Math.max(m, e.seq), afterSeq);
     }
     /**
      * Poll one session until it settles, streaming each batch as it appears.
      *
-     * Polling the JSONL rather than subscribing to the bus is deliberate: the log
-     * is the agent's own record, so a listener attached at the wrong moment can
-     * miss the start of a reply, and a crash mid-turn leaves the file as the one
-     * complete account of what happened. It also means a resumed session replays
-     * exactly the same updates.
+     * The JSONL log rather than the bus is deliberate: a bus listener attached at
+     * the wrong moment can miss the start of a reply, and after a crash mid-turn
+     * the file is the one complete account of what happened. It also means a
+     * resumed session replays exactly the same updates.
      */
     async streamTurn(sessionId, signal) {
-        // Start from the CURRENT tail: everything before this prompt belongs to
-        // earlier turns, and a resumed session has already been replayed.
+        // Everything before this prompt belongs to earlier turns.
         let cursor = await this.logTail(sessionId);
-        // NOTE the drain happens BEFORE the abort check, not after it. A short
-        // turn — a cached model, a tiny task, a failing endpoint that gives up
-        // quickly — can finish inside one poll interval, so a loop that slept and
-        // then bailed on `signal.aborted` would exit having drained NOTHING. That
-        // is exactly what happened: every turn raced the first tick and the
-        // editor received silence.
+        // The drain happens BEFORE the abort check: a turn can finish inside one poll
+        // interval, so a loop that slept and then bailed on `signal.aborted` would
+        // exit having drained NOTHING and the editor would receive silence.
         for (;;) {
             cursor = await this.drainOnce(sessionId, cursor);
             if (signal.aborted)

package/dist/agent/agent.js

@@ -538,6 +538,16 @@ export class Agent {
      * that wait would hang. isLive() answers "stop vs start" (#59/#133); this
      * answers "is work in flight".
      */
+    /**
+     * The text of every prompt still waiting for a turn boundary.
+     *
+     * Read-only view for callers that need to know WHAT is queued, not just how
+     * many — a delivery assertion has to see the text, or "the message arrived"
+     * degrades into "something is queued".
+     */
+    pendingPromptTexts() {
+        return this.pendingPrompts.map((p) => p.text);
+    }
     isBusy() {
         if (this.stopRequested)
             return false;
@@ -1802,25 +1812,14 @@ export class Agent {
                     text: "",
                     reasoning: "",
                 });
-            // #37: `prompt-delivered` must mean "the outbound request CARRYING this
-            // prompt has started", not "the prompt moved from the queue into
-            // `this.messages`".
-            //
-            // It used to be logged in drainPendingPrompts, which runs BEFORE
-            // refreshSkills, maybeRequestProgress and — critically — maybeCompact. So
-            // the marker preceded the request, and `maybeCompact()` can itself make an
-            // LLM call, which meant the timeline claimed a delivery order the API never
-            // saw. Measured before the fix:
-            //
-            //     LLM CALL #1
-            //       seq=5  prompt-delivered("first prompt")
-            //       seq=6  llm turn start
-            //
-            // The UI reorders by this marker (resequenceToDelivery), so the semantics
-            // were the bug — not timeline-order.ts.
+            // #37: `prompt-delivered` means "the outbound request CARRYING this prompt
+            // has started" — which is why it is emitted here and not in
+            // drainPendingPrompts. That runs BEFORE maybeCompact, which can itself make
+            // an LLM call, so the marker preceded the request and the timeline claimed a
+            // delivery order the API never saw.
             //
-            // Emitted ONCE per request, not per attempt: a retry sends the same payload,
-            // so re-emitting would move the marker after a later event on each try.
+            // Once per request, not per attempt: a retry sends the same payload, so
+            // re-emitting would move the marker past later events on each try.
             if (attempt === 1)
                 await this.markDeliveredPrompts();
             try {

package/dist/agent/llm.js

@@ -2,8 +2,8 @@
  * LLM access via the official `openai` npm client (OpenAI-compatible APIs:
  * OpenAI, OpenRouter, local vLLM/Ollama, ...).
  *
- * We deliberately delegate retries/timeouts/response-shape handling to the
- * SDK instead of hand-rolling them.
+ * Retries, timeouts and response-shape handling are delegated to the SDK rather
+ * than hand-rolled.
  */
 import OpenAI from "openai";
 const clients = new WeakMap();
@@ -73,11 +73,6 @@ function client(cfg) {
     }
     return c;
 }
-/**
- * Providers are picky in different ways; the common denominator is that
- * empty text content in user/assistant messages makes many of them 400.
- * Fill blanks with a harmless placeholder before sending.
- */
 /**
  * Providers occasionally glue MULTIPLE tool calls into one entry, or leak
  * their internal framing into the name field (seen live: a name of
@@ -119,6 +114,7 @@ function sanitize(messages) {
                 : { type: "text", text: p.text ?? "" });
             return { role: m.role, content: parts };
         }
+        // empty text content makes many providers 400 — send a harmless placeholder
         if ((m.role === "user" || m.role === "assistant") && !m.content) {
             return { ...m, content: m.tool_calls?.length ? "(tool call)" : "(no content)" };
         }
@@ -129,22 +125,16 @@ function sanitize(messages) {
     });
 }
 /**
- * Why did the response carry no usable message?
- *
- * #50 — this used to be a bare "LLM API returned no choices", which is what
- * made the report undiagnosable: an empty `choices` array, a 200 carrying an
- * `error` object, a `delta`-shaped body, and an SSE stream that the SDK
- * handed back as a plain String all produce the identical line, and none of
- * them is a useful thing to read in a log.
+ * Why did the response carry no usable message? (#50)
  *
- * The leading text is kept stable at "LLM API returned no choices" so any
- * existing matching (and the retry notes operators have learned to read)
- * still works; the diagnosis follows after a colon.
+ * The leading text is kept stable at "LLM API returned no choices" so existing
+ * matching (and the retry notes operators have learned to read) still works; the
+ * diagnosis follows after a colon.
  */
 function noChoicesDetail(res) {
     const base = "LLM API returned no choices";
     // a gateway that answers 200 with an error object instead of failing: the
-    // actionable message is right there and used to be thrown away
+    // actionable message is right there
     const err = res?.error;
     if (err && typeof err === "object") {
         const msg = typeof err.message === "string" ? err.message : JSON.stringify(err);
@@ -271,11 +261,9 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
     }
     catch (err) {
         const e = err;
-        // #50: our own shape-diagnosis already reads as a full sentence and names
-        // the response it saw. It carries no HTTP status (the request SUCCEEDED —
-        // that is the whole problem), so the generic wrapper below would have
-        // relabelled it "LLM API error ?: …", hiding both the diagnosis and the
-        // fact that no status was ever involved.
+        // #50: our own shape-diagnosis reads as a full sentence but carries no HTTP
+        // status (the request SUCCEEDED — that is the whole problem), so the generic
+        // wrapper below would relabel it "LLM API error ?: …".
         if (String(err.message ?? "").startsWith("LLM API returned no choices"))
             throw err;
         if (e.status === undefined && !String(err.message).includes("provider returned"))
@@ -366,11 +354,8 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
             });
         if (!message.content && !message.tool_calls) {
             // #50: a stream that opened, produced NOTHING, and closed cleanly. The
-            // throw carries a marker so the handler below can tell this apart from a
-            // request the provider actively rejected: this one is a broken/flaky
-            // proxy, and re-issuing it without `stream` is a genuinely different
-            // request that usually succeeds. Throwing a bare Error would make the two
-            // indistinguishable and cost us that safety net.
+            // marker lets the handler below tell this apart from a request the provider
+            // actively rejected — re-issuing THIS one without `stream` usually succeeds.
             const e = new Error("LLM API error: empty completion");
             e.emptyStream = true;
             throw e;
@@ -378,38 +363,24 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
         return { message, reasoning: reasoning || undefined, usage };
     }
     catch (err) {
-        // #50 — a provider that doesn't support streaming at all still gets ONE
-        // clean fallback, but ONLY when the streaming attempt produced nothing for
-        // a reason that could plausibly be the stream itself.
-        //
-        // The old condition was `!gotChunk && !signal?.aborted`, which also matched
-        // a request that FAILED — a gateway answering 200 with an SSE `error`
-        // frame, or a context-length rejection. In those cases the fallback
-        // re-issued the same oversized request in a different shape, and the
-        // resulting "LLM API returned no choices" replaced the real diagnosis.
-        // That is why a restored 1500-message session reported "no choices" three
-        // times and then errored: the genuine "context length exceeded" was
-        // discarded on the first attempt and could never be recognised by
-        // isContextOverflow(), so the compact-and-retry recovery never ran.
-        //
-        // Two exclusions, and the second one matters as much as the first:
+        // #50 — a provider that doesn't support streaming at all still gets ONE clean
+        // fallback, but ONLY when the failure could plausibly be the stream itself.
+        // The condition must NOT be `!gotChunk && !signal?.aborted`: that also matches
+        // a request that FAILED (a 200 carrying an SSE `error` frame, a context-length
+        // rejection), and the fallback then re-issues the same oversized request,
+        // replacing the real diagnosis — a restored 1500-message session reports "no
+        // choices" instead of "context length exceeded", so isContextOverflow() never
+        // runs compact-and-retry.
         //
-        //  1. A status that means the REQUEST ITSELF was rejected. Only then is
-        //     re-issuing it without `stream` a different request rather than the
-        //     same failing one. `400`/`404`/`405`/`422` are the shapes a provider
-        //     uses to say "no streaming here" — deliberately NOT the whole 4xx
-        //     range, because 408/425/429 are transient: replaying those against an
-        //     already-saturated provider just doubles the request count.
-        //  2. A THROWN error, as opposed to a request that simply produced no
-        //     chunks. A 200 that streams zero chunks and closes cleanly is a
-        //     broken/flaky proxy, and that is precisely the case the non-streaming
-        //     retry rescues. Requiring a 4xx here would have deleted that safety
-        //     net — a regression this file's own tests caught.
+        //  1. A status in STREAM_REJECTED_STATUS: only a request rejected outright is a
+        //     genuinely DIFFERENT request when re-issued without `stream`.
+        //  2. `emptyStream`: a 200 that streams zero chunks and closes cleanly is a
+        //     broken/flaky proxy — precisely the case the retry rescues. Requiring a
+        //     4xx here would delete that safety net, a regression this file's own
+        //     tests caught.
         //
-        // So the fallback runs when the request was rejected outright, OR when it
-        // completed without error and without a single chunk. Everything else —
-        // 5xx, an error frame, a mid-stream failure — is the ANSWER, rethrown
-        // untouched so overflow recovery can see it.
+        // Everything else — 5xx, an error frame, a mid-stream failure — is the ANSWER,
+        // rethrown untouched so overflow recovery can see it.
         const status = err?.status;
         const rejectedByProvider = typeof status === "number" && STREAM_REJECTED_STATUS.has(status);
         const emptyStream = err?.emptyStream === true;

package/dist/agent/skills.js

@@ -12,9 +12,8 @@
  *   (free-form instructions shown to the agent when it loads the skill)
  *
  * Roots are scanned in priority order; the first skill with a given name wins.
- * Workspace skills (<workspace>/skills) beat global ones (~config/skills), so
- * a project can override shared defaults. Everything stays human-readable and
- * git-friendly Markdown — no database, no lock-in.
+ * Workspace skills (<workspace>/skills) beat global ones (~config/skills), so a
+ * project can override shared defaults.
  */
 import { promises as fs } from "node:fs";
 import path from "node:path";
@@ -26,12 +25,10 @@ export const SKILL_FILE = "SKILL.md";
  * can skip a full rescan (a readdir per root plus a read of every SKILL.md)
  * on the overwhelmingly common "nothing changed" path.
  *
- * The fingerprint covers each root's own mtime/size AND the mtime/size of
- * every SKILL.md one level down, because writing SKILL.md does not bump the
- * parent directory's mtime. Helper scripts edited in place are covered by
- * the SKILL.md stat only in aggregate; a rewritten SKILL.md always lands
- * here too (saveSkill rewrites it), so bundled-file edits ride along with
- * the next skill write rather than triggering their own rescan.
+ * It must walk every SKILL.md the discovery walk could adopt, not just the
+ * roots: writing SKILL.md does not bump the parent directory's mtime. Helper
+ * scripts edited in place ride along with the next skill write (saveSkill
+ * rewrites SKILL.md), rather than triggering their own rescan.
  */
 export async function skillRootsFingerprint(roots) {
     const parts = [];
@@ -46,15 +43,13 @@ export async function skillRootsFingerprint(roots) {
             continue;
         }
         parts.push(`${st.mtimeMs}:${st.size}`);
-        // stamp every SKILL.md the discovery walk could adopt (same depth bound):
-        // the one-level stat missed a NESTED skill's add/edit entirely, so the
-        // stamp never changed, refreshSkills early-returned, and the skill stayed
-        // invisible/stale in list_skills and the system-prompt catalogue
+        // same depth bound as the discovery walk, or a NESTED skill's add/edit leaves
+        // this stamp unchanged and the skill stays stale in list_skills
         await stampSkillFiles(root.dir, 0, parts);
     }
     return parts.join("|");
 }
-/** recursive fingerprint walk — mirrors walkSkills' bound and containment rules */
+/** recursive fingerprint walk — mirrors walkSkills' depth bound */
 async function stampSkillFiles(dir, depth, parts) {
     if (depth > MAX_SKILL_DEPTH)
         return;
@@ -88,16 +83,16 @@ export function isValidSkillName(name) {
  * Minimal frontmatter parser for the subset we need: a leading `---` block of
  * `key: value` lines. No YAML dependency by design.
  *
- * It does understand the two YAML shapes that are common in REAL third-party
- * skills (#28), because without them those files are unreadable:
+ * It does understand the two YAML shapes common in REAL third-party skills
+ * (#28), because without them those files are unreadable:
  *  - FOLDED/LITERAL BLOCK SCALARS (`description: >-` … or `|` …), which is how
  *    most skill authors write a long description. Reading them naively yields
  *    the literal ">-" as the description, which silently destroys the one field
  *    the model matches its task against.
  *  - QUOTED values, whose surrounding quotes are stripped so a description
  *    containing a colon survives.
- * A key whose value is empty (e.g. a nested `metadata:` block) is left out rather
- * than recorded as an empty string.
+ * A key with an empty value (e.g. a nested `metadata:` block) is left out rather
+ * than recorded as "".
  */
 export function parseSkillMd(text) {
     const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
@@ -149,7 +144,6 @@ function unquote(v) {
     }
     return s;
 }
-/** Root dirs in priority order: [0] overrides later ones on name clash. */
 /**
  * Skill directories owned by OTHER coding harnesses (#28).
  *
@@ -205,15 +199,14 @@ export function foreignSkillRoots(workspace) {
  *
  * Bounded because a skill directory also holds BUNDLED FILES (helper scripts)
  * and arbitrary payload, so an unbounded walk is not safe. Depth is not the
- * thing that makes a directory a skill, though — holding a SKILL.md is — so the
- * bound only limits how far we look, never what counts.
+ * thing that makes a directory a skill — holding a SKILL.md is — so the bound
+ * only limits how far we look, never what counts.
  */
 const MAX_SKILL_DEPTH = 4;
 /** Root dirs in priority order: [0] overrides later ones on name clash. */
 export async function discoverSkills(roots) {
     const byName = new Map();
-    // name -> depth, so a SHALLOWER skill wins over a nested namesake rather than
-    // a deep one silently shadowing the obvious skill (#27)
+    // name -> depth, so a SHALLOWER skill beats a nested namesake (#27)
     const depthByName = new Map();
     for (const root of roots) {
         await walkSkills(root.dir, root.source, 0, byName, depthByName);
@@ -223,9 +216,8 @@ export async function discoverSkills(roots) {
 /**
  * Depth-first walk collecting every directory that holds a SKILL.md (#27).
  *
- * A directory WITHOUT its own SKILL.md is only a container to descend into — we
- * never treat one as a skill, which is what keeps bundled helper directories
- * from being reported as skills themselves.
+ * A directory without its own SKILL.md is only a container to descend into, which
+ * is what keeps bundled helper directories from being reported as skills.
  */
 async function walkSkills(dir, source, depth, byName, depthByName) {
     if (depth > MAX_SKILL_DEPTH)
@@ -250,7 +242,6 @@ async function walkSkills(dir, source, depth, byName, depthByName) {
         const parsed = parseSkillMd(hereText);
         const name = parsed.meta.name || path.basename(dir);
         const prevDepth = depthByName.get(name);
-        // first root wins on a name clash, and a shallower skill beats a deeper one
         const wins = prevDepth === undefined ||
             (prevDepth !== undefined && depth < prevDepth && byName.get(name)?.source === source);
         if (wins) {
@@ -277,10 +268,8 @@ async function walkSkills(dir, source, depth, byName, depthByName) {
     for (const e of entries) {
         if (!e.isDirectory() || e.name.startsWith("."))
             continue;
-        // Recurse into every subdirectory: nesting means a skill can sit at ANY depth
-        // (skills/stage1/template/SKILL.md), and "stage1" itself has no SKILL.md.
-        // Bundled helper payloads are not mistaken for skills because a directory
-        // only BECOMES a skill when it holds its own SKILL.md (#27).
+        // a skill can sit at ANY depth (skills/stage1/template/SKILL.md), and
+        // "stage1" itself has no SKILL.md (#27)
         await walkSkills(path.join(dir, e.name), source, depth + 1, byName, depthByName);
     }
 }

package/dist/agent/tools.js

@@ -1589,7 +1589,9 @@ export const TOOLS = [
     },
     {
         name: "list_children",
-        description: "List your live sub-agents: id, status, current goal.",
+        description: "List the sub-agents working under you: id, status, current goal. " +
+            "Includes NESTED ones your sub-agents spawned (marked (nested) with their own parent), " +
+            "so you can see work you would otherwise be unaware of — wait_children waits for these too.",
         parameters: { type: "object", properties: {} },
         async run(_args, ctx) {
             const sa = ctx.subAgents;
@@ -1601,7 +1603,8 @@ export const TOOLS = [
             return {
                 ok: true,
                 result: kids
-                    .map((k) => `${k.id} · ${k.status} · ${clip(k.goal, 60)}`)
+                    .map((k) => `${k.id} · ${k.status} · ${clip(k.goal, 60)}` +
+                    (k.nested ? `  (nested — spawned by @${k.parent}; address @${k.parent} to steer it)` : ""))
                     .join("\n"),
             };
         },
@@ -1630,8 +1633,10 @@ export const TOOLS = [
     {
         name: "wait_children",
         description: "Park until at least one sub-agent settles (finished, errored, stopped, or asks you a question) — " +
-            "or until the timeout lapses. Costs zero tokens while parked: prefer this over bash sleep when " +
-            "waiting on spawned work. The settling child's report is delivered to you afterwards.",
+            "or until the timeout lapses. Waits for your whole SUBTREE: a sub-agent that spawned its own " +
+            "sub-agents is not settled while those are still working, so this never returns over live nested " +
+            "work. Costs zero tokens while parked: prefer this over bash sleep when waiting on spawned work. " +
+            "The settling child's report is delivered to you afterwards.",
         parameters: {
             type: "object",
             properties: {

package/dist/config-schema.js

@@ -1,10 +1,10 @@
 /**
  * Zod schema for teapot's config — the single source of truth for what a
- * valid config looks like. Used to gate web-UI edits (PUT /api/config) and
- * any programmatic writes, with human-readable error messages.
+ * valid config looks like, used to gate web-UI edits (PUT /api/config) and any
+ * programmatic writes with human-readable error messages.
  *
- * NOTE: validation gates, it does not become the storage format — the master
- * persists the raw user JSON so unknown fields survive round-trips.
+ * Validation gates; it is not the storage format — the master persists the raw
+ * user JSON so unknown fields survive round-trips.
  */
 import { z } from "zod";
 export const ProviderSchema = z.object({

package/dist/home.js

@@ -1,29 +1,24 @@
 /**
- * The user's home directory, on every platform.
+ * The user's home directory, on every platform (#110).
  *
- * #110: `process.env.HOME` is a POSIX convention and is normally UNSET on
- * Windows. Code that expanded `~` with `process.env.HOME ?? "~"` therefore got
- * the LITERAL string "~" back on Windows — and since the result was then passed
- * to `path.resolve(base, …)` and `mkdirSync`, teapot created a directory named
- * `~`. That is the reported symptom.
+ * `process.env.HOME` is a POSIX convention and is normally UNSET on Windows, so
+ * expanding `~` with `process.env.HOME ?? "~"` produced the LITERAL "~" there —
+ * and since the result reached `path.resolve` + `mkdirSync`, teapot created a
+ * directory named `~`.
  *
- * `os.homedir()` is the answer: on Windows Node resolves it from `USERPROFILE`,
- * on POSIX from `HOME`, so it is never the literal `~`. The env lookups are kept
- * only so a test can drive the Windows shape deterministically — `os.homedir()`
- * on a Linux CI box would report `/root` and hide the very condition under test.
- *
- * Returns "" only when nothing at all is known, which callers treat as "leave the
- * `~` alone" rather than inventing a path.
+ * The `env` parameters exist so a test can drive the Windows shape
+ * deterministically; `os.homedir()` on a Linux CI box would report `/root` and
+ * hide the condition under test.
  */
+/** @returns "" when no home is known — callers leave `~` alone rather than invent a path */
 export function homeDir(env = process.env) {
     if (env.HOME)
         return env.HOME;
     if (env.USERPROFILE)
         return env.USERPROFILE;
-    // Windows also reports a home as HOMEDRIVE + HOMEPATH. Concatenate
-    // defensively: `drive.replace(...) + path` yields the STRING "undefined"
-    // rather than undefined when either part is missing, which is exactly the
-    // class of bug this helper exists to remove.
+    // Windows can report HOMEDRIVE + HOMEPATH. Both must be present:
+    // `undefined + path` yields the STRING "undefined", which is exactly the class
+    // of bug this helper exists to remove.
     const drive = env.HOMEDRIVE;
     const rest = env.HOMEPATH;
     if (drive && rest)
@@ -32,20 +27,13 @@ export function homeDir(env = process.env) {
         return drive;
     return "";
 }
-/**
- * Expand a leading `~` to the home directory.
- *
- * Kept in one place so the Windows case cannot be got wrong a second time — the
- * bug existed in three separate places before this helper (#110).
- */
+/** Expand a leading `~`. One place, so the Windows case cannot be got wrong twice (#110). */
 export function expandTilde(input, env = process.env) {
-    // #110: on Windows a path can be `~\foo`, hence the backslash in the lookahead.
+    // a Windows path can be `~\foo`, hence the backslash in the lookahead
     if (!/^~(?=$|[/\\])/.test(input))
         return input;
     const home = homeDir(env);
-    // With no home known, returning the input untouched is more honest than
-    // substituting a literal that would become a real directory.
     if (!home)
-        return input;
+        return input; // no home known: leaving `~` is more honest than inventing one
     return input.replace(/^~(?=$|[/\\])/, home);
 }