pi-agent-browser-native 0.9.3 → 0.9.5

package/dist/extensions/agent-browser/lib/temp-artifact-budget.js

@@ -0,0 +1,81 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { parsePositiveInteger } from "./parsing.js";
+const DEFAULT_MAX_BYTES = 32 * 1_024 * 1_024;
+export function getTempArtifactByteLength(content) {
+    return typeof content === "string" ? Buffer.byteLength(content) : content.byteLength;
+}
+export async function listArtifactFiles(directory, excludedNames = new Set()) {
+    const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || excludedNames.has(entry.name)) {
+            continue;
+        }
+        const path = join(directory, entry.name);
+        // Bound filesystem work and retain the original ordered scan before eviction.
+        // oxlint-disable-next-line no-await-in-loop
+        const stats = await stat(path).catch(() => undefined);
+        if (stats?.isFile() === true) {
+            files.push({ mtimeMs: stats.mtimeMs, path, size: stats.size });
+        }
+    }
+    return files;
+}
+export function getSecureTempRootMaxBytes(env = process.env) {
+    return parsePositiveInteger(env.PI_AGENT_BROWSER_TEMP_ROOT_MAX_BYTES) ?? DEFAULT_MAX_BYTES;
+}
+export function getPersistentSessionArtifactMaxBytes(env = process.env) {
+    if (env.PI_AGENT_BROWSER_SESSION_ARTIFACT_MAX_BYTES?.trim() === "0") {
+        return 0;
+    }
+    return parsePositiveInteger(env.PI_AGENT_BROWSER_SESSION_ARTIFACT_MAX_BYTES) ?? DEFAULT_MAX_BYTES;
+}
+export async function assertSecureTempRootBudget(tempRoot, additionalBytes) {
+    if (additionalBytes <= 0) {
+        return;
+    }
+    const files = await listArtifactFiles(tempRoot, new Set([".pi-agent-browser-owner.json"]));
+    const currentBytes = files.reduce((total, file) => total + file.size, 0);
+    const maxBytes = getSecureTempRootMaxBytes();
+    const nextBytes = currentBytes + additionalBytes;
+    if (nextBytes > maxBytes) {
+        throw new Error(`pi-agent-browser temp spill budget exceeded (${nextBytes} bytes > ${maxBytes} byte limit).`);
+    }
+}
+export async function prunePersistentSessionArtifactsToBudget(sessionArtifactDir, additionalBytes, protectedPaths) {
+    if (additionalBytes <= 0) {
+        return [];
+    }
+    const maxBytes = getPersistentSessionArtifactMaxBytes();
+    if (maxBytes === 0) {
+        return [];
+    }
+    const files = await listArtifactFiles(sessionArtifactDir);
+    let totalBytes = files.reduce((total, file) => total + file.size, 0);
+    if (totalBytes + additionalBytes <= maxBytes) {
+        return [];
+    }
+    const evictedArtifacts = [];
+    files.sort((left, right) => {
+        const time = left.mtimeMs - right.mtimeMs;
+        return time === 0 ? left.path.localeCompare(right.path) : time;
+    });
+    for (const file of files) {
+        if (protectedPaths.has(file.path)) {
+            continue;
+        }
+        // Evict oldest first and stop immediately once the required budget is available.
+        // oxlint-disable-next-line no-await-in-loop
+        const removed = await rm(file.path, { force: true }).then(() => true, () => false);
+        if (!removed) {
+            continue;
+        }
+        evictedArtifacts.push({ mtimeMs: file.mtimeMs, path: file.path, sizeBytes: file.size });
+        totalBytes -= file.size;
+        if (totalBytes + additionalBytes <= maxBytes) {
+            return evictedArtifacts;
+        }
+    }
+    throw new Error(`pi-agent-browser persisted spill budget exceeded (${totalBytes + additionalBytes} bytes > ${maxBytes} byte limit).`);
+}

