@mercuryo-ai/agentbrowse 0.2.50

package/dist/commands/observe.js

@@ -0,0 +1,556 @@
+/**
+ * browse observe ["<instruction>"] — Discover available actions on the page.
+ */
+import { canUseAgentbrowseAssistiveLlmClient } from "../assistive-runtime.js";
+import { saveSession } from "../session.js";
+import { ensureRuntimeState, replaceTargetsForPage } from "../runtime-state.js";
+import { incrementMetric } from "../runtime-metrics.js";
+import { bumpPageScopeEpoch, setCurrentPage } from "../runtime-page-state.js";
+import { getProtectedExposure } from "../runtime-protected-state.js";
+import { connectPlaywright, disconnectPlaywright, resolveCurrentPageContext, syncSessionPage, } from "../playwright-runtime.js";
+import { tracedStepOperation, withApiTraceContext, } from "../command-api-tracing.js";
+import { captureDiagnosticSnapshotBestEffort, finishDiagnosticStepBestEffort, recordCommandLifecycleEventBestEffort, startDiagnosticStep, } from "../diagnostics.js";
+import { outputContractFailure, outputJSON, } from "../output.js";
+import { domRuntimeResolution, stagehandRuntimeResolution, } from "../runtime-resolution.js";
+import { withStagehand } from "../stagehand-runtime.js";
+import { buildProtectedObserveBlockedResult } from "../secrets/protected-artifact-guard.js";
+import { scrubProtectedExactValues } from "../secrets/protected-exact-value-redaction.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, 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";
+/** Stable top-level error codes returned by `observe(...)`. */
+export const OBSERVE_ERROR_CODES = [
+    "browser_connection_failed",
+    "observe_failed",
+    "protected_observe_blocked",
+];
+/** Stable outcome categories emitted by `observe(...)`. */
+export const OBSERVE_OUTCOME_TYPES = [
+    "blocked",
+    "observation_completed",
+    "protected_exposure_active",
+];
+function flattenObserveTargets(scopes) {
+    if (!Array.isArray(scopes)) {
+        return [];
+    }
+    return scopes.flatMap((scope) => {
+        if (!scope || typeof scope !== "object" || Array.isArray(scope)) {
+            return [];
+        }
+        const typedScope = scope;
+        return Array.isArray(typedScope.targets) ? typedScope.targets : [];
+    });
+}
+function normalizeObserveSuccessPayload(payload) {
+    const scopes = Array.isArray(payload.scopes) ? payload.scopes : [];
+    const explicitTargets = Array.isArray(payload.targets) ? payload.targets : [];
+    const targets = explicitTargets.length > 0 || Array.isArray(payload.targets)
+        ? explicitTargets
+        : flattenObserveTargets(scopes);
+    return {
+        ...payload,
+        scopes,
+        targets,
+        signals: Array.isArray(payload.signals) ? payload.signals : [],
+        fillableForms: Array.isArray(payload.fillableForms)
+            ? payload.fillableForms
+            : [],
+        targetCount: targets.length,
+        scopeCount: scopes.length,
+        projectedTargetCount: targets.length,
+    };
+}
+function tryResolveHost(url) {
+    try {
+        return new URL(url).hostname || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildObservePageMetadata(params) {
+    return {
+        url: params.url,
+        title: params.title,
+        ...(params.protectedExposure && tryResolveHost(params.url)
+            ? { host: tryResolveHost(params.url) }
+            : {}),
+    };
+}
+function finalizeObserveStepBestEffort(step, options) {
+    return finishDiagnosticStepBestEffort({
+        step,
+        ...options,
+    });
+}
+async function buildObserveSuccessResult(session, step, payload) {
+    const normalizedPayload = scrubProtectedExactValues(session, normalizeObserveSuccessPayload(payload));
+    captureDiagnosticSnapshotBestEffort({
+        session,
+        step,
+        phase: "after",
+        pageRef: typeof normalizedPayload.pageRef === "string"
+            ? normalizedPayload.pageRef
+            : session.runtime?.currentPageRef,
+        url: typeof normalizedPayload.url === "string"
+            ? normalizedPayload.url
+            : undefined,
+        title: typeof normalizedPayload.title === "string"
+            ? normalizedPayload.title
+            : undefined,
+    });
+    recordCommandLifecycleEventBestEffort({
+        step,
+        phase: "completed",
+        attributes: {
+            outcomeType: "observation_completed",
+            ...(typeof normalizedPayload.pageRef === "string"
+                ? { pageRef: normalizedPayload.pageRef }
+                : {}),
+            ...(typeof normalizedPayload.resolvedBy === "string"
+                ? { resolvedBy: normalizedPayload.resolvedBy }
+                : {}),
+        },
+    });
+    await finalizeObserveStepBestEffort(step, {
+        success: true,
+        outcomeType: "observation_completed",
+        message: typeof normalizedPayload.message === "string"
+            ? normalizedPayload.message
+            : "Observe completed.",
+    });
+    return normalizedPayload;
+}
+async function buildObserveContractFailureResult(session, params) {
+    const step = params.step;
+    captureDiagnosticSnapshotBestEffort({
+        session,
+        step,
+        phase: "point-in-time",
+        pageRef: typeof params.pageRef === "string" ? params.pageRef : undefined,
+    });
+    recordCommandLifecycleEventBestEffort({
+        step,
+        phase: "failed",
+        attributes: {
+            ...(params.outcomeType ? { outcomeType: params.outcomeType } : {}),
+            ...(typeof params.pageRef === "string"
+                ? { pageRef: params.pageRef }
+                : {}),
+            ...(params.reason ? { reason: params.reason } : {}),
+        },
+    });
+    await finalizeObserveStepBestEffort(step, {
+        success: false,
+        outcomeType: params.outcomeType,
+        message: params.message,
+        reason: params.reason,
+    });
+    const { runId: _runId, stepId: _stepId, step: _step, ...result } = params;
+    return scrubProtectedExactValues(session, {
+        success: false,
+        ...result,
+    });
+}
+export const __testDomTargetCollection = inventoryDomTargetCollection;
+export const __testStagehandDescriptor = {
+    ...inventoryStagehandDescriptor,
+    toStagehandDescriptor,
+};
+/**
+ * Observes the current page and returns the current target inventory.
+ *
+ * The success payload always includes a flat `targets` array for direct
+ * consumption and grouped `scopes` for richer container-aware workflows.
+ */
+export async function observeBrowser(session, instruction) {
+    const allowAssistive = Boolean(instruction);
+    const canUseAssistiveLlm = allowAssistive
+        ? canUseAgentbrowseAssistiveLlmClient({ session })
+        : false;
+    const runtime = ensureRuntimeState(session);
+    let pageRef = runtime.currentPageRef;
+    let domPassError = null;
+    let stagehandFallbackReason = null;
+    let browser = null;
+    let observedScopes = [];
+    const observeStep = startDiagnosticStep({
+        runId: session.activeRunId,
+        command: "observe",
+        input: {
+            ...(instruction ? { instruction } : {}),
+        },
+        refs: {
+            pageRef,
+        },
+        protectedStep: Boolean(session.runtime?.protectedExposureByPage?.[pageRef]),
+    }, { session });
+    captureDiagnosticSnapshotBestEffort({
+        session,
+        step: observeStep,
+        phase: "before",
+        pageRef,
+    });
+    recordCommandLifecycleEventBestEffort({
+        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),
+        };
+        const initialProtectedExposure = instruction
+            ? getProtectedExposure(session, pageRef)
+            : null;
+        if (instruction && initialProtectedExposure) {
+            return buildObserveContractFailureResult(session, {
+                step: observeStep,
+                ...buildProtectedObserveBlockedResult(initialProtectedExposure, "goal-rerank"),
+                pageRef,
+                runId: session.activeRunId,
+                stepId: observeStep?.stepId,
+            });
+        }
+        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);
+                const protectedExposure = getProtectedExposure(session, pageRef);
+                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 pageSignals = await collectPageSignals(page).catch(() => []);
+                const pageState = classifyObservePageState(pageSignals);
+                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());
+                    await disconnectPlaywright(browser);
+                    browser = null;
+                    return buildObserveSuccessResult(session, observeStep, {
+                        success: true,
+                        observationMode: "deterministic_dom",
+                        pageRef,
+                        resolvedBy: "dom",
+                        ...domRuntimeResolution(),
+                        scopes: buildGroupedObserveScopes({
+                            pageRef,
+                            title,
+                            scopes: selectScopesForOutput(observedScopes, targets),
+                            targets,
+                        }),
+                        signals: compactSignals(pageSignals),
+                        fillableForms: compactFillableForms(fillableForms),
+                        metrics: session.runtime?.metrics,
+                        message: targets.length === 0
+                            ? "This observe pass returned zero targets."
+                            : undefined,
+                        ...buildObservePageMetadata({
+                            url,
+                            title,
+                            protectedExposure,
+                        }),
+                    });
+                }
+                if (!allowAssistive) {
+                    await disconnectPlaywright(browser);
+                    browser = null;
+                    return buildObserveSuccessResult(session, observeStep, {
+                        success: true,
+                        observationMode: "deterministic_dom",
+                        pageRef,
+                        resolvedBy: "dom",
+                        ...domRuntimeResolution(),
+                        scopes: [],
+                        signals: compactSignals(pageSignals),
+                        fillableForms: [],
+                        metrics: session.runtime?.metrics,
+                        message: "This observe pass returned zero targets.",
+                        ...buildObservePageMetadata({
+                            url,
+                            title,
+                            protectedExposure,
+                        }),
+                    });
+                }
+                stagehandFallbackReason = "deterministic-observe-empty";
+            }
+            catch (err) {
+                domPassError = err instanceof Error ? err.message : String(err);
+                if (!allowAssistive) {
+                    return buildObserveContractFailureResult(session, {
+                        step: observeStep,
+                        error: "observe_failed",
+                        outcomeType: "blocked",
+                        message: "Observe failed.",
+                        reason: domPassError,
+                        pageRef,
+                        runId: session.activeRunId,
+                        stepId: observeStep?.stepId,
+                    });
+                }
+                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);
+                const protectedExposure = getProtectedExposure(session, pageRef);
+                if (protectedExposure) {
+                    return buildObserveContractFailureResult(session, {
+                        step: observeStep,
+                        ...buildProtectedObserveBlockedResult(protectedExposure, "goal-rerank"),
+                        pageRef,
+                        runId: session.activeRunId,
+                        stepId: observeStep?.stepId,
+                    });
+                }
+                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 pageSignals = await collectPageSignals(page).catch(() => []);
+                const pageState = classifyObservePageState(pageSignals);
+                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 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);
+                        await disconnectPlaywright(browser);
+                        browser = null;
+                        return buildObserveSuccessResult(session, observeStep, {
+                            success: true,
+                            observationMode: canUseAssistiveLlm
+                                ? "goal_assistive_rerank"
+                                : "goal_heuristic_shortlist",
+                            pageRef,
+                            resolvedBy: "dom-rerank",
+                            ...domRuntimeResolution(),
+                            scopes: buildGroupedObserveScopes({
+                                pageRef,
+                                title,
+                                scopes: selectScopesForOutput(observedScopes, projectedTargets, explicitScopeRefs),
+                                targets: projectedTargets,
+                            }),
+                            signals: compactSignals(pageSignals),
+                            fillableForms: compactFillableForms(fillableForms),
+                            metrics: session.runtime?.metrics,
+                            url,
+                            title,
+                        });
+                    }
+                    await disconnectPlaywright(browser);
+                    browser = null;
+                    return buildObserveSuccessResult(session, observeStep, {
+                        success: true,
+                        observationMode: canUseAssistiveLlm
+                            ? "goal_assistive_rerank"
+                            : "goal_heuristic_shortlist",
+                        pageRef,
+                        resolvedBy: "dom-rerank",
+                        ...domRuntimeResolution(),
+                        scopes: [],
+                        signals: compactSignals(pageSignals),
+                        fillableForms: compactFillableForms(fillableForms),
+                        metrics: session.runtime?.metrics,
+                        message: "This goal-based observe pass returned zero matching targets.",
+                        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 connectPlaywright(session.cdpUrl);
+            }
+        }
+        catch (err) {
+            const domFailure = domPassError && domPassError.length > 0
+                ? `; dom observe failed: ${domPassError}`
+                : "";
+            return buildObserveContractFailureResult(session, {
+                step: observeStep,
+                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,
+            });
+        }
+        try {
+            const resolvedPage = await resolveCurrentPageContext(browser, session);
+            pageRef = resolvedPage.pageRef;
+            const page = resolvedPage.page;
+            const { url, title } = await syncSessionPage(session, pageRef, page);
+            const protectedExposure = getProtectedExposure(session, pageRef);
+            if (protectedExposure) {
+                return buildObserveContractFailureResult(session, {
+                    step: observeStep,
+                    ...buildProtectedObserveBlockedResult(protectedExposure, "stagehand-fallback"),
+                    fallbackReason: stagehandFallbackReason ?? undefined,
+                    deterministicObserveError: domPassError ?? undefined,
+                    pageRef,
+                    runId: session.activeRunId,
+                    stepId: observeStep?.stepId,
+                });
+            }
+            bumpPageScopeEpoch(session, pageRef);
+            setCurrentPage(session, pageRef);
+            const pageSignals = 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 = markProtectedFillableFormsUnknownForPage(session, pageRef);
+            return buildObserveSuccessResult(session, observeStep, {
+                success: true,
+                observationMode: "goal_assistive_stagehand",
+                pageRef,
+                resolvedBy: "stagehand-observe",
+                ...stagehandRuntimeResolution(stagehandFallbackReason ?? "deterministic-observe-failed"),
+                deterministicObserveError: domPassError ?? undefined,
+                scopes: buildGroupedObserveScopes({
+                    pageRef,
+                    title,
+                    scopes: selectScopesForOutput(observedScopes, targets),
+                    targets,
+                }),
+                signals: compactSignals(pageSignals),
+                fillableForms: compactFillableForms(fillableForms),
+                metrics: session.runtime?.metrics,
+                message: targets.length === 0
+                    ? "This observe pass returned zero targets."
+                    : undefined,
+                url,
+                title,
+            });
+        }
+        catch (err) {
+            const stagehandError = err instanceof Error ? err.message : String(err);
+            const details = domPassError
+                ? `${stagehandError} (deterministic observe failed earlier: ${domPassError})`
+                : stagehandError;
+            return buildObserveContractFailureResult(session, {
+                step: observeStep,
+                error: "observe_failed",
+                outcomeType: "blocked",
+                message: "Observe failed.",
+                reason: details,
+                pageRef,
+                runId: session.activeRunId,
+                stepId: observeStep?.stepId,
+            });
+        }
+        finally {
+            if (browser) {
+                await disconnectPlaywright(browser);
+            }
+        }
+    });
+}
+/** CLI wrapper for `observeBrowser(...)` that persists the observed runtime state. */
+export async function observe(session, instruction) {
+    const result = await observeBrowser(session, instruction);
+    if (result.success) {
+        saveSession(session);
+    }
+    if (result.success) {
+        return outputJSON(result);
+    }
+    const { success: _success, ...failure } = result;
+    return outputContractFailure(failure);
+}

