mirab 0.0.0-stage → 0.2.0

package/src/spawn.ts

@@ -0,0 +1,468 @@
+import { spawn } from 'node:child_process'
+import { createConnection } from 'node:net'
+import { realAgent, agentEnvironment } from './spawn-binary'
+import { profileSchema, resolveProfile } from './agent-profiles'
+import { MULTIPASS_UNAVAILABLE, usesMultipass } from './isolation/multipass'
+import { parseNudge } from './spawn-nudge'
+import type { ReportTarget } from './spawn-report'
+import type { BridgeTarget } from './spawn-bridge'
+import { runNative, supportsPty, debugFallback } from './spawn-native'
+import { DEFAULT_COLS, DEFAULT_ROWS } from './spawn-detach'
+import {
+  detachCommands,
+  detachedReady,
+  detachedSpawn,
+  dimension,
+} from './spawn-attach'
+import { readFile, rename, writeFile } from 'node:fs/promises'
+import { createHash, randomBytes } from 'node:crypto'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+import { loadHostConfig, parseLevel, prepareVm, statusLines } from './isolation'
+import { Command, InvalidArgumentError } from 'commander'
+import { spawnWorkerSource } from './spawn-bundle' with { type: 'macro' }
+import {
+  liveSessions,
+  localRequest,
+  privateSessionsDirectory,
+  socketPath,
+  MAX_MESSAGE_BYTES,
+} from './spawn-sessions'
+
+/** Linux caps one argv string at 128 KiB, so the bundled worker runs from a
+ * content-addressed file in the private ~/.mirab directory, not `node -e`. */
+async function workerFile() {
+  const source = await spawnWorkerSource()
+  const directory = dirname(await privateSessionsDirectory())
+  const path = join(
+    directory,
+    `spawn-worker-${createHash('sha256').update(source).digest('hex').slice(0, 16)}.mjs`,
+  )
+  if ((await readFile(path, 'utf8').catch(() => null)) !== source) {
+    const partial = `${path}.${process.pid}.tmp`
+    await writeFile(partial, source, { mode: 0o600 })
+    await rename(partial, path)
+  }
+  return path
+}
+
+function idleMilliseconds(value: string) {
+  const number = Number(value)
+  if (!Number.isSafeInteger(number) || number < 0 || number > 60000)
+    throw new InvalidArgumentError('idle-ms must be an integer from 0 to 60000')
+  return number
+}
+export function spawnCommands(
+  program: Command,
+  resolveIdentity?: (
+    label: string,
+    cwd: string,
+    localProfile: boolean,
+  ) => Promise<{ agent: string; report?: ReportTarget; bridge?: BridgeTarget }>,
+) {
+  program
+    .command('spawn <agent> [args...]')
+    .description('run a terminal agent with a private local message endpoint')
+    .passThroughOptions()
+    .option(
+      '--as <label>',
+      'report state with an approved local agent identity',
+    )
+    .option(
+      '--channel <owner/repo>',
+      "with --as: hear @mentions in this repo's channel (typed into the agent); repeat",
+      (value: string, previous: string[] = []) => [...previous, value],
+    )
+    .option('--print-id', 'print the local session id to stderr')
+    .option(
+      '--nudge <rule>',
+      "watchdog rule added to the profile's: idle:<duration>[:<limit>][:<message>], waiting:<duration>, ci:<owner/repo>, mention-unanswered:<duration>; repeat; put it before <agent>",
+      (value: string, previous: string[] = []) => {
+        try {
+          parseNudge(value)
+        } catch (error) {
+          throw new InvalidArgumentError((error as Error).message)
+        }
+        return [...previous, value]
+      },
+    )
+    .option(
+      '--vm',
+      'run the agent inside a VM: vz on macOS, Firecracker on Linux (each with its image fetched on first use), Multipass on Windows',
+    )
+    .option(
+      '--config-dir <path>',
+      'mirab config directory (isolation.json)',
+      join(homedir(), '.config', 'mirab'),
+    )
+    .option('--name <id>', 'memorable local session name')
+    .option(
+      '--idle-ms <ms>',
+      'wait for user input to be idle before injecting',
+      idleMilliseconds,
+      1500,
+    )
+    .option(
+      '--detach',
+      'run in the background with no terminal; prints the session id (see mirab attach, mirab stop)',
+    )
+    .option('--cols <n>', 'detached terminal width', dimension, DEFAULT_COLS)
+    .option('--rows <n>', 'detached terminal height', dimension, DEFAULT_ROWS)
+    .allowUnknownOption()
+    .action(
+      async (
+        agent: string,
+        args: string[],
+        opts: {
+          name?: string
+          idleMs: number
+          as?: string
+          channel?: string[]
+          printId?: boolean
+          nudge?: string[]
+          detach?: boolean
+          cols: number
+          rows: number
+          vm?: boolean
+          configDir: string
+        },
+      ) => {
+        const resolved =
+          agent === 'agent'
+            ? await resolveProfile(args.shift() ?? '', args)
+            : undefined
+        let profile = resolved?.profile
+        if (profile && opts.as && opts.as !== profile.name)
+          throw Error(
+            'A profile uses its own approved agent label; --as must match the profile name',
+          )
+        if (profile && opts.name)
+          throw Error('Profile sessions are named after the agent; omit --name')
+        if (opts.channel?.length) {
+          if (profile)
+            throw Error(
+              'A profile lists its own channels; use mirab agent edit --channel',
+            )
+          if (!opts.as)
+            throw Error(
+              '--channel needs --as <label>: mentions are addressed to an agent',
+            )
+          // A profile for this session only: the bridge hears the agent's mentions there.
+          profile = profileSchema.parse({
+            name: opts.as,
+            runtime: agent,
+            directory: process.cwd(),
+            args,
+            channels: opts.channel,
+          })
+        }
+        // Without an identity provider (mirab#2), an identity or a channel
+        // would be silently ignored; say so instead.
+        if (!resolveIdentity && (opts.as || profile?.channels?.length))
+          throw Error(
+            '--as and --channel need an agent identity, which mirab gets from harar (addiscorp/mirab#2); run without --as, and remove the channels from a profile, for now',
+          )
+        agent = profile?.runtime ?? agent
+        args = resolved?.args ?? args
+        const cwd = profile?.directory ?? process.cwd()
+        const label = profile?.name ?? opts.as
+        const binary = realAgent(agent, cwd)
+        if (opts.detach && !supportsPty())
+          throw Error(
+            'Detached sessions need a PTY, unavailable on this platform',
+          )
+        // macOS and Windows: Multipass, once mirab is on npm for its VM to
+        // install. Until then it refuses here, before anything else.
+        if (opts.vm && usesMultipass(opts.configDir))
+          throw Error(
+            `--vm: ${MULTIPASS_UNAVAILABLE} It never falls back to running on the host.`,
+          )
+        // Detached, the guest pty is the terminal; attached, it needs a real one.
+        if (
+          opts.vm &&
+          !opts.detach &&
+          (!process.stdin.isTTY || !process.stdout.isTTY || !supportsPty())
+        )
+          throw Error(
+            '--vm needs an interactive terminal (or --detach); it never falls back to running on the host',
+          )
+        // First --vm use: fetch the published guest image here, where the
+        // terminal shows its progress; the worker then finds it installed.
+        if (opts.vm) {
+          const { vmUnavailable } = await prepareVm(opts.configDir, {
+            want: true,
+            log: (line) => console.error(`mirab: ${line}`),
+          })
+          if (vmUnavailable)
+            throw Error(
+              `--vm: ${vmUnavailable}. It never falls back to running on the host`,
+            )
+        }
+        if (
+          !opts.detach &&
+          (!process.stdin.isTTY || !process.stdout.isTTY || !supportsPty())
+        ) {
+          process.exitCode = await runNative(
+            binary,
+            args,
+            cwd,
+            agentEnvironment(binary, profile?.env),
+          )
+          return
+        }
+        const identity =
+          label && resolveIdentity
+            ? await resolveIdentity(label, cwd, !!profile)
+            : undefined
+        const report = identity?.report
+        const nudges = [...(profile?.nudges ?? []), ...(opts.nudge ?? [])]
+        const rules = nudges.map(parseNudge)
+        // ci and mention rules read the profile's events subscription.
+        if (rules.some((r) => r.kind === 'ci') && !(profile && identity))
+          throw Error(
+            'ci nudges need an agent profile with an approved identity (mirab spawn agent <name>)',
+          )
+        if (
+          rules.some((r) => r.kind === 'mention-unanswered') &&
+          !(profile?.channels?.length && identity)
+        )
+          throw Error(
+            'mention-unanswered nudges need an agent profile with --channel and an approved identity',
+          )
+        const bridge =
+          profile?.channels?.length || rules.some((r) => r.kind === 'ci')
+            ? identity?.bridge
+            : undefined
+        const id =
+          profile?.name ??
+          opts.name ??
+          `agent-${randomBytes(3).toString('hex')}`
+        socketPath(id)
+        const ptyModule = import.meta.url.includes('$bunfs')
+          ? join(
+              dirname(process.execPath),
+              '..',
+              'vendor',
+              'node-pty',
+              'lib',
+              'index.js',
+            )
+          : new URL('../node_modules/node-pty/lib/index.js', import.meta.url)
+              .pathname
+        const worker = spawn(
+          opts.vm ? process.execPath : 'node',
+          [
+            ...(opts.vm
+              ? import.meta.url.includes('$bunfs')
+                ? ['__vm-worker']
+                : [
+                    'run',
+                    new URL('./mirab.ts', import.meta.url).pathname,
+                    '__vm-worker',
+                  ]
+              : [await workerFile()]),
+            JSON.stringify({
+              agent,
+              args,
+              id,
+              idleMs: opts.idleMs,
+              ptyModule,
+              vm: opts.vm ? { configDir: opts.configDir } : undefined,
+              // Inside the guest the hook is the guest agent, which relays over vsock.
+              hookCommand: opts.vm
+                ? ['/usr/local/bin/mirab-guest-agent']
+                : import.meta.url.includes('$bunfs')
+                  ? [process.execPath]
+                  : [
+                      process.execPath,
+                      'run',
+                      new URL('./mirab.ts', import.meta.url).pathname,
+                    ],
+              reporting: !!report,
+              bridging: !!bridge,
+              identity: identity?.agent,
+              printId: opts.printId,
+              profile: profile
+                ? {
+                    name: profile.name,
+                    channels: profile.channels,
+                    on: profile.on,
+                  }
+                : undefined,
+              envAllowlist: profile?.env,
+              nudges,
+              detach: opts.detach
+                ? { cols: opts.cols, rows: opts.rows }
+                : undefined,
+            }),
+          ],
+          opts.detach
+            ? detachedSpawn(cwd)
+            : {
+                cwd,
+                stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+              },
+        )
+        if (report)
+          worker.once('spawn', () => worker.send({ type: 'report', report }))
+        if (bridge)
+          worker.once('spawn', () => worker.send({ type: 'bridge', bridge }))
+        if (opts.detach) return console.log(await detachedReady(worker))
+        const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGHUP', 'SIGWINCH']
+        const interrupted = () => {}
+        process.on('SIGINT', interrupted)
+        const disconnected = () => worker.kill('SIGHUP')
+        process.on('disconnect', disconnected)
+        const handlers = signals.map((signal) => () => worker.kill(signal))
+        signals.forEach((signal, index) => process.on(signal, handlers[index]))
+        try {
+          process.exitCode = await new Promise<number>((resolve, reject) => {
+            worker.once('error', reject)
+            worker.once('exit', (code, signal) =>
+              resolve(
+                code ??
+                  (signal === 'SIGINT' ? 130 : signal === 'SIGHUP' ? 129 : 143),
+              ),
+            )
+          })
+        } catch (error) {
+          if (opts.vm) throw error
+          debugFallback(error)
+          process.exitCode = await runNative(
+            realAgent(agent, cwd),
+            args,
+            cwd,
+            agentEnvironment(realAgent(agent, cwd), profile?.env),
+          )
+        } finally {
+          process.off('SIGINT', interrupted)
+          process.off('disconnect', disconnected)
+          signals.forEach((signal, index) =>
+            process.off(signal, handlers[index]),
+          )
+        }
+      },
+    )
+  program
+    .command('send <id> <message>')
+    .description(
+      'queue a prompt in a local agent session (use - to read stdin)',
+    )
+    .action(async (id: string, message: string) => {
+      const directory = await privateSessionsDirectory()
+      if (message === '-') {
+        const chunks: Buffer[] = []
+        let bytes = 0
+        for await (const chunk of process.stdin) {
+          bytes += chunk.length
+          if (bytes > MAX_MESSAGE_BYTES)
+            throw new Error('Message exceeds 64 KiB')
+          chunks.push(Buffer.from(chunk))
+        }
+        message = Buffer.concat(chunks).toString('utf8')
+      }
+      await localRequest(socketPath(id, directory), { type: 'send', message })
+      // The sender (often another agent) needs to know the session accepted
+      // it; delivery waits for the agent to be ready (see mirab status).
+      console.log(`queued for ${id}`)
+    })
+  program
+    .command('sync <id>')
+    .description(
+      "copy a --vm session's working-directory changes back to the host now (also done when it exits)",
+    )
+    .action(async (id: string) => {
+      const r = await localRequest(
+        socketPath(id, await privateSessionsDirectory()),
+        { type: 'sync' },
+        10 * 60_000,
+      )
+      console.log(
+        `${id}: ${r.written} written, ${r.deleted} deleted, ${r.conflicts.length} conflicts${r.held.length ? `, ${r.held.length} held` : ''}${r.rejected ? `, ${r.rejected} rejected` : ''}`,
+      )
+      for (const c of r.conflicts)
+        console.log(
+          `  kept host copy of ${c.path} (${c.reason})${c.saved ? `; guest copy: ${c.saved}` : ''}`,
+        )
+      for (const h of r.held)
+        console.log(
+          `  held ${h.path}: the agent changed its own definition${h.saved ? `; its version: ${h.saved}` : ''}`,
+        )
+    })
+  program
+    .command('status [id]')
+    .description(
+      "inspect a live local agent session, or (no id) show this machine's isolation",
+    )
+    .option(
+      '--isolation <level>',
+      'with no id: show the outcome of this request',
+    )
+    .option(
+      '--config-dir <path>',
+      'mirab config directory',
+      join(homedir(), '.config', 'mirab'),
+    )
+    .action(async (id: string | undefined, opts) => {
+      if (!id) {
+        const host = await loadHostConfig(opts.configDir)
+        for (const line of statusLines(host, {
+          flag: parseLevel(opts.isolation, '--isolation'),
+        }))
+          console.log(line)
+        return
+      }
+      const directory = await privateSessionsDirectory()
+      console.log(
+        JSON.stringify(
+          await localRequest(socketPath(id, directory), { type: 'info' }),
+        ),
+      )
+    })
+  detachCommands(program)
+  program
+    .command('sessions')
+    .description('list live local agent sessions and remove stale sockets')
+    .option('--json', 'print session metadata as JSON')
+    .action(async (opts: { json?: boolean }) => {
+      const sessions = await liveSessions()
+      if (opts.json) console.log(JSON.stringify(sessions))
+      else {
+        console.log(
+          'ID\tAGENT\tPROFILE\tSTATE\tTOOL\tLAST ACTIVITY\tCWD\tPID\tSTARTED',
+        )
+        for (const session of sessions)
+          console.log(
+            [
+              session.id,
+              session.agent,
+              session.profile ?? '',
+              session.state === 'tool_start' ? 'running a tool' : session.state,
+              session.tool ?? '',
+              session.lastActivity,
+              session.cwd,
+              session.pid,
+              session.started,
+            ].join('\t'),
+          )
+      }
+    })
+}
+
+export async function localEvents(id: string) {
+  const directory = await privateSessionsDirectory()
+  await new Promise<void>((resolve, reject) => {
+    const socket = createConnection(socketPath(id, directory))
+    socket.on('error', reject)
+    socket.on('connect', () => socket.write('{"type":"subscribe"}\n'))
+    socket.on('data', (data) => {
+      if (!process.stdout.write(data)) socket.pause()
+    })
+    const drain = () => socket.resume()
+    process.stdout.on('drain', drain)
+    socket.on('close', () => {
+      process.stdout.off('drain', drain)
+      resolve()
+    })
+  })
+}

