@phnx-labs/agents-cli 1.22.93 → 1.22.94

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/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>;

package/dist/lib/browser/drivers/arc.js

@@ -0,0 +1,281 @@
+/** Native Apple Events transport. Never uses CDP or launches an Arc process. */
+import { spawn } from 'node:child_process';
+export const ARC_NATIVE_CAPABILITIES = Object.freeze({
+    createTab: true, navigate: true, evaluateSync: true, closeTab: true, enumerate: true,
+    screenshot: false, asyncEvaluate: false, networkCapture: false, consoleCapture: false,
+    upload: false, pdf: false, background: false,
+});
+export class ArcNativeCapabilityError extends Error {
+    capability;
+    constructor(capability, message) {
+        super(message ?? `Native Arc does not support ${capability}. Use a configured browser with that capability.`);
+        this.capability = capability;
+        this.name = 'ArcNativeCapabilityError';
+    }
+}
+const TIMEOUT_MS = 15_000;
+const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const APP_ID = 'company.thebrowser.Browser';
+let operationQueue = Promise.resolve();
+/** Serialize native operations in this service, including failures. */
+function serialized(operation) {
+    const result = operationQueue.then(operation, operation);
+    operationQueue = result.catch(() => undefined);
+    return result;
+}
+/** AppleScript strings do not implement JSON's \uXXXX escape syntax. */
+export function escapeAppleScriptString(value) {
+    const parts = value.split(/([\u0000-\u001f])/u).filter(Boolean);
+    if (parts.length === 0)
+        return '""';
+    return '(' + parts.map(part => part.length === 1 && part.charCodeAt(0) < 32
+        ? `(character id ${part.charCodeAt(0)})`
+        : `"${part.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).join(' & ') + ')';
+}
+/** No shell, bounded output and lifetime, and no blocking of the shared daemon. */
+export function execAppleScript(source, timeoutMs = TIMEOUT_MS) {
+    if (process.platform !== 'darwin')
+        return Promise.reject(new Error('Native Arc requires macOS.'));
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return Promise.reject(new Error('Invalid Apple Events timeout.'));
+    return new Promise((resolve, reject) => {
+        const child = spawn('/usr/bin/osascript', [], { stdio: ['pipe', 'pipe', 'pipe'] });
+        const chunks = [];
+        const errors = [];
+        let bytes = 0;
+        let failure;
+        const abort = (error) => {
+            failure ??= error;
+            child.kill('SIGKILL');
+        };
+        const timer = setTimeout(() => abort(new Error(`Arc Apple Event timed out after ${timeoutMs}ms.`)), timeoutMs);
+        for (const [stream, target] of [[child.stdout, chunks], [child.stderr, errors]]) {
+            stream.on('data', (chunk) => {
+                bytes += chunk.length;
+                if (bytes > MAX_OUTPUT_BYTES)
+                    abort(new Error('Arc Apple Event output exceeded the safety limit.'));
+                else
+                    target.push(chunk);
+            });
+        }
+        child.stdin.on('error', error => abort(error));
+        child.once('error', error => { clearTimeout(timer); reject(error); });
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(`Arc Apple Event failed (${signal ?? code}): ${Buffer.concat(errors).toString('utf8').trim()}`));
+                return;
+            }
+            resolve(Buffer.concat(chunks).toString('utf8').trim());
+        });
+        child.stdin.end(source);
+    });
+}
+// Foundation serializes arbitrary titles/URLs, including tabs, newlines and Unicode.
+// Delimiter splitting is not a safe wire format for browser-controlled strings.
+const PRELUDE = `use framework "Foundation"
+use scripting additions
+on jsonString(rawValue)
+  if rawValue is missing value then set rawValue to ""
+  set wrapped to {current application's NSString's stringWithString:(rawValue as text)}
+  set jsonData to current application's NSJSONSerialization's dataWithJSONObject:wrapped options:0 |error|:(missing value)
+  set jsonText to (current application's NSString's alloc()'s initWithData:jsonData encoding:(current application's NSUTF8StringEncoding)) as text
+  return text 2 thru -2 of jsonText
+end jsonString
+`;
+function script(body) {
+    return `${PRELUDE}\nif application id "${APP_ID}" is not running then error "Arc is not running. Open it before starting a native task."
+tell application id "${APP_ID}"
+${body}
+end tell`;
+}
+function identity(value, kind) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 256)
+        throw new Error(`Missing or invalid native ${kind} ID.`);
+    return escapeAppleScriptString(value);
+}
+/**
+ * Resolve all ordinals afresh INSIDE the operation; never persist an index.
+ *
+ * Every `X of every Y` below is ONE Apple Event returning a list. The naive
+ * form (`id of tab ti of targetSpace` inside a repeat) costs one round trip per
+ * tab — on a 30-tab Space that alone took the create path past the 15 s budget
+ * from inside the shared daemon, whose loop also serves everything else.
+ */
+function lookup(ref, missing = 'error "Native Arc target is no longer in its original window and Space."') {
+    return `set targetWindowIndex to 0
+set windowIds to id of every window
+set windowVisible to visible of every window
+repeat with wi from 1 to count of windowIds
+  if (item wi of windowIds as text) is ${identity(ref.windowId, 'window')} and (item wi of windowVisible) then set targetWindowIndex to wi as integer
+end repeat
+if targetWindowIndex is 0 then
+  ${missing}
+end if
+set targetSpaceIndex to 0
+set spaceIds to id of every space of window targetWindowIndex
+repeat with si from 1 to count of spaceIds
+  if (item si of spaceIds as text) is ${identity(ref.spaceId, 'Space')} then set targetSpaceIndex to si as integer
+end repeat
+if targetSpaceIndex is 0 then
+  ${missing}
+end if
+set targetSpace to a reference to space targetSpaceIndex of window targetWindowIndex
+${ref.tabId === undefined ? '' : `set targetTabIndex to 0
+set tabIds to id of every tab of targetSpace
+repeat with ti from 1 to count of tabIds
+  if (item ti of tabIds as text) is ${identity(ref.tabId, 'tab')} then set targetTabIndex to ti as integer
+end repeat
+if targetTabIndex is 0 then
+  ${missing}
+end if
+set targetTab to a reference to tab targetTabIndex of targetSpace`}`;
+}
+const TAB_JSON = `"{\\"windowId\\":" & my jsonString(id of window targetWindowIndex) & ",\\"spaceId\\":" & my jsonString(id of targetSpace) & ",\\"tabId\\":" & my jsonString(id of targetTab) & ",\\"url\\":" & my jsonString(URL of targetTab) & ",\\"title\\":" & my jsonString(title of targetTab) & "}"`;
+function parse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Arc returned an invalid native response; no target was adopted.');
+    }
+}
+export function isArcRunning() {
+    if (process.platform !== 'darwin')
+        return Promise.resolve(false);
+    return serialized(async () => (await execAppleScript(`return application id "${APP_ID}" is running`)) === 'true');
+}
+export function enumerateArcSpaces() {
+    return serialized(async () => parse(await execAppleScript(script(`set resultText to "["
+set separator to ""
+set windowIds to id of every window
+set windowVisible to visible of every window
+repeat with wi from 1 to count of windowIds
+  if item wi of windowVisible then
+    set targetWindowIndex to wi as integer
+    set windowIdText to my jsonString(item wi of windowIds)
+    set activeId to ""
+    try
+      set activeId to id of active tab of window targetWindowIndex as text
+    end try
+    set spaceIds to id of every space of window targetWindowIndex
+    set spaceTitles to title of every space of window targetWindowIndex
+    repeat with si from 1 to count of spaceIds
+      set targetSpace to a reference to space si of window targetWindowIndex
+      set resultText to resultText & separator & "{\\"windowId\\":" & windowIdText & ",\\"spaceId\\":" & my jsonString(item si of spaceIds) & ",\\"spaceTitle\\":" & my jsonString(item si of spaceTitles) & ",\\"activeTabId\\":" & my jsonString(activeId) & ",\\"tabs\\":["
+      set tabIds to id of every tab of targetSpace
+      set tabUrls to URL of every tab of targetSpace
+      set tabTitles to title of every tab of targetSpace
+      set tabSeparator to ""
+      repeat with ti from 1 to count of tabIds
+        set resultText to resultText & tabSeparator & "{\\"windowId\\":" & windowIdText & ",\\"spaceId\\":" & my jsonString(item si of spaceIds) & ",\\"tabId\\":" & my jsonString(item ti of tabIds) & ",\\"url\\":" & my jsonString(item ti of tabUrls) & ",\\"title\\":" & my jsonString(item ti of tabTitles) & "}"
+        set tabSeparator to ","
+      end repeat
+      set resultText to resultText & "]}"
+      set separator to ","
+    end repeat
+  end if
+end repeat
+return resultText & "]"`))));
+}
+/** Caller durably records marker intent before calling; never use a real page URL as ownership. */
+export function createArcTab(target, markerUrl) {
+    if (!markerUrl || markerUrl.length > 16_384)
+        return Promise.reject(new Error('A bounded unique tab creation marker URL is required.'));
+    return serialized(async () => parse(await execAppleScript(script(`${lookup(target)}
+set existingUrls to URL of every tab of targetSpace
+repeat with ti from 1 to count of existingUrls
+  if (item ti of existingUrls as text) is ${escapeAppleScriptString(markerUrl)} then error "Creation marker already exists; reconcile the saved intent instead of creating another tab."
+end repeat
+tell targetSpace
+  make new tab with properties {URL:${escapeAppleScriptString(markerUrl)}}
+end tell
+set matchCount to 0
+set targetTabIndex to 0
+-- Arc commits the new tab's URL asynchronously: read back immediately it is
+-- still empty. Poll briefly (bounded) until the marker shows up.
+repeat with attempt from 1 to 30
+  set matchCount to 0
+  set createdUrls to URL of every tab of targetSpace
+  repeat with ti from 1 to count of createdUrls
+    if (item ti of createdUrls as text) is ${escapeAppleScriptString(markerUrl)} then
+      set matchCount to matchCount + 1
+      set targetTabIndex to ti as integer
+    end if
+  end repeat
+  if matchCount is not 0 then exit repeat
+  delay 0.1
+end repeat
+if matchCount is not 1 then error "Creation marker did not resolve exactly one tab; preserve the creation intent for recovery."
+set targetTab to a reference to tab targetTabIndex of targetSpace
+return ${TAB_JSON}`))));
+}
+export function resolveArcTab(ref) {
+    return serialized(async () => parse(await execAppleScript(script(`${lookup(ref, 'return "null"')}\nreturn ${TAB_JSON}`))));
+}
+export function navigateArcTab(ref, url) {
+    return serialized(async () => {
+        await execAppleScript(script(`${lookup(ref)}\nset URL of targetTab to ${escapeAppleScriptString(url)}\nreturn "navigated"`));
+    });
+}
+/** Arc serializes a returned object once. JSON.stringify at the top level would double-encode. */
+export function executeJavaScript(ref, expression) {
+    const wrapper = `(()=>{try{const value=(0,eval)(${JSON.stringify(expression)});if(value!=null&&typeof value.then==='function')return {ok:false,error:'Native Arc does not support asynchronous evaluation.'};return {ok:true,hasValue:value!==undefined,value:value===undefined?null:JSON.parse(JSON.stringify(value))}}catch(error){return {ok:false,error:String(error)}}})()`;
+    return serialized(async () => {
+        const result = parse(await execAppleScript(script(`${lookup(ref)}\nreturn execute targetTab javascript ${escapeAppleScriptString(wrapper)}`)));
+        if (!result || result.ok !== true)
+            throw new Error(result?.error ?? 'Native Arc JavaScript returned no result.');
+        return result.hasValue ? result.value : undefined;
+    });
+}
+export function closeArcTab(ref) {
+    return serialized(async () => {
+        const result = await execAppleScript(script(`${lookup(ref, 'return "missing"')}\nclose targetTab\nreturn "closed"`));
+        if (result !== 'closed' && result !== 'missing')
+            throw new Error('Arc did not confirm tab cleanup.');
+        return result;
+    });
+}
+/** Explicit user-facing focus only. Evaluation and cleanup never invoke this. */
+export function selectArcTab(ref) {
+    return serialized(async () => { await execAppleScript(script(`${lookup(ref)}\nselect targetTab\nreturn "selected"`)); });
+}
+/** AppleScript that selects `tabId` in whatever Space of window `targetWindowIndex` holds it; returns "true"/"false". */
+function selectTabInWindowScript(tabId) {
+    return `set spaceCount to count of spaces of window targetWindowIndex
+repeat with si from 1 to spaceCount
+  set candidateIds to id of every tab of space si of window targetWindowIndex
+  repeat with ti from 1 to count of candidateIds
+    if (item ti of candidateIds as text) is ${identity(tabId, 'tab')} then
+      select tab ti of space si of window targetWindowIndex
+      return "true"
+    end if
+  end repeat
+end repeat
+return "false"`;
+}
+/**
+ * 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 function selectWindowTab(windowId, tabId) {
+    return serialized(async () => (await execAppleScript(script(`set targetWindowIndex to 0
+set windowIds to id of every window
+set windowVisible to visible of every window
+repeat with wi from 1 to count of windowIds
+  if (item wi of windowIds as text) is ${identity(windowId, 'window')} and (item wi of windowVisible) then set targetWindowIndex to wi as integer
+end repeat
+if targetWindowIndex is 0 then return "false"
+${selectTabInWindowScript(tabId)}`))) === 'true');
+}
+/** Restore only while the task's new tab is still selected; preserve a later human choice. */
+export function restoreArcSelection(owned, previousTabId) {
+    return serialized(async () => (await execAppleScript(script(`${lookup(owned, 'return "false"')}
+if (id of active tab of window targetWindowIndex as text) is not ${identity(owned.tabId, 'tab')} then return "false"
+${selectTabInWindowScript(previousTabId)}`))) === 'true');
+}

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

@@ -85,8 +85,12 @@ export declare function getProfileDownloadsDir(name: string): string;
  * one-shot migration in migrate.ts folds old captures into here.
  */
 export declare function getProfileSessionsDir(name: string, task: string): string;
+/** Whether this name has persisted agents-cli metadata on the current device. */
+export declare function isProfileDeclaredHere(name: string): boolean;
 export declare function listProfiles(): Promise<BrowserProfileWithDeclarations[]>;
 export declare function getProfile(name: string): Promise<BrowserProfileWithDeclarations | null>;
+/** Persist only the agents-cli alias for an auto-discovered Arc profile. */
+export declare function persistDiscoveredArcProfile(name: string): Promise<void>;
 /**
  * True when `profile` can actually launch or attach on THIS machine.
  *
@@ -245,7 +249,7 @@ export declare function updateProfile(profile: BrowserProfile): Promise<void>;
  * ({@link getProfileRuntimeDir}) and any live `<name>@<endpoint>` connection, so
  * changing either orphans the cached browser data. Delete and recreate instead.
  */
-export type EditableProfileFields = Partial<Pick<BrowserProfile, 'description' | 'binary' | 'electron' | 'targetFilter' | 'endpoints' | 'launchPolicy' | 'userDataDir' | 'chrome' | 'secrets' | 'viewport'>>;
+export type EditableProfileFields = Partial<Pick<BrowserProfile, 'description' | 'binary' | 'electron' | 'targetFilter' | 'endpoints' | 'launchPolicy' | 'userDataDir' | 'chrome' | 'secrets' | 'viewport' | 'arc'>>;
 export interface EditProfileResult {
     profile: BrowserProfile;
     devices: string[];

package/dist/lib/browser/profiles.js

@@ -5,6 +5,7 @@ import { getConfigValue } from '../device-config.js';
 import { machineId } from '../machine-id.js';
 import { declaringDevices, profileRegistry, } from './registry.js';
 import { findBrowserPath, isPortInUse } from './chrome.js';
+import { arcSpaceProfiles, discoverArcProfiles } from './arc-discovery.js';
 export { declaringDevices, profileKind, profileRegistry, } from './registry.js';
 /**
  * Name of the profile the setup wizards pin as this machine's default browser
@@ -129,6 +130,7 @@ function configToProfile(name, config, devices = []) {
         viewport: config.viewport,
         logDir: config.logDir,
         logHost: config.logHost,
+        arc: config.arc,
         devices,
     };
 }
@@ -162,26 +164,100 @@ function profileToConfig(profile) {
         config.logDir = profile.logDir;
     if (profile.logHost)
         config.logHost = profile.logHost;
+    if (profile.arc)
+        config.arc = profile.arc;
     return config;
 }
+/**
+ * Every Arc Space on this Mac as an agents-cli profile (PHNX-2399). A Space
+ * already carries its Arc profile's cookies and logins, so it IS the browser
+ * profile agents pick with `--profile` — no second concept.
+ *
+ * Discovery reads files Arc rewrites on every Space or tab change, so a torn
+ * read is an ordinary event, not corruption. It is reported as `error` rather
+ * than thrown: the profile store serves every browser on this machine, and a
+ * momentary Arc read must never take the Comet or Chrome rows down with it.
+ * The error surfaces where an Arc profile is actually asked for by name.
+ */
+function discoverArcSpaceProfiles() {
+    const discovered = discoverArcProfiles();
+    if (!discovered.ok) {
+        if (discovered.kind === 'unsupported' || discovered.kind === 'not-installed')
+            return { profiles: [] };
+        return { profiles: [], error: `Cannot discover Arc Spaces: ${discovered.reason}` };
+    }
+    return {
+        profiles: arcSpaceProfiles(discovered).map((space) => ({
+            name: space.name,
+            description: `Arc Space "${space.spaceTitle}" (${space.profileName})`,
+            browser: 'arc',
+            endpoints: { native: { target: 'arc-native://local' } },
+            defaultEndpoint: 'native',
+            launchPolicy: 'attach-only',
+            arc: {
+                profileId: space.profileId,
+                profileName: space.profileName,
+                spaceId: space.spaceId,
+                spaceTitle: space.spaceTitle,
+            },
+            devices: [machineId()],
+        })),
+    };
+}
+/**
+ * Bring a persisted Arc alias up to date with the live Space (title renames).
+ * A Space that is no longer discoverable leaves the alias as stored: listing
+ * still works, and using the profile fails loud in `resolveArcSpace` with the
+ * Space that is missing from Arc's visible windows.
+ */
+function refreshLocalArcProfile(profile, live) {
+    if (!profile.arc || !profile.devices.includes(machineId()))
+        return profile;
+    const current = live.find((candidate) => candidate.arc?.spaceId === profile.arc?.spaceId);
+    if (!current)
+        return profile;
+    return { ...profile, arc: current.arc, description: profile.description ?? current.description };
+}
 function selectedDeclaration(declarations) {
     return declarations.find((declaration) => declaration.device === machineId()) ?? declarations[0];
 }
 function localDeclaration(name) {
     return profileRegistry().get(name)?.find((declaration) => declaration.device === machineId());
 }
+/** Whether this name has persisted agents-cli metadata on the current device. */
+export function isProfileDeclaredHere(name) {
+    return localDeclaration(name) !== undefined;
+}
 export async function listProfiles() {
-    return [...profileRegistry()].map(([name, declarations]) => {
+    const native = discoverArcSpaceProfiles();
+    const configured = [...profileRegistry()].map(([name, declarations]) => {
         const selected = selectedDeclaration(declarations);
-        return configToProfile(name, selected.config, declarations.map((declaration) => declaration.device));
+        return refreshLocalArcProfile(configToProfile(name, selected.config, declarations.map((declaration) => declaration.device)), native.profiles);
     });
+    const names = new Set(configured.map((profile) => profile.name));
+    return [...configured, ...native.profiles.filter((profile) => !names.has(profile.name))];
 }
 export async function getProfile(name) {
+    const native = discoverArcSpaceProfiles();
     const declarations = profileRegistry().get(name);
-    if (!declarations?.length)
-        return null;
-    const selected = selectedDeclaration(declarations);
-    return configToProfile(name, selected.config, declarations.map((declaration) => declaration.device));
+    if (declarations?.length) {
+        const selected = selectedDeclaration(declarations);
+        return refreshLocalArcProfile(configToProfile(name, selected.config, declarations.map((declaration) => declaration.device)), native.profiles);
+    }
+    const discovered = native.profiles.find((profile) => profile.name === name) ?? null;
+    // Only an Arc profile asked for by name pays for a failed Arc read.
+    if (!discovered && native.error && name.startsWith('arc-'))
+        throw new Error(native.error);
+    return discovered;
+}
+/** Persist only the agents-cli alias for an auto-discovered Arc profile. */
+export async function persistDiscoveredArcProfile(name) {
+    if (localDeclaration(name))
+        return;
+    const profile = discoverArcSpaceProfiles().profiles.find((candidate) => candidate.name === name);
+    if (!profile)
+        return;
+    await createProfile(profile);
 }
 /**
  * True when `profile` can actually launch or attach on THIS machine.
@@ -194,6 +270,10 @@ export async function getProfile(name) {
  * for the current machine.
  */
 export function isProfileLaunchableHere(profile) {
+    const nativeArc = Object.values(getEndpointPresets(profile)).some((preset) => preset.target.startsWith('arc-native:'));
+    if (nativeArc) {
+        return !!profile.arc && discoverArcSpaceProfiles().profiles.some((candidate) => candidate.arc?.spaceId === profile.arc?.spaceId);
+    }
     const remote = Object.values(getEndpointPresets(profile)).some((preset) => preset.target.startsWith('ssh://'));
     if (remote)
         return true;
@@ -334,7 +414,7 @@ export async function ensureDefaultBrowserProfile() {
     const configured = getConfiguredDefaultProfileName();
     if (configured && configured !== DEFAULT_PROFILE_ALIAS) {
         const chosen = await getProfile(configured);
-        if (chosen && isProfileLaunchableHere(chosen))
+        if (chosen && (!chosen.devices.includes(machineId()) || isProfileLaunchableHere(chosen)))
             return chosen;
         if (!chosen) {
             const central = readMeta().browser ?? {};
@@ -520,7 +600,11 @@ export async function createProfile(profile) {
     // Skip for SSH profiles: the browser binary lives on the remote host, so a
     // local lookup would validate the wrong machine. The remote launcher resolves
     // it at connect time.
-    if (!hasSshEndpoint(profile.endpoints)) {
+    const nativeArc = Object.values(getEndpointPresets(profile)).some((preset) => preset.target.startsWith('arc-native:'));
+    if (nativeArc && (!profile.arc || profile.browser !== 'arc')) {
+        throw new Error('An arc-native profile requires stable Arc Space metadata. Pick a discovered one from `agents browser profiles list`.');
+    }
+    if (!hasSshEndpoint(profile.endpoints) && !nativeArc) {
         findBrowserPath(profile.browser, profile.binary);
     }
     const config = profileToConfig(profile);
@@ -575,7 +659,8 @@ export async function editProfile(name, patch) {
     assertLocalPortFree(merged, { ignore: name });
     // Same rule as create: the binary lives on the remote for an SSH profile, so a
     // local lookup would validate the wrong machine.
-    if (!hasSshEndpoint(merged.endpoints)) {
+    const nativeArc = Object.values(getEndpointPresets(merged)).some((preset) => preset.target.startsWith('arc-native:'));
+    if (!hasSshEndpoint(merged.endpoints) && !nativeArc) {
         findBrowserPath(merged.browser, merged.binary);
     }
     await updateProfile(merged);

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

@@ -10,6 +10,8 @@ export interface RefNode {
     name: string;
     attrs: string[];
     backendNodeId?: number;
+    /** Stable selector used by non-CDP DOM backends such as native Arc. */
+    selector?: string;
     editor?: string;
 }
 /**