@f5-sales-demo/xcsh 19.98.6 → 19.98.8

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.98.6",
+	"version": "19.98.8",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -57,13 +57,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.98.6",
-		"@f5-sales-demo/pi-agent-core": "19.98.6",
-		"@f5-sales-demo/pi-ai": "19.98.6",
-		"@f5-sales-demo/pi-natives": "19.98.6",
-		"@f5-sales-demo/pi-resource-management": "19.98.6",
-		"@f5-sales-demo/pi-tui": "19.98.6",
-		"@f5-sales-demo/pi-utils": "19.98.6",
+		"@f5-sales-demo/xcsh-stats": "19.98.8",
+		"@f5-sales-demo/pi-agent-core": "19.98.8",
+		"@f5-sales-demo/pi-ai": "19.98.8",
+		"@f5-sales-demo/pi-natives": "19.98.8",
+		"@f5-sales-demo/pi-resource-management": "19.98.8",
+		"@f5-sales-demo/pi-tui": "19.98.8",
+		"@f5-sales-demo/pi-utils": "19.98.8",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",
@@ -74,7 +74,7 @@
 		"linkedom": "^0.18",
 		"lru-cache": "11.5.2",
 		"markit-ai": "0.5.3",
-		"puppeteer": "^24.37",
+		"puppeteer": "^25.3",
 		"yaml": "2.9.0",
 		"zod": "4.4.3"
 	},

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.98.6",
-	"commit": "9a4b5f250189b2d423b62f15f02c2403c070fb3d",
-	"shortCommit": "9a4b5f2",
+	"version": "19.98.8",
+	"commit": "8d1e4f3e9673585d8835fd45b7b6eb7c0f21b529",
+	"shortCommit": "8d1e4f3",
 	"branch": "main",
-	"tag": "v19.98.6",
-	"commitDate": "2026-07-28T11:16:35Z",
-	"buildDate": "2026-07-28T11:40:19.737Z",
+	"tag": "v19.98.8",
+	"commitDate": "2026-07-28T13:27:14Z",
+	"buildDate": "2026-07-28T13:48:35.687Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/9a4b5f250189b2d423b62f15f02c2403c070fb3d",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.98.6"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/8d1e4f3e9673585d8835fd45b7b6eb7c0f21b529",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.98.8"
 };

package/src/sandbox/enforce.ts

@@ -18,8 +18,8 @@
  * for both bash and python.
  */
 import * as path from "node:path";
-import { parseFindPattern, parseSearchPath, resolveToCwd, splitTopLevel } from "../tools/path-utils";
-import { lexShellCommand } from "../tools/shell-lex";
+import { expandPath, parseFindPattern, parseSearchPath, resolveToCwd, splitTopLevel } from "../tools/path-utils";
+import { lexShellCommand, type ShellSimpleCommand } from "../tools/shell-lex";
 import { provenExemptWords } from "./command-operands";
 import type { SandboxAccess, SandboxPolicy } from "./policy";
 
