@phnx-labs/agents-cli 1.22.6 → 1.22.8

package/dist/commands/feed.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildDeclaredBlock, publishBlock, } from '../lib/feed.js';
 import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate, mergeActivityEvents, parseActivityPayload, } from '../lib/activity.js';
+import { projectKeyFromCwd } from '../lib/project-key.js';
 import { postFeedStatus } from '../lib/feed-post.js';
 import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, effectiveBroadcastConfig, blockBroadcastContext, blockDeliveryFailure, } from '../lib/feed-broadcast.js';
 import { getSessionById } from '../lib/session/db.js';
@@ -215,6 +216,7 @@ export function sessionHintsFromActive(sessions) {
         prNumber: s.pr?.number,
         prUrl: s.pr?.url,
         worktreeSlug: s.worktree?.slug,
+        project: s.cwd ? projectKeyFromCwd(s.cwd) : undefined,
     }));
 }
 export function registerFeedCommand(program) {
@@ -228,6 +230,7 @@ export function registerFeedCommand(program) {
         .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('--project <name>', 'Scope the feed to one project/repo (matches cwd basename, case-insensitive)')
         .option('--dispatch', 'Run stall suppression + default-on-no-answer policy and urgent notifications')
         .option('--pause <id>', 'Pause a runaway/needy local process (SIGSTOP) or cancel a cloud task')
         .option('--kill <id>', 'Kill a runaway/needy local process (SIGTERM) or cancel a cloud task');
@@ -317,7 +320,13 @@ docs/06-observability.md.
             // it the ask would scroll away like any other update.
             let outcomes;
             if (flags.blocked) {
-                const block = buildDeclaredBlock(event, {
+                const block = buildDeclaredBlock({
+                    sessionId: event.sessionId,
+                    mailboxId: event.mailboxId,
+                    host: event.host,
+                    runtime: event.runtime,
+                    cwd: event.cwd,
+                }, {
                     // Prefer title as the front-loaded ask on the phone; body is detail.
                     text: event.title
                         ? (event.detail ? `${event.title}: ${event.detail}` : event.title)
@@ -399,12 +408,12 @@ docs/06-observability.md.
             if (filter === 'all') {
                 console.log();
                 renderUpdatesView(await gatherStatusPosts({
-                    limit: UPDATES_VIEW_LIMIT, hosts: opts.host, local: opts.local, includeLocal, self,
-                }));
+                    limit: UPDATES_VIEW_LIMIT, hosts: opts.host, local: opts.local, includeLocal, self, project: opts.project,
+                }), opts.project);
                 return;
             }
             if (includeLocal)
-                renderActivityLane();
+                renderActivityLane(opts.project);
         };
         // Updates view: deliberate progress posts only (blocks are decisions, not
         // announcements). Short-circuits the block pipeline — no dispatch policy —
@@ -425,7 +434,7 @@ docs/06-observability.md.
                 console.log(JSON.stringify(updates, null, 2));
                 return;
             }
-            renderUpdatesView(updates);
+            renderUpdatesView(updates, opts.project);
             return;
         }
         // Active sessions feed both the GC sweep and outcome enrichment (ticket/PR).
@@ -487,7 +496,10 @@ docs/06-observability.md.
                 blocks = mergeFeedBlocks(visibleLocalBlocks, remote.items);
             }
         }
