pi-agent-browser-native 0.6.16 → 0.7.0

package/dist/extensions/agent-browser/lib/managed-session-policy-lock.js

@@ -1,12 +1,14 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
-import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
-import { canonicalizeAgentBrowserNamespace, getAgentBrowserSessionIdentityKey } from "./argv-grammar.js";
+import { canonicalizeAgentBrowserNamespace, foldAgentBrowserFilesystemIdentity } from "./argv-grammar.js";
+import { getAgentBrowserSocketDirValidationError, resolveAgentBrowserSocketDir } from "./process.js";
 import { processStartIdentitiesMatch, readProcessStartIdentity } from "./process-identity.js";
 const POLICY_LOCK_WAIT_MS = 1_000;
 const POLICY_LOCK_RETRY_MS = 10;
-const POLICY_LOCK_MAX_BYTES = 4_096;
+const POLICY_LOCK_MAX_BYTES = 1_048_576; // One claim may cover an entire owned-browser cleanup set.
 const LOCK_OWNER_FILE = "owner.json";
 const LOCK_TICKET_FILE = "ticket.json";
 function getCoordinationDirectory(platform = process.platform) {
@@ -43,19 +45,133 @@ async function ensureCoordinationDirectory(path, platform) {
         return false;
     }
 }
-function getPolicyLockDigest(sessionName, namespace) {
-    const identity = getAgentBrowserSessionIdentityKey(sessionName, canonicalizeAgentBrowserNamespace(namespace));
-    return createHash("sha256").update(identity).digest("hex");
+export async function resolveBrowserExecutionIdentity(options) {
+    const socketDir = resolveAgentBrowserSocketDir(options);
+    const namespace = canonicalizeAgentBrowserNamespace(options.namespace);
+    let socketContext;
+    if (process.platform === "win32") {
+        // Native Windows can reach the same namespace/session TCP daemon from
+        // different storage roots. Do not split those callers into separate locks.
+        socketContext = `win32-native:${namespace ?? ""}`;
+    }
+    else {
+        if (socketDir === undefined)
+            throw new Error("Browser execution coordination requires the native socket directory.");
+        const error = await getAgentBrowserSocketDirValidationError(socketDir);
+        if (error)
+            throw new Error(`Browser execution coordination cannot use socket storage: ${error}.`);
+        const root = await realpath(socketDir);
+        socketContext = namespace ? join(root, "namespaces", namespace, "run") : root;
+    }
+    return {
+        socketContext: foldAgentBrowserFilesystemIdentity(socketContext, process.platform),
+        ...(options.sessionName !== undefined ? { sessionName: foldAgentBrowserFilesystemIdentity(options.sessionName, process.platform) } : {}),
+    };
+}
+export function getBrowserExecutionLockPath(identity) {
+    const digest = createHash("sha256").update(identity.socketContext).digest("hex");
+    return join(getCoordinationDirectory(), `.pi-agent-browser-policy-${digest}.lock-v4`);
+}
+function groupExecutionIdentities(identities) {
+    if (identities.length === 0)
+        throw new Error("Browser execution coordination requires at least one identity.");
+    const groups = new Map();
+    for (const { socketContext, sessionName } of identities) {
+        if (sessionName === undefined)
+            groups.set(socketContext, null);
+        else if (groups.get(socketContext) !== null) {
+            const sessions = groups.get(socketContext) ?? new Set();
+            sessions.add(sessionName);
+            groups.set(socketContext, sessions);
+        }
+    }
+    return [...groups.keys()].sort().map(socketContext => {
+        const sessions = groups.get(socketContext);
+        return { socketContext, sessionNames: sessions ? [...sessions].sort() : null };
+    });
+}
+const executionScope = new AsyncLocalStorage();
+function scopeCovers(outer, inner) {
+    return inner.every(identity => outer.some(held => held.socketContext === identity.socketContext
+        && (held.sessionNames === null || identity.sessionNames !== null && identity.sessionNames.every(session => held.sessionNames.includes(session)))));
+}
+/**
+ * Hold across every helper and action (or a complete code cell), not each CLI call.
+ * Nested siblings are serialized; recursive inner calls and managed policy checks borrow
+ * the claims. Declare every old/new identity up front for replacement or multi-browser cleanup;
+ * omit sessionName for close --all. Upgrading mid-operation would allow a lock-order cycle.
+ * Sessions sharing a socket context use ONE set-valued claim: acquiring them separately
+ * could deadlock against a namespace-wide claimant between the first and second session.
+ * Cancellation never releases a still-running callback. The callback must pass its signal
+ * to subprocesses and await their termination; finally drains started children before release.
+ */
+export async function withBrowserExecutionLocks(options, run) {
+    if (!Number.isFinite(options.deadline))
+        throw new Error("Browser execution coordination requires a finite deadline.");
+    const identities = groupExecutionIdentities(options.identities);
+    const parent = executionScope.getStore();
+    if (parent && !parent.active)
+        throw new Error("Browser execution scope has already finished.");
+    if (parent && !scopeCovers(parent.identities, identities))
+        throw new Error("Cannot change or upgrade browser identity inside an execution lock; acquire every required identity before starting.");
+    const controller = new AbortController();
+    const signals = [controller.signal, options.signal, parent?.signal].filter((signal) => signal !== undefined);
+    const signal = AbortSignal.any(signals);
+    const expire = () => controller.abort(new DOMException("Browser execution deadline exceeded.", "TimeoutError"));
+    const remaining = options.deadline - Date.now();
+    const timer = setTimeout(expire, Math.max(0, Math.min(remaining, 2_147_483_647)));
+    const checkBudget = () => {
+        if (Date.now() >= options.deadline)
+            expire();
+        signal.throwIfAborted();
+    };
+    const locks = [];
+    try {
+        checkBudget();
+        if (!parent) {
+            for (const identity of identities) {
+                const lock = await acquireExecutionClaim({ identity, deadline: options.deadline, signal });
+                if (lock)
+                    locks.push(lock);
+                checkBudget();
+                if (!lock)
+                    throw new Error("Browser execution coordination is unavailable or busy; no browser command was run.");
+            }
+        }
+        const execute = async () => {
+            checkBudget();
+            if (options.waitOnly)
+                clearTimeout(timer);
+            const scope = { identities: parent?.identities ?? identities, active: true, signal, children: Promise.resolve() };
+            try {
+                return await executionScope.run(scope, () => run(signal));
+            }
+            finally {
+                scope.active = false;
+                await scope.children;
+            }
+        };
+        if (!parent)
+            return await execute();
+        const result = parent.children.then(execute);
+        parent.children = result.then(() => undefined, () => undefined);
+        return await result;
+    }
+    finally {
+        clearTimeout(timer);
+        await Promise.all(locks.reverse().map(lock => lock.release()));
+    }
 }
-export function getManagedSessionPolicyLockPath(sessionName, namespace) {
-    return join(getCoordinationDirectory(), `.pi-agent-browser-policy-${getPolicyLockDigest(sessionName, namespace)}.lock-v3`);
+export function withBrowserExecutionLock(options, run) {
+    return withBrowserExecutionLocks({ identities: [options.identity], signal: options.signal, deadline: options.deadline, waitOnly: options.waitOnly }, run);
 }
 function parseOwner(content) {
     if (Buffer.byteLength(content) > POLICY_LOCK_MAX_BYTES)
         return undefined;
     try {
         const parsed = JSON.parse(content);
-        return parsed.version === 3
+        return parsed.version === 4
+            && (parsed.sessionNames === null || Array.isArray(parsed.sessionNames) && parsed.sessionNames.length > 0 && parsed.sessionNames.every(session => typeof session === "string"))
             && Number.isSafeInteger(parsed.pid) && (parsed.pid ?? 0) > 0
             && typeof parsed.startIdentity === "string" && parsed.startIdentity.length > 0
             && typeof parsed.token === "string" && parsed.token.length > 0
@@ -71,7 +187,7 @@ function parseTicket(content, token) {
         return undefined;
     try {
         const parsed = JSON.parse(content);
-        return parsed.version === 3
+        return parsed.version === 4
             && parsed.token === token
             && Number.isSafeInteger(parsed.ticket)
             && (parsed.ticket ?? 0) > 0
@@ -150,7 +266,7 @@ async function readClaims(basePath) {
     }
     return claims;
 }
-async function ownerAlive(owner) {
+async function ownerAlive(owner, budget) {
     try {
         process.kill(owner.pid, 0);
     }
@@ -161,7 +277,7 @@ async function ownerAlive(owner) {
         if (code !== "EPERM")
             return undefined;
     }
-    const current = await readProcessStartIdentity(owner.pid);
+    const current = await readProcessStartIdentity(owner.pid, process.platform, budget);
     return current === undefined ? undefined : processStartIdentitiesMatch(owner.startIdentity, current);
 }
 async function removeClaimOwnedBy(path, token, deadline = 0) {
@@ -199,7 +315,7 @@ async function removeClaimOwnedBy(path, token, deadline = 0) {
     await rm(movedPath, { force: true, recursive: true });
     return true;
 }
-async function cleanDeadPolicyArtifacts(directory) {
+async function cleanDeadPolicyArtifacts(directory, budget) {
     let names;
     try {
         names = await readdir(directory);
@@ -208,10 +324,12 @@ async function cleanDeadPolicyArtifacts(directory) {
         return;
     }
     for (const name of names.filter((candidate) => candidate.startsWith(".pi-agent-browser-policy-remove-")
-        || candidate.includes(".lock-v3.candidate-"))) {
+        || candidate.includes(".lock-v4.candidate-"))) {
+        if (budget.signal?.aborted || Date.now() >= (budget.deadline ?? Infinity))
+            return;
         const path = join(directory, name);
         const claim = await readClaim(path);
-        if (claim && await ownerAlive(claim.owner) === false)
+        if (claim && await ownerAlive(claim.owner, budget) === false)
             await rm(path, { force: true, recursive: true }).catch(() => undefined);
     }
 }
@@ -244,23 +362,48 @@ function waitForRetry(signal) {
 export async function acquireManagedSessionPolicyLock(options) {
     if (options.signal?.aborted)
         return undefined;
+    let identity;
+    try {
+        identity = await resolveBrowserExecutionIdentity({ ...options, ownedManagedSession: true });
+    }
+    catch {
+        return undefined;
+    }
+    const scope = executionScope.getStore();
+    if (scope) {
+        if (!scope.active || !scopeCovers(scope.identities, groupExecutionIdentities([identity])))
+            return undefined;
+        return { release: async () => undefined };
+    }
+    return acquireExecutionClaim({ identity: groupExecutionIdentities([identity])[0], signal: options.signal, timeoutMs: options.timeoutMs });
+}
+async function acquireExecutionClaim(options) {
+    if (options.signal?.aborted)
+        return undefined;
+    const deadline = options.deadline ?? Date.now() + (options.timeoutMs ?? POLICY_LOCK_WAIT_MS);
+    // timeoutMs: 0 retains the existing single-attempt policy probe contract.
+    const budget = { signal: options.signal, deadline: options.timeoutMs === 0 ? undefined : deadline };
     const platform = process.platform;
     const directory = getCoordinationDirectory(platform);
     if (!await ensureCoordinationDirectory(directory, platform))
         return undefined;
-    const basePath = getManagedSessionPolicyLockPath(options.sessionName, options.namespace);
+    const basePath = getBrowserExecutionLockPath(options.identity);
     const token = randomUUID();
-    const startIdentity = await readProcessStartIdentity(process.pid);
+    const startIdentity = await readProcessStartIdentity(process.pid, process.platform, budget);
     if (!startIdentity)
         return undefined;
-    const owner = { pid: process.pid, startIdentity, token, version: 3 };
+    const owner = { pid: process.pid, startIdentity, token, sessionNames: options.identity.sessionNames, version: 4 };
+    const ownerContent = JSON.stringify(owner);
+    // Never publish metadata our reader cannot validate and ownership-safely remove.
+    if (Buffer.byteLength(ownerContent) > POLICY_LOCK_MAX_BYTES)
+        return undefined;
     const candidatePath = `${basePath}.candidate-${token}`;
     const claimPath = `${basePath}.claim-${token}`;
     let claimPublished = false;
     let lockAcquired = false;
     try {
         await mkdir(candidatePath, { mode: 0o700 });
-        await writeFile(join(candidatePath, LOCK_OWNER_FILE), JSON.stringify(owner), { encoding: "utf8", flag: "wx", mode: 0o600 });
+        await writeFile(join(candidatePath, LOCK_OWNER_FILE), ownerContent, { encoding: "utf8", flag: "wx", mode: 0o600 });
         await rename(candidatePath, claimPath);
         claimPublished = true;
         const initialClaims = await readClaims(basePath);
@@ -269,11 +412,10 @@ export async function acquireManagedSessionPolicyLock(options) {
         const maxTicket = initialClaims.reduce((max, claim) => claim.ticket === null ? max : Math.max(max, claim.ticket), 0);
         if (!Number.isSafeInteger(maxTicket + 1))
             return undefined;
-        const ticket = { ticket: maxTicket + 1, token, version: 3 };
+        const ticket = { ticket: maxTicket + 1, token, version: 4 };
         const ticketCandidatePath = join(claimPath, `.ticket-${token}.tmp`);
         await writeFile(ticketCandidatePath, JSON.stringify(ticket), { encoding: "utf8", flag: "wx", mode: 0o600 });
         await rename(ticketCandidatePath, join(claimPath, LOCK_TICKET_FILE));
-        const deadline = Date.now() + (options.timeoutMs ?? POLICY_LOCK_WAIT_MS);
         while (!options.signal?.aborted) {
             const claims = await readClaims(basePath);
             if (!claims)
@@ -283,13 +425,15 @@ export async function acquireManagedSessionPolicyLock(options) {
                 return undefined;
             let blocked = false;
             for (const claim of claims) {
-                if (claim.owner.token === token || !claimPrecedes(claim, ownClaim))
+                const disjoint = owner.sessionNames !== null && claim.owner.sessionNames !== null
+                    && !owner.sessionNames.some(session => claim.owner.sessionNames.includes(session));
+                if (claim.owner.token === token || disjoint || !claimPrecedes(claim, ownClaim))
                     continue;
                 // Choosing is transient: a later published ticket must not make
                 // its predecessor wait on it using an earlier null snapshot.
                 if (await hasPublishedLaterTicket(claim, ownClaim))
                     continue;
-                const alive = await ownerAlive(claim.owner);
+                const alive = await ownerAlive(claim.owner, budget);
                 if (alive === false) {
                     await removeClaimOwnedBy(claim.path, claim.owner.token);
                     continue;
@@ -311,7 +455,9 @@ export async function acquireManagedSessionPolicyLock(options) {
                 break;
             }
             if (!blocked) {
-                await cleanDeadPolicyArtifacts(directory);
+                await cleanDeadPolicyArtifacts(directory, budget);
+                if (options.signal?.aborted || (budget.deadline !== undefined && Date.now() >= budget.deadline))
+                    return undefined;
                 lockAcquired = true;
                 return { release: async () => { await removeClaimOwnedBy(claimPath, token, Date.now() + POLICY_LOCK_WAIT_MS); } };
             }

package/dist/extensions/agent-browser/lib/orchestration/browser-run/artifact-paths.js

@@ -2,7 +2,7 @@ import { lstatSync, readlinkSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { foldAgentBrowserFilesystemIdentity } from "../../argv-grammar.js";
 import { parseWaitCommandTokens } from "../../argv-descriptor.js";
-import { getRecordCommandOperands } from "../../command-taxonomy.js";
+import { getRecordCommandOperandIndices, getRecordCommandOperands } from "../../command-taxonomy.js";
 const SCREENSHOT_IMAGE_EXTENSIONS = [".jpeg", ".jpg", ".png", ".webp"];
 function isSingleScreenshotPathToken(token) {
     const explicitlyRelative = token.startsWith("./") || token.startsWith("../");
@@ -38,20 +38,25 @@ export function getScreenshotPathTokenIndex(commandTokens) {
     return undefined;
 }
 const DIFF_SCREENSHOT_VALUE_FLAGS = new Set(["-b", "--baseline", "-o", "--output", "-s", "--selector", "-t", "--threshold"]);
-function getDiffScreenshotOutputPath(commandTokens) {
-    let outputPath;
+export function getDiffFilePathIndices(commandTokens) {
+    if (commandTokens[0] !== "diff" || !["snapshot", "screenshot"].includes(commandTokens[1]))
+        return {};
+    const valueFlags = commandTokens[1] === "screenshot" ? DIFF_SCREENSHOT_VALUE_FLAGS : new Set(["-b", "--baseline", "-s", "--selector", "-d", "--depth"]);
+    const paths = {};
     for (let index = 2; index < commandTokens.length; index += 1) {
         const token = commandTokens[index];
-        if (!DIFF_SCREENSHOT_VALUE_FLAGS.has(token))
+        if (!valueFlags.has(token))
             continue;
         const value = commandTokens[index + 1];
         if (value === undefined)
-            return undefined;
+            return {};
         if (token === "-o" || token === "--output")
-            outputPath = value;
+            paths.output = index + 1;
+        if (token === "-b" || token === "--baseline")
+            paths.baseline = index + 1;
         index += 1;
     }
-    return outputPath;
+    return paths;
 }
 function canonicalizeArtifactPath(absolutePath, platform, seenSymlinks) {
     let cursor = absolutePath;
@@ -102,28 +107,30 @@ export function getRecordContactSheetDestination(commandTokens) {
     const extension = extname(path);
     return extension ? `${path.slice(0, -extension.length)}.contact-sheet.png` : undefined;
 }
-export function getExplicitArtifactDestination(commandTokens) {
+export function getExplicitArtifactDestinationIndex(commandTokens) {
     const command = commandTokens[0];
     const subcommand = commandTokens[1];
-    if (command === "screenshot") {
-        const index = getScreenshotPathTokenIndex(commandTokens);
-        return index === undefined ? undefined : commandTokens[index];
-    }
+    if (command === "screenshot")
+        return getScreenshotPathTokenIndex(commandTokens);
     if (command === "download")
-        return commandTokens[2];
+        return 2;
     if (command === "pdf")
-        return commandTokens[1];
+        return 1;
     if (command === "wait")
-        return parseWaitCommandTokens(commandTokens).downloadPath;
+        return parseWaitCommandTokens(commandTokens).downloadPathIndex;
     if (command === "state" && subcommand === "save")
-        return commandTokens[2];
+        return 2;
     if (command === "diff" && subcommand === "screenshot")
-        return getDiffScreenshotOutputPath(commandTokens);
+        return getDiffFilePathIndices(commandTokens).output;
     if (command === "network" && subcommand === "har" && commandTokens[2] === "stop")
-        return commandTokens[3];
+        return 3;
     if ((command === "trace" || command === "profiler") && subcommand === "stop")
-        return commandTokens[2];
+        return 2;
     if (command === "record")
-        return getRecordCommandOperands(commandTokens).path;
+        return getRecordCommandOperandIndices(commandTokens)[0];
     return undefined;
 }
+export function getExplicitArtifactDestination(commandTokens) {
+    const index = getExplicitArtifactDestinationIndex(commandTokens);
+    return index === undefined ? undefined : commandTokens[index];
+}

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

@@ -432,7 +432,7 @@ export function buildSourceLookupElectronNextActions(sourceLookup) {
     if (sessionName)
         actions.push({ id: "snapshot-electron-session", params: { args: withOptionalSessionArgs(sessionName, ["snapshot", "-i"]) }, reason: "Refresh interactive refs in the attached Electron session before retrying source lookup with a narrower target.", safety: "Read-only snapshot; no app mutation.", tool: "agent_browser" });
     if (launchId)
-        actions.push({ id: "probe-electron-launch", params: { electron: { action: "probe", launchId } }, reason: "Collect bounded wrapper/session context for the packaged Electron launch after sourceLookup found no candidates.", safety: "Read-only probe of title, URL, focus, tabs, and compact snapshot metadata.", tool: "agent_browser" });
+        actions.push({ id: "probe-electron-launch", params: { action: "probe", launchId }, reason: "Collect bounded wrapper/session context for the packaged Electron launch after sourceLookup found no candidates.", safety: "Read-only probe of title, URL, focus, tabs, and compact snapshot metadata.", tool: "agent_browser_electron" });
     if (sessionName)
         actions.push({ id: "list-electron-tabs", params: { args: withOptionalSessionArgs(sessionName, ["tab", "list"]) }, reason: "Check current Electron tabs/targets before choosing a narrower selector or @ref.", safety: "Read-only tab listing.", tool: "agent_browser" });
     return actions;
@@ -863,7 +863,7 @@ export async function collectTimeoutPartialProgress(options) {
     if ((options.commandTokens[0] === "session" && options.commandTokens[1] === "info") || isBrowserIndependentRead(options.commandTokens, options.stdin))
         return undefined;
     const rawSteps = getTimeoutProgressSteps(options.compiledJob, options.commandTokens, options.stdin);
-    const artifacts = await collectTimeoutArtifactEvidence(options.cwd, rawSteps);
+    const artifacts = await collectTimeoutArtifactEvidence(options.operationCwd ?? options.cwd, rawSteps);
     const urlData = await runSessionCommandData({ args: ["get", "url"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName });
     const recoveredUrl = extractStringResultField(urlData, "result") ?? extractStringResultField(urlData, "url");
     const titleData = recoveredUrl
@@ -901,6 +901,18 @@ function sanitizeCurrentPageUrlForTimeoutDiagnostic(url) {
         return redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(url));
     }
 }
+export function redactTimeoutPartialProgress(progress) {
+    const redact = (value) => {
+        if (typeof value === "string")
+            return /^https?:\/\//i.test(value) ? sanitizeCurrentPageUrlForTimeoutDiagnostic(value) : redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(value));
+        if (Array.isArray(value))
+            return value.map(redact);
+        if (isRecord(value))
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redact(item)]));
+        return value;
+    };
+    return redact(progress);
+}
 export function formatTimeoutPartialProgressText(progress, pageTargetUnknown = false) {
     const lines = [`Timeout partial progress: ${progress.summary}`];
     const currentPageTitle = progress.currentPage?.title ? redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(progress.currentPage.title)) : undefined;

package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result.js

@@ -4,6 +4,7 @@ import { redactNetworkSourceLookupSurface } from "../../input-modes/lookups.js";
 import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
 import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
 import { extractAgentBrowserLifecycle } from "../../results/presentation/common.js";
+import { projectAgentBrowserObservation } from "../../results/presentation/content.js";
 import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";
 import { alignPageChangeSummaryNextActionIds, appendUniqueAgentBrowserNextActions, applyNamespaceToNextActions, isStandaloneSnapshotNextAction, withOptionalSessionArgs, } from "../../results/next-actions.js";
 import { buildConnectedSessionNextActions, buildNoActivePageNextActions, buildPendingWebMcpNextActions, buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions, } from "../../results/recovery-next-actions.js";
@@ -86,9 +87,7 @@ export function redactRecoveryHint(recoveryHint) {
 }
 export function buildJsonVisibleContent(options) {
     const { error, presentation, succeeded, warnings } = options;
-    const payload = redactSensitiveValue({ artifacts: presentation.artifacts, data: presentation.data, error, recordingRecovery: presentation.recordingRecovery, readConfirmation: presentation.readConfirmation, success: succeeded, warnings: warnings && warnings.length > 0 ? warnings : undefined });
-    if (isRecord(payload) && isRecord(payload.data) && isRecord(presentation.data) && typeof presentation.data.wsUrl === "string")
-        payload.data.wsUrl = presentation.data.wsUrl;
+    const payload = projectAgentBrowserObservation({ ...presentation, ...options.details, error, warnings: warnings && warnings.length > 0 ? warnings : undefined }, succeeded);
     const images = presentation.content.filter((item) => item.type === "image");
     return [{ type: "text", text: JSON.stringify(payload, null, 2) }, ...images];
 }
@@ -175,8 +174,9 @@ export function buildRedactedPresentationContent(options) {
     return contentWithSessionWarnings.map((item) => {
         if (item.type !== "text")
             return item;
-        const exactRedactedText = redactExactSensitiveText(item.text, exactSensitiveValues);
-        return userRequestedJson && !plainTextInspection ? { ...item, text: exactRedactedText } : { ...item, text: redactSensitiveText(exactRedactedText) };
+        if (userRequestedJson && !plainTextInspection)
+            return { ...item, text: JSON.stringify(redactExactSensitiveValue(JSON.parse(item.text), exactSensitiveValues), null, 2) };
+        return { ...item, text: redactSensitiveText(redactExactSensitiveText(item.text, exactSensitiveValues)) };
     });
 }
 export async function prepareFinalResultRecoveryState(options) {
@@ -339,6 +339,10 @@ function buildResultNextActions(options) {
         append(buildComboboxFocusNextActions(options.executionPlan.sessionName));
     if (options.managedSessionOutcome)
         appendUnique(buildManagedSessionFreshFailureNextActions(options.managedSessionOutcome));
+    if (options.currentSessionTabTargetUnknown && ["aborted", "parse-failure"].includes(options.categoryDetails.failureCategory ?? "")) {
+        nextActions = nextActions.filter(action => !isStandaloneSnapshotNextAction(action));
+        appendUnique([{ id: "verify-page-target-after-interruption", tool: "agent_browser", params: { args: withOptionalSessionArgs(options.executionPlan.sessionName, ["batch", "--bail"]), stdin: JSON.stringify([["get", "url"], ["snapshot", "-i"]]) }, reason: "Verify the current URL and inspect the page after an interrupted operation.", safety: "Read-only recovery. The mutation may already have happened; inspect before deciding whether to retry." }]);
+    }
     if (options.categoryDetails.failureCategory === "timeout" && options.processResult.timedOut) {
         if (options.currentSessionTabTargetUnknown)
             nextActions = nextActions.filter((action) => !isStandaloneSnapshotNextAction(action));
@@ -354,14 +358,11 @@ function buildResultNextActions(options) {
 export function formatAgentBrowserNextActionsText(nextActions) {
     if (!nextActions || nextActions.length === 0)
         return undefined;
-    const lines = nextActions.slice(0, 6).map((action) => {
-        const params = action.params
-            ? { ...action.params, ...(action.params.stdin !== undefined && action.params.stdin.length > 500 ? { stdin: "[omitted; use details.nextActions]" } : {}) }
-            : undefined;
-        const payload = action.artifactPath ? { artifactPath: action.artifactPath } : params;
+    const lines = nextActions.map((action) => {
+        const payload = action.artifactPath ? { artifactPath: action.artifactPath } : action.params;
         return `- ${action.id}${payload ? ` ${redactSensitiveText(JSON.stringify(payload))}` : ""}: ${redactSensitiveText(action.reason)}`;
     });
-    return ["Next actions:", ...lines, "The same redacted payloads are available in details.nextActions."].join("\n");
+    return ["Next actions:", ...lines].join("\n");
 }
 function formatFailureNextActionsText(options, nextActions) {
     return options.categoryDetails.resultCategory === "failure" ? formatAgentBrowserNextActionsText(nextActions) : undefined;
@@ -438,6 +439,7 @@ function buildAgentBrowserResultDetails(options, nextActions) {
         managedSessionOutcome: options.managedSessionOutcome,
         imagePath: options.presentation.imagePath,
         imagePaths: options.presentation.imagePaths,
+        imageObservations: options.presentation.imageObservations,
         nextActions,
         pageChangeSummary,
         clickDispatch: options.clickDispatchDiagnostic,
@@ -485,6 +487,10 @@ export function buildFinalAgentBrowserToolResult(options) {
     const lifecycle = extractAgentBrowserLifecycle(options.presentationEnvelope?.data);
     const browserWindow = buildBrowserWindowStatus(options, lifecycle);
     const details = buildAgentBrowserResultDetails(options, nextActions);
+    if (options.modelVisible === false) {
+        const result = { content: [], details: redactToolDetails(details, options.exactSensitiveValues), isError: !options.succeeded };
+        return options.compiledNetworkSourceLookup ? redactNetworkSourceLookupSurface(result) : result;
+    }
     const visibleRefFallbackText = formatVisibleRefFallbackText(options.visibleRefFallbackDiagnostic);
     const richInputRecoveryText = formatRichInputRecoveryText(options.richInputRecoveryDiagnostic);
     const semanticActionCandidateText = nextActions ? formatSemanticActionCandidateText(nextActions) : undefined;
@@ -509,10 +515,17 @@ export function buildFinalAgentBrowserToolResult(options) {
     const appendedDiagnosticText = redactSensitiveText(redactExactSensitiveText(rawAppendedDiagnosticText, options.exactSensitiveValues));
     const shouldAppendDiagnosticText = appendedDiagnosticText.length > 0 && (!options.userRequestedJson || options.plainTextInspection);
     let content = shouldAppendDiagnosticText && options.redactedContent[0]?.type === "text" ? [{ ...options.redactedContent[0], text: `${options.redactedContent[0].text}\n\n${appendedDiagnosticText}` }, ...options.redactedContent.slice(1)] : options.redactedContent;
-    if (options.electronLaunchRecord && options.succeeded && content[0]?.type === "text") {
+    if (options.electronLaunchRecord && options.succeeded && !options.userRequestedJson && content[0]?.type === "text") {
         content = [{ ...content[0], text: redactSensitiveText(formatElectronLaunchText({ handoff: options.electronHandoff, record: options.electronLaunchRecord, targets: options.electronLaunch?.targets ?? [], upstreamText: content[0].text })) }, ...content.slice(1)];
     }
-    const result = { content, details: redactToolDetails(details, options.exactSensitiveValues), isError: !options.succeeded };
+    const redactedDetails = redactToolDetails(details, options.exactSensitiveValues);
+    if (options.userRequestedJson && !options.plainTextInspection) {
+        const prior = options.redactedContent[0]?.type === "text" ? JSON.parse(options.redactedContent[0].text) : undefined;
+        if (Array.isArray(prior?.warnings))
+            redactedDetails.warnings = prior.warnings;
+        content = buildJsonVisibleContent({ error: redactedDetails.error, details: redactedDetails, presentation: options.presentation, succeeded: options.succeeded, warnings: prior?.warnings });
+    }
+    const result = { content, details: redactedDetails, isError: !options.succeeded };
     return options.compiledNetworkSourceLookup ? redactNetworkSourceLookupSurface(result) : result;
 }
 export function isMissingAgentBrowserBinary(processResult) {

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

@@ -6,6 +6,7 @@ import { formatWebMcpCatalogUpdate } from "../../results/presentation/common.js"
 import { withOwnedManagedSessionContext } from "../../managed-session-restore.js";
 import { cleanupClickDispatchProbe } from "./click-dispatch.js";
 import { applyBrowserRunStatePatch, getSessionContextKey } from "./session-state.js";
+import { buildScreenshotGeometry, collectScreenshotSample } from "./screenshot-observation.js";
 import { buildJsonVisibleContent, buildMissingBinaryFailureResult } from "./final-result.js";
 import { prepareBrowserRun } from "./prepare.js";
 import { processBrowserOutput } from "./process-output.js";
@@ -27,6 +28,12 @@ export async function runAgentBrowserTool(options) {
                 result.content.push({ type: "text", text: notice });
         }
     }
+    if (result.isError && details?.error === undefined) {
+        details = { ...details, error: details?.validationError ?? details?.summary ?? result.content.filter(part => part.type === "text").map(part => part.text).join("\n") };
+        result.details = details;
+    }
+    if (options.modelVisible === false)
+        result.content = [];
     const sessionKey = getSessionContextKey(typeof details?.sessionName === "string" ? details.sessionName : undefined, typeof details?.namespace === "string" ? details.namespace : undefined);
     const page = options.state.sessionPageState.get(sessionKey);
     return page.tabReopenPending === undefined ? result : {
@@ -39,11 +46,12 @@ async function runAgentBrowserToolInContext(options) {
     applyBrowserRunStatePatch(options.state, preparedResult.kind === "ready" ? preparedResult.prepared.statePatch : preparedResult.statePatch);
     if (preparedResult.kind === "early-result") {
         const result = preparedResult.result;
-        if (options.input.toolArgs.includes("--json") && !isPlainTextInspectionArgs(options.input.toolArgs)) {
+        if (options.modelVisible !== false && options.input.toolArgs.includes("--json") && !isPlainTextInspectionArgs(options.input.toolArgs)) {
             const details = isRecord(result.details) ? result.details : {};
             const summary = result.content.filter(item => item.type === "text").map(item => item.text).join("\n");
             result.content = buildJsonVisibleContent({
                 error: result.isError ? details.validationError ?? summary : null,
+                details,
                 presentation: { content: result.content, data: details.data, summary },
                 succeeded: result.isError !== true,
             });
@@ -54,6 +62,11 @@ async function runAgentBrowserToolInContext(options) {
     const ownedManagedSession = prepared.ownedManagedSessionContext;
     return await withOwnedManagedSessionContext(ownedManagedSession, async () => {
         try {
+            const geometryOptions = { command: prepared.commandTokens, cwd: options.cwd, namespace: prepared.executionPlan.namespace, sessionName: prepared.executionPlan.sessionName, signal: options.signal,
+                env: ownedManagedSession ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs } : undefined };
+            // Do not start a cold browser through a probe or consume launch flags ahead of the requested capture.
+            const probeGeometry = prepared.commandTokens[0] === "screenshot" && !!prepared.priorSessionTabTarget && !prepared.priorSessionTabTargetUnknown && !prepared.executionPlan.startupScopedFlags?.length;
+            const before = probeGeometry ? await withChromeStartupArgs(prepared.chromeStartupArgs, () => collectScreenshotSample(geometryOptions)) : undefined;
             const artifactRunStartedAtMs = Date.now();
             const processResult = await withChromeStartupArgs(prepared.chromeStartupArgs, () => runAgentBrowserProcess({
                 args: prepared.processArgs,
@@ -70,6 +83,8 @@ async function runAgentBrowserToolInContext(options) {
                 stdin: prepared.processStdin,
                 timeoutMs: prepared.processTimeoutMs,
             }));
+            const after = probeGeometry && !processResult.aborted && !processResult.timedOut && processResult.exitCode === 0
+                ? await withChromeStartupArgs(prepared.chromeStartupArgs, () => collectScreenshotSample(geometryOptions)) : undefined;
             const missingBinaryResult = await buildMissingBinaryFailureResult({
                 compatibilityWorkaround: prepared.compatibilityWorkaround,
                 electronLaunch: prepared.electronLaunch,
@@ -88,6 +103,11 @@ async function runAgentBrowserToolInContext(options) {
                 return missingBinaryResult;
             const output = await processBrowserOutput({ ...options, artifactRunStartedAtMs, prepared, processResult });
             applyBrowserRunStatePatch(options.state, output.statePatch);
+            if (isRecord(output.result.details) && Array.isArray(output.result.details.imageObservations) && prepared.commandTokens[0] === "screenshot") {
+                output.result.details.imageObservations = redactSensitiveValue(output.result.details.imageObservations.map(image => ({
+                    ...image, geometry: buildScreenshotGeometry({ capture: image.capture, pixels: image.pixels, before, after }),
+                })));
+            }
             return output.result;
         }
         finally {

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

@@ -2,7 +2,7 @@ import { isRecord } from "../../../parsing.js";
 import { buildAgentBrowserResultCategoryDetails } from "../../../results/categories.js";
 import { buildSnapshotPresentation } from "../../../results/snapshot.js";
 import { extractRefSnapshotFromData } from "../../../session-page-state.js";
-import { redactSensitiveText } from "../../../runtime.js";
+import { redactSensitiveText, redactSensitiveValue } from "../../../runtime.js";
 import { collectScrollPositionSnapshot } from "../diagnostics.js";
 import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
 function parseSnapshotFilterRequest(commandTokens) {
@@ -237,7 +237,9 @@ export async function trySnapshotFilter(options) {
     const diff = request.diff ? buildSnapshotDiff(options.previousRefSnapshot, fullSnapshot) : undefined;
     if (fullSnapshot)
         options.sessionPageState.applyRefSnapshot({ sessionName: options.sessionStateKey ?? options.sessionName, snapshot: fullSnapshot, update: options.sessionPageStateUpdate });
-    const presentation = await buildSnapshotPresentation(filtered.data, options.persistentArtifactStore, options.artifactManifest);
+    const presentation = options.modelVisible === false
+        ? { content: [], data: redactSensitiveValue(filtered.data), summary: "Snapshot" }
+        : await buildSnapshotPresentation(filtered.data, options.persistentArtifactStore, options.artifactManifest);
     const summary = request.role || request.search
         ? `Snapshot filter: ${filtered.matchedRefs}/${filtered.totalRefs} direct refs matched${request.role ? ` role=${request.role}` : ""}${request.search ? ` search ${JSON.stringify(request.search)}` : ""}; ${filtered.visibleLines} surrounding snapshot line${filtered.visibleLines === 1 ? "" : "s"} shown.`
         : request.diff

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

@@ -36,8 +36,6 @@ export function normalizeRunInput(input) {
     switch (input.kind) {
         case "electron":
             return { ...base, compiledElectron: input.compiledElectron, redactedCompiledElectron: input.redactedCompiledElectron };
-        case "job":
-            return { ...base, compiledJob: input.compiledJob, redactedCompiledJob: input.redactedCompiledJob };
         case "networkSourceLookup":
             return { ...base, compiledNetworkSourceLookup: input.compiledNetworkSourceLookup, redactedCompiledNetworkSourceLookup: input.redactedCompiledNetworkSourceLookup };
         case "qa":
@@ -46,7 +44,6 @@ export function normalizeRunInput(input) {
             return { ...base, compiledSemanticAction: input.compiledSemanticAction, redactedCompiledSemanticAction: input.redactedCompiledSemanticAction };
         case "sourceLookup":
             return { ...base, compiledSourceLookup: input.compiledSourceLookup, redactedCompiledSourceLookup: input.redactedCompiledSourceLookup };
-        case "script":
         case "args":
             return base;
     }
@@ -937,6 +934,7 @@ export async function prepareBrowserRun(options) {
             }
             const persistentArtifactStore = getPersistentSessionArtifactStore(options.ctx);
             const snapshotFilter = await trySnapshotFilter({
+                modelVisible: options.modelVisible,
                 artifactManifest: state.artifactManifest,
                 commandTokens,
                 compatibilityWorkaround,