@phnx-labs/agents-cli 1.20.25 → 1.20.27

package/dist/lib/agent-spec.js

@@ -0,0 +1,157 @@
+// Centralized agent-spec resolution — one vocabulary, one resolver, reused by
+// every subcommand that accepts `<agent>[@<qualifier>]`.
+//
+// The qualifier vocabulary used to be split across three functions in
+// versions.ts (parseAgentSpec, resolveVersionAlias, resolveInstalledAgentTargets)
+// with diverging support — `@latest`/`@oldest` in one, `@all`/`@default` in
+// another, `@pinned` nowhere. This module is the single source of truth.
+//
+// Built for the hot path (`--launch`, ~100ms budget): the common specs resolve
+// with NO directory enumeration —
+//   exact `claude@2.1.181`   → one isVersionInstalled() (existsSync)
+//   `claude@pinned|@default` → memoized getGlobalDefault() + existsSync
+//   bare `claude`            → resolveVersion() (memoized meta), no readdir
+// Only the relative qualifiers `@latest`/`@oldest`/`@all` enumerate, and even
+// then via the mtime-cached listInstalledVersions().
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from './agents.js';
+import { listInstalledVersions, getGlobalDefault, isVersionInstalled, resolveVersion, } from './versions.js';
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export const AGENT_QUALIFIERS = ['latest', 'oldest', 'pinned', 'default', 'all'];
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export const AGENT_SPEC_HELP = 'Agent spec: <agent>[@<qualifier>]. Qualifiers: ' +
+    '@latest (highest installed), @oldest (lowest installed), ' +
+    '@pinned / @default (your configured default — synonyms), ' +
+    '@all (every installed version), or an exact @x.y.z. ' +
+    'Bare <agent> uses the resolved default (project pin → global default). ' +
+    'Comma-separate to combine: claude@all,codex@latest.';
+export class AgentSpecError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentSpecError';
+    }
+}
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * Domain = installed: `@latest`/`@oldest`/`@all` range over installed versions
+ * (`add`/`install` use a separate available-version path). Throws AgentSpecError
+ * on bad input — never calls process.exit, so it is safe on the hot path and in
+ * library contexts.
+ */
+export function resolveAgentTargets(spec, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const available = opts.availableAgents ?? ALL_AGENT_IDS;
+    const rawEntries = spec
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (rawEntries.length === 0) {
+        throw new AgentSpecError('Empty agent spec.');
+    }
+    // Expand the bare literal `all` (or `all@all`) into every available agent that
+    // has at least one installed version. Lenient: agents with nothing installed
+    // are skipped rather than erroring.
+    const entries = [];
+    for (const e of rawEntries) {
+        if (e === 'all' || e === 'all@all') {
+            for (const a of available) {
+                if (listInstalledVersions(a).length > 0)
+                    entries.push(`${a}@all`);
+            }
+        }
+        else {
+            entries.push(e);
+        }
+    }
+    const out = [];
+    const seen = new Set();
+    const push = (agent, version) => {
+        const key = `${agent}@${version ?? ''}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push({ agent, version });
+        }
+    };
+    for (const entry of entries) {
+        const at = entry.indexOf('@');
+        const agentToken = (at === -1 ? entry : entry.slice(0, at)).trim();
+        const qualifier = at === -1 ? null : entry.slice(at + 1).trim();
+        if (!agentToken)
+            continue;
+        if (at !== -1 && !qualifier) {
+            throw new AgentSpecError(`Missing version in '${entry}'. Use ${agentToken}@x.y.z, @latest, @oldest, @pinned, @default, or @all.`);
+        }
+        const agent = resolveAgentName(agentToken);
+        if (!agent || !available.includes(agent)) {
+            throw new AgentSpecError(formatAgentError(agentToken, [...available]));
+        }
+        const name = AGENTS[agent].name;
+        // ----- bare: resolved default, NO enumeration in the common case -----
+        if (qualifier === null) {
+            const resolved = resolveVersion(agent, cwd); // project pin → global default (meta-only)
+            if (resolved) {
+                push(agent, resolved);
+            }
+            else {
+                const installed = listInstalledVersions(agent);
+                if (installed.length === 0)
+                    push(agent, null);
+                else if (installed.length === 1)
+                    push(agent, installed[0]);
+                else
+                    throw new AgentSpecError(`No default version set for ${name}. Specify one (${agent}@<version>) or set it: agents use ${agent}@<version>.`);
+            }
+            continue;
+        }
+        // ----- @pinned / @default: synonyms, meta-only fast path -----
+        if (qualifier === 'pinned' || qualifier === 'default') {
+            const def = getGlobalDefault(agent);
+            if (!def) {
+                throw new AgentSpecError(`No default version set for ${name}. Run: agents use ${agent}@<version>`);
+            }
+            push(agent, def);
+            continue;
+        }
+        // ----- @all: every installed version -----
+        if (qualifier === 'all') {
+            const installed = listInstalledVersions(agent);
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`);
+            }
+            for (const v of installed)
+                push(agent, v);
+            continue;
+        }
+        // ----- @latest / @oldest: enumerate (mtime-cached), pick an end -----
+        if (qualifier === 'latest' || qualifier === 'oldest') {
+            const installed = listInstalledVersions(agent); // already sorted ascending
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`);
+            }
+            push(agent, qualifier === 'oldest' ? installed[0] : installed[installed.length - 1]);
+            continue;
+        }
+        // ----- exact version: one existsSync, NO enumeration -----
+        if (!isVersionInstalled(agent, qualifier)) {
+            const installed = listInstalledVersions(agent);
+            const hint = installed.length ? ` Installed: ${installed.join(', ')}.` : '';
+            throw new AgentSpecError(`${name}@${qualifier} is not installed.${hint} Install it: agents add ${agent}@${qualifier}`);
+        }
+        push(agent, qualifier);
+    }
+    return out;
+}
+/**
+ * Convenience for single-target commands (`use`, `run`): resolve a spec that
+ * must name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export function resolveSingleAgentTarget(spec, opts = {}) {
+    const targets = resolveAgentTargets(spec, opts);
+    if (targets.length !== 1) {
+        throw new AgentSpecError(`'${spec}' resolves to ${targets.length} targets; this command needs exactly one.`);
+    }
+    const t = targets[0];
+    if (t.version === null) {
+        throw new AgentSpecError(`No installed version for ${AGENTS[t.agent].name}. Run: agents add ${t.agent}@latest`);
+    }
+    return { agent: t.agent, version: t.version };
+}

package/dist/lib/agents.js

@@ -296,6 +296,7 @@ export const AGENTS = {
         commandsDir: '', // OpenClaw uses Gateway-based slash commands, not file-based
         commandsSubdir: '',
         skillsDir: path.join(HOME, '.openclaw', 'skills'),
+        nativeCommandRuntime: true, // Gateway resolves slash commands — don't convert commands to skills
         hooksDir: 'hooks',
         instructionsFile: 'workspace/AGENTS.md', // Primary memory file (also has SOUL.md, IDENTITY.md, etc.)
         format: 'markdown',

package/dist/lib/daemon.js

@@ -260,6 +260,36 @@ export async function runDaemon() {
     };
     const syncInterval = setInterval(() => { void runSessionSync(); }, 90_000);
     void runSessionSync(); // kick once at startup
+    // Resource safety check: heal gaps between what DotAgents repos define and
+    // what's actually installed in each agent home — the slow rot that nothing
+    // else catches (a non-default version left stale, a Claude-invalid plugin
+    // manifest silently rejecting a whole plugin). Conservative 'safe' mode: it
+    // fills missing resources, repairs invalid manifests, and fast-forwards
+    // provably-unmodified stale plugins, but never overwrites hand-edited content
+    // or a plugin it can't prove is pristine — those it reports for `doctor --fix`.
+    // Runs ~every 6h plus once ~30s after startup (staggered so launch isn't busy).
+    let healing = false;
+    const runHealCheck = async () => {
+        if (healing)
+            return;
+        healing = true;
+        try {
+            const { heal, summarizeHeal, notifyHeal, healChangedAnything } = await import('./heal.js');
+            const result = await heal({ mode: 'safe' });
+            if (healChangedAnything(result) || result.skippedPlugins.length > 0) {
+                log('INFO', `heal: ${summarizeHeal(result)}`);
+                notifyHeal(result);
+            }
+        }
+        catch (err) {
+            log('ERROR', `heal check failed: ${err.message}`);
+        }
+        finally {
+            healing = false;
+        }
+    };
+    const healInterval = setInterval(() => { void runHealCheck(); }, 6 * 60 * 60_000);
+    const healKickoff = setTimeout(() => { void runHealCheck(); }, 30_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -275,6 +305,8 @@ export async function runDaemon() {
         await browserIPC.stop();
         clearInterval(monitorInterval);
         clearInterval(syncInterval);
+        clearInterval(healInterval);
+        clearTimeout(healKickoff);
         removeDaemonPid();
         process.exit(0);
     };

package/dist/lib/doctor-diff.d.ts

@@ -59,6 +59,13 @@ export interface DiffOptions {
     cwd?: string;
     /** Restrict to specific kinds; undefined = all. */
     kinds?: DoctorKind[];
+    /**
+     * Drop the project (`<cwd>/.agents/`) layer from resolution. Used by the heal
+     * path: the GLOBAL version home is only ever reconciled against user/system/
+     * extra sources — project resources are layered at launch, never synced into
+     * the global home, so counting them as "missing" there is a false gap.
+     */
+    excludeProject?: boolean;
 }
 export declare function diffVersionResources(agent: AgentId, version: string, options?: DiffOptions): VersionResourceReport;
 export declare const DOCTOR_ALL_KINDS: DoctorKind[];

package/dist/lib/doctor-diff.js

@@ -80,13 +80,13 @@ function buildLayerBases(cwd, kind, opts = {}) {
     return out;
 }
 // ─── commands ─────────────────────────────────────────────────────────────────
-function diffCommands(agent, version, cwd) {
+function diffCommands(agent, version, cwd, excludeProject = false) {
     const agentConfig = AGENTS[agent];
     const isToml = agentConfig.format === 'toml';
     const ext = isToml ? '.toml' : '.md';
     const homeDir = getVersionCommandsDir(agent, version);
     const installed = new Set(listCommandsInVersionHome(agent, version));
-    const layerBases = buildLayerBases(cwd, 'commands');
+    const layerBases = buildLayerBases(cwd, 'commands', { excludeProject });
     const sourceByName = new Map();
     for (const base of layerBases) {
         if (!fs.existsSync(base.path))
@@ -190,10 +190,10 @@ function dirsContentMatch(src, dst) {
     }
     return true;
 }
-function diffSkills(agent, version, cwd) {
+function diffSkills(agent, version, cwd, excludeProject = false) {
     const homeDir = getVersionSkillsDir(agent, version);
     const installed = new Set(listSkillsInVersionHome(agent, version));
-    const layerBases = buildLayerBases(cwd, 'skills');
+    const layerBases = buildLayerBases(cwd, 'skills', { excludeProject });
     const sourceByName = new Map();
     for (const base of layerBases) {
         if (!fs.existsSync(base.path))
@@ -298,8 +298,8 @@ function diffHooks(agent, version, cwd) {
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
 // ─── rules / memory ───────────────────────────────────────────────────────────
-function listRulesNames(cwd) {
-    const projectDir = getProjectAgentsDir(cwd);
+function listRulesNames(cwd, excludeProject = false) {
+    const projectDir = excludeProject ? null : getProjectAgentsDir(cwd);
     const userRules = getUserRulesDir();
     const systemRules = getResolvedRulesDir();
     const extras = getEnabledExtraRepos();
@@ -349,11 +349,11 @@ function expectedRuleContent(agent, name, sourcePath) {
     }
     return readSafe(sourcePath);
 }
-function diffRules(agent, version, cwd) {
+function diffRules(agent, version, cwd, excludeProject = false) {
     const agentConfig = AGENTS[agent];
     const versionHome = getVersionHomePath(agent, version);
     const configDir = path.join(versionHome, agentConfigDirName(agent));
-    const sourcesByName = listRulesNames(cwd);
+    const sourcesByName = listRulesNames(cwd, excludeProject);
     // Files actually present in the version home.
     const homeFiles = new Set();
     if (fs.existsSync(configDir)) {
@@ -432,9 +432,14 @@ function diffPromptcuts() {
     return [{ kind: 'promptcuts', name: 'promptcuts.yaml', status: 'ok', sourcePath }];
 }
 export function diffVersionResources(agent, version, options = {}) {
-    const cwd = options.cwd ?? process.cwd();
+    const rawCwd = options.cwd ?? process.cwd();
+    const excludeProject = options.excludeProject ?? false;
     const home = getVersionHomePath(agent, version);
     const requested = new Set(options.kinds ?? ALL_KINDS);
+    // When excluding the project layer, resolve every per-cwd lookup against a
+    // neutral cwd so no `<cwd>/.agents/` is ever discovered.
+    const cwd = rawCwd;
+    const projectDir = excludeProject ? null : getProjectAgentsDir(cwd);
     const available = getAvailableResources(cwd);
     const synced = getActuallySyncedResources(agent, version, { cwd });
     const empty = {
@@ -449,13 +454,13 @@ export function diffVersionResources(agent, version, options = {}) {
         promptcuts: [],
     };
     if (requested.has('commands'))
-        empty.commands = diffCommands(agent, version, cwd);
+        empty.commands = diffCommands(agent, version, cwd, excludeProject);
     if (requested.has('skills'))
-        empty.skills = diffSkills(agent, version, cwd);
+        empty.skills = diffSkills(agent, version, cwd, excludeProject);
     if (requested.has('hooks'))
         empty.hooks = diffHooks(agent, version, cwd);
     if (requested.has('rules'))
-        empty.rules = diffRules(agent, version, cwd);
+        empty.rules = diffRules(agent, version, cwd, excludeProject);
     if (requested.has('mcp'))
         empty.mcp = diffPresenceOnly('mcp', available.mcp, synced.mcp);
     if (requested.has('permissions'))
@@ -485,7 +490,7 @@ export function diffVersionResources(agent, version, options = {}) {
         home,
         cwd,
         layers: {
-            project: getProjectAgentsDir(cwd),
+            project: projectDir,
             user: getUserAgentsDir(),
             system: getSystemAgentsDir(),
             extras: getEnabledExtraRepos().map((e) => ({ alias: e.alias, dir: e.dir })),

package/dist/lib/fs-atomic.d.ts

@@ -12,7 +12,8 @@ export declare function ensureLockTarget(filePath: string, initialContent?: stri
 export declare function atomicWriteFileSync(filePath: string, content: string): void;
 /**
  * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
- * releases the lock. Retries up to LOCK_RETRIES times with linear back-off.
- * Breaks stale locks older than LOCK_STALE_MS.
+ * releases the lock. Retries with capped linear back-off until either the lock
+ * is acquired or LOCK_ACQUIRE_TIMEOUT_MS elapses. Breaks stale locks older than
+ * LOCK_STALE_MS, so a crashed holder never blocks past the stale window.
  */
 export declare function withFileLock<T>(filePath: string, fn: () => T): T;

package/dist/lib/fs-atomic.js

@@ -3,7 +3,18 @@ import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
 const LOCK_STALE_MS = 5_000;
-const LOCK_RETRIES = 5;
+// Wall-clock budget to acquire the lock before giving up. A count-bounded retry
+// (the old 5 attempts / ~750ms ceiling) could expire while a peer legitimately
+// held the lock — under CI/parallel load two `agents` invocations mutating
+// agents.yaml would have one throw and silently drop its write. The budget must
+// comfortably exceed both a normal critical-section hold and the stale-break
+// window (LOCK_STALE_MS): a dead holder's lock turns stale at 5s and is then
+// broken on the next attempt, so this only ever waits out a live, in-progress
+// holder. Bounded (not unbounded) so a truly wedged holder still surfaces an
+// error instead of hanging the CLI forever.
+const LOCK_ACQUIRE_TIMEOUT_MS = 30_000;
+const LOCK_RETRY_MIN_MS = 50;
+const LOCK_RETRY_MAX_MS = 250;
 // Reused across all sleepSync calls — avoids allocating a new SAB each time.
 const _sleepBuf = new Int32Array(new SharedArrayBuffer(4));
 export function sleepSync(ms) {
@@ -46,26 +57,30 @@ export function atomicWriteFileSync(filePath, content) {
 }
 /**
  * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
- * releases the lock. Retries up to LOCK_RETRIES times with linear back-off.
- * Breaks stale locks older than LOCK_STALE_MS.
+ * releases the lock. Retries with capped linear back-off until either the lock
+ * is acquired or LOCK_ACQUIRE_TIMEOUT_MS elapses. Breaks stale locks older than
+ * LOCK_STALE_MS, so a crashed holder never blocks past the stale window.
  */
 export function withFileLock(filePath, fn) {
     let release = null;
     let lastError;
-    for (let attempt = 0; attempt <= LOCK_RETRIES; attempt++) {
+    const deadline = Date.now() + LOCK_ACQUIRE_TIMEOUT_MS;
+    for (let attempt = 0;; attempt++) {
         try {
             release = lockfile.lockSync(filePath, { stale: LOCK_STALE_MS });
             break;
         }
         catch (err) {
             lastError = err;
-            if (attempt < LOCK_RETRIES)
-                sleepSync(50 * (attempt + 1));
+            if (Date.now() >= deadline)
+                break;
+            const backoff = Math.min(LOCK_RETRY_MIN_MS * (attempt + 1), LOCK_RETRY_MAX_MS);
+            sleepSync(Math.min(backoff, Math.max(0, deadline - Date.now())));
         }
     }
     if (!release) {
         const message = lastError instanceof Error ? lastError.message : String(lastError);
-        throw new Error(`Could not acquire lock for ${filePath}: ${message}`);
+        throw new Error(`Could not acquire lock for ${filePath} after ${LOCK_ACQUIRE_TIMEOUT_MS}ms: ${message}`);
     }
     try {
         return fn();

package/dist/lib/heal.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Resource heal engine — close the gap between what DotAgents repos DEFINE and
+ * what is actually present/valid in each installed agent home.
+ *
+ * Powers two callers:
+ *   - `agents doctor --fix`  — explicit, operator-driven. Mode 'full': fills
+ *     missing, overwrites drifted content, and refreshes stale plugins even when
+ *     the baseline is unknown (the operator asked for it).
+ *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
+ *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
+ *     provably-unmodified stale plugins). Drift and risky refreshes are reported,
+ *     never clobbered.
+ *
+ * Built on the LIVE-home diff (`diffVersionResources`) — NOT the staleness
+ * manifest. `isStale()` only compares the last-synced manifest against the
+ * sources, so home-side rot (a deleted, corrupted, or Claude-rejected file in a
+ * version home whose source never changed) is invisible to it and to the sync
+ * fast-guard. The diff reads the actual home, so heal catches exactly that class
+ * of drift — the kind that silently broke the `code` plugin on a non-default
+ * Claude version.
+ *
+ * Heal FILLS and FIXES; it never deletes. Orphan/extra removal stays the job of
+ * `agents prune cleanup`, so a heal pass can never lose work.
+ */
+import type { AgentId } from './types.js';
+import { type DoctorKind, type DiffStatus } from './doctor-diff.js';
+export interface HealedResource {
+    kind: DoctorKind;
+    name: string;
+    /** Why it was healed: 'missing' (filled) or 'diff' (overwritten / re-pushed). */
+    was: DiffStatus;
+}
+export interface SkippedResource {
+    kind: DoctorKind;
+    name: string;
+    /** 'drift': hand-edited content left untouched in 'safe' mode.
+     *  'unreconcilable': heal wrote it but the diff still flags it — a source/home
+     *  asymmetry the writer can't satisfy (e.g. a hook sidecar the installer omits),
+     *  surfaced honestly instead of "fixed" on every pass. */
+    reason: 'drift' | 'unreconcilable';
+}
+export interface VersionHealResult {
+    agent: AgentId;
+    version: string;
+    healed: HealedResource[];
+    skipped: SkippedResource[];
+}
+export interface ManifestRepairResult {
+    plugin: string;
+    /** Bare-name fields stripped from the source plugin.json (e.g. ["skills"]). */
+    droppedFields: string[];
+}
+export interface PluginRefreshResult {
+    plugin: string;
+    from: string;
+    to: string;
+}
+export interface PluginRefreshSkip {
+    plugin: string;
+    from: string;
+    upstream: string;
+    /** 'modified': central diverged from baseline. 'no-baseline': pre-tracking install. */
+    reason: 'modified' | 'no-baseline';
+}
+export interface HealResult {
+    versions: VersionHealResult[];
+    repairedManifests: ManifestRepairResult[];
+    refreshedPlugins: PluginRefreshResult[];
+    skippedPlugins: PluginRefreshSkip[];
+}
+export interface HealOptions {
+    /** 'full' (doctor --fix): fix drift + refresh unknown-baseline plugins.
+     *  'safe' (daemon): missing + invalid-manifest + unmodified refresh only. */
+    mode: 'full' | 'safe';
+    /** Resolution cwd. Defaults to the home dir so no project layer is ever
+     *  resolved — heal targets the GLOBAL install, never a project. Tests override. */
+    cwd?: string;
+    /** Scope to one agent; omit to heal every installed agent. */
+    agent?: AgentId;
+    /** Scope to specific versions of `agent`; omit for all installed versions. */
+    versions?: string[];
+    /** Compute the plan without writing anything. */
+    dryRun?: boolean;
+}
+/** True when a heal pass made (or would make) any change at all. */
+export declare function healChangedAnything(r: HealResult): boolean;
+/** One-line summary of a heal pass for daemon logs. */
+export declare function summarizeHeal(r: HealResult): string;
+/**
+ * Fire a native desktop notification when a background heal did something
+ * noteworthy. Best-effort — missing `osascript`/`notify-send` or no display is
+ * swallowed. Silent when the pass auto-fixed everything and nothing needs the
+ * operator (no point pinging them for routine self-healing).
+ */
+export declare function notifyHeal(r: HealResult): void;
+/**
+ * Strip Claude-invalid bare-name `skills`/`commands` fields from every central
+ * plugin's SOURCE plugin.json. Unambiguously safe (Claude auto-discovers both
+ * from their directories) and the precondition for those plugins loading at all.
+ */
+export declare function repairCentralPluginManifests(dryRun?: boolean): ManifestRepairResult[];
+/**
+ * Run a heal pass. Repairs the central plugin layer once (manifest + stale
+ * refresh), then reconciles every targeted (agent, version) home against its
+ * live diff. Returns a full account of what changed (or would, under dryRun).
+ */
+export declare function heal(opts: HealOptions): Promise<HealResult>;