@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/commands/mailboxes.js

@@ -2,7 +2,9 @@ import * as os from 'os';
 import * as path from 'path';
 import chalk from 'chalk';
 import { die, humanDuration, relTime, truncate, visibleWidth } from '../lib/format.js';
+import { setHelpSections } from '../lib/help.js';
 import { listBoxes, readBox, mailboxDir, isValidMailboxId, watchMessages, } from '../lib/mailbox.js';
+import { gcMailbox } from '../lib/mailbox-gc.js';
 import { GLYPH, masthead, sparkline, aggregate, hourlyCounts, graphEdges, } from '../lib/comms-render.js';
 import { getMailboxRootDir } from '../lib/state.js';
 import { getActiveSessions } from '../lib/session/active.js';
@@ -262,6 +264,21 @@ function renderBetween(boxes, a, b, json) {
         console.log(`    ${truncate(m.text.replace(/\s+/g, ' ').trim(), 100)}`);
     }
 }
+async function runGcCommand(opts) {
+    const sessions = await getActiveSessions();
+    const activeBoxIds = new Set(sessions.map(mailboxIdForActiveSession).filter((id) => !!id));
+    const result = gcMailbox(activeBoxIds);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.messagesDroppedDead === 0 && result.messagesDroppedExpired === 0) {
+        console.log(chalk.dim(`gc: ${result.boxesScanned} boxes scanned, no pending messages dropped.`));
+        return;
+    }
+    console.log(chalk.yellow(`gc: ${result.messagesDroppedDead} dead-box messages, ${result.messagesDroppedExpired} expired messages dropped ` +
+        `(${result.boxesScanned} boxes scanned, ${result.deadBoxes} dead boxes).`));
+}
 function renderGraph(boxes, filters, json) {
     const nonEmpty = boxes.filter((b) => b.messages.length > 0);
     const msgs = aggregate(nonEmpty).filter((m) => matchesFilters(m, m.toLabel, m.box, filters));
@@ -313,7 +330,7 @@ function newestMessage(box) {
     return box.messages.reduce((a, b) => (a.ts >= b.ts ? a : b));
 }
 export function registerMailboxesCommand(program) {
-    program
+    const cmd = program
         .command('mailboxes')
         .alias('mailbox')
         .argument('[id]', 'A mailbox id (session UUID / teams agentId) to inspect in full')
@@ -387,4 +404,25 @@ export function registerMailboxesCommand(program) {
         }
         renderOverview(boxes, limit, filters);
     });
+    const gcCmd = cmd
+        .command('gc')
+        .description('Run a liveness sweep: archive pending messages in dead boxes and prune stale consumed mail.')
+        .option('--json', 'Emit the GC result as JSON')
+        .action(async (_opts, command) => runGcCommand({ json: command.optsWithGlobals().json === true }));
+    setHelpSections(gcCmd, {
+        examples: `
+      # One-shot sweep using the live session set as the liveness source
+      agents mailboxes gc
+
+      # Machine-readable summary (for scripts / monitors)
+      agents mailboxes gc --json
+    `,
+        notes: `
+      A box is considered dead when no live session (the same source
+      \`agents sessions --active\` uses) owns it. Pending messages in dead boxes
+      are archived as \`dropped: dead\`; expired messages in live boxes are
+      archived as \`dropped: expired\'. Both surfaces a failure receipt back to
+      the feed store when the message carried a blockId.
+    `,
+    });
 }

package/dist/commands/message.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { spawn } from 'child_process';
 import { die } from '../lib/format.js';
