@phnx-labs/agents-cli 1.20.32 → 1.20.34

package/dist/commands/view.d.ts

@@ -9,6 +9,7 @@
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
 import { type ProfileSummary } from '../lib/profiles.js';
+type SyncState = 'synced' | 'new' | 'modified' | 'deleted';
 /** Per-section filter flags. When any are true, only those sections render. */
 export interface ViewSectionFilter {
     commands?: boolean;
@@ -27,6 +28,7 @@ export interface ViewJsonVersion {
     isDefault: boolean;
     signedIn: boolean;
     email: string | null;
+    accountId?: string | null;
     plan: string | null;
     usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null;
     overageCredits?: {
@@ -40,6 +42,9 @@ export interface ViewJsonVersion {
     }>;
     lastActive: string | null;
     path: string;
+    /** Present only when --resources / --detailed (or --json with a section
+     *  flag) is passed: this version's resource inventory with git sync-state. */
+    resources?: VersionResourcesJson;
 }
 /** Machine-readable entry for one agent's installed versions. */
 export interface ViewJsonAgent {
@@ -47,6 +52,37 @@ export interface ViewJsonAgent {
     versions: ViewJsonVersion[];
     profiles: ProfileSummary[];
 }
+/** Resource sections that --resources can include in --json output. */
+export type ResourceSection = 'commands' | 'skills' | 'mcp' | 'memory' | 'hooks' | 'workflows' | 'plugins';
+/** One resource entry in `--json --resources` output. */
+export interface ResourceItemJson {
+    name: string;
+    scope?: 'user' | 'project';
+    /** Git sync-state vs ~/.agents. Omitted for project-scoped resources or when
+     *  ~/.agents isn't a git repo. When queried via --host it reflects the
+     *  remote's ~/.agents — i.e. per-host resource drift. */
+    syncState?: SyncState;
+    description?: string;
+    /** Skills only, when > 0. */
+    ruleCount?: number;
+}
+/** Per-version resource inventory; one key per requested section. */
+export interface VersionResourcesJson {
+    commands?: ResourceItemJson[];
+    skills?: ResourceItemJson[];
+    mcp?: ResourceItemJson[];
+    memory?: ResourceItemJson[];
+    hooks?: ResourceItemJson[];
+    workflows?: ResourceItemJson[];
+    plugins?: ResourceItemJson[];
+}
+/** Build the set of resource sections to include in `--json` from the
+ *  `--resources` / `--detailed` flags, plus (in --json mode) the per-section
+ *  boolean filters (`--skills` etc.) that plain `--json` historically ignored. */
+export declare function parseResourceSections(options: {
+    resources?: string | boolean;
+    detailed?: boolean;
+} & ViewSectionFilter, jsonMode: boolean): Set<ResourceSection>;
 /**
  * Prune older installed versions that share an email with a newer installed
  * version. Keeps the highest semver per email, skips the global default (with
@@ -66,6 +102,9 @@ export declare function viewAction(agentArg?: string, options?: {
     prune?: boolean;
     yes?: boolean;
     dryRun?: boolean;
+    resources?: string | boolean;
+    detailed?: boolean;
 } & ViewSectionFilter): Promise<void>;
 /** Register the `agents view` command. */
 export declare function registerViewCommand(program: Command): void;
+export {};

package/dist/commands/view.js

@@ -1,3 +1,4 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -5,9 +6,10 @@ import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
+import { resolveVersionFilter, AgentSpecError } from '../lib/agent-spec/index.js';
 import { listCliStatus } from '../lib/cli-resources.js';
 import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins.js';
@@ -22,8 +24,24 @@ import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
 // Shown in the email column for agents that are signed in but expose no email
-// address locally (Antigravity, Kimi store an opaque OAuth/JWT credential).
+// address locally (Antigravity stores an opaque OAuth grant with no identity).
 const SIGNED_IN_LABEL = 'signed in';
+/**
+ * Text for the account (email) column. Prefers the real email; otherwise, for a
+ * signed-in agent whose credential carries no email but does carry an opaque
+ * account id (Kimi's user_id), show `id:<user_id>` so distinct accounts read
+ * distinctly instead of a generic "signed in". Falls back to "signed in" when we
+ * have neither (Antigravity), and empty when signed out.
+ */
+function accountColumnLabel(info) {
+    if (!info)
+        return '';
+    if (info.email)
+        return info.email;
+    if (info.signedIn)
+        return info.accountId ? `id:${info.accountId}` : SIGNED_IN_LABEL;
+    return '';
+}
 /**
  * Group profile summaries by their host harness, optionally filtered to a
  * single agent. Profile YAMLs that fail validation are silently skipped by
@@ -308,7 +326,10 @@ async function showInstalledVersions(filterAgentId) {
             return info;
         return {
             ...info,
-            plan: canon.plan,
+            // Prefer a plan the live usage fetch surfaced (Kimi reports membership
+            // tier in /usages; its local auth file has none) and fall back to the
+            // account-derived plan (Claude's billingType).
+            plan: usageByKey.get(key)?.snapshot?.plan ?? canon.plan,
             // Throttle state comes from the live usage windows, not the pay-as-you-go
             // overage flag that AccountInfo.usageStatus used to carry. A maxed window
             // means rate-limited; no snapshot means no badge. See
@@ -351,10 +372,9 @@ async function showInstalledVersions(filterAgentId) {
                 maxVerLabel = Math.max(maxVerLabel, label.length);
                 const rawInfo = infoMap.get(`${agentId}:${v}`);
                 const info = rawInfo ? mergeCanonical(rawInfo) : undefined;
-                if (info?.email)
-                    maxEmail = Math.max(maxEmail, info.email.length);
-                else if (info?.signedIn)
-                    maxEmail = Math.max(maxEmail, SIGNED_IN_LABEL.length);
+                const accountLabel = accountColumnLabel(info);
+                if (accountLabel)
+                    maxEmail = Math.max(maxEmail, accountLabel.length);
                 if (info?.plan)
                     maxPlanWidth = Math.max(maxPlanWidth, info.plan.length);
             }
@@ -430,9 +450,10 @@ async function showInstalledVersions(filterAgentId) {
                 }
                 else {
                     if (hasEmail || hasUsage || hasActive || signedIn) {
-                        // Signed-in agents without a local email (Antigravity, Kimi) show a
-                        // "signed in" placeholder so they read as logged in, not blank.
-                        const display = vInfo?.email || (signedIn ? SIGNED_IN_LABEL : '');
+                        // Signed-in agents without a local email show their account id
+                        // (Kimi's user_id) or a "signed in" placeholder (Antigravity) so they
+                        // read as logged in, not blank.
+                        const display = accountColumnLabel(vInfo);
                         const emailCol = display.padEnd(maxEmail);
                         parts.push(display ? chalk.cyan(emailCol) : ' '.repeat(maxEmail));
                     }
@@ -513,7 +534,7 @@ async function showInstalledVersions(filterAgentId) {
             const gUsageStr = formatUsageSummary(gInfo?.plan || null, gUsage?.snapshot || null);
             const gActiveStr = gInfo ? formatLastActive(gInfo.lastActive) : '';
             if (gInfo?.email || gUsageStr || gActiveStr || gInfo?.signedIn) {
-                const gDisplay = gInfo?.email || (gInfo?.signedIn ? SIGNED_IN_LABEL : '');
+                const gDisplay = accountColumnLabel(gInfo);
                 parts.push(gDisplay ? chalk.cyan(gDisplay) : '');
             }
             if (gUsageStr || gActiveStr)
@@ -684,53 +705,9 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         }
     }
     const home = getVersionHomePath(agentId, version);
-    // Get git sync status if ~/.agents/ is a git repo
-    const userAgentsDir = getUserAgentsDir();
-    const hasGitRepo = isGitRepo(userAgentsDir);
-    const commandsSync = hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'commands') : null;
-    const skillsSync = hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'skills') : null;
-    const hooksSync = hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'hooks') : null;
-    const memorySync = hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'rules') : null;
-    // Helper to determine sync state for a resource
-    const getSyncState = (resourceName, resourceType, syncStatus) => {
-        if (!syncStatus)
-            return undefined;
-        let relativePath;
-        if (resourceType === 'commands') {
-            relativePath = `commands/${resourceName}.md`;
-        }
-        else if (resourceType === 'skills') {
-            relativePath = `skills/${resourceName}`;
-        }
-        else if (resourceType === 'hooks') {
-            relativePath = `hooks/${resourceName}`;
-        }
-        else {
-            // Rules files: map agent-specific name (CLAUDE.md) back to canonical (AGENTS.md)
-            const centralName = getCentralRulesFileName(agentId);
-            relativePath = `rules/${centralName}`;
-        }
-        const matchesPath = (f) => f === relativePath || f.startsWith(relativePath + '/');
-        const isNew = syncStatus.new.some(matchesPath);
-        const isStaged = syncStatus.staged.some(matchesPath);
-        const isModified = syncStatus.modified.some(matchesPath);
-        const isDeleted = syncStatus.deleted.some(matchesPath);
-        const isSynced = syncStatus.synced.some(matchesPath);
-        if (isNew || isStaged) {
-            return 'new';
-        }
-        if (isModified) {
-            return 'modified';
-        }
-        if (isDeleted) {
-            return 'deleted';
-        }
-        if (isSynced) {
-            return 'synced';
-        }
-        // Not in any array = local-only (untracked with no files)
-        return 'new';
-    };
+    // Git sync status if ~/.agents/ is a git repo (shared loader — see
+    // loadResourceSyncData / resolveResourceSyncState, reused by --json --resources).
+    const { hasGitRepo, commands: commandsSync, skills: skillsSync, hooks: hooksSync, memory: memorySync } = await loadResourceSyncData();
     const resources = getAgentResources(agentId, {
         cwd,
         scope: 'all',
@@ -743,23 +720,23 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         version,
         commands: resources.commands.map(r => ({
             ...r,
-            syncState: r.scope === 'project' ? undefined : getSyncState(r.name, 'commands', commandsSync),
+            syncState: r.scope === 'project' ? undefined : resolveResourceSyncState(agentId, r.name, 'commands', commandsSync),
         })),
         skills: resources.skills.map(r => ({
             ...r,
             // ruleCount of 0 is noise — every skill has 0 unless it ships subrules, which is rare.
             ruleCount: r.ruleCount && r.ruleCount > 0 ? r.ruleCount : undefined,
-            syncState: r.scope === 'project' ? undefined : getSyncState(r.name, 'skills', skillsSync),
+            syncState: r.scope === 'project' ? undefined : resolveResourceSyncState(agentId, r.name, 'skills', skillsSync),
         })),
         skillErrors: resources.skillErrors,
         mcp: resources.mcp.map(r => ({ name: r.name, scope: r.scope, syncState: r.scope === 'project' ? undefined : 'synced' })),
         memory: resources.memory.map(r => ({
             ...r,
-            syncState: r.scope === 'project' ? undefined : getSyncState(r.name, 'memory', memorySync),
+            syncState: r.scope === 'project' ? undefined : resolveResourceSyncState(agentId, r.name, 'memory', memorySync),
         })),
         hooks: resources.hooks.map(r => ({
             ...r,
-            syncState: r.scope === 'project' ? undefined : getSyncState(r.name, 'hooks', hooksSync),
+            syncState: r.scope === 'project' ? undefined : resolveResourceSyncState(agentId, r.name, 'hooks', hooksSync),
         })),
         workflows: resources.workflows.map(r => ({ name: r.name, path: r.path, scope: r.scope })),
     };
@@ -825,13 +802,10 @@ async function showAgentResources(agentId, requestedVersion, filter) {
             cliVersion: version,
             info: accountInfo,
         });
-        const emailStr = accountInfo.email
-            ? chalk.cyan(`  ${accountInfo.email}`)
-            : accountInfo.signedIn
-                ? chalk.cyan(`  ${SIGNED_IN_LABEL}`)
-                : '';
+        const accountLabel = accountColumnLabel(accountInfo);
+        const emailStr = accountLabel ? chalk.cyan(`  ${accountLabel}`) : '';
         const status = chalk.green(version);
-        const usageStr = formatUsageSummary(accountInfo.plan, null);
+        const usageStr = formatUsageSummary(usageInfo.snapshot?.plan ?? accountInfo.plan, null);
         const usagePart = usageStr ? `  ${usageStr}` : '';
         console.log(`  ${colorAgent(agentId)(AGENTS[agentId].name.padEnd(14))} ${status}${emailStr}${usagePart}`);
         const usageLines = formatUsageSection(usageInfo);
@@ -971,14 +945,144 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         console.log(chalk.gray('Legend:'), chalk.green('Tracked'), chalk.blue('Local-only'), chalk.yellow('Modified'), chalk.red('Deleted'));
     }
 }
+const ALL_RESOURCE_SECTIONS = ['commands', 'skills', 'mcp', 'memory', 'hooks', 'workflows', 'plugins'];
+/** Load git sync-state for the tracked resource kinds. Shared by the human
+ *  detail view (showAgentResources) and the `--json --resources` path. */
+async function loadResourceSyncData() {
+    const userAgentsDir = getUserAgentsDir();
+    const hasGitRepo = isGitRepo(userAgentsDir);
+    return {
+        hasGitRepo,
+        commands: hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'commands') : null,
+        skills: hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'skills') : null,
+        hooks: hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'hooks') : null,
+        memory: hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'rules') : null,
+    };
+}
+/** Resolve one resource's git sync-state. Extracted from showAgentResources so
+ *  the human view and the JSON path derive drift identically. */
+function resolveResourceSyncState(agentId, resourceName, resourceType, syncStatus) {
+    if (!syncStatus)
+        return undefined;
+    let relativePath;
+    if (resourceType === 'commands') {
+        relativePath = `commands/${resourceName}.md`;
+    }
+    else if (resourceType === 'skills') {
+        relativePath = `skills/${resourceName}`;
+    }
+    else if (resourceType === 'hooks') {
+        relativePath = `hooks/${resourceName}`;
+    }
+    else {
+        // Rules files: map agent-specific name (CLAUDE.md) back to canonical (AGENTS.md)
+        const centralName = getCentralRulesFileName(agentId);
+        relativePath = `rules/${centralName}`;
+    }
+    const matchesPath = (f) => f === relativePath || f.startsWith(relativePath + '/');
+    if (syncStatus.new.some(matchesPath) || syncStatus.staged.some(matchesPath))
+        return 'new';
+    if (syncStatus.modified.some(matchesPath))
+        return 'modified';
+    if (syncStatus.deleted.some(matchesPath))
+        return 'deleted';
+    if (syncStatus.synced.some(matchesPath))
+        return 'synced';
+    // Not in any array = local-only (untracked with no files)
+    return 'new';
+}
+/** Collect one version's resources for `--json`, limited to `sections`. Scans
+ *  the version's `home`, so per-version differences are reported accurately. */
+function collectVersionResources(agentId, home, cwd, cliInstalled, sections, sync) {
+    const res = getAgentResources(agentId, { cwd, scope: 'all', cliInstalled, home });
+    const out = {};
+    const withSync = (r, type, syncStatus) => {
+        const item = { name: r.name, scope: r.scope };
+        if (r.scope !== 'project') {
+            const s = resolveResourceSyncState(agentId, r.name, type, syncStatus);
+            if (s)
+                item.syncState = s;
+        }
+        if (r.description)
+            item.description = r.description;
+        return item;
+    };
+    if (sections.has('commands'))
+        out.commands = res.commands.map((r) => withSync(r, 'commands', sync.commands));
+    if (sections.has('skills')) {
+        out.skills = res.skills.map((r) => {
+            const item = withSync(r, 'skills', sync.skills);
+            // ruleCount of 0 is noise — every skill has 0 unless it ships subrules.
+            if (r.ruleCount && r.ruleCount > 0)
+                item.ruleCount = r.ruleCount;
+            return item;
+        });
+    }
+    if (sections.has('mcp')) {
+        out.mcp = res.mcp.map((r) => {
+            const item = { name: r.name, scope: r.scope };
+            if (r.scope !== 'project')
+                item.syncState = 'synced';
+            return item;
+        });
+    }
+    if (sections.has('memory'))
+        out.memory = res.memory.map((r) => withSync(r, 'memory', sync.memory));
+    if (sections.has('hooks'))
+        out.hooks = res.hooks.map((r) => withSync(r, 'hooks', sync.hooks));
+    if (sections.has('workflows'))
+        out.workflows = res.workflows.map((r) => ({ name: r.name, scope: r.scope }));
+    if (sections.has('plugins')) {
+        out.plugins = discoverPlugins()
+            .filter((p) => pluginSupportsAgent(p, agentId))
+            .map((p) => ({ name: p.name }));
+    }
+    return out;
+}
+/** Build the set of resource sections to include in `--json` from the
+ *  `--resources` / `--detailed` flags, plus (in --json mode) the per-section
+ *  boolean filters (`--skills` etc.) that plain `--json` historically ignored. */
+export function parseResourceSections(options, jsonMode) {
+    const set = new Set();
+    const addAll = () => ALL_RESOURCE_SECTIONS.forEach((s) => set.add(s));
+    if (options.detailed)
+        addAll();
+    const rv = options.resources;
+    if (rv !== undefined) {
+        if (rv === true || String(rv).trim() === '' || String(rv).toLowerCase() === 'all') {
+            addAll();
+        }
+        else {
+            for (const raw of String(rv).split(',').map((s) => s.trim().toLowerCase()).filter(Boolean)) {
+                const section = raw === 'rules' ? 'memory' : raw; // --rules is the memory file
+                if (ALL_RESOURCE_SECTIONS.includes(section))
+                    set.add(section);
+            }
+        }
+    }
+    if (jsonMode) {
+        const flagToSection = [
+            ['commands', 'commands'], ['skills', 'skills'], ['mcp', 'mcp'],
+            ['workflows', 'workflows'], ['plugins', 'plugins'], ['hooks', 'hooks'], ['rules', 'memory'],
+        ];
+        for (const [flag, section] of flagToSection)
+            if (options[flag])
+                set.add(section);
+    }
+    return set;
+}
 /**
  * Collect structured info for one or more agents without rendering to the
  * terminal. Used by `--json` output and any programmatic consumer (e.g. the
  * agents-cli extension's "resume current session in best available version"
  * command).
  */
