@phnx-labs/agents-cli 1.20.0 → 1.20.3

package/dist/commands/utils.d.ts

@@ -4,6 +4,8 @@
  * Small helpers used across multiple commands: prompt cancellation detection,
  * table formatting, spinner management, and platform-specific workarounds.
  */
+import type { AgentId } from '../lib/types.js';
+import { type InstalledAgentTargetResult, type VersionSelectionResult } from '../lib/versions.js';
 /**
  * Check if an error is from user cancelling a prompt (Ctrl+C)
  */
@@ -58,3 +60,34 @@ export declare function promptRemovalTargets(resourceName: string, targets: Remo
  * Format a path for display, using ~ for home directory
  */
 export declare function formatPath(fullPath: string, cwd?: string): string;
+/**
+ * Make sure every specific `agent@x.y.z` the user typed is installed before
+ * the caller resolves targets. Returns true if the caller should continue,
+ * false if the user declined the prompt. Exported so non-standard caller
+ * shapes (e.g. mcp.ts's manifest-shaped parser) can run the pre-flight
+ * without going through resolveAgentVersionTargets first.
+ */
+export declare function ensureAgentVersionsInstalled(value: string, availableAgents: readonly AgentId[], options?: {
+    yes?: boolean;
+}): Promise<boolean>;
+/**
+ * Resolve a `--agents` selector and, if any requested `agent@version` isn't
+ * installed yet, prompt to install it (or auto-install with --yes) before
+ * delegating to resolveAgentVersionTargets. Returns null when the user
+ * declines the install prompt — callers should treat that as a clean cancel.
+ */
+export declare function resolveAgentTargetsAutoInstalling(value: string, availableAgents: readonly AgentId[], options?: {
+    yes?: boolean;
+    allVersions?: boolean;
+}): Promise<VersionSelectionResult | null>;
+/**
+ * Same as resolveAgentTargetsAutoInstalling but returns the broader
+ * InstalledAgentTargetResult that includes `directAgents` (for paths like
+ * `agents install` and `mcp register` that fall through to unmanaged homes
+ * when no managed version is installed).
+ */
+export declare function resolveInstalledAgentTargetsAutoInstalling(value: string, availableAgents: readonly AgentId[], options?: {
+    yes?: boolean;
+    allVersions?: boolean;
+}): Promise<InstalledAgentTargetResult | null>;
+export { VersionNotInstalledError } from '../lib/versions.js';

package/dist/commands/utils.js

@@ -7,6 +7,10 @@
 import * as os from 'os';
 import { spawnSync } from 'child_process';
 import chalk from 'chalk';
+import ora from 'ora';
+import { confirm } from '@inquirer/prompts';
+import { agentLabel, resolveAgentName } from '../lib/agents.js';
+import { installVersion, listInstalledVersions, resolveAgentVersionTargets, resolveInstalledAgentTargets, } from '../lib/versions.js';
 /**
  * Check if an error is from user cancelling a prompt (Ctrl+C)
  */
@@ -135,3 +139,138 @@ export function formatPath(fullPath, cwd) {
     }
     return fullPath;
 }
