pi-agent-browser-native 0.1.1

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

@@ -0,0 +1,236 @@
+/**
+ * Purpose: Build safe, deterministic agent-browser invocations for the pi-agent-browser extension.
+ * Responsibilities: Validate raw tool arguments, derive implicit session names from the pi session identity, detect explicit session usage, and build the effective CLI argument list passed to the upstream agent-browser binary.
+ * Scope: Pure runtime-planning helpers only; no subprocess execution or filesystem access lives here.
+ * Usage: Imported by the extension entrypoint and unit tests before spawning the upstream CLI.
+ * Invariants/Assumptions: The wrapper stays thin, preserves upstream command vocabulary, and only injects `--json` plus an implicit `--session` when appropriate.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { basename } from "node:path";
+
+const STARTUP_SCOPED_FLAGS = ["--cdp", "--profile", "--session-name"] as const;
+const INSPECTION_ALLOW_PATTERNS = [
+	/\bagent[_ -]?browser\s+--(?:help|version)\b/i,
+	/\bagent[_ -]?browser\b.*\b(?:help|version|docs?|documentation|tool contract|tool guidance|tool description)\b/i,
+	/\b(?:help|version|docs?|documentation|tool contract|tool guidance|tool description)\b.*\bagent[_ -]?browser\b/i,
+	/\bdebug(?:ging)?\b.*\b(?:agent[_ -]?browser|agent_browser|browser integration)\b/i,
+	/\bwhy\s+(?:isn't|is not|doesn't|does not)\b.*\b(?:agent[_ -]?browser|agent_browser)\b/i,
+];
+const LEGACY_BASH_ALLOW_PATTERNS = [
+	/\b(?:bash-oriented workflow|bash workflow)\b/i,
+	/\b(?:use|via|through|with)\s+bash\b/i,
+	/\bnpx\s+agent-browser\b/i,
+	/\bagent-browser\s+--(?:help|version)\b/i,
+	/\bdebug(?:ging)?\b.*\b(?:agent[_ -]?browser|agent_browser|browser integration)\b/i,
+];
+
+const GLOBAL_FLAGS_WITH_VALUES = new Set([
+	"--session",
+	"--cdp",
+	"--config",
+	"--profile",
+	"--session-name",
+	"--proxy",
+	"--proxy-bypass",
+	"--headers",
+	"--executable-path",
+	"--extension",
+	"--provider",
+	"-p",
+	"--engine",
+	"--state",
+	"--download-path",
+	"--screenshot-dir",
+	"--screenshot-format",
+	"--screenshot-quality",
+	"--color-scheme",
+	"--device",
+	"--port",
+]);
+const SHELL_OPERATOR_TOKENS = new Set(["&&", "||", "|", ";", ">", ">>", "<"]);
+const IMAGE_EXTENSION_TO_MIME_TYPE: Record<string, string> = {
+	".gif": "image/gif",
+	".jpeg": "image/jpeg",
+	".jpg": "image/jpeg",
+	".png": "image/png",
+	".webp": "image/webp",
+};
+const MAX_PROJECT_SLUG_LENGTH = 24;
+
+export interface CommandInfo {
+	command?: string;
+	subcommand?: string;
+}
+
+export interface ExecutionPlan {
+	commandInfo: CommandInfo;
+	effectiveArgs: string[];
+	sessionName?: string;
+	startupScopedFlags: string[];
+	usedImplicitSession: boolean;
+	validationError?: string;
+}
+
+export interface PromptPolicy {
+	allowAgentBrowserInspection: boolean;
+	allowLegacyAgentBrowserBash: boolean;
+}
+
+export function createEphemeralSessionSeed(): string {
+	return randomUUID();
+}
+
+export function createImplicitSessionName(
+	sessionId: string | undefined,
+	cwd: string,
+	ephemeralSeed: string,
+): string {
+	const slug =
+		basename(cwd)
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-+|-+$/g, "")
+			.slice(0, MAX_PROJECT_SLUG_LENGTH) || "project";
+	const stableSessionId = sessionId?.replace(/-/g, "").slice(0, 12);
+	if (stableSessionId && stableSessionId.length > 0) {
+		return `piab-${slug}-${stableSessionId}`;
+	}
+
+	const digest = createHash("sha256").update(`ephemeral:${cwd}:${ephemeralSeed}`).digest("hex").slice(0, 12);
+	return `piab-${slug}-${digest}`;
+}
+
+export function validateToolArgs(args: string[]): string | undefined {
+	if (args.length === 0) {
+		return "`args` must contain at least one agent-browser command token.";
+	}
+
+	const shellOperator = args.find((token) => SHELL_OPERATOR_TOKENS.has(token));
+	if (shellOperator) {
+		return `Do not pass shell operators like \`${shellOperator}\`. Pass exact agent-browser CLI arguments only.`;
+	}
+
+	return undefined;
+}
+
+function hasFlagToken(args: string[], flag: string): boolean {
+	return args.some((token) => token === flag || token.startsWith(`${flag}=`));
+}
+
+export function extractExplicitSessionName(args: string[]): string | undefined {
+	for (const [index, token] of args.entries()) {
+		if (token === "--session") {
+			return args[index + 1];
+		}
+		if (token.startsWith("--session=")) {
+			return token.slice("--session=".length);
+		}
+	}
+	return undefined;
+}
+
+export function getStartupScopedFlags(args: string[]): string[] {
+	return STARTUP_SCOPED_FLAGS.filter((flag) => hasFlagToken(args, flag));
+}
+
+export function buildPromptPolicy(prompt: string): PromptPolicy {
+	return {
+		allowAgentBrowserInspection: INSPECTION_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
+		allowLegacyAgentBrowserBash: LEGACY_BASH_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
+	};
+}
+
+function getMessageText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+
+	return content
+		.map((item) => {
+			if (typeof item !== "object" || item === null) return "";
+			return item.type === "text" && typeof item.text === "string" ? item.text : "";
+		})
+		.filter((text) => text.length > 0)
+		.join("\n");
+}
+
+export function getLatestUserPrompt(branch: unknown[]): string {
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const entry = branch[index];
+		if (typeof entry !== "object" || entry === null || !("type" in entry) || entry.type !== "message") {
+			continue;
+		}
+		const message = "message" in entry ? entry.message : undefined;
+		if (typeof message !== "object" || message === null || !("role" in message) || message.role !== "user") {
+			continue;
+		}
+		return getMessageText("content" in message ? message.content : undefined);
+	}
+	return "";
+}
+
+export function buildExecutionPlan(
+	args: string[],
+	options: { implicitSessionActive: boolean; implicitSessionName: string; useActiveSession: boolean },
+): ExecutionPlan {
+	const commandInfo = parseCommandInfo(args);
+	const explicitSessionName = extractExplicitSessionName(args);
+	const startupScopedFlags = getStartupScopedFlags(args);
+	const effectiveArgs = args.includes("--json") ? [] : ["--json"];
+	let sessionName = explicitSessionName;
+	let usedImplicitSession = false;
+	let validationError: string | undefined;
+
+	if (!explicitSessionName && options.useActiveSession) {
+		if (options.implicitSessionActive && startupScopedFlags.length > 0) {
+			validationError = [
+				`The current implicit agent-browser session is already running, so startup-scoped flags ${startupScopedFlags.join(", ")} would be ignored by upstream agent-browser.`,
+				"Reuse the existing implicit session without those flags, or start a fresh upstream session explicitly with `--session ...` (or `useActiveSession: false`) for a new launch.",
+			].join(" ");
+		} else {
+			effectiveArgs.push("--session", options.implicitSessionName);
+			sessionName = options.implicitSessionName;
+			usedImplicitSession = true;
+		}
+	}
+
+	effectiveArgs.push(...args);
+
+	return {
+		commandInfo,
+		effectiveArgs,
+		sessionName,
+		startupScopedFlags,
+		usedImplicitSession,
+		validationError,
+	};
+}
+
+export function parseCommandInfo(args: string[]): CommandInfo {
+	const commands: string[] = [];
+
+	for (let index = 0; index < args.length; index += 1) {
+		const token = args[index];
+		if (token.startsWith("--session=")) {
+			continue;
+		}
+		if (token.startsWith("-")) {
+			const normalizedToken = token.split("=", 1)[0] ?? token;
+			if (GLOBAL_FLAGS_WITH_VALUES.has(normalizedToken) && !token.includes("=")) {
+				index += 1;
+			}
+			continue;
+		}
+		commands.push(token);
+		if (commands.length === 2) {
+			break;
+		}
+	}
+
+	return { command: commands[0], subcommand: commands[1] };
+}
+
+export function getImageMimeType(filePath: string): string | undefined {
+	const extension = filePath.toLowerCase().slice(filePath.lastIndexOf("."));
+	return IMAGE_EXTENSION_TO_MIME_TYPE[extension];
+}

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

@@ -0,0 +1,93 @@
+/**
+ * Purpose: Create private temporary files for the pi-agent-browser extension without leaking artifacts broadly on disk.
+ * Responsibilities: Maintain a process-private temp root, prune stale temp roots from prior runs, create securely permissioned temp files, and best-effort clean the current run's temp root on process exit.
+ * Scope: Temporary artifact lifecycle only; callers decide what data to write and when to delete long-lived references.
+ * Usage: Imported by result/process helpers when they need secure spill files instead of world-readable shared tmp paths.
+ * Invariants/Assumptions: Temp artifacts live under the OS temp directory, the active run uses a dedicated 0700 directory, and files are created with exclusive 0600 permissions.
+ */
+
+import { randomBytes } from "node:crypto";
+import { chmod, mkdtemp, open, readdir, rm, stat } from "node:fs/promises";
+import { rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const TEMP_ROOT_PREFIX = "pi-agent-browser-";
+const STALE_TEMP_ROOT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+
+let sessionTempRootPromise: Promise<string> | undefined;
+let exitCleanupRegistered = false;
+
+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;
+
+	await Promise.all(
+		entries
+			.filter((entry) => entry.isDirectory() && entry.name.startsWith(TEMP_ROOT_PREFIX))
+			.map(async (entry) => {
+				const path = join(tmpdir(), entry.name);
+				if (path === currentTempRoot) return;
+				const stats = await stat(path).catch(() => undefined);
+				if (!stats || stats.mtimeMs >= cutoffTime) return;
+				await rm(path, { force: true, recursive: true }).catch(() => undefined);
+			}),
+	);
+}
+
+function registerExitCleanup(tempRoot: string): void {
+	if (exitCleanupRegistered) return;
+	exitCleanupRegistered = true;
+	process.once("exit", () => {
+		try {
+			rmSync(tempRoot, { force: true, recursive: true });
+		} catch {
+			// Best-effort cleanup only.
+		}
+	});
+}
+
+export async function cleanupSecureTempArtifacts(): Promise<void> {
+	const tempRoot = await sessionTempRootPromise?.catch(() => undefined);
+	sessionTempRootPromise = undefined;
+	if (!tempRoot) return;
+	await rm(tempRoot, { force: true, recursive: true }).catch(() => undefined);
+}
+
+async function getSessionTempRoot(): Promise<string> {
+	if (!sessionTempRootPromise) {
+		sessionTempRootPromise = (async () => {
+			await pruneStaleTempRoots(undefined);
+			const tempRoot = await mkdtemp(join(tmpdir(), TEMP_ROOT_PREFIX));
+			await chmod(tempRoot, 0o700).catch(() => undefined);
+			registerExitCleanup(tempRoot);
+			return tempRoot;
+		})();
+	}
+
+	const tempRoot = await sessionTempRootPromise;
+	await pruneStaleTempRoots(tempRoot).catch(() => undefined);
+	return tempRoot;
+}
+
+export async function openSecureTempFile(prefix: string, suffix: string): Promise<{ fileHandle: Awaited<ReturnType<typeof open>>; path: string }> {
+	const tempRoot = await getSessionTempRoot();
+	const path = join(tempRoot, `${prefix}-${randomBytes(8).toString("hex")}${suffix}`);
+	const fileHandle = await open(path, "wx", 0o600);
+	return { fileHandle, path };
+}
+
+export async function writeSecureTempFile(options: {
+	content: string | Uint8Array;
+	prefix: string;
+	suffix: string;
+}): Promise<string> {
+	const { content, prefix, suffix } = options;
+	const { fileHandle, path } = await openSecureTempFile(prefix, suffix);
+	try {
+		await fileHandle.writeFile(content);
+	} finally {
+		await fileHandle.close();
+	}
+	return path;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "pi-agent-browser-native",
+  "version": "0.1.1",
+  "description": "Native pi integration for agent-browser",
+  "type": "module",
+  "author": "Mitch Fultz (https://github.com/fitchmultz)",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "extension",
+    "agent-browser",
+    "browser-automation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fitchmultz/pi-agent-browser.git"
+  },
+  "homepage": "https://github.com/fitchmultz/pi-agent-browser#readme",
+  "bugs": {
+    "url": "https://github.com/fitchmultz/pi-agent-browser/issues"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "files": [
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/ARCHITECTURE.md",
+    "docs/RELEASE.md",
+    "docs/REQUIREMENTS.md",
+    "docs/TOOL_CONTRACT.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/agent-browser/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.66.1",
+    "@sinclair/typebox": "^0.34.49",
+    "@types/node": "^25.5.2",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "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"
+  }
+}