@nuanu-ai/agentbrowse 0.2.47 → 0.2.49

package/dist/commands/extract.js

@@ -4,9 +4,14 @@
 import { z } from 'zod';
 import { AgentpayStructuredOutputTruncatedError } from '../agentpay-stagehand-llm.js';
 import { saveSession } from '../session.js';
-import { getPageScopeEpoch, getSurface, getTarget, markSurfaceLifecycle, markTargetLifecycle, setCurrentPage, } from '../runtime-state.js';
+import { getSurface, getTarget, markSurfaceLifecycle, markTargetLifecycle, } from '../runtime-state.js';
+import { getPageScopeEpoch, setCurrentPage } from '../runtime-page-state.js';
 import { outputContractFailure, outputJSON } from '../output.js';
 import { connectPlaywright, disconnectPlaywright, resolveCurrentPageContext, resolvePageByRef as resolvePlaywrightPageByRef, syncSessionPage, } from '../playwright-runtime.js';
+import { withApiTraceContext } from '../command-api-tracing.js';
+import { finishRunStep, startRunStep } from '../run-store.js';
+import { appendCommandLifecycleEventBestEffort, captureStepSnapshotBestEffort, } from '../run-observability.js';
+import { exportRunStepToOtlpHttpJsonBestEffort } from '../otel-exporter.js';
 import { normalizePageSignature } from './descriptor-validation.js';
 import { readScopedDialogText } from './extract-scoped-dialog-text.js';
 import { resolveScopedExtractContext } from './extract-scope-resolution.js';
