hyperbrane 0.1.0

package/dist/cli/agent.js

@@ -0,0 +1,423 @@
+import { AGENT_BACKENDS } from "../agent/api.js";
+import { CPULimit, MemoryLimit } from "../dimension/api.js";
+import { QUIET_FLAG, UsageError, forEach, printList, requireFlag } from "./command.js";
+import { createTerminalPrinter, preview } from "./streamPrinter.js";
+import { formatTable } from "./table.js";
+/** How often `session attach` looks for permission requests and questions to point out. */
+const PENDING_POLL_MS = 1_000;
+function backendArg(name) {
+    const backend = AGENT_BACKENDS.find((known) => known === name);
+    if (!backend)
+        throw new UsageError(`unknown backend ${name}: use one of ${AGENT_BACKENDS.join(", ")}`);
+    return backend;
+}
+/** "AGENT/SESSION" -> the session's ref. */
+function sessionRef(arg) {
+    const slash = arg.indexOf("/");
+    if (slash <= 0 || slash === arg.length - 1)
+        throw new UsageError(`sessions are named AGENT/SESSION, not ${arg}`);
+    return { agentName: arg.slice(0, slash), sessionName: arg.slice(slash + 1) };
+}
+function refName({ agentName, sessionName }) {
+    return `${agentName}/${sessionName}`;
+}
+/** --env KEY=VALUE flags -> an environment. */
+function envFlag(flags) {
+    const entries = flags.env;
+    if (!Array.isArray(entries) || entries.length === 0)
+        return undefined;
+    const env = {};
+    for (const entry of entries) {
+        const equals = entry.indexOf("=");
+        if (equals <= 0)
+            throw new UsageError(`--env takes KEY=VALUE, not ${entry}`);
+        env[entry.slice(0, equals)] = entry.slice(equals + 1);
+    }
+    return env;
+}
+/**
+ * Points out, once each, the permission requests and questions the session is waiting on, with the
+ * command that answers them. Returns the function that stops looking.
+ */
+function watchPending(agents, ref) {
+    const seen = new Set();
+    const name = refName(ref);
+    async function look() {
+        const [permissions, questions] = await Promise.all([agents.listPermissionRequests(ref), agents.listQuestionRequests(ref)]);
+        for (const request of permissions) {
+            if (seen.has(request.id))
+                continue;
+            seen.add(request.id);
+            process.stderr.write(`\n[permission] ${request.tool_name} ${preview(request.input)}\n` +
+                `  hyperbrane session permission allow ${name} ${request.id}   (or deny)\n`);
+        }
+        for (const request of questions) {
+            if (seen.has(request.id))
+                continue;
+            seen.add(request.id);
+            const asked = request.questions.map((question) => `  ${question.question} (${question.options.map((option) => option.label).join(" / ")})`);
+            process.stderr.write(`\n[question]\n${asked.join("\n")}\n  hyperbrane session question answer ${name} ${request.id} ANSWER...\n`);
+        }
+    }
+    const timer = setInterval(() => void look().catch(() => { }), PENDING_POLL_MS);
+    return () => clearInterval(timer);
+}
+export const agentCommands = {
+    summary: "Manage agents: session workers running in dimensions",
+    commands: {
+        ls: {
+            summary: "List agents",
+            flags: QUIET_FLAG,
+            async run(_args, flags, { agents }) {
+                const sessions = await agents.listSessions();
+                const rows = (await agents.listAgents()).map((agent) => [
+                    agent.name,
+                    agent.dimensionName,
+                    String(sessions.filter((session) => session.agentName === agent.name).length),
+                ]);
+                printList(flags, ["NAME", "DIMENSION", "SESSIONS"], rows);
+            },
+        },
+        create: {
+            summary: "Start an agent in a dimension, or bring its worker up to date",
+            args: ["NAME"],
+            flags: {
+                dimension: { type: "string", short: "d", value: "DIMENSION", description: "Dimension to run in (required)" },
+                install: { type: "string", multiple: true, value: "BACKEND", description: `Install a backend too (${AGENT_BACKENDS.join(", ")}); repeatable` },
+            },
+            async run([name], flags, { agents }) {
+                await agents.createAgent({ name: name, dimensionName: requireFlag(flags, "dimension") });
+                const backends = Array.isArray(flags.install) ? flags.install.map(backendArg) : [];
+                for (const backend of backends)
+                    await agents.install(name, backend);
+                console.log(name);
+            },
+        },
+        install: {
+            summary: `Install or update backends in an agent's dimension (${AGENT_BACKENDS.join(", ")})`,
+            args: ["AGENT", "BACKEND..."],
+            async run([agent, ...backends], _flags, { agents }) {
+                backends.forEach(backendArg); // all known, before installing any
+                await forEach(backends, (backend) => agents.install(agent, backendArg(backend)));
+            },
+        },
+        rm: {
+            summary: "Stop one or more agents' workers (their sessions stay in the dimension)",
+            args: ["NAME..."],
+            async run(names, _flags, { agents }) {
+                await forEach(names, (name) => agents.stopAgent(name));
+            },
+        },
+    },
+};
+const modelCommands = {
+    summary: "Show or switch a session's model",
+    default: {
+        summary: "Show the session's model and the ones it can switch to (starts its CLI)",
+        args: ["AGENT/SESSION"],
+        flags: QUIET_FLAG,
+        async run([name], flags, { agents }) {
+            const ref = sessionRef(name);
+            const [models, sessions] = await Promise.all([agents.listModels(ref), agents.listSessions()]);
+            const current = sessions.find((session) => session.agentName === ref.agentName && session.name === ref.sessionName)?.model ?? null;
+            if (!flags.quiet)
+                console.log(`current: ${current ?? "(default)"}\n`);
+            const rows = models.map((model) => [model.value === current ? `${model.value} *` : model.value, model.displayName, model.description]);
+            printList(flags, ["MODEL", "NAME", "DESCRIPTION"], rows);
+        },
+    },
+    commands: {
+        set: {
+            summary: `Switch a session's model from its next turn on ("default" for the backend's own)`,
+            args: ["AGENT/SESSION", "MODEL"],
+            async run([name, model], _flags, { agents }) {
+                await agents.setModel(sessionRef(name), model === "default" ? null : model);
+                console.log(model);
+            },
+        },
+    },
+};
+/** A sign-in status as lines for the terminal: what to do next when it's waiting for the user. */
+function describeAuth(name, status) {
+    if (status.state === "signedIn")
+        return "signed in";
+    if (status.state === "signedOut")
+        return status.error ? `signed out (last sign-in failed: ${status.error})` : "signed out";
+    const lines = ["waiting for you to sign in:", `  open ${status.url}`];
+    if (status.userCode)
+        lines.push(`  and enter the code ${status.userCode}`);
+    if (status.needsCode)
+        lines.push(`  then: hyperbrane session auth code ${name} CODE   (the code the page shows)`);
+    return lines.join("\n");
+}
+const authCommands = {
+    summary: "Show or change how a session's CLI is signed in",
+    default: {
+        summary: "Show whether the session's CLI is signed in",
+        args: ["AGENT/SESSION"],
+        async run([name], _flags, { agents }) {
+            console.log(describeAuth(name, await agents.getAuthStatus(sessionRef(name))));
+        },
+    },
+    commands: {
+        login: {
+            summary: "Sign the CLI in with its own login; instant when the dimension's gateway already holds a sign-in",
+            args: ["AGENT/SESSION"],
+            async run([name], _flags, { agents }) {
+                console.log(describeAuth(name, await agents.login(sessionRef(name))));
+            },
+        },
+        code: {
+            summary: "Finish a sign-in with the code the sign-in page showed (claude)",
+            args: ["AGENT/SESSION", "CODE"],
+            async run([name, code], _flags, { agents }) {
+                console.log(describeAuth(name, await agents.submitAuthCode(sessionRef(name), code)));
+            },
+        },
+    },
+};
+const taskCommands = {
+    summary: "List or stop the tasks a session's agent keeps running in the background",
+    default: {
+        summary: "List the tasks a session's agent keeps running in the background",
+        args: ["AGENT/SESSION"],
+        flags: QUIET_FLAG,
+        async run([name], flags, { agents }) {
+            const rows = (await agents.listBackgroundTasks(sessionRef(name))).map((task) => [task.task_id, task.task_type, task.description]);
+            printList(flags, ["ID", "TYPE", "DESCRIPTION"], rows);
+        },
+    },
+    commands: {
+        stop: {
+            summary: "Stop one or more background tasks",
+            args: ["AGENT/SESSION", "TASK..."],
+            async run([name, ...tasks], _flags, { agents }) {
+                const ref = sessionRef(name);
+                await forEach(tasks, (task) => agents.stopTask(ref, task));
+            },
+        },
+    },
+};
+const permissionCommands = {
+    summary: "List and answer a session's permission requests: tool calls waiting to run",
+    commands: {
+        ls: {
+            summary: "List a session's tool calls waiting for permission",
+            args: ["AGENT/SESSION"],
+            flags: QUIET_FLAG,
+            async run([name], flags, { agents }) {
+                const rows = (await agents.listPermissionRequests(sessionRef(name))).map((request) => [
+                    request.id,
+                    request.tool_name,
+                    preview(request.input),
+                ]);
+                printList(flags, ["ID", "TOOL", "INPUT"], rows);
+            },
+        },
+        allow: {
+            summary: "Let one or more waiting tool calls run",
+            args: ["AGENT/SESSION", "REQUEST..."],
+            async run([name, ...requests], _flags, { agents }) {
+                const ref = sessionRef(name);
+                await forEach(requests, (request) => agents.respondPermissionRequest(ref, request, { behavior: "allow" }));
+            },
+        },
+        deny: {
+            summary: "Refuse one or more waiting tool calls",
+            args: ["AGENT/SESSION", "REQUEST..."],
+            flags: {
+                message: { type: "string", value: "TEXT", description: "What the agent is told (default: the user denied it)" },
+            },
+            async run([name, ...requests], flags, { agents }) {
+                const ref = sessionRef(name);
+                const message = typeof flags.message === "string" ? flags.message : "The user denied this tool call.";
+                await forEach(requests, (request) => agents.respondPermissionRequest(ref, request, { behavior: "deny", message }));
+            },
+        },
+    },
+};
+const questionCommands = {
+    summary: "List and answer the questions a session asks",
+    commands: {
+        ls: {
+            summary: "List a session's questions waiting for an answer",
+            args: ["AGENT/SESSION"],
+            async run([name], _flags, { agents }) {
+                const rows = (await agents.listQuestionRequests(sessionRef(name))).flatMap((request) => request.questions.map((question, index) => [
+                    index === 0 ? request.id : "",
+                    question.question,
+                    question.options.map((option) => option.label).join(" / "),
+                ]));
+                console.log(formatTable(["ID", "QUESTION", "OPTIONS"], rows));
+            },
+        },
+        answer: {
+            summary: "Answer a question request: one ANSWER per question, in order (an option's label, or your own words)",
+            args: ["AGENT/SESSION", "REQUEST", "ANSWER..."],
+            async run([name, requestId, ...answers], _flags, { agents }) {
+                const ref = sessionRef(name);
+                const request = (await agents.listQuestionRequests(ref)).find((pending) => pending.id === requestId);
+                if (!request)
+                    throw new UsageError(`no pending question request ${requestId} in ${name}`);
+                if (answers.length !== request.questions.length) {
+                    throw new UsageError(`request ${requestId} asks ${request.questions.length} question(s); give one answer for each`);
+                }
+                const byQuestion = Object.fromEntries(request.questions.map((question, index) => [question.question, answers[index]]));
+                await agents.respondQuestionRequest(ref, requestId, { answers: byQuestion });
+                console.log(requestId);
+            },
+        },
+    },
+};
+export const sessionCommands = {
+    summary: "Manage agent sessions, named AGENT/SESSION",
+    commands: {
+        ls: {
+            summary: "List sessions",
+            flags: QUIET_FLAG,
+            async run(_args, flags, { agents }) {
+                const rows = (await agents.listSessions())
+                    .map((session) => [
+                    `${session.agentName}/${session.name}`,
+                    session.backend,
+                    session.status,
+                    session.model ?? "(default)",
+                    session.nativeId ?? "",
+                ])
+                    .sort((a, b) => a[0].localeCompare(b[0]));
+                printList(flags, ["NAME", "BACKEND", "STATUS", "MODEL", "NATIVE ID"], rows);
+            },
+        },
+        create: {
+            summary: "Create a session (its CLI starts with the first message)",
+            args: ["AGENT/SESSION"],
+            flags: {
+                backend: { type: "string", short: "b", value: "BACKEND", description: `Agent CLI to run: ${AGENT_BACKENDS.join(", ")} (required)` },
+                memory: { type: "string", short: "m", value: "BYTES", description: "Memory limit, e.g. 1G (required)" },
+                cpus: { type: "string", value: "CPUS", description: "CPU limit in cores, e.g. 1 or 500m (required)" },
+                cwd: { type: "string", value: "PATH", description: "Directory in the dimension to work in (default: the workspace)" },
+                env: { type: "string", short: "e", multiple: true, value: "KEY=VALUE", description: "Environment for the CLI; repeatable" },
+            },
+            async run([name], flags, { agents }) {
+                const ref = sessionRef(name);
+                await agents.createSession(ref.agentName, {
+                    name: ref.sessionName,
+                    backend: backendArg(requireFlag(flags, "backend")),
+                    memoryLimit: MemoryLimit(requireFlag(flags, "memory")),
+                    cpuLimit: CPULimit(requireFlag(flags, "cpus")),
+                    cwd: typeof flags.cwd === "string" ? flags.cwd : undefined,
+                    env: envFlag(flags),
+                });
+                console.log(name);
+            },
+        },
+        update: {
+            summary: "Change a session's limits (recorded; the dimension's limits are what's enforced)",
+            args: ["AGENT/SESSION"],
+            flags: {
+                memory: { type: "string", short: "m", value: "BYTES", description: "Memory limit, e.g. 1G" },
+                cpus: { type: "string", value: "CPUS", description: "CPU limit in cores, e.g. 1 or 500m" },
+            },
+            async run([name], flags, { agents }) {
+                if (typeof flags.memory !== "string" && typeof flags.cpus !== "string")
+                    throw new UsageError("give --memory, --cpus, or both");
+                await agents.updateSession(sessionRef(name), {
+                    memoryLimit: typeof flags.memory === "string" ? MemoryLimit(flags.memory) : undefined,
+                    cpuLimit: typeof flags.cpus === "string" ? CPULimit(flags.cpus) : undefined,
+                });
+                console.log(name);
+            },
+        },
+        rm: {
+            summary: "Stop one or more sessions and forget them",
+            args: ["AGENT/SESSION..."],
+            async run(names, _flags, { agents }) {
+                await forEach(names, (name) => agents.stopSession(sessionRef(name)));
+            },
+        },
+        send: {
+            summary: "Send a message; prints its uuid (follow the reply with: session attach AGENT/SESSION --after UUID)",
+            args: ["AGENT/SESSION", "MESSAGE..."],
+            async run([name, ...words], _flags, { agents }) {
+                const uuid = crypto.randomUUID();
+                await agents.sendMessage(sessionRef(name), { type: "user", message: { role: "user", content: words.join(" ") }, parent_tool_use_id: null, uuid });
+                console.log(uuid);
+            },
+        },
+        attach: {
+            summary: "Print a session's stream as it happens, until Ctrl-C",
+            args: ["AGENT/SESSION"],
+            flags: {
+                after: { type: "string", value: "UUID", description: "Start after this message (default: from the beginning)" },
+            },
+            async run([name], flags, { agents }) {
+                const ref = sessionRef(name);
+                const stopWatching = watchPending(agents, ref);
+                const printer = createTerminalPrinter({ paced: true });
+                // Ctrl-C: out with what's still being typed, and the terminal back to normal text.
+                process.once("SIGINT", () => {
+                    printer.close();
+                    process.exit(130);
+                });
+                try {
+                    for await (const message of agents.getStream(ref, { after_id: typeof flags.after === "string" ? flags.after : undefined })) {
+                        printer.print(message);
+                    }
+                }
+                finally {
+                    printer.close();
+                    stopWatching();
+                }
+            },
+        },
+        logs: {
+            summary: "Print the latest of a session's conversation (older pages with --before)",
+            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)" },
+            },
+            async run([name], flags, { agents }) {
+                const limit = typeof flags.limit === "string" ? Number(flags.limit) : undefined;
+                if (limit !== undefined && !(Number.isInteger(limit) && limit > 0))
+                    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,
+                });
+                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`);
+            },
+        },
+        status: {
+            summary: "Show where a session's agent stands, its last message and those it holds queued",
+            args: ["AGENT/SESSION"],
+            async run([name], _flags, { agents }) {
+                const ref = sessionRef(name);
+                const [state, messages] = await Promise.all([agents.getSessionStatus(ref), agents.getLastUserMessages(ref)]);
+                console.log(state);
+                for (const { message, queued } of messages) {
+                    const content = message.message.content;
+                    const text = typeof content === "string" ? content : content.map((block) => (block.type === "text" ? block.text : "")).join("");
+                    console.log(`${queued ? "queued" : "last  "}  ${preview(text)}`);
+                }
+            },
+        },
+        interrupt: {
+            summary: "End the turn in progress",
+            args: ["AGENT/SESSION..."],
+            async run(names, _flags, { agents }) {
+                await forEach(names, (name) => agents.cancel(sessionRef(name)));
+            },
+        },
+        tasks: taskCommands,
+        model: modelCommands,
+        auth: authCommands,
+        permission: permissionCommands,
+        question: questionCommands,
+    },
+};

package/dist/cli/command.d.ts

@@ -0,0 +1,46 @@
+import type { Services } from "./services.ts";
+export type Flag = {
+    type: "string" | "boolean";
+    short?: string;
+    /** Shown in help, e.g. "BYTES". */
+    value?: string;
+    description: string;
+    /** May be given more than once; its value is then a string[]. */
+    multiple?: boolean;
+};
+export type Flags = Record<string, string | boolean | string[] | undefined>;
+export type Command = {
+    summary: string;
+    /** Positional arguments: "NAME" is required, "[NAME]" optional, a trailing "NAME..." takes one or more. */
+    args?: string[];
+    flags?: Record<string, Flag>;
+    run(args: string[], flags: Flags, services: Services): Promise<void>;
+};
+export type CommandGroup = {
+    summary: string;
+    /** A group may hold groups of its own: `hyperbrane session permission allow`. */
+    commands: Record<string, Command | CommandGroup>;
+    /** Runs when the next word isn't one of `commands`: `hyperbrane session model A/S` next to `... model set`. */
+    default?: Command;
+};
+export declare function isGroup(entry: Command | CommandGroup): entry is CommandGroup;
+/** Bad invocation: printed with a pointer to --help. */
+export declare class UsageError extends Error {
+    name: string;
+}
+/** Some items of a multi-item command failed; each error was already printed. */
+export declare class PartialFailure extends Error {
+    name: string;
+}
+export declare function parseCommand(command: Command, argv: string[]): {
+    args: string[];
+    flags: Flags;
+};
+export declare function requireFlag(flags: Flags, name: string): string;
+/** docker rm style: every item is attempted, each success prints its name, failures print and fail the command. */
+export declare function forEach(names: string[], action: (name: string) => Promise<void>): Promise<void>;
+/** `ls` output: the table, or with -q only the first column. */
+export declare function printList(flags: Flags, headers: string[], rows: string[][]): void;
+export declare const QUIET_FLAG: Record<string, Flag>;
+export declare function commandUsage(path: string, command: Command): string;
+export declare function groupUsage(name: string, group: CommandGroup): string;

package/dist/cli/command.js

@@ -0,0 +1,98 @@
+import { parseArgs } from "node:util";
+import { formatTable } from "./table.js";
+export function isGroup(entry) {
+    return "commands" in entry;
+}
+/** Bad invocation: printed with a pointer to --help. */
+export class UsageError extends Error {
+    name = "UsageError";
+}
+/** Some items of a multi-item command failed; each error was already printed. */
+export class PartialFailure extends Error {
+    name = "PartialFailure";
+}
+export function parseCommand(command, argv) {
+    const options = Object.fromEntries(Object.entries(command.flags ?? {}).map(([name, { type, short, multiple }]) => [
+        name,
+        { type, ...(short ? { short } : {}), ...(multiple ? { multiple } : {}) },
+    ]));
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        throw new UsageError(error.message);
+    }
+    const specs = command.args ?? [];
+    const required = specs.filter((spec) => !spec.startsWith("[")).length;
+    const variadic = specs.at(-1)?.endsWith("...") ?? false;
+    const count = parsed.positionals.length;
+    if (count < required)
+        throw new UsageError(`missing ${specs.slice(count).filter((s) => !s.startsWith("[")).join(" ")}`);
+    if (!variadic && count > specs.length)
+        throw new UsageError(`unexpected argument ${parsed.positionals[specs.length]}`);
+    return { args: parsed.positionals, flags: parsed.values };
+}
+export function requireFlag(flags, name) {
+    const value = flags[name];
+    if (typeof value !== "string" || value === "")
+        throw new UsageError(`--${name} is required`);
+    return value;
+}
+/** docker rm style: every item is attempted, each success prints its name, failures print and fail the command. */
+export async function forEach(names, action) {
+    let failed = false;
+    for (const name of names) {
+        try {
+            await action(name);
+            console.log(name);
+        }
+        catch (error) {
+            failed = true;
+            console.error(`Error: ${error.message}`);
+        }
+    }
+    if (failed)
+        throw new PartialFailure();
+}
+/** `ls` output: the table, or with -q only the first column. */
+export function printList(flags, headers, rows) {
+    if (flags.quiet) {
+        for (const row of rows)
+            console.log(row[0]);
+        return;
+    }
+    console.log(formatTable(headers, rows));
+}
+export const QUIET_FLAG = {
+    quiet: { type: "boolean", short: "q", description: "Only display names" },
+};
+export function commandUsage(path, command) {
+    const lines = [`Usage:  hyperbrane ${path}${command.flags ? " [OPTIONS]" : ""}${(command.args ?? []).map((a) => ` ${a}`).join("")}`, "", command.summary];
+    if (command.flags) {
+        lines.push("", "Options:");
+        const entries = Object.entries(command.flags).map(([name, flag]) => [
+            `${flag.short ? `-${flag.short}, ` : "    "}--${name}${flag.value ? ` ${flag.value}` : ""}`,
+            flag.description,
+        ]);
+        const width = Math.max(...entries.map(([left]) => left.length)) + 3;
+        for (const [left, description] of entries)
+            lines.push(`  ${left.padEnd(width)}${description}`);
+    }
+    return lines.join("\n");
+}
+export function groupUsage(name, group) {
+    const width = Math.max(...Object.keys(group.commands).map((command) => command.length)) + 3;
+    const byDefault = group.default ? [commandUsage(name, group.default).split("\n")[0], ""] : [];
+    return [
+        ...byDefault,
+        `Usage:  hyperbrane ${name} COMMAND`,
+        "",
+        group.summary,
+        "",
+        "Commands:",
+        ...Object.entries(group.commands).map(([command, { summary }]) => `  ${command.padEnd(width)}${summary}`),
+        "",
+        `Run 'hyperbrane ${name} COMMAND --help' for more information on a command.`,
+    ].join("\n");
+}

package/dist/cli/dimension.d.ts

@@ -0,0 +1,2 @@
+import { type CommandGroup } from "./command.ts";
+export declare const dimensionCommands: CommandGroup;

package/dist/cli/dimension.js

@@ -0,0 +1,85 @@
+import { resolve } from "node:path";
+import { CPULimit, MemoryLimit } from "../dimension/api.js";
+import { QUIET_FLAG, UsageError, forEach, printList, requireFlag } from "./command.js";
+import { formatBytes, formatCpuPercent, formatDuration } from "./table.js";
+function statusColumn(dimension) {
+    if (dimension.status === "running" && dimension.uptimeSeconds !== null) {
+        return `Up ${formatDuration(dimension.uptimeSeconds)}`;
+    }
+    return dimension.status[0].toUpperCase() + dimension.status.slice(1);
+}
+function dimensionRow(dimension) {
+    const usage = dimension.memoryUsage === null ? "--" : formatBytes(dimension.memoryUsage);
+    return [
+        dimension.name,
+        statusColumn(dimension),
+        dimension.cpuUsage === null ? "--" : formatCpuPercent(dimension.cpuUsage),
+        `${usage} / ${formatBytes(dimension.memoryLimit)}`,
+        String(dimension.cpuLimit),
+        dimension.directory,
+    ];
+}
+export const dimensionCommands = {
+    summary: "Manage dimensions: containers bound to a host directory",
+    commands: {
+        ls: {
+            summary: "List dimensions",
+            flags: QUIET_FLAG,
+            async run(_args, flags, { dimensions }) {
+                const rows = (await dimensions.getDimensions())
+                    .sort((a, b) => a.name.localeCompare(b.name))
+                    .map(dimensionRow);
+                printList(flags, ["NAME", "STATUS", "CPU %", "MEM USAGE / LIMIT", "CPUS", "DIRECTORY"], rows);
+            },
+        },
+        create: {
+            summary: "Create a dimension, or finish creating one that was interrupted",
+            args: ["NAME"],
+            flags: {
+                dir: { type: "string", value: "PATH", description: "Host directory mounted at /workspace (default: current directory)" },
+                memory: { type: "string", short: "m", value: "BYTES", description: "Memory limit, e.g. 512M or 2G (required)" },
+                cpus: { type: "string", value: "CPUS", description: "CPU limit in cores, e.g. 1.5 or 500m (required)" },
+            },
+            async run([name], flags, { dimensions }) {
+                await dimensions.createDimension({
+                    name: name,
+                    directory: resolve(typeof flags.dir === "string" ? flags.dir : "."),
+                    memoryLimit: MemoryLimit(requireFlag(flags, "memory")),
+                    cpuLimit: CPULimit(requireFlag(flags, "cpus")),
+                });
+                console.log(name);
+            },
+        },
+        update: {
+            summary: "Change a dimension's limits in place, without restarting it",
+            args: ["NAME"],
+            flags: {
+                memory: { type: "string", short: "m", value: "BYTES", description: "Memory limit, e.g. 2G" },
+                cpus: { type: "string", value: "CPUS", description: "CPU limit in cores, e.g. 2 or 1500m" },
+            },
+            async run([name], flags, { dimensions }) {
+                if (typeof flags.memory !== "string" && typeof flags.cpus !== "string")
+                    throw new UsageError("give --memory, --cpus, or both");
+                await dimensions.updateDimension(name, {
+                    memoryLimit: typeof flags.memory === "string" ? MemoryLimit(flags.memory) : undefined,
+                    cpuLimit: typeof flags.cpus === "string" ? CPULimit(flags.cpus) : undefined,
+                });
+                console.log(name);
+            },
+        },
+        restart: {
+            summary: "Restart one or more dimensions",
+            args: ["NAME..."],
+            async run(names, _flags, { dimensions }) {
+                await forEach(names, (name) => dimensions.restartDimension(name));
+            },
+        },
+        rm: {
+            summary: "Remove one or more dimensions (the host directory is kept)",
+            args: ["NAME..."],
+            async run(names, _flags, { dimensions }) {
+                await forEach(names, (name) => dimensions.destroyDimension(name));
+            },
+        },
+    },
+};

package/dist/cli/gateway.d.ts

@@ -0,0 +1,6 @@
+import { type CommandGroup } from "./command.ts";
+export declare const gatewayCommands: CommandGroup;
+export declare const upstreamCommands: CommandGroup;
+export declare const keyCommands: CommandGroup;
+export declare const credentialCommands: CommandGroup;
+export declare const ruleCommands: CommandGroup;