@phnx-labs/agents-cli 1.20.4 → 1.20.5

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Unreleased
+
+## 1.20.5
+
+**`agents inspect` — per-agent+version detail view with drill-down (#217)**
+
+- New top-level command `agents inspect <agent>[@version]`. Summary mode shows install path, config symlink target, shim path, versioned alias, run strategy, capability table (`hooks`/`mcp`/`skills`/`commands`/`subagents`/`plugins`/`workflows`/`rules`/`allowlist`), resource counts with project/user/system scope breakdown, and session total. Replaces the awkward `agents view <agent>@<version>` deep-detail mode as a dedicated verb; `view` itself is unchanged.
+- Drill-down flags for every resource kind — `--commands`, `--skills`, `--hooks`, `--mcp`, `--rules`, `--plugins`, `--workflows`, `--subagents`. Bare flag lists every entry; passing a positional query fuzzy-searches that kind, ranking exact > substring > Damerau-Levenshtein. Zero matches exit 1 with the three closest names as suggestions. One drill-down at a time (validation error otherwise). `--json` works with summary and every drill-down for scriptable consumption.
+- Resource names render as OSC-8 terminal hyperlinks to the marker file (`SKILL.md` / `WORKFLOW.md` / `AGENT.md`) for clickable navigation in modern terminals (Ghostty, iTerm2, WezTerm) — no inline path noise. Plain text on terminals without OSC-8 support.
+- MCP detail intentionally suppresses path and env values to avoid leaking secrets — only the server name, scope, and version reach the output.
+- Removes the deprecated `agents status` alias for `view @default`. Top-level help text updated; no consumers referenced it.
+
+**Headless Linux: encrypted-file fallback when libsecret collection is locked (#183)**
+
+- On server-class Linux (Ubuntu 24.04 over SSH on the reporter's box), `agents secrets create x` failed with `secret-tool: Cannot create an item in a locked collection`. Diagnosis in the issue: `gnome-keyring-daemon` is running and D-Bus is reachable, but the default `login` collection is locked because no graphical login has fed the daemon the passphrase, and `secret-tool` from `libsecret-tools` has no `--collection` flag so it can't target the unlocked `session` collection. This made `agents secrets` effectively macOS-only on any headless box.
+- `src/lib/secrets/linux.ts` now transparently falls back to a file-based AES-256-GCM encrypted store at `~/.agents/.cache/secrets/<item>.enc` (mode 0600, per-file random scrypt salt + 96-bit IV, GCM auth tag). The encryption key is scrypt-derived from a passphrase read from `AGENTS_SECRETS_PASSPHRASE` (preferred) or a TTY prompt via `/dev/tty` with `stty -echo` for non-echoing input. The fallback also activates when `libsecret-tools` is not installed at all but `AGENTS_SECRETS_PASSPHRASE` is set, so a fresh install can store secrets without any apt-get step.
+- The decision is cached per process; on first activation we emit one stderr line: `[agents] secret-service collection locked, using file-based store at <dir>`. The `KeychainBackend` interface in `src/lib/secrets/index.ts` is unchanged — `has`/`get`/`set`/`delete`/`list` work identically against either backend, so `bundles.ts`, `sync.ts`, and every consumer above it sees no API change.
+- Items written into the file store before the fallback was added remain accessible only via libsecret if/when the collection is later unlocked; this PR does not migrate stranded items in either direction — the user simply re-creates them on a freshly headless box.
+
 ## 1.20.4
 
 **Plugin marketplace sync (skip outside-pointing symlinks)**

package/README.md

@@ -641,23 +641,54 @@ By default, secrets sync via iCloud Keychain to your other Macs. With `--no-iclo
 
 ## Compatibility
 
-| Agent | Versions | MCP | Commands | Skills | Rules | Hooks | Plugins | Permissions | Routines | Teams |
-|-------|----------|-----|----------|--------|-------|-------|---------|-------------|----------|-------|
-| Claude Code | yes | yes | yes | yes | CLAUDE.md | yes | yes | yes | yes | yes |
-| Codex CLI | yes | yes | yes | yes | AGENTS.md | yes (>= 0.116.0) | -- | yes | yes | yes |
-| Gemini CLI | yes | yes | yes | yes | GEMINI.md | yes (>= 0.26.0) | -- | -- | yes | yes |
-| OpenClaw | yes | yes | -- | yes | workspace/AGENTS.md | yes | yes | -- | -- | -- |
-| Cursor | yes | yes | yes | yes | .cursorrules | -- | -- | -- | -- | yes |
-| OpenCode | yes | yes | yes | yes | AGENTS.md | -- | -- | yes | -- | yes |
-| Copilot | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-| Amp | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-| Kiro | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-| Goose | yes | yes | -- | -- | AGENTS.md | -- | -- | -- | -- | -- |
-| Roo Code | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-
-Hooks columns marked `yes (>= X.Y.Z)` are version-gated: `agents hooks add` skips with a clear message when the installed binary is older than the listed version, instead of writing config the older binary would silently ignore. OpenCode's plugin-based hook system is on the roadmap; the entry is `--` until a writer ships.
-
-Codex command sync is version-aware: Codex `0.116.x` and older receive slash commands in `.codex/prompts/`; Codex `0.117.0+` receives those commands as generated skills so they can be invoked with `$name`.
+Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/agents.ts](src/lib/agents.ts) (`capabilities`); gates use `supports(agent, cap, version)` from [src/lib/capabilities.ts](src/lib/capabilities.ts). Full matrix also in [docs/00-concepts.md](docs/00-concepts.md).
+
+| Agent | Versions | Hooks | MCP | Permissions | Skills | Commands | Plugins | Subagents | Rules | Workflows |
+|-------|----------|-------|-----|-------------|--------|----------|---------|-----------|-------|-----------|
+| Claude Code | yes | yes | yes | yes | yes | yes | yes | yes | `CLAUDE.md` | yes |
+| Codex CLI | yes | >= 0.116.0 | yes | no | yes | < 0.117.0 · skills ($name, >= 0.117) | >= 0.128.0 | no | `AGENTS.md` | no |
+| Gemini CLI | yes | >= 0.26.0 | yes | no | yes | yes (.toml) | no | no | `GEMINI.md` | no |
+| Antigravity | yes | yes | yes | yes | yes | yes | yes | no | `AGENTS.md` | no |
+| Grok Build | yes | yes | yes | yes | yes | skills ($name) | yes | no | `AGENTS.md` | no |
+| OpenClaw | yes | yes | yes | no | yes | gateway | yes | yes | `workspace/AGENTS.md` | no |
+| Cursor | yes | no | yes | no | yes | yes | no | no | `.cursorrules` | no |
+| OpenCode | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Copilot | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Amp | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Kiro | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Goose | yes | no | yes | no | no | no | no | no | `AGENTS.md` | no |
+| Roo Code | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+
+**Legend:** `yes` / `no` = synced or skipped at install time. `skills ($name)` = no file-based slash-command dir; behavior ships as a generated skill invoked with `$command`. `gateway` = OpenClaw resolves slash commands at runtime, not from synced files. Version suffixes are enforced at sync time — out-of-range versions are skipped with a clear message.
+
+**Host CLIs** (`agents cli`) are separate: YAML manifests under `~/.agents/cli/` install binaries onto your PATH (`gh`, `higgsfield`, etc.). They are not copied into per-agent version homes.
+
+### agents-cli features (not agent-native resources)
+
+| Agent | Routines | Teams | Session index |
+|-------|----------|-------|---------------|
+| Claude Code | yes | yes | yes |
+| Codex CLI | yes | yes | yes |
+| Gemini CLI | yes | yes | yes |
+| Cursor | -- | yes | -- |
+| OpenCode | -- | yes | -- |
+| Grok Build | -- | yes | yes |
+| Antigravity | -- | yes | -- |
+| Copilot | -- | -- | yes |
+| OpenClaw, Amp, Kiro, Goose, Roo | -- | -- | -- |
+
+### Version-gated sync
+
+| Capability | Agent | Gate |
+|------------|-------|------|
+| Hooks | Codex | >= 0.116.0 |
+| Hooks | Gemini | >= 0.26.0 |
+| File-based commands | Codex | < 0.117.0 (0.117+ uses command-as-skill) |
+| Plugins | Codex | >= 0.128.0 |
+
+Codex `0.117.0+` no longer reads `.codex/prompts/`; agents-cli converts slash commands into skills so they stay invocable as `$name`. OpenCode's plugin-based hook system is on the roadmap; hooks stay `no` until a writer ships.
+
+Slash commands can declare per-agent/version targeting in frontmatter (`agents:`, `since:`, `until:`). Gating applies when syncing from `~/.agents/commands/` (user/system) into version homes — project `.agents/commands/` files are read in place and are not filtered by `agents:`. This repo ships `.agents/commands/version.md` as `/version` for Claude, Codex, Gemini, Cursor, OpenCode, Copilot, and Grok; Antigravity excluded until verified.
 
 ## FAQ
 

package/dist/commands/cli.js

@@ -52,7 +52,7 @@ Examples:
   agents cli check
 
 When to use:
-  - After 'agents pull' on a new machine, to materialize host binaries
+  - After 'agents repo refresh' on a new machine, to materialize host binaries
   - In a team setup: commit cli/ entries so teammates get the same toolchain
 `);
     cliCmd

package/dist/commands/cloud.js

@@ -123,7 +123,7 @@ Examples:
   # Codex Cloud
   agents cloud run "add auth tests" --provider codex --env env_abc123
 
-  # Default provider (set in ~/.agents-system/agents.yaml)
+  # Default provider (set in ~/.agents/agents.yaml)
   agents cloud run "refactor auth module" --repo user/repo
 `)
         .action(async (positionalPrompt, options) => {

package/dist/commands/commands.js

@@ -506,6 +506,8 @@ function buildCommandRows(opts) {
                 status = 'synced';
             else if (diff.toUpdate.includes(name))
                 status = 'stale';
+            else if (diff.toRemove.includes(name))
+                status = 'stale';
             else
                 status = 'missing';
             targets.push({

package/dist/commands/doctor.js

@@ -310,7 +310,7 @@ function renderTargetText(report, options) {
     }
     else {
         console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        console.log(chalk.gray(`  Run \`agents sync --agent ${report.agent} --agent-version ${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
+        console.log(chalk.gray(`  Run \`agents sync ${report.agent}@${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
     }
 }
 // ─── command registration ────────────────────────────────────────────────────

package/dist/commands/exec.js

@@ -85,7 +85,7 @@ export function registerRunCommand(program) {
     `,
     });
     runCmd.action(async (agentSpec, prompt, options) => {
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -202,10 +202,20 @@ export function registerRunCommand(program) {
             process.stderr.write(chalk.gray(`Workflow '${rawAgent}' → claude (${subagentCount} subagents)\n`));
         }
         else {
-            console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-            console.error(chalk.gray(`Available agents: ${ALL_AGENT_IDS.join(', ')}`));
-            console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
-            process.exit(1);
+            // Smart pick: auto-correct a single typo (insertion/deletion/substitution/transposition)
+            // against the known agent ids before giving up. Example: `cladue` -> `claude`, `grk` -> `grok`.
+            const { fuzzyMatch, FUZZY_PRESETS } = await import('../lib/fuzzy.js');
+            const suggested = fuzzyMatch(rawAgent, ALL_AGENT_IDS, FUZZY_PRESETS.agents);
+            if (suggested && isValidAgent(suggested)) {
+                process.stderr.write(chalk.gray(`Resolved '${rawAgent}' -> '${suggested}' (single-edit match)\n`));
+                agent = suggested;
+            }
+            else {
+                console.error(chalk.red(`Unknown agent: ${rawAgent}`));
+                console.error(chalk.gray(`Available agents: ${ALL_AGENT_IDS.join(', ')}`));
+                console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
+                process.exit(1);
+            }
         }
         version = resolveVersionAlias(agent, version);
         const configuredStrategy = getConfiguredRunStrategy(agent, cwd);
@@ -254,20 +264,34 @@ export function registerRunCommand(program) {
         }
         // Accept the four canonical modes plus 'full' as a permanent silent
         // alias for 'skip' (rewritten downstream by normalizeMode in exec.ts).
-        const mode = options.mode;
+        let mode = options.mode;
         if (!['plan', 'edit', 'auto', 'skip', 'full'].includes(mode)) {
             console.error(chalk.red(`Invalid mode: ${mode}. Use plan, edit, auto, or skip ('full' accepted as alias for skip).`));
             process.exit(1);
         }
-        // Surface capability errors as a clean CLI message instead of a stack
-        // trace from buildExecCommand. resolveMode degrades 'auto' silently and
-        // throws on unsupported 'plan'/'skip' — we catch and pretty-print.
+        // When the user did not pass --mode explicitly, the default is the
+        // generic 'plan'. Some agents (antigravity: edit/skip only, grok in some
+        // configurations) do not support plan. For implicit defaults, degrade
+        // silently to the agent's first listed mode rather than throwing — the
+        // user did not ask for read-only, they asked for "just run it." An
+        // explicit --mode plan still throws (see resolveMode), because silently
+        // elevating an explicit read-only request to edit is unsafe.
+        const modeSource = runCmd.getOptionValueSource('mode');
+        const modeIsDefault = modeSource === 'default';
         try {
             resolveMode(agent, normalizeMode(mode));
         }
         catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
+            if (modeIsDefault) {
+                mode = defaultModeFor(agent);
+                if (!options.quiet) {
+                    process.stderr.write(chalk.gray(`[agents] ${agent} has no '${options.mode}' mode; using '${mode}'\n`));
+                }
+            }
+            else {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
         }
         const effort = options.effort;
         if (!['low', 'medium', 'high', 'xhigh', 'max', 'auto'].includes(effort)) {
@@ -344,12 +368,24 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             const entries = options.fallback.split(',').map(s => s.trim()).filter(Boolean);
+            const { fuzzyMatch: fuzzyFb, FUZZY_PRESETS: PRESETS_FB } = await import('../lib/fuzzy.js');
             for (const entry of entries) {
-                const [fbAgent, fbVersion] = entry.split('@');
-                if (!isValidAgent(fbAgent)) {
-                    console.error(chalk.red(`Unknown fallback agent: ${fbAgent}`));
-                    console.error(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
-                    process.exit(1);
+                const [rawFbAgent, fbVersion] = entry.split('@');
+                let fbAgent;
+                if (isValidAgent(rawFbAgent)) {
+                    fbAgent = rawFbAgent;
+                }
+                else {
+                    const suggested = fuzzyFb(rawFbAgent, ALL_AGENT_IDS, PRESETS_FB.agents);
+                    if (suggested && isValidAgent(suggested)) {
+                        process.stderr.write(chalk.gray(`Resolved fallback '${rawFbAgent}' -> '${suggested}' (single-edit match)\n`));
+                        fbAgent = suggested;
+                    }
+                    else {
+                        console.error(chalk.red(`Unknown fallback agent: ${rawFbAgent}`));
+                        console.error(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
+                        process.exit(1);
+                    }
                 }
                 if (fbAgent === agent) {
                     console.error(chalk.red(`Fallback cannot include the primary agent (${agent}). Rate-limit fallback only helps when switching providers.`));

package/dist/commands/hooks.js

@@ -4,8 +4,8 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { checkbox } from '@inquirer/prompts';
-import { AGENTS, HOOKS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
-import { supports } from '../lib/capabilities.js';
+import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { supports, capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverHooksFromRepo, installHooksCentrally, listCentralHooks, listInstalledHooksWithScope, getHookInfo, parseHookManifest, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
@@ -58,7 +58,7 @@ When to use:
             agentId = resolveAgentName(agentName);
             if (!agentId) {
                 spinner.stop();
-                console.log(chalk.red(formatAgentError(agentName, [...HOOKS_CAPABLE_AGENTS])));
+                console.log(chalk.red(formatAgentError(agentName, [...capableAgents('hooks')])));
                 process.exit(1);
             }
             requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
@@ -185,7 +185,7 @@ When to use:
         }
         // No agent specified - show default version for each hooks-capable agent
         console.log(chalk.bold('Installed Hooks\n'));
-        for (const aid of HOOKS_CAPABLE_AGENTS) {
+        for (const aid of capableAgents('hooks')) {
             const agent = AGENTS[aid];
             const installedVersions = listInstalledVersions(aid);
             const defaultVer = getGlobalDefault(aid);
@@ -338,7 +338,7 @@ Examples:
             // Get agent and version selection
             let selectedAgents;
             let versionSelections;
-            const hooksCapableAgents = Array.from(HOOKS_CAPABLE_AGENTS);
+            const hooksCapableAgents = Array.from(capableAgents('hooks'));
             if (options.agents) {
                 const result = await resolveAgentTargetsAutoInstalling(options.agents, hooksCapableAgents, { yes: options.yes });
                 if (!result) {
@@ -468,7 +468,7 @@ Examples:
             // agent@x.y.z, agent@all, literal all) works here too.
             let availableTargets = hookInfo.targets;
             if (options?.agents) {
-                const requestedTargets = resolveInstalledAgentTargets(options.agents, [...HOOKS_CAPABLE_AGENTS]);
+                const requestedTargets = resolveInstalledAgentTargets(options.agents, [...capableAgents('hooks')]);
                 const requested = new Set();
                 for (const aid of requestedTargets.directAgents) {
                     for (const ver of listInstalledVersions(aid)) {

package/dist/commands/inspect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `agents inspect <agent>[@version]` — single-agent, single-version detail view.
+ *
+ * Summary mode shows the per-version header (paths, shim, capabilities, resource
+ * counts, sessions). Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...) list
+ * one resource kind; passing a positional query to the same flag fuzzy-searches
+ * for a single resource and prints its detail. Resource names render as OSC-8
+ * hyperlinks to the marker file (SKILL.md / WORKFLOW.md / AGENT.md / the file
+ * itself) so users can click straight to the source.
+ */
+import { Command } from 'commander';
+interface InspectOptions {
+    brief?: boolean;
+    json?: boolean;
+    commands?: boolean | string;
+    skills?: boolean | string;
+    hooks?: boolean | string;
+    mcp?: boolean | string;
+    rules?: boolean | string;
+    plugins?: boolean | string;
+    workflows?: boolean | string;
+    subagents?: boolean | string;
+}
+export declare function registerInspectCommand(program: Command): void;
+export declare function inspectAction(target: string, options: InspectOptions): Promise<void>;
+export {};