pi-agent-browser-native 0.2.72 → 0.2.75

package/dist/extensions/agent-browser/lib/launch-scoped-flags.js

@@ -1,8 +1,10 @@
 /**
  * Purpose: Canonical launch-scoped agent-browser flag metadata shared by runtime planning and agent-facing guidance.
- * Responsibilities: Define which upstream flags require a fresh launch, explain why, and expose stable guidance labels.
- * Scope: Metadata only; argv parsing and execution planning live in runtime.ts.
+ * Responsibilities: Define which upstream flags require a fresh launch, explain why, expose stable guidance labels, and share launch-token detection used by runtime and managed restore policy.
+ * Scope: Launch-scoped metadata and token classification; broader execution planning lives in runtime.ts.
  */
+import { findCommandStartIndex } from "./argv-descriptor.js";
+import { isBooleanFlagEnabled, optionalGlobalValueFlagConsumesNext } from "./argv-grammar.js";
 export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
     {
         flag: "--auto-connect",
@@ -88,3 +90,87 @@ export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
 export const LAUNCH_SCOPED_FLAGS = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition) => definition.flag);
 export const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAGS.join(", ");
 export const OPEN_RESULT_TAB_CORRECTION_FLAGS = new Set(["--profile", "--restore", "--session-name", "--state"]);
+/** Launch modes that must never be combined with wrapper-managed restore state. */
+export const MANAGED_RESTORE_INCOMPATIBLE_FLAGS = [
+    "--restore",
+    "--restore-save",
+    "--restore-check-url",
+    "--restore-check-text",
+    "--restore-check-fn",
+    "--allowed-domains",
+    "--profile",
+    "--state",
+    "--cdp",
+    "--auto-connect",
+    "--session-name",
+    "--provider",
+    "-p",
+    "--executable-path",
+    "--extension",
+    "--init-script",
+    "--enable",
+    "--args",
+    "--user-agent",
+    "--proxy",
+    "--proxy-bypass",
+    "--ignore-https-errors",
+    "--allow-file-access",
+    "--webgpu",
+    "--device",
+    "--engine",
+];
+/** Nonempty upstream env defaults that can replace or mutate the browser receiving restored state. */
+export const MANAGED_RESTORE_INCOMPATIBLE_ENVS = [
+    "AGENT_BROWSER_RESTORE",
+    "AGENT_BROWSER_RESTORE_SAVE",
+    "AGENT_BROWSER_RESTORE_CHECK_URL",
+    "AGENT_BROWSER_RESTORE_CHECK_TEXT",
+    "AGENT_BROWSER_RESTORE_CHECK_FN",
+    "AGENT_BROWSER_ALLOWED_DOMAINS",
+    "AGENT_BROWSER_PROFILE",
+    "AGENT_BROWSER_STATE",
+    "AGENT_BROWSER_CDP",
+    "AGENT_BROWSER_NAMESPACE",
+    "AGENT_BROWSER_SESSION_NAME",
+    "AGENT_BROWSER_PROVIDER",
+    "AGENT_BROWSER_EXECUTABLE_PATH",
+    "AGENT_BROWSER_EXTENSIONS",
+    "AGENT_BROWSER_INIT_SCRIPTS",
+    "AGENT_BROWSER_ENABLE",
+    "AGENT_BROWSER_ARGS",
+    "AGENT_BROWSER_USER_AGENT",
+    "AGENT_BROWSER_PROXY",
+    "AGENT_BROWSER_PROXY_BYPASS",
+    "AGENT_BROWSER_PLUGINS",
+    "AGENT_BROWSER_IOS_DEVICE",
+    "AGENT_BROWSER_IOS_UDID",
+    "AGENT_BROWSER_ENGINE",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+];
+/** Boolean launch mutators block restore only when enabled. */
+export const MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS = [
+    "AGENT_BROWSER_AUTO_CONNECT",
+    "AGENT_BROWSER_IGNORE_HTTPS_ERRORS",
+    "AGENT_BROWSER_ALLOW_FILE_ACCESS",
+    "AGENT_BROWSER_WEBGPU",
+];
+export function hasLaunchScopedFlagToken(args, flag) {
+    const commandStartIndex = findCommandStartIndex(args);
+    const command = commandStartIndex === undefined ? undefined : args[commandStartIndex];
+    return args.some((token, index) => {
+        if (token !== flag && !token.startsWith(`${flag}=`))
+            return false;
+        if (flag === "--auto-connect")
+            return isBooleanFlagEnabled(args, flag);
+        if (flag === "--restore" && token === "--restore" && optionalGlobalValueFlagConsumesNext(flag, args[index + 1]))
+            return true;
+        if (flag === "--state" && command === "wait" && commandStartIndex !== undefined && index > commandStartIndex)
+            return false;
+        return true;
+    });
+}

