@phnx-labs/agents-cli 1.20.68 → 1.20.69

package/dist/commands/exec.js

@@ -18,6 +18,31 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { randomUUID } from 'crypto';
+/** Distinguish a terminal account-picker marker from an explicit @version pin. */
+export function parseRunAccountPickerRequest(agentSpec) {
+    const requested = agentSpec.endsWith('@');
+    const normalizedAgentSpec = requested ? agentSpec.slice(0, -1) : agentSpec;
+    return {
+        requested,
+        normalizedAgentSpec,
+        valid: !requested || (!!normalizedAgentSpec && !normalizedAgentSpec.includes('@')),
+    };
+}
+/** Return every option whose routing semantics conflict with a local account choice. */
+export function runAccountPickerConflicts(options) {
+    const conflicts = [];
+    if (options.resume !== undefined)
+        conflicts.push('--resume');
+    if (options.strategy !== undefined)
+        conflicts.push('--strategy');
+    if (options.balanced)
+        conflicts.push('--balanced');
+    if (options.lease)
+        conflicts.push('--lease');
+    if (options.host || options.device || options.on || options.computer)
+        conflicts.push('--host/--device');
+    return conflicts;
+}
 /** Type guard that narrows a string to a known AgentId. */
 function isValidAgent(agent) {
     return agent in AGENTS;
@@ -308,6 +333,9 @@ export function registerRunCommand(program) {
       # Interactive (TUI) with the pinned default version
       agents run claude
 
+      # Pick a signed-in account/version for only this run
+      agents run claude@
+
       # Pipe JSON events to a parser (--quiet drops the preamble)
       agents run claude "..." --json --quiet | jq
 
@@ -342,6 +370,10 @@ export function registerRunCommand(program) {
         A version/account is skipped when it is rate-limited right now — any usage window (incl. the 5-hour session window) at 100%, matching the 'agents view' badge.
         --balanced is shorthand for --strategy balanced. Ignored when @version is pinned, when a profile is used, or with --fallback.
 
+      Account picker: append @ with no version (agents run claude@) to choose one
+        installed account for this run. Rows show identity, login state, plan,
+        and available limits; unsafe accounts stay visible but disabled.
+
       Fallback: --fallback codex,gemini retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
       Resume: --resume <id> continues a prior conversation (full or partial id; omit to pick interactively). claude/codex resume natively; others replay via a /continue first message. Add a prompt to continue headlessly.
@@ -370,6 +402,24 @@ export function registerRunCommand(program) {
             // a native flag, not a prompt. Run interactively.
             prompt = undefined;
         }
+        // A trailing @ is an explicit request to choose one installed account.
+        // Strip only that terminal marker; concrete agent@version pins retain
+        // their existing meaning in every dispatch path below.
+        const accountPicker = parseRunAccountPickerRequest(agentSpec);
+        const accountPickerRequested = accountPicker.requested;
+        const normalizedAgentSpec = accountPicker.normalizedAgentSpec;
+        if (!accountPicker.valid) {
+            console.error(chalk.red(`Invalid account picker target: ${agentSpec}. Use agents run <agent>@.`));
+            process.exit(1);
+        }
+        if (accountPickerRequested) {
+            const conflicts = runAccountPickerConflicts(options);
+            if (conflicts.length > 0) {
+                console.error(chalk.red(`Account selection with ${agentSpec} cannot be combined with ${conflicts.join(', ')}. ` +
+                    'Pick the account locally, or use an explicit agent@version target.'));
+                process.exit(1);
+            }
+        }
         // --lease: invent a disposable cloud box for this run (via crabbox), run
         // the agent there, then tear it down. Unlike --host, nothing is registered.
         if (options.lease) {
@@ -393,7 +443,7 @@ export function registerRunCommand(program) {
             const { leaseAndRun } = await import('../lib/crabbox/lease.js');
             const { getConfiguredRunStrategy, resolveRunVersion } = await import('../lib/rotate.js');
             const detected = await detectSignedInRuntimes();
-            const agentName = agentSpec.split('@')[0];
+            const agentName = normalizedAgentSpec.split('@')[0];
             const leaseCwd = options.cwd ?? process.cwd();
             // `--lease` requires a prompt (guarded above), so it is headless by
             // contract — never block on an interactive picker. Provision exactly the
@@ -596,7 +646,7 @@ export function registerRunCommand(program) {
                 throw e;
             }
             try {
-                const [runAgent, rawRunVersion] = agentSpec.split('@');
+                const [runAgent, rawRunVersion] = normalizedAgentSpec.split('@');
                 // Forward the explicit @version pin verbatim. Resolving aliases like
                 // @latest locally would check local installs, but the remote host may
                 // have versions the laptop does not. The remote agents CLI resolves
@@ -894,7 +944,7 @@ export function registerRunCommand(program) {
                 await warnUnpushedWork(resumeExec.cwd ?? process.cwd());
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -910,7 +960,7 @@ export function registerRunCommand(program) {
         ]);
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
         // Parse agent@version
-        const [rawAgent, rawVersion] = agentSpec.split('@');
+        const [rawAgent, rawVersion] = normalizedAgentSpec.split('@');
         let agent;
         let version = rawVersion || undefined;
         let profileEnv;
@@ -938,6 +988,16 @@ export function registerRunCommand(program) {
         // degenerates to a no-op ("I'll wait for the completion notification").
         let workflowHasSubagents = false;
         const cwd = options.cwd ?? process.cwd();
+        if (accountPickerRequested && !isValidAgent(rawAgent)) {
+            if (profileExists(rawAgent)) {
+                console.error(chalk.red(`Account selection is not available for profile '${rawAgent}'. Run its concrete host agent with @ instead.`));
+                process.exit(1);
+            }
+            if (resolveWorkflowRef(rawAgent, cwd)) {
+                console.error(chalk.red(`Account selection is not available for workflow '${rawAgent}'. Run a concrete agent with @ instead.`));
+                process.exit(1);
+            }
+        }
         if (isValidAgent(rawAgent)) {
             agent = rawAgent;
         }
@@ -1161,6 +1221,28 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
         }
+        if (accountPickerRequested) {
+            if (!supportsAccountInspection(agent)) {
+                console.error(chalk.red(`${agentLabel(agent)} does not expose local account state, so agents-cli cannot safely select an account.`));
+                console.error(chalk.gray(`Supported account pickers: ${ACCOUNT_INSPECTION_AGENT_IDS.join(', ')}`));
+                process.exit(1);
+            }
+            try {
+                const { pickRunAccountCandidate } = await import('./run-account-picker.js');
+                const selected = await pickRunAccountCandidate(agent);
+                if (!selected)
+                    return;
+                version = selected.version;
+                if (!options.quiet) {
+                    const identity = selected.accountLabel || 'signed-in account';
+                    process.stderr.write(chalk.gray(`[agents] selected ${identity} · ${agent}@${selected.version} for this run\n`));
+                }
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         version = resolveVersionAlias(agent, version);
         // --resume: resolve a prior conversation and rewrite the run target to
         // continue it. `version` here is already the alias-resolved candidate-version
@@ -1298,7 +1380,7 @@ export function registerRunCommand(program) {
         // the bare primary still resolves through the strategy — otherwise every
         // `agents run claude --fallback codex` run lands on the pinned default
         // account and account rotation silently stops (the gh-monitor heal bug).
-        if (strategy !== 'pinned' || options.balanced || explicitStrategy) {
+        if (!accountPickerRequested && (strategy !== 'pinned' || options.balanced || explicitStrategy)) {
             if (version) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
             }
@@ -1373,7 +1455,7 @@ export function registerRunCommand(program) {
                 json: options.json,
                 quiet: options.quiet,
                 authCheckDisabled: options.authCheck === false || process.env.AGENTS_NO_AUTH_CHECK === '1',
-                rotated: !!rotationResult,
+                rotated: !!rotationResult || accountPickerRequested,
             });
             if (preflight) {
                 try {

package/dist/commands/fork.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `agents fork <session>` — branch an existing conversation into a new,
+ * independent session you can continue separately. The original is untouched.
+ *
+ * Thin command layer; the copy/register logic lives in `lib/session/fork.ts`.
+ */
+import type { Command } from 'commander';
+/** Register the top-level `agents fork` command. */
+export declare function registerForkCommand(program: Command): void;

package/dist/commands/fork.js

@@ -0,0 +1,67 @@
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { findSessionsById } from '../lib/session/db.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { forkSession, isForkableAgent, FORKABLE_AGENTS } from '../lib/session/fork.js';
+/** Register the top-level `agents fork` command. */
+export function registerForkCommand(program) {
+    const cmd = program
+        .command('fork <session>')
+        .description('Branch a session into a new, independent copy you can continue separately. The original is untouched.')
+        .option('--name <label>', 'Label for the fork (default: "fork of <original>")');
+    setHelpSections(cmd, {
+        examples: `
+      # Fork a session by (partial) id, then continue the fork
+      agents fork 4f3a9c21
+      agents resume <new-id>
+
+      # Give the fork a name
+      agents fork 4f3a9c21 --name "try redis instead"
+    `,
+        notes: `
+      - 'resume' continues the SAME conversation; 'fork' copies it under a new id so the two diverge.
+      - The fork is a full copy of the conversation so far; continuing it never touches the original.
+      - Resolve the session the same way as resume: an exact or prefix id fragment.
+      - Currently supports: ${FORKABLE_AGENTS.join(', ')}. Other agents are a planned follow-up.
+    `,
+    });
+    cmd.action(async (sessionArg, options) => {
+        // Resolve the source. Try the index first; only pay for a rescan if the id
+        // isn't found yet (mirrors the resume path's freshen-then-lookup).
+        let matches = findSessionsById(sessionArg, {});
+        if (matches.length === 0) {
+            await discoverSessions({});
+            matches = findSessionsById(sessionArg, {});
+        }
+        if (matches.length === 0) {
+            console.log(chalk.red(`No session matching "${sessionArg}".`));
+            console.log(chalk.gray('List candidates with: agents sessions'));
+            return;
+        }
+        if (matches.length > 1) {
+            console.log(chalk.yellow(`"${sessionArg}" is ambiguous — ${matches.length} sessions match. Use a longer id:`));
+            for (const m of matches.slice(0, 8)) {
+                console.log(chalk.gray(`  ${m.shortId}  ${m.agent}  ${m.label || m.topic || ''}`));
+            }
+            return;
+        }
+        const source = matches[0];
+        if (!isForkableAgent(source.agent)) {
+            console.log(chalk.yellow(`fork does not support ${source.agent} sessions yet.`));
+            console.log(chalk.gray(`  Supported: ${FORKABLE_AGENTS.join(', ')}.`));
+            return;
+        }
+        let result;
+        try {
+            result = forkSession(source, { name: options.name });
+        }
+        catch (err) {
+            console.log(chalk.red(`Could not fork ${source.shortId}: ${err.message}`));
+            return;
+        }
+        console.log(chalk.green(`Forked ${source.shortId} -> ${result.shortId}`));
+        console.log(chalk.gray(`  Label:    ${result.label}`));
+        console.log(chalk.gray(`  Continue: agents resume ${result.shortId}`));
+        console.log(chalk.gray(`  Original ${source.shortId} is untouched.`));
+    });
+}

package/dist/commands/run-account-picker.d.ts

@@ -0,0 +1,14 @@
+import type { AgentId } from '../lib/types.js';
+import { type RotateCandidate } from '../lib/rotate.js';
+export interface RunAccountChoice {
+    name: string;
+    value: string;
+    disabled?: string;
+    ready: boolean;
+}
+/** Human-readable remaining capacity for every window the provider exposes. */
+export declare function formatAccountLimits(candidate: RotateCandidate): string;
+/** Build aligned picker rows with usable accounts first and unsafe rows disabled. */
+export declare function buildRunAccountChoices(candidates: RotateCandidate[], globalDefault: string | null): RunAccountChoice[];
+/** Prompt for one safe installed account/version. A cancelled picker launches nothing. */
+export declare function pickRunAccountCandidate(agent: AgentId): Promise<RotateCandidate | null>;

package/dist/commands/run-account-picker.js

@@ -0,0 +1,131 @@
+import { select } from '@inquirer/prompts';
+import { agentLabel } from '../lib/agents.js';
+import { collectRunCandidates, readinessFromCandidate, } from '../lib/rotate.js';
+import { compareVersions, getGlobalDefault } from '../lib/versions.js';
+import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
+const CANCEL_SELECTION = '__agents_cancel_account_selection__';
+const WINDOW_ORDER = ['session', 'week', 'sonnet_week', 'month'];
+const WINDOW_LABELS = {
+    session: 'Session',
+    week: 'Week',
+    sonnet_week: 'Sonnet week',
+    month: 'Month',
+};
+function formatPercent(value) {
+    const rounded = Math.round(value * 10) / 10;
+    return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+}
+/** Human-readable remaining capacity for every window the provider exposes. */
+export function formatAccountLimits(candidate) {
+    const windows = candidate.usageSnapshot?.windows;
+    if (!windows || windows.length === 0)
+        return 'limits unavailable';
+    return [...windows]
+        .sort((a, b) => WINDOW_ORDER.indexOf(a.key) - WINDOW_ORDER.indexOf(b.key))
+        .map((window) => {
+        const left = Math.max(0, 100 - window.usedPercent);
+        return left === 0
+            ? `${WINDOW_LABELS[window.key]} exhausted`
+            : `${WINDOW_LABELS[window.key]} ${formatPercent(left)}% left`;
+    })
+        .join(' · ');
+}
+function disabledReason(candidate) {
+    const readiness = readinessFromCandidate(candidate);
+    if (readiness.ready)
+        return undefined;
+    if (readiness.reason === 'signed_out')
+        return 'logged out';
+    if (readiness.reason === 'out_of_credits')
+        return 'out of credits';
+    const windows = candidate.usageSnapshot?.windows ?? [];
+    const blocking = windows.filter((window) => window.key !== 'sonnet_week');
+    const considered = blocking.length > 0 ? blocking : windows;
+    const exhausted = considered
+        .filter((window) => window.usedPercent >= 100)
+        .map((window) => WINDOW_LABELS[window.key]);
+    return exhausted.length > 0
+        ? `${exhausted.join(' and ')} ${exhausted.length === 1 ? 'limit' : 'limits'} reached`
+        : 'rate limit reached';
+}
+/** Build aligned picker rows with usable accounts first and unsafe rows disabled. */
+export function buildRunAccountChoices(candidates, globalDefault) {
+    const rows = candidates.map((candidate) => {
+        const disabled = disabledReason(candidate);
+        const version = candidate.version === globalDefault
+            ? `${candidate.version} (default)`
+            : candidate.version;
+        return {
+            candidate,
+            account: candidate.accountLabel || 'account unavailable',
+            version,
+            status: candidate.signedIn ? 'logged in' : 'logged out',
+            plan: candidate.usageSnapshot?.plan ?? candidate.plan ?? 'plan unavailable',
+            limits: formatAccountLimits(candidate),
+            disabled,
+            ready: disabled === undefined,
+        };
+    });
+    rows.sort((a, b) => {
+        if (a.ready !== b.ready)
+            return a.ready ? -1 : 1;
+        const aDefault = a.candidate.version === globalDefault;
+        const bDefault = b.candidate.version === globalDefault;
+        if (aDefault !== bDefault)
+            return aDefault ? -1 : 1;
+        return compareVersions(b.candidate.version, a.candidate.version);
+    });
+    const accountWidth = Math.max(0, ...rows.map((row) => row.account.length));
+    const versionWidth = Math.max(0, ...rows.map((row) => row.version.length));
+    const statusWidth = Math.max(0, ...rows.map((row) => row.status.length));
+    const planWidth = Math.max(0, ...rows.map((row) => row.plan.length));
+    return rows.map((row) => ({
+        name: [
+            row.account.padEnd(accountWidth),
+            row.version.padEnd(versionWidth),
+            row.status.padEnd(statusWidth),
+            row.plan.padEnd(planWidth),
+            row.limits,
+        ].join('  '),
+        value: row.candidate.version,
+        disabled: row.disabled,
+        ready: row.ready,
+    }));
+}
+/** Prompt for one safe installed account/version. A cancelled picker launches nothing. */
+export async function pickRunAccountCandidate(agent) {
+    if (!isInteractiveTerminal()) {
+        requireInteractiveSelection(`Selecting a ${agentLabel(agent)} account`, [
+            `agents run ${agent}@<version>`,
+            `agents view ${agent}`,
+        ]);
+    }
+    const candidates = await collectRunCandidates(agent);
+    if (candidates.length === 0) {
+        throw new Error(`No installed ${agentLabel(agent)} versions are available. Run: agents add ${agent}@latest`);
+    }
+    const choices = buildRunAccountChoices(candidates, getGlobalDefault(agent));
+    const hasReadyAccount = choices.some((choice) => choice.ready);
+    const promptChoices = choices.map(({ ready: _ready, ...choice }) => choice);
+    if (!hasReadyAccount) {
+        promptChoices.push({
+            name: 'No usable accounts — cancel',
+            value: CANCEL_SELECTION,
+        });
+    }
+    try {
+        const version = await select({
+            message: `Select a ${agentLabel(agent)} account for this run:`,
+            choices: promptChoices,
+            loop: false,
+        });
+        if (version === CANCEL_SELECTION)
+            return null;
+        return candidates.find((candidate) => candidate.version === version) ?? null;
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return null;
+        throw err;
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * `agents setup browser` — interactive wizard to get `agents browser` working on
+ * a fresh machine: detect an installed Chromium-family browser, create the
+ * `default` profile pinned to it, optionally make it this machine's default, and
+ * point the user at the one manual step we can't automate (first-run + sign-in).
+ *
+ * Idempotent: re-running shows the current default profile and offers to change
+ * the pinned browser or re-point the device default.
+ */
+import type { Command } from 'commander';
+/**
+ * Interactive browser setup. Returns true if a usable default profile exists
+ * afterwards, false if the machine has no supported browser or the user backed
+ * out. Never throws on cancel — the `agents setup` hub relies on that.
+ */
+export declare function runBrowserWizard(): Promise<boolean>;
+/** Register `agents setup browser` under the parent `setup` command. */
+export declare function registerSetupBrowserCommand(setupCmd: Command): void;

package/dist/commands/setup-browser.js

@@ -0,0 +1,142 @@
+/**
+ * `agents setup browser` — interactive wizard to get `agents browser` working on
+ * a fresh machine: detect an installed Chromium-family browser, create the
+ * `default` profile pinned to it, optionally make it this machine's default, and
+ * point the user at the one manual step we can't automate (first-run + sign-in).
+ *
+ * Idempotent: re-running shows the current default profile and offers to change
+ * the pinned browser or re-point the device default.
+ */
+import chalk from 'chalk';
+import { updateMeta } from '../lib/state.js';
+import { findFirstInstalledBrowser, listInstalledBrowsers } from '../lib/browser/chrome.js';
+import { DEFAULT_BROWSER_PROFILE_NAME, createProfile, findFreeProfilePort, getConfiguredDefaultProfileName, getProfile, } from '../lib/browser/profiles.js';
+import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+const INSTALL_HINT = 'Install one of: Google Chrome, Brave, Microsoft Edge, Chromium, or Comet, then re-run `agents setup browser`.\n' +
+    '(Safari and Firefox are not supported — agents browser drives over the Chrome DevTools Protocol.)';
+/**
+ * Interactive browser setup. Returns true if a usable default profile exists
+ * afterwards, false if the machine has no supported browser or the user backed
+ * out. Never throws on cancel — the `agents setup` hub relies on that.
+ */
+export async function runBrowserWizard() {
+    if (!isInteractiveTerminal()) {
+        // Non-interactive: do the safe, deterministic thing (auto-detect + pin a
+        // default) without prompting, or print the install hint and bail.
+        if (!findFirstInstalledBrowser()) {
+            console.error(chalk.red('No supported browser found.\n') + chalk.dim(INSTALL_HINT));
+            return false;
+        }
+        const existing = await getProfile(DEFAULT_BROWSER_PROFILE_NAME);
+        if (existing) {
+            console.log(chalk.dim(`Browser profile "${DEFAULT_BROWSER_PROFILE_NAME}" already exists.`));
+            return true;
+        }
+        const created = await createAutoDefault();
+        console.log(chalk.green(`Created browser profile "${created.name}" → ${created.browser}.`));
+        return true;
+    }
+    const installed = listInstalledBrowsers();
+    if (installed.length === 0) {
+        console.error(chalk.red('No supported browser found on this machine.'));
+        console.log(chalk.dim(INSTALL_HINT));
+        return false;
+    }
+    const { confirm, select } = await import('@inquirer/prompts');
+    // If a default profile already exists, this is a reconfigure.
+    const existing = await getProfile(DEFAULT_BROWSER_PROFILE_NAME);
+    if (existing) {
+        console.log(chalk.dim(`Browser profile "${existing.name}" already exists (${existing.browser}${existing.binary ? ` · ${existing.binary}` : ''}).`));
+        const change = await confirm({ message: 'Re-create it (e.g. to pin a different browser)?', default: false });
+        if (!change) {
+            await maybeSetDeviceDefault(existing.name, confirm);
+            printOnboardingNextStep(existing.name);
+            return true;
+        }
+        // Re-create: drop the old one so createProfile doesn't collide.
+        const { deleteProfile } = await import('../lib/browser/profiles.js');
+        await deleteProfile(existing.name);
+    }
+    // Pick which installed browser to pin (auto-select if only one).
+    let chosen = installed[0];
+    if (installed.length > 1) {
+        const value = await select({
+            message: 'Which browser should the default profile use?',
+            choices: installed.map((b) => ({ name: `${b.browserType}  ${chalk.dim(b.binary)}`, value: b.browserType })),
+        });
+        chosen = installed.find((b) => b.browserType === value) ?? installed[0];
+    }
+    const freePort = await findFreeProfilePort();
+    const profile = {
+        name: DEFAULT_BROWSER_PROFILE_NAME,
+        description: `${chosen.browserType} profile (agents setup browser)`,
+        browser: chosen.browserType,
+        binary: chosen.binary,
+        endpoints: [`cdp://127.0.0.1:${freePort}`],
+        viewport: { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height },
+    };
+    await createProfile(profile);
+    console.log(chalk.green(`\nCreated browser profile "${profile.name}" → ${chosen.browserType} (CDP 127.0.0.1:${freePort}).`));
+    await maybeSetDeviceDefault(profile.name, confirm);
+    printOnboardingNextStep(profile.name);
+    return true;
+}
+/** Build + persist a `default` profile pinned to the first installed browser. */
+async function createAutoDefault() {
+    const detected = findFirstInstalledBrowser();
+    if (!detected)
+        throw new Error('No supported browser found.');
+    const freePort = await findFreeProfilePort();
+    const profile = {
+        name: DEFAULT_BROWSER_PROFILE_NAME,
+        description: `Auto-detected ${detected.browserType} profile`,
+        browser: detected.browserType,
+        binary: detected.binary,
+        endpoints: [`cdp://127.0.0.1:${freePort}`],
+        viewport: { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height },
+    };
+    await createProfile(profile);
+    return profile;
+}
+/** Offer to make `name` this machine's default browser profile (device-local). */
+async function maybeSetDeviceDefault(name, confirm) {
+    const current = getConfiguredDefaultProfileName();
+    if (current === name)
+        return; // already the device default
+    const set = await confirm({
+        message: `Make "${name}" this machine's default browser profile?`,
+        default: true,
+    });
+    if (set) {
+        updateMeta((m) => ({ ...m, defaultBrowserProfile: name }));
+        console.log(chalk.dim(`Bare \`agents browser start\` will now use "${name}" on this machine.`));
+    }
+}
+/** The one step we can't automate: Chrome's first-run + your own sign-in. */
+function printOnboardingNextStep(name) {
+    console.log(chalk.bold('\nOne manual step left:'));
+    console.log('  ' +
+        chalk.cyan(`agents browser start --profile ${name}`) +
+        chalk.dim('   # finish Chrome first-run + sign in to any sites you want automated'));
+    console.log(chalk.dim(`  Then check it's ready:  agents browser profiles doctor ${name}`));
+}
+/** Register `agents setup browser` under the parent `setup` command. */
+export function registerSetupBrowserCommand(setupCmd) {
+    setupCmd
+        .command('browser')
+        .description('Set up `agents browser` — detect an installed browser and create the default profile.')
+        .action(async () => {
+        try {
+            await runBrowserWizard();
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.yellow('\nCancelled'));
+                return;
+            }
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,19 @@
+/**
+ * `agents setup computer` — guided setup for `agents computer` on macOS: fetch +
+ * verify the signed helper, install it, then walk the user through the two TCC
+ * permission grants (Accessibility + Screen Recording) by opening the exact
+ * System Settings panes and polling until the grant lands.
+ *
+ * The plain `agents computer setup` / `start` commands remain for scripted use;
+ * this wizard chains them with the permission hand-holding a fresh machine needs.
+ * Idempotent: re-running re-installs the current helper and re-checks trust.
+ */
+import type { Command } from 'commander';
+/**
+ * Interactive computer setup. Returns true if the helper is installed and trust
+ * is granted (or the user chose to finish later), false if unsupported/aborted.
+ * Never throws on cancel — the `agents setup` hub relies on that.
+ */
+export declare function runComputerWizard(): Promise<boolean>;
+/** Register `agents setup computer` under the parent `setup` command. */
+export declare function registerSetupComputerCommand(setupCmd: Command): void;