zames_pro 2.55.0 → 2.59.0

package/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.59.0]
+
+### Added
+
+- `/improve [id]` — a backlog-driven self-improvement loop. It picks the
+  next open item from `BACKLOG.md` (highest priority, or an explicit id),
+  runs the standard task loop on it (implement, typecheck/lint/test, mark
+  the item done, add a CHANGELOG entry) and leaves the changes uncommitted
+  for review. This is the reproducible hand-off path for a fresh agent.
+
+## [2.58.0]
+
+### Added
+
+- `--output-format json|jsonl` for one-shot runs: transcript events are
+  streamed as JSON lines on stdout (human text goes to stderr), so zames
+  pipes into `jq` and CI pipelines. `Transcript` gained an `onLine` mirror.
+- Loop detection: four identical tool calls in a row trigger a nudge to
+  change approach instead of repeating the same call forever.
+- MCP configs pinned to `@latest`/`@next` now warn (in `/mcp` and at
+  startup) so the tool set does not silently change between runs.
+- `/help` is grouped into sections (session / workspace / git / agent /
+  context / files) instead of one long list.
+- `Grep` accepts a comma-separated `include` list.
+- System prompt: a "Choosing the right tool" section (Edit vs MultiEdit vs
+  ApplyPatch, Grep vs Glob vs LS, Git tools vs Bash).
+
+### Changed
+
+- `coverage-gate` enforces floors for 8 more modules and prints the
+  lowest-covered modules in the CI log.
+- README: Why zames?, an FAQ and a machine-readable-output section.
+- Dependabot config for npm and GitHub Actions.
+
+## [2.57.1]
+
+### Changed
+
+- CI workflows use actions/checkout@v5 and actions/setup-node@v5 (the v4
+  actions run on the deprecated Node 20 runtime and showed up as an
+  annotation on every run).
+
+### Added
+
+- README badges (npm version/downloads, CI status, license, Node, PRs) and a
+  Features section, so the GitHub landing page and the npm page show what the
+  project is at a glance.
+- Community files: issue forms (bug report, feature request), a PR template
+  and CODE_OF_CONDUCT.md.
+- package.json: a fuller description and more keywords (npm search), and
+  CHANGELOG.md is now included in the published files.
+
+## [2.57.0]
+
+### Added
+
+- Plan mode (read-only): start with --plan or toggle with /plan [on|off].
+  In this mode mutating tools (Write/Edit/MultiEdit/ApplyPatch/Bash, GitAdd/
+  GitCommit/GitPush) are removed from the tool set entirely, so the agent can
+  investigate without touching the tree.
+- src/fsutil.ts - one shared atomic writer (writeFileAtomic/writeJsonAtomic).
+
+### Changed
+
+- config, sessions and undo now share the single atomic writer (the
+  temp-file+rename logic used to be copy-pasted in three places).
+
+### Fixed
+
+- BACKLOG.md is now git-ignored and untracked: it is the agent's own
+  improvement-notes file, rewritten constantly, and used to be published with
+  the package.
+- GitPush validates the branch name before building the shell command, so a
+  model-supplied branch cannot smuggle shell metacharacters.
+- SECURITY.md no longer promises a /permissions command / alwaysConfirm list
+  that was removed in 2.55.0; AGENTS.md cleaned of the same dead refs.
+
+## [2.56.0]
+
+### Added
+
+- `/context` — show what is loaded into the prompt (AGENTS.md, MEMORY.md,
+  skills, custom commands) plus the system-prompt size.
+- `/retry` — resend the last task into the same chat (handy after a truncated
+  or empty answer).
+- `/rename <title>` — set the current session title (shown in `/sessions`).
+- `/diffstat` — a one-line `git diff --stat` change summary.
+- `/copy` — copy the last assistant answer to the OS clipboard (wl-copy /
+  xclip / xsel / pbcopy / clip).
+- `GitShow` and `GitBranchList` git tools (read-only).
+- The status line now shows the elapsed time of the current phase ("45s",
+  "2m 05s") in BOTH the LineEditor and the non-TTY spinner, and the spinner
+  shows the same "tasks: 2/5" badge the editor does.
+- A one-time hint when the context reaches ~80% while auto-compact is off,
+  pointing at `/compact`.
+- Tests: dead-i18n-key guard, agent-facing-no-Cyrillic guard, CLI flag
+  consistency, binary content-type handling for `WebFetch`.
+
+### Changed
+
+- `WebFetch` returns a short human note for binary content types (PDF, images,
+  archives, ...) instead of dumping raw bytes into the model context.
+- `npm run build` now wipes `dist/` first (`scripts/clean-dist.mjs`), so a
+  removed source file no longer leaves an orphan `.js` in the package.
+
+### Fixed
+
+- `/undo` failure reasons are localized: `src/undo.ts` returned hardcoded
+  Russian strings that showed up in an English UI. It now returns machine codes
+  ('empty' / 'disabled') localized by the caller.
+- Removed the dead `--project` flag (it only swallowed the following argument)
+  and the no-op `--calibrate` flag together with their help/i18n entries.
+- Removed the orphaned `confirm.hint` / `confirm.ask_label` i18n keys left by
+  the confirm-subsystem removal.
+- README Node requirement aligned with `engines` / `.nvmrc` (>= 20).
+- `GitBranchList` quotes its `--format` argument so the POSIX shell does not
+  choke on the parentheses/brackets in the format string.
+
+## [2.55.0]
+
+### Added
+
+- `!command` in the prompt runs a shell command directly, bypassing the model
+  (like Claude Code's bash mode). The same sandbox guard as the `Bash` tool
+  applies, so a direct command cannot leave the project.
+- `/remember <text>` appends a durable note to the project `MEMORY.md`, so a
+  fact worth keeping across sessions is written to disk instead of living only
+  in the chat.
+- `/skills`, `/memory`, `/remember`, `/init` and `/mcp` are now listed in the
+  `/help` output (they were only in the «/» completion list before).
+
+### Changed
+
+- The shell runner moved to `src/shell.ts`, shared by the `Bash` tool and the
+  new `!command` escape (one sandbox guard, one abort wiring).
+- `/self-review` now copies root configs (`package.json`, `eslint.config.js`,
+  `tsconfig*.json`, `.prettierrc`) and `scripts/**` into a read-only `_context/`
+  folder of the snapshot, so the reviewer can read them. The editable set
+  (diff/apply) stays `.ts`-only.
+- `package.json` gained `packageManager: npm@11.19.0`.
+
+### Fixed
+
+- The status line no longer prefixes a running-tool indicator with the
+  previous answer's "done" phase (e.g. `✓ done: running Bash`): `toolCall()`
+  clears the send-phase state before starting the tool animation.
+
+### Removed
+
+- The never-wired tool-confirmation subsystem: `src/confirm.ts`
+  (`ConfirmManager`/`formatDiffPreview`) was fully implemented and tested but
+  never called by the runtime, so `confirmation.write/edit/bash`,
+  `alwaysConfirm` and the `/permissions` command did nothing. Removed the
+  module, its tests, the config keys, the `/permissions` command and the
+  related i18n strings.
+
+## [2.54.0]
+
+### Added
+
+- New unit tests for previously uncovered modules: `diff.ts` (unified/color
+  diff), `spinner.ts` (ellipsis/dots/UI surface), `confirm.ts`
+  (confirmation logic + alwaysConfirm fallback) and `markdown.ts`
+  (rendering of headings, lists, code, tables).
+
+- `WebFetch` now blocks private/loopback/link-local addresses (SSRF guard,
+  including cloud metadata `169.254.169.254`) and retries transient network
+  errors and 5xx responses with exponential backoff.
+- CI prints per-file test coverage (`node --experimental-test-coverage`) so
+  untested modules are visible in the log (informational, does not fail).
+
+### Changed
+
+- The `pre-push` git hook no longer runs the full test suite (it was fragile
+  and timed out on tag pushes); tests stay in `pre-commit` and CI.
+
+## [2.53.1]
+
+### Fixed
+
+- `require('fs')` in ESM modules (`src/attachments.ts`, `src/self-review.ts`)
+  threw `ReferenceError` at runtime: WSL clipboard detection always returned
+  `false` and `/self-review` found no sources when run from the built `dist/`.
+- Config, session and undo index writes are now atomic (temp file + rename),
+  so a crash or Ctrl+C mid-write can no longer corrupt `~/.zames/config.json`
+  or a saved session.
+
+### Changed
+
+- Removed the unused `marked` dependency (Markdown is rendered by `markdansi`).
+- CI installs dependencies with `npm ci` for reproducible builds.
+- The i18n test now validates the whole `CATALOG` instead of a small sample.
+- Added `.nvmrc` (Node 24).
+
+## [2.53.0]
+
+### Added
+
+- Session banner warns when no saved DeepSeek session exists.
+- `--no-color` flag (explicit `NO_COLOR`).
+
+[Unreleased]: https://github.com/Viqto0r/zames_pro/compare/v2.59.0...HEAD
+[2.59.0]: https://github.com/Viqto0r/zames_pro/compare/v2.58.0...v2.59.0
+[2.58.0]: https://github.com/Viqto0r/zames_pro/compare/v2.57.1...v2.58.0
+[2.57.1]: https://github.com/Viqto0r/zames_pro/compare/v2.57.0...v2.57.1
+[2.57.0]: https://github.com/Viqto0r/zames_pro/compare/v2.56.0...v2.57.0
+[2.56.0]: https://github.com/Viqto0r/zames_pro/compare/v2.55.0...v2.56.0
+[2.55.0]: https://github.com/Viqto0r/zames_pro/compare/v2.54.0...v2.55.0
+[2.54.0]: https://github.com/Viqto0r/zames_pro/compare/v2.53.1...v2.54.0
+[2.53.1]: https://github.com/Viqto0r/zames_pro/compare/v2.53.0...v2.53.1
+[2.53.0]: https://github.com/Viqto0r/zames_pro/releases/tag/v2.53.0

package/README.md

@@ -1,14 +1,53 @@
 # zames_pro
 
+[![npm version](https://img.shields.io/npm/v/zames_pro.svg)](https://www.npmjs.com/package/zames_pro)
+[![npm downloads](https://img.shields.io/npm/dm/zames_pro.svg)](https://www.npmjs.com/package/zames_pro)
+[![tests](https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml/badge.svg)](https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](package.json)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
 ![zames logo](https://raw.githubusercontent.com/Viqto0r/zames_pro/master/logo.jpg)
 
 A terminal coding agent that works on top of [chat.deepseek.com](https://chat.deepseek.com/) through Playwright.
 In spirit it is similar to Claude Code / Codex CLI: it starts in the current
 directory, reads and edits files, runs commands, and commits to git.
 
+> No API key required — it drives the DeepSeek web chat like a regular user
+> through a real (headless) browser.
+
+## Features
+
+- **Tools like Claude Code / Codex** — `Read`, `Write`, `Edit`, `Bash`,
+  `Glob`, `Grep`, plus `MultiEdit`, `ApplyPatch`, `LS`, `TodoWrite`, git and web
+  tools. Every edit is backed by `/undo`.
+- **Runs while you keep typing** — queue messages during a task; they run right
+  after it, in the same chat (like typing during generation on the web).
+- **Plan mode** — `/plan` (or `--plan`) drops all mutating tools, so the agent
+  can investigate the code without touching the tree.
+- **Project context** — reads `AGENTS.md`, `MEMORY.md`, skills (`SKILL.md`) and
+  custom commands from the repo and `~/.zames`, the same idea as Codex / Claude
+  Code.
+- **MCP support** — plug in external tool servers (e.g. `@playwright/mcp`).
+- **Self-review** — `/self-review` snapshots `src/` so the agent can review and
+  fix itself in a sandbox (`/self-fix`, `/self-apply`).
+- **Scheduling** — `/loop`, `/cron` and `/jobs` repeat tasks on a timer.
+- **Bilingual UI** — Russian / English (`/config lang`).
+
+## Why zames?
+
+- **No API key, no per-token bill** — it uses your own DeepSeek chat account,
+  not the paid API. Good for long, tool-heavy tasks.
+- **Same workflow as Claude Code / Codex** — tools, `AGENTS.md`, skills, MCP
+  and slash commands, so it feels familiar from day one.
+- **Runs unattended** — headless by default, resumable sessions, and `/loop`
+  plus `/cron` for scheduled work.
+- **Local-first** — the browser profile, credentials and logs never leave your
+  machine, and the agent is sandboxed to the project directory.
+
 ## Requirements
 
-- Node.js >= 18
+- Node.js >= 20 (CI and development use Node 24; see `.nvmrc`)
 - A DeepSeek account. On first launch zames asks for your DeepSeek
   login/password in the terminal (and stores them in `~/.zames/config.json`
   after a successful sign-in, so a later logout is handled automatically
@@ -46,6 +85,13 @@ version). You do not need `--headed` just to log in.
 Credentials and toggles can also be edited from `/config`
 (`browser.auth.username`, `browser.auth.password`, `browser.auth.saveSession`).
 
+## Links
+
+- npm: <https://www.npmjs.com/package/zames_pro>
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Security policy: [`SECURITY.md`](SECURITY.md)
+
 ## Installation
 
 ```bash
@@ -127,11 +173,30 @@ zames --resend-prompt
 zames --dir <path>
 zames --headless
 zames --headed
+zames --plan
+zames --output-format jsonl
 zames --debug
 zames --version
 zames --help
 ```
 
+### Machine-readable output (scripts / CI)
+
+For one-shot runs (`--task`) the agent can emit its event stream as JSON lines
+on stdout, keeping all human text on stderr:
+
+```bash
+zames --task "summarize the diff" --output-format jsonl
+```
+
+Each line is one event (`tool_call`, `tool_result`, `assistant_final`, ...), so
+it pipes straight into `jq`:
+
+```bash
+zames --task "..." --output-format jsonl \
+  | jq -r 'select(.type=="assistant_final") | .message'
+```
+
 ## Tools
 
 The agent has the same style of tools as Claude Code / Codex CLI:
@@ -142,7 +207,8 @@ The agent has the same style of tools as Claude Code / Codex CLI:
 - **Extra tools** — `LS` (list a directory), `MultiEdit` (several edits to one
   file applied atomically), `TodoWrite` (session task checklist), `ApplyPatch`
   (multi-file patch in Codex's V4A format: `*** Begin Patch` … `*** End Patch`).
-- **Git** — `GitStatus`, `GitDiff`, `GitLog`, `GitAdd`, `GitCommit`, `GitPush`.
+- **Git** — `GitStatus`, `GitDiff`, `GitLog`, `GitShow`, `GitBranchList`,
+  `GitAdd`, `GitCommit`, `GitPush`.
 - **Web** — `WebFetch`, `WebSearch`.
 - **Service** — `respond` (final answer to the operator, ends the task).
 
@@ -158,6 +224,13 @@ config commands (/new, /chats, /resume, /cd, /status, /config,
 Codex CLI:
 
 - /diff [--staged] — show the working-tree git diff (--staged for the index).
+- /diffstat — a one-line change summary (`git diff --stat`).
+- /context — show what is loaded into the prompt (AGENTS.md, MEMORY.md,
+  skills, custom commands) and the system-prompt size.
+- /retry — resend the last task into the same chat (handy after a truncated
+  or empty answer).
+- /rename <title> — set the current session title (shown in /sessions).
+- /copy — copy the last assistant answer to the OS clipboard.
 - /cost (alias /usage) — session stats: tasks, tool calls, duration, and the
   context size in tokens (DeepSeek's `accumulated_token_usage`).
 - /export [file] — write the session transcript to a Markdown file
@@ -174,6 +247,14 @@ Codex CLI:
   instead of the whole list.
 - /review [focus] [--staged] — ask the agent to review uncommitted changes
   and report findings (no code changes).
+- /improve [id] — self-improvement loop: take the next open item from
+  `BACKLOG.md` (or a specific id, e.g. `/improve B3`), implement it, run the
+  typecheck/lint/tests, mark it done and add a CHANGELOG entry. Nothing is
+  committed — the changes stay in the working tree for review.
+- /plan [on|off] — plan (read-only) mode. While it is on, the mutating tools
+  (Write/Edit/MultiEdit/ApplyPatch/Bash, GitAdd/GitCommit/GitPush) are removed
+  from the tool set, so the agent can investigate without touching the tree.
+  Start in it with `--plan`.
 - /compact — ask DeepSeek to compress the current chat into a handover
   summary, then open a NEW chat, resend the system prompt and post the summary
   as the carried-over context. Use it when the context gets long.
@@ -305,6 +386,34 @@ locale lives in `ui.locale` in the config file.
 
 Agent data is stored in `~/.zames`: browser profile, logs, undo history, self-review snapshots.
 
+## FAQ
+
+**Is this an official DeepSeek product?**
+No. zames drives the public chat.deepseek.com web UI through a real browser,
+like a regular user. It is not affiliated with DeepSeek.
+
+**Do I need an API key?**
+No. You sign in with your own DeepSeek account once; the session is stored in
+`~/.zames/profile` and reused.
+
+**Which model does it use?**
+Whichever the DeepSeek web chat uses (DeepSeek-V3, or the reasoning model with
+"Deep thinking" on). zames never calls the API directly.
+
+**Does it work headless / on a server?**
+Yes — headless is the default, and `--output-format jsonl` makes it scriptable.
+`--headed` is only needed for a manual sign-in or selector debugging.
+
+**Is automating the web UI allowed?**
+That depends on DeepSeek's terms; automating a website may violate them. Use at
+your own risk and keep the send throttle (15s by default) so you do not hammer
+the rate limit.
+
+**How is it different from Claude Code / Codex?**
+Same shape (tools, `AGENTS.md`, skills, MCP, slash commands) but it runs on your
+DeepSeek account instead of an API, as a browser automation rather than a
+first-party API client.
+
 ## License
 
 MIT

package/dist/agent-loop.js

@@ -146,6 +146,12 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 'Look at the uploaded images in the chat; file copies are in <project>/tmp.)';
     }
     transcript?.log('task', { task });
+    // Each guard keeps its OWN cap IN ADDITION to the shared budget below.
+    // Reason: the shared budget is replenished after every successful tool, so
+    // over a long chain of tools a single misbehaving guard could re-ask more
+    // than intended; the per-guard cap keeps any one failure mode bounded. The
+    // named counters are all reset together after a tool runs (see the reset
+    // block after the tool loop).
     let malformedRetries = 0;
     const MAX_MALFORMED_RETRIES = 3;
     let stallRetries = 0;
@@ -190,6 +196,16 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
     // Retry budget for a browser.ask() TIMEOUT (not for content): the send did
     // not come back in time. This is separate from unparsedRetries because a
     // timeout is an infrastructure failure, not a model protocol violation.
+    // Loop detection: the model sometimes repeats the SAME tool call with the
+    // SAME arguments (e.g. Read the same file) turn after turn. There was no
+    // explicit detector for that — the stale-answer guard only catches a
+    // repeated ANSWER, not a repeated call. Track the signature of the last
+    // batch of calls; after MAX_REPEAT_CALLS identical batches in a row, stop
+    // running it and nudge the model to change approach.
+    let lastCallSig = '';
+    let repeatCallCount = 0;
+    const MAX_REPEAT_CALLS = 4;
+    let repeatWarned = false;
     let afterToolRetries = 0;
     // toolsRanInTask: how many tools actually ran in THIS task. The protocol
     // guard uses it to tell "started, then slipped into chat mode" (a reasoning
@@ -197,6 +213,10 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
     // short answer. We key on the STRUCTURE (work already started), not words.
     let toolsRanInTask = 0;
     const MAX_AFTER_TOOL_RETRIES = Math.max(0, Math.floor(maxAfterToolRetries));
+    // One-time hint when the context nears full while auto-compact is OFF:
+    // the operator is told about /compact instead of silently degrading. Set
+    // once per task so the terminal is not spammed.
+    let contextHintShown = false;
     // Token count at which the last auto-compact fired. Re-arm only after
     // the (fresh) chat grows past this plus a margin, so a chat that starts
     // above the threshold does not compact on every tool call.
@@ -639,6 +659,38 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
         // message must NOT be delivered before the tools' results are known.
         // The model will get the tool results and can call respond again.
         const callsToRun = realCalls.length > 0 ? realCalls : calls;
+        // Stable signature of this batch (sorted keys) for loop detection.
+        const callSig = callsToRun
+            .map((c) => c.tool +
+            ':' +
+            JSON.stringify(c.args, Object.keys(c.args || {}).sort()))
+            .join('|');
+        if (callSig && callSig === lastCallSig)
+            repeatCallCount++;
+        else {
+            lastCallSig = callSig;
+            repeatCallCount = 1;
+            repeatWarned = false;
+        }
+        if (repeatCallCount >= MAX_REPEAT_CALLS) {
+            transcript?.log('tool_loop_detected', {
+                sig: callSig.slice(0, 300),
+                count: repeatCallCount,
+            });
+            if (!repeatWarned) {
+                repeatWarned = true;
+                safeWarning(translate(locale)('msg.tool_loop'));
+            }
+            // Reset so a single nudge does not carry into the next different call.
+            repeatCallCount = 0;
+            lastCallSig = '';
+            message =
+                'You have called the SAME tool with the SAME arguments several times ' +
+                    'in a row. Stop repeating it. Either try a different tool or approach, ' +
+                    'or, if the task is done, call respond with the final message. Do NOT ' +
+                    'repeat the identical call.';
+            continue;
+        }
         for (const call of callsToRun) {
             const tool = tools.find((t) => t.name === call.tool);
             if (!tool) {
@@ -784,6 +836,21 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 }
             }
         }
+        else if (getTokenUsage && !contextHintShown) {
+            // Auto-compact is OFF (the default). The context can still fill up and
+            // silently degrade the answers, so tell the operator ONCE that /compact
+            // exists. Same 80% threshold the status line uses to turn red.
+            const tokens = getTokenUsage();
+            if (tokens !== null && Number.isFinite(tokens) && tokens > 0) {
+                const pct = (tokens / contextLimit) * 100;
+                if (pct >= 80) {
+                    contextHintShown = true;
+                    safeWarning(translate(locale)('context.near_full', {
+                        pct: String(Math.round(pct)),
+                    }));
+                }
+            }
+        }
     }
     return 'Iteration limit reached.';
 }

package/dist/attachments.js

@@ -367,6 +367,38 @@ function tryCommand(bin, args) {
         return null;
     }
 }
+// Write text to the OS clipboard. Mirrors readClipboardImageDetailed: every
+// platform has its own tool, and a failure is returned (not thrown) so the
+// caller can tell the operator which tool was missing.
+export function writeClipboardText(text) {
+    const data = Buffer.from(String(text ?? ''), 'utf-8');
+    const win = process.platform === 'win32';
+    const mac = process.platform === 'darwin';
+    const candidates = win
+        ? [{ bin: 'clip', args: [] }]
+        : mac
+            ? [{ bin: 'pbcopy', args: [] }]
+            : [
+                { bin: 'wl-copy', args: [] },
+                { bin: 'xclip', args: ['-selection', 'clipboard'] },
+                { bin: 'xsel', args: ['--clipboard', '--input'] },
+            ];
+    for (const c of candidates) {
+        try {
+            execFileSync(c.bin, c.args, {
+                input: data,
+                stdio: ['pipe', 'ignore', 'ignore'],
+                timeout: 8000,
+                windowsHide: true,
+            });
+            return { ok: true, via: c.bin };
+        }
+        catch {
+            // try the next tool
+        }
+    }
+    return { ok: false, via: candidates.map((c) => c.bin).join('/') };
+}
 export async function findFileByName(workdir, name) {
     const candidate = path.resolve(workdir, name);
     if (await fs.stat(candidate).catch(() => null))

package/dist/commands.js

@@ -25,6 +25,58 @@ export function formatDiff(diffText, opts = {}, t = translate('en')) {
 export function diffGitArgs(staged = false) {
     return staged ? 'git diff --staged' : 'git diff';
 }
+// ---------- /diffstat ----------
+/** Render `git diff --stat` output (a compact change summary) for display. */
+export function formatDiffStat(statText, opts = {}, t = translate('en')) {
+    const maxLines = opts.maxLines ?? 60;
+    const trimmed = String(statText ?? '')
+        .split(CR + NL)
+        .join(NL)
+        .trimEnd();
+    if (!trimmed || trimmed === '(command produced no output)') {
+        return t('diff.no_changes');
+    }
+    const lines = trimmed.split(NL);
+    if (lines.length <= maxLines)
+        return trimmed;
+    const head = lines.slice(0, maxLines).join(NL);
+    return (head + NL + t('diff.more_lines', { n: String(lines.length - maxLines) }));
+}
+// ---------- /context ----------
+/** One renderable line per loaded context source (file + char count). */
+export function formatContextSources(agents, memory, skills, commands, opts = {}, t = translate('en')) {
+    const lines = [];
+    lines.push(t('context.title'));
+    if (typeof opts.systemPromptChars === 'number') {
+        lines.push(t('context.system_prompt', { n: String(opts.systemPromptChars) }));
+    }
+    const fileLine = (p, content) => '  ' + p + '  (' + content.length + ' chars)';
+    lines.push(t('context.agents'));
+    if (agents.length)
+        for (const a of agents)
+            lines.push(fileLine(a.path, a.content));
+    else
+        lines.push('  ' + t('context.none'));
+    lines.push(t('context.memory'));
+    if (memory.length)
+        for (const m of memory)
+            lines.push(fileLine(m.path, m.content));
+    else
+        lines.push('  ' + t('context.none'));
+    lines.push(t('context.skills'));
+    if (skills.length)
+        for (const s of skills)
+            lines.push('  ' + s.name + (s.path ? '  ' + s.path : ''));
+    else
+        lines.push('  ' + t('context.none'));
+    lines.push(t('context.commands'));
+    if (commands.length)
+        for (const c of commands)
+            lines.push('  /' + c.name);
+    else
+        lines.push('  ' + t('context.none'));
+    return lines.join(NL);
+}
 export function summarizeTranscript(entries) {
     const stats = {
         turns: 0,
@@ -655,6 +707,79 @@ export function mergeMessages(msgs) {
     const text = header + NL + NL + parts.join(NL + NL + '---' + NL + NL);
     return { text, attachments };
 }
+// Parse BACKLOG.md into actionable items. Recognizes headings of the form
+// `### A1. ...`, `### D7. ...` and marks an item done when its heading carries
+// a `[x]` marker. Pure; unit-tested. We deliberately do NOT parse the whole
+// markdown structure — only the headings the file contract promises.
+export function parseBacklogItems(text) {
+    const out = [];
+    let priority = '';
+    for (const raw of String(text ?? '').split(NL)) {
+        const line = raw.trimEnd();
+        const p = /^##\s+(P[0-3])\b/.exec(line);
+        if (p) {
+            priority = p[1];
+            continue;
+        }
+        const m = /^###\s+([A-Z]\d+)\.\s+(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const id = m[1];
+        const rest = m[2];
+        // The `[x]` rewrite in BACKLOG keeps the ORIGINAL heading under a
+        // <details> block wrapped in `~~`. That archived copy must not be counted
+        // as a second, open item — skip a heading whose text starts with `~~`.
+        if (rest.trim().startsWith('~~'))
+            continue;
+        const done = /^\[x\]/i.test(rest.trim());
+        // The title is the heading text with the [x] marker and the `~~` strike
+        // wrappers removed, so a done item still has a clean label.
+        const title = rest
+            .replace(/^\[x\]\s*/i, '')
+            .replace(/~~/g, '')
+            .trim();
+        out.push({ id, title, status: done ? 'done' : 'open', priority });
+    }
+    return out;
+}
+// The next item to work on: the highest-priority OPEN item, in file order.
+// P0 first, then P1..P3. An explicit id overrides the priority search.
+export function nextBacklogItem(items, wanted) {
+    const open = items.filter((i) => i.status === 'open');
+    if (wanted) {
+        const w = wanted.trim().toUpperCase();
+        return items.find((i) => i.id.toUpperCase() === w) || null;
+    }
+    if (!open.length)
+        return null;
+    const rank = (p) => {
+        const m = /P(\d)/.exec(p || '');
+        return m ? Number(m[1]) : 9;
+    };
+    return open.slice().sort((a, b) => rank(a.priority) - rank(b.priority))[0];
+}
+// The task text sent to the agent for a chosen item. Agent-facing English,
+// like the rest of the loop. Keeps the working rules explicit so a fresh agent
+// does not need any external context.
+export function buildImprovePrompt(item) {
+    return ('Implement BACKLOG item ' +
+        item.id +
+        ' (priority ' +
+        (item.priority || '?') +
+        '): ' +
+        item.title +
+        NL +
+        NL +
+        'Read the full item text in BACKLOG.md for the details and the rationale. ' +
+        'Then: (1) implement it with the smallest reasonable change; ' +
+        '(2) run `npm run typecheck`, `npm run lint`, `npm run format:check` and ' +
+        '`npm test` and fix any failure; (3) mark the item done in BACKLOG.md by ' +
+        'prefixing its heading with `[x]` and wrapping the original heading text ' +
+        'in `~~ ~~`; (4) add a CHANGELOG entry if the change is user-visible; ' +
+        '(5) do NOT commit or push — leave the changes staged in the working tree ' +
+        'for the operator to review. When done, call respond with a short report ' +
+        '(files changed, tests run, whether BACKLOG/CHANGELOG were updated).');
+}
 // ---------- /review ----------
 export function buildReviewPrompt(focus, hasStaged = false) {
     const scope = hasStaged ? 'staged' : 'uncommitted';