mirab 0.0.0-stage → 0.2.0

package/src/station/vault.ts

@@ -0,0 +1,96 @@
+// harar as the gateway's vault, on its local socket: one JSON request, the
+// write side closed, one JSON response. The same client npm `harar` ships as
+// `import { vault } from 'harar'` (addiscorp/harar, js/); mirab uses its own
+// copy until that package is published.
+import { connect } from 'node:net'
+import type { Vault } from 'rixse'
+
+/** harar answers are small; anything longer is refused. */
+const MAX_RESPONSE = 1024 * 1024
+
+/** One request to harar (the per-user agent or a primary: the same shape),
+ *  and its answer if it says ok; otherwise why not. */
+function ask(
+  socket: string,
+  request: Record<string, string>,
+  what: string,
+): Promise<{ value?: unknown; hosts?: unknown }> {
+  return new Promise((done, fail) => {
+    const conn = connect(socket)
+    const chunks: Buffer[] = []
+    let size = 0
+    conn.setTimeout(10_000, () =>
+      conn.destroy(new Error('harar did not answer in 10 s')),
+    )
+    conn.on('connect', () => conn.end(JSON.stringify(request)))
+    conn.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > MAX_RESPONSE)
+        conn.destroy(new Error('harar sent too long an answer'))
+      else chunks.push(chunk)
+    })
+    conn.on('error', (e) => fail(new Error(`harar at ${socket}: ${e.message}`)))
+    conn.on('end', () => {
+      let answer: {
+        ok?: boolean
+        value?: unknown
+        hosts?: unknown
+        error?: unknown
+      }
+      try {
+        answer = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+      } catch {
+        return fail(new Error(`harar at ${socket} did not answer with JSON`))
+      }
+      if (
+        typeof answer !== 'object' ||
+        answer === null ||
+        Array.isArray(answer)
+      )
+        return fail(
+          new Error(`harar at ${socket} did not answer with an object`),
+        )
+      if (answer.ok === true) return done(answer)
+      fail(
+        new Error(
+          `harar refused ${what}: ${typeof answer.error === 'string' ? answer.error : 'no answer'}`,
+        ),
+      )
+    })
+  })
+}
+
+/** The hosts harar lets `key` go to (`*.` for any name under one). */
+export async function hararHosts(
+  socket: string,
+  key: string,
+): Promise<string[]> {
+  const { hosts } = await ask(socket, { op: 'hosts', key }, key)
+  if (!Array.isArray(hosts) || !hosts.every((h) => typeof h === 'string'))
+    throw new Error(`harar sent no hosts for ${key}`)
+  return hosts
+}
+
+/** `key`'s value for one request to `host`: harar decides, and records the host. */
+export async function hararSend(
+  socket: string,
+  key: string,
+  host: string,
+): Promise<string> {
+  const { value } = await ask(
+    socket,
+    { op: 'send', key, host },
+    `${key} to ${host}`,
+  )
+  if (typeof value !== 'string')
+    throw new Error(`harar refused ${key} to ${host}: no value`)
+  return value
+}
+
+/** harar at `socket`, as the gateway's vault. */
+export function hararVault(socket: string): Vault {
+  return {
+    hosts: (secret) => hararHosts(socket, secret),
+    send: (secret, host) => hararSend(socket, secret, host),
+  }
+}

package/src/test-cli.ts

