mirab 0.0.0-stage → 0.2.0

package/src/spawn-attach.ts

@@ -0,0 +1,243 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process'
+import { createConnection } from 'node:net'
+import { Command, InvalidArgumentError } from 'commander'
+import { readFile } from 'node:fs/promises'
+import { endedLogPath, type StartMessage } from './spawn-detach'
+import { privateSessionsDirectory, socketPath } from './spawn-sessions'
+
+/** Caller side of detached sessions: `mirab spawn --detach`, `mirab attach`,
+ * `mirab stop`. The worker side is spawn-detach.ts. */
+export const DETACH_KEY = 0x1d // Ctrl-], as in telnet
+const CTRL_C = 0x03
+
+export function dimension(value: string) {
+  const number = Number(value)
+  if (!Number.isInteger(number) || number < 1 || number > 1000)
+    throw new InvalidArgumentError('must be an integer from 1 to 1000')
+  return number
+}
+
+/** The worker runs in its own session (setsid) with none of the caller's
+ * stdio, so a caller without a terminal (an agent's Bash tool) gets EOF as
+ * soon as `mirab spawn --detach` exits; only the IPC channel is shared. */
+export function detachedSpawn(cwd: string): SpawnOptions {
+  return { cwd, detached: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'] }
+}
+/** Resolves with the session id once the socket listens and the agent has
+ * started, then lets go of the worker. */
+export async function detachedReady(worker: ChildProcess): Promise<string> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    const result = await new Promise<StartMessage>((resolve, reject) => {
+      timer = setTimeout(() => {
+        worker.kill('SIGTERM')
+        reject(new Error('The detached session did not start within 30 s'))
+      }, 30000)
+      worker.on('message', (message: StartMessage) => {
+        if (message?.type === 'ready' || message?.type === 'failed')
+          resolve(message)
+      })
+      worker.once('error', reject)
+      worker.once('exit', (code) =>
+        reject(
+          new Error(`The detached session exited while starting (${code})`),
+        ),
+      )
+    })
+    if (result.type === 'failed') throw new Error(result.error)
+    return result.id
+  } finally {
+    clearTimeout(timer)
+    worker.removeAllListeners()
+    if (worker.connected) worker.disconnect()
+    worker.unref()
+  }
+}
+
+function connect(id: string, directory: string) {
+  const socket = createConnection(socketPath(id, directory))
+  return socket
+}
+function sessionError(id: string, error: NodeJS.ErrnoException) {
+  return error.code === 'ENOENT' || error.code === 'ECONNREFUSED'
+    ? new Error(`No live session ${id}`)
+    : error
+}
+
+/** Replays the session's recent output, then streams it live. Interactive
+ * viewers type into the agent through the session's injection queue. */
+export async function attachSession(id: string, watch: boolean) {
+  const directory = await privateSessionsDirectory()
+  const terminal = !!process.stdin.isTTY && !!process.stdout.isTTY
+  if (!watch && !terminal)
+    throw new Error(
+      'mirab attach needs a terminal; use mirab attach --watch to stream output read-only',
+    )
+  const size = () => ({
+    cols: process.stdout.columns || 80,
+    rows: process.stdout.rows || 24,
+  })
+  const socket = connect(id, directory)
+  const frame = (value: object) => {
+    if (socket.writable) socket.write(JSON.stringify(value) + '\n')
+  }
+  const wasRaw = process.stdin.isRaw ?? false
+  let raw = false
+  let byKey = false
+  const keys = watch ? [DETACH_KEY, CTRL_C] : [DETACH_KEY]
+  const input = (data: Buffer) => {
+    let at = -1
+    for (const key of keys) {
+      const index = data.indexOf(key)
+      if (index >= 0 && (at < 0 || index < at)) at = index
+    }
+    const typed = at < 0 ? data : data.subarray(0, at)
+    if (!watch && typed.length)
+      frame({ t: 'i', d: Buffer.from(typed).toString('base64') })
+    if (at >= 0) {
+      byKey = true
+      socket.end()
+    }
+  }
+  const resized = () => frame({ t: 'r', ...size() })
+  const drain = () => socket.resume()
+  const cleanup = () => {
+    process.stdin.off('data', input)
+    process.off('SIGWINCH', resized)
+    process.stdout.off('drain', drain)
+    if (raw) process.stdin.setRawMode(wasRaw)
+    process.stdin.pause()
+  }
+  await new Promise<void>((resolve, reject) => {
+    let header: Buffer | undefined = Buffer.alloc(0)
+    socket.on('connect', () =>
+      socket.write(
+        JSON.stringify({
+          type: 'attach',
+          mode: watch ? 'watch' : 'interactive',
+          ...(watch ? {} : size()),
+        }) + '\n',
+      ),
+    )
+    socket.on('error', (error) => {
+      cleanup()
+      const failure = sessionError(id, error)
+      if (failure === error) return reject(failure)
+      // An ended session: show the output it left behind.
+      const path = endedLogPath(directory, id)
+      readFile(path).then(
+        (log) => {
+          process.stdout.write(log)
+          process.stderr.write(
+            `\r\n[${id} has ended; its output is kept in ${path}]\r\n`,
+          )
+          resolve()
+        },
+        () => reject(failure),
+      )
+    })
+    const show = (data: Buffer) => {
+      if (data.length && !process.stdout.write(data)) socket.pause()
+    }
+    socket.on('data', (data: Buffer) => {
+      if (!header) return show(data)
+      header = Buffer.concat([header, data])
+      const end = header.indexOf(10)
+      if (end < 0) return
+      const reply = JSON.parse(header.subarray(0, end).toString())
+      const rest = header.subarray(end + 1)
+      header = undefined
+      if (reply.error) {
+        socket.destroy()
+        cleanup()
+        return reject(new Error(reply.error))
+      }
+      if (terminal) {
+        process.stdin.setRawMode(true)
+        raw = true
+      }
+      if (terminal || !watch) {
+        process.stdin.on('data', input)
+        process.stdin.resume()
+      }
+      if (!watch) process.on('SIGWINCH', resized)
+      process.stdout.on('drain', drain)
+      show(rest)
+    })
+    socket.on('close', () => {
+      cleanup()
+      if (byKey && terminal)
+        process.stderr.write(
+          `\r\n[detached from ${id}; it is still running]\r\n`,
+        )
+      resolve()
+    })
+  })
+}
+
+/** Takes a session offline and prints its final `exited` event. */
+export async function stopSession(id: string, graceMs: number) {
+  const directory = await privateSessionsDirectory()
+  const socket = connect(id, directory)
+  const text = await new Promise<string>((resolve, reject) => {
+    let data = ''
+    const timer = setTimeout(() => {
+      socket.destroy()
+      reject(new Error(`Session ${id} did not stop`))
+    }, graceMs + 10000)
+    socket.setEncoding('utf8')
+    socket.on('connect', () =>
+      socket.write(JSON.stringify({ type: 'stop', graceMs }) + '\n'),
+    )
+    socket.on('data', (chunk: string) => (data += chunk))
+    socket.on('error', (error) => {
+      clearTimeout(timer)
+      reject(sessionError(id, error))
+    })
+    socket.on('close', () => {
+      clearTimeout(timer)
+      resolve(data)
+    })
+  })
+  for (const line of text.split('\n')) {
+    if (!line) continue
+    const event = JSON.parse(line)
+    if (event.error) throw new Error(event.error)
+    if (event.type === 'exited') return line
+  }
+  throw new Error(`Session ${id} closed without reporting its exit`)
+}
+
+export function detachCommands(program: Command) {
+  program
+    .command('attach <id>')
+    .description('watch and type into a detached agent session')
+    .option('--watch', 'stream output read-only (several may watch at once)')
+    .addHelpText(
+      'after',
+      '\nPress Ctrl-] to detach; the agent keeps running (mirab stop <id> ends it).\n' +
+        'Ctrl-C goes to the agent. With --watch, Ctrl-C also detaches.',
+    )
+    .action((id: string, opts: { watch?: boolean }) =>
+      attachSession(id, !!opts.watch),
+    )
+  program
+    .command('stop <id>')
+    .description(
+      'hang up a local agent session, SIGKILL it after the grace period, print its exit',
+    )
+    .option(
+      '--grace-ms <ms>',
+      'how long the agent has to exit after the hangup',
+      (value: string) => {
+        const number = Number(value)
+        if (!Number.isSafeInteger(number) || number < 0 || number > 60000)
+          throw new InvalidArgumentError('must be an integer from 0 to 60000')
+        return number
+      },
+      3000,
+    )
+    .action(async (id: string, opts: { graceMs: number }) => {
+      console.log(await stopSession(id, opts.graceMs))
+    })
+}

