hyperbrane 0.1.0 → 0.1.1

package/dist/cli/agent.js

@@ -375,7 +375,11 @@ export const sessionCommands = {
             args: ["AGENT/SESSION"],
             flags: {
                 limit: { type: "string", short: "n", value: "N", description: "How many messages, about (default 50)" },
-                before: { type: "string", value: "CURSOR", description: "The page before this cursor (printed after each page that has older ones)" },
+                before: {
+                    type: "string",
+                    value: "TIME",
+                    description: "Messages from before this time: ISO 8601 (2026-10-09T14:00:00Z, 2026-10-09), or how long ago (90s, 30m, 2h, 3d)",
+                },
             },
             async run([name], flags, { agents }) {
                 const limit = typeof flags.limit === "string" ? Number(flags.limit) : undefined;
@@ -383,14 +387,14 @@ export const sessionCommands = {
                     throw new UsageError(`--limit takes a positive number, not ${flags.limit}`);
                 const page = await agents.getTranscript(sessionRef(name), {
                     limit,
-                    cursor: typeof flags.before === "string" ? flags.before : undefined,
+                    before: typeof flags.before === "string" ? timeFlag(flags.before) : undefined,
                 });
                 const printer = createTerminalPrinter({ paced: false });
                 for (const { type, message } of page.messages)
                     printer.printTranscript(type, message.content);
                 printer.close();
-                if (page.nextCursor)
-                    process.stderr.write(`(older: hyperbrane session logs ${name} --before ${page.nextCursor})\n`);
+                if (page.nextBefore)
+                    process.stderr.write(`(older: hyperbrane session logs ${name} --before ${page.nextBefore})\n`);
             },
         },
         status: {
@@ -421,3 +425,12 @@ export const sessionCommands = {
         question: questionCommands,
     },
 };
+const AGO_UNITS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** --before's TIME as an ISO 8601 time: a date or time, or how long ago ("30m"). */
+function timeFlag(value) {
+    const ago = /^(\d+)([smhd])$/.exec(value);
+    const time = ago ? Date.now() - Number(ago[1]) * AGO_UNITS[ago[2]] : Date.parse(value);
+    if (Number.isNaN(time))
+        throw new UsageError(`--before takes a time (2026-10-09T14:00:00Z) or how long ago (2h), not ${value}`);
+    return new Date(time).toISOString();
+}

package/dist/cli/services.d.ts

@@ -4,12 +4,13 @@ import { type DockerClient } from "../lib/docker.ts";
 import type { Sandbox } from "../sandbox/api.ts";
 import { type GatewayService } from "../portal-gateway/gatewayService.ts";
 import { type PortalService } from "../portal-gateway/portalService.ts";
+/** @sealed */
 export type Services = {
-    docker: DockerClient;
-    dimensions: DimensionService;
-    gateways: GatewayService;
-    portals: PortalService;
-    agents: AgentService;
+    readonly docker: DockerClient;
+    readonly dimensions: DimensionService;
+    readonly gateways: GatewayService;
+    readonly portals: PortalService;
+    readonly agents: AgentService;
 };
 /**
  * Everything runs against `host`'s docker, with state in ~/.local/share/hyperbrane of its user: this

package/dist/dimension/api.d.ts

@@ -28,14 +28,15 @@ export type DimensionLimits = {
 };
 export type DimensionStatus = "creating" | "missing" | "created" | "running" | "paused" | "restarting" | "removing" | "exited" | "dead";
 export type DimensionInfo = Dimension & {
-    status: DimensionStatus;
+    readonly status: DimensionStatus;
     /** Null unless running. */
-    uptimeSeconds: number | null;
+    readonly uptimeSeconds: number | null;
     /** Bytes. Null unless running. */
-    memoryUsage: number | null;
+    readonly memoryUsage: number | null;
     /** Cores. Null unless running. */
-    cpuUsage: number | null;
+    readonly cpuUsage: number | null;
 };