@@ -0,0 +1,90 @@
+import { generateKeyPairSync } from 'node:crypto'
+import { mkdir, mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+export function testIdentity(apiToken: unknown = null) {
+  const keys = generateKeyPairSync('ed25519')
+  return {
+    schema: 1,
+    name: 'alice',
+    device: 'test',
+    apiToken,
+    publicKey:
+      'ed25519:' +
+      keys.publicKey.export({ format: 'der', type: 'spki' }).toString('base64'),
+    secretKey: keys.privateKey
+      .export({ format: 'der', type: 'pkcs8' })
+      .toString('base64'),
+    createdAt: new Date().toISOString(),
+  }
+}
+export async function fixture(
+  handler: (request: Request) => Response | Promise<Response>,
+) {
+  await mkdir(resolve('.tmp'), { recursive: true })
+  const root = await mkdtemp(join(resolve('.tmp'), 'cli-review-'))
+  const server = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: handler })
+  const origin = server.url.origin
+  return {
+    root,
+    origin,
+    async identity(
+      token: unknown = { server: origin, token: 'gf_fixturetoken' },
+    ) {
+      const identity = testIdentity(token)
+      await writeFile(join(root, 'identity.json'), JSON.stringify(identity), {
+        mode: 0o600,
+      })
+      return identity
+    },
+    async agent(token: string | null = 'gf_agentfixture') {
+      await mkdir(join(root, 'agents'), { recursive: true })
+      const agent = {
+        ...testIdentity(),
+        name: 'alice/test',
+        server: origin,
+        token,
+        requestId: 'request-1',
+      }
+      await writeFile(join(root, 'agents/test.json'), JSON.stringify(agent), {
+        mode: 0o600,
+      })
+      return agent
+    },
+    async close() {
+      server.stop(true)
+      await rm(root, { recursive: true, force: true })
+    },
+  }
+}
+export function startCLI(root: string, args: string[], stdin?: string) {
+  return Bun.spawn(
+    [
+      process.execPath,
+      'run',
+      resolve('src/mirab.ts'),
+      '--config-dir',
+      root,
+      ...args,
+    ],
+    {
+      stdin: stdin === undefined ? 'ignore' : new Blob([stdin]),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    },
+  )
+}
+export async function cli(root: string, args: string[], stdin?: string) {
+  const proc = startCLI(root, args, stdin)
+  const timeout = setTimeout(() => proc.kill('SIGTERM'), 10000)
+  try {
+    const [code, out, err] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ])
+    return { code, out, err }
+  } finally {
+    clearTimeout(timeout)
+  }
+}

package/src/tools.ts

@@ -0,0 +1,3 @@
+// `import { defineTool } from 'mirab/tools'`, as eve's tools do.
+export { defineTool } from './agent/define'
+export type { Tool } from './agent/define'

