@phnx-labs/agents-cli 1.22.93 → 1.22.95

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

@@ -0,0 +1,121 @@
+import { truncate } from '../format.js';
+const INTERACTIVE_SELECTOR = [
+    'a[href]', 'button', 'input', 'select', 'textarea', '[contenteditable="true"]',
+    '[role="button"]', '[role="link"]', '[role="textbox"]', '[role="checkbox"]',
+    '[role="radio"]', '[role="combobox"]', '[role="listbox"]', '[role="option"]',
+    '[role="menuitem"]', '[role="tab"]', '[role="slider"]', '[role="spinbutton"]',
+    '[role="searchbox"]', '[role="switch"]', '[role="treeitem"]',
+].join(',');
+/** Build one synchronous expression that reads DOM-backed refs from native Arc. */
+export function arcRefsExpression(opts = {}) {
+    const interactive = opts.interactive ?? true;
+    const limit = opts.limit ?? 500;
+    return `(() => {
+    const selectorFor = (el) => {
+      if (el.id) return '#' + CSS.escape(el.id);
+      const parts = [];
+      for (let node = el; node && node.nodeType === 1 && node !== document.documentElement; node = node.parentElement) {
+        let part = node.localName;
+        if (!part) return '';
+        const siblings = node.parentElement ? Array.from(node.parentElement.children).filter((s) => s.localName === node.localName) : [];
+        if (siblings.length > 1) part += ':nth-of-type(' + (siblings.indexOf(node) + 1) + ')';
+        parts.unshift(part);
+      }
+      return parts.join(' > ');
+    };
+    const roleFor = (el) => {
+      const explicit = el.getAttribute('role');
+      if (explicit) return explicit.toLowerCase();
+      if (el.matches('button')) return 'button';
+      if (el.matches('a[href]')) return 'link';
+      if (el.matches('textarea,[contenteditable="true"]')) return 'textbox';
+      if (el.matches('select')) return 'combobox';
+      if (el.matches('input')) {
+        const type = (el.getAttribute('type') || 'text').toLowerCase();
+        if (type === 'checkbox') return 'checkbox';
+        if (type === 'radio') return 'radio';
+        if (type === 'range') return 'slider';
+        if (type === 'number') return 'spinbutton';
+        return 'textbox';
+      }
+      return el.localName || 'generic';
+    };
+    const nameFor = (el) => el.getAttribute('aria-label') || el.getAttribute('title') ||
+      (el.labels && el.labels[0] && el.labels[0].innerText) || el.innerText || el.value || el.getAttribute('placeholder') || '';
+    const attrsFor = (el) => ['disabled','checked','selected','expanded','required','readonly','invalid']
+      .filter((name) => el[name] === true || el.getAttribute('aria-' + name) === 'true');
+    const editorFor = (el) => {
+      for (let node = el, i = 0; node && i < 6; node = node.parentElement, i++) {
+        if (node.hasAttribute('data-lexical-editor')) return 'lexical';
+        if (node.classList.contains('ProseMirror')) return 'prosemirror';
+        if (node.hasAttribute('data-slate-editor')) return 'slate';
+        if (Array.from(node.classList).some((c) => /^DraftEditor-/.test(c))) return 'draft';
+        if (node.classList.contains('ql-editor')) return 'quill';
+        if (node.classList.contains('ck-editor__editable')) return 'ckeditor5';
+        if (node.tagName === 'TRIX-EDITOR') return 'trix';
+      }
+      return undefined;
+    };
+    const source = ${interactive ? `document.querySelectorAll(${JSON.stringify(INTERACTIVE_SELECTOR)})` : `document.querySelectorAll('body *')`};
+    const rows = [];
+    for (const el of source) {
+      if (rows.length >= ${JSON.stringify(limit)}) break;
+      const selector = selectorFor(el);
+      if (!selector) continue;
+      const row = { role: roleFor(el), name: String(nameFor(el)).trim(), attrs: attrsFor(el), selector };
+      const editor = editorFor(el);
+      if (editor) row.editor = editor;
+      rows.push(row);
+    }
+    return JSON.stringify(rows);
+  })()`;
+}
+export function parseArcRefsResult(value, opts = {}) {
+    const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+    if (!Array.isArray(parsed))
+        throw new Error('Arc returned an invalid DOM ref listing.');
+    const nodeMap = new Map();
+    const lines = [];
+    const compact = opts.compact ?? false;
+    parsed.forEach((raw, index) => {
+        const row = raw;
+        if (typeof row.role !== 'string' || typeof row.name !== 'string' ||
+            typeof row.selector !== 'string' || !Array.isArray(row.attrs) ||
+            !row.attrs.every((attr) => typeof attr === 'string')) {
+            throw new Error('Arc returned an invalid DOM ref entry.');
+        }
+        const ref = index + 1;
+        const node = { ref, role: row.role, name: row.name, attrs: row.attrs, selector: row.selector };
+        if (typeof row.editor === 'string')
+            node.editor = row.editor;
+        nodeMap.set(ref, node);
+        const name = row.name ? ` "${truncate(row.name, 50)}"` : '';
+        const attrs = row.attrs.length ? ` [${row.attrs.join('] [')}]` : '';
+        const editor = row.editor ? ` [editor=${row.editor}]` : '';
+        lines.push(`${compact ? '' : '- '}${row.role}${name} [ref=${ref}]${attrs}${editor}`);
+    });
+    return { refs: lines.join('\n'), nodeMap, opts: { interactive: opts.interactive ?? true, limit: opts.limit ?? 500 } };
+}
+export function arcClickExpression(selector) {
+    return `(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (!el) throw new Error('DOM ref is missing'); el.click(); return true; })()`;
+}
+export function arcFillExpression(selector, text, clear = true) {
+    return `(() => {
+    const el = document.querySelector(${JSON.stringify(selector)});
+    if (!el) throw new Error('DOM ref is missing');
+    const next = ${JSON.stringify(text)};
+    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+      const proto = el instanceof HTMLInputElement ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype;
+      const setter = Object.getOwnPropertyDescriptor(proto, 'value').set;
+      setter.call(el, ${clear ? 'next' : 'el.value + next'});
+    } else if (el.isContentEditable) {
+      el.textContent = ${clear ? 'next' : '(el.textContent || "") + next'};
+    } else throw new Error('DOM ref is not editable');
+    el.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'insertText', data: next }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    return true;
+  })()`;
+}
+export function arcScrollExpression(deltaX, deltaY) {
+    return `(() => { window.scrollBy(${JSON.stringify(deltaX)}, ${JSON.stringify(deltaY)}); return true; })()`;
+}

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