+/**
+ * Parse a --agents selector and collect every (agentId, specificVersion) pair
+ * the user requested where the version is a concrete x.y.z (not `default`,
+ * not `all`, not `latest`) and is NOT currently installed.
+ *
+ * This is the lookahead the auto-install wrappers use to decide whether to
+ * prompt + install before delegating to resolveAgentVersionTargets.
+ */
+function collectMissingVersions(value, availableAgents) {
+    const missing = [];
+    const seen = new Set();
+    for (const raw of value.split(',').map((s) => s.trim()).filter(Boolean)) {
+        // Literal `all` / `all@all` expand to per-agent — never missing.
+        if (raw === 'all' || raw === 'all@all')
+            continue;
+        const atIndex = raw.indexOf('@');
+        if (atIndex === -1)
+            continue; // bare agent → resolves to default; never missing in this sense
+        const agentToken = raw.slice(0, atIndex).trim();
+        const versionToken = raw.slice(atIndex + 1).trim();
+        // Non-specific selectors handled by the underlying resolver.
+        if (!versionToken || versionToken === 'default' || versionToken === 'all')
+            continue;
+        const agentId = resolveAgentName(agentToken);
+        if (!agentId || !availableAgents.includes(agentId))
+            continue;
+        const installed = listInstalledVersions(agentId);
+        if (installed.includes(versionToken))
+            continue;
+        const key = `${agentId}@${versionToken}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        missing.push({ agentId, version: versionToken });
+    }
+    return missing;
+}
+/**
+ * Sequentially install every requested missing version with a per-version
+ * spinner. Aborts via process.exit(1) on the first failure — the user
+ * already approved the install so a partial-install outcome is worse than
+ * a hard stop.
+ */
+async function installMissingVersions(missing) {
+    for (const { agentId, version } of missing) {
+        const label = `${agentLabel(agentId)}@${version}`;
+        const spinner = ora(`Installing ${label}...`).start();
+        try {
+            const result = await installVersion(agentId, version, (msg) => {
+                spinner.text = msg;
+            });
+            if (!result.success) {
+                spinner.fail(`Failed to install ${label}: ${result.error ?? 'unknown error'}`);
+                process.exit(1);
+            }
+            spinner.succeed(`Installed ${label}`);
+        }
+        catch (err) {
+            spinner.fail(`Failed to install ${label}: ${err.message}`);
+            process.exit(1);
+        }
+    }
+}
+/**
+ * Make sure every specific `agent@x.y.z` the user typed is installed before
+ * the caller resolves targets. Returns true if the caller should continue,
+ * false if the user declined the prompt. Exported so non-standard caller
+ * shapes (e.g. mcp.ts's manifest-shaped parser) can run the pre-flight
+ * without going through resolveAgentVersionTargets first.
+ */
+export async function ensureAgentVersionsInstalled(value, availableAgents, options = {}) {
+    const missing = collectMissingVersions(value, availableAgents);
+    if (missing.length === 0)
+        return true;
+    const summary = missing.map((m) => `${agentLabel(m.agentId)}@${m.version}`).join(', ');
+    if (!options.yes) {
+        if (!isInteractiveTerminal()) {
+            console.error(chalk.red(`Missing agent version(s): ${summary}`));
+            console.error(chalk.gray('In a scripted shell, opt in to auto-install:'));
+            console.error(chalk.cyan(`  rerun with --yes`));
+            console.error(chalk.gray('Or pre-install:'));
+            for (const m of missing) {
+                console.error(chalk.cyan(`  agents add ${m.agentId}@${m.version}`));
+            }
+            process.exit(1);
+        }
+        console.log(chalk.yellow(`\nThe following agent version(s) are not installed:`));
+        for (const m of missing) {
+            console.log(`  ${chalk.cyan(`${agentLabel(m.agentId)}@${m.version}`)}`);
+        }
+        let proceed;
+        try {
+            proceed = await confirm({
+                message: `Install ${missing.length} missing version${missing.length === 1 ? '' : 's'}?`,
+                default: true,
+            });
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return false;
+            throw err;
+        }
+        if (!proceed)
+            return false;
+    }
+    await installMissingVersions(missing);
+    return true;
+}
+/**
+ * Resolve a `--agents` selector and, if any requested `agent@version` isn't
+ * installed yet, prompt to install it (or auto-install with --yes) before
+ * delegating to resolveAgentVersionTargets. Returns null when the user
+ * declines the install prompt — callers should treat that as a clean cancel.
+ */
+export async function resolveAgentTargetsAutoInstalling(value, availableAgents, options = {}) {
+    const ok = await ensureAgentVersionsInstalled(value, availableAgents, options);
+    if (!ok)
+        return null;
+    return resolveAgentVersionTargets(value, availableAgents, { allVersions: options.allVersions });
+}
+/**
+ * Same as resolveAgentTargetsAutoInstalling but returns the broader
+ * InstalledAgentTargetResult that includes `directAgents` (for paths like
+ * `agents install` and `mcp register` that fall through to unmanaged homes
+ * when no managed version is installed).
+ */
+export async function resolveInstalledAgentTargetsAutoInstalling(value, availableAgents, options = {}) {
+    const ok = await ensureAgentVersionsInstalled(value, availableAgents, options);
+    if (!ok)
+        return null;
+    return resolveInstalledAgentTargets(value, availableAgents, { allVersions: options.allVersions });
+}
+// Re-export so callers can `catch (err) { if (err instanceof VersionNotInstalledError) … }`
+// without reaching into ../lib/versions directly.
+export { VersionNotInstalledError } from '../lib/versions.js';

package/dist/commands/versions.js

@@ -7,7 +7,7 @@ import { AGENTS, ALL_AGENT_IDS, getAccountEmail, getAccountInfo, agentLabel, } f
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
-import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
+import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
 import { createShim, createVersionedAlias, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 import { tryAutoPull } from '../lib/git.js';
@@ -255,7 +255,7 @@ export function registerVersionsCommands(program) {
             }
             const { agent, version } = parsed;
             const agentConfig = AGENTS[agent];
-            if (!agentConfig.npmPackage) {
+            if (!agentConfig.npmPackage && !agentConfig.installScript) {
                 console.log(chalk.yellow(`${agentLabel(agentConfig.id)} has no npm package. Install manually.`));
                 continue;
             }
@@ -293,7 +293,7 @@ export function registerVersionsCommands(program) {
                     // Smart resource detection: compare available vs ACTUALLY synced (source of truth: files)
                     const available = getAvailableResources();
                     const actuallySynced = getActuallySyncedResources(agent, installedVersion);
-                    const newResources = getNewResources(available, actuallySynced);
+                    const newResources = getNewResources(available, actuallySynced, getProjectOnlyResources());
                     const hasAnySynced = actuallySynced.commands.length > 0 ||
                         actuallySynced.skills.length > 0 ||
                         actuallySynced.hooks.length > 0 ||
@@ -577,7 +577,7 @@ export function registerVersionsCommands(program) {
                 // Smart resource detection: compare available vs ACTUALLY synced (source of truth: files, not tracking)
                 const available = getAvailableResources();
                 const actuallySynced = getActuallySyncedResources(agentId, finalVersion);
-                const newResources = getNewResources(available, actuallySynced);
+                const newResources = getNewResources(available, actuallySynced, getProjectOnlyResources());
                 // Check if anything is actually synced (source of truth: actual files)
                 const hasAnySynced = actuallySynced.commands.length > 0 ||
                     actuallySynced.skills.length > 0 ||

package/dist/commands/view.d.ts

@@ -8,6 +8,7 @@
  */
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
+import { type ProfileSummary } from '../lib/profiles.js';
 /** Machine-readable entry for a single installed version. */
 export interface ViewJsonVersion {
     version: string;
@@ -16,6 +17,10 @@ export interface ViewJsonVersion {
     email: string | null;
     plan: string | null;
     usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null;
+    overageCredits?: {
+        amount: number;
+        currency: string;
+    } | null;
     windows: Array<{
         key: 'session' | 'week' | 'sonnet_week';
         usedPercent: number;
@@ -28,6 +33,7 @@ export interface ViewJsonVersion {
 export interface ViewJsonAgent {
     agent: AgentId;
     versions: ViewJsonVersion[];
+    profiles: ProfileSummary[];
 }
 /**
  * Prune older installed versions that share an email with a newer installed

package/dist/commands/view.js

@@ -3,9 +3,9 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
-import { formatUsageSection, formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
+import { 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, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
 import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { WORKFLOW_CAPABLE_AGENTS } from '../lib/workflows.js';
@@ -16,8 +16,33 @@ import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
 import { getConfiguredRunStrategy } from '../lib/rotate.js';
+import { listProfiles, profileSummary } from '../lib/profiles.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/**
+ * Group profile summaries by their host harness, optionally filtered to a
+ * single agent. Profile YAMLs that fail validation are silently skipped by
+ * `listProfiles` so this never throws on a malformed file.
+ */
+function getProfilesByAgent(filterAgentId) {
+    const byAgent = new Map();
+    for (const profile of listProfiles()) {
+        if (filterAgentId && profile.host.agent !== filterAgentId)
+            continue;
+        const summary = profileSummary(profile);
+        const existing = byAgent.get(profile.host.agent);
+        if (existing)
+            existing.push(summary);
+        else
+            byAgent.set(profile.host.agent, [summary]);
+    }
+    return byAgent;
+}
+/** Build the usage-column equivalent for a profile row: "profile  <model>". */
+function profileKindAndModel(model, planWidth) {
+    const kind = 'profile'.padEnd(Math.max(planWidth, 'profile'.length));
+    return `${kind}  ${model}`;
+}
 function termLink(text, filePath) {
     const url = `file://${filePath}`;
     return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
@@ -88,6 +113,32 @@ function getProjectVersionFromCwd(agent) {
         return null;
     }
 }
+function getProfileSummaries(filterAgentId) {
+    return listProfiles()
+        .filter((profile) => !filterAgentId || profile.host.agent === filterAgentId)
+        .map(profileSummary);
+}
+function renderProfilesSection(profiles) {
+    if (profiles.length === 0)
+        return;
+    const nameWidth = Math.max(4, ...profiles.map((p) => p.name.length));
+    const hostWidth = Math.max(4, ...profiles.map((p) => p.host.length));
+    const providerWidth = Math.max(8, ...profiles.map((p) => p.provider.length));
+    console.log(chalk.bold('Profiles\n'));
+    console.log(`  ${chalk.gray('NAME'.padEnd(nameWidth))}  ` +
+        `${chalk.gray('HOST'.padEnd(hostWidth))}  ` +
+        `${chalk.gray('PROVIDER'.padEnd(providerWidth))}  ` +
+        chalk.gray('MODEL'));
+    for (const profile of profiles) {
+        console.log(`  ${chalk.cyan(profile.name.padEnd(nameWidth))}  ` +
+            `${profile.host.padEnd(hostWidth)}  ` +
+            `${profile.provider.padEnd(providerWidth)}  ` +
+            chalk.gray(profile.model));
+    }
+    console.log(chalk.gray('\n  Run: agents run <profile> [prompt]'));
+    console.log(chalk.gray('       agents profiles view <profile>'));
+    console.log();
+}
 /**
  * Show installed versions for one or all agents.
  * Called when: `agents view` or `agents view claude`
@@ -101,6 +152,8 @@ async function showInstalledVersions(filterAgentId) {
     spinner.stop();
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
     const showPaths = !!filterAgentId;
+    const profilesByAgent = getProfilesByAgent(filterAgentId);
+    const profileSummaries = [...profilesByAgent.values()].flat();
     // Auto-heal stale versioned aliases. Pre-v2 aliases (e.g. pre-CLAUDE_CONFIG_DIR
     // claude shims) silently route login through the default version's symlinked
     // home, so `agents view` would never reflect the right account. Regenerate on
@@ -190,15 +243,20 @@ async function showInstalledVersions(filterAgentId) {
     // Separate version-managed from globally-installed agents
     const versionManaged = [];
     const globallyInstalled = [];
+    const profileOnly = [];
     for (const agentId of agentsToShow) {
         const versions = listInstalledVersions(agentId);
         const cliState = cliStates[agentId];
+        const hasProfiles = (profilesByAgent.get(agentId)?.length ?? 0) > 0;
         if (versions.length > 0) {
             versionManaged.push(agentId);
         }
         else if (cliState?.installed) {
             globallyInstalled.push(agentId);
         }
+        else if (hasProfiles) {
+            profileOnly.push(agentId);
+        }
     }
     // Show version-managed agents
     if (versionManaged.length > 0) {
@@ -207,6 +265,7 @@ async function showInstalledVersions(filterAgentId) {
         let maxEmail = 0;
         let maxPlanWidth = 3;
         let maxUsageWidth = 0;
+        let maxStatusWidth = 0;
         for (const agentId of versionManaged) {
             const versions = listInstalledVersions(agentId);
             const globalDefault = getGlobalDefault(agentId);
@@ -220,8 +279,14 @@ async function showInstalledVersions(filterAgentId) {
                 if (info?.plan)
                     maxPlanWidth = Math.max(maxPlanWidth, info.plan.length);
             }
+            // Profile rows share these columns with version rows so they line up.
+            for (const profile of profilesByAgent.get(agentId) ?? []) {
+                maxVerLabel = Math.max(maxVerLabel, profile.name.length);
+                maxEmail = Math.max(maxEmail, profile.auth.length);
+                maxPlanWidth = Math.max(maxPlanWidth, 'profile'.length);
+            }
         }
-        // Second pass: compute max visible usage width (now that maxPlanWidth is settled)
+        // Second pass: compute max visible usage + status widths (now that maxPlanWidth is settled)
         for (const agentId of versionManaged) {
             const versions = listInstalledVersions(agentId);
             for (const v of versions) {
@@ -231,6 +296,12 @@ async function showInstalledVersions(filterAgentId) {
                 const usageInfo = usageKey ? usageByKey.get(usageKey) : undefined;
                 const usageStr = formatUsageSummary(info?.plan || null, usageInfo?.snapshot || null, maxPlanWidth);
                 maxUsageWidth = Math.max(maxUsageWidth, visibleWidth(usageStr));
+                const statusStr = formatUsageStatusBadge(info?.usageStatus);
+                maxStatusWidth = Math.max(maxStatusWidth, visibleWidth(statusStr));
+            }
+            for (const profile of profilesByAgent.get(agentId) ?? []) {
+                const usageEquivalent = profileKindAndModel(profile.model, maxPlanWidth);
+                maxUsageWidth = Math.max(maxUsageWidth, visibleWidth(usageEquivalent));
             }
         }
         for (const agentId of versionManaged) {
@@ -280,6 +351,11 @@ async function showInstalledVersions(filterAgentId) {
                         const usagePad = ' '.repeat(Math.max(0, maxUsageWidth - visibleWidth(usageStr)));
                         parts.push(usageStr + usagePad);
                     }
+                    const statusStr = formatUsageStatusBadge(vInfo?.usageStatus);
+                    if (maxStatusWidth > 0) {
+                        const statusPad = ' '.repeat(Math.max(0, maxStatusWidth - visibleWidth(statusStr)));
+                        parts.push(statusStr + statusPad);
+                    }
                     if (hasActive)
                         parts.push(activeStr);
                 }
@@ -289,6 +365,18 @@ async function showInstalledVersions(filterAgentId) {
                     console.log(chalk.gray(`      ${versionDir}`));
                 }
             }
+            // Profile rows share the same columns as versions: name | auth | "profile"+model.
+            // No status badge, no last-active — profiles don't accumulate usage state.
+            for (const profile of profilesByAgent.get(agentId) ?? []) {
+                const nameCol = chalk.cyan(profile.name.padEnd(maxVerLabel));
+                const authCol = chalk.gray(profile.auth.padEnd(maxEmail));
+                const usageEquivalent = profileKindAndModel(profile.model, maxPlanWidth);
+                const usagePad = ' '.repeat(Math.max(0, maxUsageWidth - visibleWidth(usageEquivalent)));
+                console.log(`    ${nameCol}  ${authCol}  ${chalk.gray(usageEquivalent + usagePad)}`);
+                if (showPaths) {
+                    console.log(chalk.gray(`      ${profile.path}`));
+                }
+            }
             // Check for project override
             const projectVersion = getProjectVersionFromCwd(agentId);
             if (projectVersion && projectVersion !== globalDefault) {
@@ -305,6 +393,19 @@ async function showInstalledVersions(filterAgentId) {
             const cliState = cliStates[agentId];
             return `${cliState?.version || 'installed'} (global)`.length;
         }));
+        // Pre-pass: max badge width so rows with `lastActive` line up whether or
+        // not THIS row carries a throttle badge. Without this, the row that DOES
+        // have "out of credits" shifts every other row's `lastActive` left by
+        // ~16 chars, exactly what the version-managed block at maxStatusWidth
+        // already solves above.
+        let gMaxStatusWidth = 0;
+        for (const agentId of globallyInstalled) {
+            const gInfoRaw = globalInfoMap.get(agentId);
+            const gInfo = gInfoRaw ? mergeCanonical(gInfoRaw) : undefined;
+            const w = visibleWidth(formatUsageStatusBadge(gInfo?.usageStatus));
+            if (w > gMaxStatusWidth)
+                gMaxStatusWidth = w;
+        }
         for (const agentId of globallyInstalled) {
             const agent = AGENTS[agentId];
             const cliState = cliStates[agentId];
@@ -323,25 +424,77 @@ async function showInstalledVersions(filterAgentId) {
                 parts.push(gInfo?.email ? chalk.cyan(gInfo.email) : '');
             if (gUsageStr || gActiveStr)
                 parts.push(gUsageStr);
+            const gStatusStr = formatUsageStatusBadge(gInfo?.usageStatus);
+            if (gMaxStatusWidth > 0) {
+                const statusPad = ' '.repeat(Math.max(0, gMaxStatusWidth - visibleWidth(gStatusStr)));
+                parts.push(gStatusStr + statusPad);
+            }
             if (gActiveStr)
                 parts.push(gActiveStr);
             console.log(parts.join('  '));
             if (showPaths && cliState?.path) {
                 console.log(chalk.gray(`      ${cliState.path}`));
             }
+            // Profile rows under a globally-installed harness. Use a simpler
+            // alignment here since this section doesn't share column state with
+            // the version-managed block.
+            const profilesHere = profilesByAgent.get(agentId) ?? [];
+            if (profilesHere.length > 0) {
+                const nameWidth = Math.max(globalMaxVerLabel, ...profilesHere.map((p) => p.name.length));
+                const authWidth = Math.max(...profilesHere.map((p) => p.auth.length));
+                for (const profile of profilesHere) {
+                    console.log(`    ${chalk.cyan(profile.name.padEnd(nameWidth))}  ` +
+                        `${chalk.gray(profile.auth.padEnd(authWidth))}  ` +
+                        `${chalk.gray('profile')}  ` +
+                        chalk.gray(profile.model));
+                    if (showPaths) {
+                        console.log(chalk.gray(`      ${profile.path}`));
+                    }
+                }
+            }
             if (agent.npmPackage && cliState?.version) {
                 console.log(chalk.gray(`    Manage: agents add ${agentId}@${cliState.version} -y`));
             }
             console.log();
         }
     }
+    // Agents with no install but with profiles defined — render under the same
+    // harness header so users find them where they look.
+    if (profileOnly.length > 0) {
+        if (versionManaged.length === 0 && globallyInstalled.length === 0) {
+            console.log(chalk.bold('Profile-only Agents\n'));
+        }
+        for (const agentId of profileOnly) {
+            const profilesHere = profilesByAgent.get(agentId) ?? [];
+            console.log(`  ${chalk.bold(agentLabel(agentId))}${chalk.yellow(' (profile only)')}`);
+            const nameWidth = Math.max(...profilesHere.map((p) => p.name.length));
+            const authWidth = Math.max(...profilesHere.map((p) => p.auth.length));
+            for (const profile of profilesHere) {
+                console.log(`    ${chalk.cyan(profile.name.padEnd(nameWidth))}  ` +
+                    `${chalk.gray(profile.auth.padEnd(authWidth))}  ` +
+                    `${chalk.gray('profile')}  ` +
+                    chalk.gray(profile.model));
+                if (showPaths) {
+                    console.log(chalk.gray(`      ${profile.path}`));
+                }
+            }
+            console.log();
+        }
+    }
     // If filtering to a specific agent and not found
-    if (filterAgentId && versionManaged.length === 0 && globallyInstalled.length === 0) {
+    if (filterAgentId &&
+        versionManaged.length === 0 &&
+        globallyInstalled.length === 0 &&
+        profileOnly.length === 0) {
         console.log(`  ${chalk.bold(agentLabel(filterAgentId))}: ${chalk.gray('not installed')}`);
         console.log();
     }
     // No agents installed at all
-    if (versionManaged.length === 0 && globallyInstalled.length === 0 && !filterAgentId) {
+    if (versionManaged.length === 0 &&
+        globallyInstalled.length === 0 &&
+        profileOnly.length === 0 &&
+        profileSummaries.length === 0 &&
+        !filterAgentId) {
         console.log(chalk.gray('  No agent CLIs installed.'));
         console.log(chalk.gray('  Run: agents add claude@latest'));
         console.log();
@@ -363,7 +516,8 @@ async function showInstalledVersions(filterAgentId) {
         if (defaultVersion) {
             const available = getAvailableResources();
             const synced = getActuallySyncedResources(filterAgentId, defaultVersion);
-            const newResources = getNewResources(available, synced);
+            const projectOnly = getProjectOnlyResources();
+            const newResources = getNewResources(available, synced, projectOnly);
             if (hasNewResources(newResources, filterAgentId, defaultVersion)) {
                 try {
                     const selection = await promptNewResourceSelection(filterAgentId, newResources, defaultVersion);
@@ -742,6 +896,7 @@ async function collectAgentsJson(filterAgentId) {
             email: info.email,
             plan: info.plan,
             usageStatus: info.usageStatus,
+            overageCredits: info.overageCredits,
             windows: snapshot
                 ? snapshot.windows.map((w) => ({
                     key: w.key,
@@ -758,6 +913,7 @@ async function collectAgentsJson(filterAgentId) {
         else
             byAgent.set(agentId, [entry]);
     }
+    const profilesByAgent = getProfilesByAgent(filterAgentId);
     const out = [];
     for (const agentId of agentsToShow) {
         const versions = byAgent.get(agentId) ?? [];
@@ -766,7 +922,7 @@ async function collectAgentsJson(filterAgentId) {
                 return a.isDefault ? -1 : 1;
             return compareVersions(b.version, a.version);
         });
-        out.push({ agent: agentId, versions });
+        out.push({ agent: agentId, versions, profiles: profilesByAgent.get(agentId) ?? [] });
     }
     return out;
 }
@@ -1009,7 +1165,7 @@ export async function viewAction(agentArg, options) {
         // --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);
-        console.log(JSON.stringify(data[0] ?? { agent: agentId, versions: [] }, null, 2));
+        console.log(JSON.stringify(data[0] ?? { agent: agentId, versions: [], profiles: [] }, null, 2));
         return;
     }
     if (requestedVersion) {

package/dist/commands/workflows.js

@@ -7,9 +7,9 @@ import { select, checkbox } from '@inquirer/prompts';
 import { resolveAgentName, agentLabel } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { WORKFLOW_CAPABLE_AGENTS, discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
-import { getVersionHomePath, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { getVersionHomePath, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/versions.js';
 import { recordVersionResources, getUserWorkflowsDir } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Register the `agents workflows` command tree (list, view, add, remove). */
 export function registerWorkflowsCommands(program) {
@@ -92,18 +92,25 @@ Examples:
     workflowsCmd
         .command('add [source]')
         .description('Install workflows from a source (GitHub, local) or pick from central storage')
-        .option('-a, --agents <list>', 'Targets: claude, claude@2.1.138')
+        .option('-a, --agents <list>', 'Targets: claude, claude@2.1.138, claude@all, all')
+        .option('--names <list>', 'Workflow names from the source (comma-separated)')
         .option('-y, --yes', 'Skip confirmation prompts')
         .addHelpText('after', `
 Examples:
   # Install from GitHub
   agents workflows add gh:user/workflows
 
+  # Pluck specific workflows from a multi-workflow repo
+  agents workflows add gh:user/workflows --names rdev,plan
+
   # Install a local workflow directory (must contain WORKFLOW.md)
   agents workflows add ./rdev
 
   # Install and sync to a specific version
   agents workflows add gh:user/workflows --agents claude@2.1.138
+
+  # Install across every installed Claude version
+  agents workflows add gh:user/workflows --agents claude@all
 `)
         .action(async (source, options) => {
         try {
@@ -156,11 +163,23 @@ Examples:
                     }
                     spinner.succeed('Using local path');
                 }
-                const discovered = discoverWorkflowsFromRepo(localPath);
+                let discovered = discoverWorkflowsFromRepo(localPath);
                 if (discovered.length === 0) {
                     console.log(chalk.yellow('No workflows found (looking for WORKFLOW.md files)'));
                     return;
                 }
+                // --names filter: pluck specific workflows from a multi-workflow source.
+                const requestedNames = parseCommaSeparatedList(options.names);
+                if (requestedNames.length > 0) {
+                    const discoveredNames = new Set(discovered.map((w) => w.name));
+                    const missing = requestedNames.filter((n) => !discoveredNames.has(n));
+                    if (missing.length > 0) {
+                        console.log(chalk.red(`\nWorkflow(s) not found in source: ${missing.join(', ')}`));
+                        console.log(chalk.gray(`Available: ${[...discoveredNames].join(', ')}`));
+                        process.exit(1);
+                    }
+                    discovered = discovered.filter((w) => requestedNames.includes(w.name));
+                }
                 console.log(chalk.bold(`\nFound ${discovered.length} workflow(s):`));
                 for (const w of discovered) {
                     console.log(`\n  ${chalk.cyan(w.name)}: ${w.frontmatter.description || 'no description'}`);
@@ -191,13 +210,17 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = resolveAgentVersionTargets(options.agents, WORKFLOW_CAPABLE_AGENTS);
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, WORKFLOW_CAPABLE_AGENTS, { yes: options.yes });
+                if (!result) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
             }
             else {
                 const result = await promptAgentVersionSelection(WORKFLOW_CAPABLE_AGENTS, {
-                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                    skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;