pi-agent-browser-native 0.8.2 → 0.9.0

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,8 @@
 import { Text } from "@earendil-works/pi-tui";
 import { formatAgentBrowserRenderCall } from "./pi-tool-rendering.js";
+import { JsonSchema } from "./json-schema.js";
+import { AGENT_BROWSER_NAMESPACE, AGENT_BROWSER_OUTPUT_SCHEMA, finalizeAgentBrowserNativeResult } from "./native-output.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,37 +10,35 @@ 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) {
+    const execute = async (id, params, signal, onUpdate, ctx) => finalizeAgentBrowserNativeResult(await options.execute(id, params, signal, onUpdate, ctx), params);
+    const nativeOutput = { namespace: AGENT_BROWSER_NAMESPACE, outputSchema: AGENT_BROWSER_OUTPUT_SCHEMA };
     pi.registerTool({
-        ...entryDiscovery,
         name: "agent_browser",
+        ...nativeOutput,
         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,
-        execute: options.execute,
+        execute,
         executionMode: options.executionMode,
     });
     pi.registerTool({
-        ...entryDiscovery,
         name: "agent_browser_code",
+        ...nativeOutput,
         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.",
         promptSnippet: "Branch, loop, and aggregate browser observations with explicit JSON/image output.",
         parameters: AGENT_BROWSER_CODE_PARAMS,
-        execute: options.executeCode,
+        execute: async (id, params, signal, onUpdate, ctx) => finalizeAgentBrowserNativeResult(await options.executeCode(id, params, signal, onUpdate, ctx), params),
         executionMode: options.executionMode,
         renderCall(args, theme, context) {
             const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -49,68 +48,75 @@ export function registerAgentBrowserToolSurface(pi, options) {
         renderResult: options.renderResult,
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.action,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser Action",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.action],
         parameters: AGENT_BROWSER_ACTION_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
         execute(id, { outputPath, timeoutMs, ...semanticAction }, signal, onUpdate, ctx) {
-            return options.execute(id, { semanticAction, outputPath, timeoutMs }, signal, onUpdate, ctx);
+            return execute(id, { semanticAction, outputPath, timeoutMs }, signal, onUpdate, ctx);
         },
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.qa,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser QA",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.qa],
         parameters: AGENT_BROWSER_QA_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
         execute(id, { outputPath, timeoutMs, sessionMode, ...qa }, signal, onUpdate, ctx) {
-            return options.execute(id, { qa, outputPath, timeoutMs, sessionMode }, signal, onUpdate, ctx);
+            return execute(id, { qa, outputPath, timeoutMs, sessionMode }, signal, onUpdate, ctx);
         },
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.electron,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser Electron",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.electron],
         parameters: AGENT_BROWSER_ELECTRON_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
         execute(id, { outputPath, ...electron }, signal, onUpdate, ctx) {
-            return options.execute(id, { electron, outputPath }, signal, onUpdate, ctx);
+            return execute(id, { electron, outputPath }, signal, onUpdate, ctx);
         },
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.source,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser Source",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.source],
         parameters: AGENT_BROWSER_SOURCE_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
         execute(id, { outputPath, timeoutMs, sessionMode, ...sourceLookup }, signal, onUpdate, ctx) {
-            return options.execute(id, { sourceLookup, outputPath, timeoutMs, sessionMode }, signal, onUpdate, ctx);
+            return execute(id, { sourceLookup, outputPath, timeoutMs, sessionMode }, signal, onUpdate, ctx);
         },
     });
     pi.registerTool({
-        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.network,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser Network Source",
-        promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.network],
         parameters: AGENT_BROWSER_NETWORK_SOURCE_PARAMS,
         renderResult: options.renderResult,
         executionMode: options.executionMode,
         execute(id, { outputPath, timeoutMs, sessionMode, ...networkSourceLookup }, signal, onUpdate, ctx) {
-            return options.execute(id, { networkSourceLookup, outputPath, timeoutMs, sessionMode }, signal, onUpdate, ctx);
+            return execute(id, { networkSourceLookup, outputPath, timeoutMs, sessionMode }, signal, onUpdate, ctx);
         },
     });
     pi.registerTool({
-        ...entryDiscovery,
         name: "agent_browser_tools",
+        namespace: AGENT_BROWSER_NAMESPACE,
+        outputSchema: JsonSchema.Object({
+            inventory: JsonSchema.Array(JsonSchema.Object({
+                key: JsonSchema.String(), name: JsonSchema.String(), description: JsonSchema.String(),
+                available: JsonSchema.Boolean(), active: JsonSchema.Boolean(),
+            })),
+            added: JsonSchema.Array(JsonSchema.String()),
+        }),
         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.",
         promptSnippet: "Discover and enable specialized browser actions, QA, Electron, and source tools.",
@@ -129,11 +135,13 @@ export function registerAgentBrowserToolSurface(pi, options) {
             return {
                 content: [{ type: "text", text: inventory.map((tool) => `${tool.key}: ${tool.name} (${!tool.available ? "unavailable in this Pi tool selection" : tool.active ? "active" : "inactive"}) — ${tool.description}`).join("\n") }],
                 details: { inventory, added: [...new Set(added)] },
+                structuredContent: { inventory, added: [...new Set(added)] },
             };
         },
     });
     pi.on("session_start", async (_event, ctx) => {
-        // Pi owns selected tools and their durable system-message history; keep no parallel registry.
+        // ponytail: official 1.0 SDK supplies initialActiveToolNames on resume, bypassing
+        // native transcript restoration. Remove this additive fallback once the supported SDK restores it.
         const argv = process.argv.slice(2);
         const delimiter = argv.indexOf("--");
         if ((delimiter < 0 ? argv : argv.slice(0, delimiter)).some((arg) => arg === "--tools" || arg === "-t"))
@@ -142,11 +150,20 @@ 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));
-        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))])]);
+        // Native dynamic imports bypass Pi's host-package aliases in consumer installs.
+        // Only tool names are needed; replay native deltas without requiring the optional pi-ai peer.
+        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 = new Set(pi.getActiveTools());
+        const added = [...restored].filter((name) => advancedNames.has(name) && available.has(name) && !active.has(name));
+        if (added.length > 0)
+            pi.setActiveTools([...active, ...added]);
     });
 }