@phnx-labs/agents-cli 1.20.33 → 1.20.35

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/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 {};