eve-hub 0.14.4 → 0.14.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # eve-hub
 
+## 0.14.6
+
+### Patch Changes
+
+- New `fetch_upload` tool: a bot copies a file another bot shared as a `hub://upload/<id>` link into its sandbox (for example a patch to `git apply`), with the hub credential its kit tools already send. A shell can't fetch these links: the hosted hub's Deployment Protection sends it to a login page.
+
+## 0.14.5
+
+### Patch Changes
+
+- Mac bots' bash and read_file work again on eve 0.83.3: HostSandbox speaks eve's connection-based sandbox API (eve derives the session; `/workspace` and `~` still map to the bot's root and the user's home). The sandbox hook no longer deletes the host sandbox each turn; eve itself starts fresh when a session's recorded sandbox came from another provider.
+
 ## 0.14.4
 
 ### Patch Changes

package/bash-run.mjs

@@ -241,7 +241,7 @@ export function selfStopRefusal(command, env = process.env) {
 export async function runBash(sandbox, { command, timeoutSeconds }, { hostRoot, code = workspaceCode(), graceMs = KILL_GRACE_MS, env = process.env } = {}) {
   const selfStop = selfStopRefusal(command, env);
   if (selfStop) return { exitCode: 1, stdout: "", stderr: selfStop, truncated: false };
-  const linked = linkedInstallTargets(command, sandbox.root ?? hostRoot);
+  const linked = linkedInstallTargets(command, sandbox.root?.() ?? hostRoot);
   if (linked.length) {
     const lines = linked.map(({ dir, target }) => `${join(dir, "node_modules")} -> ${target}`);
     return {

package/fork-env.mjs

@@ -9,19 +9,22 @@ import { registryFetch, sandboxRegistry } from "./registry-fetch.mjs";
 
 const TTL_MS = 3000;
 
+// A fork's config, or null once the registry says the session isn't a fork
+// (404). Any other answer throws and isn't cached: eve fixes a session's root
+// when it opens the connection, so a guess of "no fork" would pin a fork to the
+// shared checkout.
 export function createForkEnv({ registry = sandboxRegistry(), fetchImpl = globalThis.fetch, now = Date.now } = {}) {
   const cache = new Map(); // sessionId -> { config, at }
   return async function lookup(sessionId) {
     if (registry === null) return null; // no local hub: no forks
     const hit = cache.get(sessionId);
     if (hit && now() - hit.at < TTL_MS) return hit.config;
-    let config = null;
-    try {
-      const res = await registryFetch(`/api/sandbox/session-config/${encodeURIComponent(sessionId)}`, {}, { base: registry, fetchImpl });
-      if (res.ok) config = await res.json();
-    } catch {}
-    cache.set(sessionId, { config: config?.root ? config : null, at: now() });
-    return config?.root ? config : null;
+    const res = await registryFetch(`/api/sandbox/session-config/${encodeURIComponent(sessionId)}`, {}, { base: registry, fetchImpl });
+    if (res.status !== 404 && !res.ok) throw new Error(`fork config for ${sessionId}: HTTP ${res.status}`);
+    const body = res.ok ? await res.json() : null;
+    const config = body?.root ? body : null;
+    cache.set(sessionId, { config, at: now() });
+    return config;
   };
 }
 

package/hooks/sandbox.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("eve/hooks").HookDefinition<"turn.started">;
+declare const _default: import("eve/hooks").HookDefinition<never>;
 export default _default;

package/hooks/sandbox.js

@@ -1,17 +1,6 @@
 import { defineHook } from "eve/hooks";
-// Retire Docker sandboxes recorded by sessions created before the host sandbox.
+// Once retired Docker sandboxes recorded by sessions created before the host
+// sandbox. eve now does that itself: a session whose recorded sandbox came
+// from another provider starts a fresh one. Kept so existing bot stubs load.
 // Turn reporting is owned by the registry's eve stream consumer, not hooks.
-export default defineHook({
-    events: {
-        async "turn.started"(_event, ctx) {
-            try {
-                const sandbox = await ctx.getSandbox();
-                if (sandbox.resolvePath("/workspace") === "/workspace")
-                    await sandbox.delete();
-            }
-            catch (error) {
-                console.warn("[roster] sandbox migration skipped", error);
-            }
-        },
-    },
-});
+export default defineHook({ events: {} });

package/host-sandbox.d.ts

@@ -1,17 +1,18 @@
 import { type ChildProcess } from "node:child_process";
 import type { SandboxSession } from "eve/sandbox";
+import { type SandboxConnection, type SandboxProvider, type WithPrepareOption } from "eve/sandbox/provider";
 interface HostOptions {
     readonly root?: string;
 }
 type HostArtifact = {
     readonly root: string;
 };
-interface HostState {
+type HostState = {
     readonly root: string;
     readonly version: 1;
     readonly worktree?: SessionWorktree;
     readonly rootSessionId?: string;
-}
+};
 interface SessionRef {
     readonly id: string;
     readonly parent?: {
@@ -19,11 +20,20 @@ interface SessionRef {
         readonly sessionId?: string;
     };
 }
-interface SessionWorktree {
+type SessionWorktree = {
     readonly path: string;
     readonly branch: string;
     readonly repo: string;
+};
+export interface HostExtensions {
+    root(): string;
+    description(): string;
+    readonly worktree?: SessionWorktree;
 }
+export type HostConnection = SandboxConnection<HostExtensions> & {
+    readonly workspaceRoot: string;
+    ready(): Promise<void>;
+};
 export declare const HOST_ROOT: string;
 export declare function hostEnvironment(options?: HostOptions): {
     prepare(): Promise<{
@@ -32,42 +42,19 @@ export declare function hostEnvironment(options?: HostOptions): {
     start(ctx: {
         session: SessionRef;
     }, _open: unknown, artifact: HostArtifact): Promise<{
-        handle: {
-            sandbox: SandboxSession & {
-                description: string;
-                root: string;
-                worktree?: SessionWorktree;
-            };
-            onRuntimeShutdown: () => Promise<void>;
-            onSandboxStop: () => Promise<void>;
-            onSandboxDelete: () => Promise<void>;
-        };
+        connection: HostConnection;
         state: HostState;
     }>;
     resume(ctx: {
         session: SessionRef;
-    }, _artifact: unknown, state: HostState): Promise<{
-        sandbox: SandboxSession & {
-            description: string;
-            root: string;
-            worktree?: SessionWorktree;
-        };
-        onRuntimeShutdown: () => Promise<void>;
-        onSandboxStop: () => Promise<void>;
-        onSandboxDelete: () => Promise<void>;
-    }>;
-};
-export declare const HostSandbox: import("eve/sandbox/provider").SandboxProvider<HostOptions, undefined, SandboxSession>;
-export declare function hostHandle(rootOrState: string | HostState, sessionId: string): {
-    sandbox: SandboxSession & {
-        description: string;
-        root: string;
-        worktree?: SessionWorktree;
-    };
-    onRuntimeShutdown: () => Promise<void>;
-    onSandboxStop: () => Promise<void>;
-    onSandboxDelete: () => Promise<void>;
+    }, _artifact: unknown, state: HostState): Promise<HostConnection>;
+    onSessionEnd(ctx: {
+        session: SessionRef;
+    }): Promise<void>;
 };
+type HostSession = SandboxSession & HostExtensions;
+export declare const HostSandbox: SandboxProvider<WithPrepareOption<HostOptions, HostSession>, undefined, HostSession>;
+export declare function hostConnection(rootOrState: string | HostState, sessionId: string): Promise<HostConnection>;
 export declare function killTree(child: ChildProcess): void;
 declare const forkConfig: (sessionId: string) => Promise<{
     root: string;
@@ -116,9 +103,5 @@ export declare function hostSession(baseRoot: string, children: Set<ChildProcess
     rootSessionId?: string;
     lookup?: typeof forkConfig;
     guard?: Fence | ((what: string) => Promise<void>);
-}): SandboxSession & {
-    description: string;
-    root: string;
-    worktree?: SessionWorktree;
-};
+}): HostConnection;
 export {};

package/host-sandbox.js

@@ -1,15 +1,15 @@
 // A sandbox provider that is the host machine itself: commands run in the
 // user's real shell and files are the user's real files. `/workspace` maps
-// to `root` (default ~/wrk); other absolute paths and `~` pass through.
+// to `root` (default ~/wrk), `~` to the user's home; other absolute paths
+// pass through.
 //
 // There is no isolation. Every bot using this can do anything the user can.
 import { execFile, spawn as spawnChild } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { request as httpRequest } from "node:http";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { Readable } from "node:stream";
 import { promisify } from "node:util";
 import { defineSandboxProvider } from "eve/sandbox/provider";
@@ -31,7 +31,7 @@ export function hostEnvironment(options) {
             const rootSessionId = ctx.session.parent?.rootSessionId;
             const worktree = await sessionWorktree(ctx.session.id, rootSessionId);
             const state = { ...(worktree ? { root: worktree.path, worktree } : { root: artifact.root }), version: 1, ...(rootSessionId ? { rootSessionId } : {}) };
-            return { handle: hostHandle(state, ctx.session.id), state };
+            return { connection: await hostConnection(state, ctx.session.id), state };
         },
         async resume(ctx, _artifact, state) {
             // Asked again: the registry restores a worktree whose directory went
@@ -41,10 +41,16 @@ export function hostEnvironment(options) {
             const next = { ...(worktree ? { ...state, root: worktree.path, worktree } : state), ...(rootSessionId ? { rootSessionId } : {}) };
             if (!worktree)
                 await mkdir(next.root, { recursive: true }); // never fake a missing worktree with an empty dir
-            return hostHandle(next, ctx.session.id);
+            return hostConnection(next, ctx.session.id);
+        },
+        // The session is over (or its sandbox deleted): stop what it still runs.
+        // The files are the user's own and stay.
+        async onSessionEnd(ctx) {
+            await stopSession(ctx.session.id);
         },
     };
 }
+// Annotated: the inferred type names eve's internal session module, which the published .d.ts can't reference (TS2883).
 export const HostSandbox = defineSandboxProvider({
     name: "host",
     environment: hostEnvironment,
@@ -109,23 +115,35 @@ async function sessionWorktree(sessionId, rootSessionId) {
         await new Promise((r) => setTimeout(r, 300));
     }
 }
-// A root path (the shared checkout; tests call it this way) or a session's state.
-export function hostHandle(rootOrState, sessionId) {
-    const { root, worktree, rootSessionId } = typeof rootOrState === "string" ? { root: rootOrState, worktree: undefined, rootSessionId: undefined } : rootOrState;
-    const children = new Set();
-    const killAll = async () => {
+// A session's processes, shared by every connection eve opens to it (eve
+// reconnects for each step), so stop() and session end reach all of them.
+const sessionChildren = new Map();
+const childrenOf = (sessionId) => {
+    let children = sessionChildren.get(sessionId);
+    if (!children)
+        sessionChildren.set(sessionId, (children = new Set()));
+    return children;
+};
+async function stopSession(sessionId, children = sessionChildren.get(sessionId)) {
+    if (children) {
         for (const child of children)
             killTree(child);
         children.clear();
         liveSessions.delete(children);
-        await closeBrowser(sessionId);
-    };
-    return {
-        sandbox: hostSession(root, children, sessionId, { worktree, rootSessionId }),
-        onRuntimeShutdown: killAll,
-        onSandboxStop: killAll,
-        onSandboxDelete: killAll,
-    };
+    }
+    if (sessionChildren.get(sessionId) === children)
+        sessionChildren.delete(sessionId);
+    await closeBrowser(sessionId);
+}
+// A root path (the shared checkout; tests call it this way) or a session's
+// state. Resolves once a fork's root is known, since eve reads workspaceRoot
+// once, when it opens the connection: a failed fork lookup rejects here rather
+// than anchor the connection at the shared checkout.
+export async function hostConnection(rootOrState, sessionId) {
+    const { root, worktree, rootSessionId } = typeof rootOrState === "string" ? { root: rootOrState, worktree: undefined, rootSessionId: undefined } : rootOrState;
+    const connection = hostSession(root, childrenOf(sessionId), sessionId, { worktree, rootSessionId });
+    await connection.ready();
+    return connection;
 }
 // SIGTERM the whole process group; whatever ignores it gets SIGKILL after
 // KILL_AFTER_MS, so a timed-out or stopped command can't linger.
@@ -598,6 +616,9 @@ const killGroup = (pid) => {
 // `guard`: a Fence (ownershipGuard) that admits every op with a ticket, or a
 // plain `(what) => Promise<void>` that is asked before each op instead, with
 // no tickets at all (tests stand in an unguarded sandbox this way).
+// Returns eve's byte-level connection: eve derives the session (resolvePath,
+// run, the text and binary helpers) from it, anchoring relative paths at
+// workspaceRoot, so every path that arrives here is absolute.
 export function hostSession(baseRoot, children, sessionId, { worktree, rootSessionId, lookup = forkConfig, guard = ownershipGuard(sessionId, { rootSessionId }), } = {}) {
     let root = baseRoot;
     let forkEnv = {};
@@ -626,19 +647,19 @@ export function hostSession(baseRoot, children, sessionId, { worktree, rootSessi
             if (forkEnv[dir])
                 await mkdir(forkEnv[dir], { recursive: true });
     };
-    // Resolved when the session's sandbox is created; re-checked before each
-    // command and file op (cheap, cached), since a fork can be retired.
-    void ready().catch(() => { });
-    const resolvePath = (path) => {
+    // eve hands over `/workspace/...` as is, and a model's `~/x` anchored at the
+    // root (`<root>/~/x`).
+    const hostPath = (path) => {
         if (path === "/workspace" || path.startsWith("/workspace/"))
             return join(root, path.slice("/workspace".length));
-        if (path === "~" || path.startsWith("~/"))
-            return join(homedir(), path.slice(1));
-        return isAbsolute(path) ? path : join(root, path);
+        const home = join(root, "~");
+        if (path === home || path.startsWith(`${home}/`))
+            return join(homedir(), path.slice(home.length));
+        return path;
     };
     const spawn = async ({ command, workingDirectory, env, abortSignal }) => {
         await ready();
-        const cwd = resolvePath(workingDirectory ?? root);
+        const cwd = hostPath(workingDirectory);
         // Paused first: nothing of the user's runs until the ticket is granted.
         const { child, go } = spawnPaused(process.env.SHELL ?? "/bin/bash", command, cwd, { ...process.env, ...env, ...forkEnv });
         await new Promise((ok, fail) => {
@@ -705,17 +726,6 @@ export function hostSession(baseRoot, children, sessionId, { worktree, rootSessi
             kill: async () => killTree(child),
         };
     };
-    const readBinary = async (path) => {
-        await ready();
-        try {
-            return new Uint8Array(await readFile(resolvePath(path)));
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                return null;
-            throw error;
-        }
-    };
     // The effect runs under the ticket and the ticket is released with how it went.
     const fenced = async (ticket, effect) => {
         try {
@@ -730,7 +740,7 @@ export function hostSession(baseRoot, children, sessionId, { worktree, rootSessi
     };
     const write = async (path, bytes) => {
         await ready();
-        const target = resolvePath(path);
+        const target = hostPath(path);
         const sha256 = createHash("sha256").update(bytes).digest("hex");
         const ticket = await admit("write", { path: target, sha256 }, `write ${path}`);
         await fenced(ticket, async () => {
@@ -739,63 +749,49 @@ export function hostSession(baseRoot, children, sessionId, { worktree, rootSessi
         });
     };
     return {
-        // Read by the bash tool (bash-run.mjs): where this session's commands run.
-        get root() {
+        ready,
+        // Read once, when eve opens the connection; start/resume wait for ready().
+        get workspaceRoot() {
             return root;
         },
-        ...(worktree ? { worktree } : {}),
-        get description() {
-            const shell = `The host machine's own shell (${process.platform}), not an isolated sandbox.`;
-            const tail = "You have the user's full environment, credentials, and filesystem, so be deliberate with anything destructive.";
-            if (forkEnv.ROSTER_FORK)
-                return `${shell} The working directory is ${root}; /workspace maps to it. This session is fork ${forkEnv.ROSTER_FORK}: commands default to its worktree with PORT=${forkEnv.PORT} and fork-local build/cache dirs. ${tail}`;
-            if (worktree)
-                return `${shell} The working directory is ${root}: a git worktree of ${worktree.repo} on branch ${worktree.branch}, private to this thread; /workspace maps to it. Do this thread's work in ${worktree.repo} here, not in ${worktree.repo} itself (other threads use that checkout). Other paths are the user's real files. ${tail}`;
-            return `${shell} The working directory is ${root}; /workspace maps to it. ${tail}`;
+        extensions: {
+            // Read by the bash tool (bash-run.mjs): where this session's commands run.
+            root: () => root,
+            ...(worktree ? { worktree } : {}),
+            description: () => {
+                const shell = `The host machine's own shell (${process.platform}), not an isolated sandbox.`;
+                const tail = "You have the user's full environment, credentials, and filesystem, so be deliberate with anything destructive.";
+                if (forkEnv.ROSTER_FORK)
+                    return `${shell} The working directory is ${root}; /workspace maps to it. This session is fork ${forkEnv.ROSTER_FORK}: commands default to its worktree with PORT=${forkEnv.PORT} and fork-local build/cache dirs. ${tail}`;
+                if (worktree)
+                    return `${shell} The working directory is ${root}: a git worktree of ${worktree.repo} on branch ${worktree.branch}, private to this thread; /workspace maps to it. Do this thread's work in ${worktree.repo} here, not in ${worktree.repo} itself (other threads use that checkout). Other paths are the user's real files. ${tail}`;
+                return `${shell} The working directory is ${root}; /workspace maps to it. ${tail}`;
+            },
         },
-        resolvePath,
         spawn,
-        async run(options) {
-            const proc = await spawn(options);
-            const [stdout, stderr, { exitCode }] = await Promise.all([
-                new Response(proc.stdout).text(),
-                new Response(proc.stderr).text(),
-                proc.wait(),
-            ]);
-            return { exitCode, stdout, stderr };
-        },
         async readFile({ path }) {
             await ready();
-            const target = resolvePath(path);
             try {
-                await stat(target);
+                return new Uint8Array(await readFile(hostPath(path)));
             }
-            catch {
-                return null;
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
             }
-            return Readable.toWeb(createReadStream(target));
-        },
-        readBinaryFile: ({ path }) => readBinary(path),
-        async readTextFile({ path, encoding = "utf-8", startLine, endLine }) {
-            const bytes = await readBinary(path);
-            if (bytes === null)
-                return null;
-            const text = Buffer.from(bytes).toString(encoding);
-            if (startLine === undefined && endLine === undefined)
-                return text;
-            const lines = text.split("\n");
-            return lines.slice((startLine ?? 1) - 1, endLine ?? lines.length).join("\n");
         },
-        async writeFile({ path, content }) {
-            await write(path, new Uint8Array(await new Response(content).arrayBuffer()));
+        async writeFiles({ files }) {
+            for (const file of files)
+                await write(file.path, file.content);
         },
-        writeBinaryFile: ({ path, content }) => write(path, content),
-        writeTextFile: ({ path, content, encoding = "utf-8" }) => write(path, new Uint8Array(Buffer.from(content, encoding))),
         async removePath({ path, force, recursive }) {
             await ready();
-            const target = resolvePath(path);
+            const target = hostPath(path);
             const ticket = await admit("delete", { path: target, ...(recursive === undefined ? {} : { recursive }), ...(force === undefined ? {} : { force }) }, `remove ${path}`);
             await fenced(ticket, () => rm(target, { force, recursive }));
         },
+        // Releases compute: the session's processes and its browser. Also what
+        // eve calls on every open connection when the runtime shuts down.
+        stop: () => stopSession(sessionId, children),
     };
 }

package/kit-modules.json

@@ -23,6 +23,7 @@
   "tools/create_thread",
   "tools/dash_update",
   "tools/disabled",
+  "tools/fetch_upload",
   "tools/list_agents",
   "tools/list_threads",
   "tools/move_path",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.14.4",
+  "version": "0.14.6",
   "license": "Apache-2.0",
   "description": "Bot-side code shared by every hub agent: registry tools, the roster hook, the eve channel, the host sandbox and browser, and model helpers.",
   "type": "module",

package/stubs.mjs

@@ -10,6 +10,7 @@ export const KIT_FILES = {
   "tools/react.ts": ["React to a message with an emoji."],
   "tools/show.ts": ["Move the human's screen to a thread, DM, or message, or open a page or file beside the thread."],
   "tools/browser.ts": ["Its own headless browser, watched live in the Computer view."],
+  "tools/fetch_upload.ts": ["Copies a file another bot shared (hub://upload/<id>) into the sandbox."],
   "tools/view_image.ts": ["Shows the bot an image (a sandbox file or a browser screenshot) so it can see it."],
   "tools/update_thread.ts": ["Update a thread this bot is in: title, track, domain and summary."],
   "tools/list_threads.ts": ["Every workspace thread, from any session."],
@@ -57,7 +58,7 @@ export const DEPLOYED_KIT_FILES = new Set([
   "schedules/dash.ts",
   "skills/onboarding-profile.ts",
   "tools/onboarding_scripts.ts",
-  ...["react", "show", "update_thread", "list_threads", "read_thread", "post_message"].map((t) => `tools/${t}.ts`),
+  ...["react", "show", "fetch_upload", "update_thread", "list_threads", "read_thread", "post_message"].map((t) => `tools/${t}.ts`),
   "memory/team.ts",
   "skills/forms.ts",
   ...["create_thread", "set_summary", "move_path", "archive_thread", "unarchive_thread", "list_agents", "create_agent", "remove_agent", "restart_agent", "tag_threads", "dash_update", "apply_tags"].map((t) => `tools/${t}.ts`),

package/tools/bash.js

@@ -27,6 +27,6 @@ export default defineTool({
     async execute(input, ctx) {
         // HostSandbox exposes the session's real root (its thread worktree, if any).
         const sandbox = await ctx.getSandbox();
-        return runBash(sandbox, input, { hostRoot: sandbox.root ?? HOST_ROOT, code: workspaceCode() });
+        return runBash(sandbox, input, { hostRoot: sandbox.root?.() ?? HOST_ROOT, code: workspaceCode() });
     },
 });

package/tools/fetch_upload.d.ts

@@ -0,0 +1,18 @@
+declare const _default: import("eve/tools").ToolDefinition<{
+    uri: string;
+    path?: string | undefined;
+}, {
+    path: string;
+    size: number;
+    mediaType: string | null;
+}> & {
+    execute(input: {
+        uri: string;
+        path?: string | undefined;
+    }, ctx: import("eve/tools").ToolContext): Promise<{
+        path: string;
+        size: number;
+        mediaType: string | null;
+    }>;
+};
+export default _default;

package/tools/fetch_upload.js

@@ -0,0 +1,40 @@
+// The `fetch_upload` tool: copies a file another bot shared (`hub://upload/<id>`, what
+// `show(path)` returns on a hosted hub) into this bot's sandbox, e.g. a patch to `git apply`.
+// A shell can't fetch it: the hosted hub's Deployment Protection and its auth take only the bot
+// credential that registryFetch sends (registry-fetch.mjs).
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { registryFetch } from "../registry-fetch.mjs";
+const UPLOAD = /^hub:\/\/upload\/([0-9a-f]{64}\.[a-z0-9]{1,10})$/;
+export default defineTool({
+    description: "Fetch a file another bot shared as a hub://upload/<id> link (e.g. a patch, a log, a brief) into your sandbox, then read or apply it there. Your shell can't fetch these links; this tool sends your hub credential. Returns the path it wrote, the size in bytes and the media type.",
+    inputSchema: z.object({
+        uri: z.string().describe("The hub://upload/<id> link."),
+        path: z.string().optional().describe("Where to write it in your sandbox. Default /tmp/uploads/<id>."),
+    }),
+    async execute({ uri, path }, ctx) {
+        const id = UPLOAD.exec(uri.trim())?.[1];
+        if (!id)
+            throw new Error(`not a hub://upload/<id> link: ${uri}`);
+        // A redirect is Deployment Protection sending the request to a login page: an error, not the file.
+        const res = await registryFetch(`/api/uploads/${id}`, { redirect: "manual", signal: AbortSignal.timeout(30_000) });
+        if (!res.ok) {
+            const text = await res.text();
+            // Deployment Protection answers with a whole HTML page: name the redirect, or keep the body short.
+            const error = (() => { try {
+                return JSON.parse(text).error;
+            }
+            catch {
+                return undefined;
+            } })();
+            const location = res.headers.get("location");
+            const why = error ?? (location ? `redirected to ${location}` : text.slice(0, 200));
+            throw new Error(`fetch_upload failed: ${res.status} ${why}`.trim());
+        }
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        const sandbox = await ctx.getSandbox();
+        const target = path ?? `/tmp/uploads/${id}`;
+        await sandbox.writeBinaryFile({ path: target, content: bytes });
+        return { path: sandbox.resolvePath(target), size: bytes.length, mediaType: res.headers.get("content-type") };
+    },
+});