pi-agent-browser-native 0.2.77 → 0.3.0

package/dist/extensions/agent-browser/lib/input-modes/shared.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Hold tiny shared parsing helpers for structured agent_browser input modes.
- * Responsibilities: Normalize common select values, batch result rows, and workspace scan limits.
- * Scope: Generic input-mode helpers only; mode-specific policy stays in the owning module.
- */
 import { isRecord } from "../parsing.js";
 import { SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES, SOURCE_LOOKUP_MAX_WORKSPACE_FILES } from "./types.js";
 export function getSelectValues(input, context) {

package/dist/extensions/agent-browser/lib/input-modes/types.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Define structured agent_browser input-mode constants and TypeScript contracts.
- * Responsibilities: Share schema enums and compiled input-mode result types across input-mode modules.
- * Scope: Types and constants only; validation and compilation live in sibling modules.
- */
 export const DEFAULT_SESSION_MODE = "auto";
 export const AGENT_BROWSER_SEMANTIC_ACTIONS = ["check", "click", "fill", "select"];
 export const AGENT_BROWSER_SEMANTIC_LOCATORS = ["alt", "label", "placeholder", "role", "testid", "text", "title"];

package/dist/extensions/agent-browser/lib/json-schema.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Build the small JSON Schema subset used by Pi tool schemas without importing TypeBox at runtime.
- * Responsibilities: Preserve plain JSON Schema objects Pi consumes while keeping extension startup cheap.
- * Scope: Schema construction only; runtime validation still belongs to Pi and the tool input compilers.
- */
 const OPTIONAL_SCHEMA = Symbol("pi-agent-browser-optional-schema");
 function withOptions(schema, options) {
     return { ...schema, ...(options ?? {}) };

package/dist/extensions/agent-browser/lib/launch-scoped-flags.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Canonical launch-scoped agent-browser flag metadata shared by runtime planning and agent-facing guidance.
- * Responsibilities: Define which upstream flags require a fresh launch, explain why, expose stable guidance labels, and share launch-token detection used by runtime and managed restore policy.
- * Scope: Launch-scoped metadata and token classification; broader execution planning lives in runtime.ts.
- */
 import { findCommandStartIndex } from "./argv-descriptor.js";
 import { isBooleanFlagEnabled, optionalGlobalValueFlagConsumesNext } from "./argv-grammar.js";
 export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
@@ -42,6 +37,10 @@ export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
         flag: "--idle-timeout",
         reason: "configures background browser lifecycle for the launched session",
     },
+    {
+        flag: "--headed",
+        reason: "selects whether the launched browser has a visible window",
+    },
     {
         flag: "--device",
         reason: "selects the provider device for the upstream launch",

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

@@ -1,5 +1,3 @@
-// Purpose: Identify and redact wrapper-owned managed restore capabilities.
-// Scope: Pure string helpers shared by storage, policy, and presentation paths.
 const MANAGED_SESSION_RESTORE_KEY_PATTERN = /piab-r(?:2)?-[a-f\d]{32}/gi;
 const MANAGED_SESSION_RESTORE_KEY_EXACT_PATTERN = /^piab-r2-[a-f\d]{32}$/i;
 const WRAPPER_MANAGED_SESSION_PREFIX = "piab-";

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

@@ -1,6 +1,3 @@
-// Purpose: Serialize wrapper-owned daemon policy decisions across cooperating Pi processes.
-// Responsibilities: Elect one live claim, bridge the pre-update v2 path, recover proven-dead current-protocol artifacts, and release only the caller's immutable token.
-// Scope: Wrapper coordination only; agent-browser never reads these claims.
 import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";

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

@@ -1,13 +1,8 @@
-/**
- * Purpose: Own automatic restore policy for wrapper-managed browser sessions.
- * Responsibilities: Resolve owned session identity, isolate per-call policy, reject incompatible argv/env/config, and persist sticky restore-disable state.
- * Scope: Restore policy only; storage identity and snapshot retention live in focused sibling modules.
- */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { chmodSync, lstatSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { extractCommandTokens, parseCommandInfo } from "./argv-descriptor.js";
-import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, extractRequestedRestoreKey, getAgentBrowserSessionIdentityKey, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
+import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, extractRequestedRestoreKey, getAgentBrowserSessionIdentityKey, isUpstreamEnvFlagEnabled, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
 import { hasLaunchScopedFlagToken, MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS, MANAGED_RESTORE_INCOMPATIBLE_ENVS, MANAGED_RESTORE_INCOMPATIBLE_FLAGS, } from "./launch-scoped-flags.js";
 import { createManagedSessionRestoreKey, ensureManagedSessionRestoreStorageIsSecure, getManagedSessionRestoreProtectedStorageEnv, hasManagedSessionRestoreProjectIdentity, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
 import { parseUserBatchStdin } from "./orchestration/batch-stdin.js";
@@ -28,10 +23,6 @@ function isDisabledEnvFlag(value) {
         return false;
     return ["0", "false", "no", "off"].includes(value.trim().toLowerCase());
 }
-/** Match upstream env_var_is_truthy exactly: lowercase only, without trimming or accepting "off". */
-function isUpstreamEnvFlagEnabled(value) {
-    return value !== undefined && !["", "0", "false", "no"].includes(value.toLowerCase());
-}
 function hasUpstreamEnvValue(env, name) {
     return env?.[name] !== undefined;
 }
@@ -194,11 +185,35 @@ export function getOwnedManagedSessionNamespaceEnv(options) {
     const { namespace, owned, ownedContext } = resolveManagedSessionRestorePolicy(options);
     return owned ? { AGENT_BROWSER_NAMESPACE: ownedContext?.namespace ?? namespace ?? "" } : {};
 }
+const DEFAULT_AUTOSAVE_INTERVAL_MS = "30000";
+const MAX_U64 = 18446744073709551615n;
+export function resolveExplicitAutosaveInterval(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\+?\d+$/.test(value))
+        return DEFAULT_AUTOSAVE_INTERVAL_MS;
+    try {
+        const parsed = BigInt(value);
+        return parsed <= MAX_U64 ? parsed.toString() : DEFAULT_AUTOSAVE_INTERVAL_MS;
+    }
+    catch {
+        return DEFAULT_AUTOSAVE_INTERVAL_MS;
+    }
+}
 export function getOwnedManagedSessionCompatibilityEnv(options) {
     const { owned, ownedContext } = resolveManagedSessionRestorePolicy(options);
-    return owned && ownedContext?.compatibilityUserAgent
-        ? { AGENT_BROWSER_USER_AGENT: ownedContext.compatibilityUserAgent }
-        : {};
+    if (!owned || !ownedContext)
+        return {};
+    const parentEnv = options.parentEnv ?? process.env;
+    const callEnv = options.env ?? {};
+    const explicitRawInterval = Object.hasOwn(callEnv, "AGENT_BROWSER_AUTOSAVE_INTERVAL_MS")
+        ? callEnv.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS
+        : parentEnv.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS;
+    const explicitIntervalMatches = resolveExplicitAutosaveInterval(explicitRawInterval) === ownedContext.headedManagedAutosaveInterval;
+    return {
+        ...(ownedContext.compatibilityUserAgent ? { AGENT_BROWSER_USER_AGENT: ownedContext.compatibilityUserAgent } : {}),
+        ...(ownedContext.headedManagedAutosaveInterval !== undefined && !explicitIntervalMatches ? { AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: ownedContext.headedManagedAutosaveInterval } : {}),
+    };
 }
 export function shouldOmitOwnedManagedSessionRestoreEnv(options) {
     return resolveManagedSessionRestorePolicy(options).owned && closesBrowserSession(options.args);
@@ -365,6 +380,8 @@ export function buildOwnedManagedSessionRestoreContext(options) {
     return {
         ...owned,
         compatibilityUserAgent: options.compatibilityUserAgent,
+        headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled,
+        headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
         expectedDaemonRestoreKey: enabled ? restoreKey : extractRequestedRestoreKey(options.args, owned.sessionName, effectiveEnv[AGENT_BROWSER_RESTORE_ENV]),
         protectedStorageEnv: enabled ? getManagedSessionRestoreProtectedStorageEnv(true, effectiveEnv) : undefined,
         restoreDecision: optedOut ? "opted-out" : incompatible ? "incompatible" : "enabled",

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Retain only wrapper-owned managed-restore snapshots after successful close operations.
- * Responsibilities: Persist atomic per-snapshot ownership records, self-heal malformed records, and apply per-key plus superseded-generation retention without deleting unproven paths.
- * Scope: Snapshot ownership and pruning only; restore eligibility and daemon policy live in sibling modules.
- */
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join } from "node:path";

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

@@ -1,6 +1,3 @@
-// Purpose: Prevent native tool calls from crossing wrapper-owned managed-state boundaries.
-// Responsibilities: Guard destructive global state operations, foreign checkout restore/state references, and browser file access to local agent-browser state.
-// Scope: Pre-spawn policy only; result redaction and managed snapshot retention live elsewhere.
 import { realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -9,7 +6,7 @@ import { needsManagedSession } from "./command-policy.js";
 import { getScreenshotPathTokenIndex } from "./orchestration/browser-run/artifact-paths.js";
 import { parseBatchCommandArgument, parseUserBatchStdin } from "./orchestration/batch-stdin.js";
 import { isUnverifiedPageTransitionCommand } from "./command-taxonomy.js";
-import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, extractExplicitSessionName, optionalGlobalValueFlagConsumesNext, } from "./argv-grammar.js";
+import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, extractExplicitSessionName, isUpstreamEnvFlagEnabled, optionalGlobalValueFlagConsumesNext, } from "./argv-grammar.js";
 import { extractManagedSessionRestoreKeys, isWrapperManagedSessionName } from "./managed-session-capabilities.js";
 import { agentBrowserConfigIsPresent } from "./managed-session-restore.js";
 import { createManagedSessionRestoreKey, hasManagedSessionRestoreProjectIdentity } from "./managed-session-storage.js";
@@ -262,9 +259,6 @@ function getBrowserFileOperands(args, env) {
         values.push(...positionals.slice(1));
     return values.filter((value) => typeof value === "string" && value.length > 0);
 }
-function isUpstreamEnvFlagEnabled(value) {
-    return value !== undefined && !["", "0", "false", "no"].includes(value.toLowerCase());
-}
 function rawBrowserArgsEnableFileAccess(args, env) {
     return getRawBrowserArgsValues(args, env).some((value) => typeof value === "string" && /(?:^|[,\p{White_Space}])--(?:allow-file-access(?:-from-files)?|disable-web-security)(?=$|[=,\p{White_Space}])/iu.test(value));
 }

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Resolve and secure the filesystem identity used by automatic managed-session restore.
- * Responsibilities: Bind restore keys to one Git checkout generation, validate trusted HOME ancestry, and prepare owner-only upstream state directories.
- * Scope: Filesystem policy only; argv/session ownership and snapshot retention live in sibling modules.
- */
 import { createHash, randomUUID } from "node:crypto";
 import { linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";

package/dist/extensions/agent-browser/lib/navigation-policy.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Keep wrapper-side navigation policy parsing and evaluation small and explicit.
- * Responsibilities: Parse allowed-domain argv values and detect final-page host escapes.
- * Scope: Wrapper diagnostics only; upstream remains responsible for browser-time enforcement.
- */
 function normalizeDomainEntry(value) {
     let candidate = value.trim().toLowerCase();
     if (!candidate)

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

@@ -1,7 +1,7 @@
 import { stat } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { isCloseCommand, isOpenNavigationCommand } from "../../command-taxonomy.js";
-import { boundElectronProbeString } from "../../electron/text.js";
+import { boundElectronProbeString } from "../../electron/cdp.js";
 import { executableExistsOnPath } from "../../executable-path.js";
 import { isHttpOrHttpsUrl } from "../../input-modes/job.js";
 import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";

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

@@ -1,8 +1,10 @@
 import { cleanupElectronLaunchResources } from "../../electron/cleanup.js";
-import { getCompiledSemanticActionCommandIndex, getCompiledSemanticActionSessionPrefix, isCompiledSemanticActionFindCommand, redactNetworkSourceLookupSurface, } from "../../input-modes.js";
-import { buildAgentBrowserNextActions, buildAgentBrowserResultCategoryDetails, } from "../../results.js";
+import { getCompiledSemanticActionCommandIndex, getCompiledSemanticActionSessionPrefix, isCompiledSemanticActionFindCommand } from "../../input-modes/semantic-action.js";
+import { redactNetworkSourceLookupSurface } from "../../input-modes/lookups.js";
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
 import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";
-import { AgentBrowserNextActionCollector, alignPageChangeSummaryNextActionIds, applyNamespaceToNextActions, isStandaloneSnapshotNextAction, withOptionalSessionArgs, } from "../../results/next-actions.js";
+import { alignPageChangeSummaryNextActionIds, appendUniqueAgentBrowserNextActions, applyNamespaceToNextActions, isStandaloneSnapshotNextAction, withOptionalSessionArgs, } from "../../results/next-actions.js";
 import { buildConnectedSessionNextActions, buildNoActivePageNextActions, buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions, } from "../../results/recovery-next-actions.js";
 import { buildRichInputRecoveryDiagnostic, buildRichInputRecoveryNextActions, buildVisibleRefFallbackNextActions, formatRichInputRecoveryText, formatVisibleRefFallbackText, sanitizeVisibleRefFallbackDiagnostic, } from "../../results/selector-recovery.js";
 import { buildNoActivePageRefSnapshotInvalidation, isNoActivePageSnapshotFailure, } from "../../session-page-state.js";
@@ -257,68 +259,75 @@ function buildDialogTimeoutNextActions(options) {
     ];
 }
 function buildResultNextActions(options) {
-    const nextActionCollector = new AgentBrowserNextActionCollector(options.presentation.nextActions);
+    let nextActions = options.presentation.nextActions ? [...options.presentation.nextActions] : [];
+    const append = (actions) => {
+        if (actions && actions.length > 0)
+            nextActions.push(...actions);
+    };
+    const appendUnique = (actions) => {
+        appendUniqueAgentBrowserNextActions(nextActions, actions);
+    };
     if (options.categoryDetails.resultCategory === "success" && options.executionPlan.commandInfo.command === "connect" && !options.electronLaunchRecord)
-        nextActionCollector.appendUnique(buildConnectedSessionNextActions(options.executionPlan.sessionName));
+        appendUnique(buildConnectedSessionNextActions(options.executionPlan.sessionName));
     if (options.noActivePageSnapshotFailure)
-        nextActionCollector.appendUnique(buildNoActivePageNextActions(options.executionPlan.sessionName));
+        appendUnique(buildNoActivePageNextActions(options.executionPlan.sessionName));
     if (options.aboutBlankSessionMismatch) {
-        nextActionCollector.appendUnique(buildSessionTabRecoveryNextActions({ kind: "about-blank", recoveryApplied: options.aboutBlankSessionMismatch.recoveryApplied, sessionName: options.executionPlan.sessionName, tabCorrection: options.aboutBlankSessionMismatch.recoveryApplied ? options.sessionTabCorrection : undefined, target: { title: options.aboutBlankSessionMismatch.targetTitle, url: options.aboutBlankSessionMismatch.targetUrl } }));
+        appendUnique(buildSessionTabRecoveryNextActions({ kind: "about-blank", recoveryApplied: options.aboutBlankSessionMismatch.recoveryApplied, sessionName: options.executionPlan.sessionName, tabCorrection: options.aboutBlankSessionMismatch.recoveryApplied ? options.sessionTabCorrection : undefined, target: { title: options.aboutBlankSessionMismatch.targetTitle, url: options.aboutBlankSessionMismatch.targetUrl } }));
         if (!options.aboutBlankSessionMismatch.recoveryApplied)
-            nextActionCollector.removeWhere(isStandaloneSnapshotNextAction);
+            nextActions = nextActions.filter((action) => !isStandaloneSnapshotNextAction(action));
     }
     else if (options.categoryDetails.resultCategory === "success" && (options.sessionTabCorrection || options.openResultTabCorrection))
-        nextActionCollector.appendUnique(buildSessionTabRecoveryNextActions({ kind: "tab-drift", recoveryApplied: true, sessionName: options.executionPlan.sessionName, tabCorrection: options.sessionTabCorrection ?? options.openResultTabCorrection, target: options.currentSessionTabTarget ?? options.priorSessionTabTarget }));
+        appendUnique(buildSessionTabRecoveryNextActions({ kind: "tab-drift", recoveryApplied: true, sessionName: options.executionPlan.sessionName, tabCorrection: options.sessionTabCorrection ?? options.openResultTabCorrection, target: options.currentSessionTabTarget ?? options.priorSessionTabTarget }));
     if (options.categoryDetails.failureCategory === "stale-ref")
-        nextActionCollector.replace(buildSessionAwareStaleRefNextActions(options.executionPlan.sessionName));
+        nextActions = [...buildSessionAwareStaleRefNextActions(options.executionPlan.sessionName)];
     if (options.visibleRefFallbackDiagnostic)
-        nextActionCollector.append(buildVisibleRefFallbackNextActions({ diagnostic: options.visibleRefFallbackDiagnostic, sessionName: options.visibleRefFallbackSessionName }));
+        append(buildVisibleRefFallbackNextActions({ diagnostic: options.visibleRefFallbackDiagnostic, sessionName: options.visibleRefFallbackSessionName }));
     if (options.richInputRecoveryDiagnostic)
-        nextActionCollector.append(buildRichInputRecoveryNextActions({ diagnostic: options.richInputRecoveryDiagnostic, sessionName: options.visibleRefFallbackSessionName }));
+        append(buildRichInputRecoveryNextActions({ diagnostic: options.richInputRecoveryDiagnostic, sessionName: options.visibleRefFallbackSessionName }));
     if (options.electronPostCommandHealth) {
         const electronRecord = options.electronLaunchRecords.get(options.electronPostCommandHealth.launchId);
         if (electronRecord)
-            nextActionCollector.appendUnique(buildElectronLifecycleNextActions(electronRecord));
+            appendUnique(buildElectronLifecycleNextActions(electronRecord));
     }
     if (options.electronSessionMismatch) {
         const electronRecord = options.electronLaunchRecords.get(options.electronSessionMismatch.launchId);
         if (electronRecord)
-            nextActionCollector.appendUnique(buildElectronMismatchNextActions(electronRecord, options.electronSessionMismatch.liveTarget));
+            appendUnique(buildElectronMismatchNextActions(electronRecord, options.electronSessionMismatch.liveTarget));
     }
     if (options.categoryDetails.failureCategory === "selector-not-found" && options.redactedCompiledSemanticAction) {
         const candidateActions = buildSemanticActionCandidateActions(options.redactedCompiledSemanticAction);
         if (candidateActions.length > 0)
-            nextActionCollector.append(candidateActions);
+            append(candidateActions);
     }
     if (options.overlayBlockerDiagnostic)
-        nextActionCollector.append(buildOverlayBlockerNextActions({ diagnostic: options.overlayBlockerDiagnostic, sessionName: options.executionPlan.sessionName }));
+        append(buildOverlayBlockerNextActions({ diagnostic: options.overlayBlockerDiagnostic, sessionName: options.executionPlan.sessionName }));
     if (options.fillVerificationDiagnostic)
-        nextActionCollector.appendUnique(buildFillVerificationNextActions(options.fillVerificationDiagnostic, options.executionPlan.sessionName));
+        appendUnique(buildFillVerificationNextActions(options.fillVerificationDiagnostic, options.executionPlan.sessionName));
     if (options.electronRefFreshnessDiagnostic)
-        nextActionCollector.appendUnique(buildElectronRefFreshnessNextActions(options.executionPlan.sessionName));
+        appendUnique(buildElectronRefFreshnessNextActions(options.executionPlan.sessionName));
     if (options.selectorTextVisibilityDiagnostics.length > 0)
-        nextActionCollector.append(buildSelectorTextVisibilityNextActions({ diagnostics: options.selectorTextVisibilityDiagnostics, sessionName: options.executionPlan.sessionName }));
+        append(buildSelectorTextVisibilityNextActions({ diagnostics: options.selectorTextVisibilityDiagnostics, sessionName: options.executionPlan.sessionName }));
     if (options.electronBroadGetTextScopeDiagnostics.length > 0)
-        nextActionCollector.append(buildElectronBroadGetTextScopeNextActions({ diagnostics: options.electronBroadGetTextScopeDiagnostics, sessionName: options.executionPlan.sessionName }));
+        append(buildElectronBroadGetTextScopeNextActions({ diagnostics: options.electronBroadGetTextScopeDiagnostics, sessionName: options.executionPlan.sessionName }));
     if (options.sourceLookup?.electronContext)
-        nextActionCollector.appendUnique(buildSourceLookupElectronNextActions(options.sourceLookup));
+        appendUnique(buildSourceLookupElectronNextActions(options.sourceLookup));
     if (options.clickDispatchDiagnostic)
-        nextActionCollector.append(buildClickDispatchNextActions({ commandTokens: options.commandTokens, diagnostic: options.clickDispatchDiagnostic, sessionName: options.executionPlan.sessionName }));
+        append(buildClickDispatchNextActions({ commandTokens: options.commandTokens, diagnostic: options.clickDispatchDiagnostic, sessionName: options.executionPlan.sessionName }));
     if (options.scrollNoopDiagnostic)
-        nextActionCollector.append(buildScrollNoopNextActions(options.executionPlan.sessionName));
+        append(buildScrollNoopNextActions(options.executionPlan.sessionName));
     if (options.comboboxFocusDiagnostic)
-        nextActionCollector.append(buildComboboxFocusNextActions(options.executionPlan.sessionName));
+        append(buildComboboxFocusNextActions(options.executionPlan.sessionName));
     if (options.managedSessionOutcome)
-        nextActionCollector.appendUnique(buildManagedSessionFreshFailureNextActions(options.managedSessionOutcome));
+        appendUnique(buildManagedSessionFreshFailureNextActions(options.managedSessionOutcome));
     if (options.categoryDetails.failureCategory === "timeout" && options.processResult.timedOut) {
-        nextActionCollector.appendUnique(buildTimeoutPartialProgressNextActions(options));
-        nextActionCollector.appendUnique(buildDialogTimeoutNextActions({ command: options.executionPlan.commandInfo.command, sessionName: options.executionPlan.sessionName }));
+        appendUnique(buildTimeoutPartialProgressNextActions(options));
+        appendUnique(buildDialogTimeoutNextActions({ command: options.executionPlan.commandInfo.command, sessionName: options.executionPlan.sessionName }));
     }
     if (options.categoryDetails.failureCategory === "stale-ref" && options.redactedCompiledSemanticAction && isCompiledSemanticActionFindCommand(options.compiledSemanticAction))
-        nextActionCollector.append([{ id: "retry-semantic-action-after-stale-ref", params: { args: options.redactedCompiledSemanticAction.args }, reason: "Retry the same semantic target via its compiled find command after the upstream stale-ref failure proves the prior action did not execute.", safety: "Use only for the same intended target; direct stale @refs still require a fresh snapshot or stable locator before retrying.", tool: "agent_browser" }]);
+        append([{ id: "retry-semantic-action-after-stale-ref", params: { args: options.redactedCompiledSemanticAction.args }, reason: "Retry the same semantic target via its compiled find command after the upstream stale-ref failure proves the prior action did not execute.", safety: "Use only for the same intended target; direct stale @refs still require a fresh snapshot or stable locator before retrying.", tool: "agent_browser" }]);
     if (options.electronLaunchRecord)
-        nextActionCollector.append(buildAgentBrowserNextActions({ electron: { launchId: options.electronLaunchRecord.launchId, sessionName: options.electronLaunchRecord.sessionName, status: options.electronLaunchRecord.cleanupState }, failureCategory: options.categoryDetails.failureCategory, resultCategory: options.categoryDetails.resultCategory, successCategory: options.categoryDetails.successCategory }));
-    return nextActionCollector.toArray();
+        append(buildAgentBrowserNextActions({ electron: { launchId: options.electronLaunchRecord.launchId, sessionName: options.electronLaunchRecord.sessionName, status: options.electronLaunchRecord.cleanupState }, failureCategory: options.categoryDetails.failureCategory, resultCategory: options.categoryDetails.resultCategory, successCategory: options.categoryDetails.successCategory }));
+    return nextActions.length > 0 ? nextActions : undefined;
 }
 function buildAgentBrowserResultDetails(options, nextActions) {
     const publicVisibleRefFallbackDiagnostic = options.visibleRefFallbackDiagnostic ? sanitizeVisibleRefFallbackDiagnostic(options.visibleRefFallbackDiagnostic) : undefined;
@@ -358,6 +367,8 @@ function buildAgentBrowserResultDetails(options, nextActions) {
         fullOutputPath: options.parseFailureOutput.fullOutputPath ?? options.presentation.fullOutputPath,
         fullOutputPaths: options.presentation.fullOutputPaths,
         fullOutputUnavailable: options.parseFailureOutput.fullOutputUnavailable,
+        managedSessionHeadedAutosaveDisabled: options.managedSessionHeadedAutosaveDisabled,
+        managedSessionHeadedAutosaveInterval: options.managedSessionHeadedAutosaveInterval,
         managedSessionOutcome: options.managedSessionOutcome,
         imagePath: options.presentation.imagePath,
         imagePaths: options.presentation.imagePaths,

package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-daemon-policy.js

@@ -1,24 +1,28 @@
-/**
- * Purpose: Coordinate wrapper-owned managed-session daemon inspection, reuse, and cleanup policy.
- * Responsibilities: Serialize daemon policy decisions, verify live restore keys, and close owned sessions with snapshot cleanup.
- * Scope: Managed-session daemon policy only; page state and browser-result shaping live in sibling modules.
- * Usage: Called by browser-run preparation, Electron host probes, result handling, and extension shutdown cleanup.
- * Invariants/Assumptions: Every owned daemon decision holds the cross-process policy lock until its caller finishes the related operation.
- */
 import { rm } from "node:fs/promises";
 import { acquireManagedSessionPolicyLock } from "../../managed-session-policy-lock.js";
-import { pruneOwnedManagedSessionRestoreSnapshots, } from "../../managed-session-restore.js";
+import { pruneOwnedManagedSessionRestoreSnapshots, resolveExplicitAutosaveInterval, } from "../../managed-session-restore.js";
 import { isManagedSessionRestoreKey } from "../../managed-session-storage.js";
 import { isRecord } from "../../parsing.js";
 import { runAgentBrowserProcess } from "../../process.js";
-import { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "../../results.js";
+import { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "../../results/envelope.js";
 import { redactInvocationArgs } from "../../runtime.js";
-const MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS = 5_000;
+const MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS = 35_000;
+const RUNNING_HEADED_AUTOSAVE_POLICY_CHANGE_ERROR = "AGENT_BROWSER_AUTOSAVE_INTERVAL_MS cannot change a running wrapper-owned headed session's launch-time periodic autosave interval. Close that session first, then retry with sessionMode: \"fresh\" so the new daemon starts with the requested interval.";
+export function getRunningHeadedAutosavePolicyChangeError(recordedInterval, closeCommand = false) {
+    const explicitInterval = resolveExplicitAutosaveInterval(process.env.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS);
+    return recordedInterval !== undefined && !closeCommand && explicitInterval !== undefined && explicitInterval !== recordedInterval
+        ? RUNNING_HEADED_AUTOSAVE_POLICY_CHANGE_ERROR
+        : undefined;
+}
+function getHeadedManagedAutosaveEnv(interval) {
+    return interval !== undefined ? { AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: interval } : undefined;
+}
 export async function inspectManagedSessionDaemon(options) {
     const processResult = await runAgentBrowserProcess({
         allowManagedSessionTarget: options.allowManagedSessionTarget,
         args: ["--json", "--namespace", options.namespace ?? "", "--session", options.sessionName, "session", "info"],
         cwd: options.cwd,
+        env: getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval),
         preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
         signal: options.signal,
         timeoutMs: options.timeoutMs ?? MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS,
@@ -65,6 +69,7 @@ export async function acquireOwnedManagedSessionDaemonPolicy(options) {
         const daemon = await inspectManagedSessionDaemon({
             allowManagedSessionTarget: true,
             cwd: context.cwd,
+            headedManagedAutosaveInterval: context.headedManagedAutosaveInterval,
             namespace: context.namespace,
             sessionName: context.sessionName,
             signal,
@@ -128,6 +133,7 @@ export async function closeManagedSession(options) {
         const daemon = await inspectManagedSessionDaemon({
             allowManagedSessionTarget: true,
             cwd: options.cwd,
+            headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
             namespace: options.namespace,
             preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
             sessionName: options.sessionName,
@@ -142,7 +148,7 @@ export async function closeManagedSession(options) {
         const processResult = await runAgentBrowserProcess({
             args: closeArgs,
             cwd: options.cwd,
-            env: { AGENT_BROWSER_JSON: "1" },
+            env: { AGENT_BROWSER_JSON: "1", ...getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval) },
             managedSessionRestoreState: options.restoreState,
             ownedManagedSession: true,
             preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,

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

@@ -1,7 +1,7 @@
 import { mkdir, stat, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { isRecord } from "../../../parsing.js";
-import { buildAgentBrowserResultCategoryDetails } from "../../../results.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../../results/categories.js";
 import { formatSessionArtifactRetentionSummary, mergeSessionArtifactManifest } from "../../../results/artifact-manifest.js";
 import { redactSensitiveText } from "../../../runtime.js";
 import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";

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

@@ -1,5 +1,5 @@
 import { isRecord } from "../../../parsing.js";
-import { buildAgentBrowserResultCategoryDetails } from "../../../results.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../../results/categories.js";
 import { redactSensitiveText } from "../../../runtime.js";
 import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
 function parseNetworkRequestsPageFilterRequest(commandTokens) {

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

@@ -1,5 +1,5 @@
 import { isRecord } from "../../../parsing.js";
-import { buildAgentBrowserResultCategoryDetails } from "../../../results.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../../results/categories.js";
 import { applyNamespaceToNextActions } from "../../../results/next-actions.js";
 import { buildScrollNoopNextActions } from "../diagnostics.js";
 import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";

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

@@ -1,5 +1,5 @@
 import { isRecord } from "../../../parsing.js";
-import { buildAgentBrowserResultCategoryDetails } from "../../../results.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../../results/categories.js";
 import { buildSnapshotPresentation } from "../../../results/snapshot.js";
 import { extractRefSnapshotFromData } from "../../../session-page-state.js";
 import { collectScrollPositionSnapshot } from "../diagnostics.js";

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

@@ -1,25 +1,26 @@
 import { copyFile, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import { getBooleanFlagValue, isUpstreamEnvFlagEnabled } from "../../argv-grammar.js";
 import { isCloseCommand } from "../../command-taxonomy.js";
 import { cleanupElectronLaunchResources } from "../../electron/cleanup.js";
 import { launchElectronApp } from "../../electron/launch.js";
 import { pathExists } from "../../fs-utils.js";
-import { getCompiledSemanticActionSessionPrefix } from "../../input-modes.js";
+import { getCompiledSemanticActionSessionPrefix } from "../../input-modes/semantic-action.js";
 import { tryDirectAnchorDownload } from "./prepare/direct-anchor-download.js";
 import { tryNetworkRequestsPageFilter } from "./prepare/network-page-filter.js";
 import { tryContainerScroll, tryPageScrollTo } from "./prepare/scroll-shims.js";
 import { trySnapshotFilter } from "./prepare/snapshot-filter.js";
 import { commandTimeoutNeedsActivePageUrl, getCommandAwareProcessTimeoutMs } from "./prepare/wait-timeouts.js";
-import { getPersistentSessionArtifactStore } from "./session-artifacts.js";
-import { buildAgentBrowserResultCategoryDetails } from "../../results.js";
+import { getPersistentSessionArtifactStore } from "./session-state.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
 import { applyNamespaceToNextActions } from "../../results/next-actions.js";
 import { buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions } from "../../results/recovery-next-actions.js";
 import { resolveVisibleRefActionFromSnapshot } from "../../results/selector-recovery.js";
 import { extractRefSnapshotFromData } from "../../session-page-state.js";
 import { buildExecutionPlan, createFreshSessionName, extractCommandTokens, getDefaultHeadlessCompatUserAgent, redactInvocationArgs, } from "../../runtime.js";
-import { buildOwnedManagedSessionRestoreContext, canonicalizeOwnedManagedSessionCloseArgs, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
+import { buildOwnedManagedSessionRestoreContext, canonicalizeOwnedManagedSessionCloseArgs, resolveExplicitAutosaveInterval, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { getCallerOwnedSessionLivePageVerificationRequirement, getManagedSessionStateAccessValidationError, getManagedSessionTargetAccessValidationError, } from "../../managed-session-state-policy.js";
-import { acquireOwnedManagedSessionDaemonPolicy } from "./managed-session-daemon-policy.js";
+import { acquireOwnedManagedSessionDaemonPolicy, getRunningHeadedAutosavePolicyChangeError } from "./managed-session-daemon-policy.js";
 import { applyOpenResultTabCorrection, buildManagedSessionOutcome, buildPinnedBatchPlan, buildSessionDetailFields, buildStaleRefPreflight, getSessionContextKey, extractStringResultField, collectAnySessionTabSelection, collectSessionTabSelection, getGuardedRefUsage, getTraceOwnerGuardMessage, runSessionCommandData, shouldPinSessionTabForCommand, } from "./session-state.js";
 import { parseBatchStdinJsonArray } from "../batch-stdin.js";
 import { buildElectronHostFailureResult, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
@@ -397,11 +398,27 @@ export async function prepareBrowserRun(options) {
         if (!executionPlan.validationError && managedStateAccessError)
             executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: managedStateAccessError };
         const recordedOwnedSession = ownedSessionKey ? state.ownedManagedSessions.get(ownedSessionKey) : undefined;
+        const targetsCurrentManagedSession = state.managedSessionActive
+            && ownedSessionKey === getSessionContextKey(state.managedSessionName, state.managedSessionNamespace);
+        const retainedHeadedAutosaveDisabled = recordedOwnedSession?.headedManagedAutosaveDisabled === true
+            || (targetsCurrentManagedSession && state.managedSessionHeadedAutosaveDisabled === true);
+        const retainedHeadedAutosaveInterval = recordedOwnedSession?.headedManagedAutosaveInterval
+            ?? (targetsCurrentManagedSession ? state.managedSessionHeadedAutosaveInterval : undefined);
+        const explicitAutosaveInterval = resolveExplicitAutosaveInterval(process.env.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS);
+        const autosavePolicyChangeError = getRunningHeadedAutosavePolicyChangeError(retainedHeadedAutosaveInterval, isCloseCommand(executionPlan.commandInfo.command));
+        if (!executionPlan.validationError && autosavePolicyChangeError) {
+            executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: autosavePolicyChangeError };
+        }
+        const headedLaunch = getBooleanFlagValue(executionPlan.effectiveArgs, "--headed") ?? isUpstreamEnvFlagEnabled(process.env.AGENT_BROWSER_HEADED);
+        const headedManagedAutosaveDisabled = retainedHeadedAutosaveDisabled || (explicitAutosaveInterval === undefined && headedLaunch);
+        const headedManagedAutosaveInterval = retainedHeadedAutosaveInterval ?? (headedLaunch ? explicitAutosaveInterval ?? "0" : undefined);
         const ownedManagedSession = buildOwnedManagedSessionRestoreContext({
             args: executionPlan.effectiveArgs,
             cwd: recordedOwnedSession?.cwd ?? cwd,
             currentManagedSessionName: state.managedSessionName,
             currentManagedSessionNamespace: state.managedSessionNamespace,
+            headedManagedAutosaveDisabled,
+            headedManagedAutosaveInterval,
             managedSessionName: executionPlan.managedSessionName,
             namespace: executionPlan.namespace,
             recordedOwnedSession,