pi-agent-browser-native 0.9.2 → 0.9.4

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

@@ -1,285 +1,110 @@
-import { open, readFile, stat } from "node:fs/promises";
-import { extname, resolve } from "node:path";
-import { getImageDimensions } from "@earendil-works/pi-tui";
-import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
-import { getExplicitArtifactDestination } from "../../orchestration/browser-run/artifact-paths.js";
-import { isRecord, parsePositiveInteger } from "../../parsing.js";
-import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingArtifact, isPendingRecordingCommand, mergeSessionArtifactManifest, } from "../artifact-manifest.js";
-import { classifyAgentBrowserSuccessCategory } from "../categories.js";
-import { LIGHTPANDA_IMAGE_REASON } from "./common.js";
-import { formatRecordingReceipt, getRecordingReceipt } from "../recording.js";
-const PNG_HEADER = Buffer.from("89504e470d0a1a0a0000000d49484452", "hex");
-const INLINE_IMAGE_MAX_BYTES_ENV = "PI_AGENT_BROWSER_INLINE_IMAGE_MAX_BYTES";
-const DEFAULT_INLINE_IMAGE_MAX_BYTES = 5 * 1_024 * 1_024;
-const ARTIFACT_MTIME_TOLERANCE_MS = 2_000;
-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;
-}
-async function getFileImageMimeType(path) {
-    try {
-        const file = await open(path, "r");
-        try {
-            const bytes = Buffer.alloc(16);
-            const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
-            return getImageMimeType(bytes.subarray(0, bytesRead));
-        }
-        finally {
-            await file.close();
-        }
-    }
-    catch {
-        return undefined;
-    }
-}
-function getInlineImageMaxBytes(env = process.env) {
-    return parsePositiveInteger(env[INLINE_IMAGE_MAX_BYTES_ENV]) ?? DEFAULT_INLINE_IMAGE_MAX_BYTES;
-}
-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 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,
-    };
-}
-function shouldAppendArtifactRetentionNotice(entries) {
-    return entries.some((entry) => entry.retentionState === "evicted" || entry.storageScope !== "explicit-path");
+import { isRecord } from "../../parsing.js";
+import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingArtifact, mergeSessionArtifactManifest, } from "../artifact-manifest.js";
+import { getRecordingReceipt } from "../recording.js";
+import { buildFileArtifactMetadata, buildPreviousRestartRecordingArtifact, extractPathStrings, isDownloadWaitSubcommand, isNonFileArtifactPathCandidate, } from "./artifact-files.js";
+import { appendPresentationNotice } from "./artifact-images.js";
+export { attachInlineImage, extractImagePath, getScreenshotSummary } from "./artifact-images.js";
+export { formatArtifactMetadataLines, formatArtifactSummary } from "./artifact-format.js";
+export { buildArtifactVerificationSummary, classifyPresentationSuccessCategory, formatMissingArtifactFailureText, hasMissingFileArtifact, } from "./artifact-verification.js";
+function noticeWorthy(entry) {
+    return entry.retentionState === "evicted" || entry.storageScope !== "explicit-path";
 }
 export function manifestHasNewNoticeWorthyEntries(base, current) {
-    if (!current)
+    if (!current) {
         return false;
+    }
     const baseKeys = new Set((base?.entries ?? []).map(getSessionArtifactManifestEntryKey));
-    return current.entries.some((entry) => !baseKeys.has(getSessionArtifactManifestEntryKey(entry)) && (entry.retentionState === "evicted" || entry.storageScope !== "explicit-path"));
+    return current.entries.some((entry) => !baseKeys.has(getSessionArtifactManifestEntryKey(entry)) && noticeWorthy(entry));
 }
 export function applyArtifactManifest(presentation, baseManifest, entries) {
-    if (entries.length === 0)
+    if (entries.length === 0) {
         return presentation;
-    const artifactManifest = mergeSessionArtifactManifest({ base: baseManifest, entries });
-    if (!artifactManifest)
+    }
+    const artifactManifest = mergeSessionArtifactManifest({
+        base: baseManifest,
+        entries: [...entries],
+    });
+    if (!artifactManifest) {
         return presentation;
+    }
     presentation.artifactManifest = artifactManifest;
     presentation.artifactRetentionSummary = formatSessionArtifactRetentionSummary(artifactManifest);
-    if (shouldAppendArtifactRetentionNotice(entries)) {
+    if (entries.some(noticeWorthy)) {
         appendPresentationNotice(presentation, presentation.artifactRetentionSummary);
     }
     return presentation;
 }
-export function getScreenshotSummary(data) {
-    if (data.changed === false)
-        return "Screenshot unchanged; no image saved.";
-    return typeof data.path === "string" ? `Saved image: ${data.path}` : undefined;
-}
-const PATH_FIELD_CANDIDATES = [
-    "path",
-    "file",
-    "filePath",
-    "outputPath",
-    "downloadPath",
-    "diffPath",
-    "harPath",
-    "savedPath",
-    "statePath",
-    "tracePath",
-    "profilePath",
-    "videoPath",
-];
-function isDownloadWaitSubcommand(subcommand) {
-    return subcommand === "--download" || subcommand === "-d";
-}
-function getArtifactKind(commandInfo) {
-    if (commandInfo.command === "screenshot")
-        return "image";
-    if (commandInfo.command === "diff" && commandInfo.subcommand === "screenshot")
-        return "image";
-    if (commandInfo.command === "pdf")
-        return "pdf";
-    if (commandInfo.command === "download")
-        return "download";
-    if (commandInfo.command === "wait" && isDownloadWaitSubcommand(commandInfo.subcommand))
-        return "download";
-    if (commandInfo.command === "state" && commandInfo.subcommand === "save")
-        return "file";
-    if (commandInfo.command === "trace")
-        return "trace";
-    if (commandInfo.command === "profiler")
-        return "profile";
-    if (commandInfo.command === "record")
-        return "video";
-    if (commandInfo.command === "network" && commandInfo.subcommand === "har")
-        return "har";
-    return undefined;
-}
-function isNonFileArtifactPathCandidate(path) {
-    return /^(?:data|blob|https?|javascript|mailto):/i.test(path.trim());
-}
-function extractPathStrings(data) {
-    if (typeof data === "string") {
-        return data.trim().length > 0 && !isNonFileArtifactPathCandidate(data) ? [data] : [];
-    }
-    if (!isRecord(data)) {
-        return [];
-    }
-    const paths = [];
-    for (const key of PATH_FIELD_CANDIDATES) {
-        const value = data[key];
-        if (typeof value === "string" && value.trim().length > 0 && !isNonFileArtifactPathCandidate(value)) {
-            paths.push(value);
-        }
-        if (Array.isArray(value)) {
-            for (const item of value) {
-                if (typeof item === "string" && item.trim().length > 0 && !isNonFileArtifactPathCandidate(item)) {
-                    paths.push(item);
-                }
-            }
-        }
-    }
-    return [...new Set(paths)];
-}
-function artifactMtimeIsOutsideCommandWindow(updatedAtMs, minUpdatedAtMs, maxUpdatedAtMs) {
-    return minUpdatedAtMs !== undefined
-        && (updatedAtMs < minUpdatedAtMs - ARTIFACT_MTIME_TOLERANCE_MS
-            || (maxUpdatedAtMs !== undefined && updatedAtMs > maxUpdatedAtMs + ARTIFACT_MTIME_TOLERANCE_MS));
+function getRecordingPending(options, recording) {
+    return (options.recordingPending ??
+        (recording?.success === null &&
+            isRecord(options.data) &&
+            isRecord(options.data.capture) &&
+            recording.capture.endedAt === null));
 }
-async function buildFileArtifactMetadata(options) {
-    const kind = options.kind ?? getArtifactKind(options.commandInfo);
-    if (!kind) {
+async function extractContactSheet(options, recordingPending) {
+    if (options.commandInfo.command !== "record" || !isRecord(options.data)) {
         return undefined;
     }
-    const absolutePath = options.artifactRequest?.absolutePath ?? resolve(options.cwd, options.path);
-    const displayPath = options.artifactRequest?.path ?? options.path;
-    const extension = extname(absolutePath || options.path).toLowerCase() || undefined;
-    const pendingRecording = options.recordingPending === true || (isPendingRecordingCommand(options.commandInfo.command, options.commandInfo.subcommand, kind) && options.recordingOutcome !== false && options.recording?.success !== false);
-    const captureStartedAtMs = options.recording?.capture.startedAt ? Date.parse(options.recording.capture.startedAt) : NaN;
-    const recordingStartedAtMs = Number.isFinite(captureStartedAtMs) ? captureStartedAtMs : options.artifactMinUpdatedAtMs;
-    let exists;
-    let sizeBytes;
-    let mediaType;
-    let stale = false;
-    let updatedAtMs;
-    if (!pendingRecording || options.commandInfo.subcommand === "stop") {
-        try {
-            const fileStats = await stat(absolutePath);
-            exists = fileStats.isFile();
-            sizeBytes = fileStats.size;
-            updatedAtMs = fileStats.mtimeMs;
-            mediaType = fileStats.isFile() ? await getFileImageMimeType(absolutePath) : undefined;
-            const commandCreatesArtifact = !(options.commandInfo.command === "wait" && isDownloadWaitSubcommand(options.commandInfo.subcommand));
-            stale = commandCreatesArtifact && artifactMtimeIsOutsideCommandWindow(updatedAtMs, kind === "video" ? recordingStartedAtMs : options.artifactMinUpdatedAtMs, options.artifactMaxUpdatedAtMs);
-        }
-        catch (error) {
-            exists = ["ENOENT", "ENOTDIR"].includes(error.code ?? "") ? false : undefined;
-        }
+    const path = options.data.contactSheetPath;
+    if (typeof path !== "string" ||
+        path.trim().length === 0 ||
+        isNonFileArtifactPathCandidate(path)) {
+        return undefined;
     }
-    return {
-        absolutePath,
-        artifactType: kind,
-        command: options.commandInfo.command,
-        cwd: options.cwd,
-        exists,
-        extension,
-        kind,
-        mediaType,
-        namespace: options.namespace,
-        path: displayPath,
-        recording: options.recording,
-        recordingStartedAtMs: kind === "video" ? recordingStartedAtMs : undefined,
-        recordingState: pendingRecording ? "openRecording" : undefined,
-        requestedPath: options.artifactRequest?.path ?? getExplicitArtifactDestination(options.commandInfo.commandTokens ?? []),
-        session: options.sessionName,
-        sizeBytes,
-        status: pendingRecording ? "pending" : exists !== true ? exists === false ? "missing" : "unverified" : stale ? "stale"
-            : kind === "video" && (options.recording?.success === false || options.recording?.output.encoderSucceeded === false || (options.recordingOutcome === false && options.recording?.success !== null)) ? "failed"
-                : kind === "video" && ((options.recording?.success !== true && options.recordingOutcome !== true)
-                    || (options.recording?.file.sizeBytes != null && options.recording.file.sizeBytes !== sizeBytes)) ? "unverified"
-                    : options.artifactRequest?.status ?? "saved",
-        subcommand: options.commandInfo.subcommand,
-        tempPath: options.artifactRequest?.tempPath,
-        updatedAtMs,
-        willExistOnStop: pendingRecording ? true : undefined,
-    };
+    const sheet = await buildFileArtifactMetadata({
+        ...options,
+        artifactRequest: undefined,
+        kind: "image",
+        path,
+        recordingPending: recordingPending === true ||
+            ["start", "restart"].includes(options.commandInfo.subcommand ?? ""),
+    });
+    return sheet ? { ...sheet, requestedPath: undefined } : undefined;
 }
-async function buildPreviousRestartRecordingArtifact(options) {
-    if (options.commandInfo.command !== "record" || options.commandInfo.subcommand !== "restart")
+async function extractPreviousContactSheet(options) {
+    if (options.commandInfo.command !== "record" ||
+        options.commandInfo.subcommand !== "restart" ||
+        options.recordingOutcome !== true) {
         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;
     }
-    const sessionKey = options.sessionName ? getAgentBrowserSessionIdentityKey(options.sessionName, options.namespace) : undefined;
-    const previousRecording = options.artifactManifest?.entries.find((entry) => (entry.command === "record" &&
-        (entry.subcommand === "start" || entry.subcommand === "restart") &&
-        entry.kind === "video" &&
-        (!sessionKey || (entry.session && getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) === sessionKey))));
-    if (!previousRecording)
+    const path = options.previousRecordingContactSheetPath;
+    if (path === undefined || path.length === 0) {
         return undefined;
-    const absolutePath = previousRecording.absolutePath ?? resolve(options.cwd, previousRecording.path);
-    const base = {
-        absolutePath,
-        artifactType: "video",
-        command: "record",
-        cwd: previousRecording.cwd ?? options.cwd,
-        extension: previousRecording.extension ?? (extname(absolutePath).toLowerCase() || undefined),
-        kind: "video",
-        namespace: previousRecording.namespace ?? options.namespace,
-        path: previousRecording.path,
-        requestedPath: previousRecording.requestedPath,
-        session: previousRecording.session ?? options.sessionName,
-        subcommand: "restart-previous",
-    };
-    try {
-        const fileStats = await stat(absolutePath);
-        const stale = artifactMtimeIsOutsideCommandWindow(fileStats.mtimeMs, options.artifactMinUpdatedAtMs, options.artifactMaxUpdatedAtMs);
-        return {
-            ...base,
-            exists: true,
-            mediaType: fileStats.isFile() ? await getFileImageMimeType(absolutePath) : undefined,
-            sizeBytes: fileStats.size,
-            status: stale ? "stale" : "unverified",
-            updatedAtMs: fileStats.mtimeMs,
-        };
-    }
-    catch (error) {
-        const missing = ["ENOENT", "ENOTDIR"].includes(error.code ?? "");
-        return { ...base, exists: missing ? false : undefined, status: missing ? "missing" : "unverified" };
     }
+    const sheet = await buildFileArtifactMetadata({
+        ...options,
+        artifactRequest: undefined,
+        commandInfo: { command: "record", subcommand: "restart-previous" },
+        kind: "image",
+        path,
+        recordingPending: false,
+    });
+    // Native restart omits the previous sheet's terminal receipt. Disk presence isn't finalization proof.
+    return sheet
+        ? { ...sheet, status: sheet.status === "saved" ? "unverified" : sheet.status }
+        : undefined;
 }
 export async function extractFileArtifacts(options) {
-    if (options.commandInfo.command === "screenshot" && isRecord(options.data) && options.data.changed === false)
+    if (options.commandInfo.command === "screenshot" &&
+        isRecord(options.data) &&
+        options.data.changed === false) {
         return [];
-    const candidates = extractPathStrings(options.data);
-    const recording = options.commandInfo.command === "record" ? getRecordingReceipt(options.data, options.commandInfo.subcommand === "stop" ? options.recordingOutcome : undefined) : undefined;
-    const recordingPending = options.recordingPending ?? (recording?.success === null && isRecord(options.data) && isRecord(options.data.capture) && recording.capture.endedAt === null);
-    const currentArtifacts = (await Promise.all(candidates.map((path) => buildFileArtifactMetadata({ ...options, path, recording, recordingPending })))).filter((artifact) => artifact !== undefined);
-    if (options.commandInfo.command === "record" && isRecord(options.data) && typeof options.data.contactSheetPath === "string" && options.data.contactSheetPath.trim() && !isNonFileArtifactPathCandidate(options.data.contactSheetPath)) {
-        const sheet = await buildFileArtifactMetadata({ ...options, artifactRequest: undefined, kind: "image", path: options.data.contactSheetPath, recordingPending: recordingPending || ["start", "restart"].includes(options.commandInfo.subcommand ?? "") });
-        if (sheet)
-            currentArtifacts.push({ ...sheet, requestedPath: undefined });
     }
-    if (options.commandInfo.command === "record" && options.commandInfo.subcommand === "restart" && options.recordingOutcome === true && options.previousRecordingContactSheetPath) {
-        const previousSheet = await buildFileArtifactMetadata({ ...options, artifactRequest: undefined, commandInfo: { command: "record", subcommand: "restart-previous" }, kind: "image", path: options.previousRecordingContactSheetPath, recordingPending: false });
-        // Native restart omits the previous sheet's terminal receipt. Retain the
-        // known destination and disk evidence without inventing finalization proof.
-        if (previousSheet)
-            currentArtifacts.unshift({ ...previousSheet, status: previousSheet.status === "saved" ? "unverified" : previousSheet.status });
+    const recording = options.commandInfo.command === "record"
+        ? getRecordingReceipt(options.data, options.commandInfo.subcommand === "stop" ? options.recordingOutcome : undefined)
+        : undefined;
+    const recordingPending = getRecordingPending(options, recording);
+    const current = (await Promise.all(extractPathStrings(options.data).map((path) => buildFileArtifactMetadata({ ...options, path, recording, recordingPending })))).filter((artifact) => artifact !== undefined);
+    const sheet = await extractContactSheet(options, recordingPending);
+    if (sheet) {
+        current.push(sheet);
     }
-    const previousRestartRecordingArtifact = await buildPreviousRestartRecordingArtifact(options);
-    return previousRestartRecordingArtifact ? [previousRestartRecordingArtifact, ...currentArtifacts] : currentArtifacts;
+    const previousSheet = await extractPreviousContactSheet(options);
+    if (previousSheet) {
+        current.unshift(previousSheet);
+    }
+    const previous = await buildPreviousRestartRecordingArtifact(options);
+    return previous ? [previous, ...current] : current;
 }
 export function buildManifestEntriesForFileArtifacts(artifacts, nowMs = Date.now()) {
     return artifacts.map((artifact) => ({
@@ -306,313 +131,35 @@ export function buildManifestEntriesForFileArtifacts(artifacts, nowMs = Date.now
     }));
 }
 export function isManifestFileArtifact(artifact) {
-    return artifact.kind === "video" && artifact.command === "record" ? true : artifact.status !== "stale" && !isPendingRecordingArtifact(artifact);
+    return artifact.kind === "video" && artifact.command === "record"
+        ? true
+        : artifact.status !== "stale" && !isPendingRecordingArtifact(artifact);
 }
-function getArtifactVerificationEntry(artifact) {
-    if (isPendingRecordingArtifact(artifact)) {
-        return {
-            absolutePath: artifact.absolutePath,
-            exists: artifact.exists,
-            kind: artifact.kind,
-            limitation: "Recording output is pending until native finalization succeeds and the file is verified.",
-            recording: artifact.recording,
-            recordingStartedAtMs: artifact.recordingStartedAtMs,
-            mediaType: artifact.mediaType,
-            path: artifact.path,
-            recordingState: artifact.recordingState ?? "openRecording",
-            requestedPath: artifact.requestedPath,
-            retentionState: undefined,
-            sizeBytes: artifact.sizeBytes,
-            state: "pending",
-            status: artifact.status ?? "pending",
-            storageScope: undefined,
-            willExistOnStop: artifact.willExistOnStop ?? true,
-        };
+function getSavedFileCommand(commandInfo) {
+    if (commandInfo.command === "wait" && isDownloadWaitSubcommand(commandInfo.subcommand)) {
+        return "wait";
     }
-    const state = ["failed", "stale", "unverified"].includes(artifact.status ?? "")
-        ? "unverified"
-        : artifact.exists === true
-            ? "verified"
-            : artifact.exists === false
-                ? "missing"
-                : "unverified";
-    return {
-        absolutePath: artifact.absolutePath,
-        exists: artifact.exists,
-        kind: artifact.kind,
-        recording: artifact.recording,
-        recordingStartedAtMs: artifact.recordingStartedAtMs,
-        limitation: artifact.status === "failed" || artifact.status === "unverified"
-            ? "File presence does not prove successful native recording finalization or encoding. Inspect the receipt and original failure."
-            : artifact.status === "stale"
-                ? "The reported path's modification time fell outside this command's bounded artifact window. Treat the artifact as stale until regenerated."
-                : state === "missing"
-                    ? "The wrapper did not find the reported artifact at absolutePath. Treat the path as unverified until recovered or regenerated."
-                    : state === "unverified"
-                        ? "The wrapper could not prove local filesystem existence for this artifact."
-                        : undefined,
-        mediaType: artifact.mediaType,
-        path: artifact.path,
-        requestedPath: artifact.requestedPath,
-        retentionState: artifact.exists === false ? "missing" : "live",
-        sizeBytes: artifact.sizeBytes,
-        state,
-        status: artifact.status,
-        storageScope: "explicit-path",
-        updatedAtMs: artifact.updatedAtMs,
-    };
-}
-function getManifestVerificationEntry(entry) {
-    if (entry.storageScope === "explicit-path")
-        return undefined;
-    const state = entry.retentionState === "live"
-        ? "verified"
-        : entry.retentionState === "missing" || entry.retentionState === "evicted"
-            ? "missing"
-            : "unverified";
-    return {
-        absolutePath: entry.absolutePath,
-        exists: entry.exists,
-        kind: entry.kind,
-        limitation: entry.retentionState === "ephemeral"
-            ? "This spill file is process-temporary and may not survive reload or restart."
-            : entry.retentionState === "evicted"
-                ? "This persisted spill file was evicted from the bounded session artifact store."
-                : undefined,
-        mediaType: entry.mediaType,
-        path: entry.path,
-        requestedPath: entry.requestedPath,
-        retentionState: entry.retentionState,
-        sizeBytes: entry.sizeBytes,
-        state,
-        storageScope: entry.storageScope,
-    };
-}
-export function buildArtifactVerificationSummary(artifacts, manifest, manifestPaths) {
-    const entries = [
-        ...artifacts.map(getArtifactVerificationEntry),
-        ...(manifest?.entries.flatMap((entry) => {
-            if (manifestPaths && !manifestPaths.has(entry.path))
-                return [];
-            const verificationEntry = getManifestVerificationEntry(entry);
-            return verificationEntry ? [verificationEntry] : [];
-        }) ?? []),
-    ];
-    if (entries.length === 0)
-        return undefined;
-    const verifiedCount = entries.filter((entry) => entry.state === "verified").length;
-    const missingCount = entries.filter((entry) => entry.state === "missing").length;
-    const pendingCount = entries.filter((entry) => entry.state === "pending").length;
-    const unverifiedCount = entries.filter((entry) => entry.state === "unverified").length;
-    return {
-        artifacts: entries,
-        missingCount,
-        pendingCount,
-        unverifiedCount,
-        verified: entries.length > 0 && verifiedCount === entries.length,
-        verifiedCount,
-    };
-}
-export function hasMissingFileArtifact(artifacts) {
-    return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) && (artifact.exists === false || artifact.status === "stale"));
-}
-export function formatMissingArtifactFailureText(artifacts) {
-    const failedArtifacts = (artifacts ?? []).filter((artifact) => !isPendingRecordingArtifact(artifact) && (artifact.exists === false || artifact.status === "stale"));
-    if (failedArtifacts.length === 0)
-        return undefined;
-    if (failedArtifacts.length === 1) {
-        const artifact = failedArtifacts[0];
-        return artifact.status === "stale"
-            ? `Artifact verification failed: requested ${artifact.kind} path ${artifact.absolutePath} has a modification time outside the current command window.`
-            : `Artifact verification failed: requested ${artifact.kind} was not found at ${artifact.absolutePath}.`;
-    }
-    return `Artifact verification failed: ${failedArtifacts.length} requested artifacts were missing or stale.`;
-}
-export function classifyPresentationSuccessCategory(options) {
-    if ((options.artifactVerification?.missingCount ?? 0) > 0 || (options.artifactVerification?.unverifiedCount ?? 0) > 0) {
-        return "artifact-unverified";
-    }
-    return classifyAgentBrowserSuccessCategory(options);
-}
-function formatArtifactLabel(artifact) {
-    switch (artifact.kind) {
-        case "download":
-            if (artifact.exists !== true) {
-                return artifact.command === "wait" && isDownloadWaitSubcommand(artifact.subcommand) ? "Download event reported; file not verified" : "Download reported; file not verified";
-            }
-            return artifact.command === "wait" && isDownloadWaitSubcommand(artifact.subcommand) ? "Download saved and verified" : "Downloaded file verified";
-        case "file":
-            return artifact.command === "state" ? "State file" : "Saved file";
-        case "har":
-            return "Saved HAR";
-        case "image":
-            if (artifact.exists !== true)
-                return artifact.command === "diff" && artifact.subcommand === "screenshot" ? "Diff image reported; file not verified" : "Image reported; file not verified";
-            return artifact.command === "diff" && artifact.subcommand === "screenshot" ? "Saved diff image" : "Saved image";
-        case "pdf":
-            return "Saved PDF";
-        case "profile":
-            return "Saved profile";
-        case "trace":
-            return "Saved trace";
-        case "video":
-            if (artifact.status === "failed")
-                return artifact.subcommand === "restart-previous" ? "Previous recording failed" : "Recording failed";
-            if (artifact.status === "unverified")
-                return artifact.subcommand === "restart-previous" ? "Previous recording unverified" : "Recording unverified";
-            if (artifact.command === "record" && artifact.subcommand === "restart-previous") {
-                if (artifact.status === "stale")
-                    return "Previous recording stale";
-                if (artifact.exists === false)
-                    return "Previous recording missing";
-                return "Previous recording saved";
-            }
-            if (!isPendingRecordingArtifact(artifact))
-                return artifact.status === "saved" ? "Saved recording" : "Recording reported; file not verified";
-            if (artifact.subcommand === "stop")
-                return "Recording finalization pending";
-            return artifact.subcommand === "restart" ? "Recording restarted; output will be written on stop" : "Recording started; output will be written on stop";
-    }
-}
-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 previousRecordingArtifacts = artifacts.filter((artifact) => artifact.command === "record" && artifact.subcommand === "restart-previous");
-    if (restartArtifact && previousRecordingArtifacts.length > 0) {
-        return [...previousRecordingArtifacts, 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(", ")}`;
-}
-export function formatArtifactMetadataLines(artifacts) {
-    return artifacts.map((artifact, index) => {
-        if (isPendingRecordingArtifact(artifact)) {
-            return [
-                `${formatArtifactLabel(artifact)}: ${artifact.path}`,
-                `Artifact type: ${artifact.kind}`,
-                artifact.requestedPath ? `Requested path: ${artifact.requestedPath}` : undefined,
-                `Absolute path: ${artifact.absolutePath}`,
-                `Exists: ${artifact.exists ?? "pending until record stop"}`,
-                `Status: ${artifact.status ?? "pending"}`,
-                `Recording state: ${artifact.recordingState ?? "openRecording"}`,
-                `Will exist on stop: ${artifact.willExistOnStop !== false}`,
-                artifact.session ? `Session: ${artifact.session}` : undefined,
-                artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
-                artifact.recording ? formatRecordingReceipt(artifact.recording) : undefined,
-                `Machine data: details.artifacts[${index}]`,
-            ].filter((item) => item !== undefined).join("\n");
-        }
-        return [
-            `${formatArtifactLabel(artifact)}: ${artifact.path}`,
-            `Artifact type: ${artifact.kind}`,
-            artifact.requestedPath ? `Requested path: ${artifact.requestedPath}` : undefined,
-            `Absolute path: ${artifact.absolutePath}`,
-            `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")}`,
-            artifact.tempPath ? `Reported path: ${artifact.tempPath}` : undefined,
-            artifact.mediaType ? `Media type: ${artifact.mediaType}` : undefined,
-            artifact.session ? `Session: ${artifact.session}` : undefined,
-            artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
-            artifact.recording ? formatRecordingReceipt(artifact.recording) : undefined,
-            `Machine data: details.artifacts[${index}]`,
-        ].filter((item) => item !== undefined).join("\n");
-    });
-}
-function isDownloadWaitCommand(commandInfo) {
-    return commandInfo.command === "wait" && isDownloadWaitSubcommand(commandInfo.subcommand);
-}
-function extractSavedFilePath(data) {
-    return typeof data.path === "string" && data.path.trim().length > 0 ? data.path : undefined;
+    return commandInfo.command === "download" || commandInfo.command === "pdf"
+        ? commandInfo.command
+        : undefined;
 }
 export function getSavedFileDetails(commandInfo, data) {
-    const path = extractSavedFilePath(data);
-    if (!path || isNonFileArtifactPathCandidate(path)) {
+    const path = typeof data.path === "string" && data.path.trim().length > 0 ? data.path : undefined;
+    if (path === undefined || isNonFileArtifactPathCandidate(path)) {
         return undefined;
     }
-    const savedFileCommand = isDownloadWaitCommand(commandInfo)
-        ? "wait"
-        : commandInfo.command === "download" || commandInfo.command === "pdf"
-            ? commandInfo.command
-            : undefined;
-    if (!savedFileCommand) {
+    const command = getSavedFileCommand(commandInfo);
+    if (command === undefined) {
         return undefined;
     }
     const { path: _path, ...metadata } = data;
-    const details = {
-        command: savedFileCommand,
-        kind: savedFileCommand === "pdf" ? "pdf" : "download",
+    return {
+        command,
+        kind: command === "pdf" ? "pdf" : "download",
         path,
+        ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+        ...(commandInfo.subcommand !== undefined && commandInfo.subcommand.length > 0
+            ? { subcommand: commandInfo.subcommand }
+            : {}),
     };
-    if (Object.keys(metadata).length > 0) {
-        details.metadata = metadata;
-    }
-    if (commandInfo.subcommand) {
-        details.subcommand = commandInfo.subcommand;
-    }
-    return details;
-}
-function isTrustedScreenshotOutput(commandInfo) {
-    return commandInfo.command === "screenshot";
-}
-export function extractImagePath(commandInfo, cwd, data) {
-    if (!isTrustedScreenshotOutput(commandInfo)) {
-        return undefined;
-    }
-    const path = typeof data === "string" ? data : isRecord(data) && typeof data.path === "string" ? data.path : undefined;
-    return path?.trim() && !isNonFileArtifactPathCandidate(path) ? resolve(cwd, path) : undefined;
-}
-export async function attachInlineImage(presentation, imagePath, modelVisible = true) {
-    try {
-        const fileStats = await stat(imagePath);
-        const handle = await open(imagePath, "r");
-        let header;
-        try {
-            // Pi's dimension API accepts base64. Encode only a bounded header, never the whole code-mode image.
-            const bytes = Buffer.alloc(64 * 1024);
-            const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
-            header = bytes.subarray(0, bytesRead);
-        }
-        finally {
-            await handle.close();
-        }
-        const mimeType = getImageMimeType(header);
-        if (!mimeType)
-            return presentation;
-        const dimensions = getImageDimensions(header.toString("base64"), mimeType);
-        presentation.imagePath = imagePath;
-        const lifecycle = isRecord(presentation.data) && isRecord(presentation.data.lifecycle) ? presentation.data.lifecycle : undefined;
-        const textRendered = isRecord(lifecycle?.effectiveLaunch) && lifecycle.effectiveLaunch.engine === "lightpanda";
-        presentation.imageObservations = [{ path: imagePath, mimeType,
-                ...(textRendered ? { rendering: "text" } : {}),
-                pixels: dimensions ? { width: dimensions.widthPx, height: dimensions.heightPx } : undefined,
-                capture: "unknown", geometry: { status: "unknown", reason: textRendered ? LIGHTPANDA_IMAGE_REASON : dimensions ? "Capture geometry was not observed." : "Image dimensions could not be read from the bounded header." } }];
-        if (!modelVisible)
-            return presentation;
-        if (textRendered)
-            appendPresentationNotice(presentation, LIGHTPANDA_IMAGE_REASON);
-        const inlineImageMaxBytes = getInlineImageMaxBytes();
-        if (fileStats.size > inlineImageMaxBytes) {
-            appendPresentationNotice(presentation, `Image attachment skipped: ${formatByteCount(fileStats.size)} exceeds the inline limit of ${formatByteCount(inlineImageMaxBytes)}.`);
-            presentation.imagePath = imagePath;
-            return presentation;
-        }
-        const file = await readFile(imagePath);
-        presentation.content.push({ type: "image", data: file.toString("base64"), mimeType });
-        presentation.imagePath = imagePath;
-        return presentation;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        appendPresentationNotice(presentation, `Image attachment failed: ${message}`);
-        presentation.imagePath = imagePath;
-        return presentation;
-    }
 }