pi-agent-browser-native 0.8.3 → 0.9.0

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

@@ -241,14 +241,7 @@ export async function readBrowserEntries(manager, physical = false) {
         const header = metadata.find(entry => entry.value.type === "session");
         if (header?.value.id !== (manager.getHeader()?.id ?? manager.getSessionId()))
             throw new Error("Pi session journal identity does not match the active session.");
-        const publicManager = manager;
         const selected = physical ? metadata.filter(entry => entry.value.type !== "session") : branchEntries(metadata.filter(entry => entry.value.type !== "session"), leaf);
-        if (publicManager.iterateEntryMetadata) {
-            const native = new Map([...publicManager.iterateEntryMetadata(physical ? {} : { branchFrom: leaf })].map(entry => [entry.id, entry.parentId]));
-            for (const entry of selected)
-                if (typeof entry.value.id !== "string" || native.get(entry.value.id) !== entry.value.parentId)
-                    throw new Error("Published browser journal ancestry differs from the native selected boundary.");
-        }
         const projected = [];
         const definitions = new Map();
         for (const entry of selected) {
@@ -285,9 +278,7 @@ export async function readBrowserEntries(manager, physical = false) {
                 throw new Error(`Browser snapshot ${id} has no ancestral definition; inspect and take a fresh snapshot.`);
             // ponytail: a requested individual snapshot must fit its consumer's memory. Metadata
             // scans skip unlimited unrelated values; upgrade with native per-value paging if needed.
-            const native = publicManager.getEntryMetadata && typeof entry.value.id === "string" ? manager.getEntry(entry.value.id) : undefined;
-            const body = native && isRecord(native) && isRecord(native.data) ? { data: native.data }
-                : await projectJson(readRange(file, entry), [["data", "snapshot"]], Infinity);
+            const body = await projectJson(readRange(file, entry), [["data", "snapshot"]], Infinity);
             const destination = projected.find(candidate => isRecord(candidate) && candidate.id === entry.value.id);
             if (!isRecord(destination) || !isRecord(destination.data) || !isRecord(body?.data))
                 throw new Error("Winning browser snapshot could not be read.");
@@ -342,13 +333,22 @@ export function hasPublishedBrowserJournal(manager) {
 /** Capture before waiting: native selection precedes sequential session_tree handlers. */
 export function captureBrowserBranch(manager, isGenerationCurrent) {
     const sessionId = manager.getSessionId();
-    const branch = { sessionId, anchorId: manager.getLeafId(), isCurrent() {
+    let anchorId = manager.getLeafId();
+    let validatedAnchor;
+    let validatedLeaf;
+    const branch = { sessionId, anchorId, isCurrent() {
             if (!isGenerationCurrent() || manager.getSessionId() !== sessionId)
                 return false;
+            if (branch.anchorId !== anchorId) {
+                validatedAnchor = validatedLeaf = undefined;
+                anchorId = branch.anchorId;
+            }
             let leaf = manager.getLeafId();
             // Empty selection is not a universal ancestor of other independent roots.
             let current = branch.anchorId === null && leaf === null;
             const seen = new Set();
+            let selected;
+            let anchor;
             while (leaf !== null) {
                 if (typeof leaf !== "string" || seen.has(leaf))
                     throw new Error("Selected Pi journal ancestry is invalid or cyclic.");
@@ -356,10 +356,31 @@ export function captureBrowserBranch(manager, isGenerationCurrent) {
                 const entry = manager.getEntry(leaf);
                 if (!entry || entry.id !== leaf || entry.parentId !== null && typeof entry.parentId !== "string")
                     throw new Error("Selected Pi journal ancestry is incomplete.");
-                if (leaf === branch.anchorId)
+                selected ??= { entry, parentId: entry.parentId };
+                const cached = leaf === branch.anchorId ? validatedAnchor : leaf === validatedLeaf?.entry.id ? validatedLeaf : undefined;
+                if (cached) {
+                    // Keep the native indexed lookup: it also refreshes fork journal identity.
+                    if (cached.entry === entry && cached.parentId === entry.parentId) {
+                        current = true;
+                        break;
+                    }
+                    validatedAnchor = validatedLeaf = undefined;
+                }
+                if (leaf === branch.anchorId) {
                     current = true;
+                    anchor = { entry, parentId: entry.parentId };
+                }
                 leaf = entry.parentId;
             }
+            // Native entries/parents are append-only. Cache only after validating through
+            // the root (or an already validated endpoint), never merely on leaf === anchor.
+            // ponytail: behind-host mutation of an old ancestor without native reseed or
+            // generation change is outside this contract; durable file proofs
+            // remain in replay/append. Upgrade if Pi exposes a separate ancestry revision.
+            if (current && selected) {
+                validatedAnchor = anchor ?? validatedAnchor;
+                validatedLeaf = selected;
+            }
             return current;
         } };
     return branch;

package/dist/extensions/agent-browser/lib/execution-cwd.js

@@ -1,8 +1,6 @@
 import { readFileSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { isRecord } from "./parsing.js";
-import { getBrowserResultMessage } from "./browser-transcript.js";
-import { getAgentBrowserSessionIdentityKey } from "./argv-grammar.js";
 function isDirectoryOwner(source) {
     if (/^(?:npm:pi-change-working-dir|git:github\.com\/fitchmultz\/pi-change-working-dir(?:\.git)?)(?:@.+)?$/.test(source.source))
         return true;
@@ -50,17 +48,3 @@ export function getBrowserCwdError(cwd) {
     }
     return `Browser launch directory is unavailable: ${cwd}. Restore that directory, or explicitly use sessionMode: "fresh" without --session, or --config from the selected execution directory. The existing browser was left untouched.`;
 }
-export function restoreManagedSessionCwd(branch, sessionName, namespace, fallback) {
-    const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
-    for (const entry of [...branch].reverse()) {
-        const message = getBrowserResultMessage(entry);
-        if (!message)
-            continue;
-        const details = message.details;
-        if (!isRecord(details) || typeof details.sessionName !== "string" || typeof details.managedSessionCwd !== "string" || !isAbsolute(details.managedSessionCwd))
-            continue;
-        if (getAgentBrowserSessionIdentityKey(details.sessionName, typeof details.namespace === "string" ? details.namespace : undefined) === key)
-            return details.managedSessionCwd;
-    }
-    return fallback;
-}

package/dist/extensions/agent-browser/lib/native-output.js

@@ -0,0 +1,46 @@
+import { JsonSchema } from "./json-schema.js";
+import { isRecord } from "./parsing.js";
+import { finalizeAgentBrowserFailure } from "./pi-tool-rendering.js";
+import { isPlainTextInspectionArgs } from "./runtime.js";
+import { projectAgentBrowserObservation, OBSERVATION_INLINE_MAX_CHARS } from "./results/presentation/content.js";
+export const AGENT_BROWSER_NAMESPACE = {
+    name: "browser",
+    description: "Browser commands, bounded browser code, advanced UI checks, Electron, and optional web search.",
+    instructions: "Use agent_browser for native commands and batch --bail for fixed sequences. Use agent_browser_code for a fresh bounded JS cell with a persistent browser. Enable advanced direct tools with agent_browser_tools before calling them. Check success and nextActions; structured imageObservations are capture metadata, not inline images. Optional web search is available only when configured. Full browser instructions remain in the agent_browser prompt section.",
+};
+export const AGENT_BROWSER_OUTPUT_SCHEMA = JsonSchema.Object({
+    success: JsonSchema.Boolean(),
+    resultCategory: JsonSchema.Union([JsonSchema.Literal("success"), JsonSchema.Literal("failure")]),
+    data: JsonSchema.Optional(JsonSchema.Unsafe({})),
+    error: JsonSchema.Optional(JsonSchema.Unsafe({})),
+    summary: JsonSchema.Optional(JsonSchema.String()),
+    nextActions: JsonSchema.Optional(JsonSchema.Array(JsonSchema.Object({}))),
+}, { additionalProperties: true });
+/** Final public boundary, after execution, persistence, and any requested output export. */
+export async function finalizeAgentBrowserNativeResult(result, input) {
+    const finalized = finalizeAgentBrowserFailure(result, input);
+    // Native help/version stays plain text; the entrypoint intentionally skips observation rendering for it.
+    if (isRecord(input) && Array.isArray(input.args) && isPlainTextInspectionArgs(input.args))
+        return finalized;
+    const succeeded = finalized.isError !== true;
+    // The normal entrypoint supplies the exact bounded projection, including its complete spill.
+    if (isRecord(result.structuredContent) && result.structuredContent.success === succeeded)
+        return finalized;
+    const details = isRecord(result.details) ? result.details : {};
+    const observation = projectAgentBrowserObservation(details, succeeded);
+    if (JSON.stringify(observation).length > OBSERVATION_INLINE_MAX_CHARS) {
+        const { renderAgentBrowserObservation } = await import("./results/presentation/large-output.js");
+        const rendered = await renderAgentBrowserObservation({
+            content: finalized.content, details, succeeded,
+            json: isRecord(input) && ("code" in input || Array.isArray(input.args) && input.args.includes("--json")),
+            // The caller's exact visible output stays inline (for example formatted search results); only the structured field is bounded.
+            preserveContent: true,
+        });
+        const { artifactManifest, ...renderedResult } = rendered;
+        return finalizeAgentBrowserFailure({
+            ...finalized, ...renderedResult,
+            details: artifactManifest ? { ...details, artifactManifest } : details,
+        }, input);
+    }
+    return { ...finalized, structuredContent: JSON.parse(JSON.stringify(observation)) };
+}

package/dist/extensions/agent-browser/lib/pi-tool-rendering.js

@@ -1,5 +1,4 @@
 import { getKeybindings, Text, truncateToWidth } from "@earendil-works/pi-tui";
-import { BROWSER_RESULT_TOOLS } from "./browser-transcript.js";
 import { compileAgentBrowserElectron } from "./input-modes/electron.js";
 import { compileAgentBrowserQaPreset } from "./input-modes/job.js";
 import { compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup } from "./input-modes/lookups.js";
@@ -185,10 +184,10 @@ function formatModelVisibleFailureCategoryNotice(details) {
         : undefined;
     return `Result category: failure${failureCategory ? `; failureCategory: ${failureCategory}` : ""}; Pi tool isError: true.`;
 }
-function agentBrowserToolResultRequestedJson(event) {
-    const details = isRecord(event.details) ? event.details : undefined;
+function agentBrowserToolResultRequestedJson(result, input) {
+    const details = isRecord(result.details) ? result.details : undefined;
     const detailArgs = Array.isArray(details?.args) ? details.args : undefined;
-    const inputArgs = isRecord(event.input) && Array.isArray(event.input.args) ? event.input.args : undefined;
+    const inputArgs = isRecord(input) && Array.isArray(input.args) ? input.args : undefined;
     return detailArgs?.includes("--json") === true || inputArgs?.includes("--json") === true;
 }
 function agentBrowserToolResultHasParseableJsonContent(content) {
@@ -219,26 +218,41 @@ function appendModelVisibleFailureCategoryNotice(content, notice) {
         ? { ...item, text: `${textItem.text}\n\n${notice}` }
         : item);
 }
-export function buildAgentBrowserToolResultPatch(event) {
-    if (!BROWSER_RESULT_TOOLS.has(event.toolName))
-        return undefined;
-    const preservesParseableJson = (event.toolName === "agent_browser_code" || agentBrowserToolResultRequestedJson(event)) && agentBrowserToolResultHasParseableJsonContent(event.content);
-    const notice = preservesParseableJson ? undefined : formatModelVisibleFailureCategoryNotice(event.details);
-    const content = notice ? appendModelVisibleFailureCategoryNotice(event.content, notice) : undefined;
-    const shouldMarkError = isRecord(event.details) && event.details.resultCategory === "failure" && event.isError !== true;
-    if (!shouldMarkError && !content)
-        return undefined;
+export function finalizeAgentBrowserFailure(result, input) {
+    const failed = result.isError === true || (isRecord(result.details) && result.details.resultCategory === "failure");
+    const preservesParseableJson = (isRecord(input) && "code" in input || agentBrowserToolResultRequestedJson(result, input)) && agentBrowserToolResultHasParseableJsonContent(result.content);
+    const notice = preservesParseableJson ? undefined : formatModelVisibleFailureCategoryNotice(result.details);
+    const content = notice ? appendModelVisibleFailureCategoryNotice(result.content, notice) : undefined;
     return {
-        ...(content ? { content } : {}),
-        ...(shouldMarkError ? { isError: true } : {}),
+        ...result,
+        content: content ?? result.content,
+        isError: failed,
     };
 }
 export class AgentBrowserResultComponent {
     expanded = false;
     theme;
     text = new Text("", 0, 0);
+    value;
+    formatKey;
+    setResult(result, options, theme, isError) {
+        const details = isRecord(result.details) ? result.details : undefined;
+        // Theme is a stable proxy in Pi; its resolved colors identify theme/terminal-color changes.
+        const key = [getPrimaryTextContent(result), details?.summary, details?.resultCategory, details?.failureCategory, options.isPartial, isError, theme, theme.colors, theme.fg];
+        if (!this.formatKey || key.some((value, index) => value !== this.formatKey[index])) {
+            this.formatKey = key;
+            this.setState(formatAgentBrowserRenderResult(result, options, theme, isError), options.expanded, theme);
+        }
+        else {
+            this.expanded = options.expanded;
+            this.theme = theme;
+        }
+    }
     setState(value, expanded, theme) {
-        this.text.setText(value);
+        if (value !== this.value) {
+            this.text.setText(value);
+            this.value = value;
+        }
         this.expanded = expanded;
         this.theme = theme;
     }

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

@@ -199,7 +199,7 @@ export function buildPromptPolicy(prompt) {
         requestedArtifacts: extractPromptRequestedArtifacts(prompt),
     };
 }
-function getMessageText(content) {
+export function getMessageText(content) {
     if (typeof content === "string")
         return content;
     if (!Array.isArray(content))
@@ -213,17 +213,21 @@ function getMessageText(content) {
         .filter((text) => text.length > 0)
         .join("\n");
 }
-export function getLatestUserPrompt(branch) {
-    for (let index = branch.length - 1; index >= 0; index -= 1) {
-        const entry = branch[index];
-        if (typeof entry !== "object" || entry === null || !("type" in entry) || entry.type !== "message") {
-            continue;
-        }
-        const message = "message" in entry ? entry.message : undefined;
-        if (typeof message !== "object" || message === null || !("role" in message) || message.role !== "user") {
-            continue;
+/** Raw prompt intent survives compaction/context edits; only restoration walks ancestry. */
+export function getLatestUserMessage(manager) {
+    let id = manager.getLeafId();
+    const seen = new Set();
+    while (id !== null) {
+        if (typeof id !== "string" || seen.has(id))
+            throw new Error("Latest user prompt ancestry is invalid or cyclic.");
+        seen.add(id);
+        const entry = manager.getEntry(id);
+        if (!entry || entry.id !== id || entry.parentId !== null && typeof entry.parentId !== "string") {
+            throw new Error("Latest user prompt ancestry is incomplete.");
         }
-        return getMessageText("content" in message ? message.content : undefined);
+        if (entry.type === "message" && entry.message.role === "user")
+            return entry.message;
+        id = entry.parentId;
     }
-    return "";
+    return undefined;
 }

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

@@ -2,6 +2,7 @@ import { isRecord } from "../../parsing.js";
 import { redactSensitiveValue } from "../../runtime.js";
 import { omitUpstreamLifecycle } from "./common.js";
 import { redactTimeoutPartialProgress } from "../../orchestration/browser-run/diagnostics.js";
+export const OBSERVATION_INLINE_MAX_CHARS = 16_000;
 export function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
@@ -40,6 +41,9 @@ export function projectAgentBrowserObservation(details, succeeded) {
     }
     if (details.inspection === true && details.data === undefined && typeof details.stdout === "string")
         observation.data = details.stdout;
+    // Identical error/summary strings double-count large failure text against the observation bound; keep error.
+    if (typeof observation.error === "string" && observation.error === observation.summary)
+        observation.summary = undefined;
     if (isRecord(observation.data))
         observation.data = omitUpstreamLifecycle(observation.data);
     if (Array.isArray(details.batchSteps)) {

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

@@ -2,7 +2,7 @@ import { writePersistentSessionArtifactFile, writeSecureTempFile, } from "../../
 import { buildEvictedSessionArtifactEntries } from "../artifact-manifest.js";
 import { countLines, truncateText } from "../text.js";
 import { applyArtifactManifest } from "./artifacts.js";
-import { getPresentationText, projectAgentBrowserObservation } from "./content.js";
+import { getPresentationText, projectAgentBrowserObservation, OBSERVATION_INLINE_MAX_CHARS } from "./content.js";
 import { redactModelFacingText, stringifyModelFacing } from "./common.js";
 const LARGE_OUTPUT_INLINE_MAX_CHARS = 8_000;
 const LARGE_OUTPUT_INLINE_MAX_LINES = 120;
@@ -88,16 +88,17 @@ function buildSpillArtifactEntries(options) {
         ...buildEvictedSessionArtifactEntries(options.evictedArtifacts, nowMs),
     ];
 }
-export const OBSERVATION_INLINE_MAX_CHARS = 16_000;
+export { OBSERVATION_INLINE_MAX_CHARS } from "./content.js";
 /** Bound the final model-visible result, after recovery/diagnostic assembly. Never truncate executable actions. */
 export async function renderAgentBrowserObservation(options) {
     const observation = projectAgentBrowserObservation(options.details, options.succeeded);
+    let structuredContent = observation;
     const images = options.content.filter(part => part.type === "image");
     const prose = options.content.filter(part => part.type === "text").map(part => part.text).join("\n\n");
     const { data: _data, error: _error, summary: _summary, ...metadata } = observation;
     let text = options.json ? JSON.stringify(observation, null, 2) : `${prose}\n\nObservation: ${JSON.stringify(metadata)}`;
     let artifactManifest = options.details.artifactManifest;
-    if (text.length > OBSERVATION_INLINE_MAX_CHARS) {
+    if (text.length > OBSERVATION_INLINE_MAX_CHARS || JSON.stringify(observation).length > OBSERVATION_INLINE_MAX_CHARS) {
         let spill;
         let spillError;
         try {
@@ -114,7 +115,8 @@ export async function renderAgentBrowserObservation(options) {
         const compact = {
             success: options.succeeded, resultCategory: observation.resultCategory,
             failureCategory: observation.failureCategory, successCategory: observation.successCategory,
-            summary: typeof observation.summary === "string" ? truncateText(observation.summary, 700) : undefined,
+            summary: typeof observation.summary === "string" ? truncateText(observation.summary, 700)
+                : typeof observation.error === "string" ? truncateText(observation.error, 700) : undefined,
             compacted: true,
             ...(spill ? { observationPath: spill.path, retrieve: "Read observationPath for the complete redacted observation, including exact recovery actions and requested data." }
                 : { observationUnavailable: truncateText(redactModelFacingText(spillError ?? "Spill could not be written; request a smaller result."), 1_000) }),
@@ -123,11 +125,16 @@ export async function renderAgentBrowserObservation(options) {
             if (observation[key] !== undefined && JSON.stringify({ ...compact, [key]: observation[key] }, null, 2).length <= OBSERVATION_INLINE_MAX_CHARS - 500)
                 compact[key] = observation[key];
         }
-        text = JSON.stringify(compact, null, 2);
-        if (!options.json)
-            text = `Browser observation compacted.\n${text}`;
+        structuredContent = compact;
+        if (options.preserveContent)
+            text = prose;
+        else {
+            text = JSON.stringify(compact, null, 2);
+            if (!options.json)
+                text = `Browser observation compacted.\n${text}`;
+        }
     }
-    return { content: [{ type: "text", text }, ...images], artifactManifest };
+    return { content: [{ type: "text", text }, ...images], artifactManifest, structuredContent: JSON.parse(JSON.stringify(structuredContent)) };
 }
 export async function compactLargePresentationOutput(options) {
     const text = getPresentationText(options.presentation);

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

@@ -1,5 +1,7 @@
 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";
 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." },
@@ -15,24 +17,28 @@ export const AGENT_BROWSER_INSTRUCTION_GROUP = {
 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({
         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.",
         parameters: AGENT_BROWSER_PARAMS,
         renderCall: options.renderCall,
         renderResult: options.renderResult,
-        execute: options.execute,
+        execute,
         executionMode: options.executionMode,
     });
     pi.registerTool({
         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);
@@ -43,56 +49,74 @@ export function registerAgentBrowserToolSurface(pi, options) {
     });
     pi.registerTool({
         ...AGENT_BROWSER_TOOL_INVENTORY.action,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser 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({
         ...AGENT_BROWSER_TOOL_INVENTORY.qa,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser 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({
         ...AGENT_BROWSER_TOOL_INVENTORY.electron,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser 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({
         ...AGENT_BROWSER_TOOL_INVENTORY.source,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser 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({
         ...AGENT_BROWSER_TOOL_INVENTORY.network,
+        ...nativeOutput,
+        defaultActive: false,
         label: "Browser Network Source",
         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({
         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.",
@@ -111,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"))
@@ -125,7 +151,7 @@ export function registerAgentBrowserToolSurface(pi, options) {
         if (!["agent_browser", "agent_browser_code", "agent_browser_tools", ...advancedNames].every(name => available.has(name)))
             return;
         // 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.
+        // 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")
@@ -135,7 +161,9 @@ export function registerAgentBrowserToolSurface(pi, options) {
             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))])]);
+        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]);
     });
 }