@mercuryo-ai/agentbrowse 0.2.60 → 0.2.63

package/dist/commands/attach.d.ts

@@ -1,7 +1,7 @@
 /**
  * attach <cdp-url> — Attach AgentBrowse to an existing browser session.
  */
-import { type BrowserSessionState, type BrowserSessionCapabilities } from '../browser-session-state.js';
+import { type BrowserSessionState } from '../browser-session-state.js';
 import type { BrowseSessionTransport } from '../browser-session-state.js';
 /** Stable top-level error codes returned by `attach(...)`. */
 export declare const ATTACH_ERROR_CODES: readonly ["browser_attach_failed"];
@@ -13,7 +13,6 @@ export type AttachOutcomeType = (typeof ATTACH_OUTCOME_TYPES)[number];
 export type AttachOptions = {
     launchedAt?: string;
     provider?: string;
-    capabilities?: BrowserSessionCapabilities;
     transport?: BrowseSessionTransport;
 };
 /** Successful attach result for an existing CDP browser session. */
@@ -25,7 +24,6 @@ export type AttachSuccessResult = {
     url: string;
     title: string;
     provider?: string;
-    captchaSolveCapable: boolean;
 };
 /** Failed attach result with a stable top-level error code. */
 export type AttachFailureResult = {

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

@@ -1 +1 @@
-{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../src/commands/attach.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAChC,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,oCAAqC,CAAC;AAErE,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,sBAAuB,CAAC;AAEzD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAClE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,0BAA0B,CAAC;IAC1C,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC,CAAC;AAEF,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,eAAe,CAAC;IACvB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,EAAE,wBAAwB,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAErE,wFAAwF;AACxF,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA2C/F"}
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../src/commands/attach.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAG1E,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,oCAAqC,CAAC;AAErE,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,sBAAuB,CAAC;AAEzD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAClE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC,CAAC;AAEF,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,eAAe,CAAC;IACvB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,EAAE,wBAAwB,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAErE,wFAAwF;AACxF,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAoC/F"}

package/dist/commands/attach.js

@@ -2,28 +2,27 @@
  * attach <cdp-url> — Attach AgentBrowse to an existing browser session.
  */
 import { buildAttachedSession, buildCdpHttpEndpointUrl, } from '../browser-session-state.js';
-import { connectPlaywright, disconnectPlaywright, syncLaunchPage } from '../playwright-runtime.js';
+import { syncLaunchPage } from '../playwright-runtime.js';
+import { initializeBrowserSessionOwner, withStickyOwnerBrowser } from '../sticky-owner.js';
 /** Stable top-level error codes returned by `attach(...)`. */
 export const ATTACH_ERROR_CODES = ['browser_attach_failed'];
 /** Stable outcome categories emitted by `attach(...)`. */
 export const ATTACH_OUTCOME_TYPES = ['blocked'];
 /** Attaches AgentBrowse to an existing browser via a CDP websocket or HTTP endpoint. */
 export async function attach(cdpUrl, options = {}) {
-    let browser = null;
     try {
         const normalizedCdpUrl = await resolveAttachEndpoint(cdpUrl);
         const session = buildAttachedSession({
             cdpUrl: normalizedCdpUrl,
             launchedAt: options.launchedAt ?? new Date().toISOString(),
             ...(options.provider ? { provider: options.provider } : {}),
-            ...(options.capabilities ? { capabilities: options.capabilities } : {}),
             ...(options.transport ? { transport: options.transport } : {}),
         });
-        browser = await connectPlaywright(normalizedCdpUrl);
-        const syncedPage = await syncLaunchPage(session, browser, {
+        await initializeBrowserSessionOwner(session);
+        const syncedPage = await withStickyOwnerBrowser(session, (browser) => syncLaunchPage(session, browser, {
             fallbackUrl: '',
             fallbackTitle: '',
-        });
+        }));
         return {
             success: true,
             runtime: 'attached',
@@ -32,7 +31,6 @@ export async function attach(cdpUrl, options = {}) {
             url: syncedPage.url,
             title: syncedPage.title,
             ...(options.provider ? { provider: options.provider } : {}),
-            captchaSolveCapable: options.capabilities?.captchaSolve === true,
         };
     }
     catch (error) {
@@ -44,11 +42,6 @@ export async function attach(cdpUrl, options = {}) {
             reason: formatUnknownError(error),
         };
     }
-    finally {
-        if (browser) {
-            await disconnectPlaywright(browser);
-        }
-    }
 }
 async function resolveAttachEndpoint(input) {
     const normalized = input.trim();

package/dist/commands/browser-connection-failure.d.ts

@@ -0,0 +1,9 @@
+export declare const STICKY_OWNER_UNRECOVERABLE_REASON = "sticky_owner_unrecoverable";
+export declare function describeBrowserConnectionFailure(error: unknown, options: {
+    defaultMessage: string;
+    unrecoverableSessionMessage: string;
+}): {
+    message: string;
+    reason: string;
+};
+//# sourceMappingURL=browser-connection-failure.d.ts.map

package/dist/commands/browser-connection-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-connection-failure.d.ts","sourceRoot":"","sources":["../../src/commands/browser-connection-failure.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iCAAiC,+BAA+B,CAAC;AAK9E,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IACP,cAAc,EAAE,MAAM,CAAC;IACvB,2BAA2B,EAAE,MAAM,CAAC;CACrC,GACA;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAcrC"}

package/dist/commands/browser-connection-failure.js

@@ -0,0 +1,15 @@
+export const STICKY_OWNER_UNRECOVERABLE_REASON = 'sticky_owner_unrecoverable';
+const STICKY_OWNER_UNRECOVERABLE_PUBLIC_REASON = 'The previous browser session is no longer reachable, so AgentBrowse could not restore control of the browser. Launch or attach a new browser session and try again.';
+export function describeBrowserConnectionFailure(error, options) {
+    const reason = error instanceof Error ? error.message : String(error);
+    if (reason === STICKY_OWNER_UNRECOVERABLE_REASON) {
+        return {
+            message: options.unrecoverableSessionMessage,
+            reason: STICKY_OWNER_UNRECOVERABLE_PUBLIC_REASON,
+        };
+    }
+    return {
+        message: options.defaultMessage,
+        reason,
+    };
+}

package/dist/commands/browser-status.d.ts

@@ -29,13 +29,11 @@ export type BrowserStatusProtectedExposureResult = {
     exposureReason: string;
     message: string;
     reason: string;
-    captchaSolveCapable?: boolean;
 };
 /** Success result when the browser is alive and a current page could be resolved or approximated. */
 export type BrowserStatusAliveResult = {
     success: true;
     alive: true;
-    captchaSolveCapable?: boolean;
     pageRef?: string;
     url?: string;
     title?: string;

package/dist/commands/browser-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-status.d.ts","sourceRoot":"","sources":["../../src/commands/browser-status.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AAoBrC,KAAK,mBAAmB,GAAG;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,QAAQ,GAAG,gBAAgB,CAAC;CAC5C,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,4BAA4B,gFAI/B,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AACrF,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAClE,MAAM,MAAM,gCAAgC,GAAG,mBAAmB,CAAC;AAEnE,uGAAuG;AACvG,MAAM,MAAM,oCAAoC,GAAG;IACjD,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC,wBAAwB,EAAE,2BAA2B,CAAC,CAAC;IAC5E,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,mBAAmB,CAAC,EAAE,gCAAgC,CAAC;IACvD,uBAAuB,EAAE,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,qGAAqG;AACrG,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,mBAAmB,CAAC,EAAE,gCAAgC,CAAC;IACvD,qBAAqB,CAAC,EAAE,IAAI,CAAC;CAC9B,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,qBAAqB,CAAC,EAAE,IAAI,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,oCAAoC,GACpC,wBAAwB,GACxB,6BAA6B,CAAC;AAuLlC,qFAAqF;AACrF,wBAAsB,aAAa,CACjC,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAClC,OAAO,CAAC,mBAAmB,CAAC,CAgG9B"}
+{"version":3,"file":"browser-status.d.ts","sourceRoot":"","sources":["../../src/commands/browser-status.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AAiBrC,KAAK,mBAAmB,GAAG;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,QAAQ,GAAG,gBAAgB,CAAC;CAC5C,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,4BAA4B,gFAI/B,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AACrF,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAClE,MAAM,MAAM,gCAAgC,GAAG,mBAAmB,CAAC;AAEnE,uGAAuG;AACvG,MAAM,MAAM,oCAAoC,GAAG;IACjD,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC,wBAAwB,EAAE,2BAA2B,CAAC,CAAC;IAC5E,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,mBAAmB,CAAC,EAAE,gCAAgC,CAAC;IACvD,uBAAuB,EAAE,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,qGAAqG;AACrG,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,mBAAmB,CAAC,EAAE,gCAAgC,CAAC;IACvD,qBAAqB,CAAC,EAAE,IAAI,CAAC;CAC9B,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,qBAAqB,CAAC,EAAE,IAAI,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,oCAAoC,GACpC,wBAAwB,GACxB,6BAA6B,CAAC;AA+KlC,qFAAqF;AACrF,wBAAsB,aAAa,CACjC,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAClC,OAAO,CAAC,mBAAmB,CAAC,CA6F9B"}

package/dist/commands/browser-status.js

@@ -1,10 +1,11 @@
 /**
  * browse browser-status — Check live browser/page/runtime state.
  */
-import { buildCdpHttpEndpointUrl, getSessionPort, supportsCaptchaSolve, } from '../browser-session-state.js';
-import { connectPlaywright, disconnectPlaywright, resolveCurrentPageContext, } from '../playwright-runtime.js';
+import { buildCdpHttpEndpointUrl, getSessionPort, } from '../browser-session-state.js';
+import { resolveCurrentPageContext } from '../playwright-runtime.js';
 import { captureDiagnosticSnapshotBestEffort, finishDiagnosticStepBestEffort, recordCommandLifecycleEventBestEffort, startDiagnosticStep, } from '../diagnostics.js';
 import { scrubProtectedExactValues } from '../secrets/protected-exact-value-redaction.js';
+import { withStickyOwnerBrowser } from '../sticky-owner.js';
 /** Stable outcome categories exposed by `status(...)`. */
 export const BROWSER_STATUS_OUTCOME_TYPES = [
     'browser_alive',
@@ -38,9 +39,6 @@ function buildProtectedStatusPayload(params) {
         success: true,
         alive: true,
         outcomeType: 'protected_exposure_active',
-        ...(params.captchaSolveCapable !== undefined
-            ? { captchaSolveCapable: params.captchaSolveCapable }
-            : {}),
         runtime: params.runtimeSummary,
         ...(params.currentPageMismatch ? { currentPageMismatch: params.currentPageMismatch } : {}),
         protectedExposureActive: true,
@@ -56,40 +54,35 @@ function buildProtectedStatusPayload(params) {
     };
 }
 async function readCanonicalStatus(session) {
-    let browser = null;
     try {
-        browser = await connectPlaywright(session.cdpUrl);
-        const resolved = await resolveCurrentPageContext(browser, session);
-        const persisted = session.runtime?.currentPageRef;
-        const title = (await resolved.page
-            .title()
-            .catch(() => session.runtime?.pages[resolved.pageRef]?.title ?? '')) ||
-            session.runtime?.pages[resolved.pageRef]?.title ||
-            'unknown';
-        const url = resolved.page.url() || session.runtime?.pages[resolved.pageRef]?.url || 'unknown';
-        return {
-            pageRef: resolved.pageRef,
-            url,
-            title,
-            ...(persisted && (persisted !== resolved.pageRef || resolved.recoveredVia)
-                ? {
-                    currentPageMismatch: {
-                        persistedPageRef: persisted,
-                        ...(persisted !== resolved.pageRef ? { livePageRef: resolved.pageRef } : {}),
-                        ...(resolved.recoveredVia ? { recoveredVia: resolved.recoveredVia } : {}),
-                    },
-                }
-                : {}),
-        };
+        return await withStickyOwnerBrowser(session, async (browser) => {
+            const resolved = await resolveCurrentPageContext(browser, session);
+            const persisted = session.runtime?.currentPageRef;
+            const title = (await resolved.page
+                .title()
+                .catch(() => session.runtime?.pages[resolved.pageRef]?.title ?? '')) ||
+                session.runtime?.pages[resolved.pageRef]?.title ||
+                'unknown';
+            const url = resolved.page.url() || session.runtime?.pages[resolved.pageRef]?.url || 'unknown';
+            return {
+                pageRef: resolved.pageRef,
+                url,
+                title,
+                ...(persisted && (persisted !== resolved.pageRef || resolved.recoveredVia)
+                    ? {
+                        currentPageMismatch: {
+                            persistedPageRef: persisted,
+                            ...(persisted !== resolved.pageRef ? { livePageRef: resolved.pageRef } : {}),
+                            ...(resolved.recoveredVia ? { recoveredVia: resolved.recoveredVia } : {}),
+                        },
+                    }
+                    : {}),
+            };
+        });
     }
     catch {
         return null;
     }
-    finally {
-        if (browser) {
-            await disconnectPlaywright(browser);
-        }
-    }
 }
 function buildStatusEndpointUrl(session, port, resourcePath) {
     if (session) {
@@ -179,7 +172,6 @@ export async function browserStatus(session) {
                     pageRef: canonical.pageRef,
                     pageUrl: canonical.url,
                     pageTitle: canonical.title,
-                    captchaSolveCapable: supportsCaptchaSolve(session),
                     currentPageMismatch: canonical.currentPageMismatch,
                     protectedExposure,
                 });
@@ -190,7 +182,6 @@ export async function browserStatus(session) {
             const result = {
                 success: true,
                 alive: true,
-                captchaSolveCapable: supportsCaptchaSolve(session),
                 pageRef: canonical.pageRef,
                 url: canonical.url,
                 title: canonical.title,
@@ -219,7 +210,6 @@ export async function browserStatus(session) {
         const result = {
             success: true,
             alive: true,
-            ...(session ? { captchaSolveCapable: supportsCaptchaSolve(session) } : {}),
             url: page.url ?? 'unknown',
             title: page.title ?? 'unknown',
             ...(session?.runtime ? { currentPageUnresolved: true } : {}),

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

@@ -1 +1 @@
-{"version":3,"file":"close.d.ts","sourceRoot":"","sources":["../../src/commands/close.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAWvF,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,mCAAoC,CAAC;AAEnE,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,gEAAiE,CAAC;AAElG,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,uCAAuC;AACvC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,IAAI,CAAC;CACf,CAAC;AAEF,mCAAmC;AACnC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;IAClD,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAsClE,sFAAsF;AACtF,wBAAsB,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAsErF"}
+{"version":3,"file":"close.d.ts","sourceRoot":"","sources":["../../src/commands/close.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAYvF,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,mCAAoC,CAAC;AAEnE,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,gEAAiE,CAAC;AAElG,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,uCAAuC;AACvC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,IAAI,CAAC;CACf,CAAC;AAEF,mCAAmC;AACnC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;IAClD,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAsClE,sFAAsF;AACtF,wBAAsB,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAyErF"}

package/dist/commands/close.js

@@ -6,6 +6,7 @@ import { captureDiagnosticSnapshotBestEffort, finishDiagnosticStepBestEffort, re
 import { info } from '../output.js';
 import { closeOwnedBrowser } from '../owned-browser.js';
 import { isManagedBrowserPid } from '../owned-process.js';
+import { terminateBrowserSessionOwner } from '../sticky-owner.js';
 /** Stable top-level error codes returned by `close(...)`. */
 export const CLOSE_ERROR_CODES = ['browser_close_failed'];
 /** Stable outcome categories emitted by `close(...)`. */
@@ -64,6 +65,7 @@ export async function close(session) {
         },
     });
     if (isCloseableManagedSession(session)) {
+        await terminateBrowserSessionOwner(session);
         const closeResult = await closeOwnedBrowser(session);
         if (!closeResult.success) {
             recordCommandLifecycleEventBestEffort({
@@ -90,6 +92,9 @@ export async function close(session) {
             };
         }
     }
+    else if (session?.stickyOwner) {
+        await terminateBrowserSessionOwner(session);
+    }
     recordCommandLifecycleEventBestEffort({
         step: closeStep,
         phase: 'completed',

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;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAUzE,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAsBtB,KAAK,sBAAsB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAC1B,sBAAsB,GACtB,uBAAuB,GACvB,kBAAkB,EAAE,CAAC;AAEzB,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAAC;CACnC;AAED,4DAA4D;AAC5D,MAAM,MAAM,kBAAkB,GAAG,uBAAuB,GAAG,CAAC,CAAC,UAAU,CAAC;AAExE,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,8MAStB,CAAC;AAEX,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,8EAKxB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,+CAA+C;AAC/C,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG;IAChD,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAC3B,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC,kBAAkB,EAAE,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC,CAAC;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,oBAAoB,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,GAAG,qBAAqB,CAAC;AAE9E,MAAM,MAAM,aAAa,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAibxE;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,EAC9B,WAAW,EAAE,kBAAkB,EAC/B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CA8RxB;AAED,sFAAsF;AACtF,wBAAsB,OAAO,CAC3B,OAAO,EAAE,qBAAqB,EAC9B,WAAW,EAAE,MAAM,GAAG,kBAAkB,EACxC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAgCf"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/commands/extract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAUzE,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAsBtB,KAAK,sBAAsB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAC1B,sBAAsB,GACtB,uBAAuB,GACvB,kBAAkB,EAAE,CAAC;AAEzB,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAAC;CACnC;AAED,4DAA4D;AAC5D,MAAM,MAAM,kBAAkB,GAAG,uBAAuB,GAAG,CAAC,CAAC,UAAU,CAAC;AAExE,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,8MAStB,CAAC;AAEX,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,8EAKxB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,+CAA+C;AAC/C,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG;IAChD,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAC3B,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC,kBAAkB,EAAE,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC,CAAC;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,oBAAoB,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,GAAG,qBAAqB,CAAC;AAE9E,MAAM,MAAM,aAAa,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAibxE;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,EAC9B,WAAW,EAAE,kBAAkB,EAC/B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CAgSxB;AAED,sFAAsF;AACtF,wBAAsB,OAAO,CAC3B,OAAO,EAAE,qBAAqB,EAC9B,WAAW,EAAE,MAAM,GAAG,kBAAkB,EACxC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/commands/extract.js

@@ -8,12 +8,14 @@ import { getSurface, getTarget, markSurfaceLifecycle, markTargetLifecycle, } fro
 import { getPageScopeEpoch, setCurrentPage } from '../runtime-page-state.js';
 import { outputContractFailure, outputJSON, } from '../output.js';
 import { captureDiagnosticSnapshotBestEffort, finishDiagnosticStepBestEffort, recordCommandLifecycleEventBestEffort, startDiagnosticStep, } from '../diagnostics.js';
-import { connectPlaywright, disconnectPlaywright, resolveCurrentPageContext, resolvePageByRef as resolvePlaywrightPageByRef, syncSessionPage, } from '../playwright-runtime.js';
+import { resolveCurrentPageContext, resolvePageByRef as resolvePlaywrightPageByRef, syncSessionPage, } from '../playwright-runtime.js';
 import { withApiTraceContext } from '../command-api-tracing.js';
 import { normalizePageSignature } from './descriptor-validation.js';
 import { readScopedDialogText } from './extract-scoped-dialog-text.js';
 import { resolveScopedExtractContext } from './extract-scope-resolution.js';
 import { executeStagehandExtract } from './extract-stagehand-executor.js';
+import { describeBrowserConnectionFailure } from './browser-connection-failure.js';
+import { withStickyOwnerBrowser } from '../sticky-owner.js';
 /** Stable top-level error codes returned by `extract(...)`. */
 export const EXTRACT_ERROR_CODES = [
     'browser_connection_failed',
@@ -459,180 +461,181 @@ export async function extractBrowser(session, schemaInput, scopeRef) {
                 scopeRef,
             });
         }
-        let browser = null;
         let failureMessage = null;
         let cleanupScopedExtract = null;
         let staleScope = false;
         let staleReason = null;
         try {
-            browser = await connectPlaywright(session.cdpUrl);
-        }
-        catch (err) {
-            return buildExtractContractFailureResult(session, {
-                step: extractStep,
-                error: 'browser_connection_failed',
-                outcomeType: 'blocked',
-                message: 'Extraction could not start because AgentBrowse failed to connect to the browser.',
-                reason: err instanceof Error ? err.message : String(err),
-                scopeRef,
-                pageRef,
-            });
-        }
-        try {
-            let sourcePage;
-            if (scopeTarget) {
-                sourcePage = await resolvePlaywrightPageByRef(browser, session, pageRef);
-            }
-            else {
-                const resolvedPage = await resolveCurrentPageContext(browser, session);
-                pageRef = resolvedPage.pageRef;
-                sourcePage = resolvedPage.page;
-            }
-            let page = sourcePage;
-            let scopedResolution = null;
-            const { url, title } = await syncSessionPage(session, pageRef, sourcePage);
-            if (scopeTarget?.pageSignature &&
-                normalizePageSignature(url) !== scopeTarget.pageSignature) {
-                staleScope = true;
-                staleReason = 'page-signature-mismatch';
-                throw new Error('stale_scope_target_page_signature_changed');
-            }
-            let effectiveSelector;
-            if (scopeTarget) {
+            return await withStickyOwnerBrowser(session, async (browser) => {
                 try {
-                    scopedResolution = await resolveScopedExtractContext({
-                        page: sourcePage,
-                        scopeTarget,
-                        validateDomSignature: Boolean(targetScope),
+                    let sourcePage;
+                    if (scopeTarget) {
+                        sourcePage = await resolvePlaywrightPageByRef(browser, session, pageRef);
+                    }
+                    else {
+                        const resolvedPage = await resolveCurrentPageContext(browser, session);
+                        pageRef = resolvedPage.pageRef;
+                        sourcePage = resolvedPage.page;
+                    }
+                    let page = sourcePage;
+                    let scopedResolution = null;
+                    const { url, title } = await syncSessionPage(session, pageRef, sourcePage);
+                    if (scopeTarget?.pageSignature &&
+                        normalizePageSignature(url) !== scopeTarget.pageSignature) {
+                        staleScope = true;
+                        staleReason = 'page-signature-mismatch';
+                        throw new Error('stale_scope_target_page_signature_changed');
+                    }
+                    let effectiveSelector;
+                    if (scopeTarget) {
+                        try {
+                            scopedResolution = await resolveScopedExtractContext({
+                                page: sourcePage,
+                                scopeTarget,
+                                validateDomSignature: Boolean(targetScope),
+                            });
+                            cleanupScopedExtract = scopedResolution.cleanup;
+                            page = scopedResolution.page;
+                            effectiveSelector = scopedResolution.selector;
+                        }
+                        catch (error) {
+                            if (error instanceof Error &&
+                                error.message === 'stale_scope_target_dom_signature_changed') {
+                                staleScope = true;
+                                staleReason = 'dom-signature-mismatch';
+                            }
+                            else if (surfaceScope &&
+                                surfaceExtractScopeLifetime(surfaceScope) === 'snapshot' &&
+                                error instanceof Error &&
+                                error.message === 'scope_target_unresolvable') {
+                                return buildExtractContractFailureResult(session, {
+                                    step: extractStep,
+                                    error: 'expired_extract_scope',
+                                    outcomeType: 'binding_stale',
+                                    message: 'Extraction failed because the requested snapshot scope expired before it could be rebound.',
+                                    reason: `Snapshot scope ${scopeRef} is no longer present in the current visible page state.`,
+                                    scopeRef,
+                                    pageRef,
+                                    staleScope: true,
+                                    staleReason: 'snapshot-scope-expired',
+                                });
+                            }
+                            throw error;
+                        }
+                    }
+                    setCurrentPage(session, pageRef);
+                    const execution = await executeStagehandExtract({
+                        session,
+                        instruction,
+                        schema: normalizedSchema.schema,
+                        page,
+                        selector: effectiveSelector,
+                        degradationReason: scopedResolution?.degraded
+                            ? scopedResolution.degradationReason
+                            : undefined,
+                    });
+                    let data = execution.data;
+                    if (scopeTarget &&
+                        effectiveSelector &&
+                        normalizedSchema.requestsScopedDialogText &&
+                        data &&
+                        typeof data === 'object' &&
+                        !Array.isArray(data)) {
+                        const dialogText = await readScopedDialogText(page, effectiveSelector);
+                        if (typeof dialogText === 'string' && dialogText.trim().length > 0) {
+                            data = {
+                                ...data,
+                                dialog_text: dialogText,
+                            };
+                        }
+                    }
+                    return buildExtractSuccessResult(session, extractStep, {
+                        success: true,
+                        ...execution,
+                        data,
+                        pageRef,
+                        scopeRef,
+                        metrics: session.runtime?.metrics,
+                        url,
+                        title,
                     });
-                    cleanupScopedExtract = scopedResolution.cleanup;
-                    page = scopedResolution.page;
-                    effectiveSelector = scopedResolution.selector;
                 }
-                catch (error) {
-                    if (error instanceof Error &&
-                        error.message === 'stale_scope_target_dom_signature_changed') {
-                        staleScope = true;
-                        staleReason = 'dom-signature-mismatch';
+                catch (err) {
+                    if (staleScope && scopeRef) {
+                        if (targetScope) {
+                            markTargetLifecycle(session, scopeRef, 'stale', staleReason ?? 'unknown');
+                        }
+                        else if (surfaceScope) {
+                            markSurfaceLifecycle(session, scopeRef, 'stale', staleReason ?? 'unknown');
+                        }
                     }
-                    else if (surfaceScope &&
-                        surfaceExtractScopeLifetime(surfaceScope) === 'snapshot' &&
-                        error instanceof Error &&
-                        error.message === 'scope_target_unresolvable') {
+                    if (!staleScope && err instanceof AssistiveStructuredOutputTruncatedError) {
                         return buildExtractContractFailureResult(session, {
                             step: extractStep,
-                            error: 'expired_extract_scope',
-                            outcomeType: 'binding_stale',
-                            message: 'Extraction failed because the requested snapshot scope expired before it could be rebound.',
-                            reason: `Snapshot scope ${scopeRef} is no longer present in the current visible page state.`,
+                            error: 'extract_output_truncated',
+                            outcomeType: 'blocked',
+                            message: 'Extraction failed because the provider truncated structured output.',
+                            reason: buildTruncationReason(err),
                             scopeRef,
                             pageRef,
-                            staleScope: true,
-                            staleReason: 'snapshot-scope-expired',
+                            staleScope: false,
+                            provider: err.provider,
+                            model: err.model,
+                            finishReason: err.finishReason,
+                            maxOutputTokens: err.maxOutputTokens,
+                            completionTokens: err.completionTokens,
                         });
                     }
-                    throw error;
-                }
-            }
-            setCurrentPage(session, pageRef);
-            const execution = await executeStagehandExtract({
-                session,
-                instruction,
-                schema: normalizedSchema.schema,
-                page,
-                selector: effectiveSelector,
-                degradationReason: scopedResolution?.degraded
-                    ? scopedResolution.degradationReason
-                    : undefined,
-            });
-            let data = execution.data;
-            if (scopeTarget &&
-                effectiveSelector &&
-                normalizedSchema.requestsScopedDialogText &&
-                data &&
-                typeof data === 'object' &&
-                !Array.isArray(data)) {
-                const dialogText = await readScopedDialogText(page, effectiveSelector);
-                if (typeof dialogText === 'string' && dialogText.trim().length > 0) {
-                    data = {
-                        ...data,
-                        dialog_text: dialogText,
-                    };
+                    failureMessage = `Extract failed: ${err instanceof Error ? err.message : String(err)}`;
                 }
-            }
-            return buildExtractSuccessResult(session, extractStep, {
-                success: true,
-                ...execution,
-                data,
-                pageRef,
-                scopeRef,
-                metrics: session.runtime?.metrics,
-                url,
-                title,
-            });
-        }
-        catch (err) {
-            if (staleScope && scopeRef) {
-                if (targetScope) {
-                    markTargetLifecycle(session, scopeRef, 'stale', staleReason ?? 'unknown');
+                finally {
+                    if (cleanupScopedExtract) {
+                        await cleanupScopedExtract().catch(() => undefined);
+                    }
                 }
-                else if (surfaceScope) {
-                    markSurfaceLifecycle(session, scopeRef, 'stale', staleReason ?? 'unknown');
+                if (failureMessage) {
+                    return buildExtractContractFailureResult(session, {
+                        step: extractStep,
+                        error: staleScope ? 'stale_extract_scope' : 'extract_failed',
+                        outcomeType: staleScope ? 'binding_stale' : 'blocked',
+                        message: staleScope
+                            ? 'Extraction failed because the requested scope became stale.'
+                            : 'Extraction failed.',
+                        reason: staleScope && scopeRef
+                            ? `${failureMessage} (${scopeRef} marked stale: ${staleReason ?? 'stale'})`
+                            : failureMessage.replace(/^Extract failed:\s*/, ''),
+                        scopeRef,
+                        pageRef,
+                        staleScope,
+                        staleReason: staleReason ?? undefined,
+                    });
                 }
-            }
-            if (!staleScope && err instanceof AssistiveStructuredOutputTruncatedError) {
                 return buildExtractContractFailureResult(session, {
                     step: extractStep,
-                    error: 'extract_output_truncated',
+                    error: 'extract_failed',
                     outcomeType: 'blocked',
-                    message: 'Extraction failed because the provider truncated structured output.',
-                    reason: buildTruncationReason(err),
+                    message: 'Extraction failed.',
+                    reason: 'Extraction did not produce a success or failure result.',
                     scopeRef,
                     pageRef,
-                    staleScope: false,
-                    provider: err.provider,
-                    model: err.model,
-                    finishReason: err.finishReason,
-                    maxOutputTokens: err.maxOutputTokens,
-                    completionTokens: err.completionTokens,
                 });
-            }
-            failureMessage = `Extract failed: ${err instanceof Error ? err.message : String(err)}`;
-        }
-        finally {
-            if (cleanupScopedExtract) {
-                await cleanupScopedExtract().catch(() => undefined);
-            }
-            if (browser) {
-                await disconnectPlaywright(browser);
-            }
+            });
         }
-        if (failureMessage) {
+        catch (err) {
+            const browserConnectionFailure = describeBrowserConnectionFailure(err, {
+                defaultMessage: 'Extraction could not start because AgentBrowse failed to connect to the browser.',
+                unrecoverableSessionMessage: 'Extraction could not start because the previous browser session is no longer reachable.',
+            });
             return buildExtractContractFailureResult(session, {
                 step: extractStep,
-                error: staleScope ? 'stale_extract_scope' : 'extract_failed',
-                outcomeType: staleScope ? 'binding_stale' : 'blocked',
-                message: staleScope
-                    ? 'Extraction failed because the requested scope became stale.'
-                    : 'Extraction failed.',
-                reason: staleScope && scopeRef
-                    ? `${failureMessage} (${scopeRef} marked stale: ${staleReason ?? 'stale'})`
-                    : failureMessage.replace(/^Extract failed:\s*/, ''),
+                error: 'browser_connection_failed',
+                outcomeType: 'blocked',
+                message: browserConnectionFailure.message,
+                reason: browserConnectionFailure.reason,
                 scopeRef,
                 pageRef,
-                staleScope,
-                staleReason: staleReason ?? undefined,
             });
         }
-        return buildExtractContractFailureResult(session, {
-            step: extractStep,
-            error: 'extract_failed',
-            outcomeType: 'blocked',
-            message: 'Extraction failed.',
-            reason: 'Extraction did not produce a success or failure result.',
-            scopeRef,
-            pageRef,
-        });
     });
 }
 /** CLI wrapper for `extractBrowser(...)` that accepts JSON text or schema objects. */