@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/commands/doctor.js

@@ -4,106 +4,50 @@ import { checkAllClis } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../lib/agents.js';
 import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
-import { diffVersionCommands, iterCommandsCapableVersions } from '../lib/commands.js';
-import { diffVersionSkills, iterSkillsCapableVersions } from '../lib/skills.js';
-import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome } from '../lib/hooks.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
+import { checkSyncStatus, countOrphans } from '../lib/drift.js';
 import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
 import { listCliStatus } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
 import { heal, healChangedAnything } from '../lib/heal.js';
 import { blocksLocalScripts, getEffectiveExecutionPolicy } from '../lib/platform/winpath.js';
+import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
-// Lines naming exactly what's out of sync for a version, plugins prioritized:
-// each divergent plugin gets its own line with specifics (stale mirror version,
-// invalid manifest, or the bundled skills/commands missing from the mirror —
-// the system-repo plugin content that matters most). Other kinds collapse to
-// compact counts so the readout stays scannable.
-function divergenceLines(report) {
-    const lines = [];
-    for (const p of report.kinds.plugins) {
-        if (p.status === 'missing')
-            lines.push(`plugin ${p.name} — not installed`);
-        else if (p.status === 'diff')
-            lines.push(`plugin ${p.name} — ${p.detail ?? 'mirror drifted'}`);
-    }
-    const counts = [];
-    for (const kind of ['commands', 'skills', 'hooks', 'rules', 'mcp', 'permissions', 'subagents']) {
-        const rows = report.kinds[kind];
-        const miss = rows.filter((r) => r.status === 'missing').length;
-        const dif = rows.filter((r) => r.status === 'diff').length;
-        const bits = [];
-        if (miss)
-            bits.push(`${miss} missing`);
-        if (dif)
-            bits.push(`${dif} drifted`);
-        if (bits.length)
-            counts.push(`${kind} ${bits.join('/')}`);
-    }
-    if (counts.length)
-        lines.push(counts.join(' · '));
-    return lines;
+function collapseWhitespace(s) {
+    return s.replace(/\s+/g, ' ').trim();
 }
-function checkSyncStatus(cwd) {
-    const rows = [];
-    // Every installed version, not just the default — a stale NON-default version
-    // (e.g. one you launched from yesterday) is exactly the rot that silently
-    // serves outdated/invalid resources and that `--fix` now heals. Hiding it here
-    // is why that class of bug went unnoticed.
-    for (const agent of ALL_AGENT_IDS) {
-        const def = getGlobalDefault(agent);
-        for (const version of listInstalledVersions(agent)) {
-            const manifest = loadManifest(agent, version);
-            const status = !manifest
-                ? 'never-synced'
-                : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
-            const row = { agent, version, status, isDefault: version === def };
-            if (status === 'stale') {
-                // Resolve the specifics against non-project layers (the global home is
-                // never reconciled against per-cwd project resources).
-                const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
-                const lines = divergenceLines(report);
-                if (lines.length)
-                    row.divergence = lines;
-            }
-            rows.push(row);
+export function wrapLine(prefix, text, width = terminalWidth()) {
+    const words = collapseWhitespace(text).split(' ').filter(Boolean);
+    if (words.length === 0)
+        return [prefix.trimEnd()];
+    const continuation = ' '.repeat(stringWidth(prefix));
+    const lines = [];
+    let linePrefix = prefix;
+    let line = prefix;
+    let hasWord = false;
+    for (const word of words) {
+        const room = Math.max(1, width - stringWidth(linePrefix));
+        const piece = stringWidth(word) > room ? truncateToWidth(word, room) : word;
+        const candidate = hasWord ? `${line} ${piece}` : `${line}${piece}`;
+        if (hasWord && stringWidth(candidate) > width) {
+            lines.push(line);
+            linePrefix = continuation;
+            line = continuation + piece;
+            hasWord = true;
+        }
+        else {
+            line = candidate;
+            hasWord = true;
         }
     }
-    return rows;
+    lines.push(line);
+    return lines;
 }
-function countOrphans() {
-    const byKey = new Map();
-    const ensure = (agent, version) => {
-        const key = `${agent}@${version}`;
-        let row = byKey.get(key);
-        if (!row) {
-            row = { agent, version, commands: 0, skills: 0, hooks: 0 };
-            byKey.set(key, row);
-        }
-        return row;
-    };
-    for (const { agent, version } of iterCommandsCapableVersions()) {
-        const diff = diffVersionCommands(agent, version);
-        if (diff.orphans.length > 0)
-            ensure(agent, version).commands = diff.orphans.length;
-    }
-    for (const { agent, version } of iterSkillsCapableVersions()) {
-        const diff = diffVersionSkills(agent, version);
-        if (diff.orphans.length > 0)
-            ensure(agent, version).skills = diff.orphans.length;
-    }
-    // Orphan hooks are scripts in the version home that no agents.yaml/hooks.yaml
-    // entry registers — so the registrar never wires them to an event and they
-    // never fire. (Distinct from the source-diff `diffVersionHooks().orphans`,
-    // which false-flags valid system-sourced registered hooks.)
-    for (const { agent, version } of iterHooksCapableVersions()) {
-        const dead = listUnmanagedHooksInVersionHome(agent, version);
-        if (dead.length > 0)
-            ensure(agent, version).hooks = dead.length;
-    }
-    return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
+function printWrappedLine(prefix, text) {
+    for (const line of wrapLine(prefix, text))
+        console.log(chalk.gray(line));
 }
 function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
     console.log(chalk.bold('Agent CLIs'));
@@ -130,7 +74,7 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
         }
     }
     if (hidden.length > 0) {
-        console.log(chalk.gray(`  +${hidden.length} more supported (${hidden.join(', ')}) — \`agents add <name>\` to manage`));
+        printWrappedLine('  ', `+${hidden.length} more supported (${hidden.join(', ')}) — \`agents add <name>\` to manage`);
     }
     console.log();
     console.log(chalk.bold('Sync status (installed versions)'));
@@ -162,7 +106,7 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
         // Version homes are reconciled only by management commands, so point at one
         // rather than promising an auto-sync that never happens.
         if (anyOutOfSync) {
-            console.log(chalk.gray('  Reconcile with `agents doctor <agent>@<version> --fix` or `agents sync <agent>@<version>` (not applied on launch).'));
+            printWrappedLine('  ', 'Reconcile with `agents doctor <agent>@<version> --fix` or `agents sync <agent>@<version>` (not applied on launch).');
         }
     }
     console.log();
@@ -199,10 +143,17 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
             const label = manifest.name.padEnd(nameWidth);
             const src = chalk.gray(`[${manifest.source}]`);
             if (installed) {
-                console.log(`  ${chalk.green('ready')}  ${label}  ${src}  ${chalk.gray(manifest.description || '')}`);
+                const prefix = `  ${chalk.green('ready')}  ${label}  ${src}`;
+                const desc = manifest.description
+                    ? `  ${truncateToWidth(collapseWhitespace(manifest.description), Math.max(1, terminalWidth() - stringWidth(prefix) - 2))}`
+                    : '';
+                console.log(prefix + chalk.gray(desc));
             }
             else {
-                console.log(`  ${chalk.red('miss ')}  ${label}  ${src}  ${chalk.gray(`not installed — run \`agents cli install ${manifest.name}\``)}`);
+                const prefix = `  ${chalk.red('miss ')}  ${label}  ${src}`;
+                const msg = `not installed — run \`agents cli install ${manifest.name}\``;
+                const budget = Math.max(1, terminalWidth() - stringWidth(prefix) - 2);
+                console.log(prefix + chalk.gray(`  ${truncateToWidth(msg, budget)}`));
             }
         }
     }
