pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -0,0 +1,166 @@
+import { isRecord } from "./parsing.js";
+import { isBrowserStringArray } from "./browser-value-parsing.js";
+import { isSessionArtifactManifest } from "./results/artifact-manifest.js";
+import { normalizeSessionTabTarget, } from "./session-page-observation.js";
+function validRefText(value) {
+    return ((value.role === undefined || typeof value.role === "string") &&
+        (value.name === undefined || typeof value.name === "string"));
+}
+function validRefFlags(value) {
+    return ((value.isEditable === undefined || typeof value.isEditable === "boolean") &&
+        (value.isContentEditable === undefined || typeof value.isContentEditable === "boolean"));
+}
+export function isBrowserSnapshotReference(value) {
+    return isRecord(value) && validRefText(value) && validRefFlags(value);
+}
+export function isNamedBrowserSnapshotReference(value) {
+    return (isBrowserSnapshotReference(value) &&
+        typeof value.name === "string" &&
+        typeof value.role === "string");
+}
+function invalidEvent() {
+    throw new Error("Invalid browser event; inspect or convert the retained session before browser work.");
+}
+function invalidPage() {
+    throw new Error("Invalid browser page disposition; refs cannot be restored.");
+}
+function parseInvalidation(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isRecord(value) ||
+        (value.reason !== "page-transition" && value.reason !== "no-active-page") ||
+        typeof value.summary !== "string") {
+        return invalidPage();
+    }
+    return { ...value, reason: value.reason, summary: value.summary };
+}
+function parseRefs(value) {
+    if (!isRecord(value)) {
+        return invalidPage();
+    }
+    if (value.kind === "reuse" || value.kind === "replace") {
+        if (typeof value.snapshotId !== "string" || value.snapshotId.length === 0) {
+            return invalidPage();
+        }
+        return { ...value, kind: value.kind, snapshotId: value.snapshotId };
+    }
+    if (value.kind !== "unknown" && value.kind !== "invalidate") {
+        return invalidPage();
+    }
+    const invalidation = parseInvalidation(value.invalidation);
+    return { ...value, kind: value.kind, ...(invalidation ? { invalidation } : {}) };
+}
+export function decodeBrowserTarget(value) {
+    if (!isRecord(value) || typeof value.url !== "string") {
+        return undefined;
+    }
+    if ((value.title !== undefined && typeof value.title !== "string") ||
+        (value.targetId !== undefined && typeof value.targetId !== "string")) {
+        return undefined;
+    }
+    const target = { ...value, url: value.url };
+    return normalizeSessionTabTarget(target) === undefined ? undefined : target;
+}
+function parseBrowserTarget(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return decodeBrowserTarget(value) ?? invalidPage();
+}
+function pageScalarsValid(value) {
+    return ((value.confirmActions === undefined ||
+        value.confirmActions === null ||
+        typeof value.confirmActions === "string") &&
+        (value.unknown === undefined || value.unknown === true) &&
+        (value.clear === undefined || value.clear === true));
+}
+function pagePolicyValid(value) {
+    return ((value.reopenPending === undefined || typeof value.reopenPending === "boolean") &&
+        (value.pinningReason === undefined ||
+            value.pinningReason === "restore" ||
+            value.pinningReason === "drift"));
+}
+function parsePage(value) {
+    if (!isRecord(value) ||
+        typeof value.key !== "string" ||
+        !pageScalarsValid(value) ||
+        !pagePolicyValid(value)) {
+        return invalidPage();
+    }
+    const target = parseBrowserTarget(value.target);
+    return { ...value, key: value.key, refs: parseRefs(value.refs), ...(target ? { target } : {}) };
+}
+function parsePages(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        return invalidPage();
+    }
+    const pages = value;
+    return pages.map(parsePage);
+}
+function parseArtifacts(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isRecord(value) || !isBrowserStringArray(value.removals)) {
+        throw new Error("Invalid browser artifact changes; inspect the retained journal.");
+    }
+    const manifest = {
+        version: 1,
+        entries: value.upserts,
+        maxEntries: value.maxEntries,
+        updatedAtMs: value.updatedAtMs,
+        liveCount: 0,
+        evictedCount: 0,
+    };
+    if (!isSessionArtifactManifest(manifest)) {
+        throw new Error("Invalid browser artifact changes; inspect the retained journal.");
+    }
+    return {
+        ...value,
+        upserts: manifest.entries,
+        removals: value.removals,
+        maxEntries: manifest.maxEntries,
+        updatedAtMs: manifest.updatedAtMs,
+    };
+}
+function eventIdentity(value) {
+    if (typeof value.operationId !== "string" ||
+        typeof value.toolCallId !== "string" ||
+        typeof value.commandIndex !== "number" ||
+        !Number.isSafeInteger(value.commandIndex) ||
+        value.commandIndex < 0 ||
+        typeof value.isError !== "boolean") {
+        return invalidEvent();
+    }
+    return {
+        operationId: value.operationId,
+        toolCallId: value.toolCallId,
+        commandIndex: value.commandIndex,
+        isError: value.isError,
+    };
+}
+export function parseBrowserEvent(value) {
+    const phase = value.phase;
+    if (phase !== "begin" && phase !== "finish" && phase !== "state") {
+        return invalidEvent();
+    }
+    if (!isRecord(value.state)) {
+        return invalidEvent();
+    }
+    const identity = eventIdentity(value);
+    const pages = parsePages(value.pages);
+    const artifacts = parseArtifacts(value.artifacts);
+    return {
+        ...value,
+        ...identity,
+        version: 1,
+        phase,
+        state: value.state,
+        ...(pages ? { pages } : {}),
+        ...(artifacts ? { artifacts } : {}),
+    };
+}

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

