@phnx-labs/agents-cli 1.19.2 → 1.20.0

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 = '';
@@ -339,6 +375,11 @@ export const AGENTS = {
     // 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,40 @@ 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, 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',
+        installScript: 'curl -fsSL https://x.ai/cli/install.sh | bash -s VERSION',
         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,
+            rulesImports: true,
+        },
     },
 };
 /** All registered agent IDs derived from the AGENTS registry. */
@@ -499,6 +550,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 +595,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 +674,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 +763,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 +813,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 +828,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;
     }
@@ -1167,7 +1254,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 +1290,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/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,7 @@ isElectron = false) {
         '--no-first-run',
         '--no-default-browser-check',
         '--disable-features=DefaultBrowserSetting,ChromeWhatsNewUI',
+        '--disable-crash-reporter',
         ...(options.headless ? ['--headless=new'] : []),
         `--window-size=${viewport.width},${viewport.height}`,
         ...(viewport.x !== undefined && viewport.y !== undefined
@@ -109,8 +149,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;

package/dist/lib/browser/domain-skills.js

@@ -0,0 +1,157 @@
+/**
+ * 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.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/** Where domain-skills live. Override via $AGENTS_BROWSER_DOMAIN_SKILLS_DIR for tests. */
+export function domainSkillsRoot() {
+    const override = process.env.AGENTS_BROWSER_DOMAIN_SKILLS_DIR;
+    if (override)
+        return override;
+    return path.join(os.homedir(), '.agents', 'skills', 'browser', 'domain-skills');
+}
+/**
+ * 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 function hostnameMatchCandidates(hostname) {
+    const cleaned = hostname.toLowerCase().replace(/^www\./, '');
+    if (!cleaned)
+        return [];
+    const parts = cleaned.split('.').filter(Boolean);
+    const out = new Set();
+    out.add(cleaned);
+    // Progressive label-stripping from the left: app.slack.com -> slack.com.
+    for (let i = 1; i < parts.length; i++) {
+        out.add(parts.slice(i).join('.'));
+    }
+    // Second-level label without TLD: app.slack.com -> slack, perplexity.ai -> perplexity.
+    if (parts.length >= 2) {
+        out.add(parts[parts.length - 2]);
+    }
+    // First label too, so mail.google.com can resolve a `mail` dir if that's how
+    // the user organized their skills. Last so explicit second-level wins.
+    if (parts.length >= 2) {
+        out.add(parts[0]);
+    }
+    return Array.from(out);
+}
+/** Parse a SKILL.md's frontmatter `domains:` list, if any. Best-effort, no schema. */
+function parseDomainsFrontmatter(content) {
+    // Frontmatter must be at file start: ---\n...\n---\n
+    if (!content.startsWith('---'))
+        return [];
+    const end = content.indexOf('\n---', 3);
+    if (end < 0)
+        return [];
+    const fm = content.slice(3, end);
+    // Inline array form: domains: [a, b, c]
+    const inline = fm.match(/^domains:\s*\[([^\]]*)\]/m);
+    if (inline) {
+        return inline[1]
+            .split(',')
+            .map((s) => s.trim().replace(/^["']|["']$/g, '').toLowerCase())
+            .filter(Boolean);
+    }
+    // Block list form:
+    //   domains:
+    //     - a
+    //     - b
+    const block = fm.match(/^domains:\s*\n((?:\s+-\s+\S+\n?)+)/m);
+    if (block) {
+        return block[1]
+            .split('\n')
+            .map((line) => line.replace(/^\s*-\s*/, '').trim().replace(/^["']|["']$/g, '').toLowerCase())
+            .filter(Boolean);
+    }
+    return [];
+}
+/**
+ * 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 function resolveDomainSkill(url) {
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+    if (!hostname)
+        return null;
+    const root = domainSkillsRoot();
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const candidates = hostnameMatchCandidates(hostname);
+    if (candidates.length === 0)
+        return null;
+    const candidateSet = new Set(candidates);
+    const indexed = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const skillPath = path.join(root, e.name, 'SKILL.md');
+        let content;
+        try {
+            content = fs.readFileSync(skillPath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        indexed.push({
+            name: e.name,
+            skillPath,
+            content,
+            pinned: parseDomainsFrontmatter(content),
+        });
+    }
+    // Pass 1: explicit `domains:` overrides.
+    for (const s of indexed) {
+        for (const d of s.pinned) {
+            if (candidateSet.has(d)) {
+                return { name: s.name, path: s.skillPath, content: s.content, hostname };
+            }
+        }
+    }
+    // Pass 2: directory-name match, walking candidates in priority order.
+    const byName = new Map(indexed.map((s) => [s.name.toLowerCase(), s]));
+    for (const c of candidates) {
+        const hit = byName.get(c);
+        if (hit) {
+            return { name: hit.name, path: hit.skillPath, content: hit.content, hostname };
+        }
+    }
+    return null;
+}