@phnx-labs/agents-cli 1.20.52 → 1.20.53

package/dist/commands/feed.js

@@ -1,69 +1,274 @@
 import chalk from 'chalk';
-import { ensureFeedPublishHook, listBlocks } from '../lib/feed.js';
-import { machineId } from '../lib/machine-id.js';
+import { ensureFeedPublishHook, listBlocks, recordNotified } from '../lib/feed.js';
+import { enrichBlocksFromSessions, groupBlocksByOutcome, isUnambiguousOutcomeAnswer, openBlocksForOutcome, stampBlockOutcomes, } from '../lib/feed-outcome.js';
+import { classifyBlock, filterBlocksForFeed, suppressionDigest, } from '../lib/ask-classifier.js';
+import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { relTime } from '../lib/format.js';
-function renderBlock(b, localHost) {
+import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
+import { loadPolicy, applyPolicyToBlock, isPhoneUrgent } from '../lib/feed-policy.js';
+import { notifyUrgentBlock } from '../lib/notify.js';
+import { gcMailbox } from '../lib/mailbox-gc.js';
+import { getActiveSessions } from '../lib/session/active.js';
+import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
+export const FEED_NO_FANOUT_ENV = 'AGENTS_FEED_LOCAL';
+export function parseRemoteFeed(stdout, machine) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const blocks = [];
+    for (const item of parsed) {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            continue;
+        const block = item;
+        if (!block.blockId || !block.sessionId || !block.mailboxId || !block.questions?.length)
+            continue;
+        blocks.push({ ...block, host: machine });
+    }
+    return blocks;
+}
+/** Merge local and remote rows, keeping the first copy of a host/session block. */
+export function mergeFeedBlocks(...groups) {
+    const byIdentity = new Map();
+    for (const block of groups.flat()) {
+        const key = `${normalizeHost(block.host)}:${block.blockId}`;
+        if (!byIdentity.has(key))
+            byIdentity.set(key, block);
+    }
+    return [...byIdentity.values()].sort((a, b) => Date.parse(b.ts) - Date.parse(a.ts));
+}
+function hostToken(host) {
+    return normalizeHost(host.split('@').pop() || host);
+}
+export function shouldIncludeLocalFeed(hosts, self) {
+    return !hosts?.length || hosts.some((host) => hostToken(host) === self);
+}
+export function remoteFeedHostsToDial(hosts, self) {
+    if (!hosts?.length)
+        return undefined;
+    return hosts.filter((host) => hostToken(host) !== self);
+}
+function renderBlock(b, localHost, indent = '') {
     const host = b.host !== localHost ? chalk.yellow(` [${b.host}]`) : '';
     const runtime = chalk.gray(b.runtime);
     const age = chalk.gray(relTime(b.ts));
-    console.log(`${chalk.cyan(b.mailboxId)}${host}  ${runtime}  ${age}`);
+    const cls = b.blockClass ? chalk.gray(`(${b.blockClass})`) : '';
+    const consequence = b.consequence && b.consequence !== 'normal' ? chalk.red(`[${b.consequence}]`) : '';
+    const cost = b.costOfDelay ? chalk.gray(`cost:${b.costOfDelay}`) : '';
+    console.log(`${indent}${chalk.cyan(b.mailboxId)}${host}  ${runtime}  ${age}  ${cls} ${consequence} ${cost}`.trimEnd());
     for (const question of b.questions) {
         const header = question.header ? chalk.gray(`[${question.header}] `) : '';
-        console.log(`  ${header}${question.text}`);
+        console.log(`${indent}  ${header}${question.text}`);
         if (question.options?.length) {
             for (let i = 0; i < question.options.length; i++) {
                 const o = question.options[i];
                 const desc = o.description ? chalk.gray(` -- ${o.description}`) : '';
-                console.log(`    ${chalk.dim(`${i + 1}.`)} ${o.label}${desc}`);
+                console.log(`${indent}    ${chalk.dim(`${i + 1}.`)} ${o.label}${desc}`);
             }
         }
     }
-    if (b.ticket || b.pr) {
-        const meta = [b.ticket, b.pr].filter(Boolean).join('  ');
-        console.log(`  ${chalk.gray(meta)}`);
+    if (b.ticket || b.pr || b.worktreeSlug) {
+        const meta = [b.ticket, b.pr, b.worktreeSlug].filter(Boolean).join('  ');
+        console.log(`${indent}  ${chalk.gray(meta)}`);
+    }
+    if (b.answer) {
+        const verified = b.answer.verified ? chalk.green('✓') : chalk.yellow('?');
+        const who = b.answer.answeredFrom + (b.answer.answeredBy ? ` (${b.answer.answeredBy})` : '');
+        console.log(`${indent}  ${chalk.green('answered')} by ${who} ${verified}`);
+    }
+    if (b.parkedAt) {
+        console.log(`${indent}  ${chalk.red('hard-parked')} ${relTime(b.parkedAt)}`);
+    }
+    if (b.defaultedAt) {
+        console.log(`${indent}  ${chalk.yellow('defaulted')} ${relTime(b.defaultedAt)}`);
+    }
+    if (b.receipts && b.receipts.length > 0) {
+        const latest = b.receipts[b.receipts.length - 1];
+        console.log(`${indent}  ${chalk.dim('delivery:')} ${latest.status}`);
+    }
+    if (b.continuedAt) {
+        console.log(`${indent}  ${chalk.green('continued')} ${relTime(b.continuedAt)}`);
+    }
+    if (b.notifiedAt) {
+        console.log(`${indent}  ${chalk.dim('notified')} ${relTime(b.notifiedAt)}`);
+    }
+    if (!b.answer && !b.parkedAt) {
+        console.log(`${indent}  ${chalk.dim('reply:')} agents message ${b.mailboxId} "<answer>"`);
     }
-    console.log(`  ${chalk.dim('reply:')} agents message ${b.mailboxId} "<answer>"`);
     console.log();
 }
+/** Human summary line for one outcome rollup. */
+export function formatOutcomeHeader(group) {
+    const { agents, open, answered, parked } = group.counts;
+    const parts = [
+        `${agents} agent${agents === 1 ? '' : 's'}`,
+        open > 0 ? `${open} needs you` : null,
+        answered > 0 ? `${answered} answered` : null,
+        parked > 0 ? `${parked} parked` : null,
+    ].filter(Boolean);
+    return `${group.outcome.label} · ${parts.join(' · ')}`;
+}
+function renderOutcomeGroup(group, localHost) {
+    console.log(chalk.bold(formatOutcomeHeader(group)));
+    if (isUnambiguousOutcomeAnswer(group) && openBlocksForOutcome(group).length > 1) {
+        const ids = openBlocksForOutcome(group).map((b) => b.mailboxId).join(', ');
+        console.log(chalk.dim(`  same question on ${openBlocksForOutcome(group).length} agents — fan-out safe: ${ids}`));
+    }
+    for (const b of group.blocks) {
+        renderBlock(b, localHost, '  ');
+    }
+}
+/** Map active sessions into the lightweight hints outcome enrichment needs. */
+export function sessionHintsFromActive(sessions) {
+    return sessions.map((s) => ({
+        sessionId: s.sessionId,
+        agentId: s.agentId,
+        // Same precedence as mailboxIdForActiveSession (agentId ?? sessionId).
+        mailboxId: s.agentId ?? s.sessionId,
+        ticketId: s.ticket?.id,
+        prNumber: s.pr?.number,
+        prUrl: s.pr?.url,
+        worktreeSlug: s.worktree?.slug,
+    }));
+}
 export function registerFeedCommand(program) {
     program
         .command('feed')
-        .description('List open blocks -- decisions agents are waiting on')
-        .option('--json', 'Output as JSON')
+        .description('List open blocks -- decisions agents are waiting on (grouped by outcome)')
+        .option('--json', 'Output as JSON (each block stamped with its outcome + ask class)')
+        .option('--flat', 'List one block per agent instead of grouping by outcome')
+        .option('--all', 'Include stalls/FYIs that policy would suppress (default: hide them)')
+        .option('--local', 'Only this machine -- skip the cross-machine SSH fan-out')
+        .option('-H, --host <target...>', 'Scope to remote machine(s) over SSH; repeatable')
+        .option('--device <target...>', 'Alias for --host; repeatable')
+        .option('--dispatch', 'Run stall suppression + default-on-no-answer policy and urgent notifications')
         .action(async (opts) => {
+        if (opts.device?.length)
+            opts.host = [...(opts.host ?? []), ...opts.device];
+        const self = machineId();
+        const includeLocal = shouldIncludeLocalFeed(opts.host, self);
         const setupWarnings = [];
-        const hookInstall = ensureFeedPublishHook();
-        if (hookInstall.error) {
-            setupWarnings.push(hookInstall.error);
+        if (includeLocal) {
+            const hookInstall = ensureFeedPublishHook();
+            if (hookInstall.error) {
+                setupWarnings.push(hookInstall.error);
+            }
+            else {
+                const [{ iterHooksCapableVersions, parseHookManifest, registerHooksToSettings }, { getVersionHomePath }] = await Promise.all([
+                    import('../lib/hooks.js'),
+                    import('../lib/versions.js'),
+                ]);
+                const manifest = parseHookManifest({ warn: false });
+                for (const { agent, version } of iterHooksCapableVersions({ agent: 'claude' })) {
+                    const result = registerHooksToSettings(agent, getVersionHomePath(agent, version), manifest);
+                    if (result.errors.length > 0) {
+                        setupWarnings.push(`${agent}@${version}: ${result.errors.join('; ')}`);
+                    }
+                }
+            }
+        }
+        // Active sessions feed both the GC sweep and outcome enrichment (ticket/PR).
+        let sessions = [];
+        if (includeLocal) {
+            sessions = await getActiveSessions();
+        }
+        if (opts.dispatch && includeLocal) {
+            // Liveness sweep: drop messages to dead agents and retire stale blocks
+            // before we render the feed.
+            const activeBoxIds = new Set(sessions.map(mailboxIdForActiveSession).filter((id) => !!id));
+            const gcResult = gcMailbox(activeBoxIds);
+            if (gcResult.blocksRemoved > 0 || gcResult.messagesDroppedDead > 0) {
+                console.log(chalk.yellow(`gc: ${gcResult.messagesDroppedDead} dead messages, ${gcResult.blocksRemoved} stale blocks removed`));
+            }
         }
-        else {
-            const [{ iterHooksCapableVersions, parseHookManifest, registerHooksToSettings }, { getVersionHomePath }] = await Promise.all([
-                import('../lib/hooks.js'),
-                import('../lib/versions.js'),
-            ]);
-            const manifest = parseHookManifest({ warn: false });
-            for (const { agent, version } of iterHooksCapableVersions({ agent: 'claude' })) {
-                const result = registerHooksToSettings(agent, getVersionHomePath(agent, version), manifest);
-                if (result.errors.length > 0) {
-                    setupWarnings.push(`${agent}@${version}: ${result.errors.join('; ')}`);
+        const localBlocks = includeLocal ? listBlocks() : [];
+        let blocks = localBlocks;
+        const forceLocal = opts.local === true || process.env[FEED_NO_FANOUT_ENV] === '1';
+        if (!forceLocal) {
+            const remoteHosts = remoteFeedHostsToDial(opts.host, self);
+            if (!opts.host?.length || (remoteHosts && remoteHosts.length > 0)) {
+                const remote = await gatherRemoteAgentsJson({
+                    // Bare --json stays a block array so older peers and scripts keep working.
+                    args: ['feed', '--json'],
+                    noFanoutEnv: FEED_NO_FANOUT_ENV,
+                    hosts: remoteHosts,
+                    parse: parseRemoteFeed,
+                });
+                blocks = mergeFeedBlocks(localBlocks, remote.items);
+            }
+        }
+        // Fill missing ticket/PR/worktree from live session meta so outcome keys
+        // land even when the publish hook had no deliverable stamp.
+        if (sessions.length > 0) {
+            blocks = enrichBlocksFromSessions(blocks, sessionHintsFromActive(sessions));
+        }
+        // Stall suppression (RUSH-1477): auto-answer "should I…?" / "what's next?"
+        // so they never render. Applied on every feed read unless --all; --dispatch
+        // also applies so unattended ticks drain the stall backlog.
+        const filter = filterBlocksForFeed(blocks, {
+            apply: !opts.all || opts.dispatch === true,
+        });
+        if (!opts.all) {
+            blocks = filter.surfaced;
+        }
+        const digest = suppressionDigest(filter);
+        if (digest && !opts.json) {
+            console.log(chalk.dim(digest));
+        }
+        if (opts.dispatch) {
+            const policy = loadPolicy();
+            const now = new Date();
+            for (const b of blocks) {
+                const result = applyPolicyToBlock(b, policy, now);
+                if (result.action !== 'none') {
+                    console.log(`${chalk.yellow('policy')} ${b.blockId}: ${result.action}`);
+                }
+                if (isPhoneUrgent(b, policy)) {
+                    const notifyResult = await notifyUrgentBlock(b, { dryRun: opts.json });
+                    if (notifyResult.ok && !notifyResult.skipped) {
+                        recordNotified(b.blockId);
+                        console.log(`${chalk.green('notified')} ${b.blockId}`);
+                    }
+                    else if (notifyResult.error) {
+                        console.error(chalk.yellow(`Notification failed for ${b.blockId}: ${notifyResult.error}`));
+                    }
                 }
             }
         }
-        const blocks = listBlocks();
         for (const warning of setupWarnings) {
             console.error(chalk.yellow(`Feed hook setup warning: ${warning}`));
         }
         if (opts.json) {
-            console.log(JSON.stringify(blocks, null, 2));
+            // Always a block array (stamped with outcome + ask class) so remote fan-out
+            // and scripts keep a stable contract. Human grouping is text-only.
+            const stamped = stampBlockOutcomes(blocks).map((b) => ({
+                ...b,
+                ask: classifyBlock(b),
+            }));
+            console.log(JSON.stringify(stamped, null, 2));
             return;
         }
         if (blocks.length === 0) {
-            console.log(chalk.gray('No open blocks.'));
+            console.log(chalk.gray(digest ? 'No open blocks after stall suppression.' : 'No open blocks.'));
+            return;
+        }
+        if (opts.flat) {
+            console.log(chalk.bold(`${blocks.length} open block${blocks.length === 1 ? '' : 's'}:\n`));
+            for (const b of blocks)
+                renderBlock(b, self);
             return;
         }
-        const local = machineId();
-        console.log(chalk.bold(`${blocks.length} open block${blocks.length === 1 ? '' : 's'}:\n`));
-        for (const b of blocks)
-            renderBlock(b, local);
+        const groups = groupBlocksByOutcome(blocks);
+        const openOutcomes = groups.filter((g) => g.counts.open > 0).length;
+        console.log(chalk.bold(`${groups.length} outcome${groups.length === 1 ? '' : 's'} · ${blocks.length} block${blocks.length === 1 ? '' : 's'}` +
+            (openOutcomes > 0 ? ` · ${openOutcomes} need you` : '') +
+            ':\n'));
+        for (const g of groups)
+            renderOutcomeGroup(g, self);
     });
 }

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;