@@ -1,133 +1,188 @@
 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 { redactSensitiveValue } from "./runtime-redaction.js";
+import { buildPageTransitionRefSnapshotInvalidation, targetsMatch, } from "./session-page-observation.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";
+import { BROWSER_TRANSITION_ENTRY, BROWSER_STATE_FIELDS, } from "./browser-transcript-contracts.js";
+export { BROWSER_TRANSITION_ENTRY, BROWSER_STATE_FIELDS, BROWSER_RESULT_TOOLS, } from "./browser-transcript-contracts.js";
 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",
-]);
-// 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",
-    "readConfirmation", "compatibilityWorkaround", "managedSessionHeadedAutosaveDisabled", "managedSessionHeadedAutosaveInterval",
-    "managedSessionOutcome", "managedSessionCwd", "managedSessionRestoreDisabled",
-    "nativeSucceeded",
-];
+import { parseBrowserEvent, decodeBrowserTarget, isBrowserSnapshotReference, isNamedBrowserSnapshotReference, } from "./browser-transcript-validation.js";
 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: extractAgentBrowserLifecycle(step),
+    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: extractAgentBrowserLifecycle(step),
         }));
-    if (isRecord(details.electron) && (details.electron.launch !== undefined || details.electron.cleanup !== undefined)) {
+    }
+    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))
+    if (!isRecord(entry) || !isRecord(entry.data)) {
         return undefined;
-    if (entry.type !== "message" && !(entry.type === "custom" && entry.customType === BROWSER_TRANSITION_ENTRY))
+    }
+    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)
+    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))
-        && (page.confirmActions === undefined || page.confirmActions === null || typeof page.confirmActions === "string")
-        && (!["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;
+    return { ...entry.data, event: parseBrowserEvent(event) };
 }
 /** 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;
+    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)
+    if (snapshot.snapshotId === undefined || snapshot.snapshotId.length === 0) {
         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] ?? {}])),
+        refs: Object.fromEntries(snapshot.refIds.map((id) => [id, snapshot.refs?.[id] ?? {}])),
         target: snapshot.target,
         generation: snapshot.generation,
     };
 }
+function snapshotMetadataValid(definition) {
+    return ((definition.target === undefined || decodeBrowserTarget(definition.target) !== undefined) &&
+        (definition.generation === undefined || typeof definition.generation === "string"));
+}
 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"))) {
+    if (!isRecord(definition) ||
+        typeof definition.id !== "string" ||
+        definition.id.length === 0 ||
+        !isRecord(definition.refs) ||
+        !snapshotMetadataValid(definition) ||
+        !Object.entries(definition.refs).every(([id, ref]) => /^e\d+$/.test(id) && isBrowserSnapshotReference(ref))) {
         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]] : []));
+    const refs = Object.fromEntries(Object.entries(definition.refs).flatMap(([id, ref]) => isNamedBrowserSnapshotReference(ref) ? [[id, ref]] : []));
     return {
         snapshotId: definition.id,
         refIds: Object.keys(definition.refs),
-        ...(Object.keys(refs).length ? { refs } : {}),
-        target: definition.target,
-        generation: definition.generation,
+        ...(Object.keys(refs).length > 0 ? { refs } : {}),
+        target: definition.target === undefined ? undefined : decodeBrowserTarget(definition.target),
+        generation: typeof definition.generation === "string" ? definition.generation : undefined,
     };
 }
+function driftedRefDisposition(page) {
+    return {
+        kind: "invalidate",
+        invalidation: buildPageTransitionRefSnapshotInvalidation(`The saved refs came from a snapshot for ${page.refSnapshot?.target?.url ?? "unknown"}; the current session target is ${page.tabTarget?.url ?? "unknown"}. Take a fresh snapshot before using page-scoped refs.`),
+    };
+}
+function pageRefDisposition(page, previousSnapshotId) {
+    if (page.tabTargetUnknown === true) {
+        return { kind: "unknown", invalidation: page.refSnapshotInvalidation };
+    }
+    if (page.refSnapshot && !targetsMatch(page.refSnapshot.target, page.tabTarget)) {
+        return driftedRefDisposition(page);
+    }
+    const id = page.refSnapshot?.snapshotId;
+    if (id !== undefined && id.length > 0) {
+        return { kind: id === previousSnapshotId ? "reuse" : "replace", snapshotId: id };
+    }
+    return { kind: "invalidate", invalidation: page.refSnapshotInvalidation };
+}
 export function pageChange(key, page, previousSnapshotId) {
     return {
-        key, confirmActions: page.confirmActions ?? null, 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 },
+        key,
+        confirmActions: page.confirmActions ?? null,
+        target: page.tabTarget,
+        unknown: page.tabTargetUnknown,
+        reopenPending: page.tabReopenPending,
+        pinningReason: page.pinningReason,
+        refs: pageRefDisposition(page, previousSnapshotId),
     };
 }
+function indexedArtifacts(manifest) {
+    return new Map((manifest?.entries ?? []).map((row) => [getSessionArtifactManifestEntryKey(row), row]));
+}
+function redactedArtifact(row) {
+    const manifest = {
+        version: 1,
+        entries: [redactSensitiveValue(row)],
+        maxEntries: 1,
+        updatedAtMs: row.createdAtMs,
+        liveCount: 0,
+        evictedCount: 0,
+    };
+    if (!isSessionArtifactManifest(manifest)) {
+        throw new Error("Redacted browser artifact has no valid manifest receipt.");
+    }
+    return manifest.entries[0];
+}
 export function artifactChanges(previous, next) {
-    if (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;
+    }
+    const before = indexedArtifacts(previous);
+    const after = indexedArtifacts(next);
+    const upserts = [...after]
+        .filter(([key, row]) => JSON.stringify(before.get(key)) !== JSON.stringify(row))
+        .map(([, row]) => redactedArtifact(row));
+    const removals = [...before.keys()].filter((key) => !after.has(key));
+    return upserts.length > 0 || removals.length > 0
+        ? {
+            upserts,
+            removals,
+            maxEntries: (next ?? previous)?.maxEntries ?? 100,
+            updatedAtMs: next?.updatedAtMs ?? Date.now(),
+        }
+        : undefined;
 }
 export function applyArtifactChanges(previous, changes) {
-    if (!changes)
+    if (!changes) {
         return previous;
-    const rows = new Map((previous?.entries ?? []).map(row => [getSessionArtifactManifestEntryKey(row), row]));
-    for (const key of changes.removals)
+    }
+    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)
+    }
+    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))
+    }
+    const entries = [...rows.values()]
+        .sort((a, b) => {
+        const age = (b.evictedAtMs ?? b.createdAtMs) - (a.evictedAtMs ?? a.createdAtMs);
+        if (age !== 0) {
+            return age;
+        }
+        const pending = Number(isPendingRecordingArtifact(b)) - Number(isPendingRecordingArtifact(a));
+        return pending !== 0 ? pending : 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;
+    }
+    return entries.length > 0 ? manifest : undefined;
 }
 export function appendBrowserTransition(pi, record) {
     pi.appendEntry(BROWSER_TRANSITION_ENTRY, record);

package/dist/extensions/agent-browser/lib/browser-value-parsing.js

@@ -0,0 +1,15 @@
+export function isBrowserStringArray(value) {
+    if (!Array.isArray(value)) {
+        return false;
+    }
+    const rows = value;
+    return rows.every((row) => typeof row === "string");
+}
+/** Normalize only string rows from an untrusted native/transcript array, retaining their order. */
+export function browserStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const rows = value;
+    return rows.filter((row) => typeof row === "string");
+}