pi-agent-browser-native 0.2.77 → 0.5.0

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

@@ -1,12 +1,14 @@
 import { rm } from "node:fs/promises";
+import { getAgentBrowserSessionIdentityKey, VALUE_FLAGS } from "../../argv-grammar.js";
 import { runAgentBrowserProcess } from "../../process.js";
-import { buildAgentBrowserNextActions, parseAgentBrowserEnvelope } from "../../results.js";
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { parseAgentBrowserEnvelope } from "../../results/envelope.js";
 import { buildNextToolAction, withOptionalNamespaceArgs, withOptionalSessionArgs } from "../../results/next-actions.js";
 import { getSessionPageStateKey, isAboutBlankUrl, normalizeComparableUrl, normalizeSessionTabTarget, targetsMatch, } from "../../session-page-state.js";
 import { isCloseCommand, isElectronPostCommandHealthCommand, isNavigationObservableCommandName, isRefGuardedCommand, isRefInvalidatingBatchCommand, isSessionTabPinningExcludedCommand, isSessionTabPostCommandCorrectionExcludedCommand, } from "../../command-taxonomy.js";
 import { chooseOpenResultTabCorrection } from "../../runtime.js";
 import { isRecord } from "../../parsing.js";
-import { parseUserBatchStdin } from "../batch-stdin.js";
+import { getUpstreamEffectiveBatchSteps, parseUserBatchStdin } from "../batch-stdin.js";
 export const NAVIGATION_SUMMARY_EVAL = `({ title: document.title, url: location.href })`;
 export function applyBrowserRunStatePatch(state, patch) {
     if (!patch)
@@ -21,6 +23,10 @@ export function applyBrowserRunStatePatch(state, patch) {
         state.managedSessionActive = patch.managedSessionActive;
     if ("managedSessionCompatibilityWorkaround" in patch)
         state.managedSessionCompatibilityWorkaround = patch.managedSessionCompatibilityWorkaround;
+    if (patch.managedSessionHeadedAutosaveDisabled !== undefined)
+        state.managedSessionHeadedAutosaveDisabled = patch.managedSessionHeadedAutosaveDisabled;
+    if ("managedSessionHeadedAutosaveInterval" in patch)
+        state.managedSessionHeadedAutosaveInterval = patch.managedSessionHeadedAutosaveInterval;
     if (patch.managedSessionCwd !== undefined)
         state.managedSessionCwd = patch.managedSessionCwd;
     if (patch.managedSessionName !== undefined)
@@ -33,7 +39,7 @@ export function applyBrowserRunStatePatch(state, patch) {
 export const getSessionContextKey = getSessionPageStateKey;
 export function buildSessionDetailFields(sessionName, usedImplicitSession, namespace, managedSessionRestoreDisabled = false) {
     return {
-        ...(namespace ? { namespace } : {}),
+        ...(namespace !== undefined ? { namespace } : {}),
         ...(sessionName
             ? {
                 sessionName,
@@ -136,6 +142,12 @@ function formatManagedSessionOutcomeRecoveryGuidance(outcome) {
 export function formatManagedSessionOutcomeText(outcome) {
     if (!outcome)
         return undefined;
+    if (outcome.replacedSessionClosed === false) {
+        const cleanupWarning = "Cleanup warning: Automatic close of the previous wrapper-managed session failed, so it remains wrapper-owned. Use details.managedSessionOutcome for its exact identity and close it explicitly when safe.";
+        return outcome.succeeded
+            ? ["Managed session outcome: The fresh browser became current.", cleanupWarning].join("\n")
+            : [formatManagedSessionOutcomeHeadline(outcome), formatManagedSessionOutcomeRecoveryGuidance(outcome), cleanupWarning].join("\n");
+    }
     if (outcome.status === "closed" && outcome.succeeded) {
         return [
             "Managed session outcome: The current wrapper-managed browser session was closed.",
@@ -202,10 +214,15 @@ export function getTraceOwnerGuardMessage(options) {
         : `Wrapper believes tracing for session ${options.sessionName} is owned by ${activeOwner}; run ${activeOwner} stop instead of ${owner} stop.`;
 }
 export function updateTraceOwnerState(options) {
-    const owner = getTraceOwner(options.command);
-    if (!owner || !options.sessionName || !options.succeeded) {
+    if (!options.sessionName || !options.succeeded)
+        return;
+    if (isCloseCommand(options.command)) {
+        options.traceOwners.delete(options.sessionName);
         return;
     }
+    const owner = getTraceOwner(options.command);
+    if (!owner)
+        return;
     if (options.subcommand === "start") {
         options.traceOwners.set(options.sessionName, owner);
     }
@@ -237,8 +254,6 @@ export function extractNavigationSummaryFromData(data) {
 export function shouldCaptureNavigationSummary(command, data) {
     if (command === "eval")
         return true;
-    if (isRecord(data) && typeof data.clicked === "string" && !data.clicked.startsWith("@") && !data.clicked.startsWith("ref=") && typeof data.href !== "string")
-        return false;
     return (isNavigationObservableCommandName(command) &&
         (!isRecord(data) || (typeof data.title !== "string" && typeof data.url !== "string")));
 }
@@ -258,29 +273,42 @@ function extractBatchResultCommand(item) {
     return Array.isArray(item.command) ? item.command.filter((token) => typeof token === "string") : [];
 }
 export function getStaleRefArgs(commandTokens, stdin) {
-    if (commandTokens[0] !== "batch" || stdin === undefined) {
-        return commandTokens;
-    }
-    const parsed = parseUserBatchStdin(stdin);
-    if (parsed.error || parsed.steps === undefined) {
+    if (commandTokens[0] !== "batch") {
         return commandTokens;
     }
-    return parsed.steps.flatMap((step) => step);
+    const steps = getUpstreamEffectiveBatchSteps(commandTokens, stdin);
+    return steps.length > 0 ? steps.flatMap((step) => step) : commandTokens;
+}
+// Selector-carrying flags whose values remain page-scoped refs; values of other value-taking flags
+// (--text, --baseline, --name, and similar) are literal text or paths that may merely look like refs,
+// per upstream parsing. Boolean flags such as --new-tab or --full do not consume the following token,
+// so a ref after them is a genuine positional selector and must stay guarded.
+const SELECTOR_FLAG_TOKENS = new Set(["--selector", "-s"]);
+const SHORT_VALUE_FLAG_TOKENS = new Set(["-b", "-o", "-t"]);
+function isNonSelectorValueFlagToken(token) {
+    if (token === undefined || SELECTOR_FLAG_TOKENS.has(token))
+        return false;
+    return VALUE_FLAGS.has(token) || SHORT_VALUE_FLAG_TOKENS.has(token);
 }
 function collectRefsFromTokens(tokens) {
-    return tokens.filter((token) => /^@e\d+\b/.test(token)).map((token) => token.slice(1));
+    const refs = [];
+    for (const [index, token] of tokens.entries()) {
+        if (!/^@e\d+\b/.test(token))
+            continue;
+        if (isNonSelectorValueFlagToken(index > 0 ? tokens[index - 1] : undefined))
+            continue;
+        refs.push(token.slice(1));
+    }
+    return refs;
 }
 export function getGuardedRefUsage(commandTokens, stdin, options = {}) {
     const collectFromStep = (step) => isRefGuardedCommand(step[0]) ? collectRefsFromTokens(step) : [];
-    if (commandTokens[0] !== "batch" || stdin === undefined) {
-        return collectFromStep(commandTokens);
-    }
-    const parsed = parseUserBatchStdin(stdin);
-    if (parsed.error || parsed.steps === undefined) {
+    if (commandTokens[0] !== "batch") {
         return collectFromStep(commandTokens);
     }
+    const steps = getUpstreamEffectiveBatchSteps(commandTokens, stdin);
     const refsBeforeInBatchSnapshot = [];
-    for (const step of parsed.steps) {
+    for (const step of steps) {
         if (!options.includeRefsAfterBatchSnapshot && (step[0] ?? "") === "snapshot")
             break;
         refsBeforeInBatchSnapshot.push(...collectFromStep(step));
@@ -307,13 +335,10 @@ function isSafeSameSnapshotFormBatchStep(step, refSnapshot) {
     return false;
 }
 function getBatchRefInvalidationMessage(commandTokens, stdin, refSnapshot) {
-    if (commandTokens[0] !== "batch" || stdin === undefined)
-        return undefined;
-    const parsed = parseUserBatchStdin(stdin);
-    if (parsed.error || parsed.steps === undefined)
+    if (commandTokens[0] !== "batch")
         return undefined;
     let priorStepInvalidatesRefs = false;
-    for (const step of parsed.steps) {
+    for (const step of getUpstreamEffectiveBatchSteps(commandTokens, stdin)) {
         if ((step[0] ?? "") === "snapshot") {
             priorStepInvalidatesRefs = false;
         }
@@ -321,7 +346,7 @@ function getBatchRefInvalidationMessage(commandTokens, stdin, refSnapshot) {
         if (refIds.length > 0 && isRefGuardedCommand(step[0]) && priorStepInvalidatesRefs) {
             return `Batch step ${step[0]} uses page-scoped ref ${refIds.map((refId) => `@${refId}`).join(", ")} after an earlier batch step can navigate or mutate the page. Split the batch, run snapshot -i after the page-changing step, then retry with current refs.`;
         }
-        if (isRefInvalidatingBatchCommand(step[0]) && !isSafeSameSnapshotFormBatchStep(step, refSnapshot)) {
+        if (isRefInvalidatingBatchCommand(step) && !isSafeSameSnapshotFormBatchStep(step, refSnapshot)) {
             priorStepInvalidatesRefs = true;
         }
     }
@@ -344,7 +369,9 @@ export function buildStaleRefPreflight(options) {
         return undefined;
     if (options.refSnapshotInvalidation) {
         return {
-            message: `Ref ${usedRefIds.map((refId) => `@${refId}`).join(", ")} cannot be used because the latest snapshot for this session reported No active page. Run snapshot -i successfully before using page-scoped refs.`,
+            message: options.refSnapshotInvalidation.reason === "page-transition"
+                ? `Ref ${usedRefIds.map((refId) => `@${refId}`).join(", ")} cannot be used yet. ${options.refSnapshotInvalidation.summary}`
+                : `Ref ${usedRefIds.map((refId) => `@${refId}`).join(", ")} cannot be used because the latest snapshot for this session reported No active page. Run snapshot -i successfully before using page-scoped refs.`,
             refIds: usedRefIds,
             snapshotInvalidation: options.refSnapshotInvalidation,
         };
@@ -390,11 +417,22 @@ export function shouldPinSessionTabForCommand(options) {
 }
 export function buildPinnedBatchPlan(options) {
     if (options.command === "batch") {
+        const tabSelectionStep = ["tab", options.selectedTab];
+        // Upstream executes raw argument steps exclusively when any exist, so the
+        // pinned rewrite must dispatch those same steps rather than resurrecting
+        // caller stdin the guard never scanned.
+        const argumentSteps = getUpstreamEffectiveBatchSteps(options.commandTokens, undefined);
+        if (argumentSteps.length > 0) {
+            return {
+                includeNavigationSummary: false,
+                steps: [tabSelectionStep, ...argumentSteps],
+                unwrapMode: "user-batch",
+            };
+        }
         const parsed = parseUserBatchStdin(options.stdin);
         if (parsed.error) {
             return { error: parsed.error };
         }
-        const tabSelectionStep = ["tab", options.selectedTab];
         return {
             includeNavigationSummary: false,
             steps: [tabSelectionStep, ...(parsed.steps ?? [])],
@@ -602,10 +640,11 @@ export function electronTargetLabel(target) {
 export function getActiveElectronRecords(records) {
     return [...records.values()].filter((record) => record.cleanupState === "active" || record.cleanupState === "dead" || record.cleanupState === "partial" || record.cleanupState === "failed");
 }
-export function findElectronLaunchRecordForSession(sessionName, records) {
+export function findElectronLaunchRecordForSession(sessionName, records, namespace) {
     if (!sessionName)
         return undefined;
-    return getActiveElectronRecords(records).find((record) => record.sessionName === sessionName);
+    const sessionKey = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+    return getActiveElectronRecords(records).find((record) => record.sessionName && getAgentBrowserSessionIdentityKey(record.sessionName, record.namespace) === sessionKey);
 }
 function buildElectronReattachNextAction(record, liveTarget) {
     const endpoint = liveTarget?.webSocketDebuggerUrl ?? record.webSocketDebuggerUrl ?? String(record.port);
@@ -753,3 +792,8 @@ export function formatElectronRefFreshnessText(diagnostic) {
     return diagnostic?.summary;
 }
 export { extractBatchResultCommand };
+export function getPersistentSessionArtifactStore(ctx) {
+    const sessionDir = typeof ctx.sessionManager.getSessionDir === "function" ? ctx.sessionManager.getSessionDir() : undefined;
+    const sessionId = ctx.sessionManager.getSessionId();
+    return sessionDir && sessionId ? { sessionDir, sessionId } : undefined;
+}

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

@@ -1,22 +1,18 @@
-/**
- * Purpose: Own wrapper-side Electron host orchestration for agent_browser structured electron input.
- * Responsibilities: Discover Electron apps, inspect/probe/cleanup wrapper-tracked Electron launches, and build Pi-facing Electron host results.
- * Scope: Electron host actions that do not spawn the main upstream browser command; generic agent_browser execution stays in browser-run.
- */
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../../electron/cleanup.js";
 import { discoverElectronApps } from "../../electron/discovery.js";
-import { boundElectronProbeString } from "../../electron/text.js";
+import { boundElectronProbeString } from "../../electron/cdp.js";
 import { buildOwnedManagedSessionRestoreContext, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { getManagedSessionStateAccessValidationError } from "../../managed-session-state-policy.js";
 import { isRecord } from "../../parsing.js";
 import { withAttachedBrowserSessionContext } from "../../process.js";
-import { buildAgentBrowserNextActions, buildAgentBrowserResultCategoryDetails } from "../../results.js";
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
 import { appendUniqueAgentBrowserNextActions } from "../../results/next-actions.js";
 import { extractRefSnapshotFromData, getSessionPageStateKey, isAboutBlankUrl, normalizeSessionTabTarget } from "../../session-page-state.js";
 import { redactSensitiveText } from "../../runtime.js";
 import { collectElectronManagedSessionTarget } from "../browser-run/diagnostics.js";
 import { buildElectronHostFailureResult, formatElectronTargetLines, redactToolDetails } from "../browser-run/final-result.js";
-import { acquireOwnedManagedSessionDaemonPolicy, closeManagedSession } from "../browser-run/managed-session-daemon-policy.js";
+import { acquireOwnedManagedSessionDaemonPolicy, closeManagedSession, getRunningHeadedAutosavePolicyChangeError } from "../browser-run/managed-session-daemon-policy.js";
 import { buildElectronIdentifiers, buildElectronMismatchNextActions, buildElectronSessionMismatch, extractStringResultField, findElectronLaunchRecordForSession, formatElectronSessionMismatchText, getActiveElectronRecords, getLiveElectronRendererTargets, runSessionCommandData, } from "../browser-run/session-state.js";
 const ELECTRON_PROFILE_ISOLATION_NOTE = "Profile note: electron.launch starts an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app.";
 const ELECTRON_EXISTING_AUTH_GUIDANCE = "For already-authenticated desktop app content, do not stop here: if host tools are allowed and the app is not running, launch the normal app with --remote-debugging-port=<port>, verify the port, then run agent_browser connect <port>; if it is already running without a debug port, ask before relaunching it.";
@@ -118,6 +114,7 @@ function isElectronLaunchRecord(value) {
         return false;
     return value.version === 1 &&
         value.launchedByWrapper === true &&
+        (value.namespace === undefined || typeof value.namespace === "string") &&
         typeof value.launchId === "string" &&
         typeof value.appName === "string" &&
         typeof value.executablePath === "string" &&
@@ -137,13 +134,14 @@ export function restoreElectronLaunchRecordsFromBranch(branch) {
         const electron = isRecord(details?.electron) ? details.electron : undefined;
         if (!electron)
             continue;
+        const namespace = typeof details?.namespace === "string" ? details.namespace : undefined;
         const launch = isElectronLaunchRecord(electron.launch) ? electron.launch : undefined;
         if (launch)
-            records.set(launch.launchId, launch);
+            records.set(launch.launchId, { ...launch, namespace: launch.namespace ?? namespace });
         const cleanupRecords = isRecord(electron.cleanup) && Array.isArray(electron.cleanup.records) ? electron.cleanup.records : [];
         for (const cleanupRecord of cleanupRecords) {
             if (isElectronLaunchRecord(cleanupRecord))
-                records.set(cleanupRecord.launchId, cleanupRecord);
+                records.set(cleanupRecord.launchId, { ...cleanupRecord, namespace: cleanupRecord.namespace ?? namespace });
         }
     }
     return records;
@@ -398,9 +396,14 @@ function getElectronProbeSummary(probe) {
 class ElectronManagedSessionPolicyError extends Error {
 }
 async function withOwnedElectronManagedSessionPolicy(options, run) {
+    const autosavePolicyChangeError = getRunningHeadedAutosavePolicyChangeError(options.headedManagedAutosaveInterval);
+    if (autosavePolicyChangeError)
+        throw new ElectronManagedSessionPolicyError(autosavePolicyChangeError);
     const context = buildOwnedManagedSessionRestoreContext({
         args: ["--namespace", options.namespace ?? "", "--session", options.sessionName, ...options.args],
         cwd: options.cwd,
+        headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled,
+        headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
         managedSessionName: options.sessionName,
         namespace: options.namespace,
         restoreState: options.restoreState,
@@ -427,7 +430,7 @@ async function withOwnedElectronManagedSessionPolicy(options, run) {
 }
 async function collectOwnedElectronManagedSessionTarget(options) {
     try {
-        return await withOwnedElectronManagedSessionPolicy({ ...options, args: ["get", "url"] }, async () => await collectElectronManagedSessionTarget({
+        const target = await withOwnedElectronManagedSessionPolicy({ ...options, args: ["get", "url"] }, async () => await collectElectronManagedSessionTarget({
             allowManagedSessionTarget: true,
             cwd: options.cwd,
             namespace: options.namespace,
@@ -435,9 +438,10 @@ async function collectOwnedElectronManagedSessionTarget(options) {
             signal: options.signal,
             timeoutMs: options.timeoutMs,
         })) ?? { sessionName: options.sessionName };
+        return { ...target, namespace: options.namespace };
     }
     catch (error) {
-        return { error: error instanceof Error ? error.message : String(error), sessionName: options.sessionName };
+        return { error: error instanceof Error ? error.message : String(error), namespace: options.namespace, sessionName: options.sessionName };
     }
 }
 async function runElectronProbeCommandData(options) {
@@ -581,6 +585,8 @@ function buildElectronProbeResult(options) {
         },
         nextActions: nextActions.length > 0 ? nextActions : undefined,
         ...buildAgentBrowserResultCategoryDetails({ args: [], succeeded: true }),
+        managedSessionHeadedAutosaveDisabled: options.headedManagedAutosaveDisabled === true ? true : undefined,
+        managedSessionHeadedAutosaveInterval: options.headedManagedAutosaveInterval,
         namespace: options.namespace,
         refSnapshot: options.probe.refSnapshot,
         sessionName: options.probe.sessionName,
@@ -597,8 +603,10 @@ function buildElectronProbeResult(options) {
 export async function cleanupTrackedElectronHostLaunches(options) {
     const results = [];
     for (const record of options.records) {
+        const sessionKey = getSessionPageStateKey(record.sessionName, record.namespace) ?? record.sessionName;
+        const managedSessionOwner = sessionKey ? options.ownedManagedSessions.get(sessionKey) : undefined;
         const managedSessionCloseError = record.sessionName
-            ? await closeManagedSession({ cwd: options.cwd, preserveAttachedBrowserSession: options.attachedSessionKeys.has(getSessionPageStateKey(record.sessionName) ?? record.sessionName), restoreState: options.managedSessionRestoreState, sessionName: record.sessionName, timeoutMs: options.timeoutMs })
+            ? await closeManagedSession({ cwd: options.cwd, headedManagedAutosaveInterval: managedSessionOwner?.headedManagedAutosaveInterval, namespace: record.namespace, preserveAttachedBrowserSession: options.attachedSessionKeys.has(sessionKey ?? record.sessionName), restoreState: options.managedSessionRestoreState, sessionName: record.sessionName, timeoutMs: options.timeoutMs })
             : undefined;
         const managedSessionStep = record.sessionName
             ? managedSessionCloseError
@@ -643,11 +651,11 @@ export async function cleanupActiveElectronHostLaunches(options) {
 export async function handleElectronHostInput(options) {
     const currentSessionKey = getSessionPageStateKey(options.managedSessionName, options.managedSessionNamespace) ?? options.managedSessionName;
     const preserveAttachedBrowserSession = options.attachedSessionKeys.has(currentSessionKey)
-        || [...options.electronLaunchRecords.values()].some((record) => record.sessionName !== undefined && options.attachedSessionKeys.has(getSessionPageStateKey(record.sessionName) ?? record.sessionName));
+        || [...options.electronLaunchRecords.values()].some((record) => record.sessionName !== undefined && options.attachedSessionKeys.has(getSessionPageStateKey(record.sessionName, record.namespace) ?? record.sessionName));
     return await withAttachedBrowserSessionContext(preserveAttachedBrowserSession, () => handleElectronHostInputInContext(options));
 }
 async function handleElectronHostInputInContext(options) {
-    const { attachedSessionKeys, compiledElectron, cwd, electronChildProcesses, electronLaunchRecords, implicitSessionCloseTimeoutMs, managedSessionActive, managedSessionName, managedSessionNamespace, managedSessionRestoreState, redactedCompiledElectron, sessionPageState, signal, } = options;
+    const { attachedSessionKeys, compiledElectron, cwd, electronChildProcesses, electronLaunchRecords, implicitSessionCloseTimeoutMs, managedSessionActive, managedSessionName, managedSessionNamespace, managedSessionRestoreState, ownedManagedSessions, redactedCompiledElectron, sessionPageState, signal, } = options;
     if (compiledElectron?.action === "list") {
         try {
             const discovery = await discoverElectronApps({ maxResults: compiledElectron.maxResults, query: compiledElectron.query });
@@ -665,16 +673,22 @@ async function handleElectronHostInputInContext(options) {
         const statuses = await Promise.all(records.map((record) => inspectElectronLaunchStatus(record)));
         const managedSessions = await Promise.all(records
             .filter((record) => typeof record.sessionName === "string")
-            .map((record) => collectOwnedElectronManagedSessionTarget({
-            cwd,
-            restoreState: managedSessionRestoreState,
-            sessionName: record.sessionName,
-            signal,
-            timeoutMs: compiledElectron.timeoutMs,
-        })));
+            .map((record) => {
+            const sessionKey = getSessionPageStateKey(record.sessionName, record.namespace) ?? record.sessionName;
+            return collectOwnedElectronManagedSessionTarget({
+                cwd,
+                headedManagedAutosaveDisabled: ownedManagedSessions.get(sessionKey)?.headedManagedAutosaveDisabled,
+                headedManagedAutosaveInterval: ownedManagedSessions.get(sessionKey)?.headedManagedAutosaveInterval,
+                namespace: record.namespace,
+                restoreState: managedSessionRestoreState,
+                sessionName: record.sessionName,
+                signal,
+                timeoutMs: compiledElectron.timeoutMs,
+            });
+        }));
         const mismatches = managedSessions
             .map((managedSession) => {
-            const record = records.find((candidate) => candidate.sessionName === managedSession.sessionName);
+            const record = records.find((candidate) => candidate.sessionName === managedSession.sessionName && candidate.namespace === managedSession.namespace);
             const status = record ? statuses.find((candidate) => candidate.launchId === record.launchId) : undefined;
             return record && status ? buildElectronSessionMismatch({ managedSession, record, statusTargets: status.targets }) : undefined;
         })
@@ -690,7 +704,7 @@ async function handleElectronHostInputInContext(options) {
     if (compiledElectron?.action === "probe") {
         const launchRecord = compiledElectron.launchId
             ? electronLaunchRecords.get(compiledElectron.launchId)
-            : findElectronLaunchRecordForSession(managedSessionName, electronLaunchRecords);
+            : findElectronLaunchRecordForSession(managedSessionName, electronLaunchRecords, managedSessionNamespace);
         if (compiledElectron.launchId && !launchRecord) {
             return buildElectronHostFailureResult({
                 compiledElectron: redactedCompiledElectron ?? compiledElectron,
@@ -722,7 +736,7 @@ async function handleElectronHostInputInContext(options) {
         }
         try {
             const status = launchRecord ? await inspectElectronLaunchStatus(launchRecord) : undefined;
-            const probeNamespace = compiledElectron.launchId ? undefined : managedSessionNamespace;
+            const probeNamespace = compiledElectron.launchId ? launchRecord?.namespace : managedSessionNamespace;
             const pageStateKey = getSessionPageStateKey(probeSessionName, probeNamespace) ?? probeSessionName;
             const currentPageState = sessionPageState.get(pageStateKey);
             const fileAccessError = getManagedSessionStateAccessValidationError({
@@ -733,9 +747,14 @@ async function handleElectronHostInputInContext(options) {
             });
             if (fileAccessError)
                 throw new ElectronManagedSessionPolicyError(fileAccessError);
+            const managedSessionOwner = ownedManagedSessions.get(pageStateKey);
+            const headedManagedAutosaveDisabled = managedSessionOwner?.headedManagedAutosaveDisabled === true;
+            const headedManagedAutosaveInterval = managedSessionOwner?.headedManagedAutosaveInterval;
             const probe = await withOwnedElectronManagedSessionPolicy({
                 args: ["snapshot", "-i"],
                 cwd,
+                headedManagedAutosaveDisabled,
+                headedManagedAutosaveInterval,
                 namespace: probeNamespace,
                 restoreState: managedSessionRestoreState,
                 sessionName: probeSessionName,
@@ -779,6 +798,8 @@ async function handleElectronHostInputInContext(options) {
             }
             return buildElectronProbeResult({
                 compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                headedManagedAutosaveDisabled,
+                headedManagedAutosaveInterval,
                 mismatch: sessionMismatch,
                 namespace: probeNamespace,
                 probe,
@@ -801,7 +822,7 @@ async function handleElectronHostInputInContext(options) {
         const selection = selectElectronRecords(compiledElectron, electronLaunchRecords);
         if (selection.error)
             return buildElectronHostFailureResult({ compiledElectron: redactedCompiledElectron ?? compiledElectron, errorText: selection.error, failureCategory: "validation-error" });
-        const cleanupResults = await cleanupTrackedElectronHostLaunches({ attachedSessionKeys, cwd, electronChildProcesses, electronLaunchRecords, managedSessionRestoreState, records: selection.records ?? [], timeoutMs: compiledElectron.timeoutMs ?? implicitSessionCloseTimeoutMs });
+        const cleanupResults = await cleanupTrackedElectronHostLaunches({ attachedSessionKeys, cwd, electronChildProcesses, electronLaunchRecords, managedSessionRestoreState, ownedManagedSessions, records: selection.records ?? [], timeoutMs: compiledElectron.timeoutMs ?? implicitSessionCloseTimeoutMs });
         return buildElectronCleanupResult(redactedCompiledElectron ?? compiledElectron, cleanupResults);
     }
     return undefined;

package/dist/extensions/agent-browser/lib/orchestration/input-plan.js

@@ -1,7 +1,11 @@
 import { parseArgvDescriptor } from "../argv-descriptor.js";
 import { validateToolArgs, redactInvocationArgs, redactSensitiveText } from "../runtime.js";
 import { buildAgentBrowserResultCategoryDetails } from "../results/categories.js";
-import { compileAgentBrowserElectron, compileAgentBrowserJob, compileAgentBrowserNetworkSourceLookup, compileAgentBrowserQaPreset, compileAgentBrowserSemanticAction, compileAgentBrowserSourceLookup, redactNetworkSourceLookupArgs, redactNetworkSourceLookupUrl, } from "../input-modes.js";
+import { compileAgentBrowserElectron } from "../input-modes/electron.js";
+import { compileAgentBrowserJob, compileAgentBrowserQaPreset } from "../input-modes/job.js";
+import { compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup, redactNetworkSourceLookupArgs, redactNetworkSourceLookupUrl } from "../input-modes/lookups.js";
+import { compileAgentBrowserSemanticAction } from "../input-modes/semantic-action.js";
+import { AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS, compileAgentBrowserScript } from "../input-modes/script.js";
 function redactCompiledElectron(compiled) {
     if (!compiled)
         return undefined;
@@ -68,6 +72,7 @@ export function resolveAgentBrowserInput(options) {
     const sourceLookupResult = params.sourceLookup === undefined ? {} : compileAgentBrowserSourceLookup(params.sourceLookup);
     const networkSourceLookupResult = params.networkSourceLookup === undefined ? {} : compileAgentBrowserNetworkSourceLookup(params.networkSourceLookup);
     const electronResult = params.electron === undefined ? {} : compileAgentBrowserElectron(params.electron);
+    const scriptResult = params.script === undefined ? {} : compileAgentBrowserScript(params.script);
     const hasExplicitArgs = Array.isArray(params.args);
     const explicitInputModes = [
         hasExplicitArgs,
@@ -77,19 +82,21 @@ export function resolveAgentBrowserInput(options) {
         Boolean(sourceLookupResult.compiled),
         Boolean(networkSourceLookupResult.compiled),
         Boolean(electronResult.compiled),
+        Boolean(scriptResult.compiled),
     ].filter(Boolean).length;
     const inputModeError = explicitInputModes !== 1
-        ? "Provide exactly one of args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron."
+        ? "Provide exactly one of script, args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron."
         : undefined;
     const compiledSemanticAction = semanticActionResult.compiled;
     const compiledQaPreset = qaResult.compiled;
     const compiledSourceLookup = sourceLookupResult.compiled;
     const compiledNetworkSourceLookup = networkSourceLookupResult.compiled;
     const compiledElectron = electronResult.compiled;
+    const compiledScript = scriptResult.compiled;
     const compiledJob = jobResult.compiled ?? compiledQaPreset;
     const compiledGeneratedBatch = compiledNetworkSourceLookup ?? compiledSourceLookup ?? compiledJob;
     const normalizedExplicitArgs = normalizeExplicitEvalStdinArgs(params.args ?? [], params.stdin);
-    const toolArgs = compiledElectron ? [] : compiledSemanticAction?.args ?? compiledGeneratedBatch?.args ?? normalizedExplicitArgs.args;
+    const toolArgs = compiledElectron || compiledScript ? [] : compiledSemanticAction?.args ?? compiledGeneratedBatch?.args ?? normalizedExplicitArgs.args;
     const toolStdin = compiledGeneratedBatch?.stdin ?? normalizedExplicitArgs.stdin;
     const redactedArgs = redactInvocationArgs(toolArgs);
     const generatedStdinError = params.stdin !== undefined
@@ -97,7 +104,9 @@ export function resolveAgentBrowserInput(options) {
             ? "Do not provide stdin with job, qa, sourceLookup, or networkSourceLookup; those modes generate their own batch stdin."
             : compiledElectron
                 ? "Do not provide stdin with electron; electron mode is host-only or manages its own input."
-                : undefined
+                : compiledScript
+                    ? "Do not provide stdin with script; browser call stdin belongs inside browser({ args, stdin })."
+                    : undefined
         : undefined;
     const outputPathError = params.outputPath !== undefined && (typeof params.outputPath !== "string" || params.outputPath.trim().length === 0)
         ? "outputPath must be a non-empty string when provided."
@@ -106,7 +115,12 @@ export function resolveAgentBrowserInput(options) {
         ? "timeoutMs must be a positive integer when provided."
         : compiledElectron && params.timeoutMs !== undefined
             ? "Use electron.timeoutMs for electron actions; top-level timeoutMs applies only to browser CLI subprocess calls."
-            : undefined;
+            : compiledScript && params.timeoutMs !== undefined && params.timeoutMs > AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS
+                ? `script timeoutMs must be ${AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS} or less.`
+                : undefined;
+    const scriptSessionModeError = compiledScript && params.sessionMode !== undefined
+        ? "Do not provide sessionMode with script; script always uses its own isolated session."
+        : undefined;
     const attachedQaSessionError = compiledQaPreset?.checks.attached
         ? params.sessionMode === "fresh"
             ? "qa.attached cannot be used with sessionMode=fresh; attach or launch a session first, then run qa.attached with the current session."
@@ -120,31 +134,35 @@ export function resolveAgentBrowserInput(options) {
         ?? sourceLookupResult.error
         ?? networkSourceLookupResult.error
         ?? electronResult.error
+        ?? scriptResult.error
         ?? inputModeError
         ?? generatedStdinError
         ?? outputPathError
         ?? timeoutMsError
+        ?? scriptSessionModeError
         ?? attachedQaSessionError
-        ?? (compiledElectron ? undefined : validateToolArgs(toolArgs) ?? getBatchPreflightValidationError(toolArgs, toolStdin));
+        ?? (compiledElectron || compiledScript ? undefined : validateToolArgs(toolArgs) ?? getBatchPreflightValidationError(toolArgs, toolStdin));
     const redactedCompiledJob = redactCompiledJob(compiledJob);
     const redactedCompiledSemanticAction = compiledSemanticAction
         ? { ...compiledSemanticAction, args: redactInvocationArgs(compiledSemanticAction.args) }
         : undefined;
     const attemptedKind = compiledElectron
         ? "electron"
-        : compiledNetworkSourceLookup
-            ? "networkSourceLookup"
-            : compiledSourceLookup
-                ? "sourceLookup"
-                : compiledQaPreset
-                    ? "qa"
-                    : jobResult.compiled
-                        ? "job"
-                        : compiledSemanticAction
-                            ? "semanticAction"
-                            : hasExplicitArgs
-                                ? "args"
-                                : undefined;
+        : compiledScript
+            ? "script"
+            : compiledNetworkSourceLookup
+                ? "networkSourceLookup"
+                : compiledSourceLookup
+                    ? "sourceLookup"
+                    : compiledQaPreset
+                        ? "qa"
+                        : jobResult.compiled
+                            ? "job"
+                            : compiledSemanticAction
+                                ? "semanticAction"
+                                : hasExplicitArgs
+                                    ? "args"
+                                    : undefined;
     const redactedCompiledElectron = redactCompiledElectron(compiledElectron);
     const redactedCompiledNetworkSourceLookup = redactCompiledNetworkSourceLookup(compiledNetworkSourceLookup);
     const redactedCompiledQaPreset = compiledQaPreset && redactedCompiledJob ? { ...redactedCompiledJob, checks: compiledQaPreset.checks } : undefined;
@@ -175,6 +193,9 @@ export function resolveAgentBrowserInput(options) {
     if (compiledElectron && redactedCompiledElectron) {
         return { ...resolvedBase, compiledElectron, kind: "electron", redactedCompiledElectron, status: "valid" };
     }
+    if (compiledScript) {
+        return { ...resolvedBase, compiledScript, kind: "script", status: "valid" };
+    }
     if (compiledNetworkSourceLookup && redactedCompiledNetworkSourceLookup) {
         return {
             ...resolvedBase,

package/dist/extensions/agent-browser/lib/orchestration/output-file.js

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, realpath, stat, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { getAgentBrowserStoragePathValidationError } from "../managed-session-state-policy.js";
 import { isRecord } from "../parsing.js";
@@ -31,6 +31,33 @@ function appendOutputFileNotice(result, message) {
 export function getAgentBrowserOutputPathValidationError(outputPath, cwd) {
     return outputPath ? getAgentBrowserStoragePathValidationError(normalizeRequestedOutputPath(outputPath), cwd) : undefined;
 }
+function getArtifactPaths(result, cwd) {
+    const details = isRecord(result.details) ? result.details : undefined;
+    if (!details || !Array.isArray(details.artifacts))
+        return [];
+    return details.artifacts.flatMap((artifact) => {
+        if (!isRecord(artifact))
+            return [];
+        const path = typeof artifact.absolutePath === "string" ? artifact.absolutePath : typeof artifact.path === "string" ? artifact.path : undefined;
+        return path ? [isAbsolute(path) ? path : resolve(cwd, path)] : [];
+    });
+}
+async function pathsReferToSameFile(left, right) {
+    if (resolve(left) === resolve(right))
+        return true;
+    try {
+        if (await realpath(left) === await realpath(right))
+            return true;
+    }
+    catch { }
+    try {
+        const [leftStat, rightStat] = await Promise.all([stat(left), stat(right)]);
+        return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+    }
+    catch {
+        return false;
+    }
+}
 export async function applyAgentBrowserOutputPath(options) {
     if (!options.outputPath)
         return options.result;
@@ -47,6 +74,20 @@ export async function applyAgentBrowserOutputPath(options) {
     const requestedPath = normalizeRequestedOutputPath(options.outputPath);
     const absolutePath = isAbsolute(requestedPath) ? requestedPath : resolve(options.cwd, requestedPath);
     const payload = getOutputPayload(options.result);
+    for (const artifactPath of getArtifactPaths(options.result, options.cwd)) {
+        if (!await pathsReferToSameFile(absolutePath, artifactPath))
+            continue;
+        const message = "outputPath resolves to the same file as a browser artifact destination; choose a separate outputPath or omit it. The browser artifact was preserved.";
+        const outputFile = { absolutePath, error: message, path: requestedPath, source: payload.source, status: "failed" };
+        const details = isRecord(options.result.details) ? { ...options.result.details } : {};
+        delete details.successCategory;
+        return {
+            ...options.result,
+            content: appendOutputFileNotice(options.result, `Output file rejected: ${message}`),
+            details: { ...details, failureCategory: "validation-error", outputFile, resultCategory: "failure" },
+            isError: true,
+        };
+    }
     try {
         const serialized = serializeOutputPayload(payload.value);
         await mkdir(dirname(absolutePath), { recursive: true });