-async function collectAgentsJson(filterAgentId) {
+async function collectAgentsJson(filterAgentId, resourceSections) {
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
+    const wantResources = !!resourceSections && resourceSections.size > 0;
+    // Only pay for the git-status + resource scans when resources were requested.
+    const resourceSync = wantResources ? await loadResourceSyncData() : null;
+    const cliStates = wantResources ? await getAllCliStates() : null;
     const infoFetches = [];
     for (const agentId of agentsToShow) {
         for (const ver of listInstalledVersions(agentId)) {
@@ -1002,7 +1106,10 @@ async function collectAgentsJson(filterAgentId) {
             return info;
         return {
             ...info,
-            plan: canon.plan,
+            // Prefer a plan the live usage fetch surfaced (Kimi reports membership
+            // tier in /usages; its local auth file has none) and fall back to the
+            // account-derived plan (Claude's billingType).
+            plan: usageByKey.get(key)?.snapshot?.plan ?? canon.plan,
             // Throttle state comes from the live usage windows, not the pay-as-you-go
             // overage flag that AccountInfo.usageStatus used to carry. A maxed window
             // means rate-limited; no snapshot means no badge. See
@@ -1012,7 +1119,7 @@ async function collectAgentsJson(filterAgentId) {
         };
     };
     const byAgent = new Map();
-    for (const { agentId, version, info: rawInfo } of infoResults) {
+    for (const { agentId, version, home, info: rawInfo } of infoResults) {
         const info = mergeCanonical(rawInfo);
         const globalDefault = getGlobalDefault(agentId);
         const usageKey = getUsageLookupKey(info);
@@ -1023,6 +1130,7 @@ async function collectAgentsJson(filterAgentId) {
             isDefault: version === globalDefault,
             signedIn: info.signedIn,
             email: info.email,
+            accountId: info.accountId,
             plan: info.plan,
             usageStatus: info.usageStatus,
             overageCredits: info.overageCredits,
@@ -1036,6 +1144,9 @@ async function collectAgentsJson(filterAgentId) {
             lastActive: info.lastActive ? info.lastActive.toISOString() : null,
             path: getVersionDir(agentId, version),
         };
+        if (wantResources && resourceSync) {
+            entry.resources = collectVersionResources(agentId, home, process.cwd(), cliStates?.[agentId]?.installed ?? false, resourceSections, resourceSync);
+        }
         const existing = byAgent.get(agentId);
         if (existing)
             existing.push(entry);
@@ -1246,7 +1357,10 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
  * Exported for use by deprecated aliases.
  */
 export async function viewAction(agentArg, options) {
-    const json = options?.json === true;
+    // --resources / --detailed imply --json (they only shape structured output).
+    const explicitResources = options?.detailed === true || options?.resources !== undefined;
+    const json = options?.json === true || explicitResources;
+    const resourceSections = parseResourceSections(options ?? {}, json);
     const prune = options?.prune === true;
     const yes = options?.yes === true;
     const dryRun = options?.dryRun === true;
@@ -1278,7 +1392,7 @@ export async function viewAction(agentArg, options) {
             return;
         }
         if (json) {
-            const data = await collectAgentsJson();
+            const data = await collectAgentsJson(undefined, resourceSections);
             console.log(JSON.stringify(data, null, 2));
             return;
         }
@@ -1298,12 +1412,25 @@ export async function viewAction(agentArg, options) {
         console.log(chalk.red(formatAgentError(agentName)));
         process.exit(1);
     }
-    // Keep 'default'/'pinned' as-is since showAgentResources handles 'default';
-    // resolveVersionAlias returns undefined for both (they're synonyms), which
-    // would otherwise skip the detailed view.
-    const requestedVersion = (parts[1] === 'default' || parts[1] === 'pinned')
-        ? 'default'
-        : (resolveVersionAlias(agentId, parts[1]) ?? null);
+    // Resolve the @version filter through the agent-spec engine:
+    //   bare/@any → null (show all versions), @default/@pinned → 'default'
+    //   (showAgentResources handles it), @latest/@oldest/@x.y.z → concrete.
+    let requestedVersion;
+    try {
+        requestedVersion = resolveVersionFilter(agentId, parts[1]).version;
+    }
+    catch (e) {
+        if (e instanceof AgentSpecError) {
+            if (json) {
+                console.log(JSON.stringify({ error: e.message }));
+            }
+            else {
+                console.log(chalk.red(e.message));
+            }
+            process.exit(1);
+        }
+        throw e;
+    }
     if (prune) {
         if (requestedVersion) {
             console.log(chalk.red('--prune does not take a @version suffix.'));
@@ -1314,9 +1441,9 @@ export async function viewAction(agentArg, options) {
         return;
     }
     if (json) {
-        // --json ignores the @version suffix (detailed resource view is not yet
-        // exposed as structured data). Emit the version list for the agent.
-        const data = await collectAgentsJson(agentId);
+        // --json ignores the @version suffix, but --resources/--detailed (or a
+        // section flag) now attach each version's resource inventory + sync-state.
+        const data = await collectAgentsJson(agentId, resourceSections);
         console.log(JSON.stringify(data[0] ?? { agent: agentId, versions: [], profiles: [] }, null, 2));
         return;
     }
@@ -1336,10 +1463,11 @@ export async function viewAction(agentArg, options) {
 }
 /** Register the `agents view` command. */
 export function registerViewCommand(program) {
-    program
-        .command('view [agent]')
+    addHostOption(program.command('view [agent]'))
         .description('Show what agent CLIs are installed and which versions you have. Inspect resources when you pass agent@version.')
         .option('--json', 'Emit machine-readable JSON (version list, usage, signed-in status).')
+        .option('--resources [sections]', 'In --json mode, include each version\'s resources: "all" (default) or a comma list (skills,plugins,mcp,commands,workflows,memory,hooks). Implies --json.')
+        .option('--detailed', 'Include all resources in --json output (alias for --resources all). Implies --json.')
         .option('--prune', 'Remove older installed versions that share an account with a newer installed version. Skips the global default.')
         .option('--dry-run', 'With --prune, show duplicate versions without deleting')
         .option('-y, --yes', 'Skip the prune confirmation prompt.')
@@ -1367,6 +1495,11 @@ Examples:
   # Machine-readable output (used by tools that pick a version programmatically)
   agents view claude --json
 
+  # One call: full inventory + what's synced on a host (installed agents,
+  # versions, accounts, usage, and per-version resource sync-state)
+  agents view claude --host yosemite-s0 --json --resources all
+  agents view claude --json --resources skills,plugins   # just those sections
+
   # Prune older versions that duplicate an account already used by a newer version
   agents view --prune --dry-run
   agents view claude --prune

package/dist/commands/workflows.js

@@ -8,9 +8,9 @@ import { resolveAgentName, agentLabel } from '../lib/agents.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
-import { getVersionHomePath, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/versions.js';
+import { getVersionHomePath, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/versions.js';
 import { recordVersionResources, getUserWorkflowsDir } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Register the `agents workflows` command tree (list, view, add, remove). */
 export function registerWorkflowsCommands(program) {
@@ -73,7 +73,7 @@ Examples:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = parts[1] ? resolveVersionAlias(resolved, parts[1]) : undefined;
+            filterVersion = resolveListFilterOrExit(resolved, parts[1]);
         }
         const rows = buildWorkflowRows({ filterAgent, filterVersion });
         spinner.stop();

package/dist/index.js

@@ -51,7 +51,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { IS_WINDOWS } from './lib/platform/index.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
@@ -764,6 +764,7 @@ async function registerAllEagerCommands() {
     await reg(loadTrash);
     await reg(loadRestore);
     await reg(loadDoctor);
+    await reg(loadStatus);
     registerExecAliasCommand(program);
     await reg(loadProfiles);
     await reg(loadSecrets);
@@ -847,6 +848,18 @@ const requestedCommand = passedArgs.find((arg) => !arg.startsWith('-'));
 // Help and version output are pure documentation — they must never gate on
 // setup, otherwise `agents <cmd> --help` becomes useless on a fresh box.
 const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V');
+// `--host` passthrough: run this invocation on a remote machine over SSH instead
+// of locally. Handled before any local command registration / update check /
+// background sync — a remote run needs none of that. Only the allowlisted
+// read-only + config + teams commands route here; `run`/`sessions` are absent
+// from the table and fall through to their own richer `--host` handling below.
+// `--help`/`--version` stay local (docs must work without a reachable host).
+if (requestedCommand !== undefined && !helpOrVersionRequested) {
+    const { maybeRunOnHost } = await import('./lib/hosts/passthrough.js');
+    if (await maybeRunOnHost(requestedCommand, passedArgs)) {
+        process.exit(process.exitCode ?? 0);
+    }
+}
 // Register only the command(s) this invocation actually uses. Lazy commands
 // (sessions/teams/cloud) are handled after applyGlobalHelpConventions below.
 const isLazyRequest = requestedCommand !== undefined && LAZY_COMMAND_NAMES.has(requestedCommand);
@@ -882,7 +895,8 @@ if (!helpOrVersionRequested) {
     // fire-and-forget the next background sync. System repo gets a real fast-forward
     // pull (read-only locally, safe). User repo and extras get fetch-only + a
     // status marker that we'll print on the *next* invocation.
-    const { spawnDetachedSync } = await import('./lib/auto-pull.js');
+    const { spawnDetachedSync, printPendingUpdateNotices } = await import('./lib/auto-pull.js');
+    printPendingUpdateNotices();
     spawnDetachedSync();
 }
 // First-run experience: no args + no config yet + TTY -> launch interactive setup.

package/dist/lib/acp/harnesses.d.ts

@@ -2,7 +2,7 @@
  * Per-harness spawn configuration for Agent Client Protocol (ACP) mode.
  *
  * Each entry describes how to launch a coding agent CLI as an ACP server
- * (stdio JSON-RPC). Unsupported harnesses (amp, roo, goose-stdio) are omitted;
+ * (stdio JSON-RPC). Unsupported harnesses (amp, goose-stdio) are omitted;
  * callers should fall back to the legacy direct-exec path for those.
  *
  * Sources: https://agentclientprotocol.com/get-started/agents + vendor docs.

package/dist/lib/acp/harnesses.js

@@ -2,7 +2,7 @@
  * Per-harness spawn configuration for Agent Client Protocol (ACP) mode.
  *
  * Each entry describes how to launch a coding agent CLI as an ACP server
- * (stdio JSON-RPC). Unsupported harnesses (amp, roo, goose-stdio) are omitted;
+ * (stdio JSON-RPC). Unsupported harnesses (amp, goose-stdio) are omitted;
  * callers should fall back to the legacy direct-exec path for those.
  *
  * Sources: https://agentclientprotocol.com/get-started/agents + vendor docs.
@@ -61,7 +61,7 @@ export const ACP_HARNESSES = {
     // goose: ACP over HTTP via `goosed`, not a clean stdio subcommand.
     // copilot, kiro: excluded for now (not installed in the reference environment,
     //                no local verification possible).
-    // amp, roo: not on the ACP agents list.
+    // amp: not on the ACP agents list.
 };
 /** Returns the ACP spawn spec for an agent, or undefined if the harness does not speak ACP. */
 export function getAcpSpec(agent) {

package/dist/lib/agent-spec/index.d.ts

@@ -0,0 +1,18 @@
+import type { AgentId } from '../types.js';
+import type { AgentTarget, ResolveOptions, VersionFilter } from './types.js';
+export * from './types.js';
+export * from './primitives.js';
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export declare const AGENT_SPEC_HELP: string;
+/** Resolve a spec (single or comma-list) into concrete installed targets. */
+export declare function resolveAgentTargets(spec: string, opts?: ResolveOptions): AgentTarget[];
+/** Resolve a spec that must name exactly one installed version. */
+export declare function resolveSingleAgentTarget(spec: string, opts?: ResolveOptions): {
+    agent: AgentId;
+    version: string;
+    source: import('./types.js').VersionSource;
+};
+/** Resolve a read/list command's version filter (undefined → all, @default → the default, else concrete). */
+export declare function resolveVersionFilter(agent: AgentId, qualifier: string | undefined | null, opts?: ResolveOptions): VersionFilter;
+/** Concrete version filter for list/display commands (undefined → show all, @default → the default version). */
+export declare function resolveListFilter(agent: AgentId, qualifier: string | undefined | null, opts?: ResolveOptions): string | undefined;