mirab 0.0.0-stage → 0.2.0

package/types/isolation/image.d.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+/** Where mirab's releases and guest images live. */
+export declare const RELEASES = "https://mirab-releases.addis.gg";
+export declare const MIRAB_VERSION: string;
+/** The release this copy of mirab was installed from (`0.1.0-canary-abc1234`):
+ *  the release workflow stamps release.json into what it ships. From a
+ *  checkout there is none, and the package version stands in. */
+export declare const MIRAB_RELEASE: string;
+/** Where the guest kernel, rootfs and (macOS) vz helper live, published or
+ *  built by `bun run vm:image`; `vm` uses them when isolation.json names no
+ *  other files. */
+export declare function vmImagePaths(configDir: string): {
+    dir: string;
+    kernel: string;
+    rootfs: string;
+    vz: string;
+    record: string;
+};
+/** The VM platforms a release publishes, and the file each role is built as. */
+export declare const VM_PLATFORMS: {
+    readonly 'linux-x64': {
+        readonly kernel: 'vmlinux';
+        readonly rootfs: 'rootfs.ext4';
+    };
+    readonly 'darwin-x64': {
+        readonly kernel: 'bzImage';
+        readonly rootfs: 'rootfs.ext4';
+        readonly vz: 'mirab-vz';
+    };
+    readonly 'darwin-arm64': {
+        readonly kernel: 'Image';
+        readonly rootfs: 'rootfs.ext4';
+        readonly vz: 'mirab-vz';
+    };
+};
+export type VmPlatform = keyof typeof VM_PLATFORMS;
+export type VmRole = 'kernel' | 'rootfs' | 'vz';
+export declare const vmPlatform: (platform?: string, arch?: string) => VmPlatform | undefined;
+declare const entry: z.ZodObject<{
+    file: z.ZodString;
+    sha256: z.ZodString;
+    size: z.ZodNumber;
+    unpacked: z.ZodObject<{
+        sha256: z.ZodString;
+        size: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type VmFileEntry = z.infer<typeof entry>;
+export declare const vmManifestSchema: z.ZodObject<{
+    version: z.ZodString;
+    protocol: z.ZodNumber;
+    commit: z.ZodString;
+    platforms: z.ZodObject<{
+        'linux-x64': z.ZodOptional<z.ZodObject<{
+            kernel: z.ZodObject<{
+                file: z.ZodString;
+                sha256: z.ZodString;
+                size: z.ZodNumber;
+                unpacked: z.ZodObject<{
+                    sha256: z.ZodString;
+                    size: z.ZodNumber;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+            rootfs: z.ZodObject<{
+                file: z.ZodString;
+                sha256: z.ZodString;
+                size: z.ZodNumber;
+                unpacked: z.ZodObject<{
+                    sha256: z.ZodString;
+                    size: z.ZodNumber;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        'darwin-x64': z.ZodOptional<z.ZodObject<{
+            kernel: z.ZodObject<{
+                file: z.ZodString;
+                sha256: z.ZodString;
+                size: z.ZodNumber;
+                unpacked: z.ZodObject<{
+                    sha256: z.ZodString;
+                    size: z.ZodNumber;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+            rootfs: z.ZodObject<{
+                file: z.ZodString;
+                sha256: z.ZodString;
+                size: z.ZodNumber;
+                unpacked: z.ZodObject<{
+                    sha256: z.ZodString;
+                    size: z.ZodNumber;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+            vz: z.ZodObject<{
+                file: z.ZodString;
+                sha256: z.ZodString;
+                size: z.ZodNumber;
+                unpacked: z.ZodObject<{
+                    sha256: z.ZodString;
+                    size: z.ZodNumber;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        'darwin-arm64': z.ZodOptional<z.ZodObject<{
+            kernel: z.ZodObject<{
+                file: z.ZodString;
+                sha256: z.ZodString;
+                size: z.ZodNumber;
+                unpacked: z.ZodObject<{
+                    sha256: z.ZodString;
+                    size: z.ZodNumber;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+            rootfs: z.ZodObject<{
+                file: z.ZodString;
+                sha256: z.ZodString;
+                size: z.ZodNumber;
+                unpacked: z.ZodObject<{
+                    sha256: z.ZodString;
+                    size: z.ZodNumber;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+            vz: z.ZodObject<{
+                file: z.ZodString;
+                sha256: z.ZodString;
+                size: z.ZodNumber;
+                unpacked: z.ZodObject<{
+                    sha256: z.ZodString;
+                    size: z.ZodNumber;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type VmManifest = z.infer<typeof vmManifestSchema>;
+export declare class VmImageError extends Error {
+}
+/** What the next tier hint says when no image could be fetched. */
+export declare const VM_IMAGE_FALLBACK_HINT = "connect and retry, build the image yourself (docs/VM.md), or use --isolation container|host";
+/** The published image for this CLI version and platform is installed and intact (cheap: sizes). */
+export declare function releaseImageInstalled(configDir: string, version?: string, platform?: "darwin-arm64" | "darwin-x64" | "linux-x64" | undefined): boolean;
+/** `bun run vm:image` (or another hand build) owns <config dir>/vm: never overwrite it. */
+export declare const localImageInstalled: (configDir: string) => boolean;
+export interface EnsureOptions {
+    configDir: string;
+    version?: string;
+    platform?: VmPlatform;
+    /** The release root (cli/ on the bucket); tests point it at a fake. */
+    base?: string;
+    log?: (line: string) => void;
+}
+/**
+ * Make sure <config dir>/vm holds the published guest image for this mirab
+ * version and platform: nothing to do when it is already there (offline is
+ * fine), otherwise download, verify and install it. Throws VmImageError with
+ * the reason and the fallback when it cannot.
+ */
+export declare function ensureVmImage(o: EnsureOptions): Promise<'installed' | 'downloaded' | 'local'>;
+export {};

package/types/isolation/index.d.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+import { type VmStartOptions } from './firecracker';
+import { type ColimaState } from './colima';
+import { type HostUserState } from './host-user';
+import { type Level, type Resolved } from './policy';
+import { type VmPlatform } from './image';
+import type { Isolation } from './session';
+export * from './policy';
+export type { Isolation } from './session';
+export { vmImagePaths } from './image';
+/** `<config dir>/isolation.json`: what the owner set once on this host. */
+export declare const hostConfigSchema: (configDir: string) => z.ZodObject<{
+    floor: z.ZodOptional<z.ZodEnum<{
+        container: "container";
+        host: "host";
+        none: "none";
+        vm: "vm";
+    }>>;
+    default: z.ZodOptional<z.ZodEnum<{
+        container: "container";
+        host: "host";
+        none: "none";
+        vm: "vm";
+    }>>;
+    vm: z.ZodOptional<z.ZodObject<{
+        firecracker: z.ZodDefault<z.ZodString>;
+        vz: z.ZodDefault<z.ZodString>;
+        kernel: z.ZodDefault<z.ZodString>;
+        rootfs: z.ZodDefault<z.ZodString>;
+        memoryMiB: z.ZodDefault<z.ZodNumber>;
+        vcpus: z.ZodDefault<z.ZodNumber>;
+        egress: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            auto: "auto";
+            block: "block";
+        }>>;
+    }, z.core.$strict>>;
+    container: z.ZodOptional<z.ZodObject<{
+        engine: z.ZodDefault<z.ZodString>;
+        image: z.ZodDefault<z.ZodString>;
+        agent: z.ZodString;
+        memory: z.ZodDefault<z.ZodString>;
+        cpus: z.ZodDefault<z.ZodString>;
+        pids: z.ZodDefault<z.ZodNumber>;
+        egress: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            auto: "auto";
+            block: "block";
+        }>>;
+    }, z.core.$strict>>;
+    host: z.ZodOptional<z.ZodObject<{
+        user: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type HostConfig = z.infer<ReturnType<typeof hostConfigSchema>>;
+export type VmConfig = NonNullable<HostConfig['vm']>;
+/** The `vm` level's backend: Virtualization.framework on macOS, Firecracker elsewhere. */
+export declare const vmBackend: (platform?: NodeJS.Platform) => "firecracker" | "vz";
+export declare function vmAvailable(vm: VmConfig, platform?: NodeJS.Platform): boolean;
+export type { VmStartOptions } from './firecracker';
+/** Boot one microVM with `work` at /workspace (null: no work directory and
+ *  nothing of the host's inside), on this platform's backend. */
+export declare function startVm(vm: VmConfig, work: string | null, vmDir: string, log?: (line: string) => void, platform?: NodeJS.Platform, opts?: VmStartOptions): Promise<Isolation>;
+export declare function loadHostConfig(configDir: string): Promise<HostConfig>;
+/** The level a run asks for, before availability: what decides whether the
+ *  published VM image is worth fetching. */
+export declare const requestedLevel: (host: HostConfig, req: Request) => "container" | "host" | "none" | "vm" | undefined;
+export interface PreparedVm {
+    host: HostConfig;
+    /** Why the published VM image could not be fetched; `vm` then falls to the next tier. */
+    vmUnavailable?: string;
+}
+/**
+ * Load isolation.json and, when this run asks for `vm` and the owner did not
+ * point it at their own kernel and rootfs, make sure the published guest
+ * image for this mirab version is in <config dir>/vm (downloaded once, then
+ * used offline) and describe `vm` with it.
+ */
+export declare function prepareVm(configDir: string, o: {
+    want: boolean;
+    log?: (line: string) => void;
+    base?: string;
+    /** The mirab release whose image to use (default: this copy's own). A
+     *  package that embeds mirab from git names the canary of that commit. */
+    version?: string;
+    platform?: VmPlatform;
+    /** The backend's own prerequisites (Firecracker, /dev/kvm) are present. */
+    backendReady?: (host: HostConfig) => boolean;
+}): Promise<PreparedVm>;
+/** What this machine can do; tests pass their own. */
+export interface Probes {
+    platform: NodeJS.Platform;
+    /** The `vm` backend (vmBackend) works with this config. */
+    vm(vm: VmConfig): boolean;
+    oci(engine: string, agent: string, endpoint?: string): boolean;
+    colima(): ColimaState;
+    hostUser(user: string): HostUserState;
+}
+export declare const systemProbes: () => Probes;
+export interface Detected {
+    levels: Level[];
+    /** One line per backend that is configured or detected, for `mirab status`. */
+    notes: string[];
+    colima?: ColimaState;
+    hostUser?: HostUserState;
+}
+export declare function detect(host: HostConfig, p?: Probes): Detected;
+export declare function availableLevels(host: HostConfig, p?: Probes): Level[];
+export interface Request {
+    flag?: Level;
+    job?: Level;
+    profile?: Level;
+}
+/**
+ * Resolve a run's isolation. With `vmUnavailable` (the published VM image
+ * could not be fetched), a request for `vm` falls to the strongest other
+ * tier the floor allows, never to `none`, and the result says so.
+ */
+export declare function resolveForHost(host: HostConfig, req: Request, p?: Probes, vmUnavailable?: string): Resolved;
+export declare const backendName: (level: Level, platform?: NodeJS.Platform) => string;
+/** One line for `mirab status` and job logs. */
+export declare function describe(resolved: Resolved, backend?: string): string;
+export declare function startIsolation(level: Level, host: HostConfig, work: string, vmDir: string, log?: (line: string) => void, p?: Probes): Promise<Isolation | null>;
+export declare function statusLines(host: HostConfig, requested?: Request, p?: Probes): string[];
+/** Called once before a session starts: one that cannot isolate does not start. */
+export declare function assertCanIsolate(host: HostConfig, flag?: Level, p?: Probes, vmUnavailable?: string): Resolved;
+/** The VM this machine runs (the published image, fetched on first use), or why not. */
+export declare function requireVm(configDir: string, log?: (line: string) => void, version?: string): Promise<VmConfig>;

package/types/isolation/network.d.ts

@@ -0,0 +1,33 @@
+export declare const BRIDGE = "mirabbr0";
+export declare const SETUP_COMMAND = "sudo scripts/vm-network-setup.sh";
+export interface NetworkState {
+    ready: boolean;
+    /** Tap slots this user can use. */
+    slots: number[];
+    reason?: string;
+}
+export declare function networkState(uid?: number, sys?: string): NetworkState;
+export declare function guestNetwork(slot: number): {
+    tap: string;
+    mac: string;
+    ip: string;
+    cidr: number;
+    gateway: string;
+    dns: string;
+};
+/** Kernel args read by /init-mirab.sh in the guest. */
+export declare function bootNetArgs(n: ReturnType<typeof guestNetwork>): string;
+/** Claim a free tap slot with a pid lock file; stale locks of dead pids are taken over. */
+export declare function claimTap(slots: number[], lockDir: string): {
+    slot: number;
+    release: () => void;
+};
+export declare function networkStatusLine(mode: 'auto' | 'block' | 'allow', s: NetworkState): string;
+export interface NetworkPlan {
+    net?: ReturnType<typeof guestNetwork>;
+    release: () => void;
+    /** Printed in the job log. */
+    note: string;
+}
+/** Decide whether a VM gets a network device. `allow` without setup is an error, `auto` degrades loudly. */
+export declare function planNetwork(mode: 'auto' | 'block' | 'allow', state: NetworkState, lockDir: string): NetworkPlan;

package/types/isolation/policy.d.ts

@@ -0,0 +1,29 @@
+export declare const LEVELS: readonly ['vm', 'container', 'host', 'none'];
+export type Level = (typeof LEVELS)[number];
+export declare const strength: (level: Level) => number;
+export type RequestSource = 'flag' | 'job' | 'profile' | 'host-default' | 'auto';
+export interface PolicyInput {
+    /** `--isolation` on this run. Most specific, wins over everything below. */
+    flag?: Level;
+    /** `isolation:` on the workflow job. */
+    job?: Level;
+    /** `isolation` in the agent profile. */
+    profile?: Level;
+    /** The host default the owner set once in the host config. */
+    hostDefault?: Level;
+    /** Owner floor: levels weaker than this are refused, never upgraded. */
+    floor?: Level;
+    /** Backends usable on this machine. */
+    available: readonly Level[];
+}
+export interface Resolved {
+    level: Level;
+    source: RequestSource;
+    /** Set when the requested level could not be had and a weaker tier took the run. */
+    fallback?: string;
+}
+export declare class IsolationRefused extends Error {
+}
+export declare function parseLevel(text: string | undefined, where: string): Level | undefined;
+export declare function resolveIsolation(input: PolicyInput): Resolved;
+export declare const labelFor: (level: Level, backend: string) => string;

package/types/isolation/session.d.ts

@@ -0,0 +1,99 @@
+import type { Level } from './policy';
+/** The guest-agent wire protocol this CLI speaks; guest-agent/src/main.rs reads the same file. */
+export declare const GUEST_PROTOCOL: number;
+/** Where the guest image is rebuilt from; printed with every mismatch. */
+export declare const REBUILD_HINT: string;
+export interface Channel {
+    write(data: Uint8Array): void;
+    onData(cb: (chunk: Buffer) => void): void;
+    onClose(cb: (error?: Error) => void): void;
+    close(): void;
+}
+export interface ExecOptions {
+    cwd: string;
+    env: Record<string, string>;
+    timeoutMs: number;
+    signal: AbortSignal;
+    /** One call per output line (stdout and stderr), already de-framed. */
+    onLine: (line: string) => Promise<void>;
+}
+export interface Isolation {
+    readonly level: Level;
+    readonly backend: string;
+    /** What `mirab status` and job logs print. */
+    readonly label: string;
+    /** Host path of the job work directory -> where the guest sees it. */
+    guestPath(hostPath: string): string;
+    put(hostPath: string, content: string | Uint8Array, mode?: number): Promise<void>;
+    /** Run a step; resolves with its exit code (124 timeout, 130 cancelled). */
+    exec(argv: string[], options: ExecOptions): Promise<number>;
+    /** Interactive program on a guest pty (spawn --vm). */
+    pty?(request: PtyRequest): Promise<PtyHandle>;
+    /** Read the guest file tree (working-directory sync); backends without a copy omit it. */
+    files?: GuestFiles;
+    /** Messages the guest initiates toward the host on a vsock port (hooks). */
+    onGuestMessage?(port: number, handler: (message: any) => void): void;
+    /** Serve the VM's guest-to-host `port` (e.g. the station's egress): `serve`
+     *  listens on the socket path given, which belongs to this VM alone. */
+    onGuestConnect?(port: number, serve: (socketPath: string) => Promise<import('node:net').Server>): Promise<void>;
+    /** Stop the backend; preserve its workspace for recovery after incomplete sync. */
+    close(options?: {
+        preserveWorkspace?: boolean;
+        /** Keep this VM's root disk (its own copy) at this path once it has
+         *  stopped: how an agent's image is built and updated. */
+        keepRoot?: string;
+    }): Promise<void>;
+}
+/** One entry under a sync root, the same shape the guest agent's `list` op returns. */
+export interface Entry {
+    /** Path relative to the root, `/`-separated. */
+    p: string;
+    /** `f` regular file, `d` directory, `l` symlink. */
+    k: 'f' | 'd' | 'l';
+    /** Permission bits (0 for symlinks). */
+    m: number;
+    s?: number;
+    /** sha256 hex of the content (files). */
+    h?: string;
+    /** Link target (symlinks). */
+    t?: string;
+}
+export interface GuestFiles {
+    list(root: string): Promise<Entry[]>;
+    read(path: string): Promise<Buffer>;
+}
+export interface PtyRequest {
+    argv: string[];
+    env: Record<string, string>;
+    cwd: string;
+    cols: number;
+    rows: number;
+}
+export interface PtyHandle {
+    write(data: Uint8Array | string): void;
+    resize(cols: number, rows: number): void;
+    onData(cb: (data: Buffer) => void): void;
+    onExit(cb: (code: number) => void): void;
+    /** Drop the connection: the guest hangs up the session. */
+    close(): void;
+}
+export type Opener = () => Promise<Channel>;
+export interface GuestHello {
+    /** 1 for agents that predate the handshake (their ping reply has no number). */
+    protocol: number;
+    agent?: string;
+}
+export declare function guestPing(open: Opener): Promise<GuestHello>;
+export declare class GuestProtocolError extends Error {
+}
+/** Refuse a guest agent that speaks another protocol, at connect time and
+ *  with the fix, instead of failing mid-session on an op it lacks. */
+export declare function checkGuestProtocol(hello: GuestHello, image: string): void;
+export declare function guestPut(open: Opener, path: string, content: string | Uint8Array, mode?: number): Promise<void>;
+export declare function guestFiles(open: Opener): GuestFiles;
+export declare function guestExec(open: Opener, argv: string[], o: ExecOptions): Promise<number>;
+export declare function guestPty(open: Opener, request: PtyRequest): Promise<PtyHandle>;
+/** Read one length-prefixed JSON message from a connection the guest opened. */
+export declare function readOneMessage(stream: {
+    on(event: 'data', cb: (c: Buffer) => void): unknown;
+}): Promise<any>;

package/types/isolation/vz.d.ts

@@ -0,0 +1,63 @@
+import { type BootTimings, type VmStartOptions } from './firecracker';
+import { type Isolation } from './session';
+export interface VzConfig {
+    /** The signed mirab-vz helper. */
+    helper: string;
+    /** Guest kernel with virtio-pci built in: the uncompressed arm64 `Image` on
+     *  Apple silicon, a relocatable x86_64 `bzImage` on Intel Macs. */
+    kernel: string;
+    /** Base ext4 image; each VM boots an APFS clone of it. */
+    rootfs: string;
+    memoryMiB: number;
+    vcpus: number;
+    /** Guest vsock port the agent listens on. */
+    port: number;
+    egress: 'auto' | 'block' | 'allow';
+}
+/** Guest -> host vsock ports the helper relays: the spawn --vm hook relay
+ *  (9100) and the way out through the station (9101). */
+export declare const GUEST_TO_HOST_PORTS: number[];
+/** The guest's loopback port for the way out, and the host vsock port it reaches. */
+export declare const EGRESS_GUEST_PORT = 8790;
+export declare const EGRESS_HOST_PORT = 9101;
+export declare const VZ_NETWORK_MARKER = "/etc/mirab/vz-network.json";
+export declare const VZ_SETUP_COMMAND = "sudo ~/.mirab/bin/mirab vm network setup";
+/** What the marker says once the pf anchor denies guests the LAN. */
+export declare const VZ_LAN_DENIED = "lan-denied";
+/** This Mac can run Virtualization.framework guests (hosted CI Macs cannot). */
+export declare function vzHostReady(): boolean;
+export declare function vzAvailable(c: Pick<VzConfig, 'helper' | 'kernel' | 'rootfs'>, platform?: NodeJS.Platform): boolean;
+export interface VzNetworkState {
+    /** The owner installed the pf anchor that denies VZ NAT guests the LAN. */
+    filtered: boolean;
+    reason?: string;
+}
+/** Reads the root-owned marker `mirab vm network setup` writes; never runs sudo or pfctl. */
+export declare function vzNetworkState(marker?: string): VzNetworkState;
+export interface VzNetworkPlan {
+    net: 'none' | 'nat';
+    note: string;
+}
+/**
+ * VZ NAT (vmnet shared mode) gives the guest the internet AND the Mac's LAN,
+ * the Mac itself and the tailnet. Only a root pf anchor can deny those, so NAT
+ * is used only when that anchor is installed; otherwise the VM has no network.
+ */
+export declare function planVzNetwork(egress: VzConfig['egress'], state: VzNetworkState): VzNetworkPlan;
+export declare function vzNetworkStatusLine(egress: VzConfig['egress'], state: VzNetworkState): string;
+export declare function kernelCommandLine(net: VzNetworkPlan['net'], now: Date): string;
+/** The helper's `run` arguments; `share` null = no virtio-fs device at all. */
+export declare function vzRunArgs(o: {
+    cfg: Pick<VzConfig, 'kernel' | 'vcpus' | 'memoryMiB'>;
+    root: string;
+    uds: string;
+    vmDir: string;
+    share: string | null;
+    net: VzNetworkPlan['net'];
+    listen: number[];
+    now?: Date;
+}): string[];
+export declare function startVz(cfg: VzConfig, work: string | null, vmDir: string, log?: (line: string) => void, network?: VzNetworkState, opts?: VmStartOptions): Promise<Isolation & {
+    timings: BootTimings;
+    pid: number;
+}>;

package/types/runner/define.d.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+/** The guests a runner can run. */
+export declare const RUNNER_PLATFORMS: readonly ['linux-x64', 'linux-arm64'];
+export type RunnerPlatform = (typeof RUNNER_PLATFORMS)[number];
+/** Every runner carries `mirab-<os>-<arch>` (e.g. `mirab-linux-arm64`), so a
+ *  job asks for a fresh VM of a platform with one label. */
+export declare const platformLabel: (platform: RunnerPlatform) => string;
+/** One command in the VM. Steps run as the unprivileged `runner` user unless
+ *  `asRoot` (then the step is responsible for dropping to it, with RUNNER_SETPRIV). */
+export interface RunnerStep {
+    argv: string[];
+    env?: Record<string, string>;
+    asRoot?: boolean;
+}
+/** A file put into the VM before the job's steps. `secret` files are never
+ *  logged; they should live on tmpfs (/run) and be removed once read. */
+export interface RunnerFile {
+    path: string;
+    mode: number;
+    content: string;
+    secret?: boolean;
+}
+/** A one-time credential for exactly one job. Every value in `secret` is
+ *  redacted from mirab's logs and never written to the host's disk. */
+export interface RunnerTicket {
+    name: string;
+    secret: Record<string, string>;
+    meta?: Record<string, string>;
+}
+/** What a forge adapter provides. */
+export interface Forge {
+    name: string;
+    /** Host side: register one runner called `name` for one job. */
+    ticket(req: {
+        name: string;
+        labels: string[];
+        platform: RunnerPlatform;
+    }): Promise<RunnerTicket>;
+    guest: {
+        /** Baked into the runner image as root, in the build VM. `key` names
+         *  exactly what is installed (e.g. a version and checksum): a new key is
+         *  a new image. Called again at most daily, to notice new releases. */
+        install(platform: RunnerPlatform): Promise<{
+            key: string;
+            steps: RunnerStep[];
+        }>;
+        /** Hosts the image build may reach for `install`. */
+        buildEgress: string[];
+        /** One job: files put first, then the steps in order; the last one is
+         *  the runner, which takes one job and exits. */
+        job(ticket: RunnerTicket): {
+            files: RunnerFile[];
+            steps: RunnerStep[];
+            env: Record<string, string>;
+        };
+        /** True for the runner's output line that says a job has started: the
+         *  job timer (timeoutMinutes) starts there, not at boot. */
+        started(line: string): boolean;
+    };
+    /** Delete this host's registrations named `prefix*` that aren't in `live`. */
+    reconcile(prefix: string, live: string[]): Promise<void>;
+}
+/** The toolsets a runner image can carry. */
+export declare const TOOLSETS: readonly ['rust', 'node', 'go'];
+export declare const runnerSchema: z.ZodObject<{
+    name: z.ZodString;
+    forge: z.ZodCustom<Forge, Forge>;
+    labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    image: z.ZodDefault<z.ZodObject<{
+        tools: z.ZodDefault<z.ZodObject<{
+            rust: z.ZodOptional<z.ZodString>;
+            node: z.ZodOptional<z.ZodString>;
+            go: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        packages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    vm: z.ZodDefault<z.ZodObject<{
+        vcpus: z.ZodDefault<z.ZodNumber>;
+        memoryMiB: z.ZodDefault<z.ZodNumber>;
+        diskGiB: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    pool: z.ZodDefault<z.ZodObject<{
+        warm: z.ZodDefault<z.ZodNumber>;
+        max: z.ZodDefault<z.ZodNumber>;
+        idleHours: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    timeoutMinutes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type RunnerDefinition = z.infer<typeof runnerSchema>;
+export type RunnerInput = z.input<typeof runnerSchema>;
+export declare function defineRunner(input: RunnerInput): RunnerDefinition;
+/** The unprivileged user every job step runs as (created in the runner image). */
+export declare const RUNNER_USER: {
+    name: string;
+    uid: number;
+    home: string;
+};
+/** Prefix that drops a root command to the runner user, keeping its env. */
+export declare const RUNNER_SETPRIV: string[];
+/** The guest platform a VM on this host runs. */
+export declare function hostRunnerPlatform(arch?: string): RunnerPlatform;

package/types/runner/image.d.ts

@@ -0,0 +1,52 @@
+import type { VmConfig } from '../isolation';
+import { type RunnerDefinition, type RunnerPlatform, type RunnerStep } from './define';
+import { type Fetcher, type ResolvedTool } from './toolsets';
+export declare const runnerImagesDir: (configDir: string) => string;
+export interface RunnerImageMeta {
+    key: string;
+    platform: RunnerPlatform;
+    forge: {
+        name: string;
+        key: string;
+    };
+    tools: ResolvedTool[];
+    packages: string[];
+    diskGiB: number;
+    /** The toolsets' env, and PATH entries to put first, for every job. */
+    env: Record<string, string>;
+    path: string[];
+    builtAt: string;
+}
+export interface RunnerImage {
+    rootfs: string;
+    meta: RunnerImageMeta;
+}
+export interface RunnerRecipe {
+    platform: RunnerPlatform;
+    forge: {
+        name: string;
+        key: string;
+        steps: RunnerStep[];
+        egress: string[];
+    };
+    tools: ResolvedTool[];
+    packages: string[];
+    diskGiB: number;
+}
+/** Everything that decides an image, resolved: the key is the hash of it. */
+export declare function runnerRecipe(def: RunnerDefinition, o?: {
+    platform?: RunnerPlatform;
+    fetch?: Fetcher;
+}): Promise<RunnerRecipe>;
+export declare function runnerImageKey(base: string, r: RunnerRecipe): string;
+/** The build, as root in the build VM, in order. */
+export declare function buildSteps(r: RunnerRecipe): RunnerStep[];
+/** The cached image for `r`, if it was built on this base. */
+export declare function cachedRunnerImage(configDir: string, key: string): Promise<RunnerImage | undefined>;
+/** The runner's image: from the cache, or built now (a few minutes). */
+export declare function runnerImage(o: {
+    configDir: string;
+    vm: VmConfig;
+    recipe: RunnerRecipe;
+    log?: (line: string) => void;
+}): Promise<RunnerImage>;