@abot-ai/runtime 1.3.1 → 1.4.0

package/dist/src/web-ui/local-runtime/conversation-file-access.js

@@ -0,0 +1,131 @@
+import { projectSessionRuntimePaths } from "../../runtime/projects/session-paths.js";
+import { parseToolFileOutputReceipt, } from "../../capabilities/file-output-presentation.js";
+import { ConversationFileError } from "./conversation-file-format.js";
+function unavailable() {
+    throw new ConversationFileError("conversation_file_unavailable", 404, "This file is no longer available in this conversation.");
+}
+function isReferenceId(value) {
+    if (!value || value.length > 300)
+        return false;
+    if (value.includes("/"))
+        return false;
+    if (value.includes(String.fromCharCode(92)))
+        return false;
+    return ![...value].some((character) => character.charCodeAt(0) < 32);
+}
+export function readConversationFileReference(url) {
+    const environmentId = url.searchParams.get("environment");
+    const sessionId = url.searchParams.get("sessionId");
+    const requestId = url.searchParams.get("requestId");
+    const executionId = url.searchParams.get("executionId");
+    const values = [environmentId, sessionId, requestId, executionId];
+    if (!values.every(isReferenceId))
+        throw new ConversationFileError("file_reference_invalid", 400, "The file reference is incomplete. Open it from the conversation activity.");
+    return {
+        environmentId: environmentId,
+        sessionId: sessionId,
+        requestId: requestId,
+        executionId: executionId,
+    };
+}
+function belongsToConversation(replay, reference) {
+    if (!replay)
+        return false;
+    if (replay.requestId !== reference.requestId)
+        return false;
+    return replay.sessionId === reference.sessionId;
+}
+function hasRecordedCompletion(events, reference) {
+    return events.some((event) => event.name === "tool.completed" &&
+        event.executionId === reference.executionId &&
+        event.requestId === reference.requestId);
+}
+function completedFileReceipt(events, reference) {
+    const matches = events.filter((event) => isReferencedCompletion(event, reference));
+    if (matches.length !== 1)
+        return undefined;
+    const meta = matches[0]?.meta;
+    if (!meta || typeof meta !== "object" || Array.isArray(meta))
+        return undefined;
+    return parseToolFileOutputReceipt(meta.fileOutput);
+}
+function isReferencedCompletion(event, reference) {
+    if (event.type !== "event" || event.name !== "tool.completed")
+        return false;
+    if (event.requestId !== reference.requestId)
+        return false;
+    if (event.executionId !== reference.executionId)
+        return false;
+    return event.ok === true;
+}
+function sameFileReceipt(original, current) {
+    if (!current)
+        return false;
+    return Object.entries(original).every(([key, value]) => current[key] === value);
+}
+/** The recorded completion and its request generation own every file action. */
+export class ConversationFileAccess {
+    environments;
+    requests;
+    defaultEnvironmentId;
+    constructor(environments, requests, defaultEnvironmentId) {
+        this.environments = environments;
+        this.requests = requests;
+        this.defaultEnvironmentId = defaultEnvironmentId;
+    }
+    async authorize(reference) {
+        const environment = this.resolveEnvironment(reference.environmentId);
+        const sessions = environment.services.sessions;
+        const session = await sessions.getSessionById(reference.sessionId);
+        if (!session)
+            unavailable();
+        const paths = projectSessionRuntimePaths(environment.services.config.paths, session);
+        const replay = await sessions.getRequestReplayById(reference.requestId);
+        if (!belongsToConversation(replay, reference))
+            unavailable();
+        // Late events after clear cannot recreate the explicitly started generation.
+        if (!replay.generation)
+            unavailable();
+        const wasRecorded = hasRecordedCompletion(replay.events, reference);
+        const receipt = this.fileReceipt(replay, reference, !wasRecorded);
+        if (!receipt)
+            unavailable();
+        return {
+            receipt,
+            paths,
+            assertCurrent: async () => {
+                if (this.resolveEnvironment(reference.environmentId) !== environment)
+                    unavailable();
+                const current = await sessions.getRequestReplayById(reference.requestId);
+                if (this.resolveEnvironment(reference.environmentId) !== environment)
+                    unavailable();
+                if (!belongsToConversation(current, reference))
+                    unavailable();
+                if (current.generation !== replay.generation)
+                    unavailable();
+                // A persisted completion must stay persisted; only the original gap may use live events.
+                if (!sameFileReceipt(receipt, this.fileReceipt(current, reference, !wasRecorded)))
+                    unavailable();
+            },
+        };
+    }
+    fileReceipt(replay, reference, allowActive) {
+        if (hasRecordedCompletion(replay.events, reference))
+            return completedFileReceipt(replay.events, reference);
+        if (!allowActive)
+            return undefined;
+        const active = this.requests.activeReplayForSession(reference.requestId, reference.sessionId, reference.environmentId);
+        return completedFileReceipt(active ?? [], reference);
+    }
+    resolveEnvironment(environmentId) {
+        const configured = this.environments.environmentConfig();
+        const available = configured
+            ? configured.environments.some((item) => item.id === environmentId)
+            : environmentId === this.defaultEnvironmentId();
+        if (!available)
+            unavailable();
+        if (this.environments.setupRequirement(environmentId))
+            unavailable();
+        return this.environments.get(environmentId);
+    }
+}

