hyperbrane 0.1.0

package/dist/cli/streamPrinter.js

@@ -0,0 +1,251 @@
+/** Longest a tool input or result is shown, in characters. */
+const PREVIEW_LENGTH = 400;
+/** The pacer's clock: about a frame. */
+const TICK_MS = 16;
+/** Deltas arriving this close together are one burst. */
+const BURST_GAP_MS = 20;
+/** How far back the arrival rate is measured. */
+const RATE_WINDOW_MS = 2_000;
+/** The time a lone first burst is spread over, before there's a rate to go by. */
+const FIRST_BURST_MS = 300;
+/** Typing runs this much faster than text arrives, so the buffer drains rather than grows. */
+const CATCH_UP = 1.1;
+/** The slowest the pacer types, in characters per ms. */
+const MIN_RATE = 0.06;
+/** No character waits longer than this to be typed, whatever the pace. */
+const MAX_LAG_MS = 1_000;
+const DIM = "\x1b[2m";
+const NORMAL = "\x1b[22m";
+export function preview(value) {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    return text.length > PREVIEW_LENGTH ? `${text.slice(0, PREVIEW_LENGTH)}…` : text;
+}
+/**
+ * Writes to `stream`, switching styles as text changes between answer and thinking: dimmed on a
+ * terminal, marked with [thinking] otherwise. Thinking always ends on a line of its own.
+ */
+function createStyledWriter(stream) {
+    const tty = stream.isTTY === true;
+    let style = "text";
+    function switchTo(next) {
+        if (next === style)
+            return;
+        if (next === "thinking")
+            stream.write(tty ? DIM : "[thinking] ");
+        else
+            stream.write(tty ? `${NORMAL}\n\n` : "\n\n");
+        style = next;
+    }
+    return {
+        text(chunk, next) {
+            switchTo(next);
+            stream.write(chunk);
+        },
+        line(chunk) {
+            switchTo("text");
+            stream.write(chunk);
+        },
+    };
+}
+/** Writes everything at once, as it comes. */
+function createDirectOutput(stream) {
+    const writer = createStyledWriter(stream);
+    return { text: writer.text, line: writer.line, close: () => writer.line("") };
+}
+/**
+ * Types text out at a steady pace instead of in the bursts it arrives in (model APIs send several
+ * words at once, then pause for a while): at the rate text has been arriving, a little faster, so
+ * each burst lasts until about when the next one comes, and never more than MAX_LAG_MS behind. A
+ * pause shows only when the model pauses for longer than that. Lines wait for the text before
+ * them, then go out whole.
+ */
+function createPacedOutput(stream) {
+    const writer = createStyledWriter(stream);
+    const queue = [];
+    /** Recent bursts: when each came, and how many characters. */
+    const bursts = [];
+    let waitingChars = 0;
+    /** Characters the pace has allowed but not yet typed (fractions carry over between ticks). */
+    let credit = 0;
+    let lastTick = 0;
+    let timer;
+    function recordArrival(chars) {
+        const now = performance.now();
+        const last = bursts.at(-1);
+        if (last && now - last.at < BURST_GAP_MS)
+            last.chars += chars;
+        else
+            bursts.push({ at: now, chars });
+        while (bursts.length > 1 && now - bursts[0].at > RATE_WINDOW_MS)
+            bursts.shift();
+    }
+    /**
+     * Characters per ms the text has been arriving at: the bursts before the newest over the time they
+     * span up to it, since the newest is what covers the time ahead. A lone burst is spread over
+     * FIRST_BURST_MS.
+     */
+    function arrivalRate() {
+        if (bursts.length < 2)
+            return (bursts[0]?.chars ?? 0) / FIRST_BURST_MS;
+        const earlier = bursts.slice(0, -1).reduce((sum, burst) => sum + burst.chars, 0);
+        return earlier / (bursts.at(-1).at - bursts[0].at);
+    }
+    /**
+     * The least that keeps every waiting chunk within MAX_LAG_MS, spread evenly over the ticks left
+     * rather than all at once when it's due: for each chunk, the characters up to its end over the
+     * ticks until its deadline. Only matters when text arrives faster than the rate predicted.
+     */
+    function deadlinePace() {
+        const now = performance.now();
+        let before = 0;
+        let pace = 0;
+        for (const segment of queue) {
+            if (segment.kind !== "text")
+                continue;
+            before += segment.chars.length;
+            const ticksLeft = Math.max(1, Math.floor((segment.arrivedAt + MAX_LAG_MS - now) / TICK_MS));
+            pace = Math.max(pace, Math.ceil(before / ticksLeft));
+        }
+        return pace;
+    }
+    function tick() {
+        const now = performance.now();
+        // A late tick (a busy event loop) catches up, but not by more than a few frames at once.
+        credit += Math.max(MIN_RATE, arrivalRate() * CATCH_UP) * Math.min(now - lastTick, TICK_MS * 4);
+        lastTick = now;
+        let budget = Math.max(Math.floor(credit), deadlinePace());
+        const planned = budget;
+        while (queue.length > 0) {
+            const segment = queue[0];
+            if (segment.kind === "line") {
+                writer.line(segment.text);
+                queue.shift();
+                continue;
+            }
+            if (budget === 0)
+                break;
+            const taken = segment.chars.splice(0, budget);
+            budget -= taken.length;
+            waitingChars -= taken.length;
+            writer.text(taken.join(""), segment.style);
+            if (segment.chars.length === 0)
+                queue.shift();
+        }
+        credit = Math.max(0, credit - (planned - budget));
+        if (queue.length === 0)
+            stop();
+    }
+    function start() {
+        if (timer)
+            return;
+        lastTick = performance.now();
+        timer = setInterval(tick, TICK_MS);
+    }
+    // Nothing is banked while idle: the next burst paces from zero instead of coming out at once.
+    function stop() {
+        clearInterval(timer);
+        timer = undefined;
+        credit = 0;
+    }
+    function text(chunk, style) {
+        // Code points, so a character outside the BMP is never split across ticks.
+        const chars = [...chunk];
+        queue.push({ kind: "text", style, chars, arrivedAt: performance.now() });
+        waitingChars += chars.length;
+        recordArrival(chars.length);
+        start();
+    }
+    function line(chunk) {
+        queue.push({ kind: "line", text: chunk });
+        start();
+    }
+    function close() {
+        stop();
+        for (const segment of queue) {
+            if (segment.kind === "line")
+                writer.line(segment.text);
+            else
+                writer.text(segment.chars.join(""), segment.style);
+        }
+        queue.length = 0;
+        waitingChars = 0;
+        writer.line("");
+    }
+    return { text, line, close };
+}
+/**
+ * A message's content as a terminal transcript: the user's words as "> ...", tool calls and their
+ * results on lines of their own, and the assistant's text and thinking when `withText` (a stream has
+ * already printed them as partial output).
+ */
+function printContent(output, role, content, withText) {
+    if (typeof content === "string") {
+        if (role === "user")
+            output.line(`\n> ${content}\n`);
+        else if (withText)
+            output.text(`${content}\n`, "text");
+        return;
+    }
+    if (!Array.isArray(content))
+        return;
+    for (const block of content) {
+        if (block.type === "text" && role === "user")
+            output.line(`\n> ${block.text}\n`);
+        if (block.type === "text" && role === "assistant" && withText)
+            output.text(`${block.text}\n`, "text");
+        if (block.type === "thinking" && withText && block.thinking)
+            output.text(`${block.thinking}\n`, "thinking");
+        if (block.type === "tool_use")
+            output.line(`\n[${block.name}] ${preview(block.input)}\n`);
+        if (block.type === "tool_result")
+            output.line(`[result${block.is_error ? ", error" : ""}] ${preview(block.content ?? "")}\n`);
+    }
+}
+/**
+ * Prints to `stream` (stdout); `paced` text is typed out steadily (see createPacedOutput) when it's
+ * a terminal. A complete assistant message's text is printed only if none of it streamed: claude
+ * reports failures it hits before reaching the API (a TLS error, say) as a synthetic message.
+ */
+export function createTerminalPrinter({ paced, stream = process.stdout }) {
+    const output = paced && stream.isTTY ? createPacedOutput(stream) : createDirectOutput(stream);
+    let streamed = false;
+    function print(message) {
+        switch (message.type) {
+            case "stream_event": {
+                if (message.event.type !== "content_block_delta")
+                    return;
+                const { delta } = message.event;
+                if (delta.type === "text_delta")
+                    output.text(delta.text, "text");
+                else if (delta.type === "thinking_delta")
+                    output.text(delta.thinking, "thinking");
+                else
+                    return;
+                streamed = true;
+                return;
+            }
+            case "assistant":
+                printContent(output, "assistant", message.message.content, !streamed);
+                streamed = false;
+                return;
+            case "user":
+                return printContent(output, "user", message.message.content, false);
+            case "result":
+                if (message.subtype !== "success")
+                    output.line(`\n[${message.subtype}] ${message.errors.join("; ")}\n`);
+                else if (message.is_error)
+                    output.line(`\n[error] ${message.result}\n`);
+                else
+                    output.line("\n[done]\n");
+                return;
+            case "system":
+                output.line(`[session ${message.session_id}, model ${message.model}]\n`);
+                return;
+        }
+    }
+    return {
+        print,
+        printTranscript: (role, content) => printContent(output, role, content, true),
+        close: output.close,
+    };
+}

