pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/browser-legacy-pages.js

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+import { snapshotDefinition, } from "./browser-transcript.js";
+import { browserStringArray } from "./browser-value-parsing.js";
+import { isRecord } from "./parsing.js";
+import { isReadOnlyDiagnosticSessionTargetCommand } from "./command-taxonomy.js";
+import { normalizeSessionTabTarget, extractSessionTabTargetFromBatchResults, isNoActivePageSnapshotFailure, buildNoActivePageRefSnapshotInvalidation, } from "./session-page-observation.js";
+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 legacySnapshot(value, id) {
+    if (!isRecord(value) || !Array.isArray(value.refIds)) {
+        return undefined;
+    }
+    const refIds = browserStringArray(value.refIds).filter((ref) => /^e\d+$/.test(ref));
+    const sourceRefs = isRecord(value.refs) ? value.refs : {};
+    return snapshotDefinition({
+        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,
+    });
+}
+function snapshotDigest(definition) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        refs: definition.refs,
+        target: definition.target,
+        generation: definition.generation,
+    }))
+        .digest("hex");
+}
+export function canonicalPage(prior, canonical, page) {
+    const definition = isRecord(canonical.snapshot) ? canonical.snapshot : undefined;
+    const digest = definition !== undefined && Boolean(definition.refs)
+        ? snapshotDigest(definition)
+        : (prior.snapshot?.digest ?? "");
+    let snapshot;
+    if (page.refs.kind === "replace" || page.refs.kind === "reuse") {
+        snapshot = { id: page.refs.snapshotId, digest, usable: true, candidate: false };
+    }
+    else if (prior.snapshot) {
+        snapshot = { ...prior.snapshot, usable: false, candidate: canonical.event.phase === "begin" };
+    }
+    return {
+        target: page.target,
+        unknown: page.unknown,
+        reopenPending: page.reopenPending,
+        snapshot,
+        pending: canonical.event.phase === "begin"
+            ? {
+                operationId: canonical.event.operationId,
+                toolCallId: canonical.event.toolCallId,
+                index: canonical.event.commandIndex,
+            }
+            : undefined,
+    };
+}
+function parseInvalidation(value, fallbackSummary) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    if (value.reason !== "no-active-page" && value.reason !== "page-transition") {
+        throw new Error("Invalid legacy browser ref invalidation.");
+    }
+    if (typeof value.summary === "string") {
+        return { reason: value.reason, summary: value.summary };
+    }
+    if (fallbackSummary) {
+        return {
+            reason: value.reason,
+            summary: "The prior refs were invalidated; take a fresh snapshot.",
+        };
+    }
+    throw new Error("Invalid legacy browser ref invalidation summary.");
+}
+function observedInvalidation(ctx) {
+    const value = ctx.details.refSnapshotInvalidation;
+    if (isRecord(value) &&
+        (value.reason === "no-active-page" || value.reason === "page-transition")) {
+        return parseInvalidation(value, true);
+    }
+    let error;
+    if (typeof ctx.details.error === "string") {
+        error = ctx.details.error;
+    }
+    else if (typeof ctx.details.summary === "string") {
+        error = ctx.details.summary;
+    }
+    return isNoActivePageSnapshotFailure(ctx.command, error)
+        ? buildNoActivePageRefSnapshotInvalidation()
+        : undefined;
+}
+function snapshotReusable(page, details, digest) {
+    return (page.snapshot?.digest === digest &&
+        (page.snapshot.usable || page.snapshot.candidate) &&
+        (!isRecord(details.refSnapshot) ||
+            typeof details.refSnapshot.snapshotId !== "string" ||
+            details.refSnapshot.snapshotId === page.snapshot.id));
+}
+/** One legacy entry owns a shallow page draft; previous snapshots and parent views are never mutated. */
+export class LegacyPageConversion {
+    ctx;
+    page;
+    definition;
+    constructor(ctx, prior) {
+        this.ctx = ctx;
+        this.page = { ...prior };
+    }
+    knownTarget() {
+        const { details, command, subcommand } = this.ctx;
+        if (!isRecord(details.compiledNetworkSourceLookup) &&
+            !isReadOnlyDiagnosticSessionTargetCommand(command, subcommand) &&
+            isRecord(details.sessionTabTarget)) {
+            this.page.target = legacyTarget(details.sessionTabTarget) ?? this.page.target;
+        }
+        else if (command === "batch" && !isRecord(details.compiledNetworkSourceLookup)) {
+            this.page.target = extractSessionTabTargetFromBatchResults(details.data) ?? this.page.target;
+        }
+        if (this.page.target) {
+            this.page.unknown = undefined;
+        }
+        if (typeof details.sessionTabReopenPending === "boolean") {
+            this.page.reopenPending = details.sessionTabReopenPending;
+        }
+    }
+    knownRefs() {
+        const invalidation = observedInvalidation(this.ctx);
+        const candidate = invalidation
+            ? undefined
+            : legacySnapshot(this.ctx.details.refSnapshot, `snapshot-${this.ctx.nativeId}`);
+        if (candidate) {
+            const digest = snapshotDigest(candidate);
+            let refs;
+            if (snapshotReusable(this.page, this.ctx.details, digest) && this.page.snapshot) {
+                refs = { kind: "reuse", snapshotId: this.page.snapshot.id };
+            }
+            else {
+                this.definition = candidate;
+                refs = { kind: "replace", snapshotId: candidate.id };
+            }
+            this.page.snapshot = { id: refs.snapshotId, digest, usable: true, candidate: false };
+            return refs;
+        }
+        if (invalidation) {
+            this.disableSnapshot(false);
+            return { kind: "invalidate", invalidation };
+        }
+        return this.page.snapshot?.usable === true
+            ? { kind: "reuse", snapshotId: this.page.snapshot.id }
+            : { kind: "invalidate" };
+    }
+    disableSnapshot(candidate) {
+        if (this.page.snapshot) {
+            this.page.snapshot = { ...this.page.snapshot, usable: false, candidate };
+        }
+    }
+    change(key) {
+        const ctx = this.ctx;
+        if (ctx.begin) {
+            this.page.target = undefined;
+            this.page.unknown = true;
+            this.page.snapshot = ctx.prior.snapshot
+                ? { ...ctx.prior.snapshot, usable: false, candidate: true }
+                : undefined;
+            this.page.pending = {
+                toolCallId: ctx.toolCallId,
+                operationId: ctx.operationId,
+                index: ctx.commandIndex,
+            };
+            return { key, refs: { kind: "unknown" }, unknown: true };
+        }
+        if (ctx.details.sessionTabTargetUnknown === true) {
+            this.page.target = undefined;
+            this.page.unknown = true;
+            this.page.pending = undefined;
+            this.disableSnapshot(false);
+            return {
+                key,
+                refs: {
+                    kind: "unknown",
+                    invalidation: parseInvalidation(ctx.details.refSnapshotInvalidation, false),
+                },
+                unknown: true,
+            };
+        }
+        this.knownTarget();
+        const refs = this.knownRefs();
+        this.page.pending = undefined;
+        return {
+            key,
+            target: this.page.target,
+            unknown: this.page.unknown,
+            reopenPending: this.page.reopenPending,
+            refs,
+        };
+    }
+}