package/dist/commands/screenshot.d.ts

@@ -0,0 +1,37 @@
+/**
+ * browse screenshot [--path <file>] — Capture a screenshot of the current page.
+ */
+import type { BrowserCommandSession } from '../browser-session-state.js';
+/** Stable top-level error codes returned by `screenshot(...)`. */
+export declare const SCREENSHOT_ERROR_CODES: readonly ["browser_connection_failed", "protected_screenshot_blocked", "screenshot_failed"];
+/** Stable outcome categories emitted by `screenshot(...)`. */
+export declare const SCREENSHOT_OUTCOME_TYPES: readonly ["blocked", "protected_exposure_active", "screenshot_captured"];
+export type ScreenshotErrorCode = (typeof SCREENSHOT_ERROR_CODES)[number];
+export type ScreenshotOutcomeType = (typeof SCREENSHOT_OUTCOME_TYPES)[number];
+/** Successful screenshot capture result. */
+export type ScreenshotSuccessResult = {
+    success: true;
+    pageRef: string;
+    path: string;
+    url: string;
+    title: string;
+};
+/** Failed screenshot capture result. */
+export type ScreenshotFailureResult = {
+    success: false;
+    error: ScreenshotErrorCode;
+    outcomeType: Extract<ScreenshotOutcomeType, 'blocked' | 'protected_exposure_active'>;
+    message: string;
+    reason: string;
+    pageRef?: string;
+    fillRef?: string;
+    requestId?: string;
+    activatedAt?: string;
+    exposureReason?: string;
+};
+export type ScreenshotResult = ScreenshotSuccessResult | ScreenshotFailureResult;
+/** Captures a screenshot of the currently active page. */
+export declare function screenshotBrowser(session: BrowserCommandSession, filePath?: string): Promise<ScreenshotResult>;
+/** CLI wrapper for `screenshotBrowser(...)` that persists session changes and writes JSON output. */
+export declare function screenshot(session: BrowserCommandSession, filePath?: string): Promise<void>;
+//# sourceMappingURL=screenshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/commands/screenshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAqBzE,kEAAkE;AAClE,eAAO,MAAM,sBAAsB,6FAIzB,CAAC;AAEX,8DAA8D;AAC9D,eAAO,MAAM,wBAAwB,0EAI3B,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1E,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,4CAA4C;AAC5C,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wCAAwC;AACxC,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,mBAAmB,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC,qBAAqB,EAAE,SAAS,GAAG,2BAA2B,CAAC,CAAC;IACrF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,uBAAuB,CAAC;AAkJjF,0DAA0D;AAC1D,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAwH3B;AAED,qGAAqG;AACrG,wBAAsB,UAAU,CAAC,OAAO,EAAE,qBAAqB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBjG"}