@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/commands/sessions.js

@@ -1,3 +1,12 @@
+/**
+ * Session discovery, search, and rendering commands.
+ *
+ * Implements `agents sessions` -- the unified interface for finding, browsing,
+ * and reading agent conversation transcripts across Claude, Codex, Gemini,
+ * and OpenCode. Supports interactive picker mode, text/path search, markdown
+ * and JSON rendering, role/turn filtering, artifact inspection, and session
+ * resume via agent-native CLI flags.
+ */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -5,19 +14,23 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import ora from 'ora';
 import { SESSION_AGENTS } from '../lib/session/types.js';
+import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
+import { getActiveSessions } from '../lib/session/active.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
-import { colorAgent } from '../lib/agents.js';
-import { resolveVersion } from '../lib/versions.js';
+import { colorAgent, resolveAgentName } from '../lib/agents.js';
+import { resolveVersion, resolveVersionAliasLoose } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker } from './sessions-picker.js';
+import { registerSessionsTailCommand } from './sessions-tail.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 const CLAUDE_RESUME_MATCH_WINDOW_MS = 10 * 60_000;
 const LOAD_VERBS = ['Loading', 'Scanning', 'Gathering', 'Indexing', 'Reading'];
 const FIND_VERBS = ['Finding', 'Searching', 'Locating', 'Matching'];
