pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -0,0 +1,221 @@
+import { Readable, Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { isRecord } from "./parsing.js";
+import { normalizeProcessError } from "./process-errors.js";
+const ENVELOPE_MAX_BYTES = 16 * 1024 * 1024;
+function matches(field, key) {
+    return field === key || (field === "*" && typeof key === "number");
+}
+function selectedPath(path, fields) {
+    return fields.some((field) => field.every((key, index) => matches(key, path[index])) ||
+        path.every((key, index) => matches(field[index], key)));
+}
+/** Own only selected JSON values; discarded token streams still receive full syntax validation. */
+class JsonProjection {
+    fields;
+    maxBytes;
+    stack = [];
+    root;
+    literal;
+    inKey = false;
+    keyText = "";
+    bytes = 0;
+    constructor(fields, maxBytes) {
+        this.fields = fields;
+        this.maxBytes = maxBytes;
+    }
+    result() {
+        return isRecord(this.root) ? this.root : undefined;
+    }
+    reserve(size) {
+        this.bytes += size;
+        if (this.bytes > this.maxBytes) {
+            throw new Error("Selected journal envelope exceeds its bounded read size.");
+        }
+    }
+    path() {
+        const frame = this.stack.at(-1);
+        return frame ? [...frame.path, frame.key ?? frame.index] : [];
+    }
+    excluded() {
+        const frame = this.stack.at(-1);
+        return frame !== undefined && frame.value === undefined;
+    }
+    frame() {
+        const frame = this.stack.at(-1);
+        if (!frame) {
+            throw new Error("Journal JSON container is missing.");
+        }
+        return frame;
+    }
+    put(value) {
+        const parent = this.stack.at(-1);
+        if (!parent) {
+            this.root = value;
+            return;
+        }
+        if (parent.value && value !== undefined) {
+            if (Array.isArray(parent.value)) {
+                parent.value[parent.index] = value;
+            }
+            else {
+                if (parent.key === undefined) {
+                    throw new Error("Journal object key is missing.");
+                }
+                Object.defineProperty(parent.value, parent.key, {
+                    value,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+        }
+        parent.key = undefined;
+        parent.index += 1;
+    }
+    consume(token) {
+        if (token.name === "startKey") {
+            this.inKey = true;
+            this.keyText = "";
+            return;
+        }
+        if (token.name === "endKey") {
+            this.inKey = false;
+            this.frame().key = this.keyText;
+            return;
+        }
+        if (this.inKey) {
+            this.consumeKey(token);
+            return;
+        }
+        switch (token.name) {
+            case "startObject":
+            case "startArray":
+                this.startContainer(token.name);
+                break;
+            case "endObject":
+            case "endArray": {
+                const frame = this.stack.pop();
+                if (!frame) {
+                    throw new Error("Journal JSON container is missing.");
+                }
+                this.put(frame.value);
+                break;
+            }
+            case "startString":
+            case "startNumber":
+                this.literal = {
+                    value: "",
+                    selected: !this.excluded() && selectedPath(this.path(), this.fields),
+                    number: token.name === "startNumber",
+                };
+                break;
+            case "stringChunk":
+            case "numberChunk":
+                this.consumeLiteral(token.value);
+                break;
+            case "endString":
+            case "endNumber":
+                this.endLiteral();
+                break;
+            case "trueValue":
+            case "falseValue":
+            case "nullValue":
+                this.consumeConstant(token.name);
+                break;
+            case "keyValue":
+            case "numberValue":
+            case "stringValue":
+            case "whitespace":
+                // The unpacked tokenizer emits chunk events; packed/whitespace tokens need no projection.
+                break;
+        }
+    }
+    consumeKey(token) {
+        if (token.name !== "stringChunk" || this.excluded()) {
+            return;
+        }
+        const path = this.frame().path;
+        const wholeContainer = this.fields.some((field) => field.every((key, index) => matches(key, path[index])));
+        if (wholeContainer || this.keyText.length <= 1024) {
+            if (wholeContainer) {
+                this.reserve(Buffer.byteLength(token.value));
+            }
+            this.keyText += token.value;
+        }
+    }
+    startContainer(name) {
+        if (this.stack.length >= 1024) {
+            throw new Error("Journal JSON nesting exceeds 1024 levels.");
+        }
+        // Excluded containers cannot contain a requested descendant; don't allocate their keys/paths.
+        const currentPath = this.excluded() ? [] : this.path();
+        const selected = !this.excluded() && selectedPath(currentPath, this.fields);
+        if (selected) {
+            this.reserve(32);
+        }
+        let value;
+        if (selected) {
+            value = name === "startObject" ? {} : [];
+        }
+        this.stack.push({ path: currentPath, index: 0, value });
+    }
+    consumeLiteral(value) {
+        if (this.literal?.selected === true) {
+            this.reserve(Buffer.byteLength(value));
+            this.literal.value += value;
+        }
+    }
+    endLiteral() {
+        const literal = this.literal;
+        let value;
+        if (literal?.selected === true) {
+            value = literal.number ? Number(literal.value) : literal.value;
+        }
+        this.put(value);
+        this.literal = undefined;
+    }
+    consumeConstant(name) {
+        const selected = !this.excluded() && selectedPath(this.path(), this.fields);
+        if (selected) {
+            this.reserve(8);
+        }
+        let value;
+        if (selected) {
+            value = name === "nullValue" ? null : name === "trueValue";
+        }
+        this.put(value);
+    }
+}
+/** Validate discarded values too; the parser never packs their strings or numbers. */
+export async function projectJson(
+// The native async iterator owns a mutable cursor; this reader consumes bytes without mutating them.
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types
+input, fields, maxBytes = ENVELOPE_MAX_BYTES) {
+    const { parser } = await import("stream-json/parser.js");
+    async function* decode() {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        for await (const chunk of input) {
+            yield decoder.decode(chunk, { stream: true });
+        }
+        const tail = decoder.decode();
+        if (tail.length > 0) {
+            yield tail;
+        }
+    }
+    const projection = new JsonProjection(fields, maxBytes);
+    const sink = new Writable({
+        objectMode: true,
+        write(token, _encoding, done) {
+            try {
+                projection.consume(token);
+                done();
+            }
+            catch (error) {
+                done(normalizeProcessError(error));
+            }
+        },
+    });
+    await pipeline(Readable.from(decode()), parser.asStream({ packValues: false, streamValues: true }), sink);
+    return projection.result();
+}

package/dist/extensions/agent-browser/lib/browser-journal-reader.js

@@ -0,0 +1,89 @@
+import { projectJson } from "./browser-journal-projection.js";
+export { projectJson } from "./browser-journal-projection.js";
+const CHUNK_BYTES = 64 * 1024;
+export async function* readRange(file, range) {
+    let position = range.offset;
+    const end = range.offset + range.length;
+    while (position < end) {
+        const buffer = Buffer.allocUnsafe(Math.min(CHUNK_BYTES, end - position));
+        // The next range read depends on the bytes actually returned by this read.
+        // oxlint-disable-next-line no-await-in-loop
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, position);
+        if (bytesRead === 0) {
+            throw new Error("Journal changed or truncated during read.");
+        }
+        position += bytesRead;
+        yield buffer.subarray(0, bytesRead);
+    }
+}
+/** Byte framing, not readline: even one discarded value can exceed V8's string limit. */
+class JournalLineFramer {
+    start;
+    nonblank = false;
+    constructor(offset) {
+        this.start = offset;
+    }
+    *accept(buffer, position) {
+        for (let index = 0; index < buffer.length; index++) {
+            const byte = buffer[index];
+            if (byte === 10) {
+                if (this.nonblank) {
+                    yield { offset: this.start, length: position + index + 1 - this.start };
+                }
+                this.start = position + index + 1;
+                this.nonblank = false;
+            }
+            else if (![9, 13, 32].includes(byte)) {
+                this.nonblank = true;
+            }
+        }
+    }
+    final(end, sealed) {
+        return this.nonblank && sealed ? { offset: this.start, length: end - this.start } : undefined;
+    }
+}
+export async function* journalRanges(file, end, sealed = false, offset = 0) {
+    let position = offset;
+    const framer = new JournalLineFramer(offset);
+    while (position < end) {
+        const buffer = Buffer.allocUnsafe(Math.min(CHUNK_BYTES, end - position));
+        // Byte offsets and line framing depend on the preceding read's actual length.
+        // oxlint-disable-next-line no-await-in-loop
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, position);
+        if (bytesRead === 0) {
+            throw new Error("Journal truncated during read.");
+        }
+        yield* framer.accept(buffer.subarray(0, bytesRead), position);
+        position += bytesRead;
+    }
+    const final = framer.final(end, sealed);
+    if (final) {
+        yield final;
+    }
+}
+const STRUCTURAL_FIELDS = [
+    ["type"],
+    ["id"],
+    ["parentId"],
+    ["timestamp"],
+    ["version"],
+    ["customType"],
+    ["data", "event", "version"],
+    ["data", "snapshot", "id"],
+    ["message", "toolName"],
+    ["message", "details", "browserEventVersion"],
+    ["message", "details", "sessionName"],
+    ["message", "details", "artifactManifest", "version"],
+    ["message", "details", "electron", "action"],
+];
+export async function scanJournalMetadata(file, end, sealed = false) {
+    const entries = [];
+    for await (const range of journalRanges(file, end, sealed)) {
+        const value = await projectJson(readRange(file, range), STRUCTURAL_FIELDS);
+        if (!value) {
+            throw new Error(`Expected a journal object at byte ${range.offset}.`);
+        }
+        entries.push({ ...range, value });
+    }
+    return entries;
+}

package/dist/extensions/agent-browser/lib/browser-journal-replay.js

@@ -0,0 +1,246 @@
+import { constants } from "node:fs";
+import { open, stat } from "node:fs/promises";
+import { BROWSER_TRANSITION_ENTRY, BROWSER_RESULT_TOOLS, applyArtifactChanges, getBrowserRecord, snapshotFromDefinition, } from "./browser-transcript.js";
+import { isRecord } from "./parsing.js";
+import { getErrorCode } from "./process-errors.js";
+import { projectJson, readRange, scanJournalMetadata, } from "./browser-journal-reader.js";
+const REPLAY_CUSTOM_TYPES = new Set([
+    BROWSER_TRANSITION_ENTRY,
+    "agent-browser-recording-reservation",
+    "agent-browser-script-session",
+]);
+function branchEntries(entries, selectedLeaf) {
+    const byId = new Map();
+    for (const entry of entries) {
+        const id = entry.value.id;
+        if (typeof id !== "string" || byId.has(id)) {
+            throw new Error("Journal has a missing or duplicate native entry identity.");
+        }
+        byId.set(id, entry);
+    }
+    const branch = [];
+    const seen = new Set();
+    let leaf = selectedLeaf;
+    while (leaf !== null) {
+        if (seen.has(leaf)) {
+            throw new Error("Journal ancestry contains a cycle.");
+        }
+        seen.add(leaf);
+        const entry = byId.get(leaf);
+        if (!entry) {
+            throw new Error(`Selected journal entry ${leaf} is not persisted; browser work requires a committed conversation.`);
+        }
+        const parent = entry.value.parentId;
+        if (parent !== null && typeof parent !== "string") {
+            throw new Error("Invalid journal parent identity.");
+        }
+        branch.push(entry);
+        leaf = parent;
+    }
+    return branch.reverse();
+}
+function canonicalVersion(entry) {
+    return isRecord(entry.data) && isRecord(entry.data.event) && entry.data.event.version === 1;
+}
+function legacyCustom(entry) {
+    return (entry.type === "custom" &&
+        (entry.customType === BROWSER_TRANSITION_ENTRY ||
+            entry.customType === "agent-browser-script-session") &&
+        !canonicalVersion(entry));
+}
+function browserMessage(entry) {
+    const message = isRecord(entry.message) ? entry.message : undefined;
+    return message &&
+        typeof message.toolName === "string" &&
+        BROWSER_RESULT_TOOLS.has(message.toolName)
+        ? message
+        : undefined;
+}
+function legacyBrowserResult(entry) {
+    const message = browserMessage(entry);
+    if (!message ||
+        !isRecord(message.details) ||
+        message.details.browserEventVersion === 1 ||
+        canonicalVersion(entry)) {
+        return false;
+    }
+    return (message.details.sessionName !== undefined ||
+        message.details.artifactManifest !== undefined ||
+        message.details.electron !== undefined);
+}
+function validateMemoryEntry(entry) {
+    if (!isRecord(entry)) {
+        return;
+    }
+    if (legacyCustom(entry) && !getBrowserRecord(entry)) {
+        throw new Error("Legacy browser records require stopped separate-copy conversion before replay.");
+    }
+    const message = browserMessage(entry);
+    if (entry.type === "message" &&
+        message &&
+        isRecord(message.details) &&
+        message.details.browserEventVersion !== 1 &&
+        !getBrowserRecord(entry)) {
+        throw new Error("Legacy browser observations require stopped separate-copy conversion before replay.");
+    }
+}
+function inMemoryEntries(manager, physical) {
+    const entries = physical ? manager.getEntries() : [];
+    if (!physical) {
+        const seen = new Set();
+        let leaf = manager.getLeafId();
+        while (leaf !== null) {
+            if (seen.has(leaf)) {
+                throw new Error("In-memory journal ancestry contains a cycle.");
+            }
+            seen.add(leaf);
+            const entry = manager.getEntry(leaf);
+            if (!isRecord(entry) || (entry.parentId !== null && typeof entry.parentId !== "string")) {
+                throw new Error("In-memory journal ancestry is incomplete.");
+            }
+            entries.push(entry);
+            leaf = entry.parentId;
+        }
+        entries.reverse();
+    }
+    for (const entry of entries) {
+        validateMemoryEntry(entry);
+    }
+    return entries;
+}
+class PublishedJournalReplay {
+    file;
+    projected = [];
+    definitions = new Map();
+    constructor(file) {
+        this.file = file;
+    }
+    async project(entries) {
+        for (const entry of entries) {
+            // Preserve journal order and bound selected envelope memory during replay.
+            // oxlint-disable-next-line no-await-in-loop
+            await this.projectEntry(entry);
+        }
+    }
+    async projectEntry(entry) {
+        const { value } = entry;
+        const definition = isRecord(value.data) && isRecord(value.data.snapshot) ? value.data.snapshot.id : undefined;
+        if (typeof definition === "string") {
+            if (this.definitions.has(definition)) {
+                throw new Error("Browser snapshot identity is defined more than once on this ancestry.");
+            }
+            this.definitions.set(definition, entry);
+        }
+        if (legacyCustom(value) || legacyBrowserResult(value)) {
+            throw new Error("This session contains legacy browser records. Convert a stopped separate copy with npm exec --package pi-agent-browser-native -- pi-agent-browser-convert before resuming browser work; the original journal is retained.");
+        }
+        if (!replayRelevant(value, definition)) {
+            return;
+        }
+        const fields = value.customType === BROWSER_TRANSITION_ENTRY || value.type === "message"
+            ? [
+                ["data", "event"],
+                ["data", "snapshot", "id"],
+            ]
+            : [["data"]];
+        const body = await projectJson(readRange(this.file, entry), fields);
+        this.projected.push({ ...value, ...body });
+    }
+    async resolveWinningDefinitions(physical) {
+        const { SessionPageState } = await import("./session-page-state.js");
+        const reduced = SessionPageState.fromBranch(this.projected);
+        const winners = new Set((physical ? [] : [...reduced.views().values()]).flatMap((page) => page.refSnapshot?.snapshotId !== undefined && page.refSnapshot.snapshotId.length > 0
+            ? [page.refSnapshot.snapshotId]
+            : []));
+        for (const id of winners) {
+            // Each winning snapshot is materialized once, without retaining unrelated historical ref maps.
+            // oxlint-disable-next-line no-await-in-loop
+            await this.resolveDefinition(id);
+        }
+        let manifest;
+        for (const entry of this.projected) {
+            manifest = applyArtifactChanges(manifest, getBrowserRecord(entry)?.event.artifacts);
+        }
+        return this.projected;
+    }
+    async resolveDefinition(id) {
+        const entry = this.definitions.get(id);
+        if (!entry) {
+            throw new Error(`Browser snapshot ${id} has no ancestral definition; inspect and take a fresh snapshot.`);
+        }
+        // ponytail: a requested individual snapshot must fit the consumer's memory; upgrade with native per-value paging if needed.
+        const body = await projectJson(readRange(this.file, entry), [["data", "snapshot"]], Infinity);
+        const destination = this.projected.find((candidate) => isRecord(candidate) && candidate.id === entry.value.id);
+        if (!isRecord(destination) || !isRecord(destination.data) || !isRecord(body?.data)) {
+            throw new Error("Winning browser snapshot could not be read.");
+        }
+        destination.data.snapshot = body.data.snapshot;
+        if (!isRecord(body.data.snapshot) || body.data.snapshot.id !== id) {
+            throw new Error("Winning browser snapshot identity is invalid.");
+        }
+        snapshotFromDefinition(body.data.snapshot);
+    }
+}
+function replayRelevant(value, definition) {
+    return ((value.type === "custom" &&
+        typeof value.customType === "string" &&
+        REPLAY_CUSTOM_TYPES.has(value.customType)) ||
+        (isRecord(value.data) && isRecord(value.data.event)) ||
+        definition !== undefined);
+}
+async function verifyCapturedFile(file, path, captured) {
+    const current = await file.stat();
+    const currentPath = await stat(path);
+    if (current.dev !== captured.dev ||
+        current.ino !== captured.ino ||
+        current.size < captured.size ||
+        currentPath.dev !== captured.dev ||
+        currentPath.ino !== captured.ino) {
+        throw new Error("Pi journal replaced or truncated during replay.");
+    }
+}
+function validateJournalHeader(metadata, sessionId) {
+    const header = metadata.find((entry) => entry.value.type === "session");
+    if (header?.value.id !== sessionId) {
+        throw new Error("Pi session journal identity does not match the active session.");
+    }
+}
+async function openPublishedJournal(path) {
+    try {
+        return await open(path, constants.O_RDONLY);
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export async function readBrowserEntries(manager, physical = false) {
+    const path = manager.getSessionFile();
+    if (path === undefined || path.length === 0) {
+        return inMemoryEntries(manager, physical);
+    }
+    const leaf = physical ? null : manager.getLeafId();
+    const file = await openPublishedJournal(path);
+    if (!file) {
+        return inMemoryEntries(manager, physical);
+    }
+    try {
+        const captured = await file.stat();
+        if (!captured.isFile()) {
+            throw new Error("Pi session journal is not a regular file.");
+        }
+        const metadata = await scanJournalMetadata(file, captured.size);
+        validateJournalHeader(metadata, manager.getHeader()?.id ?? manager.getSessionId());
+        const records = metadata.filter((entry) => entry.value.type !== "session");
+        const replay = new PublishedJournalReplay(file);
+        await replay.project(physical ? records : branchEntries(records, leaf));
+        const entries = await replay.resolveWinningDefinitions(physical);
+        await verifyCapturedFile(file, path, captured);
+        return entries;
+    }
+    finally {
+        await file.close();
+    }
+}