package/dist/extensions/agent-browser/lib/managed-session-capabilities.js

@@ -0,0 +1,22 @@
+// Purpose: Identify and redact wrapper-owned managed restore capabilities.
+// Scope: Pure string helpers shared by storage, policy, and presentation paths.
+const MANAGED_SESSION_RESTORE_KEY_PATTERN = /piab-r(?:2)?-[a-f\d]{32}/gi;
+const MANAGED_SESSION_RESTORE_KEY_EXACT_PATTERN = /^piab-r2-[a-f\d]{32}$/i;
+const WRAPPER_MANAGED_SESSION_PREFIX = "piab-";
+export function isWrapperManagedSessionName(value) {
+    return typeof value === "string" && value.toLowerCase().startsWith(WRAPPER_MANAGED_SESSION_PREFIX);
+}
+export function isManagedSessionRestoreKey(value) {
+    return typeof value === "string" && MANAGED_SESSION_RESTORE_KEY_EXACT_PATTERN.test(value);
+}
+export function extractManagedSessionRestoreKeys(value) {
+    return [...new Set(value.match(MANAGED_SESSION_RESTORE_KEY_PATTERN)?.map((key) => key.toLowerCase()) ?? [])];
+}
+export function containsManagedSessionRestoreKey(value) {
+    MANAGED_SESSION_RESTORE_KEY_PATTERN.lastIndex = 0;
+    return MANAGED_SESSION_RESTORE_KEY_PATTERN.test(value);
+}
+export function redactManagedSessionRestoreKeys(value) {
+    MANAGED_SESSION_RESTORE_KEY_PATTERN.lastIndex = 0;
+    return value.replace(MANAGED_SESSION_RESTORE_KEY_PATTERN, "[REDACTED MANAGED STATE]");
+}

package/dist/extensions/agent-browser/lib/managed-session-policy-lock.js

