pi-agent-browser-native 0.2.15 → 0.2.17

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.2.17 - 2026-05-03
+
+### Fixed
+- close the active extension-managed `piab-*` browser session when the originating `pi` process quits, while preserving managed browser continuity across `/reload` and resumable session transitions
+- added lifecycle regression coverage for quit-time managed-session cleanup and reload-time preservation
+
+### Changed
+- clarified that the managed-session idle timeout is now an abnormal-exit backstop, not the primary cleanup path for normal `pi` exits
+
+## 0.2.16 - 2026-05-02
+
+### Fixed
+- made screenshot artifact paths reliable for agent workflows by normalizing explicit screenshot output paths, including dot-directory paths such as `.dogfood/...`, to absolute paths before invoking upstream `agent-browser`
+- repaired screenshot outputs from upstream temp files when needed and made the requested path the primary visible artifact path
+- extended the screenshot path contract to annotated batch screenshots, so top-level `--annotate` batch calls preserve and verify per-step requested output paths
+- blocked per-step batch `--annotate` screenshot forms that upstream parses unsafely and now point agents to the safe top-level `--annotate batch` form
+- added wrapper-observed trace/profiler owner guards to prevent known conflicting start/stop sequences from corrupting upstream tracing state
+
+### Changed
+- artifact-producing commands now render direct visible artifact metadata, including artifact type, requested path, absolute path, existence, size, status, cwd, session, and temp path when repaired
+- explicit `--json` calls now render valid JSON in visible tool content; `stream status` JSON is enriched with `wsUrl` and frame format metadata
+- documented the artifact contract, batch annotation guidance, trace/profiler caveat, and package-development bash bypass for upstream debugging
+
 ## 0.2.15 - 2026-05-01
 
 ### Changed

package/README.md

@@ -242,9 +242,10 @@ Validated workflow examples:
 - in configured-source lifecycle mode, verify `/reload` and full restart + `/resume` keep following the same implicit managed browser session
 - run `batch` with JSON via `stdin`
 - run `eval --stdin`
-- take a screenshot with inline attachment support
+- take a screenshot with inline attachment support and visible artifact metadata: artifact type, requested path, absolute path, existence, size, cwd, session, and repair/copy status when applicable
 - inspect upstream help/version through native tool calls like `{ "args": ["--help"] }` and `{ "args": ["--version"] }` via the tool's stateless plain-text inspection fallback
 - use `download <selector> <path>` for direct attachment/file-save workflows instead of trying to infer downloads from generic clicks or large eval dumps
+- for `.dogfood/...` or other dot-directory screenshot paths, rely on the wrapper's path normalization/repair contract; the visible result reports the requested path and absolute path rather than only an upstream temp path
 - use `click` plus `wait --download <path>` for asynchronous export flows, confirm `details.savedFilePath`/`details.savedFile` are present on the wait result or batch wait step, and check `details.artifacts[].exists` before relying on requested-path persistence
 - confirm oversized outputs show the actual spill file path directly in tool content, not just a details key name
 - inspect `details.artifactManifest` / `details.artifactRetentionSummary` during artifact-heavy flows to recover recent saved files, spill files, and visible eviction state after reload/resume
@@ -262,7 +263,7 @@ These calls return plain text and stay stateless: the extension does not inject
 Current cautions:
 - passing `--profile` is an explicit upstream choice; this extension does not add its own profile-cloning or isolation layer
 - launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, and `--auto-connect` are for the first command that launches a session; if the implicit session is already active, retry that call with `sessionMode: "fresh"` or provide an explicit `--session ...` for the new launch
-- implicit `piab-*` sessions are extension-managed convenience sessions; they stay alive across `pi` shutdown/reload so later default calls can keep following the active managed browser on `/reload` or `/resume`, rely on the configured idle timeout to reduce stale background daemons, store persisted-session large snapshot spill files under a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` and metadata-only `details.artifactManifest` survive reload/resume without unbounded growth, and still clean up process-private temp spill artifacts on shutdown
+- implicit `piab-*` sessions are extension-managed convenience sessions; they stay alive across `/reload` and resumable session transitions so later default calls can keep following the active managed browser on `/reload` or `/resume`, close when the originating `pi` process quits, rely on the configured idle timeout only as an abnormal-exit backstop, store persisted-session large snapshot spill files under a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` and metadata-only `details.artifactManifest` survive reload/resume without unbounded growth, and still clean up process-private temp spill artifacts on shutdown
 - `sessionMode: "fresh"` without an explicit `--session` rotates that extension-managed session to the new browser so later auto calls keep using it
 - for local Unix launches, the wrapper uses a short private socket directory under `/tmp` so extension-generated session names do not trip upstream Unix socket-path limits in longer cwd/session-name combinations
 - for direct headless local Chrome launches to `chat.com`, `chatgpt.com`, and `chat.openai.com`, the extension injects a normal Chrome user agent when the caller did not explicitly provide `--user-agent`; this keeps the default headless workflow usable without forcing `--headed` or `--auto-connect`
@@ -274,6 +275,9 @@ Current cautions:
 - If a known session target unexpectedly reports about:blank, agent_browser preserves the prior intended target, best-effort re-selects it when it still exists, and reports exact recovery guidance when it cannot be re-selected.
 <!-- agent-browser-playbook:end wrapper-tab-recovery -->
 - oversized snapshots and oversized generic outputs compact inline content and print the actual spill file path directly in the tool result when a spill file exists; recent spills and explicit saved artifacts are also summarized in `details.artifactManifest`, including `evicted` entries when retention budgets remove older persisted files
+- artifact-producing commands render direct readable artifact metadata in visible content and `details.artifacts`: `kind`/`artifactType`, `path`, `requestedPath`, `absolutePath`, `exists`, `sizeBytes`, `status`, `cwd`, `session`, and `tempPath` when the wrapper repaired an upstream temp fallback
+- if the caller explicitly passes `--json`, the visible text content is valid JSON; for `stream status`, the wrapper enriches data with `wsUrl` and `frameFormat`
+- `trace` and `profiler` share upstream tracing machinery; the wrapper blocks starts/stops that conflict with owner state it observed in the current Pi session, but the message says "wrapper believes" because upstream or external CLI calls can desynchronize that local state
 - explicit caller-provided `--session` values are treated as user-managed and are not auto-closed by the extension
 - explicit caller-provided `--user-agent` values win over the ChatGPT/OpenAI compatibility workaround
 - tool progress/details redact sensitive invocation values such as `--headers`, proxy credentials, and auth-bearing URL parameters before echoing them back into Pi

package/docs/ARCHITECTURE.md

@@ -87,8 +87,9 @@ V1 ownership rule:
 - extension-managed sessions should be reusable during an active `pi` session and across `/reload` / `/resume`, while still being cleaned up predictably
 
 Practical policy:
-- preserve the current extension-managed session across normal `pi` shutdown/reload so persisted sessions can keep following the live browser after `/reload` or `/resume`
-- set an idle timeout on extension-managed sessions so abandoned daemons self-clean after inactivity
+- preserve the current extension-managed session across `/reload` and resumable session transitions so persisted sessions can keep following the live browser after `/reload` or `/resume`
+- close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone
+- set an idle timeout on extension-managed sessions as a backstop for abnormal exits or cleanup failures
 - clean up process-private temp spill artifacts on shutdown, but keep persisted-session snapshot spill files in a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` stays usable after reload/resume without unbounded growth
 - reconstruct the current extension-managed session from persisted tool details on resume/reload so later default calls keep following the active managed browser
 - if an unnamed fresh launch replaces an active extension-managed session, best-effort close the old managed session after the switch succeeds

package/docs/COMMAND_REFERENCE.md

@@ -128,11 +128,19 @@ A successful wait-based download renders a readable summary such as `Download co
 Prefer `download <selector> <path>` when the target element itself is the downloadable link/control. Use `click` plus `wait --download [path]` when a previous action starts the download indirectly.
 
 Wrapper result rendering is metadata-first for saved files:
-- screenshots return a saved-path summary, structured `details.artifacts` metadata, and an inline image attachment when safe
+- screenshots return a saved-path summary, visible artifact metadata, structured `details.artifacts` metadata, and an inline image attachment when safe; the visible block includes artifact type, requested path, absolute path, existence, size, cwd, session, and repair/copy status when applicable
 - downloads, PDFs, `wait --download` files, traces, CPU profiles, completed WebM recordings from `record stop`, and path-bearing HAR captures return concise saved-path summaries plus structured `details.artifacts` metadata without inlining large files
 - `record start <path>` reports that recording started and that output will be written on `record stop`; the target file may not exist until recording stops
 - `batch` keeps each step's artifacts in `details.batchSteps[].artifacts` and aggregates them in top-level `details.artifacts` in step order
 
+For screenshot paths under dot-directories such as `.dogfood/run/foo.png`, the wrapper normalizes the requested path to an absolute path before invoking upstream `agent-browser`, verifies the requested file exists, and repairs from an upstream temp screenshot when possible. The requested path remains visible as `Requested path`, while `Absolute path` shows the actual on-disk location.
+
+For annotated screenshots in `batch`, put `--annotate` in top-level args instead of inside the screenshot step:
+
+```json
+{ "args": ["--annotate", "batch"], "stdin": "[[\"screenshot\",\"/tmp/page.png\"]]" }
+```
+
 #### Artifact retention and dogfood-heavy QA runs
 
 The wrapper keeps a bounded, metadata-only `details.artifactManifest` of recent artifacts so long sessions do not grow unbounded. The default recent window is 100 entries and can be raised for screenshot/video-heavy QA sessions with `PI_AGENT_BROWSER_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES=<count>`.