package/dist/src/web-ui/local-runtime/conversation-file-content.d.ts

@@ -0,0 +1,21 @@
+import type { ToolFileOutputReceipt } from "../../capabilities/file-output-presentation.js";
+import type { RuntimePaths } from "../../runtime/ports.js";
+import { type OpenedConversationFile } from "./conversation-file-target.js";
+export type ConversationFileMode = "preview" | "image" | "download";
+export type ConversationFileContent = {
+    file: {
+        name: string;
+        mimeType: string;
+        size: number;
+        kind: "text" | "image" | "unsupported";
+        operation: ToolFileOutputReceipt["operation"];
+        content?: string;
+        truncated: boolean;
+        location: string;
+        downloadAvailable: boolean;
+        nativeOpenAvailable: boolean;
+    };
+    bytes?: Buffer;
+};
+/** Reads current contents from the tool-owned root without following a replaced leaf. */
+export declare function readConversationFile(receipt: ToolFileOutputReceipt, paths: RuntimePaths, mode: ConversationFileMode, canOpenNative?: (file: OpenedConversationFile) => boolean): Promise<ConversationFileContent>;

package/dist/src/web-ui/local-runtime/conversation-file-content.js

@@ -0,0 +1,75 @@
+import { basename } from "node:path";
+import { withConversationFileTarget, } from "./conversation-file-target.js";
+import { ConversationFileError, MAX_CONVERSATION_DOWNLOAD_BYTES, MAX_CONVERSATION_IMAGE_BYTES, MAX_CONVERSATION_TEXT_BYTES, conversationFileMimeType, conversationTextPreview, rasterImageMimeType, } from "./conversation-file-format.js";
+async function readFilePrefix(handle, size) {
+    const bytes = Buffer.alloc(size);
+    let offset = 0;
+    while (offset < size) {
+        const result = await handle.read(bytes, offset, size - offset, offset);
+        if (result.bytesRead <= 0)
+            throw new ConversationFileError("conversation_file_changed", 409, "The file changed while it was being read. Open it again to see the current content.");
+        offset += result.bytesRead;
+    }
+    return bytes;
+}
+function requestedReadLimit(mode) {
+    if (mode === "download")
+        return MAX_CONVERSATION_DOWNLOAD_BYTES;
+    if (mode === "image")
+        return MAX_CONVERSATION_IMAGE_BYTES;
+    return MAX_CONVERSATION_TEXT_BYTES;
+}
+function assertBoundedContent(mode, size) {
+    if (mode === "preview")
+        return;
+    if (size <= requestedReadLimit(mode))
+        return;
+    throw new ConversationFileError("conversation_file_too_large", 413, mode === "image"
+        ? "This image is too large for an inline preview."
+        : "This file is too large to download through the Web UI. It remains on your computer.");
+}
+function previewKind(rasterMime, size, text) {
+    if (rasterMime && size <= MAX_CONVERSATION_IMAGE_BYTES)
+        return "image";
+    if (text !== undefined)
+        return "text";
+    return "unsupported";
+}
+function projectFileContent(receipt, size, bytes, mode, nativeOpenAvailable) {
+    const name = basename(receipt.relativePath);
+    const rasterMime = rasterImageMimeType(bytes);
+    const truncated = bytes.length < size;
+    const text = mode === "preview" && !rasterMime
+        ? conversationTextPreview(name, bytes, truncated)
+        : undefined;
+    const kind = previewKind(rasterMime, size, text);
+    if (mode === "image" && kind !== "image")
+        throw new ConversationFileError("conversation_file_preview_unsupported", 415, "This file type cannot be displayed as an image.");
+    const mimeType = rasterMime ??
+        (text !== undefined ? "text/plain" : conversationFileMimeType(name));
+    return {
+        file: {
+            name,
+            mimeType,
+            size,
+            kind,
+            operation: receipt.operation,
+            ...(mode === "preview" && text !== undefined ? { content: text } : {}),
+            truncated: kind === "text" && truncated,
+            location: receipt.logicalPath,
+            downloadAvailable: size <= MAX_CONVERSATION_DOWNLOAD_BYTES,
+            nativeOpenAvailable,
+        },
+        ...(mode === "preview" ? {} : { bytes }),
+    };
+}
+/** Reads current contents from the tool-owned root without following a replaced leaf. */
+export async function readConversationFile(receipt, paths, mode, canOpenNative = () => false) {
+    return withConversationFileTarget(receipt, paths, async (file) => {
+        const size = Number(file.stats.size);
+        assertBoundedContent(mode, size);
+        const bytes = await readFilePrefix(file.handle, Math.min(size, requestedReadLimit(mode)));
+        await file.assertCurrent();
+        return projectFileContent(receipt, size, bytes, mode, canOpenNative(file));
+    });
+}

