pi-agent-browser-native 0.8.1 → 0.8.3

package/dist/extensions/agent-browser/lib/browser-session-conversion.js

@@ -0,0 +1,381 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, unlink } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import parser from "stream-json/parser.js";
+import ignore from "stream-json/filters/ignore.js";
+import stringer from "stream-json/stringer.js";
+import disassembler from "stream-json/disassembler.js";
+import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
+import { getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "./argv-grammar.js";
+import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
+import { BROWSER_RESULT_TOOLS, BROWSER_STATE_FIELDS, BROWSER_TRANSITION_ENTRY, applyArtifactChanges, artifactChanges, browserStateEffects, getBrowserRecord, snapshotDefinition } from "./browser-transcript.js";
+import { projectJson, readRange, scanJournalMetadata } from "./browser-journal.js";
+import { isCloseAllCommand, isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand } from "./command-taxonomy.js";
+import { isRecord } from "./parsing.js";
+import { isSessionArtifactManifest } from "./results/artifact-manifest.js";
+import { buildNoActivePageRefSnapshotInvalidation, extractSessionTabTargetFromBatchResults, isNoActivePageSnapshotFailure, normalizeSessionTabTarget } from "./session-page-state.js";
+const emptyProjection = () => ({ pages: new Map(), nextIndex: 0 });
+function legacyTarget(value) {
+    return normalizeSessionTabTarget({
+        url: typeof value.url === "string" ? value.url : undefined,
+        title: typeof value.title === "string" ? value.title : undefined,
+        targetId: typeof value.targetId === "string" ? value.targetId : undefined,
+    });
+}
+function legacyMessage(entry) {
+    if (entry.type === "custom" && entry.customType === BROWSER_TRANSITION_ENTRY && isRecord(entry.data) && isRecord(entry.data.details))
+        return entry.data;
+    const message = entry.type === "message" && isRecord(entry.message) ? entry.message : undefined;
+    return message && typeof message.toolName === "string" && BROWSER_RESULT_TOOLS.has(message.toolName) && isRecord(message.details)
+        && message.details.browserEventVersion !== 1 ? message : undefined;
+}
+function legacySnapshot(value, id) {
+    if (!isRecord(value) || !Array.isArray(value.refIds))
+        return undefined;
+    const refIds = value.refIds.filter((ref) => typeof ref === "string" && /^e\d+$/.test(ref));
+    const sourceRefs = isRecord(value.refs) ? value.refs : {};
+    const snapshot = {
+        snapshotId: typeof value.snapshotId === "string" ? value.snapshotId : id, refIds,
+        generation: typeof value.generation === "string" ? value.generation : undefined,
+        refs: Object.fromEntries(refIds.flatMap(refId => {
+            const ref = sourceRefs[refId];
+            if (!isRecord(ref) || typeof ref.name !== "string" || typeof ref.role !== "string")
+                return [];
+            return [[refId, { name: ref.name, role: ref.role, ...(typeof ref.isEditable === "boolean" ? { isEditable: ref.isEditable } : {}), ...(typeof ref.isContentEditable === "boolean" ? { isContentEditable: ref.isContentEditable } : {}) }]];
+        })),
+        target: isRecord(value.target) ? legacyTarget(value.target) : undefined,
+    };
+    return snapshotDefinition(snapshot);
+}
+/** Offline only: normalize old receipts along their actual parent ancestry, never physical-order equality. */
+export function convertLegacyBrowserEntry(entry, parent = emptyProjection(), ownerSessionId) {
+    const current = { pages: new Map(parent.pages), manifest: parent.manifest, nextIndex: parent.nextIndex };
+    const nativeId = typeof entry.id === "string" ? entry.id : randomUUID();
+    const canonical = getBrowserRecord(entry);
+    if (canonical) {
+        current.manifest = applyArtifactChanges(parent.manifest, canonical.event.artifacts);
+        for (const page of canonical.event.pages ?? []) {
+            const prior = current.pages.get(page.key) ?? {};
+            if (page.clear) {
+                current.pages.delete(page.key);
+                continue;
+            }
+            const definition = canonical.snapshot;
+            const digest = definition?.refs ? createHash("sha256").update(JSON.stringify({ refs: definition.refs, target: definition.target, generation: definition.generation })).digest("hex") : prior.snapshot?.digest ?? "";
+            current.pages.set(page.key, { target: page.target, unknown: page.unknown, reopenPending: page.reopenPending,
+                snapshot: page.refs.kind === "replace" || page.refs.kind === "reuse" ? { id: page.refs.snapshotId, digest, usable: true, candidate: false }
+                    : prior.snapshot ? { ...prior.snapshot, usable: false, candidate: canonical.event.phase === "begin" } : undefined,
+                pending: canonical.event.phase === "begin" ? { operationId: canonical.event.operationId, toolCallId: canonical.event.toolCallId, index: canonical.event.commandIndex } : undefined });
+        }
+        return { projection: current };
+    }
+    if (entry.type === "custom" && entry.customType === "agent-browser-script-session" && isRecord(entry.data)) {
+        return { record: { event: { version: 1, phase: "state", operationId: `legacy-${nativeId}`, toolCallId: `legacy-${nativeId}`, commandIndex: 0, isError: entry.data.cleanup !== "closed", state: { scriptLease: { ...entry.data, ownerSessionId: entry.data.ownerSessionId ?? ownerSessionId } } } }, projection: current };
+    }
+    const message = legacyMessage(entry);
+    if (!message || !isRecord(message.details))
+        return { projection: parent };
+    const details = message.details;
+    const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
+    const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
+    const key = sessionName ? getAgentBrowserSessionIdentityKey(sessionName, namespace) : undefined;
+    const args = Array.isArray(details.args) ? details.args.filter((arg) => typeof arg === "string") : [];
+    const tokens = extractUpstreamCommandTokens(args);
+    const command = typeof details.command === "string" ? details.command : tokens[0];
+    const subcommand = typeof details.subcommand === "string" ? details.subcommand : tokens[1];
+    const isError = message.isError === true;
+    const toolCallId = typeof message.toolCallId === "string" ? message.toolCallId : `legacy-${nativeId}`;
+    const prior = key ? current.pages.get(key) ?? {} : {};
+    const begin = entry.type === "custom" && details.sessionTabTargetUnknown === true && details.command === undefined && details.exitCode === undefined && details.agentBrowserStarted === undefined;
+    const pending = prior.pending?.toolCallId === toolCallId ? prior.pending : undefined;
+    const phase = begin ? "begin" : pending ? "finish" : "state";
+    const commandIndex = begin ? current.nextIndex++ : pending?.index ?? 0;
+    const operationId = pending?.operationId ?? `legacy-${nativeId}`;
+    const pages = [];
+    const closeLifecycle = getSuccessfulBatchCloseLifecycle(details.batchSteps);
+    const closeAll = details.closeAllApplied === true || (!isError && isCloseAllCommand(tokens)) || batchHasSuccessfulCloseAll(details.batchSteps);
+    const lifecycleReset = !isError && isCloseCommand(command) || closeLifecycle !== undefined;
+    if (closeAll) {
+        for (const pageKey of current.pages.keys())
+            if (isAgentBrowserSessionIdentityKeyInNamespace(pageKey, namespace)) {
+                current.pages.delete(pageKey);
+                pages.push({ key: pageKey, clear: true, refs: { kind: "invalidate" } });
+            }
+    }
+    else if (key && lifecycleReset) {
+        current.pages.delete(key);
+        pages.push({ key, clear: true, refs: { kind: "invalidate" } });
+    }
+    let definition;
+    const hasPageEffects = begin || ["sessionTabTargetUnknown", "sessionTabTarget", "sessionTabReopenPending", "refSnapshot", "refSnapshotInvalidation"].some(field => details[field] !== undefined)
+        || command === "batch" && Array.isArray(details.data);
+    if (key && hasPageEffects && !((closeAll || lifecycleReset) && (isCloseCommand(command) || closeLifecycle?.endsClosed === true))) {
+        const page = { ...(current.pages.get(key) ?? {}) };
+        if (begin) {
+            page.target = undefined;
+            page.unknown = true;
+            page.snapshot = prior.snapshot ? { ...prior.snapshot, usable: false, candidate: true } : undefined;
+            page.pending = { toolCallId, operationId, index: commandIndex };
+            pages.push({ key, refs: { kind: "unknown" }, unknown: true });
+        }
+        else if (details.sessionTabTargetUnknown === true) {
+            page.target = undefined;
+            page.unknown = true;
+            page.pending = undefined;
+            page.snapshot = page.snapshot ? { ...page.snapshot, usable: false, candidate: false } : undefined;
+            pages.push({ key, refs: { kind: "unknown", invalidation: isRecord(details.refSnapshotInvalidation) ? details.refSnapshotInvalidation : undefined }, unknown: true });
+        }
+        else {
+            if (!isRecord(details.compiledNetworkSourceLookup) && !isReadOnlyDiagnosticSessionTargetCommand(command, subcommand) && isRecord(details.sessionTabTarget))
+                page.target = legacyTarget(details.sessionTabTarget) ?? page.target;
+            else if (command === "batch" && !isRecord(details.compiledNetworkSourceLookup))
+                page.target = extractSessionTabTargetFromBatchResults(details.data) ?? page.target;
+            if (page.target)
+                page.unknown = undefined;
+            if (typeof details.sessionTabReopenPending === "boolean")
+                page.reopenPending = details.sessionTabReopenPending;
+            const invalidation = isRecord(details.refSnapshotInvalidation) && ["no-active-page", "page-transition"].includes(String(details.refSnapshotInvalidation.reason))
+                ? details.refSnapshotInvalidation
+                : isNoActivePageSnapshotFailure(command, typeof details.error === "string" ? details.error : typeof details.summary === "string" ? details.summary : undefined) ? buildNoActivePageRefSnapshotInvalidation() : undefined;
+            const candidate = invalidation ? undefined : legacySnapshot(details.refSnapshot, `snapshot-${nativeId}`);
+            let refs;
+            if (candidate) {
+                const digest = createHash("sha256").update(JSON.stringify({ refs: candidate.refs, target: candidate.target, generation: candidate.generation })).digest("hex");
+                if (page.snapshot?.digest === digest && (page.snapshot.usable || page.snapshot.candidate)
+                    && (!isRecord(details.refSnapshot) || typeof details.refSnapshot.snapshotId !== "string" || details.refSnapshot.snapshotId === page.snapshot.id))
+                    refs = { kind: "reuse", snapshotId: page.snapshot.id };
+                else {
+                    definition = candidate;
+                    refs = { kind: "replace", snapshotId: candidate.id };
+                }
+                page.snapshot = { id: refs.snapshotId, digest, usable: true, candidate: false };
+            }
+            else if (invalidation) {
+                refs = { kind: "invalidate", invalidation: { reason: invalidation.reason, summary: typeof invalidation.summary === "string" ? invalidation.summary : "The prior refs were invalidated; take a fresh snapshot." } };
+                page.snapshot = page.snapshot ? { ...page.snapshot, usable: false, candidate: false } : undefined;
+            }
+            else
+                refs = page.snapshot?.usable ? { kind: "reuse", snapshotId: page.snapshot.id } : { kind: "invalidate" };
+            page.pending = undefined;
+            pages.push({ key, target: page.target, unknown: page.unknown, reopenPending: page.reopenPending, refs });
+        }
+        current.pages.set(key, page);
+    }
+    if (isSessionArtifactManifest(details.artifactManifest) && (!parent.manifest || details.artifactManifest.updatedAtMs >= parent.manifest.updatedAtMs))
+        current.manifest = details.artifactManifest;
+    const artifacts = artifactChanges(parent.manifest, current.manifest);
+    if (!artifacts)
+        current.manifest = parent.manifest;
+    const state = browserStateEffects(details);
+    if (isRecord(state.electron)) {
+        const stamp = (value) => isRecord(value) ? { ...value, ownerSessionId: value.ownerSessionId ?? ownerSessionId } : value;
+        const cleanup = isRecord(state.electron.cleanup) ? state.electron.cleanup : undefined;
+        state.electron = { ...state.electron, launch: stamp(state.electron.launch), ...(cleanup ? { cleanup: {
+                    ...cleanup, records: Array.isArray(cleanup.records) ? cleanup.records.map(stamp) : cleanup.records,
+                    results: Array.isArray(cleanup.results) ? cleanup.results.map(row => isRecord(row) ? { ...row, record: stamp(row.record) } : row) : cleanup.results,
+                } } : {}) };
+    }
+    return { record: { event: { version: 1, phase, operationId, toolCallId, commandIndex, isError, state, pages, artifacts }, ...(definition ? { snapshot: definition } : {}) }, projection: current };
+}
+/** Explicit archive/in-memory conversion. Runtime restoration never invokes the legacy decoder. */
+export function convertBrowserEntries(entries, ownerSessionId) {
+    const states = new Map();
+    let linear = emptyProjection();
+    return entries.map((value, index) => {
+        if (!isRecord(value))
+            return value;
+        const entry = { ...value, id: typeof value.id === "string" ? value.id : `archive-${index}`, parentId: value.parentId ?? null };
+        const parent = typeof value.parentId === "string" ? states.get(value.parentId) ?? emptyProjection() : Object.hasOwn(value, "parentId") ? emptyProjection() : linear;
+        const converted = convertLegacyBrowserEntry(entry, parent, ownerSessionId);
+        states.set(entry.id, converted.projection);
+        linear = converted.projection;
+        return converted.record ? { ...entry, ...(entry.type === "custom" ? { customType: BROWSER_TRANSITION_ENTRY } : {}), data: converted.record } : entry;
+    });
+}
+const LEGACY_DETAILS_FIELDS = [...BROWSER_STATE_FIELDS, "browserEventVersion", "electron", "compiledNetworkSourceLookup", "sessionTabTarget", "sessionTabTargetUnknown", "sessionTabReopenPending", "refSnapshot", "refSnapshotInvalidation", "artifactManifest", "error", "summary"];
+const LEGACY_FIELDS = [
+    ["data", "event"], ["data", "snapshot"], ["data", "cleanup"], ["data", "sessionName"], ["data", "closeCommandArgs"], ["data", "launchAttempted"],
+    ["data", "toolCallId"], ["data", "isError"], ["message", "toolName"], ["message", "toolCallId"], ["message", "isError"],
+    ...["data", "message"].flatMap(root => LEGACY_DETAILS_FIELDS.map(field => [root, "details", field])),
+    ...["data", "message"].flatMap(root => [
+        ...["command", "success", "lifecycle"].map(field => [root, "details", "batchSteps", "*", field]),
+        ...[["data", "lifecycle"], ["result", "lifecycle"]].map(field => [root, "details", "batchSteps", "*", ...field]),
+    ]),
+    ...["data", "message"].flatMap(root => [
+        ...[["command"], ["success"], ["error"]].map(field => [root, "details", "data", "*", ...field]),
+        ...["url", "title", "origin", "targetId"].map(field => [root, "details", "data", "*", "result", field]),
+    ]),
+];
+async function sourceChecksum(file, size) {
+    const hash = createHash("sha256");
+    for await (const chunk of readRange(file, { offset: 0, length: size }))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+async function writeBytes(file, chunks) {
+    for await (const chunk of chunks) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        let offset = 0;
+        while (offset < buffer.length) {
+            const { bytesWritten } = await file.write(buffer, offset, buffer.length - offset);
+            if (!bytesWritten)
+                throw new Error("Could not write converted journal.");
+            offset += bytesWritten;
+        }
+    }
+}
+async function rewriteMessage(file, range, destination, record) {
+    async function* decode() {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        for await (const bytes of readRange(file, range))
+            yield decoder.decode(bytes, { stream: true });
+        const tail = decoder.decode();
+        if (tail)
+            yield tail;
+    }
+    const tokenizer = parser.asStream({ packValues: false, packKeys: true, streamKeys: false });
+    const filter = ignore.asStream({ filter: /^(?:data|message\.details\.(?:refSnapshot|artifactManifest|browserEventVersion))$/ });
+    async function* inject(tokens) {
+        let depth = 0;
+        for await (const token of tokens) {
+            if (token.name === "startObject" || token.name === "startArray")
+                depth++;
+            if (token.name === "endObject" || token.name === "endArray") {
+                depth--;
+                if (depth === 0) {
+                    yield { name: "keyValue", value: "data" };
+                    yield* disassembler({ packValues: false, packKeys: true, streamKeys: false })(record);
+                }
+            }
+            yield token;
+        }
+    }
+    const output = stringer.asStream({ useKeyValues: true });
+    const processing = pipeline(Readable.from(decode()), tokenizer, filter, inject, output);
+    try {
+        await writeBytes(destination, output);
+        await processing;
+    }
+    finally {
+        tokenizer.destroy();
+        filter.destroy();
+        output.destroy();
+    }
+    await destination.write("\n");
+}
+/** Separate-copy publication only. The operator must quiesce the exact writer first. */
+export async function convertBrowserSession(options) {
+    if (!options.confirmedStopped)
+        throw new Error("Stop/quiesce the exact session writer first, then pass --confirm-stopped. Conversion never stops a session.");
+    const source = resolve(options.source);
+    const destination = resolve(options.destination);
+    if (source === destination)
+        throw new Error("Conversion requires a separate destination; originals are never rewritten.");
+    const sourcePathStat = await lstat(source);
+    if (!sourcePathStat.isFile() || sourcePathStat.isSymbolicLink())
+        throw new Error("Conversion source must be a regular file, not a symlink.");
+    const directory = dirname(destination);
+    await mkdir(directory, { mode: 0o700, recursive: true });
+    const directoryStat = await lstat(directory);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink() || process.platform !== "win32" && (directoryStat.uid !== process.getuid?.() || (directoryStat.mode & 0o077) !== 0))
+        throw new Error("Conversion destination must be a private current-user directory (0700 on POSIX), without symlinks.");
+    try {
+        await lstat(destination);
+        throw new Error("Conversion destination is occupied.");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const file = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const stagePath = `${destination}.${randomUUID()}.tmp`;
+    let stage;
+    let published = false;
+    try {
+        const initial = await file.stat();
+        if (initial.dev !== sourcePathStat.dev || initial.ino !== sourcePathStat.ino)
+            throw new Error("Conversion source changed before capture.");
+        const checksum = await sourceChecksum(file, initial.size);
+        const metadata = await scanJournalMetadata(file, initial.size, true);
+        const header = metadata[0];
+        if (header?.value.type !== "session" || typeof header.value.id !== "string")
+            throw new Error("Conversion source has no native session header.");
+        const ids = new Set();
+        const states = new Map();
+        stage = await open(stagePath, "wx+", 0o600);
+        let convertedRecords = 0;
+        let snapshotDefinitions = 0;
+        for (const entry of metadata) {
+            let record;
+            if (entry.value.type !== "session") {
+                if (typeof entry.value.id !== "string" || ids.has(entry.value.id))
+                    throw new Error("Conversion source contains a missing or duplicate native entry ID.");
+                if (entry.value.parentId !== null && (typeof entry.value.parentId !== "string" || !ids.has(entry.value.parentId)))
+                    throw new Error("Conversion source contains a missing or forward parent.");
+                ids.add(entry.value.id);
+                const parent = typeof entry.value.parentId === "string" ? states.get(entry.value.parentId) ?? emptyProjection() : emptyProjection();
+                const relevant = entry.value.type === "custom" && [BROWSER_TRANSITION_ENTRY, "agent-browser-script-session"].includes(String(entry.value.customType))
+                    || isRecord(entry.value.message) && BROWSER_RESULT_TOOLS.has(String(entry.value.message.toolName));
+                if (relevant) {
+                    const details = await projectJson(readRange(file, entry), LEGACY_FIELDS, Infinity);
+                    const conversion = convertLegacyBrowserEntry({ ...entry.value, ...details }, parent, header.value.id);
+                    record = conversion.record;
+                    states.set(entry.value.id, conversion.projection);
+                }
+                else
+                    states.set(entry.value.id, parent);
+            }
+            if (record) {
+                const data = { ...record, archive: { sourceSha256: checksum, offset: entry.offset, length: entry.length } };
+                if (entry.value.type === "message")
+                    await rewriteMessage(file, entry, stage, data);
+                else
+                    await stage.write(`${JSON.stringify({ ...entry.value, customType: BROWSER_TRANSITION_ENTRY, data })}\n`);
+                convertedRecords++;
+                if (record.snapshot)
+                    snapshotDefinitions++;
+            }
+            else {
+                await writeBytes(stage, readRange(file, entry));
+                if (entry.offset + entry.length === initial.size) {
+                    const lastByte = Buffer.alloc(1);
+                    await file.read(lastByte, 0, 1, initial.size - 1);
+                    if (lastByte[0] !== 10)
+                        await stage.write("\n");
+                }
+            }
+        }
+        await stage.sync();
+        const output = await stage.stat();
+        const destinationSha256 = await sourceChecksum(stage, output.size);
+        const final = await file.stat();
+        const finalPath = await lstat(source);
+        if (final.dev !== initial.dev || final.ino !== initial.ino || final.size !== initial.size || final.mtimeMs !== initial.mtimeMs
+            || finalPath.dev !== initial.dev || finalPath.ino !== initial.ino || await sourceChecksum(file, initial.size) !== checksum)
+            throw new Error("Conversion source changed; no destination was published.");
+        await stage.close();
+        stage = undefined;
+        await link(stagePath, destination); // Exclusive publication; never overwrite an existing destination.
+        published = true;
+        return { version: 1, source, destination, sessionId: header.value.id, sourceSha256: checksum, destinationSha256, entryCount: ids.size,
+            convertedRecords, snapshotDefinitions, sourceBytes: initial.size, destinationBytes: output.size };
+    }
+    finally {
+        await stage?.close();
+        await file.close();
+        await unlink(stagePath).catch(error => { if (error.code !== "ENOENT")
+            throw error; });
+        if (published && process.platform !== "win32") {
+            const parent = await open(directory, constants.O_RDONLY);
+            try {
+                await parent.sync();
+            }
+            finally {
+                await parent.close();
+            }
+        }
+    }
+}

package/dist/extensions/agent-browser/lib/browser-transcript.js

@@ -1,33 +1,133 @@
 import { isRecord } from "./parsing.js";
+import { redactSensitiveValue } from "./runtime.js";
+import { buildPageTransitionRefSnapshotInvalidation, normalizeSessionTabTarget, targetsMatch } from "./session-page-state.js";
+import { getSessionArtifactManifestEntryKey, isPendingRecordingArtifact, isSessionArtifactManifest } from "./results/artifact-manifest.js";
+import { extractAgentBrowserLifecycle } from "./results/presentation/common.js";
 export const BROWSER_TRANSITION_ENTRY = "agent-browser-transition";
+export const BROWSER_EVENT_VERSION = 1;
 export const BROWSER_RESULT_TOOLS = new Set([
     "agent_browser", "agent_browser_code", "agent_browser_action", "agent_browser_qa", "agent_browser_electron",
     "agent_browser_source", "agent_browser_network_source",
 ]);
-/** Direct tools and ordered code calls replay through the same browser state reducers. */
-export function getBrowserResultMessage(entry) {
-    if (!isRecord(entry))
-        return undefined;
-    if (entry.type === "custom" && entry.customType === BROWSER_TRANSITION_ENTRY && isRecord(entry.data)) {
-        return isRecord(entry.data.details) && typeof entry.data.isError === "boolean" ? entry.data : undefined;
-    }
-    const message = entry.type === "message" && isRecord(entry.message) ? entry.message : undefined;
-    return message && typeof message.toolName === "string" && BROWSER_RESULT_TOOLS.has(message.toolName) ? message : undefined;
-}
-// Page data and rendered output are not state. Keep only fields consumed by the
-// existing replay reducers; recording reservations retain their own native journal.
-const TRANSITION_FIELDS = [
+// These are small native lifecycle/ownership receipts, not rendered page data.
+export const BROWSER_STATE_FIELDS = [
     "args", "command", "subcommand", "sessionName", "namespace", "sessionMode", "usedImplicitSession",
+    "managedSessionSocketDir",
+    "managedSessionDaemon", "ownerSessionId",
     "agentBrowserStarted", "resultCategory", "exitCode", "closeAllApplied", "attachedBrowserSession",
-    "sessionTabTarget", "sessionTabTargetUnknown", "sessionTabReopenPending", "refSnapshot", "refSnapshotInvalidation",
     "readConfirmation", "compatibilityWorkaround", "managedSessionHeadedAutosaveDisabled", "managedSessionHeadedAutosaveInterval",
-    "managedSessionOutcome", "managedSessionCwd", "managedSessionRestoreDisabled", "artifactManifest", "electron", "compiledNetworkSourceLookup",
+    "managedSessionOutcome", "managedSessionCwd", "managedSessionRestoreDisabled",
+    "nativeSucceeded",
 ];
-export function appendBrowserTransition(pi, toolCallId, details, isError) {
-    const state = Object.fromEntries(TRANSITION_FIELDS.filter(key => details[key] !== undefined).map(key => [key, details[key]]));
+export function browserStateEffects(details) {
+    const state = Object.fromEntries(BROWSER_STATE_FIELDS.filter(key => details[key] !== undefined).map(key => [key, details[key]]));
     if (Array.isArray(details.batchSteps))
         state.batchSteps = details.batchSteps.filter(isRecord).map(step => ({
-            command: step.command, success: step.success, lifecycle: step.lifecycle,
+            command: step.command, success: step.success, lifecycle: extractAgentBrowserLifecycle(step),
         }));
-    pi.appendEntry(BROWSER_TRANSITION_ENTRY, { toolCallId, details: state, isError });
+    if (isRecord(details.electron) && (details.electron.launch !== undefined || details.electron.cleanup !== undefined)) {
+        state.electron = { launch: details.electron.launch, cleanup: details.electron.cleanup };
+    }
+    return state;
+}
+export function getBrowserRecord(entry) {
+    if (!isRecord(entry) || !isRecord(entry.data))
+        return undefined;
+    if (entry.type !== "message" && !(entry.type === "custom" && entry.customType === BROWSER_TRANSITION_ENTRY))
+        return undefined;
+    const event = entry.data.event;
+    if (!isRecord(event) || event.version !== BROWSER_EVENT_VERSION)
+        return undefined;
+    if (!["begin", "finish", "state"].includes(String(event.phase)) || typeof event.operationId !== "string"
+        || typeof event.toolCallId !== "string" || !Number.isSafeInteger(event.commandIndex) || event.commandIndex < 0 || typeof event.isError !== "boolean" || !isRecord(event.state)) {
+        throw new Error("Invalid browser event; inspect or convert the retained session before browser work.");
+    }
+    if (event.pages !== undefined && (!Array.isArray(event.pages) || !event.pages.every(page => isRecord(page)
+        && typeof page.key === "string" && isRecord(page.refs) && ["reuse", "replace", "invalidate", "unknown"].includes(String(page.refs.kind))
+        && (!["reuse", "replace"].includes(String(page.refs.kind)) || typeof page.refs.snapshotId === "string" && page.refs.snapshotId.length > 0)
+        && (page.target === undefined || isRecord(page.target) && normalizeSessionTabTarget(page.target) !== undefined)
+        && (page.unknown === undefined || page.unknown === true) && (page.clear === undefined || page.clear === true)
+        && (page.reopenPending === undefined || typeof page.reopenPending === "boolean")
+        && (page.pinningReason === undefined || ["restore", "drift"].includes(String(page.pinningReason)))
+        && (page.refs.invalidation === undefined || isRecord(page.refs.invalidation) && ["page-transition", "no-active-page"].includes(String(page.refs.invalidation.reason)) && typeof page.refs.invalidation.summary === "string")))) {
+        throw new Error("Invalid browser page disposition; refs cannot be restored.");
+    }
+    if (event.artifacts !== undefined) {
+        const changes = event.artifacts;
+        if (!isRecord(changes) || !Array.isArray(changes.removals) || !changes.removals.every(key => typeof key === "string")
+            || !isSessionArtifactManifest({ version: 1, entries: changes.upserts, maxEntries: changes.maxEntries, updatedAtMs: changes.updatedAtMs, liveCount: 0, evictedCount: 0 })) {
+            throw new Error("Invalid browser artifact changes; inspect the retained journal.");
+        }
+    }
+    return entry.data;
+}
+/** Only canonical receipts participate in live replay. Legacy shapes belong to the offline converter. */
+export function getBrowserResultMessage(entry) {
+    const record = getBrowserRecord(entry);
+    return record ? { details: record.event.state, isError: typeof record.event.state.nativeSucceeded === "boolean" ? !record.event.state.nativeSucceeded : record.event.isError } : undefined;
+}
+export function snapshotDefinition(snapshot) {
+    if (!snapshot.snapshotId)
+        throw new Error("A snapshot capture must have an identity before publication.");
+    return {
+        id: snapshot.snapshotId,
+        refs: Object.fromEntries(snapshot.refIds.map(id => [id, snapshot.refs?.[id] ?? {}])),
+        target: snapshot.target,
+        generation: snapshot.generation,
+    };
+}
+export function snapshotFromDefinition(definition) {
+    if (!definition || typeof definition.id !== "string" || definition.id.length === 0 || !isRecord(definition.refs)
+        || definition.target !== undefined && normalizeSessionTabTarget(definition.target) === undefined
+        || definition.generation !== undefined && typeof definition.generation !== "string"
+        || !Object.entries(definition.refs).every(([id, ref]) => /^e\d+$/.test(id) && isRecord(ref)
+            && (ref.role === undefined || typeof ref.role === "string") && (ref.name === undefined || typeof ref.name === "string")
+            && (ref.isEditable === undefined || typeof ref.isEditable === "boolean") && (ref.isContentEditable === undefined || typeof ref.isContentEditable === "boolean"))) {
+        throw new Error("Missing or invalid browser snapshot definition; take a new complete snapshot before using refs.");
+    }
+    const refs = Object.fromEntries(Object.entries(definition.refs).flatMap(([id, ref]) => typeof ref.name === "string" && typeof ref.role === "string" ? [[id, ref]] : []));
+    return {
+        snapshotId: definition.id,
+        refIds: Object.keys(definition.refs),
+        ...(Object.keys(refs).length ? { refs } : {}),
+        target: definition.target,
+        generation: definition.generation,
+    };
+}
+export function pageChange(key, page, previousSnapshotId) {
+    return {
+        key, target: page.tabTarget, unknown: page.tabTargetUnknown, reopenPending: page.tabReopenPending, pinningReason: page.pinningReason,
+        refs: page.tabTargetUnknown ? { kind: "unknown", invalidation: page.refSnapshotInvalidation }
+            : page.refSnapshot && !targetsMatch(page.refSnapshot.target, page.tabTarget) ? { kind: "invalidate", invalidation: buildPageTransitionRefSnapshotInvalidation(`The saved refs came from a snapshot for ${page.refSnapshot.target?.url}; the current session target is ${page.tabTarget?.url}. Take a fresh snapshot before using page-scoped refs.`) }
+                : page.refSnapshot?.snapshotId ? { kind: page.refSnapshot.snapshotId === previousSnapshotId ? "reuse" : "replace", snapshotId: page.refSnapshot.snapshotId }
+                    : { kind: "invalidate", invalidation: page.refSnapshotInvalidation },
+    };
+}
+export function artifactChanges(previous, next) {
+    if (previous === next)
+        return undefined;
+    const before = new Map((previous?.entries ?? []).map(row => [getSessionArtifactManifestEntryKey(row), row]));
+    const after = new Map((next?.entries ?? []).map(row => [getSessionArtifactManifestEntryKey(row), row]));
+    const upserts = [...after].filter(([key, row]) => JSON.stringify(before.get(key)) !== JSON.stringify(row)).map(([, row]) => redactSensitiveValue(row));
+    const removals = [...before.keys()].filter(key => !after.has(key));
+    return upserts.length || removals.length ? { upserts, removals, maxEntries: next?.maxEntries ?? previous?.maxEntries ?? 100, updatedAtMs: next?.updatedAtMs ?? Date.now() } : undefined;
+}
+export function applyArtifactChanges(previous, changes) {
+    if (!changes)
+        return previous;
+    const rows = new Map((previous?.entries ?? []).map(row => [getSessionArtifactManifestEntryKey(row), row]));
+    for (const key of changes.removals)
+        rows.delete(key);
+    for (const row of changes.upserts)
+        rows.set(getSessionArtifactManifestEntryKey(row), row);
+    const entries = [...rows.values()].sort((a, b) => (b.evictedAtMs ?? b.createdAtMs) - (a.evictedAtMs ?? a.createdAtMs)
+        || Number(isPendingRecordingArtifact(b)) - Number(isPendingRecordingArtifact(a)) || a.path.localeCompare(b.path)).slice(0, changes.maxEntries);
+    const manifest = { version: 1, entries, maxEntries: changes.maxEntries, updatedAtMs: changes.updatedAtMs,
+        liveCount: entries.filter(row => row.retentionState === "live").length, evictedCount: entries.filter(row => row.retentionState === "evicted").length };
+    if (!isSessionArtifactManifest(manifest))
+        throw new Error("Invalid browser artifact changes; inspect the retained journal.");
+    return entries.length ? manifest : undefined;
+}
+export function appendBrowserTransition(pi, record) {
+    pi.appendEntry(BROWSER_TRANSITION_ENTRY, record);
 }

package/dist/extensions/agent-browser/lib/input-modes/job.js

@@ -1,5 +1,6 @@
 import { isRecord } from "../parsing.js";
 import { summarizeNetworkFailures } from "../results/network.js";
+import { truncateText } from "../results/text.js";
 import { getBatchResultItems, getCommandNameFromBatchItem } from "./shared.js";
 import { AGENT_BROWSER_QA_LOAD_STATES, } from "./types.js";
 function describeQaChecksRun(checks) {
@@ -61,15 +62,19 @@ export function buildQaCompactPassText(options) {
     return lines.join("\n");
 }
 export function buildQaCompactFailureText(options) {
-    const lines = [options.qaPreset.summary];
+    const lines = [options.causalError
+            ? truncateText(options.causalError.replace(/\s+/g, " ").trim(), 700)
+            : options.qaPreset.summary];
     const pageParts = [options.page?.title, options.page?.url].filter((part) => typeof part === "string" && part.length > 0);
     if (pageParts.length > 0)
         lines.push(`Page: ${pageParts.join(" — ")}`);
     if (options.qaPreset.failedChecks.length > 0)
         lines.push("Failed checks:", ...options.qaPreset.failedChecks.map((failure) => `- ${failure}`));
+    if (options.qaPreset.notRunChecks.length > 0)
+        lines.push("Not run:", ...options.qaPreset.notRunChecks.map((check) => `- ${check}`));
     if (options.qaPreset.warnings.length > 0)
         lines.push("Warnings:", ...options.qaPreset.warnings.map((warning) => `- ${warning}`));
-    lines.push(`Checks run: ${describeQaChecksRun(options.checks)} (${options.batchStepCount} batch step${options.batchStepCount === 1 ? "" : "s"})`);
+    lines.push(`Execution: ${options.executedStepCount ?? "unknown"}/${options.plannedStepCount} batch steps`);
     lines.push("Full diagnostic matrix: see details.qaPreset and details.batchSteps.");
     return lines.join("\n");
 }
@@ -182,11 +187,45 @@ export function analyzeQaPresetTimeout(compiled) {
     const failedChecks = compiled.checks.expectedText.map((text) => `expected text was not verified before timeout: ${formatQaExpectedTextPreview(text)}`);
     return {
         failedChecks,
+        notRunChecks: [],
         passed: false,
         summary: `QA preset failed: ${failedChecks.join("; ")}.`,
         warnings: ["The wrapper timed out before expected-text evidence could be verified; inspect timeoutPartialProgress and retry with a narrower readiness condition if the page was still loading."],
     };
 }
+function describeNotRunQaChecks(compiled, executedStepCount) {
+    const checks = [];
+    let expectedTextIndex = 0;
+    for (const [index, step] of compiled.steps.entries()) {
+        let check;
+        if (step.action === "assertText") {
+            const expected = compiled.checks.expectedText[expectedTextIndex++];
+            if (expected)
+                check = `expected text: ${formatQaExpectedTextPreview(expected)}`;
+        }
+        else if (step.args[0] === "wait" && step.args[1] === "--load") {
+            check = `load state: ${step.args[2]}`;
+        }
+        else if (compiled.checks.expectedSelector && step.args[0] === "wait" && step.args[1] === compiled.checks.expectedSelector) {
+            check = `expected selector: ${formatQaExpectedTextPreview(compiled.checks.expectedSelector)}`;
+        }
+        else if (step.args[0] === "network" && !step.args.includes("--clear")) {
+            check = "network diagnostics";
+        }
+        else if (step.args[0] === "console" && !step.args.includes("--clear")) {
+            check = "console diagnostics";
+        }
+        else if (step.args[0] === "errors" && !step.args.includes("--clear") && step.generatedFrom !== "qa.errorBaselineAfterClear") {
+            check = "page error diagnostics";
+        }
+        else if (step.action === "screenshot") {
+            check = `screenshot: ${formatQaExpectedTextPreview(step.args[1] ?? "")}`;
+        }
+        if (index >= executedStepCount && check)
+            checks.push(check);
+    }
+    return checks;
+}
 export function analyzeQaPresetResults(data, compiled) {
     const items = getBatchResultItems(data);
     if (items.length === 0)
@@ -238,6 +277,8 @@ export function analyzeQaPresetResults(data, compiled) {
             const expected = compiled.checks.expectedText[expectedTextIndex++];
             if (!expected)
                 return;
+            if (!items[index])
+                return;
             const visibleTextPassed = qaVisibleTextWaitPassed(items[index], step);
             if (visibleTextPassed === true)
                 return;
@@ -246,10 +287,16 @@ export function analyzeQaPresetResults(data, compiled) {
                 failedChecks.push(`expected text not found: ${formatQaExpectedTextPreview(expected)}`);
         });
     }
+    const stoppedEarly = compiled && items.length < compiled.steps.length;
+    const failedFast = stoppedEarly && items.at(-1)?.success === false;
+    if (stoppedEarly && !failedFast)
+        failedChecks.push("QA execution could not be verified (incomplete batch results)");
     const uniqueFailures = [...new Set(failedChecks)];
     const uniqueWarnings = [...new Set(warnings)];
+    const notRunChecks = compiled && failedFast ? describeNotRunQaChecks(compiled, items.length) : [];
     return {
         failedChecks: uniqueFailures,
+        notRunChecks,
         passed: uniqueFailures.length === 0,
         summary: uniqueFailures.length === 0
             ? uniqueWarnings.length === 0 ? "QA preset passed." : `QA preset passed with warnings: ${uniqueWarnings.join("; ")}.`