package/dist/cli/table.d.ts

@@ -0,0 +1,7 @@
+export declare function formatTable(headers: string[], rows: string[][]): string;
+/** 268435456 -> "256MiB", 1597440 -> "1.523MiB" (docker's units.BytesSize). */
+export declare function formatBytes(bytes: number): string;
+/** 0.0512 cores -> "5.12%" (docker stats' CPU %: 100% is one full core). */
+export declare function formatCpuPercent(cores: number): string;
+/** Seconds -> "3 minutes", "About an hour", ... (docker's units.HumanDuration). */
+export declare function formatDuration(seconds: number): string;

package/dist/cli/table.js

@@ -0,0 +1,54 @@
+// Output in the style of the docker CLI (its tabwriter: min width 10, padding 3).
+const MIN_WIDTH = 10;
+const PADDING = 3;
+export function formatTable(headers, rows) {
+    const widths = headers.map((header, column) => Math.max(MIN_WIDTH, ...[header, ...rows.map((row) => row[column] ?? "")].map((cell) => cell.length + PADDING)));
+    return [headers, ...rows]
+        .map((row) => row
+        .map((cell, column) => (column === row.length - 1 ? cell : cell.padEnd(widths[column])))
+        .join("")
+        .trimEnd())
+        .join("\n");
+}
+const BYTE_UNITS = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
+/** 268435456 -> "256MiB", 1597440 -> "1.523MiB" (docker's units.BytesSize). */
+export function formatBytes(bytes) {
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < BYTE_UNITS.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${Number(value.toPrecision(4))}${BYTE_UNITS[unit]}`;
+}
+/** 0.0512 cores -> "5.12%" (docker stats' CPU %: 100% is one full core). */
+export function formatCpuPercent(cores) {
+    return `${(cores * 100).toFixed(2)}%`;
+}
+/** Seconds -> "3 minutes", "About an hour", ... (docker's units.HumanDuration). */
+export function formatDuration(seconds) {
+    const minutes = seconds / 60;
+    const hours = minutes / 60;
+    const days = hours / 24;
+    if (seconds < 1)
+        return "Less than a second";
+    if (seconds === 1)
+        return "1 second";
+    if (seconds < 60)
+        return `${Math.floor(seconds)} seconds`;
+    if (Math.floor(minutes) === 1)
+        return "About a minute";
+    if (minutes < 60)
+        return `${Math.floor(minutes)} minutes`;
+    if (Math.round(hours) === 1)
+        return "About an hour";
+    if (hours < 48)
+        return `${Math.round(hours)} hours`;
+    if (days < 7 * 2)
+        return `${Math.floor(days)} days`;
+    if (days < 30 * 2)
+        return `${Math.floor(days / 7)} weeks`;
+    if (days < 365 * 2)
+        return `${Math.floor(days / 30)} months`;
+    return `${Math.floor(days / 365)} years`;
+}

package/dist/dimension/api.d.ts

@@ -0,0 +1,67 @@
+export type MemoryLimit = number & {
+    readonly __brand: "MemoryLimit";
+};
+export type CPULimit = number & {
+    readonly __brand: "CPULimit";
+};
+/** Bytes. Accepts "512", "10M", "1.5G", "10Mi", "10MB", "10MiB" (binary units, like docker). */
+export declare function MemoryLimit(value: string): MemoryLimit;
+/** Cores. Accepts "2", "0.5", or kubernetes-style millicores "500m". */
+export declare function CPULimit(value: string): CPULimit;
+export type Dimension = {
+    name: string;
+    /**
+     * The host directory mounted as its workspace. Relative ("work", "~/work") is the host user's,
+     * under their home: resolved when the dimension is created, and recorded resolved. Made (by the
+     * host user) if it doesn't exist.
+     */
+    directory: string;
+    memoryLimit: MemoryLimit;
+    cpuLimit: CPULimit;
+    portals?: string[];
+};
+/** "creating": provisioning in progress. "missing": recorded but no container (retry create). Otherwise docker's container state. */
+/** What `updateDimension` can change on a running dimension; omitted limits stay as they are. */
+export type DimensionLimits = {
+    memoryLimit?: MemoryLimit;
+    cpuLimit?: CPULimit;
+};
+export type DimensionStatus = "creating" | "missing" | "created" | "running" | "paused" | "restarting" | "removing" | "exited" | "dead";
+export type DimensionInfo = Dimension & {
+    status: DimensionStatus;
+    /** Null unless running. */
+    uptimeSeconds: number | null;
+    /** Bytes. Null unless running. */
+    memoryUsage: number | null;
+    /** Cores. Null unless running. */
+    cpuUsage: number | null;
+};
+export interface DimensionClient {
+    /** POST /v1/dimensions */
+    createDimension(dimension: Dimension): Promise<Dimension>;
+    /** DELETE /v1/dimensions/:dimensionName */
+    destroyDimension(dimensionName: string): Promise<void>;
+    /** POST /v1/dimensions/:dimensionName/restart */
+    restartDimension(dimensionName: string): Promise<void>;
+    /** PATCH /v1/dimensions/:dimensionName — changes its limits in place, without a restart. */
+    updateDimension(dimensionName: string, limits: DimensionLimits): Promise<Dimension>;
+    /** GET /v1/dimensions */
+    listDimensions(): Promise<DimensionInfo[]>;
+}
+/** The request can't be satisfied as sent (bad directory, ...). */
+export declare class DimensionInvalidError extends Error {
+    name: string;
+}
+/** No dimension (or no container for it) by that name. */
+export declare class DimensionNotFoundError extends Error {
+    name: string;
+}
+/** The name is taken by a dimension with a different spec, or by a container hyperbrane doesn't own. */
+export declare class DimensionConflictError extends Error {
+    name: string;
+}
+export declare class DimensionApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare function createDimensionClient(baseUrl: string): DimensionClient;

package/dist/dimension/api.js

@@ -0,0 +1,81 @@
+const MEMORY_UNITS = {
+    "": 1,
+    K: 1024,
+    M: 1024 ** 2,
+    G: 1024 ** 3,
+    T: 1024 ** 4,
+};
+/** Bytes. Accepts "512", "10M", "1.5G", "10Mi", "10MB", "10MiB" (binary units, like docker). */
+export function MemoryLimit(value) {
+    const match = /^(\d+(?:\.\d+)?)\s*([KMGT]?)(?:iB|i|B)?$/i.exec(value.trim());
+    if (!match)
+        throw new Error(`Invalid memory limit: "${value}"`);
+    const bytes = Math.round(Number(match[1]) * MEMORY_UNITS[match[2].toUpperCase()]);
+    if (bytes <= 0)
+        throw new Error(`Memory limit must be positive: "${value}"`);
+    return bytes;
+}
+/** Cores. Accepts "2", "0.5", or kubernetes-style millicores "500m". */
+export function CPULimit(value) {
+    const match = /^(\d+(?:\.\d+)?)\s*(m?)$/.exec(value.trim());
+    if (!match)
+        throw new Error(`Invalid CPU limit: "${value}"`);
+    const cores = match[2] === "m" ? Number(match[1]) / 1000 : Number(match[1]);
+    if (cores <= 0)
+        throw new Error(`CPU limit must be positive: "${value}"`);
+    return cores;
+}
+/** The request can't be satisfied as sent (bad directory, ...). */
+export class DimensionInvalidError extends Error {
+    name = "DimensionInvalidError";
+}
+/** No dimension (or no container for it) by that name. */
+export class DimensionNotFoundError extends Error {
+    name = "DimensionNotFoundError";
+}
+/** The name is taken by a dimension with a different spec, or by a container hyperbrane doesn't own. */
+export class DimensionConflictError extends Error {
+    name = "DimensionConflictError";
+}
+export class DimensionApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "DimensionApiError";
+    }
+}
+export function createDimensionClient(baseUrl) {
+    async function request(method, path, body) {
+        const res = await fetch(new URL(path, baseUrl), {
+            method,
+            headers: body === undefined ? undefined : { "content-type": "application/json" },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (res.ok)
+            return res;
+        const text = await res.text();
+        let message = text;
+        try {
+            message = JSON.parse(text).error ?? text;
+        }
+        catch { }
+        throw new DimensionApiError(res.status, `${method} ${path} -> ${res.status}: ${message}`);
+    }
+    async function createDimension(dimension) {
+        return (await request("POST", "/v1/dimensions", dimension)).json();
+    }
+    async function destroyDimension(dimensionName) {
+        await request("DELETE", `/v1/dimensions/${encodeURIComponent(dimensionName)}`);
+    }
+    async function restartDimension(dimensionName) {
+        await request("POST", `/v1/dimensions/${encodeURIComponent(dimensionName)}/restart`);
+    }
+    async function listDimensions() {
+        return (await request("GET", "/v1/dimensions")).json();
+    }
+    async function updateDimension(dimensionName, limits) {
+        return (await request("PATCH", `/v1/dimensions/${encodeURIComponent(dimensionName)}`, limits)).json();
+    }
+    return { createDimension, destroyDimension, restartDimension, listDimensions, updateDimension };
+}

package/dist/dimension/http.d.ts

@@ -0,0 +1,7 @@
+import { type DimensionService } from "./service.ts";
+export interface DimensionHttpServer {
+    /** Resolves with the URL the server is listening on (useful with port 0). */
+    start(): Promise<URL>;
+    stop(): Promise<void>;
+}
+export declare function createDimensionHttpServer(service: DimensionService, port: number): DimensionHttpServer;

package/dist/dimension/http.js

@@ -0,0 +1,77 @@
+import { DimensionConflictError, DimensionInvalidError, DimensionNotFoundError, } from "./api.js";
+import { createDockerClient } from "../lib/docker.js";
+import { createLocalSandbox } from "../sandbox/localService.js";
+import { createDimensionImage } from "./image.js";
+import { createDimensionService } from "./service.js";
+import { createFileStorage } from "./storage.js";
+export function createDimensionHttpServer(service, port) {
+    let server;
+    async function handleListDimensions() {
+        return Response.json(await service.getDimensions());
+    }
+    async function handleCreateDimension(req) {
+        // TODO: add validation with proper JSON reply
+        const dimension = (await req.json());
+        await service.createDimension(dimension);
+        return Response.json(dimension, { status: 201 });
+    }
+    async function handleDestroyDimension(req) {
+        await service.destroyDimension(req.params.dimensionName);
+        return new Response(null, { status: 204 });
+    }
+    async function handleUpdateDimension(req) {
+        const limits = (await req.json());
+        return Response.json(await service.updateDimension(req.params.dimensionName, limits));
+    }
+    async function handleRestartDimension(req) {
+        await service.restartDimension(req.params.dimensionName);
+        return new Response(null, { status: 204 });
+    }
+    function handleNotFound() {
+        return new Response("Not Found", { status: 404 });
+    }
+    function handleError(error) {
+        if (error instanceof DimensionInvalidError)
+            return Response.json({ error: error.message }, { status: 400 });
+        if (error instanceof DimensionConflictError)
+            return Response.json({ error: error.message }, { status: 409 });
+        if (error instanceof DimensionNotFoundError)
+            return Response.json({ error: error.message }, { status: 404 });
+        console.error(error);
+        return Response.json({ error: error.message }, { status: 500 });
+    }
+    async function start() {
+        server = Bun.serve({
+            port,
+            routes: {
+                "/v1/dimensions": {
+                    GET: handleListDimensions,
+                    POST: handleCreateDimension,
+                },
+                "/v1/dimensions/:dimensionName": {
+                    DELETE: handleDestroyDimension,
+                    PATCH: handleUpdateDimension,
+                },
+                "/v1/dimensions/:dimensionName/restart": {
+                    POST: handleRestartDimension,
+                },
+            },
+            fetch: handleNotFound,
+            error: handleError,
+        });
+        console.log(`dimension service listening on ${server.url}`);
+        return server.url;
+    }
+    async function stop() {
+        await server?.stop();
+        server = undefined;
+    }
+    return { start, stop };
+}
+if (import.meta.main) {
+    const port = Number(process.env.PORT ?? 3000);
+    const host = createLocalSandbox("/");
+    const docker = createDockerClient(host);
+    const service = createDimensionService(createFileStorage(host), docker, createDimensionImage(docker), host);
+    await createDimensionHttpServer(service, port).start();
+}

package/dist/dimension/image.d.ts

@@ -0,0 +1,13 @@
+import { type DockerClient } from "../lib/docker.ts";
+/**
+ * Bump whenever anything under ./image changes (and run `bun run embed:images`); the tag is how an
+ * existing build is recognised.
+ */
+export declare const DIMENSION_IMAGE_VERSION = "v6";
+export declare const DIMENSION_IMAGE_REPOSITORY = "hyperbrane-dimension";
+export declare const DIMENSION_IMAGE = "hyperbrane-dimension:v6";
+export interface DimensionImage {
+    /** Builds the base image if it isn't present yet, removes outdated ones, and returns its tag. */
+    ensure(): Promise<string>;
+}
+export declare function createDimensionImage(docker: DockerClient): DimensionImage;

package/dist/dimension/image.js

@@ -0,0 +1,43 @@
+import { DockerError } from "../lib/docker.js";
+// The files under ./image, as strings (scripts/embed-image-files.ts), so they travel inside the module
+// graph under any runtime or bundler instead of being looked up on disk at runtime.
+import { IMAGE_FILES } from "./imageFiles.generated.js";
+/**
+ * Bump whenever anything under ./image changes (and run `bun run embed:images`); the tag is how an
+ * existing build is recognised.
+ */
+export const DIMENSION_IMAGE_VERSION = "v6";
+export const DIMENSION_IMAGE_REPOSITORY = "hyperbrane-dimension";
+export const DIMENSION_IMAGE = `${DIMENSION_IMAGE_REPOSITORY}:${DIMENSION_IMAGE_VERSION}`;
+const BUILD_CONTEXT = IMAGE_FILES;
+export function createDimensionImage(docker) {
+    // Concurrent builds of the same tag (from any process) are harmless: they produce the same image.
+    async function ensure() {
+        if (!(await docker.imageExists(DIMENSION_IMAGE))) {
+            await docker.buildImage({
+                tag: DIMENSION_IMAGE,
+                context: BUILD_CONTEXT,
+                labels: { hyperbrane: "true", "hyperbrane.image.version": DIMENSION_IMAGE_VERSION },
+            });
+        }
+        await removeOutdatedImages().catch((error) => console.warn("removing outdated dimension images failed:", error));
+        return DIMENSION_IMAGE;
+    }
+    // Images still used by a container are skipped (docker answers 409) and retried on a later ensure().
+    async function removeOutdatedImages() {
+        const images = await docker.listImages({ label: ["hyperbrane"], reference: [DIMENSION_IMAGE_REPOSITORY] });
+        const outdated = images
+            .flatMap((image) => image.RepoTags ?? [])
+            .filter((tag) => tag.startsWith(`${DIMENSION_IMAGE_REPOSITORY}:`) && tag !== DIMENSION_IMAGE);
+        for (const tag of outdated) {
+            try {
+                await docker.removeImage(tag);
+            }
+            catch (error) {
+                if (!(error instanceof DockerError && error.status === 409))
+                    throw error;
+            }
+        }
+    }
+    return { ensure };
+}

package/dist/dimension/imageFiles.generated.d.ts

@@ -0,0 +1 @@
+export declare const IMAGE_FILES: Record<string, string>;

package/dist/dimension/imageFiles.generated.js

@@ -0,0 +1,5 @@
+// Generated by scripts/embed-image-files.ts from dimension/image/ — do not edit; run `bun run embed:images`.
+export const IMAGE_FILES = {
+    "Dockerfile": "# bun runs the agent session worker (agent/session/), and the agent CLIs it installs.\nFROM oven/bun:1.3.13-slim AS bun\nFROM debian:13-slim\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends bash sudo git jq curl wget iputils-ping ca-certificates procps \\\n && rm -rf /var/lib/apt/lists/*\nCOPY --from=bun /usr/local/bin/bun /usr/local/bin/bun\nCOPY ensure-user.sh /usr/local/bin/hyb-ensure-user\nRUN chmod 0755 /usr/local/bin/hyb-ensure-user\nWORKDIR /workspace\nCMD [\"sleep\", \"infinity\"]\n",
+    "ensure-user.sh": "#!/bin/sh\n# Creates the dimension user for HYB_UID/HYB_GID (the host directory owner) with passwordless sudo.\n# Safe to re-run: every step checks before it acts, and concurrent runs are serialized by the lock.\nset -eu\n\nexec 9>/run/hyb-ensure-user.lock\nflock 9\n\nuid=\"$HYB_UID\"\ngid=\"$HYB_GID\"\n[ \"$uid\" = 0 ] && exit 0\n\ngroup=\"$(getent group \"$gid\" | cut -d: -f1 || true)\"\nif [ -z \"$group\" ]; then\n  groupadd -g \"$gid\" dimension\n  group=dimension\nfi\n\nif ! getent passwd \"$uid\" >/dev/null; then\n  useradd -m -u \"$uid\" -g \"$group\" -d /home/dimension -s /bin/bash dimension\nfi\n\necho \"#$uid ALL=(ALL) NOPASSWD: ALL\" > /etc/sudoers.d/dimension\nchmod 0440 /etc/sudoers.d/dimension\n",
+};

package/dist/dimension/paths.d.ts

@@ -0,0 +1,5 @@
+export declare const WORKSPACE_PATH = "/workspace";
+/** Where the dimension's run directory (see Storage.ensureRunDirectory) is mounted. */
+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";

package/dist/dimension/paths.js

@@ -0,0 +1,7 @@
+// 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.
+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";

package/dist/dimension/service.d.ts

@@ -0,0 +1,22 @@
+import { type DockerClient } from "../lib/docker.ts";
+import { type Sandbox } from "../sandbox/api.ts";
+import { type Dimension, type DimensionInfo, type DimensionLimits } from "./api.ts";
+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 };
+export interface DimensionService {
+    getDimensions(): Promise<DimensionInfo[]>;
+    /** The dimensions' names, from the records alone: none of getDimensions' container status and usage. */
+    getDimensionNames(): Promise<string[]>;
+    createDimension(dimension: Dimension): Promise<void>;
+    destroyDimension(dimensionName: string): Promise<void>;
+    restartDimension(dimensionName: string): Promise<void>;
+    updateDimension(dimensionName: string, limits: DimensionLimits): Promise<Dimension>;
+}
+export declare function containerName(dimensionName: string): string;
+/**
+ * `host` is the machine the docker daemon runs on, rooted at "/" so dimension directories
+ * (bind-mount sources) resolve the same way docker resolves them.
+ */
+export declare function createDimensionService(storage: Storage, docker: DockerClient, image: DimensionImage, host: Sandbox): DimensionService;