pi-agent-browser-native 0.8.2 → 0.8.3

package/dist/extensions/agent-browser/lib/orchestration/script-mode.js

@@ -1,18 +1,22 @@
 import { stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { AGENT_BROWSER_SCRIPT_FINAL_OUTPUT_MAX_BYTES, createAgentBrowserScriptCloseArgs, isAgentBrowserScriptSessionName, } from "../input-modes/script.js";
 import { isRecord } from "../parsing.js";
+import { appendBrowserTransition, getBrowserRecord } from "../browser-transcript.js";
 import { redactSensitiveText } from "../runtime.js";
 import { attachInlineImage } from "../results/presentation/artifacts.js";
 import { projectAgentBrowserObservation } from "../results/presentation/content.js";
 import { redactPresentationData } from "../results/presentation/diagnostics.js";
-const SCRIPT_SESSION_ENTRY_TYPE = "agent-browser-script-session";
-// Retire outstanding pre-0.7 isolated-session leases when an old transcript resumes.
-export function getScriptSessionLeasesFromBranch(branch) {
+// The offline converter retains outstanding isolated-session cleanup facts in canonical events.
+export function getScriptSessionLeasesFromBranch(branch, ownerSessionId) {
     const leases = new Map();
     for (const entry of branch) {
-        if (!isRecord(entry) || entry.type !== "custom" || entry.customType !== SCRIPT_SESSION_ENTRY_TYPE || !isRecord(entry.data))
+        const lease = getBrowserRecord(entry)?.event.state.scriptLease;
+        if (!isRecord(lease))
             continue;
-        const { cleanup, closeCommandArgs, launchAttempted, sessionName } = entry.data;
+        if (ownerSessionId !== undefined && lease.ownerSessionId !== ownerSessionId)
+            continue;
+        const { cleanup, closeCommandArgs, launchAttempted, sessionName } = lease;
         if (!isAgentBrowserScriptSessionName(sessionName))
             continue;
         const expected = createAgentBrowserScriptCloseArgs(sessionName);
@@ -20,12 +24,13 @@ export function getScriptSessionLeasesFromBranch(branch) {
             || !Array.isArray(closeCommandArgs) || closeCommandArgs.length !== expected.length
             || !closeCommandArgs.every((token, index) => token === expected[index]))
             continue;
-        leases.set(sessionName, { cleanup, closeCommandArgs: expected, launchAttempted: true, sessionName });
+        leases.set(sessionName, { cleanup, closeCommandArgs: expected, launchAttempted: true, sessionName, ownerSessionId: typeof lease.ownerSessionId === "string" ? lease.ownerSessionId : undefined });
     }
     return leases;
 }
-export function appendScriptSessionLease(pi, sessionName, cleanup) {
-    pi.appendEntry(SCRIPT_SESSION_ENTRY_TYPE, { cleanup, closeCommandArgs: createAgentBrowserScriptCloseArgs(sessionName), launchAttempted: true, sessionName });
+export function appendScriptSessionLease(pi, sessionName, cleanup, ownerSessionId) {
+    appendBrowserTransition(pi, { event: { version: 1, phase: "state", operationId: randomUUID(), toolCallId: "cleanup", commandIndex: 0, isError: cleanup !== "closed",
+            state: { scriptLease: { cleanup, closeCommandArgs: createAgentBrowserScriptCloseArgs(sessionName), launchAttempted: true, sessionName, ownerSessionId } } } });
 }
 export function createBrowserCodeOutput() {
     const images = new Map();

package/dist/extensions/agent-browser/lib/playbook.js

@@ -12,7 +12,7 @@ export const QUICK_START_GUIDELINES = [
     "Use { args: [\"batch\", \"--bail\"], stdin: \"[[\\\"fill\\\",\\\"@e1\\\",\\\"text\\\"],[\\\"click\\\",\\\"@e2\\\"]]\" } for same-snapshot form fields followed by submit. Split if a fill rerenders later fields. Add native condition waits after navigation-prone actions; a click alone does not prove the destination loaded. Avoid blind mutation retries after timeout.",
     "agent_browser_code takes { code, session?, namespace?, timeoutMs?, outputPath? }. JavaScript globals are fresh for every call; the selected browser persists and is shared with agent_browser. Use await browser({ args, stdin?, timeoutMs? }), inspect result.success, and emit selected JSON instead of whole envelopes. Use emitImage(result.imageObservations[0]) only when image inspection is needed; image handles belong to the current code call. No imports or host filesystem/network/process APIs are exposed.",
     "Example agent_browser_code: { code: 'const result = await browser({args:[\"get\",\"title\"]}); if (!result.success) { emit(result); } else { emit({title:result.data}); }' }. Native batch still avoids extra CLI processes for fixed segments inside code. Explicit session/namespace controls select the browser for this cell without changing the default browser.",
-    "Call agent_browser_tools with no fields for inventory, or { enable: [\"action\", \"qa\", \"electron\", \"source\", \"network\"] } for advanced native tools. It adds agent_browser_action, agent_browser_qa, agent_browser_electron, agent_browser_source, and agent_browser_network_source without disabling other tools. Their specialized instructions appear when activated.",
+    "Call agent_browser_tools with no fields for inventory, or { enable: [\"action\", \"qa\", \"electron\", \"source\", \"network\"] } for advanced native tools. It adds agent_browser_action, agent_browser_qa, agent_browser_electron, agent_browser_source, and agent_browser_network_source without disabling other tools. The browser instructions cover these capabilities; activation reveals their selected tool declarations.",
     "Use read <url> for readable web text; get title/url, get text/html/value/count <selector>, or get attr <selector> <name> for targeted state. For eval --stdin, put JavaScript in stdin and return the desired value. outputPath saves result data and must differ from screenshot/download/recording paths. Use --json only when JSON text is needed.",
     "For artifacts, verify artifactVerification and artifacts before reporting success. A pending recording is not verified output; install ffmpeg before starting and pair start with stop. Native download owns the click and saves Blob/redirect downloads. Close keeps explicitly saved files. Save promptGuard-required paths before close. Screenshot pixels are not browser CSS coordinates: use imageObservations geometry (dimensions, viewport, crop/origin, scroll and DPR) before any visual-coordinate action; full-page and element captures are not current-viewport coordinates, and Pi resizing only maps sent pixels to original image pixels.",
     "Follow model-visible nextActions when present, including identity and stdin, instead of guessing commands. Treat native pending confirmations and unknown mutation outcomes as inspection boundaries. For dense snapshots, inspect Omitted high-value controls before reading a full spill.",
@@ -38,6 +38,13 @@ export const ADVANCED_TOOL_PROMPT_GUIDELINES = {
     ],
 };
 export const WEB_SEARCH_PROMPT_GUIDELINE = "Prefer agent_browser_web_search for current or external web facts and URL discovery over public search-engine forms that can hit anti-bot/CAPTCHA-gated pages. For research before implementation, pass searchType: deep-lite unless webSearch.defaultSearchType already does; omit it for everyday lookups so config/auto wins. Provider rank is not proof of authority: when correctness or version matters, prefer the vendor or project's primary current docs, inspect page-date and version clues, and constrain one follow-up after discovering the official domain (Exa includeDomains; Brave site: in query). Do not count URL aliases as independent sources. Use agent_browser after you have a target URL that needs interaction, screenshots, or DOM inspection.";
+export const WEB_SEARCH_TOOL_PROMPT_GUIDELINES = [
+    WEB_SEARCH_PROMPT_GUIDELINE,
+    "agent_browser_web_search chooses Exa or Brave from configured keys; when both are available, Exa is preferred by default unless webSearch.preferredProvider says otherwise. Use provider only when the user/config calls for a specific provider.",
+    "Use Exa deep only when deep-lite may miss angles, and deep-reasoning only for exhaustive or still-thin research. Do not run parallel agent_browser_web_search calls; make one high-signal query, inspect its results, then at most one follow-up.",
+    "If agent_browser_web_search returns HTTP 429, stop searching and tell the user the API plan/rate limit needs time or a plan change.",
+    "After using agent_browser_web_search, cite result URLs in the final answer when web evidence informed the answer.",
+];
 export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     QUICK_START_GUIDELINES[0],
     QUICK_START_GUIDELINES[3],
@@ -96,7 +103,7 @@ export const WRAPPER_TAB_RECOVERY_BEHAVIOR = [
     "If a known session target unexpectedly reports about:blank, agent_browser best-effort re-selects the prior intended target when it still exists; if recovery fails, it records the observed about:blank target and reports exact recovery guidance instead of treating the prior page as active.",
     "If upstream reports tab_gone, the pinned bound tab is gone; use details.nextActions (tab list / tab new) instead of assuming another tab is yours.",
 ];
-/** Tier A: always-on tool promptGuidelines (keep small; Tier B lives in SHARED_BROWSER_PLAYBOOK_GUIDELINES and docs). */
+/** Concise orientation included alongside the full operating playbook. */
 export const RUNTIME_PROMPT_GUIDELINES = [
     "Use agent_browser for one native command; batch --bail with JSON-array stdin for fixed sequences; agent_browser_code for loops/branches/aggregation. Return to the model at judgment boundaries. Use agent_browser_tools to discover/enable action, qa, electron, source, or network tools.",
     "agent_browser_code runs fresh JavaScript against the persistent browser: await browser({args, stdin?, timeoutMs?}), check result.success, emit(selected JSON), or emitImage(result.imageObservations[0]). No host APIs/imports; globals do not persist. Explicit session/namespace selects this cell's browser without changing the default.",

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

@@ -1,10 +1,3 @@
-const BROWSER_PROMPT_PATTERNS = [
-    /\b(?:agent[_ -]?browser|browser automation|eval\s+--stdin|screenshot|snapshot|tab\s+list)\b/i,
-    /\b(?:react\s+(?:tree|inspect|renders|suspense)|web\s+vitals|core\s+web\s+vitals|pushstate)\b/i,
-    /\b(?:live\s+docs?|online\s+research|research\s+(?:online|the\s+web)|search\s+(?:online|the\s+web)|web\s+research)\b/i,
-    /\bbrowser\b.*\b(?:automation|click|fill|navigate|open|page|screenshot|site|snapshot|tab|url|visit|web(?:site| page)?)\b/i,
-    /\b(?:browse|click|fill|login|navigate|open|visit)\b.*\b(?:https?:\/\/\S+|page|site|tab|url|web(?:site| page)?)\b/i,
-];
 const LEGACY_BASH_ALLOW_PATTERNS = [
     /\b(?:bash-oriented workflow|bash workflow)\b/i,
     /\b(?:use|via|through|with)\s+bash\b/i,
@@ -220,13 +213,6 @@ function getMessageText(content) {
         .filter((text) => text.length > 0)
         .join("\n");
 }
-export function shouldAppendBrowserSystemPrompt(prompt) {
-    const normalizedPrompt = prompt.trim();
-    if (normalizedPrompt.length === 0) {
-        return false;
-    }
-    return BROWSER_PROMPT_PATTERNS.some((pattern) => pattern.test(normalizedPrompt));
-}
 export function getLatestUserPrompt(branch) {
     for (let index = branch.length - 1; index >= 0; index -= 1) {
         const entry = branch[index];

package/dist/extensions/agent-browser/lib/results/presentation/large-output.js

@@ -101,7 +101,8 @@ export async function renderAgentBrowserObservation(options) {
         let spill;
         let spillError;
         try {
-            spill = await writeLargeOutputSpillFile({ data: { ...observation, ...(!options.json ? { text: prose } : {}) }, persistentArtifactStore: options.persistentArtifactStore, text });
+            const write = () => writeLargeOutputSpillFile({ data: { ...observation, ...(!options.json ? { text: prose } : {}) }, persistentArtifactStore: options.persistentArtifactStore, text });
+            spill = await (options.withArtifactWrite ? options.withArtifactWrite(write) : write());
             artifactManifest = applyArtifactManifest({ content: [], summary: "" }, artifactManifest, buildSpillArtifactEntries({
                 commandInfo: { command: typeof options.details.command === "string" ? options.details.command : undefined },
                 evictedArtifacts: spill.evictedArtifacts, path: spill.path, storageScope: spill.storageScope,

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

@@ -1,8 +1,8 @@
+import { randomUUID } from "node:crypto";
 import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
 import { getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "./argv-grammar.js";
-import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
-import { getBrowserResultMessage } from "./browser-transcript.js";
-import { isCloseAllCommand, isCloseCommand, isOpenNavigationCommand, isReadOnlyDiagnosticSessionTargetCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand, isWebMcpPageMutationCommand, isWindowOrDiffPageTransitionCommand } from "./command-taxonomy.js";
+import { getBrowserRecord, snapshotFromDefinition } from "./browser-transcript.js";
+import { isCloseCommand, isOpenNavigationCommand, isReadOnlyDiagnosticSessionTargetCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand, isWebMcpPageMutationCommand, isWindowOrDiffPageTransitionCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
 import { findReadConfirmation as findPendingReadConfirmation, parseReadConfirmation } from "./read-confirmation.js";
 import { getEditableRefEvidence } from "./results/editable-ref-evidence.js";
@@ -148,43 +148,6 @@ export function deriveSessionTabTarget(options) {
         return observedTarget ?? options.previousTarget;
     return undefined;
 }
-function batchContainsOnlyReadOnlyDiagnosticTargets(data) {
-    if (!Array.isArray(data) || data.length === 0) {
-        return false;
-    }
-    return data.every((item) => {
-        if (!isRecord(item))
-            return false;
-        const [command, subcommand] = extractBatchResultCommand(item);
-        return isReadOnlyDiagnosticSessionTargetCommand(command, subcommand);
-    });
-}
-function getRestoredSessionTabTarget(details, command, subcommand) {
-    if (isReadOnlyDiagnosticSessionTargetCommand(command, subcommand)) {
-        return undefined;
-    }
-    const storedTarget = isRecord(details.sessionTabTarget)
-        ? normalizeSessionTabTarget({
-            targetId: typeof details.sessionTabTarget.targetId === "string" ? details.sessionTabTarget.targetId : undefined,
-            title: typeof details.sessionTabTarget.title === "string" ? details.sessionTabTarget.title : undefined,
-            url: typeof details.sessionTabTarget.url === "string" ? details.sessionTabTarget.url : undefined,
-        })
-        : undefined;
-    if (command !== "batch") {
-        return storedTarget;
-    }
-    if (isRecord(details.compiledNetworkSourceLookup) || batchContainsOnlyReadOnlyDiagnosticTargets(details.data)) {
-        return undefined;
-    }
-    // The stored target includes post-batch live verification and native tab identity.
-    if (storedTarget || details.sessionTabTargetUnknown === true)
-        return storedTarget;
-    const batchTarget = extractSessionTabTargetFromBatchResults(details.data);
-    if (batchTarget) {
-        return batchTarget;
-    }
-    return storedTarget;
-}
 function extractRefSnapshotRefs(data) {
     if (!isRecord(data) || !isRecord(data.refs))
         return undefined;
@@ -278,62 +241,6 @@ export function extractLatestRefSnapshotStateFromBatchResults(data) {
     }
     return latestState;
 }
-function getRestoredRefSnapshotInvalidation(details, command) {
-    const invalidation = isRecord(details.refSnapshotInvalidation) ? details.refSnapshotInvalidation : undefined;
-    if (invalidation?.reason === "no-active-page")
-        return buildNoActivePageRefSnapshotInvalidation();
-    if (invalidation?.reason === "page-transition")
-        return buildPageTransitionRefSnapshotInvalidation(typeof invalidation.summary === "string" ? invalidation.summary : undefined);
-    const errorText = typeof details.error === "string"
-        ? details.error
-        : typeof details.summary === "string"
-            ? details.summary
-            : undefined;
-    return isNoActivePageSnapshotFailure(command, errorText) ? buildNoActivePageRefSnapshotInvalidation() : undefined;
-}
-function getRestoredRefSnapshot(details) {
-    const refSnapshot = isRecord(details.refSnapshot) ? details.refSnapshot : undefined;
-    if (!refSnapshot || !Array.isArray(refSnapshot.refIds))
-        return undefined;
-    const refIds = refSnapshot.refIds.filter((refId) => typeof refId === "string" && /^e\d+$/.test(refId));
-    const refRecord = isRecord(refSnapshot.refs) ? refSnapshot.refs : undefined;
-    const refEntries = refRecord
-        ? Object.fromEntries(refIds.flatMap((refId) => {
-            const entry = refRecord[refId];
-            if (!isRecord(entry) || typeof entry.name !== "string" || typeof entry.role !== "string")
-                return [];
-            const isContentEditable = typeof entry.isContentEditable === "boolean" ? entry.isContentEditable : undefined;
-            const isEditable = typeof entry.isEditable === "boolean" ? entry.isEditable : undefined;
-            return [[refId, { ...(isContentEditable !== undefined ? { isContentEditable } : {}), ...(isEditable !== undefined ? { isEditable } : {}), name: entry.name, role: entry.role }]];
-        }))
-        : undefined;
-    return {
-        refIds,
-        ...(refEntries && Object.keys(refEntries).length > 0 ? { refs: refEntries } : {}),
-        target: isRecord(refSnapshot.target)
-            ? normalizeSessionTabTarget({
-                title: typeof refSnapshot.target.title === "string" ? refSnapshot.target.title : undefined,
-                url: typeof refSnapshot.target.url === "string" ? refSnapshot.target.url : undefined,
-            })
-            : undefined,
-    };
-}
-function getLatestTabTargetOrder(targets, unknownTargets) {
-    let latestOrder = 0;
-    for (const target of targets.values())
-        latestOrder = Math.max(latestOrder, target.order);
-    for (const order of unknownTargets.values())
-        latestOrder = Math.max(latestOrder, order);
-    return latestOrder;
-}
-function getLatestRefStateOrder(snapshots, invalidations) {
-    let latestOrder = 0;
-    for (const snapshot of snapshots.values())
-        latestOrder = Math.max(latestOrder, snapshot.order);
-    for (const invalidation of invalidations.values())
-        latestOrder = Math.max(latestOrder, invalidation.order);
-    return latestOrder;
-}
 function shouldApplyTabTargetUpdate(current, unknownOrder, updateOrder) {
     return updateOrder >= Math.max(current?.order ?? 0, unknownOrder ?? 0);
 }
@@ -342,7 +249,7 @@ function shouldApplyRefStateUpdate(options) {
     return options.updateOrder >= currentOrder;
 }
 function stripRefSnapshotOrder(snapshot) {
-    return snapshot ? { refIds: snapshot.refIds, ...(snapshot.refs ? { refs: snapshot.refs } : {}), target: snapshot.target } : undefined;
+    return snapshot ? { ...(snapshot.snapshotId ? { snapshotId: snapshot.snapshotId } : {}), ...(snapshot.generation ? { generation: snapshot.generation } : {}), refIds: snapshot.refIds, ...(snapshot.refs ? { refs: snapshot.refs } : {}), target: snapshot.target } : undefined;
 }
 function stripRefSnapshotInvalidationOrder(invalidation) {
     return invalidation ? { reason: invalidation.reason, summary: invalidation.summary } : undefined;
@@ -358,78 +265,96 @@ export class SessionPageState {
     tabTargetUnknownOrders = new Map();
     tabTargets = new Map();
     updateOrder = 0;
+    nativeGenerations = new Map();
+    pending = new Map();
     static fromBranch(branch) {
         const state = new SessionPageState();
-        let restoredOrder = 0;
         for (const entry of branch) {
-            const message = getBrowserResultMessage(entry);
-            if (!message)
-                continue;
-            const details = isRecord(message.details) ? message.details : undefined;
-            if (!details)
+            const record = getBrowserRecord(entry);
+            if (record)
+                state.applyBrowserRecord(record);
+        }
+        for (const key of state.tabTargets.keys())
+            state.tabPinningReasons.set(key, "restore");
+        return state;
+    }
+    /** A command operates on its admitted state while the committed view is unavailable. */
+    fork() {
+        const state = new SessionPageState();
+        state.readConfirmations = new Map(this.readConfirmations);
+        state.refSnapshotInvalidations = new Map(this.refSnapshotInvalidations);
+        state.refSnapshots = new Map(this.refSnapshots);
+        state.tabPinningReasons = new Map(this.tabPinningReasons);
+        state.tabTargetUnknownOrders = new Map(this.tabTargetUnknownOrders);
+        state.tabTargets = new Map([...this.tabTargets].map(([key, value]) => [key, { ...value }]));
+        state.pending = new Map(this.pending);
+        state.nativeGenerations = new Map(this.nativeGenerations);
+        state.updateOrder = this.updateOrder;
+        return state;
+    }
+    views() {
+        return new Map([...new Set([...this.tabTargets.keys(), ...this.tabTargetUnknownOrders.keys(), ...this.refSnapshots.keys(), ...this.refSnapshotInvalidations.keys()])].map(key => [key, this.get(key)]));
+    }
+    /** The same reducer commits live observations and replays selected journal envelopes. */
+    applyBrowserRecord({ event, snapshot }) {
+        const update = this.beginUpdate();
+        const confirmation = parseReadConfirmation(event.state.readConfirmation);
+        for (const page of event.pages ?? []) {
+            const key = page.key;
+            if (event.phase === "begin") {
+                this.pending.set(key, { operationId: event.operationId, snapshot: this.refSnapshots.get(key) ?? this.pending.get(key)?.snapshot });
+                this.markTabTargetUnknown({ sessionName: key, update });
+                this.applyRefSnapshotInvalidation({ sessionName: key, update, invalidation: buildPageTransitionRefSnapshotInvalidation("This browser operation has no persisted finish. Inspect the current URL and take a fresh snapshot before using refs; changes may already have happened.") });
                 continue;
-            const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
-            const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
-            const sessionKey = getSessionPageStateKey(sessionName, namespace);
-            const args = Array.isArray(details.args) && details.args.every((arg) => typeof arg === "string") ? details.args : [];
-            const commandTokens = extractUpstreamCommandTokens(args);
-            const command = typeof details.command === "string" ? details.command : commandTokens[0];
-            const subcommand = typeof details.subcommand === "string" ? details.subcommand : commandTokens[1];
-            const batchCloseLifecycle = getSuccessfulBatchCloseLifecycle(details.batchSteps);
-            const closeAllApplied = details.closeAllApplied === true
-                || (message.isError !== true && isCloseAllCommand(commandTokens))
-                || batchHasSuccessfulCloseAll(details.batchSteps);
-            const lifecycleReset = (isCloseCommand(command) && message.isError !== true) || batchCloseLifecycle !== undefined;
-            if (closeAllApplied) {
-                restoredOrder += 1;
-                state.clearNamespace(namespace);
             }
-            else if (sessionKey && lifecycleReset) {
-                restoredOrder += 1;
-                state.clearSession(sessionKey);
-            }
-            const readConfirmation = parseReadConfirmation(details.readConfirmation);
-            if (readConfirmation)
-                state.applyReadConfirmation(readConfirmation, ++restoredOrder);
-            if (!sessionKey || ((closeAllApplied || lifecycleReset) && (isCloseCommand(command) || batchCloseLifecycle?.endsClosed === true)))
+            if (page.clear) {
+                this.clearSession(key);
                 continue;
-            const tabTarget = getRestoredSessionTabTarget(details, command, subcommand);
-            const tabTargetUnknown = details.sessionTabTargetUnknown === true;
-            const reopenPending = typeof details.sessionTabReopenPending === "boolean" ? details.sessionTabReopenPending : undefined;
-            const refSnapshotInvalidation = getRestoredRefSnapshotInvalidation(details, command);
-            const refSnapshot = refSnapshotInvalidation ? undefined : getRestoredRefSnapshot(details);
-            if (!tabTarget && !tabTargetUnknown && !refSnapshotInvalidation && !refSnapshot && reopenPending === undefined)
+            }
+            const pending = this.pending.get(key);
+            if (event.phase === "finish" && pending && pending.operationId !== event.operationId)
                 continue;
-            restoredOrder += 1;
-            if (tabTargetUnknown) {
-                state.refSnapshots.delete(sessionKey);
-                if (refSnapshotInvalidation)
-                    state.refSnapshotInvalidations.set(sessionKey, { ...refSnapshotInvalidation, order: restoredOrder });
-                else
-                    state.refSnapshotInvalidations.delete(sessionKey);
-                state.tabTargets.delete(sessionKey);
-                state.tabTargetUnknownOrders.set(sessionKey, restoredOrder);
+            if (page.unknown || page.refs.kind === "unknown") {
+                this.markTabTargetUnknown({ sessionName: key, update });
+                this.applyRefSnapshotInvalidation({ sessionName: key, update, invalidation: page.refs.kind === "unknown" && page.refs.invalidation
+                        ? page.refs.invalidation : buildPageTransitionRefSnapshotInvalidation("The browser target or operation outcome is unknown. Verify the current URL and take a fresh snapshot before using refs.") });
                 continue;
             }
-            if (tabTarget) {
-                state.tabTargetUnknownOrders.delete(sessionKey);
-                state.tabTargets.set(sessionKey, { order: restoredOrder, reopenPending: state.tabTargets.get(sessionKey)?.reopenPending, target: tabTarget });
+            if (page.target)
+                this.applyTabTarget({ sessionName: key, target: page.target, update });
+            else {
+                this.tabTargets.delete(key);
+                this.tabTargetUnknownOrders.delete(key);
+            }
+            if (page.reopenPending !== undefined)
+                this.setTabReopenPending({ pending: page.reopenPending, sessionName: key, update });
+            if (page.pinningReason)
+                this.markPinning(key, page.pinningReason);
+            else
+                this.tabPinningReasons.delete(key);
+            if (page.refs.kind === "replace") {
+                const definition = snapshot?.id === page.refs.snapshotId && snapshot.refs ? snapshotFromDefinition(snapshot)
+                    : { snapshotId: page.refs.snapshotId, refIds: [] };
+                this.applyRefSnapshot({ sessionName: key, snapshot: definition, fallbackTarget: page.target, update });
             }
-            const currentTarget = state.tabTargets.get(sessionKey);
-            if (currentTarget && reopenPending !== undefined)
-                currentTarget.reopenPending = reopenPending;
-            if (refSnapshotInvalidation) {
-                state.refSnapshots.delete(sessionKey);
-                state.refSnapshotInvalidations.set(sessionKey, { ...refSnapshotInvalidation, order: restoredOrder });
+            else if (page.refs.kind === "reuse") {
+                const candidate = pending?.snapshot ?? this.refSnapshots.get(key);
+                if (candidate?.snapshotId === page.refs.snapshotId)
+                    this.applyRefSnapshot({ sessionName: key, snapshot: candidate, fallbackTarget: page.target, update });
+                else
+                    this.applyRefSnapshotInvalidation({ sessionName: key, update, invalidation: buildPageTransitionRefSnapshotInvalidation("The ancestral snapshot definition is unavailable. Take a new complete snapshot before using refs.") });
             }
-            else if (refSnapshot) {
-                state.refSnapshotInvalidations.delete(sessionKey);
-                state.refSnapshots.set(sessionKey, { ...refSnapshot, order: restoredOrder });
+            else {
+                this.refSnapshots.delete(key);
+                if (page.refs.invalidation)
+                    this.applyRefSnapshotInvalidation({ sessionName: key, invalidation: page.refs.invalidation, update });
+                else
+                    this.refSnapshotInvalidations.delete(key);
             }
+            this.pending.delete(key);
         }
-        state.updateOrder = Math.max(restoredOrder, getLatestTabTargetOrder(state.tabTargets, state.tabTargetUnknownOrders), getLatestRefStateOrder(state.refSnapshots, state.refSnapshotInvalidations));
-        state.tabPinningReasons = new Map([...state.tabTargets.keys()].map((sessionName) => [sessionName, "restore"]));
-        return state;
+        if (confirmation)
+            this.applyReadConfirmation(confirmation, update);
     }
     beginUpdate() {
         this.updateOrder += 1;
@@ -437,6 +362,8 @@ export class SessionPageState {
     }
     reset() {
         this.readConfirmations.clear();
+        this.pending.clear();
+        this.nativeGenerations.clear();
         this.refSnapshotInvalidations = new Map();
         this.refSnapshots = new Map();
         this.tabPinningReasons = new Map();
@@ -490,11 +417,20 @@ export class SessionPageState {
         })) {
             return { ...this.get(options.sessionName), applied: false, stale: true };
         }
-        const snapshot = { ...options.snapshot, target: options.snapshot.target ?? options.fallbackTarget };
+        const snapshot = { ...options.snapshot, generation: options.snapshot.generation ?? this.nativeGenerations.get(options.sessionName), snapshotId: options.snapshot.snapshotId ?? randomUUID(), target: options.snapshot.target ?? options.fallbackTarget };
         this.refSnapshotInvalidations.delete(options.sessionName);
         this.refSnapshots.set(options.sessionName, { ...snapshot, order: options.update });
         return { ...this.get(options.sessionName), applied: true };
     }
+    bindSnapshotGeneration(sessionName, generation) {
+        if (generation)
+            this.nativeGenerations.set(sessionName, generation);
+        else
+            this.nativeGenerations.delete(sessionName);
+        const snapshot = this.refSnapshots.get(sessionName);
+        if (snapshot)
+            this.refSnapshots.set(sessionName, { ...snapshot, generation });
+    }
     applyRefSnapshotInvalidation(options) {
         if (!shouldApplyRefStateUpdate({
             currentInvalidation: this.refSnapshotInvalidations.get(options.sessionName),
@@ -519,6 +455,8 @@ export class SessionPageState {
         return { ...this.get(options.sessionName), applied: true };
     }
     clearSession(sessionName) {
+        this.pending.delete(sessionName);
+        this.nativeGenerations.delete(sessionName);
         this.readConfirmations.delete(sessionName);
         this.refSnapshotInvalidations.delete(sessionName);
         this.refSnapshots.delete(sessionName);

package/dist/extensions/agent-browser/lib/temp.js

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { randomBytes, randomInt } from "node:crypto";
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -10,6 +10,8 @@ const TEMP_ROOT_MARKER_FILE_NAME = ".pi-agent-browser-owner.json";
 const TEMP_ROOT_MARKER_KIND = "pi-agent-browser-temp-root";
 const TEMP_ROOT_MARKER_VERSION = 2;
 const STALE_TEMP_ROOT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+const STALE_TEMP_ROOT_BATCH_SIZE = 8;
+let lastTempGcName;
 const TEMP_ROOT_MAX_BYTES_ENV = "PI_AGENT_BROWSER_TEMP_ROOT_MAX_BYTES";
 const DEFAULT_TEMP_ROOT_MAX_BYTES = 32 * 1_024 * 1_024;
 const SESSION_ARTIFACT_MAX_BYTES_ENV = "PI_AGENT_BROWSER_SESSION_ARTIFACT_MAX_BYTES";
@@ -237,10 +239,17 @@ async function pruneStaleTempRoots(currentTempRoot) {
     const entries = await readdir(tmpdir(), { withFileTypes: true }).catch(() => []);
     const cutoffTime = Date.now() - STALE_TEMP_ROOT_MAX_AGE_MS;
     const currentUid = getCurrentProcessUid();
-    await Promise.all(entries
-        .filter((entry) => entry.isDirectory() && entry.name.startsWith(TEMP_ROOT_PREFIX))
-        .map(async (entry) => {
-        const path = join(tmpdir(), entry.name);
+    // ponytail: list/sort all names; stream directories if enumeration becomes the bottleneck.
+    const candidates = entries.filter((entry) => entry.isDirectory() && entry.name.startsWith(TEMP_ROOT_PREFIX))
+        .map((entry) => entry.name).sort();
+    if (candidates.length === 0)
+        return;
+    const start = lastTempGcName === undefined ? randomInt(candidates.length)
+        : Math.max(0, candidates.findIndex((name) => name > lastTempGcName));
+    const batch = Array.from({ length: Math.min(STALE_TEMP_ROOT_BATCH_SIZE, candidates.length) }, (_, offset) => candidates[(start + offset) % candidates.length]);
+    lastTempGcName = batch.at(-1);
+    await Promise.all(batch.map(async (name) => {
+        const path = join(tmpdir(), name);
         if (path === currentTempRoot)
             return;
         const ownershipMarker = await readTempRootOwnershipMarker(path);
@@ -400,7 +409,6 @@ async function prunePersistentSessionArtifactsToBudget(sessionArtifactDir, addit
 async function getSessionTempRoot() {
     if (!sessionTempRootPromise) {
         sessionTempRootPromise = (async () => {
-            await pruneStaleTempRoots(undefined);
             const tempRoot = await mkdtemp(join(tmpdir(), TEMP_ROOT_PREFIX));
             await chmod(tempRoot, 0o700).catch(() => undefined);
             await writeSecureTempRootOwnershipMarker(tempRoot);

package/dist/extensions/agent-browser/lib/tool-surface.js

@@ -1,7 +1,6 @@
 import { Text } from "@earendil-works/pi-tui";
 import { formatAgentBrowserRenderCall } from "./pi-tool-rendering.js";
 import { AGENT_BROWSER_PARAMS, AGENT_BROWSER_CODE_PARAMS, AGENT_BROWSER_ACTION_PARAMS, AGENT_BROWSER_QA_PARAMS, AGENT_BROWSER_ELECTRON_PARAMS, AGENT_BROWSER_SOURCE_PARAMS, AGENT_BROWSER_NETWORK_SOURCE_PARAMS, AGENT_BROWSER_TOOLS_PARAMS, } from "./input-modes/params.js";
-import { ADVANCED_TOOL_PROMPT_GUIDELINES, buildToolPromptGuidelines } from "./playbook.js";
 export const AGENT_BROWSER_TOOL_INVENTORY = {
     action: { name: "agent_browser_action", description: "Click, check, fill, or select a unique accessible target using stable locators or current refs." },
     qa: { name: "agent_browser_qa", description: "Check a URL or attached page with visible assertions and a diagnostic pass/fail verdict." },
@@ -9,23 +8,18 @@ export const AGENT_BROWSER_TOOL_INVENTORY = {
     source: { name: "agent_browser_source", description: "Find experimental DOM/React/local-source candidates with a bounded workspace scan." },
     network: { name: "agent_browser_network_source", description: "Correlate failed requests with initiator and local-source candidates." },
 };
-export const AGENT_BROWSER_DISCOVERY_GROUP = {
+export const AGENT_BROWSER_INSTRUCTION_GROUP = {
     name: "browser",
     description: "Search the web, browse and interact with pages, verify browser UI, and inspect Electron apps.",
-    sections: ["agent_browser"],
 };
-const entryDiscovery = { discovery: { group: AGENT_BROWSER_DISCOVERY_GROUP, role: "entry" } };
-const advancedDiscovery = { discovery: { group: AGENT_BROWSER_DISCOVERY_GROUP, role: "advanced" } };
 const advancedNames = new Set(Object.values(AGENT_BROWSER_TOOL_INVENTORY).map(({ name }) => name));
 /** Register once; advanced calls adapt only their input shape and reuse the ordinary executor. */
 export function registerAgentBrowserToolSurface(pi, options) {
     pi.registerTool({
-        ...entryDiscovery,
         name: "agent_browser",
         label: "Agent Browser",
         description: "Browse and interact through native agent-browser commands. One command in args; fixed sequences use batch --bail and JSON-array stdin. Use agent_browser_code for loops/branches and agent_browser_tools for advanced capabilities.",
         promptSnippet: "Browse pages, inspect current refs, interact, and run native command batches.",
-        promptGuidelines: options.promptGuidelines ?? buildToolPromptGuidelines({ includeWebSearch: false }),
         parameters: AGENT_BROWSER_PARAMS,
         renderCall: options.renderCall,
         renderResult: options.renderResult,
@@ -33,7 +27,6 @@ export function registerAgentBrowserToolSurface(pi, options) {
         executionMode: options.executionMode,
     });
     pi.registerTool({
-        ...entryDiscovery,
         name: "agent_browser_code",
         label: "Agent Browser Code",
         description: "Run fresh JavaScript against a persistent browser. await browser({args,stdin?,timeoutMs?}) returns success/data/error/nextActions and imageObservations; emit(selected JSON) and emitImage(image handle) explicitly choose output. No host APIs or imports. Use native batch for fixed sequences.",
@@ -49,10 +42,8 @@ export function registerAgentBrowserToolSurface(pi, options) {
         renderResult: options.renderResult,
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.action,
         label: "Browser Action",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.action],
         parameters: AGENT_BROWSER_ACTION_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
@@ -61,10 +52,8 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.qa,
         label: "Browser QA",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.qa],
         parameters: AGENT_BROWSER_QA_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
@@ -73,10 +62,8 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.electron,
         label: "Browser Electron",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.electron],
         parameters: AGENT_BROWSER_ELECTRON_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
@@ -85,10 +72,8 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.source,
         label: "Browser Source",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.source],
         parameters: AGENT_BROWSER_SOURCE_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
@@ -97,10 +82,8 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.network,
         label: "Browser Network Source",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.network],
         parameters: AGENT_BROWSER_NETWORK_SOURCE_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
@@ -109,7 +92,6 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
-        ...entryDiscovery,
         name: "agent_browser_tools",
         label: "Browser Tools",
         description: "List or enable advanced browser tools: action → agent_browser_action; qa → agent_browser_qa; electron → agent_browser_electron; source → agent_browser_source; network → agent_browser_network_source. Omit enable for inventory. Activation only adds tools; it preserves other active tools.",
@@ -142,10 +124,17 @@ export function registerAgentBrowserToolSurface(pi, options) {
         const available = new Set(pi.getAllTools().map(({ name }) => name));
         if (!["agent_browser", "agent_browser_code", "agent_browser_tools", ...advancedNames].every(name => available.has(name)))
             return;
-        // Keep Pi's replay helper behind the awaited restoration boundary, not factory registration.
-        const { getCurrentSystemMessage } = await import("@earendil-works/pi-ai");
-        const current = getCurrentSystemMessage(ctx.sessionManager.buildSessionProjection().messages);
-        const restored = new Set(current?.toolsAdded?.map(({ name }) => name));
+        // Native dynamic imports bypass Pi's host-package aliases in consumer installs.
+        // Only tool names are needed; replay their native deltas without a host import.
+        const restored = new Set();
+        for (const message of ctx.sessionManager.buildSessionProjection().messages) {
+            if (message.role !== "system")
+                continue;
+            for (const removed of message.toolsRemoved ?? [])
+                restored.delete(removed.name);
+            for (const added of message.toolsAdded ?? [])
+                restored.add(added.name);
+        }
         const active = pi.getActiveTools().filter((name) => !advancedNames.has(name) || restored.has(name));
         pi.setActiveTools([...new Set([...active, ...[...restored].filter((name) => advancedNames.has(name) && available.has(name))])]);
     });

package/dist/extensions/agent-browser/lib/web-search.js

@@ -1,5 +1,4 @@
 import { JsonSchema } from "./json-schema.js";
-import { WEB_SEARCH_PROMPT_GUIDELINE } from "./playbook.js";
 import { StringEnum as localStringEnum } from "./string-enum-schema.js";
 import { DEFAULT_WEB_SEARCH_PROVIDER, EXA_SEARCH_TYPES, WEB_SEARCH_PROVIDERS, resolvePreferredWebSearchCredential, } from "./config.js";
 export const AGENT_BROWSER_WEB_SEARCH_TOOL_NAME = "agent_browser_web_search";
@@ -566,13 +565,6 @@ export function createAgentBrowserWebSearchTool(configState, options = {}) {
         label: "Agent Browser Web Search",
         description: `Search the live web with Exa or Brave for current or external information. For Exa research tasks, use searchType deep-lite or deeper. Returns up to ${MAX_SEARCH_RESULT_COUNT} concise web results.`,
         promptSnippet: "Search the live web with Exa or Brave for current or external information.",
-        promptGuidelines: [
-            WEB_SEARCH_PROMPT_GUIDELINE,
-            "agent_browser_web_search chooses Exa or Brave from configured keys; when both are available, Exa is preferred by default unless webSearch.preferredProvider says otherwise. Use provider only when the user/config calls for a specific provider.",
-            "Use Exa deep only when deep-lite may miss angles, and deep-reasoning only for exhaustive or still-thin research. Do not run parallel agent_browser_web_search calls; make one high-signal query, inspect its results, then at most one follow-up.",
-            "If agent_browser_web_search returns HTTP 429, stop searching and tell the user the API plan/rate limit needs time or a plan change.",
-            "After using agent_browser_web_search, cite result URLs in the final answer when web evidence informed the answer.",
-        ],
         parameters: AgentBrowserWebSearchParams,
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             const runtimeConfigState = ctx ? options.loadConfigState?.(ctx) ?? configState : configState;