reasonix 0.14.0 → 0.15.0

package/dist/index.js

@@ -139,12 +139,7 @@ var DeepSeekClient = class {
     }
     return payload;
   }
-  /**
-   * Fetch the current DeepSeek account balance. Separate endpoint
-   * from chat completions, no billing impact. Returns null on any
-   * network/auth failure so callers can gate the balance display
-   * without a hard error — the rest of the session works regardless.
-   */
+  /** Returns null on failure so callers can degrade — session must keep working without balance UI. */
   async getBalance(opts = {}) {
     try {
       const resp = await this._fetch(`${this.baseUrl}/user/balance`, {
@@ -160,13 +155,7 @@ var DeepSeekClient = class {
       return null;
     }
   }
-  /**
-   * Fetch the model catalog DeepSeek currently exposes. Today this is
-   * `deepseek-chat` (V3) and `deepseek-reasoner` (R1), but querying is
-   * the only way to learn about new ones without a Reasonix release.
-   * Returns null on any network/auth failure so callers can degrade
-   * gracefully — e.g. `/models` falls back to the hardcoded hint.
-   */
+  /** Returns null on failure — callers fall back to a hardcoded model hint. */
   async listModels(opts = {}) {
     try {
       const resp = await this._fetch(`${this.baseUrl}/models`, {
@@ -915,19 +904,7 @@ function setByPath(target, path, value) {
 var ToolRegistry = class {
   _tools = /* @__PURE__ */ new Map();
   _autoFlatten;
-  /**
-   * When true, `dispatch` refuses any tool whose `readOnly` flag isn't
-   * set (and whose `readOnlyCheck` doesn't pass on the specific args).
-   * Drives `reasonix code`'s Plan Mode — the model can still explore
-   * via read tools but its writes and non-allowlisted shell calls are
-   * bounced until the user approves a submitted plan.
-   */
   _planMode = false;
-  /**
-   * Optional hook run after arg parsing but before tool.fn. Lets the TUI
-   * reroute specific tool calls (e.g. edit_file in review mode) without
-   * modifying the tool definitions themselves.
-   */
   _interceptor = null;
   constructor(opts = {}) {
     this._autoFlatten = opts.autoFlatten !== false;
@@ -940,11 +917,7 @@ var ToolRegistry = class {
   get planMode() {
     return this._planMode;
   }
-  /**
-   * Install or clear the dispatch interceptor. At most one interceptor
-   * is active at a time — calling twice replaces the previous. Pass
-   * `null` to remove.
-   */
+  /** At most one interceptor active; calling twice replaces. */
   setToolInterceptor(fn) {
     this._interceptor = fn;
   }
@@ -1180,33 +1153,10 @@ function blockToString(block) {
 import { createHash } from "crypto";
 var ImmutablePrefix = class {
   system;
-  /**
-   * Backing array for `toolSpecs`. Originally `Object.freeze`d at
-   * construction (hence the class name) — but `addTool` now lets the
-   * dashboard register `semantic_search` after a mid-session
-   * `reasonix index` build without forcing the user to restart. Each
-   * add is documented to cost one cache-miss turn (the cached prefix
-   * on DeepSeek's side is keyed by the full tool list); subsequent
-   * turns re-cache against the new shape.
-   */
+  /** Each `addTool` costs one cache-miss turn — DeepSeek's prefix cache is keyed by full tool list. */
   _toolSpecs;
   fewShots;
-  /**
-   * Cached SHA-256 of the prefix payload. Computed lazily on first
-   * `fingerprint` access, invalidated only by mutations that go
-   * through `addTool` (the one legitimate post-construction mutation
-   * path). The TUI reads `fingerprint` on every render — without the
-   * cache, that means a fresh `JSON.stringify` + sha256 over the
-   * full prefix (system prompt + tools list + few-shots, typically
-   * 5-10KB) on every keystroke.
-   *
-   * The lazy-init also acts as a cheap drift guard: if some future
-   * code path mutates `_toolSpecs` directly without going through
-   * `addTool`, `fingerprint` will return the stale cached value
-   * while the actual prefix sent to DeepSeek diverges — the cache
-   * miss would be the first symptom. {@link verifyFingerprint}
-   * lets dev / test code assert the cache matches reality.
-   */
+  /** Invalidated only via `addTool`; bypassing it leaves cache stale → fingerprint diverges from sent prefix. */
   _fingerprintCache = null;
   constructor(opts) {
     this.system = opts.system;
@@ -1222,12 +1172,6 @@ var ImmutablePrefix = class {
   tools() {
     return this._toolSpecs.map((t) => structuredClone(t));
   }
-  /**
-   * Add a tool spec to the prefix. Returns `true` if added, `false`
-   * if a tool with the same name was already present (callers can
-   * decide whether to ignore or surface the no-op). The model picks
-   * up the new tool on the next turn after the cache busts once.
-   */
   addTool(spec) {
     const name = spec.function?.name;
     if (!name) return false;
@@ -1241,14 +1185,7 @@ var ImmutablePrefix = class {
     this._fingerprintCache = this.computeFingerprint();
     return this._fingerprintCache;
   }
-  /**
-   * Recompute the fingerprint from scratch and assert it matches the
-   * cached value. Returns the freshly-computed hash on success; throws
-   * with a diff if the cache drifted, which always indicates a bug —
-   * either a non-`addTool` mutation path was added, or `addTool`
-   * forgot to invalidate the cache. Dev / test only; the live loop
-   * doesn't call this on the hot path.
-   */
+  /** Dev/test only — throws on cache drift, which always means a non-`addTool` mutation slipped in. */
   verifyFingerprint() {
     const fresh = this.computeFingerprint();
     if (this._fingerprintCache !== null && this._fingerprintCache !== fresh) {
@@ -1279,13 +1216,7 @@ var AppendOnlyLog = class {
   extend(messages) {
     for (const m of messages) this.append(m);
   }
-  /**
-   * Bulk-replace entries. Intentionally named to be hard to reach for —
-   * this is the one mutation path that breaks the log's append-only
-   * spirit, reserved for compaction flows (`/compact`) and recovery
-   * where the caller has consciously decided to drop old history. Any
-   * other use is almost certainly wrong; append() is what you want.
-   */
+  /** The one append-only-breaking path — reserved for `/compact` + recovery. Use `append()` otherwise. */
   compactInPlace(replacement) {
     this._entries = [...replacement];
   }
@@ -1559,13 +1490,7 @@ var ToolCallRepair = class {
     this.opts = opts;
     this.storm = new StormBreaker(opts.stormWindow ?? 6, opts.stormThreshold ?? 3, opts.isMutating);
   }
-  /**
-   * Drop the StormBreaker's sliding window of recent (name, args)
-   * signatures. Called at the start of every user turn — a fresh user
-   * message is a new intent, so carrying old repetition state into it
-   * would turn a valid "try again with different input" flow into a
-   * false-positive block.
-   */
+  /** Called at start of every user turn — fresh intent shouldn't inherit old repetition state. */
   resetStorm() {
     this.storm.reset();
   }
@@ -1846,85 +1771,23 @@ var CacheFirstLoop = class {
   harvestOptions;
   branchEnabled;
   branchOptions;
-  /** See ReconfigurableOptions — mutable so `/effort` can flip mid-session. */
   reasoningEffort;
-  /**
-   * Auto-escalation toggle. `true` lets the loop self-promote to pro
-   * mid-turn (NEEDS_PRO marker / failure threshold); `false` keeps it
-   * pinned to `model`. Mutable so the dashboard's preset switcher can
-   * flip it live alongside `model`.
-   */
   autoEscalate = true;
-  /**
-   * Soft USD budget — see {@link CacheFirstLoopOptions.budgetUsd}.
-   * Mutable so `/budget` slash can set / change / clear it mid-session.
-   * `null` (the default) disables all budget checks.
-   */
   budgetUsd;
-  /**
-   * Set the first time a turn crosses 80% of the budget so the warning
-   * doesn't repeat every turn afterwards. Cleared by `setBudget` (any
-   * change re-arms the warning, including raising the cap above the
-   * current spend).
-   */
+  /** One-shot 80% warning latch — cleared by setBudget so a bump re-arms at the new boundary. */
   _budgetWarned = false;
   sessionName;
-  /**
-   * Hook list, mutable so `/hooks reload` can swap it without
-   * reconstructing the loop. Default empty — the filter cost on a
-   * tool call is one array length check.
-   */
   hooks;
-  /**
-   * `cwd` reported to hook stdin. Mutable so `/cwd` can switch the
-   * working directory mid-session — the App keeps it in sync with
-   * the same currentRootDir that drives tool re-registration.
-   */
   hookCwd;
   /** Number of messages that were pre-loaded from the session file. */
   resumedMessageCount;
   _turn = 0;
   _streamPreference;
-  /**
-   * AbortController per active turn. Threaded through the DeepSeek
-   * HTTP calls AND every tool dispatch so Esc actually cancels the
-   * in-flight network/subprocess work — not "we'll get to it after
-   * the current call finishes." Re-created at the start of each
-   * `step()` (the prior turn's signal has already fired).
-   */
+  /** Threaded through HTTP + every tool dispatch so Esc cancels in-flight work, not after. */
   _turnAbort = new AbortController();
-  /**
-   * "Next turn should run on pro, regardless of this.model." Set by the
-   * `/pro` slash command; consumed at the next turn's start (flipping
-   * `_escalateThisTurn` on and self-clearing) so it's a fire-and-forget
-   * single-turn upgrade. Survives across multiple slash inputs so
-   * typing `/pro` and then hesitating a while before submitting a real
-   * message still applies.
-   */
   _proArmedForNextTurn = false;
-  /**
-   * Active for the current turn only — true means every model call
-   * this turn uses pro instead of `this.model`. Turned on by EITHER
-   * the pro-armed consumption OR the mid-turn auto-escalation
-   * threshold (see `_turnFailureCount`). Cleared at turn end.
-   */
   _escalateThisTurn = false;
-  /**
-   * Visible-failure count for the current turn. Incremented by tool
-   * dispatch paths when a result matches a known "flash is struggling"
-   * shape (SEARCH-not-found errors, scavenge / truncation / storm
-   * repair fires). Once it hits {@link FAILURE_ESCALATION_THRESHOLD},
-   * the remainder of the turn's model calls auto-upgrade to pro so
-   * the user doesn't watch flash retry the same edit 5 times.
-   */
   _turnFailureCount = 0;
-  /**
-   * Per-type breakdown of failure signals counted toward the turn's
-   * auto-escalation threshold. Surfaced in the warning when the
-   * threshold trips so the user sees what kind of trouble flash
-   * actually hit ("3× search-mismatch, 2× truncated") rather than
-   * just a bare count. Reset alongside _turnFailureCount.
-   */
   _turnFailureTypes = {};
   constructor(opts) {
     this.client = opts.client;
@@ -1995,55 +1858,7 @@ var CacheFirstLoop = class {
       this.resumedMessageCount = 0;
     }
   }
-  /**
-   * Shrink the log by re-truncating oversized tool results to a tighter
-   * token cap, and persist the result back to disk so the next launch
-   * doesn't re-inherit a fat session file. Returns a summary the TUI
-   * can display.
-   *
-   * The cap is in DeepSeek V3 tokens (not chars) — so CJK text gets
-   * capped at the same effective context footprint as English instead
-   * of slipping past a char cap at 2× the token cost. Default 4000
-   * tokens, matching the token-aware dispatch cap from 0.5.2.
-   *
-   * Only tool-role messages are touched (same rationale as
-   * {@link healLoadedMessages}). User and assistant messages carry
-   * authored intent we can't mechanically shrink without losing
-   * meaning.
-   */
-  /**
-   * Conservative args-only shrink fired after every tool response —
-   * strictly about ONE thing: stop oversized `edit_file` / `write_file`
-   * arguments from riding every future turn's prompt.
-   *
-   * Why this is worth doing AUTOMATICALLY (not just on /compact):
-   * Each tool-call arguments string sticks in the log verbatim. On a
-   * coding session with ~10 edits, that's 20-40K tokens of stale
-   * SEARCH/REPLACE text riding along on every turn. Even at a 98.9%
-   * cache hit rate the input cost still adds up linearly (cache-hit
-   * price × tokens × turns). Compacting IMMEDIATELY after the tool
-   * responds means the next turn's prompt is already smaller — the
-   * shrink is a one-time write that saves every future prompt.
-   *
-   * Threshold rationale: 800 tokens ≈ 3 KB. A typical 20-line edit's
-   * args land well under that; massive rewrites (whole-file content,
-   * 100+ line refactors) land above and get the compaction. Small
-   * edits stay byte-verbatim so nothing common-case changes.
-   *
-   * Safety: we ONLY shrink args whose tool has ALREADY responded.
-   * Structurally that's every call in `log.toMessages()` at this
-   * point — the current turn's assistant/tool pairing is by
-   * construction closed by the time we get here (append happens
-   * AFTER dispatch). The in-flight assistant message being built
-   * lives in scratch, not the log, so this pass can't touch it.
-   *
-   * Model impact: the model may occasionally want to reference the
-   * exact SEARCH text of a prior edit — it then reads the file
-   * directly (which shows current state) or looks at the preceding
-   * assistant text (which has its plan). Losing the stale args is a
-   * net win: one extra read_file vs. dragging N KB of stale text
-   * through every subsequent turn.
-   */
+  /** Shrink huge edit_file/write_file args post-dispatch — tool result already explains. */
   compactToolCallArgsAfterResponse() {
     const before = this.log.toMessages();
     const { messages, healedCount } = shrinkOversizedToolCallArgsByTokens(
@@ -2059,25 +1874,7 @@ var CacheFirstLoop = class {
       }
     }
   }
-  /**
-   * Fired at the END of a turn (just before `done` is yielded). Shrinks
-   * every tool RESULT in the log that exceeds {@link TURN_END_RESULT_CAP_TOKENS}
-   * to a tight cap so the NEXT turn's prompt doesn't re-pay for big
-   * reads or searches done earlier. Unlike the reactive 40/80%
-   * thresholds which react to context pressure, this runs unconditionally
-   * — the win is preventive: each turn's big outputs get trimmed before
-   * they ride into the next prompt. Saves compounding cost on long
-   * sessions.
-   *
-   * Why compact the JUST-finished turn's results too (not just older
-   * turns)? The same-turn iters already consumed the raw content to
-   * make their decisions — the log is only carried forward for future
-   * prompts. And "let me re-read the file" is vastly cheaper than
-   * "carry this 12KB result in every future turn's prompt forever."
-   *
-   * Safe by construction: args-compact for THIS turn already ran
-   * inside `compactToolCallArgsAfterResponse`; this pass is orthogonal.
-   */
+  /** Preventive end-of-turn shrink — trim big results before they ride into the next prompt. */
   autoCompactToolResultsOnTurnEnd() {
     const before = this.log.toMessages();
     const shrunk = shrinkOversizedToolResultsByTokens(before, TURN_END_RESULT_CAP_TOKENS);
@@ -2118,17 +1915,7 @@ var CacheFirstLoop = class {
       }
     }
   }
-  /**
-   * Start a fresh conversation WITHOUT exiting. Drops every message
-   * in the in-memory log AND rewrites the session file to empty so
-   * a resume won't re-hydrate the old turns. Unlike `/forget`, which
-   * deletes the session entirely, this keeps the session name and
-   * config intact — it's the "new chat" button.
-   *
-   * The immutable prefix (system prompt + tool specs) is preserved
-   * — that's the cache-first invariant, not part of the conversation.
-   * Returns the number of messages dropped so the UI can show it.
-   */
+  /** "New chat" — drops messages but keeps session + immutable prefix (cache-first invariant). */
   clearLog() {
     const dropped = this.log.length;
     this.log.compactInPlace([]);
@@ -2141,12 +1928,6 @@ var CacheFirstLoop = class {
     this.scratch.reset();
     return { dropped };
   }
-  /**
-   * Reconfigure model/harvest/branch/stream mid-session. The loop's log,
-   * scratch, and stats are preserved — only the per-turn behavior changes.
-   * Used by the TUI's slash commands and by library callers who want to
-   * flip a knob between turns.
-   */
   configure(opts) {
     if (opts.model !== void 0) this.model = opts.model;
     if (opts.stream !== void 0) this._streamPreference = opts.stream;
@@ -2173,22 +1954,12 @@ var CacheFirstLoop = class {
     }
     this.stream = this.branchEnabled ? false : this._streamPreference;
   }
-  /**
-   * Set / change / clear the soft USD budget. `null` (or any non-
-   * positive number) disables the cap entirely. Re-arms the 80%
-   * warning so a user who bumps the cap mid-session sees a fresh
-   * threshold message at the new boundary.
-   */
+  /** `null` disables the cap; any change re-arms the 80% warning. */
   setBudget(usd) {
     this.budgetUsd = typeof usd === "number" && usd > 0 ? usd : null;
     this._budgetWarned = false;
   }
-  /**
-   * Arm pro for the next turn (consumed at turn start). Called by
-   * `/pro`. Idempotent — repeated calls stay armed, `disarmPro()`
-   * clears. Separate from `/preset max` which persistently switches
-   * this.model; armed state is strictly single-turn.
-   */
+  /** Single-turn upgrade consumed at next step() — distinct from `/preset max` (persistent). */
   armProForNextTurn() {
     this._proArmedForNextTurn = true;
   }
@@ -2204,25 +1975,10 @@ var CacheFirstLoop = class {
   get escalatedThisTurn() {
     return this._escalateThisTurn;
   }
-  /**
-   * Model the current model call should use. Defaults to `this.model`;
-   * upgrades to {@link ESCALATION_MODEL} when the turn is armed for
-   * pro (via `/pro`) or has hit the failure-escalation threshold.
-   * Same thinking + effort policy applies regardless — pro defaults
-   * to thinking=enabled and effort=max, which the current turn wanted
-   * anyway when flash was struggling.
-   */
   modelForCurrentCall() {
     return this._escalateThisTurn ? ESCALATION_MODEL : this.model;
   }
-  /**
-   * Parse the escalation marker out of the model's leading content.
-   * Returns `{ matched: true, reason? }` for both bare and reason-
-   * carrying forms. Only the FIRST line matters — the model is
-   * instructed to emit the marker as the first output token if at
-   * all. Matches anywhere else in the text are normal content
-   * references (e.g. the user asked about the marker itself).
-   */
+  /** Anchored to lead — mid-text matches are normal content (user asking about the marker). */
   parseEscalationMarker(content) {
     const m = NEEDS_PRO_MARKER_RE.exec(content.trimStart());
     if (!m) return { matched: false };
@@ -2233,14 +1989,7 @@ var CacheFirstLoop = class {
   isEscalationRequest(content) {
     return this.parseEscalationMarker(content).matched;
   }
-  /**
-   * Could `buf` STILL plausibly become the full marker as more chunks
-   * arrive? Drives the streaming buffer's flush decision: while this
-   * is true we keep accumulating; once it's false (or the buffer
-   * exceeds the byte limit) we flush so the user isn't staring at a
-   * delayed display for arbitrary content that just happens to start
-   * with `<`.
-   */
+  /** Drives streaming flush — while plausibly partial, keep accumulating; else flush. */
   looksLikePartialEscalationMarker(buf) {
     const t = buf.trimStart();
     if (t.length === 0) return true;
@@ -2252,16 +2001,7 @@ var CacheFirstLoop = class {
     if (rest[0] !== ">" && rest[0] !== ":") return false;
     return true;
   }
-  /**
-   * Check whether a tool result string looks like a "flash struggled"
-   * signal and, if so, increment the turn's failure counter. Escalates
-   * the REST of the current turn to pro once the threshold is hit.
-   * Idempotent after escalation — further failures don't re-escalate,
-   * but the turn is already on pro so it doesn't matter.
-   *
-   * Return: `true` when this call tipped the turn into escalation
-   * mode (so the loop can surface a one-time warning to the user).
-   */
+  /** Returns true ONLY on the tipping call — caller surfaces a one-shot warning. */
   noteToolFailureSignal(resultJson, repair) {
     let bumped = false;
     const bump = (kind, by = 1) => {
@@ -2283,12 +2023,6 @@ var CacheFirstLoop = class {
     }
     return false;
   }
-  /**
-   * Render `_turnFailureTypes` as a comma-separated breakdown like
-   * "2× search-mismatch, 1× truncated" for the auto-escalation
-   * warning. Empty if no types have been recorded yet (defensive —
-   * the warning sites only call this after a bump).
-   */
   formatFailureBreakdown() {
     const parts = Object.entries(this._turnFailureTypes).filter(([, n]) => n > 0).map(([kind, n]) => `${n}\xD7 ${kind}`);
     return parts.length > 0 ? parts.join(", ") : `${this._turnFailureCount} repair/error signal(s)`;
@@ -2299,28 +2033,10 @@ var CacheFirstLoop = class {
     if (pendingUser !== null) msgs.push({ role: "user", content: pendingUser });
     return msgs;
   }
-  /**
-   * Signal the currently-running {@link step} to stop **now**. Cancels
-   * the in-flight network request (DeepSeek HTTP/SSE) AND any tool call
-   * currently dispatching (MCP `notifications/cancelled` + promise
-   * reject). The loop itself also sees `signal.aborted` at each
-   * iteration boundary and exits quickly instead of looping again.
-   * Called by the TUI on Esc.
-   */
   abort() {
     this._turnAbort.abort();
   }
-  /**
-   * Drop everything in the log after (and including) the most recent
-   * user message. Used by `/retry` so the caller can re-send that
-   * message with a fresh turn instead of layering another response on
-   * top of the prior exchange. Returns the content of the dropped user
-   * message, or `null` if there isn't one yet.
-   *
-   * Persists by rewriting the session file — otherwise the next
-   * launch would rehydrate the old exchange and `/retry` would seem
-   * to have done nothing.
-   */
+  /** Drop the last user message + everything after; caller re-sends. Persists to session file. */
   retryLastUser() {
     const entries = this.log.entries;
     let lastUserIdx = -1;
@@ -2931,22 +2647,7 @@ ${summary}`;
     }
     return final;
   }
-  /**
-   * Build an assistant message for the log. The `producingModel` arg is
-   * the model that actually generated this turn (flash, pro, the
-   * forced-summary flash call, `this.model` for synthetics, etc.) —
-   * NOT `this.model`, because escalation + forced-summary can both
-   * route a single turn to a different model.
-   *
-   * The single invariant this encodes: if the producing model is
-   * thinking-mode, `reasoning_content` MUST be present on the
-   * persisted message — even as an empty string. DeepSeek's validator
-   * 400s the NEXT request if any historical thinking-mode assistant
-   * turn is missing it. We used to gate on `reasoning.length > 0`,
-   * which silently dropped the field whenever the stream emitted zero
-   * reasoning deltas or the API returned `reasoning_content: null` —
-   * both legitimate edge cases the 0.5.15/0.5.18 fixes missed.
-   */
+  /** Thinking-mode producer ⇒ reasoning_content MUST be set (even ""), or next call 400s. */
   assistantMessage(content, toolCalls, producingModel, reasoningContent) {
     const msg = { role: "assistant", content };
     if (toolCalls.length > 0) msg.tool_calls = toolCalls;
@@ -2955,13 +2656,7 @@ ${summary}`;
     }
     return msg;
   }
-  /**
-   * Synthetic assistant message (abort notices, future system injections)
-   * — no real API round trip. Delegates to {@link assistantMessage} with
-   * `this.model` as the stand-in producer, so the same thinking-mode
-   * invariant applies: reasoner sessions get an empty-string
-   * `reasoning_content`; V3 sessions get nothing.
-   */
+  /** Abort notices etc — uses this.model as stand-in producer for the thinking-mode stamp. */
   syntheticAssistantMessage(content) {
     return this.assistantMessage(content, [], this.model, "");
   }
@@ -3594,11 +3289,7 @@ var SkillStore = class {
   hasProjectScope() {
     return this.projectRoot !== void 0;
   }
-  /**
-   * Root directories scanned, in priority order. Project scope first
-   * so a per-repo skill overrides a global one with the same name —
-   * users expect the local copy to win when both exist.
-   */
+  /** Project scope first so per-repo skill overrides a global with the same name. */
   roots() {
     const out = [];
     if (this.projectRoot) {
@@ -3610,11 +3301,7 @@ var SkillStore = class {
     out.push({ dir: join6(this.homeDir, ".reasonix", SKILLS_DIRNAME), scope: "global" });
     return out;
   }
-  /**
-   * List every skill visible to this store. On name collisions the
-   * higher-priority root (project over global over builtin) wins.
-   * Sorted by name for stable prefix hashing.
-   */
+  /** Higher-priority root wins on collision (project > global > builtin); sorted for stable prefix hash. */
   list() {
     const byName = /* @__PURE__ */ new Map();
     for (const { dir, scope } of this.roots()) {
@@ -4001,10 +3688,6 @@ var MemoryStore = class {
   hasProjectScope() {
     return this.projectRoot !== void 0;
   }
-  /**
-   * Read the `MEMORY.md` index for a scope. Returns post-cap content
-   * (with a truncation marker if clipped), or `null` when absent / empty.
-   */
   loadIndex(scope) {
     if (scope === "project" && !this.projectRoot) return null;
     const file = join7(
@@ -4043,11 +3726,7 @@ var MemoryStore = class {
       createdAt: data.created ?? ""
     };
   }
-  /**
-   * List every memory in this store. Scans both scopes (skips project
-   * scope if unconfigured). Silently skips malformed files; the index
-   * must stay queryable even if one file is hand-edited into nonsense.
-   */
+  /** Skips malformed files — index stays queryable even if one file is hand-edited into nonsense. */
   list() {
     const out = [];
     const scopes = this.projectRoot ? ["global", "project"] : ["global"];
@@ -4072,11 +3751,6 @@ var MemoryStore = class {
     }
     return out;
   }
-  /**
-   * Write a new memory (or overwrite existing). Creates the scope dir,
-   * writes the `.md` file, and regenerates `MEMORY.md`. Returns the
-   * absolute path written to.
-   */
   write(input) {
     if (input.scope === "project" && !this.projectRoot) {
       throw new Error("cannot write project-scoped memory: no projectRoot configured");
@@ -4112,12 +3786,7 @@ var MemoryStore = class {
     this.regenerateIndex(scope);
     return true;
   }
-  /**
-   * Rebuild `MEMORY.md` from the `.md` files currently in the scope dir.
-   * Called after every write/delete. Sorted by name for stable prefix
-   * hashing — two stores with the same set of files produce byte-identical
-   * MEMORY.md content, keeping the cache prefix reproducible.
-   */
+  /** Sorted by name — same file set must produce byte-identical MEMORY.md for stable prefix hashing. */
   regenerateIndex(scope) {
     const dir = scopeDir({ homeDir: this.homeDir, scope, projectRoot: this.projectRoot });
     if (!existsSync7(dir)) return;
@@ -5053,12 +4722,6 @@ var PlanProposedError = class extends Error {
     this.steps = steps;
     this.summary = summary;
   }
-  /**
-   * Structured tool-result shape. Consumed by the TUI to extract the
-   * plan without regex-scraping the error message. Optional fields
-   * are omitted from the payload when absent so consumers don't see
-   * `undefined` keys in the JSON.
-   */
   toToolResult() {
     const payload = {
       error: `${this.name}: ${this.message}`,
@@ -5569,11 +5232,7 @@ var READY_SIGNALS = [
 var JobRegistry = class {
   jobs = /* @__PURE__ */ new Map();
   nextId = 1;
-  /**
-   * Spawn a background child. Resolves after `waitSec` OR on ready
-   * signal OR on early exit, whichever comes first. The child continues
-   * to run (and buffer output) regardless of which path fires.
-   */
+  /** Resolves on (a) ready signal, (b) early exit, or (c) waitSec deadline — child keeps running regardless. */
   async start(command, opts) {
     const trimmed = command.trim();
     if (!trimmed) throw new Error("run_background: empty command");
@@ -5708,12 +5367,6 @@ ${job.output.slice(start)}`;
       exitCode: job.exitCode
     };
   }
-  /**
-   * Read a job's accumulated output. `since` lets a caller poll
-   * incrementally: pass the byte count returned from the last call to
-   * get only newly-written content. Returns both full output and a
-   * running snapshot so the caller can use whichever.
-   */
   read(id, opts = {}) {
     const job = this.jobs.get(id);
     if (!job) return null;
@@ -5737,11 +5390,7 @@ ${job.output.slice(start)}`;
       spawnError: job.spawnError
     };
   }
-  /**
-   * Send SIGTERM, wait `graceMs`, then SIGKILL if still alive. Returns
-   * the final job record (or null when the job id is unknown). Safe to
-   * call on an already-exited job — returns the record unchanged.
-   */
+  /** SIGTERM, wait graceMs, then SIGKILL. Idempotent on already-exited jobs. */
   async stop(id, opts = {}) {
     const job = this.jobs.get(id);
     if (!job) return null;
@@ -5772,11 +5421,6 @@ ${job.output.slice(start)}`;
   list() {
     return [...this.jobs.values()].map(snapshot);
   }
-  /**
-   * Best-effort kill of every still-running job. Called on TUI shutdown
-   * so dev servers don't outlive the Reasonix process. Resolves after
-   * every child has closed or a hard deadline passes (3s total).
-   */
   async shutdown(deadlineMs = 5e3) {
     const start = Date.now();
     const runningJobs = [...this.jobs.values()].filter((j) => j.running && j.child);
@@ -7240,10 +6884,7 @@ var McpClient = class {
   get serverInstructions() {
     return this._instructions;
   }
-  /**
-   * Complete the initialize → initialized handshake. Must be called
-   * before any other method (otherwise compliant servers reject).
-   */
+  /** Compliant servers reject other methods until this completes. */
   async initialize() {
     if (this.initialized) throw new Error("MCP client already initialized");
     this.startReaderIfNeeded();
@@ -7273,22 +6914,7 @@ var McpClient = class {
     this.assertInitialized();
     return this.request("tools/list", {});
   }
-  /**
-   * Invoke a tool by name. When `onProgress` is supplied, attaches a
-   * fresh progress token so the server can send incremental updates
-   * via `notifications/progress`; they're routed to the callback until
-   * the final response arrives (or the request times out, in which
-   * case the handler is simply dropped — no extra notification).
-   *
-   * When `signal` is supplied, aborting it:
-   *   1) fires `notifications/cancelled` to the server (MCP 2024-11-05
-   *      way of saying "forget this request, I no longer care"), and
-   *   2) rejects the pending promise immediately with an AbortError,
-   *      so the caller doesn't have to wait for the subprocess to
-   *      finish its in-flight file write or network request.
-   * The server MAY still emit a late response; we drop it in dispatch
-   * since the request id is gone from `pending`.
-   */
+  /** Abort sends `notifications/cancelled` and rejects immediately; late server responses are dropped. */
   async callTool(name, args, opts = {}) {
     this.assertInitialized();
     const params = { name, arguments: args ?? {} };
@@ -7304,13 +6930,7 @@ var McpClient = class {
       if (token !== void 0) this.progressHandlers.delete(token);
     }
   }
-  /**
-   * List resources the server exposes. Supports a pagination cursor;
-   * callers interested in the full set should loop on `nextCursor`.
-   * Servers that don't support resources respond with method-not-found
-   * (−32601) — we surface that as a thrown Error so callers can gate
-   * on the `serverCapabilities.resources` field first.
-   */
+  /** Throws on method-not-found; callers should gate on `serverCapabilities.resources` first. */
   async listResources(cursor) {
     this.assertInitialized();
     return this.request("resources/list", {
@@ -7331,11 +6951,6 @@ var McpClient = class {
       ...cursor ? { cursor } : {}
     });
   }
-  /**
-   * Fetch a rendered prompt by name. `args` supplies values for any
-   * required template arguments; the server validates. Returns messages
-   * ready to prepend to the model's input.
-   */
   async getPrompt(name, args) {
     this.assertInitialized();
     return this.request("prompts/get", {
@@ -7352,7 +6967,6 @@ var McpClient = class {
     this.pending.clear();
     await this.transport.close();
   }
-  // ---------- internals ----------
   assertInitialized() {
     if (!this.initialized) throw new Error("MCP client not initialized \u2014 call initialize() first");
   }
@@ -7620,7 +7234,6 @@ var SseTransport = class {
     } catch {
     }
   }
-  // ---------- internals ----------
   async runStream() {
     let res;
     try {
@@ -7812,7 +7425,6 @@ var StreamableHttpTransport = class {
   getSessionId() {
     return this.sessionId;
   }
-  // ---------- internals ----------
   async consumeStream(body) {
     const parser = createParser3({
       onEvent: (ev) => {