zames_pro 2.60.0 → 2.63.0

package/dist/checkpoint.js

@@ -0,0 +1,197 @@
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { execFile } from 'child_process';
+import { writeJsonAtomic } from './fsutil.js';
+// Checkpoints / rewind (BACKLOG B3).
+//
+// Undo (src/undo.ts) reverts ONE file write. A checkpoint snapshots the WHOLE
+// working tree at the start of a task, so a risky task can be rolled back with
+// a single `/rewind`. A tarball — not a git stash — is used on purpose: it
+// works in a non-git directory and never touches the operator's index/stash.
+//
+// Machine codes only ('not_found', 'archive_missing', ...): the caller
+// (src/index.ts) localizes them through the i18n catalog, exactly like
+// undo.ts. Keeping prose out of this module is also why no Russian leaks here
+// (see test/agent-facing-english.test.ts).
+const CHECKPOINT_DIR = path.join(os.homedir(), '.zames', 'checkpoints');
+// Never snapshotted and never deleted on restore: dependencies, the git object
+// store (the operator's own safety net), build output and the agent's scratch
+// dir. Everything else is part of the snapshot. Patterns are anchored to the
+// archive root ('./x') so a nested `src/tmp` is NOT accidentally excluded.
+export const CHECKPOINT_EXCLUDES = ['node_modules', '.git', 'dist', 'tmp'];
+// ---------- pure helpers (unit-tested without tar) ----------
+export function tarCreateArgs(archive, _dir) {
+    const args = ['-czf', archive];
+    for (const e of CHECKPOINT_EXCLUDES)
+        args.push('--exclude=./' + e);
+    args.push('-C', _dir, '.');
+    return args;
+}
+export function tarExtractArgs(archive, dir) {
+    return ['-xzf', archive, '-C', dir];
+}
+/** Keep only the newest `max` records (returns a new array; order preserved). */
+export function rotateRecords(records, max) {
+    if (max <= 0)
+        return [];
+    if (records.length <= max)
+        return records.slice();
+    return records.slice(records.length - max);
+}
+/**
+ * Resolve a `/rewind` selector against records sorted NEWEST FIRST.
+ * `1` = most recent; a non-numeric selector is matched as a stamp prefix.
+ */
+export function pickRecord(records, selector) {
+    const sel = String(selector ?? '').trim();
+    if (!sel)
+        return null;
+    if (/^\d+$/.test(sel)) {
+        const n = Number(sel);
+        // A small number is an index (1 = newest). An out-of-range number is
+        // still tried as a stamp prefix below, so `/rewind 1730000` works.
+        if (n >= 1 && n <= records.length)
+            return records[n - 1];
+    }
+    return records.find((r) => String(r.stamp).startsWith(sel)) || null;
+}
+// ---------- tar / fs plumbing ----------
+function runTar(args, cwd, timeout = 60_000) {
+    return new Promise((resolve) => {
+        execFile('tar', args, { cwd, timeout, maxBuffer: 1024 * 1024 * 8, windowsHide: true }, (err, _stdout, stderr) => {
+            if (!err)
+                return resolve({ code: 0, stderr: '' });
+            const raw = err.code;
+            const code = typeof raw === 'number' ? raw : 127;
+            resolve({ code, stderr: String(stderr || err.message || '') });
+        });
+    });
+}
+async function copyTree(from, to) {
+    await fs.mkdir(to, { recursive: true });
+    const entries = await fs.readdir(from, { withFileTypes: true });
+    for (const e of entries) {
+        const src = path.join(from, e.name);
+        const dst = path.join(to, e.name);
+        if (e.isDirectory())
+            await copyTree(src, dst);
+        else if (e.isSymbolicLink()) {
+            const link = await fs.readlink(src).catch(() => null);
+            if (link !== null)
+                await fs.symlink(link, dst).catch(() => { });
+        }
+        else
+            await fs.copyFile(src, dst);
+    }
+}
+// ---------- store ----------
+export class CheckpointStore {
+    enabled;
+    maxBackups;
+    dir;
+    constructor({ enabled = true, maxBackups = 50, dir = CHECKPOINT_DIR, } = {}) {
+        this.enabled = enabled;
+        this.maxBackups = maxBackups;
+        this.dir = dir;
+    }
+    get indexFile() {
+        return path.join(this.dir, 'index.json');
+    }
+    async _ensure() {
+        await fs.mkdir(this.dir, { recursive: true });
+    }
+    async _readIndex() {
+        try {
+            const data = JSON.parse(await fs.readFile(this.indexFile, 'utf-8'));
+            return Array.isArray(data) ? data : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Snapshot `workdir` into a tarball. Best-effort: a missing tar, an
+     * unreadable dir or a timeout yields null, never a thrown error — a failed
+     * checkpoint must not abort the task it was meant to protect.
+     */
+    async create(workdir, label) {
+        if (!this.enabled)
+            return null;
+        await this._ensure();
+        const stamp = Date.now();
+        const file = path.join(this.dir, `${stamp}.tgz`);
+        const res = await runTar(tarCreateArgs(file, workdir), workdir);
+        if (res.code !== 0) {
+            await fs.rm(file, { force: true }).catch(() => { });
+            return null;
+        }
+        const record = { stamp, file, workdir };
+        if (label)
+            record.label = label;
+        const history = await this._readIndex();
+        history.push(record);
+        const kept = rotateRecords(history, this.maxBackups);
+        // Drop the archives that fell out of the retention window.
+        const keptStamps = new Set(kept.map((r) => r.stamp));
+        for (const r of history) {
+            if (!keptStamps.has(r.stamp))
+                await fs.rm(r.file, { force: true }).catch(() => { });
+        }
+        writeJsonAtomic(this.indexFile, kept);
+        return record;
+    }
+    /** Newest-first list, capped at `count`. */
+    async list(count = 10) {
+        const history = await this._readIndex();
+        return history.slice().reverse().slice(0, count);
+    }
+    /**
+     * Restore the working tree to a checkpoint. Backs up the CURRENT tree first
+     * (a 'pre-rewind' checkpoint), so the rewind itself is reversible. Returns
+     * machine codes; the caller localizes them.
+     */
+    async restore(selector) {
+        if (!this.enabled)
+            return { ok: false, reason: 'disabled' };
+        const history = await this._readIndex();
+        const newestFirst = history.slice().reverse();
+        const record = pickRecord(newestFirst, selector);
+        if (!record)
+            return { ok: false, reason: 'not_found' };
+        const exists = await fs
+            .stat(record.file)
+            .then(() => true)
+            .catch(() => false);
+        if (!exists)
+            return { ok: false, reason: 'archive_missing' };
+        // Backup the CURRENT tree before touching it.
+        const backup = await this.create(record.workdir, 'pre-rewind');
+        // Extract to a temp dir FIRST; only a successful extract may touch workdir
+        // (otherwise a bad archive would wipe the tree).
+        const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'zames-rewind-'));
+        try {
+            const res = await runTar(tarExtractArgs(record.file, tmp), tmp);
+            if (res.code !== 0)
+                return { ok: false, reason: 'extract_failed' };
+            // Full restore: drop everything in workdir except the excludes, then
+            // copy the snapshot in. A partial extract would leave behind files the
+            // task created after the checkpoint.
+            const entries = await fs
+                .readdir(record.workdir)
+                .catch(() => []);
+            for (const e of entries) {
+                if (CHECKPOINT_EXCLUDES.includes(e))
+                    continue;
+                await fs
+                    .rm(path.join(record.workdir, e), { recursive: true, force: true })
+                    .catch(() => { });
+            }
+            await copyTree(tmp, record.workdir);
+            return { ok: true, record, backup };
+        }
+        finally {
+            await fs.rm(tmp, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+}

package/dist/commands.js

@@ -82,6 +82,8 @@ export function summarizeTranscript(entries) {
         turns: 0,
         toolCalls: 0,
         toolCounts: {},
+        toolMs: 0,
+        toolTime: {},
         durationMs: 0,
         startedAt: null,
         autoCompacts: 0,
@@ -98,6 +100,14 @@ export function summarizeTranscript(entries) {
             const tool = String(e.tool ?? '?');
             stats.toolCounts[tool] = (stats.toolCounts[tool] || 0) + 1;
         }
+        if (e.type === 'tool_result') {
+            const ms = Number(e.durationMs);
+            if (Number.isFinite(ms) && ms > 0) {
+                stats.toolMs += ms;
+                const tool = String(e.tool ?? '?');
+                stats.toolTime[tool] = (stats.toolTime[tool] || 0) + ms;
+            }
+        }
         if (typeof e.elapsed === 'number' && e.elapsed > stats.durationMs) {
             stats.durationMs = e.elapsed;
         }
@@ -179,6 +189,19 @@ export function renderCost(stats, transcriptFile, tokenUsage = null, t = transla
         for (const [name, n] of top)
             lines.push(' ' + name + ': ' + n);
     }
+    // T-D3: where the time went. Sort by total ms, show the top tools with the
+    // count and a human duration, so Read→Edit cycles and slow Bash calls are
+    // visible at a glance.
+    const byTime = Object.entries(stats.toolTime || {})
+        .filter(([, ms]) => ms > 0)
+        .sort((a, b) => b[1] - a[1]);
+    if (byTime.length) {
+        lines.push(t('cost.by_time', { dur: formatDuration(stats.toolMs) }));
+        for (const [name, ms] of byTime.slice(0, 8)) {
+            const count = stats.toolCounts[name] ?? 0;
+            lines.push(' ' + name + ': ' + formatDuration(ms) + ' ×' + count);
+        }
+    }
     lines.push(t('cost.duration', { dur: formatDuration(stats.durationMs) }));
     if (stats.startedAt)
         lines.push(t('cost.started', { v: stats.startedAt }));
@@ -615,6 +638,118 @@ export function rewriteFailedAttachments(text, failed) {
     }
     return out;
 }
+// Split a custom-command argument string into positional tokens, honoring
+// single/double quotes (so two quoted words stay one token). Pure, so it is
+// unit-tested.
+export function splitCommandArgs(rest) {
+    const out = [];
+    const s = String(rest ?? '');
+    const SQ = String.fromCharCode(39);
+    const DQ = String.fromCharCode(34);
+    let cur = '';
+    let quote = '';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = '';
+                continue;
+            }
+            cur += ch;
+            continue;
+        }
+        if (ch === SQ || ch === DQ) {
+            quote = ch;
+            continue;
+        }
+        if (ch.charCodeAt(0) <= 32) {
+            if (cur) {
+                out.push(cur);
+                cur = '';
+            }
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+}
+function isAllDigits(tok) {
+    if (!tok)
+        return false;
+    for (let i = 0; i < tok.length; i++) {
+        const c = tok.charCodeAt(i);
+        if (c < 48 || c > 57)
+            return false;
+    }
+    return true;
+}
+function isWordChar(ch) {
+    const c = ch.charCodeAt(0);
+    return ((c >= 48 && c <= 57) ||
+        (c >= 65 && c <= 90) ||
+        (c >= 97 && c <= 122) ||
+        ch === '_');
+}
+// Replace $1..$N and $name tokens in an already-expanded body. A whole word is
+// read after $ so $foobar never matches the name foo. Pure.
+function replaceDollarTokens(s, parts, names) {
+    let res = '';
+    let i = 0;
+    while (i < s.length) {
+        const ch = s[i];
+        if (ch !== '$') {
+            res += ch;
+            i++;
+            continue;
+        }
+        let j = i + 1;
+        let tok = '';
+        while (j < s.length && isWordChar(s[j])) {
+            tok += s[j];
+            j++;
+        }
+        if (!tok) {
+            res += ch;
+            i++;
+            continue;
+        }
+        if (isAllDigits(tok)) {
+            res += parts[Number(tok) - 1] ?? '';
+        }
+        else {
+            const idx = names.indexOf(tok);
+            res += idx >= 0 ? (parts[idx] ?? '') : '$' + tok;
+        }
+        i = j;
+    }
+    return res;
+}
+// Expand a custom-command body: {{args}} / $ARGUMENTS become the whole argument
+// string, $1..$N the positional tokens, $name the declared positions. Pure, so
+// it is unit-tested.
+export function expandCommandArgs(body, rest, names = []) {
+    const parts = splitCommandArgs(rest);
+    let out = String(body ?? '');
+    out = out.split('{{args}}').join(rest);
+    out = out.split('$ARGUMENTS').join(rest);
+    out = replaceDollarTokens(out, parts, names);
+    return out.trim();
+}
+// Names declared in `arguments:` but not supplied on the command line (by
+// position). Pure, so the caller can refuse an incomplete invocation.
+export function missingCommandArgs(names, rest) {
+    if (!names || !names.length)
+        return [];
+    const parts = splitCommandArgs(rest);
+    const missing = [];
+    for (let i = 0; i < names.length; i++) {
+        if (!parts[i])
+            missing.push(names[i]);
+    }
+    return missing;
+}
 // True when a `/config ...` line can be handled LIVE (while the agent is busy):
 // the text subcommands only touch config values, never the chat. The bare
 // `/config` and `/config menu` (which pause the editor and read keys) are NOT
@@ -781,6 +916,28 @@ export function buildImprovePrompt(item) {
         '(files changed, tests run, whether BACKLOG/CHANGELOG were updated).');
 }
 // ---------- /review ----------
+// Commands that only make sense while developing zames itself. A regular user
+// who installed the package must not see them in /help or the «/» hints, and
+// the main loop rejects them unless dev mode is on (--dev / config.hotReload).
+// Kept here (pure) so the list has ONE source of truth and is unit-tested.
+export const DEV_ONLY_COMMANDS = [
+    '/improve',
+    '/backlog',
+    '/self-review',
+    '/self-fix',
+    '/self-done',
+    '/self-list',
+    '/self-diff',
+    '/self-apply',
+];
+/** True when the typed line invokes a dev-only command. */
+export function isDevOnlyCommand(text) {
+    const name = String(text ?? '')
+        .trim()
+        .split(/\s+/)[0]
+        .toLowerCase();
+    return DEV_ONLY_COMMANDS.find((c) => c === name) || null;
+}
 export function buildReviewPrompt(focus, hasStaged = false) {
     const scope = hasStaged ? 'staged' : 'uncommitted';
     const f = String(focus ?? '').trim();

package/dist/compact.js

@@ -14,7 +14,7 @@ export const COMPACT_FALLBACK_LIMIT = 40;
  * The caller owns the browser and the throttle; this function only sends.
  */
 export async function performCompact(opts) {
-    const { browser, workdir, locale, task, transcript = null, ui = null, buildSystemPrompt, tools, answerTimeoutMs, fallbackLimit = COMPACT_FALLBACK_LIMIT, skipUiLock = false, quiet = false, } = opts;
+    const { browser, workdir, locale, task, transcript = null, ui = null, buildSystemPrompt, tools, answerTimeoutMs, fallbackLimit = COMPACT_FALLBACK_LIMIT, skipUiLock = false, quiet = false, selfImprovement = false, } = opts;
     const t = translate(locale);
     const log = (msg) => {
         if (!quiet)
@@ -124,7 +124,7 @@ export async function performCompact(opts) {
         });
         // 2) New chat + system prompt + the summary as the first message.
         await browser.newChat();
-        await browser.ask(buildSystemPrompt({ workdir, tools, locale }), {
+        await browser.ask(buildSystemPrompt({ workdir, tools, locale, selfImprovement }), {
             timeout: 60_000,
             agent: false,
         });

package/dist/config.js

@@ -22,6 +22,12 @@ export const DEFAULTS = {
         enabled: true,
         maxBackups: 200,
     },
+    // BACKLOG B3: snapshot the whole working tree at the start of each task so
+    // /rewind can roll a risky task back in one step.
+    checkpoint: {
+        enabled: true,
+        maxBackups: 50,
+    },
     transcript: {
         enabled: true,
         dir: path.join(os.homedir(), '.zames', 'logs'),
@@ -162,6 +168,20 @@ export const CONFIG_SCHEMA = [
         labelKey: 'cfg.f.undo_maxBackups',
         groupKey: 'cfg.group.undo',
     },
+    {
+        path: 'checkpoint.enabled',
+        type: 'boolean',
+        labelKey: 'cfg.f.checkpoint_enabled',
+        groupKey: 'cfg.group.checkpoint',
+    },
+    {
+        path: 'checkpoint.maxBackups',
+        type: 'number',
+        min: 1,
+        max: 1000,
+        labelKey: 'cfg.f.checkpoint_maxBackups',
+        groupKey: 'cfg.group.checkpoint',
+    },
     {
         path: 'transcript.enabled',
         type: 'boolean',

package/dist/context.js

@@ -1,4 +1,5 @@
 import fs from 'fs/promises';
+import { statSync } from 'fs';
 import path from 'path';
 import os from 'os';
 // Built-in skills, always available unless a project/global skill with the
@@ -169,11 +170,21 @@ function parseFrontmatter(raw) {
     const userInvokable = typeof out['user-invokable'] === 'string'
         ? out['user-invokable'].toLowerCase() !== 'false'
         : undefined;
+    const argumentsList = typeof out['arguments'] === 'string'
+        ? out['arguments']
+            .split(/[,\s]+/)
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : undefined;
     return {
         name: out.name,
         description: out.description,
         allowedTools,
         userInvokable,
+        argumentHint: typeof out['argument-hint'] === 'string'
+            ? out['argument-hint']
+            : undefined,
+        arguments: argumentsList,
     };
 }
 export function skillBody(raw) {
@@ -302,6 +313,8 @@ async function loadCommandsFromDir(dir) {
             description: (fm.description || '').replace(/\s+/g, ' ').trim(),
             path: full,
             body: skillBody(raw),
+            argumentHint: fm.argumentHint,
+            arguments: fm.arguments,
         });
     }
     return out;
@@ -376,13 +389,14 @@ async function loadMemoryChain(workdir) {
     }
     return out;
 }
-export async function loadProjectContext(workdir) {
+export async function loadProjectContext(workdir, touchPaths = []) {
     const [agents, memory, skills, commands] = await Promise.all([
         loadAgentsChain(workdir).catch(() => []),
         loadMemoryChain(workdir).catch(() => []),
         loadSkills(workdir).catch(() => []),
         loadCommands(workdir).catch(() => []),
     ]);
+    const scopedAgents = await loadScopedAgents(workdir, touchPaths).catch(() => []);
     let used = 0;
     const withinBudget = (files) => {
         const kept = [];
@@ -396,8 +410,81 @@ export async function loadProjectContext(workdir) {
     };
     return {
         agents: withinBudget(agents),
+        // Scoped files are dropped silently when the total budget is already spent
+        // on the main chain: a nested AGENTS.md is an optimization, not a hard
+        // requirement, and must never push out a top-level instruction.
+        scopedAgents: withinBudget(scopedAgents),
         memory: withinBudget(memory),
         skills,
         commands,
     };
 }
+// A directory is "touched" by a task when the task text mentions a path inside
+// it (a `@ref`, a quoted path, a bare `src/foo.ts`). We look for the deepest
+// existing directories named in the text and collect AGENTS.md/MEMORY.md from
+// them and their ancestors below `workdir`. Implemented by scanning word tokens
+// rather than a regex over the whole text so a long prompt stays cheap.
+function touchedDirs(workdir, text) {
+    const root = path.resolve(workdir);
+    const out = new Set();
+    const words = String(text || '')
+        .split(/\s+/)
+        .map((w) => w.replace(/^[\('"\[]+/, '').replace(/[\),.;:'"\]]+$/, ''));
+    for (const w of words) {
+        if (!w || w.length > 300)
+            continue;
+        // Only path-looking tokens (contain a separator or a known file extension).
+        if (!/[\\/]/.test(w) && !/\.[A-Za-z0-9]{1,8}$/.test(w))
+            continue;
+        const abs = path.isAbsolute(w) ? w : path.resolve(root, w);
+        if (abs !== root && !abs.startsWith(root + path.sep))
+            continue;
+        // Walk from the deepest directory that actually exists up to the root.
+        let dir = abs;
+        let st = statSyncSafe(dir);
+        while (!st && dir !== root && dir.startsWith(root + path.sep)) {
+            dir = path.dirname(dir);
+            st = statSyncSafe(dir);
+        }
+        if (!st || !st.isDirectory())
+            continue;
+        let cur = dir;
+        while (cur.startsWith(root + path.sep)) {
+            out.add(cur);
+            cur = path.dirname(cur);
+        }
+    }
+    return [...out];
+}
+function statSyncSafe(p) {
+    try {
+        return statSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+async function loadScopedAgents(workdir, touchPaths) {
+    if (!touchPaths.length)
+        return [];
+    const root = path.resolve(workdir);
+    // Collect every directory named by the task, deepest first, so the most
+    // specific instructions come first and win the budget.
+    const dirs = touchedDirs(root, touchPaths.join(' '));
+    dirs.sort((a, b) => b.length - a.length);
+    const out = [];
+    const seen = new Set();
+    for (const dir of dirs) {
+        for (const names of [AGENT_NAMES, MEMORY_NAMES]) {
+            const p = await findNamedFile(dir, names);
+            if (!p || seen.has(p))
+                continue;
+            const f = await readIfFile(p, MAX_FILE_BASE);
+            if (!f)
+                continue;
+            seen.add(p);
+            out.push(f);
+        }
+    }
+    return out;
+}