pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/browser-run/native-helper-observation.js

@@ -0,0 +1,65 @@
+import { getAgentBrowserSessionIdentityKey, resolveAgentBrowserNamespace, } from "../../argv-grammar.js";
+import { parseArgvDescriptor } from "../../argv-descriptor.js";
+import { isBrowserIndependentRead, needsManagedSession } from "../../command-policy.js";
+import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { nextReadConfirmation, parseReadConfirmation } from "../../read-confirmation.js";
+import { nativePolicyDefinitelyUnestablished, } from "./session-state.js";
+function helperNamespace(helper) {
+    return resolveAgentBrowserNamespace([], helper.namespace ?? getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+}
+function helperMayRun(helper, effects) {
+    const pending = parseReadConfirmation(effects?.readConfirmation);
+    return ((!needsManagedSession(parseArgvDescriptor(helper.args), helper.stdin) &&
+        !isBrowserIndependentRead(helper.args, helper.stdin)) ||
+        pending?.state !== "pending" ||
+        getAgentBrowserSessionIdentityKey(helper.sessionName ?? "default", helperNamespace(helper)) !==
+            getAgentBrowserSessionIdentityKey(pending.sessionName, pending.namespace));
+}
+function helperSucceeded(observation) {
+    return (observation.envelope?.success === true &&
+        observation.processResult.exitCode === 0 &&
+        !observation.processResult.aborted &&
+        !observation.processResult.timedOut);
+}
+function markPendingOpenTargetUnknown(state, update, key) {
+    const invalidation = state.sessionPageState.get(key).refSnapshotInvalidation;
+    state.sessionPageState.markTabTargetUnknown({ sessionName: key, update });
+    if (invalidation) {
+        state.sessionPageState.applyRefSnapshotInvalidation({ sessionName: key, update, invalidation });
+    }
+}
+function applyHelperConfirmation(state, update, observation) {
+    const { helper, envelope, processResult } = observation;
+    const namespace = helperNamespace(helper);
+    const sessionName = helper.sessionName ?? "default";
+    const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+    if (key === state.confirmationPolicyIdentity &&
+        !nativePolicyDefinitelyUnestablished(processResult, envelope, helper.args)) {
+        state.confirmationPolicyMayBeEstablished = true;
+    }
+    const confirmation = nextReadConfirmation({
+        commandTokens: helper.args,
+        current: state.sessionPageState.getReadConfirmation(key),
+        data: envelope?.data,
+        namespace,
+        sessionName,
+        succeeded: helperSucceeded(observation),
+    });
+    if (!confirmation) {
+        return;
+    }
+    state.sessionPageState.applyReadConfirmation(confirmation, update);
+    if (helper.args[0] === "open" && confirmation.state === "pending") {
+        markPendingOpenTargetUnknown(state, update, key);
+    }
+    state.observedBrowserEffects = {
+        ...state.observedBrowserEffects,
+        readConfirmation: confirmation,
+    };
+}
+export function createNativeHelperObserver(state, update) {
+    return {
+        allow: (helper) => helperMayRun(helper, state.observedBrowserEffects),
+        observe: (helper, processResult, envelope) => applyHelperConfirmation(state, update, { helper, processResult, envelope }),
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/observation-types.js

@@ -0,0 +1 @@
+export {};

package/dist/extensions/agent-browser/lib/orchestration/browser-run/overlay-diagnostics.js

@@ -0,0 +1,120 @@
+import { isRecord } from "../../parsing.js";
+import { buildInspectOverlayStateAction, withOptionalSessionArgs, } from "../../results/next-actions.js";
+import { extractRefSnapshotFromData, normalizeComparableUrl, } from "../../session-page-state.js";
+import { rawStringField } from "./diagnostic-values.js";
+import { runSessionCommandData } from "./session-state.js";
+const OVERLAY_CLOSE_NAME_PATTERN = /(?:\b(?:close|dismiss|no thanks|not now|maybe later|hide|skip|continue without|x)\b|^\s*×\s*$)/i;
+const OVERLAY_CONTEXT_ROLES = new Set(["alertdialog", "dialog"]);
+const OVERLAY_ACTION_ROLES = new Set(["button", "link", "menuitem"]);
+const OVERLAY_BLOCKER_CANDIDATE_LIMIT = 3;
+function overlayBlockerCandidate(ref, entry) {
+    if (!/^e\d+$/.test(ref) || !isRecord(entry)) {
+        return undefined;
+    }
+    const role = rawStringField(entry, "role");
+    const name = rawStringField(entry, "name");
+    if (role === undefined ||
+        role === "" ||
+        !OVERLAY_ACTION_ROLES.has(role.toLowerCase()) ||
+        name === undefined ||
+        name === "" ||
+        !OVERLAY_CLOSE_NAME_PATTERN.test(name)) {
+        return undefined;
+    }
+    return {
+        args: ["click", `@${ref}`],
+        name,
+        reason: `Visible ${role} ${JSON.stringify(name)} appears in a snapshot that also contains overlay/banner/dialog context.`,
+        ref: `@${ref}`,
+        role,
+    };
+}
+function getOverlayBlockerCandidates(snapshotData) {
+    const refs = isRecord(snapshotData) && isRecord(snapshotData.refs) ? snapshotData.refs : undefined;
+    if (!refs ||
+        !Object.values(refs).some((entry) => isRecord(entry) &&
+            OVERLAY_CONTEXT_ROLES.has((rawStringField(entry, "role") ?? "").toLowerCase()))) {
+        return [];
+    }
+    const candidates = [];
+    for (const [ref, entry] of Object.entries(refs)) {
+        const candidate = overlayBlockerCandidate(ref, entry);
+        if (candidate) {
+            candidates.push(candidate);
+        }
+        if (candidates.length >= OVERLAY_BLOCKER_CANDIDATE_LIMIT) {
+            break;
+        }
+    }
+    return candidates;
+}
+export function formatOverlayBlockerText(diagnostic) {
+    return [
+        "Possible overlay blockers:",
+        ...diagnostic.candidates.map((candidate) => {
+            const role = candidate.role !== undefined && candidate.role !== "" ? ` ${candidate.role}` : "";
+            const name = candidate.name !== undefined && candidate.name !== ""
+                ? ` ${JSON.stringify(candidate.name)}`
+                : "";
+            return `- ${candidate.ref}${role}${name}: ${candidate.reason}`;
+        }),
+    ].join("\n");
+}
+export function buildOverlayBlockerNextActions(options) {
+    return [
+        buildInspectOverlayStateAction(options.sessionName),
+        ...options.diagnostic.candidates.map((candidate, index) => ({
+            id: `try-overlay-blocker-candidate-${index + 1}`,
+            params: { args: withOptionalSessionArgs(options.sessionName, candidate.args) },
+            reason: candidate.reason,
+            safety: "Only click this if the candidate is clearly a close/dismiss control for an overlay that blocks the intended workflow.",
+            tool: "agent_browser",
+        })),
+    ];
+}
+export function collectSnapshotOverlayBlockerDiagnostic(data) {
+    const candidates = getOverlayBlockerCandidates(data);
+    const snapshot = extractRefSnapshotFromData(data);
+    return candidates.length === 0 || !snapshot
+        ? undefined
+        : {
+            candidates,
+            snapshot,
+            summary: "Snapshot contains dialog/modal context plus likely close or dismiss controls; treat covered controls as potentially obstructed until the overlay state is resolved.",
+        };
+}
+function isSnapshotRefClick(data) {
+    return (isRecord(data) &&
+        typeof data.clicked === "string" &&
+        (data.clicked.startsWith("@") || data.clicked.startsWith("ref=")));
+}
+function stationaryRefClickUrl(options) {
+    if (options.command !== "click" || !isSnapshotRefClick(options.data)) {
+        return undefined;
+    }
+    const priorUrl = normalizeComparableUrl(options.priorTarget?.url);
+    const currentUrl = normalizeComparableUrl(options.navigationSummary?.url);
+    return currentUrl !== undefined && currentUrl !== "" && currentUrl === priorUrl
+        ? currentUrl
+        : undefined;
+}
+export async function collectOverlayBlockerDiagnostic(options) {
+    const currentUrl = stationaryRefClickUrl(options);
+    if (currentUrl === undefined) {
+        return undefined;
+    }
+    const snapshotData = await runSessionCommandData({
+        args: ["snapshot", "-i"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    });
+    const diagnostic = collectSnapshotOverlayBlockerDiagnostic(snapshotData);
+    return diagnostic
+        ? {
+            ...diagnostic,
+            summary: `Click completed but the page stayed on ${currentUrl}; a fresh snapshot contains likely overlay close/dismiss controls.`,
+        }
+        : undefined;
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/network-page-filter.js

@@ -1,11 +1,12 @@
 import { isRecord } from "../../../parsing.js";
 import { buildAgentBrowserResultCategoryDetails } from "../../../results/categories.js";
 import { redactPresentationData } from "../../../results/presentation/diagnostics.js";
-import { redactInvocationArgs, redactSensitiveText } from "../../../runtime.js";
+import { redactInvocationArgs, redactSensitiveText } from "../../../runtime-redaction.js";
 import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
 function parseNetworkRequestsPageFilterRequest(commandTokens) {
-    if (commandTokens[0] !== "network" || commandTokens[1] !== "requests")
+    if (commandTokens[0] !== "network" || commandTokens[1] !== "requests") {
         return undefined;
+    }
     const cleanArgs = [];
     let mode;
     for (const token of commandTokens) {
@@ -19,36 +20,44 @@ function parseNetworkRequestsPageFilterRequest(commandTokens) {
         }
         cleanArgs.push(token);
     }
-    if (!mode)
+    if (mode === undefined) {
         return undefined;
+    }
     return { cleanArgs, mode };
 }
 function extractCurrentUrl(data) {
-    if (typeof data === "string")
+    if (typeof data === "string") {
         return data;
-    if (!isRecord(data))
+    }
+    if (!isRecord(data)) {
         return undefined;
+    }
     const candidates = [data.url, data.currentUrl, data.href, data.result];
-    for (const candidate of candidates)
-        if (typeof candidate === "string" && candidate.length > 0)
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.length > 0) {
             return candidate;
+        }
+    }
     return undefined;
 }
 function getRequestUrl(row) {
-    if (!isRecord(row))
+    if (!isRecord(row)) {
         return undefined;
+    }
     const candidate = row.url ?? row.requestUrl ?? row.href;
     return typeof candidate === "string" ? candidate : undefined;
 }
 function requestMatchesCurrentPage(row, currentUrl, mode) {
     const requestUrl = getRequestUrl(row);
-    if (!requestUrl)
+    if (requestUrl === undefined || requestUrl === "") {
         return false;
+    }
     try {
         const current = new URL(currentUrl);
         const request = new URL(requestUrl, current);
-        if (mode === "origin")
+        if (mode === "origin") {
             return current.origin === request.origin;
+        }
         const currentComparable = `${current.origin}${current.pathname}`;
         const requestComparable = `${request.origin}${request.pathname}`;
         return requestComparable === currentComparable;
@@ -58,49 +67,123 @@ function requestMatchesCurrentPage(row, currentUrl, mode) {
     }
 }
 function filterNetworkRequestsData(data, currentUrl, request) {
-    if (!isRecord(data))
+    if (!isRecord(data)) {
         return undefined;
-    const requestRows = Array.isArray(data.requests) ? data.requests : Array.isArray(data.items) ? data.items : Array.isArray(data.entries) ? data.entries : undefined;
-    if (!requestRows)
+    }
+    const key = ["requests", "items", "entries"].find((name) => Array.isArray(data[name]));
+    if (key === undefined) {
+        return undefined;
+    }
+    const requestRows = data[key];
+    if (!Array.isArray(requestRows)) {
         return undefined;
+    }
     const rows = requestRows.filter((row) => requestMatchesCurrentPage(row, currentUrl, request.mode));
-    const key = Array.isArray(data.requests) ? "requests" : Array.isArray(data.items) ? "items" : "entries";
-    return { data: { ...data, [key]: rows }, matchedRows: rows.length, rows, totalRows: requestRows.length };
+    return {
+        data: { ...data, [key]: rows },
+        matchedRows: rows.length,
+        rows,
+        totalRows: requestRows.length,
+    };
 }
 function formatNetworkRequestRow(row) {
-    if (!isRecord(row))
-        return redactSensitiveText(String(row));
+    if (!isRecord(row)) {
+        return redactSensitiveText(formatNetworkValue(row));
+    }
     const status = row.status ?? row.statusCode ?? row.responseStatus ?? "?";
-    const method = typeof row.method === "string" ? row.method : typeof row.requestMethod === "string" ? row.requestMethod : "?";
-    const id = typeof row.id === "string" ? ` id=${row.id}` : typeof row.requestId === "string" ? ` id=${row.requestId}` : "";
+    const method = [row.method, row.requestMethod].find((value) => typeof value === "string") ?? "?";
+    const identifier = [row.id, row.requestId].find((value) => typeof value === "string");
+    const id = identifier === undefined ? "" : ` id=${identifier}`;
     const url = getRequestUrl(row) ?? "(no url)";
-    return redactSensitiveText(`- ${status} ${method}${id} ${url}`);
+    return redactSensitiveText(`- ${formatNetworkValue(status)} ${method}${id} ${url}`);
+}
+function formatNetworkValue(value) {
+    switch (typeof value) {
+        case "string":
+        case "number":
+        case "bigint":
+        case "boolean":
+        case "undefined":
+        case "symbol":
+        case "function":
+            return String(value);
+        case "object":
+            if (value === null) {
+                return "null";
+            }
+            return Array.isArray(value)
+                ? value.map(formatNetworkArrayElement).join(",")
+                : Object.prototype.toString.call(value);
+    }
+}
+function formatNetworkArrayElement(value) {
+    return value === null || value === undefined ? "" : formatNetworkValue(value);
+}
+function formatFilteredNetworkText(options) {
+    const preview = options.rows.slice(0, 12).map(formatNetworkRequestRow);
+    const omitted = options.rows.length > preview.length
+        ? [`- …${options.rows.length - preview.length} more matching rows omitted`]
+        : [];
+    return [
+        redactSensitiveText(options.summary),
+        `Current page: ${redactSensitiveText(options.currentUrl)}`,
+        ...preview,
+        ...omitted,
+    ].join("\n");
 }
 export async function tryNetworkRequestsPageFilter(options) {
     const request = parseNetworkRequestsPageFilterRequest(options.commandTokens);
-    if (!request || !options.sessionName)
+    if (!request || options.sessionName === undefined || options.sessionName === "") {
         return undefined;
-    const currentUrl = extractCurrentUrl(await runSessionCommandData({ args: ["get", "url"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal }));
-    if (!currentUrl)
+    }
+    const currentUrl = extractCurrentUrl(await runSessionCommandData({
+        args: ["get", "url"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    }));
+    if (currentUrl === undefined || currentUrl === "") {
         return undefined;
-    const networkData = await runSessionCommandData({ args: request.cleanArgs, cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal });
+    }
+    const networkData = await runSessionCommandData({
+        args: request.cleanArgs,
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    });
     const filtered = filterNetworkRequestsData(networkData, currentUrl, request);
-    if (!filtered)
+    if (!filtered) {
         return undefined;
+    }
     const summary = `Network requests filtered to current ${request.mode === "origin" ? "origin" : "URL"}: ${filtered.matchedRows}/${filtered.totalRows} rows matched.`;
-    const preview = filtered.rows.slice(0, 12).map(formatNetworkRequestRow);
-    const omitted = filtered.rows.length > preview.length ? [`- …${filtered.rows.length - preview.length} more matching rows omitted`] : [];
     return {
-        content: [{ type: "text", text: [redactSensitiveText(summary), `Current page: ${redactSensitiveText(currentUrl)}`, ...preview, ...omitted].join("\n") }],
+        content: [
+            {
+                type: "text",
+                text: formatFilteredNetworkText({ summary, currentUrl, rows: filtered.rows }),
+            },
+        ],
         details: {
             args: options.redactedArgs,
             command: "network",
             compatibilityWorkaround: options.compatibilityWorkaround,
             data: redactPresentationData({ command: "network", subcommand: "requests" }, filtered.data),
             effectiveArgs: options.effectiveArgs,
-            networkRequestsPageFilter: { cleanArgs: redactInvocationArgs(request.cleanArgs), currentUrl: redactSensitiveText(currentUrl), matchedRows: filtered.matchedRows, mode: request.mode, totalRows: filtered.totalRows },
+            networkRequestsPageFilter: {
+                cleanArgs: redactInvocationArgs(request.cleanArgs),
+                currentUrl: redactSensitiveText(currentUrl),
+                matchedRows: filtered.matchedRows,
+                mode: request.mode,
+                totalRows: filtered.totalRows,
+            },
             sessionMode: options.sessionMode,
-            ...buildAgentBrowserResultCategoryDetails({ args: options.effectiveArgs, command: "network", succeeded: true }),
+            ...buildAgentBrowserResultCategoryDetails({
+                args: options.effectiveArgs,
+                command: "network",
+                succeeded: true,
+            }),
             ...buildSessionDetailFields(options.sessionName, options.usedImplicitSession, options.namespace, options.managedSessionRestoreDisabled()),
             summary,
         },

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/scroll-shims.js

@@ -1,18 +1,24 @@
 import { isRecord } from "../../../parsing.js";
 import { buildAgentBrowserResultCategoryDetails } from "../../../results/categories.js";
 import { applyNamespaceToNextActions } from "../../../results/next-actions.js";
-import { buildScrollNoopNextActions } from "../diagnostics.js";
+import { buildScrollNoopNextActions } from "../interaction-diagnostics.js";
 import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
 const SCROLL_CONTAINER_DIRECTIONS = new Set(["down", "left", "right", "up"]);
 function getContainerScrollRequest(commandTokens) {
-    if (commandTokens[0] !== "scroll" || commandTokens.length < 3)
+    if (commandTokens[0] !== "scroll" || commandTokens.length < 3) {
         return undefined;
+    }
     const selector = commandTokens[1];
     const direction = commandTokens[2]?.toLowerCase();
-    if (!selector || selector.startsWith("-") || selector.startsWith("@") || SCROLL_CONTAINER_DIRECTIONS.has(selector.toLowerCase()))
+    if (selector === "" ||
+        selector.startsWith("-") ||
+        selector.startsWith("@") ||
+        SCROLL_CONTAINER_DIRECTIONS.has(selector.toLowerCase())) {
         return undefined;
-    if (!SCROLL_CONTAINER_DIRECTIONS.has(direction))
+    }
+    if (!SCROLL_CONTAINER_DIRECTIONS.has(direction)) {
         return undefined;
+    }
     return { amount: commandTokens[3], direction, selector };
 }
 function buildContainerScrollScript(request) {
@@ -53,10 +59,18 @@ function buildScrollResult(options) {
             data: options.result,
             effectiveArgs: options.effectiveArgs,
             exitCode: options.succeeded ? 0 : 1,
-            nextActions: options.succeeded ? undefined : applyNamespaceToNextActions(buildScrollNoopNextActions(options.sessionName), options.namespace),
+            nextActions: options.succeeded
+                ? undefined
+                : applyNamespaceToNextActions(buildScrollNoopNextActions(options.sessionName), options.namespace),
             [options.scrollField]: options.scrollValue,
             sessionMode: options.sessionMode,
-            ...buildAgentBrowserResultCategoryDetails({ args: options.effectiveArgs, command: options.command, errorText: options.succeeded ? undefined : options.message, succeeded: options.succeeded, validationError: options.succeeded ? undefined : options.message }),
+            ...buildAgentBrowserResultCategoryDetails({
+                args: options.effectiveArgs,
+                command: options.command,
+                errorText: options.succeeded ? undefined : options.message,
+                succeeded: options.succeeded,
+                validationError: options.succeeded ? undefined : options.message,
+            }),
             ...buildSessionDetailFields(options.sessionName, options.usedImplicitSession, options.namespace, options.managedSessionRestoreDisabled()),
             summary: options.message,
             validationError: options.succeeded ? undefined : options.message,
@@ -64,40 +78,87 @@ function buildScrollResult(options) {
         isError: !options.succeeded,
     };
 }
+function getScrollResult(data) {
+    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
+    return isRecord(result) && typeof result.status === "string"
+        ? { ...result, status: result.status }
+        : undefined;
+}
+function describeScrollAmount(amount) {
+    return amount !== undefined && amount !== "" ? ` by ${amount}` : "";
+}
 export async function tryContainerScroll(options) {
     const request = getContainerScrollRequest(options.commandTokens);
-    if (!request || !options.sessionName)
+    if (!request || (options.sessionName ?? "") === "") {
         return undefined;
-    const data = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, stdin: buildContainerScrollScript(request) });
-    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
-    if (!isRecord(result) || typeof result.status !== "string")
+    }
+    const data = await runSessionCommandData({
+        args: ["eval", "--stdin"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+        stdin: buildContainerScrollScript(request),
+    });
+    const result = getScrollResult(data);
+    if (!result) {
         return undefined;
+    }
     const succeeded = result.status === "scrolled";
     const message = succeeded
-        ? `Scrolled container ${request.selector} ${request.direction}${request.amount ? ` by ${request.amount}` : ""}.`
+        ? `Scrolled container ${request.selector} ${request.direction}${describeScrollAmount(request.amount)}.`
         : `Scroll container ${request.selector} did not move (${result.status}).`;
-    return buildScrollResult({ ...options, command: "scroll", message, result, scrollField: "scrollContainer", scrollValue: { request, result }, succeeded });
+    return buildScrollResult({
+        ...options,
+        command: "scroll",
+        message,
+        result,
+        scrollField: "scrollContainer",
+        scrollValue: { request, result },
+        succeeded,
+    });
+}
+function isPageScrollDirection(direction) {
+    return (direction === "down" || direction === "left" || direction === "right" || direction === "up");
+}
+function isValidScrollAmount(amount) {
+    if (amount === undefined || amount === "") {
+        return true;
+    }
+    return /^\d+(?:\.\d+)?(?:px|%)?$/.test(amount) && Number(amount.replace(/(?:px|%)$/, "")) > 0;
+}
+function describePageScroll(request) {
+    if ("target" in request) {
+        return `to ${request.target}`;
+    }
+    return `${request.direction}${describeScrollAmount(request.amount)}`;
 }
 function getPageScrollToRequest(commandTokens) {
-    if (commandTokens[0] !== "scroll")
+    if (commandTokens[0] !== "scroll") {
         return undefined;
+    }
     if (commandTokens[1]?.toLowerCase() === "to") {
-        const target = commandTokens[2]?.toLowerCase();
-        return target === "end" || target === "top" ? { target } : undefined;
+        return getPageScrollTarget(commandTokens.at(2));
     }
     const direction = commandTokens[1]?.toLowerCase();
-    if (!SCROLL_CONTAINER_DIRECTIONS.has(direction) || commandTokens.length > 3)
+    if (!isPageScrollDirection(direction) || commandTokens.length > 3) {
         return undefined;
-    const amount = commandTokens[2];
-    if (amount && (!/^\d+(?:\.\d+)?(?:px|%)?$/.test(amount) || Number(amount.replace(/(?:px|%)$/, "")) <= 0))
+    }
+    const amount = commandTokens.at(2);
+    if (!isValidScrollAmount(amount)) {
         return undefined;
-    return { amount, direction: direction };
+    }
+    return { amount, direction };
+}
+function getPageScrollTarget(token) {
+    const target = token?.toLowerCase();
+    return target === "end" || target === "top" ? { target } : undefined;
 }
 function buildPageScrollToScript(request) {
     return `(() => {
   const target = ${JSON.stringify("target" in request ? request.target : undefined)};
   const direction = ${JSON.stringify("direction" in request ? request.direction : undefined)};
-  const amountToken = ${JSON.stringify("amount" in request ? request.amount ?? "" : "")};
+  const amountToken = ${JSON.stringify("amount" in request ? (request.amount ?? "") : "")};
   const request = target ? { target } : { direction, amount: amountToken || undefined };
   const scroller = document.scrollingElement || document.documentElement || document.body;
   if (!scroller) return { status: "no-scroller", ...request };
@@ -129,16 +190,36 @@ function buildPageScrollToScript(request) {
 }
 export async function tryPageScrollTo(options) {
     const request = getPageScrollToRequest(options.commandTokens);
-    if (!request || !options.sessionName)
+    if (!request || (options.sessionName ?? "") === "") {
         return undefined;
-    const data = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, stdin: buildPageScrollToScript(request) });
-    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
-    if (!isRecord(result) || typeof result.status !== "string")
+    }
+    const data = await runSessionCommandData({
+        args: ["eval", "--stdin"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+        stdin: buildPageScrollToScript(request),
+    });
+    const result = getScrollResult(data);
+    if (!result) {
         return undefined;
+    }
     const succeeded = result.status === "scrolled";
-    if (!succeeded && "direction" in request)
+    if (!succeeded && "direction" in request) {
         return undefined;
-    const description = "target" in request ? `to ${request.target}` : `${request.direction}${request.amount ? ` by ${request.amount}` : ""}`;
-    const message = succeeded ? `Scrolled page ${description}.` : `Scroll ${description} completed with no observed movement (${result.status}).`;
-    return buildScrollResult({ ...options, command: "scroll", message, result, scrollField: "scrollPage", scrollValue: { request, result }, succeeded });
+    }
+    const description = describePageScroll(request);
+    const message = succeeded
+        ? `Scrolled page ${description}.`
+        : `Scroll ${description} completed with no observed movement (${result.status}).`;
+    return buildScrollResult({
+        ...options,
+        command: "scroll",
+        message,
+        result,
+        scrollField: "scrollPage",
+        scrollValue: { request, result },
+        succeeded,
+    });
 }