@@ -177,230 +182,362 @@ function buildTruncationReason(error) {
 function schemaRequestsScopedDialogText(schemaDescriptor) {
     return schemaDescriptor.dialog_text === 'string';
 }
-export async function extract(session, schemaJson, scopeRef) {
-    let schemaDescriptor;
-    try {
-        schemaDescriptor = JSON.parse(schemaJson);
-    }
-    catch {
-        return outputContractFailure({
-            error: 'invalid_extract_schema',
-            outcomeType: 'blocked',
-            message: 'Extraction could not start because the schema JSON is invalid.',
-            reason: 'The provided schema argument is not valid JSON.',
-        });
+function finalizeExtractStepBestEffort(runId, stepId, options) {
+    if (!runId || !stepId) {
+        return;
     }
-    const schema = buildSchema(schemaDescriptor);
-    const instruction = buildInstruction(schemaDescriptor, scopeRef);
-    const targetScope = scopeRef ? getTarget(session, scopeRef) : null;
-    const surfaceScope = !targetScope && scopeRef ? getSurface(session, scopeRef) : null;
-    const scopeTarget = targetScope ?? surfaceScope;
-    let pageRef = scopeTarget?.pageRef ?? session.runtime?.currentPageRef ?? 'p0';
-    if (scopeRef && !scopeTarget) {
-        return outputContractFailure({
-            error: 'unknown_scope_ref',
-            outcomeType: 'blocked',
-            message: 'Extraction could not start because the requested scopeRef is unknown.',
-            reason: `No live scope target matches scopeRef ${scopeRef}.`,
-            scopeRef,
+    try {
+        finishRunStep({
+            runId,
+            stepId,
+            ...options,
         });
     }
-    if (scopeTarget && scopeTarget.lifecycle !== 'live') {
-        return outputContractFailure({
-            error: 'stale_extract_scope',
-            outcomeType: 'binding_stale',
-            message: 'Extraction could not start because the requested scope is no longer live.',
-            reason: `Scope ${scopeRef} is ${scopeTarget.lifecycle}${scopeTarget.lifecycleReason ? ` because ${scopeTarget.lifecycleReason}` : ''}.`,
-            scopeRef,
-        });
+    catch {
     }
-    if (surfaceScope) {
-        const snapshotScopeReason = snapshotScopeUnavailableReason(session, surfaceScope);
-        if (snapshotScopeReason) {
-            return outputContractFailure({
-                error: 'expired_extract_scope',
+}
+async function emitExtractSuccess(session, runId, stepId, payload) {
+    const step = runId && stepId ? { runId, stepId, command: 'extract' } : null;
+    captureStepSnapshotBestEffort({
+        session,
+        step,
+        phase: 'after',
+        pageRef: typeof payload.pageRef === 'string' ? payload.pageRef : session.runtime?.currentPageRef,
+        url: typeof payload.url === 'string' ? payload.url : undefined,
+        title: typeof payload.title === 'string' ? payload.title : undefined,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step,
+        phase: 'completed',
+        attributes: {
+            outcomeType: 'extraction_completed',
+            pageRef: typeof payload.pageRef === 'string' ? payload.pageRef : undefined,
+            scopeRef: typeof payload.scopeRef === 'string' ? payload.scopeRef : undefined,
+        },
+    });
+    finalizeExtractStepBestEffort(runId, stepId, {
+        success: true,
+        outcomeType: 'extraction_completed',
+        message: 'Extraction completed.',
+    });
+    await exportRunStepToOtlpHttpJsonBestEffort(runId, stepId);
+    return outputJSON(payload);
+}
+async function emitExtractContractFailure(session, params) {
+    const step = params.runId && params.stepId
+        ? { runId: params.runId, stepId: params.stepId, command: 'extract' }
+        : null;
+    captureStepSnapshotBestEffort({
+        session,
+        step,
+        phase: 'point-in-time',
+        pageRef: typeof params.pageRef === 'string' ? params.pageRef : session.runtime?.currentPageRef,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step,
+        phase: 'failed',
+        attributes: {
+            outcomeType: params.outcomeType,
+            pageRef: typeof params.pageRef === 'string' ? params.pageRef : undefined,
+            scopeRef: typeof params.scopeRef === 'string' ? params.scopeRef : undefined,
+            staleScope: params.staleScope === true,
+            reason: params.reason,
+        },
+    });
+    finalizeExtractStepBestEffort(params.runId, params.stepId, {
+        success: false,
+        outcomeType: params.outcomeType,
+        message: params.message,
+        reason: params.reason,
+    });
+    await exportRunStepToOtlpHttpJsonBestEffort(params.runId, params.stepId);
+    const { runId: _runId, stepId: _stepId, ...result } = params;
+    return outputContractFailure(result);
+}
+export async function extract(session, schemaJson, scopeRef) {
+    const initialPageRef = session.runtime?.currentPageRef ?? 'p0';
+    const extractStep = session.activeRunId
+        ? startRunStep({
+            runId: session.activeRunId,
+            command: 'extract',
+            input: {
+                schemaJson,
+                ...(scopeRef ? { scopeRef } : {}),
+            },
+            refs: {
+                pageRef: initialPageRef,
+            },
+        })
+        : null;
+    const extractStepHandle = session.activeRunId && extractStep?.stepId
+        ? {
+            runId: session.activeRunId,
+            stepId: extractStep.stepId,
+            command: 'extract',
+        }
+        : null;
+    captureStepSnapshotBestEffort({
+        session,
+        step: extractStepHandle,
+        phase: 'before',
+        pageRef: initialPageRef,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step: extractStepHandle,
+        phase: 'started',
+        attributes: {
+            schemaJson,
+            pageRef: initialPageRef,
+            ...(scopeRef ? { scopeRef } : {}),
+        },
+    });
+    return withApiTraceContext({
+        runId: session.activeRunId,
+        stepId: extractStep?.stepId,
+        command: 'extract',
+    }, async () => {
+        let schemaDescriptor;
+        try {
+            schemaDescriptor = JSON.parse(schemaJson);
+        }
+        catch {
+            return emitExtractContractFailure(session, {
+                error: 'invalid_extract_schema',
+                outcomeType: 'blocked',
+                message: 'Extraction could not start because the schema JSON is invalid.',
+                reason: 'The provided schema argument is not valid JSON.',
+                runId: session.activeRunId,
+                stepId: extractStep?.stepId,
+            });
+        }
+        const schema = buildSchema(schemaDescriptor);
+        const instruction = buildInstruction(schemaDescriptor, scopeRef);
+        const targetScope = scopeRef ? getTarget(session, scopeRef) : null;
+        const surfaceScope = !targetScope && scopeRef ? getSurface(session, scopeRef) : null;
+        const scopeTarget = targetScope ?? surfaceScope;
+        let pageRef = scopeTarget?.pageRef ?? session.runtime?.currentPageRef ?? 'p0';
+        if (scopeRef && !scopeTarget) {
+            return emitExtractContractFailure(session, {
+                error: 'unknown_scope_ref',
+                outcomeType: 'blocked',
+                message: 'Extraction could not start because the requested scopeRef is unknown.',
+                reason: `No live scope target matches scopeRef ${scopeRef}.`,
+                scopeRef,
+                runId: session.activeRunId,
+                stepId: extractStep?.stepId,
+            });
+        }
+        if (scopeTarget && scopeTarget.lifecycle !== 'live') {
+            return emitExtractContractFailure(session, {
+                error: 'stale_extract_scope',
                 outcomeType: 'binding_stale',
-                message: 'Extraction could not start because the requested snapshot scope is no longer current.',
-                reason: snapshotScopeReason,
+                message: 'Extraction could not start because the requested scope is no longer live.',
+                reason: `Scope ${scopeRef} is ${scopeTarget.lifecycle}${scopeTarget.lifecycleReason ? ` because ${scopeTarget.lifecycleReason}` : ''}.`,
                 scopeRef,
-                pageRef,
-                staleScope: true,
-                staleReason: 'snapshot-scope-expired',
+                runId: session.activeRunId,
+                stepId: extractStep?.stepId,
             });
         }
-    }
-    if (targetScope && !canUseTargetAsExtractScope(targetScope)) {
-        return outputContractFailure({
-            error: 'invalid_extract_scope',
-            outcomeType: 'unsupported',
-            message: 'Extraction cannot use the requested target as a scope.',
-            reason: `Target ${scopeRef} is a leaf control, not an extractable scope container.`,
-            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 outputContractFailure({
-            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);
+        if (surfaceScope) {
+            const snapshotScopeReason = snapshotScopeUnavailableReason(session, surfaceScope);
+            if (snapshotScopeReason) {
+                return emitExtractContractFailure(session, {
+                    error: 'expired_extract_scope',
+                    outcomeType: 'binding_stale',
+                    message: 'Extraction could not start because the requested snapshot scope is no longer current.',
+                    reason: snapshotScopeReason,
+                    scopeRef,
+                    pageRef,
+                    staleScope: true,
+                    staleReason: 'snapshot-scope-expired',
+                    runId: session.activeRunId,
+                    stepId: extractStep?.stepId,
+                });
+            }
         }
-        else {
-            const resolvedPage = await resolveCurrentPageContext(browser, session);
-            pageRef = resolvedPage.pageRef;
-            sourcePage = resolvedPage.page;
+        if (targetScope && !canUseTargetAsExtractScope(targetScope)) {
+            return emitExtractContractFailure(session, {
+                error: 'invalid_extract_scope',
+                outcomeType: 'unsupported',
+                message: 'Extraction cannot use the requested target as a scope.',
+                reason: `Target ${scopeRef} is a leaf control, not an extractable scope container.`,
+                scopeRef,
+                runId: session.activeRunId,
+                stepId: extractStep?.stepId,
+            });
         }
-        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 browser = null;
+        let failureMessage = null;
+        let cleanupScopedExtract = null;
+        let staleScope = false;
+        let staleReason = null;
+        try {
+            browser = await connectPlaywright(session.cdpUrl);
         }
-        let effectiveSelector;
-        if (scopeTarget) {
-            try {
-                scopedResolution = await resolveScopedExtractContext({
-                    page: sourcePage,
-                    scopeTarget,
-                    validateDomSignature: Boolean(targetScope),
-                });
-                cleanupScopedExtract = scopedResolution.cleanup;
-                page = scopedResolution.page;
-                effectiveSelector = scopedResolution.selector;
+        catch (err) {
+            return emitExtractContractFailure(session, {
+                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,
+                runId: session.activeRunId,
+                stepId: extractStep?.stepId,
+            });
+        }
+        try {
+            let sourcePage;
+            if (scopeTarget) {
+                sourcePage = await resolvePlaywrightPageByRef(browser, session, pageRef);
             }
-            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') {
-                    outputContractFailure({
-                        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',
+            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 emitExtractContractFailure(session, {
+                            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',
+                            runId: session.activeRunId,
+                            stepId: extractStep?.stepId,
+                        });
+                    }
+                    throw error;
                 }
-                throw error;
             }
-        }
-        setCurrentPage(session, pageRef);
-        const execution = await executeStagehandExtract({
-            session,
-            instruction,
-            schema,
-            page,
-            selector: effectiveSelector,
-            degradationReason: scopedResolution?.degraded
-                ? scopedResolution.degradationReason
-                : undefined,
-        });
-        let data = execution.data;
-        if (scopeTarget &&
-            effectiveSelector &&
-            schemaRequestsScopedDialogText(schemaDescriptor) &&
-            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,
-                };
+            setCurrentPage(session, pageRef);
+            const execution = await executeStagehandExtract({
+                session,
+                instruction,
+                schema,
+                page,
+                selector: effectiveSelector,
+                degradationReason: scopedResolution?.degraded
+                    ? scopedResolution.degradationReason
+                    : undefined,
+            });
+            let data = execution.data;
+            if (scopeTarget &&
+                effectiveSelector &&
+                schemaRequestsScopedDialogText(schemaDescriptor) &&
+                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,
+                    };
+                }
             }
+            saveSession(session);
+            return emitExtractSuccess(session, session.activeRunId, extractStep?.stepId, {
+                success: true,
+                ...execution,
+                data,
+                pageRef,
+                scopeRef,
+                metrics: session.runtime?.metrics,
+                url,
+                title,
+            });
         }
-        saveSession(session);
-        outputJSON({
-            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');
+        catch (err) {
+            if (staleScope && scopeRef) {
+                if (targetScope) {
+                    markTargetLifecycle(session, scopeRef, 'stale', staleReason ?? 'unknown');
+                }
+                else if (surfaceScope) {
+                    markSurfaceLifecycle(session, scopeRef, 'stale', staleReason ?? 'unknown');
+                }
+                saveSession(session);
             }
-            else if (surfaceScope) {
-                markSurfaceLifecycle(session, scopeRef, 'stale', staleReason ?? 'unknown');
+            if (err instanceof Error && err.message.startsWith('outputContractFailure:')) {
+                throw err;
             }
-            saveSession(session);
+            if (!staleScope && err instanceof AgentpayStructuredOutputTruncatedError) {
+                return emitExtractContractFailure(session, {
+                    error: 'extract_output_truncated',
+                    outcomeType: 'blocked',
+                    message: 'Extraction failed because the provider truncated structured output.',
+                    reason: buildTruncationReason(err),
+                    scopeRef,
+                    pageRef,
+                    staleScope: false,
+                    provider: err.provider,
+                    model: err.model,
+                    finishReason: err.finishReason,
+                    maxOutputTokens: err.maxOutputTokens,
+                    completionTokens: err.completionTokens,
+                    runId: session.activeRunId,
+                    stepId: extractStep?.stepId,
+                });
+            }
+            failureMessage = `Extract failed: ${err instanceof Error ? err.message : String(err)}`;
         }
-        if (err instanceof Error && err.message.startsWith('outputContractFailure:')) {
-            throw err;
+        finally {
+            if (cleanupScopedExtract) {
+                await cleanupScopedExtract().catch(() => undefined);
+            }
+            if (browser) {
+                await disconnectPlaywright(browser);
+            }
         }
-        if (!staleScope && err instanceof AgentpayStructuredOutputTruncatedError) {
-            outputContractFailure({
-                error: 'extract_output_truncated',
-                outcomeType: 'blocked',
-                message: 'Extraction failed because the provider truncated structured output.',
-                reason: buildTruncationReason(err),
+        if (failureMessage) {
+            return emitExtractContractFailure(session, {
+                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: false,
-                provider: err.provider,
-                model: err.model,
-                finishReason: err.finishReason,
-                maxOutputTokens: err.maxOutputTokens,
-                completionTokens: err.completionTokens,
+                staleScope,
+                staleReason: staleReason ?? undefined,
+                runId: session.activeRunId,
+                stepId: extractStep?.stepId,
             });
         }
-        failureMessage = `Extract failed: ${err instanceof Error ? err.message : String(err)}`;
-    }
-    finally {
-        if (cleanupScopedExtract) {
-            await cleanupScopedExtract().catch(() => undefined);
-        }
-        if (browser) {
-            disconnectPlaywright(browser);
-        }
-    }
-    if (failureMessage) {
-        outputContractFailure({
-            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,
-        });
-    }
+    });
 }

package/dist/commands/fill-secret.d.ts

@@ -1,7 +1,7 @@
 /**
- * browse fill-secret <fillRef> <intentId> — Fill protected fields from a cached one-time secret payload
- * using the persisted plan and deterministic browser execution.
+ * browse fill-secret <fillRef> <requestId> — Claim an already approved secret request and fill
+ * protected fields using deterministic browser execution.
  */
 import type { BrowseSession } from '../session.js';
-export declare function fillSecret(session: BrowseSession, fillRef: string, intentId: string): Promise<void>;
+export declare function fillSecret(session: BrowseSession, fillRef: string, requestId: string): Promise<void>;
 //# sourceMappingURL=fill-secret.d.ts.map

package/dist/commands/fill-secret.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fill-secret.d.ts","sourceRoot":"","sources":["../../src/commands/fill-secret.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AA8InD,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAmUf"}
+{"version":3,"file":"fill-secret.d.ts","sourceRoot":"","sources":["../../src/commands/fill-secret.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAkRnD,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAggBf"}