@phnx-labs/agents-cli 1.20.67 → 1.20.69

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;

package/dist/commands/setup-computer.js

@@ -0,0 +1,133 @@
+/**
+ * `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 os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import chalk from 'chalk';
+import { installComputerHelperMacLocal, activateComputerHelperMacLocal, probeComputerTrust, } from './computer.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';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Open a System Settings Privacy pane (best-effort — never throws). */
+function openPane(pane) {
+    try {
+        execFileSync('/usr/bin/open', [pane], { stdio: 'ignore' });
+    }
+    catch {
+        // ignore — we print the manual path as a fallback
+    }
+}
+/**
+ * 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 async function runComputerWizard() {
+    if (os.platform() !== 'darwin') {
+        console.log(chalk.yellow('`agents setup computer` configures the macOS helper (local control).'));
+        console.log(chalk.dim('On Windows, provision a remote host from a Mac/Linux box instead: `agents computer setup --host <device>`.'));
+        return false;
+    }
+    // 1. Download + verify + install the signed, notarized helper.
+    console.log(chalk.bold('Installing the Computer Helper...'));
+    try {
+        await installComputerHelperMacLocal();
+    }
+    catch (err) {
+        console.error(chalk.red(`Install failed: ${err.message}`));
+        return false;
+    }
+    // 2. Activate the daemon so macOS can attribute the TCC grants to it.
+    console.log(chalk.bold('\nStarting the helper...'));
+    let trusted = false;
+    try {
+        ({ trusted } = await activateComputerHelperMacLocal());
+    }
+    catch (err) {
+        console.error(chalk.red(`Could not start the helper: ${err.message}`));
+        return false;
+    }
+    // 3. Guide the two permission grants if not already trusted.
+    if (!trusted) {
+        console.log(chalk.bold('\nGrant two permissions to "Computer Helper" (one-time):'));
+        console.log('  1. ' + chalk.cyan('Accessibility') + chalk.dim('     — lets it click/type'));
+        console.log('  2. ' + chalk.cyan('Screen Recording') + chalk.dim('  — lets it screenshot windows'));
+        console.log(chalk.dim('\nOpening System Settings > Privacy & Security ...'));
+        openPane(ACCESSIBILITY_PANE);
+        if (isInteractiveTerminal()) {
+            trusted = await pollForTrust();
+        }
+        // Also nudge the Screen Recording pane so both are visible.
+        openPane(SCREEN_PANE);
+        if (!trusted) {
+            console.log(chalk.yellow('\nAccessibility not granted yet.'));
+            console.log(chalk.dim('Finish both grants in System Settings, then run: ') + chalk.cyan('agents computer start'));
+            console.log(chalk.dim('  Accessibility:    System Settings > Privacy & Security > Accessibility'));
+            console.log(chalk.dim('  Screen Recording: System Settings > Privacy & Security > Screen Recording'));
+        }
+    }
+    if (trusted) {
+        console.log(chalk.green('\nComputer control is ready.'));
+    }
+    // 4. App allow-list guidance (deny-by-default) — always shown; it's the gate
+    // between "trusted" and "can actually drive an app".
+    console.log(chalk.bold('\nWhitelist the apps the helper may drive (default is deny-all):'));
+    console.log(chalk.dim('  Add a YAML under ~/.agents/permissions/groups/, e.g. computer.yaml:'));
+    console.log(chalk.dim('    name: computer'));
+    console.log(chalk.dim('    allow:'));
+    console.log(chalk.dim('      - "Computer(com.apple.finder)"'));
+    console.log(chalk.dim('      - "Computer(com.apple.notes)"'));
+    console.log(chalk.dim('  Then reload: ') + chalk.cyan('agents computer reload'));
+    return trusted;
+}
+/**
+ * Poll the daemon's trust status while the user toggles the Accessibility
+ * checkbox in System Settings. Bounded to ~2 minutes; the user can Ctrl+C.
+ */
+async function pollForTrust() {
+    const { default: ora } = await import('ora');
+    const spinner = ora('Waiting for Accessibility to be granted (toggle the checkbox in System Settings)...').start();
+    const deadline = Date.now() + 120_000;
+    try {
+        while (Date.now() < deadline) {
+            if (await probeComputerTrust()) {
+                spinner.succeed('Accessibility granted.');
+                return true;
+            }
+            await sleep(2000);
+        }
+        spinner.stop();
+        return false;
+    }
+    catch {
+        spinner.stop();
+        return false;
+    }
+}
+/** Register `agents setup computer` under the parent `setup` command. */
+export function registerSetupComputerCommand(setupCmd) {
+    setupCmd
+        .command('computer')
+        .description('Set up `agents computer` (macOS) — install the signed helper and grant control permissions.')
+        .action(async () => {
+        try {
+            await runComputerWizard();
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.yellow('\nCancelled'));
+                return;
+            }
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,17 @@
+/**
+ * `agents setup share` — interactive wizard to configure the `agents share`
+ * endpoint (Cloudflare R2 + Worker). A friendly front door over the existing
+ * `agents share setup` (provision) and `agents share join` flows, reusing their
+ * exact logic so there is a single source of truth for provisioning.
+ *
+ * Idempotent: re-running shows the current endpoint and offers to reconfigure.
+ */
+import type { Command } from 'commander';
+/**
+ * Interactive share setup. Returns true if the user configured (or already had)
+ * an endpoint, false if they skipped. Never throws on user cancel — callers
+ * (the `agents setup` hub) rely on that to keep the fresh-machine flow going.
+ */
+export declare function runShareWizard(): Promise<boolean>;
+/** Register `agents setup share` under the parent `setup` command. */
+export declare function registerSetupShareCommand(setupCmd: Command): void;

package/dist/commands/setup-share.js

@@ -0,0 +1,85 @@
+/**
+ * `agents setup share` — interactive wizard to configure the `agents share`
+ * endpoint (Cloudflare R2 + Worker). A friendly front door over the existing
+ * `agents share setup` (provision) and `agents share join` flows, reusing their
+ * exact logic so there is a single source of truth for provisioning.
+ *
+ * Idempotent: re-running shows the current endpoint and offers to reconfigure.
+ */
+import chalk from 'chalk';
+import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_WORKER_NAME, readShareConfig, } from '../lib/share/config.js';
+import { runShareProvision, runShareJoin } from './share.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/**
+ * Interactive share setup. Returns true if the user configured (or already had)
+ * an endpoint, false if they skipped. Never throws on user cancel — callers
+ * (the `agents setup` hub) rely on that to keep the fresh-machine flow going.
+ */
+export async function runShareWizard() {
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('agents setup share needs an interactive terminal. ' +
+            'Non-interactively, use `agents share setup` (provision) or `agents share join <url>`.'));
+        return false;
+    }
+    const existing = readShareConfig();
+    if (existing) {
+        console.log(chalk.dim(`Share is already configured → ${chalk.green(existing.baseUrl)}`));
+        console.log(chalk.dim(`  worker ${existing.workerName} · bucket ${existing.bucketName} · account ${existing.accountId}`));
+        const { confirm } = await import('@inquirer/prompts');
+        const reconfigure = await confirm({ message: 'Reconfigure the share endpoint?', default: false });
+        if (!reconfigure) {
+            console.log(chalk.dim('Keeping the current endpoint.'));
+            return true;
+        }
+    }
+    const { select } = await import('@inquirer/prompts');
+    const mode = await select({
+        message: 'How do you want to publish shared links?',
+        choices: [
+            {
+                name: 'Provision my own (Cloudflare R2 + Worker)',
+                value: 'provision',
+                description: 'One-time: creates a bucket + Worker on your Cloudflare account (~$0). Needs a Cloudflare API token.',
+            },
+            {
+                name: 'Join an existing endpoint (a teammate already provisioned one)',
+                value: 'join',
+                description: 'Paste the base URL + write token from whoever owns the endpoint.',
+            },
+        ],
+    });
+    if (mode === 'provision') {
+        await runShareProvision({
+            bundle: DEFAULT_CF_BUNDLE,
+            worker: DEFAULT_WORKER_NAME,
+            bucket: DEFAULT_BUCKET_NAME,
+        });
+        return true;
+    }
+    const { input } = await import('@inquirer/prompts');
+    const baseUrl = await input({
+        message: 'Endpoint base URL (e.g. https://share.agents-cli.sh)',
+        validate: (v) => (v.trim().startsWith('http') ? true : 'Enter the full https:// URL of the endpoint.'),
+    });
+    await runShareJoin(baseUrl.trim());
+    return true;
+}
+/** Register `agents setup share` under the parent `setup` command. */
+export function registerSetupShareCommand(setupCmd) {
+    setupCmd
+        .command('share')
+        .description('Configure the `agents share` endpoint (Cloudflare R2 + Worker) — provision your own or join one.')
+        .action(async () => {
+        try {
+            await runShareWizard();
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.yellow('\nCancelled'));
+                return;
+            }
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/setup.d.ts

@@ -18,5 +18,5 @@ export declare function runSetup(program: Command, options?: {
  * error and exit.
  */
 export declare function ensureInitialized(program: Command): Promise<void>;
-/** Register the `agents setup` command. */
+/** Register the `agents setup` command and its capability subcommands. */
 export declare function registerSetupCommand(program: Command): void;

package/dist/commands/setup.js

@@ -18,6 +18,9 @@ import { AGENTS, agentConfigDirName, getUnmanagedAgentInstalls, countSessionFile
 import { setGlobalDefault } from '../lib/versions.js';
 import { ensureShimCurrent, switchHomeFileSymlinks, isShimsInPath, addShimsToPath, getPathSetupInstructions } from '../lib/shims.js';
 import { setHelpSections } from '../lib/help.js';
+import { registerSetupBrowserCommand, runBrowserWizard } from './setup-browser.js';
+import { registerSetupComputerCommand, runComputerWizard } from './setup-computer.js';
+import { registerSetupShareCommand, runShareWizard } from './setup-share.js';
 const HOME = os.homedir();
 /**
  * Import an existing unmanaged agent installation into agents-cli.
@@ -186,6 +189,10 @@ export async function runSetup(program, options = {}) {
     }
     if (options.suppressFooter)
         return;
+    // Fresh-machine hub: offer to set up the optional capabilities that need their
+    // own guided flow. TTY-only and fully opt-in — a non-interactive `agents setup`
+    // stops at the system-repo bootstrap above, unchanged.
+    await runSetupHub();
     console.log(chalk.bold('\nSetup complete. Try:'));
     console.log(chalk.cyan('  agents view                 ') + chalk.gray(' # see what\'s installed'));
     console.log(chalk.cyan('  agents run <agent> "hello"  ') + chalk.gray(' # run an agent'));
@@ -217,13 +224,52 @@ export async function ensureInitialized(program) {
     }
     await runSetup(program, { suppressFooter: true });
 }
-/** Register the `agents setup` command. */
+/**
+ * Interactive "what else do you want to set up?" menu shown after the bare
+ * `agents setup` finishes on a TTY. Each pick runs that capability's guided
+ * wizard. Never throws — a cancel or an optional wizard's error just skips the
+ * rest and lets core setup complete.
+ */
+async function runSetupHub() {
+    if (!isInteractiveTerminal())
+        return;
+    try {
+        const { checkbox } = await import('@inquirer/prompts');
+        const picks = await checkbox({
+            message: 'Set up optional capabilities now? (space to select, enter to confirm)',
+            choices: [
+                { name: 'browser  — drive a real Chrome/Brave/Edge for web automation', value: 'browser' },
+                { name: 'computer — control native macOS apps (screenshot, click, type)', value: 'computer' },
+                { name: 'share    — publish shareable links (Cloudflare R2 + Worker)', value: 'share' },
+            ],
+        });
+        for (const pick of picks) {
+            console.log();
+            if (pick === 'browser')
+                await runBrowserWizard();
+            else if (pick === 'computer')
+                await runComputerWizard();
+            else if (pick === 'share')
+                await runShareWizard();
+        }
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return;
+        console.log(chalk.yellow(`Optional setup skipped: ${err.message}`));
+    }
+}
+/** Register the `agents setup` command and its capability subcommands. */
 export function registerSetupCommand(program) {
     const setupCmd = program
         .command('setup')
         .description('First-time setup. Clones a config repo and installs agent CLIs.')
         .option('-f, --force', 'Re-run setup even if ~/.agents/.system/ already exists (use with caution)')
         .option('--no-system-repo', 'Skip cloning the system repo (you must populate ~/.agents/.system/ yourself)');
+    // Capability subcommands: `agents setup browser|computer|share`.
+    registerSetupBrowserCommand(setupCmd);
+    registerSetupComputerCommand(setupCmd);
+    registerSetupShareCommand(setupCmd);
     setHelpSections(setupCmd, {
         examples: `
       # First-time setup (clones the system repo into ~/.agents/.system/)
@@ -231,11 +277,22 @@ export function registerSetupCommand(program) {
 
       # Re-run after corruption or to repair ~/.agents/.system/
       agents setup --force
+
+      # Set up a specific capability on its own
+      agents setup browser
+      agents setup computer
+      agents setup share
     `,
         notes: `
       What it does:
         1. Clones the system repo into ~/.agents/.system/
         2. Imports any unmanaged agent installations it finds
+        3. On a TTY, offers to set up optional capabilities (browser/computer/share)
+
+      Capability setup can also be run any time on its own:
+        agents setup browser    # detect a browser + create the default profile
+        agents setup computer    # install the signed macOS helper + grant permissions
+        agents setup share       # provision or join a Cloudflare share endpoint
 
       To install CLIs from agents.yaml and sync resources into version homes:
         agents repo refresh -y