@nuanu-ai/agentbrowse 0.2.21 → 0.2.23

package/dist/commands/descriptor-validation.js

@@ -1,3 +1,4 @@
+import { OBSERVE_DOM_LABEL_CONTRACT_HELPER_SCRIPT } from './observe-dom-label-contract.js';
 export function normalizePageSignature(url) {
     try {
         const parsed = new URL(url);
@@ -8,184 +9,30 @@ export function normalizePageSignature(url) {
     }
 }
 export const LOCATOR_DOM_SIGNATURE_SCRIPT = String.raw `
+  ${OBSERVE_DOM_LABEL_CONTRACT_HELPER_SCRIPT}
   if (!(element instanceof HTMLElement)) {
     return null;
   }
 
-  const inputTypeOf = () => {
-    if (element.tagName.toLowerCase() !== 'input') return '';
-    return (element.getAttribute('type') || 'text').toLowerCase();
-  };
-
-  const isButtonLikeInput = () => {
-    return element.tagName.toLowerCase() === 'input' &&
-      ['button', 'submit', 'reset'].includes(inputTypeOf());
-  };
-
-  const inferRole = () => {
-    const explicitRole = element.getAttribute('role')?.trim();
-    if (explicitRole) return explicitRole;
-
-    const tag = element.tagName.toLowerCase();
-    if (tag === 'button') return 'button';
-    if (tag === 'a' && element.getAttribute('href')) return 'link';
-    if (tag === 'select') return 'combobox';
-    if (tag === 'textarea') return 'textbox';
-    if (tag === 'input') {
-      if (isButtonLikeInput()) return 'button';
-      return 'textbox';
-    }
-    return '';
-  };
-
-  const textOf = (target) => {
-    if (target === element && isButtonLikeInput()) {
-      const value = (element.getAttribute('value') || element.value || '').trim();
-      if (value) {
-        return value.replace(/\s+/g, ' ');
-      }
-    }
-    const value = target?.innerText?.trim() || target?.textContent?.trim() || '';
-    return value.replace(/\s+/g, ' ');
-  };
-
-  const isMeaningfulLabel = (value) => {
-    const normalized = (value || '').replace(/\s+/g, ' ').trim();
-    return Boolean(normalized) && normalized !== '[object Object]';
-  };
-
-  const composedParentElement = (node) => {
-    if (!node) {
-      return null;
-    }
-    if (node.parentElement) {
-      return node.parentElement;
-    }
-    const root = node.getRootNode?.();
-    return root instanceof ShadowRoot && root.host instanceof HTMLElement ? root.host : null;
-  };
-
-  const ariaLabelledbyTextOf = () => {
-    const labelledBy = element.getAttribute('aria-labelledby')?.trim();
-    if (!labelledBy) return undefined;
-
-    const text = labelledBy
-      .split(/\s+/)
-      .map((id) => textOf(document.getElementById(id)))
-      .filter(Boolean)
-      .join(' ')
-      .trim();
-
-    return isMeaningfulLabel(text) ? text : undefined;
-  };
-
-  const nearestFieldLabelOf = () => {
-    const anchors = [
-      composedParentElement(element),
-      composedParentElement(composedParentElement(element)),
-      composedParentElement(composedParentElement(composedParentElement(element))),
-    ].filter(Boolean);
-
-    for (const anchor of anchors) {
-      if (!(anchor instanceof HTMLElement)) continue;
-
-      const explicitLabels = Array.from(
-        anchor.querySelectorAll('label, legend, [class*="label"], [data-testid*="label"]')
-      ).filter((candidate) => {
-        return (
-          candidate instanceof HTMLElement &&
-          candidate !== element &&
-          !candidate.contains(element) &&
-          !element.contains(candidate)
-        );
-      });
-
-      for (const candidate of explicitLabels) {
-        const candidateText = textOf(candidate);
-        if (isMeaningfulLabel(candidateText)) {
-          return candidateText;
-        }
-      }
-
-      for (const child of Array.from(anchor.children).slice(0, 8)) {
-        if (!(child instanceof HTMLElement)) continue;
-        if (child === element || child.contains(element) || element.contains(child)) continue;
-
-        const candidateText = textOf(child);
-        if (isMeaningfulLabel(candidateText)) {
-          return candidateText;
-        }
-      }
-    }
-
-    return undefined;
-  };
-
-  const syntheticLabelOf = () => {
-    const tag = element.tagName.toLowerCase();
-    const explicitRole = element.getAttribute('role')?.trim();
-    if (tag === 'input') {
-      const inputType = inputTypeOf();
-      if (isButtonLikeInput()) return 'Button';
-      if (inputType === 'tel') return 'Phone input';
-      if (inputType === 'email') return 'Email input';
-      if (inputType === 'password') return 'Password input';
-      if (inputType === 'search') return 'Search input';
-      if (inputType === 'date') return 'Date input';
-      return 'Text input';
-    }
-    if (tag === 'textarea') return 'Text area';
-    if (tag === 'select' || explicitRole === 'combobox') return 'Combobox';
-    if (explicitRole === 'textbox') return 'Text input';
-    return undefined;
-  };
-
-  const labelOf = () => {
-    const ariaLabel = element.getAttribute('aria-label')?.trim();
-    if (isMeaningfulLabel(ariaLabel)) return ariaLabel;
-
-    const customLabel = element.getAttribute('label')?.trim();
-    if (isMeaningfulLabel(customLabel)) return customLabel;
-
-    const ariaLabelledbyText = ariaLabelledbyTextOf();
-    if (isMeaningfulLabel(ariaLabelledbyText)) return ariaLabelledbyText;
-
-    if ('labels' in element && Array.isArray(Array.from(element.labels ?? []))) {
-      const labels = element.labels;
-      const firstLabel = labels && labels.length > 0 ? textOf(labels[0]) : '';
-      if (isMeaningfulLabel(firstLabel)) return firstLabel;
-    }
-
-    const text = textOf(element);
-    if (isMeaningfulLabel(text)) return text;
-
-    const nearestFieldLabel = isButtonLikeInput() ? undefined : nearestFieldLabelOf();
-    if (isMeaningfulLabel(nearestFieldLabel)) return nearestFieldLabel;
-
-    return syntheticLabelOf() || '';
-  };
-
-  return element.tagName.toLowerCase() + '|' + inferRole() + '|' + labelOf();
+  return (
+    element.tagName.toLowerCase() +
+    '|' +
+    observedInferRole(element) +
+    '|' +
+    observedLabelOf(element)
+  );
 `;
 function readLocatorDomSignatureInBrowser(element) {
     return Function('element', LOCATOR_DOM_SIGNATURE_SCRIPT)(element);
 }
 const LOCATOR_BINDING_SNAPSHOT_SCRIPT = String.raw `
+  ${OBSERVE_DOM_LABEL_CONTRACT_HELPER_SCRIPT}
   if (!(element instanceof HTMLElement)) {
     return null;
   }
 
   const read = Function('element', ${JSON.stringify(LOCATOR_DOM_SIGNATURE_SCRIPT)});
-  const explicitRole = element.getAttribute('role')?.trim() || '';
-  const role =
-    explicitRole ||
-    (element.tagName.toLowerCase() === 'select'
-      ? 'combobox'
-      : element.tagName.toLowerCase() === 'textarea'
-        ? 'textbox'
-        : element.tagName.toLowerCase() === 'input'
-          ? 'textbox'
-          : '');
+  const role = observedInferRole(element);
   const domSignature = read(element);
   const label = typeof domSignature === 'string' ? domSignature.split('|').slice(2).join('|') : undefined;
   return {
@@ -287,14 +134,8 @@ export async function readLocatorOuterHtml(locator) {
                 'track',
                 'wbr',
             ]);
-            const escapeText = (value) => value
-                .replace(/&/g, '&')
-                .replace(/</g, '&lt;')
-                .replace(/>/g, '&gt;');
-            const escapeAttribute = (value) => value
-                .replace(/&/g, '&amp;')
-                .replace(/"/g, '&quot;')
-                .replace(/</g, '&lt;');
+            const escapeText = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+            const escapeAttribute = (value) => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
             const serializeChildren = (parent) => Array.from(parent.childNodes)
                 .map((node) => serializeNode(node))
                 .join('');

package/dist/commands/extract-scoped-dialog-text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-scoped-dialog-text.d.ts","sourceRoot":"","sources":["../../src/commands/extract-scoped-dialog-text.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAuM5C,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyB/F"}
+{"version":3,"file":"extract-scoped-dialog-text.d.ts","sourceRoot":"","sources":["../../src/commands/extract-scoped-dialog-text.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAuM5C,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAsB/F"}

package/dist/commands/extract-scoped-dialog-text.js

@@ -196,10 +196,7 @@ export async function readScopedDialogText(page, selector) {
         return null;
     }
     try {
-        const result = await page
-            .locator(selector)
-            .first()
-            .evaluate(readScopedDialogTextInBrowser, {
+        const result = await page.locator(selector).first().evaluate(readScopedDialogTextInBrowser, {
             marker: BLOCK_MARKER,
             anchorSelector: ANCHOR_SELECTOR,
             minBlockTextLength: 20,

package/dist/commands/extract-snapshot-sanitizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-snapshot-sanitizer.d.ts","sourceRoot":"","sources":["../../src/commands/extract-snapshot-sanitizer.ts"],"names":[],"mappings":"AAwEA,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQhE"}
+{"version":3,"file":"extract-snapshot-sanitizer.d.ts","sourceRoot":"","sources":["../../src/commands/extract-snapshot-sanitizer.ts"],"names":[],"mappings":"AAuEA,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQhE"}

package/dist/commands/extract-stagehand-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-stagehand-executor.d.ts","sourceRoot":"","sources":["../../src/commands/extract-stagehand-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAI5C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAA8B,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAI9F,MAAM,MAAM,yBAAyB,GAAG,iBAAiB,GAAG;IAC1D,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,mBAAmB,CAAC;CACjC,CAAC;AAaF,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAsDrC"}
+{"version":3,"file":"extract-stagehand-executor.d.ts","sourceRoot":"","sources":["../../src/commands/extract-stagehand-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAI5C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAA8B,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAI9F,MAAM,MAAM,yBAAyB,GAAG,iBAAiB,GAAG;IAC1D,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,mBAAmB,CAAC;CACjC,CAAC;AAiBF,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAsDrC"}

package/dist/commands/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/commands/extract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AA8KnD,wBAAsB,OAAO,CAC3B,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAkMf"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/commands/extract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAmMnD,wBAAsB,OAAO,CAC3B,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAkMf"}

package/dist/commands/extract.js

@@ -44,10 +44,14 @@ function describeSchema(descriptor, prefix) {
         }
         if (Array.isArray(value)) {
             const itemDescriptor = value[0];
-            if (itemDescriptor === 'string' || itemDescriptor === 'number' || itemDescriptor === 'boolean') {
+            if (itemDescriptor === 'string' ||
+                itemDescriptor === 'number' ||
+                itemDescriptor === 'boolean') {
                 lines.push(`${fieldPath}[]: ${itemDescriptor}`);
             }
-            else if (typeof itemDescriptor === 'object' && itemDescriptor !== null && !Array.isArray(itemDescriptor)) {
+            else if (typeof itemDescriptor === 'object' &&
+                itemDescriptor !== null &&
+                !Array.isArray(itemDescriptor)) {
                 lines.push(...describeSchema(itemDescriptor, `${fieldPath}[]`));
             }
             else {
@@ -98,8 +102,23 @@ function canUseTargetAsExtractScope(target) {
         'form',
         'group',
     ]);
-    const leafInteractiveKinds = new Set(['input', 'textarea', 'select', 'option', 'button', 'link', 'combobox']);
-    const leafInteractiveRoles = new Set(['textbox', 'combobox', 'option', 'menuitem', 'button', 'link']);
+    const leafInteractiveKinds = new Set([
+        'input',
+        'textarea',
+        'select',
+        'option',
+        'button',
+        'link',
+        'combobox',
+    ]);
+    const leafInteractiveRoles = new Set([
+        'textbox',
+        'combobox',
+        'option',
+        'menuitem',
+        'button',
+        'link',
+    ]);
     const iframeFieldLike = Boolean(target.framePath?.length) &&
         (target.allowedActions.includes('fill') ||
             target.allowedActions.includes('type') ||

package/dist/commands/launch.d.ts

@@ -1,10 +1,31 @@
 /**
  * browse launch [url] — Start browser session, optionally navigate.
  */
+import type { SecretCatalogSummary } from '../secrets/catalog-sync.js';
 export type LaunchCliOptions = {
     compact?: boolean;
     profile?: string;
     headless?: boolean;
+    proxy?: string;
+    noProxy?: boolean;
 };
-export declare function launch(url?: string, opts?: LaunchCliOptions): Promise<void>;
+export type LaunchSuccessResult = {
+    success: true;
+    runtime: 'managed';
+    captchaSolveCapable: true;
+    profile: string;
+    cdpUrl: string;
+    url: string;
+    title: string;
+    secretCatalog?: SecretCatalogSummary;
+};
+export type LaunchFailureResult = {
+    success: false;
+    error: 'browser_launch_failed';
+    outcomeType: 'blocked';
+    message: 'Browser launch failed.';
+    reason: string;
+};
+export type LaunchResult = LaunchSuccessResult | LaunchFailureResult;
+export declare function launch(url?: string, opts?: LaunchCliOptions): Promise<LaunchResult>;
 //# sourceMappingURL=launch.d.ts.map

package/dist/commands/launch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/commands/launch.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsBH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,wBAAsB,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjF"}
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/commands/launch.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAWvE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,SAAS,CAAC;IACnB,mBAAmB,EAAE,IAAI,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,oBAAoB,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,uBAAuB,CAAC;IAC/B,WAAW,EAAE,SAAS,CAAC;IACvB,OAAO,EAAE,wBAAwB,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAErE,wBAAsB,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAazF"}

package/dist/commands/launch.js

@@ -1,92 +1,112 @@
 /**
  * browse launch [url] — Start browser session, optionally navigate.
  */
-import { execSync } from 'node:child_process';
 import { readConfig } from '../solver/config.js';
 import { ensureProfile } from '../solver/profile-manager.js';
 import { launchSolver } from '../solver/browser-launcher.js';
-import { saveSession } from '../session.js';
+import { buildOwnedSession, isOwnedSession, loadSession, saveSession } from '../session.js';
 import { findChromePid } from '../stagehand.js';
-import { outputContractFailure, outputJSON } from '../output.js';
 import { applyAgentpayGatewayEnv, tryResolveAgentpayGatewayConfig } from '../agentpay-gateway.js';
 import { connectPlaywright, disconnectPlaywright, syncLaunchPage } from '../playwright-runtime.js';
 import { summarizeSecretCatalog, syncSecretCatalogForUrl } from '../secrets/catalog-sync.js';
-const CDP_PORT = 9222;
+import { terminateOwnedPid } from '../owned-process.js';
+import { info } from '../output.js';
 const DEFAULT_PROFILE = 'default';
 const COMPACT_WINDOW = {
     width: 1280,
     height: 900,
 };
 export async function launch(url, opts) {
-    await killChromeOnPort(CDP_PORT);
+    const cleanupFailure = await cleanupOwnedSession();
+    if (cleanupFailure) {
+        return cleanupFailure;
+    }
     const compact = opts?.compact ?? true;
     const profileName = opts?.profile ?? DEFAULT_PROFILE;
     const headless = opts?.headless ?? false;
-    await launchManaged(url, profileName, headless, compact);
+    const proxyOverride = opts?.proxy;
+    const noProxy = opts?.noProxy ?? false;
+    return launchManaged(url, profileName, headless, compact, proxyOverride, noProxy);
 }
-async function killChromeOnPort(port) {
-    const pids = getPidsOnPort(port);
-    if (pids.length === 0)
-        return;
-    for (const pid of pids) {
-        try {
-            process.kill(pid, 'SIGTERM');
-        }
-        catch {
-            // Skip stale PID.
-        }
+async function cleanupOwnedSession() {
+    const existingSession = loadSession();
+    if (!isOwnedSession(existingSession)) {
+        return null;
     }
-    for (let i = 0; i < 20; i++) {
-        if (getPidsOnPort(port).length === 0)
-            return;
-        await sleep(100);
+    const termination = await terminateOwnedPid(existingSession.pid);
+    if (termination === 'still_alive') {
+        return buildLaunchFailure(new Error(`Existing owned browser pid ${existingSession.pid} did not exit after SIGTERM/SIGKILL.`));
     }
-    for (const pid of getPidsOnPort(port)) {
-        try {
-            process.kill(pid, 'SIGKILL');
-        }
-        catch {
-            // Skip stale PID.
+    return null;
+}
+function buildLaunchFailure(err) {
+    return {
+        success: false,
+        error: 'browser_launch_failed',
+        outcomeType: 'blocked',
+        message: 'Browser launch failed.',
+        reason: formatUnknownError(err),
+    };
+}
+function getPortFromCdpUrl(cdpUrl) {
+    try {
+        const url = new URL(cdpUrl);
+        if (!url.port) {
+            return undefined;
         }
+        const port = Number(url.port);
+        return Number.isFinite(port) && port > 0 ? port : undefined;
+    }
+    catch {
+        return undefined;
     }
 }
-async function launchManaged(url, profileName, headless, compact) {
+async function launchManaged(url, profileName, headless, compact, proxyOverride, noProxy = false) {
     let session;
     let browser = null;
     let secretCatalogSummary;
     try {
-        const profile = ensureProfile(profileName);
+        const baseProfile = ensureProfile(profileName);
         const config = readConfig();
+        const runtimeProxy = resolveLaunchProxy({
+            profileProxy: baseProfile.fingerprint.proxy,
+            configProxy: config.defaults?.proxy,
+            cliProxy: proxyOverride,
+            noProxy,
+        });
+        const profile = withLaunchProxy(baseProfile, runtimeProxy);
         const gateway = tryResolveAgentpayGatewayConfig();
         if (gateway) {
             applyAgentpayGatewayEnv(gateway);
         }
+        if (runtimeProxy) {
+            info(`[launch] starting browser with proxy ${runtimeProxy.server}`);
+        }
         session = await launchSolver(profile, {
             headless: headless || config.defaults?.headless,
             url,
-            cdpPort: CDP_PORT,
+            cdpPort: undefined,
             windowSize: compact ? COMPACT_WINDOW : undefined,
         });
     }
     catch (err) {
-        outputContractFailure({
-            error: 'browser_launch_failed',
-            outcomeType: 'blocked',
-            message: 'Browser launch failed.',
-            reason: formatUnknownError(err),
-        });
+        return buildLaunchFailure(err);
+    }
+    const cdpPort = getPortFromCdpUrl(session.cdpUrl);
+    const chromePid = findChromePid(cdpPort);
+    if (!chromePid) {
+        await session.close().catch(() => undefined);
+        return buildLaunchFailure(new Error('Launched browser PID could not be resolved.'));
     }
-    const chromePid = findChromePid(CDP_PORT) ?? process.pid;
-    const persistedSession = {
+    const persistedSession = buildOwnedSession({
         cdpUrl: session.cdpUrl,
         pid: chromePid,
-        port: CDP_PORT,
         profile: profileName,
         launchedAt: new Date().toISOString(),
         capabilities: {
             captchaSolve: true,
         },
-    };
+    });
     saveSession(persistedSession);
     let currentUrl = session.page.url();
     let title = await session.page.title().catch(() => '');
@@ -111,10 +131,12 @@ async function launchManaged(url, profileName, headless, compact) {
     }
     if (url) {
         const snapshot = await syncSecretCatalogForUrl(persistedSession, currentUrl || url);
-        secretCatalogSummary = summarizeSecretCatalog(snapshot);
+        if (snapshot) {
+            secretCatalogSummary = summarizeSecretCatalog(snapshot);
+        }
     }
     saveSession(persistedSession);
-    outputJSON({
+    return {
         success: true,
         runtime: 'managed',
         captchaSolveCapable: true,
@@ -123,21 +145,7 @@ async function launchManaged(url, profileName, headless, compact) {
         url: currentUrl,
         title,
         secretCatalog: secretCatalogSummary,
-    });
-}
-function getPidsOnPort(port) {
-    try {
-        const out = execSync(`lsof -ti :${port}`, { encoding: 'utf-8' }).trim();
-        if (!out)
-            return [];
-        return out
-            .split('\n')
-            .map((value) => Number(value))
-            .filter((value) => Number.isFinite(value) && value > 0);
-    }
-    catch {
-        return [];
-    }
+    };
 }
 function formatUnknownError(err) {
     if (err instanceof Error)
@@ -154,6 +162,61 @@ function formatUnknownError(err) {
     }
     return String(err);
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function resolveLaunchProxy(options) {
+    if (options.noProxy) {
+        return undefined;
+    }
+    if (options.cliProxy) {
+        return normalizeProxySetting(options.cliProxy);
+    }
+    if (options.configProxy) {
+        return normalizeProxySetting(options.configProxy);
+    }
+    if (options.profileProxy) {
+        return normalizeProxySetting(options.profileProxy);
+    }
+    return undefined;
+}
+function withLaunchProxy(profile, proxy) {
+    return {
+        ...profile,
+        fingerprint: {
+            ...profile.fingerprint,
+            proxy,
+        },
+    };
+}
+function normalizeProxySetting(value) {
+    if (typeof value === 'string') {
+        return parseProxyString(value);
+    }
+    const normalized = parseProxyString(value.server);
+    const username = value.username?.trim() || normalized.username;
+    const password = value.password ?? normalized.password;
+    return {
+        server: normalized.server,
+        ...(username ? { username } : {}),
+        ...(password ? { password } : {}),
+    };
+}
+function parseProxyString(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error('Proxy value must not be empty.');
+    }
+    try {
+        const parsed = new URL(trimmed);
+        const server = `${parsed.protocol}//${parsed.host}`;
+        if (!parsed.hostname) {
+            throw new Error('missing hostname');
+        }
+        return {
+            server,
+            ...(parsed.username ? { username: decodeURIComponent(parsed.username) } : {}),
+            ...(parsed.password ? { password: decodeURIComponent(parsed.password) } : {}),
+        };
+    }
+    catch {
+        return { server: trimmed };
+    }
 }

