pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/browser-execution-claim-storage.js

@@ -0,0 +1,232 @@
+import { randomInt, randomUUID } from "node:crypto";
+import { lstat, readFile, readdir, rename, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { processStartIdentitiesMatch, readProcessStartIdentity } from "./process-identity.js";
+import { getErrorCode } from "./process-errors.js";
+import { parseOwner, parseTicket, POLICY_LOCK_MAX_BYTES, } from "./browser-execution-claim-codec.js";
+export const POLICY_LOCK_WAIT_MS = 1_000;
+export const LOCK_OWNER_FILE = "owner.json";
+export const LOCK_TICKET_FILE = "ticket.json";
+const STALE_CLAIM_MIN_AGE_MS = 30 * 60 * 1_000;
+const POLICY_GC_BATCH_SIZE = 8;
+let lastPolicyGcName;
+function secureEntry(entry, directory) {
+    if (entry.isSymbolicLink() || (directory ? !entry.isDirectory() : !entry.isFile())) {
+        return false;
+    }
+    if (!directory && entry.size > POLICY_LOCK_MAX_BYTES) {
+        return false;
+    }
+    return secureEntryOwnership(entry, directory ? 0o077 : 0o177);
+}
+function secureEntryOwnership(entry, mask) {
+    if (process.platform === "win32") {
+        return true;
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    return uid !== undefined && entry.uid === uid && (entry.mode & mask) === 0;
+}
+async function readClaimTicket(path, owner) {
+    const ticketPath = join(path, LOCK_TICKET_FILE);
+    try {
+        if (!secureEntry(await lstat(ticketPath), false)) {
+            return undefined;
+        }
+        const ticket = parseTicket(await readFile(ticketPath, "utf8"), owner.token);
+        return ticket === undefined ? undefined : { owner, path, ticket };
+    }
+    catch (error) {
+        return getErrorCode(error) === "ENOENT" ? { owner, path, ticket: null } : undefined;
+    }
+}
+export async function readClaim(path) {
+    try {
+        const directory = await lstat(path);
+        const ownerPath = join(path, LOCK_OWNER_FILE);
+        const ownerEntry = await lstat(ownerPath);
+        if (!secureEntry(directory, true) || !secureEntry(ownerEntry, false)) {
+            return undefined;
+        }
+        const owner = parseOwner(await readFile(ownerPath, "utf8"));
+        return owner ? await readClaimTicket(path, owner) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function claimDisappeared(path) {
+    try {
+        await lstat(path);
+        return false;
+    }
+    catch (error) {
+        return getErrorCode(error) === "ENOENT";
+    }
+}
+export 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);
+        // Claim absence must be resolved before accepting the next contender.
+        // oxlint-disable-next-line no-await-in-loop
+        const claim = await readClaim(path);
+        if (!claim) {
+            // A disappearing immutable claim is not a corrupt contender.
+            // oxlint-disable-next-line no-await-in-loop
+            if (await claimDisappeared(path)) {
+                continue;
+            }
+            return undefined;
+        }
+        if (name !== `${prefix}${claim.owner.token}`) {
+            return undefined;
+        }
+        claims.push(claim);
+    }
+    return claims;
+}
+export async function ownerAlive(owner, budget) {
+    try {
+        process.kill(owner.pid, 0);
+    }
+    catch (error) {
+        const code = getErrorCode(error);
+        if (code === "ESRCH") {
+            return false;
+        }
+        if (code !== "EPERM") {
+            return undefined;
+        }
+    }
+    const current = await readProcessStartIdentity(owner.pid, process.platform, budget);
+    return current === undefined
+        ? undefined
+        : processStartIdentitiesMatch(owner.startIdentity, current);
+}
+export function waitForRetry(signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted === true) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(done, 10);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+async function moveOwnedClaim(path, movedPath, token, deadline) {
+    while (true) {
+        // Each retry must revalidate ownership before another move attempt.
+        // oxlint-disable-next-line no-await-in-loop
+        if ((await readClaim(path))?.owner.token !== token) {
+            return undefined;
+        }
+        try {
+            // Windows readers may temporarily hold the directory; moves stay serialized.
+            // oxlint-disable-next-line no-await-in-loop
+            await rename(path, movedPath);
+            return "moved";
+        }
+        catch (error) {
+            const code = getErrorCode(error);
+            if (code === "ENOENT") {
+                return "absent";
+            }
+            if (process.platform !== "win32" || code !== "EPERM" || Date.now() >= deadline) {
+                return undefined;
+            }
+            // Retry only after a bounded pause, then revalidate the same immutable owner.
+            // oxlint-disable-next-line no-await-in-loop
+            await waitForRetry();
+            if (Date.now() >= deadline) {
+                return undefined;
+            }
+        }
+    }
+}
+export async function removeClaimOwnedBy(path, token, deadline = 0) {
+    const movedPath = join(dirname(path), `.pi-agent-browser-policy-remove-${token}-${randomUUID()}`);
+    const movement = await moveOwnedClaim(path, movedPath, token, deadline);
+    if (movement === "absent") {
+        return true;
+    }
+    if (movement !== "moved") {
+        return false;
+    }
+    const moved = await readClaim(movedPath);
+    if (moved?.owner.token !== token) {
+        try {
+            await rename(movedPath, path);
+        }
+        catch {
+            /* An unverified moved claim remains unavailable to contenders. */
+        }
+        return false;
+    }
+    await rm(movedPath, { force: true, recursive: true });
+    return true;
+}
+function gcBatch(names) {
+    // ponytail: list/sort all names; stream directories if enumeration becomes the bottleneck.
+    const candidates = names
+        .filter((name) => name.startsWith(".pi-agent-browser-policy-remove-") ||
+        /^\.pi-agent-browser-policy-[a-f0-9]{64}\.lock-v4\.(?:candidate|claim)-/.test(name))
+        .sort();
+    if (candidates.length === 0) {
+        return [];
+    }
+    const previous = lastPolicyGcName;
+    const start = previous === undefined
+        ? randomInt(candidates.length)
+        : Math.max(0, candidates.findIndex((name) => name > previous));
+    const batch = Array.from({ length: Math.min(POLICY_GC_BATCH_SIZE, candidates.length) }, (_, offset) => candidates[(start + offset) % candidates.length]);
+    lastPolicyGcName = batch.at(-1);
+    return batch;
+}
+async function cleanDeadClaim(directory, name, budget) {
+    const path = join(directory, name);
+    const published = name.includes(".lock-v4.claim-");
+    if (published) {
+        const entry = await lstat(path).catch(() => undefined);
+        if (!entry || entry.mtimeMs >= Date.now() - STALE_CLAIM_MIN_AGE_MS) {
+            return;
+        }
+    }
+    const claim = await readClaim(path);
+    if (!claim || (published && !name.endsWith(`.claim-${claim.owner.token}`))) {
+        return;
+    }
+    if ((await ownerAlive(claim.owner, budget)) === false) {
+        await removeClaimOwnedBy(path, claim.owner.token).catch(() => false);
+    }
+}
+export async function cleanDeadPolicyArtifacts(directory, budget) {
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return;
+    }
+    for (const name of gcBatch(names)) {
+        if (budget.signal?.aborted === true || Date.now() >= (budget.deadline ?? Infinity)) {
+            return;
+        }
+        // Bounded GC respects the acquisition budget between native liveness probes.
+        // oxlint-disable-next-line no-await-in-loop
+        await cleanDeadClaim(directory, name, budget);
+    }
+}