package/dist/src/web-ui/local-runtime/conversation-file-format.d.ts

@@ -0,0 +1,12 @@
+export declare const MAX_CONVERSATION_TEXT_BYTES: number;
+export declare const MAX_CONVERSATION_IMAGE_BYTES: number;
+export declare const MAX_CONVERSATION_DOWNLOAD_BYTES: number;
+export declare class ConversationFileError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(code: string, statusCode: number, message: string);
+}
+export declare function rasterImageMimeType(bytes: Buffer): string | undefined;
+export declare function conversationTextPreview(name: string, bytes: Buffer, truncated: boolean): string | undefined;
+export declare function conversationFileMimeType(name: string): string;
+export declare function conversationDownloadDisposition(name: string): string;

package/dist/src/web-ui/local-runtime/conversation-file-format.js

@@ -0,0 +1,87 @@
+import { extname } from "node:path";
+export const MAX_CONVERSATION_TEXT_BYTES = 256 * 1024;
+export const MAX_CONVERSATION_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MAX_CONVERSATION_DOWNLOAD_BYTES = 64 * 1024 * 1024;
+export class ConversationFileError extends Error {
+    code;
+    statusCode;
+    constructor(code, statusCode, message) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+const BINARY_EXTENSIONS = new Set([
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".xls",
+    ".xlsx",
+    ".ppt",
+    ".pptx",
+    ".zip",
+    ".gz",
+    ".tar",
+    ".7z",
+    ".mp3",
+    ".mp4",
+    ".wav",
+    ".mov",
+    ".exe",
+    ".bin",
+    ".gif",
+    ".avif",
+    ".heic",
+    ".ico",
+]);
+export function rasterImageMimeType(bytes) {
+    if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return "image/png";
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "image/jpeg";
+    if (bytes.toString("ascii", 0, 4) !== "RIFF")
+        return undefined;
+    return bytes.toString("ascii", 8, 12) === "WEBP" ? "image/webp" : undefined;
+}
+function containsBinaryControls(bytes) {
+    return bytes.some((byte) => byte < 9 || (byte > 13 && byte < 32));
+}
+export function conversationTextPreview(name, bytes, truncated) {
+    if (BINARY_EXTENSIONS.has(extname(name).toLowerCase()))
+        return undefined;
+    if (containsBinaryControls(bytes))
+        return undefined;
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes, {
+            stream: truncated,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+export function conversationFileMimeType(name) {
+    switch (extname(name).toLowerCase()) {
+        case ".md":
+        case ".markdown":
+            return "text/markdown";
+        case ".json":
+            return "application/json";
+        case ".pdf":
+            return "application/pdf";
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".webp":
+            return "image/webp";
+        default:
+            return "application/octet-stream";
+    }
+}
+export function conversationDownloadDisposition(name) {
+    const fallback = name.replace(/[^a-zA-Z0-9._-]/gu, "_").slice(0, 180) || "file";
+    const encoded = encodeURIComponent(name).replace(/['()*]/gu, (character) => "%" + character.charCodeAt(0).toString(16).toUpperCase());
+    return ('attachment; filename="' + fallback + "\"; filename*=UTF-8''" + encoded);
+}

package/dist/src/web-ui/local-runtime/conversation-file-native-open.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage } from "node:http";
+import type { OpenedConversationFile } from "./conversation-file-target.js";
+export type ConversationNativeOpenOptions = {
+    platform?: NodeJS.Platform;
+    launch?: (absolutePath: string) => Promise<void>;
+};
+export declare function canOpenNativeConversationFile(request: IncomingMessage, file: OpenedConversationFile, platform?: NodeJS.Platform): boolean;
+/** Absolute paths are one argv entry; no shell or caller-selected command is used. */
+export declare function launchMacConversationFile(absolutePath: string): Promise<void>;
+export declare function openNativeConversationFile(file: OpenedConversationFile, assertConversationCurrent: () => Promise<void>, launch?: (absolutePath: string) => Promise<void>): Promise<void>;

package/dist/src/web-ui/local-runtime/conversation-file-native-open.js

@@ -0,0 +1,94 @@
+import { spawn } from "node:child_process";
+import { extname, isAbsolute } from "node:path";
+import { ConversationFileError } from "./conversation-file-format.js";
+import { isLocalNativeFileRequest } from "./conversation-file-native-request.js";
+// A document action must never dispatch a script, application, or active web page.
+const NATIVE_DOCUMENT_EXTENSIONS = new Set([
+    ".txt",
+    ".md",
+    ".markdown",
+    ".json",
+    ".csv",
+    ".tsv",
+    ".log",
+    ".yaml",
+    ".yml",
+    ".pdf",
+    ".rtf",
+    ".docx",
+    ".xlsx",
+    ".pptx",
+    ".odt",
+    ".ods",
+    ".odp",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".gif",
+    ".tif",
+    ".tiff",
+    ".heic",
+    ".avif",
+]);
+function isNativeDocument(file) {
+    if (!file.stats.isFile())
+        return false;
+    if ((file.stats.mode & 73n) !== 0n)
+        return false;
+    return NATIVE_DOCUMENT_EXTENSIONS.has(extname(file.target.absolutePath).toLowerCase());
+}
+export function canOpenNativeConversationFile(request, file, platform = process.platform) {
+    if (platform !== "darwin")
+        return false;
+    if (!isLocalNativeFileRequest(request))
+        return false;
+    return isNativeDocument(file);
+}
+function nativeOpenFailed() {
+    return new ConversationFileError("native_open_failed", 502, "The file could not be opened in its app. Try again from the preview.");
+}
+/** Absolute paths are one argv entry; no shell or caller-selected command is used. */
+export function launchMacConversationFile(absolutePath) {
+    if (!isAbsolute(absolutePath))
+        return Promise.reject(nativeOpenFailed());
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const child = spawn("/usr/bin/open", [absolutePath], {
+            shell: false,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        const finish = (failure) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            resolve();
+        };
+        const timeout = setTimeout(() => {
+            child.kill("SIGKILL");
+            finish(nativeOpenFailed());
+        }, 5000);
+        child.once("error", () => finish(nativeOpenFailed()));
+        child.once("exit", (code) => finish(code === 0 ? undefined : nativeOpenFailed()));
+    });
+}
+export async function openNativeConversationFile(file, assertConversationCurrent, launch = launchMacConversationFile) {
+    if (!isNativeDocument(file))
+        throw new ConversationFileError("native_open_type_unsupported", 415, "This file type can be viewed here but cannot be opened in an app from the conversation.");
+    await assertConversationCurrent();
+    file.assertCurrentForNativeOpen();
+    // The file descriptor remains held through dispatch. After dispatch, the Mac
+    // app resolves the pathname asynchronously, like a user opening it in Finder.
+    try {
+        await launch(file.target.absolutePath);
+    }
+    catch {
+        throw nativeOpenFailed();
+    }
+}

package/dist/src/web-ui/local-runtime/conversation-file-native-request.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage } from "node:http";
+/** Only a browser connected directly to this computer may offer native opening. */
+export declare function isLocalNativeFileRequest(request: IncomingMessage): boolean;
+export declare function assertNativeFileOpenRequest(request: IncomingMessage, platform: NodeJS.Platform): void;

package/dist/src/web-ui/local-runtime/conversation-file-native-request.js

@@ -0,0 +1,72 @@
+import { isIP } from "node:net";
+import { ConversationFileError } from "./conversation-file-format.js";
+function isLoopbackIp(value) {
+    if (!value)
+        return false;
+    const address = value.replace(/^\[|\]$/g, "");
+    const family = isIP(address);
+    if (family === 4)
+        return address.startsWith("127.");
+    if (family !== 6)
+        return false;
+    try {
+        const normalized = new URL("http://[" + address + "]").hostname;
+        if (normalized === "[::1]")
+            return true;
+        return /^\[::ffff:7f[0-9a-f]{2}:/.test(normalized);
+    }
+    catch {
+        // Scoped IPv6 addresses may pass isIP but are not URL hostnames.
+        return false;
+    }
+}
+function readLocalAuthority(request) {
+    if (!isLoopbackIp(request.socket.remoteAddress))
+        return undefined;
+    if (!isLoopbackIp(request.socket.localAddress))
+        return undefined;
+    const host = request.headers.host;
+    if (!host || /[\s,/\\?#@]/u.test(host))
+        return undefined;
+    const secure = "encrypted" in request.socket && request.socket.encrypted;
+    try {
+        const authority = new URL((secure ? "https://" : "http://") + host);
+        const hostname = authority.hostname.toLowerCase().replace(/\.$/, "");
+        if (hostname !== "localhost" && !isLoopbackIp(hostname))
+            return undefined;
+        const defaultPort = secure ? 443 : 80;
+        const port = authority.port ? Number(authority.port) : defaultPort;
+        if (port !== request.socket.localPort)
+            return undefined;
+        return authority;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Only a browser connected directly to this computer may offer native opening. */
+export function isLocalNativeFileRequest(request) {
+    if (request.headers["sec-fetch-site"] === "cross-site")
+        return false;
+    const authority = readLocalAuthority(request);
+    if (!authority)
+        return false;
+    const origin = request.headers.origin;
+    if (origin === undefined)
+        return true;
+    return origin === authority.origin;
+}
+function hasNativeOpenOrigin(request) {
+    if (!request.headers.origin)
+        return false;
+    return isLocalNativeFileRequest(request);
+}
+export function assertNativeFileOpenRequest(request, platform) {
+    if (platform !== "darwin")
+        throw new ConversationFileError("native_open_unavailable", 415, "Opening in an app is available on this Mac only.");
+    if (!hasNativeOpenOrigin(request))
+        throw new ConversationFileError("native_open_request_rejected", 403, "Open files from the Web UI on this computer.");
+    const contentType = request.headers["content-type"] ?? "";
+    if (contentType.split(";", 1)[0].trim().toLowerCase() !== "application/json")
+        throw new ConversationFileError("native_open_request_rejected", 415, "Opening a file requires a JSON request.");
+}

package/dist/src/web-ui/local-runtime/conversation-file-routes.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RuntimeEnvironmentRegistry } from "./environment-registry.js";
+import type { LocalRequestExecution } from "./request-execution.js";
+import { type ConversationNativeOpenOptions } from "./conversation-file-native-open.js";
+/** A recorded tool completion is the only authority; no browser path is accepted. */
+export declare class ConversationFileRoutes {
+    private readonly nativeOpen;
+    private readonly access;
+    constructor(environments: Pick<RuntimeEnvironmentRegistry, "environmentConfig" | "setupRequirement" | "get">, requests: LocalRequestExecution, defaultEnvironmentId: () => string, nativeOpen?: ConversationNativeOpenOptions);
+    handle(route: string, request: IncomingMessage, response: ServerResponse): Promise<boolean>;
+}

package/dist/src/web-ui/local-runtime/conversation-file-routes.js

@@ -0,0 +1,105 @@
+import { ConversationFileAccess, readConversationFileReference, } from "./conversation-file-access.js";
+import { readConversationFile, } from "./conversation-file-content.js";
+import { ConversationFileError, conversationDownloadDisposition, } from "./conversation-file-format.js";
+import { assertNativeFileOpenRequest } from "./conversation-file-native-request.js";
+import { canOpenNativeConversationFile, openNativeConversationFile, } from "./conversation-file-native-open.js";
+import { withConversationFileTarget } from "./conversation-file-target.js";
+import { readBody, readJsonBody, sendJson } from "./http.js";
+function hasSameOrigin(request) {
+    if (request.headers["sec-fetch-site"] === "cross-site")
+        return false;
+    const origin = request.headers.origin;
+    if (!origin)
+        return true;
+    try {
+        const secure = "encrypted" in request.socket && request.socket.encrypted;
+        const expected = (secure ? "https://" : "http://") + request.headers.host;
+        return new URL(origin).origin === expected;
+    }
+    catch {
+        return false;
+    }
+}
+function assertFileRequestOrigin(request) {
+    if (hasSameOrigin(request))
+        return;
+    throw new ConversationFileError("file_request_rejected", 403, "Files can only be opened from this Web UI.");
+}
+function contentMode(url) {
+    if (url.searchParams.get("download") === "1")
+        return "download";
+    if (url.searchParams.get("content") === "1")
+        return "image";
+    return "preview";
+}
+async function assertEmptyNativeOpenBody(request) {
+    try {
+        const body = readJsonBody(await readBody(request, { maxBytes: 1024 }));
+        if (Object.keys(body).length === 0)
+            return;
+    }
+    catch {
+        // The only file authority is the conversation reference in the URL.
+    }
+    throw new ConversationFileError("file_reference_invalid", 400, "Open this file from the conversation preview.");
+}
+/** A recorded tool completion is the only authority; no browser path is accepted. */
+export class ConversationFileRoutes {
+    nativeOpen;
+    access;
+    constructor(environments, requests, defaultEnvironmentId, nativeOpen = {}) {
+        this.nativeOpen = nativeOpen;
+        this.access = new ConversationFileAccess(environments, requests, defaultEnvironmentId);
+    }
+    async handle(route, request, response) {
+        const isPreviewRead = route === "chat/files" && request.method === "GET";
+        const isNativeOpen = route === "chat/files/open" && request.method === "POST";
+        if (!isPreviewRead && !isNativeOpen)
+            return false;
+        response.setHeader("cache-control", "private, no-store");
+        response.setHeader("x-content-type-options", "nosniff");
+        response.setHeader("cross-origin-resource-policy", "same-origin");
+        response.setHeader("content-security-policy", "default-src 'none'; sandbox");
+        try {
+            assertFileRequestOrigin(request);
+            const platform = this.nativeOpen.platform ?? process.platform;
+            if (isNativeOpen) {
+                assertNativeFileOpenRequest(request, platform);
+                await assertEmptyNativeOpenBody(request);
+            }
+            const url = new URL(request.url || "/", "http://localhost");
+            const reference = readConversationFileReference(url);
+            const authority = await this.access.authorize(reference);
+            if (isNativeOpen) {
+                await withConversationFileTarget(authority.receipt, authority.paths, (file) => openNativeConversationFile(file, authority.assertCurrent, this.nativeOpen.launch));
+                sendJson(response, 200, { ok: true });
+                return true;
+            }
+            const mode = contentMode(url);
+            const result = await readConversationFile(authority.receipt, authority.paths, mode, (file) => canOpenNativeConversationFile(request, file, platform));
+            await authority.assertCurrent();
+            if (mode === "preview") {
+                sendJson(response, 200, { ok: true, file: result.file });
+                return true;
+            }
+            const bytes = result.bytes;
+            response.setHeader("content-length", String(bytes.byteLength));
+            response.setHeader("content-type", mode === "image" ? result.file.mimeType : "application/octet-stream");
+            if (mode === "download")
+                response.setHeader("content-disposition", conversationDownloadDisposition(result.file.name));
+            response.writeHead(200);
+            response.end(bytes);
+        }
+        catch (error) {
+            const failure = error instanceof ConversationFileError
+                ? error
+                : new ConversationFileError("conversation_file_unavailable", 404, "This file is no longer available in this conversation.");
+            sendJson(response, failure.statusCode, {
+                ok: false,
+                error: failure.code,
+                message: failure.message,
+            });
+        }
+        return true;
+    }
+}

package/dist/src/web-ui/local-runtime/conversation-file-target.d.ts

@@ -0,0 +1,14 @@
+import { type BigIntStats } from "node:fs";
+import { type FileHandle } from "node:fs/promises";
+import type { ToolFileOutputReceipt } from "../../capabilities/file-output-presentation.js";
+import type { ResolvedRuntimeToolPath } from "../../capabilities/tool-types.js";
+import type { RuntimePaths } from "../../runtime/ports.js";
+export type OpenedConversationFile = {
+    target: ResolvedRuntimeToolPath;
+    handle: FileHandle;
+    stats: BigIntStats;
+    assertCurrent: () => Promise<void>;
+    assertCurrentForNativeOpen: () => void;
+};
+/** Keeps the recorded file descriptor alive for the complete caller operation. */
+export declare function withConversationFileTarget<T>(receipt: ToolFileOutputReceipt, paths: RuntimePaths, action: (file: OpenedConversationFile) => Promise<T>): Promise<T>;