package/src/station/config.ts

@@ -0,0 +1,89 @@
+// station.json in mirab's config directory: where the station's harar is,
+// and which harar secret each model route adds. Explicit, so nothing comes
+// from the environment.
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { z } from 'zod'
+import { humanNameProblem } from '../agent/define'
+
+export const stationConfigSchema = z.strictObject({
+  harar: z.strictObject({
+    /** The harar primary's (or per-user agent's) socket. */
+    socket: z.string().startsWith('/', 'the harar socket is an absolute path'),
+  }),
+  models: z.strictObject({
+    anthropic: z
+      .strictObject({
+        /** The harar secret holding the API key, e.g. `personal/anthropic/API_KEY`. */
+        key: z.string().min(1),
+      })
+      .optional(),
+    claude: z
+      .strictObject({
+        /** The harar secret holding Claude Code's token (`claude setup-token`),
+         *  for Claude Code in a VM on the person's own subscription. */
+        token: z.string().min(1),
+      })
+      .optional(),
+  }),
+  /** Keys for any service: each harar secret a project's .env may name, and
+   *  the hosts it may go to. The VM gets placeholders; the station swaps them. */
+  /** Where a secret may go is harar's to say now: a station.json that still
+   *  lists secrets loads, the list is ignored, and the station says where
+   *  hosts went. */
+  secrets: z.unknown().optional(),
+  /** The person at this station, by harar name (`gg.addis.human.sami`): who
+   *  they are in the channels it hosts. */
+  human: z
+    .string()
+    .refine((name) => !humanNameProblem(name), {
+      message: 'human is a harar name like gg.addis.human.sami',
+    })
+    .optional(),
+})
+export type StationConfig = z.infer<typeof stationConfigSchema>
+
+export const STATION_EXAMPLE = JSON.stringify(
+  {
+    harar: { socket: '/var/run/harar.sock' },
+    models: {
+      anthropic: { key: 'personal/anthropic/API_KEY' },
+      claude: { token: 'personal/claude/OAUTH_TOKEN' },
+    },
+  },
+  null,
+  2,
+)
+
+/** station.json, or undefined when there is none and `optional` says that's fine. */
+export async function loadStationConfig(
+  configDir: string,
+): Promise<StationConfig>
+export async function loadStationConfig(
+  configDir: string,
+  options: { optional: true },
+): Promise<StationConfig | undefined>
+export async function loadStationConfig(
+  configDir: string,
+  options?: { optional: true },
+): Promise<StationConfig | undefined> {
+  const path = join(configDir, 'station.json')
+  const text = await readFile(path, 'utf8').catch(() => undefined)
+  if (text === undefined && options?.optional) return undefined
+  if (text === undefined)
+    throw new Error(
+      `${path} is missing: it says where harar is and which secret is the model key, like\n${STATION_EXAMPLE}`,
+    )
+  let data: unknown
+  try {
+    data = JSON.parse(text)
+  } catch {
+    throw new Error(`${path} isn't JSON`)
+  }
+  const parsed = stationConfigSchema.safeParse(data)
+  if (!parsed.success)
+    throw new Error(
+      `${path}: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`,
+    )
+  return parsed.data
+}

