@rynx-ai/server 0.1.11-beta.3 → 0.1.11-beta.30

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";
@@ -19,6 +20,7 @@ import { parseRuntimeBrowserStateGetParams } from "@rynx-ai/protocol/runtime-bro
 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;
@@ -724,6 +726,30 @@ export function createControlRouter(opts) {
         if (outcome.ok)
             ctx.body = outcome.result;
     };
+    const runtimeSessionExecutionSettings = async (ctx) => {
+        const outcome = await runtimeCall(ctx, "session.execution.get", {
+            sessionId: ctx.params.id,
+        });
+        if (outcome.ok)
+            ctx.body = outcome.result;
+    };
+    const runtimeSessionExecutionSettingsUpdate = async (ctx) => {
+        const body = await readRuntimeBody(ctx);
+        if (!body)
+            return;
+        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;
+    };
     const runtimeSessionCreate = async (ctx) => {
         const body = await readRuntimeBody(ctx);
         if (!body)
@@ -834,7 +860,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 = "";
@@ -847,7 +879,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) {
@@ -855,23 +889,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;
@@ -879,9 +911,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 {
@@ -898,16 +928,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 })
@@ -915,44 +947,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 {
@@ -968,7 +1028,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,
@@ -1012,16 +1072,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);
@@ -1029,48 +1105,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) => {
@@ -1094,6 +1190,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)
@@ -1714,6 +2047,8 @@ export function createControlRouter(opts) {
     router.get("/api/runtimes/:selector/sessions/launch-options", publicRuntimeRead(runtimeSessionLaunchOptions));
     router.post("/api/runtimes/:selector/sessions", publicRuntimeMutation(runtimeSessionCreate));
     router.post("/api/runtimes/:selector/sessions/:id/fork", publicRuntimeMutation(runtimeSessionFork));
+    router.get("/api/runtimes/:selector/sessions/:id/execution", publicRuntimeRead(runtimeSessionExecutionSettings));
+    router.put("/api/runtimes/:selector/sessions/:id/execution", publicRuntimeMutation(runtimeSessionExecutionSettingsUpdate));
     router.get("/api/runtimes/:selector/sessions/:id/snapshot", publicRuntimeRead(runtimeSessionSnapshot));
     router.get("/api/runtimes/:selector/sessions/:id/snapshot-page", publicRuntimeRead(runtimeSessionSnapshotPage));
     router.get("/api/runtimes/:selector/sessions/:id/stream", publicRuntimeRead(runtimeSessionStream));
@@ -1723,6 +2058,11 @@ 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));
@@ -2711,6 +3051,14 @@ export function createControlRouter(opts) {
     router.get("/api/agents", async (ctx) => {
         ctx.body = { agents: await deps.listAgents() };
     });
+    router.get("/api/agents/runtime-options", async (ctx) => {
+        if (!deps.listAgentRuntimeOptions)
+            return notFound(ctx, "local runtime discovery is unavailable");
+        ctx.set("Cache-Control", "no-store");
+        ctx.body = {
+            runtimes: await deps.listAgentRuntimeOptions({ refresh: asString(ctx.query.refresh) === "1" }),
+        };
+    });
     router.get("/api/agents/:id", async (ctx) => {
         const spec = await deps.getAgent(ctx.params.id);
         if (!spec)
@@ -2723,6 +3071,11 @@ export function createControlRouter(opts) {
         if (!id)
             return bad(ctx, "missing agent id");
         try {
+            if (await deps.getAgent(id)) {
+                ctx.status = 409;
+                ctx.body = { error: "agent id already exists" };
+                return;
+            }
             deps.writeAgent(id, body);
         }
         catch (error) {
@@ -2730,6 +3083,19 @@ export function createControlRouter(opts) {
         }
         ctx.body = { ok: true };
     });
+    router.put("/api/agents/:id", async (ctx) => {
+        const id = ctx.params.id;
+        const body = await readJson(ctx);
+        if (!await deps.getAgent(id))
+            return notFound(ctx, "agent not found");
+        try {
+            deps.writeAgent(id, { ...body, id });
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+        ctx.body = { ok: true };
+    });
     router.delete("/api/agents/:id", (ctx) => {
         ctx.body = { ok: deps.removeAgent(ctx.params.id) };
     });
@@ -2769,6 +3135,64 @@ export function createControlRouter(opts) {
             return bad(ctx, error instanceof Error ? error.message : String(error));
         }
     });
+    router.post("/api/skills/local-scan", async (ctx) => {
+        if (!deps.scanLocalSkills)
+            return notFound(ctx, "local Skill discovery is unavailable");
+        const body = await readJson(ctx);
+        const runtime = parseProviderCliId(body.runtime);
+        if (!runtime)
+            return bad(ctx, "runtime must be codex, traex, or claude");
+        try {
+            ctx.body = { candidates: await deps.scanLocalSkills(runtime) };
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    });
+    router.post("/api/skills/local-import", async (ctx) => {
+        if (!deps.importLocalSkills)
+            return notFound(ctx, "local Skill import is unavailable");
+        const body = await readJson(ctx);
+        const runtime = parseProviderCliId(body.runtime);
+        const rawKeys = Array.isArray(body.keys) ? body.keys : [];
+        const keys = rawKeys.length > 0
+            ? rawKeys.filter((value) => typeof value === "string" && value.length > 0)
+            : [];
+        if (!runtime)
+            return bad(ctx, "runtime must be codex, traex, or claude");
+        if (keys.length === 0 || keys.length !== rawKeys.length || keys.length > 100) {
+            return bad(ctx, "keys must contain 1-100 non-empty candidate keys");
+        }
+        try {
+            ctx.body = { results: await deps.importLocalSkills(runtime, keys) };
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    });
+    router.post("/api/skills/import-archive", async (ctx) => {
+        if (!deps.importSkillArchive)
+            return notFound(ctx, "Skill archive import is unavailable");
+        let body;
+        try {
+            body = await readJson(ctx, 29 * 1024 * 1024);
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+        const filename = asString(body.filename);
+        const contentBase64 = asString(body.contentBase64);
+        if (!filename || !contentBase64)
+            return bad(ctx, "filename and contentBase64 are required");
+        if (contentBase64.length > 28 * 1024 * 1024)
+            return bad(ctx, "archive payload is too large");
+        try {
+            ctx.body = { results: await deps.importSkillArchive(filename, contentBase64) };
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    });
     router.delete("/api/skills/:name", async (ctx) => {
         try {
             ctx.body = { ok: await deps.removeSkill(ctx.params.name) };
@@ -3107,12 +3531,16 @@ export function createControlRouter(opts) {
         const body = await readJson(ctx);
         const agent = asString(body.agent);
         const provider = asString(body.provider);
+        const permissionPreset = parseSessionPermissionPreset(body.permissionPreset);
         if (body.config != null) {
             return bad(ctx, "inline Agent configs are no longer supported; save an Agent first");
         }
         if (Boolean(agent) === Boolean(provider)) {
             return bad(ctx, "provide exactly one Agent or Provider");
         }
+        if (body.permissionPreset !== undefined && !permissionPreset) {
+            return bad(ctx, "permissionPreset must be default, read-only, workspace-write, or full-access");
+        }
         try {
             ctx.body = await localMachineSessions.create({
                 ...(agent ? { agent } : { provider: provider }),
@@ -3120,6 +3548,7 @@ export function createControlRouter(opts) {
                 ...(asString(body.reasoningEffort)
                     ? { reasoningEffort: asString(body.reasoningEffort) }
                     : {}),
+                ...(permissionPreset ? { permissionPreset } : {}),
                 ...(asString(body.title) ? { title: asString(body.title) } : {}),
                 ...(asString(body.projectId) ? { projectId: asString(body.projectId) } : {}),
             });
@@ -3140,7 +3569,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;
         }
@@ -3159,26 +3601,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
@@ -3399,11 +3846,28 @@ export function synthesizeSessionTitle(message, limit = 60) {
         return collapsed;
     return `${collapsed.slice(0, limit - 1).trimEnd()}…`;
 }
-async function readJson(ctx) {
+async function readJson(ctx, maxBytes) {
     const raw = await new Promise((resolve, reject) => {
         let data = "";
-        ctx.req.on("data", (chunk) => (data += chunk));
-        ctx.req.on("end", () => resolve(data));
+        let bytes = 0;
+        let exceeded = false;
+        ctx.req.on("data", (chunk) => {
+            if (exceeded)
+                return;
+            bytes += typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.byteLength;
+            if (maxBytes !== undefined && bytes > maxBytes) {
+                exceeded = true;
+                data = "";
+                return;
+            }
+            data += chunk;
+        });
+        ctx.req.on("end", () => {
+            if (exceeded)
+                reject(new Error("request body is too large"));
+            else
+                resolve(data);
+        });
         ctx.req.on("error", reject);
     });
     if (!raw.trim())
@@ -3424,6 +3888,14 @@ function parseProviderCliId(value) {
         ? value
         : undefined;
 }
+function parseSessionPermissionPreset(value) {
+    return value === "default" ||
+        value === "read-only" ||
+        value === "workspace-write" ||
+        value === "full-access"
+        ? value
+        : undefined;
+}
 function parseProviderCliOperation(value) {
     return value === "install" || value === "update" ? value : undefined;
 }
@@ -3439,6 +3911,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") {
@@ -3542,6 +4022,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) => {
@@ -3762,8 +4272,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 }),
     };
 }
@@ -3851,6 +4367,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) {