@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/agents.js

@@ -2,7 +2,7 @@
  * Core agent configuration and detection module.
  *
  * Defines the canonical registry of all supported AI coding agents (Claude, Codex,
- * Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Roo) with their
+ * Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Roo, Grok) with their
  * CLI commands, config paths, capability flags, and MCP integration points.
  *
  * Provides functions for detecting installed CLIs, resolving version-managed binaries,
@@ -18,7 +18,6 @@ import chalk from 'chalk';
 import { walkForFiles } from './fs-walk.js';
 import { getVersionsDir, getShimsDir, getCliVersionCachePath } from './state.js';
 import { resolveVersion, getVersionHomePath, getBinaryPath } from './versions.js';
-import { loadClaudeOauth } from './usage.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
 /**
@@ -77,6 +76,43 @@ function findInPath(command) {
     }
     return null;
 }
+/** Grok-specific binary resolution.
+ * Grok does not live in node_modules/.bin. Its versioned binaries live in
+ * ~/.grok/downloads/ with names like `grok-0.1.218-macos-aarch64`.
+ * We still use the agents-cli version dir for *config isolation* via GROK_HOME.
+ */
+function resolveGrokBinary(version) {
+    const grokDownloads = path.join(HOME, '.grok', 'downloads');
+    if (!fs.existsSync(grokDownloads))
+        return null;
+    const entries = fs.readdirSync(grokDownloads);
+    // Prefer exact version match in filename
+    if (version && version !== 'latest') {
+        const match = entries.find((e) => e.includes(version) && e.startsWith('grok-'));
+        if (match)
+            return path.join(grokDownloads, match);
+    }
+    // Fallback: the "current" symlink or the plain `grok-*` without version in name
+    const current = entries.find((e) => e === 'grok' || e.startsWith('grok-') && !e.match(/grok-\d/));
+    if (current)
+        return path.join(grokDownloads, current);
+    // Last resort: newest file by mtime
+    let latest = null;
+    let latestMtime = 0;
+    for (const e of entries) {
+        if (!e.startsWith('grok-'))
+            continue;
+        try {
+            const stat = fs.statSync(path.join(grokDownloads, e));
+            if (stat.mtimeMs > latestMtime) {
+                latestMtime = stat.mtimeMs;
+                latest = e;
+            }
+        }
+        catch { }
+    }
+    return latest ? path.join(grokDownloads, latest) : null;
+}
 function splitCommandLine(command) {
     const args = [];
     let current = '';
@@ -155,7 +191,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, rulesImports: true },
+        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, modes: ['plan', 'edit', 'auto', 'skip'], rulesImports: true },
     },
     // codex hooks: gated to >= 0.116.0 (introduced [features] codex_hooks flag).
     codex: {
@@ -174,7 +210,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' } },
+        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, modes: ['plan', 'edit', 'skip'] },
     },
     gemini: {
         id: 'gemini',
@@ -193,7 +229,7 @@ export const AGENTS = {
         supportsHooks: true,
         nativeAgentsSkillsDir: true,
         // gemini hooks: shipped in v0.26.0 (Jan 2026); older binaries silently ignore the `hooks` key.
-        capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, rulesImports: true },
+        capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit', 'skip'], rulesImports: true },
     },
     cursor: {
         id: 'cursor',
@@ -211,7 +247,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['edit', 'skip'] },
     },
     opencode: {
         id: 'opencode',
@@ -228,7 +264,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit'] },
     },
     openclaw: {
         id: 'openclaw',
@@ -245,7 +281,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '{{ARGUMENTS}}',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: false, plugins: true },
+        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: false, plugins: true, modes: ['plan', 'edit', 'skip'] },
     },
     copilot: {
         id: 'copilot',
@@ -262,7 +298,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit', 'auto', 'skip'] },
     },
     amp: {
         id: 'amp',
@@ -279,7 +315,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit'] },
     },
     kiro: {
         id: 'kiro',
@@ -297,7 +333,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['edit'] },
     },
     goose: {
         id: 'goose',
@@ -315,7 +351,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: false, commands: false, plugins: false },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: false, commands: false, plugins: false, modes: ['edit'] },
     },
     roo: {
         id: 'roo',
@@ -333,12 +369,17 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit'] },
     },
     // Google Antigravity CLI (`agy`) — official replacement for Gemini CLI as of IO 2026.
     // configDir nests inside `~/.gemini/` since agy shares the parent dir with the Gemini
     // CLI but isolates its own state in the `antigravity-cli/` subdir. Per-version HOME
     // isolation works because the shim's configDirName carries the full nested path.
