pi-agent-browser-native 0.2.22 → 0.2.24

package/docs/TOOL_CONTRACT.md

@@ -78,7 +78,7 @@ Examples:
 
 - type: `string`
 - optional
-- raw stdin for `eval --stdin` and `batch`
+- raw stdin for `eval --stdin`, `batch`, and `auth save --password-stdin`
 - rejected before launch for any other command/stdin combination, including commands such as `click`, `snapshot`, or `open`
 
 Examples:
@@ -91,6 +91,10 @@ Examples:
 { "args": ["batch"], "stdin": "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }
 ```
 
+```json
+{ "args": ["auth", "save", "my-login", "--password-stdin"], "stdin": "password from the user-approved secret source" }
+```
+
 ### `sessionMode`
 
 - type: `"auto" | "fresh"`
@@ -190,9 +194,12 @@ For oversized snapshots and other oversized tool outputs, details should switch
 
 "Rendering" here means how results appear inside `pi`, not embedding a browser UI.
 
+The TUI renderer is user-facing only. It may compact or colorize what the human sees in the Pi transcript, but it must not further truncate, summarize, or remove the model-facing `content` returned by the tool. Use the existing `details.fullOutputPath` / spill-file contracts for content that is too large for the model.
+
 Worth doing in v1:
 - 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
+- TUI display → custom `agent_browser` call/result rendering with colorized command/output text and a built-in-style collapsed view for long visible output; `ctrl+o` expansion reveals the full rendered tool result without changing the model-facing content
 - 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
@@ -222,7 +229,7 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - 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
 - if that unnamed fresh launch replaced an already-active managed session, best-effort close the old managed session after the switch succeeds
-- treat explicit caller-provided `--session` choices as user-managed
+- treat explicit caller-provided `--session` choices as user-managed; `--session` isolates a live browser session but is not a persisted tab/auth restore mechanism after `close`, so use `--profile`, `--session-name`, or `--state` when persisted auth/tab state is required
 - pass explicit `--profile` straight through to upstream `agent-browser`; no profile-cloning or isolation layer is added in v1
 <!-- agent-browser-playbook:start wrapper-tab-recovery -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->

package/extensions/agent-browser/index.ts

@@ -10,7 +10,15 @@ import { copyFile, mkdir, readFile, rm, stat } from "node:fs/promises";
 import { dirname, extname, isAbsolute, join, resolve } from "node:path";
 
 import { StringEnum } from "@earendil-works/pi-ai";
-import { isToolCallEventType, type AgentToolResult, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	highlightCode,
+	isToolCallEventType,
+	keyHint,
+	type AgentToolResult,
+	type ExtensionAPI,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import {
@@ -73,7 +81,7 @@ const AGENT_BROWSER_PARAMS = Type.Object({
 		description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators.",
 		minItems: 1,
 	}),
-	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content; only supported for batch and eval --stdin." })),
+	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content; only supported for batch, eval --stdin, and auth save --password-stdin." })),
 	sessionMode: Type.Optional(
 		StringEnum(["auto", "fresh"] as const, {
 			description:
@@ -97,6 +105,154 @@ function buildInvocationPreview(effectiveArgs: string[]): string {
 	return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
 }
 
+const TUI_COLLAPSED_OUTPUT_MAX_LINES = 10;
+const TUI_INVOCATION_PREVIEW_MAX_CHARS = 120;
+const ANSI_CONTROL_SEQUENCE_PATTERN = /\x1B(?:\][^\x07\x1B]*(?:\x07|\x1B\\)|\[[0-?]*[ -/]*[@-~]|P[^\x1B]*(?:\x1B\\)|_[^\x1B]*(?:\x1B\\)|\^[^\x1B]*(?:\x1B\\)|[@-Z\\-_])/g;
+const UNSAFE_DISPLAY_CONTROL_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\x80-\x9F]/g;
+
+function sanitizeDisplayText(text: string): string {
+	return text
+		.replace(ANSI_CONTROL_SEQUENCE_PATTERN, "")
+		.replace(/\r/g, "")
+		.replace(UNSAFE_DISPLAY_CONTROL_PATTERN, "�");
+}
+
+function replaceTabsForDisplay(text: string): string {
+	return text.replaceAll("\t", "    ");
+}
+
+function trimTrailingBlankLines(lines: string[]): string[] {
+	let end = lines.length;
+	while (end > 0 && lines[end - 1].trim().length === 0) {
+		end -= 1;
+	}
+	return lines.slice(0, end);
+}
+
+function isJsonDocumentText(text: string): boolean {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+		return false;
+	}
+	try {
+		JSON.parse(trimmed);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function getPrimaryTextContent(result: AgentToolResult<unknown>): string {
+	const textContent = result.content.find((item) => item.type === "text");
+	return textContent?.type === "text" ? textContent.text : "";
+}
+
+function colorizeToolOutputLines(text: string, theme: Theme, isError: boolean): string[] {
+	const normalizedLines = trimTrailingBlankLines(replaceTabsForDisplay(sanitizeDisplayText(text)).split("\n"));
+	const normalizedText = normalizedLines.join("\n");
+	if (normalizedText.length === 0) {
+		return [];
+	}
+	if (isJsonDocumentText(normalizedText)) {
+		return highlightCode(normalizedText, "json");
+	}
+	return normalizedLines.map((line) => {
+		if (line.length === 0) {
+			return "";
+		}
+		return isError ? theme.fg("error", line) : theme.fg("toolOutput", line);
+	});
+}
+
+function formatExpandHint(theme: Theme): string {
+	try {
+		return keyHint("app.tools.expand", "to expand");
+	} catch {
+		return `${theme.fg("dim", "ctrl+o")} ${theme.fg("muted", "to expand")}`;
+	}
+}
+
+function formatVisualTruncationNotice(remainingLines: number, totalLines: number, theme: Theme): string {
+	return `${theme.fg("muted", `... (${remainingLines} more lines, ${totalLines} total, `)}${formatExpandHint(theme)}${theme.fg("muted", ")")}`;
+}
+
+function formatAgentBrowserRenderCall(args: unknown, theme: Theme): string {
+	const input = isRecord(args) ? args : {};
+	const rawArgs = Array.isArray(input.args) ? input.args.filter((value): value is string => typeof value === "string") : [];
+	const redactedArgs = redactInvocationArgs(rawArgs);
+	const invocation = sanitizeDisplayText(redactedArgs.join(" ")).replace(/\s+/g, " ").trim();
+	const invocationPreview =
+		invocation.length > TUI_INVOCATION_PREVIEW_MAX_CHARS
+			? `${invocation.slice(0, TUI_INVOCATION_PREVIEW_MAX_CHARS - 3)}...`
+			: invocation;
+	let text = theme.fg("toolTitle", theme.bold("agent_browser"));
+	if (invocationPreview.length > 0) {
+		text += ` ${theme.fg("accent", invocationPreview)}`;
+	}
+	if (input.sessionMode === "fresh") {
+		text += theme.fg("dim", " sessionMode=fresh");
+	}
+	if (typeof input.stdin === "string") {
+		text += theme.fg("dim", " + stdin");
+	}
+	return text;
+}
+
+function formatAgentBrowserRenderResult(
+	result: AgentToolResult<unknown>,
+	options: { expanded: boolean; isPartial: boolean },
+	theme: Theme,
+	isError: boolean,
+): string {
+	if (options.isPartial) {
+		return theme.fg("warning", "Running agent-browser...");
+	}
+
+	const outputText = getPrimaryTextContent(result);
+	const outputLines = colorizeToolOutputLines(outputText, theme, isError);
+	if (outputLines.length === 0) {
+		const details = isRecord(result.details) ? result.details : undefined;
+		const rawSummary = typeof details?.summary === "string" ? details.summary : isError ? "agent-browser failed" : "Done";
+		const sanitizedSummary = sanitizeDisplayText(rawSummary).trim();
+		const summary = sanitizedSummary.length > 0 ? sanitizedSummary : isError ? "agent-browser failed" : "Done";
+		return isError ? theme.fg("error", summary) : theme.fg("success", summary);
+	}
+
+	return `\n${outputLines.join("\n")}`;
+}
+
+class AgentBrowserResultComponent {
+	private expanded = false;
+	private theme: Theme | undefined;
+	private readonly text = new Text("", 0, 0);
+
+	setState(value: string, expanded: boolean, theme: Theme): void {
+		this.text.setText(value);
+		this.expanded = expanded;
+		this.theme = theme;
+	}
+
+	render(width: number): string[] {
+		const lines = this.text.render(width);
+		if (this.expanded || lines.length <= TUI_COLLAPSED_OUTPUT_MAX_LINES) {
+			return lines;
+		}
+		const theme = this.theme;
+		if (!theme) {
+			return lines.slice(0, TUI_COLLAPSED_OUTPUT_MAX_LINES);
+		}
+		const hiddenLineCount = lines.length - TUI_COLLAPSED_OUTPUT_MAX_LINES;
+		return [
+			...lines.slice(0, TUI_COLLAPSED_OUTPUT_MAX_LINES),
+			formatVisualTruncationNotice(hiddenLineCount, lines.length, theme),
+		];
+	}
+
+	invalidate(): void {
+		this.text.invalidate();
+	}
+}
+
 function buildWrapperRecoveryHint(options: {
 	pinnedBatchUnwrapMode?: PinnedBatchUnwrapMode;
 	sessionTabCorrection?: OpenResultTabCorrection;
@@ -936,6 +1092,45 @@ function restoreArtifactManifestFromBranch(branch: unknown[]): SessionArtifactMa
 	return restoredManifest;
 }
 
+function isPasswordStdinAuthSave(options: { command?: string; commandTokens: string[] }): boolean {
+	return options.command === "auth" && options.commandTokens[1] === "save" && options.commandTokens.includes("--password-stdin");
+}
+
+function getExactSensitiveStdinValues(options: { command?: string; commandTokens: string[]; stdin?: string }): string[] {
+	if (options.stdin === undefined || !isPasswordStdinAuthSave(options)) {
+		return [];
+	}
+	return [...new Set([options.stdin, options.stdin.trimEnd(), options.stdin.trim()].filter((value) => value.length > 0))];
+}
+
+function redactExactSensitiveText(text: string, sensitiveValues: string[]): string {
+	let redacted = text;
+	for (const value of sensitiveValues) {
+		redacted = redacted.split(value).join("[REDACTED]");
+	}
+	return redacted;
+}
+
+function redactExactSensitiveValue(value: unknown, sensitiveValues: string[]): unknown {
+	if (sensitiveValues.length === 0) {
+		return value;
+	}
+	if (typeof value === "string") {
+		return redactExactSensitiveText(value, sensitiveValues);
+	}
+	if (Array.isArray(value)) {
+		return value.map((item) => redactExactSensitiveValue(item, sensitiveValues));
+	}
+	if (!isRecord(value)) {
+		return value;
+	}
+	return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [key, redactExactSensitiveValue(entryValue, sensitiveValues)]));
+}
+
+function redactToolDetails(details: Record<string, unknown>, sensitiveValues: string[]): Record<string, unknown> {
+	return redactSensitiveValue(redactExactSensitiveValue(details, sensitiveValues)) as Record<string, unknown>;
+}
+
 function validateStdinCommandContract(options: { command?: string; commandTokens: string[]; stdin?: string }): string | undefined {
 	if (options.stdin === undefined) {
 		return undefined;
@@ -946,8 +1141,11 @@ function validateStdinCommandContract(options: { command?: string; commandTokens
 	if (options.command === "eval" && options.commandTokens.includes("--stdin")) {
 		return undefined;
 	}
+	if (isPasswordStdinAuthSave(options)) {
+		return undefined;
+	}
 	const commandLabel = options.command ? `\`${options.command}\`` : "the requested command";
-	return `agent_browser stdin is only supported for \`batch\` and \`eval --stdin\`; remove stdin from ${commandLabel} or use one of those command forms.`;
+	return `agent_browser stdin is only supported for \`batch\`, \`eval --stdin\`, and \`auth save --password-stdin\`; remove stdin from ${commandLabel} or use one of those command forms.`;
 }
 
 function supportsPinnedStdinCommand(options: { command?: string; commandTokens: string[]; stdin?: string }): boolean {
@@ -1029,6 +1227,17 @@ function parseUserBatchStdin(stdin: string | undefined): { error?: string; steps
 	}
 }
 