package/dist/commands/observe-accessibility.d.ts

@@ -0,0 +1,22 @@
+import type { Page } from 'playwright-core';
+import type { DomObservedTarget } from './observe-inventory.js';
+type ObserveAccessibilitySemantics = {
+    role?: string;
+    name?: string;
+    states?: Record<string, string | boolean | number>;
+};
+export type ObserveAccessibilityStats = {
+    axAttempts: number;
+    axHits: number;
+    fallbackUses: number;
+};
+type ObserveAccessibilityOptions = {
+    onStats?: (stats: ObserveAccessibilityStats) => void;
+};
+export declare function parseObserveAriaSnapshot(snapshot: string | undefined | null): ObserveAccessibilitySemantics | null;
+export declare function enrichDomTargetsWithAccessibility(page: Page, targets: ReadonlyArray<DomObservedTarget>, options?: ObserveAccessibilityOptions): Promise<DomObservedTarget[]>;
+export declare const __testObserveAccessibility: {
+    parseObserveAriaSnapshot: typeof parseObserveAriaSnapshot;
+};
+export {};
+//# sourceMappingURL=observe-accessibility.d.ts.map

package/dist/commands/observe-accessibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe-accessibility.d.ts","sourceRoot":"","sources":["../../src/commands/observe-accessibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAS5C,OAAO,KAAK,EAEV,iBAAiB,EAElB,MAAM,wBAAwB,CAAC;AAEhC,KAAK,6BAA6B,GAAG;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;CACpD,CAAC;AAOF,MAAM,MAAM,yBAAyB,GAAG;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,KAAK,2BAA2B,GAAG;IACjC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,CAAC;CACtD,CAAC;AAyDF,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAClC,6BAA6B,GAAG,IAAI,CAoDtC;AA+nBD,wBAAsB,iCAAiC,CACrD,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,EACzC,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAY9B;AAED,eAAO,MAAM,0BAA0B;;CAEtC,CAAC"}