@phnx-labs/agents-cli 1.20.51 → 1.20.53

package/dist/commands/logs.js

@@ -1,10 +1,14 @@
 /**
- * `agents logs` — unified, discoverable run-log viewer.
+ * `agents logs` — unified, discoverable run-log viewer + audit trail.
  *
  * 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
  *
+ * Subcommands:
+ *  - `agents logs audit` — read the structured audit/event log
+ *  - `agents logs stats` — show aggregate audit statistics
+ *
  * Concise by default: a bare `agents logs <id>` prints the same summary digest as
  * `agents sessions <id>` — cheap for an agent to glance at. The token-heavy full
  * transcript / raw stdout is opt-in behind `--full` (alias `-m/--markdown`).
@@ -17,12 +21,14 @@
  * the same underlying helpers (showHostTaskLog / streamSessionTail).
  */
 import chalk from 'chalk';
+import * as fs from 'fs';
 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';
+import { query, stats, getLogsPath, rotate, levelFor, } from '../lib/events.js';
 /** Compact one-line label used by both the picker and the non-TTY list. */
 function candidateLabel(c) {
     if (c.kind === 'task') {
@@ -130,11 +136,207 @@ async function runLogs(id, opts) {
         return;
     await showCandidate(picked.item, follow, full);
 }
+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);
+}
+function originLabel(r) {
+    if (r.transport === 'ssh') {
+        return chalk.yellow(`ssh${r.sshClientIp ? ' ' + r.sshClientIp : ''}`);
+    }
+    return chalk.gray('local');
+}
+function auditDetailFor(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.server === 'string')
+        bits.push(`server=${r.server}`);
+    if (typeof r.error === 'string')
+        bits.push(chalk.red(r.error));
+    return bits.join(' ');
+}
+function levelColor(level) {
+    if (level === 'audit')
+        return chalk.magenta(level);
+    if (level === 'warn')
+        return chalk.yellow(level);
+    if (level === 'debug')
+        return chalk.gray(level);
+    return chalk.blue(level);
+}
+function renderAuditRow(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 lvl = levelColor(r.level ?? levelFor(r.event));
+    const agent = r.agent ? chalk.gray(` ${r.agent}`) : '';
+    const caller = chalk.gray(`via ${r.caller ?? 'unknown'}${r.session ? ` ${r.session}` : ''}`);
+    return `${time}  ${lvl.padEnd(14)} ${originLabel(r).padEnd(24)} ${user.padEnd(22)} ${caller.padEnd(28)} ${ev.padEnd(26)}${agent}  ${auditDetailFor(r)}`;
+}
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+async function runAudit(opts) {
+    if (opts.follow) {
+        await followAuditLog();
+        return;
+    }
+    const limit = Math.max(1, parseInt(opts.limit ?? '50', 10) || 50);
+    let startDate;
+    try {
+        startDate = opts.since ? parseSince(opts.since) : undefined;
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(2);
+    }
+    const records = query({
+        startDate,
+        eventTypes: opts.event?.length ? opts.event : undefined,
+        level: opts.level,
+        agent: opts.agent,
+        caller: opts.caller,
+        command: opts.command,
+        module: opts.module,
+        limit,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(records, null, 2));
+        return;
+    }
+    if (records.length === 0) {
+        console.log(chalk.gray('No matching events.'));
+        return;
+    }
+    for (const r of records.slice().reverse())
+        console.log(renderAuditRow(r));
+    console.log(chalk.gray(`\n${records.length} event(s). Log: ${getLogsPath()}`));
+}
+async function followAuditLog() {
+    const file = getLogsPath();
+    let offset = 0;
+    try {
+        offset = fs.statSync(file).size;
+    }
+    catch {
+        // File may not exist yet — start at 0.
+    }
+    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;
+            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(renderAuditRow(JSON.parse(line)));
+                }
+                catch {
+                    // Skip malformed lines.
+                }
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    };
+    await new Promise(() => {
+        setInterval(drain, 500);
+    });
+}
+function humanBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function runStats(opts) {
+    let days = 7;
+    if (opts.since) {
+        try {
+            const d = parseSince(opts.since);
+            days = Math.max(1, Math.ceil((Date.now() - d.getTime()) / 86_400_000));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+    }
+    const s = stats({ days });
+    if (opts.json) {
+        console.log(JSON.stringify(s, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`Audit statistics (last ${days} day${days === 1 ? '' : 's'})\n`));
+    console.log(`  Total events:  ${s.totalEvents}`);
+    console.log(`  Log files:     ${s.fileCount} (${humanBytes(s.totalBytes)})`);
+    console.log(`  Log path:      ${chalk.gray(getLogsPath())}`);
+    if (Object.keys(s.byLevel).length) {
+        console.log(chalk.bold('\n  By level:'));
+        for (const [k, v] of Object.entries(s.byLevel).sort((a, b) => b[1] - a[1])) {
+            console.log(`    ${levelColor(k).padEnd(20)} ${v}`);
+        }
+    }
+    if (Object.keys(s.byEvent).length) {
+        console.log(chalk.bold('\n  By event (top 15):'));
+        for (const [k, v] of Object.entries(s.byEvent).sort((a, b) => b[1] - a[1]).slice(0, 15)) {
+            console.log(`    ${chalk.cyan(k).padEnd(30)} ${v}`);
+        }
+    }
+    if (Object.keys(s.byModule).length) {
+        console.log(chalk.bold('\n  By module:'));
+        for (const [k, v] of Object.entries(s.byModule).sort((a, b) => b[1] - a[1])) {
+            console.log(`    ${k.padEnd(20)} ${v}`);
+        }
+    }
+    if (Object.keys(s.byUser).length) {
+        console.log(chalk.bold('\n  By user:'));
+        for (const [k, v] of Object.entries(s.byUser).sort((a, b) => b[1] - a[1])) {
+            console.log(`    ${k.padEnd(30)} ${v}`);
+        }
+    }
+    console.log();
+}
 /** Register the top-level `agents logs` command. */
 export function registerLogsCommand(program) {
-    program
+    const logsCmd = program
         .command('logs [id]')
-        .description('Show a run’s concise summary — a host-dispatch task or a session. --full for the raw transcript, -f to follow a live one.')
+        .description('Show a run log, audit trail, or stats. Subcommands: audit, stats, rotate.')
         .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')
@@ -142,4 +344,47 @@ export function registerLogsCommand(program) {
         .option('-f, --follow', 'Follow live output')
         .option('-m, --full', 'Show the full raw transcript / stdout instead of the concise summary')
         .action((id, opts) => runLogs(id, opts));
+    logsCmd
+        .command('audit')
+        .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)', collect, [])
+        .option('--agent <name>', 'Only events tagged with this agent')
+        .option('--caller <kind>', 'Only this caller kind (claude-code, codex, gemini, cursor, terminal, script)')
+        .option('--level <level>', 'Only this level: audit, warn, info, debug')
+        .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 logs audit                          Recent activity across everything
+  agents logs audit --module teams           Team lifecycle (create / add / disband)
+  agents logs audit --module secrets         Every secret accessed or revealed
+  agents logs audit --level audit            Only audit-level events
+  agents logs audit --command "teams create" Just team creations
+  agents logs audit --event secrets.get --since 7d --json
+  agents logs audit -f                       Live tail`)
+        .action(async (options) => runAudit(options));
+    logsCmd
+        .command('stats')
+        .description('Show aggregate audit statistics')
+        .option('--since <time>', 'Window size (e.g. 7d, 30d; default 7d)')
+        .option('--json', 'Output stats as JSON')
+        .action(async (opts) => runStats(opts));
+    logsCmd
+        .command('rotate')
+        .description('Force log rotation — remove files older than the retention period')
+        .option('--days <n>', 'Retention period in days (default 7)', '7')
+        .action((opts) => {
+        const days = Math.max(1, parseInt(opts.days ?? '7', 10) || 7);
+        const removed = rotate(days);
+        if (removed > 0) {
+            console.log(`Removed ${removed} log file${removed === 1 ? '' : 's'} older than ${days} day${days === 1 ? '' : 's'}.`);
+        }
+        else {
+            console.log(chalk.gray('No log files to remove.'));
+        }
+    });
 }

package/dist/commands/mcp.js

@@ -3,6 +3,7 @@ import { truncate } from '../lib/format.js';
 import ora from 'ora';
 import { checkbox } from '@inquirer/prompts';
 import { capableAgents, isCapable } from '../lib/capabilities.js';
+import { emit } from '../lib/events.js';
 import { AGENTS, getAllCliStates, resolveAgentName, formatAgentError, registerMcpToTargets, unregisterMcpFromTargets, listInstalledMcpsWithScope, parseMcpConfig, getMcpConfigPathForHome, agentLabel, } from '../lib/agents.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
 import { listMcpServerConfigs, discoverMcpConfigsFromRepo, installMcpConfigCentrally, } from '../lib/mcp.js';
@@ -293,6 +294,7 @@ Examples:
             };
         }
         writeManifest(localPath, manifest);
+        emit('mcp.add', { module: 'mcp', server: name });
         console.log(chalk.green(`Added MCP server '${name}' to manifest`));
         console.log(chalk.gray('Run: agents mcp register to apply'));
     });
@@ -441,6 +443,8 @@ Examples:
             console.log(chalk.yellow('No MCP servers removed.'));
         }
         else {
+            for (const n of mcpsToRemove)
+                emit('mcp.remove', { module: 'mcp', server: n });
             console.log(chalk.green(`\nRemoved ${removed} MCP server(s).`));
         }
     });
@@ -575,6 +579,7 @@ Examples:
                 targets = resolveConfiguredAgentTargets(config.agents, config.agentVersions, capableAgents('mcp'));
             }
             const results = await registerMcpToTargets(targets, mcpName, commandOrUrl, config.scope || 'user', transport, { headers: config.headers });
+            const applied = results.filter(r => r.success).length;
             for (const result of results) {
                 if (result.success) {
                     console.log(`    ${chalk.green('+')} ${formatTargetLabel(result.agentId, result.version)}`);
@@ -586,6 +591,8 @@ Examples:
                     console.log(`    ${chalk.red('x')} ${formatTargetLabel(result.agentId, result.version)}: ${result.error}`);
                 }
             }
+            if (applied > 0)
+                emit('mcp.register', { module: 'mcp', server: mcpName, applied });
         }
     });
 }

package/dist/commands/memory.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `agents memory` — first-class knowledge/facts resource (not rules).
+ *
+ * Mirrors the skills surface at list / add / remove / view / sync scale.
+ * Canonical storage: ~/.agents/memory/ (project > user > system layering).
+ */
+import type { Command } from 'commander';
+/** Register the `agents memory` command tree. */
+export declare function registerMemoryCommands(program: Command): void;

package/dist/commands/memory.js

@@ -0,0 +1,164 @@
+/**
+ * `agents memory` — first-class knowledge/facts resource (not rules).
+ *
+ * Mirrors the skills surface at list / add / remove / view / sync scale.
+ * Canonical storage: ~/.agents/memory/ (project > user > system layering).
+ */
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { listMemoryFacts, addMemoryFact, removeMemoryFact, readMemoryFact, ensureUserMemoryDir, getUserMemoryDir, syncMemoryToVersionHome, } from '../lib/memory.js';
+import { capableAgents } from '../lib/capabilities.js';
+import { resolveAgentName, formatAgentError, agentLabel, ALL_AGENT_IDS } from '../lib/agents.js';
+import { listInstalledVersions, getVersionHomePath, } from '../lib/versions.js';
+import { supports } from '../lib/capabilities.js';
+import { setHelpSections } from '../lib/help.js';
+/** Register the `agents memory` command tree. */
+export function registerMemoryCommands(program) {
+    const memoryCmd = program
+        .command('memory')
+        .description('Manage portable agent memory (facts, preferences, project knowledge)');
+    setHelpSections(memoryCmd, {
+        examples: `
+      # List all memory facts (project > user > system)
+      agents memory list
+
+      # Add a fact
+      agents memory add preferred-editor --body "User prefers vim keybindings"
+
+      # View a fact
+      agents memory view preferred-editor
+
+      # Remove a fact from the user layer
+      agents memory remove preferred-editor
+
+      # Fan out to all capable installed agent versions
+      agents memory sync
+    `,
+        notes: `
+      Memory is the knowledge store (learned facts), distinct from rules
+      (instructions / AGENTS.md persona). Stored under ~/.agents/memory/ and
+      synced into capable agents' version homes (claude/codex/openclaw/grok).
+
+      Format: MEMORY.md index + one <slug>.md file per fact.
+    `,
+    });
+    memoryCmd
+        .command('list')
+        .description('List memory facts from project, user, and system layers')
+        .option('--json', 'Emit machine-readable JSON')
+        .action((options) => {
+        const facts = listMemoryFacts(process.cwd());
+        if (options.json) {
+            process.stdout.write(JSON.stringify(facts, null, 2) + '\n');
+            return;
+        }
+        if (facts.length === 0) {
+            console.log(chalk.gray('No memory facts yet.'));
+            console.log(chalk.gray(`  Add one: agents memory add <name> --body "..."`));
+            console.log(chalk.gray(`  Dir:     ${getUserMemoryDir()}`));
+            return;
+        }
+        console.log(chalk.bold(`Memory (${facts.length})`));
+        for (const f of facts) {
+            const layer = chalk.dim(`[${f.layer}]`);
+            console.log(`  ${chalk.cyan(f.name)} ${layer}  ${f.summary}`);
+        }
+        const capable = capableAgents('memory');
+        if (capable.length > 0) {
+            console.log(chalk.gray(`\nCapable agents: ${capable.join(', ')}`));
+        }
+    });
+    memoryCmd
+        .command('add <name>')
+        .description('Add or overwrite a user-layer memory fact')
+        .requiredOption('--body <text>', 'Fact body (markdown)')
+        .option('--sync', 'Immediately sync to all capable installed versions')
+        .action((name, options) => {
+        const filePath = addMemoryFact(name, options.body);
+        console.log(chalk.green(`Added memory fact: ${name}`));
+        console.log(chalk.gray(`  ${filePath}`));
+        if (options.sync) {
+            for (const r of syncAllMemory(process.cwd())) {
+                console.log(chalk.gray(`  synced ${r.agent}@${r.version} (${r.facts.length} facts)`));
+            }
+        }
+        else {
+            console.log(chalk.gray('  Run: agents memory sync  (or agents sync) to fan out'));
+        }
+    });
+    memoryCmd
+        .command('remove <name>')
+        .alias('rm')
+        .description('Remove a user-layer memory fact')
+        .action((name) => {
+        if (removeMemoryFact(name)) {
+            console.log(chalk.green(`Removed memory fact: ${name}`));
+        }
+        else {
+            console.error(chalk.red(`No user-layer fact named "${name}"`));
+            process.exit(1);
+        }
+    });
+    memoryCmd
+        .command('view <name>')
+        .description('Print a memory fact (winning layer)')
+        .action((name) => {
+        const fact = readMemoryFact(name, process.cwd());
+        if (!fact) {
+            console.error(chalk.red(`No memory fact named "${name}"`));
+            process.exit(1);
+        }
+        console.log(chalk.dim(`# ${fact.name}  [${fact.layer}]  ${fact.path}`));
+        console.log(fs.readFileSync(fact.path, 'utf-8'));
+    });
+    memoryCmd
+        .command('sync [agent]')
+        .description('Copy canonical memory into capable agent version homes')
+        .option('-a, --agent <agent>', 'Limit to one agent (or agent@version)')
+        .action(async (agentArg, options) => {
+        ensureUserMemoryDir();
+        const input = agentArg || options.agent;
+        if (input) {
+            const parts = input.split('@');
+            const resolved = resolveAgentName(parts[0]);
+            if (!resolved) {
+                console.error(chalk.red(formatAgentError(parts[0], capableAgents('memory'))));
+                process.exit(1);
+            }
+            const agent = resolved;
+            const versions = parts[1]
+                ? [parts[1]]
+                : listInstalledVersions(agent);
+            if (versions.length === 0) {
+                console.log(chalk.yellow(`No installed versions of ${agentLabel(agent)}`));
+                return;
+            }
+            for (const version of versions) {
+                const home = getVersionHomePath(agent, version);
+                const facts = syncMemoryToVersionHome(agent, home, process.cwd());
+                console.log(chalk.green(`Synced ${facts.length} fact(s) → ${agent}@${version}`));
+            }
+            return;
+        }
+        const results = syncAllMemory(process.cwd());
+        if (results.length === 0) {
+            console.log(chalk.gray('No memory-capable agent versions installed.'));
+            return;
+        }
+        for (const r of results) {
+            console.log(chalk.green(`Synced ${r.facts.length} fact(s) → ${r.agent}@${r.version}`));
+        }
+    });
+}
+function syncAllMemory(cwd) {
+    const out = [];
+    for (const agent of ALL_AGENT_IDS) {
+        if (!supports(agent, 'memory').ok)
+            continue;
+        for (const version of listInstalledVersions(agent)) {
+            const home = getVersionHomePath(agent, version);
+            out.push({ agent, version, facts: syncMemoryToVersionHome(agent, home, cwd) });
+        }
+    }
+    return out;
+}

package/dist/commands/message.d.ts

@@ -1,15 +1,20 @@
 /**
- * `agents message <target> <text>` — send a message to a running agent.
+ * `agents message <target> <text>` — send a message to a running or parked 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`).
+ * Delivery is routed by agent state (RUSH-1474):
+ *   - running, between tool calls → mailbox spool (PreToolUse inject)
+ *   - parked on AskUserQuestion with a tmux/iterm/pty rail → keystroke inject
+ *   - parked headless (no rail) → `agents run --resume <id> -- <answer>`
+ *   - cloud task → provider.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.
+ *
+ * For local agents, the message is tied to the agent's current open feed block
+ * (if any). The first answer to a block wins: a second concurrent answer is
+ * rejected with the surface that already answered. Delivery receipts
+ * (queued → consumed → continued) are surfaced in the feed store.
  */
 import type { Command } from 'commander';
 export declare function registerMessageCommand(program: Command): void;