@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/commands/inspect.d.ts

@@ -18,6 +18,8 @@ import { type PluginResourceGroup } from '../lib/plugins.js';
 /** Resource kinds the inspect command can drill into. */
 declare const DRILLABLE_KINDS: readonly ["commands", "skills", "hooks", "mcp", "rules", "plugins", "workflows", "subagents"];
 type DrillableKind = typeof DRILLABLE_KINDS[number];
+/** Wrap a separator-joined value list under `prefix`, preserving a hanging indent. */
+export declare function wrapJoined(prefix: string, items: string[], sep: string, width: number): string[];
 interface ResourceItem {
     name: string;
     source: string;

package/dist/commands/inspect.js

@@ -11,7 +11,7 @@
  * names render as OSC-8 hyperlinks to the marker file (SKILL.md / WORKFLOW.md /
  * AGENT.md / the file itself) so users can click straight to the source.
  */
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { addHostOption } from '../lib/hosts/option.js';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -31,6 +31,7 @@ import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups } from '../
 import { PLUGIN_GROUP_COLORS } from './plugins.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
 import { damerauLevenshtein } from '../lib/fuzzy.js';
+import { terminalWidth, truncateToWidth, stringWidth, stripAnsi } from '../lib/session/width.js';
 /** Resource kinds the inspect command can drill into. */
 const DRILLABLE_KINDS = [
     'commands',
@@ -68,6 +69,44 @@ const SINGULAR_DRILL_ALIASES = {
 const CAPABILITY_NAMES = [
     'hooks', 'mcp', 'skills', 'commands', 'subagents', 'plugins', 'workflows', 'rules', 'allowlist',
 ];
+/** Wrap a separator-joined value list under `prefix`, preserving a hanging indent. */
+export function wrapJoined(prefix, items, sep, width) {
+    if (items.length === 0)
+        return [];
+    const continuation = ' '.repeat(stringWidth(prefix));
+    const fitItem = (item, linePrefix) => {
+        const room = Math.max(1, width - stringWidth(linePrefix));
+        return stringWidth(item) > room ? truncateToWidth(item, room) : item;
+    };
+    const lines = [];
+    let linePrefix = prefix;
+    let line = prefix;
+    let hasItem = false;
+    for (const raw of items) {
+        const item = fitItem(raw, linePrefix);
+        const candidate = hasItem ? `${line}${sep}${item}` : `${line}${item}`;
+        if (hasItem && stringWidth(candidate) > width) {
+            lines.push(line);
+            linePrefix = continuation;
+            line = continuation + fitItem(raw, linePrefix);
+            hasItem = true;
+        }
+        else {
+            line = candidate;
+            hasItem = true;
+        }
+    }
+    if (hasItem)
+        lines.push(line);
+    return lines;
+}
+function printWrappedJoined(prefix, items, sep) {
+    for (const line of wrapJoined(prefix, items, sep, terminalWidth()))
+        console.log(line);
+}
+function truncateValueForPrefix(prefix, value) {
+    return truncateToWidth(stripAnsi(value), Math.max(1, terminalWidth() - stringWidth(prefix)));
+}
 // ─── Command registration ────────────────────────────────────────────────────
 export function registerInspectCommand(program) {
     const cmd = addHostOption(program.command('inspect <target>'))
@@ -425,7 +464,10 @@ function renderRepoSummary(repo, options) {
         console.log(`  ${'git'.padEnd(10)} ${git.branch}${dirty}${url}`);
         if (git.lastCommit) {
             const rel = git.lastCommit.relative ? `  ${chalk.gray(`(${git.lastCommit.relative})`)}` : '';
-            sub('last', `${chalk.cyan(git.lastCommit.sha)}  ${truncate(git.lastCommit.subject, 60)}${rel}`);
+            const prefix = `  ${''.padEnd(10)} ${chalk.gray('last'.padEnd(8))} `;
+            const sha = chalk.cyan(git.lastCommit.sha);
+            const subjectWidth = Math.max(8, terminalWidth() - stringWidth(prefix) - stringWidth(sha) - 2 - stringWidth(rel));
+            console.log(`${prefix}${sha}  ${truncateToWidth(git.lastCommit.subject, subjectWidth)}${rel}`);
         }
         if (git.ahead !== null && git.behind !== null && (git.ahead > 0 || git.behind > 0)) {
             sub('sync', `ahead ${git.ahead} ${chalk.gray('·')} behind ${git.behind}`);
@@ -440,10 +482,12 @@ function renderRepoSummary(repo, options) {
         console.log(`  ${'manifests'.padEnd(10)} ${manifests.join(', ')}`);
         if (manifest) {
             if (manifest.versions.length > 0) {
-                sub('versions', manifest.versions.map(v => `${v.agent} ${chalk.cyan(v.version)}`).join(chalk.gray(' · ')));
+                const prefix = `  ${''.padEnd(10)} ${chalk.gray('versions'.padEnd(8))} `;
+                printWrappedJoined(prefix, manifest.versions.map(v => `${v.agent} ${chalk.cyan(v.version)}`), chalk.gray(' · '));
             }
             if (manifest.strategies.length > 0) {
-                sub('run', manifest.strategies.map(s => `${s.agent}:${s.strategy}`).join(chalk.gray(' · ')));
+                const prefix = `  ${''.padEnd(10)} ${chalk.gray('run'.padEnd(8))} `;
+                printWrappedJoined(prefix, manifest.strategies.map(s => `${s.agent}:${s.strategy}`), chalk.gray(' · '));
             }
         }
     }
@@ -468,35 +512,34 @@ function renderRepoSummary(repo, options) {
 export function repoGitInfo(root) {
     const git = (args) => {
         try {
-            return execSync(`git -C ${JSON.stringify(root)} ${args}`, { stdio: ['ignore', 'pipe', 'ignore'] })
-                .toString().trim();
+            return execFileSync('git', ['-C', root, ...args], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim();
         }
         catch {
             return null;
         }
     };
-    const branch = git('rev-parse --abbrev-ref HEAD');
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD']);
     if (branch === null)
         return null;
-    // Read status WITHOUT trimming — git()'s .trim() would strip the leading
+    // Read status WITHOUT trimming — trimming would strip the leading
     // space of the first porcelain line (`XY path`), corrupting the path slice.
     let statusRaw;
     try {
-        statusRaw = execSync(`git -C ${JSON.stringify(root)} status --porcelain`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+        statusRaw = execFileSync('git', ['-C', root, 'status', '--porcelain'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' });
     }
     catch {
         statusRaw = null;
     }
     const dirtyFiles = statusRaw ? statusRaw.split('\n').filter(Boolean).map(l => l.slice(3)) : [];
     let lastCommit = null;
-    const log = git('log -1 --format=%h%x1f%s%x1f%cr');
+    const log = git(['log', '-1', '--format=%h%x1f%s%x1f%cr']);
     if (log) {
         const [sha, subject, relative] = log.split('\x1f');
         if (sha)
             lastCommit = { sha, subject: subject ?? '', relative: relative ?? '' };
     }
     let ahead = null, behind = null;
-    const counts = git("rev-list --left-right --count '@{upstream}...HEAD'");
+    const counts = git(['rev-list', '--left-right', '--count', '@{upstream}...HEAD']);
     if (counts) {
         const [b, a] = counts.split(/\s+/).map(n => parseInt(n, 10));
         if (Number.isFinite(b) && Number.isFinite(a)) {
@@ -504,7 +547,7 @@ export function repoGitInfo(root) {
             ahead = a;
         }
     }
-    return { branch, dirty: dirtyFiles.length, dirtyFiles, url: git('remote get-url origin'), lastCommit, ahead, behind };
+    return { branch, dirty: dirtyFiles.length, dirtyFiles, url: git(['remote', 'get-url', 'origin']), lastCommit, ahead, behind };
 }
 // ─── Summary mode ────────────────────────────────────────────────────────────
 async function renderSummary(agent, version, versionHome, options) {
@@ -551,8 +594,10 @@ async function renderSummary(agent, version, versionHome, options) {
         ['alias', aliasPath],
         ['strategy', strategy],
     ];
-    for (const [k, v] of rows)
-        console.log(`  ${k.padEnd(10)} ${v}`);
+    for (const [k, v] of rows) {
+        const prefix = `  ${k.padEnd(10)} `;
+        console.log(prefix + truncateValueForPrefix(prefix, v));
+    }
     console.log('\n' + chalk.bold('Capabilities'));
     for (const cap of CAPABILITY_NAMES) {
         const res = capabilities[cap];
@@ -603,7 +648,8 @@ function renderItemList(header, jsonHead, kind, items, options) {
         const tag = chalk.gray(`[${item.source}]`.padEnd(10));
         console.log(`  ${tag} ${termLink(chalk.cyan(item.name), item.linkTarget)}`);
         if (item.description) {
-            console.log(`             ${chalk.gray(truncate(item.description, 90))}`);
+            const prefix = '             ';
+            console.log(prefix + chalk.gray(truncateToWidth(item.description, Math.max(1, terminalWidth() - stringWidth(prefix)))));
         }
         if (item.groups)
             printGroupRows(item.groups);
@@ -1171,7 +1217,7 @@ function readFirstProseLine(p) {
 }
 // ─── OSC-8 + path helpers ────────────────────────────────────────────────────
 function termLink(text, filePath) {
-    if (!filePath)
+    if (!filePath || !process.stdout.isTTY)
         return text;
     const url = `file://${filePath}`;
     return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;

package/dist/commands/lock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents lock` — write a deterministic `agents.lock` for the resolved resource
+ * set at the project root; `agents lock --frozen` verifies the live resources
+ * match that lock EXACTLY and fails closed (non-zero exit + a clear diff) on any
+ * drift. The reproducible-CI slice of governance #337.
+ *
+ * This is OFF the default path: normal `agents add` / `agents sync` never touch
+ * the lock. Generation and verification only run when this command is invoked.
+ */
+import { Command } from 'commander';
+/** Register the `agents lock` command. */
+export declare function registerLockCommand(program: Command): void;

package/dist/commands/lock.js

@@ -0,0 +1,70 @@
+/**
+ * `agents lock` — write a deterministic `agents.lock` for the resolved resource
+ * set at the project root; `agents lock --frozen` verifies the live resources
+ * match that lock EXACTLY and fails closed (non-zero exit + a clear diff) on any
+ * drift. The reproducible-CI slice of governance #337.
+ *
+ * This is OFF the default path: normal `agents add` / `agents sync` never touch
+ * the lock. Generation and verification only run when this command is invoked.
+ */
+import chalk from 'chalk';
+import { enumerateLockSources, buildLock, writeLock, readLock, verifyLock, lockDiffIsClean, resolveProjectRoot, LOCK_FILENAME, } from '../lib/lock.js';
+/** Register the `agents lock` command. */
+export function registerLockCommand(program) {
+    program
+        .command('lock')
+        .summary('Write or verify agents.lock — a SHA-256 manifest of resolved resources')
+        .description('Capture a deterministic SHA-256 per resolved resource file (commands, skills, hooks, rules, mcp, permissions, subagents — project > user > system > extras) into an agents.lock at the project root.\n\n' +
+        'Run bare to (re)generate the lock. Pass --frozen to VERIFY the live resolved resources match an existing agents.lock exactly — it exits non-zero with an added/removed/changed diff on any mismatch, and errors if no lock exists yet. That is the reproducible-CI gate; normal installs and syncs are unaffected.')
+        .option('--cwd <path>', 'Working directory to resolve resources and the project root from')
+        .option('--frozen', 'Verify resolved resources match agents.lock exactly; fail (non-zero) on any drift', false)
+        .action((opts) => {
+        runLock(opts);
+    });
+}
+function runLock(opts) {
+    const cwd = opts.cwd || process.cwd();
+    const projectRoot = resolveProjectRoot(cwd);
+    const sources = enumerateLockSources(cwd);
+    if (opts.frozen) {
+        verifyFrozen(projectRoot, sources);
+        return;
+    }
+    const lock = buildLock(sources);
+    const written = writeLock(projectRoot, lock);
+    const count = Object.keys(lock.resources).length;
+    console.log(chalk.green(`Wrote ${LOCK_FILENAME}`) +
+        chalk.gray(` — ${count} resource file(s) → ${written}`));
+}
+function verifyFrozen(projectRoot, sources) {
+    let existing;
+    try {
+        existing = readLock(projectRoot);
+    }
+    catch (e) {
+        console.error(chalk.red(`agents lock --frozen: ${e.message}`));
+        process.exitCode = 1;
+        return;
+    }
+    if (!existing) {
+        console.error(chalk.red(`No ${LOCK_FILENAME} at ${projectRoot}.`));
+        console.error(chalk.gray('Generate one first: agents lock'));
+        process.exitCode = 1;
+        return;
+    }
+    const diff = verifyLock(existing, sources);
+    if (lockDiffIsClean(diff)) {
+        const count = Object.keys(existing.resources).length;
+        console.log(chalk.green(`✓ ${count} resource file(s) match ${LOCK_FILENAME}`));
+        return;
+    }
+    console.error(chalk.red(`✗ resources drifted from ${LOCK_FILENAME}:`));
+    for (const key of diff.changed)
+        console.error(chalk.yellow(`  changed  ${key}`));
+    for (const key of diff.added)
+        console.error(chalk.yellow(`  added    ${key}`));
+    for (const key of diff.removed)
+        console.error(chalk.yellow(`  removed  ${key}`));
+    console.error(chalk.gray('Re-lock once the change is intended: agents lock'));
+    process.exitCode = 1;
+}

package/dist/commands/logs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `agents logs` — unified, discoverable run-log viewer.
+ *
+ * Resolves a run across two substrates and shows (or `-f` follows) its log:
+ *  - host-dispatch tasks (`agents run --host`) → combined-stdout log, offset-tailed
+ *  - sessions (the local index) → transcript, tailed via the sessions tailer
+ *
+ * `[id]`/`--session` load directly (host task tried first, then session). With no
+ * id, `--host`/`--agent`/`--version` filter a merged candidate list; one match is
+ * shown, several open the fuzzy picker (or, non-TTY, print the list).
+ *
+ * Additive: `agents hosts logs` and `agents sessions tail` are unchanged and share
+ * the same underlying helpers (showHostTaskLog / streamSessionTail).
+ */
+import type { Command } from 'commander';
+/** Register the top-level `agents logs` command. */
+export declare function registerLogsCommand(program: Command): void;

package/dist/commands/logs.js

@@ -0,0 +1,139 @@
+/**
+ * `agents logs` — unified, discoverable run-log viewer.
+ *
+ * Resolves a run across two substrates and shows (or `-f` follows) its log:
+ *  - host-dispatch tasks (`agents run --host`) → combined-stdout log, offset-tailed
+ *  - sessions (the local index) → transcript, tailed via the sessions tailer
+ *
+ * `[id]`/`--session` load directly (host task tried first, then session). With no
+ * id, `--host`/`--agent`/`--version` filter a merged candidate list; one match is
+ * shown, several open the fuzzy picker (or, non-TTY, print the list).
+ *
+ * Additive: `agents hosts logs` and `agents sessions tail` are unchanged and share
+ * the same underlying helpers (showHostTaskLog / streamSessionTail).
+ */
+import chalk from 'chalk';
+import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
+import { parseAgentFilter, renderSessionLog } from './sessions.js';
+import { streamSessionTail, isTailable } from './sessions-tail.js';
+import { showHostTaskLog } from '../lib/hosts/logs.js';
+import { listTasks } from '../lib/hosts/tasks.js';
+import { itemPicker } from '../lib/picker.js';
+/** Compact one-line label used by both the picker and the non-TTY list. */
+function candidateLabel(c) {
+    if (c.kind === 'task') {
+        const t = c.task;
+        const status = t.status === 'completed' ? chalk.green(t.status)
+            : t.status === 'failed' ? chalk.red(t.status)
+                : chalk.yellow(t.status);
+        return `${chalk.gray('task')} ${t.id.slice(0, 8).padEnd(9)} ${t.host.padEnd(14)} ${t.agent.padEnd(8)} ${status}  ${t.prompt.slice(0, 40)}`;
+    }
+    const s = c.session;
+    const ver = s.version ? chalk.gray(`@${s.version}`) : '';
+    const title = s.label || s.topic || '';
+    return `${chalk.gray('sess')} ${s.shortId.padEnd(9)} ${(s.agent + ver).padEnd(14)} ${chalk.gray(s.timestamp.slice(0, 16))}  ${title.slice(0, 40)}`;
+}
+/** Show a resolved session — follow (tail) or render its transcript. */
+async function showSession(session, follow) {
+    if (follow) {
+        if (!isTailable(session.agent)) {
+            console.error(chalk.red(`Tailing is supported for claude and codex sessions only (got ${session.agent}).`));
+            process.exit(2);
+        }
+        await streamSessionTail(session, {});
+        return;
+    }
+    await renderSessionLog(session);
+}
+async function showCandidate(c, follow) {
+    if (c.kind === 'task') {
+        const res = await showHostTaskLog(c.task.id, follow);
+        if (res.exitCode !== undefined)
+            process.exitCode = res.exitCode;
+        return;
+    }
+    await showSession(c.session, follow);
+}
+/** Resolve an explicit id/--session: host task first, then a session. */
+async function showById(id, follow) {
+    const hostRes = await showHostTaskLog(id, follow);
+    if (hostRes.found) {
+        if (hostRes.exitCode !== undefined)
+            process.exitCode = hostRes.exitCode;
+        return;
+    }
+    const sessions = await discoverSessions({ all: true, limit: 5000 });
+    const matches = resolveSessionById(sessions, id);
+    if (matches.length === 0) {
+        console.error(chalk.red(`No run or session found matching "${id}".`));
+        process.exit(1);
+    }
+    await showSession(matches[0], follow);
+}
+async function runLogs(id, opts) {
+    const follow = !!opts.follow;
+    const directId = opts.session ?? id;
+    if (directId) {
+        await showById(directId, follow);
+        return;
+    }
+    const { agent, version } = parseAgentFilter(opts.agent);
+    const wantVersion = opts.version ?? version;
+    // Host tasks carry no session-index metadata; sessions carry no host tag.
+    // So --host scopes to dispatched tasks, and --version to sessions.
+    const candidates = [];
+    let tasks = listTasks();
+    if (opts.host)
+        tasks = tasks.filter((t) => t.host === opts.host);
+    if (agent)
+        tasks = tasks.filter((t) => t.agent === agent);
+    for (const t of tasks)
+        candidates.push({ kind: 'task', task: t });
+    if (!opts.host) {
+        const sessions = await discoverSessions({ agent, version: wantVersion, limit: 50 });
+        for (const s of sessions)
+            candidates.push({ kind: 'session', session: s });
+    }
+    if (candidates.length === 0) {
+        console.error(chalk.yellow('No matching runs. Dispatch one: agents run <agent> "<task>" [--host <name>]'));
+        process.exit(1);
+    }
+    if (candidates.length === 1) {
+        await showCandidate(candidates[0], follow);
+        return;
+    }
+    // Multiple sessions matched → picker if interactive, else a list to pick from.
+    if (!process.stdin.isTTY) {
+        console.error(chalk.yellow(`${candidates.length} runs match. Pass an id or --session <id>:`));
+        for (const c of candidates.slice(0, 30))
+            console.error('  ' + candidateLabel(c));
+        process.exit(1);
+    }
+    const picked = await itemPicker({
+        message: 'Select a run to view its log:',
+        items: candidates,
+        filter: (query) => {
+            const q = query.trim().toLowerCase();
+            if (!q)
+                return candidates;
+            return candidates.filter((c) => candidateLabel(c).toLowerCase().includes(q));
+        },
+        labelFor: (c) => candidateLabel(c),
+        shortIdFor: (c) => (c.kind === 'task' ? c.task.id : c.session.shortId),
+    });
+    if (!picked)
+        return;
+    await showCandidate(picked.item, follow);
+}
+/** Register the top-level `agents logs` command. */
+export function registerLogsCommand(program) {
+    program
+        .command('logs [id]')
+        .description('Show a run’s log — a host-dispatch task or a session. -f to follow a live one.')
+        .option('--host <name>', 'Scope to runs dispatched to a host')
+        .option('-a, --agent <agent>', 'Filter by agent (e.g. claude, codex@0.116.0)')
+        .option('--version <version>', 'Filter by agent version')
+        .option('--session <id>', 'Select a session/run by id (same as the positional id)')
+        .option('-f, --follow', 'Follow live output')
+        .action((id, opts) => runLogs(id, opts));
+}

package/dist/commands/message.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agents message <target> <text>` — send a message to a running agent.
+ *
+ * Unifies two delivery paths behind one verb:
+ *   - a live LOCAL/teams/loop agent → enqueue into its file-spool mailbox; the
+ *     PreToolUse hook injects it at the agent's next tool call.
+ *   - a CLOUD task id → the existing provider follow-up path (was
+ *     `agents cloud message`).
+ *
+ * Cross-host is handled one layer up: `--host <h>` routes the whole command over
+ * ssh via `REMOTE_PASSTHROUGH` (see src/lib/hosts/passthrough.ts), so the box is
+ * written on the host that actually owns the agent.
+ */
+import type { Command } from 'commander';
+export declare function registerMessageCommand(program: Command): void;

package/dist/commands/message.js

@@ -0,0 +1,56 @@
+import chalk from 'chalk';
+import { getActiveSessions } from '../lib/session/active.js';
+import { getTaskById, updateTaskStatus } from '../lib/cloud/store.js';
+import { resolveProvider } from '../lib/cloud/registry.js';
+import { mailboxDir, enqueue } from '../lib/mailbox.js';
+import { resolveMessageTarget } from '../lib/mailbox-target.js';
+function die(msg, code = 1) {
+    console.error(chalk.red(msg));
+    process.exit(code);
+}
+export function registerMessageCommand(program) {
+    program
+        .command('message <target> <text>')
+        .description('Send a message to a running agent (delivered at its next tool call) or a cloud task.')
+        .option('--from <who>', 'Label recorded as the sender of this message')
+        .action(async (target, text, opts) => {
+        if (!target.trim()) {
+            die('Target must be a session/agent id or cloud task id. Run `agents sessions --active` to list running agents.');
+        }
+        const sessions = await getActiveSessions();
+        const res = resolveMessageTarget(target, sessions, (id) => getTaskById(id) != null);
+        switch (res.kind) {
+            case 'cloud': {
+                const task = getTaskById(res.id);
+                const provider = resolveProvider(task.provider);
+                try {
+                    await provider.message(res.id, text);
+                    updateTaskStatus(res.id, 'running');
+                    console.log(chalk.green(`Message sent to cloud task ${res.id}. Agent is continuing.`));
+                }
+                catch (err) {
+                    die(err.message);
+                }
+                return;
+            }
+            case 'local': {
+                try {
+                    const msgId = enqueue(mailboxDir(res.id), { to: res.id, text, from: opts.from });
+                    console.log(chalk.green(`Queued message ${msgId} for ${res.id}. `) +
+                        chalk.dim('The agent will see it at its next tool call.'));
+                }
+                catch (err) {
+                    die(err.message);
+                }
+                return;
+            }
+            case 'ambiguous': {
+                const lines = res.candidates.map((c) => `  ${c.id}  ${chalk.dim(c.label)}`).join('\n');
+                die(`"${target}" matches ${res.candidates.length} running agents:\n${lines}\nRe-run with a full id.`);
+                return;
+            }
+            case 'none':
+                die(`No running agent or cloud task matches "${target}". List targets with \`agents sessions --active\`.`);
+        }
+    });
+}

package/dist/commands/models.d.ts

@@ -8,3 +8,6 @@
 import type { Command } from 'commander';
 /** Register the hidden `agents models` command. */
 export declare function registerModelsCommand(program: Command): void;
+export declare function formatModelSourceLine(kind: string, sourcePath: string, width?: number): string;
+export declare function formatModelAliasLines(parts: string[], width?: number): string[];
+export declare function formatModelSummaryLine(star: string, id: string, displayName?: string, alias?: string, width?: number): string;

package/dist/commands/models.js

@@ -11,6 +11,8 @@ import { homeDir } from '../lib/platform/index.js';
 import { resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
 import { getModelCatalog, locateModelSource } from '../lib/models.js';
+import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
+import { wrapJoined } from './inspect.js';
 const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi'];
 /**
  * Agents that don't necessarily install under ~/.agents/versions (cursor ships
@@ -131,21 +133,19 @@ function printCatalog(agent, version, isDefault, options) {
         console.log(chalk.yellow(`  No models extracted from ${src.kind} at ${src.path}.`));
         return;
     }
-    console.log(chalk.gray(`  source: ${src.kind} (${shortPath(src.path)})`));
+    console.log(chalk.gray(formatModelSourceLine(src.kind, shortPath(src.path))));
     if (Object.keys(catalog.aliases).length > 0) {
         const parts = Object.entries(catalog.aliases).map(([alias, id]) => `${chalk.cyan(alias)}=${id}`);
-        console.log(chalk.gray(`  aliases: `) + parts.join(', '));
+        for (const line of formatModelAliasLines(parts))
+            console.log(line);
     }
     console.log();
     for (const model of catalog.models) {
         const star = model.isDefault ? chalk.green('*') : ' ';
-        const display = model.displayName && model.displayName !== model.id
-            ? chalk.gray(` (${model.displayName})`)
-            : '';
-        const aliasTag = model.alias ? chalk.cyan(` [${model.alias}]`) : '';
-        console.log(`  ${star} ${chalk.bold(model.id)}${display}${aliasTag}`);
+        console.log(formatModelSummaryLine(star, model.id, model.displayName, model.alias));
         if (model.description) {
-            console.log(chalk.gray(`      ${model.description}`));
+            const descPrefix = '      ';
+            console.log(chalk.gray(descPrefix + truncateToWidth(model.description, Math.max(1, terminalWidth() - stringWidth(descPrefix)))));
         }
         if (options.cloud && model.perCloud) {
             const c = model.perCloud;
@@ -175,3 +175,22 @@ function printCatalog(agent, version, isDefault, options) {
 function shortPath(p) {
     return p.replace(homeDir(), '~');
 }
+export function formatModelSourceLine(kind, sourcePath, width = terminalWidth()) {
+    const prefix = `  source: ${kind} (`;
+    const suffix = ')';
+    const room = Math.max(1, width - stringWidth(prefix) - stringWidth(suffix));
+    return prefix + truncateToWidth(sourcePath, room) + suffix;
+}
+export function formatModelAliasLines(parts, width = terminalWidth()) {
+    return wrapJoined(chalk.gray('  aliases: '), parts, ', ', width);
+}
+export function formatModelSummaryLine(star, id, displayName, alias, width = terminalWidth()) {
+    const display = displayName && displayName !== id ? ` (${displayName})` : '';
+    const aliasTag = alias ? ` [${alias}]` : '';
+    const prefix = `  ${star} `;
+    const plain = `${id}${display}${aliasTag}`;
+    if (stringWidth(plain) > Math.max(1, width - stringWidth(prefix))) {
+        return prefix + truncateToWidth(plain, Math.max(1, width - stringWidth(prefix)));
+    }
+    return prefix + chalk.bold(id) + chalk.gray(display) + chalk.cyan(aliasTag);
+}

package/dist/commands/permissions.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import ora from 'ora';
+import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -191,9 +192,15 @@ When to use:
                 return;
             }
             console.log(chalk.bold('Installed Permission Sets:\n'));
+            const permCols = terminalWidth();
             for (const perm of sets) {
-                const desc = perm.set.description ? ` - ${chalk.gray(perm.set.description)}` : '';
-                console.log(`  ${chalk.cyan(perm.name)}${desc}`);
+                const prefix = `  ${chalk.cyan(perm.name)}`;
+                // Cap the description to the line so a prose-paragraph set (400+ chars) can't smear.
+                const budget = permCols - stringWidth(prefix) - 3;
+                const desc = perm.set.description && budget > 3
+                    ? ` - ${chalk.gray(truncateToWidth(perm.set.description, budget))}`
+                    : '';
+                console.log(`${prefix}${desc}`);
                 console.log(`    ${chalk.gray(`${perm.set.allow.length} allow, ${perm.set.deny?.length || 0} deny rules`)}`);
             }
         }

package/dist/commands/repo.d.ts

@@ -28,6 +28,36 @@ export declare function resourceUnit(file: string): {
     kind: RepoResourceKind;
     unit: string;
 };
+/** One resource kind + action, collapsed to a unit count (e.g. 2 new skills). */
+export interface CountedResource {
+    action: ChangeAction;
+    kind: RepoResourceKind;
+    count: number;
+}
+/** Resource-level summary of a changed-file set. */
+export interface ResourceDelta {
+    /** Counts in display order (grouped new -> changed -> removed, then RESOURCE_ORDER). */
+    counts: CountedResource[];
+    /** Total distinct resource units changed. */
+    total: number;
+}
+/**
+ * Collapse a changed-file set to distinct resource units, then count them by
+ * (action, kind). A skill whose three files all changed counts as one changed
+ * skill; a unit with mixed add+modify reads as a single change. This is the
+ * shared structured core behind every SYNC / CHANGES rendering.
+ */
+export declare function resourceDelta(entries: {
+    action: ChangeAction;
+    file: string;
+}[]): ResourceDelta;
+/**
+ * Kind-only brief for the compact (wide-terminal) layout: `(24 skills, 9 commands, +20)`
+ * — the top `maxKinds` kinds by display order, with a `+N` remainder. Drops the
+ * new/changed verb (the arrow already carries direction) to stay short. Returns
+ * '' when there is nothing to summarize.
+ */
+export declare function deltaBrief(delta: ResourceDelta, maxKinds?: number): string;
 /**
  * Render a set of changed files as a resource-level summary, e.g.
  * `2 new skills, 1 changed hook`. Counts distinct resource units (a skill whose
@@ -39,6 +69,10 @@ export declare function formatResourceDelta(entries: {
     action: ChangeAction;
     file: string;
 }[], maxParts?: number): string;
+/** `owner/repo` from a git URL, for the compact card header. Falls back to the raw URL. */
+export declare function repoSlug(url: string): string;
+/** Pack colored phrases into `, `-joined lines no wider than `width`. */
+export declare function wrapPhrases(parts: string[], width: number): string[];
 /** Register the `agents repo` command tree. */
 export declare function registerRepoCommands(program: Command): void;
 export {};