@@ -325,6 +333,8 @@ Stable tab ids look like `t1`, `t2`, and `t3`. Optional user labels such as `doc
 
 When these diagnostic commands are invoked through the native `agent_browser` tool, structured console and page-error outputs render as compact summaries with counts and key fields. Large outputs are previewed with a `Full output path:` spill file instead of dumping the entire payload into context.
 
+`trace` and `profiler` share upstream Chrome tracing machinery. Do not run them at the same time. The wrapper tracks owner state it observes in the current Pi session and blocks conflicting starts/stops with "wrapper believes ..." wording because direct upstream CLI use or browser restarts can desynchronize wrapper-local state.
+
 ### Batch, auth, confirmations, sessions, chat, dashboard, and setup
 
 | Command | Purpose |

package/docs/TOOL_CONTRACT.md

@@ -171,7 +171,7 @@ Additional structured fields can appear when relevant:
 - `batchFailure` and `batchSteps` for `batch` rendering, including mixed-success runs
 - `navigationSummary` for navigation-style commands like `click`, `back`, `forward`, and `reload`
 - `imagePath` / `imagePaths` for screenshots and batched image outputs
-- `artifacts` for upstream saved files such as screenshots, PDFs, downloads, `wait --download` files, traces, CPU profiles, completed WebM recordings, path-bearing HAR captures, and future recording output paths reported by `record start`. Each artifact includes the original saved or requested `path`, resolved `absolutePath`, `kind`, optional `mediaType`, optional `extension`, and best-effort disk metadata such as `exists` and `sizeBytes`.
+- `artifacts` for upstream saved files such as screenshots, PDFs, downloads, `wait --download` files, traces, CPU profiles, completed WebM recordings, path-bearing HAR captures, and future recording output paths reported by `record start`. Each artifact includes the original saved or requested `path`, resolved `absolutePath`, `kind`/`artifactType`, optional `mediaType`, optional `extension`, best-effort disk metadata such as `exists` and `sizeBytes`, plus `requestedPath`, `status`, `cwd`, `session`, and `tempPath` when applicable.
 - `savedFilePath` / `savedFile` for direct `download`, `pdf`, and `wait --download` saved-file workflows; batch results preserve the same fields on the relevant `batchSteps` entry.
 - `batchSteps[].artifacts` for per-step artifacts in `batch` output; top-level `artifacts` aggregates all step artifacts in order
 - `fullOutputPath` / `fullOutputPaths` when large snapshot output or other oversized tool output is compacted and spilled to a private file; persisted sessions keep that path under a private session-scoped artifact directory with a bounded per-session budget so it survives reload/resume without unbounded growth
@@ -189,15 +189,16 @@ For oversized snapshots and other oversized tool outputs, details should switch
 "Rendering" here means how results appear inside `pi`, not embedding a browser UI.
 
 Worth doing in v1:
-- screenshots → saved-path summary, `details.artifacts` metadata, and inline image attachment when safe
+- screenshots → saved-path summary, visible artifact metadata, `details.artifacts` metadata, and inline image attachment when safe; screenshot paths that upstream would treat ambiguously, such as `.dogfood/run/foo.png`, are normalized to absolute paths before launch and repaired from upstream temp output when possible
 - file artifacts such as PDFs, downloads, `wait --download` files, traces, CPU profiles, completed WebM recordings, and path-bearing HAR captures → concise saved-path summaries plus metadata in `details.artifacts` and bounded recent metadata in `details.artifactManifest`; `record start` reports recording lifecycle state and the future output path without adding a missing manifest entry; direct saved-file workflows also expose `details.savedFilePath` / `details.savedFile`; large or binary artifacts are not inlined into model context; the recent manifest cap can age out explicit-file metadata but does not remove explicit saved files from disk
 - snapshots → origin + ref count + main-content-first compact preview, with the raw snapshot spill path printed directly in content and kept in `details.fullOutputPath` plus `details.artifactManifest` when the inline result would otherwise be too large
 - oversized generic outputs such as large `eval --stdin` payloads → compact preview plus the actual spill file path instead of dumping the whole payload into model context
 - extraction-style commands like `eval --stdin` and `get title` → scalar-first text with lightweight origin context when available
 - navigation actions like `click`, `back`, `forward`, and `reload` → lightweight post-action title/url summary when available
 - tab lists → compact summary/table
-- stream status → enabled/connected/port summary
+- stream status → enabled/connected/port summary plus WebSocket URL and frame format when a port is known; if the caller explicitly passed `--json`, visible text is valid JSON instead of a prose summary
 - diagnostic/status families (`session`, `session list`, `profiles`, `doctor`, `auth list`/`show`, `network requests`, `console`, `errors`, and dashboard start/stop/status outputs) → compact readable summaries with counts and stable fields; large log/request/error outputs use previews plus `fullOutputPath` spill files; sensitive nested auth/header/token fields are not expanded in the model-facing text
+- trace/profiler owner conflicts → when the wrapper has observed one owner active for a session, block conflicting starts/stops with "wrapper believes ..." wording because upstream or external CLI use can desynchronize wrapper-local state
 
 ## Missing binary behavior
 
@@ -212,8 +213,9 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - derive the base implicit session name from the official `pi` session id plus a cwd hash so same-named checkouts do not collide
 - respect explicit upstream `--session` with minimal interference
 - treat the extension-managed session as convenience state owned by the wrapper
-- preserve the current extension-managed session across normal `pi` shutdown/reload so persisted sessions can keep following the live browser on `/reload` or `/resume`
-- set an idle timeout on extension-managed sessions so abandoned daemons eventually self-clean
+- preserve the current extension-managed session across `/reload` and resumable session transitions so persisted sessions can keep following the live browser on `/reload` or `/resume`
+- close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone
+- set an idle timeout on extension-managed sessions as a backstop for abnormal exits or cleanup failures
 - clean up process-private temp spill artifacts on shutdown, while keeping persisted-session snapshot spill files in a private session-scoped artifact directory so `details.fullOutputPath` survives reload/restart and the oldest spill files are evicted if the per-session artifact budget is exceeded
 - reconstruct the current extension-managed session and latest `artifactManifest` from persisted tool details on resume/reload so later default calls keep following the active managed browser and can continue reporting artifact retention state
 - when an unnamed `sessionMode: "fresh"` launch succeeds, make it the new extension-managed session so later default calls keep using it

package/extensions/agent-browser/index.ts

@@ -6,7 +6,8 @@
  * Invariants/Assumptions: agent-browser is installed separately on PATH, the wrapper targets the current locally installed upstream version only, and no backward-compatibility shims are provided.
  */
 
-import { readFile, rm } from "node:fs/promises";
+import { copyFile, mkdir, readFile, rm, stat } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, resolve } from "node:path";
 
 import { StringEnum } from "@mariozechner/pi-ai";
 import { isToolCallEventType, type AgentToolResult, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
@@ -64,6 +65,8 @@ import {
 } from "./lib/results/shared.js";
 
 const DEFAULT_SESSION_MODE = "auto" as const;
+const DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV = "PI_AGENT_BROWSER_ALLOW_DIRECT_BASH";
+const PACKAGE_NAME = "pi-agent-browser-native";
 
 const AGENT_BROWSER_PARAMS = Type.Object({
 	args: Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name." }), {
@@ -292,6 +295,23 @@ function isHarmlessAgentBrowserInspectionCommand(command: string): boolean {
 	return HARMLESS_AGENT_BROWSER_INSPECTION_PATTERN.test(command);
 }
 
+function isTruthyEnvValue(value: string | undefined): boolean {
+	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
+}
+
+async function isPackageDevelopmentCwd(cwd: string): Promise<boolean> {
+	try {
+		const packageJson = JSON.parse(await readFile(join(cwd, "package.json"), "utf8")) as { name?: unknown };
+		return packageJson.name === PACKAGE_NAME;
+	} catch {
+		return false;
+	}
+}
+
+async function isDirectAgentBrowserBashAllowed(cwd: string): Promise<boolean> {
+	return isTruthyEnvValue(process.env[DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV]) || await isPackageDevelopmentCwd(cwd);
+}
+
 const NAVIGATION_SUMMARY_COMMANDS = new Set(["back", "click", "dblclick", "forward", "reload"]);
 
 interface NavigationSummary {
@@ -303,6 +323,330 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
+const SCREENSHOT_VALUE_FLAGS = new Set(["--screenshot-dir", "--screenshot-format", "--screenshot-quality"]);
+const SCREENSHOT_IMAGE_EXTENSIONS = new Set([".jpeg", ".jpg", ".png", ".webp"]);
+
+interface ScreenshotPathRequest {
+	absolutePath: string;
+	path: string;
+}
+
+interface PreparedAgentBrowserArgs {
+	args: string[];
+	batchScreenshotPathRequests?: Array<ScreenshotPathRequest | undefined>;
+	screenshotPathRequest?: ScreenshotPathRequest;
+	stdin?: string;
+}
+
+interface ScreenshotArtifactRequest extends ScreenshotPathRequest {
+	status?: "missing" | "repaired-from-temp" | "saved" | "upstream-temp-only";
+	tempPath?: string;
+}
+
+type TraceOwner = "profiler" | "trace";
+
+function isImagePathToken(token: string): boolean {
+	const extension = extname(token).toLowerCase();
+	return SCREENSHOT_IMAGE_EXTENSIONS.has(extension);
+}
+
+function getScreenshotPathTokenIndex(commandTokens: string[]): number | undefined {
+	if (commandTokens[0] !== "screenshot") {
+		return undefined;
+	}
+
+	const positionalIndices: number[] = [];
+	for (let index = 1; index < commandTokens.length; index += 1) {
+		const token = commandTokens[index];
+		if (token === "--") {
+			for (let positionalIndex = index + 1; positionalIndex < commandTokens.length; positionalIndex += 1) {
+				positionalIndices.push(positionalIndex);
+			}
+			break;
+		}
+		if (token.startsWith("-")) {
+			const normalizedToken = token.split("=", 1)[0] ?? token;
+			if (SCREENSHOT_VALUE_FLAGS.has(normalizedToken) && !token.includes("=")) {
+				index += 1;
+			}
+			continue;
+		}
+		positionalIndices.push(index);
+	}
+
+	if (positionalIndices.length === 0) {
+		return undefined;
+	}
+	const candidateIndex = positionalIndices[positionalIndices.length - 1];
+	const candidate = commandTokens[candidateIndex];
+	if (positionalIndices.length >= 2 || isImagePathToken(candidate) || isAbsolute(candidate) || candidate.startsWith("./") || candidate.startsWith("../")) {
+		return candidateIndex;
+	}
+	return undefined;
+}
+
+async function normalizeScreenshotPathInTokens(commandTokens: string[], cwd: string): Promise<{
+	request?: ScreenshotPathRequest;
+	tokens: string[];
+}> {
+	const screenshotPathTokenIndex = getScreenshotPathTokenIndex(commandTokens);
+	if (screenshotPathTokenIndex === undefined) {
+		return { tokens: commandTokens };
+	}
+
+	const requestedPath = commandTokens[screenshotPathTokenIndex];
+	const absolutePath = resolve(cwd, requestedPath);
+	await mkdir(dirname(absolutePath), { recursive: true });
+
+	const tokens = [...commandTokens];
+	tokens[screenshotPathTokenIndex] = absolutePath;
+	const terminatorIndex = tokens.indexOf("--");
+	if (terminatorIndex >= 0) {
+		tokens.splice(terminatorIndex, 1);
+	}
+
+	return {
+		request: {
+			absolutePath,
+			path: requestedPath,
+		},
+		tokens,
+	};
+}
+
+async function prepareBatchScreenshotPaths(args: string[], stdin: string | undefined, cwd: string): Promise<PreparedAgentBrowserArgs | undefined> {
+	const commandTokens = extractCommandTokens(args);
+	if (commandTokens[0] !== "batch" || stdin === undefined) {
+		return undefined;
+	}
+	let steps: unknown;
+	try {
+		steps = JSON.parse(stdin);
+	} catch {
+		return undefined;
+	}
+	if (!Array.isArray(steps)) {
+		return undefined;
+	}
+
+	let changed = false;
+	const batchScreenshotPathRequests: Array<ScreenshotPathRequest | undefined> = [];
+	const preparedSteps = await Promise.all(steps.map(async (step, index) => {
+		if (!Array.isArray(step) || !step.every((item) => typeof item === "string") || step[0] !== "screenshot") {
+			return step;
+		}
+		const normalized = await normalizeScreenshotPathInTokens(step, cwd);
+		batchScreenshotPathRequests[index] = normalized.request;
+		if (normalized.request) {
+			changed = true;
+		}
+		return normalized.tokens;
+	}));
+
+	return changed
+		? {
+				args,
+				batchScreenshotPathRequests,
+				stdin: JSON.stringify(preparedSteps),
+		  }
+		: undefined;
+}
+
+async function prepareAgentBrowserArgs(args: string[], stdin: string | undefined, cwd: string): Promise<PreparedAgentBrowserArgs> {
+	const preparedBatch = await prepareBatchScreenshotPaths(args, stdin, cwd);
+	if (preparedBatch) {
+		return preparedBatch;
+	}
+
+	const commandTokens = extractCommandTokens(args);
+	const normalized = await normalizeScreenshotPathInTokens(commandTokens, cwd);
+	if (!normalized.request) {
+		return { args };
+	}
+
+	const commandStartIndex = args.length - commandTokens.length;
+	return {
+		args: [...args.slice(0, commandStartIndex), ...normalized.tokens],
+		screenshotPathRequest: normalized.request,
+	};
+}
+
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function repairScreenshotData(options: {
+	cwd: string;
+	data: Record<string, unknown>;
+	request: ScreenshotPathRequest;
+}): Promise<{ data: Record<string, unknown>; request: ScreenshotArtifactRequest }> {
+	const { cwd, data, request } = options;
+	const reportedPath = typeof data.path === "string" ? data.path : undefined;
+	const reportedAbsolutePath = reportedPath ? resolve(cwd, reportedPath) : undefined;
+	let status: ScreenshotArtifactRequest["status"] = await pathExists(request.absolutePath) ? "saved" : "missing";
+	let tempPath: string | undefined;
+
+	if (reportedAbsolutePath && reportedAbsolutePath !== request.absolutePath) {
+		tempPath = reportedAbsolutePath;
+		if (status === "missing" && await pathExists(reportedAbsolutePath)) {
+			await mkdir(dirname(request.absolutePath), { recursive: true });
+			await copyFile(reportedAbsolutePath, request.absolutePath);
+			status = "repaired-from-temp";
+		}
+	}
+
+	return {
+		data: {
+			...data,
+			path: request.absolutePath,
+		},
+		request: {
+			...request,
+			status,
+			tempPath,
+		},
+	};
+}
+
+async function repairScreenshotArtifact(options: {
+	cwd: string;
+	envelope?: AgentBrowserEnvelope;
+	request?: ScreenshotPathRequest;
+}): Promise<{ envelope?: AgentBrowserEnvelope; request?: ScreenshotArtifactRequest }> {
+	const { cwd, envelope, request } = options;
+	if (!request || !envelope || !isRecord(envelope.data)) {
+		return { envelope, request };
+	}
+
+	const repaired = await repairScreenshotData({ cwd, data: envelope.data, request });
+	return {
+		envelope: { ...envelope, data: repaired.data },
+		request: repaired.request,
+	};
+}
+
+async function repairBatchScreenshotArtifacts(options: {
+	cwd: string;
+	envelope?: AgentBrowserEnvelope;
+	requests?: Array<ScreenshotPathRequest | undefined>;
+}): Promise<{ envelope?: AgentBrowserEnvelope; requests?: Array<ScreenshotArtifactRequest | undefined> }> {
+	const { cwd, envelope, requests } = options;
+	if (!envelope || !Array.isArray(envelope.data) || !requests?.some((request) => request !== undefined)) {
+		return { envelope, requests };
+	}
+
+	const repairedRequests: Array<ScreenshotArtifactRequest | undefined> = [];
+	const repairedData = await Promise.all(envelope.data.map(async (item, index) => {
+		const request = requests[index];
+		if (!request || !isRecord(item) || !isRecord(item.result)) {
+			return item;
+		}
+		const repaired = await repairScreenshotData({ cwd, data: item.result, request });
+		repairedRequests[index] = repaired.request;
+		return {
+			...item,
+			result: repaired.data,
+		};
+	}));
+
+	return {
+		envelope: { ...envelope, data: repairedData },
+		requests: repairedRequests,
+	};
+}
+
+function buildJsonVisibleContent(options: {
+	error: unknown;
+	presentation: Awaited<ReturnType<typeof buildToolPresentation>>;
+	succeeded: boolean;
+	warnings?: string[];
+}): Array<{ text: string; type: "text" } | { data: string; mimeType: string; type: "image" }> {
+	const { error, presentation, succeeded, warnings } = options;
+	const payload = redactSensitiveValue({
+		artifacts: presentation.artifacts,
+		data: presentation.data,
+		error,
+		success: succeeded,
+		warnings: warnings && warnings.length > 0 ? warnings : undefined,
+	});
+	if (isRecord(payload) && isRecord(payload.data) && isRecord(presentation.data) && typeof presentation.data.wsUrl === "string") {
+		payload.data.wsUrl = presentation.data.wsUrl;
+	}
+	const images = presentation.content.filter((item): item is { data: string; mimeType: string; type: "image" } => item.type === "image");
+	return [{ type: "text", text: JSON.stringify(payload, null, 2) }, ...images];
+}
+
+function getBatchAnnotateValidationError(args: string[], stdin: string | undefined): string | undefined {
+	const commandTokens = extractCommandTokens(args);
+	if (commandTokens[0] !== "batch" || stdin === undefined) {
+		return undefined;
+	}
+	let steps: unknown;
+	try {
+		steps = JSON.parse(stdin);
+	} catch {
+		return undefined;
+	}
+	if (!Array.isArray(steps)) {
+		return undefined;
+	}
+	const badStepIndex = steps.findIndex((step) => Array.isArray(step) && step[0] === "screenshot" && step.includes("--annotate"));
+	if (badStepIndex < 0) {
+		return undefined;
+	}
+	return [
+		`Unsupported batch screenshot annotation in step ${badStepIndex + 1}: put --annotate in top-level args, not inside the batch step.`,
+		`Use: { "args": ["--annotate", "batch"], "stdin": "[[\\"screenshot\\",\\"/path/to/image.png\\"]]" }`,
+	].join("\n");
+}
+
+function getTraceOwner(command: string | undefined): TraceOwner | undefined {
+	return command === "trace" || command === "profiler" ? command : undefined;
+}
+
+function getTraceOwnerGuardMessage(options: {
+	command: string | undefined;
+	sessionName: string | undefined;
+	subcommand: string | undefined;
+	traceOwners: Map<string, TraceOwner>;
+}): string | undefined {
+	const owner = getTraceOwner(options.command);
+	if (!owner || !options.sessionName || (options.subcommand !== "start" && options.subcommand !== "stop")) {
+		return undefined;
+	}
+	const activeOwner = options.traceOwners.get(options.sessionName);
+	if (!activeOwner || activeOwner === owner) {
+		return undefined;
+	}
+	return options.subcommand === "start"
+		? `Wrapper believes ${activeOwner} tracing is active for session ${options.sessionName}; stop ${activeOwner} before starting ${owner}.`
+		: `Wrapper believes tracing for session ${options.sessionName} is owned by ${activeOwner}; run ${activeOwner} stop instead of ${owner} stop.`;
+}
+
+function updateTraceOwnerState(options: {
+	command: string | undefined;
+	sessionName: string | undefined;
+	subcommand: string | undefined;
+	succeeded: boolean;
+	traceOwners: Map<string, TraceOwner>;
+}): void {
+	const owner = getTraceOwner(options.command);
+	if (!owner || !options.sessionName || !options.succeeded) {
+		return;
+	}
+	if (options.subcommand === "start") {
+		options.traceOwners.set(options.sessionName, owner);
+	}
+	if (options.subcommand === "stop" && options.traceOwners.get(options.sessionName) === owner) {
+		options.traceOwners.delete(options.sessionName);
+	}
+}
+
 function shouldCaptureNavigationSummary(command: string | undefined, data: unknown): boolean {
 	return (
 		command !== undefined &&
@@ -1025,6 +1369,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 	let freshSessionOrdinal = 0;
 	let sessionTabTargets = new Map<string, OrderedSessionTabTarget>();
 	let sessionTabTargetUpdateOrder = 0;
+	let traceOwners = new Map<string, TraceOwner>();
 	let artifactManifest: SessionArtifactManifest | undefined;
 	const managedSessionExecutionQueue = new AsyncExecutionQueue();
 
@@ -1040,10 +1385,21 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		artifactManifest = restoreArtifactManifestFromBranch(ctx.sessionManager.getBranch());
 	});
 
-	pi.on("session_shutdown", async () => {
+	pi.on("session_shutdown", async (event) => {
+		if (event?.reason === "quit") {
+			await managedSessionExecutionQueue.run(async () => {
+				if (!managedSessionActive) return;
+				await closeManagedSession({
+					cwd: managedSessionCwd,
+					sessionName: managedSessionName,
+					timeoutMs: implicitSessionCloseTimeoutMs,
+				});
+			});
+		}
 		managedSessionActive = false;
 		sessionTabTargets = new Map<string, OrderedSessionTabTarget>();
 		sessionTabTargetUpdateOrder = 0;
+		traceOwners = new Map<string, TraceOwner>();
 		artifactManifest = undefined;
 		await cleanupSecureTempArtifacts();
 	});
@@ -1063,7 +1419,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 			isToolCallEventType("bash", event) &&
 			!promptPolicy.allowLegacyAgentBrowserBash &&
 			looksLikeDirectAgentBrowserBash(event.input.command) &&
-			!isHarmlessAgentBrowserInspectionCommand(event.input.command)
+			!isHarmlessAgentBrowserInspectionCommand(event.input.command) &&
+			!(await isDirectAgentBrowserBashAllowed(ctx.cwd))
 		) {
 			return {
 				block: true,
@@ -1083,7 +1440,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		parameters: AGENT_BROWSER_PARAMS,
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const redactedArgs = redactInvocationArgs(params.args);
-			const validationError = validateToolArgs(params.args);
+			const validationError = validateToolArgs(params.args) ?? getBatchAnnotateValidationError(params.args, params.stdin);
 			if (validationError) {
 				return {
 					content: [{ type: "text", text: validationError }],
@@ -1091,12 +1448,14 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					isError: true,
 				};
 			}
+			const preparedArgs = await prepareAgentBrowserArgs(params.args, params.stdin, ctx.cwd);
+			const userRequestedJson = params.args.includes("--json");
 
 			const tabTargetUpdateOrder = ++sessionTabTargetUpdateOrder;
 			const runTool = async (): Promise<AgentBrowserToolResult> => {
 				const sessionMode = params.sessionMode ?? DEFAULT_SESSION_MODE;
 				const freshSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1);
-				const executionPlan = buildExecutionPlan(params.args, {
+				const executionPlan = buildExecutionPlan(preparedArgs.args, {
 					freshSessionName,
 					managedSessionActive,
 					managedSessionName,
@@ -1124,7 +1483,28 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					};
 				}
 
-				const commandTokens = extractCommandTokens(params.args);
+				const commandTokens = extractCommandTokens(preparedArgs.args);
+				const traceOwnerGuardMessage = getTraceOwnerGuardMessage({
+					command: executionPlan.commandInfo.command,
+					sessionName: executionPlan.sessionName,
+					subcommand: executionPlan.commandInfo.subcommand,
+					traceOwners,
+				});
+				if (traceOwnerGuardMessage) {
+					return {
+						content: [{ type: "text", text: traceOwnerGuardMessage }],
+						details: {
+							args: redactedArgs,
+							command: executionPlan.commandInfo.command,
+							compatibilityWorkaround,
+							effectiveArgs: redactedEffectiveArgs,
+							sessionMode,
+							validationError: traceOwnerGuardMessage,
+							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+						},
+						isError: true,
+					};
+				}
 				const stdinValidationError = validateStdinCommandContract({
 					command: executionPlan.commandInfo.command,
 					commandTokens,
@@ -1152,7 +1532,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				let includePinnedNavigationSummary = false;
 				let sessionTabCorrection: OpenResultTabCorrection | undefined;
 				let processArgs = executionPlan.effectiveArgs;
-				let processStdin = params.stdin;
+				let processStdin = preparedArgs.stdin ?? params.stdin;
 				if (
 					priorSessionTabTarget &&
 					shouldPinSessionTabForCommand({
@@ -1283,6 +1663,20 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						presentationEnvelope = pinnedBatchResult.envelope ?? presentationEnvelope;
 						navigationSummary = pinnedBatchResult.navigationSummary;
 					}
+					const repairedScreenshot = await repairScreenshotArtifact({
+						cwd: ctx.cwd,
+						envelope: presentationEnvelope,
+						request: preparedArgs.screenshotPathRequest,
+					});
+					presentationEnvelope = repairedScreenshot.envelope;
+					const repairedBatchScreenshots = await repairBatchScreenshotArtifacts({
+						cwd: ctx.cwd,
+						envelope: presentationEnvelope,
+						requests: preparedArgs.batchScreenshotPathRequests,
+					});
+					presentationEnvelope = repairedBatchScreenshots.envelope;
+					const screenshotArtifactRequest = repairedScreenshot.request;
+					const batchScreenshotArtifactRequests = repairedBatchScreenshots.requests;
 					const parseFailureOutput = parseError
 						? await preserveParseFailureOutput({
 								artifactManifest,
@@ -1296,6 +1690,13 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					const envelopeSuccess = plainTextInspection ? true : presentationEnvelope?.success !== false;
 					const succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
 					const inspectionText = plainTextInspection ? processResult.stdout.trim() : undefined;
+					updateTraceOwnerState({
+						command: executionPlan.commandInfo.command,
+						sessionName: executionPlan.sessionName,
+						subcommand: executionPlan.commandInfo.subcommand,
+						succeeded,
+						traceOwners,
+					});
 
 					if (succeeded && !navigationSummary && shouldCaptureNavigationSummary(executionPlan.commandInfo.command, presentationEnvelope?.data)) {
 						navigationSummary = await collectNavigationSummary({
@@ -1477,11 +1878,14 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						  }
 						: await buildToolPresentation({
 								artifactManifest,
+								artifactRequest: screenshotArtifactRequest,
+								batchArtifactRequests: batchScreenshotArtifactRequests,
 								commandInfo: executionPlan.commandInfo,
 								cwd: ctx.cwd,
 								envelope: presentationEnvelope,
 								errorText,
 								persistentArtifactStore,
+								sessionName: executionPlan.sessionName,
 						  });
 					if (parseFailureOutput.artifactManifest) {
 						presentation.artifactManifest = parseFailureOutput.artifactManifest;
@@ -1504,20 +1908,29 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					if (presentation.artifactManifest) {
 						artifactManifest = presentation.artifactManifest;
 					}
-					const contentWithSessionWarnings = aboutBlankSessionMismatch ? [...presentation.content] : presentation.content;
-					if (aboutBlankSessionMismatch) {
-						const warning = buildAboutBlankWarning(aboutBlankSessionMismatch);
+					const warningText = aboutBlankSessionMismatch ? buildAboutBlankWarning(aboutBlankSessionMismatch) : undefined;
+					const contentWithSessionWarnings = userRequestedJson && !plainTextInspection
+						? buildJsonVisibleContent({
+								error: presentationEnvelope?.error,
+								presentation,
+								succeeded,
+								warnings: warningText ? [warningText] : undefined,
+						  })
+						: warningText
+							? [...presentation.content]
+							: presentation.content;
+					if (warningText && !userRequestedJson) {
 						if (contentWithSessionWarnings[0]?.type === "text") {
 							contentWithSessionWarnings[0] = {
 								...contentWithSessionWarnings[0],
-								text: `${warning}\n\n${contentWithSessionWarnings[0].text}`,
+								text: `${warningText}\n\n${contentWithSessionWarnings[0].text}`,
 							};
 						} else {
-							contentWithSessionWarnings.unshift({ type: "text", text: warning });
+							contentWithSessionWarnings.unshift({ type: "text", text: warningText });
 						}
 					}
 					const redactedContent = contentWithSessionWarnings.map((item) =>
-						item.type === "text" ? { ...item, text: redactSensitiveText(item.text) } : item,
+						item.type === "text" && !(userRequestedJson && !plainTextInspection) ? { ...item, text: redactSensitiveText(item.text) } : item,
 					);
 
 					return {

package/extensions/agent-browser/lib/playbook.ts

@@ -18,6 +18,7 @@ export const QUICK_START_GUIDELINES = [
 	"Common first calls: { args: [\"open\", \"https://example.com\"] } then { args: [\"snapshot\", \"-i\"] }; after navigation, use { args: [\"click\", \"@e2\"] } then { args: [\"snapshot\", \"-i\"] }.",
 	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, and { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }.",
 	"High-value command reference: download <selector> <path> saves a file triggered by a click; get title/url/text/html/value/attr/count reads page state; screenshot [path] captures an image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab.",
+	"For artifact-producing commands, read the visible artifact block for requested path, absolute path, existence, size, type, cwd, and session; details.artifacts contains the same machine-readable metadata. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step.",
 ] as const;
 
 export const BRAVE_SEARCH_PROMPT_GUIDELINE =

package/extensions/agent-browser/lib/results/presentation.ts

@@ -173,10 +173,27 @@ function getStreamSummary(data: Record<string, unknown>): string | undefined {
 	];
 	if (typeof data.port === "number") {
 		lines.push(`Port: ${data.port}`);
+		lines.push(`WebSocket URL: ${getStreamWebSocketUrl(data.port)}`);
+		lines.push(`Frame format: JSON messages with base64 JPEG frame data`);
 	}
 	return lines.join("\n");
 }
 
+function getStreamWebSocketUrl(port: number): string {
+	return `ws://127.0.0.1:${port}`;
+}
+
+function enrichStreamStatusData(commandInfo: CommandInfo, data: unknown): unknown {
+	if (commandInfo.command !== "stream" || commandInfo.subcommand !== "status" || !isRecord(data) || typeof data.port !== "number") {
+		return data;
+	}
+	return {
+		...data,
+		frameFormat: "JSON messages with base64 JPEG frame data",
+		wsUrl: getStreamWebSocketUrl(data.port),
+	};
+}
+
 function getArrayField(data: Record<string, unknown>, key: string): unknown[] | undefined {
 	return Array.isArray(data[key]) ? data[key] : undefined;
 }