@@ -38,6 +38,23 @@ export interface LaunchResult {
     port: number;
     wsUrl: string;
 }
+/**
+ * The process that holds a Chromium user-data dir, read from the `SingletonLock`
+ * symlink Chromium keeps inside the dir on macOS and Linux (`<host>-<pid>`,
+ * PHNX-4042). A live pid means a browser already owns that store: a launch on it
+ * would only hand its arguments to the running instance and the requested debug
+ * port would never bind. Windows keeps no lock file, so this reports null there
+ * and `launchBrowser` catches the hand-off by the child's early exit instead.
+ */
+export declare function storeOccupant(userDataDir: string): {
+    pid: number;
+} | null;
+/**
+ * The relaunch that makes a browser holding `userDataDir` attachable: the
+ * ownership guard reads `--user-data-dir` off the running process, so the
+ * owner's normal launch (no flag) can never be verified.
+ */
+export declare function storeRelaunchCommand(browserType: BrowserType, port: number, userDataDir: string, profileDirectory?: string): string;
 /**
  * Resolve a browser-profile secrets bundle into an env map for the child, or an
  * EMPTY map when the bundle is absent, locked, or otherwise unreadable — never a

package/dist/lib/browser/chrome.js

@@ -24,6 +24,10 @@ const BROWSER_PATHS = {
         brave: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
         edge: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
         arc: ['/Applications/Arc.app/Contents/MacOS/Arc'],
+        firefox: [
+            '/Applications/Firefox.app/Contents/MacOS/firefox',
+            '/Applications/Firefox Developer Edition.app/Contents/MacOS/firefox',
+        ],
         custom: [],
     },
     linux: {
@@ -34,6 +38,10 @@ const BROWSER_PATHS = {
         edge: ['/usr/bin/microsoft-edge'],
         // Arc has no Linux build (macOS + Windows only).
         arc: [],
+        // `/usr/bin/firefox` on Ubuntu is the snap wrapper script: it execs the snap
+        // in place, so the pid survives and `--remote-debugging-port` works through
+        // it. The driver reads the real pid from the BiDi handshake anyway.
+        firefox: ['/usr/bin/firefox', '/snap/bin/firefox', '/usr/lib/firefox/firefox', '/opt/firefox/firefox'],
         custom: [],
     },
     win32: {
@@ -63,6 +71,11 @@ const BROWSER_PATHS = {
         // Arc ships a Windows build, but its install path is not yet verified here;
         // leave unlisted (undetected) rather than guess a path that false-positives.
         arc: [],
+        firefox: [
+            `${WIN_PROGRAMFILES}\\Mozilla Firefox\\firefox.exe`,
+            `${WIN_PROGRAMFILES_X86}\\Mozilla Firefox\\firefox.exe`,
+            `${WIN_LOCALAPPDATA}\\Mozilla Firefox\\firefox.exe`,
+        ],
         custom: [],
     },
 };
@@ -236,6 +249,43 @@ export function listInstalledBrowsers(platform = os.platform()) {
     }
     return found;
 }
+/**
+ * The process that holds a Chromium user-data dir, read from the `SingletonLock`
+ * symlink Chromium keeps inside the dir on macOS and Linux (`<host>-<pid>`,
+ * PHNX-4042). A live pid means a browser already owns that store: a launch on it
+ * would only hand its arguments to the running instance and the requested debug
+ * port would never bind. Windows keeps no lock file, so this reports null there
+ * and `launchBrowser` catches the hand-off by the child's early exit instead.
+ */
+export function storeOccupant(userDataDir) {
+    let target;
+    try {
+        target = fs.readlinkSync(path.join(userDataDir, 'SingletonLock'));
+    }
+    catch {
+        return null;
+    }
+    const pid = Number(/-(\d+)$/.exec(target)?.[1]);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        return error.code === 'EPERM' ? { pid } : null;
+    }
+    return { pid };
+}
+/**
+ * The relaunch that makes a browser holding `userDataDir` attachable: the
+ * ownership guard reads `--user-data-dir` off the running process, so the
+ * owner's normal launch (no flag) can never be verified.
+ */
+export function storeRelaunchCommand(browserType, port, userDataDir, profileDirectory) {
+    const app = browserType === 'comet' ? 'Comet' : browserType;
+    const profileFlag = profileDirectory ? ` --profile-directory=${profileDirectory}` : '';
+    return `open -a ${app} --args --remote-debugging-port=${port} --user-data-dir=${userDataDir}${profileFlag}`;
+}
 /**
  * Resolve a browser-profile secrets bundle into an env map for the child, or an
  * EMPTY map when the bundle is absent, locked, or otherwise unreadable — never a
@@ -265,14 +315,25 @@ export async function launchBrowser(profileName, browserType, port, options = {}
 // orphan reaper and `agents browser status` can label processes.
 isElectron = false) {
     const browserPath = findBrowserPath(browserType, customBinary);
+    // A profile discovered from the browser's OWN store (PHNX-4042) launches on
+    // that store — the owner's real user-data dir and profile directory — so the
+    // window agents open is the window the owner uses. Its Preferences are the
+    // owner's and are never rewritten. Anything else runs under a managed dir.
+    const ownerStore = options.userDataDir !== undefined;
     const runtimeDir = getProfileRuntimeDir(profileName);
-    const userDataDir = path.join(runtimeDir, 'chrome-data');
-    fs.mkdirSync(userDataDir, { recursive: true });
-    // Pre-launch Preferences pass: first-launch profile-name stamp, plus (for
-    // real browsers, not Electron apps) the session-cookie persistence pin.
-    // Electron apps manage their own storage and don't read Chromium's
-    // `session.*` prefs, so they get the name stamp only.
-    ensureProfilePreferences(userDataDir, profileName, !isElectron);
+    const userDataDir = options.userDataDir ?? path.join(runtimeDir, 'chrome-data');
+    if (!ownerStore) {
+        fs.mkdirSync(userDataDir, { recursive: true });
+        // Pre-launch Preferences pass: first-launch profile-name stamp, plus (for
+        // real browsers, not Electron apps) the session-cookie persistence pin.
+        // Electron apps manage their own storage and don't read Chromium's
+        // `session.*` prefs, so they get the name stamp only.
+        ensureProfilePreferences(userDataDir, profileName, !isElectron);
+    }
+    // The owner's store is attached over a TCP port rather than the daemon's
+    // private pipe: the instance outlives any one daemon and must stay reachable
+    // (and verifiable by the ownership guard) after a daemon restart.
+    const transport = ownerStore ? 'port' : 'pipe';
     // Chromium on macOS coordinates instances via the SingletonLock file
     // *inside* each user-data-dir. Direct binary spawn with a fresh
     // --user-data-dir creates a fully independent process — the user's
@@ -288,8 +349,9 @@ isElectron = false) {
     // profile never reaches this launcher (see connectLocal / isAttachOnlyProfile).
     const viewport = options.viewport ?? { width: 1512, height: 982 };
     const args = [
-        '--remote-debugging-pipe',
+        transport === 'pipe' ? '--remote-debugging-pipe' : `--remote-debugging-port=${port}`,
         `--user-data-dir=${userDataDir}`,
+        ...(options.profileDirectory ? [`--profile-directory=${options.profileDirectory}`] : []),
         '--disable-background-timer-throttling',
         '--disable-backgrounding-occluded-windows',
         '--disable-renderer-backgrounding',
@@ -311,7 +373,7 @@ isElectron = false) {
         // cookies survive, no ghost tabs — and the task flow creates its own tab
         // over CDP anyway. Electron apps need their window to appear (the CDP
         // driver binds to it), so they skip the flag.
-        ...(isElectron ? [] : ['--no-startup-window']),
+        ...(isElectron || ownerStore ? [] : ['--no-startup-window']),
         ...(options.headless ? ['--headless=new'] : []),
         `--window-size=${viewport.width},${viewport.height}`,
         ...(viewport.x !== undefined && viewport.y !== undefined
@@ -324,26 +386,69 @@ isElectron = false) {
     const env = { ...process.env, ...(await resolveProfileSecretsEnv(secrets)) };
     const child = spawn(browserPath, args, {
         detached: true,
-        stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
+        stdio: transport === 'pipe' ? ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
         env,
     });
     child.unref();
     child.stdout?.resume();
     child.stderr?.resume();
     const pid = child.pid;
-    const writePipe = child.stdio[3];
-    const readPipe = child.stdio[4];
-    if (!writePipe || !readPipe) {
-        throw new Error('Chrome failed to expose CDP pipe file descriptors');
+    let wsUrl;
+    if (transport === 'pipe') {
+        const writePipe = child.stdio[3];
+        const readPipe = child.stdio[4];
+        if (!writePipe || !readPipe) {
+            throw new Error('Chrome failed to expose CDP pipe file descriptors');
+        }
+        wsUrl = registerPipeTransport({ read: readPipe, write: writePipe });
+    }
+    else {
+        wsUrl = (await waitForDevToolsPort(port, profileName, child, { browserType, userDataDir, profileDirectory: options.profileDirectory })).wsUrl;
     }
-    const wsUrl = registerPipeTransport({ read: readPipe, write: writePipe });
     writeProfileRuntime(profileName, {
         pid,
         command: path.basename(browserPath),
         userDataDir,
         kind: isElectron ? 'electron' : 'browser',
     });
-    return { pid, port: 0, wsUrl };
+    return { pid, port: transport === 'pipe' ? 0 : port, wsUrl };
+}
+/**
+ * Poll the DevTools endpoint of a browser just launched with
+ * `--remote-debugging-port` until it answers, or fail loud naming the pid.
+ * Chromium binds the port only after its profile has loaded, which on a real
+ * signed-in store takes a few seconds. A child that exits first never bound
+ * it: on an owner's store that is the singleton hand-off to a browser already
+ * open there (PHNX-4042), so the failure names that instance's relaunch
+ * instead of waiting out the deadline.
+ */
+async function waitForDevToolsPort(port, profileName, child, store, timeoutMs = 20_000) {
+    const pid = child.pid;
+    let exited;
+    child.once('exit', (code, signal) => {
+        exited = code !== null ? `code ${code}` : `signal ${signal}`;
+    });
+    const deadline = Date.now() + timeoutMs;
+    let lastError = '';
+    while (Date.now() < deadline) {
+        if (exited) {
+            const app = store.browserType === 'comet' ? 'Comet' : store.browserType;
+            throw new Error(`${app} (pid ${pid}) exited (${exited}) before serving the DevTools protocol on port ${port} ` +
+                `for profile "${profileName}". A ${app} already open on ${store.userDataDir} takes a new launch ` +
+                `as an argument hand-off and never binds the port; quit it, then relaunch it with remote debugging:\n` +
+                `  ${storeRelaunchCommand(store.browserType, port, store.userDataDir, store.profileDirectory)}\n` +
+                `and retry. If none is open, the browser crashed on start.`);
+        }
+        try {
+            return await discoverBrowserWsUrl(port, 'localhost', profileName);
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    throw new Error(`Browser for profile "${profileName}" (pid ${pid}) did not serve the DevTools protocol on ` +
+        `port ${port} within ${Math.round(timeoutMs / 1000)}s: ${lastError}`);
 }
 export async function attachToChrome(port) {
     const { wsUrl } = await discoverBrowserWsUrl(port);

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

@@ -0,0 +1,27 @@
+import type { BrowserType } from './types.js';
+export interface ChromiumNativeProfile {
+    browser: BrowserType;
+    /** The agents-cli profile name: `<browser>-<display-name-slug>`. */
+    name: string;
+    /** The browser's user-data dir (its own, never a cache dir). */
+    userDataDir: string;
+    /** Profile directory basename inside the user-data dir. Authoritative id. */
+    profileDirectory: string;
+    /** Display-only name from Local State. */
+    displayName: string;
+}
+export type ChromiumDiscoveryResult = {
+    ok: true;
+    profiles: ChromiumNativeProfile[];
+    userDataDir: string;
+} | {
+    ok: false;
+    kind: 'unsupported' | 'not-installed' | 'invalid';
+    reason: string;
+};
+/** The browser's own user-data dir on this platform, or undefined where it does not ship. */
+export declare function chromiumUserDataDir(browser: BrowserType): string | undefined;
+export declare function discoverChromiumProfilesAt(browser: BrowserType, userDataDir: string): ChromiumDiscoveryResult;
+export declare function discoverChromiumProfiles(browser: BrowserType): ChromiumDiscoveryResult;
+/** Every browser whose native profiles agents-cli discovers on this platform. */
+export declare function discoverableChromiumBrowsers(): BrowserType[];

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

@@ -0,0 +1,96 @@
+/**
+ * Read-only discovery of a Chromium-family browser's OWN profiles (PHNX-4042).
+ *
+ * Chromium keeps its profiles under one user-data dir: `Local State` lists them
+ * in `profile.info_cache` keyed by directory (`Default`, `Profile 1`, ...) with
+ * the display name the user sees in the profile menu. Each entry becomes one
+ * agents-cli profile (`comet-work`, ...) pinned to that dir and directory, so
+ * the owner and agents share ONE window per profile instead of agents spawning
+ * a rival instance under a cache dir. Nothing here writes to the browser's
+ * files.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Browsers whose native profiles are discovered, and the env var that points tests at another user-data dir. */
+const NATIVE_CHROMIUM = {
+    comet: { dirName: 'Comet', envOverride: 'AGENTS_COMET_DIR' },
+};
+/** The browser's own user-data dir on this platform, or undefined where it does not ship. */
+export function chromiumUserDataDir(browser) {
+    const entry = NATIVE_CHROMIUM[browser];
+    if (!entry)
+        return undefined;
+    const override = process.env[entry.envOverride];
+    if (override)
+        return path.resolve(override);
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', entry.dirName);
+    }
+    if (process.platform === 'win32') {
+        const local = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+        return path.join(local, entry.dirName, 'User Data');
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+export function discoverChromiumProfilesAt(browser, userDataDir) {
+    const localState = path.join(userDataDir, 'Local State');
+    if (!fs.existsSync(localState)) {
+        return { ok: false, kind: 'not-installed', reason: `${browser} Local State not found: ${localState}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(localState, 'utf8'));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: error instanceof SyntaxError
+                ? `${browser} Local State is not valid JSON`
+                : `Cannot read ${browser} Local State: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.profile) || !isRecord(parsed.profile.info_cache)) {
+        return { ok: false, kind: 'invalid', reason: `${browser} Local State has no profile.info_cache map` };
+    }
+    const rows = [];
+    for (const [profileDirectory, value] of Object.entries(parsed.profile.info_cache)) {
+        if (!isRecord(value) || typeof value.name !== 'string' || value.name.trim() === '') {
+            return { ok: false, kind: 'invalid', reason: `${browser} Local State profile ${JSON.stringify(profileDirectory)} has no non-empty name` };
+        }
+        rows.push({
+            browser,
+            name: `${browser}-${slugify(value.name) || 'profile'}`,
+            userDataDir,
+            profileDirectory,
+            displayName: value.name,
+        });
+    }
+    // Two profiles with the same display name stay distinct by their directory.
+    const counts = new Map();
+    for (const row of rows)
+        counts.set(row.name, (counts.get(row.name) ?? 0) + 1);
+    return {
+        ok: true,
+        userDataDir,
+        profiles: rows.map((row) => (counts.get(row.name) ?? 0) > 1 ? { ...row, name: `${row.name}-${slugify(row.profileDirectory)}` } : row),
+    };
+}
+export function discoverChromiumProfiles(browser) {
+    const userDataDir = chromiumUserDataDir(browser);
+    if (!userDataDir) {
+        return { ok: false, kind: 'unsupported', reason: `${browser} profiles are not discovered on this platform` };
+    }
+    return discoverChromiumProfilesAt(browser, userDataDir);
+}
+/** Every browser whose native profiles agents-cli discovers on this platform. */
+export function discoverableChromiumBrowsers() {
+    return Object.keys(NATIVE_CHROMIUM).filter((browser) => chromiumUserDataDir(browser) !== undefined);
+}

package/dist/lib/browser/drivers/arc.d.ts

@@ -0,0 +1,57 @@
+export interface ArcNativeTabRef {
+    windowId: string;
+    spaceId: string;
+    tabId: string;
+}
+export interface ArcNativeTab extends ArcNativeTabRef {
+    url: string;
+    title: string;
+}
+export interface ArcEnumeratedSpace {
+    windowId: string;
+    spaceId: string;
+    spaceTitle: string;
+    activeTabId?: string;
+    tabs: ArcNativeTab[];
+}
+export declare const ARC_NATIVE_CAPABILITIES: Readonly<{
+    readonly createTab: true;
+    readonly navigate: true;
+    readonly evaluateSync: true;
+    readonly closeTab: true;
+    readonly enumerate: true;
+    readonly screenshot: false;
+    readonly asyncEvaluate: false;
+    readonly networkCapture: false;
+    readonly consoleCapture: false;
+    readonly upload: false;
+    readonly pdf: false;
+    readonly background: false;
+}>;
+export declare class ArcNativeCapabilityError extends Error {
+    readonly capability: string;
+    constructor(capability: string, message?: string);
+}
+/** AppleScript strings do not implement JSON's \uXXXX escape syntax. */
+export declare function escapeAppleScriptString(value: string): string;
+/** No shell, bounded output and lifetime, and no blocking of the shared daemon. */
+export declare function execAppleScript(source: string, timeoutMs?: number): Promise<string>;
+export declare function isArcRunning(): Promise<boolean>;
+export declare function enumerateArcSpaces(): Promise<ArcEnumeratedSpace[]>;
+/** Caller durably records marker intent before calling; never use a real page URL as ownership. */
+export declare function createArcTab(target: Pick<ArcNativeTabRef, 'windowId' | 'spaceId'>, markerUrl: string): Promise<ArcNativeTab>;
+export declare function resolveArcTab(ref: ArcNativeTabRef): Promise<ArcNativeTab | null>;
+export declare function navigateArcTab(ref: ArcNativeTabRef, url: string): Promise<void>;
+/** Arc serializes a returned object once. JSON.stringify at the top level would double-encode. */
+export declare function executeJavaScript(ref: ArcNativeTabRef, expression: string): Promise<unknown>;
+export declare function closeArcTab(ref: ArcNativeTabRef): Promise<'closed' | 'missing'>;
+/** Explicit user-facing focus only. Evaluation and cleanup never invoke this. */
+export declare function selectArcTab(ref: ArcNativeTabRef): Promise<void>;
+/**
+ * Select `tabId` wherever it lives in window `windowId` (any Space). Used to put
+ * the owner back on their tab after a creation that failed mid-way, when there is
+ * no owned tab to check against. Returns false when the tab is gone.
+ */
+export declare function selectWindowTab(windowId: string, tabId: string): Promise<boolean>;
+/** Restore only while the task's new tab is still selected; preserve a later human choice. */
+export declare function restoreArcSelection(owned: ArcNativeTabRef, previousTabId: string): Promise<boolean>;