package/src/station/gateway.ts

@@ -0,0 +1,94 @@
+// mirab's side of rixse's gateway (`import { gateway } from 'rixse'`): one
+// gateway session per VM, mounted as the VM's only way out. The gateway
+// knows nothing about VMs; this maps the guest's egress port to it, puts its
+// certificate authority where the guest's programs trust it, and passes its
+// environment on. Shared by `mirab spawn --vm` and `mirab dev`.
+import { gateway, type GatewayConfig, type Route, type Upstream } from 'rixse'
+import type { Isolation } from '../isolation/session'
+import { EGRESS_GUEST_PORT, EGRESS_HOST_PORT } from '../isolation/vz'
+import type { StationConfig } from './config'
+import { hararVault } from './vault'
+import { shellQuote } from '../spawn-adapters/types'
+
+/** Where the gateway's authority lands in the guest. */
+export const GUEST_CA = '/usr/local/share/ca-certificates/mirab-station.crt'
+/** The bundle curl, git, Go and OpenSSL programs read. */
+const GUEST_BUNDLE = '/etc/ssl/certs/ca-certificates.crt'
+/** The gateway's address in the guest. */
+export const GUEST_PROXY = `http://127.0.0.1:${EGRESS_GUEST_PORT}`
+
+export interface VmStation {
+  /** What the guest's programs get: a placeholder per secret, and the gateway as their proxy. */
+  env: Record<string, string>
+  /** Things the person should know. */
+  notes: string[]
+  /** Serves the VM's way out, and makes the guest trust the gateway's authority. */
+  attach(iso: Isolation): Promise<void>
+  close(): Promise<void>
+}
+
+export async function vmStation(o: {
+  project: string
+  station: StationConfig
+  configDir: string
+  zone: string
+  auditLog: string
+  routes: Record<string, Route>
+  allow: string[]
+  /** Whose grants: `project:<real path>`. */
+  agent: string
+  /** Tests point the hosts the gateway opens at a local stand-in. */
+  upstream?: (host: string) => Promise<Upstream>
+  /** The agent's gateway section, as the person approved it. */
+  config?: GatewayConfig
+}): Promise<VmStation> {
+  const session = await gateway({
+    project: o.project,
+    vault: hararVault(o.station.harar.socket),
+    configDir: o.configDir,
+    zone: o.zone,
+    auditLog: o.auditLog,
+    routes: o.routes,
+    allow: o.allow,
+    agent: o.agent,
+    guest: { proxy: GUEST_PROXY, caPath: GUEST_CA },
+    upstream: o.upstream,
+    config: o.config,
+  })
+  // The gateway says what's missing; mirab says how to give it, here.
+  const notes = session.notes.map((note) => {
+    // The agent is the one mirab named; a project path can hold spaces.
+    const m = /names harar:\/\/(\S+), which /.exec(note)
+    return m && note.includes(`, which ${o.agent} hasn't been allowed`)
+      ? `${note}. Allow it: mirab secrets allow ${m[1]} --agent ${shellQuote(o.agent)}`
+      : note
+  })
+  if (o.station.secrets !== undefined)
+    notes.push(
+      "station.json's secrets are ignored now: harar says where each secret may go (harar hosts allow <secret> <host>, or a role's send at a primary)",
+    )
+  return {
+    env: session.env,
+    notes,
+    async attach(iso) {
+      await iso.onGuestConnect!(EGRESS_HOST_PORT, (socketPath) =>
+        session.listen(socketPath),
+      )
+      if (!session.caCert) return
+      await iso.put(GUEST_CA, session.caCert, 0o644)
+      const code = await iso.exec(
+        ['sh', '-c', `cat ${GUEST_CA} >> ${GUEST_BUNDLE}`],
+        {
+          cwd: '/',
+          env: { PATH: '/usr/bin:/bin' },
+          timeoutMs: 10_000,
+          signal: new AbortController().signal,
+          onLine: async () => {},
+        },
+      )
+      if (code !== 0)
+        throw new Error("the VM couldn't be told to trust the gateway")
+    },
+    close: () => session.close(),
+  }
+}