pi-agent-browser-native 0.3.0 → 0.6.5

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

@@ -1,4 +1,5 @@
 import { rm } from "node:fs/promises";
+import { getAgentBrowserSessionIdentityKey, VALUE_FLAGS } from "../../argv-grammar.js";
 import { runAgentBrowserProcess } from "../../process.js";
 import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
 import { parseAgentBrowserEnvelope } from "../../results/envelope.js";
@@ -7,13 +8,11 @@ import { getSessionPageStateKey, isAboutBlankUrl, normalizeComparableUrl, normal
 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)
         return;
-    if (patch.allowedDomainsBySession)
-        state.allowedDomainsBySession = patch.allowedDomainsBySession;
     if ("artifactManifest" in patch)
         state.artifactManifest = patch.artifactManifest;
     if (patch.freshSessionOrdinal !== undefined)
@@ -38,7 +37,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,
@@ -213,10 +212,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);
     }
@@ -243,14 +247,13 @@ export function extractNavigationSummaryFromData(data) {
     const result = isRecord(data) && isRecord(data.result) ? data.result : data;
     const title = extractStringResultField(result, "title");
     const url = extractStringResultField(result, "url");
-    return title || url ? { title, url } : undefined;
+    const urlChanged = isRecord(result) && typeof result.urlChanged === "boolean" ? result.urlChanged : undefined;
+    return title || url ? { title, url, urlChanged } : undefined;
 }
-export function shouldCaptureNavigationSummary(command, data) {
+export function shouldCaptureNavigationSummary(command, data, subcommand) {
     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) &&
+    return (isNavigationObservableCommandName(command, subcommand) &&
         (!isRecord(data) || (typeof data.title !== "string" && typeof data.url !== "string")));
 }
 export function mergeNavigationSummaryIntoData(data, navigationSummary) {
@@ -269,29 +272,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));
@@ -318,13 +334,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;
         }
@@ -332,7 +345,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;
         }
     }
@@ -355,7 +368,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,
         };
