teapot-coding-agent 0.37.49 → 0.37.51

package/dist/agent/agent.js

@@ -74,13 +74,6 @@ export const PROGRESS_REQUEST =
     // and every requested report appeared TWICE on the timeline
     "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
- * state) re-prices the whole context. That is why session state lives behind
- * meta tools instead. The cache rationale itself stays HERE in a comment —
- * the model does not need our cost-engineering notes every turn.
- */
 /**
  * Recent context kept VERBATIM through a compaction, in tokens.
  *
@@ -235,6 +228,13 @@ const SUMMARY_CLOSE = "\n</conversation_checkpoint>";
  * claim, and must not be able to change what it is judging.
  */
 const AUDIT_READ_ONLY_TOOLS = new Set(["read_file", "list_dir", "grep", "bash"]);
+/**
+ * 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
+ * state) re-prices the whole context. That is why session state lives behind
+ * meta tools instead. The cache rationale itself stays HERE in a comment —
+ * the model does not need our cost-engineering notes every turn.
+ */
 const SYSTEM_TEMPLATE = `You are a coding agent working autonomously inside a workspace.
 
 Most session state is not injected into prompts — fetch it with tools instead:
@@ -665,31 +665,14 @@ export class Agent {
      * are exempt — those are not "keep trying", they are "the operator/provider asked".
      */
     consecutiveCompactFailures = 0;
-    /**
-     * Rescan skill roots — but only when something actually changed.
-     * This used to run a readdir per root plus a read of every SKILL.md at the
-     * top of EVERY turn; the cache is only ever read by list_skills, so that
-     * was pure I/O on the hot path. A cheap stat fingerprint of the roots and
-     * their SKILL.md files gates the real scan, so a turn only pays when a
-     * 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.
-     *
-     * 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.
-     */
     /**
      * A bounded DIGEST of memory.md: every heading, plus its first line.
      *
-     * they are genuinely long — 2.6KB is the median, and the largest hold full project briefs. A
-     * model that never sees them cannot decide to consult them: that is the whole finding of #48
-     * (182 writes, 13 reads after a write). A model that sees the WHOLE file pays for it on every
-     * request and breaks the prefix cache.
+     * Memory notes are worth this much because they are what a later session reads instead of
+     * re-learning the workspace: they are genuinely long — 2.6KB is the median, and the largest hold
+     * full project briefs. A model that never sees them cannot decide to consult them: that is the
+     * whole finding of #48 (182 writes, 13 reads after a write). A model that sees the WHOLE file
+     * pays for it on every request and breaks the prefix cache.
      *
      * Codex solves this with a `MEMORY_SUMMARY` in the prompt plus a searchable registry on disk.
      * This is the same shape: the digest says what memory HOLDS, `read_memory(query)` fetches the
@@ -950,14 +933,6 @@ export class Agent {
             // `needs_operator` snapshot reported `live: false` until this was added.
             this.status === "needs_operator");
     }
-    /**
-     * Is this agent doing in-flight work that a WAITER (wait_children) should
-     * hold for? Deliberately narrower than isLive(): queued prompts are DORMANT
-     * work (a stopped/idle child touches them only after it is started), so
-     * they must not keep a parent parked on a child that is visibly idle —
-     * 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.
      *
@@ -968,6 +943,14 @@ export class Agent {
     pendingPromptTexts() {
         return this.pendingPrompts.map((p) => p.text);
     }
+    /**
+     * Is this agent doing in-flight work that a WAITER (wait_children) should
+     * hold for? Deliberately narrower than isLive(): queued prompts are DORMANT
+     * work (a stopped/idle child touches them only after it is started), so
+     * they must not keep a parent parked on a child that is visibly idle —
+     * that wait would hang. isLive() answers "stop vs start" (#59/#133); this
+     * answers "is work in flight".
+     */
     isBusy() {
         if (this.stopRequested)
             return false;
@@ -977,6 +960,11 @@ export class Agent {
             this.parkedByTool ||
             this.compactPhase !== "");
     }
+    /** recently read workspace files (most recent first) — post-compact restore */
+    recentReads = [];
+    trackFileRead(p) {
+        this.recentReads = [p, ...this.recentReads.filter((x) => x !== p)].slice(0, 5);
+    }
     /**
      * A background shell (bash background=true) finished. Two channels:
      * 1. a system_note row in the timeline — the operator sees the outcome
@@ -985,11 +973,6 @@ export class Agent {
      *    agent learns exit code + output tail WITHOUT having to poll
      *    bash_output blindly. Failed jobs say so loudly so the model reacts.
      */
-    /** recently read workspace files (most recent first) — post-compact restore */
-    recentReads = [];
-    trackFileRead(p) {
-        this.recentReads = [p, ...this.recentReads.filter((x) => x !== p)].slice(0, 5);
-    }
     onBackgroundJobExit(info) {
         const ok = info.code === 0;
         const one = info.cmd.replace(/\s+/g, " ").slice(0, 80);
@@ -1097,11 +1080,6 @@ export class Agent {
             bus.emit("update", { kind: "agent-update", agentId: this.opts.id });
         }
     }
-    /**
-     * Restore the conversation from the JSONL log exactly once, on demand.
-     * Everything that touches history (prompts, start, fork, UI selection)
-     * funnels through here; boot stays cheap no matter how many sessions exist.
-     */
     /**
      * Resolve the session/workspace this agent operates on.
      *
@@ -1272,16 +1250,6 @@ export class Agent {
             /* keep the session copy if the agent-wide write failed — losing notes is worse */
         }
     }
-    /**
-     * Rebuild the in-memory conversation from the JSONL event log so a restart
-     * continues where the agent left off instead of starting blank.
-     *
-     * Strategy: find the most recent event overall (its branch is where the
-     * agent was), walk the `parent` chain backwards (crossing fork points),
-     * then replay events forward into ChatMessages. Meta-tool calls
-     * (finish / report_progress) never produced logged tool results, so we
-     * synthesize their responses to keep the message sequence valid.
-     */
     /**
      * Resolve a leading sub_fork header: load the parent session's file (and
      * recurse if THAT one is itself a sub_fork), take its lineage up to the
@@ -1323,6 +1291,17 @@ export class Agent {
             prefix.shift();
         return [...prefix, ...own.filter((e) => e !== header)];
     }
+    /**
+     * Restore the conversation from the JSONL log exactly once, on demand.
+     * Everything that touches history (prompts, start, fork, UI selection)
+     * funnels through here; boot stays cheap no matter how many sessions exist.
+     *
+     * Strategy: find the most recent event overall (its branch is where the
+     * agent was), walk the `parent` chain backwards (crossing fork points),
+     * then replay events forward into ChatMessages. Meta-tool calls
+     * (finish / report_progress) never produced logged tool results, so we
+     * synthesize their responses to keep the message sequence valid.
+     */
     async restoreFromLog() {
         const own = await readEvents(this.log.filePath);
         if (own.length === 0)
@@ -1637,14 +1616,6 @@ export class Agent {
         await fs.writeFile(this.todoFile, text, "utf8");
         await this.log.append("todo", this.currentSession, this.currentBranch, { event: "set", by });
     }
-    /**
-     * Update SPECIFIC checkbox items without rewriting the whole list — the
-     * full-replacement path made agents lazy (a mid-task progress tick meant
-     * re-emitting the entire markdown, so they skipped updates) and risky (one
-     * sloppy regeneration mangled unrelated sections). Items are matched by
-     * normalized text; unknown items are reported back instead of silently
-     * dropped. Returns a short human-readable summary for the tool result.
-     */
     /**
      * Apply surgical changes to todo.md.
      *
@@ -4592,7 +4563,6 @@ export class Agent {
             bus.emit("update", { kind: "compaction-progress", agentId: this.opts.id, phase: "done" });
         }
     }
-    /** Ask the model for dense continuation notes over the compacted range. */
     /**
      * Summarize `old` into continuation notes.
      *

package/dist/master.js

@@ -19,7 +19,6 @@ import { bus } from "./bus.js";
 import { mcp } from "./agent/mcp-registry.js";
 import { loadPlugins } from "./agent/plugins.js";
 import { fetchModelList, peekModelList, contextLengthFor, isReasoningEffort, } from "./model-meta.js";
-/** how deep sub-agent spawning may nest (parent=0, its subs=1, …) */
 /**
  * Did the effective data dir come from an ENV OVERRIDE that disagrees with the
  * config file's own `dataDir`?
@@ -282,7 +281,6 @@ export function loadConfig(configPath) {
         providers: Object.fromEntries(Object.entries(user.providers ?? {}).map(([name, p]) => [name, migrateProviderKeys(p)])),
     };
 }
-/** Raw parsed user config (for lossless persistence of web edits). */
 /**
  * Can this path be replaced by an atomic rename?
  *
@@ -587,7 +585,6 @@ export class Master {
         this.configDirty = false;
         this.saveConfig();
     }
-    /** write-and-rename, so config.json is never observed empty or half-written */
     /**
      * The shared pool for a provider, created on first use.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teapot-coding-agent",
-  "version": "0.37.49",
+  "version": "0.37.51",
   "description": "A lightweight, always-on multi-agent harness for AI coding agents",
   "type": "module",
   "license": "AGPL-3.0-or-later",
@@ -37,6 +37,8 @@
     "typecheck-web": "tsc -p tsconfig.frontend.json",
     "typecheck:scripts": "tsc -p tsconfig.scripts.json",
     "lint": "oxlint src frontend test scripts",
+    "lint:comments": "node scripts/find-stacked-comments.ts",
+    "lint:comments:strict": "node scripts/find-stacked-comments.ts --strict",
     "start": "node dist/index.js",
     "dev": "node src/index.ts",
     "dev-web": "vite",