@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/web-ui/local-runtime/configuration-activation.js

@@ -0,0 +1,107 @@
+import { closeIdleEnvironments, closeReplacementEnvironments, requireActivationIntakeOpen, settleExistingEnvironments, startReplacementEnvironments, } from "./configuration-activation-environments.js";
+function blockedActivation(message) {
+    return { status: "restart_required", message };
+}
+function ownerActivationBlock(current) {
+    const hasExternalOwner = current.some(([, environment]) => environment.getOwnership() !== "owner");
+    if (hasExternalOwner) {
+        return blockedActivation("Another process owns this runtime. Changes are saved and will apply when that process restarts.");
+    }
+    const hasBusyOwner = current.some(([, environment]) => !environment.isOwnerIdle());
+    if (hasBusyOwner) {
+        return blockedActivation("Your agent is working. Wait for active conversations and Jobs to finish, then apply again.");
+    }
+    return undefined;
+}
+function desiredEnvironmentIds(options) {
+    const ids = new Set(options.environmentIds ?? options.environments.keys());
+    if (ids.size === 0)
+        ids.add(options.defaultEnvironmentId);
+    return [...ids];
+}
+/** Idle admission is checked at the owning host, never from a browser activity list. */
+export async function applyRuntimeConfiguration(options) {
+    requireActivationIntakeOpen(options);
+    const ids = desiredEnvironmentIds(options);
+    const current = await settleExistingEnvironments(options);
+    const initialBlock = ownerActivationBlock(current);
+    if (initialBlock)
+        return initialBlock;
+    options.prepareConfiguration?.();
+    const gatewayCheck = await options.checkGateway?.();
+    requireActivationIntakeOpen(options);
+    if (gatewayCheck?.status === "restart_required")
+        return gatewayCheck;
+    // Config parsing is synchronous and cannot alter owner intake.
+    const replacements = ids.map((id) => [id, options.createEnvironment(id)]);
+    const finalBlock = ownerActivationBlock(current);
+    if (finalBlock)
+        return finalBlock;
+    const gatewayRestorePoint = options.createGatewayRestorePoint?.();
+    const shutdown = await closeIdleEnvironments(options, current);
+    if (shutdown.status === "failed") {
+        await restoreAfterIdleShutdownFailure(options, shutdown);
+        throw shutdown.error;
+    }
+    let activation;
+    try {
+        requireActivationIntakeOpen(options);
+        activation = await options.activateGateway();
+        requireActivationIntakeOpen(options);
+        if (isRuntimeActivationReady(activation))
+            await startReplacementEnvironments(options, replacements);
+    }
+    catch (error) {
+        await restoreConfigurationAfterFailure(options, current, gatewayRestorePoint, error);
+        throw error;
+    }
+    if (!isRuntimeActivationReady(activation)) {
+        await restoreConfigurationAfterFailure(options, current, gatewayRestorePoint, new Error(activation.message ?? "Runtime configuration was not activated."));
+    }
+    return activation;
+}
+async function restoreAfterIdleShutdownFailure(options, shutdown) {
+    if (isActivationStopped(options))
+        return;
+    // A rejected close does not prove that the previous owner's lease was released.
+    if (shutdown.hasUncertainOwners)
+        options.onRestorationFailure?.();
+    try {
+        options.restoreConfiguration?.();
+        const restored = shutdown.closed.map(([id, environment]) => [id, options.recreateEnvironment(id, environment)]);
+        await startReplacementEnvironments(options, restored);
+    }
+    catch (restorationError) {
+        if (isActivationStopped(options))
+            return;
+        options.onRestorationFailure?.();
+        throw new AggregateError([shutdown.error, restorationError], "Idle runtime shutdown failed and closed environments could not be restored.");
+    }
+}
+async function restoreConfigurationAfterFailure(options, previous, gateway, activationError) {
+    if (isActivationStopped(options))
+        return;
+    try {
+        await closeReplacementEnvironments(options, previous);
+        if (isActivationStopped(options))
+            return;
+        options.restoreConfiguration?.();
+        await gateway?.restore();
+        if (isActivationStopped(options))
+            return;
+        const restored = previous.map(([id, environment]) => [id, options.recreateEnvironment(id, environment)]);
+        await startReplacementEnvironments(options, restored);
+    }
+    catch (restorationError) {
+        if (isActivationStopped(options))
+            return;
+        options.onRestorationFailure?.();
+        throw new AggregateError([activationError, restorationError], "Configuration activation failed and the previous runtime could not be restored.");
+    }
+}
+function isActivationStopped(options) {
+    return options.canContinue?.() === false;
+}
+function isRuntimeActivationReady(activation) {
+    return activation.status === "ready";
+}