+    // Auth: Google OAuth on first launch, or ANTIGRAVITY_API_KEY env var for headless.
+    // Hooks: JSON entries under a top-level `hooks` key in settings.json; events are
+    // before_tool_call, after_model_call, on_loop_stop, on_error. Plugins are the
+    // renamed Gemini CLI extensions. Permissions live in settings.json under a
+    // `permissions` key with allow/deny arrays.
     antigravity: {
         id: 'antigravity',
         name: 'Antigravity',
@@ -354,30 +395,41 @@ export const AGENTS = {
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '{{args}}',
-        supportsHooks: false,
-        nativeAgentsSkillsDir: true,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, rulesImports: false },
+        supportsHooks: true,
+        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, modes: ['edit', 'skip'], rulesImports: false },
     },
     // xAI Grok Build CLI (`grok`) — early beta, SuperGrok Heavy. Auth via OAuth on
-    // first launch, or GROK_CODE_XAI_API_KEY env var for headless. MCP supported
-    // out of the box; exact config file path verified at first install.
+    // first launch, or XAI_API_KEY env var for headless. MCP servers configured inline
+    // under [mcp_servers] in ~/.grok/config.toml. Hooks auto-discovered from
+    // ~/.grok/hooks/ (+ project .grok/hooks/) — events PreToolUse, PostToolUse, etc.
+    // Plugins live in ~/.grok/plugins/ with marketplaces. Permissions: --allow/--deny
+    // CLI flags or [permission] TOML block in ~/.grok/config.toml.
     grok: {
         id: 'grok',
         name: 'Grok',
-        color: 'whiteBright',
+        color: 'cyanBright',
         cliCommand: 'grok',
         npmPackage: '',
         installScript: 'curl -fsSL https://x.ai/cli/install.sh | bash',
         configDir: path.join(HOME, '.grok'),
-        commandsDir: path.join(HOME, '.grok', 'commands'),
-        commandsSubdir: 'commands',
+        commandsDir: '', // Grok primarily uses skills + slash commands from skills
+        commandsSubdir: '',
         skillsDir: path.join(HOME, '.grok', 'skills'),
-        hooksDir: 'hooks',
+        hooksDir: path.join(HOME, '.grok', 'hooks'),
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
-        supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
+        supportsHooks: true,
+        capabilities: {
+            hooks: true,
+            mcp: true,
+            allowlist: true, // maps to Grok's granular Bash/Edit/Write/Read/Grep/WebFetch/MCPTool rules
+            skills: true,
+            commands: false, // covered by skills
+            plugins: true,
+            modes: ['plan', 'edit', 'skip'],
+            rulesImports: true,
+        },
     },
 };
 /** All registered agent IDs derived from the AGENTS registry. */
@@ -499,6 +551,18 @@ export async function getCliState(agentId) {
         }
     }
     // Non-version-managed: single PATH lookup + cached version read
