pi-agent-browser-native 0.9.3 → 0.9.4

package/dist/extensions/agent-browser/lib/runtime-redaction.js

@@ -0,0 +1,118 @@
+import { extractUpstreamCommandTokens, findCommandStartIndex } from "./argv-descriptor.js";
+import { projectUpstreamGlobalFlags } from "./argv-grammar.js";
+import { parseBatchCommandArgument } from "./orchestration/batch-stdin.js";
+import { isRecord } from "./parsing.js";
+import { isSensitiveFieldName, redactBearerCredentials, redactEnvSecretAssignments, redactStandaloneBasicCredential, } from "./redaction-fields.js";
+import { redactEmbeddedStructuredText, redactSerializedJson } from "./redaction-json.js";
+import { redactLooseUrls, redactUrlToken } from "./redaction-url.js";
+const SENSITIVE_VALUE_FLAGS = new Set(["--body", "--headers", "--password", "--proxy"]);
+export function redactSensitiveText(text) {
+    // Redact JSON string literals before text heuristics consume their escapes.
+    // Non-JSON stays whole so assignments and headers retain their credential context.
+    const serialized = redactSerializedJson(text, redactSensitiveText);
+    if (serialized !== undefined) {
+        return serialized;
+    }
+    const embedded = redactEmbeddedStructuredText(text, redactSensitiveText);
+    const credentials = redactStandaloneBasicCredential(redactBearerCredentials(redactLooseUrls(embedded)))
+        .replace(/\b(Authorization\s*:\s*Basic)\s+[^\s",]+/gi, "$1 [REDACTED]")
+        .replace(/\b(Cookie|Set-Cookie)\s*:\s*[^\n\r"]+/gi, "$1: [REDACTED]");
+    return redactEmbeddedStructuredText(redactEnvSecretAssignments(credentials), redactSensitiveText);
+}
+export function redactSensitiveValue(value) {
+    if (typeof value === "string") {
+        return redactSensitiveText(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSensitiveValue(item));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [
+        key,
+        isSensitiveFieldName(key) ? "[REDACTED]" : redactSensitiveValue(entryValue),
+    ]));
+}
+function redactFlagTokens(args) {
+    const redacted = [];
+    let pendingValueFlag;
+    for (const token of args) {
+        if (pendingValueFlag !== undefined) {
+            redacted.push(SENSITIVE_VALUE_FLAGS.has(pendingValueFlag) ? "[REDACTED]" : redactUrlToken(token));
+            pendingValueFlag = undefined;
+            continue;
+        }
+        const normalizedToken = token.split("=", 1)[0] ?? token;
+        if (SENSITIVE_VALUE_FLAGS.has(normalizedToken)) {
+            if (token.includes("=")) {
+                redacted.push(`${normalizedToken}=[REDACTED]`);
+            }
+            else {
+                redacted.push(token);
+                pendingValueFlag = normalizedToken;
+            }
+            continue;
+        }
+        redacted.push(redactSensitiveText(redactUrlToken(token)));
+    }
+    return redacted;
+}
+function sensitiveOperandIndices(args, start) {
+    const command = args[start];
+    const subcommand = args[start + 1];
+    switch (command) {
+        case "set":
+            return subcommand === "credentials" ? [start + 2, start + 3] : [];
+        case "cookies":
+            return subcommand === "set" && !extractUpstreamCommandTokens(args).slice(2).includes("--curl")
+                ? [start + 3]
+                : [];
+        case "storage":
+            return ["local", "session"].includes(subcommand) && args[start + 2] === "set"
+                ? [start + 4]
+                : [];
+        case "clipboard":
+            return subcommand === "write"
+                ? args.slice(start + 2).map((_, index) => start + 2 + index)
+                : [];
+        default:
+            return [];
+    }
+}
+function redactBatchRows(args) {
+    const batch = projectUpstreamGlobalFlags(args);
+    const replacements = new Map();
+    if (batch.tokens[0] !== "batch") {
+        return replacements;
+    }
+    for (let index = 1; index < batch.tokens.length; index++) {
+        if (batch.tokens[index] === "--bail") {
+            continue;
+        }
+        const step = parseBatchCommandArgument(batch.tokens[index]).step;
+        if (!step) {
+            continue;
+        }
+        const safe = redactInvocationArgs(step);
+        if (safe.some((token, offset) => token !== step[offset])) {
+            replacements.set(batch.indices[index], safe.map((token) => `'${token.replaceAll("'", "'\\''")}'`).join(" "));
+        }
+    }
+    return replacements;
+}
+export function redactInvocationArgs(args) {
+    const redacted = redactFlagTokens(args);
+    const start = findCommandStartIndex(args);
+    if (start !== undefined) {
+        for (const index of sensitiveOperandIndices(args, start)) {
+            if (index < redacted.length) {
+                redacted[index] = "[REDACTED]";
+            }
+        }
+    }
+    for (const [index, replacement] of redactBatchRows(args)) {
+        redacted[index] = replacement;
+    }
+    return redacted;
+}

package/dist/extensions/agent-browser/lib/runtime-replay-events.js

@@ -0,0 +1,144 @@
+import { extractUpstreamCommandTokens, parseCommandInfo } from "./argv-descriptor.js";
+import { canonicalizeAgentBrowserNamespace, extractExplicitSessionName } from "./argv-grammar.js";
+import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
+import { getBrowserResultMessage } from "./browser-transcript.js";
+import { isCloseAllCommand, isCloseCommand } from "./command-taxonomy.js";
+import { isRecord } from "./parsing.js";
+import { isPlainTextInspectionArgs } from "./runtime-args-validation.js";
+import { getRestorableManagedSessionName } from "./runtime-session-identity.js";
+function text(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function cleanupSession(step, record, fallbackNamespace, fallbackSessionName) {
+    if (!isRecord(step) ||
+        step.resource !== "managed-session" ||
+        (step.state !== "removed" && step.state !== "already-gone")) {
+        return;
+    }
+    const sessionName = getRestorableManagedSessionName(step.sessionName, fallbackSessionName) ??
+        getRestorableManagedSessionName(record?.sessionName, fallbackSessionName);
+    if (sessionName === undefined || sessionName.length === 0) {
+        return;
+    }
+    return { namespace: text(step.namespace) ?? fallbackNamespace, sessionName };
+}
+function cleanupSessionsForResult(result, detailsNamespace, fallbackSessionName) {
+    if (!isRecord(result) || !Array.isArray(result.steps)) {
+        return [];
+    }
+    const record = isRecord(result.record) ? result.record : undefined;
+    const namespace = text(record?.namespace) ?? detailsNamespace;
+    const closedSessions = [];
+    for (const step of result.steps) {
+        const identity = cleanupSession(step, record, namespace, fallbackSessionName);
+        if (identity) {
+            closedSessions.push(identity);
+        }
+    }
+    return closedSessions;
+}
+function getElectronCleanupClosedManagedSessions(details, fallbackSessionName) {
+    const electron = isRecord(details.electron) ? details.electron : undefined;
+    const cleanup = isRecord(electron?.cleanup) ? electron.cleanup : undefined;
+    const results = Array.isArray(cleanup?.results) ? cleanup.results : [];
+    return results.flatMap((result) => cleanupSessionsForResult(result, text(details.namespace), fallbackSessionName));
+}
+function outcomeClosedSession(outcome, sessionName, fallbackSessionName) {
+    if (outcome?.status !== "closed" || outcome.succeeded !== true) {
+        return;
+    }
+    return (getRestorableManagedSessionName(outcome.attemptedSessionName, fallbackSessionName) ??
+        getRestorableManagedSessionName(outcome.currentSessionName, fallbackSessionName) ??
+        getRestorableManagedSessionName(sessionName, fallbackSessionName));
+}
+function selectManagedReplaySession(options) {
+    if (options.closedSessionName !== undefined) {
+        return options.closedSessionName;
+    }
+    const { explicitSessionName, restorableDetailSessionName } = options;
+    if ((explicitSessionName ?? "").length > 0) {
+        return options.closesSession && restorableDetailSessionName === explicitSessionName
+            ? restorableDetailSessionName
+            : undefined;
+    }
+    if (options.usedImplicitSession || options.freshSession) {
+        return (restorableDetailSessionName ?? "").length > 0 ? restorableDetailSessionName : undefined;
+    }
+    return;
+}
+function replaySucceeded(options) {
+    const { outcome } = options;
+    const activeCurrent = outcome?.activeAfter === true &&
+        outcome.currentSessionName === options.managedSessionName &&
+        ["created", "replaced", "unchanged"].includes(text(outcome.status) ?? "");
+    if (activeCurrent || options.nestedBatchRemainsActive) {
+        return true;
+    }
+    if (typeof options.messageIsError === "boolean") {
+        return !options.messageIsError;
+    }
+    return typeof options.exitCode !== "number" || options.exitCode === 0;
+}
+export function decodeManagedReplayEvent(entry, fallbackSessionName) {
+    const message = getBrowserResultMessage(entry);
+    if (!message || !isRecord(message.details)) {
+        return;
+    }
+    const details = message.details;
+    const args = Array.isArray(details.args) && details.args.every((item) => typeof item === "string")
+        ? details.args
+        : [];
+    if (isPlainTextInspectionArgs(args)) {
+        return;
+    }
+    return decodeLifecycleEvent(details, args, message.isError, fallbackSessionName);
+}
+function closeAllApplied(details, args, messageIsError) {
+    return (details.closeAllApplied === true ||
+        (messageIsError !== true && isCloseAllCommand(extractUpstreamCommandTokens(args))) ||
+        batchHasSuccessfulCloseAll(details.batchSteps));
+}
+function decodeLifecycleEvent(details, args, messageIsError, fallbackSessionName) {
+    const sessionName = text(details.sessionName);
+    const namespace = canonicalizeAgentBrowserNamespace(text(details.namespace));
+    const command = text(details.command) ?? parseCommandInfo(args).command;
+    const lifecycle = getSuccessfulBatchCloseLifecycle(details.batchSteps);
+    const nestedBatchEndsClosed = lifecycle?.endsClosed === true;
+    const nestedBatchRemainsActive = lifecycle?.endsClosed === false;
+    const closesSession = isCloseCommand(command) || nestedBatchEndsClosed;
+    const outcome = isRecord(details.managedSessionOutcome)
+        ? details.managedSessionOutcome
+        : undefined;
+    const closedSessionName = outcomeClosedSession(outcome, sessionName, fallbackSessionName);
+    const outcomeClosed = (closedSessionName ?? "").length > 0;
+    const restorableDetailSessionName = getRestorableManagedSessionName(sessionName, fallbackSessionName);
+    const managedSessionName = selectManagedReplaySession({
+        closedSessionName,
+        explicitSessionName: extractExplicitSessionName(args),
+        restorableDetailSessionName,
+        usedImplicitSession: details.usedImplicitSession === true,
+        freshSession: details.sessionMode === "fresh",
+        closesSession,
+    });
+    const succeeded = replaySucceeded({
+        outcome,
+        managedSessionName,
+        nestedBatchRemainsActive,
+        messageIsError,
+        exitCode: details.exitCode,
+    });
+    return {
+        cleanupSessions: getElectronCleanupClosedManagedSessions(details, fallbackSessionName),
+        namespace,
+        detailSessionName: sessionName,
+        restoreDisabled: details.managedSessionRestoreDisabled === true,
+        restorableDetailSessionName,
+        closeAllApplied: closeAllApplied(details, args, messageIsError),
+        nestedBatchRemainsActive,
+        managedSessionName,
+        closesSession: closesSession || outcomeClosed,
+        closeSucceeded: nestedBatchEndsClosed || outcomeClosed || succeeded,
+        command,
+        succeeded,
+    };
+}

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

@@ -0,0 +1,76 @@
+import { createHash, randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import { canonicalizeAgentBrowserNamespace } from "./argv-grammar.js";
+import { isCloseCommand } from "./command-taxonomy.js";
+import { MANAGED_SESSION_NAME_PREFIX } from "./managed-session-restore.js";
+function namespaceFields(namespace) {
+    // Canonical namespaces have already collapsed the empty default to undefined.
+    return namespace === undefined ? {} : { namespace };
+}
+export function resolveManagedSessionState(options) {
+    const { command, managedSessionName, priorActive, priorSessionName, succeeded } = options;
+    const managedNamespace = canonicalizeAgentBrowserNamespace(options.managedSessionNamespace);
+    const priorNamespace = canonicalizeAgentBrowserNamespace(options.priorNamespace);
+    const priorState = {
+        active: priorActive,
+        ...namespaceFields(priorNamespace),
+        sessionName: priorSessionName,
+    };
+    if (managedSessionName === undefined || managedSessionName.length === 0) {
+        return priorState;
+    }
+    if (isCloseCommand(command) && managedSessionName === priorSessionName) {
+        if (managedNamespace !== priorNamespace || !succeeded) {
+            return priorState;
+        }
+        return { active: false, sessionName: priorSessionName };
+    }
+    if (!succeeded) {
+        return priorState;
+    }
+    return {
+        active: true,
+        ...namespaceFields(managedNamespace),
+        replacedSessionName: priorActive && priorSessionName !== managedSessionName ? priorSessionName : undefined,
+        sessionName: managedSessionName,
+    };
+}
+export function isRestorableManagedSessionName(sessionName, fallbackSessionName) {
+    return (sessionName === fallbackSessionName || sessionName.startsWith(`${fallbackSessionName}-fresh-`));
+}
+export function getRestorableManagedSessionName(value, fallbackSessionName) {
+    return typeof value === "string" && isRestorableManagedSessionName(value, fallbackSessionName)
+        ? value
+        : undefined;
+}
+export function createEphemeralSessionSeed() {
+    return randomUUID();
+}
+export function createImplicitSessionName(sessionId, cwd, ephemeralSeed, platform = process.platform) {
+    const normalizedSessionId = sessionId?.replaceAll("-", "").toLowerCase();
+    const identity = normalizedSessionId !== undefined && normalizedSessionId.length > 0
+        ? `session:${normalizedSessionId}:cwd:${cwd}`
+        : `ephemeral:${cwd}:${ephemeralSeed}`;
+    if (platform === "android") {
+        return `${MANAGED_SESSION_NAME_PREFIX}${createHash("sha256").update(identity).digest("hex").slice(0, 20)}`;
+    }
+    const projectSlug = basename(cwd)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 24);
+    const slug = projectSlug.length > 0 ? projectSlug : "project";
+    const cwdHash = createHash("sha256").update(`cwd:${cwd}`).digest("hex").slice(0, 8);
+    const sessionIdentity = normalizedSessionId !== undefined && normalizedSessionId.length > 0
+        ? `session:${normalizedSessionId}`
+        : identity;
+    const digest = createHash("sha256").update(sessionIdentity).digest("hex").slice(0, 12);
+    return `${MANAGED_SESSION_NAME_PREFIX}${slug}-${digest}-${cwdHash}`;
+}
+export function createFreshSessionName(baseSessionName, ephemeralSeed, ordinal) {
+    const suffix = createHash("sha256")
+        .update(`fresh:${baseSessionName}:${ephemeralSeed}:${ordinal}`)
+        .digest("hex")
+        .slice(0, 10);
+    return `${baseSessionName}-fresh-${suffix}`;
+}

package/dist/extensions/agent-browser/lib/runtime-session-plan.js

@@ -0,0 +1,114 @@
+import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
+import { isCloseCommand } from "./command-taxonomy.js";
+import { LAUNCH_SCOPED_FLAG_LABEL } from "./launch-scoped-flags.js";
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
+export function stripExplicitIdentityArgs(args, flag) {
+    const indices = new Set();
+    for (const occurrence of scanUpstreamGlobalFlagOccurrences(args, flag)) {
+        indices.add(occurrence.index);
+        indices.add(occurrence.index + 1);
+    }
+    return args.filter((_, index) => !indices.has(index));
+}
+export function freshSessionRecoveryHint(args, reason) {
+    return {
+        exampleArgs: args,
+        exampleParams: { args, sessionMode: "fresh" },
+        reason,
+        recommendedSessionMode: "fresh",
+    };
+}
+export function launchFlagsRecoveryReason() {
+    return `Launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}) need a fresh upstream launch once the extension-managed session is already active.`;
+}
+function hasExplicitNamespace(args) {
+    return scanUpstreamGlobalFlagOccurrences(args, "--namespace").length > 0;
+}
+function requestedNamespace(args) {
+    return hasExplicitNamespace(args) ? (extractExplicitNamespace(args) ?? "") : undefined;
+}
+function nativeNamespace(args) {
+    return resolveAgentBrowserNamespace(args, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+}
+function explicitSessionSelection(args, sessionName, options) {
+    const explicitNamespace = hasExplicitNamespace(args);
+    const managedNamespace = canonicalizeAgentBrowserNamespace(options.managedSessionNamespace);
+    const targetsCurrent = options.managedSessionActive &&
+        getAgentBrowserSessionIdentityKey(sessionName, managedNamespace) ===
+            getAgentBrowserSessionIdentityKey(options.managedSessionName, managedNamespace);
+    const fallbackNamespace = targetsCurrent ? managedNamespace : nativeNamespace(args);
+    const namespace = explicitNamespace ? requestedNamespace(args) : fallbackNamespace;
+    return {
+        argsToAppend: explicitNamespace ? stripExplicitIdentityArgs(args, "--namespace") : args,
+        prefixArgs: explicitNamespace ? ["--namespace", namespace ?? ""] : [],
+        namespace,
+        sessionName,
+        usedImplicitSession: false,
+    };
+}
+function namedManagedSelection(args, identity, implicit, command) {
+    const { namespace, sessionName } = identity;
+    return {
+        argsToAppend: hasExplicitNamespace(args)
+            ? stripExplicitIdentityArgs(args, "--namespace")
+            : args,
+        prefixArgs: [
+            ...(namespace === undefined ? [] : ["--namespace", namespace]),
+            "--session",
+            sessionName,
+        ],
+        // Empty names retain native namespace reporting without changing the launch prefix.
+        namespace: sessionName.length === 0 && command !== undefined && !hasExplicitNamespace(args)
+            ? nativeNamespace(args)
+            : namespace,
+        sessionName,
+        managedSessionName: sessionName,
+        usedImplicitSession: implicit,
+    };
+}
+function implicitSessionSelection(args, options, command) {
+    if (options.managedSessionActive && command.startupScopedFlags.length > 0) {
+        return {
+            argsToAppend: args,
+            prefixArgs: [],
+            namespace: command.command === undefined ? requestedNamespace(args) : nativeNamespace(args),
+            usedImplicitSession: false,
+            sessionName: extractExplicitSessionName(args),
+            recoveryHint: freshSessionRecoveryHint(args, launchFlagsRecoveryReason()),
+            validationError: [
+                `The current extension-managed agent-browser session is already running, so launch-scoped flags ${command.startupScopedFlags.join(", ")} would be ignored by upstream agent-browser.`,
+                'Retry this call with `sessionMode: "fresh"` to force a fresh upstream launch, or pass an explicit `--session ...` if you want to name the new session yourself.',
+            ].join(" "),
+        };
+    }
+    const namespace = hasExplicitNamespace(args)
+        ? requestedNamespace(args)
+        : canonicalizeAgentBrowserNamespace(options.managedSessionNamespace);
+    return namedManagedSelection(args, { sessionName: options.managedSessionName, namespace }, true, command.command);
+}
+function unmanagedSessionSelection(args, command) {
+    const explicitNamespace = hasExplicitNamespace(args);
+    const namespace = command !== undefined && !explicitNamespace ? nativeNamespace(args) : requestedNamespace(args);
+    return {
+        argsToAppend: args,
+        prefixArgs: [],
+        namespace,
+        sessionName: extractExplicitSessionName(args),
+        usedImplicitSession: false,
+    };
+}
+export function selectExecutionSession(args, options, command) {
+    const explicitSession = extractExplicitSessionName(args);
+    if (explicitSession !== undefined && explicitSession.length > 0) {
+        return explicitSessionSelection(args, explicitSession, options);
+    }
+    if (command.needsManagedSession) {
+        if (options.sessionMode === "auto") {
+            return implicitSessionSelection(args, options, command);
+        }
+        if (command.command !== undefined && !isCloseCommand(command.command)) {
+            return namedManagedSelection(args, { sessionName: options.freshSessionName, namespace: requestedNamespace(args) }, false, command.command);
+        }
+    }
+    return unmanagedSessionSelection(args, command.command);
+}

package/dist/extensions/agent-browser/lib/runtime-session-replay.js

@@ -0,0 +1,123 @@
+import { canonicalizeAgentBrowserNamespace, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace, } from "./argv-grammar.js";
+import { decodeManagedReplayEvent, } from "./runtime-replay-events.js";
+import { isRestorableManagedSessionName, resolveManagedSessionState, } from "./runtime-session-identity.js";
+// One replay owns its ranks, active identity and sticky policies; no caller state is mutated.
+class ManagedSessionReplay {
+    #fallbackSessionName;
+    #freshSessionRanks = new Map();
+    #restoreDisabledIdentities = new Map();
+    #state;
+    #activeRestoreRank = 0;
+    #closedSessionName;
+    #freshSessionOrdinal = 0;
+    constructor(fallbackSessionName) {
+        this.#fallbackSessionName = fallbackSessionName;
+        this.#state = { active: false, sessionName: fallbackSessionName };
+    }
+    #rank(sessionName) {
+        if (sessionName === this.#fallbackSessionName) {
+            return 0;
+        }
+        if (!isRestorableManagedSessionName(sessionName, this.#fallbackSessionName)) {
+            return;
+        }
+        const existing = this.#freshSessionRanks.get(sessionName);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const nextRank = this.#freshSessionRanks.size + 1;
+        this.#freshSessionRanks.set(sessionName, nextRank);
+        return nextRank;
+    }
+    #close(identity) {
+        const namespace = canonicalizeAgentBrowserNamespace(identity.namespace);
+        if (this.#rank(identity.sessionName) === undefined ||
+            identity.sessionName !== this.#state.sessionName ||
+            namespace !== this.#state.namespace) {
+            return;
+        }
+        this.#state = { active: false, sessionName: this.#state.sessionName };
+        this.#closedSessionName = identity.sessionName;
+    }
+    #closeAll(event) {
+        if (!event.closeAllApplied || !this.#state.active) {
+            return;
+        }
+        const restoredKey = getAgentBrowserSessionIdentityKey(this.#state.sessionName, this.#state.namespace);
+        const sessionName = event.restorableDetailSessionName;
+        const resultKey = sessionName !== undefined && sessionName.length > 0
+            ? getAgentBrowserSessionIdentityKey(sessionName, event.namespace)
+            : undefined;
+        const retainsCurrent = event.nestedBatchRemainsActive && resultKey === restoredKey;
+        if (isAgentBrowserSessionIdentityKeyInNamespace(restoredKey, event.namespace) &&
+            !retainsCurrent) {
+            this.#close(this.#state);
+        }
+    }
+    #applyCompletion(event, identity, rank) {
+        if (event.closesSession) {
+            if (event.closeSucceeded) {
+                this.#restoreDisabledIdentities.delete(getAgentBrowserSessionIdentityKey(identity.sessionName, identity.namespace));
+                this.#close(identity);
+            }
+            return;
+        }
+        if (event.succeeded && rank < this.#activeRestoreRank) {
+            return;
+        }
+        this.#state = resolveManagedSessionState({
+            command: event.command,
+            managedSessionName: identity.sessionName,
+            managedSessionNamespace: identity.namespace,
+            priorActive: this.#state.active,
+            priorNamespace: this.#state.namespace,
+            priorSessionName: this.#state.sessionName,
+            succeeded: event.succeeded,
+        });
+        if (event.succeeded && this.#state.active) {
+            this.#activeRestoreRank = rank;
+            this.#closedSessionName = undefined;
+        }
+    }
+    apply(event) {
+        for (const identity of event.cleanupSessions) {
+            this.#close(identity);
+        }
+        this.#closeAll(event);
+        // Sticky restore policy includes explicit current-managed rows, even without lifecycle replay.
+        if (event.restoreDisabled && event.detailSessionName !== undefined) {
+            const identity = { namespace: event.namespace, sessionName: event.detailSessionName };
+            this.#restoreDisabledIdentities.set(getAgentBrowserSessionIdentityKey(identity.sessionName, identity.namespace), identity);
+        }
+        if (event.managedSessionName === undefined || event.managedSessionName.length === 0) {
+            return;
+        }
+        const rank = this.#rank(event.managedSessionName);
+        if (rank === undefined) {
+            return;
+        }
+        this.#freshSessionOrdinal = Math.max(this.#freshSessionOrdinal, rank);
+        this.#applyCompletion(event, { namespace: event.namespace, sessionName: event.managedSessionName }, rank);
+    }
+    result() {
+        const closedSessionName = this.#closedSessionName;
+        return {
+            ...this.#state,
+            ...(closedSessionName !== undefined && closedSessionName.length > 0
+                ? { closedSessionName }
+                : {}),
+            freshSessionOrdinal: this.#freshSessionOrdinal,
+            managedSessionRestoreDisabledIdentities: [...this.#restoreDisabledIdentities.values()],
+        };
+    }
+}
+export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName) {
+    const replay = new ManagedSessionReplay(fallbackSessionName);
+    for (const entry of branch) {
+        const event = decodeManagedReplayEvent(entry, fallbackSessionName);
+        if (event) {
+            replay.apply(event);
+        }
+    }
+    return replay.result();
+}

package/dist/extensions/agent-browser/lib/runtime-tab-correction.js

@@ -0,0 +1,65 @@
+function normalizeComparableUrl(url) {
+    const normalizedUrl = url.trim();
+    if (normalizedUrl.length === 0) {
+        return;
+    }
+    try {
+        const parsedUrl = new URL(normalizedUrl);
+        parsedUrl.hash = "";
+        return parsedUrl.toString();
+    }
+    catch {
+        return;
+    }
+}
+function normalizeTabSelectionValue(value) {
+    const normalizedValue = value?.trim();
+    return normalizedValue !== undefined && normalizedValue.length > 0 ? normalizedValue : undefined;
+}
+function extractTabSelection(tab) {
+    const tabId = normalizeTabSelectionValue(tab.tabId);
+    if (tabId !== undefined) {
+        return { selectedTab: tabId, selectionKind: "tabId" };
+    }
+    const label = normalizeTabSelectionValue(tab.label);
+    if (label !== undefined) {
+        return { selectedTab: label, selectionKind: "label" };
+    }
+    if (typeof tab.index === "number" && Number.isInteger(tab.index) && tab.index >= 0) {
+        return { selectedTab: String(tab.index), selectionKind: "index" };
+    }
+    return;
+}
+function selectMatchingTab(tabs, targetTitle) {
+    const title = typeof targetTitle === "string" ? targetTitle.trim() : "";
+    const titledMatch = title.length === 0
+        ? undefined
+        : tabs.find((tab) => typeof tab.title === "string" && tab.title.trim() === title);
+    return {
+        selection: extractTabSelection(titledMatch ?? tabs[0]),
+        targetTitle: title.length > 0 ? title : undefined,
+    };
+}
+export function chooseOpenResultTabCorrection(options) {
+    const normalizedTargetUrl = typeof options.targetUrl === "string" ? normalizeComparableUrl(options.targetUrl) : undefined;
+    if (normalizedTargetUrl === undefined) {
+        return;
+    }
+    const tabsWithIndices = options.tabs.map((tab, index) => ({
+        ...tab,
+        index: typeof tab.index === "number" ? tab.index : index,
+        label: normalizeTabSelectionValue(tab.label),
+        tabId: normalizeTabSelectionValue(tab.tabId),
+    }));
+    const activeTab = tabsWithIndices.find((tab) => tab.active === true) ??
+        tabsWithIndices.find((tab) => tab.index === options.activeTabIndex);
+    if (activeTab && normalizeComparableUrl(activeTab.url ?? "") === normalizedTargetUrl) {
+        return;
+    }
+    const matchingTabs = tabsWithIndices.filter((tab) => normalizeComparableUrl(tab.url ?? "") === normalizedTargetUrl);
+    if (matchingTabs.length === 0) {
+        return;
+    }
+    const { selection, targetTitle } = selectMatchingTab(matchingTabs, options.targetTitle);
+    return selection ? { ...selection, targetTitle, targetUrl: normalizedTargetUrl } : undefined;
+}

package/dist/extensions/agent-browser/lib/runtime-timeouts.js

@@ -0,0 +1,28 @@
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
+const DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS = 15 * 60 * 1000;
+// Native close includes a five-second Chrome exit grace after protocol shutdown.
+// Use the normal CLI watchdog budget rather than interrupting that grace.
+const DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS = 35_000;
+function parseTimeoutMs(rawValue, minimumValue) {
+    if (rawValue === undefined) {
+        return;
+    }
+    const normalizedValue = rawValue.trim();
+    if (!/^\d+$/.test(normalizedValue)) {
+        return;
+    }
+    const parsedValue = Number(normalizedValue);
+    if (!Number.isSafeInteger(parsedValue) || parsedValue < minimumValue) {
+        return;
+    }
+    return parsedValue;
+}
+export function getImplicitSessionIdleTimeoutMs(env = getAgentBrowserProcessEnvironment()) {
+    return (parseTimeoutMs(env.PI_AGENT_BROWSER_IMPLICIT_SESSION_IDLE_TIMEOUT_MS, 0) ??
+        parseTimeoutMs(env.AGENT_BROWSER_IDLE_TIMEOUT_MS, 0) ??
+        DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS);
+}
+export function getImplicitSessionCloseTimeoutMs(env = getAgentBrowserProcessEnvironment()) {
+    return (parseTimeoutMs(env.PI_AGENT_BROWSER_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS, 0) ??
+        DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS);
+}