@phnx-labs/agents-cli 1.22.93 → 1.22.95

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/drivers/firefox.d.ts

@@ -0,0 +1,103 @@
+import type { BrowserProfile, ConnectionKey } from '../types.js';
+/** How agents obtain a live Firefox — matches the CDP driver's launch/attach split. */
+export interface FirefoxConnection {
+    bidi: FirefoxBiDiClient;
+    port: number;
+    /** The Firefox process pid we launched, or 0 when we attached to a running one. */
+    pid: number;
+    /** The BiDi session id from `session.new`. */
+    sessionId: string;
+}
+/**
+ * A verb Firefox-over-BiDi cannot serve (network capture, upload, pdf, trusted
+ * key input, …). Mirrors `ArcNativeCapabilityError`: the service throws it in
+ * the one place the capability is missing, and the message steers the caller to
+ * a Chromium-family profile that has it.
+ */
+export declare class FirefoxCapabilityError extends Error {
+    readonly capability: string;
+    constructor(capability: string, message?: string);
+}
+/** A BiDi error frame carrying the protocol error + human message. */
+export declare class FirefoxBiDiError extends Error {
+    readonly bidiError: string;
+    constructor(bidiError: string, message: string);
+}
+/**
+ * Minimal WebDriver BiDi client: request/response keyed by the `id` field, with
+ * events drained and ignored. Deliberately shaped like `CDPClient` so the
+ * service treats a Firefox connection the same way it treats a CDP one. The
+ * large `maxPayload` matches CDPClient's, so a base64 screenshot of a
+ * content-rich page never trips the socket's decompressed-size cap.
+ */
+export declare class FirefoxBiDiClient {
+    private ws;
+    private nextId;
+    private pending;
+    private closed;
+    get isOpen(): boolean;
+    connect(url: string): Promise<void>;
+    private handleMessage;
+    private handleClose;
+    send<T = Record<string, unknown>>(method: string, params?: Record<string, unknown>): Promise<T>;
+    close(): void;
+}
+/**
+ * The loud error raised when a Firefox already holds this profile but exposes no
+ * BiDi port, so agents cannot attach and must not launch a rival (Firefox is
+ * single-instance per profile dir). Mirrors `attachOnlyRequiredError` in
+ * `drivers/local.ts`: name the exact relaunch that makes the running instance
+ * attachable. Exported so the contract is unit-testable without a real Firefox.
+ */
+export declare function firefoxAttachRequiredError(profile: Pick<BrowserProfile, 'name'> & {
+    firefox?: {
+        profileName: string;
+    };
+}, port: number, profileDir: string): Error;
+/**
+ * Connect a Firefox profile over BiDi: attach if the port is already served,
+ * otherwise launch Firefox and wait for it. Fails loud when a Firefox holds the
+ * profile without a port.
+ */
+export declare function connectFirefox(profile: BrowserProfile, key: ConnectionKey, port: number, opts?: {
+    profileDir: string;
+    headless?: boolean;
+}): Promise<FirefoxConnection>;
+export declare function deserializeBidi(remote: unknown): unknown;
+/** One top-level browsing context (a tab), flattened from `browsingContext.getTree`. */
+export interface BiDiContext {
+    context: string;
+    url: string;
+}
+/** Every top-level tab currently open in this Firefox. */
+export declare function bidiTopLevelContexts(bidi: FirefoxBiDiClient): Promise<BiDiContext[]>;
+/** Open a fresh tab and return its context id. */
+export declare function bidiCreateTab(bidi: FirefoxBiDiClient): Promise<string>;
+/** Navigate a context and wait for the document to finish loading. */
+export declare function bidiNavigate(bidi: FirefoxBiDiClient, context: string, url: string): Promise<void>;
+/** Reload a context in place, waiting for load. */
+export declare function bidiReload(bidi: FirefoxBiDiClient, context: string): Promise<void>;
+/** Close a tab. */
+export declare function bidiCloseTab(bidi: FirefoxBiDiClient, context: string): Promise<void>;
+/** Bring a tab to the foreground (explicit focus only). */
+export declare function bidiActivate(bidi: FirefoxBiDiClient, context: string): Promise<void>;
+/**
+ * Evaluate an expression in a context and return the deserialized value.
+ * `awaitPromise` mirrors the CDP evaluate contract; a thrown/rejected value
+ * surfaces as an Error rather than a silent undefined.
+ */
+export declare function bidiEvaluate(bidi: FirefoxBiDiClient, context: string, expression: string): Promise<unknown>;
+/** Capture a screenshot of the viewport as raw bytes. `quality` is 0–1 for JPEG. */
+export declare function bidiScreenshot(bidi: FirefoxBiDiClient, context: string, format: {
+    type: 'image/png';
+} | {
+    type: 'image/jpeg';
+    quality: number;
+}): Promise<Buffer>;
+/**
+ * A real, trusted left click at viewport coordinates via `input.performActions`
+ * — the pointer path CDP `Input.dispatchMouseEvent` gives Chromium, which Arc
+ * (Apple Events) never had. The service resolves a ref to (x, y) first, exactly
+ * as the CDP click path does.
+ */
+export declare function bidiClickAt(bidi: FirefoxBiDiClient, context: string, x: number, y: number): Promise<void>;