package/src/spawn-binary.ts

@@ -0,0 +1,90 @@
+import { agentEnvironment as baseEnvironment } from './spawn-native'
+import {
+  accessSync,
+  constants,
+  openSync,
+  readSync,
+  closeSync,
+  realpathSync,
+} from 'node:fs'
+import { basename, delimiter, resolve } from 'node:path'
+/** Resolve PATH without executing shims; aliases are expanded by the caller's shell. */
+export function realAgent(
+  agent: string,
+  cwd = process.cwd(),
+  platform = process.platform,
+): string {
+  // Native Windows spawning owns executable-suffix lookup.
+  if (platform === 'win32') return agent
+  let visited: string[] = []
+  try {
+    const chain = JSON.parse(process.env.MIRAB_SPAWN_CHAIN ?? '[]')
+    if (Array.isArray(chain))
+      visited = chain.filter((p): p is string => typeof p === 'string')
+  } catch {}
+  const candidates = agent.includes('/')
+    ? [resolve(cwd, agent)]
+    : (process.env.PATH ?? '')
+        .split(delimiter)
+        .map((dir) => resolve(cwd, dir || '.', agent))
+  for (const candidate of candidates) {
+    try {
+      accessSync(candidate, constants.X_OK)
+      const real = realpathSync(candidate)
+      if (visited.includes(real)) continue
+      if (
+        real === realpathSync(process.execPath) &&
+        basename(agent) === 'mirab'
+      )
+        continue
+      // Shell/script wrappers that re-enter mirab cannot be the native agent.
+      const fd = openSync(candidate, 'r')
+      const buffer = Buffer.alloc(8192)
+      let prefix: string
+      try {
+        prefix = buffer
+          .subarray(0, readSync(fd, buffer, 0, buffer.length, 0))
+          .toString()
+      } finally {
+        closeSync(fd)
+      }
+      if (prefix.startsWith('#!') && /\bmirab\s+spawn\b/.test(prefix)) continue
+      if (basename(real) === 'mirab' || basename(real) === 'mirab.js') continue
+      return candidate
+    } catch {}
+  }
+  throw new Error(
+    `No native ${agent} executable found on PATH (mirab spawn wrappers are skipped)`,
+  )
+}
+export function agentEnvironment(binary?: string, allowlist?: string[]) {
+  const env = baseEnvironment()
+  const baseline = ['PATH', 'HOME', 'TERM', 'LANG', 'USER', 'SHELL', 'TMPDIR']
+  for (const name of Object.keys(env)) {
+    if (allowlist && !allowlist.includes(name) && !baseline.includes(name))
+      delete env[name]
+  }
+
+  let chain: string[] = []
+  try {
+    const previous = JSON.parse(process.env.MIRAB_SPAWN_CHAIN ?? '[]')
+    if (Array.isArray(previous))
+      chain = previous.filter((p): p is string => typeof p === 'string')
+  } catch {}
+  if (binary && process.platform !== 'win32') {
+    const fd = openSync(binary, 'r'),
+      prefix = Buffer.alloc(2)
+    let script = false
+    try {
+      script = readSync(fd, prefix, 0, 2, 0) === 2 && prefix.toString() === '#!'
+    } finally {
+      closeSync(fd)
+    }
+    // Native executables cannot re-enter mirab as shell shims. Do not carry their
+    // paths into an agent's own later spawn command.
+    if (script) chain.push(realpathSync(binary))
+    else chain = []
+  }
+  env.MIRAB_SPAWN_CHAIN = JSON.stringify(chain)
+  return env
+}