mirab 0.0.0 → 0.2.0

package/src/spawn-report.ts

@@ -0,0 +1,114 @@
+import { randomUUID } from 'node:crypto'
+import { GildClient } from './api/client'
+import type { AgentEvent } from './spawn-events'
+import { sessionState, type SessionInput } from './api/sessions-contract'
+export type ReportTarget = {
+  server: string
+  token: string
+  agent: string
+  owner: string
+  repo: string
+  sha: string
+}
+/** gild.gg answered a commit-session receipt in 2–4.5 s on 10 Oct; a 1 s
+ * abort dropped every report, so the channel never showed an agent's state.
+ * Only one request is in flight and the latest state wins, so a slow answer
+ * delays the next update rather than piling them up. */
+export const REPORT_TIMEOUT_MS = 10_000
+/** One in-flight update, latest state wins. No local content reaches the API. */
+export class StateReporter {
+  private readonly id = randomUUID()
+  private readonly started = new Date().toISOString()
+  private readonly client: GildClient
+  private pending?: NonNullable<SessionInput['state']>
+  private timer?: ReturnType<typeof setTimeout>
+  private sending?: Promise<void>
+  private lastSent = 0
+  private ended = false
+  constructor(
+    private readonly target: ReportTarget,
+    private readonly model: string,
+    fetcher?: ConstructorParameters<typeof GildClient>[2],
+  ) {
+    this.client = new GildClient(
+      target.server + '/api/v1',
+      target.token,
+      fetcher,
+    )
+  }
+  event(event: AgentEvent) {
+    if (this.ended || event.type === 'message') return
+    const parsedTool = sessionState.shape.tool.safeParse(event.tool)
+    const tool = parsedTool.success ? parsedTool.data : undefined
+    this.pending = {
+      status: event.type,
+      ...(tool ? { tool } : {}),
+      last_activity: event.ts,
+    }
+    this.schedule()
+  }
+  private schedule() {
+    if (this.sending || this.timer || !this.pending) return
+    this.timer = setTimeout(
+      () => {
+        this.timer = undefined
+        void this.send()
+      },
+      Math.max(0, 1000 - (Date.now() - this.lastSent)),
+    )
+  }
+  private async send(timeoutMs = REPORT_TIMEOUT_MS) {
+    if (this.sending || !this.pending) return
+    const state = this.pending
+    this.pending = undefined
+    this.lastSent = Date.now()
+    this.sending = this.client
+      .request(
+        'createCommitSession',
+        {
+          owner: this.target.owner,
+          repo: this.target.repo,
+          sha: this.target.sha,
+        },
+        {
+          id: this.id,
+          agent: this.target.agent,
+          started_at: this.started,
+          ended_at: state.status === 'ended' ? state.last_activity : null,
+          model: this.model,
+          state,
+          tokens_in: 0,
+          tokens_out: 0,
+          currency: 'USD',
+          commands: [],
+          files: { read: [], written: [] },
+          notes: '',
+        },
+        undefined,
+        { signal: AbortSignal.timeout(timeoutMs) },
+      )
+      .then(
+        () => {},
+        () => {},
+      )
+    await this.sending
+    this.lastSent = Date.now()
+    this.sending = undefined
+    this.schedule()
+  }
+  async close() {
+    this.ended = true
+    clearTimeout(this.timer)
+    this.timer = undefined
+    this.pending = { status: 'ended', last_activity: new Date().toISOString() }
+    await this.sending
+    clearTimeout(this.timer)
+    this.timer = undefined
+    // Honor the same rate limit for the final update.
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.max(0, 1000 - (Date.now() - this.lastSent))),
+    )
+    // Exit waits for this one, so it gets less time than a live update.
+    await this.send(5000)
+  }
+}

package/src/spawn-sessions.ts