@@ -357,8 +308,12 @@ function renderKindSection(kind, rows, layers, options) {
     }
     for (const r of visible) {
         const src = sourceLabel(r, layers);
-        const detail = r.detail ? chalk.gray(`  ${r.detail}`) : '';
-        console.log(`    ${statusLabel(r.status)}  ${r.name.padEnd(28)} ${src}${detail}`);
+        const name = padToWidth(truncateToWidth(r.name, 28), 28);
+        const prefix = `    ${statusLabel(r.status)}  ${name} ${src}`;
+        const detail = r.detail
+            ? chalk.gray(`  ${truncateToWidth(collapseWhitespace(r.detail), Math.max(1, terminalWidth() - stringWidth(prefix) - 2))}`)
+            : '';
+        console.log(prefix + detail);
         if (options.showDiff && r.status === 'diff' && r.sourcePath && r.homePath) {
             const expected = readExpectedForDiff(kind, r);
             const actual = safeRead(r.homePath);
@@ -395,8 +350,10 @@ function readExpectedForDiff(kind, row) {
 function renderTargetText(report, options) {
     const label = `${AGENT_NAMES[report.agent] || report.agent}@${report.version}`;
     console.log(chalk.bold(label));
-    console.log(chalk.gray(`  home: ${report.home}`));
-    console.log(chalk.gray(`  cwd:  ${report.cwd}`));
+    const homePrefix = '  home: ';
+    const cwdPrefix = '  cwd:  ';
+    console.log(chalk.gray(homePrefix + truncateToWidth(report.home, Math.max(1, terminalWidth() - stringWidth(homePrefix)))));
+    console.log(chalk.gray(cwdPrefix + truncateToWidth(report.cwd, Math.max(1, terminalWidth() - stringWidth(cwdPrefix)))));
     const layerStr = [
         report.layers.project ? `project=${report.layers.project}` : null,
         `user=${report.layers.user}`,
@@ -405,7 +362,7 @@ function renderTargetText(report, options) {
             ? `extras=[${report.layers.extras.map((e) => e.alias).join(',')}]`
             : null,
     ].filter(Boolean).join(' ');
-    console.log(chalk.gray(`  layers: ${layerStr}`));
+    printWrappedLine('  layers: ', layerStr);
     // Staleness manifest verdict — single-line summary from the staleness
     // library, sitting alongside the detailed per-resource diff below.
     const manifest = loadManifest(report.agent, report.version);
@@ -446,7 +403,7 @@ function renderTargetText(report, options) {
     }
     else {
         console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        console.log(chalk.gray(`  Run \`agents doctor ${report.agent}@${report.version} --fix\` to heal, or \`agents prune cleanup\` to drop extras.`));
+        printWrappedLine('  ', `Run \`agents doctor ${report.agent}@${report.version} --fix\` to heal, or \`agents prune cleanup\` to drop extras.`);
     }
 }
 // ─── fix / heal mode ───────────────────────────────────────────────────────────

package/dist/commands/events.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `agents events` — read the structured audit/event log.
+ *
+ * The event log (`~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl`) records every
+ * `agents <module> <cmd>` invocation plus richer typed events (secrets access,
+ * version installs, ...), each stamped with who ran it and from where (OS user,
+ * local vs SSH, remote client IP). This command reads it back — the audit trail
+ * for "who accessed a secret / created a team / started an agent, and from which
+ * host?".
+ *
+ * Filter by `--module` (top-level group, e.g. teams), `--command` (path prefix,
+ * e.g. "teams create"), `--event` (typed event), `--agent`, and `--since`.
+ * `--follow` tails today's log live.
+ */
+import type { Command } from 'commander';
+export declare function registerEventsCommand(program: Command): void;

package/dist/commands/events.js

@@ -0,0 +1,173 @@
+/**
+ * `agents events` — read the structured audit/event log.
+ *
+ * The event log (`~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl`) records every
+ * `agents <module> <cmd>` invocation plus richer typed events (secrets access,
+ * version installs, ...), each stamped with who ran it and from where (OS user,
+ * local vs SSH, remote client IP). This command reads it back — the audit trail
+ * for "who accessed a secret / created a team / started an agent, and from which
+ * host?".
+ *
+ * Filter by `--module` (top-level group, e.g. teams), `--command` (path prefix,
+ * e.g. "teams create"), `--event` (typed event), `--agent`, and `--since`.
+ * `--follow` tails today's log live.
+ */
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { query, getLogsPath } from '../lib/events.js';
+/** Parse `--since`: relative offsets (30s/5m/2h/7d/4w) or an ISO/absolute date. */
+function parseSince(s) {
+    const m = s.match(/^(\d+)([smhdw])$/);
+    if (m) {
+        const n = parseInt(m[1], 10);
+        const unitMs = {
+            s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000,
+        };
+        return new Date(Date.now() - n * unitMs[m[2]]);
+    }
+    const ms = Date.parse(s);
+    if (isNaN(ms))
+        throw new Error(`Invalid --since value: ${s} (use e.g. 2h, 7d, or an ISO date)`);
+    return new Date(ms);
+}
+/** How the run reached this host — 'local' or 'ssh 203.0.113.7'. */
+function originLabel(r) {
+    if (r.transport === 'ssh') {
+        return chalk.yellow(`ssh${r.sshClientIp ? ' ' + r.sshClientIp : ''}`);
+    }
+    return chalk.gray('local');
+}
+/** The most useful one-line detail for a record, by event family. */
+function detailFor(r) {
+    if (r.command)
+        return r.command;
+    const bits = [];
+    if (typeof r.team === 'string')
+        bits.push(`team=${r.team}`);
+    if (typeof r.bundle === 'string')
+        bits.push(`bundle=${r.bundle}`);
+    if (typeof r.skill === 'string')
+        bits.push(`skill=${r.skill}`);
+    if (typeof r.version === 'string')
+        bits.push(`v=${r.version}`);
+    if (typeof r.profile === 'string')
+        bits.push(`profile=${r.profile}`);
+    if (typeof r.error === 'string')
+        bits.push(chalk.red(r.error));
+    return bits.join(' ');
+}
+function renderRow(r) {
+    const time = chalk.gray(r.ts.slice(0, 19).replace('T', ' '));
+    const user = `${r.osUser ?? '?'}@${r.hostname}`;
+    const ev = r.event.startsWith('error') ? chalk.red(r.event) : chalk.cyan(r.event);
+    const agent = r.agent ? chalk.gray(` ${r.agent}`) : '';
+    return `${time}  ${originLabel(r).padEnd(24)} ${user.padEnd(22)} ${ev.padEnd(26)}${agent}  ${detailFor(r)}`;
+}
+export function registerEventsCommand(program) {
+    program
+        .command('events')
+        .description('Read the structured audit/event log (who ran what, from where)')
+        .option('--module <name>', 'Only events from this command group (e.g. teams, secrets)')
+        .option('--command <path>', 'Only this command path — prefix match (e.g. "teams create")')
+        .option('--event <type>', 'Only this typed event (repeatable, e.g. secrets.get)', collect, [])
+        .option('--agent <name>', 'Only events tagged with this agent')
+        .option('--since <time>', 'Only events newer than this (e.g. 2h, 7d, or ISO date)')
+        .option('--limit <n>', 'Max records to show (default 50)', '50')
+        .option('--json', 'Output raw records as JSON')
+        .option('-f, --follow', "Tail today's log live")
+        .addHelpText('after', `
+Examples:
+  agents events                          Recent activity across everything
+  agents events --module teams           Team lifecycle (create / add / disband)
+  agents events --module secrets         Every secret accessed or revealed
+  agents events --command "teams create" Just team creations
+  agents events --event secrets.get --since 7d --json
+  agents events -f                       Live tail`)
+        .action(async (options) => {
+        if (options.follow) {
+            await followLog();
+            return;
+        }
+        const limit = Math.max(1, parseInt(options.limit ?? '50', 10) || 50);
+        let startDate;
+        try {
+            startDate = options.since ? parseSince(options.since) : undefined;
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+        const records = query({
+            startDate,
+            eventTypes: options.event && options.event.length ? options.event : undefined,
+            agent: options.agent,
+            command: options.command,
+            module: options.module,
+            limit,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(records, null, 2));
+            return;
+        }
+        if (records.length === 0) {
+            console.log(chalk.gray('No matching events.'));
+            return;
+        }
+        // query() returns newest-first; print oldest-first so a tail reads naturally.
+        for (const r of records.slice().reverse())
+            console.log(renderRow(r));
+        console.log(chalk.gray(`\n${records.length} event(s). Log: ${getLogsPath()}`));
+    });
+}
+/** commander repeatable-option collector. */
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+/** Tail today's event file, printing new lines as they land. */
+async function followLog() {
+    const today = new Date();
+    const file = `${getLogsPath()}/events-${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, '0')}-${String(today.getDate()).padStart(2, '0')}.jsonl`;
+    let offset = 0;
+    try {
+        offset = fs.statSync(file).size;
+    }
+    catch {
+        // File may not exist yet — start at 0 and pick it up on first write.
+    }
+    console.log(chalk.gray(`Tailing ${file} — Ctrl-C to stop`));
+    const drain = () => {
+        let size = 0;
+        try {
+            size = fs.statSync(file).size;
+        }
+        catch {
+            return;
+        }
+        if (size <= offset) {
+            if (size < offset)
+                offset = 0; // rotated/truncated
+            return;
+        }
+        const fd = fs.openSync(file, 'r');
+        try {
+            const buf = Buffer.alloc(size - offset);
+            fs.readSync(fd, buf, 0, buf.length, offset);
+            offset = size;
+            for (const line of buf.toString('utf-8').split('\n').filter(Boolean)) {
+                try {
+                    console.log(renderRow(JSON.parse(line)));
+                }
+                catch {
+                    // Skip malformed lines.
+                }
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    };
+    // Poll — simpler and more portable than fs.watch across platforms/editors.
+    await new Promise(() => {
+        setInterval(drain, 500);
+    });
+}

package/dist/commands/exec.d.ts

@@ -6,6 +6,7 @@
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
 import { type Command } from 'commander';
+import type { ExecEffort } from '../lib/exec.js';
 /**
  * Build the LoopConfig the driver consumes from CLI flags and/or a workflow's
  * `loop:` frontmatter block (issue #332). Returns undefined when neither source
@@ -26,5 +27,23 @@ export declare function buildLoopConfig(flags: {
 }, workflowLoop?: import('../lib/workflows.js').LoopConfigRaw): import('../lib/loop.js').LoopConfig | undefined;
 /** Map a loop stop reason to a process exit code. condition-met/max are clean exits. */
 export declare function loopExitCode(stoppedBy: import('../lib/loop.js').LoopStoppedBy): number;
+/**
+ * Drive a workflow's declarative `for_each:` fan-out end-to-end (issue #343).
+ *
+ * Runs the producer, expands one stage teammate per produced item (respecting
+ * `max_items` / `DEFAULT_FOR_EACH_CAP`, surfacing any truncation — never a
+ * silent cap), stages them into a fresh team via the existing `runForEach`
+ * bridge, then drives the teams supervisor until the DAG drains. When a verify
+ * panel is declared, tallies each item's `keep_if` gate from the skeptics'
+ * terminal status and logs which items survived.
+ *
+ * Reuses the teams substrate wholesale — no new orchestration engine. Returns
+ * the process exit code (0 on drain, 1 on producer failure / non-drain).
+ */
+export declare function runWorkflowForEach(spec: import('../lib/workflows.js').ForEachSpec, opts: {
+    workflowName: string;
+    cwd: string;
+    effort?: ExecEffort;
+}): Promise<number>;
 /** Register the `agents run <agent> [prompt]` command. */
 export declare function registerRunCommand(program: Command): void;