+/** @sealed */
 export interface DimensionClient {
     /** POST /v1/dimensions */
     createDimension(dimension: Dimension): Promise<Dimension>;

package/dist/dimension/paths.d.ts

@@ -3,3 +3,7 @@ export declare const WORKSPACE_PATH = "/workspace";
 export declare const RUN_PATH = "/run/hyperbrane";
 /** Where the dimension's state directory (see Storage.ensureStateDirectory) is mounted. */
 export declare const STATE_PATH = "/var/lib/hyperbrane";
+/** On the host, under hyperbrane's data directory: a dimension's run directory, mounted at RUN_PATH. */
+export declare function dimensionRunDirectory(dataDirectory: string, dimensionName: string): string;
+/** On the host, under hyperbrane's data directory: a dimension's state directory, mounted at STATE_PATH. */
+export declare function dimensionStateDirectory(dataDirectory: string, dimensionName: string): string;

package/dist/dimension/paths.js

@@ -1,7 +1,15 @@
-// Where things are inside every dimension. Its own module so code running in a dimension (the agent
-// worker) can use them without the docker client service.ts brings along.
+// Where things are inside every dimension, and on the host. Its own module so code running in a
+// dimension (the agent worker) can use them without the docker client service.ts brings along.
 export const WORKSPACE_PATH = "/workspace";
 /** Where the dimension's run directory (see Storage.ensureRunDirectory) is mounted. */
 export const RUN_PATH = "/run/hyperbrane";
 /** Where the dimension's state directory (see Storage.ensureStateDirectory) is mounted. */
 export const STATE_PATH = "/var/lib/hyperbrane";
+/** On the host, under hyperbrane's data directory: a dimension's run directory, mounted at RUN_PATH. */
+export function dimensionRunDirectory(dataDirectory, dimensionName) {
+    return `${dataDirectory}/dimension-run/${dimensionName}`;
+}
+/** On the host, under hyperbrane's data directory: a dimension's state directory, mounted at STATE_PATH. */
+export function dimensionStateDirectory(dataDirectory, dimensionName) {
+    return `${dataDirectory}/dimension-state/${dimensionName}`;
+}

package/dist/dimension/service.d.ts

@@ -5,6 +5,7 @@ import type { DimensionImage } from "./image.ts";
 import type { Storage } from "./storage.ts";
 import { RUN_PATH, STATE_PATH, WORKSPACE_PATH } from "./paths.ts";
 export { RUN_PATH, STATE_PATH, WORKSPACE_PATH };
+/** @sealed */
 export interface DimensionService {
     getDimensions(): Promise<DimensionInfo[]>;
     /** The dimensions' names, from the records alone: none of getDimensions' container status and usage. */

package/dist/dimension/storage.js

@@ -1,6 +1,7 @@
 import { dirname } from "node:path";
 import { createJsonDirectory } from "../lib/jsonDirectory.js";
 import { SandboxNotFoundError } from "../sandbox/api.js";
+import { dimensionRunDirectory, dimensionStateDirectory } from "./paths.js";
 const EXTENSION = ".json";
 /**
  * `dir` is a sandbox path; defaults to ~/.local/share/hyperbrane/dimensions of the sandbox's user.
@@ -44,7 +45,7 @@ export function createFileStorage(sandbox, dir) {
         await sandbox.removeFile(await pathFor(dimensionName));
     }
     async function runDirectory(dimensionName) {
-        return `${dirname(await storageDir())}/dimension-run/${dimensionName}`;
+        return dimensionRunDirectory(dirname(await storageDir()), dimensionName);
     }
     async function ensureRunDirectory(dimensionName) {
         const path = await runDirectory(dimensionName);
@@ -55,7 +56,7 @@ export function createFileStorage(sandbox, dir) {
         await sandbox.removeDirectory(await runDirectory(dimensionName));
     }
     async function stateDirectory(dimensionName) {
-        return `${dirname(await storageDir())}/dimension-state/${dimensionName}`;
+        return dimensionStateDirectory(dirname(await storageDir()), dimensionName);
     }
     async function ensureStateDirectory(dimensionName) {
         const path = await stateDirectory(dimensionName);

package/dist/index.d.ts

@@ -10,9 +10,7 @@ export { BOAT_API_URL, BoatError, archiveBoatMachine, authorizeBoatSshKey, boatH
 export { parseAccessibleHost, proxyCredentialsAuth, type SandboxEndpointAuth, type SandboxEndpointsOptions } from "./sandbox/endpointProxy.ts";
 export { exeDevProxyAuth, type ExeDevAuthOptions } from "./sandbox/exeDevAuth.ts";
 export { EndpointLoginRequiredError, endpointRequest, exeDevLoginUrl, openSseConnection, type EndpointAccess } from "./sandbox/sseConnection.ts";
-export { createWorkerClient, type WorkerClient } from "./agent/session/client.ts";
-export { workerSseConnector, type WorkerEndpoint } from "./agent/session/workerSseConnection.ts";
-export { sharedConnector, type SharedConnector } from "./agent/session/sharedConnection.ts";
+export * from "./agent/client.ts";
 export { createDockerClient, DockerError, type DockerClient } from "./lib/docker.ts";
 export { BUILTIN_UPSTREAMS } from "./upstreams/index.ts";
 export { HYPERBRANE_VERSION } from "./lib/version.ts";

package/dist/index.js

@@ -1,5 +1,6 @@
-// The hyperbrane SDK's entry point: what an application drives a server with. Everything else is
-// reachable by its path too (`hyperbrane/sandbox/sshService`, ...).
+// The hyperbrane SDK's entry point: what an application drives a server with. The package exports
+// this and, for browsers (which can't take the server side along), each part's api and the worker
+// client: hyperbrane/{sandbox,dimension,portal-gateway,agent}/api, hyperbrane/agent/client.
 // The APIs: types, errors and helpers of each part.
 export * from "./sandbox/api.js";
 export * from "./dimension/api.js";
@@ -17,9 +18,7 @@ export { parseAccessibleHost, proxyCredentialsAuth } from "./sandbox/endpointPro
 export { exeDevProxyAuth } from "./sandbox/exeDevAuth.js";
 export { EndpointLoginRequiredError, endpointRequest, exeDevLoginUrl, openSseConnection } from "./sandbox/sseConnection.js";
 // An agent's worker, reached through its endpoint (AgentService.exposeAgent), from a server or a browser.
-export { createWorkerClient } from "./agent/session/client.js";
-export { workerSseConnector } from "./agent/session/workerSseConnection.js";
-export { sharedConnector } from "./agent/session/sharedConnection.js";
+export * from "./agent/client.js";
 export { createDockerClient, DockerError } from "./lib/docker.js";
 export { BUILTIN_UPSTREAMS } from "./upstreams/index.js";
 export { HYPERBRANE_VERSION } from "./lib/version.js";

package/dist/lib/docker.d.ts

@@ -34,6 +34,7 @@ export type BuildOptions = {
     context: Record<string, string>;
     labels?: Record<string, string>;
 };
+/** @sealed */
 export interface DockerClient {
     imageExists(image: string): Promise<boolean>;
     buildImage(options: BuildOptions): Promise<void>;

package/dist/portal-gateway/api.d.ts

@@ -18,10 +18,10 @@ export type Upstream = UpstreamDefinition;
  * with the key's fake, which is what a client in a dimension is given in place of the key.
  */
 export type GatewayCredential = {
-    name: string;
-    gatewayName: string;
-    type: "oauth" | "apiKey";
-    fake?: string;
+    readonly name: string;
+    readonly gatewayName: string;
+    readonly type: "oauth" | "apiKey";
+    readonly fake?: string;
 };
 /**
  * Applies to traffic arriving through the gateway's portals. "tcp://<address>:<port>" covers every
@@ -39,6 +39,7 @@ export type TrafficRule = {
     action: "BLOCK" | "DELAY" | "ASK" | "INTERCEPT";
     delayMs: number;
 };
+/** @sealed */
 export interface PortalGatewayClient {
     /** POST /v1/gateways — also replaces a container made from an older gateway image, keeping its state. */
     createGateway(gateway: Gateway): Promise<Gateway>;
@@ -63,7 +64,7 @@ export interface PortalGatewayClient {
      * to give the client in the dimension (e.g. as its API key env var) in place of the key.
      */
     setApiKey(gatewayName: string, upstreamName: string, keyName: string, key: string): Promise<{
-        fake: string;
+        readonly fake: string;
     }>;
     /** DELETE /v1/gateways/:gatewayName/upstreams/:upstreamName/api-keys/:keyName */
     deleteApiKey(gatewayName: string, upstreamName: string, keyName: string): Promise<void>;

package/dist/portal-gateway/gatewayService.d.ts

@@ -4,6 +4,7 @@ import { type Sandbox } from "../sandbox/api.ts";
 import { type Gateway, type GatewayCredential, type TrafficRule, type Upstream } from "./api.ts";
 import type { GatewayStorage } from "./gatewayStorage.ts";
 import type { PortalStorage } from "./portalStorage.ts";
+/** @sealed */
 export interface GatewayService {
     createGateway(gateway: Gateway): Promise<Gateway>;
     destroyGateway(gatewayName: string): Promise<void>;

package/dist/portal-gateway/portalService.d.ts

@@ -4,6 +4,7 @@ import type { Sandbox } from "../sandbox/api.ts";
 import { type Portal } from "./api.ts";
 import type { GatewayStorage } from "./gatewayStorage.ts";
 import type { PortalStorage } from "./portalStorage.ts";
+/** @sealed */
 export interface PortalService {
     createPortal(portal: Portal): Promise<Portal>;
     destroyPortal(portalName: string): Promise<void>;
@@ -38,6 +39,7 @@ export declare const OS_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
  * `image` is the gateway image: it carries the wiring script run by the privileged helper.
  */
 export declare function createPortalService(storage: PortalStorage, gateways: GatewayStorage, docker: DockerClient, image: ManagedImage, host: Sandbox): PortalService;
+/** @sealed */
 export interface PortalWatcher {
     /** Restores every portal, then keeps restoring those of each hyperbrane container that starts. */
     start(): void;

package/dist/sandbox/api.d.ts

@@ -5,14 +5,16 @@ export type RunCommandOptions = {
     stdin?: string | Uint8Array;
 };
 export type RunCommandResult = {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
 };
 export type SandboxFileInfo = {
-    type: "file" | "directory" | "other";
-    uid: number;
-    gid: number;
+    readonly type: "file" | "directory" | "other";
+    readonly uid: number;
+    readonly gid: number;
+    /** In bytes; what the system reports for anything that isn't a file. */
+    readonly size: number;
 };
 export type SandboxFetchInit = {
     method?: string;
@@ -27,7 +29,11 @@ export type SandboxFetchInit = {
      */
     timeout?: number | false;
 };
-/** A stream connection to a unix socket inside a sandbox (see Sandbox.connect). */
+/**
+ * A stream connection to a unix socket inside a sandbox (see Sandbox.connect).
+ *
+ * @sealed
+ */
 export type SandboxConnection = {
     write(data: Uint8Array): void;
     /** Receives every chunk read from the socket, in order. */
@@ -49,14 +55,14 @@ export type SandboxEndpointTarget = {
 export type SandboxEndpointCredentials = 
 /** `Authorization: Bearer <token>`. */
 {
-    scheme: "bearer";
-    token: string;
+    readonly scheme: "bearer";
+    readonly token: string;
 }
 /** `Authorization: Basic ...`; browsers prompt for it on their own. */
  | {
-    scheme: "basic";
-    username: string;
-    password: string;
+    readonly scheme: "basic";
+    readonly username: string;
+    readonly password: string;
 }
 /**
  * Logged in with exe.dev, as a user the VM is shared with; exe.dev's proxy checks it (exeDevAuth.ts).
@@ -64,8 +70,8 @@ export type SandboxEndpointCredentials =
  * first (exeDevLoginUrl in agent/session/workerSseConnection.ts).
  */
  | {
-    scheme: "exe.dev";
-    loginUrl: string;
+    readonly scheme: "exe.dev";
+    readonly loginUrl: string;
 };
 export type SandboxEndpointScheme = SandboxEndpointCredentials["scheme"];
 export type SandboxEndpointRequest = {
@@ -88,24 +94,31 @@ export type SandboxEndpointRequest = {
     allowedOrigins?: string[];
 };
 export type SandboxEndpoint = {
-    id: string;
+    readonly id: string;
     /**
      * Where the client reaches the endpoint, directly over the network (not through the backend's own
      * connection), at the host the sandbox was created with.
      */
-    url: string;
+    readonly url: string;
     /** What the client presents; requests without it are refused before reaching the target. */
-    credentials: SandboxEndpointCredentials;
+    readonly credentials: SandboxEndpointCredentials;
     /** As requested: fixed for the endpoint's life. */
-    allowedOrigins: string[];
+    readonly allowedOrigins: string[];
 };
 /**
  * Paths are sandbox paths: relative or absolute, both resolved against the sandbox root.
  * Operations that report a missing path throw SandboxNotFoundError, whatever the backend.
+ *
+ * @sealed
  */
 export interface SandboxFileOperations {
     /** Throws SandboxNotFoundError if missing. */
     readFile(path: string): Promise<Uint8Array>;
+    /**
+     * Bytes `start` up to `end` (exclusive) of the file, fewer where the file ends sooner, so a large
+     * file can be read a part at a time. Throws SandboxNotFoundError if missing.
+     */
+    readFileRange(path: string, start: number, end: number): Promise<Uint8Array>;
     /** Atomically replaces the file (readers never see partial content). Creates missing parent directories. */
     writeFile(path: string, data: string | Uint8Array): Promise<void>;
     /**
@@ -126,10 +139,15 @@ export interface SandboxFileOperations {
     /** Sandbox path of the home directory of the user operations run as. */
     homeDirectory(): Promise<string>;
 }
+/** @sealed */
 export interface SandboxCommands {
     runCommand(cmd: string[], options?: RunCommandOptions): Promise<RunCommandResult>;
 }
-/** Reaching into the sandbox from the caller's side. */
+/**
+ * Reaching into the sandbox from the caller's side.
+ *
+ * @sealed
+ */
 export interface SandboxNetwork {
     /** HTTP request made from inside the sandbox. */
     fetch(url: string, init?: SandboxFetchInit): Promise<Response>;
@@ -142,6 +160,8 @@ export interface SandboxNetwork {
  * clients reach it at), by the backends that can. Always authenticated: a scheme the sandbox's auth
  * can't enforce is refused with SandboxEndpointError. An endpoint lasts until it is closed, past the
  * sandbox object that exposed it.
+ *
+ * @sealed
  */
 export interface SandboxAccessibleEndpoint {
     /**
@@ -158,7 +178,11 @@ export interface SandboxAccessibleEndpoint {
      */
     ensureEndpoint(endpointId: string): Promise<boolean>;
 }
-/** A sandbox that stops itself on a timer (Boat). */
+/**
+ * A sandbox that stops itself on a timer (Boat).
+ *
+ * @sealed
+ */
 export interface SandboxExpiration {
     /** When it stops itself; null if it never does. */
     getExpiration(): Promise<Date | null>;
@@ -167,7 +191,11 @@ export interface SandboxExpiration {
 }
 /** Whether the sandbox has the SandboxExpiration capability. */
 export declare function hasExpiration<T extends object>(sandbox: T): sandbox is T & SandboxExpiration;
-/** What every backend provides. */
+/**
+ * What every backend provides.
+ *
+ * @sealed
+ */
 export type Sandbox = SandboxFileOperations & SandboxCommands & SandboxNetwork & {
     /** Releases what the sandbox holds open (a remote connection). Optional: most hold nothing. */
     close?(): void;

package/dist/sandbox/boatService.js

@@ -103,6 +103,13 @@ export function createBoatSandbox(api, sandboxId, { proxyPort = DEFAULT_PROXY_PO
             throw error;
         }
     }
+    // Boat's file call reads whole files only.
+    async function readFileRange(path, start, end) {
+        const target = full(path);
+        const result = await sh(`[ -e "$1" ] || exit ${NOT_FOUND}; tail -c +$(($2 + 1)) -- "$1" | head -c "$3" | base64 -w0`, target, String(start), String(Math.max(0, end - start)));
+        check(result, "read", target);
+        return new Uint8Array(Buffer.from(result.stdout, "base64"));
+    }
     /**
      * Uploads `data`, copies it beside `target` (creating its directory) and runs `publish` on the copy
      * ($3) and the target ($2), so readers never see part of it.
@@ -140,11 +147,11 @@ export function createBoatSandbox(api, sandboxId, { proxyPort = DEFAULT_PROXY_PO
         return result.stdout.split("\n").filter(Boolean);
     }
     async function stat(path) {
-        const result = await sh(`[ -e "$1" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%F' -- "$1"`, full(path));
+        const result = await sh(`[ -e "$1" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%s:%F' -- "$1"`, full(path));
         check(result, "stat", full(path));
-        const [uid = "", gid = "", kind = ""] = result.stdout.trim().split(":");
+        const [uid = "", gid = "", size = "", kind = ""] = result.stdout.trim().split(":");
         const type = kind === "directory" ? "directory" : kind.startsWith("regular") ? "file" : "other";
-        return { type, uid: Number(uid), gid: Number(gid) };
+        return { type, uid: Number(uid), gid: Number(gid), size: Number(size) };
     }
     let home = null;
     function homeDirectory() {
@@ -233,6 +240,7 @@ export function createBoatSandbox(api, sandboxId, { proxyPort = DEFAULT_PROXY_PO
         getExpiration,
         setExpiration,
         readFile,
+        readFileRange,
         writeFile,
         writeFileExclusive,
         removeFile,

package/dist/sandbox/containerService.js

@@ -38,6 +38,12 @@ export function createContainerSandbox(docker, container, { user } = {}) {
         const result = check(await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; base64 -w0 -- "$P"`, { P: full }), "read", full);
         return new Uint8Array(Buffer.from(result.stdout, "base64"));
     }
+    async function readFileRange(path, start, end) {
+        const full = containerPath(path);
+        const script = `[ -e "$P" ] || exit ${NOT_FOUND}; tail -c +$(($S + 1)) -- "$P" | head -c "$L" | base64 -w0`;
+        const result = check(await sh(script, { P: full, S: String(start), L: String(Math.max(0, end - start)) }), "read", full);
+        return new Uint8Array(Buffer.from(result.stdout, "base64"));
+    }
     /**
      * Extracts `data` next to `full` under a unique hidden name, handed to the sandbox user, and runs
      * `publish` (as root, with $T the temp file and $F the target) to move it into place.
@@ -81,10 +87,10 @@ export function createContainerSandbox(docker, container, { user } = {}) {
     }
     async function stat(path) {
         const full = containerPath(path);
-        const result = check(await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%F' -- "$P"`, { P: full }), "stat", full);
-        const [uid = "", gid = "", kind = ""] = result.stdout.trim().split(":");
+        const result = check(await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%s:%F' -- "$P"`, { P: full }), "stat", full);
+        const [uid = "", gid = "", size = "", kind = ""] = result.stdout.trim().split(":");
         const type = kind === "directory" ? "directory" : kind.startsWith("regular") ? "file" : "other";
-        return { type, uid: Number(uid), gid: Number(gid) };
+        return { type, uid: Number(uid), gid: Number(gid), size: Number(size) };
     }
     // docker exec doesn't always set HOME for a numeric user, so ask the user database.
     async function homeDirectory() {
@@ -136,6 +142,7 @@ export function createContainerSandbox(docker, container, { user } = {}) {
     }
     return {
         readFile,
+        readFileRange,
         writeFile,
         writeFileExclusive,
         removeFile,

package/dist/sandbox/localService.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { link, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { link, mkdir, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { request as httpRequest } from "node:http";
 import { createConnection } from "node:net";
 import { homedir } from "node:os";
@@ -36,6 +36,23 @@ export function createLocalSandbox(root, { endpoints } = {}) {
     async function readFileLocal(path) {
         return new Uint8Array(await notFoundAs(path, readFile(hostPath(path))));
     }
+    async function readFileRangeLocal(path, start, end) {
+        const file = await notFoundAs(path, open(hostPath(path), "r"));
+        try {
+            const buffer = new Uint8Array(Math.max(0, end - start));
+            let filled = 0;
+            while (filled < buffer.length) {
+                const { bytesRead } = await file.read(buffer, filled, buffer.length - filled, start + filled);
+                if (bytesRead === 0)
+                    break;
+                filled += bytesRead;
+            }
+            return buffer.subarray(0, filled);
+        }
+        finally {
+            await file.close();
+        }
+    }
     async function writeFileLocal(path, data) {
         const full = hostPath(path);
         await rename(await writeTemp(full, data), full);
@@ -72,7 +89,7 @@ export function createLocalSandbox(root, { endpoints } = {}) {
     async function statLocal(path) {
         const stats = await notFoundAs(path, stat(hostPath(path)));
         const type = stats.isFile() ? "file" : stats.isDirectory() ? "directory" : "other";
-        return { type, uid: stats.uid, gid: stats.gid };
+        return { type, uid: stats.uid, gid: stats.gid, size: stats.size };
     }
     async function homeDirectory() {
         const rel = relative(base, homedir());
@@ -112,6 +129,7 @@ export function createLocalSandbox(root, { endpoints } = {}) {
     }
     const sandbox = {
         readFile: readFileLocal,
+        readFileRange: readFileRangeLocal,
         writeFile: writeFileLocal,
         writeFileExclusive,
         removeFile,

package/dist/sandbox/sshService.js

@@ -5,6 +5,7 @@ import { createProxyEndpoints } from "./endpointProxy.js";
 import { socketConnection } from "./localService.js";
 /** SFTP status codes (draft-ietf-secsh-filexfer-02). */
 const SFTP_NO_SUCH_FILE = 2;
+const SFTP_EOF = 1;
 /**
  * Commands running at once on the connection. sshd refuses sessions past its MaxSessions (10 by
  * default) per connection, and counts a closed one until it has cleaned up after it, so this stays
@@ -181,6 +182,30 @@ export function createSshSandbox(host, options) {
         const data = await sftpCall("read", full, (channel, done) => channel.readFile(full, done));
         return new Uint8Array(data);
     }
+    async function sftpReadFileRange(path, start, end) {
+        const full = remotePath(path);
+        const channel = await sftp();
+        const handle = await sftpCall("read", full, (sftpChannel, done) => sftpChannel.open(full, "r", done));
+        try {
+            const buffer = Buffer.alloc(Math.max(0, end - start));
+            let filled = 0;
+            while (filled < buffer.length) {
+                const read = await new Promise((resolve, reject) => channel.read(handle, buffer, filled, buffer.length - filled, start + filled, (error, bytesRead) => {
+                    // The end of the file comes as an EOF status rather than a short read.
+                    if (error && error.code !== SFTP_EOF)
+                        return reject(new Error(`read ${full} on ${host} failed: ${error.message}`));
+                    resolve(error ? 0 : bytesRead);
+                }));
+                if (read === 0)
+                    break;
+                filled += read;
+            }
+            return new Uint8Array(buffer.subarray(0, filled));
+        }
+        finally {
+            channel.close(handle, () => { });
+        }
+    }
     /** Writes `data` to a unique hidden file next to `full` (creating its directory) and returns its path. */
     async function writeTemp(full, data) {
         await createDirectory(posix.dirname(full));
@@ -268,7 +293,7 @@ export function createSshSandbox(host, options) {
     async function sftpStat(path) {
         const info = await statOf(remotePath(path));
         const type = info.isDirectory() ? "directory" : info.isFile() ? "file" : "other";
-        return { type, uid: info.uid, gid: info.gid };
+        return { type, uid: info.uid, gid: info.gid, size: info.size };
     }
     // SFTP starts in the user's home directory. Asked once: storage paths start from it on every call.
     let home = null;
@@ -301,6 +326,12 @@ export function createSshSandbox(host, options) {
             checkShell(result, "read", full);
             return new Uint8Array(result.stdout);
         },
+        async readFileRange(full, start, end) {
+            const script = `[ -e "$P" ] || exit ${NOT_FOUND}; tail -c +$(($S + 1)) -- "$P" | head -c "$L"`;
+            const result = await runBytes(commandLine(["sh", "-c", script], { P: full, S: String(start), L: String(Math.max(0, end - start)) }));
+            checkShell(result, "read", full);
+            return new Uint8Array(result.stdout);
+        },
         /** Streams `data` into a temp file beside `full`, then runs `publish` ($T the temp file, $F the target). */
         writeVia(full, data, publish) {
             const tmp = posix.join(posix.dirname(full), `.${posix.basename(full)}.${crypto.randomUUID()}.tmp`);
@@ -329,11 +360,11 @@ export function createSshSandbox(host, options) {
             return result.stdout.split("\n").filter(Boolean);
         },
         async stat(full) {
-            const result = await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%F' -- "$P"`, { P: full });
+            const result = await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%s:%F' -- "$P"`, { P: full });
             checkShell(result, "stat", full);
-            const [uid = "", gid = "", kind = ""] = result.stdout.trim().split(":");
+            const [uid = "", gid = "", size = "", kind = ""] = result.stdout.trim().split(":");
             const type = kind === "directory" ? "directory" : kind.startsWith("regular") ? "file" : "other";
-            return { type, uid: Number(uid), gid: Number(gid) };
+            return { type, uid: Number(uid), gid: Number(gid), size: Number(size) };
         },
         // sshd always sets HOME for the session.
         async homeDirectory() {
@@ -343,6 +374,7 @@ export function createSshSandbox(host, options) {
         },
     };
     const readFile = async (path) => ((await sftpAvailable()) ? sftpReadFile(path) : shell.readFile(remotePath(path)));
+    const readFileRange = async (path, start, end) => (await sftpAvailable()) ? sftpReadFileRange(path, start, end) : shell.readFileRange(remotePath(path), start, end);
     const writeFile = async (path, data) => (await sftpAvailable()) ? sftpWriteFile(path, data) : shell.writeFile(remotePath(path), data);
     const writeFileExclusive = async (path, data) => (await sftpAvailable()) ? sftpWriteFileExclusive(path, data) : shell.writeFileExclusive(remotePath(path), data);
     const removeFile = async (path) => ((await sftpAvailable()) ? sftpRemoveFile(path) : shell.removeFile(remotePath(path)));
@@ -592,6 +624,7 @@ export function createSshSandbox(host, options) {
     }
     const sandbox = {
         readFile,
+        readFileRange,
         writeFile,
         writeFileExclusive,
         removeFile,