@phnx-labs/agents-cli 1.22.93 → 1.22.95

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.22.95
+
+- **Firefox automation over WebDriver BiDi (PHNX-4043).** `agents browser` now drives
+  Firefox, which dropped the Chrome DevTools Protocol in 129. Every Firefox profile in
+  `profiles.ini` is discovered read-only as a `firefox-<name>` browser profile
+  (`firefox-default`, `firefox-default-release`, …) pinned to that profile directory;
+  agents launch it headless with a debug port (or attach to a running one, failing loud
+  when a portless Firefox already holds the profile). Supported verbs: start, navigate,
+  tab add, tabs, evaluate, refs, click, fill/type, scroll, screenshot, done — with the
+  same same-task reopen semantics as the rest of the service. A trusted pointer click
+  goes through `input.performActions`. Network capture, upload, and PDF fail loud with a
+  structured error naming a Chromium-family profile. Source: `apps/cli/src/lib/browser/drivers/firefox.ts`,
+  `apps/cli/src/lib/browser/firefox-discovery.ts`, `apps/cli/src/lib/browser/service.ts`.
+
+- **Comet's own profiles are browser profiles, and discovered profiles reach the whole fleet (PHNX-4042).** On a Mac, `agents browser profiles list` now shows one profile per entry in Comet's profile menu (`comet-work`, ...), read from Comet's `Local State` and pinned to Comet's real user-data dir and `--profile-directory`, next to the `arc-*` rows for Arc Spaces. Agents and you share one Comet window per profile: agents attach when it runs with remote debugging on the profile's port, launch Comet on your own store when it is not running (over a TCP port, so the instance outlives a daemon restart and the ownership guard can verify it), and fail loud with the relaunch command when it runs without a port. The daemon's fleet-sync tick publishes every discovered profile into this device's declaration, so other boxes list it with `WHERE=<device>` and `--profile arc-gmail` from a worker routes to the Mac that owns it. `AGENTS_COMET_DIR` points discovery at another store. Source: `cli/src/lib/browser/chromium-discovery.ts`, `cli/src/lib/browser/profiles.ts`, `cli/src/lib/browser/chrome.ts`, `cli/src/lib/browser/drivers/local.ts`, `cli/src/lib/daemon/usage-sync-service.ts`.
+
+## 1.22.94
+
+- **Agents drive your running Arc, one profile per Arc Space (PHNX-2399, macOS).** On a Mac with Arc, `agents browser profiles list` shows every Arc Space as a profile — `arc-gmail`, `arc-work`, `arc-dev`, named after the Space title — discovered read-only from Arc's `User Data/Local State` and `StorableSidebar.json`. A Space already carries its Arc profile's logins, so it is the browser profile agents pick with `--profile`; there is no separate Space flag and nothing to create. `agents browser use arc-gmail` makes it the default. Tabs are created, navigated, evaluated, and closed through Apple Events against the Arc you already have open — no debug port, no relaunch, never a second Arc. Agents only ever touch the tabs they created: durable task state addresses them by stable window, Space, and tab ids, a crash-safe marker intent guards creation, and closing a task removes only its own tabs. Creating a tab makes Arc select it for about 100 ms before the tab you had selected is restored; navigate, evaluate, and close are silent. Native refs, click, fill/type, scroll, and `tab focus` work; screenshots, promise evaluation, trusted input, network/console capture, uploads/downloads, and PDF fail with `ArcNativeCapabilityError` and point at a Chromium-family profile. Source: `cli/src/lib/browser/arc-discovery.ts`, `cli/src/lib/browser/drivers/arc.ts`, `cli/src/lib/browser/arc-dom.ts`, `cli/src/lib/browser/profiles.ts`, `cli/src/lib/browser/service.ts`, `cli/src/commands/browser.ts`.
+
 ## 1.22.93
 
 - **An idle reminder is not a permission request — attention is classified from explicit harness evidence, and time-based signals expire (PHNX-3999).** The fleet feed was rendering Claude's `idle_prompt` Notification ("the turn ended and you have been idle") as a `permission` with Approve/Deny — a session whose whole transcript was "reply with exactly: pong" → "pong" got an approval banner — and the state engine labelled any tool call that had run quietly for two minutes a permission too. Now a `notification` block is a `permission` only when its recorded subtype is `permission_prompt` and the session's transcript corroborates it (no tool result or new turn stamped after the block, process alive); the feed-publish hook no longer publishes `idle_prompt` at all, an `idle_prompt` block left on disk yields no request, an `elicitation_dialog` is a question with no invented buttons, and a pending tool call reads as `working` however long it has run. One unresolved record per `host/session/generation` is resolved by later evidence — a transcript event after the block, or a dead process — never by dismissing the banner. What the CLI cannot confirm (a stale hook block with no transcript cursor to check, a notification with no recorded subtype, an older peer's elapsed-time `permission` claim) is the new `unverified` kind: the banner and the `feed watch` stream say "Could not verify request" with an Open terminal action only, and `agents feed answer` refuses it. `computeLiveSignals` now memoizes only the parsed transcript tail on mtime and re-classifies against the current clock every call, so the 30-minute prose-question decay expires on schedule instead of freezing until someone types; rows carry `lastEventMs`, the harness stamp on the last meaningful event. Source: `cli/src/lib/feed/attention.ts`, `cli/src/lib/session/state.ts`, `cli/src/lib/session/active.ts`, `cli/src/lib/feed/feed.ts`, `cli/src/lib/feed/answer.ts`, `cli/src/lib/daemon/attention-notify-service.ts`.

package/dist/commands/browser.d.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { type BrowserProfile } from '../lib/browser/profiles.js';
 import { listInstalledBrowsers } from '../lib/browser/chrome.js';
+export declare function remoteStartTaskName(stdout: string, explicit?: string): string | undefined;
 /**
  * The fleet browser hub this box drives by default (`browser.device`), or
  * undefined to drive locally. It is one fleet-synced value in the central

package/dist/commands/browser.js

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import { spawnSync } from 'node:child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, formatProfilesTable, editProfile, renameProfile, assertRegistrableProfileName, isProfileLaunchableHere, isAttachOnlyProfile, resolveProfileDataDir, normalizeDataDir, } from '../lib/browser/profiles.js';
+import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, formatProfilesTable, editProfile, renameProfile, assertRegistrableProfileName, isProfileLaunchableHere, isAttachOnlyProfile, resolveProfileDataDir, normalizeDataDir, persistDiscoveredProfile, } from '../lib/browser/profiles.js';
 import { declaringDevices, migrateCentralBrowserProfiles, profileKind } from '../lib/browser/registry.js';
 import { resolveActor } from '../lib/actor.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
@@ -36,6 +36,8 @@ import { buildHar } from '../lib/browser/har.js';
 import { getCliVersion } from '../lib/version.js';
 import { runBrowserIPCStream } from '../lib/browser/stream.js';
 import { machineId } from '../lib/machine-id.js';
+import { isArcRunning } from '../lib/browser/drivers/arc.js';
+import { resolveBrowserTarget } from '../lib/browser/resolve-target.js';
 /**
  * Task name inferred from the local task→device index when `--task` was
  * omitted and this session owns exactly one open task. Set by the page-verb
@@ -161,6 +163,22 @@ async function dispatchBrowserToDevice(device, forwardedArgs, mode) {
         stderr: result.stderr,
     };
 }
+export function remoteStartTaskName(stdout, explicit) {
+    if (explicit)
+        return explicit;
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const decoded = JSON.parse(trimmed);
+        if (typeof decoded.task === 'string' && decoded.task.length > 0)
+            return decoded.task;
+    }
+    catch {
+        // Human output is one task name on the first non-empty line.
+    }
+    return trimmed.split('\n').map((line) => line.trim()).find(Boolean);
+}
 async function pullRemoteFile(device, remotePath, localPath) {
     const host = await resolveHost(device);
     if (!host) {
@@ -424,6 +442,7 @@ export async function runBrowserUse(name, opts, interactive = isInteractiveTermi
             console.error(`Available profiles: ${all.map((profile) => profile.name).join(', ')}`);
         return false;
     }
+    await persistDiscoveredProfile(selectedName);
     setConfigValue('browser.profile', selectedName);
     const endpoint = Object.values(getEndpointPresets(target))[0]?.target ?? '';
     console.log(`Default browser profile (this machine) is now "${selectedName}" (${target.browser}${endpoint ? `, ${endpoint}` : ''}).`);
@@ -484,7 +503,7 @@ function registerProfilesCommands(browser) {
             console.log(JSON.stringify(allProfiles.map((profile) => ({
                 ...profile,
                 devices: profile.devices,
-                kind: profileKind(profile.name),
+                kind: profile.arc || profile.firefox ? 'identity' : profileKind(profile.name),
                 isConfiguredDefault: profile.name === configuredDefault,
             })), null, 2));
             return;
@@ -927,6 +946,15 @@ function registerProfilesCommands(browser) {
             console.log(`Target filter: ${profile.targetFilter}`);
         if (profile.description)
             console.log(`Description: ${profile.description}`);
+        if (profile.arc) {
+            console.log(`Arc Space: ${profile.arc.spaceTitle} (${profile.arc.spaceId})`);
+            console.log(`Arc profile: ${profile.arc.profileName} (${profile.arc.profileId})`);
+        }
+        if (profile.firefox) {
+            console.log(`Firefox profile: ${profile.firefox.profileName}${profile.firefox.isDefault ? ' (default)' : ''}`);
+            if (profile.userDataDir)
+                console.log(`Profile directory: ${profile.userDataDir}`);
+        }
         const presets = getEndpointPresets(profile);
         const defaultName = profile.defaultEndpoint && presets[profile.defaultEndpoint]
             ? profile.defaultEndpoint
@@ -952,6 +980,8 @@ function registerProfilesCommands(browser) {
             console.log(`Headless: true`);
         // Login state per known service: live session + account identity + whether
         // login creds are declared in the profile's secrets bundle.
+        if (profile.arc || profile.firefox)
+            return;
         const active = await loginsForProfile(profile.name);
         const accounts = await accountsForProfile(profile.name);
         const lines = [];
@@ -975,7 +1005,7 @@ function registerProfilesCommands(browser) {
     profiles
         .command('remove <name>')
         .alias('delete')
-        .description('Remove a browser profile (drops YAML config + all cached runtime dirs)')
+        .description('Remove the agents-cli profile alias and cached runtime dirs (never deletes native Arc data)')
         .option('--keep-cache', "Leave ~/.agents/.cache/browser/<name>* dirs in place (don't wipe chrome-data)")
         .action(async (name, opts) => {
         await deleteProfile(name);
@@ -1094,12 +1124,20 @@ function registerProfilesCommands(browser) {
       profile that is in use, the configured default, or the \`auto-chrome\`
       profile a setup wizard created.
 
-      Arc is your PERSONAL browser and Comet is what agents drive (PHNX-3967).
-      Arc is single-instance with no debug port, so agents can only attach to a
-      running Arc, never launch one — it stays yours. Point agents at Comet as
-      one canonical signed-in profile that never spawns a second window:
+      On a Mac with Arc, every Arc Space is listed as a profile (arc-gmail,
+      arc-work, ...) discovered read-only from Arc's own metadata — a Space
+      already carries its Arc profile's logins, so it IS the browser profile.
+      Agents attach to the running Arc through Apple Events and never launch or
+      relaunch it. Comet's own profiles are listed the same way (comet-work, ...),
+      pinned to Comet's real user-data dir, so agents and you share one Comet
+      window per profile: agents attach when it is running with remote debugging,
+      launch it on your store when it is not running, and fail loud with the
+      relaunch command when it runs without a port. The daemon publishes every
+      discovered profile into this device's declaration, so other fleet boxes list
+      it with WHERE=<this device> and route to it. Point agents at Comet when a workflow needs screenshots,
+      downloads, network capture, or trusted input:
         agents browser profiles create agents-comet --browser comet --attach-only
-      An \`--attach-only\` profile (and Arc, always) attaches to a browser you
+      A CDP \`--attach-only\` profile attaches to a browser you
       already started with remote debugging and fails loud with the relaunch
       command otherwise, pinned to a durable --user-data-dir so the sign-in
       survives quit+relaunch. A foreign browser squatting the canonical port is
@@ -1115,6 +1153,17 @@ function registerProfilesCommands(browser) {
             console.error(`Profile "${name}" not found`);
             process.exit(1);
         }
+        if ((profile.arc || profile.firefox) && !isFleetRemoteInvocation()) {
+            const routed = resolveBrowserTarget(profile.name);
+            if (!routed.local && routed.commandDispatch) {
+                const result = await dispatchBrowserToDevice(routed.device, ['browser', 'profiles', 'doctor', name], 'capture');
+                process.stdout.write(result.stdout);
+                process.stderr.write(result.stderr);
+                if (result.code !== 0)
+                    process.exit(result.code);
+                return;
+            }
+        }
         const checks = [];
         // 0. Declaration topology. An identity-bearing profile declared by a
         //    different device cannot be diagnosed through a loopback CDP endpoint
@@ -1139,6 +1188,31 @@ function registerProfilesCommands(browser) {
             }
             process.exit(1);
         }
+        if (profile.arc) {
+            checks.push({
+                label: 'space',
+                ok: true,
+                detail: `${profile.arc.spaceTitle} (${profile.arc.spaceId})`,
+            });
+            checks.push({
+                label: 'arc-profile',
+                ok: true,
+                detail: `${profile.arc.profileName} (${profile.arc.profileId})`,
+            });
+            const running = await isArcRunning();
+            checks.push({
+                label: 'Arc process',
+                ok: running,
+                detail: running ? 'running; native automation attaches without launching or restarting Arc' : 'not running — start Arc normally',
+            });
+            const allOk = checks.every((check) => check.ok);
+            for (const check of checks) {
+                console.log(`${check.ok ? 'OK  ' : 'FAIL'}  ${check.label.padEnd(15)} ${check.detail}`);
+            }
+            if (!allOk)
+                process.exit(1);
+            return;
+        }
         // 1. Binary exists for declared browser type, and is a real executable we
         //    can drive — not a distro launcher script. findBrowserPath already
         //    unwraps the known Chromium wrappers to their ELF; if it still hands
@@ -1358,8 +1432,41 @@ function registerTaskCommands(browser) {
         }
         if (top === 'stop' && opts.profile && !taskFlag)
             return;
+        // A native Arc endpoint cannot be represented by an SSH-forwarded socket.
+        // For a cold profile-scoped page verb, create the task on the declaring
+        // owner first and bind that owner locally; the ordinary task router below
+        // then forwards this complete verb and every subsequent verb to that host.
+        if (!taskFlag && opts.profile) {
+            try {
+                const profileName = (await resolveProfileRef(opts.profile)) ?? opts.profile;
+                const target = resolveBrowserTarget(profileName);
+                if (!target.local && target.commandDispatch) {
+                    const started = await dispatchBrowserToDevice(target.device, ['browser', 'start', '--profile', profileName, '--json'], 'capture');
+                    if (started.code !== 0) {
+                        process.stdout.write(started.stdout);
+                        process.stderr.write(started.stderr);
+                        process.exit(started.code);
+                    }
+                    const task = remoteStartTaskName(started.stdout);
+                    if (!task)
+                        throw new Error(`Remote start on ${target.device} produced no task name.`);
+                    bindTask(task, {
+                        device: target.device,
+                        profile: profileName,
+                        sessionId: callerSessionId(),
+                        launchId: callerLaunchId(),
+                        createdAt: Date.now(),
+                    });
+                    inferredTaskName = task;
+                }
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            }
+        }
         const route = resolveTaskRoute({
-            task: taskFlag ?? process.env.AGENTS_BROWSER_TASK,
+            task: inferredTaskName ?? taskFlag ?? process.env.AGENTS_BROWSER_TASK,
             sessionId: callerSessionId(),
             launchId: callerLaunchId(),
             hub: defaultBrowserHub(),
@@ -1545,7 +1652,7 @@ function registerTaskCommands(browser) {
                     process.stderr.write(result.stderr);
                     if (result.code !== 0)
                         process.exit(result.code);
-                    const taskName = opts.task || result.stdout.trim().split('\n').find((line) => line.length > 0);
+                    const taskName = remoteStartTaskName(result.stdout, opts.task);
                     if (!taskName) {
                         console.error(`Remote start on ${hub} produced no task name.`);
                         process.exit(1);
@@ -1614,7 +1721,7 @@ function registerTaskCommands(browser) {
                     process.stderr.write(result.stderr);
                     if (result.code !== 0)
                         process.exit(result.code);
-                    const taskName = opts.task || result.stdout.trim().split('\n').find((line) => line.length > 0);
+                    const taskName = remoteStartTaskName(result.stdout, opts.task);
                     if (!taskName) {
                         console.error(`Remote start on ${deviceName} produced no task name.`);
                         process.exit(1);
@@ -1668,6 +1775,44 @@ function registerTaskCommands(browser) {
             console.error(`Create one with: agents browser profiles create ${profileName} --browser <chrome|comet|chromium|brave|edge|arc|custom>`);
             process.exit(1);
         }
+        // Discovery is read-only for list/show/doctor. Starting is the explicit
+        // adoption point: persist only the agents-cli alias/native identity, never
+        // mutate Arc's own profile or Space data.
+        await persistDiscoveredProfile(profileName);
+        // A native endpoint is not CDP and cannot be tunnelled. Re-exec the
+        // complete command on the declaring owner, then bind its returned task
+        // locally so every later verb follows the same owner from task-index.
+        if (!isFleetRemoteInvocation()) {
+            let routed;
+            try {
+                routed = resolveBrowserTarget(profileName, { endpointName: opts.endpoint });
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            }
+            if (!routed.local && routed.commandDispatch) {
+                const result = await dispatchBrowserToDevice(routed.device, browserForwardedArgv(), 'capture');
+                process.stdout.write(result.stdout);
+                process.stderr.write(result.stderr);
+                if (result.code !== 0)
+                    process.exit(result.code);
+                const taskName = remoteStartTaskName(result.stdout, opts.task);
+                if (!taskName) {
+                    console.error(`Remote start on ${routed.device} produced no task name.`);
+                    process.exit(1);
+                }
+                bindTask(taskName, {
+                    device: routed.device,
+                    profile: profileName,
+                    url: opts.url,
+                    sessionId: callerSessionId(),
+                    launchId: callerLaunchId(),
+                    createdAt: Date.now(),
+                });
+                return;
+            }
+        }
         // Pre-check the endpoint name too — same fail-fast rationale.
         if (opts.endpoint) {
             const presets = getEndpointPresets(profile);

package/dist/lib/browser/arc-discovery.d.ts

@@ -0,0 +1,60 @@
+export interface ArcSpace {
+    /** Stable UUID used for every native operation. */
+    id: string;
+    /** Display-only title. */
+    title: string;
+}
+export interface ArcProfile {
+    /** Arc's profile directory basename: the stable profile identity. */
+    profileId: string;
+    /** Display-only profile name from Local State. */
+    displayName: string;
+    spaces: ArcSpace[];
+}
+export type ArcDiscoveryResult = {
+    ok: true;
+    profiles: ArcProfile[];
+    userDataDir: string;
+} | {
+    ok: false;
+    kind: 'unsupported' | 'not-installed' | 'invalid';
+    reason: string;
+};
+interface SidebarSpace {
+    id: string;
+    title: string;
+    profileId: string;
+}
+/**
+ * Arc's application-support root on this Mac. Arc keeps its Chromium `Local
+ * State` under `<root>/User Data/` and its own sidebar model (Spaces and their
+ * profile bindings) at `<root>/StorableSidebar.json` — two different levels,
+ * so discovery is rooted here rather than at the Chromium user-data dir.
+ * `AGENTS_ARC_DIR` points tests and non-default installs at another root.
+ */
+export declare function arcSupportDir(): string | undefined;
+export declare function parseLocalStateProfiles(localStatePath: string): Map<string, string> | {
+    error: string;
+};
+export declare function parseSidebarSpaces(sidebarPath: string): SidebarSpace[] | {
+    error: string;
+};
+export declare function discoverArcProfilesAt(arcDir: string): ArcDiscoveryResult;
+export declare function discoverArcProfiles(): ArcDiscoveryResult;
+/** One Arc Space, flattened with the Arc profile it belongs to. */
+export interface ArcSpaceProfile {
+    /** The agents-cli profile name: `arc-<space-title-slug>`. */
+    name: string;
+    profileId: string;
+    profileName: string;
+    spaceId: string;
+    spaceTitle: string;
+}
+/**
+ * Flatten discovery into one agents-cli profile per Space (the concept agents
+ * already know), named `arc-<space-title>`. Two Spaces with the same title get
+ * the first six characters of their stable Space id appended, so the names
+ * stay distinct without inventing a second selector.
+ */
+export declare function arcSpaceProfiles(result: ArcDiscoveryResult): ArcSpaceProfile[];
+export {};

package/dist/lib/browser/arc-discovery.js

@@ -0,0 +1,187 @@
+/** Read-only Arc profile/Space discovery from Arc's native metadata. */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Arc's application-support root on this Mac. Arc keeps its Chromium `Local
+ * State` under `<root>/User Data/` and its own sidebar model (Spaces and their
+ * profile bindings) at `<root>/StorableSidebar.json` — two different levels,
+ * so discovery is rooted here rather than at the Chromium user-data dir.
+ * `AGENTS_ARC_DIR` points tests and non-default installs at another root.
+ */
+export function arcSupportDir() {
+    const override = process.env.AGENTS_ARC_DIR;
+    if (override)
+        return path.resolve(override);
+    if (process.platform !== 'darwin')
+        return undefined;
+    return path.join(os.homedir(), 'Library', 'Application Support', 'Arc');
+}
+export function parseLocalStateProfiles(localStatePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(localStatePath, 'utf8'));
+    }
+    catch (error) {
+        return {
+            error: error instanceof SyntaxError
+                ? 'Arc Local State is not valid JSON'
+                : `Cannot read Arc Local State: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.profile) || !isRecord(parsed.profile.info_cache)) {
+        return { error: 'Arc Local State has no profile.info_cache map' };
+    }
+    const profiles = new Map();
+    for (const [profileId, value] of Object.entries(parsed.profile.info_cache)) {
+        if (profileId === '__ARC_SYSTEM_PROFILE')
+            continue;
+        if (!isRecord(value) || typeof value.name !== 'string' || value.name.trim() === '') {
+            return { error: `Arc Local State profile ${JSON.stringify(profileId)} has no non-empty name` };
+        }
+        profiles.set(profileId, value.name);
+    }
+    return profiles;
+}
+function parseProfileId(value, spaceId) {
+    if (!isRecord(value)) {
+        return { error: `Arc Space ${JSON.stringify(spaceId)} has no profile mapping` };
+    }
+    if (value.default === true && value.custom === undefined)
+        return 'Default';
+    if (!isRecord(value.custom)) {
+        return { error: `Arc Space ${JSON.stringify(spaceId)} has an unknown profile mapping` };
+    }
+    const entries = Object.values(value.custom);
+    if (entries.length !== 1 || !isRecord(entries[0])) {
+        return { error: `Arc Space ${JSON.stringify(spaceId)} has an ambiguous custom profile mapping` };
+    }
+    const profileId = entries[0].directoryBasename;
+    if (typeof profileId !== 'string' || profileId.trim() === '') {
+        return { error: `Arc Space ${JSON.stringify(spaceId)} has no custom profile id` };
+    }
+    return profileId;
+}
+export function parseSidebarSpaces(sidebarPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(sidebarPath, 'utf8'));
+    }
+    catch (error) {
+        return {
+            error: error instanceof SyntaxError
+                ? 'Arc StorableSidebar.json is not valid JSON'
+                : `Cannot read Arc StorableSidebar.json: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!isRecord(parsed) || parsed.version !== 1) {
+        const version = isRecord(parsed) ? parsed.version : undefined;
+        return { error: `Unsupported StorableSidebar version: ${String(version)}` };
+    }
+    if (!isRecord(parsed.sidebar) || !Array.isArray(parsed.sidebar.containers)) {
+        return { error: 'StorableSidebar.json has no sidebar.containers array' };
+    }
+    const spaces = [];
+    const ids = new Set();
+    for (const container of parsed.sidebar.containers) {
+        if (!isRecord(container) || container.spaces === undefined)
+            continue;
+        if (!Array.isArray(container.spaces) || container.spaces.length % 2 !== 0) {
+            return { error: 'StorableSidebar.json contains a malformed alternating spaces array' };
+        }
+        for (let i = 0; i < container.spaces.length; i += 2) {
+            const encodedId = container.spaces[i];
+            const value = container.spaces[i + 1];
+            if (typeof encodedId !== 'string' || !isRecord(value)) {
+                return { error: `StorableSidebar.json contains a malformed Space at index ${i}` };
+            }
+            if (typeof value.id !== 'string' || value.id !== encodedId) {
+                return { error: `Arc Space key ${JSON.stringify(encodedId)} does not match its stable id` };
+            }
+            if (typeof value.title !== 'string') {
+                return { error: `Arc Space ${JSON.stringify(encodedId)} has no title` };
+            }
+            if (ids.has(encodedId)) {
+                return { error: `Arc Space ${JSON.stringify(encodedId)} appears more than once` };
+            }
+            const profileId = parseProfileId(value.profile, encodedId);
+            if (typeof profileId !== 'string')
+                return profileId;
+            ids.add(encodedId);
+            spaces.push({ id: encodedId, title: value.title, profileId });
+        }
+    }
+    return spaces;
+}
+export function discoverArcProfilesAt(arcDir) {
+    const userDataDir = path.join(arcDir, 'User Data');
+    if (!fs.existsSync(userDataDir)) {
+        return { ok: false, kind: 'not-installed', reason: `Arc user data directory not found: ${userDataDir}` };
+    }
+    const profileNames = parseLocalStateProfiles(path.join(userDataDir, 'Local State'));
+    if ('error' in profileNames)
+        return { ok: false, kind: 'invalid', reason: profileNames.error };
+    if (profileNames.size === 0) {
+        return { ok: false, kind: 'invalid', reason: 'No Arc profiles found in Local State' };
+    }
+    const spaces = parseSidebarSpaces(path.join(arcDir, 'StorableSidebar.json'));
+    if ('error' in spaces)
+        return { ok: false, kind: 'invalid', reason: spaces.error };
+    const profiles = new Map();
+    for (const [profileId, displayName] of profileNames) {
+        profiles.set(profileId, { profileId, displayName, spaces: [] });
+    }
+    for (const space of spaces) {
+        const profile = profiles.get(space.profileId);
+        if (!profile) {
+            return {
+                ok: false,
+                kind: 'invalid',
+                reason: `Arc Space ${JSON.stringify(space.id)} maps to unknown profile ${JSON.stringify(space.profileId)}`,
+            };
+        }
+        profile.spaces.push({ id: space.id, title: space.title });
+    }
+    return { ok: true, profiles: [...profiles.values()], userDataDir };
+}
+export function discoverArcProfiles() {
+    const arcDir = arcSupportDir();
+    if (!arcDir) {
+        return { ok: false, kind: 'unsupported', reason: 'Arc is not supported on this platform' };
+    }
+    return discoverArcProfilesAt(arcDir);
+}
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/**
+ * Flatten discovery into one agents-cli profile per Space (the concept agents
+ * already know), named `arc-<space-title>`. Two Spaces with the same title get
+ * the first six characters of their stable Space id appended, so the names
+ * stay distinct without inventing a second selector.
+ */
+export function arcSpaceProfiles(result) {
+    if (!result.ok)
+        return [];
+    const flat = [];
+    for (const profile of result.profiles) {
+        for (const space of profile.spaces) {
+            flat.push({
+                name: `arc-${slugify(space.title) || 'space'}`,
+                profileId: profile.profileId,
+                profileName: profile.displayName,
+                spaceId: space.id,
+                spaceTitle: space.title,
+            });
+        }
+    }
+    const counts = new Map();
+    for (const entry of flat)
+        counts.set(entry.name, (counts.get(entry.name) ?? 0) + 1);
+    return flat.map((entry) => (counts.get(entry.name) ?? 0) > 1
+        ? { ...entry, name: `${entry.name}-${slugify(entry.spaceId).slice(0, 6)}` }
+        : entry);
+}

package/dist/lib/browser/arc-dom.d.ts

@@ -0,0 +1,14 @@
+import type { RefNode, RefOpts } from './refs.js';
+/** Build one synchronous expression that reads DOM-backed refs from native Arc. */
+export declare function arcRefsExpression(opts?: RefOpts): string;
+export declare function parseArcRefsResult(value: unknown, opts?: RefOpts): {
+    refs: string;
+    nodeMap: Map<number, RefNode>;
+    opts: {
+        interactive: boolean;
+        limit: number;
+    };
+};
+export declare function arcClickExpression(selector: string): string;
+export declare function arcFillExpression(selector: string, text: string, clear?: boolean): string;
+export declare function arcScrollExpression(deltaX: number, deltaY: number): string;