+import { parseDuration } from '../lib/hooks/cache.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { getTaskById, updateTaskStatus } from '../lib/cloud/store.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
@@ -53,6 +54,7 @@ async function deliverViaMailbox(mailboxId, text, block, opts) {
         text,
         from: opts.from,
         blockId: block?.blockId,
+        ttlSeconds: opts.ttlSeconds,
     });
     if (block) {
         recordMessageReceipt(block.blockId, {
@@ -116,10 +118,19 @@ export function registerMessageCommand(program) {
         .option('--from <who>', 'Label recorded as the sender of this message')
         .option('--as <operator>', 'Verified operator id answering a high-consequence block')
         .option('--surface <surface>', 'Surface that is sending this answer (feed, terminal, etc.)', 'cli')
+        .option('--ttl <dur>', 'Delivery TTL if the message is not consumed (e.g. 30m, 1h, 24h); 0 disables expiry')
         .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.');
         }
+        let ttlSeconds;
+        if (opts.ttl !== undefined) {
+            const parsed = parseDuration(opts.ttl);
+            if (parsed == null) {
+                die(`Invalid --ttl ${JSON.stringify(opts.ttl)}: expected a duration like 30m, 1h, 24h, or 0.`);
+            }
+            ttlSeconds = parsed;
+        }
         const sessions = await getActiveSessions();
         const res = resolveMessageTarget(target, sessions, (id) => getTaskById(id) != null);
         switch (res.kind) {
@@ -152,7 +163,7 @@ export function registerMessageCommand(program) {
                     // First-answer-wins for any path that closes an open block.
                     claimBlockAnswer(block, opts);
                     if (route.kind === 'mailbox') {
-                        await deliverViaMailbox(res.id, text, block, opts);
+                        await deliverViaMailbox(res.id, text, block, { from: opts.from, ttlSeconds });
                         return;
                     }
                     if (route.kind === 'tmux' || route.kind === 'iterm' || route.kind === 'pty') {

package/dist/commands/packages.js

@@ -14,7 +14,7 @@ import { AGENTS, getAllCliStates, agentLabel, } from '../lib/agents.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { DEFAULT_REGISTRIES } from '../lib/types.js';
 import { getRegistries, setRegistry, removeRegistry, search as searchRegistries, resolvePackage, validatedNpmSpec, validatedPyPISpec, buildSkillIndex, verifySkillIntegrity, parseOwnerRepoFromRemote, } from '../lib/registry.js';
-import { cloneRepo, commitAndPush, getRemoteUrl, isGitRepo } from '../lib/git.js';
+import { cloneRepo, commitAndPush, getCurrentBranch, getRemoteUrl, isGitRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommand, installCommandCentrally, } from '../lib/commands.js';
 import { discoverSkillsFromRepo, installSkill, installSkillCentrally, } from '../lib/skills.js';
 import { discoverHooksFromRepo, installHooks, installHooksCentrally, } from '../lib/hooks.js';
@@ -335,7 +335,7 @@ When to use:
         .description('Generate a skills-index.json for a git repo and push it, making its skills discoverable via agents search/install')
         .option('--repo <alias>', 'Publish an extra repo added via `agents repo add` (default: your ~/.agents repo)')
         .option('--name <name>', 'Registry name to suggest in the output (default: the repo name)')
-        .option('--branch <branch>', 'Branch the raw URL should reference', 'main')
+        .option('--branch <branch>', 'Branch to push the index to and reference in the raw URL (default: the repo\'s current branch)')
         .option('--dry-run', 'Write the index and print the URL without committing or pushing')
         .addHelpText('after', `
 Publish walks a repo's skills/ directory, records a sha256 of every SKILL.md,
@@ -398,20 +398,29 @@ the sha256 in the index and abort on mismatch.
         for (const s of index.skills) {
             console.log(`  ${chalk.cyan(s.name)} ${chalk.gray(`sha256:${s.sha256?.slice(0, 12)}…`)}`);
         }
+        // The branch the URL references must be the branch the index actually
+        // lands on. In a real push that's whatever commitAndPush reports back
+        // (the requested --branch, else the checked-out branch); in a dry run we
+        // resolve it the same way without pushing.
+        let urlBranch;
         if (options.dryRun) {
+            urlBranch = options.branch || (await getCurrentBranch(repoDir));
             console.log(chalk.gray(`\nDry run — wrote ${indexPath} but did not commit or push.`));
         }
         else {
             const pushSpinner = ora('Committing and pushing skills-index.json...').start();
-            const result = await commitAndPush(repoDir, 'chore: update skills-index.json (agents publish)');
+            const result = await commitAndPush(repoDir, 'chore: update skills-index.json (agents publish)', options.branch);
             if (!result.success) {
                 pushSpinner.fail(`Push failed: ${result.error}`);
                 console.log(chalk.gray('The index was written locally — commit and push it manually to publish.'));
                 process.exit(1);
             }
-            pushSpinner.succeed('Pushed skills-index.json');
+            // commitAndPush always reports the pushed branch on success; the `??`
+            // only satisfies the optional return type, it is not a behavior path.
+            urlBranch = result.branch ?? (await getCurrentBranch(repoDir));
+            pushSpinner.succeed(`Pushed skills-index.json to ${urlBranch}`);
         }
-        const rawUrl = `https://raw.githubusercontent.com/${repoSlug}/${options.branch}/skills-index.json`;
+        const rawUrl = `https://raw.githubusercontent.com/${repoSlug}/${urlBranch}/skills-index.json`;
         const registryName = options.name || repoSlug.split('/')[1] || 'my-skills';
         console.log(chalk.bold('\nPublished. Share these with anyone who wants your skills:\n'));
         console.log(chalk.gray('  Index URL:'));

package/dist/commands/projects.d.ts

@@ -9,4 +9,42 @@
  * lifecycle state, plan completion, open PRs, and tickets in flight.
  */
 import type { Command } from 'commander';
+import { type LinearMilestone } from '../lib/linear-project-counts.js';
+/** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
+export declare const PROJECTS_NO_FANOUT_ENV = "AGENTS_PROJECTS_LOCAL";
+/**
+ * One compact trailing note for peers that didn't answer the `--fleet`
+ * fan-out — unreachable, running an agents-cli too old to carry `projects
+ * probe`, or too slow to finish inside the 12s SSH budget. Mirrors
+ * `formatUnreachableNote` (activity) with the probe-specific reasons; empty
+ * string when everything answered.
+ */
+export declare function formatFleetSkippedNote(skipped: string[]): string;
+/** One `projects list` row, pre-render. */
+export interface ProjectListRow {
+    name: string;
+    path: string;
+    repo: string;
+}
+/**
+ * Column widths for `projects list`, sized to the rows actually being printed.
+ * Fixed padding was the bug: home-relative roots run past 50 characters, so a
+ * hardcoded 32 pushed the repo column off its gridline on every long path.
+ * Paths longer than {@link LIST_PATH_MAX} truncate rather than widen the table.
+ */
+export declare function computeProjectListWidths(rows: ProjectListRow[]): {
+    name: number;
+    path: number;
+    repo: number;
+};
+/**
+ * A milestone's target date as a person would say it — "due tomorrow",
+ * "overdue by 3 days", "due Aug 21" — never a raw `2026-08-21` or a duration in
+ * hours. Linear stores a calendar date with no timezone, so both sides are
+ * compared at LOCAL midnight; parsing `YYYY-MM-DD` with `new Date(str)` would
+ * read it as UTC and shift the answer by a day for anyone west of Greenwich.
+ */
+export declare function formatMilestoneDue(targetDate: string, nowMs: number): string | undefined;
+/** The `next` card line: what this project is due to hit, and how far along it is. */
+export declare function formatNextMilestone(ms: LinearMilestone, nowMs: number): string;
 export declare function registerProjectsCommands(program: Command): void;