@@ -0,0 +1,166 @@
+import type { SessionState } from './spawn-events'
+import type { NudgeStatus } from './spawn-nudge'
+import { chmod, lstat, mkdir, readdir, unlink } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { createConnection } from 'node:net'
+
+export type ChannelStatus = {
+  repo: string
+  state: 'connecting' | 'listening' | 'error'
+  error?: string
+}
+export type LocalSession = SessionState & {
+  id: string
+  agent: string
+  profile?: string
+  identity?: string
+  channels?: ChannelStatus[]
+  held?: { queued: number; reason: string }
+  nudges?: NudgeStatus[]
+  /** Detached sessions (`mirab spawn --detach`) only. */
+  detached?: true
+  viewers?: number
+  interactive?: boolean
+  cols?: number
+  rows?: number
+  log?: string
+  cwd: string
+  pid: number
+  childPid: number
+  started: string
+}
+export const MAX_MESSAGE_BYTES = 64 * 1024
+export const sessionsDirectory = () => join(homedir(), '.mirab', 'sessions')
+
+export function socketPath(id: string, directory = sessionsDirectory()) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,31}$/.test(id))
+    throw new Error(
+      'Session name must be 1–32 letters, digits, underscores or hyphens',
+    )
+  const path = join(directory, id + '.sock')
+  if (Buffer.byteLength(path) > 103)
+    throw new Error('Session socket path is too long for a Unix socket')
+  return path
+}
+export function requireUnix() {
+  if (process.platform === 'win32')
+    throw new Error('Local agent sessions are not supported on Windows in v1')
+}
+export async function privateSessionsDirectory() {
+  requireUnix()
+  const directory = sessionsDirectory()
+  for (const path of [join(homedir(), '.mirab'), directory]) {
+    await mkdir(path, { mode: 0o700 }).catch((error: NodeJS.ErrnoException) => {
+      if (error.code !== 'EEXIST') throw error
+    })
+    const info = await lstat(path)
+    if (
+      !info.isDirectory() ||
+      info.isSymbolicLink() ||
+      info.uid !== process.getuid!()
+    )
+      throw new Error(`Unsafe session directory: ${path}`)
+    await chmod(path, 0o700)
+  }
+  return directory
+}
+export interface SyncSummary {
+  written: number
+  deleted: number
+  rejected: number
+  conflicts: { path: string; reason: string; saved?: string }[]
+  /** What the agent changed about itself: held aside, never applied. */
+  held: { path: string; reason: string; saved?: string }[]
+}
+export function localRequest(
+  path: string,
+  request: { type: 'sync' },
+  timeoutMs?: number,
+): Promise<SyncSummary>
+export function localRequest(
+  path: string,
+  request: { type: 'info' } | { type: 'send'; message: string },
+  timeoutMs?: number,
+): Promise<LocalSession | { queued: true }>
+export function localRequest(
+  path: string,
+  request:
+    { type: 'info' } | { type: 'send'; message: string } | { type: 'sync' },
+  timeoutMs = 3000,
+): Promise<LocalSession | { queued: true } | SyncSummary> {
+  const data = JSON.stringify(request) + '\n'
+  if (Buffer.byteLength(data) > MAX_MESSAGE_BYTES)
+    return Promise.reject(new Error('Message exceeds 64 KiB'))
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(path)
+    let response = ''
+    const fail = (error: Error) => {
+      socket.destroy()
+      reject(error)
+    }
+    socket.setEncoding('utf8')
+    socket.setTimeout(timeoutMs, () =>
+      fail(new Error('Session did not respond')),
+    )
+    socket.on('error', fail)
+    socket.on('connect', () => socket.write(data))
+    socket.on('data', (chunk: string) => {
+      response += chunk
+      if (Buffer.byteLength(response) > MAX_MESSAGE_BYTES)
+        return fail(new Error('Invalid session response'))
+      if (!response.includes('\n')) return
+      try {
+        const result = JSON.parse(response.slice(0, response.indexOf('\n')))
+        socket.destroy()
+        if (result.error) reject(new Error(result.error))
+        else resolve(result)
+      } catch {
+        fail(new Error('Invalid session response'))
+      }
+    })
+    socket.on('end', () => fail(new Error('Session closed without a response')))
+  })
+}
+export async function liveSessions(): Promise<LocalSession[]> {
+  const directory = await privateSessionsDirectory()
+  const sessions: LocalSession[] = []
+  for (const entry of await readdir(directory)) {
+    if (!entry.endsWith('.sock')) continue
+    const path = join(directory, entry)
+    const socket = await lstat(path).catch(() => null)
+    if (!socket?.isSocket()) continue
+    try {
+      const result = await localRequest(path, { type: 'info' })
+      if ('id' in result) sessions.push(result)
+    } catch (error) {
+      if (!(await removeDeadSocket(path, error, socket))) throw error
+    }
+  }
+  return sessions.sort((a, b) => a.started.localeCompare(b.started))
+}
+
+/** Probe first; unlink only a refused socket whose inode still belongs to that probe. */
+export async function removeDeadSocket(
+  path: string,
+  error?: unknown,
+  socket?: Awaited<ReturnType<typeof lstat>>,
+) {
+  socket ??= await lstat(path).catch(() => undefined)
+  if (!socket?.isSocket()) return false
+  if (!error) {
+    try {
+      await localRequest(path, { type: 'info' })
+      return false
+    } catch (probeError) {
+      error = probeError
+    }
+  }
+  const code = (error as NodeJS.ErrnoException).code
+  if (code !== 'ECONNREFUSED' && code !== 'ENOENT') return false
+  const current = await lstat(path).catch(() => undefined)
+  if (!current) return true
+  if (current.ino !== socket.ino || current.dev !== socket.dev) return false
+  await unlink(path)
+  return true
+}

