@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/commands.js

@@ -1,11 +1,3 @@
-/**
- * Slash command management -- discovery, installation, and syncing.
- *
- * Commands are markdown files in ~/.agents/commands/ exposed as `/command-name`
- * shortcuts by agents. This module discovers them, converts between formats
- * (markdown for Claude/Codex, TOML for Gemini), and installs them into
- * agent version homes.
- */
 import * as fs from 'fs';
 import { compareVersions } from './agent-spec/primitives.js';
 import { installedReleaseFor } from './installations/store.js';
@@ -37,11 +29,6 @@ function parseAgentsField(raw) {
     }
     return out.length > 0 ? out : undefined;
 }
-/**
- * Whether a slash command should sync to the given agent@version. Checks
- * frontmatter `agents` / `since` / `until` after the agent-level commands
- * (or commands-as-skills) capability gate.
- */
 export function commandAppliesTo(agent, version, metadata) {
     if (!supports(agent, 'commands', version).ok && !shouldInstallCommandAsSkill(agent, version)) {
         return { ok: false, reason: 'unsupported' };
@@ -75,7 +62,6 @@ function explainCommandSkip(agent, version, commandName, result) {
             return `${tag}: /${commandName} skipped`;
     }
 }
-/** Parse command metadata (name, description, targeting) from YAML frontmatter or TOML headers. */
 export function parseCommandMetadata(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
@@ -83,7 +69,6 @@ export function parseCommandMetadata(filePath) {
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
         const lines = content.split('\n');
-        // Check for YAML frontmatter
         if (lines[0] === '---') {
             const endIndex = lines.slice(1).findIndex((l) => l === '---');
             if (endIndex > 0) {
@@ -99,7 +84,6 @@ export function parseCommandMetadata(filePath) {
                 };
             }
         }
-        // Check for TOML format
         const tomlNameMatch = content.match(/name\s*=\s*"([^"]+)"/);
         const tomlDescMatch = content.match(/description\s*=\s*"([^"]+)"/);
         if (tomlNameMatch || tomlDescMatch) {
@@ -108,14 +92,12 @@ export function parseCommandMetadata(filePath) {
                 description: tomlDescMatch?.[1] || '',
             };
         }
-        // No valid frontmatter found
         return null;
     }
     catch {
         return null;
     }
 }
-/** Validate command metadata, returning errors and warnings. */
 function validateCommandMetadata(metadata, commandName) {
     const errors = [];
     const warnings = [];
@@ -123,12 +105,9 @@ function validateCommandMetadata(metadata, commandName) {
         errors.push('Missing YAML frontmatter with name and description');
         return { valid: false, errors, warnings };
     }
-    // name is optional - if not provided, will use filename (commandName)
-    // Only validate length if name is explicitly provided
     if (metadata.name && metadata.name.length > 64) {
         warnings.push(`name exceeds 64 characters (${metadata.name.length})`);
     }
-    // description is required
     if (!metadata.description || metadata.description.trim() === '') {
         errors.push('Missing required field: description');
     }
@@ -137,7 +116,6 @@ function validateCommandMetadata(metadata, commandName) {
     }
     return { valid: errors.length === 0, errors, warnings };
 }