@@ -662,18 +679,28 @@ function extractPathStrings(data: unknown): string[] {
 	return [...new Set(paths)];
 }
 
+interface ArtifactRequestContext {
+	absolutePath: string;
+	path: string;
+	status?: FileArtifactMetadata["status"];
+	tempPath?: string;
+}
+
 async function buildFileArtifactMetadata(options: {
+	artifactRequest?: ArtifactRequestContext;
 	commandInfo: CommandInfo;
 	cwd: string;
 	path: string;
+	sessionName?: string;
 }): Promise<FileArtifactMetadata | undefined> {
 	const kind = getArtifactKind(options.commandInfo);
 	if (!kind) {
 		return undefined;
 	}
 
-	const absolutePath = resolve(options.cwd, options.path);
-	const extension = extname(options.path).toLowerCase() || undefined;
+	const absolutePath = options.artifactRequest?.absolutePath ?? resolve(options.cwd, options.path);
+	const displayPath = options.artifactRequest?.path ?? options.path;
+	const extension = extname(absolutePath || options.path).toLowerCase() || undefined;
 	let exists: boolean | undefined;
 	let sizeBytes: number | undefined;
 	try {
@@ -686,20 +713,32 @@ async function buildFileArtifactMetadata(options: {
 
 	return {
 		absolutePath,
+		artifactType: kind,
 		command: options.commandInfo.command,
+		cwd: options.cwd,
 		exists,
 		extension,
 		kind,
 		mediaType: extension ? ARTIFACT_EXTENSION_TO_MEDIA_TYPE[extension] : undefined,
-		path: options.path,
+		path: displayPath,
+		requestedPath: options.artifactRequest?.path,
+		session: options.sessionName,
 		sizeBytes,
+		status: options.artifactRequest?.status ?? (exists === false ? "missing" : "saved"),
 		subcommand: options.commandInfo.subcommand,
+		tempPath: options.artifactRequest?.tempPath,
 	};
 }
 
-async function extractFileArtifacts(commandInfo: CommandInfo, cwd: string, data: unknown): Promise<FileArtifactMetadata[]> {
-	const candidates = extractPathStrings(data);
-	const artifacts = await Promise.all(candidates.map((path) => buildFileArtifactMetadata({ commandInfo, cwd, path })));
+async function extractFileArtifacts(options: {
+	artifactRequest?: ArtifactRequestContext;
+	commandInfo: CommandInfo;
+	cwd: string;
+	data: unknown;
+	sessionName?: string;
+}): Promise<FileArtifactMetadata[]> {
+	const candidates = extractPathStrings(options.data);
+	const artifacts = await Promise.all(candidates.map((path) => buildFileArtifactMetadata({ ...options, path })));
 	return artifacts.filter((artifact): artifact is FileArtifactMetadata => artifact !== undefined);
 }
 
@@ -708,12 +747,15 @@ function buildManifestEntriesForFileArtifacts(artifacts: FileArtifactMetadata[],
 		absolutePath: artifact.absolutePath,
 		command: artifact.command,
 		createdAtMs: nowMs,
+		cwd: artifact.cwd,
 		exists: artifact.exists,
 		extension: artifact.extension,
 		kind: artifact.kind,
 		mediaType: artifact.mediaType,
 		path: artifact.path,
+		requestedPath: artifact.requestedPath,
 		retentionState: artifact.exists === false ? "missing" : "live",
+		session: artifact.session,
 		sizeBytes: artifact.sizeBytes,
 		storageScope: "explicit-path",
 		subcommand: artifact.subcommand,
@@ -761,17 +803,37 @@ function formatArtifactSummary(artifacts: FileArtifactMetadata[]): string | unde
 }
 
 function formatArtifactMetadataLines(artifacts: FileArtifactMetadata[]): string[] {
-	return artifacts.map((artifact) => {
+	return artifacts.map((artifact, index) => {
 		if (isRecordingStartArtifact(artifact)) {
-			return `${formatArtifactLabel(artifact)}: ${artifact.path}`;
+			return [
+				`${formatArtifactLabel(artifact)}: ${artifact.path}`,
+				`Artifact type: ${artifact.kind}`,
+				`Requested path: ${artifact.requestedPath ?? artifact.path}`,
+				`Absolute path: ${artifact.absolutePath}`,
+				`Exists: ${artifact.exists === true}`,
+				`Status: ${artifact.status ?? (artifact.exists === false ? "missing" : "saved")}`,
+				artifact.session ? `Session: ${artifact.session}` : undefined,
+				artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
+				`Machine data: details.artifacts[${index}]`,
+			].filter((item): item is string => item !== undefined).join("\n");
 		}
 
-		const suffix = [
-			artifact.mediaType,
-			typeof artifact.sizeBytes === "number" ? formatByteCount(artifact.sizeBytes) : undefined,
+		return [
+			`${formatArtifactLabel(artifact)}: ${artifact.path}`,
+			`Artifact type: ${artifact.kind}`,
+			`Requested path: ${artifact.requestedPath ?? artifact.path}`,
+			`Absolute path: ${artifact.absolutePath}`,
+			`Exists: ${artifact.exists === true}`,
 			artifact.exists === false ? "not found on disk" : undefined,
-		].filter((item): item is string => item !== undefined).join(", ");
-		return suffix ? `${formatArtifactLabel(artifact)}: ${artifact.path} (${suffix})` : `${formatArtifactLabel(artifact)}: ${artifact.path}`;
+			typeof artifact.sizeBytes === "number" ? `Size: ${formatByteCount(artifact.sizeBytes)}` : undefined,
+			typeof artifact.sizeBytes === "number" ? `Size bytes: ${artifact.sizeBytes}` : undefined,
+			`Status: ${artifact.status ?? (artifact.exists === false ? "missing" : "saved")}`,
+			artifact.tempPath ? `Temp path: ${artifact.tempPath}` : undefined,
+			artifact.mediaType ? `Media type: ${artifact.mediaType}` : undefined,
+			artifact.session ? `Session: ${artifact.session}` : undefined,
+			artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
+			`Machine data: details.artifacts[${index}]`,
+		].filter((item): item is string => item !== undefined).join("\n");
 	});
 }
 
@@ -1020,12 +1082,14 @@ function getBatchFailureDetails(steps: Array<{ details: BatchStepPresentationDet
 
 async function buildBatchStepPresentation(options: {
 	artifactManifest?: SessionArtifactManifest;
+	artifactRequest?: ArtifactRequestContext;
 	cwd: string;
 	index: number;
 	item: AgentBrowserBatchResult;
 	persistentArtifactStore?: PersistentSessionArtifactStore;
+	sessionName?: string;
 }): Promise<{ details: BatchStepPresentationDetails; presentation: ToolPresentation }> {
-	const { artifactManifest, cwd, index, item, persistentArtifactStore } = options;
+	const { artifactManifest, artifactRequest, cwd, index, item, persistentArtifactStore, sessionName } = options;
 	const command = isStringArray(item.command) ? item.command : undefined;
 	const commandText = formatBatchStepCommand(command, index);
 
@@ -1052,10 +1116,12 @@ async function buildBatchStepPresentation(options: {
 
 	const presentation = await buildToolPresentation({
 		artifactManifest,
+		artifactRequest,
 		commandInfo: parseCommandInfo(command ?? []),
 		cwd,
 		envelope: { data: item.result, success: true },
 		persistentArtifactStore,
+		sessionName,
 	});
 	const fullOutputPaths = getPresentationPaths({
 		primaryPath: presentation.fullOutputPath,
@@ -1090,24 +1156,28 @@ async function buildBatchStepPresentation(options: {
 
 async function buildBatchPresentation(options: {
 	artifactManifest?: SessionArtifactManifest;
+	artifactRequests?: Array<ArtifactRequestContext | undefined>;
 	cwd: string;
 	data: AgentBrowserBatchResult[];
 	persistentArtifactStore?: PersistentSessionArtifactStore;
+	sessionName?: string;
 	summary: string;
 }): Promise<ToolPresentation> {
-	const { cwd, data, persistentArtifactStore, summary } = options;
+	const { artifactRequests, cwd, data, persistentArtifactStore, sessionName, summary } = options;
 	const steps: Array<{ details: BatchStepPresentationDetails; presentation: ToolPresentation }> = [];
 	const protectedPersistentPaths: string[] = [];
 	let currentArtifactManifest = options.artifactManifest;
 	for (const [index, item] of data.entries()) {
 		const step = await buildBatchStepPresentation({
 			artifactManifest: currentArtifactManifest,
+			artifactRequest: artifactRequests?.[index],
 			cwd,
 			index,
 			item,
 			persistentArtifactStore: persistentArtifactStore
 				? { ...persistentArtifactStore, protectedPaths: protectedPersistentPaths }
 				: undefined,
+			sessionName,
 		});
 		steps.push(step);
 		currentArtifactManifest = step.presentation.artifactManifest ?? currentArtifactManifest;
@@ -1522,13 +1592,16 @@ async function compactLargePresentationOutput(options: {
 
 export async function buildToolPresentation(options: {
 	artifactManifest?: SessionArtifactManifest;
+	artifactRequest?: ArtifactRequestContext;
+	batchArtifactRequests?: Array<ArtifactRequestContext | undefined>;
 	commandInfo: CommandInfo;
 	cwd: string;
 	envelope?: AgentBrowserEnvelope;
 	errorText?: string;
 	persistentArtifactStore?: PersistentSessionArtifactStore;
+	sessionName?: string;
 }): Promise<ToolPresentation> {
-	const { artifactManifest, commandInfo, cwd, envelope, errorText, persistentArtifactStore } = options;
+	const { artifactManifest, artifactRequest, commandInfo, cwd, envelope, errorText, persistentArtifactStore, sessionName } = options;
 	if (errorText) {
 		const hintedErrorText = appendSelectorRecoveryHint(redactModelFacingText(errorText));
 		return {
@@ -1537,14 +1610,14 @@ export async function buildToolPresentation(options: {
 		};
 	}
 
-	const data = envelope?.data;
-	const artifacts = await extractFileArtifacts(commandInfo, cwd, data);
+	const data = enrichStreamStatusData(commandInfo, envelope?.data);
+	const artifacts = await extractFileArtifacts({ artifactRequest, commandInfo, cwd, data, sessionName });
 	const artifactSummary = formatArtifactSummary(artifacts);
 	const summary = artifactSummary ?? formatSummary(commandInfo, data);
 	const artifactText = artifacts.length > 0 ? formatArtifactMetadataLines(artifacts).join("\n") : undefined;
 	const presentation =
 		commandInfo.command === "batch" && Array.isArray(data)
-			? await buildBatchPresentation({ artifactManifest, cwd, data: data as AgentBrowserBatchResult[], persistentArtifactStore, summary })
+			? await buildBatchPresentation({ artifactManifest, artifactRequests: options.batchArtifactRequests, cwd, data: data as AgentBrowserBatchResult[], persistentArtifactStore, sessionName, summary })
 			: commandInfo.command === "snapshot" && isRecord(data)
 				? await buildSnapshotPresentation(data, persistentArtifactStore, artifactManifest)
 				: {
@@ -1564,7 +1637,7 @@ export async function buildToolPresentation(options: {
 		}
 	}
 
-	const imagePath = extractImagePath(commandInfo, cwd, data);
+	const imagePath = artifactRequest?.absolutePath ?? extractImagePath(commandInfo, cwd, data);
 	const presentationWithImage = imagePath ? await attachInlineImage(presentation, imagePath) : presentation;
 	const compactedPresentation = await compactLargePresentationOutput({
 		artifactManifest,

package/extensions/agent-browser/lib/results/shared.ts

@@ -21,16 +21,24 @@ export interface AgentBrowserBatchResult {
 
 export type FileArtifactKind = "download" | "file" | "har" | "image" | "pdf" | "profile" | "trace" | "video";
 
+export type FileArtifactStatus = "missing" | "repaired-from-temp" | "saved" | "upstream-temp-only";
+
 export interface FileArtifactMetadata {
 	absolutePath: string;
+	artifactType?: FileArtifactKind;
 	command?: string;
+	cwd?: string;
 	exists?: boolean;
 	extension?: string;
 	kind: FileArtifactKind;
 	mediaType?: string;
 	path: string;
+	requestedPath?: string;
+	session?: string;
 	sizeBytes?: number;
+	status?: FileArtifactStatus;
 	subcommand?: string;
+	tempPath?: string;
 }
 
 export interface SavedFilePresentationDetails {
@@ -49,13 +57,16 @@ export interface SessionArtifactManifestEntry {
 	absolutePath?: string;
 	command?: string;
 	createdAtMs: number;
+	cwd?: string;
 	evictedAtMs?: number;
 	exists?: boolean;
 	extension?: string;
 	kind: FileArtifactKind | "spill";
 	mediaType?: string;
 	path: string;
+	requestedPath?: string;
 	retentionState: ArtifactRetentionState;
+	session?: string;
 	sizeBytes?: number;
 	storageScope: ArtifactStorageScope;
 	subcommand?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",