@nuanu-ai/agentbrowse 0.2.47 → 0.2.49

package/dist/commands/observe.js

@@ -2,23 +2,101 @@
  * browse observe ["<instruction>"] — Discover available actions on the page.
  */
 import { saveSession } from '../session.js';
-import { bumpPageScopeEpoch, ensureRuntimeState, incrementMetric, replaceTargetsForPage, setCurrentPage, } from '../runtime-state.js';
+import { ensureRuntimeState, replaceTargetsForPage } from '../runtime-state.js';
+import { incrementMetric } from '../runtime-metrics.js';
+import { bumpPageScopeEpoch, setCurrentPage } from '../runtime-page-state.js';
 import { connectPlaywright, disconnectPlaywright, resolveCurrentPageContext, syncSessionPage, } from '../playwright-runtime.js';
+import { tracedStepOperation, withApiTraceContext } from '../command-api-tracing.js';
 import { outputContractFailure, outputJSON } from '../output.js';
+import { appendCommandLifecycleEventBestEffort, captureStepSnapshotBestEffort, } from '../run-observability.js';
+import { exportRunStepToOtlpHttpJsonBestEffort } from '../otel-exporter.js';
 import { domRuntimeResolution, stagehandRuntimeResolution } from '../runtime-resolution.js';
+import { finishRunStep, startRunStep } from '../run-store.js';
 import { withStagehand } from '../stagehand-runtime.js';
 import { normalizePageSignature } from './descriptor-validation.js';
 import { collectDomTargets, __testDomTargetCollection as inventoryDomTargetCollection, __testStagehandDescriptor as inventoryStagehandDescriptor, } from './observe-inventory.js';
 import { enrichDomTargetsWithAccessibility } from './observe-accessibility.js';
 import { collectPageSignals } from './observe-signals.js';
 import { attachObservedTargetOwners, linkObservedSurfaceGraph, reconcileObservedTargetsForPage, persistObservedSurfacesForPage, toDomDescriptor, } from './observe-persistence.js';
-import { clearProtectedFillableFormsForPage, persistProtectedFillableFormsForPage, } from './observe-protected.js';
+import { clearProtectedFillableFormsForPage, markProtectedFillableFormsUnknownForPage, persistProtectedFillableFormsForPage, } from './observe-protected.js';
 import { classifyObservePageState, shouldSuppressFillableFormsForObserve, } from './observe-page-state.js';
 import { annotateDomTargets, compressSemanticallyDuplicateTargets, orderBySurfaceCompetition, prioritizeGoalActionTargets, } from './observe-semantics.js';
 import { buildGroupedObserveScopes, buildGoalProjectionScopeRefs, buildGoalObserveInventoryCandidates, compactFillableForms, compactSignals, expandWorkflowGraphTargets, projectPersistedTargetsForGoal, selectTargetsForGoalMatches, } from './observe-projection.js';
 import { collectSurfaceDescriptors, selectScopesForOutput } from './observe-surfaces.js';
 import { toStagehandDescriptor } from './observe-stagehand.js';
 import { rerankDomTargetsForGoal } from './semantic-observe.js';