@@ -0,0 +1,432 @@
+// Purpose: Serialize wrapper-owned daemon policy decisions across cooperating Pi processes.
+// Responsibilities: Elect one live claim, bridge the pre-update v2 path, recover proven-dead current-protocol artifacts, and release only the caller's immutable token.
+// Scope: Wrapper coordination only; agent-browser never reads these claims.
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { canonicalizeAgentBrowserNamespace, getAgentBrowserSessionIdentityKey } from "./argv-grammar.js";
+import { processStartIdentitiesMatch, readProcessStartIdentity } from "./process-identity.js";
+const POLICY_LOCK_WAIT_MS = 1_000;
+const POLICY_LOCK_RETRY_MS = 10;
+const POLICY_LOCK_MAX_BYTES = 4_096;
+const LOCK_OWNER_FILE = "owner.json";
+const LOCK_TICKET_FILE = "ticket.json";
+function getCoordinationDirectory(platform = process.platform) {
+    if (platform !== "win32") {
+        const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+        return `/tmp/pi-agent-browser-policy${uid === undefined ? "" : `-${uid}`}`;
+    }
+    const user = process.env.USERNAME ?? process.env.USER ?? "unknown";
+    const suffix = createHash("sha256").update(user).digest("hex").slice(0, 12);
+    return join(tmpdir(), `pi-agent-browser-policy-${suffix}`);
+}
+async function ensureCoordinationDirectory(path, platform) {
+    try {
+        try {
+            await mkdir(path, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                return false;
+        }
+        const entry = await lstat(path);
+        if (entry.isSymbolicLink() || !entry.isDirectory())
+            return false;
+        if (platform !== "win32") {
+            const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+            if (uid === undefined || entry.uid !== uid || (entry.mode & 0o077) !== 0)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getPolicyLockDigest(sessionName, namespace) {
+    const identity = getAgentBrowserSessionIdentityKey(sessionName, canonicalizeAgentBrowserNamespace(namespace));
+    return createHash("sha256").update(identity).digest("hex");
+}
+export function getManagedSessionPolicyLockPath(sessionName, namespace) {
+    return join(getCoordinationDirectory(), `.pi-agent-browser-policy-${getPolicyLockDigest(sessionName, namespace)}.lock-v3`);
+}
+export function getLegacyManagedSessionPolicyLockPath(sessionName, namespace) {
+    return join(getCoordinationDirectory(), `.pi-agent-browser-policy-${getPolicyLockDigest(sessionName, namespace)}.lock-v2`);
+}
+function parseOwner(content) {
+    if (Buffer.byteLength(content) > POLICY_LOCK_MAX_BYTES)
+        return undefined;
+    try {
+        const parsed = JSON.parse(content);
+        return parsed.version === 3
+            && Number.isSafeInteger(parsed.pid) && (parsed.pid ?? 0) > 0
+            && typeof parsed.startIdentity === "string" && parsed.startIdentity.length > 0
+            && typeof parsed.token === "string" && parsed.token.length > 0
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseLegacyBridgeOwner(content) {
+    if (Buffer.byteLength(content) > POLICY_LOCK_MAX_BYTES)
+        return undefined;
+    try {
+        const parsed = JSON.parse(content);
+        return (parsed.version === 2 || parsed.version === 3)
+            && Number.isSafeInteger(parsed.pid) && (parsed.pid ?? 0) > 0
+            && typeof parsed.startIdentity === "string" && parsed.startIdentity.length > 0
+            && typeof parsed.token === "string" && parsed.token.length > 0
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseTicket(content, token) {
+    if (Buffer.byteLength(content) > POLICY_LOCK_MAX_BYTES)
+        return undefined;
+    try {
+        const parsed = JSON.parse(content);
+        return parsed.version === 3
+            && parsed.token === token
+            && Number.isSafeInteger(parsed.ticket)
+            && (parsed.ticket ?? 0) > 0
+            ? parsed.ticket
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readClaim(path) {
+    try {
+        const directory = await lstat(path);
+        const ownerPath = join(path, LOCK_OWNER_FILE);
+        const ownerEntry = await lstat(ownerPath);
+        if (!directory.isDirectory() || directory.isSymbolicLink() || !ownerEntry.isFile() || ownerEntry.isSymbolicLink())
+            return undefined;
+        if (ownerEntry.size > POLICY_LOCK_MAX_BYTES)
+            return undefined;
+        if (process.platform !== "win32") {
+            const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+            if (uid === undefined || directory.uid !== uid || ownerEntry.uid !== uid || (directory.mode & 0o077) !== 0 || (ownerEntry.mode & 0o177) !== 0)
+                return undefined;
+        }
+        const owner = parseOwner(await readFile(ownerPath, "utf8"));
+        if (!owner)
+            return undefined;
+        const ticketPath = join(path, LOCK_TICKET_FILE);
+        try {
+            const ticketEntry = await lstat(ticketPath);
+            if (!ticketEntry.isFile() || ticketEntry.isSymbolicLink() || ticketEntry.size > POLICY_LOCK_MAX_BYTES)
+                return undefined;
+            if (process.platform !== "win32") {
+                const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+                if (uid === undefined || ticketEntry.uid !== uid || (ticketEntry.mode & 0o177) !== 0)
+                    return undefined;
+            }
+            const ticket = parseTicket(await readFile(ticketPath, "utf8"), owner.token);
+            return ticket === undefined ? undefined : { owner, path, ticket };
+        }
+        catch (error) {
+            return error.code === "ENOENT" ? { owner, path, ticket: null } : undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readLegacyBridgeOwner(path) {
+    try {
+        const directory = await lstat(path);
+        const ownerPath = join(path, LOCK_OWNER_FILE);
+        const ownerEntry = await lstat(ownerPath);
+        if (!directory.isDirectory() || directory.isSymbolicLink() || !ownerEntry.isFile() || ownerEntry.isSymbolicLink())
+            return undefined;
+        if (ownerEntry.size > POLICY_LOCK_MAX_BYTES)
+            return undefined;
+        if (process.platform !== "win32") {
+            const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+            if (uid === undefined || directory.uid !== uid || ownerEntry.uid !== uid || (directory.mode & 0o077) !== 0 || (ownerEntry.mode & 0o177) !== 0)
+                return undefined;
+        }
+        return parseLegacyBridgeOwner(await readFile(ownerPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readClaims(basePath) {
+    const directory = dirname(basePath);
+    const prefix = `${basename(basePath)}.claim-`;
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return undefined;
+    }
+    const claims = [];
+    for (const name of names.filter((candidate) => candidate.startsWith(prefix))) {
+        const path = join(directory, name);
+        const claim = await readClaim(path);
+        if (!claim) {
+            try {
+                await lstat(path);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+            }
+            return undefined;
+        }
+        if (name !== `${prefix}${claim.owner.token}`)
+            return undefined;
+        claims.push(claim);
+    }
+    return claims;
+}
+async function ownerAlive(owner) {
+    try {
+        process.kill(owner.pid, 0);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return false;
+        if (code !== "EPERM")
+            return undefined;
+    }
+    const current = await readProcessStartIdentity(owner.pid);
+    return current === undefined ? undefined : processStartIdentitiesMatch(owner.startIdentity, current);
+}
+async function removeClaimOwnedBy(path, token) {
+    const current = await readClaim(path);
+    if (current?.owner.token !== token)
+        return false;
+    const movedPath = join(dirname(path), `.pi-agent-browser-policy-remove-${token}-${randomUUID()}`);
+    try {
+        await rename(path, movedPath);
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+    const moved = await readClaim(movedPath);
+    if (moved?.owner.token !== token) {
+        try {
+            await rename(movedPath, path);
+        }
+        catch { }
+        return false;
+    }
+    await rm(movedPath, { force: true, recursive: true });
+    return true;
+}
+async function removeLegacyBridgeOwnedBy(path, token) {
+    const current = await readLegacyBridgeOwner(path);
+    if (current?.version !== 3 || current.token !== token)
+        return false;
+    const movedPath = join(dirname(path), `.pi-agent-browser-policy-bridge-remove-${token}-${randomUUID()}`);
+    try {
+        await rename(path, movedPath);
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+    const moved = await readLegacyBridgeOwner(movedPath);
+    if (moved?.version !== 3 || moved.token !== token) {
+        try {
+            await rename(movedPath, path);
+        }
+        catch { }
+        return false;
+    }
+    await rm(movedPath, { force: true, recursive: true });
+    return true;
+}
+async function cleanDeadPolicyArtifacts(directory) {
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return;
+    }
+    for (const name of names.filter((candidate) => candidate.startsWith(".pi-agent-browser-policy-remove-")
+        || candidate.startsWith(".pi-agent-browser-policy-bridge-remove-")
+        || candidate.includes(".lock-v2.bridge-candidate-")
+        || candidate.includes(".lock-v2.candidate-")
+        || candidate.includes(".lock-v3.candidate-"))) {
+        const path = join(directory, name);
+        const owner = await readLegacyBridgeOwner(path);
+        if (owner && await ownerAlive(owner) === false)
+            await rm(path, { force: true, recursive: true }).catch(() => undefined);
+    }
+}
+async function hasLegacyV2Contender(path) {
+    try {
+        const prefix = `${basename(path)}.candidate-`;
+        return (await readdir(dirname(path))).some((name) => name.startsWith(prefix));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function acquireLegacyPolicyBridge(options) {
+    const path = getLegacyManagedSessionPolicyLockPath(options.sessionName, options.namespace);
+    const candidatePath = `${path}.bridge-candidate-${options.owner.token}`;
+    try {
+        await mkdir(candidatePath, { mode: 0o700 });
+        await writeFile(join(candidatePath, LOCK_OWNER_FILE), JSON.stringify(options.owner), { encoding: "utf8", flag: "wx", mode: 0o600 });
+        while (!options.signal?.aborted) {
+            const legacyContender = await hasLegacyV2Contender(path);
+            if (legacyContender === undefined)
+                return undefined;
+            if (legacyContender) {
+                if (Date.now() >= options.deadline)
+                    return undefined;
+                await waitForRetry(options.signal);
+                continue;
+            }
+            try {
+                await rename(candidatePath, path);
+                const installed = await readLegacyBridgeOwner(path);
+                return installed?.version === 3 && installed.token === options.owner.token
+                    ? { release: async () => { await removeLegacyBridgeOwnedBy(path, options.owner.token); } }
+                    : undefined;
+            }
+            catch (error) {
+                if (!["EACCES", "EEXIST", "ENOTEMPTY", "EPERM"].includes(error.code ?? ""))
+                    return undefined;
+            }
+            const observed = await readLegacyBridgeOwner(path);
+            if (!observed)
+                return undefined;
+            if (observed.version === 3 && await ownerAlive(observed) === false) {
+                if (await removeLegacyBridgeOwnedBy(path, observed.token))
+                    continue;
+            }
+            if (Date.now() >= options.deadline)
+                return undefined;
+            await waitForRetry(options.signal);
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await rm(candidatePath, { force: true, recursive: true }).catch(() => undefined);
+    }
+}
+function claimPrecedes(left, right) {
+    if (left.ticket === null)
+        return true;
+    if (right.ticket === null)
+        return false;
+    return left.ticket < right.ticket || (left.ticket === right.ticket && left.owner.token < right.owner.token);
+}
+function waitForRetry(signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(done, POLICY_LOCK_RETRY_MS);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+export async function acquireManagedSessionPolicyLock(options) {
+    if (options.signal?.aborted)
+        return undefined;
+    const platform = process.platform;
+    const directory = getCoordinationDirectory(platform);
+    if (!await ensureCoordinationDirectory(directory, platform))
+        return undefined;
+    const basePath = getManagedSessionPolicyLockPath(options.sessionName, options.namespace);
+    const token = randomUUID();
+    const startIdentity = await readProcessStartIdentity(process.pid);
+    if (!startIdentity)
+        return undefined;
+    const owner = { pid: process.pid, startIdentity, token, version: 3 };
+    const candidatePath = `${basePath}.candidate-${token}`;
+    const claimPath = `${basePath}.claim-${token}`;
+    let claimPublished = false;
+    let legacyBridge;
+    let lockAcquired = false;
+    try {
+        await mkdir(candidatePath, { mode: 0o700 });
+        await writeFile(join(candidatePath, LOCK_OWNER_FILE), JSON.stringify(owner), { encoding: "utf8", flag: "wx", mode: 0o600 });
+        await rename(candidatePath, claimPath);
+        claimPublished = true;
+        const initialClaims = await readClaims(basePath);
+        if (!initialClaims)
+            return undefined;
+        const maxTicket = initialClaims.reduce((max, claim) => claim.ticket === null ? max : Math.max(max, claim.ticket), 0);
+        if (!Number.isSafeInteger(maxTicket + 1))
+            return undefined;
+        const ticket = { ticket: maxTicket + 1, token, version: 3 };
+        const ticketCandidatePath = join(claimPath, `.ticket-${token}.tmp`);
+        await writeFile(ticketCandidatePath, JSON.stringify(ticket), { encoding: "utf8", flag: "wx", mode: 0o600 });
+        await rename(ticketCandidatePath, join(claimPath, LOCK_TICKET_FILE));
+        const deadline = Date.now() + (options.timeoutMs ?? POLICY_LOCK_WAIT_MS);
+        while (!options.signal?.aborted) {
+            const claims = await readClaims(basePath);
+            if (!claims)
+                return undefined;
+            const ownClaim = claims.find((claim) => claim.owner.token === token);
+            if (!ownClaim || ownClaim.ticket !== ticket.ticket)
+                return undefined;
+            let blocked = false;
+            for (const claim of claims) {
+                if (claim.owner.token === token || !claimPrecedes(claim, ownClaim))
+                    continue;
+                const alive = await ownerAlive(claim.owner);
+                if (alive === false) {
+                    await removeClaimOwnedBy(claim.path, claim.owner.token);
+                    continue;
+                }
+                blocked = true;
+                break;
+            }
+            if (!blocked) {
+                await cleanDeadPolicyArtifacts(directory);
+                legacyBridge = await acquireLegacyPolicyBridge({
+                    deadline,
+                    owner,
+                    signal: options.signal,
+                    sessionName: options.sessionName,
+                    namespace: options.namespace,
+                });
+                if (!legacyBridge)
+                    return undefined;
+                lockAcquired = true;
+                return { release: async () => {
+                        await legacyBridge?.release();
+                        await removeClaimOwnedBy(claimPath, token);
+                    } };
+            }
+            if (Date.now() >= deadline)
+                return undefined;
+            await waitForRetry(options.signal);
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await rm(candidatePath, { force: true, recursive: true }).catch(() => undefined);
+        if (!lockAcquired)
+            await legacyBridge?.release();
+        if (claimPublished && !lockAcquired)
+            await removeClaimOwnedBy(claimPath, token);
+    }
+}