+/** Build a spinner-backed progress tracker that cycles through verbs while scanning sessions. */
 function createScanProgressTracker(verbs, suffix, spinner) {
     const counts = new Map();
     let verbIndex = 0;
@@ -73,7 +86,134 @@ function resolvePathFilter(query) {
         : query;
     return path.resolve(expanded);
 }
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function renderArtifactsForSession(session, listAll, name) {
+    const artifacts = discoverArtifacts(session);
+    if (name !== undefined) {
+        const artifact = resolveArtifact(artifacts, name);
+        if (!artifact) {
+            console.error(chalk.red(`No artifact matching "${name}" in session ${session.shortId}.`));
+            if (artifacts.length > 0) {
+                console.error(chalk.gray('Available artifacts:'));
+                for (const a of artifacts) {
+                    console.error(chalk.gray(`  ${a.path}`));
+                }
+            }
+            process.exit(1);
+        }
+        if (!artifact.exists) {
+            console.error(chalk.red(`Artifact exists in session history but the file is no longer on disk: ${artifact.path}`));
+            process.exit(1);
+        }
+        process.stdout.write(readArtifact(artifact));
+        return;
+    }
+    if (artifacts.length === 0) {
+        console.log(chalk.gray('No file-write artifacts found in this session.'));
+        return;
+    }
+    const agentColor = colorAgent(session.agent);
+    console.log('');
+    console.log(agentColor(session.agent) +
+        chalk.gray(` · ${session.shortId} · ${formatRelativeTime(session.timestamp)}`));
+    console.log(chalk.gray('─'.repeat(72)));
+    for (const a of artifacts) {
+        const exists = a.exists ? chalk.green('yes') : chalk.red('no');
+        const size = a.exists && a.sizeBytes !== undefined ? chalk.cyan(formatBytes(a.sizeBytes)) : chalk.gray('-');
+        const tool = chalk.yellow(padRight(a.tool, 10));
+        const when = chalk.gray(formatRelativeTime(a.timestamp));
+        const p = chalk.white(a.path);
+        console.log(`  ${exists}  ${size.padEnd(10)}  ${tool}  ${when.padEnd(16)}  ${p}`);
+    }
+    console.log(chalk.gray(`\n${artifacts.length} artifact${artifacts.length !== 1 ? 's' : ''}.`));
+}
+function statusColor(status) {
+    switch (status) {
+        case 'running': return chalk.green;
+        case 'idle': return chalk.gray;
+        case 'queued': return chalk.blue;
+        case 'input_required': return chalk.yellow;
+    }
+}
+function contextColor(context) {
+    switch (context) {
+        case 'terminal': return chalk.magenta;
+        case 'teams': return chalk.cyan;
+        case 'cloud': return chalk.blue;
+        case 'headless': return chalk.gray;
+    }
+}
+function shortCwd(cwd) {
+    if (!cwd)
+        return '-';
+    const home = os.homedir();
+    return cwd.startsWith(home) ? '~' + cwd.slice(home.length) : cwd;
+}
+function formatStartedAt(startedAtMs) {
+    if (!startedAtMs)
+        return '-';
+    return formatRelativeTime(new Date(startedAtMs).toISOString());
+}
+/** Render the unified active-session view. */
+async function renderActiveSessions(asJson) {
+    const sessions = await getActiveSessions();
+    if (asJson) {
+        process.stdout.write(JSON.stringify(sessions, null, 2) + '\n');
+        return;
+    }
+    if (sessions.length === 0) {
+        console.log(chalk.gray('No active agent sessions.'));
+        return;
+    }
+    for (const s of sessions) {
+        const kindCol = colorAgent(s.kind)(padRight(truncate(s.kind, 8), 9));
+        const ctxCol = contextColor(s.context)(padRight(truncate(s.context, 8), 9));
+        const hostCol = chalk.gray(padRight(truncate(s.host ?? '-', 8), 9));
+        const statusCol = statusColor(s.status)(padRight(truncate(s.status, 8), 9));
+        const pidCol = chalk.yellow(padRight(s.pid ? String(s.pid) : '-', 7));
+        const idCol = chalk.white(padRight(s.sessionId ? s.sessionId.slice(0, 8) : '-', 10));
+        const detail = s.context === 'cloud'
+            ? `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`
+            : s.context === 'teams'
+                ? `${s.teamName ?? ''}${s.label ? ` · ${s.label}` : ''}`
+                : s.label ?? shortCwd(s.cwd);
+        console.log(pidCol +
+            kindCol +
+            ctxCol +
+            hostCol +
+            statusCol +
+            idCol +
+            chalk.cyan(padRight(truncate(detail || '-', 30), 32)) +
+            chalk.gray(formatStartedAt(s.startedAtMs)));
+    }
+    const runningCount = sessions.filter(s => s.status === 'running').length;
+    const idleCount = sessions.filter(s => s.status === 'idle').length;
+    const queuedCount = sessions.filter(s => s.status === 'queued' || s.status === 'input_required').length;
+    const parts = [];
+    if (runningCount > 0)
+        parts.push(`${runningCount} running`);
+    if (idleCount > 0)
+        parts.push(`${idleCount} idle`);
+    if (queuedCount > 0)
+        parts.push(`${queuedCount} queued`);
+    console.log(chalk.gray(`\n${sessions.length} active (${parts.join(', ')}).`));
+}
+/** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
+    if (options.active) {
+        await renderActiveSessions(options.json === true);
+        return;
+    }
+    if (options.cloud) {
+        await runCloudSessions(query, options);
+        return;
+    }
     let filterOpts;
     try {
         filterOpts = buildFilterOptions(options);
@@ -98,9 +238,19 @@ async function sessionsAction(query, options) {
     else {
         searchQuery = query;
     }
+    // Artifact flags require a session query.
+    if ((options.artifacts || options.artifact !== undefined) && !query) {
+        console.error(chalk.red('--artifacts and --artifact require a session ID or query.'));
+        process.exit(1);
+    }
     const mode = resolveViewMode(options, filterOpts);
     // --markdown or any filter flag forces single-session render.
     const wantsRender = mode === 'markdown' || hasAnyFilter(filterOpts);
+    // Artifact-list or artifact-read paths: widen scope and resolve session globally.
+    if ((options.artifacts || options.artifact !== undefined) && searchQuery) {
+        await renderArtifactsGlobal(searchQuery, options.artifacts ?? false, options.artifact, { agent: options.agent, project: options.project });
+        return;
+    }
     // When the user explicitly asks to render (via mode flag), resolve the
     // query globally so sessions outside the default cwd/30d window are found.
     if (wantsRender && searchQuery) {
@@ -473,9 +623,82 @@ export function buildResumeCommand(session, activeVersion) {
             return ['opencode', '--session', session.id];
         case 'gemini':
         case 'openclaw':
+        case 'rush':
+        case 'hermes':
+            // Rush and Hermes sessions are captured artifacts, not resumable locally.
             return null;
     }
 }
+// ---------------------------------------------------------------------------
+// Cloud session source (--cloud)
+// ---------------------------------------------------------------------------
+/**
+ * Handle `agents sessions --cloud [id] [filters]`.
+ * - Without id: list captured cloud-runs, optionally as JSON.
+ * - With id: fetch the jsonl, parse with the recorded format, render via
+ *   the same pipeline as local sessions (summary / markdown / json).
+ */
+async function runCloudSessions(query, options) {
+    const { discoverCloudSessions, ensureCloudSessionCached } = await import('../lib/session/cloud.js');
+    let filterOpts;
+    try {
+        filterOpts = buildFilterOptions(options);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+    const mode = resolveViewMode(options, filterOpts);
+    const spinner = options.json ? null : ora('Loading cloud sessions...').start();
+    let sessions;
+    try {
+        sessions = await discoverCloudSessions({ limit: parseInt(options.limit || '50', 10) });
+    }
+    catch (err) {
+        spinner?.stop();
+        console.error(chalk.red(`Failed to list cloud sessions: ${err?.message || err}`));
+        process.exit(1);
+    }
+    spinner?.stop();
+    if (!query) {
+        if (options.json) {
+            process.stdout.write(JSON.stringify(sessions, null, 2) + '\n');
+            return;
+        }
+        if (sessions.length === 0) {
+            console.log(chalk.gray('No cloud sessions captured yet.'));
+            return;
+        }
+        printSessionTable(sessions);
+        return;
+    }
+    const matches = sessions.filter((s) => s.id === query || s.shortId === query || s.id.startsWith(query));
+    if (matches.length === 0) {
+        console.error(chalk.red(`No cloud session matching: ${query}`));
+        process.exit(1);
+    }
+    if (matches.length > 1) {
+        console.error(chalk.red(`Multiple cloud sessions match "${query}":`));
+        for (const m of matches.slice(0, 10)) {
+            console.error(chalk.cyan(`  ${m.shortId}  ${m.id}`));
+        }
+        process.exit(1);
+    }
+    const meta = matches[0];
+    const cachedSpinner = options.json ? null : ora('Fetching session...').start();
+    let cachedPath;
+    try {
+        cachedPath = await ensureCloudSessionCached(meta.id, meta.filePath);
+    }
+    catch (err) {
+        cachedSpinner?.stop();
+        console.error(chalk.red(`Failed to fetch session: ${err?.message || err}`));
+        process.exit(1);
+    }
+    cachedSpinner?.stop();
+    // Ensure the SessionMeta points at the local cache path for renderSession.
+    await renderSession({ ...meta, filePath: cachedPath }, mode, filterOpts);
+}
 function parseAgentFilter(agentName) {
     if (!agentName)
         return {};
@@ -497,6 +720,7 @@ function formatSearchMessage(options) {
         return 'Search sessions:';
     return `Search sessions (${filters.join(', ')}):`;
 }
+/** Filter and rank sessions by a multi-term search query across metadata and content. */
 export function filterSessionsByQuery(sessions, query) {
     const trimmed = query?.trim().toLowerCase() || '';
     if (!trimmed)
@@ -600,8 +824,10 @@ function applyScopeFilters(sessions, scope) {
         });
     }
     if (scope.agent) {
-        // Accept "claude" or "claude@2.1.112". Version suffix narrows further.
-        const [wantAgent, wantVersion] = scope.agent.split('@');
+        // Accept "claude" or "claude@2.1.112" / "claude@default" / "claude@latest". Version suffix narrows further.
+        const [wantAgent, rawVersion] = scope.agent.split('@');
+        const resolvedAgent = resolveAgentName(wantAgent);
+        const wantVersion = resolvedAgent ? resolveVersionAliasLoose(resolvedAgent, rawVersion) : rawVersion;
         filtered = filtered.filter((s) => {
             if (s.agent !== wantAgent)
                 return false;
@@ -612,6 +838,46 @@ function applyScopeFilters(sessions, scope) {
     }
     return filtered;
 }
+async function renderArtifactsGlobal(query, listAll, name, scope) {
+    const spinner = ora().start();
+    const tracker = createScanProgressTracker(FIND_VERBS, 'session', spinner);
+    try {
+        const discovered = await discoverSessions({
+            all: true,
+            cwd: process.cwd(),
+            limit: 5000,
+            onProgress: tracker.onProgress,
+        });
+        tracker.stop();
+        const allSessions = applyScopeFilters(discovered, scope);
+        const matches = resolveSessionById(allSessions, query);
+        const queryMatches = matches.length > 0 ? matches : filterSessionsByQuery(allSessions, query);
+        if (queryMatches.length === 0) {
+            spinner.stop();
+            console.error(chalk.red(`No session found matching: ${query}`));
+            process.exit(1);
+        }
+        if (queryMatches.length > 1) {
+            spinner.stop();
+            console.error(chalk.red(`Multiple sessions match "${query}":`));
+            for (const m of queryMatches.slice(0, 10)) {
+                console.error(chalk.cyan(`  ${m.shortId}  ${m.id}  ${m.label ?? m.topic ?? ''}`));
+            }
+            console.error(chalk.gray('Pass a longer ID to narrow it down.'));
+            process.exit(1);
+        }
+        spinner.stop();
+        await renderArtifactsForSession(queryMatches[0], listAll, name);
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return;
+        tracker.stop();
+        spinner.stop();
+        console.error(chalk.red(`Failed to read session: ${err.message}`));
+        process.exit(1);
+    }
+}
 async function renderOneSession(query, mode, scope) {
     const spinner = ora().start();
     const tracker = createScanProgressTracker(FIND_VERBS, 'session', spinner);
@@ -688,8 +954,9 @@ async function renderOneSession(query, mode, scope) {
         process.exit(1);
     }
 }
+/** Register the `agents sessions` command with all its options and help text. */
 export function registerSessionsCommands(program) {
-    program
+    const sessionsCmd = program
         .command('sessions')
         .argument('[query]', 'Session ID, search query, or path (., ../, /path) to filter by project')
         .description('Find, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode.')
@@ -706,6 +973,10 @@ export function registerSessionsCommands(program) {
         .option('--exclude <roles>', 'Exclude these roles (comma-separated): user, assistant, thinking, tools')
         .option('--first <n>', 'Keep only the first N turns (a turn starts at each user message)')
         .option('--last <n>', 'Keep only the last N turns (a turn starts at each user message)')
+        .option('--artifacts', 'List all files written or edited during a session')
+        .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
+        .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
+        .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
         .addHelpText('after', `
 Examples:
   # Interactive picker: browse and search recent sessions (TTY only)
@@ -724,7 +995,7 @@ Examples:
   agents sessions --agent claude --since 7d
 
   # Filter sessions in a specific directory
-  agents sessions /Users/muqsit/src/my-project
+  agents sessions ~/src/my-project
 
   # Default summary view for one session
   agents sessions a1b2c3d4
@@ -753,6 +1024,16 @@ Examples:
   # Include team-spawned sessions in results
   agents sessions --teams
 
+  # Show only live sessions across terminals, teams, cloud, and headless agents
+  agents sessions --active
+  agents sessions --active --json
+
+  # List captured cloud-run sessions (claude/codex/rush) via Rush Cloud
+  agents sessions --cloud
+  agents sessions --cloud <execution_id>
+  agents sessions --cloud <execution_id> --markdown
+  agents sessions --cloud <execution_id> --include user,assistant --last 3
+
 Notes:
   - --include and --exclude are mutually exclusive.
   - --first and --last are mutually exclusive.
@@ -761,6 +1042,7 @@ Notes:
         .action(async (query, options) => {
         await sessionsAction(query, options);
     });
+    registerSessionsTailCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();
@@ -974,4 +1256,3 @@ function formatRelativeTime(isoTimestamp) {
     const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
     return `${months[d.getMonth()]} ${d.getDate()}`;
 }
-//# sourceMappingURL=sessions.js.map

package/dist/commands/skills.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Skill management commands for adding domain-specific capabilities to agents.
+ *
+ * Implements `agents skills` -- list, add, remove, sync, prune, and view
+ * packaged SKILL.md bundles (with optional rules/ directories). Central
+ * storage lives in ~/.agents/skills/ and skills are synced to individual
+ * version homes via copy or symlink.
+ */
 import type { Command } from 'commander';
+/** Register the `agents skills` command tree (list, add, remove, sync, prune, view). */
 export declare function registerSkillsCommands(program: Command): void;
-//# sourceMappingURL=skills.d.ts.map

package/dist/commands/skills.js

@@ -3,14 +3,15 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { select, checkbox, confirm } from '@inquirer/prompts';
+import { select, checkbox } from '@inquirer/prompts';
 import { SKILLS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
-import { discoverSkillsFromRepo, installSkillCentrally, uninstallSkill, listInstalledSkills, listInstalledSkillsWithScope, getSkillInfo, getSkillRules, getSkillsDir, countSkillFiles, tryParseSkillMetadata, diffVersionSkills, installSkillToVersion, removeSkillFromVersion, iterSkillsCapableVersions, } from '../lib/skills.js';
-import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { discoverSkillsFromRepo, installSkillCentrally, uninstallSkill, listInstalledSkills, listInstalledSkillsWithScope, getSkillInfo, getSkillRules, getSkillsDir, countSkillFiles, tryParseSkillMetadata, diffVersionSkills, iterSkillsCapableVersions, } from '../lib/skills.js';
+import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
+/** Register the `agents skills` command tree (list, add, remove, sync, prune, view). */
 export function registerSkillsCommands(program) {
     const skillsCmd = program
         .command('skills')
@@ -57,7 +58,7 @@ When to use:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = parts[1] || undefined;
+            filterVersion = resolveVersionAlias(resolved, parts[1]);
         }
         const rows = await buildSkillRows({ filterAgent, filterVersion });
         spinner.stop();
@@ -344,181 +345,26 @@ Examples:
             }
         }
     });
+    // `skills sync` is gone — sync runs automatically when the agent launches.
     skillsCmd
-        .command('sync')
-        .description('Reconcile version-home skills against central ~/.agents/skills/ (add + update, never delete)')
-        .option('-a, --agent <agent>', 'Scope to a specific agent or agent@version')
-        .option('-m, --method <method>', 'Install method: copy (default) or symlink', 'copy')
-        .addHelpText('after', `
-Examples:
-  # Sync every installed version of every skills-capable agent
-  agents skills sync
-
-  # Scope to one agent
-  agents skills sync --agent claude
-
-  # Scope to one version
-  agents skills sync --agent claude@2.1.113
-
-  # Symlink into version homes (central updates propagate automatically)
-  agents skills sync --method symlink
-
-Sync is additive: it installs missing skills and refreshes changed ones. To
-remove orphans (skills in a version home but not in central), use 'agents
-skills prune'.
-`)
-        .action(async (options) => {
-        const method = (options.method === 'symlink' ? 'symlink' : 'copy');
-        let filter;
-        if (options.agent) {
-            const [name, version] = String(options.agent).split('@');
-            const agentId = resolveAgentName(name);
-            if (!agentId) {
-                console.log(chalk.red(formatAgentError(name, SKILLS_CAPABLE_AGENTS)));
-                process.exit(1);
-            }
-            filter = { agent: agentId, version: version || undefined };
-        }
-        const pairs = iterSkillsCapableVersions(filter);
-        if (pairs.length === 0) {
-            console.log(chalk.gray('No matching installed versions.'));
-            return;
-        }
-        const diffs = pairs.map(({ agent, version }) => diffVersionSkills(agent, version));
-        const plan = diffs.filter((d) => d.toAdd.length > 0 || d.toUpdate.length > 0);
-        if (plan.length === 0) {
-            console.log(chalk.green('All version homes are up to date with central.'));
-            if (diffs.some((d) => d.orphans.length > 0)) {
-                console.log(chalk.gray('Orphan skills present. Run \'agents skills prune --dry-run\' to review.'));
-            }
-            return;
-        }
-        console.log(chalk.bold(`Syncing skills (method: ${method})\n`));
-        let adds = 0, updates = 0, failures = 0;
-        for (const diff of plan) {
-            const label = `${diff.agent}@${diff.version}`;
-            if (diff.toAdd.length > 0) {
-                console.log(`  ${chalk.cyan(label)} ${chalk.gray('add:')} ${diff.toAdd.join(', ')}`);
-                for (const name of diff.toAdd) {
-                    const r = installSkillToVersion(diff.agent, diff.version, name, method);
-                    if (r.success)
-                        adds++;
-                    else {
-                        failures++;
-                        console.log(chalk.red(`    ! ${name}: ${r.error}`));
-                    }
-                }
-            }
-            if (diff.toUpdate.length > 0) {
-                console.log(`  ${chalk.cyan(label)} ${chalk.gray('update:')} ${diff.toUpdate.join(', ')}`);
-                for (const name of diff.toUpdate) {
-                    const r = installSkillToVersion(diff.agent, diff.version, name, method);
-                    if (r.success)
-                        updates++;
-                    else {
-                        failures++;
-                        console.log(chalk.red(`    ! ${name}: ${r.error}`));
-                    }
-                }
-            }
-        }
-        console.log();
-        console.log(chalk.green(`Synced: ${adds} added, ${updates} updated${failures > 0 ? chalk.red(`, ${failures} failed`) : ''}.`));
-        const totalOrphans = diffs.reduce((n, d) => n + d.orphans.length, 0);
-        if (totalOrphans > 0) {
-            console.log(chalk.gray(`${totalOrphans} orphan(s) remain. Run 'agents skills prune --dry-run' to review.`));
-        }
+        .command('sync', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(chalk.red('"agents skills sync" is gone.'));
+        console.error(chalk.gray('Sync runs automatically when you launch the agent.'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune skills'));
+        process.exit(1);
     });
+    // `skills prune` moved to the top-level `agents prune` command.
     skillsCmd
-        .command('prune')
-        .description('Remove orphan skills from version homes (skills present locally but not in central)')
-        .option('-a, --agent <agent>', 'Scope to a specific agent or agent@version')
-        .option('--dry-run', 'Show orphans without deleting')
-        .option('-y, --yes', 'Skip confirmation prompt')
-        .addHelpText('after', `
-Examples:
-  # See what would be pruned
-  agents skills prune --dry-run
-
-  # Prune across every installed version (prompts for confirmation)
-  agents skills prune
-
-  # Scope to one agent or version
-  agents skills prune --agent claude@2.0.65
-
-  # Skip confirmation (for scripts)
-  agents skills prune -y
-
-Orphans are skills that exist inside a version home but are missing from the
-central ~/.agents/skills/ source of truth. Usually they are leftovers from a
-skill that was deleted centrally but never removed from the version install.
-`)
-        .action(async (options) => {
-        let filter;
-        if (options.agent) {
-            const [name, version] = String(options.agent).split('@');
-            const agentId = resolveAgentName(name);
-            if (!agentId) {
-                console.log(chalk.red(formatAgentError(name, SKILLS_CAPABLE_AGENTS)));
-                process.exit(1);
-            }
-            filter = { agent: agentId, version: version || undefined };
-        }
-        const pairs = iterSkillsCapableVersions(filter);
-        const diffs = pairs
-            .map(({ agent, version }) => diffVersionSkills(agent, version))
-            .filter((d) => d.orphans.length > 0);
-        if (diffs.length === 0) {
-            console.log(chalk.green('No orphan skills.'));
-            return;
-        }
-        const total = diffs.reduce((n, d) => n + d.orphans.length, 0);
-        console.log(chalk.bold(`Orphans (in version home, not in central)\n`));
-        for (const d of diffs) {
-            console.log(`  ${chalk.cyan(`${d.agent}@${d.version}`)}  ${d.orphans.join(', ')}`);
-        }
-        console.log();
-        if (options.dryRun) {
-            console.log(chalk.gray(`${total} orphan(s). Run without --dry-run to delete.`));
-            return;
-        }
-        if (!options.yes) {
-            if (!isInteractiveTerminal()) {
-                console.log(chalk.yellow('Non-interactive shell: pass -y to confirm, or --dry-run to preview.'));
-                process.exit(1);
-            }
-            let ok = false;
-            try {
-                ok = await confirm({
-                    message: `Delete ${total} orphan skill director${total === 1 ? 'y' : 'ies'}?`,
-                    default: false,
-                });
-            }
-            catch (err) {
-                if (isPromptCancelled(err)) {
-                    console.log(chalk.gray('Cancelled'));
-                    return;
-                }
-                throw err;
-            }
-            if (!ok) {
-                console.log(chalk.gray('Cancelled'));
-                return;
-            }
-        }
-        let removed = 0, failures = 0;
-        for (const d of diffs) {
-            for (const name of d.orphans) {
-                const r = removeSkillFromVersion(d.agent, d.version, name);
-                if (r.success)
-                    removed++;
-                else {
-                    failures++;
-                    console.log(chalk.red(`  ! ${d.agent}@${d.version} ${name}: ${r.error}`));
-                }
-            }
-        }
-        console.log(chalk.green(`Pruned ${removed} orphan(s)${failures > 0 ? chalk.red(`, ${failures} failed`) : ''}.`));
+        .command('prune', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(chalk.red('"agents skills prune" moved.'));
+        console.error(chalk.gray('Use:  agents prune skills   (or `agents prune` for everything)'));
+        process.exit(1);
     });
     skillsCmd
         .command('view [name]')
@@ -664,9 +510,14 @@ async function buildSkillRows(opts) {
             });
         }
         const fileCount = countSkillFiles(skill.path);
+        // Append repo source when a skill comes from a registered extra so users
+        // can see which DotAgent repo owns it at a glance.
+        const description = skill.source
+            ? `${skill.metadata.description || ''}${skill.metadata.description ? ' ' : ''}${chalk.gray(`[${skill.source}]`)}`
+            : skill.metadata.description;
         rows.push({
             name,
-            description: skill.metadata.description,
+            description,
             extra: fileCount > 0 ? `${fileCount}` : '-',
             targets,
             buildDetail: () => formatSkillDetail(name, skill, targets, fileCount),
@@ -713,4 +564,3 @@ function formatSkillDetail(name, skill, targets, fileCount) {
     lines.push(buildTargetsSection(targets));
     return lines.join('\n');
 }
-//# sourceMappingURL=skills.js.map

package/dist/commands/status.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Deprecated status command.
+ *
+ * Registers the `agents status` command as a backward-compatible alias
+ * for `agents view`. Prints a deprecation notice and delegates to viewAction.
+ */
 import type { Command } from 'commander';
+/** Register the deprecated `agents status` command (alias for `agents view`). */
 export declare function registerStatusCommand(program: Command): void;
-//# sourceMappingURL=status.d.ts.map