package/types/agent/define.d.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+/** Why `name` isn't a harar name of `kind` (`<org>.<kind>.<local>`), or null. */
+export declare function nameProblem(name: string, kind: 'agent' | 'channel' | 'human', example: string): string | null;
+/** Why `name` isn't an agent name (`<org>.agent.<local>`, harar's rules), or null. */
+export declare function agentNameProblem(name: string): string | null;
+/** Why `name` isn't a human's harar name (`<org>.human.<local>`), or null. */
+export declare function humanNameProblem(name: string): string | null;
+/** `provider/model`, e.g. `anthropic/claude-sonnet-5-5`. */
+export declare const MODEL: RegExp;
+/** A tool's name is its file's name, or its key in `tools`; the model sees exactly that. */
+export declare const TOOL_NAME: RegExp;
+/** Why `name` can't be a tool's name, or null. `__proto__` is refused: as a
+ *  key in plain data it is dropped or changes the object, never a tool. */
+export declare function toolNameProblem(name: string): string | null;
+/** A tool's input: a JSON Schema for an object, which is what models take. */
+export declare const toolInput: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** A tool that is an executable in the VM: the model's input as JSON on its
+ *  stdin (checked against `input` first), its answer as JSON on stdout. */
+export declare const commandToolSchema: z.ZodObject<{
+    description: z.ZodString;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type CommandTool = z.infer<typeof commandToolSchema>;
+/** Tools by name. zod's record drops a `__proto__` key before checking it,
+ *  so the raw data is checked for one first. */
+export declare function toolRecord<T extends z.ZodType>(tool: T): z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, T>>;
+/** A whitelist entry as the station matches it: `api.github.com`, or
+ *  `*.github.com` for every name under it. Names only, never an address. */
+export declare function domainProblem(domain: string): string | null;
+/** Characters that can make a terminal show something other than the text:
+ *  controls, C1 controls, line separators and bidirectional overrides. A
+ *  person approves rules by reading them, so none may appear in one. */
+export declare const UNSHOWABLE: RegExp;
+/** What agent/agent.ts declares. TypeScript tools are files in agent/tools/;
+ *  `tools` here holds command tools. */
+export declare const agentSchema: z.ZodObject<{
+    name: z.ZodString;
+    model: z.ZodString;
+    tools: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>>;
+    packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    channels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    gateway: z.ZodOptional<z.ZodObject<{
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            host: z.ZodString;
+            method: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            effect: z.ZodEnum<{
+                apply: "apply";
+                forbidden: "forbidden";
+                request: "request";
+            }>;
+        }, z.core.$strict>>>;
+        secrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            agent: z.ZodString;
+            approved: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Agent = z.infer<typeof agentSchema>;
+export declare function defineAgent(agent: Agent): Agent;
+export interface Tool<Input extends z.ZodType> {
+    description: string;
+    inputSchema: Input;
+    execute(input: z.infer<Input>): unknown | Promise<unknown>;
+}
+export declare function defineTool<Input extends z.ZodType>(tool: Tool<Input>): Tool<Input>;

package/types/agent/manifest.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { type Tool } from './define';
+/** A TypeScript tool, `agent/<file>`, run by the agent loop. */
+export declare const typescriptToolSchema: z.ZodObject<{
+    description: z.ZodString;
+    file: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export declare const manifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    model: z.ZodString;
+    instructions: z.ZodString;
+    tools: z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        description: z.ZodString;
+        file: z.ZodString;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>, z.ZodObject<{
+        description: z.ZodString;
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>]>>>;
+    packages: z.ZodArray<z.ZodString>;
+    domains: z.ZodArray<z.ZodString>;
+    channels: z.ZodArray<z.ZodString>;
+    gateway: z.ZodDefault<z.ZodObject<{
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            host: z.ZodString;
+            method: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            effect: z.ZodEnum<{
+                apply: "apply";
+                forbidden: "forbidden";
+                request: "request";
+            }>;
+        }, z.core.$strict>>>;
+        secrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            agent: z.ZodString;
+            approved: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Manifest = z.infer<typeof manifestSchema>;
+/** Checks manifest data from anywhere (agent.ts, `nix eval --json`). */
+export declare function parseManifest(data: unknown, from: string): Manifest;
+export interface LoadedManifest {
+    manifest: Manifest;
+    /** The TypeScript tools as their files export them, by name. */
+    typescript: Record<string, Tool<z.ZodType>>;
+}
+/** Reads `<project>/agent` (agent.ts, instructions.md, tools/*.ts) into a manifest. */
+export declare function loadManifest(project: string): Promise<LoadedManifest>;

package/types/agent/modules.d.ts

@@ -0,0 +1 @@
+export declare function registerAgentModules(): void;

package/types/images.d.ts

@@ -0,0 +1,124 @@
+import { type VmConfig } from './isolation';
+import type { Isolation } from './isolation/session';
+/** Where apt goes, over HTTPS: the station lets nothing else out. */
+export declare const UBUNTU_MIRRORS: string[];
+export interface ImageMeta {
+    key: string;
+    packages: string[];
+    base: string;
+    builtAt: string;
+    updatedAt: string;
+    /** What the last update upgraded. */
+    upgraded: string[];
+}
+export declare const imagesDir: (configDir: string) => string;
+/** The base image: where it is, its size, when it was written, and a hash of
+ *  its first 4 MB (the filesystem's superblock and early blocks), without
+ *  reading all 3 GB. A new base is a new key. */
+export declare function baseId(rootfs: string): Promise<string>;
+/** A cache key for any build recipe: the base plus the recipe as canonical
+ *  JSON (object keys sorted at every level), so equal recipes share a key. */
+export declare function recipeKey(base: string, recipe: unknown): string;
+/** The cache key: the base and the package list, order and repeats aside. */
+export declare function imageKey(base: string, packages: string[]): string;
+export interface CachedImage {
+    rootfs: string;
+    meta: ImageMeta;
+}
+export declare function cachedImage(configDir: string, key: string, base?: string): Promise<CachedImage | undefined>;
+/** In a build VM: tools other than apt (curl, rustup) reach the station too. */
+export declare const BUILD_ENV: {
+    PATH: string;
+    HOME: string;
+    DEBIAN_FRONTEND: string;
+    LANG: string;
+    HTTP_PROXY: string;
+    HTTPS_PROXY: string;
+    http_proxy: string;
+    https_proxy: string;
+    NO_PROXY: string;
+};
+/** Runs one command as root in the VM; a failure carries the end of its output. */
+export declare function run(iso: Pick<Isolation, 'exec'>, argv: string[], log?: (l: string) => void, env?: Record<string, string>): Promise<string[]>;
+/** A build VM on `rootfs` whose only way out is the station, to the hosts in
+ *  `allow` (default: Ubuntu's mirrors, for apt). `rootGiB` grows its root
+ *  disk first; the build then grows the filesystem (resize2fs). */
+export declare function bootForBuild(o: {
+    configDir: string;
+    vm: VmConfig;
+    rootfs: string;
+    key: string;
+    allow?: string[];
+    rootGiB?: number;
+    log?: (line: string) => void;
+}): Promise<{
+    iso: Isolation;
+    cleanup: () => Promise<void>;
+}>;
+/** Grows the running guest's root filesystem to fill its (grown) disk, while
+ *  mounted. resize2fs can't: the kernel mounts the root as /dev/root, so it
+ *  doesn't see /dev/vda as mounted and refuses an exclusive open. This is the
+ *  ioctl resize2fs itself uses online (EXT4_IOC_RESIZE_FS). */
+export declare const GROW_ROOT_FS: string;
+/** Stops the VM and keeps its root disk as the image in `dir`, moving any
+ *  image there now aside as the previous one. */
+export declare function keep(iso: Pick<Isolation, 'exec' | 'close'>, dir: string, meta: object, opts?: {
+    previous?: boolean;
+}): Promise<string>;
+/** The agent's image: from the cache, or built now. */
+export declare function agentImage(o: {
+    configDir: string;
+    vm: VmConfig;
+    packages: string[];
+    log?: (line: string) => void;
+}): Promise<string>;
+/** The packages a dry-run `apt-get -s upgrade` would upgrade. */
+export declare function upgradesIn(lines: string[]): string[];
+/** Boots the agent's image and upgrades it in place when apt has anything
+ *  newer; the image before stays as the previous one. */
+export declare function updateImage(o: {
+    configDir: string;
+    vm: VmConfig;
+    packages: string[];
+    log?: (line: string) => void;
+}): Promise<{
+    rootfs: string;
+    upgraded: string[];
+}>;
+export interface ListedImage {
+    key: string;
+    packages: string[];
+    /** Built on the base this mirab boots now; otherwise it is never used again. */
+    current: boolean;
+    /** When it was built, updated or booted last. */
+    usedAt: Date;
+    bytes: number;
+}
+/** Every cached agent image, newest use first. */
+export declare function listImages(configDir: string, currentBase: string): Promise<ListedImage[]>;
+/**
+ * What `mirab image prune` removes: images built on a base this mirab no
+ * longer boots (after an upgrade they are never used again), images unused
+ * for `days` (at least one), and what a build left behind a day or more ago:
+ * scratch and an image directory that never got as far as its meta.json. An
+ * image used in the last hour always stays, and a VM boots from its own copy,
+ * so a running one is never touched. One that can't be removed is reported,
+ * and the rest go on.
+ */
+export declare function pruneImages(o: {
+    configDir: string;
+    currentBase: string;
+    days: number;
+    dryRun?: boolean;
+    now?: Date;
+}): Promise<{
+    removed: {
+        key: string;
+        why: string;
+        bytes: number;
+    }[];
+    failed: {
+        key: string;
+        error: string;
+    }[];
+}>;

package/types/index.d.ts

@@ -0,0 +1,6 @@
+export { agentNameProblem, defineAgent, defineTool } from './agent/define';
+export type { Agent, Tool } from './agent/define';
+export { loadManifest, manifestSchema, parseManifest } from './agent/manifest';
+export type { Manifest } from './agent/manifest';
+export { defineRunner, RUNNER_PLATFORMS, RUNNER_SETPRIV, RUNNER_USER, TOOLSETS, } from './runner/define';
+export type { Forge, RunnerDefinition, RunnerFile, RunnerInput, RunnerPlatform, RunnerStep, RunnerTicket, } from './runner/define';

package/types/isolation/colima.d.ts

@@ -0,0 +1,37 @@
+export declare const COLIMA_INSTALL = "brew install colima docker && colima start --vm-type vz --mount-type virtiofs";
+export interface ColimaMount {
+    location: string;
+    writable: boolean;
+}
+export type ColimaState = {
+    running: true;
+    /** `unix://…/docker.sock`, passed to docker as `--host`. */
+    socket: string;
+    vmType: string;
+    arch: string;
+    mountType: string;
+    mounts: ColimaMount[];
+} | {
+    running: false;
+    reason: string;
+    fix: string;
+};
+export interface ColimaProbe {
+    /** stdout of `colima status --json`, or undefined if it failed or is not installed. */
+    status(): string | undefined;
+    installed(): boolean;
+    /** ~/.colima/default/colima.yaml, if present. */
+    config(): string | undefined;
+    home: string;
+    exists(path: string): boolean;
+}
+export declare const systemColimaProbe: (profile?: string) => ColimaProbe;
+/** The `mounts:` list of colima.yaml; an empty list means Colima's default ($HOME, writable). */
+export declare function colimaMounts(yaml: string | undefined, home: string): {
+    location: string;
+    writable: boolean;
+}[];
+export declare function detectColima(p: ColimaProbe): ColimaState;
+/** The mount that makes `path` visible in Colima's VM, if any (and writable when asked). */
+export declare function colimaMountFor(path: string, mounts: ColimaMount[], writable: boolean): ColimaMount | undefined;
+export declare function colimaStatusLine(c: ColimaState): string;

package/types/isolation/container.d.ts

@@ -0,0 +1,25 @@
+import { type Isolation } from './session';
+export interface OciConfig {
+    /** `docker` or `podman` (anything with the same CLI). */
+    engine: string;
+    image: string;
+    /** Static linux guest agent binary, mounted read-only into the container. */
+    agent: string;
+    memory: string;
+    cpus: string;
+    pids: number;
+    egress: 'auto' | 'block' | 'allow';
+    /** Engine endpoint (`docker --host`), e.g. Colima's socket on macOS. */
+    host?: string;
+    /** Where the engine runs, for labels: `Colima vz VM`. */
+    where?: string;
+}
+export declare const EGRESS_NETWORK = "mirab-egress";
+/** Network the container joins: the filtered bridge, or none. `allow` without setup is an error. */
+export declare function containerNetwork(mode: OciConfig['egress'], ready: boolean, setup?: string): "mirab-egress" | "none";
+export declare const GUEST_WORK = "/workspace";
+export declare const NETWORK_SETUP = "sudo scripts/vm-network-setup.sh";
+/** The same script, run inside Colima's VM, where the containers' network lives. */
+export declare const COLIMA_NETWORK_SETUP = "colima ssh -- sudo sh -s up < scripts/vm-network-setup.sh";
+export declare function ociAvailable(engine: string, agent: string, host?: string): boolean;
+export declare function startOci(cfg: OciConfig, work: string, log?: (line: string) => void): Isolation;

package/types/isolation/firecracker.d.ts

@@ -0,0 +1,55 @@
+import { type Server } from 'node:net';
+import { type Channel, type Isolation, type Opener } from './session';
+export interface FirecrackerConfig {
+    firecracker: string;
+    kernel: string;
+    /** Read-only base image containing mirab-guest-agent and /init-mirab.sh. */
+    rootfs: string;
+    memoryMiB: number;
+    vcpus: number;
+    /** Guest vsock port the agent listens on. */
+    port: number;
+    /** `block` = no network device; `allow` = tap or refuse; `auto` = tap when set up, else none. */
+    egress: 'auto' | 'block' | 'allow';
+}
+export declare const GUEST_WORK = "/workspace";
+/**
+ * The Firecracker to run when isolation.json names none: the one shipped next
+ * to the mirab executable (where mirab's packaging will put it), else
+ * `firecracker` on PATH. `vm.firecracker` in isolation.json wins over both.
+ */
+export declare function defaultFirecracker(execPath?: string): string;
+/** /dev/kvm, Firecracker and mke2fs: what this host needs besides the guest image. */
+export declare function firecrackerHostReady(firecracker: string): boolean;
+export declare function firecrackerAvailable(c: Pick<FirecrackerConfig, 'firecracker' | 'kernel' | 'rootfs'>): boolean;
+export declare function vsockChannel(uds: string, port: number): Promise<Channel>;
+/**
+ * The Isolation members every vsock backend shares (Firecracker, vz): the
+ * work directory (when there is one) appears at /workspace, and guest connections to host port N
+ * arrive on the unix socket `<uds>_N` (Firecracker's convention, which the vz
+ * helper follows too).
+ */
+export declare function vsockMembers(open: Opener, uds: string, work: string | null, listeners: Server[]): Pick<Isolation, 'guestPath' | 'put' | 'exec' | 'pty' | 'files' | 'onGuestMessage' | 'onGuestConnect'>;
+/** What a VM start may add to the backend's config. */
+export interface VmStartOptions {
+    /** Grow this VM's root disk clone to this size before boot (sparse; never
+     *  shrinks). The guest sees a bigger /dev/vda; growing the filesystem on it
+     *  (resize2fs) is the guest's job. */
+    rootGiB?: number;
+    /** vz: guest-to-host vsock ports to forward (default GUEST_TO_HOST_PORTS);
+     *  [] for a VM that must not reach the host at all. Firecracker forwards a
+     *  port only when someone serves it (onGuestConnect), so it needs no list. */
+    listen?: number[];
+}
+/** Sparse-grows a disk image file to `gib` GiB; refuses to shrink one. */
+export declare function growDisk(path: string, gib: number): Promise<void>;
+/** Checked bytes, not a signed 32-bit shift: large work images stay positive. */
+export declare function workImageBytes(usedKiB: number): number;
+export interface BootTimings {
+    imageMs: number;
+    bootToAgentMs: number;
+}
+export declare function startFirecracker(cfg: FirecrackerConfig, work: string | null, vmDir: string, log?: (line: string) => void, opts?: VmStartOptions): Promise<Isolation & {
+    timings: BootTimings;
+    pid: number;
+}>;

package/types/isolation/host-user.d.ts

@@ -0,0 +1,47 @@
+import { type Isolation } from './session';
+export declare const MARKER_DIR = "/etc/mirab/host-users";
+/** What scripts/host-user-setup.sh wrote to /etc/mirab/host-users/<user>.json. */
+export interface Marker {
+    version: 1;
+    user: string;
+    uid: number;
+    gid: number;
+    owner: string;
+    agent: string;
+    workRoot: string;
+    network?: string;
+}
+/** Everything detection looks at, so tests can describe any machine. */
+export interface HostProbe {
+    marker(user: string): string | undefined;
+    uidOf(user: string): number | undefined;
+    me: {
+        uid: number;
+        name: string;
+        groups: number[];
+    };
+    stat(path: string): {
+        uid: number;
+        gid: number;
+        mode: number;
+        dir: boolean;
+    } | undefined;
+}
+export declare const systemProbe: (markerDir?: string) => HostProbe;
+export type HostUserState = {
+    ok: true;
+    marker: Marker;
+} | {
+    ok: false;
+    reason: string;
+    fix: string;
+};
+export declare const setupCommand: (user: string, owner: string) => string;
+/** Is the host tier for `user` set up, and set up safely? Never runs sudo. */
+export declare function hostUserState(user: string, probe: HostProbe): HostUserState;
+/**
+ * Stage the job directory under the shared work root, then run the agent as
+ * the dedicated user. `runAs` is the privilege switch: the sudo rule from the
+ * setup script; tests pass [] to exercise the same path as themselves.
+ */
+export declare function startHostUser(marker: Marker, work: string, log?: (line: string) => void, runAs?: string[]): Promise<Isolation>;