@phnx-labs/agents-cli 1.22.102 → 1.22.104

package/dist/commands/setup-computer.js

@@ -9,9 +9,10 @@
  * Idempotent: re-running re-installs the current helper and re-checks trust.
  */
 import os from 'node:os';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import chalk from 'chalk';
 import { installComputerHelperMacLocal, activateComputerHelperMacLocal, probeComputerTrust, } from './computer.js';
+import { resolveComputerBin, ComputerClientError } from '../lib/computer-client.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 const ACCESSIBILITY_PANE = 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility';
 const SCREEN_PANE = 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture';
@@ -36,6 +37,24 @@ export async function runComputerWizard() {
         console.log(chalk.dim('On Windows, provision a remote host from a Mac/Linux box instead: `agents computer setup --device <device>`.'));
         return false;
     }
+    try {
+        resolveComputerBin();
+    }
+    catch (error) {
+        if (!(error instanceof ComputerClientError) || error.code !== 'COMPUTER_BIN_MISSING')
+            throw error;
+        console.log('Installing @phnx-labs/computer-cli@0.1.1…');
+        const installed = spawnSync('npm', ['install', '-g', '@phnx-labs/computer-cli@0.1.1'], { stdio: 'inherit' });
+        if (installed.status !== 0)
+            return false;
+        try {
+            resolveComputerBin();
+        }
+        catch {
+            console.error('Computer CLI installation did not produce an executable on PATH.');
+            return false;
+        }
+    }
     // 1. Download + verify + install the signed, notarized helper.
     console.log(chalk.bold('Installing the Agents Computer helper...'));
     try {

package/dist/commands/setup-secrets.d.ts

@@ -8,8 +8,8 @@
  * `npm i -g`. Users do not set extra env vars.
  */
 import type { Command } from 'commander';
-export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli@0.1.2";
-export declare const INSTALL_HINT = "agents clis install secrets   # or: npm i -g @phnx-labs/secrets-cli@0.1.2";
+export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli@0.1.4";
+export declare const INSTALL_HINT = "agents clis install secrets   # or: npm i -g @phnx-labs/secrets-cli@0.1.4";
 export declare function setupSecretsPrefsPath(): string;
 /** True when the standalone `secrets` executable resolves ($SECRETS_BIN or PATH). */
 export declare function isSecretsCliInstalled(): boolean;

package/dist/commands/setup-secrets.js

@@ -14,7 +14,7 @@ import { spawnSync } from 'node:child_process';
 import { getHistoryDir } from '../lib/state.js';
 import { resolveSecretsBin, invocation, SecretsClientError, _resetSecretsClientForTest } from '../lib/secrets-client.js';
 import { installCli, resolveCliManifest } from '../lib/cli-resources.js';
-export const SECRETS_CLI_PACKAGE = '@phnx-labs/secrets-cli@0.1.2';
+export const SECRETS_CLI_PACKAGE = '@phnx-labs/secrets-cli@0.1.4';
 export const INSTALL_HINT = `agents clis install secrets   # or: npm i -g ${SECRETS_CLI_PACKAGE}`;
 export function setupSecretsPrefsPath() {
     return path.join(getHistoryDir(), 'setup', 'secrets.json');

package/dist/commands/view.js

@@ -31,7 +31,7 @@ import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins/plugins.js';
 import { getAgentsDir, getUserAgentsDir, getEffectivePromptcutsPath, readMergedPromptcuts, readMeta } from '../lib/state.js';
 import { findNativeAccountByIdentity } from '../lib/account-registry.js';
-import { accountListJson, loadAccountCatalog, renderAccountRows, secretsUnavailableNote } from '../lib/account-catalog.js';
+import { ACCOUNT_LISTING_LEGEND, accountListJson, loadAccountCatalog, renderAccountRows, secretsUnavailableNote } from '../lib/account-catalog.js';
 import { addSupported } from '../lib/accounts/add.js';
 import { readInstallation } from '../lib/installations/store.js';
 import { isAutoUpdateEnabledForAgent } from '../lib/installations/update-policy.js';
@@ -557,12 +557,10 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         }
         if (filterAgentId) {
             console.log(chalk.gray(`  Add an account: agents accounts add ${filterAgentId} [name]`));
-            console.log(chalk.gray('  STATE: LIVE ready · LIMITED rate-limited · EXPIRED needs refresh · REVOKED needs login · UNVERIFIED unconfirmed · MISSING not provisioned · * stale usage\n'));
-        }
-        else {
-            // Overview also renders account tables (footer:false) — explain STATE there too.
-            console.log(chalk.gray('  STATE: LIVE ready · LIMITED rate-limited · EXPIRED needs refresh · REVOKED needs login · UNVERIFIED unconfirmed · MISSING not provisioned · * stale usage\n'));
         }
+        // Overview renders the same account rows with footer:false, so both paths
+        // need the legend the shared renderer would otherwise have printed.
+        console.log(chalk.gray(`  ${ACCOUNT_LISTING_LEGEND}\n`));
     }
     if (versionManaged.length > 0 && viewOpts?.versions) {
         // Calculate column widths across all agents for alignment

package/dist/lib/account-catalog.d.ts

@@ -201,8 +201,29 @@ export declare function loadAccountCatalog(): Promise<AccountCatalog>;
  */
 export declare function secretsUnavailableNote(catalog: Pick<AccountCatalog, 'secretsUnavailable'>): string | null;
 export declare function accountListJson(native: NativeAccountCatalogRow[], providers?: ProviderAccountCatalogRow[], harness?: AgentId): AccountListJson;
-export declare function whereText(row: NativeAccountCatalogRow, localDevice: string): string;
+/**
+ * A state worth an operator's attention, rendered at the END of the row.
+ * `live`, `ready`, `unverified` and `per-device` are the ordinary cases: they
+ * were on every row of the old table and pushed it past the terminal width
+ * without telling anyone anything. They stay in `accounts list --fleet`,
+ * `accounts view <name>` and `--json`.
+ */
+export declare function verdictNote(verdict: AccountVerdict): string | null;
+/**
+ * Device coverage, but only when it SPLITS the fleet: some boxes can use the
+ * account and some cannot. Full coverage is the ordinary case, and "none of
+ * them" is already exactly what the row's state note says, so both render
+ * nothing — `accounts list --fleet` is the per-device table.
+ */
+export declare function coverageNote(row: NativeAccountCatalogRow, localDevice: string): string | null;
 export declare const OVERVIEW_MAX_USAGE_WINDOWS = 2;
+/**
+ * The one line under an account listing. It explains the two marks a row can
+ * carry and names where the columns the listing no longer prints — identity,
+ * per-device state — still live. Shared with `agents view` so the two surfaces
+ * cannot drift.
+ */
+export declare const ACCOUNT_LISTING_LEGEND = "* stale usage \u00B7 a healthy account carries no state \u00B7 identity + per-box state: agents accounts list --fleet";
 /** Shared text renderer used by both `accounts list` and account-first `view`. */
 export declare function renderAccountRows(rows: NativeAccountCatalogRow[], opts: {
     heading?: boolean;

package/dist/lib/account-catalog.js

@@ -367,35 +367,55 @@ export function accountListJson(native, providers = [], harness) {
         ],
     };
 }
-function verdictText(verdict) {
+/**
+ * A state worth an operator's attention, rendered at the END of the row.
+ * `live`, `ready`, `unverified` and `per-device` are the ordinary cases: they
+ * were on every row of the old table and pushed it past the terminal width
+ * without telling anyone anything. They stay in `accounts list --fleet`,
+ * `accounts view <name>` and `--json`.
+ */
+export function verdictNote(verdict) {
     if (verdict === 'rate_limited')
-        return 'LIMITED';
-    return verdict.toUpperCase();
+        return chalk.yellow('rate-limited');
+    if (verdict === 'expired' || verdict === 'revoked' || verdict === 'missing') {
+        return chalk.red(verdict);
+    }
+    return null;
 }
-export function whereText(row, localDevice) {
+/**
+ * Device coverage, but only when it SPLITS the fleet: some boxes can use the
+ * account and some cannot. Full coverage is the ordinary case, and "none of
+ * them" is already exactly what the row's state note says, so both render
+ * nothing — `accounts list --fleet` is the per-device table.
+ */
+export function coverageNote(row, localDevice) {
     const names = [...new Set(row.devices.map((device) => device.device))];
     // Peers on an older release do not publish slot verdicts, so the only
-    // observation is this box — say so rather than a coverage count.
+    // observation is this box — that is a gap in what we can see, not a gap in
+    // provisioning, so it is not an alarm.
     if (names.length === 1 && names[0] === localDevice)
-        return 'this box';
-    // Per-device accounts are provisioned per box; show which boxes are present
-    // rather than a live/total fraction — the fraction would hide that each box
+        return null;
+    // Per-device accounts are provisioned per box; name the boxes it is NOT on
+    // rather than a usable/total fraction — the fraction would hide that each box
     // is its own account.
     if (row.provisioning === 'per-device') {
-        const present = row.devices
-            .filter((device) => device.verdict !== 'missing')
-            .map((device) => device.device);
-        return present.join(', ') || 'this box';
+        const absent = row.devices.filter((device) => device.verdict === 'missing').map((device) => device.device);
+        return absent.length > 0 && absent.length < row.devices.length ? `not on ${absent.join(', ')}` : null;
     }
     const provisioned = row.devices.filter((device) => device.verdict !== 'missing').length;
-    if (provisioned === 0)
-        return '—';
     const usable = row.devices.filter((device) => device.verdict === 'live' || device.verdict === 'rate_limited' || device.verdict === 'unverified').length;
-    if (usable === provisioned)
-        return `on ${usable} ${usable === 1 ? 'box' : 'boxes'}`;
-    return `on ${usable} of ${provisioned} boxes`;
+    if (usable === 0 || usable === provisioned)
+        return null;
+    return `usable on ${usable} of ${provisioned} boxes`;
 }
 export const OVERVIEW_MAX_USAGE_WINDOWS = 2;
+/**
+ * The one line under an account listing. It explains the two marks a row can
+ * carry and names where the columns the listing no longer prints — identity,
+ * per-device state — still live. Shared with `agents view` so the two surfaces
+ * cannot drift.
+ */
+export const ACCOUNT_LISTING_LEGEND = '* stale usage · a healthy account carries no state · identity + per-box state: agents accounts list --fleet';
 function usageText(row, maxWindows) {
     if (row.usageSnapshot) {
         const usageInfo = { snapshot: row.usageSnapshot, error: row.usageError ?? null };
@@ -411,13 +431,35 @@ function usageText(row, maxWindows) {
     const percent = `${row.usage.usedPercent}%${row.usage.stale ? '*' : ''}`;
     return `${renderBar(row.usage.usedPercent, LISTING_USAGE_BAR_LEN)} ${percent}`;
 }
+/**
+ * True only when the USAGE cell is certain to print a throttle marker, so the
+ * `rate-limited` note would say the same thing twice. Mirrors `usageText`
+ * branch for branch: with a snapshot, `formatUsageSummary` appends
+ * 'out of credits' or 'session-limited (…)' exactly for these `unavailable`
+ * reasons; without one, `usageText` prints 'limited' or 'no credits'. A verdict
+ * thrown by a maxed WINDOW is deliberately NOT here: the overview caps the cell
+ * at `OVERVIEW_MAX_USAGE_WINDOWS`, so the window that tripped it can be hidden
+ * behind the `+N` count with no color at all, and the note is the only signal.
+ */
+function usageCellNamesThrottle(row) {
+    if (row.usageSnapshot) {
+        const unavailable = row.usageSnapshot.unavailable;
+        return unavailable?.reason === 'out_of_credits'
+            || (unavailable?.reason === 'session_limit' && !!unavailable.resetsAt);
+    }
+    return row.usage?.status === 'out_of_credits'
+        || (row.usage?.status === 'rate_limited' && (row.usage.usedPercent === null || row.usage.usedPercent === undefined));
+}
 function nativeLine(row, localDevice, maxWindows) {
     return {
-        name: row.name ?? 'unnamed',
-        identityLabel: row.identityLabel,
-        verdict: row.verdict,
-        where: whereText(row, localDevice),
-        fix: row.fix,
+        // A discovered login nobody has named is still identified by what it is:
+        // the row no longer carries an IDENTITY column, so the identity IS the name.
+        name: row.name ?? row.identityLabel,
+        notes: [
+            usageCellNamesThrottle(row) && row.verdict === 'rate_limited' ? null : verdictNote(row.verdict),
+            coverageNote(row, localDevice),
+            row.fix ? chalk.gray(`fix: ${row.fix}`) : null,
+        ].filter((note) => !!note),
         usage: usageText(row, maxWindows),
         isDefault: row.isDefault,
     };
@@ -425,32 +467,27 @@ function nativeLine(row, localDevice, maxWindows) {
 function providerLine(row, harness) {
     return {
         name: row.name,
-        identityLabel: row.identityLabel,
-        verdict: row.verdict,
-        where: '—',
-        fix: row.fix,
+        notes: [
+            verdictNote(row.verdict),
+            row.fix ? chalk.gray(`fix: ${row.fix}`) : null,
+        ].filter((note) => !!note),
         usage: '',
         isDefault: harness ? row.defaultFor.includes(harness) : false,
     };
 }
-function formatListingLine(line, nameW, identityW, stateW, whereW, usageW) {
+function formatListingLine(line, nameW, usageW) {
     const marker = line.isDefault ? '*' : ' ';
-    const fix = line.fix ? `fix: ${line.fix}` : '';
     return (`  ${chalk.green(marker)} ${chalk.cyan(line.name.padEnd(nameW))}  `
-        + `${line.identityLabel.padEnd(identityW)}  `
-        + `${verdictText(line.verdict).padEnd(stateW)}  `
-        + `${line.where.padEnd(whereW)}  `
         + `${padToWidth(line.usage, usageW)}  `
-        + `${fix ? chalk.gray(fix) : ''}`).trimEnd();
+        + line.notes.join(chalk.gray(' · '))).trimEnd();
 }
 function pushGroup(out, title, lines, widths, harnessHeadings) {
     if (lines.length === 0)
         return;
     if (harnessHeadings)
         out.push(chalk.bold(title));
-    out.push(chalk.gray(`  ${'ACCOUNT'.padEnd(widths.nameW + 2)}${'IDENTITY'.padEnd(widths.identityW + 2)}${'STATE'.padEnd(widths.stateW + 2)}${'WHERE'.padEnd(widths.whereW + 2)}${'USAGE'.padEnd(widths.usageW + 2)}FIX`));
     for (const line of lines) {
-        out.push(formatListingLine(line, widths.nameW, widths.identityW, widths.stateW, widths.whereW, widths.usageW));
+        out.push(formatListingLine(line, widths.nameW, widths.usageW));
     }
     out.push('');
 }
@@ -501,9 +538,6 @@ export function renderAccountRows(rows, opts) {
         const allLines = [...grouped.values()].flat().concat(orphans);
         const widths = {
             nameW: Math.max(7, ...allLines.map((line) => line.name.length)),
-            identityW: Math.max(8, ...allLines.map((line) => line.identityLabel.length)),
-            stateW: Math.max(5, ...allLines.map((line) => verdictText(line.verdict).length)),
-            whereW: Math.max(5, ...allLines.map((line) => line.where.length)),
             usageW: Math.max(5, ...allLines.map((line) => stringWidth(line.usage))),
         };
         for (const [harness, lines] of grouped) {
@@ -519,7 +553,7 @@ export function renderAccountRows(rows, opts) {
         const count = visibleNative.filter((row) => !!row.fix).length
             + visibleProviders.filter((row) => !!row.fix).length;
         out.push(chalk.gray(`${count} accounts need you · add: agents accounts add <harness>`));
-        out.push(chalk.gray('STATE: LIVE ready · LIMITED rate-limited · EXPIRED needs refresh · REVOKED needs login · UNVERIFIED unconfirmed · MISSING not provisioned · * stale usage'));
+        out.push(chalk.gray(ACCOUNT_LISTING_LEGEND));
     }
     return out.join('\n').trimEnd();
 }

package/dist/lib/accounting/usage.js

@@ -624,12 +624,13 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         parts.push(chalk.gray(plan.padEnd(planWidth)));
     }
     if (snapshot) {
-        if (snapshot.unavailable?.reason === 'out_of_credits') {
-            parts.push(chalk.red('out of credits'));
-        }
-        else if (snapshot.unavailable?.reason === 'session_limit' && snapshot.unavailable.resetsAt) {
-            parts.push(chalk.yellow(`session-limited (${formatResetHint(snapshot.unavailable.resetsAt)})`));
-        }
+        // A blocking marker renders AFTER the bars: leading it pushed every gauge
+        // out of its column, so one throttled account misaligned the whole table.
+        const blocked = snapshot.unavailable?.reason === 'out_of_credits'
+            ? chalk.red('out of credits')
+            : snapshot.unavailable?.reason === 'session_limit' && snapshot.unavailable.resetsAt
+                ? chalk.yellow(`session-limited (${formatResetHint(snapshot.unavailable.resetsAt)})`)
+                : null;
         // Compact rows show BLOCKING windows — the same set
         // deriveUsageStatusFromSnapshot uses for the rate-limited badge — so an
         // account throttled by its month window (Droid meters on 5h/week/month)
@@ -698,6 +699,8 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         else if (opts?.unverified) {
             parts.push(chalk.yellow('unverified'));
         }
+        if (blocked)
+            parts.push(blocked);
     }
     else if (opts?.headless) {
         // No bars at all: still name the scope gap so "usage pending" is not
@@ -2357,7 +2360,7 @@ function formatAgeShort(diffMs) {
  * Staleness suffix for a last-known window the freshness gate dropped. A window
  * whose reset/period boundary passed while the sample itself is still inside its
  * `windowMinutes` rolled OVER — the number describes a period that is done, so
- * name it ("period ended 1h ago", e.g. Grok's weekly billing period). A window
+ * name it ("period ended 1h", e.g. Grok's weekly billing period). A window
  * that aged past its own `windowMinutes` (Claude's 5h session read never
  * refreshed in time) is a stale sample of a still-rolling window, so report the
  * capture age ("6h old"). Falls back to the reset age, then a bare "stale".
@@ -2368,25 +2371,26 @@ function formatStaleWindowSuffix(window, capturedAt, now) {
         window.windowMinutes !== null &&
         capturedAt.getTime() + window.windowMinutes * 60 * 1000 <= now.getTime();
     if (resetPassed && !captureExpired) {
-        return `stale (period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())} ago)`;
+        return `period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())}`;
     }
     if (capturedAt)
         return `${formatAgeShort(now.getTime() - capturedAt.getTime())} old`;
     if (resetPassed)
-        return `stale (period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())} ago)`;
+        return `period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())}`;
     return 'stale';
 }
 /**
- * Render a dropped-but-last-known window as "S: ▍░░░░ 30% · 6h old": the gauge
- * and percentage exactly as a live bar, then a dim staleness suffix so the
- * number is always visible and unmistakably not current. VIEW-ONLY — these
- * windows are never in `snapshot.windows`, so routing never sees them.
+ * Render a dropped-but-last-known window as "S: ▍░░░░ 30%* (6h old)": the gauge
+ * and percentage exactly as a live bar, then the `*` stale marker the listing
+ * legend explains and a dim age, so the number is always visible and
+ * unmistakably not current. VIEW-ONLY — these windows are never in
+ * `snapshot.windows`, so routing never sees them.
  */
 function renderStaleUsageWindow(window, capturedAt, shortLabel, now) {
     const bar = renderCompactUsageBar(window.usedPercent);
     const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
     const suffix = formatStaleWindowSuffix(window, capturedAt, now);
-    return `${chalk.gray(`${shortLabel}:`)} ${bar} ${pct} ${chalk.dim(`· ${suffix}`)}`;
+    return `${chalk.gray(`${shortLabel}:`)} ${bar} ${pct}${chalk.dim('*')} ${chalk.dim(`(${suffix})`)}`;
 }
 /** Format a reset timestamp as a human-readable relative or absolute time. */
 function formatResetAt(date) {

package/dist/lib/agent-spec/agents.d.ts

@@ -24,6 +24,7 @@ export declare const GEMINI_HOOKS_MIN_VERSION = "0.26.0";
  * section, even though the user had nothing to import.
  */
 interface NativeBinaryResolutionOptions {
+    accept?: (candidate: string) => boolean;
     shimsDir?: string;
     historyDir?: string;
 }

package/dist/lib/agent-spec/agents.js

@@ -134,7 +134,7 @@ export function findInPath(command, options = {}) {
                 if (process.platform !== 'win32')
                     fs.accessSync(full, fs.constants.X_OK);
                 const native = resolveNativeBinaryPath(command, full, options);
-                if (native)
+                if (native && (!options.accept || options.accept(native)))
                     return native;
             }
             catch {

package/dist/lib/browser/drivers/ssh.js

@@ -11,7 +11,7 @@ export { shellQuote };
 // The `ssh -L` tunnel spawn is shared with `agents computer --device`; it lives in
 // the single ssh-tunnel helper. Calling it with no options preserves this
 // driver's original foreground, stderr-captured behavior exactly.
-import { startSSHTunnel } from '../../computer/ssh-tunnel.js';
+import { startSSHTunnel } from '../../ssh-tunnel.js';
 import { encodePwshBase64 } from '../../pwsh.js';
 /** Lifecycle for a registry-driven tunnel vs a profile the daemon launched. */
 export function persistRemoteLifecycle(persistRemote) {

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

@@ -0,0 +1,83 @@
+/**
+ * context.ts — everything agents-cli knows that the standalone `computer`
+ * engine cannot work out for itself, serialized as one JSON object onto fd 3.
+ *
+ * This is the whole contract of the consumer half, and it is deliberately four
+ * fields wide. The engine accepts exactly this shape:
+ *
+ *   version      `1`. The engine matches on it; a field added later must be
+ *                optional so an older engine keeps working.
+ *   permissions  which apps are allowed, derived from `Computer(<bundle-id>)`
+ *                rules in the agents permissions resource layer. The engine
+ *                would have to re-learn resource layering to compute this.
+ *   peers        which executables the daemon accepts a connection from.
+ *   target       the `--device <name>` target, resolved against the fleet:
+ *                devices registry, ssh identity, platform. The engine matches
+ *                its own `--device <alias>` against this instead of reading a
+ *                registry it does not have. Absent for a local invocation.
+ *   session      who is acting — actor id and agent session — so an action
+ *                lands in the right session history.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. The transport (`COMPUTER_HELPER_TCP`,
+ * `COMPUTER_HELPER_VNC`, `COMPUTER_HELPER_SOCKET`), the remote helper's auth
+ * token, and the policy-file paths are the ENGINE's: it provisions the Windows
+ * helper, mints and stores the token, opens the `ssh -L` tunnel and hydrates its
+ * own transport from the state it wrote. agents-cli publishing a loopback
+ * endpoint here (or on `COMPUTER_HELPER_TCP`) would be a second, drifting copy
+ * of that answer — and a copy without the token, which the daemon rejects with
+ * `auth_failed`. Service-manager safety (launchd/systemd registration under a
+ * redirected HOME) is likewise the standalone's own: it inherits `HOME` and
+ * `AGENTS_REAL_HOME` and renders its own manifest, so agents-cli neither
+ * computes a label nor issues a verdict for it.
+ *
+ * The context is PUSHED (written and closed) rather than exposed as a callback,
+ * 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. */
+export interface ComputerSessionContext {
+    sessionId?: string;
+    launchId?: string;
+    actor: string;
+}
+export interface ComputerContext {
+    version: 1;
+    permissions?: {
+        allow: string[];
+    };
+    peers: {
+        allow: string[];
+    };
+    target?: ComputerTargetContext;
+    session: ComputerSessionContext;
+}
+export 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;
+}
+/**
+ * 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>;

package/dist/lib/computer/context.js

@@ -0,0 +1,91 @@
+/**
+ * context.ts — everything agents-cli knows that the standalone `computer`
+ * engine cannot work out for itself, serialized as one JSON object onto fd 3.
+ *
+ * This is the whole contract of the consumer half, and it is deliberately four
+ * fields wide. The engine accepts exactly this shape:
+ *
+ *   version      `1`. The engine matches on it; a field added later must be
+ *                optional so an older engine keeps working.
+ *   permissions  which apps are allowed, derived from `Computer(<bundle-id>)`
+ *                rules in the agents permissions resource layer. The engine
+ *                would have to re-learn resource layering to compute this.
+ *   peers        which executables the daemon accepts a connection from.
+ *   target       the `--device <name>` target, resolved against the fleet:
+ *                devices registry, ssh identity, platform. The engine matches
+ *                its own `--device <alias>` against this instead of reading a
+ *                registry it does not have. Absent for a local invocation.
+ *   session      who is acting — actor id and agent session — so an action
+ *                lands in the right session history.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. The transport (`COMPUTER_HELPER_TCP`,
+ * `COMPUTER_HELPER_VNC`, `COMPUTER_HELPER_SOCKET`), the remote helper's auth
+ * token, and the policy-file paths are the ENGINE's: it provisions the Windows
+ * helper, mints and stores the token, opens the `ssh -L` tunnel and hydrates its
+ * own transport from the state it wrote. agents-cli publishing a loopback
+ * endpoint here (or on `COMPUTER_HELPER_TCP`) would be a second, drifting copy
+ * of that answer — and a copy without the token, which the daemon rejects with
+ * `auth_failed`. Service-manager safety (launchd/systemd registration under a
+ * redirected HOME) is likewise the standalone's own: it inherits `HOME` and
+ * `AGENTS_REAL_HOME` and renders its own manifest, so agents-cli neither
+ * computes a label nor issues a verdict for it.
+ *
+ * The context is PUSHED (written and closed) rather than exposed as a callback,
+ * so the engine never re-enters agents-cli and there is exactly one direction of
+ * dependency.
+ */
+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
+        || env.CLAUDE_SESSION_ID
+        || env.AGENTS_SESSION_ID
+        || env.AGENT_SESSION_ID
+        || 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;
+    if (opts.device) {
+        const resolved = await resolveRemoteDevice(opts.device, {
+            expectPlatform: 'windows',
+            forWhat: '`agents computer --device` drives the Windows computer-helper daemon, so it',
+        });
+        target = {
+            alias: opts.device,
+            host: resolved.target,
+            user: resolved.user,
+            hostname: resolved.host,
+            platform: resolved.device.platform,
+            sshArgs: resolved.identityArgs,
+        };
+    }
+    return {
+        version: 1,
+        ...(!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(),
+            launchId: process.env.AGENT_LAUNCH_ID,
+            actor: resolveActor().id,
+        },
+    };
+}

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

@@ -0,0 +1,46 @@
+/** 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[];
+/**
+ * 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.
+ */
+export declare function parseVncEndpoint(raw: string | undefined): {
+    host: string;
+    port: number;
+} | null;
+export declare function resolveTcpEndpoint(): {
+    host: string;
+    port: number;
+    token: string | null;
+} | null;
+export declare function resolveVncEndpoint(): {
+    host: string;
+    port: number;
+    password: string;
+} | null;