@phnx-labs/agents-cli 1.22.113 → 1.22.115

package/dist/lib/daemon-services.js

@@ -92,6 +92,11 @@ export const DAEMON_SERVICES = [
         title: 'Live session state',
         description: 'Publishes this host\'s active session metadata for sessions watch and fleet consumers.',
     },
+    {
+        id: 'feed-stream',
+        title: 'Shared feed stream',
+        description: 'Owns the one fleet feed fan-out and serves it to every reader over a socket, so N consumers cost one ssh per peer instead of N.',
+    },
     {
         id: 'session-index',
         title: 'Session-index warm',

package/dist/lib/daemon-webhooks.d.ts

@@ -35,7 +35,7 @@ export interface HostedReceiverConfig {
     /** Public Funnel exposure; omit to bind localhost only. */
     funnel?: HostedReceiverFunnel;
 }
-export interface DaemonWebhooksConfig {
+interface DaemonWebhooksConfig {
     receivers: HostedReceiverConfig[];
 }
 /** Path to `~/.agents/daemon/webhooks.yaml`. */

package/dist/lib/deeplink/register.d.ts

@@ -1,6 +1,5 @@
 export declare const AGENTS_URL_SCHEME = "agents";
-export declare const MAC_BUNDLE_ID = "dev.agents.urlhandler";
-export interface SchemeStatus {
+interface SchemeStatus {
     registered: boolean;
     platform: NodeJS.Platform;
     /** One human line: where the handler is, or why it is not registered. */
@@ -11,15 +10,6 @@ export interface SchemeStatus {
  * out of the handler command.
  */
 export declare function shQuote(p: string): string;
-/**
- * Resolve how the OS handler should invoke this CLI, as an already-quoted
- * command prefix (without the `open <url>` suffix).
- *
- * A macOS GUI app does NOT inherit the shell PATH, so the handler must use an
- * absolute path. Prefer the `agents` shim on PATH (directly executable); fall
- * back to `<node> <entry>` for a bare JS install.
- */
-export declare function resolveAgentsInvocation(platform?: NodeJS.Platform): string;
 /** The freedesktop `.desktop` entry that claims `x-scheme-handler/agents`. */
 export declare function linuxDesktopEntry(invocation: string): string;
 /**
@@ -33,10 +23,9 @@ export declare function macPlistBuddyCommands(plistPath: string): string[][];
 /** `reg add` argv lists that register the scheme under HKCU on Windows. */
 export declare function windowsRegistryCommands(invocation: string): string[][];
 export declare function linuxDesktopPath(home?: string): string;
-export declare function macAppPath(home?: string): string;
 /** Whether the handler artifact exists on disk (a cheap, side-effect-free check). */
 export declare function agentsUrlSchemeStatus(platform?: NodeJS.Platform, home?: string): SchemeStatus;
-export interface RegisterOptions {
+interface RegisterOptions {
     platform?: NodeJS.Platform;
     home?: string;
     /** Skip if already present (used by best-effort callers like setup). */
@@ -47,3 +36,4 @@ export declare function unregisterAgentsUrlScheme(opts?: {
     platform?: NodeJS.Platform;
     home?: string;
 }): SchemeStatus;
+export {};

package/dist/lib/deeplink/register.js

@@ -23,7 +23,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { getAgentsBinPath } from '../cli-entry.js';
 export const AGENTS_URL_SCHEME = 'agents';
-export const MAC_BUNDLE_ID = 'dev.agents.urlhandler';
+const MAC_BUNDLE_ID = 'dev.agents.urlhandler';
 const LINUX_DESKTOP_FILE = 'agents-url-handler.desktop';
 const MAC_APP_NAME = 'AgentsURLHandler.app';
 // ---------------------------------------------------------------------------
@@ -44,7 +44,7 @@ export function shQuote(p) {
  * absolute path. Prefer the `agents` shim on PATH (directly executable); fall
  * back to `<node> <entry>` for a bare JS install.
  */
-export function resolveAgentsInvocation(platform = os.platform()) {
+function resolveAgentsInvocation(platform = os.platform()) {
     const onPath = whichAgents(platform);
     if (onPath)
         return platform === 'win32' ? `"${onPath}"` : shQuote(onPath);
@@ -123,7 +123,7 @@ export function windowsRegistryCommands(invocation) {
 export function linuxDesktopPath(home = os.homedir()) {
     return path.join(home, '.local', 'share', 'applications', LINUX_DESKTOP_FILE);
 }
-export function macAppPath(home = os.homedir()) {
+function macAppPath(home = os.homedir()) {
     return path.join(home, 'Applications', MAC_APP_NAME);
 }
 // ---------------------------------------------------------------------------

package/dist/lib/deeplink/url.d.ts

@@ -16,14 +16,14 @@
  *   agents://session/<id>              — resume <id>, owner host resolved from the id
  *   agents://session/<id>?host=<name>  — the same, with a routing hint
  */
-export interface AgentsSessionLink {
+interface AgentsSessionLink {
     kind: 'session';
     /** The session id (or short-id/alias) to resume. */
     id: string;
     /** Optional owning-host hint; resume self-resolves the owner from the id regardless. */
     host?: string;
 }
-export interface AgentsUrlError {
+interface AgentsUrlError {
     error: string;
 }
 export declare function isDeepLinkSessionId(raw: string): boolean;
@@ -32,3 +32,4 @@ export declare function isDeepLinkSessionId(raw: string): boolean;
  * {@link AgentsUrlError} with a human reason. Never throws.
  */
 export declare function parseAgentsUrl(input: string): AgentsSessionLink | AgentsUrlError;
+export {};

package/dist/lib/device-config.d.ts

@@ -44,7 +44,7 @@ export type ConfigScope = 'user' | 'device';
  */
 export type ConfigVisibility = 'shared' | 'machine';
 /** Value type of a config key — drives validation and `--json` rendering. */
-export type ConfigType = 'string' | 'int' | 'bool' | 'string-list';
+type ConfigType = 'string' | 'int' | 'bool' | 'string-list';
 /** Fields every key carries, regardless of scope. */
 interface ConfigKeySpecBase {
     /** CLI dotted name, e.g. `interactive.host`. */
@@ -81,7 +81,7 @@ export interface ConfigEntry {
     source: ConfigSource;
 }
 /** Options scoping a read/write: a specific device (default: this machine), or the fleet-defaults layer. */
-export interface ConfigTarget {
+interface ConfigTarget {
     device?: string;
     /** Write/read the fleet-wide defaults layer (central fleet.defaults.config). */
     fleet?: boolean;
@@ -92,16 +92,8 @@ declare const DEVICE_ROLES: readonly ["worker", "personal", "desktop"];
 declare const AUTO_POOL_MODES: readonly ["workers", "all"];
 export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
 export declare function configKeySpec(name: string): ConfigKeySpec;
-/**
- * Fold the legacy config/pins stores into the current layout, once per
- * process. A failure is loud but non-fatal — config reads must keep working,
- * and the next process retries the fold. Honors AGENTS_SKIP_MIGRATION=1, the
- * same gate bootstrap's runMigration uses (tests pin it so a fork never folds
- * the developer's real ~/.agents as a side effect).
- */
-export declare function ensureDeviceConfigMigrated(): void;
-/** The fleet-defaults config layer (central `fleet.defaults.config`; {} when unset). */
-export declare function readFleetConfigDefaults(): Record<string, unknown>;
+/** Throw when `value` does not match the key's declared type or validation. */
+export declare function assertValidValue(spec: ConfigKeySpec, value: unknown): void;
 /**
  * The effective device-scope config block for `device`: fleet.defaults.config
  * overlaid with the per-device doc's config:. This is the single read path
@@ -130,9 +122,6 @@ export declare function getConfigValueAsync(name: string, opts?: ConfigTarget):
  * must not hard-fail. Asking for such a key by name still errors.
  */
 export declare function listConfig(opts?: ConfigTarget): ConfigEntry[];
-/** List user-scope config keys with their values. Used to show inherited settings
- * in per-device views without implying those keys are device-local. */
-export declare function listUserConfig(): ConfigEntry[];
 /**
  * Set a config key (validated). Device-scope keys target this machine unless
  * `opts.device` names a peer; `opts.fleet` writes the fleet-wide defaults layer

package/dist/lib/device-config.js

@@ -39,6 +39,7 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { machineId } from './machine-id.js';
 import { assertValidDeviceName, assertRegistrableDeviceName } from './devices/registry.js';
 import { migrateDeviceConfigStores } from './devices/config-migration.js';
+import { parseAddress } from './address.js';
 import { isAgentId } from './types.js';
 const DEVICE_PLATFORMS = ['windows', 'linux', 'macos', 'unknown'];
 const SSH_AUTH_METHODS = ['key', 'password'];
@@ -46,6 +47,16 @@ const SSH_AUTH_METHODS = ['key', 'password'];
 const DEVICE_ROLES = ['worker', 'personal', 'desktop'];
 /** Which devices automatic placement may pick — see the `auto.pool` key below. */
 const AUTO_POOL_MODES = ['workers', 'all'];
+/**
+ * A device's physical form factor (`formFactor` key) — a factual hardware fact
+ * the menu bar shows as an icon. Set explicitly per device (no inference from
+ * platform, no hardcoded device names). `unknown` is the effective default.
+ */
+const DEVICE_FORM_FACTORS = ['laptop', 'desktop', 'server', 'unknown'];
+/** A validate() that accepts only one of `allowed` — the enum-string keys reuse it. */
+function oneOf(name, allowed) {
+    return (v) => (allowed.includes(v) ? null : `${name} must be one of ${allowed.join(' | ')}.`);
+}
 export const CONFIG_KEYS = [
     {
         name: 'interactive.host',
@@ -133,6 +144,28 @@ export const CONFIG_KEYS = [
         type: 'string',
         description: 'Browser profile `agents browser start` resolves to without --profile (set via `agents browser use`).',
     },
+    {
+        name: 'computer.host',
+        yamlKey: 'computerHost',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        description: 'The --host address (PHNX-4090) `agents computer --device <name>` forwards to the standalone engine: ' +
+            'ssh://[user@]host[:port], vnc://host[:port], or tcp://host:port. Unset falls back to the fleet ssh ' +
+            'identity (ssh://user@host resolved against the device registry).',
+        validate: (v) => {
+            try {
+                const addr = parseAddress(v);
+                if (addr.scheme !== 'ssh' && addr.scheme !== 'vnc' && addr.scheme !== 'tcp') {
+                    return `computer.host speaks ssh://, vnc:// and tcp:// only (got ${addr.scheme}://).`;
+                }
+                return null;
+            }
+            catch (err) {
+                return err?.message ?? String(err);
+            }
+        },
+    },
     {
         name: 'browser.device',
         yamlKey: 'defaultBrowserDevice',
@@ -344,6 +377,134 @@ export const CONFIG_KEYS = [
         defaultValue: false,
         description: 'Boost this device in `--device auto` ranking (default off) — picked ahead of load-equal peers when eligible.',
     },
+    {
+        name: 'formFactor',
+        yamlKey: 'formFactor',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        defaultValue: 'unknown',
+        description: "This device's physical form factor, a factual hardware fact the menu bar renders as an icon: " +
+            'laptop, desktop, server, or unknown. Synced fleet-wide (any box may set it for any device). Set it ' +
+            'explicitly — never inferred from the OS platform. Unset reads as `unknown`.',
+        validate: oneOf('formFactor', DEVICE_FORM_FACTORS),
+    },
+    // ─── AGI Menu preferences (PHNX-3999) ──────────────────────────────────────
+    // User-scope so one value syncs fleet-wide via `agents repo push/pull` and the
+    // native menu reads it from `agents config list --json`. Names mirror the Swift
+    // MenuPreferences local-cache keys. `config list` OMITS an unset key, so the
+    // native app falls back to its own known defaults — the defaults documented
+    // here match those, they are not substituted on read.
+    {
+        name: 'menubar.menu.defaultProject',
+        yamlKey: 'menubarMenuDefaultProject',
+        scope: 'user',
+        type: 'string',
+        description: 'AGI Menu: the project name the menu opens focused on. Unset = no default project.',
+    },
+    {
+        name: 'menubar.menu.workingRowsShown',
+        yamlKey: 'menubarMenuWorkingRowsShown',
+        scope: 'user',
+        type: 'int',
+        defaultValue: 3,
+        description: 'AGI Menu: how many working (in-progress) rows to show per group — 2, 3, or 4.',
+        validate: (v) => ([2, 3, 4].includes(v) ? null : 'menubar.menu.workingRowsShown must be 2, 3, or 4.'),
+    },
+    {
+        name: 'menubar.menu.showPreviews',
+        yamlKey: 'menubarMenuShowPreviews',
+        scope: 'user',
+        type: 'bool',
+        defaultValue: true,
+        description: 'AGI Menu: show the session preview line under each row.',
+    },
+    {
+        name: 'menubar.menu.projectPriorityFilter',
+        yamlKey: 'menubarMenuProjectPriorityFilter',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'all',
+        description: 'AGI Menu: minimum project priority shown — all, urgent, high, or medium.',
+        validate: oneOf('menubar.menu.projectPriorityFilter', ['all', 'urgent', 'high', 'medium']),
+    },
+    {
+        name: 'menubar.menu.hideCompletedMilestones',
+        yamlKey: 'menubarMenuHideCompletedMilestones',
+        scope: 'user',
+        type: 'bool',
+        defaultValue: true,
+        description: 'AGI Menu: hide milestones that are fully complete.',
+    },
+    {
+        name: 'menubar.menu.bannerWhenNeedsYou',
+        yamlKey: 'menubarMenuBannerWhenNeedsYou',
+        scope: 'user',
+        type: 'bool',
+        defaultValue: true,
+        description: 'AGI Menu: show a top banner when a session needs the operator.',
+    },
+    {
+        name: 'menubar.menu.includeOtherDeviceRequests',
+        yamlKey: 'menubarMenuIncludeOtherDeviceRequests',
+        scope: 'user',
+        type: 'bool',
+        defaultValue: true,
+        description: 'AGI Menu: include needs-you requests from sessions on OTHER fleet devices.',
+    },
+    {
+        name: 'menubar.menu.groupBy',
+        yamlKey: 'menubarMenuGroupBy',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'project',
+        description: 'AGI Menu: primary grouping of rows — none, project, agent, or device.',
+        validate: oneOf('menubar.menu.groupBy', ['none', 'project', 'agent', 'device']),
+    },
+    {
+        name: 'menubar.menu.thenBy',
+        yamlKey: 'menubarMenuThenBy',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'none',
+        description: 'AGI Menu: secondary grouping within each group — none, project, agent, or device.',
+        validate: oneOf('menubar.menu.thenBy', ['none', 'project', 'agent', 'device']),
+    },
+    {
+        name: 'menubar.menu.projectScope',
+        yamlKey: 'menubarMenuProjectScope',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'cycle',
+        description: 'AGI Menu: which project issues to show — the current cycle only, or all.',
+        validate: oneOf('menubar.menu.projectScope', ['cycle', 'all']),
+    },
+    {
+        name: 'menubar.menu.projectSort',
+        yamlKey: 'menubarMenuProjectSort',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'updated',
+        description: 'AGI Menu: how projects are ordered — updated, priority, or name.',
+        validate: oneOf('menubar.menu.projectSort', ['updated', 'priority', 'name']),
+    },
+    {
+        name: 'menubar.menu.ticketSort',
+        yamlKey: 'menubarMenuTicketSort',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'priority',
+        description: 'AGI Menu: how tickets within a project are ordered — priority, updated, or title.',
+        validate: oneOf('menubar.menu.ticketSort', ['priority', 'updated', 'title']),
+    },
+    {
+        name: 'menubar.menu.showPullRequests',
+        yamlKey: 'menubarMenuShowPullRequests',
+        scope: 'user',
+        type: 'bool',
+        defaultValue: true,
+        description: 'AGI Menu: show the open pull requests section for each project.',
+    },
 ];
 /** Look up a key spec by CLI dotted name, or throw listing the known keys. */
 /**
@@ -377,7 +538,7 @@ export function configKeySpec(name) {
     return spec;
 }
 /** Throw when `value` does not match the key's declared type or validation. */
-function assertValidValue(spec, value) {
+export function assertValidValue(spec, value) {
     switch (spec.type) {
         case 'string':
             if (typeof value !== 'string' || value.length === 0) {
@@ -413,7 +574,7 @@ let migrationDone = false;
  * same gate bootstrap's runMigration uses (tests pin it so a fork never folds
  * the developer's real ~/.agents as a side effect).
  */
-export function ensureDeviceConfigMigrated() {
+function ensureDeviceConfigMigrated() {
     if (migrationDone || process.env.AGENTS_SKIP_MIGRATION === '1')
         return;
     try {
@@ -499,7 +660,7 @@ function writeDeviceDoc(device, doc) {
     atomicWriteFileSync(p, META_HEADER + yaml.stringify(doc));
 }
 /** The fleet-defaults config layer (central `fleet.defaults.config`; {} when unset). */
-export function readFleetConfigDefaults() {
+function readFleetConfigDefaults() {
     const config = readMeta().fleet?.defaults?.config;
     return config && typeof config === 'object' && !Array.isArray(config) ? config : {};
 }
@@ -609,11 +770,6 @@ export function listConfig(opts) {
         : CONFIG_KEYS;
     return visible.map((spec) => getConfigValue(spec.name, opts));
 }
-/** List user-scope config keys with their values. Used to show inherited settings
- * in per-device views without implying those keys are device-local. */
-export function listUserConfig() {
-    return CONFIG_KEYS.filter((spec) => spec.scope === 'user').map((spec) => getConfigValue(spec.name));
-}
 // ─── Writes ───────────────────────────────────────────────────────────────────
 /** The fleet manifest for a defaults write: `devices` materializes as an
  * explicit empty map (NOT 'all') so `agents apply` targets nothing until the

package/dist/lib/devices/connect.d.ts

@@ -30,13 +30,43 @@ export declare function sshTargetFor(device: DeviceProfile): string;
  */
 export declare function fleetDialTarget(device: DeviceProfile): string;
 /**
- * Wrap a remote command for the device's shell. Windows devices speak
- * PowerShell, so a bare command is run through `powershell -NoProfile
- * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
- * shell parses it). Returns undefined when no command was given (interactive
+ * Render `cmd` as the single command string ssh sends to the peer.
+ *
+ * Windows devices speak PowerShell, so the result is run through
+ * `powershell -NoProfile -EncodedCommand`; POSIX devices get it as the remote
+ * login shell sees it. Returns undefined when no command was given (interactive
  * login).
+ *
+ * TWO MODES, and the difference is load-bearing rather than a convenience.
+ *
+ * The default joins the tokens RAW. That is not a bug to be tidied away: every
+ * existing caller of `agents ssh` relies on the remote shell interpreting what it
+ * is handed — `agents ssh box 'bash -lc "cd x && make"'` arrives as ONE token
+ * whose pipeline, globs and redirections the peer's shell must expand. Quoting
+ * that would ship the whole line as a literal argument and break it.
+ *
+ * `{ argv: true }` is for a caller that genuinely holds an argv ARRAY and needs
+ * each element delivered as exactly one token. Joining those raw destroys any
+ * token containing a space or a metacharacter — `['--title', 'two words']`
+ * arrives as three tokens, and `'a & b'` arrives as a backgrounded command — which
+ * is what a native client hitting this path actually hit.
+ *
+ * So fidelity is opt-in at the call site that knows which shape it has, and the
+ * quoting itself reuses the canonical helpers (`shellQuote`, {@link pwshQuote})
+ * rather than introducing a third escaping scheme.
  */
-export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
+export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[], opts?: {
+    argv?: boolean;
+    prelude?: string[];
+}): string | undefined;
+/**
+ * Single-quote one token for PowerShell's OWN parser. Inside a single-quoted pwsh
+ * string the only special character is `'`, escaped by doubling.
+ *
+ * This is correct for a value PowerShell itself consumes, and NOT sufficient for
+ * an argument handed on to a native program — see the Win32 note below.
+ */
+export declare function pwshQuote(token: string): string;
 /**
  * True when `cmd` is a browser drive: `agents browser …`, `ag browser …`, or
  * the standalone `browser` binary (`cli/package.json` `bin.browser` →
@@ -65,6 +95,19 @@ export declare function isAgentsBrowserDrive(cmd: string[]): boolean;
  * fan-out stamps the marker before {@link buildSshInvocation}) is left unchanged
  * so nothing is doubled.
  */
+/**
+ * The provenance prefix as READY SHELL SYNTAX for the device's shell.
+ *
+ * These tokens are already quoted/escaped for their target shell — a POSIX
+ * `K=V` pair is `shellQuote`d here, and a PowerShell assignment is a complete
+ * statement with its own doubled quotes. That matters because argv mode quotes
+ * every token it is handed: quoting THESE again turns
+ * `'AGENTS_ACTOR=Some Name'` into `''\''AGENTS_ACTOR=Some Name'\'''` and turns a
+ * pwsh assignment into an inert string literal. So the prelude is composed
+ * SEPARATELY from the caller's argv rather than concatenated into it, and this is
+ * the single definition both paths use.
+ */
+export declare function fleetRemotePrelude(device: Pick<DeviceProfile, 'shell'>, provenanceEnv?: Record<string, string>): string[];
 export declare function markFleetRemote(cmd: string[], device: Pick<DeviceProfile, 'shell'>, provenanceEnv?: Record<string, string>): string[];
 /**
  * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
@@ -91,7 +134,7 @@ export declare function markFleetRemote(cmd: string[], device: Pick<DeviceProfil
  */
 export declare function buildInteractiveShellCommand(device: DeviceProfile, mirrorCwd: string | undefined): string | undefined;
 /** Host-key posture for {@link buildSshInvocation}. */
-export interface SshHostKeyOptions {
+interface SshHostKeyOptions {
     /**
      * True when the device's host key is already pinned in the managed
      * known_hosts store — connections then verify with `StrictHostKeyChecking=yes`
@@ -136,6 +179,7 @@ export declare function deviceIdentityArgs(device: DeviceProfile): string[];
 export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string, hostKey?: SshHostKeyOptions, opts?: {
     agentOnly?: boolean;
     interactiveCwd?: string;
+    argv?: boolean;
 }): {
     args: string[];
     env: Record<string, string>;
@@ -162,3 +206,4 @@ export declare function buildAskpassShimBody(launch?: {
  * protocol back into the CLI, which then resolves the bundle.
  */
 export declare function writeAskpassShim(): string;
+export {};