+    // Special case for grok: it manages its own binaries in ~/.grok/downloads/
+    if (agentId === 'grok') {
+        const grokBin = resolveGrokBinary();
+        if (!grokBin) {
+            return { installed: false, version: null, path: null };
+        }
+        return {
+            installed: true,
+            version: await getCachedVersionForBinary(agentId, grokBin),
+            path: grokBin,
+        };
+    }
     const binaryPath = findInPath(agent.cliCommand);
     if (!binaryPath) {
         return { installed: false, version: null, path: null };
@@ -532,7 +596,7 @@ export function isConfigured(agentId) {
  */
 export async function getUnmanagedAgentInstalls() {
     const unmanaged = [];
-    const candidates = ['claude', 'codex', 'gemini'];
+    const candidates = ['claude', 'codex', 'gemini', 'grok'];
     for (const agentId of candidates) {
         const agent = AGENTS[agentId];
         try {
@@ -611,13 +675,15 @@ export async function getAccountInfo(agentId, home) {
                     ['org', organizationId],
                 ]);
                 const usageKey = buildIdentityKey(agentId, [['org', organizationId]]);
+                // Plan is derived from .claude.json's billingType only. Reading
+                // subscriptionType from the keychain item ("Claude Code-credentials-<hash>")
+                // forces a macOS Keychain ACL prompt on every `agents run` (one prompt per
+                // installed version under balanced rotation) because Claude Code writes its
+                // credentials with its own process in the ACL — our helper isn't trusted by
+                // that item. Callers that genuinely need subscriptionType (e.g. detailed
+                // `agents view`) should call loadClaudeOauth() directly.
                 let plan = null;
-                const keychainOauth = await loadClaudeOauth(home);
-                if (keychainOauth?.subscriptionType) {
-                    plan = keychainOauth.subscriptionType.charAt(0).toUpperCase()
-                        + keychainOauth.subscriptionType.slice(1);
-                }
-                else if (oa?.billingType === 'stripe_subscription') {
+                if (oa?.billingType === 'stripe_subscription') {
                     plan = 'Pro';
                 }
                 else if (oa?.billingType) {
@@ -698,6 +764,19 @@ export async function getAccountInfo(agentId, home) {
                 const data = JSON.parse(await fs.promises.readFile(path.join(base, '.gemini', 'google_accounts.json'), 'utf-8'));
                 return { ...empty, email: data.active || null, lastActive };
             }
+            case 'grok': {
+                // Grok stores auth in ~/.grok/auth.json
+                try {
+                    const authPath = path.join(base, '.grok', 'auth.json');
+                    if (fs.existsSync(authPath)) {
+                        const data = JSON.parse(await fs.promises.readFile(authPath, 'utf-8'));
+                        const email = data.email || data.user?.email || data.account?.email || null;
+                        return { ...empty, email, lastActive };
+                    }
+                }
+                catch { }
+                return { ...empty, lastActive };
+            }
             default:
                 return { ...empty, lastActive };
         }
@@ -735,6 +814,12 @@ function getSessionDir(agentId, base) {
             return path.join(base, '.codex', 'sessions');
         case 'gemini':
             return path.join(base, '.gemini', 'tmp');
+        case 'grok':
+            return path.join(base, '.grok', 'sessions');
+        case 'copilot':
+            // Copilot persists sessions at ~/.copilot/session-state/<id>/events.jsonl.
+            // The events.jsonl is the canonical NDJSON event stream per session.
+            return path.join(base, '.copilot', 'session-state');
         default:
             return null;
     }
@@ -744,9 +829,12 @@ function getSessionExtension(agentId) {
     switch (agentId) {
         case 'claude':
         case 'codex':
+        case 'copilot':
             return '.jsonl';
         case 'gemini':
             return '.json';
+        case 'grok':
+            return '.json'; // sessions contain summary.json, events.jsonl, etc.
         default:
             return null;
     }
@@ -1110,7 +1198,7 @@ function parseMcpFromOpenCodeConfig(configPath) {
 /**
  * Get user-scoped MCP config path for an agent.
  */
-function getUserMcpConfigPath(agentId) {
+export function getUserMcpConfigPath(agentId) {
     const agent = AGENTS[agentId];
     switch (agentId) {
         case 'claude':
@@ -1128,6 +1216,9 @@ function getUserMcpConfigPath(agentId) {
         case 'openclaw':
             // OpenClaw uses openclaw.json
             return path.join(agent.configDir, 'openclaw.json');
+        case 'copilot':
+            // GitHub Copilot CLI uses mcp-config.json (matches versioned + project paths)
+            return path.join(agent.configDir, 'mcp-config.json');
         case 'antigravity':
             // agy uses mcp_config.json inside its nested config dir (~/.gemini/antigravity-cli/)
             return path.join(agent.configDir, 'mcp_config.json');
@@ -1167,7 +1258,7 @@ export function getMcpConfigPathForHome(agentId, home) {
         case 'antigravity':
             return path.join(home, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
-            return path.join(home, '.grok', 'mcp.json');
+            return path.join(home, '.grok', 'config.toml');
         default:
             return path.join(home, `.${agentId}`, 'settings.json');
     }
@@ -1203,7 +1294,7 @@ function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
         case 'antigravity':
             return path.join(cwd, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
-            return path.join(cwd, '.grok', 'mcp.json');
+            return path.join(cwd, '.grok', 'config.toml');
         default:
             return path.join(cwd, `.${agentId}`, 'settings.json');
     }

package/dist/lib/auto-pull-worker.js

@@ -14,6 +14,15 @@ import { tryAutoPull, isGitRepo } from './git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, getFetchCacheDir, } from './state.js';
 import { lockFilePath, statusFilePath } from './auto-pull.js';
 const LOCK_TTL_MS = 5 * 60 * 1000;
+/**
+ * Background auto-pull of ~/.agents-system/ is off by default. When enabled it
+ * silently fast-forwards a tracked source tree that the CLI then reads as a
+ * source of skills, hooks, install manifests, and commands — anyone with push
+ * access to that upstream gets remote code execution on every user the next
+ * time they invoke a command that loads a system resource. Operators that
+ * really want the convenience can set AGENTS_AUTO_PULL=1.
+ */
+const ENABLE_AUTO_PULL = process.env.AGENTS_AUTO_PULL === '1';
 function ensureFetchDir() {
     const dir = getFetchCacheDir();
     if (!fs.existsSync(dir)) {
@@ -84,7 +93,15 @@ async function processTarget(target) {
         return;
     try {
         if (target.mode === 'pull') {
-            await tryAutoPull(target.dir);
+            if (!ENABLE_AUTO_PULL) {
+                // Demote to a fetch + notify; the user still sees ahead/behind on the
+                // next foreground CLI invocation, but the source tree is never mutated
+                // by a detached worker.
+                await notifyRepo(target);
+            }
+            else {
+                await tryAutoPull(target.dir);
+            }
         }
         else {
             await notifyRepo(target);

package/dist/lib/browser/cdp.d.ts

@@ -32,7 +32,14 @@ export interface BrowserDiscovery {
     wsUrl: string;
     browser: string;
 }
-export declare function discoverBrowserWsUrl(port: number, host?: string): Promise<BrowserDiscovery>;
+export declare class BrowserCdpConnectionError extends Error {
+    readonly port: number;
+    readonly profileName: string;
+    readonly host: string;
+    constructor(port: number, profileName?: string, host?: string);
+}
+export declare function formatBrowserCdpConnectionError(port: number, profileName?: string, host?: string): string;
+export declare function discoverBrowserWsUrl(port: number, host?: string, profileName?: string): Promise<BrowserDiscovery>;
 export declare function normalizeBrowserName(s: string): string;
 export declare function verifyBrowserIdentity(reported: string, expected: string, port: number, host?: string): void;
 export declare function listTargets(port: number, host?: string): Promise<Array<{

package/dist/lib/browser/cdp.js

@@ -152,10 +152,47 @@ export class CDPClient {
         this.transport = null;
     }
 }
-export async function discoverBrowserWsUrl(port, host = 'localhost') {
-    const response = await fetch(`http://${host}:${port}/json/version`);
+export class BrowserCdpConnectionError extends Error {
+    port;
+    profileName;
+    host;
+    constructor(port, profileName = '<name>', host = 'localhost') {
+        super(formatBrowserCdpConnectionError(port, profileName, host));
+        this.port = port;
+        this.profileName = profileName;
+        this.host = host;
+        this.name = 'BrowserCdpConnectionError';
+    }
+}
+export function formatBrowserCdpConnectionError(port, profileName = '<name>', host = 'localhost') {
+    const target = host === 'localhost' || host === '127.0.0.1'
+        ? `port ${port}`
+        : `${host}:${port}`;
+    return [
+        `Could not connect to Chrome on ${target}.`,
+        `- Is Chrome running with --remote-debugging-port=${port}?`,
+        `- Try: agents browser start --profile ${profileName}`,
+    ].join('\n');
+}
+export async function discoverBrowserWsUrl(port, host = 'localhost', profileName = '<name>') {
+    // Node's fetch has no default timeout — a port that ACKs the TCP connect
+    // but never sends an HTTP response will hang here indefinitely. Bound the
+    // discovery probe so the caller can surface an actionable error in seconds,
+    // not minutes.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3000);
+    let response;
+    try {
+        response = await fetch(`http://${host}:${port}/json/version`, { signal: controller.signal });
+    }
+    catch {
+        throw new BrowserCdpConnectionError(port, profileName, host);
+    }
+    finally {
+        clearTimeout(timer);
+    }
     if (!response.ok) {
-        throw new Error(`Failed to discover browser: ${response.status}`);
+        throw new BrowserCdpConnectionError(port, profileName, host);
     }
     const data = (await response.json());
     const browserField = data.Browser || data.Product || '';

package/dist/lib/browser/chrome.d.ts

@@ -1,6 +1,19 @@
 import type { ChromeOptions } from './types.js';
 import type { BrowserType } from './types.js';
 export declare function findBrowserPath(browserType: BrowserType, customBinary?: string): string;
+/**
+ * Walk the per-platform priority list and return the first browser that's
+ * actually installed on disk. Returns null if none of them are present.
+ *
+ * This is the auto-pick the `agents browser start` command uses when the user
+ * doesn't pass `--profile`. The intent matches "use whatever's preinstalled,"
+ * but constrained to Chromium-family binaries so CDP works without a new
+ * driver layer.
+ */
+export declare function findFirstInstalledBrowser(platform?: string): {
+    browserType: BrowserType;
+    binary: string;
+} | null;
 export interface LaunchResult {
     pid: number;
     port: number;

package/dist/lib/browser/chrome.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { getProfileRuntimeDir } from './profiles.js';
 import { discoverBrowserWsUrl, registerPipeTransport } from './cdp.js';
-import { readBundle, resolveBundleEnv, bundleExists } from '../secrets/bundles.js';
+import { readAndResolveBundleEnv, bundleExists } from '../secrets/bundles.js';
 import { writeProfileRuntime, readProfileRuntime } from './runtime-state.js';
 const BROWSER_PATHS = {
     darwin: {
@@ -65,6 +65,45 @@ export function findBrowserPath(browserType, customBinary) {
     }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
+// Per-platform Chromium-family priority list for "no --profile" auto-pick.
+// Order is: most-likely-installed-and-stable first. Safari and Firefox are
+// intentionally excluded — they don't speak the Chrome DevTools Protocol the
+// way cdp.ts expects, so they'd need separate drivers.
+const DEFAULT_BROWSER_PRIORITY = {
+    // macOS: Chrome leads (>70% of dev machines), then the rest of the family.
+    darwin: ['chrome', 'brave', 'edge', 'chromium', 'comet'],
+    // Linux: Chrome/Chromium first (apt/snap), then Brave/Edge if present.
+    linux: ['chrome', 'chromium', 'brave', 'edge'],
+    // Windows: Edge is preinstalled on every supported build, so it's the
+    // reliable always-there default.
+    win32: ['edge', 'chrome', 'brave'],
+};
+/**
+ * Walk the per-platform priority list and return the first browser that's
+ * actually installed on disk. Returns null if none of them are present.
+ *
+ * This is the auto-pick the `agents browser start` command uses when the user
+ * doesn't pass `--profile`. The intent matches "use whatever's preinstalled,"
+ * but constrained to Chromium-family binaries so CDP works without a new
+ * driver layer.
+ */
+export function findFirstInstalledBrowser(platform = os.platform()) {
+    const priority = DEFAULT_BROWSER_PRIORITY[platform];
+    if (!priority)
+        return null;
+    const platformPaths = BROWSER_PATHS[platform];
+    if (!platformPaths)
+        return null;
+    for (const browserType of priority) {
+        const candidates = platformPaths[browserType] || [];
+        for (const p of candidates) {
+            if (fs.existsSync(p)) {
+                return { browserType, binary: p };
+            }
+        }
+    }
+    return null;
+}
 export async function launchBrowser(profileName, browserType, port, options = {}, secrets, customBinary, 
 // `electron: true` distinguishes Notion / VS Code-style apps from
 // regular Chrome — purely informational, stored in meta.json so the
@@ -99,6 +138,11 @@ isElectron = false) {
         '--no-first-run',
         '--no-default-browser-check',
         '--disable-features=DefaultBrowserSetting,ChromeWhatsNewUI',
+        '--disable-crash-reporter',
+        // Suppress navigator.webdriver = true, which Chromium sets whenever a
+        // remote-debugging transport is active. That property is the loudest
+        // signal Cloudflare Turnstile, hCaptcha, and similar checks read.
+        '--disable-blink-features=AutomationControlled',
         ...(options.headless ? ['--headless=new'] : []),
         `--window-size=${viewport.width},${viewport.height}`,
         ...(viewport.x !== undefined && viewport.y !== undefined
@@ -109,8 +153,7 @@ isElectron = false) {
     let env = { ...process.env };
     if (secrets && bundleExists(secrets)) {
         try {
-            const bundle = readBundle(secrets);
-            const bundleEnv = resolveBundleEnv(bundle, { caller: 'browser profile' });
+            const { env: bundleEnv } = readAndResolveBundleEnv(secrets, { caller: 'browser profile' });
             env = { ...env, ...bundleEnv };
         }
         catch {

package/dist/lib/browser/domain-skills.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Domain-skill discovery for `agents browser start`.
+ *
+ * When a browser task opens a URL, look up a site-specific SKILL.md from
+ * `~/.agents/skills/browser/domain-skills/<dir>/SKILL.md` and surface its
+ * contents so the calling agent gets per-site operating instructions
+ * (selectors, gotchas, sign-in quirks) before it starts driving the page.
+ *
+ * Matching is intentionally simple: derive the hostname's second-level
+ * label (e.g. `perplexity` from `perplexity.ai`, `slack` from `app.slack.com`)
+ * and look for a directory of the same name. If the user wants a different
+ * mapping (e.g. `mail.google.com` -> `gmail/`), they can pin it via a
+ * `domains: [...]` array in the SKILL.md frontmatter; that override beats
+ * the directory-name match.
+ */
+/** Result of resolving a URL to a domain-skill. */
+export interface ResolvedDomainSkill {
+    /** Skill identifier — the directory name under domain-skills/. */
+    name: string;
+    /** Absolute path to the SKILL.md that was matched. */
+    path: string;
+    /** Full SKILL.md contents (frontmatter included). */
+    content: string;
+    /** Hostname the match was made against (post-www strip). */
+    hostname: string;
+}
+/** Where domain-skills live. Override via $AGENTS_BROWSER_DOMAIN_SKILLS_DIR for tests. */
+export declare function domainSkillsRoot(): string;
+/**
+ * Derive match candidates from a hostname. Order matters — earlier candidates
+ * are tried first.
+ *
+ * Examples:
+ *   perplexity.ai      -> ['perplexity.ai', 'perplexity']
+ *   app.slack.com      -> ['app.slack.com', 'slack.com', 'slack']
+ *   mail.google.com    -> ['mail.google.com', 'google.com', 'google', 'mail']
+ *   higgsfield.ai      -> ['higgsfield.ai', 'higgsfield']
+ */
+export declare function hostnameMatchCandidates(hostname: string): string[];
+/**
+ * Resolve a URL to its matching domain-skill, or null if none.
+ *
+ * Two-pass strategy:
+ *   1. Index every SKILL.md in the root and read its `domains:` frontmatter.
+ *      If any pinned domain matches a candidate, return that skill.
+ *   2. Fall back to directory-name match against the candidate list.
+ *
+ * Errors (missing root, unreadable file, invalid URL) are swallowed and
+ * yield null — domain-skill discovery must never break browser start.
+ */
+export declare function resolveDomainSkill(url: string): ResolvedDomainSkill | null;