pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -0,0 +1,244 @@
+import { createHash, randomUUID } from "node:crypto";
+import { linkSync, lstatSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { isRecord } from "./parsing.js";
+import { getErrorCode } from "./process-errors.js";
+const MANAGED_SESSION_RESTORE_KEY_PATTERN = /^piab-r2-[a-f\d]{32}$/i;
+const MANAGED_SESSION_NAME_PREFIX = "piab-r2-";
+export function isManagedSessionRestoreKey(value) {
+    return typeof value === "string" && MANAGED_SESSION_RESTORE_KEY_PATTERN.test(value);
+}
+const MANAGED_SESSION_FRESH_SUFFIX_PATTERN = /-fresh-[a-f\d]{10}$/i;
+const MANAGED_SESSION_RESTORE_KEY_HASH_LENGTH = 32;
+const PROJECT_GENERATION_MARKER_NAME = "pi-agent-browser-project-generation-v1.json";
+const PROJECT_GENERATION_MARKER_MAX_BYTES = 1_024;
+const projectGenerationCache = new Map();
+import { isTrustedPosixDirectory, isTrustedCurrentFile } from "./managed-session-posix-storage.js";
+function readGitPointer(directory, entry, platform) {
+    const dotGit = join(directory, ".git");
+    if (!entry.isFile() ||
+        entry.isSymbolicLink() ||
+        entry.size > PROJECT_GENERATION_MARKER_MAX_BYTES ||
+        !isTrustedCurrentFile(entry, platform, 0o022)) {
+        return undefined;
+    }
+    const match = /^gitdir:\s*(.+)\s*$/i.exec(readFileSync(dotGit, "utf8"));
+    if (match?.[1] === undefined || match[1].length === 0) {
+        return undefined;
+    }
+    return {
+        gitDirectory: realpathSync(resolve(directory, match[1])),
+        worktreeDirectory: realpathSync(directory),
+    };
+}
+function resolveGitCheckout(cwd, platform) {
+    let directory = cwd;
+    while (true) {
+        const dotGit = join(directory, ".git");
+        try {
+            const entry = lstatSync(dotGit);
+            if (entry.isDirectory() && !entry.isSymbolicLink()) {
+                return { gitDirectory: realpathSync(dotGit), worktreeDirectory: realpathSync(directory) };
+            }
+            return readGitPointer(directory, entry, platform);
+        }
+        catch (error) {
+            if (getErrorCode(error) !== "ENOENT") {
+                return undefined;
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            return undefined;
+        }
+        directory = parent;
+    }
+}
+function readProjectGenerationMarker(path, platform) {
+    try {
+        const entry = lstatSync(path);
+        if (entry.isSymbolicLink() ||
+            !entry.isFile() ||
+            entry.size > PROJECT_GENERATION_MARKER_MAX_BYTES) {
+            return undefined;
+        }
+        if (!isTrustedCurrentFile(entry, platform, 0o177)) {
+            return undefined;
+        }
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!isRecord(parsed)) {
+            return undefined;
+        }
+        return parsed.version === 1 &&
+            typeof parsed.id === "string" &&
+            /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/i.test(parsed.id)
+            ? parsed.id
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getDirectoryFilesystemIdentity(path, platform) {
+    try {
+        const entry = statSync(path, { bigint: true });
+        if (!entry.isDirectory() || entry.dev <= 0n || entry.ino <= 0n) {
+            return undefined;
+        }
+        // ponytail: Android reports mutable ctime as birthtime; use statx birthtime/inode generation when Node exposes either reliably.
+        if (platform === "android") {
+            return `${entry.dev.toString()}:${entry.ino.toString()}`;
+        }
+        if (entry.birthtimeNs <= 0n) {
+            return undefined;
+        }
+        return `${entry.dev.toString()}:${entry.ino.toString()}:${entry.birthtimeNs.toString()}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveManagedSessionRestoreProjectCheckout(cwd, platform) {
+    let canonicalCwd;
+    try {
+        canonicalCwd = realpathSync(cwd);
+    }
+    catch {
+        return undefined;
+    }
+    if (platform !== "win32" && !isTrustedPosixDirectory(canonicalCwd, false, platform)) {
+        return undefined;
+    }
+    const checkout = resolveGitCheckout(canonicalCwd, platform);
+    if (!checkout) {
+        return undefined;
+    }
+    if (platform !== "win32" &&
+        (!isTrustedPosixDirectory(checkout.worktreeDirectory, true, platform) ||
+            !isTrustedPosixDirectory(checkout.gitDirectory, true, platform))) {
+        return undefined;
+    }
+    return { canonicalCwd, ...checkout };
+}
+export function resolveManagedSessionRestoreCheckoutRoot(cwd, platform = process.platform) {
+    return resolveManagedSessionRestoreProjectCheckout(cwd, platform)?.worktreeDirectory;
+}
+function matchingCacheIdentity(cached, checkout, filesystem) {
+    if (cached === undefined) {
+        return undefined;
+    }
+    return cached.gitDirectory === checkout.gitDirectory &&
+        cached.worktreeDirectory === checkout.worktreeDirectory &&
+        cached.gitFilesystemIdentity === filesystem.git &&
+        cached.worktreeFilesystemIdentity === filesystem.worktree &&
+        cached.marker === filesystem.marker
+        ? cached.identity
+        : undefined;
+}
+function publishGenerationMarker(markerPath, platform) {
+    const content = JSON.stringify({ id: randomUUID(), version: 1 });
+    if (platform === "android") {
+        // ponytail: Android denies hard links in app storage; use renameat2(RENAME_NOREPLACE) if Node exposes it.
+        try {
+            writeFileSync(markerPath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            return true;
+        }
+        catch (error) {
+            return getErrorCode(error) === "EEXIST";
+        }
+    }
+    const candidatePath = `${markerPath}.candidate-${process.pid}-${randomUUID()}`;
+    try {
+        writeFileSync(candidatePath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        try {
+            linkSync(candidatePath, markerPath);
+            return true;
+        }
+        catch (error) {
+            return getErrorCode(error) === "EEXIST";
+        }
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            unlinkSync(candidatePath);
+        }
+        catch {
+            /* Cleanup is best-effort; only the validated published marker supplies identity. */
+        }
+    }
+}
+function resolveProjectGenerationIdentity(cwd, platform = process.platform) {
+    const checkout = resolveManagedSessionRestoreProjectCheckout(cwd, platform);
+    if (!checkout) {
+        return undefined;
+    }
+    const { canonicalCwd } = checkout;
+    const gitFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.gitDirectory, platform);
+    const worktreeFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.worktreeDirectory, platform);
+    if (gitFilesystemIdentity === undefined || worktreeFilesystemIdentity === undefined) {
+        return undefined;
+    }
+    const markerPath = join(checkout.gitDirectory, PROJECT_GENERATION_MARKER_NAME);
+    let marker = readProjectGenerationMarker(markerPath, platform);
+    const cached = projectGenerationCache.get(canonicalCwd);
+    const cachedIdentity = matchingCacheIdentity(cached, checkout, {
+        git: gitFilesystemIdentity,
+        worktree: worktreeFilesystemIdentity,
+        marker,
+    });
+    if (cachedIdentity !== undefined) {
+        return cachedIdentity;
+    }
+    projectGenerationCache.delete(canonicalCwd);
+    try {
+        if (marker === undefined) {
+            if (!publishGenerationMarker(markerPath, platform)) {
+                return undefined;
+            }
+            marker = readProjectGenerationMarker(markerPath, platform);
+        }
+        if (marker === undefined) {
+            return undefined;
+        }
+        const identity = `${platform}:${worktreeFilesystemIdentity}:${gitFilesystemIdentity}:${marker}`;
+        projectGenerationCache.set(canonicalCwd, {
+            gitDirectory: checkout.gitDirectory,
+            gitFilesystemIdentity,
+            identity,
+            marker,
+            worktreeDirectory: checkout.worktreeDirectory,
+            worktreeFilesystemIdentity,
+        });
+        return identity;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function hasManagedSessionRestoreProjectIdentity(cwd) {
+    return resolveProjectGenerationIdentity(cwd) !== undefined;
+}
+/** Keep fresh rotations from one Pi transcript in one private upstream restore pool. */
+export function getManagedSessionRestoreScope(sessionName) {
+    return sessionName.replace(MANAGED_SESSION_FRESH_SUFFIX_PATTERN, "");
+}
+/** Stable for one Pi transcript and checkout generation; isolated from other concurrent transcripts. */
+export function createManagedSessionRestoreKey(cwd, restoreScope = "", platform = process.platform) {
+    let canonicalCwd = resolve(cwd);
+    try {
+        canonicalCwd = realpathSync(canonicalCwd);
+    }
+    catch {
+        // Missing cwd keeps the deterministic unavailable identity without claiming a durable checkout.
+    }
+    const identity = resolveProjectGenerationIdentity(canonicalCwd, platform);
+    const material = identity ?? `unavailable:${canonicalCwd}`;
+    const digest = createHash("sha256")
+        .update(`restore-v3:${material}:scope:${restoreScope}`)
+        .digest("hex")
+        .slice(0, MANAGED_SESSION_RESTORE_KEY_HASH_LENGTH);
+    return `${MANAGED_SESSION_NAME_PREFIX}${digest}`;
+}

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

@@ -0,0 +1,84 @@
+import { extractRequestedRestoreKey } from "./argv-grammar.js";
+import { hasLaunchScopedFlagToken } from "./launch-scoped-flags.js";
+import { createManagedSessionRestoreKey, getManagedSessionRestoreScope, getManagedSessionRestoreProtectedStorageEnv, hasManagedSessionRestoreProjectIdentity, } from "./managed-session-storage.js";
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
+import { resolveOwnedManagedSessionContext, } from "./owned-managed-session-context.js";
+import { AGENT_BROWSER_RESTORE_ENV, agentBrowserExplicitConfigIsPresent, isManagedSessionRestoreIncompatible, managedSessionRestoreOptedOut, } from "./managed-session-restore-policy.js";
+function reuseIsSuppressed(options, env) {
+    return (managedSessionRestoreOptedOut(options) ||
+        agentBrowserExplicitConfigIsPresent(env, options.args) ||
+        ["--restore", "--session-name"].some((flag) => hasLaunchScopedFlagToken(options.args, flag)) ||
+        env.AGENT_BROWSER_RESTORE !== undefined ||
+        env.AGENT_BROWSER_SESSION_NAME !== undefined);
+}
+function reuseContext(options, owned) {
+    const env = { ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env };
+    const enabled = !options.restoreState.isDisabled(owned.sessionName, owned.namespace);
+    const scope = getManagedSessionRestoreScope(owned.sessionName);
+    const knownKey = options.restoreState.getDaemonRestoreKey(owned.sessionName, owned.namespace);
+    const cwd = owned.cwd ?? options.cwd;
+    const key = knownKey === undefined && enabled && hasManagedSessionRestoreProjectIdentity(cwd)
+        ? createManagedSessionRestoreKey(cwd, scope)
+        : knownKey;
+    return {
+        ...owned,
+        reuseOnly: true,
+        restoreKey: key ?? undefined,
+        restoreScope: scope,
+        protectedStorageEnv: enabled
+            ? getManagedSessionRestoreProtectedStorageEnv(true, env)
+            : undefined,
+        restoreDecision: enabled ? "enabled" : undefined,
+        restoreSuppressed: reuseIsSuppressed(options, env),
+        headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled,
+        headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
+    };
+}
+function restoreDecision(optedOut, incompatible) {
+    if (optedOut) {
+        return "opted-out";
+    }
+    return incompatible ? "incompatible" : "enabled";
+}
+function launchContext(options, owned) {
+    const cwd = owned.cwd ?? options.cwd;
+    const policy = {
+        args: options.args,
+        cwd,
+        env: options.env,
+        parentEnv: options.parentEnv,
+        stdin: options.stdin,
+        wrapperInjectedUserAgent: options.wrapperInjectedUserAgent,
+    };
+    const optedOut = managedSessionRestoreOptedOut(policy);
+    const projectIdentityAvailable = !optedOut && hasManagedSessionRestoreProjectIdentity(cwd);
+    const incompatible = !optedOut && isManagedSessionRestoreIncompatible(policy, owned.namespace);
+    const enabled = !optedOut && !incompatible;
+    const env = { ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env };
+    const scope = getManagedSessionRestoreScope(owned.sessionName);
+    const key = projectIdentityAvailable ? createManagedSessionRestoreKey(cwd, scope) : undefined;
+    const decision = restoreDecision(optedOut, incompatible);
+    return {
+        ...owned,
+        compatibilityUserAgent: options.compatibilityUserAgent,
+        headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled,
+        headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
+        expectedDaemonRestoreKey: enabled
+            ? key
+            : extractRequestedRestoreKey(options.args, owned.sessionName, env[AGENT_BROWSER_RESTORE_ENV]),
+        protectedStorageEnv: enabled
+            ? getManagedSessionRestoreProtectedStorageEnv(true, env)
+            : undefined,
+        restoreDecision: decision,
+        restoreKey: key,
+        restoreScope: scope,
+        restoreSuppressed: optedOut || incompatible,
+    };
+}
+export function buildOwnedManagedSessionRestoreContext(options) {
+    const owned = resolveOwnedManagedSessionContext(options);
+    if (!owned) {
+        return undefined;
+    }
+    return options.reuseOnly === true ? reuseContext(options, owned) : launchContext(options, owned);
+}

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

@@ -0,0 +1,119 @@
+import { extractUpstreamCommandTokens, parseCommandInfo } from "./argv-descriptor.js";
+import { extractExplicitNamespace, extractExplicitSessionName, isUpstreamEnvFlagEnabled, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
+import { hasLaunchScopedFlagToken, MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS, MANAGED_RESTORE_INCOMPATIBLE_ENVS, MANAGED_RESTORE_INCOMPATIBLE_FLAGS, } from "./launch-scoped-flags.js";
+import { ensureManagedSessionRestoreStorageIsSecure, hasManagedSessionRestoreProjectIdentity, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
+import { parseUserBatchStdin } from "./orchestration/batch-stdin.js";
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
+import { ownedContextMatches } from "./owned-managed-session-context.js";
+export const AGENT_BROWSER_CONFIG_ENV = "AGENT_BROWSER_CONFIG";
+export const AGENT_BROWSER_RESTORE_ENV = "AGENT_BROWSER_RESTORE";
+export const MANAGED_SESSION_RESTORE_ENV = "PI_AGENT_BROWSER_MANAGED_SESSION_RESTORE";
+export function isDisabledEnvFlag(value) {
+    return value !== undefined && ["0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}
+export function hasUpstreamEnvValue(env, name) {
+    return env?.[name] !== undefined;
+}
+function hasExplicitConfigArg(args) {
+    return scanUpstreamGlobalFlagOccurrences(args, "--config").length > 0;
+}
+export function closesBrowserSession(args) {
+    return ["close", "exit", "quit"].includes(parseCommandInfo(args).command ?? "");
+}
+export function agentBrowserExplicitConfigIsPresent(parentEnv = getAgentBrowserProcessEnvironment(), args = []) {
+    return hasExplicitConfigArg(args) || hasUpstreamEnvValue(parentEnv, AGENT_BROWSER_CONFIG_ENV);
+}
+/** Caller-selected config disables automatic restore injection without blocking native config. */
+export function agentBrowserConfigBlocksManagedRestore(parentEnv = getAgentBrowserProcessEnvironment(), args = [], platform = process.platform) {
+    return ((resolveManagedSessionRestoreHome(parentEnv, platform) ?? "").length === 0 ||
+        agentBrowserExplicitConfigIsPresent(parentEnv, args));
+}
+function omitWrapperInjectedUserAgent(args, enabled) {
+    if (enabled !== true) {
+        return [...args];
+    }
+    const index = args.indexOf("--user-agent");
+    return index < 0 ? [...args] : [...args.slice(0, index), ...args.slice(index + 2)];
+}
+function batchHasManagedSessionRestoreConflict(args, stdin) {
+    const [command, ...commandArgs] = extractUpstreamCommandTokens(args);
+    if (command !== "batch") {
+        return false;
+    }
+    if (commandArgs.some((token) => token !== "--bail")) {
+        return true;
+    }
+    const parsed = parseUserBatchStdin(stdin);
+    if ((parsed.error !== undefined && parsed.error.length > 0) || !parsed.steps) {
+        return false;
+    }
+    return parsed.steps.some((step) => ["connect", "batch"].includes(parseCommandInfo(step).command ?? ""));
+}
+function hasLaunchConflict(options) {
+    const effectiveEnv = {
+        ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()),
+        ...options.env,
+    };
+    const args = omitWrapperInjectedUserAgent(options.args, options.wrapperInjectedUserAgent);
+    if (MANAGED_RESTORE_INCOMPATIBLE_ENVS.some((name) => hasUpstreamEnvValue(effectiveEnv, name))) {
+        return true;
+    }
+    if (MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS.some((name) => isUpstreamEnvFlagEnabled(effectiveEnv[name]))) {
+        return true;
+    }
+    if (MANAGED_RESTORE_INCOMPATIBLE_FLAGS.some((flag) => hasLaunchScopedFlagToken(args, flag))) {
+        return true;
+    }
+    if (parseCommandInfo(args).command === "connect" ||
+        batchHasManagedSessionRestoreConflict(args, options.stdin)) {
+        return true;
+    }
+    return agentBrowserExplicitConfigIsPresent(effectiveEnv, args);
+}
+export function managedSessionRestoreOptedOut(options) {
+    return isDisabledEnvFlag({ ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env }[MANAGED_SESSION_RESTORE_ENV]);
+}
+function lacksProjectStorage(options, env) {
+    if (options.cwd === undefined || options.cwd.length === 0) {
+        return false;
+    }
+    return (!hasManagedSessionRestoreProjectIdentity(options.cwd) ||
+        agentBrowserConfigBlocksManagedRestore(env, omitWrapperInjectedUserAgent(options.args, options.wrapperInjectedUserAgent)));
+}
+export function isManagedSessionRestoreIncompatible(options, namespace = extractExplicitNamespace(options.args)) {
+    if (hasLaunchConflict(options)) {
+        return true;
+    }
+    if (managedSessionRestoreOptedOut(options)) {
+        return false;
+    }
+    const env = { ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env };
+    return (lacksProjectStorage(options, env) ||
+        !ensureManagedSessionRestoreStorageIsSecure(env, process.platform, namespace));
+}
+export function resolveManagedSessionRestorePolicy(options) {
+    const parentEnv = options.parentEnv ?? getAgentBrowserProcessEnvironment();
+    const sessionName = extractExplicitSessionName(options.args);
+    const ownedContext = ownedContextMatches(sessionName, options.args);
+    const namespace = ownedContext ? ownedContext.namespace : extractExplicitNamespace(options.args);
+    const restoreState = ownedContext?.restoreState ?? options.restoreState;
+    const owned = (options.ownedManagedSession === true || ownedContext !== undefined) &&
+        restoreState !== undefined;
+    return { namespace, owned, ownedContext, parentEnv, restoreState, sessionName };
+}
+export function resolveExplicitAutosaveInterval(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const defaultInterval = "30000";
+    if (!/^\+?\d+$/.test(value)) {
+        return defaultInterval;
+    }
+    try {
+        const parsed = BigInt(value);
+        return parsed <= 18446744073709551615n ? parsed.toString() : defaultInterval;
+    }
+    catch {
+        return defaultInterval;
+    }
+}

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

@@ -0,0 +1,83 @@
+import { getAgentBrowserSessionIdentityKey } from "./argv-grammar.js";
+import { isRecord } from "./parsing.js";
+/** Per-extension sticky restore decisions and current-process daemon provenance. */
+export class ManagedSessionRestoreState {
+    #daemonRestoreKeys = new Map();
+    #disabled = new Set();
+    clear(sessionName, namespace) {
+        if (sessionName !== undefined && sessionName.length > 0) {
+            const identity = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+            this.#daemonRestoreKeys.delete(identity);
+            this.#disabled.delete(identity);
+        }
+        else {
+            this.#daemonRestoreKeys.clear();
+            this.#disabled.clear();
+        }
+    }
+    disable(sessionName, namespace) {
+        if (sessionName !== undefined && sessionName.length > 0) {
+            this.#disabled.add(getAgentBrowserSessionIdentityKey(sessionName, namespace));
+        }
+    }
+    getDaemonRestoreKey(sessionName, namespace) {
+        return typeof sessionName === "string"
+            ? this.#daemonRestoreKeys.get(getAgentBrowserSessionIdentityKey(sessionName, namespace))
+                ?.restoreKey
+            : undefined;
+    }
+    hasDaemonRestoreKey(sessionName, namespace) {
+        return (typeof sessionName === "string" &&
+            this.#daemonRestoreKeys.get(getAgentBrowserSessionIdentityKey(sessionName, namespace))
+                ?.restored !== true &&
+            this.#daemonRestoreKeys.has(getAgentBrowserSessionIdentityKey(sessionName, namespace)));
+    }
+    forgetDaemonRestoreKey(sessionName, namespace) {
+        if (sessionName !== undefined && sessionName.length > 0) {
+            this.#daemonRestoreKeys.delete(getAgentBrowserSessionIdentityKey(sessionName, namespace));
+        }
+    }
+    isDisabled(sessionName, namespace) {
+        return (typeof sessionName === "string" &&
+            this.#disabled.has(getAgentBrowserSessionIdentityKey(sessionName, namespace)));
+    }
+    recordDaemonRestoreKey(sessionName, namespace, restoreKey, generation) {
+        if (sessionName !== undefined && sessionName.length > 0) {
+            const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+            const previous = this.#daemonRestoreKeys.get(key);
+            this.#daemonRestoreKeys.set(key, {
+                restoreKey,
+                generation: generation ?? (previous?.restoreKey === restoreKey ? previous.generation : undefined),
+            });
+        }
+    }
+    getDaemonReceipt(sessionName, namespace) {
+        const receipt = sessionName !== undefined && sessionName.length > 0
+            ? this.#daemonRestoreKeys.get(getAgentBrowserSessionIdentityKey(sessionName, namespace))
+            : undefined;
+        return receipt?.generation !== undefined && receipt.generation.length > 0
+            ? { restoreKey: receipt.restoreKey, generation: receipt.generation }
+            : undefined;
+    }
+    restoreDaemonReceipt(sessionName, namespace, receipt) {
+        if (isRecord(receipt) &&
+            typeof receipt.generation === "string" &&
+            receipt.generation.length > 0 &&
+            (receipt.restoreKey === null || typeof receipt.restoreKey === "string")) {
+            this.#daemonRestoreKeys.set(getAgentBrowserSessionIdentityKey(sessionName, namespace), {
+                restoreKey: receipt.restoreKey,
+                generation: receipt.generation,
+                restored: true,
+            });
+        }
+    }
+    replace(identities = [], options = {}) {
+        if (options.preserveDaemonRestoreKeys !== true) {
+            this.#daemonRestoreKeys.clear();
+        }
+        this.#disabled.clear();
+        for (const identity of identities) {
+            this.disable(identity.sessionName, identity.namespace);
+        }
+    }
+}