pi-agent-browser-native 0.9.3 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/operation-paths.js

@@ -1,76 +1,142 @@
 import { isAbsolute, resolve } from "node:path";
 import { projectUpstreamGlobalFlags, scanUpstreamGlobalFlagOccurrences } from "../argv-grammar.js";
-import { getDiffFilePathIndices, getExplicitArtifactDestinationIndex } from "./browser-run/artifact-paths.js";
+import { getDiffFilePathIndices, getExplicitArtifactDestinationIndex, } from "./browser-run/artifact-paths.js";
 import { parseBatchCommandArgument, parseUserBatchStdin } from "./batch-stdin.js";
-/** Bind caller file operands without moving the native process/config or interpreting literal form data. */
-export function resolveOperationPaths(args, stdin, cwd, batchStep = false) {
-    let resolved = args;
-    const setPath = (index, prefix = "") => {
-        const path = index === undefined ? undefined : args[index]?.slice(prefix.length);
-        if (index === undefined || !path || isAbsolute(path))
+const FILE_GLOBAL_FLAGS = [
+    "--config",
+    "--ca-cert",
+    "--executable-path",
+    "--extension",
+    "--init-script",
+    "--download-path",
+    "--screenshot-dir",
+    "--action-policy",
+    "--state",
+];
+/** Owns copy-on-write argv; unchanged rows retain identity for batch stdin preservation. */
+class OperationPathBinding {
+    args;
+    cwd;
+    changedArgs;
+    tokens;
+    indices;
+    constructor(args, cwd, batchStep) {
+        this.args = args;
+        this.cwd = cwd;
+        const projection = batchStep
+            ? { tokens: args, indices: args.map((_, index) => index) }
+            : projectUpstreamGlobalFlags(args);
+        this.tokens = projection.tokens;
+        this.indices = projection.indices;
+    }
+    get result() {
+        return this.changedArgs ?? this.args;
+    }
+    replace(index, value) {
+        this.changedArgs ??= [...this.args];
+        this.changedArgs[index] = value;
+    }
+    setPath(index, prefix = "") {
+        if (index === undefined) {
             return;
-        if (resolved === args)
-            resolved = [...args];
-        resolved[index] = prefix + resolve(cwd, path);
-    };
-    const { tokens, indices } = batchStep ? { tokens: args, indices: args.map((_, index) => index) } : projectUpstreamGlobalFlags(args);
-    if (!batchStep) {
-        for (const flag of ["--config", "--ca-cert", "--executable-path", "--extension", "--init-script", "--download-path", "--screenshot-dir", "--action-policy", "--state"]) {
-            for (const occurrence of scanUpstreamGlobalFlagOccurrences(args, flag)) {
-                if (flag === "--state" && tokens[0] === "wait" && occurrence.index > indices[0])
+        }
+        const path = this.args.at(index)?.slice(prefix.length);
+        if (path === undefined || path.length === 0 || isAbsolute(path)) {
+            return;
+        }
+        this.replace(index, prefix + resolve(this.cwd, path));
+    }
+    bindGlobals() {
+        for (const flag of FILE_GLOBAL_FLAGS) {
+            for (const occurrence of scanUpstreamGlobalFlagOccurrences([...this.args], flag)) {
+                if (flag === "--state" && this.tokens[0] === "wait" && occurrence.index > this.indices[0]) {
                     continue;
-                setPath(occurrence.index + 1);
+                }
+                this.setPath(occurrence.index + 1);
             }
         }
-        for (const occurrence of scanUpstreamGlobalFlagOccurrences(args, "--profile")) {
-            // Native Chrome profile names are identities, not workspace file paths.
-            if (occurrence.value && /[\\/]/.test(occurrence.value) && !occurrence.value.startsWith("~"))
-                setPath(occurrence.index + 1);
+        for (const occurrence of scanUpstreamGlobalFlagOccurrences([...this.args], "--profile")) {
+            const value = occurrence.value;
+            // Chrome profile names are identities, not workspace file paths.
+            if (value !== undefined && /[\\/]/.test(value) && !value.startsWith("~")) {
+                this.setPath(occurrence.index + 1);
+            }
         }
     }
-    if (tokens[0] === "batch") {
-        if (tokens.slice(1).some(token => token !== "--bail")) {
-            for (let index = 1; index < tokens.length; index++) {
-                if (tokens[index] === "--bail")
-                    continue;
-                const row = parseBatchCommandArgument(tokens[index]).step;
-                if (!row)
-                    continue;
-                const bound = resolveOperationPaths(row, undefined, cwd, true).args;
-                if (bound === row)
-                    continue;
-                if (resolved === args)
-                    resolved = [...args];
-                resolved[indices[index]] = bound.map(token => `'${token.replaceAll("'", "'\\''")}'`).join(" ");
+    bindRawBatchRows() {
+        for (let index = 1; index < this.tokens.length; index++) {
+            if (this.tokens[index] === "--bail") {
+                continue;
+            }
+            const row = parseBatchCommandArgument(this.tokens[index]).step;
+            if (row === undefined) {
+                continue;
+            }
+            const bound = resolveOperationPaths(row, undefined, this.cwd, true).args;
+            if (bound !== row) {
+                this.replace(this.indices[index], bound.map((token) => `'${token.replaceAll("'", "'\\''")}'`).join(" "));
             }
-            return { args: resolved, stdin }; // Native ignores stdin when raw rows exist.
         }
-        const rows = parseUserBatchStdin(stdin).steps;
-        if (!rows?.length)
-            return { args: resolved, stdin };
-        const bound = rows.map(row => resolveOperationPaths(row, undefined, cwd, true).args);
-        return { args: resolved, stdin: bound.some((row, index) => row !== rows[index]) ? JSON.stringify(bound) : stdin };
     }
-    setPath(indices[getExplicitArtifactDestinationIndex(tokens) ?? -1]);
-    if (tokens[0] === "upload")
-        for (let index = 2; index < tokens.length; index++)
-            setPath(indices[index]);
-    if (tokens[0] === "state" && tokens[1] === "load")
-        setPath(indices[2]);
-    setPath(indices[getDiffFilePathIndices(tokens).baseline ?? -1]);
-    if (tokens[0] === "cookies" && tokens[1] === "set") {
-        const index = tokens.indexOf("--curl");
-        if (index >= 0)
-            setPath(indices[index + 1]);
+    bindFileOperands() {
+        this.setPath(this.indices[getExplicitArtifactDestinationIndex([...this.tokens]) ?? -1]);
+        if (this.tokens[0] === "upload") {
+            for (let index = 2; index < this.tokens.length; index++) {
+                this.setPath(this.indices[index]);
+            }
+        }
+        if (this.tokens[0] === "state" && this.tokens[1] === "load") {
+            this.setPath(this.indices[2]);
+        }
+        this.setPath(this.indices[getDiffFilePathIndices([...this.tokens]).baseline ?? -1]);
+        if (this.tokens[0] === "cookies" && this.tokens[1] === "set") {
+            const index = this.tokens.indexOf("--curl");
+            if (index >= 0) {
+                this.setPath(this.indices[index + 1]);
+            }
+        }
+        this.bindWebMcpParams();
+    }
+    bindBatch(stdin) {
+        if (this.tokens.slice(1).some((token) => token !== "--bail")) {
+            this.bindRawBatchRows();
+            return { args: this.result, stdin }; // Native ignores stdin when raw rows exist.
+        }
+        const rows = parseUserBatchStdin(stdin).steps;
+        if (rows === undefined || rows.length === 0) {
+            return { args: this.result, stdin };
+        }
+        const bound = rows.map((row) => resolveOperationPaths(row, undefined, this.cwd, true).args);
+        return {
+            args: this.result,
+            stdin: bound.some((row, index) => row !== rows[index]) ? JSON.stringify(bound) : stdin,
+        };
     }
-    if (tokens[0] === "webmcp" && tokens[1] === "invoke") {
-        for (let index = 3; index < tokens.length; index++) {
-            if (!["--params", "--frame", "--timeout"].includes(tokens[index]))
+    bindWebMcpParams() {
+        if (this.tokens[0] !== "webmcp" || this.tokens[1] !== "invoke") {
+            return;
+        }
+        for (let index = 3; index < this.tokens.length; index++) {
+            if (!["--params", "--frame", "--timeout"].includes(this.tokens[index])) {
                 continue;
-            if (tokens[index] === "--params" && tokens[index + 1]?.startsWith("@"))
-                setPath(indices[index + 1], "@");
+            }
+            if (this.tokens[index] === "--params" &&
+                this.tokens.at(index + 1)?.startsWith("@") === true) {
+                this.setPath(this.indices[index + 1], "@");
+            }
             index++;
         }
     }
-    return { args: resolved, stdin };
+}
+/** Bind file operands without moving native process/config or interpreting literal form data. */
+export function resolveOperationPaths(args, stdin, cwd, batchStep = false) {
+    const binding = new OperationPathBinding(args, cwd, batchStep);
+    if (!batchStep) {
+        binding.bindGlobals();
+    }
+    if (binding.tokens[0] === "batch") {
+        return binding.bindBatch(stdin);
+    }
+    binding.bindFileOperands();
+    return { args: binding.result, stdin };
 }

package/dist/extensions/agent-browser/lib/orchestration/output-file.js

@@ -1,119 +1,190 @@
 import { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import { dirname, extname, isAbsolute, resolve } from "node:path";
 import { isRecord } from "../parsing.js";
+import { isStringArray } from "../input-modes/shared.js";
 import { getBooleanFlagValue } from "../argv-grammar.js";
 import { isSessionArtifactManifest } from "../results/artifact-manifest.js";
 import { parseCommandInfo, redactSensitiveValue } from "../runtime.js";
+import { stringifyUnknown } from "../results/text.js";
 export function normalizeRequestedOutputPath(path) {
     return path.startsWith("@") ? path.slice(1) : path;
 }
 function getTextContent(result) {
     return result.content
-        ?.filter((item) => item.type === "text")
+        .filter((item) => item.type === "text")
         .map((item) => item.text)
-        .join("\n\n") ?? "";
+        .join("\n\n");
 }
 function getResultCommand(details) {
-    const args = Array.isArray(details?.args) && details.args.every(value => typeof value === "string") ? details.args : [];
-    return parseCommandInfo(args);
+    return parseCommandInfo(isStringArray(details?.args) ? details.args : []);
 }
 function isRecordingReceiptResult(result) {
     const details = isRecord(result.details) ? result.details : undefined;
-    return details?.command === "record" || getResultCommand(details).command === "record" || details?.recordingRecovery !== undefined
-        || (Array.isArray(details?.batchSteps) && details.batchSteps.some((step) => isRecord(step) && Array.isArray(step.command) && step.command[0] === "record"));
+    return (details?.command === "record" ||
+        getResultCommand(details).command === "record" ||
+        details?.recordingRecovery !== undefined ||
+        (Array.isArray(details?.batchSteps) &&
+            details.batchSteps.some((step) => isRecord(step) && Array.isArray(step.command) && step.command[0] === "record")));
 }
 export function canWriteAgentBrowserOutput(result) {
-    return isRecordingReceiptResult(result) || (!result.isError && !(isRecord(result.details) && result.details.resultCategory === "failure"));
+    return (isRecordingReceiptResult(result) ||
+        (result.isError !== true &&
+            !(isRecord(result.details) && result.details.resultCategory === "failure")));
 }
 function getOutputSource(result) {
-    if (isRecordingReceiptResult(result))
+    if (isRecordingReceiptResult(result)) {
         return "recording-receipt";
-    return isRecord(result.details) && result.details.data !== undefined ? "details.data" : "content.text";
+    }
+    return isRecord(result.details) && result.details.data !== undefined
+        ? "details.data"
+        : "content.text";
+}
+function preferredString(record, primary, fallback) {
+    const first = record?.[primary];
+    if (typeof first === "string") {
+        return first;
+    }
+    const second = fallback === undefined ? undefined : record?.[fallback];
+    return typeof second === "string" ? second : undefined;
 }
 async function readCompactedSpill(path, manifest) {
-    if (!path || !manifest?.entries.some((entry) => entry.kind === "spill"
-        && (entry.path === path || entry.absolutePath === path)
-        && (entry.storageScope === "persistent-session" || entry.storageScope === "process-temp")
-        && (entry.retentionState === "live" || entry.retentionState === "ephemeral")))
+    const live = manifest?.entries.some((entry) => entry.kind === "spill" &&
+        (entry.path === path || entry.absolutePath === path) &&
+        (entry.storageScope === "persistent-session" || entry.storageScope === "process-temp") &&
+        (entry.retentionState === "live" || entry.retentionState === "ephemeral"));
+    if (path === undefined || path.length === 0 || live !== true) {
         throw new Error("Full compacted output is unavailable from the wrapper-managed spill; outputPath was not written.");
+    }
     const text = await readFile(path, "utf8");
-    return extname(path) === ".json" ? JSON.parse(text) : text;
+    if (extname(path) !== ".json") {
+        return text;
+    }
+    const parsed = JSON.parse(text);
+    return parsed;
 }
 async function rehydrateCompactedData(data, details, manifest) {
     if (isRecord(data) && data.compacted === true) {
-        return readCompactedSpill(typeof details.fullOutputPath === "string" ? details.fullOutputPath : undefined, manifest);
+        return readCompactedSpill(preferredString(details, "fullOutputPath"), manifest);
     }
-    if (!Array.isArray(data))
+    if (!Array.isArray(data)) {
         return data;
+    }
     const batchSteps = Array.isArray(details.batchSteps) ? details.batchSteps : [];
     return Promise.all(data.map(async (row, index) => {
-        if (!isRecord(row) || !isRecord(row.result) || row.result.compacted !== true)
+        if (!isRecord(row) || !isRecord(row.result) || row.result.compacted !== true) {
             return row;
-        const step = isRecord(batchSteps[index]) ? batchSteps[index] : undefined;
-        const path = typeof step?.fullOutputPath === "string"
-            ? step.fullOutputPath
-            : typeof row.result.fullOutputPath === "string" ? row.result.fullOutputPath : undefined;
+        }
+        const rawStep = batchSteps[index];
+        const step = isRecord(rawStep) ? rawStep : undefined;
+        const path = preferredString(step, "fullOutputPath") ?? preferredString(row.result, "fullOutputPath");
         return { ...row, result: await readCompactedSpill(path, manifest) };
     }));
 }
+function recordingAttempt(details, success) {
+    return {
+        success,
+        agentBrowserStarted: details.agentBrowserStarted ?? null,
+        exitCode: details.exitCode ?? null,
+        timedOut: details.timedOut === true,
+        error: details.error ?? details.validationError ?? null,
+        parseError: details.parseError ?? null,
+    };
+}
+function recordingError(result, details, success) {
+    return details.error ?? (success ? null : (details.summary ?? getTextContent(result)));
+}
+function recordingReceipt(result, data, details) {
+    const success = result.isError !== true && details.resultCategory !== "failure";
+    const recovery = isRecord(details.recordingRecovery) ? details.recordingRecovery : undefined;
+    const command = getResultCommand(details);
+    return redactSensitiveValue({
+        success,
+        error: recordingError(result, details, success),
+        command: details.command ?? command.command,
+        subcommand: details.subcommand ?? command.subcommand,
+        sessionName: details.sessionName,
+        namespace: details.namespace,
+        attempt: recovery?.attempt ?? recordingAttempt(details, success),
+        data: data ?? null,
+        artifacts: details.artifacts,
+        artifactVerification: details.artifactVerification,
+        recordingRecovery: recovery,
+    });
+}
 async function getOutputPayload(result) {
     const details = isRecord(result.details) ? result.details : undefined;
-    if (!details)
+    if (details === undefined) {
         return { source: "content.text", value: getTextContent(result) };
-    const manifest = isSessionArtifactManifest(details.artifactManifest) ? details.artifactManifest : undefined;
+    }
+    const manifest = isSessionArtifactManifest(details.artifactManifest)
+        ? details.artifactManifest
+        : undefined;
     const data = await rehydrateCompactedData(details.data, details, manifest);
     if (isRecordingReceiptResult(result)) {
-        const success = !result.isError && details.resultCategory !== "failure";
-        const recovery = isRecord(details.recordingRecovery) ? details.recordingRecovery : undefined;
-        const commandInfo = getResultCommand(details);
-        return { source: "recording-receipt", value: redactSensitiveValue({
-                success, error: details.error ?? (success ? null : details.summary ?? getTextContent(result)),
-                command: details.command ?? commandInfo.command, subcommand: details.subcommand ?? commandInfo.subcommand, sessionName: details.sessionName, namespace: details.namespace,
-                attempt: recovery?.attempt ?? { success, agentBrowserStarted: details.agentBrowserStarted ?? null, exitCode: details.exitCode ?? null, timedOut: details.timedOut === true, error: details.error ?? details.validationError ?? null, parseError: details.parseError ?? null },
-                data: data ?? null, artifacts: details.artifacts, artifactVerification: details.artifactVerification, recordingRecovery: recovery,
-            }) };
+        return { source: "recording-receipt", value: recordingReceipt(result, data, details) };
     }
-    return data === undefined ? { source: "content.text", value: getTextContent(result) } : { source: "details.data", value: data };
+    return data === undefined
+        ? { source: "content.text", value: getTextContent(result) }
+        : { source: "details.data", value: data };
 }
-function serializeOutputPayload(value) {
-    return typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`;
+function jsonOutputNotice(result, text, message, failed) {
+    const nativeText = isRecord(result.details) &&
+        isStringArray(result.details.args) &&
+        getBooleanFlagValue(result.details.args, "--json") === false;
+    if (nativeText) {
+        return undefined;
+    }
+    try {
+        const json = JSON.parse(text);
+        if (isRecord(json) && typeof json.success === "boolean") {
+            return JSON.stringify({
+                ...json,
+                ...(failed ? { success: false, error: message } : {}),
+                outputFileNotice: message,
+            }, null, 2);
+        }
+    }
+    catch {
+        /* Non-JSON native text receives a prose notice instead. */
+    }
+    return undefined;
 }
 function appendOutputFileNotice(result, message, failed = false) {
-    const content = [...(result.content ?? [])];
+    const content = [...result.content];
     if (content[0]?.type === "text") {
-        const nativeText = isRecord(result.details) && Array.isArray(result.details.args) && getBooleanFlagValue(result.details.args, "--json") === false;
-        try {
-            const json = nativeText ? undefined : JSON.parse(content[0].text);
-            if (isRecord(json) && typeof json.success === "boolean") {
-                content[0] = { type: "text", text: JSON.stringify({ ...json, ...(failed ? { success: false, error: message } : {}), outputFileNotice: message }, null, 2) };
-                return content;
-            }
-        }
-        catch { }
-        content[0] = { ...content[0], text: `${content[0].text}\n\n${message}` };
+        const json = jsonOutputNotice(result, content[0].text, message, failed);
+        content[0] = { type: "text", text: json ?? `${content[0].text}\n\n${message}` };
         return content;
     }
     return [{ type: "text", text: message }, ...content];
 }
 function getArtifactPaths(result, cwd) {
     const details = isRecord(result.details) ? result.details : undefined;
-    if (!details || !Array.isArray(details.artifacts))
+    if (details === undefined || !Array.isArray(details.artifacts)) {
         return [];
+    }
     return details.artifacts.flatMap((artifact) => {
-        if (!isRecord(artifact))
+        if (!isRecord(artifact)) {
             return [];
-        const path = typeof artifact.absolutePath === "string" ? artifact.absolutePath : typeof artifact.path === "string" ? artifact.path : undefined;
-        return path ? [isAbsolute(path) ? path : resolve(cwd, path)] : [];
+        }
+        const path = preferredString(artifact, "absolutePath", "path");
+        return path !== undefined && path.length > 0
+            ? [isAbsolute(path) ? path : resolve(cwd, path)]
+            : [];
     });
 }
 async function pathsReferToSameFile(left, right) {
-    if (resolve(left) === resolve(right))
+    if (resolve(left) === resolve(right)) {
         return true;
+    }
     try {
-        if (await realpath(left) === await realpath(right))
+        if ((await realpath(left)) === (await realpath(right))) {
             return true;
+        }
+    }
+    catch {
+        /* Missing paths can still be compared through stat when both resolve later. */
     }
-    catch { }
     try {
         const [leftStat, rightStat] = await Promise.all([stat(left), stat(right)]);
         return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
@@ -122,57 +193,84 @@ async function pathsReferToSameFile(left, right) {
         return false;
     }
 }
+async function overlapsArtifact(result, path, cwd) {
+    for (const artifact of getArtifactPaths(result, cwd)) {
+        // Stop on the first alias; never write while any browser artifact identity remains unchecked.
+        // oxlint-disable-next-line no-await-in-loop
+        if (await pathsReferToSameFile(path, artifact)) {
+            return true;
+        }
+    }
+    return false;
+}
+function failedOutputResult(result, outputFile, rejected) {
+    const details = isRecord(result.details) ? { ...result.details } : {};
+    delete details.successCategory;
+    const message = outputFile.error ?? "Output file failed.";
+    return {
+        ...result,
+        content: appendOutputFileNotice(result, rejected
+            ? `Output file rejected: ${message}`
+            : `Output file failed: ${outputFile.path} (${message}).`, true),
+        details: {
+            ...details,
+            error: message,
+            summary: rejected ? "Output file rejected." : "Output file failed.",
+            failureCategory: rejected
+                ? "validation-error"
+                : (details.failureCategory ?? "upstream-error"),
+            outputFile,
+            resultCategory: "failure",
+        },
+        isError: true,
+    };
+}
+async function saveOutput(result, destination, preserveText) {
+    const payload = await getOutputPayload(result);
+    const serialized = typeof payload.value === "string"
+        ? payload.value
+        : `${JSON.stringify(payload.value, null, 2)}\n`;
+    await mkdir(dirname(destination.absolutePath), { recursive: true });
+    await writeFile(destination.absolutePath, serialized, "utf8");
+    const bytes = Buffer.byteLength(serialized, "utf8");
+    const outputFile = {
+        ...destination,
+        bytes,
+        source: payload.source,
+        status: "saved",
+    };
+    const details = isRecord(result.details) ? { ...result.details, outputFile } : { outputFile };
+    return {
+        ...result,
+        content: preserveText
+            ? result.content
+            : appendOutputFileNotice(result, `Output file: ${destination.path} (${bytes} bytes from ${payload.source}).`),
+        details,
+    };
+}
 export async function applyAgentBrowserOutputPath(options) {
-    if (!options.outputPath)
+    if (options.outputPath === undefined ||
+        options.outputPath.length === 0 ||
+        !canWriteAgentBrowserOutput(options.result)) {
         return options.result;
-    if (!canWriteAgentBrowserOutput(options.result))
-        return options.result;
-    const requestedPath = normalizeRequestedOutputPath(options.outputPath);
-    const absolutePath = isAbsolute(requestedPath) ? requestedPath : resolve(options.cwd, requestedPath);
-    const source = getOutputSource(options.result);
-    for (const artifactPath of getArtifactPaths(options.result, options.cwd)) {
-        if (!await pathsReferToSameFile(absolutePath, artifactPath))
-            continue;
-        const message = "outputPath resolves to the same file as a browser artifact destination; choose a separate outputPath or omit it. The browser artifact was preserved.";
-        const outputFile = { absolutePath, error: message, path: requestedPath, source, status: "failed" };
-        const details = isRecord(options.result.details) ? { ...options.result.details } : {};
-        delete details.successCategory;
-        return {
-            ...options.result,
-            content: appendOutputFileNotice(options.result, `Output file rejected: ${message}`, true),
-            details: { ...details, error: message, summary: "Output file rejected.", failureCategory: "validation-error", outputFile, resultCategory: "failure" },
-            isError: true,
-        };
+    }
+    const path = normalizeRequestedOutputPath(options.outputPath);
+    const destination = {
+        absolutePath: isAbsolute(path) ? path : resolve(options.cwd, path),
+        path,
+        source: getOutputSource(options.result),
+        status: "failed",
+    };
+    if (await overlapsArtifact(options.result, destination.absolutePath, options.cwd)) {
+        return failedOutputResult(options.result, {
+            ...destination,
+            error: "outputPath resolves to the same file as a browser artifact destination; choose a separate outputPath or omit it. The browser artifact was preserved.",
+        }, true);
     }
     try {
-        const payload = await getOutputPayload(options.result);
-        const serialized = serializeOutputPayload(payload.value);
-        await mkdir(dirname(absolutePath), { recursive: true });
-        await writeFile(absolutePath, serialized, "utf8");
-        const bytes = Buffer.byteLength(serialized, "utf8");
-        const outputFile = { absolutePath, bytes, path: requestedPath, source: payload.source, status: "saved" };
-        const details = isRecord(options.result.details) ? { ...options.result.details, outputFile } : { outputFile };
-        return {
-            ...options.result,
-            content: options.preserveTextContent ? options.result.content : appendOutputFileNotice(options.result, `Output file: ${requestedPath} (${bytes} bytes from ${payload.source}).`),
-            details,
-        };
+        return await saveOutput(options.result, destination, options.preserveTextContent === true);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        const outputFile = { absolutePath, error: message, path: requestedPath, source, status: "failed" };
-        const details = isRecord(options.result.details)
-            ? (() => {
-                const rest = { ...options.result.details };
-                delete rest.successCategory;
-                return { ...rest, error: message, summary: "Output file failed.", failureCategory: rest.failureCategory ?? "upstream-error", outputFile, resultCategory: "failure" };
-            })()
-            : { error: message, summary: "Output file failed.", failureCategory: "upstream-error", outputFile, resultCategory: "failure" };
-        return {
-            ...options.result,
-            content: appendOutputFileNotice(options.result, `Output file failed: ${requestedPath} (${message}).`, true),
-            details,
-            isError: true,
-        };
+        return failedOutputResult(options.result, { ...destination, error: error instanceof Error ? error.message : stringifyUnknown(error) }, false);
     }
 }