@rynx-ai/server 0.1.11-beta.5 → 0.1.11-beta.51

package/dist/control-api.js

@@ -7,6 +7,7 @@
  * owns that state and exposes its own management application.
  */
 import { timingSafeEqual } from "node:crypto";
+import { Readable } from "node:stream";
 import Router from "@koa/router";
 import { skillInstallRecipeSchema, } from "@rynx-ai/core";
 import { DAEMON_BROWSER_ARTIFACT_CLEAN_PATH, DAEMON_BROWSER_ARTIFACT_INSTALL_PATH, DAEMON_BROWSER_ARTIFACT_UPDATE_PATH, DAEMON_BROWSER_ARTIFACT_VERSION_PATH, DAEMON_CHROME_INSPECTION_PATH, DAEMON_CLEANUP_SESSIONS_PATH, DAEMON_MAINTENANCE_LEASE_HEADER, DAEMON_MAINTENANCE_LEASE_RELEASE_PATH, DAEMON_SHUTDOWN_IF_IDLE_PATH, parseDaemonBrowserArtifactInstallInput, parseDaemonBrowserArtifactUpdateInput, parseDaemonChromeInspectionConfigureInput, parseDaemonCleanupSessionsInput, } from "@rynx-ai/protocol/control";
@@ -14,11 +15,12 @@ import { DIRECT_RUNTIME_CONTROL_PATH, encodePairingCode, } from "@rynx-ai/protoc
 import { PLUGIN_CONSOLE_INSTALL_PREPARATIONS_PATH, PLUGIN_CONSOLE_MARKETPLACES_PATH, PLUGIN_INSTALL_PREPARATIONS_PATH, PLUGIN_MARKETPLACES_PATH, parsePluginInstallCommitInput, parsePluginInstallPrepareInput, parsePluginMarketplaceAddInput, } from "@rynx-ai/protocol/plugin-management";
 import { parseDaemonStatus } from "@rynx-ai/protocol/remote-runtime";
 import { materializeRemoteRuntimeSessionEvent, materializeRemoteRuntimeSessionRuntimeSnapshot, parseRemoteRuntimeRpcRequest, REMOTE_RUNTIME_RPC_MAX_FRAME_BYTES, SESSION_IMAGE_MEDIA_TYPES, SESSION_RESOURCE_MAX_IMAGE_BYTES, SESSION_RESOURCE_MAX_FILENAME_CHARS, SESSION_RESOURCE_TRANSFER_CHUNK_BYTES, REMOTE_RUNTIME_SESSION_MAX_PAGE_SIZE, } from "@rynx-ai/protocol/remote-runtime-rpc";
-import { RUNTIME_BROWSER_BOOTSTRAP_PATH, RUNTIME_BROWSER_CAPABILITY_HEADER, RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX, RUNTIME_BROWSER_RPC_PATH, RUNTIME_BROWSER_SESSION_ID_HEADER, parseRuntimeBrowserBootstrapCredential, } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+import { RUNTIME_BROWSER_BOOTSTRAP_PATH, RUNTIME_BROWSER_CAPABILITY_HEADER, RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX, RUNTIME_BROWSER_RPC_PATH, RUNTIME_BROWSER_EXECUTE_PATH, RUNTIME_BROWSER_SESSION_ID_HEADER, parseRuntimeBrowserBootstrapCredential, parseRuntimeBrowserAutomationCommand, } from "@rynx-ai/protocol/runtime-browser-bootstrap";
 import { parseRuntimeBrowserStateGetParams } from "@rynx-ai/protocol/runtime-browser";
 import { encodeDaemonStatus } from "./remote-runtime.js";
 import { SessionRuntimeIndex } from "./session-runtime-index.js";
 import { authorizeRuntimeWebRequest, RUNTIME_WEB_CAPABILITY, RUNTIME_WEB_CAPABILITY_HEADER, } from "./runtime-web-auth.js";
+import { MachineSessionServiceFailure, } from "./machine-session-service.js";
 const PLUGIN_CLI_BODY_MAX_BYTES = 512 * 1024;
 const PLUGIN_CLI_STDIN_MAX_BYTES = 256 * 1024;
 const PLUGIN_CLI_ARG_MAX_BYTES = 4 * 1024;
