hyperbrane 0.1.0

package/dist/cli/gateway.js

@@ -0,0 +1,245 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { resolve } from "node:path";
+import anthropic from "../upstreams/anthropic.js";
+import openai from "../upstreams/openai.js";
+import { QUIET_FLAG, UsageError, forEach, printList, requireFlag } from "./command.js";
+const BUILTIN_UPSTREAMS = { anthropic, openai };
+const TRAFFIC_ACTIONS = ["BLOCK", "DELAY", "ASK", "INTERCEPT"];
+export const gatewayCommands = {
+    summary: "Manage portal gateways: proxies that hold credentials for the dimensions behind them",
+    commands: {
+        ls: {
+            summary: "List gateways",
+            flags: QUIET_FLAG,
+            async run(_args, flags, { gateways, portals }) {
+                const allPortals = await portals.listPortals();
+                const rows = await Promise.all((await gateways.listGateways())
+                    .sort((a, b) => a.name.localeCompare(b.name))
+                    .map(async ({ name }) => [
+                    name,
+                    (await gateways.listUpstreams(name)).map((upstream) => upstream.name).join(", "),
+                    allPortals
+                        .filter((portal) => portal.gatewayName === name)
+                        .map((portal) => portal.name)
+                        .sort()
+                        .join(", "),
+                ]));
+                printList(flags, ["NAME", "UPSTREAMS", "PORTALS"], rows);
+            },
+        },
+        create: {
+            summary: "Create a gateway, finish creating one that was interrupted, or upgrade one to the current image",
+            args: ["NAME"],
+            async run([name], _flags, { gateways, portals }) {
+                await gateways.createGateway({ name: name });
+                // An upgrade replaces the container, and its portals' links with it.
+                await portals.restorePortals({ gatewayName: name });
+                console.log(name);
+            },
+        },
+        restart: {
+            summary: "Restart one or more gateways",
+            args: ["NAME..."],
+            async run(names, _flags, { gateways }) {
+                await forEach(names, (name) => gateways.restartGateway(name));
+            },
+        },
+        rm: {
+            summary: "Remove one or more gateways, with their credentials (remove their portals first)",
+            args: ["NAME..."],
+            async run(names, _flags, { gateways }) {
+                await forEach(names, (name) => gateways.destroyGateway(name));
+            },
+        },
+    },
+};
+async function loadUpstream(source) {
+    const builtin = BUILTIN_UPSTREAMS[source];
+    if (builtin)
+        return builtin;
+    if (!/[/\\]|\.(ts|js|mjs|json)$/.test(source)) {
+        throw new UsageError(`unknown upstream ${source}: use one of ${Object.keys(BUILTIN_UPSTREAMS).join(", ")}, or a file path`);
+    }
+    const module = (await import(__rewriteRelativeImportExtension(resolve(source))));
+    if (!module.default)
+        throw new UsageError(`${source} has no default export`);
+    return module.default;
+}
+export const upstreamCommands = {
+    summary: "Manage the upstreams (APIs) a gateway holds credentials for",
+    commands: {
+        ls: {
+            summary: "List a gateway's upstreams",
+            args: ["GATEWAY"],
+            flags: QUIET_FLAG,
+            async run([gateway], flags, { gateways }) {
+                const rows = (await gateways.listUpstreams(gateway)).map((upstream) => {
+                    const modes = Object.entries(upstream.modes).filter(([, mode]) => mode);
+                    const hosts = new Set(modes.flatMap(([, mode]) => mode.hosts));
+                    return [upstream.name, modes.map(([name]) => name).join(", "), [...hosts].join(", ")];
+                });
+                printList(flags, ["NAME", "MODES", "HOSTS"], rows);
+            },
+        },
+        add: {
+            summary: `Add or replace an upstream: built-in (${Object.keys(BUILTIN_UPSTREAMS).join(", ")}) or a module exporting a definition`,
+            args: ["GATEWAY", "UPSTREAM"],
+            async run([gateway, source], _flags, { gateways }) {
+                const upstream = await gateways.registerUpstream(gateway, await loadUpstream(source));
+                console.log(upstream.name);
+            },
+        },
+        rm: {
+            summary: "Remove one or more upstreams from a gateway, with their credentials",
+            args: ["GATEWAY", "UPSTREAM..."],
+            async run([gateway, ...names], _flags, { gateways }) {
+                await forEach(names, (name) => gateways.removeUpstream(gateway, name));
+            },
+        },
+    },
+};
+async function readKeyFromStdin() {
+    if (process.stdin.isTTY) {
+        throw new UsageError("pipe the key on stdin, e.g. `hyperbrane key set GATEWAY UPSTREAM NAME < key.txt`");
+    }
+    return (await Bun.stdin.text()).replace(/\r?\n$/, "");
+}
+export const keyCommands = {
+    summary: "Manage API keys (a client in a dimension uses the key's fake in its place)",
+    commands: {
+        set: {
+            summary: "Set an API key, read from stdin (never pass keys as arguments); prints its fake",
+            args: ["GATEWAY", "UPSTREAM", "NAME"],
+            async run([gateway, upstream, name], _flags, { gateways }) {
+                const { fake } = await gateways.setApiKey(gateway, upstream, name, await readKeyFromStdin());
+                console.log(fake);
+            },
+        },
+        rm: {
+            summary: "Remove one or more API keys",
+            args: ["GATEWAY", "UPSTREAM", "NAME..."],
+            async run([gateway, upstream, ...names], _flags, { gateways }) {
+                await forEach(names, (name) => gateways.deleteApiKey(gateway, upstream, name));
+            },
+        },
+    },
+};
+export const credentialCommands = {
+    summary: "Manage the credentials a gateway holds (secrets are never shown; API keys' fakes are)",
+    commands: {
+        ls: {
+            summary: "List a gateway's credentials",
+            args: ["GATEWAY"],
+            flags: QUIET_FLAG,
+            async run([gateway], flags, { gateways }) {
+                const rows = (await gateways.listCredentials(gateway)).map((credential) => [
+                    credential.name,
+                    credential.type,
+                    credential.fake ?? "",
+                ]);
+                printList(flags, ["NAME", "TYPE", "FAKE"], rows);
+            },
+        },
+        rm: {
+            summary: "Remove one or more credentials (<upstream>.oauth or <upstream>.key.<name>)",
+            args: ["GATEWAY", "CREDENTIAL..."],
+            async run([gateway, ...names], _flags, { gateways }) {
+                await forEach(names, (name) => gateways.deleteCredential(gateway, name));
+            },
+        },
+    },
+};
+const RULE_FLAGS = {
+    "url-mask": {
+        type: "string",
+        value: "MASK",
+        description: 'What the rule covers: "tcp://<address>:<port>" or a URL glob like "https://*.github.com/*"',
+    },
+    action: { type: "string", value: "ACTION", description: TRAFFIC_ACTIONS.join(", ") },
+    "delay-ms": { type: "string", value: "MS", description: "Delay for DELAY rules (default 0)" },
+};
+function parseAction(value) {
+    const action = value.toUpperCase();
+    if (!TRAFFIC_ACTIONS.includes(action))
+        throw new UsageError(`--action must be one of ${TRAFFIC_ACTIONS.join(", ")}`);
+    return action;
+}
+function parseDelay(value) {
+    const delayMs = Number(value);
+    if (!Number.isInteger(delayMs) || delayMs < 0)
+        throw new UsageError("--delay-ms must be a whole number of milliseconds");
+    return delayMs;
+}
+function ruleFromFlags(name, flags, base) {
+    return {
+        name,
+        urlMask: typeof flags["url-mask"] === "string" ? flags["url-mask"] : (base?.urlMask ?? requireFlag(flags, "url-mask")),
+        action: typeof flags.action === "string" ? parseAction(flags.action) : (base?.action ?? parseAction(requireFlag(flags, "action"))),
+        delayMs: typeof flags["delay-ms"] === "string" ? parseDelay(flags["delay-ms"]) : (base?.delayMs ?? 0),
+    };
+}
+export const ruleCommands = {
+    summary: "Manage traffic rules: what a gateway does with its portals' traffic (checked in name order)",
+    commands: {
+        ls: {
+            summary: "List a gateway's traffic rules, in the order they're checked",
+            args: ["GATEWAY"],
+            flags: QUIET_FLAG,
+            async run([gateway], flags, { gateways }) {
+                const rows = (await gateways.listTrafficRules(gateway)).map((rule) => [
+                    rule.name,
+                    rule.action,
+                    rule.action === "DELAY" ? `${rule.delayMs}ms` : "",
+                    rule.urlMask,
+                ]);
+                printList(flags, ["NAME", "ACTION", "DELAY", "URL MASK"], rows);
+            },
+        },
+        create: {
+            summary: "Create a traffic rule",
+            args: ["GATEWAY", "NAME"],
+            flags: RULE_FLAGS,
+            async run([gateway, name], flags, { gateways }) {
+                await gateways.createTrafficRule(gateway, ruleFromFlags(name, flags));
+                console.log(name);
+            },
+        },
+        update: {
+            summary: "Change a traffic rule; options left out keep their current value",
+            args: ["GATEWAY", "NAME"],
+            flags: RULE_FLAGS,
+            async run([gateway, name], flags, { gateways }) {
+                const current = (await gateways.listTrafficRules(gateway)).find((rule) => rule.name === name);
+                if (!current)
+                    throw new UsageError(`traffic rule ${name} does not exist on gateway ${gateway}`);
+                await gateways.updateTrafficRule(gateway, ruleFromFlags(name, flags, current));
+                console.log(name);
+            },
+        },
+        rm: {
+            summary: "Remove one or more traffic rules (requests an ASK rule holds carry on)",
+            args: ["GATEWAY", "NAME..."],
+            async run([gateway, ...names], _flags, { gateways }) {
+                await forEach(names, (name) => gateways.deleteTrafficRule(gateway, name));
+            },
+        },
+        respond: {
+            summary: "Answer the requests an ASK rule is holding right now: allow or deny",
+            args: ["GATEWAY", "NAME", "ANSWER"],
+            async run([gateway, name, answer], _flags, { gateways }) {
+                const action = answer.toUpperCase();
+                if (action !== "ALLOW" && action !== "DENY")
+                    throw new UsageError("ANSWER must be allow or deny");
+                await gateways.trafficRuleRespond(gateway, name, action);
+                console.log(name);
+            },
+        },
+    },
+};

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli/main.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+import { createPortalWatcher } from "../portal-gateway/portalService.js";
+import { PartialFailure, UsageError, commandUsage, groupUsage, parseCommand, isGroup, } from "./command.js";
+import { agentCommands, sessionCommands } from "./agent.js";
+import { dimensionCommands } from "./dimension.js";
+import { credentialCommands, gatewayCommands, keyCommands, ruleCommands, upstreamCommands } from "./gateway.js";
+import { portalCommands } from "./portal.js";
+import { createServices } from "./services.js";
+const daemon = {
+    summary: "Run the background work until stopped: restoring portals after container restarts",
+    async run(_args, _flags, { portals, docker }) {
+        const watcher = createPortalWatcher(portals, docker);
+        watcher.start();
+        console.error("hyperbrane daemon running; Ctrl-C to stop");
+        await new Promise((done) => {
+            process.once("SIGINT", done);
+            process.once("SIGTERM", done);
+        });
+        await watcher.stop();
+    },
+};
+const GROUPS = {
+    dimension: dimensionCommands,
+    gateway: gatewayCommands,
+    upstream: upstreamCommands,
+    key: keyCommands,
+    credential: credentialCommands,
+    rule: ruleCommands,
+    portal: portalCommands,
+    agent: agentCommands,
+    session: sessionCommands,
+};
+const COMMANDS = { daemon };
+function usage() {
+    const names = [...Object.keys(GROUPS), ...Object.keys(COMMANDS)];
+    const width = Math.max(...names.map((name) => name.length)) + 3;
+    return [
+        "Usage:  hyperbrane COMMAND",
+        "",
+        "Manage dimensions, the portal gateways they reach the outside through, and the agents running in them",
+        "",
+        "Management Commands:",
+        ...Object.entries(GROUPS).map(([name, group]) => `  ${name.padEnd(width)}${group.summary}`),
+        "",
+        "Commands:",
+        ...Object.entries(COMMANDS).map(([name, command]) => `  ${name.padEnd(width)}${command.summary}`),
+        "",
+        "Run 'hyperbrane COMMAND --help' for more information on a command.",
+    ].join("\n");
+}
+const isHelp = (arg) => arg === "--help" || arg === "-h";
+/** Resolves the command to run, or returns help text to print. Groups nest: each word picks an entry. */
+function resolveCommand(argv) {
+    const [first] = argv;
+    if (first === undefined || isHelp(first) || first === "help")
+        return { help: usage() };
+    const standalone = COMMANDS[first];
+    if (standalone)
+        return { path: first, command: standalone, rest: argv.slice(1) };
+    let group = GROUPS[first];
+    if (!group)
+        return new UsageError(`unknown command ${first}`);
+    const path = [first];
+    for (let index = 1;; index++) {
+        const word = argv[index];
+        if (word === undefined || isHelp(word))
+            return { help: groupUsage(path.join(" "), group) };
+        const entry = group.commands[word];
+        if (!entry && group.default)
+            return { path: path.join(" "), command: group.default, rest: argv.slice(index) };
+        if (!entry)
+            return new UsageError(`unknown command ${[...path, word].join(" ")}`);
+        path.push(word);
+        if (!isGroup(entry))
+            return { path: path.join(" "), command: entry, rest: argv.slice(index + 1) };
+        group = entry;
+    }
+}
+async function main(argv) {
+    const resolved = resolveCommand(argv);
+    if (resolved instanceof UsageError) {
+        console.error(`Error: ${resolved.message}\nRun 'hyperbrane --help' for usage.`);
+        return 2;
+    }
+    if ("help" in resolved) {
+        console.log(resolved.help);
+        return 0;
+    }
+    const { path, command, rest } = resolved;
+    if (rest.some(isHelp)) {
+        console.log(commandUsage(path, command));
+        return 0;
+    }
+    let parsed;
+    try {
+        parsed = parseCommand(command, rest);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}\nRun 'hyperbrane ${path} --help' for usage.`);
+        return 2;
+    }
+    const services = createServices();
+    // A container restart takes its portals with it, and nothing else may be running to notice: every
+    // command re-wires what's gone first (a quick look at each gateway when nothing is).
+    await services.portals.restorePortals().catch((error) => {
+        console.error(`Warning: restoring portals failed: ${error.message}`);
+    });
+    try {
+        await command.run(parsed.args, parsed.flags, services);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof PartialFailure)
+            return 1;
+        if (error instanceof UsageError) {
+            console.error(`Error: ${error.message}\nRun 'hyperbrane ${path} --help' for usage.`);
+            return 2;
+        }
+        console.error(`Error: ${error.message}`);
+        if (process.env.HYPERBRANE_DEBUG)
+            console.error(error);
+        return 1;
+    }
+}
+process.exit(await main(Bun.argv.slice(2)));

package/dist/cli/portal.d.ts

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

package/dist/cli/portal.js

@@ -0,0 +1,39 @@
+import { QUIET_FLAG, forEach, printList, requireFlag } from "./command.js";
+export const portalCommands = {
+    summary: "Manage portals: connections from a dimension to a gateway",
+    commands: {
+        ls: {
+            summary: "List portals",
+            flags: QUIET_FLAG,
+            async run(_args, flags, { portals }) {
+                const rows = (await portals.listPortals())
+                    .sort((a, b) => a.name.localeCompare(b.name))
+                    .map((portal) => [portal.name, portal.dimensionName, portal.gatewayName]);
+                printList(flags, ["NAME", "DIMENSION", "GATEWAY"], rows);
+            },
+        },
+        create: {
+            summary: "Connect a dimension to a gateway, or repair an existing connection",
+            args: ["NAME"],
+            flags: {
+                dimension: { type: "string", short: "d", value: "DIMENSION", description: "Dimension to connect (required)" },
+                gateway: { type: "string", short: "g", value: "GATEWAY", description: "Gateway to connect it to (required)" },
+            },
+            async run([name], flags, { portals }) {
+                await portals.createPortal({
+                    name: name,
+                    dimensionName: requireFlag(flags, "dimension"),
+                    gatewayName: requireFlag(flags, "gateway"),
+                });
+                console.log(name);
+            },
+        },
+        rm: {
+            summary: "Remove one or more portals",
+            args: ["NAME..."],
+            async run(names, _flags, { portals }) {
+                await forEach(names, (name) => portals.destroyPortal(name));
+            },
+        },
+    },
+};

package/dist/cli/services.d.ts

@@ -0,0 +1,18 @@
+import { type AgentService } from "../agent/agentService.ts";
+import { type DimensionService } from "../dimension/service.ts";
+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";
+export type Services = {
+    docker: DockerClient;
+    dimensions: DimensionService;
+    gateways: GatewayService;
+    portals: PortalService;
+    agents: AgentService;
+};
+/**
+ * Everything runs against `host`'s docker, with state in ~/.local/share/hyperbrane of its user: this
+ * machine by default, or e.g. an SSH sandbox to drive a remote server the same way.
+ */
+export declare function createServices(host?: Sandbox): Services;

package/dist/cli/services.js

@@ -0,0 +1,33 @@
+import { createAgentService } from "../agent/agentService.js";
+import { createAgentStorage } from "../agent/agentStorage.js";
+import { createGatewaySignIns } from "../agent/gatewaySignIns.js";
+import { createDimensionImage } from "../dimension/image.js";
+import { createDimensionService } from "../dimension/service.js";
+import { createFileStorage } from "../dimension/storage.js";
+import { createDockerClient } from "../lib/docker.js";
+import { createLocalSandbox } from "../sandbox/localService.js";
+import { createGatewayImage } from "../portal-gateway/image.js";
+import { createGatewayService } from "../portal-gateway/gatewayService.js";
+import { createGatewayStorage } from "../portal-gateway/gatewayStorage.js";
+import { createPortalService } from "../portal-gateway/portalService.js";
+import { createPortalStorage } from "../portal-gateway/portalStorage.js";
+/**
+ * Everything runs against `host`'s docker, with state in ~/.local/share/hyperbrane of its user: this
+ * machine by default, or e.g. an SSH sandbox to drive a remote server the same way.
+ */
+export function createServices(host = createLocalSandbox("/")) {
+    const docker = createDockerClient(host);
+    const gatewayStorage = createGatewayStorage(host);
+    const portalStorage = createPortalStorage(host);
+    const gatewayImage = createGatewayImage(docker);
+    const portals = createPortalService(portalStorage, gatewayStorage, docker, gatewayImage, host);
+    const gateways = createGatewayService(gatewayStorage, portalStorage, docker, gatewayImage, host);
+    const dimensions = createDimensionService(createFileStorage(host), docker, createDimensionImage(docker), host);
+    return {
+        docker,
+        dimensions,
+        gateways,
+        portals,
+        agents: createAgentService(createAgentStorage(host), docker, host, createGatewaySignIns(portals, gateways)),
+    };
+}

package/dist/cli/streamPrinter.d.ts

@@ -0,0 +1,23 @@
+import type { AgentStreamingMessage } from "../agent/api.ts";
+export declare function preview(value: unknown): string;
+/** The part of stdout the printer uses. */
+export type TerminalStream = {
+    isTTY?: boolean;
+    write(chunk: string): unknown;
+};
+export interface TerminalPrinter {
+    /** A stream message: partial text and thinking as they arrive, tool calls and results, and how each turn ended. */
+    print(message: AgentStreamingMessage): void;
+    /** A complete message of a transcript. */
+    printTranscript(role: "user" | "assistant", content: unknown): void;
+    close(): void;
+}
+/**
+ * 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 declare function createTerminalPrinter({ paced, stream }: {
+    paced: boolean;
+    stream?: TerminalStream;
+}): TerminalPrinter;