@phnx-labs/agents-cli 1.20.68 → 1.20.70

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

package/dist/commands/share.d.ts

@@ -1,2 +1,17 @@
 import type { Command } from 'commander';
 export declare function registerShareCommands(program: Command): void;
+/** Provision a fresh R2 bucket + Worker on the user's Cloudflare and persist the
+ * endpoint config + write token. Shared by `agents share setup` and the unified
+ * `agents setup share` wizard. */
+export declare function runShareProvision(opts: {
+    bundle: string;
+    worker: string;
+    bucket: string;
+    account?: string;
+    token?: string;
+    domain?: string;
+}): Promise<void>;
+/** Join an existing share endpoint (no provisioning): prompt for the endpoint
+ * details + write token and persist them. Shared by `agents share join` and the
+ * unified `agents setup share` wizard. */
+export declare function runShareJoin(baseUrl: string): Promise<void>;

package/dist/commands/share.js

@@ -52,7 +52,7 @@ export function registerShareCommands(program) {
         .option('--domain <host>', 'also map a custom domain (e.g. share.agents-cli.sh) if the token owns the zone')
         .action(async (opts) => {
         try {
-            await runSetup(opts);
+            await runShareProvision(opts);
         }
         catch (e) {
             console.error(chalk.red(e.message));
@@ -65,7 +65,7 @@ export function registerShareCommands(program) {
         .argument('<baseUrl>', 'base URL of the endpoint, e.g. https://share.agents-cli.sh')
         .action(async (baseUrl) => {
         try {
-            await runJoin(baseUrl);
+            await runShareJoin(baseUrl);
         }
         catch (e) {
             console.error(chalk.red(e.message));
@@ -85,7 +85,10 @@ export function registerShareCommands(program) {
         console.log(chalk.dim(`worker ${cfg.workerName} · bucket ${cfg.bucketName} · account ${cfg.accountId}`));
     });
 }
-async function runSetup(opts) {
+/** Provision a fresh R2 bucket + Worker on the user's Cloudflare and persist the
+ * endpoint config + write token. Shared by `agents share setup` and the unified
+ * `agents setup share` wizard. */
+export async function runShareProvision(opts) {
     const { default: ora } = await import('ora');
     const { input } = await import('@inquirer/prompts');
     const { apiToken, accountId: acctFromBundle } = readCloudflareCreds(opts.bundle, {
@@ -132,7 +135,10 @@ async function runSetup(opts) {
         throw e;
     }
 }
-async function runJoin(baseUrl) {
+/** Join an existing share endpoint (no provisioning): prompt for the endpoint
+ * details + write token and persist them. Shared by `agents share join` and the
+ * unified `agents setup share` wizard. */
+export async function runShareJoin(baseUrl) {
     const { password, input } = await import('@inquirer/prompts');
     const clean = baseUrl.replace(/\/+$/, '');
     const workerName = await input({ message: 'Worker name', default: DEFAULT_WORKER_NAME });