+function getStaleRefArgs(commandTokens: string[], stdin?: string): string[] {
+	if (commandTokens[0] !== "batch" || stdin === undefined) {
+		return commandTokens;
+	}
+	const parsed = parseUserBatchStdin(stdin);
+	if (parsed.error || parsed.steps === undefined) {
+		return commandTokens;
+	}
+	return parsed.steps.flatMap((step) => step);
+}
+
 function buildPinnedBatchPlan(options: {
 	command?: string;
 	commandTokens: string[];
@@ -1293,6 +1502,7 @@ function getPersistentSessionArtifactStore(ctx: {
 
 async function preserveParseFailureOutput(options: {
 	artifactManifest?: SessionArtifactManifest;
+	exactSensitiveValues?: string[];
 	persistentArtifactStore?: PersistentSessionArtifactStore;
 	stdoutSpillPath?: string;
 }): Promise<{
@@ -1306,7 +1516,7 @@ async function preserveParseFailureOutput(options: {
 	}
 
 	try {
-		const rawOutput = await readFile(options.stdoutSpillPath);
+		const rawOutput = redactExactSensitiveText(await readFile(options.stdoutSpillPath, "utf8"), options.exactSensitiveValues ?? []);
 		const nowMs = Date.now();
 		let evictedArtifacts: PersistentSessionArtifactEviction[] = [];
 		let fullOutputPath: string;
@@ -1500,6 +1710,18 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 			"Browse websites, read live docs, click and fill pages, extract browser content, take screenshots, and automate real web workflows.",
 		promptGuidelines: toolPromptGuidelines,
 		parameters: AGENT_BROWSER_PARAMS,
+		renderCall(args, theme, context) {
+			const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+			text.setText(formatAgentBrowserRenderCall(args, theme));
+			return text;
+		},
+		renderResult(result, options, theme, context) {
+			const component = context.lastComponent instanceof AgentBrowserResultComponent
+				? context.lastComponent
+				: new AgentBrowserResultComponent();
+			component.setState(formatAgentBrowserRenderResult(result, options, theme, context.isError), options.expanded, theme);
+			return component;
+		},
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const redactedArgs = redactInvocationArgs(params.args);
 			const validationError = validateToolArgs(params.args) ?? getBatchAnnotateValidationError(params.args, params.stdin);
@@ -1546,6 +1768,11 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				}
 
 				const commandTokens = extractCommandTokens(preparedArgs.args);
+				const exactSensitiveValues = getExactSensitiveStdinValues({
+					command: executionPlan.commandInfo.command,
+					commandTokens,
+					stdin: params.stdin,
+				});
 				const traceOwnerGuardMessage = getTraceOwnerGuardMessage({
 					command: executionPlan.commandInfo.command,
 					sessionName: executionPlan.sessionName,
@@ -1755,9 +1982,13 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					presentationEnvelope = repairedBatchScreenshots.envelope;
 					const screenshotArtifactRequest = repairedScreenshot.request;
 					const batchScreenshotArtifactRequests = repairedBatchScreenshots.requests;
+					if (presentationEnvelope && exactSensitiveValues.length > 0) {
+						presentationEnvelope = redactExactSensitiveValue(presentationEnvelope, exactSensitiveValues) as AgentBrowserEnvelope;
+					}
 					const parseFailureOutput = parseError
 						? await preserveParseFailureOutput({
 								artifactManifest,
+								exactSensitiveValues,
 								persistentArtifactStore,
 								stdoutSpillPath: processResult.stdoutSpillPath,
 							})
@@ -1934,6 +2165,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						exitCode: processResult.exitCode,
 						parseError,
 						plainTextInspection,
+						staleRefArgs: getStaleRefArgs(commandTokens, params.stdin),
 						spawnError: processResult.spawnError,
 						stderr: processResult.stderr,
 						timedOut: processResult.timedOut,
@@ -2009,54 +2241,55 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							contentWithSessionWarnings.unshift({ type: "text", text: warningText });
 						}
 					}
-					const redactedContent = contentWithSessionWarnings.map((item) =>
-						item.type === "text" && !(userRequestedJson && !plainTextInspection) ? { ...item, text: redactSensitiveText(item.text) } : item,
-					);
+					const redactedContent = contentWithSessionWarnings.map((item) => {
+						if (item.type !== "text") return item;
+						const exactRedactedText = redactExactSensitiveText(item.text, exactSensitiveValues);
+						return userRequestedJson && !plainTextInspection
+							? { ...item, text: exactRedactedText }
+							: { ...item, text: redactSensitiveText(exactRedactedText) };
+					});
+					const details = {
+						args: redactedArgs,
+						artifactManifest: presentation.artifactManifest,
+						artifactRetentionSummary: presentation.artifactRetentionSummary,
+						artifacts: presentation.artifacts,
+						batchFailure: presentation.batchFailure,
+						batchSteps: presentation.batchSteps,
+						command: executionPlan.commandInfo.command,
+						compatibilityWorkaround,
+						subcommand: executionPlan.commandInfo.subcommand,
+						data: presentation.data,
+						error: plainTextInspection ? undefined : presentationEnvelope?.error,
+						inspection: plainTextInspection || undefined,
+						navigationSummary,
+						aboutBlankSessionMismatch,
+						openResultTabCorrection,
+						effectiveArgs: redactedProcessArgs,
+						exitCode: processResult.exitCode,
+						fullOutputPath: parseFailureOutput.fullOutputPath ?? presentation.fullOutputPath,
+						fullOutputPaths: presentation.fullOutputPaths,
+						fullOutputUnavailable: parseFailureOutput.fullOutputUnavailable,
+						imagePath: presentation.imagePath,
+						imagePaths: presentation.imagePaths,
+						parseError: plainTextInspection ? undefined : parseError,
+						savedFile: presentation.savedFile,
+						savedFilePath: presentation.savedFilePath,
+						sessionMode,
+						sessionTabCorrection,
+						sessionTabTarget: currentSessionTabTarget,
+						...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+						sessionRecoveryHint: redactedRecoveryHint,
+						startupScopedFlags: executionPlan.startupScopedFlags,
+						stderr: processResult.stderr,
+						stdout: plainTextInspection ? inspectionText ?? "" : parseSucceeded ? undefined : processResult.stdout,
+						summary: presentation.summary,
+						timedOut: processResult.timedOut || undefined,
+						timeoutMs: processResult.timeoutMs,
+					};
 
 					return {
 						content: redactedContent,
-						details: {
-							args: redactedArgs,
-							artifactManifest: redactSensitiveValue(presentation.artifactManifest),
-							artifactRetentionSummary: presentation.artifactRetentionSummary,
-							artifacts: redactSensitiveValue(presentation.artifacts),
-							batchFailure: redactSensitiveValue(presentation.batchFailure),
-							batchSteps: redactSensitiveValue(presentation.batchSteps),
-							command: executionPlan.commandInfo.command,
-							compatibilityWorkaround,
-							subcommand: executionPlan.commandInfo.subcommand,
-							data: redactSensitiveValue(presentation.data),
-							error: plainTextInspection ? undefined : redactSensitiveValue(presentationEnvelope?.error),
-							inspection: plainTextInspection || undefined,
-							navigationSummary: redactSensitiveValue(navigationSummary),
-							aboutBlankSessionMismatch: redactSensitiveValue(aboutBlankSessionMismatch),
-							openResultTabCorrection: redactSensitiveValue(openResultTabCorrection),
-							effectiveArgs: redactedProcessArgs,
-							exitCode: processResult.exitCode,
-							fullOutputPath: parseFailureOutput.fullOutputPath ?? presentation.fullOutputPath,
-							fullOutputPaths: presentation.fullOutputPaths,
-							fullOutputUnavailable: parseFailureOutput.fullOutputUnavailable,
-							imagePath: presentation.imagePath,
-							imagePaths: presentation.imagePaths,
-							parseError: plainTextInspection ? undefined : parseError,
-							savedFile: redactSensitiveValue(presentation.savedFile),
-							savedFilePath: presentation.savedFilePath ? redactSensitiveText(presentation.savedFilePath) : undefined,
-							sessionMode,
-							sessionTabCorrection: redactSensitiveValue(sessionTabCorrection),
-							sessionTabTarget: redactSensitiveValue(currentSessionTabTarget),
-							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
-							sessionRecoveryHint: redactedRecoveryHint,
-							startupScopedFlags: executionPlan.startupScopedFlags,
-							stderr: processResult.stderr ? redactSensitiveText(processResult.stderr) : undefined,
-							stdout: plainTextInspection
-								? redactSensitiveText(inspectionText ?? "")
-								: parseSucceeded
-									? undefined
-									: redactSensitiveText(processResult.stdout),
-							summary: redactSensitiveText(presentation.summary),
-							timedOut: processResult.timedOut || undefined,
-							timeoutMs: processResult.timeoutMs,
-						},
+						details: redactToolDetails(details, exactSensitiveValues),
 						isError: !succeeded,
 					};
 				} finally {

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

@@ -3,7 +3,7 @@
  * Responsibilities: Define stable guidance bullets, native tool-call examples, and wrapper-behavior notes without importing runtime/browser process code.
  * Scope: Agent-facing documentation and prompt-guidance text only; command execution and wrapper state behavior live in runtime modules.
  * Usage: Imported by the extension entrypoint for promptGuidelines and by the documentation drift-check script for generated Markdown blocks.
- * Invariants/Assumptions: The native pi tool receives args after the agent-browser binary, stdin is only for batch/eval --stdin, and wrapper behavior documented here must match implemented behavior.
+ * Invariants/Assumptions: The native pi tool receives args after the agent-browser binary, stdin is only for batch/eval --stdin/auth save --password-stdin, and wrapper behavior documented here must match implemented behavior.
  */
 
 export const PROJECT_RULE_PROMPT =
@@ -14,9 +14,9 @@ export const TOOL_PROMPT_GUIDELINES_PREFIX = [
 ] as const;
 
 export const QUICK_START_GUIDELINES = [
-	"Quick start mental model: args are the exact agent-browser CLI args after the binary; stdin is only for batch and eval --stdin, and other command/stdin combinations are rejected before launch; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable state.",
+	"Quick start mental model: args are the exact agent-browser CLI args after the binary; stdin is only for batch, eval --stdin, and auth save --password-stdin, and other command/stdin combinations are rejected before launch; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable state.",
 	"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\" }, { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }, and { args: [\"open\", \"--enable\", \"react-devtools\", \"https://example.com\"], sessionMode: \"fresh\" }.",
+	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, { args: [\"auth\", \"save\", \"name\", \"--password-stdin\"], stdin: \"<password from user-approved secret source>\" }, { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }, and { args: [\"open\", \"--enable\", \"react-devtools\", \"https://example.com\"], 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; react tree/inspect/renders/suspense introspect React after --enable react-devtools; vitals [url] measures Core Web Vitals; pushstate <url> performs SPA navigation.",
 	"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;
@@ -47,7 +47,7 @@ export const TOOL_PROMPT_GUIDELINES_SUFFIX = [
 	"Prefer agent_browser over bash for opening sites, reading docs on the web, clicking, filling, screenshots, eval, and batch workflows.",
 	"Do not fall back to osascript, AppleScript, or generic browser-driving bash commands when agent_browser can do the job.",
 	"Pass exact agent-browser CLI arguments in args, excluding the binary name.",
-	"Use stdin only for eval --stdin and batch instead of shell heredocs; other command/stdin combinations are rejected before launch.",
+	"Use stdin only for eval --stdin, batch, and auth save --password-stdin instead of shell heredocs or password args; other command/stdin combinations are rejected before launch.",
 	"Let the extension-managed session handle the common path unless you explicitly need a fresh launch for upstream flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable.",
 	"Use sessionMode=fresh when switching from an existing implicit session to a new profile/debug/init-script launch without inventing a fixed explicit session name; later auto calls will follow that new session.",
 ] as const;

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

@@ -135,6 +135,17 @@ function buildUpstreamIpcReadTimeoutMessage(): string {
 	].join(" ");
 }
 
+function maybeAppendStaleRefHint(message: string, args?: string[]): string {
+	const usedRef = args?.some((arg) => /^@e\d+\b/.test(arg)) ?? false;
+	if (!usedRef || !/could not locate element|element not found|no element/i.test(message)) {
+		return message;
+	}
+	return [
+		message,
+		"This @ref may be stale after navigation, scrolling, or a DOM update. Run `agent_browser` with `{ \"args\": [\"snapshot\", \"-i\"] }` again and retry with a current ref, or use a stable `find` locator.",
+	].join("\n");
+}
+
 export function getAgentBrowserErrorText(options: {
 	aborted: boolean;
 	command?: string;
@@ -144,6 +155,7 @@ export function getAgentBrowserErrorText(options: {
 	parseError?: string;
 	plainTextInspection: boolean;
 	spawnError?: Error;
+	staleRefArgs?: string[];
 	stderr: string;
 	timedOut?: boolean;
 	timeoutMs?: number;
@@ -163,7 +175,8 @@ export function getAgentBrowserErrorText(options: {
 		if (envelopeErrorText && isUpstreamIpcReadTimeoutMessage(envelopeErrorText)) {
 			return buildUpstreamIpcReadTimeoutMessage();
 		}
-		return envelopeErrorText ?? (stderr.trim() || buildFailureFallback(options));
+		const fallback = envelopeErrorText ?? (stderr.trim() || buildFailureFallback(options));
+		return maybeAppendStaleRefHint(fallback, options.staleRefArgs ?? options.effectiveArgs);
 	}
 	if (exitCode !== 0) {
 		return stderr.trim() || buildExitCodeFallback(options);

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

@@ -349,6 +349,9 @@ function splitShellWords(input: string): string[] | undefined {
 			current += input[index];
 			continue;
 		}
+		if (char === "#" && current.length === 0) {
+			break;
+		}
 		if (/\s/.test(char)) {
 			if (current.length > 0) {
 				words.push(current);
@@ -384,7 +387,7 @@ function formatNativeSkillContent(content: string): string {
 		const heredocMatch = /^(.*?)\s+(<<-?)['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?\s*$/.exec(rawArgsText);
 		const argsText = heredocMatch?.[1] ?? rawArgsText;
 		const args = splitShellWords(argsText);
-		if (!args) {
+		if (!args || args.length === 0) {
 			output.push(line);
 			continue;
 		}
@@ -419,7 +422,7 @@ function formatSkillsText(commandInfo: CommandInfo, data: unknown): string | und
 	if (content) {
 		const note = [
 			"Pi native-tool note: upstream skill text was adapted for this native tool.",
-			"Use args for CLI tokens and stdin only for batch or eval --stdin; do not pipe heredocs through bash unless the user explicitly asks for a bash workflow.",
+			"Use args for CLI tokens and stdin only for batch, eval --stdin, or auth save --password-stdin; do not pipe heredocs through bash unless the user explicitly asks for a bash workflow.",
 		].join("\n");
 		return `${note}\n\n${redactModelFacingText(formatNativeSkillContent(content))}`;
 	}