pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/results/presentation/artifact-files.js

@@ -0,0 +1,320 @@
+import { open, stat } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
+import { getExplicitArtifactDestination } from "../../orchestration/browser-run/artifact-paths.js";
+import { isRecord } from "../../parsing.js";
+import { isPendingRecordingCommand } from "../artifact-manifest.js";
+import { getRecordingReceipt } from "../recording.js";
+const PNG_HEADER = Buffer.from("89504e470d0a1a0a0000000d49484452", "hex");
+const ARTIFACT_MTIME_TOLERANCE_MS = 2_000;
+export function getImageMimeType(bytes) {
+    if (bytes.length < 16) {
+        return undefined;
+    }
+    if (bytes.subarray(0, 16).equals(PNG_HEADER)) {
+        return "image/png";
+    }
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff && bytes[3] !== 0xf7) {
+        return "image/jpeg";
+    }
+    if (["GIF87a", "GIF89a"].includes(bytes.toString("utf8", 0, 6))) {
+        return "image/gif";
+    }
+    if (bytes.toString("utf8", 0, 4) === "RIFF" && bytes.toString("utf8", 8, 12) === "WEBP") {
+        return "image/webp";
+    }
+    return undefined;
+}
+export async function readImageHeader(path, length) {
+    const file = await open(path, "r");
+    try {
+        const bytes = Buffer.alloc(length);
+        const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+        return bytes.subarray(0, bytesRead);
+    }
+    finally {
+        await file.close();
+    }
+}
+async function getFileImageMimeType(path) {
+    try {
+        return getImageMimeType(await readImageHeader(path, 16));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isMissingFileError(error) {
+    return (isRecord(error) && typeof error.code === "string" && ["ENOENT", "ENOTDIR"].includes(error.code));
+}
+async function readDiskEvidence(absolutePath) {
+    try {
+        const fileStats = await stat(absolutePath);
+        return {
+            exists: fileStats.isFile(),
+            sizeBytes: fileStats.size,
+            updatedAtMs: fileStats.mtimeMs,
+            mediaType: fileStats.isFile() ? await getFileImageMimeType(absolutePath) : undefined,
+        };
+    }
+    catch (error) {
+        return { exists: isMissingFileError(error) ? false : undefined };
+    }
+}
+export function isDownloadWaitSubcommand(subcommand) {
+    return subcommand === "--download" || subcommand === "-d";
+}
+function getArtifactKind(info) {
+    switch (info.command) {
+        case "screenshot":
+            return "image";
+        case "diff":
+            return info.subcommand === "screenshot" ? "image" : undefined;
+        case "pdf":
+            return "pdf";
+        case "download":
+            return "download";
+        case "wait":
+            return isDownloadWaitSubcommand(info.subcommand) ? "download" : undefined;
+        case "state":
+            return info.subcommand === "save" ? "file" : undefined;
+        case "trace":
+            return "trace";
+        case "profiler":
+            return "profile";
+        case "record":
+            return "video";
+        case "network":
+            return info.subcommand === "har" ? "har" : undefined;
+        case undefined:
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+export function isNonFileArtifactPathCandidate(path) {
+    return /^(?:data|blob|https?|javascript|mailto):/i.test(path.trim());
+}
+function validPath(value) {
+    return (typeof value === "string" && value.trim().length > 0 && !isNonFileArtifactPathCandidate(value));
+}
+const PATH_FIELDS = [
+    "path",
+    "file",
+    "filePath",
+    "outputPath",
+    "downloadPath",
+    "diffPath",
+    "harPath",
+    "savedPath",
+    "statePath",
+    "tracePath",
+    "profilePath",
+    "videoPath",
+];
+export function extractPathStrings(data) {
+    if (typeof data === "string") {
+        return data.trim().length > 0 && !isNonFileArtifactPathCandidate(data) ? [data] : [];
+    }
+    if (!isRecord(data)) {
+        return [];
+    }
+    return [
+        ...new Set(PATH_FIELDS.flatMap((key) => {
+            const value = data[key];
+            if (Array.isArray(value)) {
+                return value.filter(validPath);
+            }
+            return validPath(value) ? [value] : [];
+        })),
+    ];
+}
+function artifactMtimeIsOutsideCommandWindow(updatedAtMs, options, minUpdatedAtMs = options.artifactMinUpdatedAtMs) {
+    if (updatedAtMs === undefined || minUpdatedAtMs === undefined) {
+        return false;
+    }
+    return (updatedAtMs < minUpdatedAtMs - ARTIFACT_MTIME_TOLERANCE_MS ||
+        (options.artifactMaxUpdatedAtMs !== undefined &&
+            updatedAtMs > options.artifactMaxUpdatedAtMs + ARTIFACT_MTIME_TOLERANCE_MS));
+}
+function isPendingRecording(options, kind) {
+    return (options.recordingPending === true ||
+        (isPendingRecordingCommand(options.commandInfo.command, options.commandInfo.subcommand, kind) &&
+            options.recordingOutcome !== false &&
+            options.recording?.success !== false));
+}
+function getRecordingStartedAtMs(options) {
+    const startedAt = options.recording?.capture.startedAt;
+    const captureStartedAtMs = startedAt !== undefined && startedAt !== null && startedAt.length > 0
+        ? Date.parse(startedAt)
+        : NaN;
+    return Number.isFinite(captureStartedAtMs) ? captureStartedAtMs : options.artifactMinUpdatedAtMs;
+}
+function nativeRecordingFailed(options) {
+    const receipt = options.recording;
+    return (receipt?.success === false ||
+        receipt?.output.encoderSucceeded === false ||
+        (options.recordingOutcome === false && receipt?.success !== null));
+}
+function recordingSizeMismatch(options, sizeBytes) {
+    const recordedSize = options.recording?.file.sizeBytes;
+    return recordedSize !== undefined && recordedSize !== null && recordedSize !== sizeBytes;
+}
+function getRecordingStatus(options, sizeBytes) {
+    const receipt = options.recording;
+    if (nativeRecordingFailed(options)) {
+        return "failed";
+    }
+    if ((receipt?.success !== true && options.recordingOutcome !== true) ||
+        recordingSizeMismatch(options, sizeBytes)) {
+        return "unverified";
+    }
+    return options.artifactRequest?.status ?? "saved";
+}
+function getArtifactStatus(options, evidence, kind, state) {
+    if (state.pending) {
+        return "pending";
+    }
+    if (evidence.exists === false) {
+        return "missing";
+    }
+    if (evidence.exists !== true) {
+        return "unverified";
+    }
+    if (state.stale) {
+        return "stale";
+    }
+    return kind === "video"
+        ? getRecordingStatus(options, evidence.sizeBytes)
+        : (options.artifactRequest?.status ?? "saved");
+}
+function buildArtifactIdentity(options, kind) {
+    const { absolutePath = resolve(options.cwd, options.path), path: requestedPath, tempPath, } = options.artifactRequest ?? {};
+    const extension = extname(absolutePath.length > 0 ? absolutePath : options.path).toLowerCase();
+    return {
+        absolutePath,
+        artifactType: kind,
+        command: options.commandInfo.command,
+        cwd: options.cwd,
+        extension: extension.length > 0 ? extension : undefined,
+        kind,
+        namespace: options.namespace,
+        path: requestedPath ?? options.path,
+        requestedPath: requestedPath ??
+            getExplicitArtifactDestination([...(options.commandInfo.commandTokens ?? [])]),
+        session: options.sessionName,
+        subcommand: options.commandInfo.subcommand,
+        tempPath,
+    };
+}
+function artifactIsStale(options, evidence, kind, recordingStartedAtMs) {
+    if (options.commandInfo.command === "wait" &&
+        isDownloadWaitSubcommand(options.commandInfo.subcommand)) {
+        return false;
+    }
+    return artifactMtimeIsOutsideCommandWindow(evidence.updatedAtMs, options, kind === "video" ? recordingStartedAtMs : options.artifactMinUpdatedAtMs);
+}
+export async function buildFileArtifactMetadata(options) {
+    const kind = options.kind ?? getArtifactKind(options.commandInfo);
+    if (kind === undefined) {
+        return undefined;
+    }
+    const identity = buildArtifactIdentity(options, kind);
+    const pending = isPendingRecording(options, kind);
+    const recordingStartedAtMs = getRecordingStartedAtMs(options);
+    const evidence = !pending || options.commandInfo.subcommand === "stop"
+        ? await readDiskEvidence(identity.absolutePath)
+        : {};
+    const stale = artifactIsStale(options, evidence, kind, recordingStartedAtMs);
+    return {
+        ...identity,
+        exists: evidence.exists,
+        sizeBytes: evidence.sizeBytes,
+        mediaType: evidence.mediaType,
+        updatedAtMs: evidence.updatedAtMs,
+        recording: options.recording,
+        recordingStartedAtMs: kind === "video" ? recordingStartedAtMs : undefined,
+        recordingState: pending ? "openRecording" : undefined,
+        status: getArtifactStatus(options, evidence, kind, { pending, stale }),
+        willExistOnStop: pending ? true : undefined,
+    };
+}
+function findPreviousRecording(options) {
+    const sessionKey = options.sessionName !== undefined && options.sessionName.length > 0
+        ? getAgentBrowserSessionIdentityKey(options.sessionName, options.namespace)
+        : undefined;
+    return options.artifactManifest?.entries.find((entry) => {
+        if (entry.command !== "record" ||
+            !["start", "restart"].includes(entry.subcommand ?? "") ||
+            entry.kind !== "video") {
+            return false;
+        }
+        if (sessionKey === undefined || sessionKey.length === 0) {
+            return true;
+        }
+        return (entry.session !== undefined &&
+            entry.session.length > 0 &&
+            getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) === sessionKey);
+    });
+}
+function buildPreviousIdentity(previous, options) {
+    const absolutePath = previous.absolutePath ?? resolve(options.cwd, previous.path);
+    const extension = extname(absolutePath).toLowerCase();
+    return {
+        absolutePath,
+        artifactType: "video",
+        command: "record",
+        cwd: previous.cwd ?? options.cwd,
+        extension: previous.extension ?? (extension.length > 0 ? extension : undefined),
+        kind: "video",
+        namespace: previous.namespace ?? options.namespace,
+        path: previous.path,
+        requestedPath: previous.requestedPath,
+        session: previous.session ?? options.sessionName,
+        subcommand: "restart-previous",
+    };
+}
+async function buildPreviousDiskRecording(options) {
+    const previous = findPreviousRecording(options);
+    if (!previous) {
+        return undefined;
+    }
+    const identity = buildPreviousIdentity(previous, options);
+    const evidence = await readDiskEvidence(identity.absolutePath);
+    const stale = artifactMtimeIsOutsideCommandWindow(evidence.updatedAtMs, options);
+    let status = "unverified";
+    if (stale) {
+        status = "stale";
+    }
+    if (evidence.exists === false && evidence.updatedAtMs === undefined) {
+        status = "missing";
+    }
+    // Restart's path and disk evidence alone never prove native finalization.
+    return {
+        ...identity,
+        ...evidence,
+        exists: evidence.updatedAtMs !== undefined ? true : evidence.exists,
+        status,
+    };
+}
+export async function buildPreviousRestartRecordingArtifact(options) {
+    if (options.commandInfo.command !== "record" || options.commandInfo.subcommand !== "restart") {
+        return undefined;
+    }
+    if (isRecord(options.data) && "previousRecording" in options.data) {
+        const recording = getRecordingReceipt(options.data.previousRecording);
+        return recording
+            ? buildFileArtifactMetadata({
+                ...options,
+                commandInfo: { command: "record", subcommand: "restart-previous" },
+                path: recording.path,
+                recording,
+            })
+            : undefined;
+    }
+    // A rejected or pending restart has not acknowledged replacement of the active take.
+    if (!isRecord(options.data) || options.data.restarted !== true) {
+        return undefined;
+    }
+    return buildPreviousDiskRecording(options);
+}

package/dist/extensions/agent-browser/lib/results/presentation/artifact-format.js

@@ -0,0 +1,138 @@
+import { isPendingRecordingArtifact } from "../artifact-manifest.js";
+import { formatRecordingReceipt } from "../recording.js";
+import { isDownloadWaitSubcommand } from "./artifact-files.js";
+export function formatByteCount(bytes) {
+    if (bytes < 1_024) {
+        return `${bytes} B`;
+    }
+    if (bytes < 1_024 * 1_024) {
+        return `${(bytes / 1_024).toFixed(1)} KiB`;
+    }
+    return `${(bytes / (1_024 * 1_024)).toFixed(1)} MiB`;
+}
+function formatPreviousRecordingLabel(artifact) {
+    if (artifact.status === "stale") {
+        return "Previous recording stale";
+    }
+    return artifact.exists === false ? "Previous recording missing" : "Previous recording saved";
+}
+function formatRecordingLabel(artifact) {
+    const previous = artifact.subcommand === "restart-previous";
+    if (artifact.status === "failed") {
+        return previous ? "Previous recording failed" : "Recording failed";
+    }
+    if (artifact.status === "unverified") {
+        return previous ? "Previous recording unverified" : "Recording unverified";
+    }
+    if (artifact.command === "record" && previous) {
+        return formatPreviousRecordingLabel(artifact);
+    }
+    if (!isPendingRecordingArtifact(artifact)) {
+        return artifact.status === "saved"
+            ? "Saved recording"
+            : "Recording reported; file not verified";
+    }
+    return formatPendingRecordingLabel(artifact.subcommand);
+}
+function formatPendingRecordingLabel(subcommand) {
+    if (subcommand === "stop") {
+        return "Recording finalization pending";
+    }
+    return subcommand === "restart"
+        ? "Recording restarted; output will be written on stop"
+        : "Recording started; output will be written on stop";
+}
+function formatDownloadLabel(artifact) {
+    const wait = artifact.command === "wait" && isDownloadWaitSubcommand(artifact.subcommand);
+    if (artifact.exists !== true) {
+        return wait
+            ? "Download event reported; file not verified"
+            : "Download reported; file not verified";
+    }
+    return wait ? "Download saved and verified" : "Downloaded file verified";
+}
+function formatImageLabel(artifact) {
+    const diff = artifact.command === "diff" && artifact.subcommand === "screenshot";
+    if (artifact.exists !== true) {
+        return diff ? "Diff image reported; file not verified" : "Image reported; file not verified";
+    }
+    return diff ? "Saved diff image" : "Saved image";
+}
+function formatArtifactLabel(artifact) {
+    switch (artifact.kind) {
+        case "download":
+            return formatDownloadLabel(artifact);
+        case "file":
+            return artifact.command === "state" ? "State file" : "Saved file";
+        case "har":
+            return "Saved HAR";
+        case "image":
+            return formatImageLabel(artifact);
+        case "pdf":
+            return "Saved PDF";
+        case "profile":
+            return "Saved profile";
+        case "trace":
+            return "Saved trace";
+        case "video":
+            return formatRecordingLabel(artifact);
+    }
+}
+export function formatArtifactSummary(artifacts) {
+    if (artifacts.length === 0) {
+        return undefined;
+    }
+    if (artifacts.length === 1) {
+        const artifact = artifacts[0];
+        return `${formatArtifactLabel(artifact)}: ${artifact.path}`;
+    }
+    const restartArtifact = artifacts.find((artifact) => isPendingRecordingArtifact(artifact) && artifact.subcommand === "restart");
+    const previous = artifacts.filter((artifact) => artifact.command === "record" && artifact.subcommand === "restart-previous");
+    if (restartArtifact && previous.length > 0) {
+        return [...previous, restartArtifact]
+            .map((artifact) => `${formatArtifactLabel(artifact)}: ${artifact.path}`)
+            .join("\n");
+    }
+    return `${artifacts.every((artifact) => artifact.status === "saved") ? "Saved" : "Reported"} ${artifacts.length} artifacts: ${artifacts.map((artifact) => `${artifact.kind} ${artifact.path}`).join(", ")}`;
+}
+function optionalField(label, value) {
+    return value !== undefined && value.length > 0 ? `${label}: ${value}` : undefined;
+}
+function formatPendingDetails(artifact) {
+    return [
+        `Exists: ${artifact.exists ?? "pending until record stop"}`,
+        `Status: ${artifact.status ?? "pending"}`,
+        `Recording state: ${artifact.recordingState ?? "openRecording"}`,
+        `Will exist on stop: ${artifact.willExistOnStop !== false}`,
+    ];
+}
+function formatFileDetails(artifact) {
+    return [
+        `Exists: ${artifact.exists ?? "unknown"}`,
+        artifact.exists === false ? "not found on disk" : undefined,
+        typeof artifact.sizeBytes === "number"
+            ? `Size: ${formatByteCount(artifact.sizeBytes)}`
+            : undefined,
+        typeof artifact.sizeBytes === "number" ? `Size bytes: ${artifact.sizeBytes}` : undefined,
+        `Status: ${artifact.status ?? (artifact.exists === false ? "missing" : "saved")}`,
+        optionalField("Reported path", artifact.tempPath),
+        optionalField("Media type", artifact.mediaType),
+    ];
+}
+export function formatArtifactMetadataLines(artifacts) {
+    return artifacts.map((artifact, index) => [
+        `${formatArtifactLabel(artifact)}: ${artifact.path}`,
+        `Artifact type: ${artifact.kind}`,
+        optionalField("Requested path", artifact.requestedPath),
+        `Absolute path: ${artifact.absolutePath}`,
+        ...(isPendingRecordingArtifact(artifact)
+            ? formatPendingDetails(artifact)
+            : formatFileDetails(artifact)),
+        optionalField("Session", artifact.session),
+        optionalField("CWD", artifact.cwd),
+        artifact.recording ? formatRecordingReceipt(artifact.recording) : undefined,
+        `Machine data: details.artifacts[${index}]`,
+    ]
+        .filter((item) => item !== undefined)
+        .join("\n"));
+}

package/dist/extensions/agent-browser/lib/results/presentation/artifact-images.js

@@ -0,0 +1,113 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { inspect } from "node:util";
+import { getImageDimensions } from "@earendil-works/pi-tui";
+import { isRecord, parsePositiveInteger } from "../../parsing.js";
+import { LIGHTPANDA_IMAGE_REASON } from "./common.js";
+import { getImageMimeType, isNonFileArtifactPathCandidate, readImageHeader, } from "./artifact-files.js";
+import { formatByteCount } from "./artifact-format.js";
+const DEFAULT_INLINE_IMAGE_MAX_BYTES = 5 * 1_024 * 1_024;
+function getInlineImageMaxBytes(env = process.env) {
+    return (parsePositiveInteger(env.PI_AGENT_BROWSER_INLINE_IMAGE_MAX_BYTES) ??
+        DEFAULT_INLINE_IMAGE_MAX_BYTES);
+}
+export function appendPresentationNotice(presentation, message) {
+    const existingText = presentation.content[0]?.type === "text" ? presentation.content[0].text : "";
+    presentation.content[0] = {
+        type: "text",
+        text: existingText.length > 0 ? `${existingText}\n\n${message}` : message,
+    };
+}
+export function getScreenshotSummary(data) {
+    if (data.changed === false) {
+        return "Screenshot unchanged; no image saved.";
+    }
+    return typeof data.path === "string" ? `Saved image: ${data.path}` : undefined;
+}
+export function extractImagePath(commandInfo, cwd, data) {
+    if (commandInfo.command !== "screenshot") {
+        return undefined;
+    }
+    let path;
+    if (typeof data === "string") {
+        path = data;
+    }
+    else if (isRecord(data) && typeof data.path === "string") {
+        path = data.path;
+    }
+    return path !== undefined && path.trim().length > 0 && !isNonFileArtifactPathCandidate(path)
+        ? resolve(cwd, path)
+        : undefined;
+}
+function isTextRendered(data) {
+    if (!isRecord(data) || !isRecord(data.lifecycle)) {
+        return false;
+    }
+    return (isRecord(data.lifecycle.effectiveLaunch) &&
+        data.lifecycle.effectiveLaunch.engine === "lightpanda");
+}
+function buildImageObservation(imagePath, header, mimeType, textRendered) {
+    const dimensions = getImageDimensions(header.toString("base64"), mimeType);
+    let reason = "Image dimensions could not be read from the bounded header.";
+    if (dimensions) {
+        reason = "Capture geometry was not observed.";
+    }
+    if (textRendered) {
+        reason = LIGHTPANDA_IMAGE_REASON;
+    }
+    return {
+        path: imagePath,
+        mimeType,
+        ...(textRendered ? { rendering: "text" } : {}),
+        pixels: dimensions ? { width: dimensions.widthPx, height: dimensions.heightPx } : undefined,
+        capture: "unknown",
+        geometry: { status: "unknown", reason },
+    };
+}
+async function attachVisibleImage(presentation, options) {
+    if (options.textRendered) {
+        appendPresentationNotice(presentation, LIGHTPANDA_IMAGE_REASON);
+    }
+    const limit = getInlineImageMaxBytes();
+    if (options.size > limit) {
+        appendPresentationNotice(presentation, `Image attachment skipped: ${formatByteCount(options.size)} exceeds the inline limit of ${formatByteCount(limit)}.`);
+        return;
+    }
+    const file = await readFile(options.imagePath);
+    presentation.content.push({
+        type: "image",
+        data: file.toString("base64"),
+        mimeType: options.mimeType,
+    });
+}
+export async function attachInlineImage(presentation, imagePath, modelVisible = true) {
+    try {
+        const fileStats = await stat(imagePath);
+        // Pi's dimension API accepts base64. Encode only a bounded header, never the whole code-mode image.
+        const header = await readImageHeader(imagePath, 64 * 1024);
+        const mimeType = getImageMimeType(header);
+        if (mimeType === undefined) {
+            return presentation;
+        }
+        const textRendered = isTextRendered(presentation.data);
+        presentation.imagePath = imagePath;
+        presentation.imageObservations = [
+            buildImageObservation(imagePath, header, mimeType, textRendered),
+        ];
+        if (modelVisible) {
+            await attachVisibleImage(presentation, {
+                imagePath,
+                size: fileStats.size,
+                mimeType,
+                textRendered,
+            });
+        }
+        return presentation;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : inspect(error);
+        appendPresentationNotice(presentation, `Image attachment failed: ${message}`);
+        presentation.imagePath = imagePath;
+        return presentation;
+    }
+}