+function finalizeObserveStepBestEffort(runId, stepId, options) {
+    if (!runId || !stepId) {
+        return;
+    }
+    try {
+        finishRunStep({
+            runId,
+            stepId,
+            ...options,
+        });
+    }
+    catch { }
+}
+async function emitObserveSuccess(session, step, payload) {
+    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: 'observation_completed',
+            ...(typeof payload.pageRef === 'string' ? { pageRef: payload.pageRef } : {}),
+            ...(typeof payload.resolvedBy === 'string' ? { resolvedBy: payload.resolvedBy } : {}),
+        },
+    });
+    finalizeObserveStepBestEffort(step?.runId, step?.stepId, {
+        success: true,
+        outcomeType: 'observation_completed',
+        message: typeof payload.message === 'string' ? payload.message : 'Observe completed.',
+    });
+    await exportRunStepToOtlpHttpJsonBestEffort(step?.runId, step?.stepId);
+    return outputJSON(payload);
+}
+async function emitObserveContractFailure(session, params) {
+    const step = params.runId && params.stepId
+        ? {
+            runId: params.runId,
+            stepId: params.stepId,
+            command: 'observe',
+        }
+        : null;
+    captureStepSnapshotBestEffort({
+        session,
+        step,
+        phase: 'point-in-time',
+        pageRef: typeof params.pageRef === 'string' ? params.pageRef : undefined,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step,
+        phase: 'failed',
+        attributes: {
+            ...(params.outcomeType ? { outcomeType: params.outcomeType } : {}),
+            ...(typeof params.pageRef === 'string' ? { pageRef: params.pageRef } : {}),
+            ...(params.reason ? { reason: params.reason } : {}),
+        },
+    });
+    finalizeObserveStepBestEffort(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 const __testDomTargetCollection = inventoryDomTargetCollection;
 export const __testStagehandDescriptor = {
     ...inventoryStagehandDescriptor,
@@ -31,233 +109,339 @@ export async function observe(session, instruction) {
     let stagehandFallbackReason = null;
     let browser = null;
     let observedScopes = [];
-    if (!instruction) {
-        try {
-            browser = await connectPlaywright(session.cdpUrl);
-            const resolvedPage = await resolveCurrentPageContext(browser, session);
-            pageRef = resolvedPage.pageRef;
-            const page = resolvedPage.page;
-            const { url, title } = await syncSessionPage(session, pageRef, page);
-            bumpPageScopeEpoch(session, pageRef);
-            setCurrentPage(session, pageRef);
-            const collectedTargets = await collectDomTargets(page);
-            let observeAccessibilityStats;
-            const domTargets = compressSemanticallyDuplicateTargets(orderBySurfaceCompetition(annotateDomTargets(await enrichDomTargetsWithAccessibility(page, collectedTargets, {
-                onStats: (stats) => {
-                    observeAccessibilityStats = stats;
-                },
-            }))));
-            if (observeAccessibilityStats) {
-                incrementMetric(session, 'observeAxAttempts', observeAccessibilityStats.axAttempts);
-                incrementMetric(session, 'observeAxHits', observeAccessibilityStats.axHits);
-                incrementMetric(session, 'observeFallbackUses', observeAccessibilityStats.fallbackUses);
-            }
-            const signals = compactSignals(await collectPageSignals(page).catch(() => []));
-            const pageState = classifyObservePageState(signals);
-            const persisted = persistObservedSurfacesForPage(session, pageRef, domTargets);
-            observedScopes = persisted.observedScopes;
-            const surfaceRefMap = persisted.surfaceRefMap;
-            if (domTargets.length > 0) {
-                const targets = replaceTargetsForPage(session, pageRef, domTargets.map((target) => toDomDescriptor(pageRef, target, surfaceRefMap)));
-                reconcileObservedTargetsForPage(session, pageRef, targets);
-                attachObservedTargetOwners(domTargets, targets);
-                observedScopes = linkObservedSurfaceGraph(session, pageRef, domTargets, targets, observedScopes, surfaceRefMap);
-                const fillableForms = shouldSuppressFillableFormsForObserve(pageState)
-                    ? clearProtectedFillableFormsForPage(session, pageRef)
-                    : await persistProtectedFillableFormsForPage(session, pageRef, url, targets, new Date().toISOString());
-                saveSession(session);
-                disconnectPlaywright(browser);
-                browser = null;
-                outputJSON({
-                    success: true,
-                    pageRef,
-                    resolvedBy: 'dom',
-                    ...domRuntimeResolution(),
-                    scopes: buildGroupedObserveScopes({
-                        pageRef,
-                        title,
-                        scopes: selectScopesForOutput(observedScopes, targets),
-                        targets,
-                    }),
-                    signals,
-                    fillableForms: compactFillableForms(fillableForms),
-                    metrics: session.runtime?.metrics,
-                    message: targets.length === 0 ? 'No targets found.' : undefined,
-                    url,
-                    title,
+    const observeStep = session.activeRunId
+        ? startRunStep({
+            runId: session.activeRunId,
+            command: 'observe',
+            input: {
+                ...(instruction ? { instruction } : {}),
+            },
+            refs: {
+                pageRef,
+            },
+            protectedStep: Boolean(session.runtime?.protectedExposureByPage?.[pageRef]),
+        })
+        : null;
+    captureStepSnapshotBestEffort({
+        session,
+        step: observeStep,
+        phase: 'before',
+        pageRef,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step: observeStep,
+        phase: 'started',
+        attributes: {
+            ...(instruction ? { instruction } : {}),
+            pageRef,
+        },
+    });
+    return withApiTraceContext({
+        runId: session.activeRunId,
+        stepId: observeStep?.stepId,
+        command: 'observe',
+    }, async () => {
+        const observePhaseAttributes = {
+            'agentbrowse.observe.goal_based': Boolean(instruction),
+        };
+        if (!instruction) {
+            try {
+                browser = await tracedStepOperation(() => connectPlaywright(session.cdpUrl), {
+                    spanName: 'agentbrowse.observe.connect_browser',
+                    attributes: observePhaseAttributes,
                 });
-                return;
-            }
-            stagehandFallbackReason = 'deterministic-observe-empty';
-        }
-        catch (err) {
-            domPassError = err instanceof Error ? err.message : String(err);
-            stagehandFallbackReason = 'deterministic-observe-failed';
-        }
-    }
-    if (instruction) {
-        try {
-            if (!browser) {
-                browser = await connectPlaywright(session.cdpUrl);
-            }
-            const resolvedPage = await resolveCurrentPageContext(browser, session);
-            pageRef = resolvedPage.pageRef;
-            const page = resolvedPage.page;
-            const { url, title } = await syncSessionPage(session, pageRef, page);
-            bumpPageScopeEpoch(session, pageRef);
-            setCurrentPage(session, pageRef);
-            const collectedTargets = await collectDomTargets(page, {
-                includeActivationAffordances: true,
-            });
-            let observeAccessibilityStats;
-            const domTargets = compressSemanticallyDuplicateTargets(orderBySurfaceCompetition(annotateDomTargets(await enrichDomTargetsWithAccessibility(page, collectedTargets, {
-                onStats: (stats) => {
-                    observeAccessibilityStats = stats;
-                },
-            }))));
-            if (observeAccessibilityStats) {
-                incrementMetric(session, 'observeAxAttempts', observeAccessibilityStats.axAttempts);
-                incrementMetric(session, 'observeAxHits', observeAccessibilityStats.axHits);
-                incrementMetric(session, 'observeFallbackUses', observeAccessibilityStats.fallbackUses);
-            }
-            const signals = compactSignals(await collectPageSignals(page).catch(() => []));
-            const pageState = classifyObservePageState(signals);
-            const surfaceInputs = collectSurfaceDescriptors(pageRef, domTargets);
-            if (domTargets.length > 0) {
-                const rerankedCandidates = await rerankDomTargetsForGoal(instruction, buildGoalObserveInventoryCandidates(domTargets, surfaceInputs), { session });
-                const { targets: goalMatchedTargets, selectedSurfaceIds } = selectTargetsForGoalMatches(domTargets, rerankedCandidates);
-                const selectedTargets = prioritizeGoalActionTargets(instruction, expandWorkflowGraphTargets(domTargets, goalMatchedTargets, { selectedSurfaceIds }));
-                const persisted = persistObservedSurfacesForPage(session, pageRef, domTargets, {
-                    allSurfaceInputs: surfaceInputs,
-                    explicitSurfaceIds: selectedSurfaceIds,
+                const resolvedPage = await tracedStepOperation(() => resolveCurrentPageContext(browser, session), {
+                    spanName: 'agentbrowse.observe.resolve_page_context',
+                    attributes: observePhaseAttributes,
                 });
+                pageRef = resolvedPage.pageRef;
+                const page = resolvedPage.page;
+                const { url, title } = await tracedStepOperation(() => syncSessionPage(session, pageRef, page), {
+                    spanName: 'agentbrowse.observe.sync_session_page',
+                    attributes: observePhaseAttributes,
+                });
+                bumpPageScopeEpoch(session, pageRef);
+                setCurrentPage(session, pageRef);
+                const collectedTargets = await tracedStepOperation(() => collectDomTargets(page), {
+                    spanName: 'agentbrowse.observe.collect_dom_targets',
+                    attributes: observePhaseAttributes,
+                });
+                let observeAccessibilityStats;
+                const domTargets = compressSemanticallyDuplicateTargets(orderBySurfaceCompetition(annotateDomTargets(await tracedStepOperation(() => enrichDomTargetsWithAccessibility(page, collectedTargets, {
+                    onStats: (stats) => {
+                        observeAccessibilityStats = stats;
+                    },
+                }), {
+                    spanName: 'agentbrowse.observe.enrich_accessibility',
+                    attributes: observePhaseAttributes,
+                }))));
+                if (observeAccessibilityStats) {
+                    incrementMetric(session, 'observeAxAttempts', observeAccessibilityStats.axAttempts);
+                    incrementMetric(session, 'observeAxHits', observeAccessibilityStats.axHits);
+                    incrementMetric(session, 'observeFallbackUses', observeAccessibilityStats.fallbackUses);
+                }
+                const signals = compactSignals(await tracedStepOperation(() => collectPageSignals(page).catch(() => []), {
+                    spanName: 'agentbrowse.observe.collect_page_signals',
+                    attributes: observePhaseAttributes,
+                }));
+                const pageState = classifyObservePageState(signals);
+                const persisted = persistObservedSurfacesForPage(session, pageRef, domTargets);
                 observedScopes = persisted.observedScopes;
                 const surfaceRefMap = persisted.surfaceRefMap;
-                const targets = replaceTargetsForPage(session, pageRef, domTargets.map((target) => toDomDescriptor(pageRef, target, surfaceRefMap)));
-                reconcileObservedTargetsForPage(session, pageRef, targets);
-                attachObservedTargetOwners(domTargets, targets);
-                observedScopes = linkObservedSurfaceGraph(session, pageRef, domTargets, targets, observedScopes, surfaceRefMap);
-                const fillableForms = shouldSuppressFillableFormsForObserve(pageState)
-                    ? clearProtectedFillableFormsForPage(session, pageRef)
-                    : await persistProtectedFillableFormsForPage(session, pageRef, url, targets, new Date().toISOString());
-                if (selectedTargets.length > 0 || selectedSurfaceIds.size > 0) {
-                    const projectedTargets = projectPersistedTargetsForGoal(domTargets, targets, selectedTargets);
-                    const explicitScopeRefs = buildGoalProjectionScopeRefs(projectedTargets, selectedSurfaceIds, surfaceRefMap);
+                if (domTargets.length > 0) {
+                    const targets = replaceTargetsForPage(session, pageRef, domTargets.map((target) => toDomDescriptor(pageRef, target, surfaceRefMap)));
+                    reconcileObservedTargetsForPage(session, pageRef, targets);
+                    attachObservedTargetOwners(domTargets, targets);
+                    observedScopes = linkObservedSurfaceGraph(session, pageRef, domTargets, targets, observedScopes, surfaceRefMap);
+                    const fillableForms = shouldSuppressFillableFormsForObserve(pageState)
+                        ? clearProtectedFillableFormsForPage(session, pageRef)
+                        : await tracedStepOperation(() => persistProtectedFillableFormsForPage(session, pageRef, url, targets, new Date().toISOString()), {
+                            spanName: 'agentbrowse.observe.persist_fillable_forms',
+                            attributes: {
+                                ...observePhaseAttributes,
+                                'agentbrowse.observe.target_count': targets.length,
+                            },
+                        });
                     saveSession(session);
-                    disconnectPlaywright(browser);
+                    await disconnectPlaywright(browser);
                     browser = null;
-                    outputJSON({
+                    return emitObserveSuccess(session, observeStep, {
                         success: true,
                         pageRef,
-                        resolvedBy: 'dom-rerank',
+                        resolvedBy: 'dom',
                         ...domRuntimeResolution(),
                         scopes: buildGroupedObserveScopes({
                             pageRef,
                             title,
-                            scopes: selectScopesForOutput(observedScopes, projectedTargets, explicitScopeRefs),
-                            targets: projectedTargets,
+                            scopes: selectScopesForOutput(observedScopes, targets),
+                            targets,
                         }),
                         signals,
                         fillableForms: compactFillableForms(fillableForms),
                         metrics: session.runtime?.metrics,
+                        message: targets.length === 0 ? 'No targets found.' : undefined,
                         url,
                         title,
                     });
-                    return;
                 }
-                saveSession(session);
-                disconnectPlaywright(browser);
-                browser = null;
-                outputJSON({
-                    success: true,
-                    pageRef,
-                    resolvedBy: 'dom-rerank',
-                    ...domRuntimeResolution(),
-                    scopes: [],
-                    signals,
-                    fillableForms: compactFillableForms(fillableForms),
-                    metrics: session.runtime?.metrics,
-                    message: 'No targets matched the requested goal.',
-                    url,
-                    title,
+                stagehandFallbackReason = 'deterministic-observe-empty';
+            }
+            catch (err) {
+                domPassError = err instanceof Error ? err.message : String(err);
+                stagehandFallbackReason = 'deterministic-observe-failed';
+            }
+        }
+        if (instruction) {
+            try {
+                if (!browser) {
+                    browser = await tracedStepOperation(() => connectPlaywright(session.cdpUrl), {
+                        spanName: 'agentbrowse.observe.connect_browser',
+                        attributes: observePhaseAttributes,
+                    });
+                }
+                const resolvedPage = await tracedStepOperation(() => resolveCurrentPageContext(browser, session), {
+                    spanName: 'agentbrowse.observe.resolve_page_context',
+                    attributes: observePhaseAttributes,
+                });
+                pageRef = resolvedPage.pageRef;
+                const page = resolvedPage.page;
+                const { url, title } = await tracedStepOperation(() => syncSessionPage(session, pageRef, page), {
+                    spanName: 'agentbrowse.observe.sync_session_page',
+                    attributes: observePhaseAttributes,
+                });
+                bumpPageScopeEpoch(session, pageRef);
+                setCurrentPage(session, pageRef);
+                const collectedTargets = await tracedStepOperation(() => collectDomTargets(page, {
+                    includeActivationAffordances: true,
+                }), {
+                    spanName: 'agentbrowse.observe.collect_dom_targets',
+                    attributes: observePhaseAttributes,
+                });
+                let observeAccessibilityStats;
+                const domTargets = compressSemanticallyDuplicateTargets(orderBySurfaceCompetition(annotateDomTargets(await tracedStepOperation(() => enrichDomTargetsWithAccessibility(page, collectedTargets, {
+                    onStats: (stats) => {
+                        observeAccessibilityStats = stats;
+                    },
+                }), {
+                    spanName: 'agentbrowse.observe.enrich_accessibility',
+                    attributes: observePhaseAttributes,
+                }))));
+                if (observeAccessibilityStats) {
+                    incrementMetric(session, 'observeAxAttempts', observeAccessibilityStats.axAttempts);
+                    incrementMetric(session, 'observeAxHits', observeAccessibilityStats.axHits);
+                    incrementMetric(session, 'observeFallbackUses', observeAccessibilityStats.fallbackUses);
+                }
+                const signals = compactSignals(await tracedStepOperation(() => collectPageSignals(page).catch(() => []), {
+                    spanName: 'agentbrowse.observe.collect_page_signals',
+                    attributes: observePhaseAttributes,
+                }));
+                const pageState = classifyObservePageState(signals);
+                const surfaceInputs = collectSurfaceDescriptors(pageRef, domTargets);
+                if (domTargets.length > 0) {
+                    const rerankedCandidates = await tracedStepOperation(() => rerankDomTargetsForGoal(instruction, buildGoalObserveInventoryCandidates(domTargets, surfaceInputs), { session }), {
+                        spanName: 'agentbrowse.observe.rerank_goal_candidates',
+                        attributes: {
+                            ...observePhaseAttributes,
+                            'agentbrowse.observe.target_count': domTargets.length,
+                        },
+                    });
+                    const { targets: goalMatchedTargets, selectedSurfaceIds } = selectTargetsForGoalMatches(domTargets, rerankedCandidates);
+                    const selectedTargets = prioritizeGoalActionTargets(instruction, expandWorkflowGraphTargets(domTargets, goalMatchedTargets, { selectedSurfaceIds }));
+                    const persisted = persistObservedSurfacesForPage(session, pageRef, domTargets, {
+                        allSurfaceInputs: surfaceInputs,
+                        explicitSurfaceIds: selectedSurfaceIds,
+                    });
+                    observedScopes = persisted.observedScopes;
+                    const surfaceRefMap = persisted.surfaceRefMap;
+                    const targets = replaceTargetsForPage(session, pageRef, domTargets.map((target) => toDomDescriptor(pageRef, target, surfaceRefMap)));
+                    reconcileObservedTargetsForPage(session, pageRef, targets);
+                    attachObservedTargetOwners(domTargets, targets);
+                    observedScopes = linkObservedSurfaceGraph(session, pageRef, domTargets, targets, observedScopes, surfaceRefMap);
+                    const fillableForms = shouldSuppressFillableFormsForObserve(pageState)
+                        ? clearProtectedFillableFormsForPage(session, pageRef)
+                        : await tracedStepOperation(() => persistProtectedFillableFormsForPage(session, pageRef, url, targets, new Date().toISOString()), {
+                            spanName: 'agentbrowse.observe.persist_fillable_forms',
+                            attributes: {
+                                ...observePhaseAttributes,
+                                'agentbrowse.observe.target_count': targets.length,
+                            },
+                        });
+                    if (selectedTargets.length > 0 || selectedSurfaceIds.size > 0) {
+                        const projectedTargets = projectPersistedTargetsForGoal(domTargets, targets, selectedTargets);
+                        const explicitScopeRefs = buildGoalProjectionScopeRefs(projectedTargets, selectedSurfaceIds, surfaceRefMap);
+                        saveSession(session);
+                        await disconnectPlaywright(browser);
+                        browser = null;
+                        return emitObserveSuccess(session, observeStep, {
+                            success: true,
+                            pageRef,
+                            resolvedBy: 'dom-rerank',
+                            ...domRuntimeResolution(),
+                            scopes: buildGroupedObserveScopes({
+                                pageRef,
+                                title,
+                                scopes: selectScopesForOutput(observedScopes, projectedTargets, explicitScopeRefs),
+                                targets: projectedTargets,
+                            }),
+                            signals,
+                            fillableForms: compactFillableForms(fillableForms),
+                            metrics: session.runtime?.metrics,
+                            url,
+                            title,
+                        });
+                    }
+                    saveSession(session);
+                    await disconnectPlaywright(browser);
+                    browser = null;
+                    return emitObserveSuccess(session, observeStep, {
+                        success: true,
+                        pageRef,
+                        resolvedBy: 'dom-rerank',
+                        ...domRuntimeResolution(),
+                        scopes: [],
+                        signals,
+                        fillableForms: compactFillableForms(fillableForms),
+                        metrics: session.runtime?.metrics,
+                        message: 'No targets matched the requested goal.',
+                        url,
+                        title,
+                    });
+                }
+                stagehandFallbackReason = 'deterministic-observe-empty';
+            }
+            catch (err) {
+                domPassError = err instanceof Error ? err.message : String(err);
+                stagehandFallbackReason = 'deterministic-observe-failed';
+            }
+        }
+        try {
+            if (!browser) {
+                browser = await tracedStepOperation(() => connectPlaywright(session.cdpUrl), {
+                    spanName: 'agentbrowse.observe.connect_browser',
+                    attributes: observePhaseAttributes,
                 });
-                return;
             }
-            stagehandFallbackReason = 'deterministic-observe-empty';
         }
         catch (err) {
-            domPassError = err instanceof Error ? err.message : String(err);
-            stagehandFallbackReason = 'deterministic-observe-failed';
-        }
-    }
-    try {
-        if (!browser) {
-            browser = await connectPlaywright(session.cdpUrl);
+            const domFailure = domPassError && domPassError.length > 0 ? `; dom observe failed: ${domPassError}` : '';
+            return emitObserveContractFailure(session, {
+                error: 'browser_connection_failed',
+                outcomeType: 'blocked',
+                message: 'Observe could not start because AgentBrowse failed to connect to the browser.',
+                reason: `${err instanceof Error ? err.message : String(err)}${domFailure}`,
+                pageRef,
+                runId: session.activeRunId,
+                stepId: observeStep?.stepId,
+            });
         }
-    }
-    catch (err) {
-        const domFailure = domPassError && domPassError.length > 0 ? `; dom observe failed: ${domPassError}` : '';
-        outputContractFailure({
-            error: 'browser_connection_failed',
-            outcomeType: 'blocked',
-            message: 'Observe could not start because AgentBrowse failed to connect to the browser.',
-            reason: `${err instanceof Error ? err.message : String(err)}${domFailure}`,
-            pageRef,
-        });
-    }
-    try {
-        const resolvedPage = await resolveCurrentPageContext(browser, session);
-        pageRef = resolvedPage.pageRef;
-        const page = resolvedPage.page;
-        const { url, title } = await syncSessionPage(session, pageRef, page);
-        bumpPageScopeEpoch(session, pageRef);
-        setCurrentPage(session, pageRef);
-        const signals = compactSignals(await collectPageSignals(page).catch(() => []));
-        const actions = await withStagehand(session, async (stagehand) => {
-            incrementMetric(session, 'stagehandCalls');
-            return instruction
-                ? (await stagehand.observe(instruction, { page }))
-                : (await stagehand.observe({ page }));
-        });
-        const targets = replaceTargetsForPage(session, pageRef, await Promise.all(actions.map((action) => toStagehandDescriptor(pageRef, action, page, normalizePageSignature(url)))));
-        const fillableForms = clearProtectedFillableFormsForPage(session, pageRef);
-        saveSession(session);
-        outputJSON({
-            success: true,
-            pageRef,
-            resolvedBy: 'stagehand-observe',
-            ...stagehandRuntimeResolution(stagehandFallbackReason ?? 'deterministic-observe-failed'),
-            deterministicObserveError: domPassError ?? undefined,
-            scopes: buildGroupedObserveScopes({
+        try {
+            const resolvedPage = await tracedStepOperation(() => resolveCurrentPageContext(browser, session), {
+                spanName: 'agentbrowse.observe.resolve_page_context',
+                attributes: observePhaseAttributes,
+            });
+            pageRef = resolvedPage.pageRef;
+            const page = resolvedPage.page;
+            const { url, title } = await tracedStepOperation(() => syncSessionPage(session, pageRef, page), {
+                spanName: 'agentbrowse.observe.sync_session_page',
+                attributes: observePhaseAttributes,
+            });
+            bumpPageScopeEpoch(session, pageRef);
+            setCurrentPage(session, pageRef);
+            const signals = compactSignals(await tracedStepOperation(() => collectPageSignals(page).catch(() => []), {
+                spanName: 'agentbrowse.observe.collect_page_signals',
+                attributes: observePhaseAttributes,
+            }));
+            const actions = await tracedStepOperation(() => withStagehand(session, async (stagehand) => {
+                incrementMetric(session, 'stagehandCalls');
+                return instruction
+                    ? (await stagehand.observe(instruction, { page }))
+                    : (await stagehand.observe({ page }));
+            }), {
+                spanName: 'agentbrowse.observe.stagehand_observe',
+                attributes: observePhaseAttributes,
+            });
+            const targets = replaceTargetsForPage(session, pageRef, await Promise.all(actions.map((action) => toStagehandDescriptor(pageRef, action, page, normalizePageSignature(url)))));
+            const fillableForms = markProtectedFillableFormsUnknownForPage(session, pageRef);
+            saveSession(session);
+            return emitObserveSuccess(session, observeStep, {
+                success: true,
                 pageRef,
+                resolvedBy: 'stagehand-observe',
+                ...stagehandRuntimeResolution(stagehandFallbackReason ?? 'deterministic-observe-failed'),
+                deterministicObserveError: domPassError ?? undefined,
+                scopes: buildGroupedObserveScopes({
+                    pageRef,
+                    title,
+                    scopes: selectScopesForOutput(observedScopes, targets),
+                    targets,
+                }),
+                signals,
+                fillableForms: compactFillableForms(fillableForms),
+                metrics: session.runtime?.metrics,
+                message: targets.length === 0 ? 'No targets found.' : undefined,
+                url,
                 title,
-                scopes: selectScopesForOutput(observedScopes, targets),
-                targets,
-            }),
-            signals,
-            fillableForms: compactFillableForms(fillableForms),
-            metrics: session.runtime?.metrics,
-            message: targets.length === 0 ? 'No targets found.' : undefined,
-            url,
-            title,
-        });
-    }
-    catch (err) {
-        const stagehandError = err instanceof Error ? err.message : String(err);
-        const details = domPassError
-            ? `${stagehandError} (deterministic observe failed earlier: ${domPassError})`
-            : stagehandError;
-        outputContractFailure({
-            error: 'observe_failed',
-            outcomeType: 'blocked',
-            message: 'Observe failed.',
-            reason: details,
-            pageRef,
-        });
-    }
-    finally {
-        if (browser) {
-            disconnectPlaywright(browser);
+            });
         }
-    }
+        catch (err) {
+            const stagehandError = err instanceof Error ? err.message : String(err);
+            const details = domPassError
+                ? `${stagehandError} (deterministic observe failed earlier: ${domPassError})`
+                : stagehandError;
+            return emitObserveContractFailure(session, {
+                error: 'observe_failed',
+                outcomeType: 'blocked',
+                message: 'Observe failed.',
+                reason: details,
+                pageRef,
+                runId: session.activeRunId,
+                stepId: observeStep?.stepId,
+            });
+        }
+        finally {
+            if (browser) {
+                await disconnectPlaywright(browser);
+            }
+        }
+    });
 }