package/dist/src/web-ui/local-runtime/contracts.d.ts

@@ -1,3 +1,6 @@
+import type { RuntimeSetupGatewayRestorePoint } from "../runtime-setup-gateway.js";
+import type { WebUiEnvironmentConfig } from "../environment-config.js";
+import type { RuntimeSetupActivation } from "./runtime-setup-input.js";
 import type { LocalRuntimeApplication } from "../../runtime/local-application.js";
 import type { RequestSteeringInbox } from "../../runtime/request/request-steering.js";
 import type { ModelProviderAdapterRegistry } from "../../model-gateway/index.js";
@@ -6,7 +9,11 @@ export type LocalRuntimeBackendOptions = {
     rootDir?: string;
     configPath?: string;
     defaultEnvironmentId: string;
+    resolveEnvironmentConfig?: (configPath?: string) => WebUiEnvironmentConfig;
     providerAdapters?: ModelProviderAdapterRegistry;
+    onRuntimeSetup?: (configPath: string) => Promise<RuntimeSetupActivation>;
+    createRuntimeSetupRestorePoint?: () => RuntimeSetupGatewayRestorePoint;
+    checkRuntimeSetupActivation?: (configPath: string) => Promise<RuntimeSetupActivation>;
 };
 export type ResolvedLocalRuntimeBackendOptions = Omit<LocalRuntimeBackendOptions, "providerAdapters"> & {
     providerAdapters: ModelProviderAdapterRegistry;
@@ -16,6 +23,7 @@ export type RuntimeSetupRequirement = {
     status: "setup_required";
     code: "runtime_configuration_required";
     message: string;
+    recovery?: "configuration";
 };
 export type RuntimeAvailability = {
     status: "ready";

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

@@ -0,0 +1,30 @@
+import type { RuntimeEnvironmentRegistry } from "./environment-registry.js";
+import type { LocalRequestExecution } from "./request-execution.js";
+export type ConversationFileReference = {
+    environmentId: string;
+    sessionId: string;
+    requestId: string;
+    executionId: string;
+};
+export declare function readConversationFileReference(url: URL): ConversationFileReference;
+/** The recorded completion and its request generation own every file action. */
+export declare class ConversationFileAccess {
+    private readonly environments;
+    private readonly requests;
+    private readonly defaultEnvironmentId;
+    constructor(environments: Pick<RuntimeEnvironmentRegistry, "environmentConfig" | "setupRequirement" | "get">, requests: LocalRequestExecution, defaultEnvironmentId: () => string);
+    authorize(reference: ConversationFileReference): Promise<{
+        receipt: Readonly<{
+            version: 1;
+            location: import("../../capabilities/file-output-presentation.js").ToolFileOutputLocation;
+            rootId: string;
+            relativePath: string;
+            logicalPath: string;
+            operation: import("../../capabilities/file-output-presentation.js").ToolFileOutputOperation;
+        }>;
+        paths: import("../../runtime/ports.js").RuntimePaths;
+        assertCurrent: () => Promise<void>;
+    }>;
+    private fileReceipt;
+    private resolveEnvironment;
+}

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;