@steipete/oracle 0.15.0 → 0.15.2

package/dist/src/remote/client.js

@@ -1,6 +1,11 @@
 import http from "node:http";
+import { createWriteStream } from "node:fs";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import path from "node:path";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat } from "node:fs/promises";
+import { appendArtifacts, computeFileSha256, resolveSessionArtifactsDir, resolveUniqueArtifactPath, sanitizeArtifactFilename, sanitizeArtifactMimeType, validateArtifactFile, } from "../browser/artifacts.js";
+import { MAX_REMOTE_ARTIFACT_BYTES, } from "./types.js";
 import { parseHostPort } from "../bridge/connection.js";
 export function createRemoteBrowserExecutor({ host, token }) {
     // Return a drop-in replacement for runBrowserMode so the browser session runner can stay unchanged.
@@ -25,6 +30,18 @@ export function createRemoteBrowserExecutor({ host, token }) {
         const body = Buffer.from(JSON.stringify(payload));
         const { hostname, port } = parseHost(host);
         return new Promise((resolve, reject) => {
+            const transferredFiles = [];
+            const transferFailures = [];
+            const transferPromises = [];
+            let artifactTransferQueue = Promise.resolve();
+            let settled = false;
+            let resolved = null;
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(error);
+            };
             const req = http.request({
                 hostname,
                 port,
@@ -38,13 +55,12 @@ export function createRemoteBrowserExecutor({ host, token }) {
             }, (res) => {
                 if (res.statusCode !== 200) {
                     collectError(res)
-                        .then((message) => reject(new Error(message)))
-                        .catch(reject);
+                        .then((message) => fail(new Error(message)))
+                        .catch(fail);
                     return;
                 }
                 res.setEncoding("utf8");
                 let buffer = "";
-                let resolved = null;
                 res.on("data", (chunk) => {
                     buffer += chunk;
                     let newlineIndex = buffer.indexOf("\n");
@@ -52,22 +68,51 @@ export function createRemoteBrowserExecutor({ host, token }) {
                         const line = buffer.slice(0, newlineIndex).trim();
                         buffer = buffer.slice(newlineIndex + 1);
                         if (line.length > 0) {
-                            handleEvent(line, options, (result) => {
-                                resolved = result;
-                            }, reject);
+                            const transferPromise = handleEvent({
+                                line,
+                                options,
+                                hostname,
+                                port,
+                                token,
+                                onResult: (result) => {
+                                    resolved = result;
+                                },
+                                onArtifact: (artifact) => {
+                                    transferredFiles.push(artifact);
+                                },
+                                onArtifactFailure: (message) => {
+                                    transferFailures.push(message);
+                                },
+                                enqueueArtifactTransfer: (transfer) => {
+                                    const queued = artifactTransferQueue.then(transfer);
+                                    artifactTransferQueue = queued.catch(() => undefined);
+                                    return queued;
+                                },
+                                onError: fail,
+                            });
+                            if (transferPromise) {
+                                transferPromises.push(transferPromise);
+                            }
                         }
                         newlineIndex = buffer.indexOf("\n");
                     }
                 });
                 res.on("end", () => {
-                    if (resolved) {
-                        resolve(resolved);
-                        return;
-                    }
-                    reject(new Error("Remote browser run completed without a result."));
+                    void (async () => {
+                        await Promise.allSettled(transferPromises);
+                        if (settled)
+                            return;
+                        if (!resolved) {
+                            fail(new Error("Remote browser run completed without a result."));
+                            return;
+                        }
+                        settled = true;
+                        resolve(mergeTransferredArtifacts(resolved, transferredFiles, transferFailures));
+                    })().catch(fail);
                 });
+                res.on("error", fail);
             });
-            req.on("error", reject);
+            req.on("error", fail);
             req.write(body);
             req.end();
         });
@@ -95,26 +140,212 @@ function parseHost(input) {
         throw new Error(`Invalid remote host: ${input} (${error instanceof Error ? error.message : String(error)})`);
     }
 }
-function handleEvent(line, options, onResult, onError) {
+function handleEvent(params) {
     let event;
     try {
-        event = JSON.parse(line);
+        event = JSON.parse(params.line);
     }
     catch (error) {
-        onError(new Error(`Failed to parse remote event: ${error instanceof Error ? error.message : String(error)}`));
-        return;
+        params.onError(new Error(`Failed to parse remote event: ${error instanceof Error ? error.message : String(error)}`));
+        return null;
     }
     if (event.type === "log") {
-        options.log?.(event.message);
-        return;
+        params.options.log?.(event.message);
+        return null;
     }
     if (event.type === "error") {
-        onError(new Error(event.message));
-        return;
+        params.onError(new Error(event.message));
+        return null;
+    }
+    if (event.type === "artifact-progress") {
+        if (params.options.verbose) {
+            params.options.log?.(`[browser] Artifact ${event.artifactId} ${event.phase}${event.receivedBytes !== undefined && event.totalBytes !== undefined
+                ? ` ${event.receivedBytes}/${event.totalBytes} bytes`
+                : ""}`);
+        }
+        return null;
+    }
+    if (event.type === "artifact-ready") {
+        const displayFilename = sanitizeArtifactFilename(String(event.artifact?.filename ?? ""), "artifact.bin");
+        const transfer = params.enqueueArtifactTransfer(() => transferRemoteArtifact({
+            hostname: params.hostname,
+            port: params.port,
+            token: params.token,
+            descriptor: event.artifact,
+            sessionId: params.options.sessionId,
+            log: params.options.log,
+        })
+            .then((artifact) => {
+            params.onArtifact(artifact);
+        })
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            const fallback = `Oracle captured the browser text response, but bridge artifact transfer failed for ${displayFilename}. Open the ChatGPT browser on the bridge host, download the ZIP/file shown in the current response, and copy it to a cloud-readable path. Reason: ${message}`;
+            params.options.log?.(`[browser] ${fallback}`);
+            params.onArtifactFailure(fallback);
+        }));
+        return transfer;
     }
     if (event.type === "result") {
-        onResult(event.result);
+        params.onResult(event.result);
+    }
+    return null;
+}
+async function transferRemoteArtifact(params) {
+    validateRemoteArtifactDescriptor(params.descriptor);
+    const sessionId = params.sessionId ?? params.descriptor.runId;
+    const artifactsDir = resolveSessionArtifactsDir(sessionId);
+    await mkdir(artifactsDir, { recursive: true });
+    const filename = sanitizeArtifactFilename(params.descriptor.filename, `artifact-${params.descriptor.artifactId}.bin`);
+    const finalPath = await resolveUniqueArtifactPath(path.join(artifactsDir, filename));
+    const partPath = `${finalPath}.part-${params.descriptor.artifactId}`;
+    const artifactPath = `/runs/${encodeURIComponent(params.descriptor.runId)}/artifacts/${encodeURIComponent(params.descriptor.artifactId)}`;
+    params.log?.(`[browser] Transferring artifact ${filename} from bridge host...`);
+    await downloadArtifactToFile({
+        hostname: params.hostname,
+        port: params.port,
+        path: artifactPath,
+        token: params.token,
+        targetPath: partPath,
+        descriptor: params.descriptor,
+    }).catch(async (error) => {
+        await rm(partPath, { force: true }).catch(() => undefined);
+        throw error;
+    });
+    const fileStat = await stat(partPath);
+    if (fileStat.size !== params.descriptor.byteSize) {
+        await rm(partPath, { force: true }).catch(() => undefined);
+        throw new Error(`size mismatch (${fileStat.size} != ${params.descriptor.byteSize})`);
+    }
+    const sha256 = await computeFileSha256(partPath);
+    if (sha256 !== params.descriptor.sha256) {
+        await rm(partPath, { force: true }).catch(() => undefined);
+        throw new Error("sha256 mismatch");
+    }
+    const validation = await validateArtifactFile({
+        path: partPath,
+        filename,
+        mimeType: sanitizeArtifactMimeType(params.descriptor.mimeType),
+    });
+    if (!validation.ok) {
+        await rm(partPath, { force: true }).catch(() => undefined);
+        throw new Error(`${validation.type} validation failed: ${validation.error ?? "invalid"}`);
+    }
+    await rename(partPath, finalPath);
+    params.log?.(`[browser] Transferred artifact to ${finalPath}`);
+    const publishedFilename = path.basename(finalPath);
+    return {
+        kind: "file",
+        path: finalPath,
+        label: publishedFilename,
+        mimeType: sanitizeArtifactMimeType(params.descriptor.mimeType),
+        sizeBytes: fileStat.size,
+        sourceUrl: "bridge-artifact",
+        sha256,
+        validation,
+        transfer: { status: "completed", bytes: fileStat.size },
+        origin: { mode: "bridge" },
+        url: "bridge-artifact",
+        finalUrl: "bridge-artifact",
+        filename: publishedFilename,
+    };
+}
+async function downloadArtifactToFile(params) {
+    await new Promise((resolve, reject) => {
+        const req = http.request({
+            hostname: params.hostname,
+            port: params.port,
+            path: params.path,
+            method: "GET",
+            headers: params.token ? { authorization: `Bearer ${params.token}` } : undefined,
+        }, (res) => {
+            if (res.statusCode !== 200) {
+                collectError(res)
+                    .then((message) => reject(new Error(message)))
+                    .catch(reject);
+                return;
+            }
+            const headerSha = String(res.headers["x-oracle-artifact-sha256"] ?? "");
+            if (headerSha && headerSha !== params.descriptor.sha256) {
+                res.resume();
+                reject(new Error("artifact sha256 header mismatch"));
+                return;
+            }
+            const contentLengthHeader = res.headers["content-length"];
+            const contentLength = typeof contentLengthHeader === "string" ? Number(contentLengthHeader) : undefined;
+            if (contentLength !== undefined &&
+                (!Number.isSafeInteger(contentLength) ||
+                    contentLength <= 0 ||
+                    contentLength > MAX_REMOTE_ARTIFACT_BYTES ||
+                    contentLength !== params.descriptor.byteSize)) {
+                res.resume();
+                reject(new Error("artifact content-length mismatch"));
+                return;
+            }
+            const output = createWriteStream(params.targetPath, { flags: "wx" });
+            let receivedBytes = 0;
+            const limiter = new Transform({
+                transform(chunk, _encoding, callback) {
+                    receivedBytes += chunk.length;
+                    if (receivedBytes > params.descriptor.byteSize ||
+                        receivedBytes > MAX_REMOTE_ARTIFACT_BYTES) {
+                        callback(new Error("artifact exceeded declared size"));
+                        return;
+                    }
+                    callback(null, chunk);
+                },
+            });
+            void pipeline(res, limiter, output).then(() => resolve(), reject);
+        });
+        req.on("error", reject);
+        req.end();
+    });
+}
+function validateRemoteArtifactDescriptor(descriptor) {
+    if (!descriptor ||
+        typeof descriptor !== "object" ||
+        descriptor.kind !== "file" ||
+        typeof descriptor.runId !== "string" ||
+        !/^[a-zA-Z0-9_-]{1,128}$/.test(descriptor.runId) ||
+        typeof descriptor.artifactId !== "string" ||
+        !/^[a-zA-Z0-9_-]{1,128}$/.test(descriptor.artifactId) ||
+        typeof descriptor.filename !== "string" ||
+        !Number.isSafeInteger(descriptor.byteSize) ||
+        descriptor.byteSize <= 0 ||
+        descriptor.byteSize > MAX_REMOTE_ARTIFACT_BYTES ||
+        typeof descriptor.sha256 !== "string" ||
+        !/^[a-f0-9]{64}$/.test(descriptor.sha256)) {
+        throw new Error("invalid bridge artifact descriptor");
+    }
+}
+function mergeTransferredArtifacts(result, transferredFiles, transferFailures) {
+    const artifacts = appendArtifacts(result.artifacts, transferredFiles);
+    const savedFiles = appendSavedFiles(result.savedFiles, transferredFiles);
+    const warnings = [
+        ...(result.warnings ?? []),
+        ...transferFailures.map((message) => ({
+            code: "remote-artifact-transfer-failed",
+            severity: "warning",
+            message,
+        })),
+    ];
+    return {
+        ...result,
+        artifacts,
+        savedFiles,
+        warnings: warnings.length > 0 ? warnings : undefined,
+    };
+}
+function appendSavedFiles(existing, additions) {
+    const merged = new Map();
+    for (const artifact of existing ?? []) {
+        merged.set(artifact.path, artifact);
+    }
+    for (const artifact of additions) {
+        merged.set(artifact.path, artifact);
     }
+    const values = Array.from(merged.values());
+    return values.length > 0 ? values : undefined;
 }
 function collectError(res) {
     return new Promise((resolve, reject) => {

package/dist/src/remote/health.js

@@ -1,6 +1,7 @@
 import http from "node:http";
 import net from "node:net";
 import { parseHostPort } from "../bridge/connection.js";
+import { MAX_REMOTE_ARTIFACT_BYTES } from "./types.js";
 export async function checkTcpConnection(host, timeoutMs = 2000) {
     const { hostname, port } = parseHostPort(host);
     return await new Promise((resolve) => {
@@ -47,11 +48,13 @@ export async function checkRemoteHealth({ host, token, timeoutMs = 5000, }) {
             const ok = response.json.ok === true;
             const version = response.json.version;
             const uptimeSeconds = response.json.uptimeSeconds;
+            const capabilities = parseCapabilities(response.json.capabilities);
             return {
                 ok,
                 statusCode: response.statusCode,
                 version: typeof version === "string" ? version : undefined,
                 uptimeSeconds: typeof uptimeSeconds === "number" ? uptimeSeconds : undefined,
+                capabilities,
             };
         }
         if (response.statusCode === 404) {
@@ -68,6 +71,30 @@ export async function checkRemoteHealth({ host, token, timeoutMs = 5000, }) {
         return { ok: false, error: error instanceof Error ? error.message : String(error) };
     }
 }
+function parseCapabilities(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const raw = value;
+    if (raw.artifactTransfer !== true) {
+        return undefined;
+    }
+    const artifactProtocolVersion = raw.artifactProtocolVersion;
+    const maxArtifactBytes = raw.maxArtifactBytes;
+    if (typeof artifactProtocolVersion !== "number" ||
+        !Number.isSafeInteger(artifactProtocolVersion) ||
+        artifactProtocolVersion <= 0 ||
+        typeof maxArtifactBytes !== "number" ||
+        !Number.isSafeInteger(maxArtifactBytes) ||
+        maxArtifactBytes <= 0) {
+        return undefined;
+    }
+    return {
+        artifactTransfer: true,
+        artifactProtocolVersion,
+        maxArtifactBytes: Math.min(maxArtifactBytes, MAX_REMOTE_ARTIFACT_BYTES),
+    };
+}
 function extractErrorMessage(json, bodyText) {
     if (json && typeof json === "object") {
         const err = json.error;

package/dist/src/remote/server.js

@@ -1,17 +1,29 @@
 import http from "node:http";
+import { createReadStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
 import os from "node:os";
 import path from "node:path";
 import net from "node:net";
 import { randomBytes, randomUUID } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
-import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, mkdir, writeFile, stat, realpath } from "node:fs/promises";
 import chalk from "chalk";
 import { runBrowserMode } from "../browserMode.js";
+import { MAX_REMOTE_ARTIFACT_BYTES } from "./types.js";
 import { getCookies } from "@steipete/sweet-cookie";
 import { CHATGPT_URL } from "../browser/constants.js";
 import { getCliVersion } from "../version.js";
+import { getOracleHomeDir } from "../oracleHome.js";
 import { cleanupStaleProfileState, readDevToolsPort, verifyDevToolsReachable, writeChromePid, writeDevToolsActivePort, } from "../browser/profileState.js";
 import { normalizeChatgptUrl } from "../browser/utils.js";
+import { computeFileSha256, sanitizeArtifactFilename, sanitizeArtifactMimeType, validateArtifactFile, } from "../browser/artifacts.js";
+const ARTIFACT_PROTOCOL_VERSION = 1;
+const REMOTE_ARTIFACT_TTL_MS = 30 * 60 * 1000;
+const ARTIFACT_CAPABILITIES = {
+    artifactTransfer: true,
+    artifactProtocolVersion: ARTIFACT_PROTOCOL_VERSION,
+    maxArtifactBytes: MAX_REMOTE_ARTIFACT_BYTES,
+};
 async function findAvailablePort() {
     return await new Promise((resolve, reject) => {
         const srv = net.createServer();
@@ -40,6 +52,7 @@ export async function createRemoteServer(options = {}, deps = {}) {
         : (_formatter, msg) => msg;
     // Single-flight guard: remote Chrome can only host one run at a time, so we serialize requests.
     let busy = false;
+    const artifactRegistry = new Map();
     if (!process.listenerCount("unhandledRejection")) {
         process.on("unhandledRejection", (reason) => {
             logger(`Unhandled promise rejection in remote server: ${reason instanceof Error ? reason.message : String(reason)}`);
@@ -67,9 +80,24 @@ export async function createRemoteServer(options = {}, deps = {}) {
                 ok: true,
                 version: getCliVersion(),
                 uptimeSeconds: Math.round((Date.now() - startedAt) / 1000),
+                capabilities: ARTIFACT_CAPABILITIES,
             }));
             return;
         }
+        const artifactMatch = matchArtifactRequest(req);
+        if (artifactMatch) {
+            await serveRemoteArtifact({
+                req,
+                res,
+                authToken,
+                artifactRegistry,
+                logger,
+                verbose,
+                runId: artifactMatch.runId,
+                artifactId: artifactMatch.artifactId,
+            });
+            return;
+        }
         if (req.method !== "POST" || req.url !== "/runs") {
             res.statusCode = 404;
             res.end();
@@ -190,8 +218,30 @@ export async function createRemoteServer(options = {}, deps = {}) {
                 sessionId: payload.options.sessionId,
                 followUpPrompts: payload.options.followUpPrompts,
             });
-            sendEvent({ type: "result", result: sanitizeResult(result) });
-            logger(`[serve] Run ${runId} completed in ${Date.now() - runStartedAt}ms`);
+            const artifactRegistration = await registerRemoteArtifacts({
+                runId,
+                result,
+                artifactRegistry,
+                logger,
+            });
+            const artifactDescriptors = artifactRegistration.descriptors;
+            if (artifactDescriptors.length > 0) {
+                sendEvent({
+                    type: "log",
+                    message: `[browser] ${artifactDescriptors.length} artifact(s) ready for bridge transfer. ` +
+                        "If no cloud-local artifact path appears, upgrade both Oracle bridge endpoints or copy the file manually from the Windows browser host.",
+                });
+            }
+            for (const artifact of artifactDescriptors) {
+                sendEvent({ type: "artifact-ready", runId, artifact });
+            }
+            sendEvent({
+                type: "result",
+                result: sanitizeResult(result, artifactRegistration.warnings),
+            });
+            logger(`[serve] Run ${runId} completed in ${Date.now() - runStartedAt}ms${artifactDescriptors.length > 0
+                ? `; ${artifactDescriptors.length} artifact(s) ready for bridge transfer`
+                : ""}`);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -303,6 +353,190 @@ export async function serveRemote(options = {}) {
         process.on("SIGTERM", shutdown);
     });
 }
+function matchArtifactRequest(req) {
+    if (req.method !== "GET" || !req.url) {
+        return null;
+    }
+    let url;
+    try {
+        url = new URL(req.url, "http://oracle.local");
+    }
+    catch {
+        return null;
+    }
+    const match = /^\/runs\/([^/]+)\/artifacts\/([^/]+)$/.exec(url.pathname);
+    if (!match) {
+        return null;
+    }
+    try {
+        return {
+            runId: decodeURIComponent(match[1] ?? ""),
+            artifactId: decodeURIComponent(match[2] ?? ""),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function serveRemoteArtifact(params) {
+    const authHeader = params.req.headers.authorization ?? "";
+    if (authHeader !== `Bearer ${params.authToken}`) {
+        if (params.verbose) {
+            params.logger(`[serve] Unauthorized artifact transfer attempt from ${formatSocket(params.req)} (missing/invalid token)`);
+        }
+        params.res.writeHead(401, { "Content-Type": "application/json" });
+        params.res.end(JSON.stringify({ error: "unauthorized" }));
+        return;
+    }
+    pruneExpiredArtifacts(params.artifactRegistry);
+    const key = remoteArtifactKey(params.runId, params.artifactId);
+    const artifact = params.artifactRegistry.get(key);
+    if (!artifact) {
+        params.res.writeHead(404, { "Content-Type": "application/json" });
+        params.res.end(JSON.stringify({ error: "artifact_not_found" }));
+        return;
+    }
+    if (Date.now() > artifact.expiresAt) {
+        params.artifactRegistry.delete(key);
+        params.res.writeHead(410, { "Content-Type": "application/json" });
+        params.res.end(JSON.stringify({ error: "artifact_expired" }));
+        return;
+    }
+    const fileStat = await stat(artifact.filePath).catch(() => null);
+    if (!fileStat?.isFile() || fileStat.size <= 0) {
+        params.res.writeHead(410, { "Content-Type": "application/json" });
+        params.res.end(JSON.stringify({ error: "artifact_unavailable" }));
+        return;
+    }
+    if (fileStat.size > MAX_REMOTE_ARTIFACT_BYTES) {
+        params.res.writeHead(413, { "Content-Type": "application/json" });
+        params.res.end(JSON.stringify({ error: "artifact_too_large" }));
+        return;
+    }
+    const filename = sanitizeArtifactFilename(artifact.descriptor.filename, "artifact.bin");
+    params.res.writeHead(200, {
+        "Content-Type": sanitizeArtifactMimeType(artifact.descriptor.mimeType) ?? "application/octet-stream",
+        "Content-Length": fileStat.size,
+        "Content-Disposition": `attachment; filename="${filename.replace(/"/g, "")}"`,
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+        "X-Oracle-Artifact-Id": artifact.descriptor.artifactId,
+        "X-Oracle-Artifact-Sha256": artifact.descriptor.sha256,
+    });
+    await pipeline(createReadStream(artifact.filePath), params.res).catch((error) => {
+        params.logger(`[serve] Artifact transfer failed for ${artifact.descriptor.artifactId}: ${error instanceof Error ? error.message : String(error)}`);
+    });
+}
+function pruneExpiredArtifacts(artifactRegistry) {
+    const now = Date.now();
+    for (const [key, artifact] of artifactRegistry) {
+        if (artifact.expiresAt <= now) {
+            artifactRegistry.delete(key);
+        }
+    }
+}
+function remoteArtifactKey(runId, artifactId) {
+    return `${runId}:${artifactId}`;
+}
+async function registerRemoteArtifacts(params) {
+    pruneExpiredArtifacts(params.artifactRegistry);
+    const seen = new Set();
+    const fileArtifacts = [
+        ...(params.result.savedFiles ?? []),
+        ...(params.result.artifacts ?? []).filter((artifact) => artifact.kind === "file"),
+    ];
+    const descriptors = [];
+    const warnings = [];
+    for (const artifact of fileArtifacts) {
+        if (!artifact?.path || seen.has(artifact.path)) {
+            continue;
+        }
+        seen.add(artifact.path);
+        const registration = await buildRemoteArtifactRegistration(params.runId, artifact).catch((error) => {
+            const filename = sanitizeArtifactFilename(path.basename(artifact.path), "artifact.bin");
+            params.logger(`[serve] Skipping remote artifact descriptor: ${error instanceof Error ? error.message : String(error)}`);
+            warnings.push({
+                code: "remote-artifact-registration-failed",
+                severity: "warning",
+                message: `Oracle captured the browser text response, but the bridge host could not prepare ${filename} for transfer. ` +
+                    "Open the ChatGPT browser on the bridge host, download the ZIP/file shown in the current response, and copy it to a cloud-readable path.",
+            });
+            return null;
+        });
+        if (!registration) {
+            continue;
+        }
+        params.artifactRegistry.set(remoteArtifactKey(params.runId, registration.descriptor.artifactId), {
+            descriptor: registration.descriptor,
+            filePath: registration.filePath,
+            expiresAt: Date.now() + REMOTE_ARTIFACT_TTL_MS,
+        });
+        descriptors.push(registration.descriptor);
+    }
+    return { descriptors, warnings };
+}
+async function buildRemoteArtifactRegistration(runId, artifact) {
+    if (artifact.path.endsWith(".crdownload")) {
+        throw new Error("artifact is still a Chrome partial download");
+    }
+    const filePath = await resolveRegisteredArtifactPath(artifact.path);
+    const fileStat = await stat(filePath);
+    if (!fileStat.isFile() || fileStat.size <= 0) {
+        throw new Error("artifact is not a completed non-empty file");
+    }
+    if (fileStat.size > MAX_REMOTE_ARTIFACT_BYTES) {
+        throw new Error("artifact exceeds bridge transfer size limit");
+    }
+    const filename = sanitizeArtifactFilename(path.basename(filePath), "artifact.bin");
+    const mimeType = sanitizeArtifactMimeType(artifact.mimeType);
+    // Recompute security metadata from the exact file registered for transfer.
+    const validation = await validateArtifactFile({
+        path: filePath,
+        filename,
+        mimeType,
+    });
+    const sha256 = await computeFileSha256(filePath);
+    return {
+        filePath,
+        descriptor: {
+            artifactId: randomUUID(),
+            runId,
+            kind: "file",
+            filename,
+            mimeType,
+            byteSize: fileStat.size,
+            sha256,
+            validation,
+            sourceUrlKind: classifySourceUrlKind(artifact.sourceUrl),
+            transferStatus: "ready",
+        },
+    };
+}
+async function resolveRegisteredArtifactPath(filePath) {
+    const [resolvedFile, sessionsRoot] = await Promise.all([
+        realpath(filePath),
+        realpath(path.join(getOracleHomeDir(), "sessions")),
+    ]);
+    const relative = path.relative(sessionsRoot, resolvedFile);
+    const segments = relative.split(path.sep);
+    if (!relative ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative) ||
+        segments.length < 3 ||
+        segments[1] !== "artifacts") {
+        throw new Error("artifact is outside Oracle's session artifact boundary");
+    }
+    return resolvedFile;
+}
+function classifySourceUrlKind(sourceUrl) {
+    if (sourceUrl?.startsWith("sandbox:")) {
+        return "sandbox";
+    }
+    if (sourceUrl === "browser-download") {
+        return "browser-download";
+    }
+    return "chatgpt-file-endpoint";
+}
 async function readRequestBody(req) {
     const chunks = [];
     for await (const chunk of req) {
@@ -313,7 +547,7 @@ async function readRequestBody(req) {
 function sanitizeName(raw) {
     return raw.replace(/[^a-zA-Z0-9._-]/g, "_");
 }
-function sanitizeResult(result) {
+function sanitizeResult(result, warnings = []) {
     return {
         answerText: result.answerText,
         answerMarkdown: result.answerMarkdown,
@@ -321,6 +555,7 @@ function sanitizeResult(result) {
         tookMs: result.tookMs,
         answerTokens: result.answerTokens,
         answerChars: result.answerChars,
+        warnings: warnings.length > 0 ? warnings : undefined,
         chromePid: undefined,
         chromePort: undefined,
         userDataDir: undefined,

package/dist/src/remote/types.js

@@ -1 +1 @@
-export {};
+export const MAX_REMOTE_ARTIFACT_BYTES = 512 * 1024 * 1024;