@phnx-labs/agents-cli 1.20.26 → 1.20.28

package/dist/lib/doctor-diff.js

@@ -23,7 +23,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, } from './state.js';
-import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, } from './versions.js';
+import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, compareVersions, } from './versions.js';
+import { discoverPlugins, marketplaceSpecForName } from './plugins.js';
+import { pluginInstallDir, repairableManifestFields } from './plugin-marketplace.js';
 import { markdownToToml } from './convert.js';
 import { resolveImports, supportsRulesImports } from './rules/compile.js';
 import { listCommandsInVersionHome, getVersionCommandsDir } from './commands.js';
@@ -80,13 +82,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 +192,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 +300,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 +351,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)) {
@@ -425,6 +427,91 @@ function diffPresenceOnly(kind, available, synced) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
+// ─── plugins (content-aware) ───────────────────────────────────────────────
+function listPluginSkillDirs(pluginDir) {
+    const d = path.join(pluginDir, 'skills');
+    try {
+        return fs.readdirSync(d, { withFileTypes: true })
+            .filter((e) => (e.isDirectory() || e.isSymbolicLink()) && fs.existsSync(path.join(d, e.name, 'SKILL.md')))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+function listPluginCommandFiles(pluginDir) {
+    const d = path.join(pluginDir, 'commands');
+    try {
+        return fs.readdirSync(d).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Describe how a version's marketplace MIRROR of a plugin diverges from its
+ * central source — the detail presence-only checks miss. Surfaces a stale mirror
+ * version, a Claude-invalid manifest, and (the part users care about) the
+ * plugin's own skills/commands that never made it into the mirror. Returns null
+ * when the mirror faithfully matches source.
+ */
+export function describePluginDrift(central, mirrorDir) {
+    if (!fs.existsSync(mirrorDir))
+        return 'mirror missing';
+    const parts = [];
+    let mManifest = null;
+    try {
+        mManifest = JSON.parse(fs.readFileSync(path.join(mirrorDir, '.claude-plugin', 'plugin.json'), 'utf-8'));
+    }
+    catch {
+        mManifest = null;
+    }
+    const mVer = mManifest && typeof mManifest.version === 'string' ? mManifest.version : undefined;
+    const cVer = central.manifest.version;
+    if (mVer && cVer && compareVersions(cVer, mVer) > 0)
+        parts.push(`${mVer}→${cVer}`);
+    if (mManifest && repairableManifestFields(mManifest).length > 0)
+        parts.push('invalid manifest');
+    const mirrorSkills = new Set(listPluginSkillDirs(mirrorDir));
+    const missSkills = listPluginSkillDirs(central.root).filter((s) => !mirrorSkills.has(s)).sort();
+    const mirrorCmds = new Set(listPluginCommandFiles(mirrorDir));
+    const missCmds = listPluginCommandFiles(central.root).filter((c) => !mirrorCmds.has(c)).sort();
+    if (missSkills.length)
+        parts.push(`missing skill${missSkills.length > 1 ? 's' : ''}: ${missSkills.join(', ')}`);
+    if (missCmds.length)
+        parts.push(`missing command${missCmds.length > 1 ? 's' : ''}: ${missCmds.join(', ')}`);
+    return parts.length ? parts.join(', ') : null;
+}
+function diffPlugins(agent, version, cwd) {
+    const versionHome = getVersionHomePath(agent, version);
+    const synced = new Set(getActuallySyncedResources(agent, version, { cwd }).plugins);
+    const rows = [];
+    const seen = new Set();
+    for (const p of discoverPlugins({ cwd })) {
+        if (seen.has(p.name))
+            continue; // dedupe across marketplaces for the readout
+        seen.add(p.name);
+        if (!synced.has(p.name)) {
+            rows.push({ kind: 'plugins', name: p.name, status: 'missing', sourcePath: p.root });
+            continue;
+        }
+        const mirror = pluginInstallDir(p, marketplaceSpecForName(p.marketplace), agent, versionHome);
+        const detail = describePluginDrift(p, mirror);
+        rows.push({
+            kind: 'plugins',
+            name: p.name,
+            status: detail ? 'diff' : 'ok',
+            sourcePath: p.root,
+            homePath: mirror,
+            ...(detail ? { detail } : {}),
+        });
+    }
+    for (const name of synced) {
+        if (!seen.has(name))
+            rows.push({ kind: 'plugins', name, status: 'extra' });
+    }
+    return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
 function diffPromptcuts() {
     const sourcePath = getEffectivePromptcutsPath();
     if (!fs.existsSync(sourcePath))
@@ -432,9 +519,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 +541,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'))
@@ -463,7 +555,7 @@ export function diffVersionResources(agent, version, options = {}) {
     if (requested.has('subagents'))
         empty.subagents = diffPresenceOnly('subagents', available.subagents, synced.subagents);
     if (requested.has('plugins'))
-        empty.plugins = diffPresenceOnly('plugins', available.plugins, synced.plugins);
+        empty.plugins = diffPlugins(agent, version, cwd);
     if (requested.has('promptcuts'))
         empty.promptcuts = diffPromptcuts();
     let ok = 0, diff = 0, missing = 0, extra = 0;
@@ -485,7 +577,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/exec.d.ts

@@ -80,6 +80,14 @@ export interface ExecOptions {
     addDirs?: string[];
     timeout?: string;
     sessionId?: string;
+    /**
+     * Resume the conversation named by `sessionId` using the agent's NATIVE resume
+     * form (claude `--resume`, codex `resume`) instead of the default `--session-id`
+     * create. Only set for agents where `nativeResume` returns true; other agents
+     * resume via a `/continue <id>` first message (Tier 2), which needs no flag and
+     * leaves this unset.
+     */
+    resume?: boolean;
     verbose?: boolean;
     env?: Record<string, string>;
     /**
@@ -150,6 +158,19 @@ export interface AgentCommandTemplate {
     modelFlag?: string;
     printFlags?: string[];
     verboseFlag?: string;
+    /**
+     * How this agent natively resumes a prior conversation. Presence here is the
+     * single source of truth for `nativeResume(agent)` — agents without it fall
+     * back to the universal `/continue <id>` replay (Tier 2). Two shapes:
+     *   { flag }       — append `<flag> <id>` (e.g. claude `--resume <id>`)
+     *   { subcommand } — replace the headless base subcommand with `<subcommand> <id>`
+     *                    (codex: `codex exec` -> `codex exec resume <id>`)
+     */
+    resume?: {
+        flag: string;
+    } | {
+        subcommand: string;
+    };
 }
 /**
  * CLI command templates for every supported agent.
@@ -158,6 +179,12 @@ export interface AgentCommandTemplate {
  * AGENTS[agent].capabilities.modes. A test in exec.test.ts asserts this.
  */
 export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
+/**
+ * Whether `agent` has a native resume form (Tier 1). Derived solely from the
+ * command template's `resume` field — the single source of truth. Agents that
+ * return false resume via the universal Tier-2 `/continue` replay instead.
+ */
+export declare function nativeResume(agent: AgentId): boolean;
 /** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */

package/dist/lib/exec.js

@@ -261,10 +261,12 @@ export const AGENT_COMMANDS = {
         modelFlag: '--model',
         printFlags: ['--print'],
         verboseFlag: '--verbose',
+        resume: { flag: '--resume' },
     },
     codex: {
         base: ['codex', 'exec'],
         promptFlag: 'positional',
+        resume: { subcommand: 'resume' },
         modeFlags: {
             // NOTE: codex has no read-only mode in --sandbox; 'plan' here means
             // "workspace-write but no auto-approval" — closer to plan-as-restraint.
@@ -302,6 +304,9 @@ export const AGENT_COMMANDS = {
     opencode: {
         base: ['opencode', 'run'],
         promptFlag: 'positional',
+        // opencode's native resume is `opencode --session <id>` (NOT under `run`), so
+        // it does not compose with this headless `run` base. Until that's verified on
+        // a box with opencode installed, opencode resumes via Tier-2 `/continue`.
         modeFlags: {
             plan: ['--agent', 'plan'],
             edit: ['--agent', 'build'],
@@ -436,6 +441,14 @@ export const AGENT_COMMANDS = {
         modelFlag: '-m',
     },
 };
+/**
+ * Whether `agent` has a native resume form (Tier 1). Derived solely from the
+ * command template's `resume` field — the single source of truth. Agents that
+ * return false resume via the universal Tier-2 `/continue` replay instead.
+ */
+export function nativeResume(agent) {
+    return AGENT_COMMANDS[agent]?.resume !== undefined;
+}
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
@@ -453,30 +466,36 @@ export function buildExecCommand(options) {
             cmd.splice(1, 1);
         }
     }
+    // Native resume with a `{ subcommand }` shape (codex) appends the resume verb
+    // to the base: `codex exec` -> `codex exec resume` (headless) and, after the
+    // interactive drop above, `codex` -> `codex resume` (TUI). The session id is
+    // pushed later as the first positional (before any prompt). `{ flag }` agents
+    // (claude) need no base change — the flag is appended with the id below.
+    const resumeSpec = options.resume ? template.resume : undefined;
+    if (resumeSpec && 'subcommand' in resumeSpec) {
+        cmd.push(resumeSpec.subcommand);
+    }
     // Use versioned alias if a specific version was requested (e.g., claude@2.1.98).
     // Resolve to the absolute path of the shim so spawn doesn't depend on PATH —
     // on Linux installs where the shims dir isn't on PATH, spawning the bare
     // versioned name fails with ENOENT even though `agents view` shows the agent.
     //
-    // On Windows, shims are bash scripts and cannot be executed by spawn() directly.
-    // buildExecEnv() already sets the isolation env vars (CLAUDE_CONFIG_DIR, CODEX_HOME,
-    // etc.) that the bash shim would set, so we can skip the shim entirely and resolve
-    // straight to the real binary via getBinaryPath.
+    // On Windows the shims dir holds a `.cmd` companion next to the bash alias
+    // (see createVersionedAlias); prefer it so spawn() can launch it (the bash
+    // script is not directly executable by cmd.exe). When no shim exists on disk
+    // we fall back to the bare versioned name, which spawnAgent() resolves via
+    // PATH (+ PATHEXT/shell on Windows).
     if (options.version && cmd.length > 0) {
-        if (process.platform === 'win32') {
-            const binaryPath = getBinaryPath(options.agent, options.version);
-            const binaryPathCmd = binaryPath + '.cmd';
-            if (fs.existsSync(binaryPathCmd)) {
-                cmd[0] = binaryPathCmd;
-            }
-            else if (fs.existsSync(binaryPath)) {
-                cmd[0] = binaryPath;
-            }
+        const versionedName = `${cmd[0]}@${options.version}`;
+        const absPath = path.join(getShimsDir(), versionedName);
+        if (process.platform === 'win32' && fs.existsSync(absPath + '.cmd')) {
+            cmd[0] = absPath + '.cmd';
+        }
+        else if (fs.existsSync(absPath)) {
+            cmd[0] = absPath;
         }
         else {
-            const versionedName = `${cmd[0]}@${options.version}`;
-            const absPath = path.join(getShimsDir(), versionedName);
-            cmd[0] = fs.existsSync(absPath) ? absPath : versionedName;
+            cmd[0] = versionedName;
         }
     }
     // Add reasoning effort flags (before mode flags for codex -c positioning)
@@ -505,15 +524,39 @@ export function buildExecCommand(options) {
         // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
-    cmd.push(...modeFlags);
+    if (resumeSpec && 'subcommand' in resumeSpec) {
+        // codex `exec resume` / `resume` does NOT accept `--sandbox <mode>` (only the
+        // bypass flag, verified against `codex exec resume --help`). So the standard
+        // codex modeFlags can't be reused on resume. A non-plan HEADLESS resume needs
+        // the bypass or it stalls on approval prompts; plan and interactive resume
+        // inherit codex's default sandbox and pass no flag.
+        if (!interactive && resolvedMode !== 'plan') {
+            cmd.push('--dangerously-bypass-approvals-and-sandbox');
+        }
+    }
+    else {
+        cmd.push(...modeFlags);
+    }
     // Add print/headless flags only when a prompt is provided. Without a prompt
     // the caller wants an interactive REPL -- passing --print would immediately
     // wait on stdin and never render the TUI.
     if (!interactive && options.headless && template.printFlags) {
         cmd.push(...template.printFlags);
     }
-    // Add session ID (Claude only)
-    if (options.sessionId && options.agent === 'claude') {
+    // Resume vs. create. With `resume`, emit the agent's NATIVE resume reference:
+    // `{ flag }` agents append `<flag> <id>` (claude `--resume <id>`); `{ subcommand }`
+    // agents (codex) already pushed the verb above, so the id is the first
+    // positional here — placed before the prompt positional appended later. Without
+    // `resume`, the legacy claude-only `--session-id` CREATES a session with that id.
+    if (options.resume && options.sessionId && resumeSpec) {
+        if ('flag' in resumeSpec) {
+            cmd.push(resumeSpec.flag, options.sessionId);
+        }
+        else {
+            cmd.push(options.sessionId);
+        }
+    }
+    else if (options.sessionId && options.agent === 'claude') {
         cmd.push('--session-id', options.sessionId);
     }
     // Add model (only if explicitly provided by user)

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>;