@@ -54,6 +56,8 @@ const RUNTIME_TARGET_SELECTOR_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,255}$/;
 const SESSION_INTERACTION_RESOLUTION_MAX_BYTES = 128 * 1024;
 const RUNTIME_BROWSER_RPC_METHODS = new Set([
     "browser.state.get",
+    "browser.request-headers.get",
+    "browser.request-headers.set",
     "browser.open",
     "browser.close",
     "browser.page.create",
@@ -630,6 +634,7 @@ export function createControlRouter(opts) {
         let afterId;
         let bytes = 0;
         let runtime;
+        let pendingInputs = [];
         try {
             for (let pageIndex = 0; pageIndex < REMOTE_RUNTIME_SESSION_BFF_MAX_PAGES; pageIndex += 1) {
                 const page = await lease.call("session.snapshot.get", {
@@ -641,6 +646,7 @@ export function createControlRouter(opts) {
                     throw runtimeProtocolError("Runtime Session snapshot identity changed");
                 }
                 runtime = page.runtime;
+                pendingInputs = page.pendingInputs ?? [];
                 for (const item of page.items) {
                     if (ids.has(item.id)) {
                         throw runtimeProtocolError("Runtime Session snapshot repeated an item");
@@ -660,6 +666,7 @@ export function createControlRouter(opts) {
                     ctx.body = {
                         sessionId,
                         items,
+                        pendingInputs,
                         runtime: materializeRemoteRuntimeSessionRuntimeSnapshot(runtime, items),
                     };
                     return;
@@ -735,12 +742,15 @@ export function createControlRouter(opts) {
         const body = await readRuntimeBody(ctx);
         if (!body)
             return;
-        if (!acceptRuntimeBodyKeys(ctx, body, ["model", "reasoningEffort"]))
+        if (!acceptRuntimeBodyKeys(ctx, body, ["model", "reasoningEffort", "collaborationMode"]))
             return;
         const outcome = await runtimeCall(ctx, "session.execution.update", {
             sessionId: ctx.params.id,
             model: body.model,
             reasoningEffort: body.reasoningEffort,
+            ...(body.collaborationMode === undefined
+                ? {}
+                : { collaborationMode: body.collaborationMode }),
         });
         if (outcome.ok)
             ctx.body = outcome.result;
@@ -855,7 +865,13 @@ export function createControlRouter(opts) {
     };
     const runtimeSessionResourceUpload = async (ctx) => {
         const uploadStarted = performance.now();
-        const mediaType = ctx.get("content-type").split(";", 1)[0]?.trim();
+        const mediaType = ctx.get("content-type").split(";", 1)[0]?.trim().toLowerCase();
+        const requestedType = ctx.get("x-rynx-resource-type").trim();
+        const resourceType = requestedType === "input_image" || requestedType === "input_file"
+            ? requestedType
+            : SESSION_IMAGE_MEDIA_TYPES.includes(mediaType)
+                ? "input_image"
+                : "input_file";
         const clientUploadId = ctx.get("x-rynx-upload-id").trim();
         const encodedFilename = ctx.get("x-rynx-filename").trim();
         let filename = "";
@@ -868,7 +884,9 @@ export function createControlRouter(opts) {
             return;
         }
         if (!mediaType ||
-            !SESSION_IMAGE_MEDIA_TYPES.includes(mediaType) ||
+            !isMediaType(mediaType) ||
+            (resourceType === "input_image" &&
+                !SESSION_IMAGE_MEDIA_TYPES.includes(mediaType)) ||
             !clientUploadId ||
             !filename ||
             filename.length > SESSION_RESOURCE_MAX_FILENAME_CHARS) {
@@ -876,23 +894,21 @@ export function createControlRouter(opts) {
             ctx.body = { error: "invalid_resource_upload" };
             return;
         }
-        let bytes;
-        const bodyReadStarted = performance.now();
-        try {
-            bytes = await readBoundedBinary(ctx, SESSION_RESOURCE_MAX_IMAGE_BYTES);
-        }
-        catch (error) {
-            ctx.status = error instanceof RequestBodyTooLargeError ? 413 : 400;
-            ctx.body = {
-                error: error instanceof RequestBodyTooLargeError
-                    ? "request_too_large"
-                    : "invalid_resource_upload",
-            };
+        const contentLengthHeader = ctx.get("content-length").trim();
+        if (!contentLengthHeader) {
+            ctx.status = 411;
+            ctx.body = { error: "content_length_required" };
             return;
         }
-        if (bytes.byteLength === 0) {
+        const byteLength = Number(contentLengthHeader);
+        if (!Number.isSafeInteger(byteLength) || byteLength <= 0) {
             ctx.status = 400;
-            ctx.body = { error: "empty_resource" };
+            ctx.body = { error: "invalid_content_length" };
+            return;
+        }
+        if (resourceType === "input_image" && byteLength > SESSION_RESOURCE_MAX_IMAGE_BYTES) {
+            ctx.status = 413;
+            ctx.body = { error: "request_too_large" };
             return;
         }
         const sessionId = ctx.params.id;
@@ -900,9 +916,7 @@ export function createControlRouter(opts) {
         const lease = local ? undefined : await acquireRuntimeLease(ctx);
         if (!local && !lease)
             return;
-        const timings = new Map([
-            ["body", performance.now() - bodyReadStarted],
-        ]);
+        const timings = new Map();
         const timed = async (name, operation) => {
             const started = performance.now();
             try {
@@ -919,16 +933,18 @@ export function createControlRouter(opts) {
             ? local.beginResourceUpload({
                 sessionId,
                 clientUploadId,
+                type: resourceType,
                 filename,
                 mediaType,
-                byteLength: bytes.byteLength,
+                byteLength,
             })
             : lease.call("session.resource.upload.begin", {
                 sessionId,
                 clientUploadId,
+                type: resourceType,
                 filename,
                 mediaType,
-                byteLength: bytes.byteLength,
+                byteLength,
             }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS }));
         const writeChunk = (uploadId, offset, data) => timed("chunks", () => local
             ? local.writeResourceUploadChunk({ sessionId, uploadId, offset, data })
@@ -936,44 +952,72 @@ export function createControlRouter(opts) {
         const commit = (uploadId) => timed("commit", () => local
             ? local.commitResourceUpload({ sessionId, uploadId })
             : lease.call("session.resource.upload.commit", { sessionId, uploadId }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS }));
+        const discardPartial = (resourceId) => timed("restart", () => local
+            ? local.deleteResource({ sessionId, resourceId })
+            : lease.call("session.resource.delete", { sessionId, resourceId }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS }));
+        let requestResourceId;
+        let resourceCommitted = false;
         try {
             const resourcePolicy = await policy();
             if (!resourcePolicy.enabled ||
-                !resourcePolicy.mediaTypes.includes(mediaType) ||
-                bytes.byteLength > resourcePolicy.maxImageBytes) {
+                (resourceType === "input_image" &&
+                    (!resourcePolicy.mediaTypes.includes(mediaType) ||
+                        byteLength > resourcePolicy.maxImageBytes))) {
                 ctx.status = 413;
                 ctx.body = { error: "resource_policy_rejected" };
                 return;
             }
-            const begun = await begin();
+            let begun = await begin();
             if (begun.complete && begun.resource) {
+                ctx.req.resume();
                 ctx.set("Cache-Control", "no-store");
                 ctx.body = { resource: begun.resource };
                 return;
             }
-            if (begun.offset < 0 || begun.offset > bytes.byteLength) {
+            if (begun.offset < 0 || begun.offset > byteLength) {
                 throw runtimeProtocolError("Runtime Session resource upload offset is invalid");
             }
-            let offset = begun.offset;
-            while (offset < bytes.byteLength) {
-                const chunk = bytes.subarray(offset, Math.min(offset + SESSION_RESOURCE_TRANSFER_CHUNK_BYTES, bytes.byteLength));
-                const written = await writeChunk(begun.uploadId, offset, chunk.toString("base64"));
-                if (written.offset <= offset || written.offset > bytes.byteLength) {
-                    throw runtimeProtocolError("Runtime Session resource upload did not advance");
+            // Browser retries send the complete File body again. A target-side
+            // partial cannot be blindly combined with the new body's suffix: the
+            // caller may have reused an upload id for changed bytes. Restart the
+            // incomplete upload so committed content always matches this request.
+            if (begun.offset > 0) {
+                const discarded = await discardPartial(begun.resourceId);
+                if (!discarded.deleted) {
+                    throw runtimeProtocolError("Runtime Session partial upload could not be restarted");
+                }
+                begun = await begin();
+                if (begun.complete || begun.offset !== 0) {
+                    throw runtimeProtocolError("Runtime Session resource upload did not restart");
                 }
-                offset = written.offset;
             }
+            requestResourceId = begun.resourceId;
+            const bodyStarted = performance.now();
+            await forwardResourceUploadBody(ctx, begun.uploadId, begun.offset, byteLength, writeChunk);
+            timings.set("body", performance.now() - bodyStarted);
             const committed = await commit(begun.uploadId);
             if (committed.resource.resourceId !== begun.resourceId ||
+                committed.resource.type !== resourceType ||
                 committed.resource.mediaType !== mediaType ||
-                committed.resource.byteLength !== bytes.byteLength) {
+                committed.resource.byteLength !== byteLength) {
                 throw runtimeProtocolError("Runtime Session resource upload identity changed");
             }
+            resourceCommitted = true;
             ctx.status = 201;
             ctx.set("Cache-Control", "no-store");
             ctx.body = committed;
         }
         catch (error) {
+            if (requestResourceId && !resourceCommitted) {
+                try {
+                    await discardPartial(requestResourceId);
+                }
+                catch {
+                    // The original error remains authoritative. Targets also reap stale
+                    // uploads, so a disconnected target cannot make cleanup block the
+                    // browser response indefinitely.
+                }
+            }
             runtimeTargetHostError(ctx, error);
         }
         finally {
@@ -989,7 +1033,7 @@ export function createControlRouter(opts) {
                     event: "session.resource.upload.slow",
                     selector: ctx.params.selector,
                     sessionId,
-                    byteLength: bytes.byteLength,
+                    byteLength,
                     status: ctx.status,
                     timings: Object.fromEntries([...timings.entries()].map(([name, duration]) => [
                         name,
@@ -1033,16 +1077,32 @@ export function createControlRouter(opts) {
         const sessionId = ctx.params.id;
         const resourceId = ctx.params.resourceId;
         const local = ctx.params.selector === "local" ? localSessionResources : undefined;
-        const lease = local ? undefined : await acquireRuntimeLease(ctx);
-        if (!local && !lease)
+        const invocation = downloadInvocationAbortScope(ctx, shutdownSignal);
+        const lease = local ? undefined : await acquireRuntimeLease(ctx, invocation.signal);
+        if (!local && !lease) {
+            invocation.dispose();
             return;
+        }
+        let streamOwnsLease = false;
+        let cleanedUp = false;
+        const cleanup = () => {
+            if (cleanedUp)
+                return;
+            cleanedUp = true;
+            lease?.release();
+            invocation.dispose();
+        };
         try {
             const { resource } = local
                 ? await local.getResource({ sessionId, resourceId })
-                : await lease.call("session.resource.get", { sessionId, resourceId }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS });
+                : await lease.call("session.resource.get", { sessionId, resourceId }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS, signal: invocation.signal });
             if (resource.resourceId !== resourceId) {
                 throw runtimeProtocolError("Runtime Session resource identity changed");
             }
+            const byteLength = resource.byteLength;
+            if (!Number.isSafeInteger(byteLength) || !byteLength || byteLength < 1) {
+                throw runtimeProtocolError("Runtime Session resource length is invalid");
+            }
             const etag = `"sha256-${resource.sha256}"`;
             ctx.set("Cache-Control", "private, max-age=0, must-revalidate");
             ctx.set("ETag", etag);
@@ -1050,48 +1110,68 @@ export function createControlRouter(opts) {
                 ctx.status = 304;
                 return;
             }
-            const chunks = [];
-            let offset = 0;
-            while (offset < (resource.byteLength ?? 0)) {
-                const result = local
-                    ? await local.readResource({
-                        sessionId,
-                        resourceId,
-                        offset,
-                        length: SESSION_RESOURCE_TRANSFER_CHUNK_BYTES,
-                    })
-                    : await lease.call("session.resource.read", {
-                        sessionId,
-                        resourceId,
-                        offset,
-                        length: SESSION_RESOURCE_TRANSFER_CHUNK_BYTES,
-                    }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS });
-                const chunk = Buffer.from(result.data, "base64");
-                if (result.offset !== offset + chunk.byteLength || (!result.eof && chunk.byteLength === 0)) {
-                    throw runtimeProtocolError("Runtime Session resource read did not advance");
-                }
-                chunks.push(chunk);
-                offset = result.offset;
-                if (result.eof)
-                    break;
-            }
-            const body = Buffer.concat(chunks);
-            if (body.byteLength !== resource.byteLength) {
-                throw runtimeProtocolError("Runtime Session resource length changed");
+            const requestedRange = ctx.get("range");
+            const ifRange = ctx.get("if-range");
+            const range = ifRange && ifRange !== etag
+                ? undefined
+                : parseSingleByteRange(requestedRange, byteLength);
+            if (range === "unsatisfiable") {
+                ctx.status = 416;
+                ctx.set("Content-Range", `bytes */${byteLength}`);
+                return;
             }
+            const start = range?.start ?? 0;
+            const end = range?.end ?? byteLength - 1;
+            const responseLength = end - start + 1;
             ctx.set("Content-Security-Policy", "default-src 'none'; sandbox");
             ctx.set("Cross-Origin-Resource-Policy", "same-origin");
             ctx.set("X-Content-Type-Options", "nosniff");
-            ctx.set("Content-Disposition", "inline");
+            ctx.set("Accept-Ranges", "bytes");
+            ctx.set("Content-Disposition", contentDisposition(resource.filename));
+            if (range) {
+                ctx.status = 206;
+                ctx.set("Content-Range", `bytes ${start}-${end}/${byteLength}`);
+            }
             ctx.type = resource.mediaType;
-            ctx.length = body.byteLength;
+            ctx.length = responseLength;
+            if (ctx.method === "HEAD") {
+                ctx.status = range ? 206 : 200;
+                return;
+            }
+            streamOwnsLease = true;
+            const body = Readable.from((async function* () {
+                let offset = start;
+                try {
+                    while (offset <= end) {
+                        const length = Math.min(SESSION_RESOURCE_TRANSFER_CHUNK_BYTES, end - offset + 1);
+                        const result = local
+                            ? await local.readResource({ sessionId, resourceId, offset, length })
+                            : await lease.call("session.resource.read", { sessionId, resourceId, offset, length }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS, signal: invocation.signal });
+                        const chunk = Buffer.from(result.data, "base64");
+                        if (result.offset !== offset + chunk.byteLength || chunk.byteLength === 0) {
+                            throw runtimeProtocolError("Runtime Session resource read did not advance");
+                        }
+                        offset = result.offset;
+                        yield chunk;
+                    }
+                    if (offset !== end + 1) {
+                        throw runtimeProtocolError("Runtime Session resource length changed");
+                    }
+                }
+                finally {
+                    cleanup();
+                }
+            })());
+            body.once("close", cleanup);
             ctx.body = body;
         }
         catch (error) {
             runtimeTargetHostError(ctx, error);
         }
         finally {
-            lease?.release();
+            if (!streamOwnsLease) {
+                cleanup();
+            }
         }
     };
     const runtimeSessionResourceDelete = async (ctx) => {
@@ -1115,6 +1195,243 @@ export function createControlRouter(opts) {
         if (outcome.ok)
             ctx.body = outcome.result;
     };
+    const runtimeSessionItemFileContent = async (ctx) => {
+        const sessionId = ctx.params.id;
+        const itemId = ctx.params.itemId;
+        const partIndex = Number(ctx.params.partIndex);
+        if (!Number.isSafeInteger(partIndex) || partIndex < 0 || partIndex > 1_024) {
+            ctx.status = 400;
+            ctx.body = { error: "invalid_part_index" };
+            return;
+        }
+        const local = ctx.params.selector === "local" ? localMachineSessions : undefined;
+        const invocation = downloadInvocationAbortScope(ctx, shutdownSignal);
+        const lease = local ? undefined : await acquireRuntimeLease(ctx, invocation.signal);
+        if (!local && !lease) {
+            invocation.dispose();
+            return;
+        }
+        let streamOwnsLease = false;
+        let cleanedUp = false;
+        const cleanup = () => {
+            if (cleanedUp)
+                return;
+            cleanedUp = true;
+            lease?.release();
+            invocation.dispose();
+        };
+        try {
+            const { file } = local
+                ? await local.getFile({ sessionId, itemId, partIndex })
+                : await lease.call("session.file.get", { sessionId, itemId, partIndex }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS, signal: invocation.signal });
+            if (file.itemId !== itemId || file.partIndex !== partIndex) {
+                throw runtimeProtocolError("Runtime Session file identity changed");
+            }
+            const etag = `"file-${file.version}"`;
+            ctx.set("Cache-Control", "private, max-age=0, must-revalidate");
+            ctx.set("ETag", etag);
+            if (ctx.get("if-none-match").split(",").map((value) => value.trim()).includes(etag)) {
+                ctx.status = 304;
+                return;
+            }
+            const requestedRange = ctx.get("range");
+            const ifRange = ctx.get("if-range");
+            const range = ifRange && ifRange !== etag
+                ? undefined
+                : parseSingleByteRange(requestedRange, file.byteLength);
+            if (range === "unsatisfiable") {
+                ctx.status = 416;
+                ctx.set("Content-Range", `bytes */${file.byteLength}`);
+                return;
+            }
+            const start = range?.start ?? 0;
+            const end = range?.end ?? file.byteLength - 1;
+            ctx.set("Content-Security-Policy", "default-src 'none'; sandbox");
+            ctx.set("Cross-Origin-Resource-Policy", "same-origin");
+            ctx.set("X-Content-Type-Options", "nosniff");
+            ctx.set("Accept-Ranges", "bytes");
+            ctx.set("Content-Disposition", contentDisposition(file.filename));
+            if (range) {
+                ctx.status = 206;
+                ctx.set("Content-Range", `bytes ${start}-${end}/${file.byteLength}`);
+            }
+            ctx.type = file.mediaType;
+            ctx.length = end - start + 1;
+            if (ctx.method === "HEAD") {
+                ctx.status = range ? 206 : 200;
+                return;
+            }
+            streamOwnsLease = true;
+            const body = Readable.from((async function* () {
+                let offset = start;
+                try {
+                    while (offset <= end) {
+                        const length = Math.min(SESSION_RESOURCE_TRANSFER_CHUNK_BYTES, end - offset + 1);
+                        const result = local
+                            ? await local.readFile({
+                                sessionId,
+                                itemId,
+                                partIndex,
+                                version: file.version,
+                                offset,
+                                length,
+                            })
+                            : await lease.call("session.file.read", {
+                                sessionId,
+                                itemId,
+                                partIndex,
+                                version: file.version,
+                                offset,
+                                length,
+                            }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS, signal: invocation.signal });
+                        const chunk = Buffer.from(result.data, "base64");
+                        if (result.offset !== offset + chunk.byteLength || chunk.byteLength === 0) {
+                            throw runtimeProtocolError("Runtime Session file read did not advance");
+                        }
+                        offset = result.offset;
+                        yield chunk;
+                    }
+                }
+                finally {
+                    cleanup();
+                }
+            })());
+            body.once("close", cleanup);
+            ctx.body = body;
+        }
+        catch (error) {
+            runtimeTargetHostError(ctx, error);
+        }
+        finally {
+            if (!streamOwnsLease) {
+                cleanup();
+            }
+        }
+    };
+    const runtimeSessionWorkspaceFileContent = async (ctx) => {
+        const sessionId = ctx.params.id;
+        const path = ctx.query.path;
+        if (typeof path !== "string" ||
+            path.length === 0 ||
+            path.length > 4_096 ||
+            path.includes("\0")) {
+            ctx.status = 400;
+            ctx.body = { error: "invalid_workspace_file_path" };
+            return;
+        }
+        const local = ctx.params.selector === "local" ? localMachineSessions : undefined;
+        const invocation = downloadInvocationAbortScope(ctx, shutdownSignal);
+        const lease = local ? undefined : await acquireRuntimeLease(ctx, invocation.signal);
+        if (!local && !lease) {
+            invocation.dispose();
+            return;
+        }
+        let streamOwnsLease = false;
+        let cleanedUp = false;
+        const cleanup = () => {
+            if (cleanedUp)
+                return;
+            cleanedUp = true;
+            lease?.release();
+            invocation.dispose();
+        };
+        try {
+            const { file } = local
+                ? await local.getWorkspaceFile({ sessionId, path })
+                : await lease.call("session.workspace.file.get", { sessionId, path }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS, signal: invocation.signal });
+            if (file.path !== path) {
+                throw runtimeProtocolError("Runtime Session workspace file identity changed");
+            }
+            const etag = `"workspace-file-${file.version}"`;
+            ctx.set("Cache-Control", "private, max-age=0, must-revalidate");
+            ctx.set("ETag", etag);
+            if (ctx.get("if-none-match").split(",").map((value) => value.trim()).includes(etag)) {
+                ctx.status = 304;
+                return;
+            }
+            ctx.set("Content-Security-Policy", "default-src 'none'; sandbox");
+            ctx.set("Cross-Origin-Resource-Policy", "same-origin");
+            ctx.set("X-Content-Type-Options", "nosniff");
+            ctx.set("Accept-Ranges", "bytes");
+            ctx.set("Content-Disposition", contentDisposition(file.filename));
+            ctx.type = file.mediaType;
+            if (file.byteLength === 0) {
+                if (ctx.get("range")) {
+                    ctx.status = 416;
+                    ctx.set("Content-Range", "bytes */0");
+                    return;
+                }
+                ctx.status = 200;
+                ctx.length = 0;
+                if (ctx.method !== "HEAD")
+                    ctx.body = Buffer.alloc(0);
+                return;
+            }
+            const requestedRange = ctx.get("range");
+            const ifRange = ctx.get("if-range");
+            const range = ifRange && ifRange !== etag
+                ? undefined
+                : parseSingleByteRange(requestedRange, file.byteLength);
+            if (range === "unsatisfiable") {
+                ctx.status = 416;
+                ctx.set("Content-Range", `bytes */${file.byteLength}`);
+                return;
+            }
+            const start = range?.start ?? 0;
+            const end = range?.end ?? file.byteLength - 1;
+            if (range) {
+                ctx.status = 206;
+                ctx.set("Content-Range", `bytes ${start}-${end}/${file.byteLength}`);
+            }
+            ctx.length = end - start + 1;
+            if (ctx.method === "HEAD") {
+                ctx.status = range ? 206 : 200;
+                return;
+            }
+            streamOwnsLease = true;
+            const body = Readable.from((async function* () {
+                let offset = start;
+                try {
+                    while (offset <= end) {
+                        const length = Math.min(SESSION_RESOURCE_TRANSFER_CHUNK_BYTES, end - offset + 1);
+                        const result = local
+                            ? await local.readWorkspaceFile({
+                                sessionId,
+                                path,
+                                version: file.version,
+                                offset,
+                                length,
+                            })
+                            : await lease.call("session.workspace.file.read", {
+                                sessionId,
+                                path,
+                                version: file.version,
+                                offset,
+                                length,
+                            }, { timeoutMs: REMOTE_RUNTIME_SESSION_TIMEOUT_MS, signal: invocation.signal });
+                        const chunk = Buffer.from(result.data, "base64");
+                        if (result.offset !== offset + chunk.byteLength || chunk.byteLength === 0) {
+                            throw runtimeProtocolError("Runtime Session workspace file read did not advance");
+                        }
+                        offset = result.offset;
+                        yield chunk;
+                    }
+                }
+                finally {
+                    cleanup();
+                }
+            })());
+            body.once("close", cleanup);
+            ctx.body = body;
+        }
+        catch (error) {
+            runtimeTargetHostError(ctx, error);
+        }
+        finally {
+            if (!streamOwnsLease)
+                cleanup();
+        }
+    };
     const runtimeSessionMessageEnqueue = async (ctx) => {
         const body = await readRuntimeBody(ctx);
         if (!body)
@@ -1174,6 +1491,32 @@ export function createControlRouter(opts) {
         if (outcome.ok)
             ctx.body = outcome.result;
     };
+    const runtimeBrowserRequestHeaders = async (ctx) => {
+        const outcome = await runtimeCall(ctx, "browser.request-headers.get", {
+            sessionId: ctx.params.id,
+        });
+        if (outcome.ok) {
+            ctx.set("Cache-Control", "no-store");
+            ctx.body = outcome.result;
+        }
+    };
+    const runtimeBrowserRequestHeadersUpdate = async (ctx) => {
+        const body = await readRuntimeBody(ctx);
+        if (!body)
+            return;
+        if (!acceptRuntimeBodyKeys(ctx, body, ["expectedRevision", "enabled", "headers"]))
+            return;
+        const outcome = await runtimeCall(ctx, "browser.request-headers.set", {
+            sessionId: ctx.params.id,
+            expectedRevision: body.expectedRevision,
+            enabled: body.enabled,
+            headers: body.headers,
+        });
+        if (outcome.ok) {
+            ctx.set("Cache-Control", "no-store");
+            ctx.body = outcome.result;
+        }
+    };
     const runtimeBrowserOpen = async (ctx) => {
         const body = await readRuntimeBody(ctx);
         if (!body)
@@ -1746,12 +2089,22 @@ export function createControlRouter(opts) {
     router.post("/api/runtimes/:selector/sessions/:id/resources", publicRuntimeMutation(runtimeSessionResourceUpload));
     router.get("/api/runtimes/:selector/sessions/:id/resources/:resourceId", publicRuntimeRead(runtimeSessionResourceMetadata));
     router.get("/api/runtimes/:selector/sessions/:id/resources/:resourceId/content", publicRuntimeRead(runtimeSessionResourceContent));
+    router.head("/api/runtimes/:selector/sessions/:id/resources/:resourceId/content", publicRuntimeRead(runtimeSessionResourceContent));
+    router.get("/api/runtimes/:selector/sessions/:id/items/:itemId/files/:partIndex/content", publicRuntimeRead(runtimeSessionItemFileContent));
+    router.head("/api/runtimes/:selector/sessions/:id/items/:itemId/files/:partIndex/content", publicRuntimeRead(runtimeSessionItemFileContent));
+    router.get("/api/runtimes/:selector/sessions/:id/workspace/files/content", publicRuntimeRead(runtimeSessionWorkspaceFileContent));
+    router.head("/api/runtimes/:selector/sessions/:id/workspace/files/content", publicRuntimeRead(runtimeSessionWorkspaceFileContent));
     router.delete("/api/runtimes/:selector/sessions/:id/resources/:resourceId", publicRuntimeMutation(runtimeSessionResourceDelete));
     router.post("/api/runtimes/:selector/sessions/:id/messages/queue", publicRuntimeMutation(runtimeSessionMessageEnqueue));
     router.post("/api/runtimes/:selector/sessions/:id/terminal/start", publicRuntimeMutation(runtimeSessionTerminalStart));
     router.post("/api/runtimes/:selector/sessions/:id/interactions/:interactionId/resolve", publicRuntimeMutation(runtimeSessionResolveInteraction));
     router.delete("/api/runtimes/:selector/sessions/:id", publicRuntimeMutation(runtimeSessionDelete));
     router.get("/api/runtimes/:selector/sessions/:id/browser", publicRuntimeRead(runtimeBrowserState));
+    router.get("/api/runtimes/:selector/sessions/:id/browser/request-headers", 
+    // Header values may be sensitive. Reading them requires the same
+    // process-lifetime capability and Portal grant as a mutation.
+    publicRuntimeMutation(runtimeBrowserRequestHeaders));
+    router.put("/api/runtimes/:selector/sessions/:id/browser/request-headers", publicRuntimeMutation(runtimeBrowserRequestHeadersUpdate));
     router.post("/api/runtimes/:selector/sessions/:id/browser/open", publicRuntimeMutation(runtimeBrowserOpen));
     router.post("/api/runtimes/:selector/sessions/:id/browser/close", publicRuntimeMutation(runtimeBrowserClose));
     router.post("/api/runtimes/:selector/sessions/:id/browser/pages", publicRuntimeMutation(runtimeBrowserPageCreate));
@@ -1771,6 +2124,71 @@ export function createControlRouter(opts) {
     router.post("/api/internal/runtimes/:selector/emulator/gesture", internalRuntimeCall(runtimeGestureEmulator));
     router.post("/api/internal/runtimes/:selector/emulator/kill", internalRuntimeCall((ctx) => runtimeDeviceCommand(ctx, "emulator.kill")));
     router.post("/api/internal/runtimes/:selector/emulator/shutdown", internalRuntimeCall((ctx) => runtimeDeviceCommand(ctx, "emulator.shutdown")));
+    const executeLocalBrowser = async (ctx, management) => {
+        if (!runtimeLocalBrowser?.executeForSession) {
+            notFound(ctx, "Page automation requires a Runtime upgrade");
+            return;
+        }
+        if (!isLoopbackRequest(ctx)) {
+            ctx.status = 403;
+            ctx.body = { error: "loopback_only" };
+            return;
+        }
+        let sessionId;
+        if (management) {
+            if (!isConfiguredDaemonManagement(daemonManagement)) {
+                notFound(ctx, "Daemon management is unavailable");
+                return;
+            }
+            if (!authorizeLoopbackManagementRequest(ctx, daemonManagement.managementToken))
+                return;
+            try {
+                sessionId = parseRuntimeBrowserStateGetParams({ sessionId: ctx.params.sessionId }).sessionId;
+            }
+            catch {
+                bad(ctx, "invalid Session id");
+                return;
+            }
+        }
+        else {
+            try {
+                const credential = parseRuntimeBrowserBootstrapCredential({
+                    sessionId: ctx.get(RUNTIME_BROWSER_SESSION_ID_HEADER), capability: ctx.get(RUNTIME_BROWSER_CAPABILITY_HEADER),
+                });
+                if (!await runtimeLocalBrowser.authorizeCredential(credential))
+                    throw new Error("unauthorized");
+                sessionId = credential.sessionId;
+            }
+            catch {
+                ctx.status = 401;
+                ctx.body = { error: "invalid Runtime Browser Session capability" };
+                return;
+            }
+        }
+        if (!ctx.is("application/json")) {
+            ctx.status = 415;
+            ctx.body = { error: "unsupported_media_type" };
+            return;
+        }
+        let command;
+        try {
+            command = parseRuntimeBrowserAutomationCommand(await readBoundedJson(ctx, 128 * 1024));
+        }
+        catch (error) {
+            ctx.status = error instanceof RequestBodyTooLargeError ? 413 : 400;
+            ctx.body = { error: "invalid_request" };
+            return;
+        }
+        try {
+            ctx.set("Cache-Control", "no-store");
+            ctx.body = await runtimeLocalBrowser.executeForSession(sessionId, command);
+        }
+        catch (error) {
+            runtimeLocalBrowserError(ctx, error);
+        }
+    };
+    router.post(RUNTIME_BROWSER_EXECUTE_PATH, (ctx) => executeLocalBrowser(ctx, false));
+    router.post(`${RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX}/:sessionId/execute`, (ctx) => executeLocalBrowser(ctx, true));
     router.get(RUNTIME_BROWSER_BOOTSTRAP_PATH, async (ctx) => {
         if (!runtimeLocalBrowser) {
             return notFound(ctx, "Runtime-local Browser automation is not configured");
@@ -1948,10 +2366,17 @@ export function createControlRouter(opts) {
         }
         if (!authorizeLoopbackManagementRequest(ctx, daemonManagement.managementToken))
             return;
-        const maintenanceLeaseToken = ctx.get(DAEMON_MAINTENANCE_LEASE_HEADER).trim() || undefined;
+        if (ctx.get(DAEMON_MAINTENANCE_LEASE_HEADER).trim()) {
+            ctx.set("Cache-Control", "no-store");
+            ctx.status = 410;
+            ctx.body = {
+                error: "cross-process maintenance leases are retired; upgrade the caller",
+            };
+            return;
+        }
         let result;
         try {
-            result = await daemonManagement.shutdownIfIdle(maintenanceLeaseToken);
+            result = await daemonManagement.shutdownIfIdle();
         }
         catch (error) {
             ctx.set("Cache-Control", "no-store");
@@ -1966,15 +2391,16 @@ export function createControlRouter(opts) {
         ctx.body = result;
     });
     router.post(DAEMON_MAINTENANCE_LEASE_RELEASE_PATH, (ctx) => {
-        if (!isConfiguredDaemonManagement(daemonManagement)
-            || !daemonManagement.releaseMaintenanceLease) {
-            return notFound(ctx, "daemon maintenance lease management is not configured");
+        if (!isConfiguredDaemonManagement(daemonManagement)) {
+            return notFound(ctx, "daemon management is not configured");
         }
         if (!authorizeLoopbackManagementRequest(ctx, daemonManagement.managementToken))
             return;
-        const result = daemonManagement.releaseMaintenanceLease(ctx.get(DAEMON_MAINTENANCE_LEASE_HEADER).trim());
+        // Compatibility for updaters released before Plugin-owned drain became
+        // the sole upgrade fence. New daemons never acquire a Host lease.
+        const result = { outcome: "not_active" };
         ctx.set("Cache-Control", "no-store");
-        ctx.status = result.outcome === "denied" ? 403 : 200;
+        ctx.status = 200;
         ctx.body = result;
     });
     router.post(DAEMON_BROWSER_ARTIFACT_INSTALL_PATH, async (ctx) => {
@@ -3178,7 +3604,7 @@ export function createControlRouter(opts) {
     // ── sessions (channel-agnostic agent runs) ───────────────────────────────
     // Create a session bound to a preset agent (`agent`) or an inline spec
     // (`config`, the config-driven / remote-ready path), then drive it with
-    // messages over SSE. reference implementation-style: create carries no message.
+    // messages over SSE. Creating the session does not submit a message.
     // One unified list: every session is a machine-session record. The registry
     // (console + every channel) supplies identity — `source` is a plain field, not
     // parsed from the id — and the canonical log supplies recency. A legacy session
@@ -3252,7 +3678,20 @@ export function createControlRouter(opts) {
             }
             catch (error) {
                 ctx.status = 503;
-                ctx.body = { error: error instanceof Error ? error.message : String(error) };
+                const runtimeFailure = error instanceof MachineSessionServiceFailure
+                    ? error.runtimeFailure
+                    : undefined;
+                const message = runtimeFailure?.message
+                    ?? (error instanceof MachineSessionServiceFailure ? error.detail : undefined)
+                    ?? (error instanceof Error ? error.message : String(error));
+                ctx.body = {
+                    error: message,
+                    code: runtimeFailure?.code
+                        ?? (error instanceof MachineSessionServiceFailure ? error.code : "runtime_error"),
+                    outcome: error instanceof MachineSessionServiceFailure && error.code === "outcome_unknown"
+                        ? "unknown"
+                        : "not_started",
+                };
             }
             return;
         }
@@ -3271,26 +3710,31 @@ export function createControlRouter(opts) {
             execution: structuredClone(meta.execution),
         });
         if (!live) {
+            const failure = runnerManager.lastLiveSessionFailure?.(id);
             ctx.status = 503;
             ctx.body = {
-                error: `live session unavailable (${meta.execution.provider})`,
-                ...(runnerManager.lastLiveSessionError?.(id)
-                    ? { detail: runnerManager.lastLiveSessionError(id) }
-                    : {}),
+                error: failure?.message
+                    ?? runnerManager.lastLiveSessionError?.(id)
+                    ?? `live session unavailable (${meta.execution.provider})`,
+                code: failure?.code ?? "live_unavailable",
+                outcome: "not_started",
             };
             return;
         }
-        const outcome = await runnerManager.injectMessage(id, message);
-        if (outcome === "injected") {
+        const result = await runnerManager.injectMessage(id, message);
+        const outcome = result.outcome;
+        if (outcome === "injected" || outcome === "steered") {
             ctx.body = { ok: true, injected: true };
             return;
         }
         ctx.status = 503;
+        const failure = runnerManager.lastLiveSessionFailure?.(id);
         ctx.body = {
-            error: `live injection ${outcome}`,
-            ...(runnerManager.lastLiveSessionError?.(id)
-                ? { detail: runnerManager.lastLiveSessionError(id) }
-                : {}),
+            error: failure?.message
+                ?? runnerManager.lastLiveSessionError?.(id)
+                ?? `live injection ${outcome}`,
+            code: failure?.code ?? "live_inject_failed",
+            outcome: outcome === "failed" ? "unknown" : "not_started",
         };
     });
     // Stop the session's active turn (the web Stop button). For a live native
@@ -3316,6 +3760,7 @@ export function createControlRouter(opts) {
         ctx.body = {
             sessionId: id,
             items: sessionLog ? await sessionLog.snapshot(id) : [],
+            pendingInputs: [],
             runtime: sessionRuntimeIndex.snapshot(id),
         };
     });
@@ -3406,7 +3851,15 @@ export function createControlRouter(opts) {
             ctx.body = { error: "session_resource_cleanup_failed" };
             return;
         }
-        runnerManager?.stopRunner(id);
+        if (runnerManager?.terminateLiveSession) {
+            await runnerManager.terminateLiveSession(id).catch((error) => {
+                console.warn(`[control-api] session=${id} live teardown failed during deletion; continuing best-effort: ${error instanceof Error ? error.message : String(error)}`);
+                return false;
+            });
+        }
+        else {
+            runnerManager?.stopRunner(id);
+        }
         sessionBus?.close(id);
         deps.removeSessionMeta(id);
         // Hard-delete the transcript too — the session list is meta ∪ log, so
@@ -3503,8 +3956,8 @@ function abortAsNull(signal) {
     });
 }
 /** Derive a one-line session title from the first user message: collapse
- *  whitespace, trim, and truncate to `limit` chars + an ellipsis (reference implementation's
- *  rule — no LLM call). */
+ *  whitespace, trim, and fit within `limit` characters, including an ellipsis
+ *  when truncated. No LLM call is made. */
 export function synthesizeSessionTitle(message, limit = 60) {
     const collapsed = message.replace(/\s+/g, " ").trim();
     if (collapsed.length <= limit)
@@ -3576,6 +4029,14 @@ function optionalRuntimeDevice(body) {
     return body.device === undefined ? {} : { device: body.device };
 }
 function remoteRuntimeRpcTimeoutMs(method, params) {
+    // Native startup/delivery owns phase-specific deadlines and returns their
+    // concrete failures. A BFF deadline here would race those phases and replace
+    // the real error with an ambiguous generic RPC timeout. The setup queue also
+    // awaits Terminal startup before acknowledging the request.
+    if (method === "session.message.send" ||
+        method === "session.message.enqueue" ||
+        method === "session.terminal.start")
+        return null;
     if (method === "session.emulator.attach")
         return REMOTE_RUNTIME_EMULATOR_ATTACH_TIMEOUT_MS;
     if (method === "session.emulator.type") {
@@ -3679,6 +4140,36 @@ function pluginInstallInvocationAbortScope(ctx, shutdownSignal) {
 function browserArtifactInvocationAbortScope(ctx, shutdownSignal) {
     return managementInvocationAbortScope(ctx, shutdownSignal, BROWSER_ARTIFACT_OPERATION_TIMEOUT_MS, "Browser artifact operation");
 }
+function downloadInvocationAbortScope(ctx, shutdownSignal) {
+    const controller = new AbortController();
+    const abort = (reason) => {
+        if (!controller.signal.aborted)
+            controller.abort(reason);
+    };
+    const onRequestAborted = () => abort(namedError("download request aborted", "AbortError"));
+    const onResponseClose = () => {
+        if (!ctx.res.writableEnded) {
+            abort(namedError("download client disconnected", "AbortError"));
+        }
+    };
+    const onShutdown = () => abort(shutdownSignal?.reason ?? namedError("daemon is shutting down", "AbortError"));
+    ctx.req.once("aborted", onRequestAborted);
+    ctx.res.once("close", onResponseClose);
+    if (shutdownSignal?.aborted)
+        onShutdown();
+    else
+        shutdownSignal?.addEventListener("abort", onShutdown, { once: true });
+    if (ctx.req.aborted)
+        onRequestAborted();
+    return {
+        signal: controller.signal,
+        dispose() {
+            ctx.req.removeListener("aborted", onRequestAborted);
+            ctx.res.removeListener("close", onResponseClose);
+            shutdownSignal?.removeEventListener("abort", onShutdown);
+        },
+    };
+}
 function managementInvocationAbortScope(ctx, shutdownSignal, timeoutMs, label) {
     const controller = new AbortController();
     const abort = (reason) => {
@@ -3899,8 +4390,14 @@ function runtimeTargetHostError(ctx, error, forcedOutcome) {
     const status = runtimeTargetHttpStatus(code);
     ctx.status = status;
     const outcome = forcedOutcome ?? runtimeTargetErrorOutcome(error);
+    const applicationMessage = error instanceof Error && error.name === "DirectRuntimeRpcError"
+        ? error.message.replace(/^Remote Runtime RPC failed: [^:]+: /, "")
+        : undefined;
     ctx.body = {
-        error: status === 500 ? "internal_error" : code,
+        error: applicationMessage ?? (status === 500 ? "internal_error" : code),
+        ...(applicationMessage
+            ? { code: status === 500 ? "internal_error" : code }
+            : {}),
         ...(outcome === undefined ? {} : { outcome }),
     };
 }
@@ -3909,9 +4406,19 @@ function runtimeLocalBrowserError(ctx, error) {
         ? error.code
         : undefined;
     switch (code) {
+        case "human_control_active":
+            ctx.status = 409;
+            ctx.body = { error: code, hint: "Release Browser Control before Agent actions." };
+            return;
+        case "command_timeout":
+            ctx.status = 504;
+            ctx.body = { error: "command_timeout", outcome: "unknown" };
+            return;
         case "invalid_request":
             ctx.status = 400;
-            ctx.body = { error: "invalid_request" };
+            ctx.body = { error: "invalid_request", ...(error instanceof Error && error.name === "PageAutomationError"
+                    ? { message: error.message.slice(0, 2048), hint: "Run rynx skills get browser for Browser resources; after opening a Browser, use rynx browser exec -- --help for page commands." }
+                    : {}) };
             return;
         case "not_found":
             ctx.status = 404;
@@ -3923,10 +4430,30 @@ function runtimeLocalBrowserError(ctx, error) {
             ctx.body = { error: "unavailable" };
             return;
         case "host_failure":
-        case "outcome_unknown":
             ctx.status = 502;
             ctx.body = { error: "operation_failed" };
             return;
+        case "outcome_unknown":
+            ctx.status = 502;
+            ctx.body = { error: "outcome_unknown", outcome: "unknown", hint: "Do not replay this action. Run rynx browser exec -- snapshot -i to inspect its outcome." };
+            return;
+        case "driver_restarted":
+        case "generation_mismatch":
+            ctx.status = 409;
+            ctx.body = { error: code, hint: "Run rynx browser exec -- snapshot -i for fresh Page references." };
+            return;
+        case "capacity":
+            ctx.status = 429;
+            ctx.body = { error: "capacity" };
+            return;
+        case "unsupported":
+            ctx.status = 501;
+            ctx.body = { error: "unsupported", hint: "Upgrade the Runtime and Desktop Host together." };
+            return;
+        case "command_failed":
+            ctx.status = 422;
+            ctx.body = { error: "command_failed", message: error instanceof Error ? error.message : "agent-browser command failed", hint: "Run rynx browser exec -- --help, or inspect a fresh snapshot before another action." };
+            return;
         default:
             ctx.status = 500;
             ctx.body = { error: "internal_error" };
@@ -3988,6 +4515,83 @@ function publicRuntimeStreamError(error) {
 }
 class RequestBodyTooLargeError extends Error {
 }
+function isMediaType(value) {
+    return value.length <= 255 && /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(value);
+}
+async function forwardResourceUploadBody(ctx, uploadId, resumeOffset, expectedBytes, writeChunk) {
+    let received = 0;
+    let remoteOffset = resumeOffset;
+    let carry = Buffer.alloc(0);
+    for await (const raw of ctx.req) {
+        const incoming = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+        if (received + incoming.byteLength > expectedBytes) {
+            throw runtimeProtocolError("Resource upload exceeds Content-Length");
+        }
+        const skip = Math.min(incoming.byteLength, Math.max(0, resumeOffset - received));
+        received += incoming.byteLength;
+        let cursor = skip;
+        while (cursor < incoming.byteLength) {
+            const needed = SESSION_RESOURCE_TRANSFER_CHUNK_BYTES - carry.byteLength;
+            const take = Math.min(needed, incoming.byteLength - cursor);
+            carry = carry.byteLength === 0
+                ? incoming.subarray(cursor, cursor + take)
+                : Buffer.concat([carry, incoming.subarray(cursor, cursor + take)]);
+            cursor += take;
+            if (carry.byteLength < SESSION_RESOURCE_TRANSFER_CHUNK_BYTES)
+                continue;
+            const written = await writeChunk(uploadId, remoteOffset, carry.toString("base64"));
+            if (written.offset !== remoteOffset + carry.byteLength) {
+                throw runtimeProtocolError("Runtime Session resource upload did not advance");
+            }
+            remoteOffset = written.offset;
+            carry = Buffer.alloc(0);
+        }
+    }
+    if (received !== expectedBytes) {
+        throw runtimeProtocolError("Resource upload ended before Content-Length");
+    }
+    if (carry.byteLength > 0) {
+        const written = await writeChunk(uploadId, remoteOffset, carry.toString("base64"));
+        if (written.offset !== remoteOffset + carry.byteLength) {
+            throw runtimeProtocolError("Runtime Session resource upload did not advance");
+        }
+        remoteOffset = written.offset;
+    }
+    if (remoteOffset !== expectedBytes) {
+        throw runtimeProtocolError("Runtime Session resource upload length changed");
+    }
+}
+function parseSingleByteRange(header, byteLength) {
+    if (!header)
+        return undefined;
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match || byteLength <= 0)
+        return "unsatisfiable";
+    const [, startText, endText] = match;
+    if (!startText && !endText)
+        return "unsatisfiable";
+    if (!startText) {
+        const suffix = Number(endText);
+        if (!Number.isSafeInteger(suffix) || suffix <= 0)
+            return "unsatisfiable";
+        return { start: Math.max(0, byteLength - suffix), end: byteLength - 1 };
+    }
+    const start = Number(startText);
+    const requestedEnd = endText ? Number(endText) : byteLength - 1;
+    if (!Number.isSafeInteger(start) ||
+        !Number.isSafeInteger(requestedEnd) ||
+        start < 0 ||
+        requestedEnd < start ||
+        start >= byteLength) {
+        return "unsatisfiable";
+    }
+    return { start, end: Math.min(requestedEnd, byteLength - 1) };
+}
+function contentDisposition(filename) {
+    if (!filename)
+        return "inline";
+    return `inline; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
 async function readBoundedBinary(ctx, maxBytes) {
     const declaredLength = Number(ctx.get("content-length"));
     if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {