mirab 0.0.0-stage → 0.2.0

package/src/spawn-detach.ts

@@ -0,0 +1,301 @@
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fchmodSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeSync,
+} from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import type { Socket } from 'node:net'
+import type { RecoveryLocation } from './isolation/sync'
+
+/** Worker side of `mirab spawn --detach`: output kept while nobody watches,
+ * and the viewers of `mirab attach`. The terminal-facing client is spawn-attach.ts. */
+export const DEFAULT_COLS = 120
+export const DEFAULT_ROWS = 40
+export const RING_BYTES = 256 * 1024
+export const LOG_BYTES = 8 * 1024 * 1024
+const MAX_VIEWER_BACKLOG = 1024 * 1024
+/** Ended sessions whose output is kept (newest first); each is at most LOG_BYTES. */
+export const KEPT_LOGS = 10
+const ENDED_LOG = '.output.log'
+
+/** Where an ended session's output stays: `<sessions>/<id>.output.log` (0600). */
+export const endedLogPath = (sessions: string, id: string) =>
+  join(sessions, id + ENDED_LOG)
+
+/** Keep only the newest `keep` ended-session logs in `sessions`. */
+export function pruneEndedLogs(sessions: string, keep = KEPT_LOGS) {
+  const logs = readdirSync(sessions)
+    .filter((name) => name.endsWith(ENDED_LOG))
+    .map((name) => {
+      const path = join(sessions, name)
+      try {
+        return { path, mtime: statSync(path).mtimeMs }
+      } catch {
+        return undefined
+      }
+    })
+    .filter((log) => log !== undefined)
+    .sort((a, b) => b.mtime - a.mtime)
+  for (const { path } of logs.slice(keep)) rmSync(path, { force: true })
+}
+
+/** The most recent PTY output, bounded; replayed to whoever attaches. */
+export class OutputRing {
+  private chunks: Buffer[] = []
+  private size = 0
+  constructor(private readonly limit = RING_BYTES) {}
+  push(data: Buffer) {
+    this.chunks.push(data)
+    this.size += data.length
+    while (this.size > this.limit) {
+      const over = this.size - this.limit
+      const first = this.chunks[0]
+      if (first.length <= over) {
+        this.chunks.shift()
+        this.size -= first.length
+      } else {
+        this.chunks[0] = first.subarray(over)
+        this.size -= over
+      }
+    }
+  }
+  snapshot() {
+    return Buffer.concat(this.chunks)
+  }
+}
+
+/** Append-only 0600 log; at the cap the file becomes `.1` (replacing the
+ * previous one) and a new file starts, so disk use stays bounded. */
+export class OutputLog {
+  private fd: number | undefined
+  private size = 0
+  constructor(
+    readonly path: string,
+    private readonly cap = LOG_BYTES,
+  ) {
+    this.open()
+  }
+  private open() {
+    this.fd = openSync(this.path, 'a', 0o600)
+    fchmodSync(this.fd, 0o600)
+    this.size = 0
+  }
+  write(data: Buffer) {
+    if (this.fd === undefined) return
+    try {
+      if (data.length > this.cap) data = data.subarray(data.length - this.cap)
+      if (this.size + data.length > this.cap) {
+        closeSync(this.fd)
+        renameSync(this.path, this.path + '.1')
+        this.open()
+      }
+      for (let at = 0; at < data.length;)
+        at += writeSync(this.fd!, data, at, data.length - at)
+      this.size += data.length
+    } catch {
+      // A full disk must not take the agent down with it.
+      this.close()
+    }
+  }
+  close() {
+    if (this.fd === undefined) return
+    try {
+      closeSync(this.fd)
+    } catch {}
+    this.fd = undefined
+  }
+}
+
+type Viewer = { interactive: boolean; pending: string }
+export type DetachedOptions = {
+  cols: number
+  rows: number
+  ringBytes?: number
+  logBytes?: number
+  resize: (cols: number, rows: number) => void
+  input: (data: Buffer) => void
+}
+const dimension = (value: unknown, fallback: number) =>
+  Number.isInteger(value) && (value as number) >= 1 && (value as number) <= 1000
+    ? (value as number)
+    : fallback
+
+export class DetachedHost {
+  private readonly ring: OutputRing
+  private readonly viewers = new Map<Socket, Viewer>()
+  private log: OutputLog | undefined
+  private directory: string | undefined
+  constructor(private readonly options: DetachedOptions) {
+    this.ring = new OutputRing(options.ringBytes)
+  }
+  /** Created after the agent adapter, which owns `mkdir` of this directory. */
+  openLog(directory: string) {
+    this.directory = directory
+    mkdirSync(directory, { recursive: true, mode: 0o700 })
+    chmodSync(directory, 0o700)
+    this.log = new OutputLog(
+      join(directory, 'output.log'),
+      this.options.logBytes,
+    )
+  }
+  get info() {
+    return {
+      detached: true as const,
+      viewers: this.viewers.size,
+      interactive: [...this.viewers.values()].some((v) => v.interactive),
+      cols: this.options.cols,
+      rows: this.options.rows,
+      ...(this.log ? { log: this.log.path } : {}),
+    }
+  }
+  push(data: Buffer) {
+    this.ring.push(data)
+    this.log?.write(data)
+    for (const socket of this.viewers.keys()) {
+      if (socket.writableLength + data.length > MAX_VIEWER_BACKLOG)
+        socket.destroy()
+      else socket.write(data)
+    }
+  }
+  has(socket: Socket) {
+    return this.viewers.has(socket)
+  }
+  /** Replay and registration happen in one tick, so no byte is lost or doubled. */
+  attach(socket: Socket, request: Record<string, unknown>) {
+    const interactive = request.mode !== 'watch'
+    if (request.mode !== 'watch' && request.mode !== 'interactive')
+      throw new Error('Invalid attach mode')
+    if (interactive && this.info.interactive)
+      throw new Error(
+        'Another viewer is attached interactively; use mirab attach --watch',
+      )
+    socket.setTimeout(0)
+    socket.write(
+      JSON.stringify({
+        attached: true,
+        mode: request.mode,
+        cols: this.options.cols,
+        rows: this.options.rows,
+      }) + '\n',
+    )
+    socket.write(this.ring.snapshot())
+    this.viewers.set(socket, { interactive, pending: '' })
+    socket.once('close', () => this.drop(socket))
+    if (interactive)
+      this.options.resize(
+        dimension(request.cols, this.options.cols),
+        dimension(request.rows, this.options.rows),
+      )
+  }
+  /** Viewer frames are JSON lines: {t:'i',d:<base64 keystrokes>} or {t:'r',cols,rows}. */
+  feed(socket: Socket, chunk: string) {
+    const viewer = this.viewers.get(socket)
+    if (!viewer) return
+    viewer.pending += chunk
+    if (viewer.pending.length > MAX_VIEWER_BACKLOG) return socket.destroy()
+    for (let end; (end = viewer.pending.indexOf('\n')) >= 0;) {
+      const line = viewer.pending.slice(0, end)
+      viewer.pending = viewer.pending.slice(end + 1)
+      let frame: { t?: string; d?: string; cols?: number; rows?: number }
+      try {
+        frame = JSON.parse(line)
+      } catch {
+        return socket.destroy()
+      }
+      if (!viewer.interactive) continue
+      if (frame.t === 'i' && typeof frame.d === 'string')
+        this.options.input(Buffer.from(frame.d, 'base64'))
+      else if (frame.t === 'r')
+        this.options.resize(
+          dimension(frame.cols, this.options.cols),
+          dimension(frame.rows, this.options.rows),
+        )
+    }
+  }
+  private drop(socket: Socket) {
+    const viewer = this.viewers.get(socket)
+    if (!viewer) return
+    this.viewers.delete(socket)
+    // Detaching returns the agent to the fixed size nobody is watching at.
+    if (viewer.interactive)
+      this.options.resize(this.options.cols, this.options.rows)
+  }
+  /** Hands the viewers over to be ended in order (see endSocket), not reset. */
+  endViewers(): Socket[] {
+    const sockets = [...this.viewers.keys()]
+    this.viewers.clear()
+    return sockets
+  }
+  /** Removes the session's private files but keeps its latest output as
+   * `<sessions>/<id>.output.log`, so it can be read after the session ended
+   * (`mirab attach --watch <id>`); only the newest KEPT_LOGS are kept. */
+  cleanup() {
+    this.log?.close()
+    if (!this.directory) return
+    const log = this.log?.path
+    // A session that never printed (one that failed to start) leaves nothing.
+    if (log && existsSync(log) && statSync(log).size > 0) {
+      const sessions = dirname(this.directory)
+      try {
+        renameSync(log, endedLogPath(sessions, basename(this.directory)))
+        pruneEndedLogs(sessions)
+      } catch {}
+    }
+    rmSync(this.directory, { recursive: true, force: true })
+  }
+}
+
+/** The last line on the events stream of a session that has ended. */
+export function exitLine(
+  session: string,
+  code: number,
+  recovery?: RecoveryLocation,
+) {
+  return (
+    JSON.stringify({
+      session,
+      type: 'exited',
+      code,
+      ...(recovery ? { recovery } : {}),
+      ts: new Date().toISOString(),
+    }) + '\n'
+  )
+}
+/** Ends a socket and resolves once its last bytes are written (or it died). */
+export function endSocket(socket: Socket, last?: string) {
+  return new Promise<void>((resolve) => {
+    if (socket.destroyed || socket.writableFinished) return resolve()
+    socket.once('finish', () => resolve())
+    socket.once('close', () => resolve())
+    socket.once('error', () => resolve())
+    if (!socket.writableEnded) {
+      if (last) socket.end(last)
+      else socket.end()
+    }
+  })
+}
+export type StartMessage =
+  { type: 'ready'; id: string } | { type: 'failed'; error: string }
+/** The worker tells `mirab spawn --detach` over IPC that it is ready, or why not. */
+export function reportDetached(
+  detach: unknown,
+  message: StartMessage,
+): Promise<void> {
+  if (!detach || !process.send || !process.connected) return Promise.resolve()
+  // Resolves once the message is handed to the IPC channel, so exiting right after cannot drop it.
+  return new Promise((resolve) => {
+    try {
+      process.send!(message, undefined, undefined, () => resolve())
+    } catch {
+      resolve()
+    }
+  })
+}

package/src/spawn-events.ts

@@ -0,0 +1,35 @@
+/** The sole local event envelope. Raw payloads never leave the local socket. */
+export type AgentEvent = {
+  session: string
+  agent: string
+  type: 'busy' | 'idle' | 'tool_start' | 'tool_end' | 'waiting' | 'message'
+  tool?: string
+  text?: string
+  ts: string
+  raw: unknown
+}
+export type AgentState =
+  'unknown' | Exclude<AgentEvent['type'], 'message' | 'tool_end'>
+export type SessionState = {
+  state: AgentState
+  tool?: string
+  lastActivity: string
+  agentSessionId?: string
+  transcriptPath?: string
+}
+export function applyEvent(state: SessionState, event: AgentEvent): void {
+  state.lastActivity = event.ts
+  if (event.type !== 'message') {
+    state.state = event.type === 'tool_end' ? 'busy' : event.type
+    state.tool = event.type === 'tool_start' ? event.tool : undefined
+  }
+  const raw = event.raw as Record<string, unknown> | null
+  if (raw && typeof raw === 'object') {
+    if (typeof raw.session_id === 'string')
+      state.agentSessionId = raw.session_id
+    if (typeof raw.transcript_path === 'string')
+      state.transcriptPath = raw.transcript_path
+    if (typeof raw['thread-id'] === 'string')
+      state.agentSessionId = raw['thread-id']
+  }
+}

package/src/spawn-hook.ts

@@ -0,0 +1,86 @@
+import { spawn } from 'node:child_process'
+import { createConnection } from 'node:net'
+import type { Readable } from 'node:stream'
+import { socketPath, MAX_MESSAGE_BYTES } from './spawn-sessions'
+/** Deliberately independent of Commander, identity loading, API clients and PTYs. */
+export async function forwardHook(
+  args: string[],
+  input: Readable = process.stdin,
+  schedule: (
+    done: () => void,
+    ms: number,
+  ) => ReturnType<typeof setTimeout> = setTimeout,
+) {
+  await new Promise<void>((resolve) => {
+    let socket: ReturnType<typeof createConnection> | undefined
+    let bytes = 0
+    const chunks: Buffer[] = []
+    const done = () => {
+      clearTimeout(timer)
+      input.pause()
+      input.off('data', data)
+      input.off('end', forward)
+      input.off('error', done)
+      socket?.destroy()
+      resolve()
+    }
+    const timer = schedule(done, 200)
+    const data = (chunk: Buffer) => {
+      bytes += chunk.length
+      if (bytes > MAX_MESSAGE_BYTES - 1024) done()
+      else chunks.push(Buffer.from(chunk))
+    }
+    const forward = () => {
+      try {
+        const index = args.indexOf('--session')
+        if (index < 0) return done()
+        const raw = JSON.parse(
+          args.at(-1)?.startsWith('{')
+            ? args.at(-1)!
+            : Buffer.concat(chunks).toString('utf8'),
+        )
+        const agentIndex = args.indexOf('--agent')
+        const agent = agentIndex < 0 ? 'claude' : args[agentIndex + 1]
+        socket = createConnection(socketPath(args[index + 1]))
+        socket.on('error', done)
+        socket.on('connect', () =>
+          socket!.end(JSON.stringify({ type: 'hook', agent, raw }) + '\n'),
+        )
+        socket.on('close', done)
+      } catch {
+        done()
+      }
+    }
+    // Codex appends notification JSON as argv, Claude sends stdin JSON.
+    if (args.at(-1)?.startsWith('{')) forward()
+    else {
+      input.on('data', data)
+      input.once('end', forward)
+      input.once('error', done)
+      input.resume()
+    }
+  })
+}
+
+export async function runHook(args: string[]) {
+  await forwardHook(args)
+  // The forwarding deadline bounds mirab only; the caller's notifier retains its
+  // own runtime and receives exactly the payload argument Codex appended.
+  const index = args.indexOf('--notify-command')
+  if (index >= 0) {
+    const command: unknown = JSON.parse(args[index + 1])
+    if (
+      Array.isArray(command) &&
+      command.length &&
+      command.every((arg) => typeof arg === 'string')
+    ) {
+      await new Promise<void>((resolve) => {
+        const child = spawn(command[0], [...command.slice(1), args.at(-1)!], {
+          stdio: 'inherit',
+        })
+        child.once('error', () => resolve())
+        child.once('exit', () => resolve())
+      })
+    }
+  }
+}

package/src/spawn-input.ts

@@ -0,0 +1,107 @@
+/** Conservative composer tracking; unknown editing controls never authorize injection. */
+export class InputLine {
+  dirty = false
+  private cause = ''
+  private paste = false
+  private escape = ''
+  private pasteDirty = false
+  // Terminal replies (OSC colour, DCS version, APC…) arrive on stdin when the
+  // agent queries the terminal. They are not typing, so they never dirty the
+  // line; they end at BEL or ESC \, and a line break ends a malformed one.
+  private string: '' | 'body' | 'escape' = ''
+  feed(data: Buffer | string): boolean {
+    let submitted = false
+    for (const byte of typeof data === 'string' ? Buffer.from(data) : data) {
+      if (this.string && byte !== 10 && byte !== 13) {
+        if (byte === 7 || (this.string === 'escape' && byte === 92))
+          this.string = ''
+        else this.string = byte === 27 ? 'escape' : 'body'
+        continue
+      }
+      this.string = ''
+      if (!this.paste && [3, 21, 10, 13].includes(byte)) {
+        this.escape = ''
+        this.dirty = false
+        if (byte === 10 || byte === 13) submitted = true
+        continue
+      }
+      if (this.escape === '\x1b' && [93, 80, 95, 94, 88].includes(byte)) {
+        this.escape = ''
+        this.string = 'body'
+        continue
+      }
+      if (this.escape) {
+        this.escape += String.fromCharCode(byte)
+        if (
+          '\x1b[200~'.startsWith(this.escape) ||
+          '\x1b[201~'.startsWith(this.escape)
+        ) {
+          if (this.escape === '\x1b[200~') {
+            this.paste = true
+            this.escape = ''
+            this.pasteDirty = false
+          } else if (this.escape === '\x1b[201~') {
+            this.paste = false
+            this.dirty ||= this.pasteDirty
+            this.escape = ''
+          }
+          continue
+        }
+        // CSI / SS3 cursor and function keys can arrive in separate chunks.
+        if (this.escape === '\x1b[' || this.escape === '\x1bO') continue
+        // Full CSI grammar: parameter bytes 0x30–0x3F (digits ; < = > ?),
+        // intermediates 0x20–0x2F, then one final byte. SGR mouse reports
+        // (ESC [ < b ; x ; y M) arrive on every click and are not typing.
+        if (/^\x1b\[[\x30-\x3f]*[\x20-\x2f]*$/.test(this.escape)) continue
+        const sequence = this.escape
+        this.escape = ''
+        // Esc cancels dialogs, but does not reliably erase or precede a draft.
+        if (
+          !sequence.startsWith('\x1b[') &&
+          !sequence.startsWith('\x1bO') &&
+          byte >= 32 &&
+          byte !== 127
+        ) {
+          this.dirty = true
+          this.cause = sequence
+        }
+        continue
+      }
+      if (byte === 27) {
+        this.escape = '\x1b'
+        continue
+      }
+      if (this.paste) {
+        this.pasteDirty = true
+        this.dirty = true
+        continue
+      }
+      if (byte === 13 || byte === 10) {
+        this.dirty = false
+        submitted = true
+      } else if (byte === 21 || byte === 3) this.dirty = false
+      // Backspace/delete and cursor editing are intentionally conservative.
+      else if ((byte >= 32 && byte !== 127) || byte === 9) {
+        this.dirty = true
+        this.cause = byte === 9 ? 'tab' : 'typed'
+      }
+    }
+    return submitted
+  }
+  settleEscape() {
+    if (this.escape === '\x1b') this.escape = ''
+  }
+  get why() {
+    return {
+      dirty: this.dirty && this.cause,
+      paste: this.paste,
+      escape: this.escape,
+      string: this.string,
+    }
+  }
+  get unsent() {
+    return (
+      this.dirty || this.paste || this.escape.length > 0 || this.string !== ''
+    )
+  }
+}

package/src/spawn-native.ts

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process'
+import { constants } from 'node:os'
+
+export function agentEnvironment() {
+  const env: Record<string, string> = {}
+  for (const [name, value] of Object.entries(process.env)) {
+    if (
+      value === undefined ||
+      /^(CLAUDECODE|CLAUDE_PID|CLAUDE_CODE_CHILD_SESSION|CLAUDE_CODE_SESSION_ID|CLAUDE_CODE_PARENT_SESSION_ID|CLAUDE_CODE_BRIDGE_SESSION_ID|CLAUDE_CODE_MESSAGING_SOCKET|CLAUDE_CODE_MESSAGING_TOKEN|CLAUDE_CODE_SESSION_ATTENDED|CLAUDE_CODE_ENTRYPOINT|CODEX_SESSION_ID|CODEX_THREAD_ID)$/.test(
+        name,
+      )
+    )
+      continue
+    env[name] = value
+  }
+  return env
+}
+export function debugFallback(reason: unknown) {
+  if (process.env.MIRAB_DEBUG)
+    console.error(`mirab spawn: native fallback: ${String(reason)}`)
+}
+export function supportsPty(platform = process.platform) {
+  return platform !== 'win32'
+}
+/** The child shares the foreground process group: terminal SIGINT already reaches it. */
+export async function runNative(
+  binary: string,
+  args: string[],
+  cwd = process.cwd(),
+  env = agentEnvironment(),
+) {
+  const child = spawn(binary, args, { stdio: 'inherit', cwd, env })
+  const interrupt = () => {}
+  process.on('SIGINT', interrupt)
+  const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGHUP']
+  const handlers = signals.map((signal) => () => child.kill(signal))
+  signals.forEach((signal, i) => process.on(signal, handlers[i]))
+  try {
+    return await new Promise<number>((resolve, reject) => {
+      child.once('error', reject)
+      child.once('exit', (code, signal) =>
+        resolve(code ?? 128 + (signal ? constants.signals[signal] : 0)),
+      )
+    })
+  } finally {
+    process.off('SIGINT', interrupt)
+    signals.forEach((signal, i) => process.off(signal, handlers[i]))
+  }
+}

package/src/spawn-nudge-worker.ts

@@ -0,0 +1,61 @@
+import { GildClient } from './api/client'
+import type { BridgeTarget } from './spawn-bridge'
+import { parseNudge, Watchdog, type NudgeEvent } from './spawn-nudge'
+
+function pair(repo: string) {
+  const [owner, name] = repo.split('/')
+  return { owner, repo: name }
+}
+
+/** The worker's watchdog: channel notes and reply checks use the session's
+ * own agent identity. gild-site has no system-note route for clients yet, so a
+ * note is an ordinary message from the agent, prefixed `[mirab nudge]`. */
+export function startWatchdog(o: {
+  specs: string[]
+  session: string
+  agent?: string
+  channels: string[]
+  target?: BridgeTarget
+  enqueue: (text: string) => void
+  emit: (event: NudgeEvent) => void
+}) {
+  if (!o.specs.length) return undefined
+  const client = o.target
+    ? new GildClient(o.target.server + '/api/v1', o.target.token)
+    : undefined
+  const agent = o.target?.agent ?? o.agent
+  return new Watchdog({
+    rules: o.specs.map(parseNudge),
+    session: o.session,
+    agent,
+    enqueue: o.enqueue,
+    emit: o.emit,
+    note:
+      client && o.channels.length
+        ? async (text, repo) => {
+            const own = o.channels.find(
+              (c) => c.toLowerCase() === repo?.toLowerCase(),
+            )
+            for (const channel of own ? [own] : o.channels)
+              await client.request('channelPost', pair(channel), { body: text })
+          }
+        : undefined,
+    replied:
+      client && agent
+        ? async (repo, cursor) => {
+            const page = await client.request(
+              'channelMessages',
+              pair(repo),
+              undefined,
+              { after: cursor, limit: 200 },
+            )
+            return page.messages.some(
+              (m) =>
+                m.kind === 'message' &&
+                m.author.name.toLowerCase() === agent.toLowerCase() &&
+                !m.body.startsWith('[mirab nudge]'),
+            )
+          }
+        : undefined,
+  })
+}