package/src/spawn-vm.ts

@@ -0,0 +1,356 @@
+// `mirab spawn --vm`: the agent process runs on a pty inside a microVM
+// (Firecracker on Linux, Virtualization.framework on macOS); the host keeps the terminal, session socket, hooks, injection queue
+// and everything else (spawn-worker.ts). This file only builds the guest
+// child and the hook relay.
+import { projectAgent } from 'rixse'
+import { createConnection } from 'node:net'
+import { mkdtemp, readFile, stat, writeFile } from 'node:fs/promises'
+import { basename, isAbsolute, join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { requireVm, startVm, type Isolation, type VmConfig } from './isolation'
+import { privateSessionsDirectory, socketPath } from './spawn-sessions'
+import type { StationConfig } from './station/config'
+import type { Upstream } from 'rixse'
+import { GUEST_PROXY, vmStation, type VmStation } from './station/gateway'
+import { claudeRoute, withClaudeRoute } from 'rixse'
+import { hararVault } from './station/vault'
+import {
+  describeSync,
+  hostManifest,
+  syncBack,
+  type SyncResult,
+  type RecoveryLocation,
+} from './isolation/sync'
+
+export const GUEST_AGENT = '/usr/local/bin/mirab-guest-agent'
+const GUEST_PATH =
+  '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'
+const MAX_UPLOAD = 1 << 20
+
+export interface VmChild {
+  pid: number
+  write(data: string | Uint8Array): void
+  resize(cols: number, rows: number): void
+  onData(cb: (data: Buffer) => void): void
+  onExit(cb: (e: { exitCode: number; signal?: number }) => void): void
+  pause(): void
+  resume(): void
+  /** Hang up the guest session (the agent gets SIGHUP). */
+  kill(): void
+  /** Copy the guest's changes to the working directory back to the host now. */
+  sync(): Promise<SyncResult>
+  /** Sync once, then stop; incomplete sync retains the workspace for recovery. */
+  dispose(): Promise<SyncResult | undefined>
+  /** Available even when final sync throws; contains only private local paths. */
+  readonly recovery?: RecoveryLocation
+}
+
+export class VmSyncError extends Error {
+  constructor(
+    message: string,
+    readonly recovery: RecoveryLocation,
+    cause: unknown,
+  ) {
+    super(message, { cause })
+  }
+}
+
+/** Shut down the VM without deleting work that could not safely reach the host. */
+export async function finishVmSync(
+  sync: () => Promise<SyncResult>,
+  isolation: Pick<Isolation, 'close'>,
+  vmDir: string,
+  log: (line: string) => void = (line) => console.error(`mirab: ${line}`),
+) {
+  let result: SyncResult | undefined, failure: unknown
+  try {
+    result = await sync()
+  } catch (e) {
+    failure = e
+  }
+  const preserve =
+    failure !== undefined ||
+    !result ||
+    result.conflicts.length > 0 ||
+    result.rejected.length > 0
+  const recovery: RecoveryLocation = {
+    directory: vmDir,
+    note: join(vmDir, 'recovery.json'),
+  }
+  try {
+    await isolation.close({ preserveWorkspace: preserve })
+  } catch (e) {
+    log(`VM shutdown failed; recovery workspace: ${vmDir}`)
+    throw new VmSyncError(
+      `VM shutdown failed: ${(e as Error).message}`,
+      recovery,
+      e,
+    )
+  }
+  if (preserve) {
+    log(`VM workspace retained for recovery: ${vmDir}`)
+    // No tokens or process environment are persisted in this host-owned note.
+    try {
+      await writeFile(
+        join(vmDir, 'recovery.json'),
+        JSON.stringify(
+          {
+            state: 'sync-incomplete',
+            createdAt: new Date().toISOString(),
+            error:
+              failure instanceof Error
+                ? failure.message
+                : failure
+                  ? String(failure)
+                  : undefined,
+            result,
+          },
+          null,
+          2,
+        ) + '\n',
+        { mode: 0o600 },
+      )
+    } catch (e) {
+      throw new VmSyncError(
+        `Writing recovery note failed: ${(e as Error).message}`,
+        recovery,
+        e,
+      )
+    }
+    if (result) result = { ...result, recovery }
+  }
+  if (failure !== undefined)
+    throw new VmSyncError(
+      failure instanceof Error ? failure.message : String(failure),
+      recovery,
+      failure,
+    )
+  return result!
+}
+
+/**
+ * Git in the guest trusts the work directory. Its files keep the host user's
+ * uid (mke2fs -d copies ownership) while the agent runs as root, so without
+ * this every git command in /workspace stops at "detected dubious ownership".
+ * Set through git's environment config, so it needs no change to the image.
+ */
+export const guestGitEnvironment = (work = '/workspace') => ({
+  GIT_CONFIG_COUNT: '1',
+  GIT_CONFIG_KEY_0: 'safe.directory',
+  GIT_CONFIG_VALUE_0: work,
+})
+
+/** Env for the guest: a fixed baseline plus only what the adapter or profile added; never the host env. */
+export function guestEnvironment(
+  hostEnv: Record<string, string | undefined>,
+  baseline: Record<string, string | undefined>,
+  allowlist?: string[],
+) {
+  const out: Record<string, string> = {
+    PATH: GUEST_PATH,
+    HOME: '/root',
+    TERM: 'xterm-256color',
+    LANG: 'C.UTF-8',
+    ...guestGitEnvironment(),
+  }
+  for (const [k, v] of Object.entries(hostEnv)) {
+    if (v === undefined || k in out) continue
+    const addedByAdapter = baseline[k] !== v
+    if (addedByAdapter || allowlist?.includes(k)) out[k] = v
+  }
+  return out
+}
+
+/** Moved to isolation (the runner side needs it without the agent session code). */
+export { requireVm }
+
+export async function startVmChild(opts: {
+  configDir: string
+  sessionId: string
+  cwd: string
+  binary: string
+  args: string[]
+  env: Record<string, string>
+  cols: number
+  rows: number
+  log?: (line: string) => void
+  /** The station, for Claude Code on the person's own subscription. */
+  station?: {
+    config: StationConfig
+    /** Where its decisions go (JSON lines). */
+    auditLog: string
+    /** Where the claude route goes; tests point it at a stand-in. */
+    upstream?: string
+    /** Where the hosts the station opens are; tests point them at a stand-in. */
+    opened?: (host: string) => Promise<Upstream>
+  }
+}): Promise<VmChild> {
+  const vm = await requireVm(opts.configDir, opts.log)
+  const kb = Number(
+    execFileSync('du', ['-sk', opts.cwd], { encoding: 'utf8' }).split(/\s+/)[0],
+  )
+  if (kb > 2 * 1024 * 1024)
+    throw new Error(
+      `${opts.cwd} is larger than 2 GiB; --vm copies the working directory into the VM`,
+    )
+  // What the guest starts from: the baseline every later sync is compared to.
+  const baseline = await hostManifest(opts.cwd)
+  const vmDir = await mkdtemp(
+    join(await privateSessionsDirectory(), `${opts.sessionId}.vm-`),
+  )
+  const iso: Isolation = await startVm(vm, opts.cwd, vmDir, opts.log)
+  const fail = async (e: unknown) => {
+    await iso.close()
+    throw e
+  }
+  try {
+    // Hooks run inside the guest and arrive here over vsock; only this session's id is accepted.
+    iso.onGuestMessage!(9100, (m) => {
+      if (
+        m?.op !== 'hook' ||
+        m.session !== opts.sessionId ||
+        typeof m.raw !== 'string'
+      )
+        return
+      let raw: unknown
+      try {
+        raw = JSON.parse(m.raw)
+      } catch {
+        return
+      }
+      const s = createConnection(socketPath(opts.sessionId))
+      s.on('error', () => {})
+      s.on('connect', () =>
+        s.end(
+          JSON.stringify({
+            type: 'hook',
+            agent: String(m.agent ?? 'claude'),
+            raw,
+          }) + '\n',
+        ),
+      )
+    })
+    // Small files the host prepared (hook settings, a script agent) are copied into the guest tmpfs.
+    let n = 0
+    const upload = async (path: string, executable: boolean) => {
+      if (!isAbsolute(path)) return undefined
+      const st = await stat(path).catch(() => null)
+      if (!st?.isFile() || st.size > MAX_UPLOAD) return undefined
+      const target = `/tmp/mirab/${n++}-${basename(path)}`
+      await iso.put(
+        target,
+        await readFile(path, 'utf8'),
+        executable ? 0o700 : 0o600,
+      )
+      return target
+    }
+    const head = await readFile(opts.binary, {
+      encoding: 'latin1',
+      flag: 'r',
+    }).then(
+      (t) => t.slice(0, 2),
+      () => '',
+    )
+    const program =
+      (head === '#!' && (await upload(opts.binary, true))) ||
+      basename(opts.binary)
+    const args: string[] = []
+    for (const a of opts.args) args.push((await upload(a, false)) ?? a)
+    // The station is the VM's way out: Claude Code on the person's own
+    // subscription (the VM holds a placeholder, the station adds the token from
+    // harar), and the keys the project's .env names, as placeholders the
+    // station swaps on their own hosts. Any program named claude gets the
+    // route; whatever it is, it can reach only api.anthropic.com/v1/messages.
+    let env = opts.env
+    let station: VmStation | undefined
+    const isClaude = basename(opts.binary) === 'claude'
+    if (opts.station) {
+      const claude = isClaude
+        ? claudeRoute(
+            hararVault(opts.station.config.harar.socket),
+            opts.station.config.models.claude?.token,
+            opts.station.upstream,
+          )
+        : undefined
+      station = await vmStation({
+        project: opts.cwd,
+        station: opts.station.config,
+        configDir: opts.configDir,
+        // No harar identity for spawn sessions yet (#2): named by session.
+        zone: `vm-${opts.sessionId}`,
+        auditLog: opts.station.auditLog,
+        routes: claude ? { claude } : {},
+        allow: [],
+        agent: projectAgent(opts.cwd),
+        upstream: opts.station.opened,
+      })
+      for (const note of station.notes) opts.log?.(note)
+      await station.attach(iso)
+      env = { ...env, ...station.env }
+      if (claude) env = withClaudeRoute(env, GUEST_PROXY)
+    }
+    if (isClaude && !opts.station?.config.models.claude)
+      opts.log?.(
+        'Claude Code in the VM has no login: add models.claude.token to station.json (the harar secret from `claude setup-token`)',
+      )
+    const pty = await iso.pty!({
+      argv: [program, ...args],
+      env,
+      cwd: '/workspace',
+      cols: opts.cols,
+      rows: opts.rows,
+    })
+    const conflictDir = join(
+      await privateSessionsDirectory(),
+      `${opts.sessionId}.conflicts`,
+    )
+    // One sync at a time; each one carries only what changed since the last.
+    let chain: Promise<unknown> = Promise.resolve()
+    const sync = () => {
+      const next = chain.then(async () => {
+        const r = await syncBack({
+          root: opts.cwd,
+          guestRoot: '/workspace',
+          files: iso.files!,
+          baseline,
+          conflictDir,
+        })
+        opts.log?.(`synced ${describeSync(r)}`)
+        return r
+      })
+      chain = next.catch(() => {})
+      return next
+    }
+    let disposed: Promise<SyncResult | undefined> | undefined
+    let recovery: RecoveryLocation | undefined
+    const dispose = async () => {
+      await station?.close()
+      try {
+        const result = await finishVmSync(sync, iso, vmDir, opts.log)
+        recovery = result.recovery
+        return result
+      } catch (e) {
+        if (e instanceof VmSyncError) recovery = e.recovery
+        throw e
+      }
+    }
+    return {
+      pid: -1,
+      write: (d) => pty.write(d),
+      resize: (c, r) => pty.resize(c, r),
+      onData: (cb) => pty.onData(cb),
+      // guestPty replays an exit that happened before this listener.
+      onExit: (cb) => pty.onExit((code) => cb({ exitCode: code })),
+      pause() {},
+      resume() {},
+      kill: () => pty.close(),
+      sync,
+      dispose: () => (disposed ??= dispose()),
+      get recovery() {
+        return recovery
+      },
+    }
+  } catch (e) {
+    return fail(e)
+  }
+}