@@ -401,11 +416,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 ?? [])],
@@ -415,7 +441,7 @@ export function buildPinnedBatchPlan(options) {
     if (options.commandTokens.length === 0) {
         return undefined;
     }
-    const includeNavigationSummary = isNavigationObservableCommandName(options.command);
+    const includeNavigationSummary = isNavigationObservableCommandName(options.command, options.commandTokens[1]);
     const tabSelectionStep = ["tab", options.selectedTab];
     const commandStep = options.commandTokens;
     const navigationSummarySteps = includeNavigationSummary ? [["eval", NAVIGATION_SUMMARY_EVAL]] : [];
@@ -505,11 +531,10 @@ export function unwrapPinnedSessionBatchEnvelope(options) {
     };
 }
 export async function runSessionCommandData(options) {
-    const { allowManagedSessionTarget, args, cwd, namespace, pinNamespace, sessionName, signal, stdin, throwOnFailure, timeoutMs } = options;
+    const { args, cwd, namespace, pinNamespace, sessionName, signal, stdin, throwOnFailure, timeoutMs } = options;
     if (!sessionName)
         return undefined;
     const processResult = await runAgentBrowserProcess({
-        allowManagedSessionTarget,
         args: ["--json", ...(namespace !== undefined || pinNamespace ? ["--namespace", namespace ?? ""] : []), "--session", sessionName, ...args],
         cwd,
         signal,
@@ -613,10 +638,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);

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

@@ -2,7 +2,7 @@ import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../
 import { discoverElectronApps } from "../../electron/discovery.js";
 import { boundElectronProbeString } from "../../electron/cdp.js";
 import { buildOwnedManagedSessionRestoreContext, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
-import { getManagedSessionStateAccessValidationError } from "../../managed-session-state-policy.js";
+import { getPageTargetValidationError } from "../../page-target-validation.js";
 import { isRecord } from "../../parsing.js";
 import { withAttachedBrowserSessionContext } from "../../process.js";
 import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
@@ -114,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" &&
@@ -133,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;
@@ -428,22 +430,22 @@ async function withOwnedElectronManagedSessionPolicy(options, run) {
 }
 async function collectOwnedElectronManagedSessionTarget(options) {
     try {
-        return await withOwnedElectronManagedSessionPolicy({ ...options, args: ["get", "url"] }, async () => await collectElectronManagedSessionTarget({
-            allowManagedSessionTarget: true,
+        const target = await withOwnedElectronManagedSessionPolicy({ ...options, args: ["get", "url"] }, async () => await collectElectronManagedSessionTarget({
             cwd: options.cwd,
             namespace: options.namespace,
             sessionName: options.sessionName,
             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) {
     try {
-        return { data: await runSessionCommandData({ ...options, allowManagedSessionTarget: true, pinNamespace: true, throwOnFailure: true }) };
+        return { data: await runSessionCommandData({ ...options, pinNamespace: true, throwOnFailure: true }) };
     }
     catch (error) {
         return { error: error instanceof Error ? error.message : String(error) };
@@ -457,9 +459,6 @@ async function collectElectronProbe(options) {
     const url = boundElectronProbeString(extractStringResultField(urlResult.data, "result") ?? extractStringResultField(urlResult.data, "url"), 300);
     if (!url)
         throw new Error("get url returned no active page URL.");
-    const fileAccessError = getManagedSessionStateAccessValidationError({ args: ["snapshot", "-i"], currentPageUrl: url, cwd: options.cwd });
-    if (fileAccessError)
-        throw new ElectronManagedSessionPolicyError(fileAccessError);
     const titleResult = await runElectronProbeCommandData({ ...commandContext, args: ["get", "title"] });
     const focusedResult = await runElectronProbeCommandData({ ...commandContext, args: ["eval", "--stdin"], stdin: ELECTRON_FOCUSED_ELEMENT_EVAL });
     const tabsResult = await runElectronProbeCommandData({ ...commandContext, args: ["tab", "list"] });
@@ -600,10 +599,10 @@ function buildElectronProbeResult(options) {
 export async function cleanupTrackedElectronHostLaunches(options) {
     const results = [];
     for (const record of options.records) {
-        const sessionKey = getSessionPageStateKey(record.sessionName) ?? record.sessionName;
+        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, headedManagedAutosaveInterval: managedSessionOwner?.headedManagedAutosaveInterval, preserveAttachedBrowserSession: options.attachedSessionKeys.has(sessionKey ?? 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
@@ -648,7 +647,7 @@ 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) {
@@ -671,11 +670,12 @@ async function handleElectronHostInputInContext(options) {
         const managedSessions = await Promise.all(records
             .filter((record) => typeof record.sessionName === "string")
             .map((record) => {
-            const sessionKey = getSessionPageStateKey(record.sessionName) ?? record.sessionName;
+            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,
@@ -684,7 +684,7 @@ async function handleElectronHostInputInContext(options) {
         }));
         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;
         })
@@ -700,7 +700,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,
@@ -732,17 +732,16 @@ 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({
+            const pageTargetError = getPageTargetValidationError({
                 args: ["snapshot", "-i"],
                 currentPageUrl: currentPageState.tabTarget?.url,
-                cwd,
                 pageUrlUnknown: currentPageState.tabTargetUnknown === true,
             });
-            if (fileAccessError)
-                throw new ElectronManagedSessionPolicyError(fileAccessError);
+            if (pageTargetError)
+                throw new ElectronManagedSessionPolicyError(pageTargetError);
             const managedSessionOwner = ownedManagedSessions.get(pageStateKey);
             const headedManagedAutosaveDisabled = managedSessionOwner?.headedManagedAutosaveDisabled === true;
             const headedManagedAutosaveInterval = managedSessionOwner?.headedManagedAutosaveInterval;

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

@@ -5,6 +5,7 @@ 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;
@@ -71,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,
@@ -80,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
@@ -100,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."
@@ -109,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."
@@ -123,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;
@@ -178,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,7 +1,7 @@
-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 { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, resolve } from "node:path";
 import { isRecord } from "../parsing.js";
+import { isSessionArtifactManifest } from "../results/artifact-manifest.js";
 export function normalizeRequestedOutputPath(path) {
     return path.startsWith("@") ? path.slice(1) : path;
 }
@@ -11,11 +11,41 @@ function getTextContent(result) {
         .map((item) => item.text)
         .join("\n\n") ?? "";
 }
-function getOutputPayload(result) {
+function getOutputSource(result) {
+    return isRecord(result.details) && result.details.data !== undefined ? "details.data" : "content.text";
+}
+async function readCompactedSpill(path, manifest) {
+    if (!path || !manifest?.entries.some((entry) => entry.kind === "spill"
+        && (entry.path === path || entry.absolutePath === path)
+        && (entry.storageScope === "persistent-session" || entry.storageScope === "process-temp")
+        && (entry.retentionState === "live" || entry.retentionState === "ephemeral")))
+        throw new Error("Full compacted output is unavailable from the wrapper-managed spill; outputPath was not written.");
+    const text = await readFile(path, "utf8");
+    return extname(path) === ".json" ? JSON.parse(text) : text;
+}
+async function rehydrateCompactedData(data, details, manifest) {
+    if (isRecord(data) && data.compacted === true) {
+        return readCompactedSpill(typeof details.fullOutputPath === "string" ? details.fullOutputPath : undefined, manifest);
+    }
+    if (!Array.isArray(data))
+        return data;
+    const batchSteps = Array.isArray(details.batchSteps) ? details.batchSteps : [];
+    return Promise.all(data.map(async (row, index) => {
+        if (!isRecord(row) || !isRecord(row.result) || row.result.compacted !== true)
+            return row;
+        const step = isRecord(batchSteps[index]) ? batchSteps[index] : undefined;
+        const path = typeof step?.fullOutputPath === "string"
+            ? step.fullOutputPath
+            : typeof row.result.fullOutputPath === "string" ? row.result.fullOutputPath : undefined;
+        return { ...row, result: await readCompactedSpill(path, manifest) };
+    }));
+}
+async function getOutputPayload(result) {
     const details = isRecord(result.details) ? result.details : undefined;
-    if (details && details.data !== undefined)
-        return { source: "details.data", value: details.data };
-    return { source: "content.text", value: getTextContent(result) };
+    if (details?.data === undefined)
+        return { source: "content.text", value: getTextContent(result) };
+    const manifest = isSessionArtifactManifest(details.artifactManifest) ? details.artifactManifest : undefined;
+    return { source: "details.data", value: await rehydrateCompactedData(details.data, details, manifest) };
 }
 function serializeOutputPayload(value) {
     return typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`;
@@ -28,9 +58,6 @@ function appendOutputFileNotice(result, message) {
     }
     return [{ type: "text", text: message }, ...content];
 }
-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))
@@ -61,24 +88,16 @@ async function pathsReferToSameFile(left, right) {
 export async function applyAgentBrowserOutputPath(options) {
     if (!options.outputPath)
         return options.result;
-    const validationError = getAgentBrowserOutputPathValidationError(options.outputPath, options.cwd);
-    if (validationError) {
-        return {
-            content: [{ type: "text", text: validationError }],
-            details: { failureCategory: "validation-error", resultCategory: "failure", validationError },
-            isError: true,
-        };
-    }
     if (options.result.isError || (isRecord(options.result.details) && options.result.details.resultCategory === "failure"))
         return options.result;
     const requestedPath = normalizeRequestedOutputPath(options.outputPath);
     const absolutePath = isAbsolute(requestedPath) ? requestedPath : resolve(options.cwd, requestedPath);
-    const payload = getOutputPayload(options.result);
+    const source = getOutputSource(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 outputFile = { absolutePath, error: message, path: requestedPath, source, status: "failed" };
         const details = isRecord(options.result.details) ? { ...options.result.details } : {};
         delete details.successCategory;
         return {
@@ -89,6 +108,7 @@ export async function applyAgentBrowserOutputPath(options) {
         };
     }
     try {
+        const payload = await getOutputPayload(options.result);
         const serialized = serializeOutputPayload(payload.value);
         await mkdir(dirname(absolutePath), { recursive: true });
         await writeFile(absolutePath, serialized, "utf8");
@@ -103,7 +123,7 @@ export async function applyAgentBrowserOutputPath(options) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        const outputFile = { absolutePath, error: message, path: requestedPath, source: payload.source, status: "failed" };
+        const outputFile = { absolutePath, error: message, path: requestedPath, source, status: "failed" };
         const details = isRecord(options.result.details)
             ? (() => {
                 const rest = { ...options.result.details };