package/dist/extensions/agent-browser/lib/browser-execution-claims.js

@@ -0,0 +1,202 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { getErrorCode } from "./process-errors.js";
+import { join } from "node:path";
+import { readProcessStartIdentity } from "./process-identity.js";
+import { POLICY_LOCK_MAX_BYTES, } from "./browser-execution-claim-codec.js";
+import { ensureCoordinationDirectory, getCoordinationDirectory, getBrowserExecutionLockPath, } from "./browser-execution-identity.js";
+import { cleanDeadPolicyArtifacts, readClaim, readClaims, removeClaimOwnedBy, ownerAlive, waitForRetry, LOCK_OWNER_FILE, LOCK_TICKET_FILE, POLICY_LOCK_WAIT_MS, } from "./browser-execution-claim-storage.js";
+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));
+}
+async function hasPublishedLaterTicket(claim, ownClaim) {
+    if (claim.ticket !== null) {
+        return false;
+    }
+    const current = await readClaim(claim.path);
+    return current?.owner.token === claim.owner.token && !claimPrecedes(current, ownClaim);
+}
+function relevantPredecessor(claim, ownClaim) {
+    if (claim.owner.token === ownClaim.owner.token || !claimPrecedes(claim, ownClaim)) {
+        return false;
+    }
+    const ownSessions = ownClaim.owner.sessionNames;
+    const sessions = claim.owner.sessionNames;
+    return (ownSessions === null ||
+        sessions === null ||
+        ownSessions.some((session) => sessions.includes(session)));
+}
+async function claimBlocks(claim, ownClaim, budget) {
+    if (!relevantPredecessor(claim, ownClaim) || (await hasPublishedLaterTicket(claim, ownClaim))) {
+        return false;
+    }
+    const alive = await ownerAlive(claim.owner, budget);
+    if (alive === false) {
+        await removeClaimOwnedBy(claim.path, claim.owner.token);
+        return false;
+    }
+    // Native identity queries can outlive the whole critical section. Re-read the immutable
+    // claim so an already released owner, or a newly published later ticket, cannot block us.
+    if (!(await claimStillExists(claim.path))) {
+        return false;
+    }
+    return !(await hasPublishedLaterTicket(claim, ownClaim));
+}
+async function claimStillExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        return getErrorCode(error) !== "ENOENT";
+    }
+}
+async function anyPredecessorBlocks(claims, own, budget) {
+    for (const claim of claims) {
+        // Contender inspection/removal is ordered before the next ticket decision.
+        // oxlint-disable-next-line no-await-in-loop
+        if (await claimBlocks(claim, own, budget)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function prepareClaim(identity, budget) {
+    const directory = getCoordinationDirectory(process.platform);
+    if (!(await ensureCoordinationDirectory(directory, process.platform))) {
+        return undefined;
+    }
+    const basePath = getBrowserExecutionLockPath(identity);
+    const token = randomUUID();
+    const startIdentity = await readProcessStartIdentity(process.pid, process.platform, budget);
+    if (startIdentity === undefined || startIdentity.length === 0) {
+        return undefined;
+    }
+    const owner = {
+        pid: process.pid,
+        startIdentity,
+        token,
+        sessionNames: identity.sessionNames,
+        version: 4,
+    };
+    const content = JSON.stringify(owner);
+    if (Buffer.byteLength(content) > POLICY_LOCK_MAX_BYTES) {
+        return undefined;
+    }
+    return {
+        owner,
+        content,
+        basePath,
+        directory,
+        candidatePath: `${basePath}.candidate-${token}`,
+        path: `${basePath}.claim-${token}`,
+    };
+}
+async function publishClaim(claim) {
+    await mkdir(claim.candidatePath, { mode: 0o700 });
+    await writeFile(join(claim.candidatePath, LOCK_OWNER_FILE), claim.content, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o600,
+    });
+    await rename(claim.candidatePath, claim.path);
+}
+async function publishTicket(claim) {
+    const claims = await readClaims(claim.basePath);
+    if (!claims) {
+        return undefined;
+    }
+    const maxTicket = claims.reduce((max, entry) => (entry.ticket === null ? max : Math.max(max, entry.ticket)), 0);
+    if (!Number.isSafeInteger(maxTicket + 1)) {
+        return undefined;
+    }
+    const ticket = { ticket: maxTicket + 1, token: claim.owner.token, version: 4 };
+    const candidate = join(claim.path, `.ticket-${claim.owner.token}.tmp`);
+    await writeFile(candidate, JSON.stringify(ticket), { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await rename(candidate, join(claim.path, LOCK_TICKET_FILE));
+    return ticket.ticket;
+}
+function acquisitionExpired(budget) {
+    return (budget.signal?.aborted === true ||
+        (budget.deadline !== undefined && Date.now() >= budget.deadline));
+}
+async function waitForTurn(claim, ticket, budget, deadline) {
+    while (budget.signal?.aborted !== true) {
+        // Each poll observes a fresh published ticket set after the previous delay.
+        // oxlint-disable-next-line no-await-in-loop
+        const claims = await readClaims(claim.basePath);
+        if (!claims) {
+            return false;
+        }
+        const own = claims.find((entry) => entry.owner.token === claim.owner.token);
+        if (!own || own.ticket !== ticket) {
+            return false;
+        }
+        // Liveness checks and stale-claim removal must finish before acquisition.
+        // oxlint-disable-next-line no-await-in-loop
+        if (!(await anyPredecessorBlocks(claims, own, budget))) {
+            // Opportunistic GC must finish before the final cancellation check.
+            // oxlint-disable-next-line no-await-in-loop
+            await cleanDeadPolicyArtifacts(claim.directory, budget);
+            // Re-read cancellation/deadline after the awaited filesystem/native probes.
+            return !acquisitionExpired(budget);
+        }
+        if (Date.now() >= deadline) {
+            return false;
+        }
+        // Polling respects ordering and cancellation; contenders cannot run concurrently here.
+        // oxlint-disable-next-line no-await-in-loop
+        await waitForRetry(budget.signal);
+    }
+    return false;
+}
+function acquisitionDeadline(options) {
+    return options.deadline ?? Date.now() + (options.timeoutMs ?? POLICY_LOCK_WAIT_MS);
+}
+export async function acquireExecutionClaim(options) {
+    if (options.signal?.aborted === true) {
+        return undefined;
+    }
+    const deadline = acquisitionDeadline(options);
+    // timeoutMs: 0 retains the existing single-attempt policy probe contract.
+    const budget = {
+        signal: options.signal,
+        deadline: options.timeoutMs === 0 ? undefined : deadline,
+    };
+    const claim = await prepareClaim(options.identity, budget);
+    if (!claim) {
+        return undefined;
+    }
+    let published = false;
+    let acquired = false;
+    try {
+        await publishClaim(claim);
+        published = true;
+        const ticket = await publishTicket(claim);
+        if (ticket === undefined || !(await waitForTurn(claim, ticket, budget, deadline))) {
+            return undefined;
+        }
+        acquired = true;
+        return {
+            release: async () => {
+                await removeClaimOwnedBy(claim.path, claim.owner.token, Date.now() + POLICY_LOCK_WAIT_MS);
+            },
+        };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await rm(claim.candidatePath, { force: true, recursive: true }).catch(() => undefined);
+        if (published && !acquired) {
+            await removeClaimOwnedBy(claim.path, claim.owner.token, Date.now() + POLICY_LOCK_WAIT_MS);
+        }
+    }
+}

package/dist/extensions/agent-browser/lib/browser-execution-identity.js

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { canonicalizeAgentBrowserNamespace, foldAgentBrowserFilesystemIdentity, } from "./argv-grammar.js";
+import { getAgentBrowserSocketDirValidationError, resolveAgentBrowserSocketDir, } from "./process-socket-storage.js";
+import { getCurrentProcessUid } from "./process-identity.js";
+import { getErrorCode } from "./process-errors.js";
+export function getCoordinationDirectory(platform = process.platform) {
+    if (platform !== "win32") {
+        const uid = getCurrentProcessUid();
+        const suffix = uid === undefined ? "" : `-${uid}`;
+        return platform === "android"
+            ? join(tmpdir(), `pi-agent-browser-policy${suffix}`)
+            : `/tmp/pi-agent-browser-policy${suffix}`;
+    }
+    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}`);
+}
+function directoryOwnerTrusted(entry, platform) {
+    if (platform === "win32") {
+        return true;
+    }
+    const uid = getCurrentProcessUid();
+    return uid !== undefined && entry.uid === uid && (entry.mode & 0o077) === 0;
+}
+export async function ensureCoordinationDirectory(path, platform) {
+    try {
+        try {
+            await mkdir(path, { mode: 0o700 });
+        }
+        catch (error) {
+            if (getErrorCode(error) !== "EEXIST") {
+                return false;
+            }
+        }
+        const entry = await lstat(path);
+        return !entry.isSymbolicLink() && entry.isDirectory() && directoryOwnerTrusted(entry, platform);
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve only after native routing; omit sessionName for a namespace-wide operation. */
+export async function resolveBrowserExecutionIdentity(options) {
+    const socketDir = resolveAgentBrowserSocketDir(options);
+    const namespace = canonicalizeAgentBrowserNamespace(options.namespace);
+    let socketContext;
+    if (process.platform === "win32") {
+        // Windows native TCP daemons are shared across storage roots; don't split their coordination.
+        socketContext = `win32-native:${namespace ?? ""}`;
+    }
+    else {
+        if (socketDir === undefined) {
+            throw new Error("Browser execution coordination requires the native socket directory.");
+        }
+        const error = await getAgentBrowserSocketDirValidationError(socketDir);
+        if (error !== undefined && error.length > 0) {
+            throw new Error(`Browser execution coordination cannot use socket storage: ${error}.`);
+        }
+        const root = await realpath(socketDir);
+        socketContext =
+            namespace !== undefined && namespace.length > 0
+                ? join(root, "namespaces", namespace, "run")
+                : root;
+    }
+    return {
+        socketContext: foldAgentBrowserFilesystemIdentity(socketContext, process.platform),
+        ...(options.sessionName !== undefined
+            ? { sessionName: foldAgentBrowserFilesystemIdentity(options.sessionName, process.platform) }
+            : {}),
+    };
+}
+export function getBrowserExecutionLockPath(identity) {
+    return join(getCoordinationDirectory(), `.pi-agent-browser-policy-${createHash("sha256").update(identity.socketContext).digest("hex")}.lock-v4`);
+}

package/dist/extensions/agent-browser/lib/browser-journal-branch.js

@@ -0,0 +1,98 @@
+import { isRecord } from "./parsing.js";
+/** An admitted branch follows native append-only identity/ancestry, never entry body snapshots. */
+class CapturedBrowserBranch {
+    manager;
+    isGenerationCurrent;
+    sessionId;
+    anchorId;
+    trackedAnchor;
+    validatedAnchor;
+    validatedLeaf;
+    constructor(manager, isGenerationCurrent) {
+        this.manager = manager;
+        this.isGenerationCurrent = isGenerationCurrent;
+        this.sessionId = manager.getSessionId();
+        this.anchorId = manager.getLeafId();
+        this.trackedAnchor = this.anchorId;
+    }
+    isCurrent() {
+        if (!this.isGenerationCurrent() || this.manager.getSessionId() !== this.sessionId) {
+            return false;
+        }
+        if (this.anchorId !== this.trackedAnchor) {
+            this.clearCache();
+            this.trackedAnchor = this.anchorId;
+        }
+        const result = this.walk();
+        // Native entries/parents are append-only. Cache only after validation to a root or cached endpoint.
+        // ponytail: behind-host ancestor mutation without native reseed/generation is outside this contract; upgrade if Pi exposes ancestry revisions.
+        if (result.current && result.selected) {
+            this.validatedAnchor = result.anchor ?? this.validatedAnchor;
+            this.validatedLeaf = result.selected;
+        }
+        return result.current;
+    }
+    clearCache() {
+        this.validatedAnchor = undefined;
+        this.validatedLeaf = undefined;
+    }
+    entry(leaf) {
+        const entry = this.manager.getEntry(leaf);
+        if (!isRecord(entry) ||
+            entry.id !== leaf ||
+            (entry.parentId !== null && typeof entry.parentId !== "string")) {
+            throw new Error("Selected Pi journal ancestry is incomplete.");
+        }
+        return { value: entry, parentId: entry.parentId };
+    }
+    cached(leaf) {
+        if (leaf === this.anchorId) {
+            return this.validatedAnchor;
+        }
+        return leaf === (isRecord(this.validatedLeaf?.entry) ? this.validatedLeaf.entry.id : undefined)
+            ? this.validatedLeaf
+            : undefined;
+    }
+    validCache(leaf, entry) {
+        const cached = this.cached(leaf);
+        if (!cached) {
+            return false;
+        }
+        // Keep indexed lookup: the native API also refreshes fork journal identity.
+        if (cached.entry === entry.value && cached.parentId === entry.parentId) {
+            return true;
+        }
+        this.clearCache();
+        return false;
+    }
+    walk() {
+        let leaf = this.manager.getLeafId();
+        // Empty selection is not a universal ancestor of independent roots.
+        let current = this.anchorId === null && leaf === null;
+        const seen = new Set();
+        let selected;
+        let anchor;
+        while (leaf !== null) {
+            if (typeof leaf !== "string" || seen.has(leaf)) {
+                throw new Error("Selected Pi journal ancestry is invalid or cyclic.");
+            }
+            seen.add(leaf);
+            const entry = this.entry(leaf);
+            selected ??= { entry: entry.value, parentId: entry.parentId };
+            if (this.validCache(leaf, entry)) {
+                current = true;
+                break;
+            }
+            if (leaf === this.anchorId) {
+                current = true;
+                anchor = { entry: entry.value, parentId: entry.parentId };
+            }
+            leaf = entry.parentId;
+        }
+        return { current, selected, anchor };
+    }
+}
+/** Capture before waiting: native branch selection precedes awaited session_tree handlers. */
+export function captureBrowserBranch(manager, isGenerationCurrent) {
+    return new CapturedBrowserBranch(manager, isGenerationCurrent);
+}

package/dist/extensions/agent-browser/lib/browser-journal-contracts.js

@@ -0,0 +1 @@
+export {};