-/** Discover all command markdown files in a repository's commands/ directory. */
 export function discoverCommands(repoPath) {
     const commands = [];
     const commandsDir = path.join(repoPath, 'commands');
@@ -172,7 +150,6 @@ function extractDescription(content) {
     const firstLine = content.split('\n').find((l) => l.trim() && !l.startsWith('---'));
     return firstLine?.slice(0, 80) || '';
 }
-/** Find the source path for a command in a repository. */
 export function resolveCommandSource(repoPath, commandName) {
     const commandPath = path.join(repoPath, 'commands', `${commandName}.md`);
     if (fs.existsSync(commandPath)) {
@@ -180,9 +157,7 @@ export function resolveCommandSource(repoPath, commandName) {
     }
     return null;
 }
-/** Install a command into an agent's config directory, with optional format conversion. */
 export function installCommand(sourcePath, agentId, commandName, method = 'symlink') {
-    // Validate command metadata before installation
     const metadata = parseCommandMetadata(sourcePath);
     const validation = validateCommandMetadata(metadata, commandName);
     if (!validation.valid) {
@@ -216,8 +191,6 @@ export function installCommand(sourcePath, agentId, commandName, method = 'symli
             return { path: '', method: 'copy', error: installed.error, warnings: validation.warnings };
         }
     }
-    // Goose: a slash command is a recipe YAML registered in config.yaml, not a
-    // native command file under commandsSubdir.
     if (agentId === 'goose') {
         const result = installGooseCommandToVersion(home, commandName, sourcePath);
         if (!result.success) {
@@ -251,17 +224,10 @@ export function installCommand(sourcePath, agentId, commandName, method = 'symli
     fs.copyFileSync(sourcePath, targetPath);
     return { path: targetPath, method: 'copy', warnings: validation.warnings };
 }
-/**
- * Path to the commands dir of a specific version home (not the active one).
- * Respects per-agent commandsSubdir (e.g. 'prompts' for codex).
- */
 export function getVersionCommandsDir(agent, version) {
     const home = getVersionHomePath(agent, version);
     return path.join(home, agentConfigDirName(agent), AGENTS[agent].commandsSubdir);
 }
-/**
- * List command names (without extension) installed in a specific version home.
- */
 export function listCommandsInVersionHome(agent, version) {
     const versionHome = getVersionHomePath(agent, version);
     const agentDir = path.join(versionHome, agentConfigDirName(agent));
@@ -280,10 +246,6 @@ export function listCommandsInVersionHome(agent, version) {
         .map((f) => f.slice(0, -ext.length))
         .sort();
 }
-/**
- * Check if a command installed in a specific version matches the central source.
- * Handles markdown-to-TOML conversion for Gemini.
- */
 function versionCommandMatches(agent, version, commandName) {
     const sourcePath = path.join(getCommandsDir(), `${commandName}.md`);
     if (!fs.existsSync(sourcePath))
@@ -314,18 +276,6 @@ function versionCommandMatches(agent, version, commandName) {
         return false;
     }
 }
-/**
- * Compare a version home's commands against central. Returns the reconciliation diff.
- */
-/**
- * Flattened names of plugin-bundled commands (`<plugin>-<command>`), matching
- * exactly how `syncPluginToVersion` installs a plugin's `commands/<cmd>.md` as a
- * command-skill (plugins.ts → `installCommandSkillToVersion(agentDir,
- * `${plugin.name}-${cmd}`, …)`). These are source-managed by their plugin, so
- * the orphan detector must NOT flag them — else `prune cleanup` proposes
- * deleting live plugin commands (swarm-plan, code-review, …). Scans user +
- * system + extra marketplaces (no project layer), matching the trusted sources.
- */
 export function listPluginCommandNames() {
     const names = new Set();
     for (const plugin of discoverPlugins()) {
@@ -367,9 +317,6 @@ export function diffVersionCommands(agent, version) {
             }
             continue;
         }
-        // A plugin-bundled command (installed as `<plugin>-<cmd>`) is source-managed
-        // by its plugin — not an orphan. Only a name with no central AND no plugin
-        // source is genuinely unmanaged.
         if (pluginCommands.has(name))
             continue;
         orphans.push(name);
@@ -384,10 +331,6 @@ export function diffVersionCommands(agent, version) {
         orphans: orphans.sort(),
     };
 }
-/**
- * Install a single command from central into a specific version home.
- * Handles markdown-to-TOML conversion when the agent requires it.
- */
 export function installCommandToVersion(agent, version, commandName, method = 'copy') {
     const sourcePath = path.join(getCommandsDir(), `${commandName}.md`);
     if (!fs.existsSync(sourcePath)) {
@@ -411,8 +354,6 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
         if (!installed.success)
             return installed;
     }
-    // Goose: a slash command is a recipe YAML registered in config.yaml, not a
-    // native command file. Write the recipe + slash_commands entry.
     if (agent === 'goose') {
         return installGooseCommandToVersion(versionHome, commandName, sourcePath);
     }
@@ -441,10 +382,6 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
     }
     return { success: true };
 }
-/**
- * Remove a single command from a specific version home.
- * Soft-deletes to ~/.agents/.trash/commands/.
- */
 export function removeCommandFromVersion(agent, version, commandName) {
     const versionHome = getVersionHomePath(agent, version);
     const agentDir = path.join(versionHome, agentConfigDirName(agent));
@@ -476,10 +413,6 @@ export function removeCommandFromVersion(agent, version, commandName) {
     }
     return { success: true };
 }
-/**
- * Iterate all (agent, version) pairs that support commands and are installed,
- * optionally scoped to a single agent/version.
- */
 export function iterCommandsCapableVersions(filter) {
     const pairs = [];
     const agents = filter?.agent ? [filter.agent] : capableAgents('commands');
@@ -495,7 +428,6 @@ export function iterCommandsCapableVersions(filter) {
     }
     return pairs;
 }
-/** Remove a command from an agent's config directory. */
 export function uninstallCommand(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -508,7 +440,6 @@ export function uninstallCommand(agentId, commandName) {
     }
     return false;
 }
-/** List command names installed for an agent in the active version home. */
 function listInstalledCommands(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -522,9 +453,6 @@ function listInstalledCommands(agentId) {
         .filter((f) => f.endsWith(ext))
         .map((f) => f.replace(ext, ''));
 }
-/**
- * Check if a command exists for an agent.
- */
 function commandExists(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -533,16 +461,9 @@ function commandExists(agentId, commandName) {
     const targetPath = path.join(commandsDir, `${commandName}${ext}`);
     return fs.existsSync(targetPath);
 }
-/**
- * Normalize content for comparison (trim, normalize line endings).
- */
 function normalizeContent(content) {
     return content.replace(/\r\n/g, '\n').trim();
 }
-/**
- * Check if installed command content matches source content.
- * Handles format conversion (markdown to TOML for Gemini).
- */
 function commandContentMatches(agentId, commandName, sourcePath) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -567,12 +488,6 @@ function commandContentMatches(agentId, commandName, sourcePath) {
         return false;
     }
 }
-/**
- * Get the project-scoped commands directory for an agent.
- * Claude: .claude/commands/
- * Codex: .codex/prompts/
- * Cursor: .cursor/commands/
- */
 function getProjectCommandsDirs(agentId, cwd = process.cwd()) {
     const agent = AGENTS[agentId];
     const dirs = [];
@@ -583,9 +498,6 @@ function getProjectCommandsDirs(agentId, cwd = process.cwd()) {
     dirs.push(path.join(cwd, `.${agentId}`, agent.commandsSubdir));
     return dirs;
 }
-/**
- * List commands from a specific directory.
- */
 function listCommandsFromDir(dir, exts) {
     if (!fs.existsSync(dir)) {
         return [];
@@ -595,10 +507,6 @@ function listCommandsFromDir(dir, exts) {
         .filter((f) => exts.some(ext => f.endsWith(ext)))
         .map((f) => f.replace(/\.(md|toml)$/, ''));
 }
-/**
- * List installed commands with scope information.
- * Pass options.home to read from a version-managed agent's home directory.
- */
 export function listInstalledCommandsWithScope(agentId, cwd = process.cwd(), options) {
     const agent = AGENTS[agentId];
     const ext = agent.format === 'toml' ? '.toml' : '.md';
@@ -617,7 +525,6 @@ export function listInstalledCommandsWithScope(agentId, cwd = process.cwd(), opt
         });
         seen.add(name);
     };
-    // Project-scoped commands (new .agents/commands takes precedence over agent-specific project dirs)
     const projectDirs = getProjectCommandsDirs(agentId, cwd);
     for (const projectDir of projectDirs) {
         const projectExts = ['.md', '.toml'];
@@ -626,7 +533,6 @@ export function listInstalledCommandsWithScope(agentId, cwd = process.cwd(), opt
             addCommand(name, 'project', projectDir, projectExts);
         }
     }
-    // User-scoped commands (version-aware when home is provided)
     const home = options?.home || getEffectiveHome(agentId);
     const userCommandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     const userExts = [ext];
@@ -636,9 +542,6 @@ export function listInstalledCommandsWithScope(agentId, cwd = process.cwd(), opt
     }
     return results;
 }
-/**
- * Get command description from file.
- */
 function getCommandDescription(filePath) {
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
@@ -648,12 +551,7 @@ function getCommandDescription(filePath) {
         return undefined;
     }
 }
-/**
- * Install a command to central ~/.agents/commands/ directory.
- * Shims will symlink this to per-agent directories for synced agents.
- */
 export function installCommandCentrally(sourcePath, commandName) {
-    // Validate command metadata before installation
     const metadata = parseCommandMetadata(sourcePath);
     const validation = validateCommandMetadata(metadata, commandName);
     if (!validation.valid) {
@@ -668,7 +566,6 @@ export function installCommandCentrally(sourcePath, commandName) {
     if (!fs.existsSync(centralDir)) {
         fs.mkdirSync(centralDir, { recursive: true });
     }
-    // Always use markdown for central storage
     const targetPath = path.join(centralDir, `${commandName}.md`);
     if (fs.existsSync(targetPath)) {
         fs.unlinkSync(targetPath);
@@ -681,10 +578,6 @@ export function installCommandCentrally(sourcePath, commandName) {
         return { success: false, path: '', error: err.message };
     }
 }
-/**
- * List commands from user (~/.agents/commands/) and system (~/.agents/.system/commands/) dirs.
- * User dir takes priority; deduplication preserves first occurrence.
- */
 export function listCentralCommands() {
     const seen = new Set();
     for (const dir of [getUserCommandsDir(), getCommandsDir()]) {
@@ -692,8 +585,6 @@ export function listCentralCommands() {
             continue;
         for (const f of fs.readdirSync(dir).filter((f) => f.endsWith('.md'))) {
             const name = f.replace('.md', '');
-            // A directory's README/AGENTS/CLAUDE/GEMINI documents the dir, it is not a
-            // command. Without this the picker offers a name resolveResource refuses.
             if (isDirectoryDoc('commands', name))
                 continue;
             seen.add(name);
@@ -701,9 +592,6 @@ export function listCentralCommands() {
     }
     return Array.from(seen);
 }
-/**
- * Get detailed info about a command from central storage.
- */
 export function getCommandInfo(name) {
     const centralDir = getCommandsDir();
     const cmdPath = path.join(centralDir, `${name}.md`);

package/dist/lib/comms-render.d.ts

@@ -11,7 +11,6 @@ export declare const GLYPH: {
     readonly thread: "⇄";
 };
 type Accent = 'cyan' | 'amber';
-/** Render the shared one-line comms header, with `right` aligned to the terminal edge. */
 export declare function masthead(o: {
     title: string;
     host: string;
@@ -19,17 +18,13 @@ export declare function masthead(o: {
     right?: string;
     stats?: string[];
 }): string;
-/** Normalize non-negative counts across the eight Unicode sparkline levels. */
 export declare function sparkline(counts: number[]): string;
-/** Flatten mailbox histories into one newest-first communication stream. */
 export declare function aggregate(boxes: {
     id: string;
     label: string;
     messages: import('./mailbox.js').StoredMessage[];
 }[]): CommsMsg[];
-/** Count messages in rolling one-hour buckets, ordered oldest to newest. */
 export declare function hourlyCounts(msgs: CommsMsg[], hours: number, now?: Date): number[];
-/** Aggregate the human-readable sender-to-recipient routes, busiest first. */
 export declare function graphEdges(msgs: CommsMsg[]): {
     from: string;
     to: string;

package/dist/lib/comms-render.js

@@ -10,7 +10,6 @@ export const GLYPH = {
     stream: '─→',
     thread: '⇄',
 };
-/** Render the shared one-line comms header, with `right` aligned to the terminal edge. */
 export function masthead(o) {
     const accent = o.accent === 'cyan' ? chalk.cyan : chalk.yellow;
     const title = `${accent('⌁')} ${chalk.bold(accent(o.title))}`;
@@ -24,7 +23,6 @@ export function masthead(o) {
     return `${left}${' '.repeat(gap)}${right}`;
 }
 const SPARK_LEVELS = '▁▂▃▄▅▆▇█';
-/** Normalize non-negative counts across the eight Unicode sparkline levels. */
 export function sparkline(counts) {
     if (counts.length === 0)
         return ' ';
@@ -36,7 +34,6 @@ export function sparkline(counts) {
         .map((count) => SPARK_LEVELS[Math.round((count / max) * (SPARK_LEVELS.length - 1))])
         .join('');
 }
-/** Flatten mailbox histories into one newest-first communication stream. */
 export function aggregate(boxes) {
     return boxes
         .flatMap((box) => {
@@ -54,7 +51,6 @@ export function aggregate(boxes) {
         .sort((a, b) => compareText(b.ts, a.ts));
 }
 const HOUR_MS = 60 * 60 * 1_000;
-/** Count messages in rolling one-hour buckets, ordered oldest to newest. */
 export function hourlyCounts(msgs, hours, now = new Date()) {
     const bucketCount = Number.isFinite(hours) ? Math.max(0, Math.floor(hours)) : 0;
     const counts = Array.from({ length: bucketCount }, () => 0);
@@ -71,7 +67,6 @@ export function hourlyCounts(msgs, hours, now = new Date()) {
     }
     return counts;
 }
-/** Aggregate the human-readable sender-to-recipient routes, busiest first. */
 export function graphEdges(msgs) {
     const edges = new Map();
     for (const message of msgs) {

package/dist/lib/computer/context.d.ts

@@ -34,20 +34,14 @@
  * so the engine never re-enters agents-cli and there is exactly one direction of
  * dependency.
  */
-/** A `--device <name>` target, resolved against the fleet. */
 export interface ComputerTargetContext {
-    /** The device name as the user typed it. */
     alias: string;
-    /** `user@host`, already validated against ssh option injection. */
     host: string;
     user: string;
-    /** Bare host — the ssh-config Host name or address, without the user. */
     hostname: string;
     platform: string;
-    /** Per-device ssh identity flags, in argv order. Possibly empty. */
     sshArgs: string[];
 }
-/** Who is acting, so the engine can stamp the action it reports back. */
 interface ComputerSessionContext {
     sessionId?: string;
     launchId?: string;
@@ -65,27 +59,10 @@ interface ComputerContext {
     session: ComputerSessionContext;
 }
 interface BuildContextOptions {
-    /** `--device <name>`, if given. */
     device?: string;
-    /** Direct host targeting, which bypasses fleet resolution. */
     host?: string;
-    /** Resolved path of the standalone executable, for the peer allow list. */
     computerBin?: string;
-    /**
-     * A precomputed target (PHNX-4090: `resolveDeviceHost` in `commands/computer.ts`
-     * already resolved the device's `computer.host` config, or the ssh fallback).
-     * When present, `device` is used only to gate the local-permissions branch
-     * below — this skips a second, possibly Windows-gated, fleet resolution.
-     */
     target?: ComputerTargetContext;
 }
-/**
- * Build the context handed to the engine on fd 3.
- *
- * `device` resolution goes through the shared fleet resolver and keeps the
- * Windows expectation the computer subsystem has always enforced — a
- * `--device` pointing at a Mac gets the same refusal as before, from the fleet
- * layer that can actually see the device's platform.
- */
 export declare function buildComputerContext(opts?: BuildContextOptions): Promise<ComputerContext>;
 export {};

package/dist/lib/computer/context.js

@@ -37,10 +37,6 @@
 import { resolveActor } from '../actor.js';
 import { loadComputerAllowList, loadDefaultPeers } from './policy.js';
 import { resolveRemoteDevice } from '../ssh-tunnel.js';
-/**
- * Which agent session is acting. Same precedence the admission cache used
- * before the extraction — the harness-native id first, then agents' own.
- */
 function agentSessionId(env = process.env) {
     return env.CODEX_THREAD_ID
         || env.CLAUDE_CODE_SESSION_ID
@@ -50,14 +46,6 @@ function agentSessionId(env = process.env) {
         || env.AGENTS_RUN_ID
         || undefined;
 }
-/**
- * Build the context handed to the engine on fd 3.
- *
- * `device` resolution goes through the shared fleet resolver and keeps the
- * Windows expectation the computer subsystem has always enforced — a
- * `--device` pointing at a Mac gets the same refusal as before, from the fleet
- * layer that can actually see the device's platform.
- */
 export async function buildComputerContext(opts = {}) {
     let target = opts.target;
     if (!target && opts.device) {
@@ -79,8 +67,6 @@ export async function buildComputerContext(opts = {}) {
         ...(!opts.device && !opts.host && !process.env.COMPUTER_HELPER_TCP && !process.env.COMPUTER_HELPER_VNC
             ? { permissions: { allow: loadComputerAllowList() } } : {}),
         peers: { allow: loadDefaultPeers({ computerBin: opts.computerBin }) },
-        // Spread rather than assigned: a local invocation must not ship a `target`
-        // key at all, so the engine never has to distinguish absent from null.
         ...(target ? { target } : {}),
         session: {
             sessionId: agentSessionId(),

package/dist/lib/computer/policy.d.ts

@@ -1,24 +1,4 @@
-/** Resolve Agents permission groups and caller identities for the standalone
- * engine. The engine alone writes helper policy and peer files. */
 export declare function loadComputerAllowList(): string[];
-/**
- * Default peer set: the standalone `computer` executable, this `agents` CLI's
- * own runtime, plus Rush.app if it's installed. realpath() the symlink chain so
- * we record the on-disk path the helper will see via proc_pidpath, not the shim
- * path.
- *
- * The standalone's path is the one that changed with PHNX-4075: the daemon's
- * caller is now the engine process, not this CLI. `agents`' own execPath stays
- * on the list because the engine may be a `.js` bin run through this same
- * runtime (`invocation()` in computer-client.ts), in which case proc_pidpath
- * still reports the runtime.
- *
- * Why path-based instead of codesign-team-id? The agents CLI is unsigned
- * today (npm distribution), and even if we sign Rush.app the team-id
- * check would need a separate roundtrip. Path is concrete and fast; the
- * daemon already runs as the user so anyone who can swap a binary at
- * these paths can do worse via other means.
- */
 export declare function loadDefaultPeers(opts?: {
     computerBin?: string;
 }): string[];

package/dist/lib/computer/policy.js

@@ -1,13 +1,6 @@
-/** Resolve Agents permission groups and caller identities for the standalone
- * engine. The engine alone writes helper policy and peer files. */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getUserPermissionsDir, getPermissionsDir } from '../state.js';
-// Walk all permission group YAMLs (user dir wins on name collision) and
-// collect Computer(<bundle-id>) patterns from each group's `allow:` list.
-// Returns distinct bundle ids. Line-by-line regex extraction matches
-// buildPermissionsFromGroups: YAML parsers stumble on the nested quotes in
-// some rule values, but the strict pattern below catches our shape cleanly.
 export function loadComputerAllowList() {
     const seenFiles = new Set();
     const allowed = new Set();
@@ -27,7 +20,6 @@ export function loadComputerAllowList() {
                 continue;
             if (!entry.name.endsWith('.yml') && !entry.name.endsWith('.yaml'))
                 continue;
-            // User dir wins on filename collision.
             const stem = entry.name.replace(/\.(yaml|yml)$/, '');
             if (seenFiles.has(stem))
                 continue;
@@ -40,9 +32,6 @@ export function loadComputerAllowList() {
             catch {
                 continue;
             }
-            // Strict regex: optional whitespace, dash, quoted Computer(<id>).
-            // Only honors `allow:` lines — `deny:` Computer patterns would be a
-            // contradiction (everything is deny-by-default already).
             let inAllow = false;
             for (const rawLine of content.split('\n')) {
                 const line = rawLine.replace(/\r$/, '');
@@ -64,24 +53,6 @@ export function loadComputerAllowList() {
     }
     return [...allowed].sort();
 }
-/**
- * Default peer set: the standalone `computer` executable, this `agents` CLI's
- * own runtime, plus Rush.app if it's installed. realpath() the symlink chain so
- * we record the on-disk path the helper will see via proc_pidpath, not the shim
- * path.
- *
- * The standalone's path is the one that changed with PHNX-4075: the daemon's
- * caller is now the engine process, not this CLI. `agents`' own execPath stays
- * on the list because the engine may be a `.js` bin run through this same
- * runtime (`invocation()` in computer-client.ts), in which case proc_pidpath
- * still reports the runtime.
- *
- * Why path-based instead of codesign-team-id? The agents CLI is unsigned
- * today (npm distribution), and even if we sign Rush.app the team-id
- * check would need a separate roundtrip. Path is concrete and fast; the
- * daemon already runs as the user so anyone who can swap a binary at
- * these paths can do worse via other means.
- */
 export function loadDefaultPeers(opts = {}) {
     const out = new Set();
     const add = (p) => {
@@ -92,16 +63,10 @@ export function loadDefaultPeers(opts = {}) {
             out.add(p);
         }
     };
-    // The standalone engine — the process that actually opens the socket now.
     if (opts.computerBin)
         add(opts.computerBin);
-    // The runtime currently running this CLI. Still a possible proc_pidpath when
-    // the engine is a .js bin executed through it.
     if (process.execPath)
         add(process.execPath);
-    // Rush.app — the consumer Electron client. Both the helper-binary and
-    // the main app binary are possible callers depending on how Rush wires
-    // the RPC client.
     const rushCandidates = [
         '/Applications/Rush.app/Contents/MacOS/Rush',
         '/Applications/Rush.app/Contents/MacOS/Electron',
@@ -112,14 +77,6 @@ export function loadDefaultPeers(opts = {}) {
     }
     return [...out].sort();
 }
-/**
- * Parse a `host:port` VNC endpoint, defaulting the port to 5901. Pure.
- *
- * Kept on the consumer side because the `--vnc` FLAG is parsed here — the
- * platform gate has to know whether a remote desktop was named before the
- * engine is ever spawned (see `shouldBlockOffPlatform`). The RFB protocol
- * implementation itself went to the engine.
- */
 function parseVncEndpoint(raw) {
     if (!raw || raw.length === 0)
         return null;
@@ -131,11 +88,6 @@ function parseVncEndpoint(raw) {
         return null;
     return { host: host || '127.0.0.1', port };
 }
-// Resolve the TCP endpoint for a remote daemon (the Windows helper), if
-// configured. That helper binds loopback TCP and is reached over an `ssh -L`
-// tunnel, so the endpoint is a local forwarded port. COMPUTER_HELPER_TCP is
-// "host:port" (host defaults to 127.0.0.1); COMPUTER_HELPER_TOKEN is the shared
-// secret sent in the first `auth` frame.
 export function resolveTcpEndpoint() {
     const raw = process.env.COMPUTER_HELPER_TCP;
     if (!raw || raw.length === 0)
@@ -147,11 +99,6 @@ export function resolveTcpEndpoint() {
     const token = process.env.COMPUTER_HELPER_TOKEN;
     return { host: hostPart || '127.0.0.1', port, token: token && token.length > 0 ? token : null };
 }
-// Resolve the VNC/RFB endpoint for driving a remote GUI desktop over the RFB
-// protocol (an x11vnc/Xvnc server — e.g. a headless Linux desktop or an LXD
-// container exposing x11vnc on the host's Tailscale IP). COMPUTER_HELPER_VNC is
-// "host:port" (port defaults to 5901); COMPUTER_HELPER_VNC_PASSWORD is the VNC
-// password.
 export function resolveVncEndpoint() {
     const parsed = parseVncEndpoint(process.env.COMPUTER_HELPER_VNC);
     if (!parsed)

package/dist/lib/computer/record.d.ts

@@ -1,38 +1,5 @@
-/**
- * record.ts — turn the engine's NDJSON action events into agents-cli's own
- * records: a feed event and a row in the computer-session history that
- * `agents computer sessions` and `agents sessions --computer` read.
- *
- * WHY THIS STAYS HERE. The feed, the actor registry, and `sessions.db` are
- * agents-cli state. Handing the standalone engine a writer for all three would
- * have made it a second author of the session index — precisely the
- * "one engine, one executor" rule the repo holds elsewhere. Instead the engine
- * reports what it did on fd 4 and agents-cli, which owns those stores, records it.
- *
- * Before PHNX-4075 this was `emitComputerAction`, called inline by each verb in
- * the same process. The behavior is unchanged; only the trigger moved from a
- * function call to a line on a pipe.
- *
- * WHAT THE ENGINE OWNS, AND IS NOT REWRITTEN HERE: the action's identity. The
- * engine mints the `invocationId` that groups a whole run into one session row,
- * names the `host` it drove, and echoes back the session/launch/actor it was
- * handed. Re-deriving any of those from this process would describe the CLI that
- * spawned the engine rather than the run that happened — and for `--device` the
- * two genuinely differ.
- */
 import type { ComputerActionEvent } from '../computer-client.js';
-/**
- * Fallback grouping id for an engine that reported no `invocationId` of its own.
- * One per `agents computer` process, so such a run still collapses to a single
- * session row instead of N unrelated ones.
- */
 export declare const COMPUTER_INVOCATION_ID: `${string}-${string}-${string}-${string}-${string}`;
-/**
- * Record one action the engine performed. Never throws: the action already
- * happened and already reported its own success or failure on the engine's
- * stderr, so a bookkeeping failure must not turn a successful click into a
- * failed command.
- */
 export declare function recordComputerAction(event: ComputerActionEvent, opts?: {
     device?: string;
 }): void;