package/dist/extensions/agent-browser/lib/temp-mutation-queue.js

@@ -0,0 +1,7 @@
+let tempMutationQueue = Promise.resolve();
+/** One queue owns all root cleanup, preservation, spill writes and persistent eviction. */
+export function enqueueTempMutation(task) {
+    const nextTask = tempMutationQueue.then(task, task);
+    tempMutationQueue = nextTask.then(() => undefined, () => undefined);
+    return nextTask;
+}

package/dist/extensions/agent-browser/lib/temp-root-ownership.js

@@ -0,0 +1,234 @@
+import { chmod, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { isRecord } from "./parsing.js";
+import { processStartIdentitiesMatch, readProcessStartIdentity } from "./process-identity.js";
+import { getErrorCode } from "./process-errors.js";
+export const TEMP_ROOT_MARKER_FILE_NAME = ".pi-agent-browser-owner.json";
+const TEMP_ROOT_MARKER_KIND = "pi-agent-browser-temp-root";
+const TEMP_ROOT_MARKER_VERSION = 2;
+export function getCurrentProcessUid() {
+    return typeof process.getuid === "function" ? process.getuid() : undefined;
+}
+function isPositiveFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function isProtectedTempChildName(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    if (value === "" || value === "." || value === ".." || value === TEMP_ROOT_MARKER_FILE_NAME) {
+        return false;
+    }
+    if (value.includes("/") || value.includes("\\")) {
+        return false;
+    }
+    return basename(value) === value;
+}
+function isTempRootOwnershipRecord(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (value.kind !== TEMP_ROOT_MARKER_KIND || value.version !== TEMP_ROOT_MARKER_VERSION) {
+        return false;
+    }
+    if (!isPositiveFiniteNumber(value.createdAtMs)) {
+        return false;
+    }
+    return validLeaseAndProcess(value) && validOwnershipAndChildren(value);
+}
+function validLeaseAndProcess(value) {
+    if (value.leaseUpdatedAtMs !== undefined && !isPositiveFiniteNumber(value.leaseUpdatedAtMs)) {
+        return false;
+    }
+    if (value.ownerPid !== undefined &&
+        (typeof value.ownerPid !== "number" ||
+            !Number.isSafeInteger(value.ownerPid) ||
+            value.ownerPid <= 0)) {
+        return false;
+    }
+    return (value.ownerProcessStartIdentity === undefined ||
+        (typeof value.ownerProcessStartIdentity === "string" &&
+            value.ownerProcessStartIdentity.trim() !== ""));
+}
+function validOwnershipAndChildren(value) {
+    if (value.ownerUid !== undefined &&
+        (typeof value.ownerUid !== "number" ||
+            !Number.isSafeInteger(value.ownerUid) ||
+            value.ownerUid < 0)) {
+        return false;
+    }
+    if (value.protectedChildNames === undefined) {
+        return true;
+    }
+    if (!Array.isArray(value.protectedChildNames)) {
+        return false;
+    }
+    const names = value.protectedChildNames;
+    return names.every(isProtectedTempChildName);
+}
+export async function readTempRootOwnershipMarker(tempRoot) {
+    try {
+        const markerText = await readFile(join(tempRoot, TEMP_ROOT_MARKER_FILE_NAME), "utf8");
+        const parsed = JSON.parse(markerText);
+        return isTempRootOwnershipRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function getProtectedTempChildName(tempRoot, childPath) {
+    const normalizedTempRoot = resolve(tempRoot);
+    const normalizedChildPath = resolve(childPath);
+    if (dirname(normalizedChildPath) !== normalizedTempRoot) {
+        return undefined;
+    }
+    const childName = basename(normalizedChildPath);
+    // A string can still be an unsafe child name; validation checks separators and reserved names.
+    // oxlint-disable-next-line typescript/no-unnecessary-condition
+    return isProtectedTempChildName(childName) ? childName : undefined;
+}
+function normalizeProtectedChildNames(names) {
+    return [...new Set([...names].filter(isProtectedTempChildName))].sort();
+}
+export function getPersistedProtectedChildPaths(tempRoot, ownershipMarker) {
+    const normalizedTempRoot = resolve(tempRoot);
+    return new Set((ownershipMarker?.protectedChildNames ?? []).map((childName) => resolve(join(normalizedTempRoot, childName))));
+}
+async function writeTempRootOwnershipMarkerRecord(tempRoot, markerRecord, options = {}) {
+    const markerPath = join(tempRoot, TEMP_ROOT_MARKER_FILE_NAME);
+    await writeFile(markerPath, JSON.stringify(markerRecord, null, 2), {
+        encoding: "utf8",
+        flag: options.flag,
+        mode: 0o600,
+    });
+    await chmod(markerPath, 0o600).catch(() => undefined);
+    return markerPath;
+}
+export async function persistProtectedTempChildren(tempRoot, protectedChildren) {
+    if (protectedChildren.size === 0) {
+        return;
+    }
+    const ownershipMarker = await readTempRootOwnershipMarker(tempRoot);
+    if (!ownershipMarker) {
+        return;
+    }
+    const childNames = normalizeProtectedChildNames([
+        ...(ownershipMarker.protectedChildNames ?? []),
+        ...[...protectedChildren]
+            .map((path) => getProtectedTempChildName(tempRoot, path))
+            .filter((childName) => childName !== undefined),
+    ]);
+    if (childNames.length === 0) {
+        return;
+    }
+    await writeTempRootOwnershipMarkerRecord(tempRoot, {
+        ...ownershipMarker,
+        leaseUpdatedAtMs: Date.now(),
+        protectedChildNames: childNames,
+        version: TEMP_ROOT_MARKER_VERSION,
+    });
+}
+export async function getExistingProtectedChildren(tempRoot, protectedChildren) {
+    const normalizedTempRoot = resolve(tempRoot);
+    const existingChildren = new Set();
+    for (const path of protectedChildren) {
+        const normalizedPath = resolve(path);
+        if (dirname(normalizedPath) !== normalizedTempRoot) {
+            continue;
+        }
+        if (
+        // Scan in bounded sequence instead of opening an unbounded number of filesystem requests.
+        // oxlint-disable-next-line no-await-in-loop
+        await stat(normalizedPath).then((stats) => stats.isDirectory(), () => false)) {
+            existingChildren.add(normalizedPath);
+        }
+    }
+    return existingChildren;
+}
+export async function removeTempRootChildrenExcept(tempRoot, protectedChildren) {
+    const entries = await readdir(tempRoot, { withFileTypes: true }).catch(() => []);
+    await Promise.all(entries.map(async (entry) => {
+        if (entry.name === TEMP_ROOT_MARKER_FILE_NAME) {
+            return;
+        }
+        const entryPath = join(tempRoot, entry.name);
+        if (protectedChildren.has(resolve(entryPath))) {
+            return;
+        }
+        await rm(entryPath, { force: true, recursive: true }).catch(() => undefined);
+    }));
+}
+async function getProcessStartIdentity(pid) {
+    return pid === undefined ? undefined : await readProcessStartIdentity(pid);
+}
+export async function writeSecureTempRootOwnershipMarker(tempRoot, options = {}) {
+    const createdAtMs = options.createdAtMs ?? Date.now();
+    const ownerPid = options.ownerPid ?? process.pid;
+    const markerRecord = {
+        createdAtMs,
+        kind: TEMP_ROOT_MARKER_KIND,
+        leaseUpdatedAtMs: options.leaseUpdatedAtMs ?? createdAtMs,
+        ownerPid,
+        ownerProcessStartIdentity: options.ownerProcessStartIdentity ?? (await getProcessStartIdentity(ownerPid)),
+        ownerUid: getCurrentProcessUid(),
+        version: TEMP_ROOT_MARKER_VERSION,
+    };
+    return await writeTempRootOwnershipMarkerRecord(tempRoot, markerRecord, { flag: "wx" });
+}
+export async function refreshSecureTempRootLease(tempRoot) {
+    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) {
+        const identitiesMatch = processStartIdentitiesMatch(ownershipMarker.ownerProcessStartIdentity, currentProcessStartIdentity);
+        if (!identitiesMatch) {
+            return;
+        }
+    }
+    const refreshedMarker = {
+        ...ownershipMarker,
+        leaseUpdatedAtMs: Date.now(),
+        ownerPid: process.pid,
+        ownerProcessStartIdentity: currentProcessStartIdentity ?? ownershipMarker.ownerProcessStartIdentity,
+        ownerUid: currentUid,
+        version: TEMP_ROOT_MARKER_VERSION,
+    };
+    await writeTempRootOwnershipMarkerRecord(tempRoot, refreshedMarker);
+}
+export async function getMarkerOwnerLiveness(ownershipMarker) {
+    const pid = ownershipMarker.ownerPid;
+    if (pid === undefined) {
+        return "unknown";
+    }
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        const code = getErrorCode(error);
+        if (code === "ESRCH") {
+            return "dead";
+        }
+        if (code !== "EPERM") {
+            return "unknown";
+        }
+    }
+    const currentProcessStartIdentity = await getProcessStartIdentity(pid);
+    if (ownershipMarker.ownerProcessStartIdentity === undefined ||
+        currentProcessStartIdentity === undefined) {
+        return "unknown";
+    }
+    const identitiesMatch = processStartIdentitiesMatch(ownershipMarker.ownerProcessStartIdentity, currentProcessStartIdentity);
+    return identitiesMatch ? "alive" : "dead";
+}

package/dist/extensions/agent-browser/lib/temp-root.js

@@ -0,0 +1,211 @@
+import { randomInt } from "node:crypto";
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { chmod, mkdtemp, readdir, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { enqueueTempMutation } from "./temp-mutation-queue.js";
+import { TEMP_ROOT_MARKER_FILE_NAME, getCurrentProcessUid, readTempRootOwnershipMarker, getProtectedTempChildName, getPersistedProtectedChildPaths, persistProtectedTempChildren, getExistingProtectedChildren, removeTempRootChildrenExcept, getMarkerOwnerLiveness, refreshSecureTempRootLease, writeSecureTempRootOwnershipMarker, } from "./temp-root-ownership.js";
+export { refreshSecureTempRootLease, writeSecureTempRootOwnershipMarker, } from "./temp-root-ownership.js";
+const TEMP_ROOT_PREFIX = "pi-agent-browser-";
+const STALE_TEMP_ROOT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+const STALE_TEMP_ROOT_BATCH_SIZE = 8;
+let lastTempGcName;
+let sessionTempRootPromise;
+let exitCleanupRegistered = false;
+const ownedTempRoots = new Set();
+const protectedTempChildren = new Set();
+function markerMatchesUid(marker, uid) {
+    return uid === undefined || marker.ownerUid === undefined || marker.ownerUid === uid;
+}
+async function pruneTempRoot(path, currentUid, cutoffTime) {
+    const marker = await readTempRootOwnershipMarker(path);
+    if (!marker || !markerMatchesUid(marker, currentUid)) {
+        return;
+    }
+    if ((marker.leaseUpdatedAtMs ?? marker.createdAtMs) >= cutoffTime) {
+        return;
+    }
+    // Preserve ambiguous owner liveness; never delete another live process's files.
+    if ((await getMarkerOwnerLiveness(marker)) !== "dead") {
+        return;
+    }
+    const stats = await stat(path).catch(() => undefined);
+    if (stats?.isDirectory() !== true) {
+        return;
+    }
+    const protectedChildren = await getExistingProtectedChildren(path, getPersistedProtectedChildPaths(path, marker));
+    if (protectedChildren.size > 0) {
+        await removeTempRootChildrenExcept(path, protectedChildren);
+        return;
+    }
+    await rm(path, { force: true, recursive: true }).catch(() => {
+        /* Stale-root cleanup is best-effort. */
+    });
+}
+async function pruneStaleTempRoots(currentTempRoot) {
+    const entries = await readdir(tmpdir(), { withFileTypes: true }).catch(() => []);
+    const cutoffTime = Date.now() - STALE_TEMP_ROOT_MAX_AGE_MS;
+    const currentUid = getCurrentProcessUid();
+    // ponytail: list/sort all names; stream directories if enumeration becomes the bottleneck.
+    const candidates = entries
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith(TEMP_ROOT_PREFIX))
+        .map((entry) => entry.name)
+        .sort();
+    if (candidates.length === 0) {
+        return;
+    }
+    const previousName = lastTempGcName;
+    const start = previousName === undefined
+        ? randomInt(candidates.length)
+        : Math.max(0, candidates.findIndex((name) => name > previousName));
+    const batch = Array.from({ length: Math.min(STALE_TEMP_ROOT_BATCH_SIZE, candidates.length) }, (_, offset) => candidates[(start + offset) % candidates.length]);
+    lastTempGcName = batch.at(-1);
+    await Promise.all(batch.map(async (name) => {
+        const path = join(tmpdir(), name);
+        if (path !== currentTempRoot) {
+            await pruneTempRoot(path, currentUid, cutoffTime);
+        }
+    }));
+}
+function getProtectedChildrenForRoot(tempRoot) {
+    const normalizedTempRoot = resolve(tempRoot);
+    return new Set([...protectedTempChildren].filter((path) => dirname(path) === normalizedTempRoot && existsSync(path)));
+}
+function removeTempRootChildrenExceptSync(tempRoot, protectedChildren) {
+    for (const entry of readdirSync(tempRoot, { withFileTypes: true })) {
+        if (entry.name === TEMP_ROOT_MARKER_FILE_NAME) {
+            continue;
+        }
+        const entryPath = join(tempRoot, entry.name);
+        if (protectedChildren.has(resolve(entryPath))) {
+            continue;
+        }
+        rmSync(entryPath, { force: true, recursive: true });
+    }
+}
+function registerExitCleanup() {
+    if (exitCleanupRegistered) {
+        return;
+    }
+    exitCleanupRegistered = true;
+    process.once("exit", () => {
+        for (const tempRoot of ownedTempRoots) {
+            try {
+                const protectedChildren = getProtectedChildrenForRoot(tempRoot);
+                if (protectedChildren.size === 0) {
+                    rmSync(tempRoot, { force: true, recursive: true });
+                }
+                else {
+                    removeTempRootChildrenExceptSync(tempRoot, protectedChildren);
+                }
+            }
+            catch {
+                /* Best-effort process-exit cleanup. */
+            }
+        }
+    });
+}
+export async function preserveSecureTempDirectory(path) {
+    await enqueueTempMutation(async () => {
+        const childPath = resolve(path);
+        const tempRoot = dirname(childPath);
+        if (!ownedTempRoots.has(tempRoot) ||
+            getProtectedTempChildName(tempRoot, childPath) === undefined ||
+            !(await stat(childPath)).isDirectory()) {
+            throw new Error(`Cannot preserve ${path}; expected an existing child directory of a currently owned temp root.`);
+        }
+        protectedTempChildren.add(childPath);
+        await persistProtectedTempChildren(tempRoot, new Set([childPath]));
+        if (!getPersistedProtectedChildPaths(tempRoot, await readTempRootOwnershipMarker(tempRoot)).has(childPath)) {
+            throw new Error(`Could not persist temp directory preservation for ${path}.`);
+        }
+    });
+}
+function rememberPreservedPaths(tempRoot, paths) {
+    for (const path of paths) {
+        const childName = getProtectedTempChildName(tempRoot, path);
+        if (childName !== undefined && childName.length > 0) {
+            protectedTempChildren.add(resolve(join(tempRoot, childName)));
+        }
+    }
+}
+function forgetMissingPreservedPaths(tempRoot, preservedChildren) {
+    for (const path of protectedTempChildren) {
+        if (dirname(path) === tempRoot && !preservedChildren.has(path)) {
+            protectedTempChildren.delete(path);
+        }
+    }
+}
+export async function cleanupSecureTempArtifacts(options = {}) {
+    await enqueueTempMutation(async () => {
+        const tempRoot = await sessionTempRootPromise?.catch(() => undefined);
+        if (tempRoot === undefined || tempRoot.length === 0) {
+            return;
+        }
+        const normalizedTempRoot = resolve(tempRoot);
+        rememberPreservedPaths(normalizedTempRoot, options.preservePaths ?? []);
+        const preservedChildren = await getExistingProtectedChildren(normalizedTempRoot, protectedTempChildren);
+        forgetMissingPreservedPaths(normalizedTempRoot, preservedChildren);
+        if (preservedChildren.size === 0) {
+            sessionTempRootPromise = undefined;
+            ownedTempRoots.delete(tempRoot);
+            await rm(tempRoot, { force: true, recursive: true }).catch(() => {
+                /* Cleanup failure cannot revive retired ownership. */
+            });
+            return;
+        }
+        await persistProtectedTempChildren(tempRoot, preservedChildren);
+        await removeTempRootChildrenExcept(tempRoot, preservedChildren);
+        await refreshSecureTempRootLease(tempRoot).catch(() => {
+            /* Cleanup retains existing ownership evidence on failed renewal. */
+        });
+    });
+}
+async function allocateSessionTempRoot() {
+    const tempRoot = await mkdtemp(join(tmpdir(), TEMP_ROOT_PREFIX));
+    try {
+        await chmod(tempRoot, 0o700).catch(() => {
+            /* mkdtemp already creates a private root. */
+        });
+        await writeSecureTempRootOwnershipMarker(tempRoot);
+        ownedTempRoots.add(tempRoot);
+        registerExitCleanup();
+        return tempRoot;
+    }
+    catch (error) {
+        await rm(tempRoot, { force: true, recursive: true }).catch(() => {
+            /* Preserve the allocation failure if private-root cleanup also fails. */
+        });
+        throw error;
+    }
+}
+export async function getSessionTempRoot() {
+    sessionTempRootPromise ??= allocateSessionTempRoot().catch((error) => {
+        sessionTempRootPromise = undefined;
+        throw error;
+    });
+    const tempRoot = await sessionTempRootPromise;
+    await refreshSecureTempRootLease(tempRoot).catch(() => {
+        /* A failed refresh leaves the existing marker. */
+    });
+    await pruneStaleTempRoots(tempRoot).catch(() => {
+        /* GC cannot prevent using the owned root. */
+    });
+    return tempRoot;
+}
+export async function getSecureTempChildDirectoryValidationError(path, childPrefix) {
+    const parentDirectory = dirname(path);
+    const childName = path.slice(parentDirectory.length + 1);
+    if (!childName.startsWith(childPrefix)) {
+        return `Refusing to remove ${path}; expected wrapper temp child prefix ${childPrefix}.`;
+    }
+    const marker = await readTempRootOwnershipMarker(parentDirectory);
+    if (!marker) {
+        return `Refusing to remove ${path}; parent directory is not a pi-agent-browser owned temp root.`;
+    }
+    const currentUid = getCurrentProcessUid();
+    if (!markerMatchesUid(marker, currentUid)) {
+        return `Refusing to remove ${path}; parent temp root is owned by uid ${marker.ownerUid ?? "unknown"}, not current uid ${currentUid ?? "unknown"}.`;
+    }
+    return undefined;
+}