pi-agent-browser-native 0.2.12 → 0.2.13

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

@@ -6,11 +6,15 @@
  * Invariants/Assumptions: Temp artifacts live under the OS temp directory, each active run uses a dedicated 0700 directory, files are created with exclusive 0600 permissions, session-scoped persisted artifacts stay under the pi session directory, and stale pruning only touches roots with an explicit pi-agent-browser ownership marker.
  */
 
+import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { rmSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+import { isRecord, parsePositiveInteger } from "./parsing.js";
 
 const TEMP_ROOT_PREFIX = "pi-agent-browser-";
 const TEMP_ROOT_MARKER_FILE_NAME = ".pi-agent-browser-owner.json";
@@ -22,6 +26,8 @@ const DEFAULT_TEMP_ROOT_MAX_BYTES = 32 * 1_024 * 1_024;
 const SESSION_ARTIFACT_MAX_BYTES_ENV = "PI_AGENT_BROWSER_SESSION_ARTIFACT_MAX_BYTES";
 const DEFAULT_SESSION_ARTIFACT_MAX_BYTES = 32 * 1_024 * 1_024;
 const SESSION_ARTIFACTS_ROOT_DIR_NAME = ".pi-agent-browser-artifacts";
+const PROCESS_START_IDENTITY_TIMEOUT_MS = 1_000;
+const execFileAsync = promisify(execFile);
 
 export interface PersistentSessionArtifactStore {
 	protectedPaths?: readonly string[];
@@ -29,40 +35,64 @@ export interface PersistentSessionArtifactStore {
 	sessionId: string;
 }
 
+export interface PersistentSessionArtifactEviction {
+	mtimeMs: number;
+	path: string;
+	sizeBytes: number;
+}
+
+export interface PersistentSessionArtifactWriteResult {
+	evictedArtifacts: PersistentSessionArtifactEviction[];
+	path: string;
+}
+
 interface TempRootOwnershipRecord {
 	createdAtMs: number;
 	kind: string;
+	leaseUpdatedAtMs?: number;
+	ownerPid?: number;
+	ownerProcessStartIdentity?: string;
 	ownerUid?: number;
 	version: number;
 }
 
+interface TempRootOwnershipMarkerOptions {
+	createdAtMs?: number;
+	leaseUpdatedAtMs?: number;
+	ownerPid?: number;
+	ownerProcessStartIdentity?: string;
+}
+
+type ProcessLiveness = "alive" | "dead" | "unknown";
+
 let sessionTempRootPromise: Promise<string> | undefined;
 let exitCleanupRegistered = false;
 let tempMutationQueue = Promise.resolve();
 const ownedTempRoots = new Set<string>();
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 function getCurrentProcessUid(): number | undefined {
 	return typeof process.getuid === "function" ? process.getuid() : undefined;
 }
 
-function parsePositiveInteger(rawValue: string | undefined): number | undefined {
-	if (typeof rawValue !== "string") return undefined;
-	const normalizedValue = rawValue.trim();
-	if (!/^\d+$/.test(normalizedValue)) return undefined;
-	const parsedValue = Number(normalizedValue);
-	if (!Number.isSafeInteger(parsedValue) || parsedValue <= 0) return undefined;
-	return parsedValue;
+function isPositiveFiniteNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
 }
 
 function isTempRootOwnershipRecord(value: unknown): value is TempRootOwnershipRecord {
 	if (!isRecord(value)) return false;
 	if (value.kind !== TEMP_ROOT_MARKER_KIND || value.version !== TEMP_ROOT_MARKER_VERSION) return false;
-	if (typeof value.createdAtMs !== "number" || !Number.isFinite(value.createdAtMs) || value.createdAtMs <= 0) return false;
-	return value.ownerUid === undefined || typeof value.ownerUid === "number";
+	if (!isPositiveFiniteNumber(value.createdAtMs)) return false;
+	if (value.leaseUpdatedAtMs !== undefined && !isPositiveFiniteNumber(value.leaseUpdatedAtMs)) return false;
+	if (value.ownerPid !== undefined) {
+		if (typeof value.ownerPid !== "number" || !Number.isSafeInteger(value.ownerPid) || value.ownerPid <= 0) return false;
+	}
+	if (value.ownerProcessStartIdentity !== undefined) {
+		if (typeof value.ownerProcessStartIdentity !== "string" || value.ownerProcessStartIdentity.trim() === "") return false;
+	}
+	if (value.ownerUid !== undefined) {
+		if (typeof value.ownerUid !== "number" || !Number.isSafeInteger(value.ownerUid) || value.ownerUid < 0) return false;
+	}
+	return true;
 }
 
 function getTempArtifactByteLength(content: string | Uint8Array): number {
@@ -107,11 +137,33 @@ async function readTempRootOwnershipMarker(tempRoot: string): Promise<TempRootOw
 	}
 }
 
-export async function writeSecureTempRootOwnershipMarker(tempRoot: string, createdAtMs = Date.now()): Promise<string> {
+async function getProcessStartIdentity(pid: number | undefined): Promise<string | undefined> {
+	if (pid === undefined) return undefined;
+	if (!Number.isSafeInteger(pid) || pid <= 0) return undefined;
+	try {
+		const { stdout } = await execFileAsync("ps", ["-p", String(pid), "-o", "lstart="], {
+			timeout: PROCESS_START_IDENTITY_TIMEOUT_MS,
+		});
+		const identity = stdout.trim().replace(/\s+/g, " ");
+		return identity || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function writeSecureTempRootOwnershipMarker(
+	tempRoot: string,
+	options: TempRootOwnershipMarkerOptions = {},
+): Promise<string> {
 	const markerPath = join(tempRoot, TEMP_ROOT_MARKER_FILE_NAME);
+	const createdAtMs = options.createdAtMs ?? Date.now();
+	const ownerPid = options.ownerPid ?? process.pid;
 	const markerRecord: TempRootOwnershipRecord = {
 		createdAtMs,
 		kind: TEMP_ROOT_MARKER_KIND,
+		leaseUpdatedAtMs: options.leaseUpdatedAtMs ?? createdAtMs,
+		ownerPid,
+		ownerProcessStartIdentity: options.ownerProcessStartIdentity ?? (await getProcessStartIdentity(ownerPid)),
 		ownerUid: getCurrentProcessUid(),
 		version: TEMP_ROOT_MARKER_VERSION,
 	};
@@ -120,6 +172,54 @@ export async function writeSecureTempRootOwnershipMarker(tempRoot: string, creat
 	return markerPath;
 }
 
+async function refreshSecureTempRootLease(tempRoot: string): Promise<void> {
+	const markerPath = join(tempRoot, TEMP_ROOT_MARKER_FILE_NAME);
+	const ownershipMarker = await readTempRootOwnershipMarker(tempRoot);
+	if (!ownershipMarker) return;
+	if (ownershipMarker.ownerPid !== process.pid) return;
+	const currentUid = getCurrentProcessUid();
+	if (currentUid !== undefined && ownershipMarker.ownerUid !== undefined && ownershipMarker.ownerUid !== currentUid) return;
+	const currentProcessStartIdentity = await getProcessStartIdentity(process.pid);
+	if (
+		ownershipMarker.ownerProcessStartIdentity !== undefined &&
+		currentProcessStartIdentity !== undefined &&
+		ownershipMarker.ownerProcessStartIdentity !== currentProcessStartIdentity
+	) {
+		return;
+	}
+	const refreshedMarker: TempRootOwnershipRecord = {
+		...ownershipMarker,
+		leaseUpdatedAtMs: Date.now(),
+		ownerPid: process.pid,
+		ownerProcessStartIdentity: currentProcessStartIdentity ?? ownershipMarker.ownerProcessStartIdentity,
+		ownerUid: currentUid,
+	};
+	await writeFile(markerPath, JSON.stringify(refreshedMarker, null, 2), { encoding: "utf8", mode: 0o600 });
+	await chmod(markerPath, 0o600).catch(() => undefined);
+}
+
+async function getMarkerOwnerLiveness(ownershipMarker: TempRootOwnershipRecord): Promise<ProcessLiveness> {
+	const pid = ownershipMarker.ownerPid;
+	if (pid === undefined) return "unknown";
+	try {
+		process.kill(pid, 0);
+	} catch (error) {
+		const errorWithCode = error as NodeJS.ErrnoException;
+		if (errorWithCode.code === "ESRCH") return "dead";
+		if (errorWithCode.code !== "EPERM") return "unknown";
+	}
+
+	const currentProcessStartIdentity = await getProcessStartIdentity(pid);
+	if (
+		ownershipMarker.ownerProcessStartIdentity !== undefined &&
+		currentProcessStartIdentity !== undefined &&
+		ownershipMarker.ownerProcessStartIdentity === currentProcessStartIdentity
+	) {
+		return "alive";
+	}
+	return "dead";
+}
+
 async function pruneStaleTempRoots(currentTempRoot: string | undefined): Promise<void> {
 	const entries = await readdir(tmpdir(), { withFileTypes: true }).catch(() => []);
 	const cutoffTime = Date.now() - STALE_TEMP_ROOT_MAX_AGE_MS;
@@ -141,9 +241,12 @@ async function pruneStaleTempRoots(currentTempRoot: string | undefined): Promise
 				) {
 					return;
 				}
+				const staleTimestampMs = ownershipMarker.leaseUpdatedAtMs ?? ownershipMarker.createdAtMs;
+				if (staleTimestampMs >= cutoffTime) return;
+				if ((await getMarkerOwnerLiveness(ownershipMarker)) === "alive") return;
 
 				const stats = await stat(path).catch(() => undefined);
-				if (!stats?.isDirectory() || stats.mtimeMs >= cutoffTime) return;
+				if (!stats?.isDirectory()) return;
 				await rm(path, { force: true, recursive: true }).catch(() => undefined);
 			}),
 	);
@@ -205,23 +308,25 @@ async function prunePersistentSessionArtifactsToBudget(
 	sessionArtifactDir: string,
 	additionalBytes: number,
 	protectedPaths: ReadonlySet<string>,
-): Promise<void> {
-	if (additionalBytes <= 0) return;
+): Promise<PersistentSessionArtifactEviction[]> {
+	if (additionalBytes <= 0) return [];
 	const maxBytes = getPersistentSessionArtifactMaxBytes();
 	let files = await listArtifactFiles(sessionArtifactDir);
 	let totalBytes = files.reduce((total, file) => total + file.size, 0);
 	if (totalBytes + additionalBytes <= maxBytes) {
-		return;
+		return [];
 	}
+	const evictedArtifacts: PersistentSessionArtifactEviction[] = [];
 	files = files.sort((left, right) => left.mtimeMs - right.mtimeMs || left.path.localeCompare(right.path));
 	for (const file of files) {
 		if (protectedPaths.has(file.path)) {
 			continue;
 		}
 		await rm(file.path, { force: true }).catch(() => undefined);
+		evictedArtifacts.push({ mtimeMs: file.mtimeMs, path: file.path, sizeBytes: file.size });
 		totalBytes -= file.size;
 		if (totalBytes + additionalBytes <= maxBytes) {
-			return;
+			return evictedArtifacts;
 		}
 	}
 	throw new Error(`pi-agent-browser persisted spill budget exceeded (${totalBytes + additionalBytes} bytes > ${maxBytes} byte limit).`);
@@ -241,6 +346,7 @@ async function getSessionTempRoot(): Promise<string> {
 	}
 
 	const tempRoot = await sessionTempRootPromise;
+	await refreshSecureTempRootLease(tempRoot).catch(() => undefined);
 	await pruneStaleTempRoots(tempRoot).catch(() => undefined);
 	return tempRoot;
 }
@@ -259,7 +365,9 @@ export async function writeSecureTempChunk(options: {
 }): Promise<void> {
 	const { content, fileHandle, path } = options;
 	await enqueueTempMutation(async () => {
-		await assertSecureTempRootBudget(dirname(path), getTempArtifactByteLength(content));
+		const tempRoot = dirname(path);
+		await refreshSecureTempRootLease(tempRoot).catch(() => undefined);
+		await assertSecureTempRootBudget(tempRoot, getTempArtifactByteLength(content));
 		await fileHandle.appendFile(content);
 	});
 }
@@ -287,11 +395,11 @@ export async function writePersistentSessionArtifactFile(options: {
 	prefix: string;
 	store: PersistentSessionArtifactStore;
 	suffix: string;
-}): Promise<string> {
+}): Promise<PersistentSessionArtifactWriteResult> {
 	const { content, prefix, store, suffix } = options;
 	return await enqueueTempMutation(async () => {
 		const artifactDir = await ensurePersistentSessionArtifactDir(store);
-		await prunePersistentSessionArtifactsToBudget(
+		const evictedArtifacts = await prunePersistentSessionArtifactsToBudget(
 			artifactDir,
 			getTempArtifactByteLength(content),
 			new Set((store.protectedPaths ?? []).filter((path) => dirname(path) === artifactDir)),
@@ -306,7 +414,7 @@ export async function writePersistentSessionArtifactFile(options: {
 		} finally {
 			await fileHandle.close().catch(() => undefined);
 		}
-		return path;
+		return { evictedArtifacts, path };
 	});
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -26,8 +26,13 @@
   "engines": {
     "node": ">=20.6.0"
   },
+  "bin": {
+    "pi-agent-browser-doctor": "scripts/doctor.mjs"
+  },
   "files": [
     "extensions",
+    "scripts/doctor.mjs",
+    "scripts/agent-browser-capability-baseline.mjs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -56,12 +61,10 @@
     "basic-ftp": "5.3.0"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "docs": "node ./scripts/project.mjs docs",
+    "doctor": "node ./scripts/doctor.mjs",
     "test": "tsx --test test/**/*.test.ts",
-    "pack:dry-run": "npm pack --json --dry-run",
-    "verify": "npm run typecheck && npm run test",
-    "verify:package": "node ./scripts/verify-package.mjs",
-    "verify:release": "npm run verify && npm run verify:package"
+    "verify": "node ./scripts/project.mjs verify"
   },
   "packageManager": "npm@10.9.8"
 }

package/scripts/agent-browser-capability-baseline.mjs

@@ -0,0 +1,104 @@
+/**
+ * Purpose: Define the canonical upstream agent-browser capability baseline targeted by this package.
+ * Responsibilities: Store the target upstream version, sampled help commands, and verifier/doc token expectations in one importable metadata object.
+ * Scope: Versioned capability metadata only; it does not execute agent-browser or validate documentation by itself.
+ * Usage: Imported by command-reference verifier, generated docs checker, and tests when upstream agent-browser is re-baselined.
+ * Invariants/Assumptions: This package targets the current installed upstream agent-browser only and does not keep compatibility shims for older versions.
+ */
+
+export const CAPABILITY_BASELINE_SOURCE = "scripts/agent-browser-capability-baseline.mjs";
+export const COMMAND_REFERENCE_DOC_PATH = "docs/COMMAND_REFERENCE.md";
+export const CAPABILITY_BASELINE_BLOCK_MARKER_PREFIX = "agent-browser-capability-baseline";
+export const COMMAND_REFERENCE_BASELINE_BLOCK_IDS = Object.freeze(["upstream-baseline", "capability-token-baseline"]);
+
+export const CAPABILITY_BASELINE = Object.freeze({
+  targetVersion: "0.26.0",
+  helpCommands: Object.freeze([
+    Object.freeze({ label: "root help", args: Object.freeze(["--help"]) }),
+    Object.freeze({ label: "tab help", args: Object.freeze(["tab", "--help"]) }),
+    Object.freeze({ label: "snapshot help", args: Object.freeze(["snapshot", "--help"]) }),
+    Object.freeze({ label: "wait help", args: Object.freeze(["wait", "--help"]) }),
+  ]),
+  docRequiredTokens: Object.freeze([
+    "skills list",
+    "skills get core --full",
+    "keyboard type <text>",
+    "scroll <dir> [px]",
+    "scrollintoview <sel>",
+    "connect <port|url>",
+    "is <what> <selector>",
+    "find <locator> <value> <action>",
+    "mouse <action> [args]",
+    "set <setting> [value]",
+    "network <action>",
+    "cookies [get|set|clear]",
+    "storage <local|session>",
+    "diff snapshot",
+    "trace start|stop [path]",
+    "profiler start|stop [path]",
+    "record start <path> [url]",
+    "console [--clear]",
+    "errors [--clear]",
+    "highlight <sel>",
+    "inspect",
+    "clipboard <op> [text]",
+    "stream enable [--port <n>]",
+    "auth save <name>",
+    "confirm <id>",
+    "deny <id>",
+    "chat <message>",
+    "dashboard start --port <n>",
+    "install --with-deps",
+    "upgrade",
+    "doctor [--fix]",
+    "profiles",
+    "snapshot -i --urls",
+    "snapshot --urls",
+    "wait --download [path]",
+    "tab new --label <name> [url]",
+    "--action-policy <path>",
+    "--confirm-actions <list>",
+    "--engine <name>",
+    "AGENT_BROWSER_CONFIG",
+  ]),
+  upstreamExpectations: Object.freeze([
+    Object.freeze({ token: "skills", help: "root help" }),
+    Object.freeze({ token: "keyboard", help: "root help" }),
+    Object.freeze({ token: "scroll", help: "root help" }),
+    Object.freeze({ token: "scrollintoview", help: "root help" }),
+    Object.freeze({ token: "connect", help: "root help" }),
+    Object.freeze({ token: "is", help: "root help" }),
+    Object.freeze({ token: "find", help: "root help" }),
+    Object.freeze({ token: "mouse", help: "root help" }),
+    Object.freeze({ token: "set", help: "root help" }),
+    Object.freeze({ token: "network", help: "root help" }),
+    Object.freeze({ token: "cookies [get|set|clear]", help: "root help" }),
+    Object.freeze({ token: "storage", help: "root help" }),
+    Object.freeze({ token: "diff snapshot", help: "root help" }),
+    Object.freeze({ token: "trace start|stop [path]", help: "root help" }),
+    Object.freeze({ token: "profiler start|stop [path]", help: "root help" }),
+    Object.freeze({ token: "record start <path> [url]", help: "root help" }),
+    Object.freeze({ token: "console [--clear]", help: "root help" }),
+    Object.freeze({ token: "errors [--clear]", help: "root help" }),
+    Object.freeze({ token: "highlight <sel>", help: "root help" }),
+    Object.freeze({ token: "inspect", help: "root help" }),
+    Object.freeze({ token: "clipboard <op> [text]", help: "root help" }),
+    Object.freeze({ token: "stream enable [--port <n>]", help: "root help" }),
+    Object.freeze({ token: "auth save <name>", help: "root help" }),
+    Object.freeze({ token: "confirm <id>", help: "root help" }),
+    Object.freeze({ token: "deny <id>", help: "root help" }),
+    Object.freeze({ token: "chat <message>", help: "root help" }),
+    Object.freeze({ token: "dashboard start --port <n>", help: "root help" }),
+    Object.freeze({ token: "install --with-deps", help: "root help" }),
+    Object.freeze({ token: "upgrade", help: "root help" }),
+    Object.freeze({ token: "doctor [--fix]", help: "root help" }),
+    Object.freeze({ token: "profiles", help: "root help" }),
+    Object.freeze({ token: "-u, --urls", help: "snapshot help" }),
+    Object.freeze({ token: "--download [path]", help: "wait help" }),
+    Object.freeze({ token: "new --label <name> [url]", help: "tab help" }),
+  ]),
+});
+
+export function expectedVersionLabel() {
+  return `agent-browser ${CAPABILITY_BASELINE.targetVersion}`;
+}