package/dist/extensions/agent-browser/lib/browser-legacy-projection.js

@@ -0,0 +1,282 @@
+import { randomUUID } from "node:crypto";
+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_TRANSITION_ENTRY, applyArtifactChanges, artifactChanges, browserStateEffects, getBrowserRecord, } from "./browser-transcript.js";
+import { isCloseAllCommand, isCloseCommand } from "./command-taxonomy.js";
+import { isRecord } from "./parsing.js";
+import { isSessionArtifactManifest } from "./results/artifact-manifest.js";
+import { browserStringArray } from "./browser-value-parsing.js";
+import { canonicalPage, LegacyPageConversion } from "./browser-legacy-pages.js";
+export const emptyProjection = () => ({ pages: new Map(), nextIndex: 0 });
+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 isLegacyToolMessage(message) ? message : undefined;
+}
+function isLegacyToolMessage(message) {
+    return (message !== undefined &&
+        typeof message.toolName === "string" &&
+        BROWSER_RESULT_TOOLS.has(message.toolName) &&
+        isRecord(message.details) &&
+        message.details.browserEventVersion !== 1);
+}
+function applyCanonical(current, parent, canonical) {
+    current.manifest = applyArtifactChanges(parent.manifest, canonical.event.artifacts);
+    for (const page of canonical.event.pages ?? []) {
+        if (page.clear === true) {
+            current.pages.delete(page.key);
+            continue;
+        }
+        current.pages.set(page.key, canonicalPage(current.pages.get(page.key) ?? {}, canonical, page));
+    }
+}
+function scriptRecord(entry, nativeId, ownerSessionId) {
+    if (entry.type !== "custom" ||
+        entry.customType !== "agent-browser-script-session" ||
+        !isRecord(entry.data)) {
+        return undefined;
+    }
+    return {
+        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 },
+            },
+        },
+    };
+}
+function isLegacyBegin(entry, details) {
+    return (entry.type === "custom" &&
+        details.sessionTabTargetUnknown === true &&
+        details.command === undefined &&
+        details.exitCode === undefined &&
+        details.agentBrowserStarted === undefined);
+}
+function legacyIdentity(details) {
+    const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
+    const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
+    const key = sessionName !== undefined && sessionName.length > 0
+        ? getAgentBrowserSessionIdentityKey(sessionName, namespace)
+        : undefined;
+    const tokens = extractUpstreamCommandTokens(browserStringArray(details.args));
+    return {
+        key,
+        namespace,
+        tokens,
+        command: typeof details.command === "string" ? details.command : tokens[0],
+        subcommand: typeof details.subcommand === "string" ? details.subcommand : tokens[1],
+    };
+}
+function legacyPrior(key, current) {
+    return key === undefined ? {} : (current.pages.get(key) ?? {});
+}
+function operationIdentity(options, current) {
+    const prior = legacyPrior(options.key, current);
+    const begin = isLegacyBegin(options.entry, options.details);
+    const pending = prior.pending?.toolCallId === options.toolCallId ? prior.pending : undefined;
+    let phase = "state";
+    if (begin) {
+        phase = "begin";
+    }
+    else if (pending) {
+        phase = "finish";
+    }
+    let commandIndex = pending?.index ?? 0;
+    if (begin) {
+        commandIndex = current.nextIndex;
+        current.nextIndex++;
+    }
+    return {
+        prior,
+        begin,
+        phase,
+        commandIndex,
+        operationId: pending?.operationId ?? `legacy-${options.nativeId}`,
+    };
+}
+function context(entry, message, details, current) {
+    const nativeId = typeof entry.id === "string" ? entry.id : randomUUID();
+    const toolCallId = typeof message.toolCallId === "string" ? message.toolCallId : `legacy-${nativeId}`;
+    const identity = legacyIdentity(details);
+    const operation = operationIdentity({ entry, details, key: identity.key, toolCallId, nativeId }, current);
+    return {
+        ...identity,
+        ...operation,
+        nativeId,
+        details,
+        isError: message.isError === true,
+        toolCallId,
+    };
+}
+function closingLifecycle(ctx) {
+    const close = getSuccessfulBatchCloseLifecycle(ctx.details.batchSteps);
+    const closeAll = ctx.details.closeAllApplied === true ||
+        (!ctx.isError && isCloseAllCommand(ctx.tokens)) ||
+        batchHasSuccessfulCloseAll(ctx.details.batchSteps);
+    return {
+        closeAll,
+        lifecycleReset: (!ctx.isError && isCloseCommand(ctx.command)) || close !== undefined,
+        endsClosed: close?.endsClosed === true,
+    };
+}
+function closePages(current, ctx) {
+    const closing = closingLifecycle(ctx);
+    const pages = [];
+    if (closing.closeAll) {
+        for (const key of current.pages.keys()) {
+            if (isAgentBrowserSessionIdentityKeyInNamespace(key, ctx.namespace)) {
+                current.pages.delete(key);
+                pages.push({ key, clear: true, refs: { kind: "invalidate" } });
+            }
+        }
+    }
+    else if (ctx.key !== undefined && closing.lifecycleReset) {
+        current.pages.delete(ctx.key);
+        pages.push({ key: ctx.key, clear: true, refs: { kind: "invalidate" } });
+    }
+    return { ...closing, pages };
+}
+function hasPageEffects(ctx) {
+    return (ctx.begin ||
+        [
+            "sessionTabTargetUnknown",
+            "sessionTabTarget",
+            "sessionTabReopenPending",
+            "refSnapshot",
+            "refSnapshotInvalidation",
+        ].some((field) => ctx.details[field] !== undefined) ||
+        (ctx.command === "batch" && Array.isArray(ctx.details.data)));
+}
+function stampElectronState(state, ownerSessionId) {
+    if (!isRecord(state.electron)) {
+        return state;
+    }
+    const stamp = (value) => isRecord(value) ? { ...value, ownerSessionId: value.ownerSessionId ?? ownerSessionId } : value;
+    const cleanup = isRecord(state.electron.cleanup) ? state.electron.cleanup : undefined;
+    return {
+        ...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,
+                    },
+                }
+                : {}),
+        },
+    };
+}
+function updateManifest(current, parent, details) {
+    if (isSessionArtifactManifest(details.artifactManifest) &&
+        (!parent.manifest || details.artifactManifest.updatedAtMs >= parent.manifest.updatedAtMs)) {
+        current.manifest = details.artifactManifest;
+    }
+    const changes = artifactChanges(parent.manifest, current.manifest);
+    if (!changes) {
+        current.manifest = parent.manifest;
+    }
+    return changes;
+}
+function convertMessage(ctx, parent, current, ownerSessionId) {
+    const closing = closePages(current, ctx);
+    const pages = closing.pages;
+    let definition;
+    const suppressPage = (closing.closeAll || closing.lifecycleReset) &&
+        (isCloseCommand(ctx.command) || closing.endsClosed);
+    if (ctx.key !== undefined && hasPageEffects(ctx) && !suppressPage) {
+        const conversion = new LegacyPageConversion(ctx, current.pages.get(ctx.key) ?? {});
+        pages.push(conversion.change(ctx.key));
+        current.pages.set(ctx.key, conversion.page);
+        definition = conversion.definition;
+    }
+    const artifacts = updateManifest(current, parent, ctx.details);
+    return {
+        event: {
+            version: 1,
+            phase: ctx.phase,
+            operationId: ctx.operationId,
+            toolCallId: ctx.toolCallId,
+            commandIndex: ctx.commandIndex,
+            isError: ctx.isError,
+            state: stampElectronState(browserStateEffects(ctx.details), ownerSessionId),
+            pages,
+            artifacts,
+        },
+        ...(definition ? { snapshot: definition } : {}),
+    };
+}
+/** Offline only: normalize old receipts along their actual parent ancestry, never physical equality. */
+export function convertLegacyBrowserEntry(entry, parent = emptyProjection(), ownerSessionId) {
+    const current = {
+        pages: new Map(parent.pages),
+        manifest: parent.manifest,
+        nextIndex: parent.nextIndex,
+    };
+    const canonical = getBrowserRecord(entry);
+    if (canonical) {
+        applyCanonical(current, parent, canonical);
+        return { projection: current };
+    }
+    const script = scriptRecord(entry, typeof entry.id === "string" ? entry.id : randomUUID(), ownerSessionId);
+    if (script) {
+        return { record: script, projection: current };
+    }
+    const message = legacyMessage(entry);
+    if (!message || !isRecord(message.details)) {
+        return { projection: parent };
+    }
+    return {
+        record: convertMessage(context(entry, message, message.details, current), parent, current, ownerSessionId),
+        projection: current,
+    };
+}
+function archiveParent(value, states, linear) {
+    if (typeof value.parentId === "string") {
+        return states.get(value.parentId) ?? emptyProjection();
+    }
+    return Object.hasOwn(value, "parentId") ? emptyProjection() : linear;
+}
+/** Explicit archive 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 converted = convertLegacyBrowserEntry(entry, archiveParent(value, states, linear), 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;
+    });
+}

package/dist/extensions/agent-browser/lib/browser-legacy-types.js

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