@@ -194,6 +194,12 @@ function operandAccess(operator: string): SandboxAccess | "skip" {
 interface PathCandidate {
 	token: string;
 	access: SandboxAccess;
+	/**
+	 * A directory the shell is about to move into. It must clear both boundaries on its own merits,
+	 * and the system-root read exemption does not apply: `/usr` being readable is no reason to let
+	 * the working directory — and with it every unchecked relative path — move there.
+	 */
+	mustBeInTree?: boolean;
 }
 
 /** Write first, so a `<>` denial names the stricter boundary the caller is most likely missing. */
@@ -205,6 +211,9 @@ const REDIRECT_OPERATOR = /[0-9]*(?:&>>|&>|<<<|<<-|<<|>>|>\||<>|>&|<&|>|<)/g;
 /** A whitespace token that is only a redirection operator, so the next token is its operand. */
 const BARE_REDIRECT = /^[0-9]*(?:&>>|&>|<<<|<<-|<<|>>|>\||<>|>&|<&|>|<)$/;
 
+/** Where a shell word ends inside a whitespace token: an operator, separator, or grouping. */
+const METACHARACTER = /[;&|<>()]/;
+
 /**
  * A path glued to its option, as one shell word (#2524).
  *
@@ -267,7 +276,17 @@ function codePathOccurrences(command: string): PathOccurrence[] {
 			const access = operandAccess(operator[0]);
 			if (access === "skip") continue;
 			const from = operator.index + operator[0].length;
-			add(stripped.slice(from).replace(/^["']|["']$/g, ""), match.index + openingQuote + from, access);
+			// The operand ends at the first shell metacharacter, not at the end of the whitespace
+			// token. `>/dev/null; echo x` is one token, and taking all of it produced the "path"
+			// `/dev/null;`, which matched no write sink and refused a completely ordinary command
+			// (#2540). Truncating only ever shortens a candidate, so nothing blocked becomes allowed.
+			const rest = stripped.slice(from);
+			const stop = rest.search(METACHARACTER);
+			add(
+				(stop === -1 ? rest : rest.slice(0, stop)).replace(/^["']|["']$/g, ""),
+				match.index + openingQuote + from,
+				access,
+			);
 		}
 
 		// An option glued to its value is one word too, and the lexer cannot help: it
@@ -323,13 +342,22 @@ function codePathCandidates(command: string): PathCandidate[] {
  * confidently, the floor stands alone.
  */
 /**
- * A redirect target the shell will certainly open, whose path cannot be resolved here —
- * `printf x >"$TARGET"`. Unlike an operand, there is no reading under which this is data
- * rather than a file, so it cannot be waved through (#2534).
+ * Something the shell will act on whose path this layer cannot resolve — `cd "$DEST"`.
+ *
+ * Refusal is justified here and *not* for a redirect target, which is the asymmetry worth stating: a
+ * redirect target that escapes damages one file, while a directory change silently relocates every
+ * later relative path in the session, and relative paths are never candidates at all. So an
+ * unresolvable `cd` fails closed, and an unresolvable `> "$LOG"` does not.
+ *
+ * The reverse was tried (#2552) and refused `make > "$LOG"`, `> "$TMPDIR/f"` and `> out-$$.txt` —
+ * ordinary shell, writing in-tree. Narrowing it is not possible either: a variable's *value* can
+ * contain `../`, so `> "out-$X"` escapes while looking relative. Resolving that needs the expansion,
+ * which only the shell has — Phase 2 (#2554).
  */
 interface UnresolvableTarget {
 	text: string;
-	access: SandboxAccess;
+	/** What the shell was about to do, for a message that names the actual problem. */
+	what: "directory change";
 }
 
 interface ShellScan {
@@ -337,6 +365,116 @@ interface ShellScan {
 	unresolvable: UnresolvableTarget[];
 }
 
+/**
+ * Why a directory change was refused. Distinct from `describe` because the remedy differs: the path
+ * may well be readable, and the problem is that standing there redefines every relative path the
+ * boundary trusts to stay in the tree.
+ */
+function describeDirectoryChange(policy: SandboxPolicy, target?: string, unresolved?: string): string {
+	const what =
+		target === undefined
+			? `a directory this check cannot resolve from the command text (${unresolved})`
+			: `${target}, which is outside it`;
+	return `Refusing to change the working directory to ${what} (session directory: ${policy.cwd}). Relative paths are trusted to stay inside the session tree, so moving out of it would silently take every later path with it. Use an absolute path, or --allow-path to widen the boundary first.`;
+}
+
+/** Builtins that move the shell, and therefore move what every later relative path means. */
+const DIRECTORY_CHANGE = new Set(["cd", "pushd"]);
+
+/** `cd`'s own options. All boolean, so the target is the first non-option operand. */
+const DIRECTORY_CHANGE_OPTIONS = new Set(["-L", "-P", "-e", "-@"]);
+
+/**
+ * Commands whose operand is a script the shell will run. The lexer hands the script over as one
+ * word, so a directory change inside it is invisible unless that word is lexed in turn.
+ */
+const SCRIPT_RUNNERS = new Set(["sh", "bash", "zsh", "dash", "ksh", "eval"]);
+
+/**
+ * Prefixes that run the *following words* as a command rather than a script string. `command` is
+ * already unwrapped by the lexer; `builtin` is not, and `builtin cd /` would otherwise sail past a
+ * gate that only looks at `name`.
+ */
+const COMMAND_PREFIXES = new Set(["builtin"]);
+
+/** Cheap pre-filter: only lex a script operand that could contain a directory change at all. */
+const DIRECTORY_CHANGE_TOKEN = /(^|[\s;&|(])(cd|pushd)([\s;&|)]|$)/;
+
+/**
+ * Targets of a directory change: a candidate that must resolve in-tree, or the raw text when it
+ * cannot be resolved at all.
+ *
+ * This gate exists because a relative operand is never a candidate — the floor assumes it resolves
+ * under the session directory. `cd` is what breaks that assumption: the bash tool runs one
+ * persistent brush-core shell in the agent's own process, so a directory change outlives the call
+ * that made it and afterwards `cat tmp/x` reads somewhere else entirely (#2542).
+ *
+ * It is defence-in-depth, not a boundary. Verified still open: `c=cd; $c /`, `alias g=cd; g /`, and
+ * a symlink created in the same command (#2553). Those need the shell's own resolution, which is
+ * Phase 2 (#2554). Do not add a seventh spelling here — two adversarial rounds produced six.
+ */
+function directoryChangeTargets(commands: readonly ShellSimpleCommand[], depth = 0): (PathCandidate | string)[] {
+	const targets: (PathCandidate | string)[] = [];
+
+	for (const command of commands) {
+		if (command.name === undefined) continue;
+		let name = command.name;
+		let operands = command.words.slice(command.operandStart).filter(word => word.redirect === undefined);
+		// `builtin cd sub` is a `cd`; unwrap the prefix before deciding anything.
+		while (COMMAND_PREFIXES.has(name) && operands.length > 0 && operands[0].literal) {
+			name = operands[0].text;
+			operands = operands.slice(1);
+		}
+
+		// A script operand is text the shell will run, so lex it and gate what it contains. `eval
+		// 'cd /'` and `sh -c '…'` both arrive here. One level is enough for every real spelling;
+		// deeper nesting is unprovable.
+		if (SCRIPT_RUNNERS.has(name)) {
+			for (const operand of operands) {
+				if (!operand.literal) {
+					targets.push(operand.text); // `eval "$cmd"` — nothing to read
+					continue;
+				}
+				if (!DIRECTORY_CHANGE_TOKEN.test(operand.text)) continue;
+				if (depth > 0) {
+					targets.push(operand.text);
+					continue;
+				}
+				const inner = lexShellCommand(operand.text);
+				if (inner.unterminated) targets.push(operand.text);
+				else targets.push(...directoryChangeTargets(inner.commands, depth + 1));
+			}
+			continue;
+		}
+
+		if (!DIRECTORY_CHANGE.has(name)) continue;
+
+		// Options precede the target and are all boolean. One the model does not recognise means the
+		// target cannot be located, so the proof fails rather than guessing which operand it is.
+		let index = 0;
+		let unparseable = false;
+		while (index < operands.length && operands[index].text.startsWith("-") && operands[index].text !== "-") {
+			if (!DIRECTORY_CHANGE_OPTIONS.has(operands[index].text)) {
+				unparseable = true;
+				break;
+			}
+			index++;
+		}
+		if (unparseable) {
+			targets.push(operands.map(word => word.text).join(" "));
+			continue;
+		}
+
+		const target = operands[index];
+		// `cd` with no operand goes to $HOME; `cd -` returns somewhere only the shell remembers; a
+		// non-literal target cannot be resolved from text.
+		if (target === undefined) targets.push(`${name} (no target: goes to $HOME)`);
+		else if (!target.literal || target.text === "-") targets.push(target.text);
+		else targets.push({ token: target.text, access: "read", mustBeInTree: true });
+	}
+	return targets;
+}
+
 function shellPathCandidates(command: string): ShellScan {
 	const lexed = lexShellCommand(command);
 	// Unbalanced quotes mean every word boundary is a guess: neither the blanking nor the write
@@ -366,18 +504,21 @@ function shellPathCandidates(command: string): ShellScan {
 	// Not gated on `looksLikePath`: that test is for the floor's *guesses* about which fragments of a
 	// command might be filenames. A redirect target is one the shell will certainly open, so a bare
 	// `out.txt` is checked too — it resolves under the cwd, which a read-only cwd does not license.
-	const unresolvable: UnresolvableTarget[] = [];
 	for (const word of lexed.words) {
 		if (word.redirect === undefined || word.redirect === "here-string") continue;
 		for (const access of word.redirect === "read-write" ? WRITE_AND_READ : [word.redirect]) {
-			// `literal` is false when the word carries `$VAR`, a substitution, a glob or a brace
-			// expansion, so `text` is not a stand-in for one filesystem reference. Resolving it
-			// anyway is what let `>"$TARGET"` through: it became the literal string `$TARGET`
-			// under the cwd, which the boundary happily allowed.
+			// A non-literal target — `$VAR`, a substitution, a glob — is not checked. `text` is not a
+			// stand-in for one filesystem reference, and refusing on that basis rejected ordinary
+			// in-tree shell (see UnresolvableTarget). Resolving it is Phase 2's job.
 			if (word.literal) candidates.push({ token: word.text, access });
-			else unresolvable.push({ text: word.text, access });
 		}
 	}
+
+	const unresolvable: UnresolvableTarget[] = [];
+	for (const target of directoryChangeTargets(lexed.commands)) {
+		if (typeof target === "string") unresolvable.push({ text: target, what: "directory change" });
+		else candidates.push(target);
+	}
 	return { candidates, unresolvable };
 }
 
@@ -402,7 +543,12 @@ function evaluateCodeTool(check: ToolCallCheck, fields: string[], shell: boolean
 
 	const rawCwd = typeof input.cwd === "string" ? input.cwd : undefined;
 	const base = rawCwd ? resolveToCwd(rawCwd, cwd) : cwd;
-	if (rawCwd && !policy.isAllowed(base, "read")) return deny(policy, base, "read");
+	// Both boundaries, for the same reason a `cd` target needs both: relative paths are never
+	// scanned, so wherever the command runs is somewhere it can write freely. Read alone let
+	// `{ cwd: "/shared/ctx", command: "touch notes.md" }` write into a read-only root.
+	if (rawCwd && !(policy.isAllowed(base, "read") && policy.isAllowed(base, "write"))) {
+		return { block: true, reason: describeDirectoryChange(policy, base) };
+	}
 
 	const commands: string[] = [];
 	for (const field of fields) {
@@ -429,17 +575,19 @@ function evaluateCodeTool(check: ToolCallCheck, fields: string[], shell: boolean
 		// at this layer at all. That is the Phase 2 OS-sandbox's job; do not read the text
 		// boundary as complete (#2534).
 		for (const target of scan.unresolvable) {
-			return {
-				block: true,
-				reason:
-					`sandbox: refusing to ${target.access} a redirect target this layer cannot resolve: ` +
-					`${target.text}. The shell will open it, but its path comes from an expansion, so the ` +
-					"boundary cannot be checked. Write to an explicit path, or use --allow-path.",
-			};
+			return { block: true, reason: describeDirectoryChange(policy, undefined, target.text) };
 		}
 		const seen = new Set<string>();
-		for (const { token, access } of scan.candidates) {
-			if (!seen.add(`${access}\0${token}`)) continue;
+		for (const { token, access, mustBeInTree } of scan.candidates) {
+			if (!seen.add(`${access}\0${mustBeInTree ? "cd\0" : ""}${token}`)) continue;
+			if (mustBeInTree) {
+				// `path.resolve`, not `resolveToCwd`: the latter maps an all-slashes path to the cwd,
+				// which would read `cd /` as `cd .` and let the shell walk out. Both boundaries,
+				// because relative paths go unchecked wherever the shell is standing.
+				const moved = path.resolve(base, expandPath(token));
+				if (policy.isAllowed(moved, "read") && policy.isAllowed(moved, "write")) continue;
+				return { block: true, reason: describeDirectoryChange(policy, moved) };
+			}
 			const resolved = resolveToCwd(token, base);
 			if (policy.isAllowed(resolved, access)) continue;
 			// SYSTEM_READ_ROOTS is a read allowance — "directories a subprocess may legitimately

package/src/tools/browser-stealth.ts

@@ -0,0 +1,121 @@
+/**
+ * Assembles the stealth init script injected into every page.
+ *
+ * Split out of `browser.ts` so the bundle can be built and asserted without a
+ * `BrowserTool` instance — see `test/browser/stealth-bundle.test.ts` (CI) and
+ * `test/e2e/stealth-surfaces.e2e.test.ts` (local, real Chrome).
+ */
+
+import stealthTamperingScript from "./puppeteer/00_stealth_tampering.txt" with { type: "text" };
+import stealthActivityScript from "./puppeteer/01_stealth_activity.txt" with { type: "text" };
+import stealthHairlineScript from "./puppeteer/02_stealth_hairline.txt" with { type: "text" };
+import stealthBotdScript from "./puppeteer/03_stealth_botd.txt" with { type: "text" };
+import stealthIframeScript from "./puppeteer/04_stealth_iframe.txt" with { type: "text" };
+import stealthWebglScript from "./puppeteer/05_stealth_webgl.txt" with { type: "text" };
+import stealthScreenScript from "./puppeteer/06_stealth_screen.txt" with { type: "text" };
+import stealthFontsScript from "./puppeteer/07_stealth_fonts.txt" with { type: "text" };
+import stealthAudioScript from "./puppeteer/08_stealth_audio.txt" with { type: "text" };
+import stealthLocaleScript from "./puppeteer/09_stealth_locale.txt" with { type: "text" };
+import stealthPluginsScript from "./puppeteer/10_stealth_plugins.txt" with { type: "text" };
+import stealthHardwareScript from "./puppeteer/11_stealth_hardware.txt" with { type: "text" };
+import stealthCodecsScript from "./puppeteer/12_stealth_codecs.txt" with { type: "text" };
+import stealthWorkerScript from "./puppeteer/13_stealth_worker.txt" with { type: "text" };
+
+/**
+ * The injected surfaces, in load order. Order is load-bearing: `tampering` must
+ * run first so later scripts' patched functions are already covered by its
+ * `Function.prototype.toString` shim.
+ */
+export const STEALTH_SCRIPTS: ReadonlyArray<{ readonly name: string; readonly source: string }> = [
+	{ name: "tampering", source: stealthTamperingScript },
+	{ name: "activity", source: stealthActivityScript },
+	{ name: "hairline", source: stealthHairlineScript },
+	{ name: "botd", source: stealthBotdScript },
+	{ name: "iframe", source: stealthIframeScript },
+	{ name: "webgl", source: stealthWebglScript },
+	{ name: "screen", source: stealthScreenScript },
+	{ name: "fonts", source: stealthFontsScript },
+	{ name: "audio", source: stealthAudioScript },
+	{ name: "locale", source: stealthLocaleScript },
+	{ name: "plugins", source: stealthPluginsScript },
+	{ name: "hardware", source: stealthHardwareScript },
+	{ name: "codecs", source: stealthCodecsScript },
+	{ name: "worker", source: stealthWorkerScript },
+];
+
+export type StealthBundleOptions = {
+	/**
+	 * Name of a global to collect per-script failures into, as
+	 * `[{ name, message }]`. Omit in production: each script is wrapped in its
+	 * own try/catch so one failure cannot take down the rest, but recording those
+	 * failures means writing a `window.<name>` that a detection script could look
+	 * for — which would defeat the point of the bundle. Tests pass a name so a
+	 * silently-broken script is assertable instead of invisible.
+	 */
+	readonly errorSink?: string;
+};
+
+/** Wraps one script so a failure cannot stop the scripts after it. */
+function wrapScript(script: { name: string; source: string }, errorSink: string | undefined): string {
+	const record = errorSink
+		? `(globalThis[${JSON.stringify(errorSink)}] ||= []).push({ name: ${JSON.stringify(script.name)}, message: String(e && e.message || e) });`
+		: "";
+	return `
+		try {
+			${script.source};
+		} catch (e) { ${record} }
+	`;
+}
+
+/**
+ * Builds the full init script.
+ *
+ * Caches pristine builtins up front so the surfaces can still reach unpatched
+ * references after earlier surfaces have replaced the page's own.
+ *
+ * The cache is taken from the CURRENT realm, not a detached iframe. This script
+ * is injected via `Page.addScriptToEvaluateOnNewDocument`, which runs before any
+ * page script — and before any DOM at all: at that point `document.readyState`
+ * is `"loading"` and `document.head`, `document.body` and
+ * `document.documentElement` are all null. An earlier version created a helper
+ * iframe and appended it to `document.head`, which threw on that first statement
+ * outside every per-surface guard, so all fourteen surfaces silently never ran.
+ * Because nothing else has executed yet, `globalThis`'s builtins are themselves
+ * still pristine, which is exactly what the iframe was there to provide.
+ */
+export function buildStealthBundle(options: StealthBundleOptions = {}): string {
+	const joint = STEALTH_SCRIPTS.map(script => wrapScript(script, options.errorSink)).join(";\n");
+
+	return `(() => {
+			// Native function cache — this script runs first, so the current realm's
+			// builtins have not been touched yet.
+			const nativeWindow = globalThis;
+
+			// Cache pristine native functions
+			const Function_toString = nativeWindow.Function.prototype.toString;
+			const Object_getOwnPropertyDescriptor = nativeWindow.Object.getOwnPropertyDescriptor;
+			const Object_getOwnPropertyDescriptors = nativeWindow.Object.getOwnPropertyDescriptors;
+			const Object_getPrototypeOf = nativeWindow.Object.getPrototypeOf;
+			const Object_defineProperty = nativeWindow.Object.defineProperty;
+			const Object_getOwnPropertyDescriptorOriginal = nativeWindow.Object.getOwnPropertyDescriptor;
+			const Object_create = nativeWindow.Object.create;
+			const Object_keys = nativeWindow.Object.keys;
+			const Object_getOwnPropertyNames = nativeWindow.Object.getOwnPropertyNames;
+			const Object_entries = nativeWindow.Object.entries;
+			const Object_setPrototypeOf = nativeWindow.Object.setPrototypeOf;
+			const Object_assign = nativeWindow.Object.assign;
+			const Window_setTimeout = nativeWindow.setTimeout;
+			const Math_random = nativeWindow.Math.random;
+			const Math_floor = nativeWindow.Math.floor;
+			const Math_max = nativeWindow.Math.max;
+			const Math_min = nativeWindow.Math.min;
+			const Window_Event = nativeWindow.Event;
+			const Promise_resolve = nativeWindow.Promise.resolve.bind(nativeWindow.Promise);
+			const Window_Blob = nativeWindow.Blob;
+			const Window_Proxy = nativeWindow.Proxy;
+			const Intl_DateTimeFormat = nativeWindow.Intl.DateTimeFormat;
+			const Date_constructor = nativeWindow.Date;
+
+			${joint}
+		})();`;
+}

package/src/tools/browser-user-agent.ts

@@ -0,0 +1,111 @@
+/**
+ * Derives the stealth user-agent override from whichever Chrome puppeteer bundles.
+ *
+ * Split out of `browser.ts` so it can be asserted without launching a browser:
+ * every field here is a pure function of the raw user-agent string and the
+ * browser version, and the output changes whenever puppeteer's bundled Chrome
+ * changes major version. See `test/browser/user-agent-override.test.ts`.
+ */
+
+const STEALTH_ACCEPT_LANGUAGE = "en-US,en";
+
+export type UserAgentOverride = {
+	userAgent: string;
+	platform: string;
+	acceptLanguage: string;
+	userAgentMetadata: {
+		brands: Array<{ brand: string; version: string }>;
+		fullVersion: string;
+		platform: string;
+		platformVersion: string;
+		architecture: string;
+		model: string;
+		mobile: boolean;
+	};
+};
+
+/**
+ * Chromium's GREASE permutation table, indexed by `majorVersion % 6`.
+ * Mirrors `GenerateBrandVersionList` in
+ * components/embedder_support/user_agent_utils.cc — Chrome shuffles the brand
+ * list per version so that servers cannot hardcode its ordering, and a client
+ * that emits a fixed order is detectable for that reason alone.
+ */
+const BRAND_ORDERS: ReadonlyArray<readonly [number, number, number]> = [
+	[0, 1, 2],
+	[0, 2, 1],
+	[1, 0, 2],
+	[1, 2, 0],
+	[2, 0, 1],
+	[2, 1, 0],
+];
+
+/** The escape characters Chromium permutes into the greased brand name. */
+const GREASE_ESCAPE_CHARS = [" ", " ", ";"] as const;
+
+/** Builds the three-entry brand list for a Chrome major version. */
+function buildBrands(majorVersion: number): Array<{ brand: string; version: string }> {
+	const order = BRAND_ORDERS[majorVersion % BRAND_ORDERS.length] ?? BRAND_ORDERS[0];
+	const greasedBrand = `${GREASE_ESCAPE_CHARS[order[0]]}Not${GREASE_ESCAPE_CHARS[order[1]]}A${GREASE_ESCAPE_CHARS[order[2]]}Brand`;
+	const brands: Array<{ brand: string; version: string }> = [];
+	brands[order[0]] = { brand: greasedBrand, version: "99" };
+	brands[order[1]] = { brand: "Chromium", version: String(majorVersion) };
+	brands[order[2]] = { brand: "Google Chrome", version: String(majorVersion) };
+	return brands;
+}
+
+/**
+ * @param rawUserAgent the browser's own user-agent string, e.g. from `browser.userAgent()`
+ * @param browserVersion the browser version string, e.g. from `browser.version()`;
+ *   used only when the user agent carries no `Chrome/<version>` token
+ */
+export function deriveUserAgentOverride(rawUserAgent: string, browserVersion: string): UserAgentOverride {
+	let userAgent = rawUserAgent.replace("HeadlessChrome/", "Chrome/");
+	if (userAgent.includes("Linux") && !userAgent.includes("Android")) {
+		userAgent = userAgent.replace(/\(([^)]+)\)/, "(Windows NT 10.0; Win64; x64)");
+	}
+
+	const uaVersionMatch = userAgent.match(/Chrome\/([\d|.]+)/);
+	const fallbackVersionMatch = uaVersionMatch ?? browserVersion.match(/\/([\d|.]+)/);
+	const uaVersion = fallbackVersionMatch?.[1] ?? "0";
+	const majorVersion = Number.parseInt(uaVersion.split(".")[0] ?? "0", 10) || 0;
+	const isAndroid = userAgent.includes("Android");
+	const platform = userAgent.includes("Mac OS X")
+		? "MacIntel"
+		: isAndroid
+			? "Android"
+			: userAgent.includes("Linux")
+				? "Linux"
+				: "Win32";
+	const platformFull = userAgent.includes("Mac OS X")
+		? "Mac OS X"
+		: isAndroid
+			? "Android"
+			: userAgent.includes("Linux")
+				? "Linux"
+				: "Windows";
+	const platformVersion = userAgent.includes("Mac OS X ")
+		? (userAgent.match(/Mac OS X ([^)]+)/)?.[1] ?? "")
+		: userAgent.includes("Android ")
+			? (userAgent.match(/Android ([^;]+)/)?.[1] ?? "")
+			: userAgent.includes("Windows ")
+				? (userAgent.match(/Windows .*?([\d|.]+);?/)?.[1] ?? "")
+				: "";
+	const architecture = isAndroid ? "" : "x86";
+	const model = isAndroid ? (userAgent.match(/Android.*?;\s([^)]+)/)?.[1] ?? "") : "";
+
+	return {
+		userAgent,
+		platform,
+		acceptLanguage: STEALTH_ACCEPT_LANGUAGE,
+		userAgentMetadata: {
+			brands: buildBrands(majorVersion),
+			fullVersion: uaVersion,
+			platform: platformFull,
+			platformVersion,
+			architecture,
+			model,
+			mobile: isAndroid,
+		},
+	};
+}

package/src/tools/browser.ts

@@ -27,22 +27,10 @@ import browserDescription from "../prompts/tools/browser.md" with { type: "text"
 import type { ToolSession } from "../sdk";
 import { resizeImage } from "../utils/image-resize";
 import { htmlToBasicMarkdown } from "../web/scrapers/types";
+import { buildStealthBundle } from "./browser-stealth";
+import { deriveUserAgentOverride, type UserAgentOverride } from "./browser-user-agent";
 import type { OutputMeta } from "./output-meta";
 import { expandPath, resolveToCwd } from "./path-utils";
-import stealthTamperingScript from "./puppeteer/00_stealth_tampering.txt" with { type: "text" };
-import stealthActivityScript from "./puppeteer/01_stealth_activity.txt" with { type: "text" };
-import stealthHairlineScript from "./puppeteer/02_stealth_hairline.txt" with { type: "text" };
-import stealthBotdScript from "./puppeteer/03_stealth_botd.txt" with { type: "text" };
-import stealthIframeScript from "./puppeteer/04_stealth_iframe.txt" with { type: "text" };
-import stealthWebglScript from "./puppeteer/05_stealth_webgl.txt" with { type: "text" };
-import stealthScreenScript from "./puppeteer/06_stealth_screen.txt" with { type: "text" };
-import stealthFontsScript from "./puppeteer/07_stealth_fonts.txt" with { type: "text" };
-import stealthAudioScript from "./puppeteer/08_stealth_audio.txt" with { type: "text" };
-import stealthLocaleScript from "./puppeteer/09_stealth_locale.txt" with { type: "text" };
-import stealthPluginsScript from "./puppeteer/10_stealth_plugins.txt" with { type: "text" };
-import stealthHardwareScript from "./puppeteer/11_stealth_hardware.txt" with { type: "text" };
-import stealthCodecsScript from "./puppeteer/12_stealth_codecs.txt" with { type: "text" };
-import stealthWorkerScript from "./puppeteer/13_stealth_worker.txt" with { type: "text" };
 import { formatScreenshot } from "./render-utils";
 import { ToolAbortError, ToolError, throwIfAborted } from "./tool-errors";
 import { toolResult } from "./tool-result";
@@ -99,8 +87,16 @@ export function pickCoDrivePage(pages: { url(): string }[]): number {
 }
 
 /**
- * Lazy-import puppeteer from a safe CWD so cosmiconfig doesn't choke
- * on malformed package.json files in the user's project tree.
+ * Lazy-import puppeteer from a safe CWD so its config loader doesn't choke on
+ * malformed package.json files in the user's project tree.
+ *
+ * Puppeteer 25 swapped cosmiconfig for lilconfig, so the original rationale no
+ * longer names the right library. Retained deliberately rather than removed:
+ * importing puppeteer 25 from a directory containing a deliberately malformed
+ * package.json was verified to succeed, but that only exercises import-time
+ * loading — whether `launch()` reads config lazily was not established, so
+ * dropping the guard would be an unverified behaviour change for a demo-critical
+ * path. It costs one chdir.
  */
 let puppeteerModule: typeof Puppeteer | undefined;
 async function loadPuppeteer(): Promise<typeof Puppeteer> {
@@ -123,7 +119,8 @@ const STEALTH_IGNORE_DEFAULT_ARGS = [
 	"--disable-default-apps",
 	"--disable-component-extensions-with-background-pages",
 ];
-const STEALTH_ACCEPT_LANGUAGE = "en-US,en";
+/** Kept in step with the locale profile in puppeteer/09_stealth_locale.txt. */
+const STEALTH_TIMEZONE = "America/New_York";
 const PUPPETEER_SOURCE_URL_SUFFIX = "//# sourceURL=__puppeteer_evaluation_script__";
 const INTERACTIVE_AX_ROLES = new Set([
 	"button",
@@ -153,21 +150,6 @@ type PuppeteerCdpClient = {
 	send: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
 };
 
-type UserAgentOverride = {
-	userAgent: string;
-	platform: string;
-	acceptLanguage: string;
-	userAgentMetadata: {
-		brands: Array<{ brand: string; version: string }>;
-		fullVersion: string;
-		platform: string;
-		platformVersion: string;
-		architecture: string;
-		model: string;
-		mobile: boolean;
-	};
-};
-
 function resolvePageClient(page: Page): PuppeteerCdpClient | null {
 	const pageWithClient = page as Page & {
 		_client?: (() => PuppeteerCdpClient) | PuppeteerCdpClient;
@@ -539,7 +521,7 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 		if (this.#page && !this.#page.isClosed()) {
 			return this.#page;
 		}
-		if (!this.#browser?.isConnected()) {
+		if (!this.#browser?.connected) {
 			return this.#resetBrowser(params);
 		}
 		// co-drive: reuse the human's current tab when attached, else a fresh page
@@ -698,9 +680,33 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 	async #applyStealthPatches(page: Page): Promise<void> {
 		this.#patchSourceUrl(page);
 		await this.#applyUserAgentOverride(page);
+		await this.#applyTimezoneOverride(page);
 		await this.#injectStealthScripts(page);
 	}
 
+	/**
+	 * Overrides the timezone through CDP rather than in the injected scripts.
+	 *
+	 * Chrome recomputes Date, Intl, getTimezoneOffset and the zone name from the
+	 * overridden zone, so they all agree. Patching them in page script cannot
+	 * achieve that: the previous attempt rewrote only the displayed zone NAME and
+	 * forced its zone into every Intl.DateTimeFormat call, which overrode a
+	 * caller's explicit `timeZone` and corrupted formatted output (see
+	 * 09_stealth_locale.txt).
+	 */
+	async #applyTimezoneOverride(page: Page): Promise<void> {
+		const client = resolvePageClient(page);
+		if (!client) return;
+		try {
+			await client.send("Emulation.setTimezoneOverride", { timezoneId: STEALTH_TIMEZONE });
+		} catch (error) {
+			// A rejected zone id must not take the rest of the stealth setup down.
+			logger.debug("Failed to apply timezone override", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
 	async #applyUserAgentOverride(page: Page): Promise<void> {
 		const client = resolvePageClient(page);
 		if (!client) return;
@@ -711,71 +717,8 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 
 	async #resolveUserAgentOverride(page: Page): Promise<UserAgentOverride> {
 		if (this.#userAgentOverride) return this.#userAgentOverride;
-		const rawUserAgent = await page.browser().userAgent();
-		let userAgent = rawUserAgent.replace("HeadlessChrome/", "Chrome/");
-		if (userAgent.includes("Linux") && !userAgent.includes("Android")) {
-			userAgent = userAgent.replace(/\(([^)]+)\)/, "(Windows NT 10.0; Win64; x64)");
-		}
-
-		const uaVersionMatch = userAgent.match(/Chrome\/([\d|.]+)/);
-		const fallbackVersionMatch = uaVersionMatch ?? (await page.browser().version()).match(/\/([\d|.]+)/);
-		const uaVersion = fallbackVersionMatch?.[1] ?? "0";
-		const majorVersion = Number.parseInt(uaVersion.split(".")[0] ?? "0", 10) || 0;
-		const isAndroid = userAgent.includes("Android");
-		const platform = userAgent.includes("Mac OS X")
-			? "MacIntel"
-			: isAndroid
-				? "Android"
-				: userAgent.includes("Linux")
-					? "Linux"
-					: "Win32";
-		const platformFull = userAgent.includes("Mac OS X")
-			? "Mac OS X"
-			: isAndroid
-				? "Android"
-				: userAgent.includes("Linux")
-					? "Linux"
-					: "Windows";
-		const platformVersion = userAgent.includes("Mac OS X ")
-			? (userAgent.match(/Mac OS X ([^)]+)/)?.[1] ?? "")
-			: userAgent.includes("Android ")
-				? (userAgent.match(/Android ([^;]+)/)?.[1] ?? "")
-				: userAgent.includes("Windows ")
-					? (userAgent.match(/Windows .*?([\d|.]+);?/)?.[1] ?? "")
-					: "";
-		const architecture = isAndroid ? "" : "x86";
-		const model = isAndroid ? (userAgent.match(/Android.*?;\s([^)]+)/)?.[1] ?? "") : "";
-
-		const brandOrders = [
-			[0, 1, 2],
-			[0, 2, 1],
-			[1, 0, 2],
-			[1, 2, 0],
-			[2, 0, 1],
-			[2, 1, 0],
-		];
-		const order = brandOrders[majorVersion % brandOrders.length] ?? brandOrders[0];
-		const escapedChars = [" ", " ", ";"];
-		const greaseyBrand = `${escapedChars[order[0]]}Not${escapedChars[order[1]]}A${escapedChars[order[2]]}Brand`;
-		const brands: { brand: string; version: string }[] = [];
-		brands[order[0]] = { brand: greaseyBrand, version: "99" };
-		brands[order[1]] = { brand: "Chromium", version: String(majorVersion) };
-		brands[order[2]] = { brand: "Google Chrome", version: String(majorVersion) };
-
-		this.#userAgentOverride = {
-			userAgent,
-			platform,
-			acceptLanguage: STEALTH_ACCEPT_LANGUAGE,
-			userAgentMetadata: {
-				brands,
-				fullVersion: uaVersion,
-				platform: platformFull,
-				platformVersion,
-				architecture,
-				model,
-				mobile: isAndroid,
-			},
-		};
+		const browser = page.browser();
+		this.#userAgentOverride = deriveUserAgentOverride(await browser.userAgent(), await browser.version());
 		return this.#userAgentOverride;
 	}
 
@@ -877,70 +820,7 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 
 	/** Injects stealth scripts that cover common puppeteer detection surfaces. */
 	async #injectStealthScripts(page: Page): Promise<void> {
-		const scripts = [
-			stealthTamperingScript,
-			stealthActivityScript,
-			stealthHairlineScript,
-			stealthBotdScript,
-			stealthIframeScript,
-			stealthWebglScript,
-			stealthScreenScript,
-			stealthFontsScript,
-			stealthAudioScript,
-			stealthLocaleScript,
-			stealthPluginsScript,
-			stealthHardwareScript,
-			stealthCodecsScript,
-			stealthWorkerScript,
-		];
-
-		const joint = scripts
-			.map(
-				script => `
-		try {
-			${script};
-		} catch (e) {}
-	`,
-			)
-			.join(";\n");
-
-		await page.evaluateOnNewDocument(`(() => {
-				// Native function cache - captured before any tampering
-				const iframe = document.createElement("iframe");
-				iframe.style.display = "none";
-				document.head.appendChild(iframe);
-				const nativeWindow = iframe.contentWindow;
-				if (!nativeWindow) return;
-
-				// Cache pristine native functions
-				const Function_toString = nativeWindow.Function.prototype.toString;
-				const Object_getOwnPropertyDescriptor = nativeWindow.Object.getOwnPropertyDescriptor;
-				const Object_getOwnPropertyDescriptors = nativeWindow.Object.getOwnPropertyDescriptors;
-				const Object_getPrototypeOf = nativeWindow.Object.getPrototypeOf;
-				const Object_defineProperty = nativeWindow.Object.defineProperty;
-				const Object_getOwnPropertyDescriptorOriginal = nativeWindow.Object.getOwnPropertyDescriptor;
-				const Object_create = nativeWindow.Object.create;
-				const Object_keys = nativeWindow.Object.keys;
-				const Object_getOwnPropertyNames = nativeWindow.Object.getOwnPropertyNames;
-				const Object_entries = nativeWindow.Object.entries;
-				const Object_setPrototypeOf = nativeWindow.Object.setPrototypeOf;
-				const Object_assign = nativeWindow.Object.assign;
-				const Window_setTimeout = nativeWindow.setTimeout;
-				const Math_random = nativeWindow.Math.random;
-				const Math_floor = nativeWindow.Math.floor;
-				const Math_max = nativeWindow.Math.max;
-				const Math_min = nativeWindow.Math.min;
-				const Window_Event = nativeWindow.Event;
-				const Promise_resolve = nativeWindow.Promise.resolve.bind(nativeWindow.Promise);
-				const Window_Blob = nativeWindow.Blob;
-				const Window_Proxy = nativeWindow.Proxy;
-				const Intl_DateTimeFormat = nativeWindow.Intl.DateTimeFormat;
-				const Date_constructor = nativeWindow.Date;
-
-				
-				${joint}
-
-				document.head.removeChild(iframe);})();`);
+		await page.evaluateOnNewDocument(buildStealthBundle());
 	}
 
 	async execute(

package/src/tools/puppeteer/00_stealth_tampering.txt

@@ -58,6 +58,3 @@ Object.getOwnPropertyDescriptor = function (obj, prop) {
 
   return descriptor;
 };
-
-// Cleanup
-document.head.removeChild(iframe);

package/src/tools/puppeteer/03_stealth_botd.txt

@@ -372,6 +372,18 @@ if (navigator.permissions?.query) {
 			}
 			return originalQuery.call(this, parameters);
 		};
+		// Mask the replacement, or String(navigator.permissions.query) hands a
+		// detector this function's source where Chrome reports native code. The
+		// tampering surface masks every function it patches, but this one is
+		// replaced here, after that surface has already run.
+		// Binding the cached native toString to the ORIGINAL query reproduces
+		// Chrome's exact output, same idiom as 04_stealth_iframe / 13_stealth_worker.
+		Object_defineProperty(navigator.permissions.query, "toString", {
+			value: Function_toString.bind(originalQuery),
+			writable: false,
+			configurable: true,
+			enumerable: false,
+		});
 	}
 }
 

package/src/tools/puppeteer/04_stealth_iframe.txt

@@ -23,24 +23,34 @@ const addContentWindowProxy = (iframe) => {
 	}
 };
 
+// The native accessor, captured from the prototype so the shim below can hand
+// off to it. Without this the shim has nothing to delegate to.
+const nativeSrcdocDescriptor = Object_getOwnPropertyDescriptor(HTMLIFrameElement.prototype, "srcdoc");
+
 const handleIframeCreation = (target, thisArg, args) => {
 	const iframe = target.apply(thisArg, args);
-	const originalIframe = iframe;
-	const originalSrcdoc = originalIframe.srcdoc;
 
+	// A one-shot shim: install the contentWindow proxy on the first srcdoc
+	// assignment, then step aside so the element behaves natively.
+	//
+	// It must step aside by DELETING itself. An earlier version redefined srcdoc
+	// as a non-writable data property and then assigned through the same element,
+	// so the write silently failed against its own frozen property and the native
+	// setter was never reached: srcdoc stayed "", the attribute was never set, and
+	// every dynamically created srcdoc iframe loaded empty.
 	Object_defineProperty(iframe, "srcdoc", {
 		configurable: true,
 		get() {
-			return originalSrcdoc;
+			return nativeSrcdocDescriptor?.get ? nativeSrcdocDescriptor.get.call(this) : "";
 		},
 		set(newValue) {
 			addContentWindowProxy(this);
-			Object_defineProperty(iframe, "srcdoc", {
-				configurable: false,
-				writable: false,
-				value: originalSrcdoc,
-			});
-			originalIframe.srcdoc = newValue;
+			delete iframe.srcdoc;
+			if (nativeSrcdocDescriptor?.set) {
+				nativeSrcdocDescriptor.set.call(iframe, newValue);
+			} else {
+				iframe.setAttribute("srcdoc", newValue);
+			}
 		},
 	});
 

package/src/tools/puppeteer/09_stealth_locale.txt

@@ -1,7 +1,6 @@
 // Define a consistent locale profile
 const locale = "en-US";
 const languages = ["en-US", "en"];
-const timezone = "America/New_York";
 
 // Override navigator language properties
 Object_defineProperty(navigator, "language", {
@@ -15,32 +14,22 @@ Object_defineProperty(navigator, "languages", {
   enumerable: true,
 });
 
-// Override Intl.DateTimeFormat for timezone consistency
-const OriginalDateTimeFormat = Intl_DateTimeFormat;
-Intl.DateTimeFormat = class extends OriginalDateTimeFormat {
-  constructor(locales, options) {
-    const mergedOptions = { ...options, timeZone: timezone };
-    super(locales, mergedOptions);
-  }
-  resolvedOptions() {
-    const options = super.resolvedOptions();
-    options.timeZone = timezone;
-    return options;
-  }
-};
-
-// Ensure Date timezone is consistent
-const originalDateConstructor = Date_constructor;
-const originalToString = originalDateConstructor.prototype.toString;
-const originalToTimeString = originalDateConstructor.prototype.toTimeString;
-
-Date.prototype.toString = function () {
-  return originalToString
-    .call(this)
-    .replace(/\(.*\)$/, "(Eastern Standard Time)");
-};
-Date.prototype.toTimeString = function () {
-  return originalToTimeString
-    .call(this)
-    .replace(/\(.*\)$/, "(Eastern Standard Time)");
-};
+// Timezone is NOT spoofed here.
+//
+// It is applied through CDP Emulation.setTimezoneOverride in browser.ts, which
+// shifts the clock itself: Date, Intl, getTimezoneOffset and the zone name all
+// agree, because Chrome computes them from the overridden zone.
+//
+// Two earlier attempts in this file were worse than nothing:
+//
+//   1. Wrapping Intl.DateTimeFormat and forcing `timeZone` into every options
+//      object overrode the CALLER's explicit zone, so
+//      `new Intl.DateTimeFormat("en-US", { timeZone: "UTC" })` silently formatted
+//      in New York — 08:00 where the page asked for 12:00. That corrupts data a
+//      page displays or submits, which is far worse than a fingerprinting tell.
+//
+//   2. Rewriting Date.prototype.toString/toTimeString only replaced the zone
+//      NAME, never the numeric offset, and hardcoded "Eastern Standard Time" —
+//      so in July it claimed EST while getTimezoneOffset still returned 240
+//      (EDT). Self-contradictory, and a detector comparing the two sees it
+//      immediately.