-        blocks = rankFeedBlocks(blocks, localSignals);
+        blocks = rankFeedBlocks(blocks, localSignals).filter((b) => blockMatchesProject(b, opts.project));
+        const dispatchBlocksProject = opts.project
+            ? dispatchBlocks.filter((b) => blockMatchesProject(b, opts.project))
+            : dispatchBlocks;
         const digest = suppressionDigest(preparedLocal.filter);
         if (digest && !opts.json) {
             console.log(chalk.dim(digest));
@@ -495,7 +507,7 @@ docs/06-observability.md.
         if (opts.dispatch) {
             const policy = loadPolicy();
             const now = new Date();
-            for (const b of dispatchBlocks) {
+            for (const b of dispatchBlocksProject) {
                 // Wrap per-block policy so one malformed block (e.g. a crafted
                 // mailboxId that throws in mailboxDir) can't abort the whole loop and
                 // strand every remaining block's dispatch.
@@ -540,7 +552,7 @@ docs/06-observability.md.
         }
         // Shared fleet-comms masthead (same family as `agents mailboxes`).
         console.log(masthead({
-            title: 'they need you',
+            title: opts.project ? `${opts.project} needs you` : 'they need you',
             accent: 'amber',
             host: self,
             right: formatFeedMastheadRight(blocks),
@@ -630,6 +642,18 @@ export function resolveFeedFilter(raw) {
         return 'all';
     return 'needs';
 }
+/** True when a block belongs to the requested project (case-insensitive). */
+function blockMatchesProject(block, project) {
+    if (!project)
+        return true;
+    return (block.project ?? '').toLowerCase() === project.toLowerCase();
+}
+/** True when an activity event belongs to the requested project (case-insensitive). */
+function eventMatchesProject(ev, project) {
+    if (!project)
+        return true;
+    return ((ev.project ?? projectKeyFromCwd(ev.cwd) ?? '')).toLowerCase() === project.toLowerCase();
+}
 /**
  * Render one activity event in the lane: deliberate progress posts
  * (`status.posted`) use the rich multi-line {@link formatProgressUpdate}; hook
@@ -668,30 +692,33 @@ function readStatusPosts(limit) {
  * uses; `--local` (or the no-fanout env guard on a peer) keeps it to this box.
  */
 async function gatherStatusPosts(opts) {
-    const local = opts.includeLocal ? readStatusPosts(opts.limit) : [];
+    const local = opts.includeLocal
+        ? readStatusPosts(opts.limit).filter((ev) => eventMatchesProject(ev, opts.project))
+        : [];
     const forceLocal = opts.local === true || process.env[FEED_NO_FANOUT_ENV] === '1';
     if (forceLocal)
-        return local;
+        return local.slice(0, opts.limit);
     const remoteHosts = opts.hosts?.length ? remoteFeedHostsToDial(opts.hosts, opts.self) : undefined;
     if (opts.hosts?.length && (!remoteHosts || remoteHosts.length === 0))
-        return local;
+        return local.slice(0, opts.limit);
     const remote = await gatherRemoteAgentsJson({
         args: ['feed', '--filter', 'updates', '--json'],
         noFanoutEnv: FEED_NO_FANOUT_ENV,
         hosts: remoteHosts,
         parse: parseActivityPayload,
     });
-    return mergeActivityEvents(local, remote.items).slice(0, opts.limit);
+    const merged = mergeActivityEvents(local, remote.items).filter((ev) => eventMatchesProject(ev, opts.project));
+    return merged.slice(0, opts.limit);
 }
 /**
  * Render the **Updates** view: deliberate progress posts only (`status.posted`),
  * recency-ordered, with rich identity chips. Pure `file.edited` / git-hook noise
  * is excluded so operators see announcements, not tool churn.
  */
-function renderUpdatesView(updates) {
+function renderUpdatesView(updates, project) {
     const hosts = new Set(updates.map((e) => e.host).filter(Boolean));
     console.log(masthead({
-        title: 'updates',
+        title: project ? `${project} updates` : 'updates',
         accent: 'cyan',
         host: hosts.size > 1 ? `${hosts.size} machines` : (updates[0]?.host ?? machineId()),
         right: `${updates.length} post${updates.length === 1 ? '' : 's'}`,
@@ -712,16 +739,16 @@ function renderUpdatesView(updates) {
  * activity logs. Read-only tail of the logs -- no transcript re-parsing. Silent
  * when empty.
  */
-function renderActivityLane(limit = 6) {
+function renderActivityLane(project, limit = 6) {
     const events = readRecentActivity({
         sinceMs: Date.now() - 24 * 60 * 60 * 1000,
-        limit,
+        limit: limit * (project ? 4 : 1),
         tier: 'milestone',
-    });
+    }).filter((ev) => eventMatchesProject(ev, project));
     if (events.length === 0)
         return;
-    console.log(chalk.bold('\n  recent activity'));
-    for (const ev of events)
+    console.log(chalk.bold(project ? `\n  recent activity · ${project}` : '\n  recent activity'));
+    for (const ev of events.slice(0, limit))
         renderActivityEntry(ev);
-    console.log(chalk.gray('  → agents activity  for the full stream'));
+    console.log(chalk.gray('  → agents feed --project ' + (project ?? '<project>') + '  for the full stream'));
 }

package/dist/commands/focus.js

@@ -20,8 +20,9 @@ import { runOnPeer } from '../lib/session/remote-list.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { openSurfaces, currentContext, availableBackends, detectCurrentBackend, } from '../lib/terminal/index.js';
 import { isInteractiveTerminal } from './utils.js';
+import { setHelpSections } from '../lib/help.js';
 export function registerFocusCommand(program) {
-    program
+    const cmd = program
         .command('focus')
         .argument('[id]', 'Short/full session id to focus; omit for an interactive picker')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
@@ -30,6 +31,26 @@ export function registerFocusCommand(program) {
         .action(async (id, opts) => {
         await focusAction(id, opts);
     });
+    setHelpSections(cmd, {
+        examples: `
+      # Jump to a live session (attach pane/tab, or open a new tab and resume)
+      agents sessions focus a1b2c3d4
+
+      # Attach only — refuse if nothing is joinable (old sessions go)
+      agents sessions focus a1b2c3d4 --attach-only
+
+      # Pick from live sessions on this machine only
+      agents sessions focus --local
+    `,
+        notes: `
+      Lifecycle siblings (not synonyms):
+        focus              live jump (default "take me there")
+        focus --attach-only  attach only; never fork (replaces go)
+        detach / attach    interactive ↔ headless presence
+        resume             multi-select history → tabs
+        run --resume       single scripted continue
+    `,
+    });
 }
 /**
  * Which fallback fires when a session has no attach rail. `--attach-only` (the old

package/dist/commands/harness.d.ts

@@ -24,7 +24,6 @@ export interface ForkOptions {
     baseUrl?: string;
     authProvider?: string;
     version?: string;
-    label?: string;
     description?: string;
     keyStdin?: boolean;
     force?: boolean;

package/dist/commands/harness.js

@@ -12,7 +12,7 @@
  */
 import chalk from 'chalk';
 import { addProfile, ensureProviderToken } from './profiles.js';
-import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, } from '../lib/profiles.js';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, editProfile, renameProfile, } from '../lib/profiles.js';
 import { listPresets } from '../lib/profiles-presets.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName } from '../lib/agents.js';
 /** Short capability summary for a native harness — its supported run modes. */
@@ -58,7 +58,6 @@ export function buildFork(source, name, opts) {
             baseUrl: opts.baseUrl,
             provider: opts.authProvider,
             version: opts.version,
-            label: opts.label,
             description: opts.description,
         });
     }
@@ -75,7 +74,6 @@ export function buildFork(source, name, opts) {
         baseUrl: opts.baseUrl,
         provider: opts.authProvider,
         authEnvVar: opts.authProvider ? authEnvKeyForHostOrThrow(host) : undefined,
-        label: opts.label,
         description: opts.description ?? `Forked from ${host}: ${opts.model}`,
     });
 }
@@ -147,7 +145,6 @@ Examples:
         .option('--base-url <url>', 'Custom endpoint base URL (claude/codex hosts)')
         .option('--auth-provider <provider>', 'Attach a keychain-backed API key under this provider')
         .option('--version <version>', 'Pin the host CLI version (e.g., 1.16.0)')
-        .option('--label <text>', 'Human-facing name shown by `agents view` (defaults to <name>)')
         .option('--description <text>', 'One-line description')
         .option('--key-stdin', 'Read the API key from stdin instead of prompting (for scripts/CI)')
         .option('--force', 'Overwrite an existing harness with the same name')
@@ -249,4 +246,63 @@ Examples:
         }
         console.log(chalk.green(`Harness '${name}' removed.`));
     });
+    cmd
+        .command('edit <name>')
+        .description('Edit a custom harness in place (model, endpoint, host version, description).')
+        // Flags mirror ForkProfileOptions exactly — `editProfile` reuses
+        // `forkProfile`'s override logic, so anything it does not accept would be a
+        // flag that parses and does nothing. There is deliberately no --label: the
+        // header `agents view` prints is derived from the harness name.
+        .option('--model <id>', 'Swap the pinned model (e.g., meta/muse-spark-2.0)')
+        .option('--base-url <url>', 'Set or replace the endpoint base URL (claude/codex hosts)')
+        .option('--version <ver>', 'Re-pin the host CLI version. Empty string unpins (tracks latest).')
+        .option('--description <text>', 'Set the one-line description')
+        .addHelpText('after', `
+Examples:
+  # Upgrade the pinned model
+  agents harness edit spark --model meta/muse-spark-2.0
+
+  # Point to a new private endpoint
+  agents harness edit corp --base-url https://gw.corp/v2
+
+  # Track the host's latest instead of a pinned version
+  agents harness edit spark --version ""
+
+  # The display name is derived from the harness name, so to change it, rename:
+  agents harness rename spark muse-spark
+`)
+        .action((name, opts) => {
+        try {
+            const edited = editProfile(readProfile(name), opts);
+            writeProfile(edited);
+            console.log(chalk.green(`Harness '${name}' updated.`));
+            console.log(chalk.gray(`Model:  ${profileModelLabel(edited)}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('rename <name> <new-name>')
+        .description('Rename a custom harness — updates the file name and its internal name field.')
+        .addHelpText('after', `
+Examples:
+  # Rename 'spark' to 'muse'
+  agents harness rename spark muse
+
+  # Rename then run under the new name
+  agents harness rename deepseek ds && agents run ds "hello"
+`)
+        .action((name, newName) => {
+        try {
+            renameProfile(name, newName);
+            console.log(chalk.green(`Harness '${name}' renamed to '${newName}'.`));
+            console.log(chalk.gray(`Run: agents run ${newName} "hello"`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
 }

package/dist/commands/models.js

@@ -16,13 +16,13 @@ import { setTierOverride, clearTierOverride, listTierOverrides } from '../lib/mo
 import { getModelPricing } from '../lib/pricing/index.js';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import { wrapJoined } from './inspect.js';
-const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi', 'grok', 'droid'];
+const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi', 'grok', 'droid', 'pi'];
 /**
  * Agents that don't necessarily install under ~/.agents/versions (cursor ships
  * via a curl script). For these, fall back to the PATH binary and synthesize
  * a version label from the install path so cache keys stay stable.
  */
-const PATH_ONLY_AGENTS = new Set(['cursor']);
+const PATH_ONLY_AGENTS = new Set(['cursor', 'pi']);
 /** Derive a version label from the PATH-installed binary location for agents without managed versions. */
 function fallbackPathVersion(agent) {
     const src = locateModelSource(agent, 'unresolved');

package/dist/commands/monitors.js

@@ -315,9 +315,9 @@ export function registerMonitorsCommands(program) {
         .option('--notify [channel]', 'Notify the owner (notify.owner); [channel] overrides the owner channel')
         .option('--webhook-out <url>', 'POST the event to this URL')
         // PLACEMENT / hygiene
-        .option('--device <name>', 'OWNER device — the single machine that evaluates + fires (exactly-once)')
+        .option('--device <name>', 'OWNER (not body placement) — the single machine that evaluates + fires (exactly-once). See docs/00-concepts.md#placement.')
         .option('--devices <list>', 'Allowlist (comma-separated): each device fires independently')
-        .option('--run-on <host>', 'Execute the ACTION on this machine over SSH (placement)')
+        .option('--run-on <host>', 'BODY placement — execute the ACTION on this machine over SSH (same idea as run --where device:<host>)')
         .option('--rate-limit <spec>', 'Auto-pause if it fires more than N/<interval> (e.g. 5/1m)')
         .option('--disabled', 'Create the monitor paused (enable later with resume)')
         .action(async (nameOrPath, options) => {