@agfpd/iapeer 0.2.59 → 0.2.61

package/src/supervisor/index.ts

@@ -0,0 +1,137 @@
+// Supervisor entry + CLI dispatch (cutover Block 2, ported from PoC pts.mjs). DARK: this module
+// (and daemon.ts/client.ts) load @xterm — they are reachable ONLY via the `supervisor` CLI verb
+// (dynamic import) and are NOT imported by transport/lifecycle/launch/daemon. The supervisor
+// serves NOTHING on the live fleet; it is validated on throwaway `tick` sessions in-repo. When
+// serving is productionized (a later block) the daemon-spawn argv is repointed at the installed
+// binary; for now it self-spawns from source (bun + this file), which is what the tests exercise.
+import { spawn as nodeSpawn } from 'node:child_process'
+import { existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { runSupervisorDaemon } from './daemon.ts'
+import { runSupervisorClient, sessionAlive } from './client.ts'
+import { defaultRunDir, logPath, pidPath, sockPath } from './paths.ts'
+
+export { runSupervisorDaemon } from './daemon.ts'
+export { runSupervisorClient, sessionAlive } from './client.ts'
+export { defaultRunDir, sockPath, pidPath } from './paths.ts'
+
+export interface StartDaemonOptions {
+  session: string
+  runtime: string
+  runDir: string
+  /** How to launch the detached daemon process (default: bun + this file). The trailing
+   *  `daemon <session> <runtime> --run-dir <runDir>` is appended. Serving-prod injects the
+   *  installed-binary argv here. */
+  daemonArgv?: string[]
+  /** Max ms to wait for the daemon socket+pid to appear (default 5000). */
+  timeoutMs?: number
+}
+
+export interface StartDaemonResult {
+  state: 'started' | 'already-running' | 'failed'
+  pid?: number
+  detail?: string
+}
+
+const selfArgv = (): string[] => [process.execPath, fileURLToPath(import.meta.url)]
+
+/** Start a detached supervisor daemon and wait until its socket is live. Idempotent. */
+export function startSupervisorDaemon(opts: StartDaemonOptions): StartDaemonResult {
+  const { session, runtime, runDir } = opts
+  if (sessionAlive(runDir, session)) return { state: 'already-running' }
+  mkdirSync(runDir, { recursive: true })
+  try {
+    if (existsSync(sockPath(runDir, session))) unlinkSync(sockPath(runDir, session))
+  } catch {
+    /* */
+  }
+  const out = openSync(logPath(runDir, session), 'a')
+  const argv = opts.daemonArgv ?? selfArgv()
+  const child = nodeSpawn(argv[0]!, [...argv.slice(1), 'daemon', session, runtime, '--run-dir', runDir], {
+    detached: true,
+    stdio: ['ignore', out, out],
+  })
+  child.unref()
+  const deadline = Date.now() + (opts.timeoutMs ?? 5000)
+  while (Date.now() < deadline) {
+    if (existsSync(sockPath(runDir, session)) && sessionAlive(runDir, session)) {
+      return { state: 'started', pid: Number(readFileSync(pidPath(runDir, session), 'utf8')) }
+    }
+    Bun.sleepSync(80)
+  }
+  return { state: 'failed', detail: `daemon did not come up; see ${logPath(runDir, session)}` }
+}
+
+export function listSessions(runDir: string): Array<{ session: string; alive: boolean; pid?: number }> {
+  if (!existsSync(runDir)) return []
+  return readdirSync(runDir)
+    .filter(f => f.endsWith('.sock'))
+    .map(f => f.replace(/\.sock$/, ''))
+    .map(session => {
+      const alive = sessionAlive(runDir, session)
+      return { session, alive, pid: alive ? Number(readFileSync(pidPath(runDir, session), 'utf8')) : undefined }
+    })
+}
+
+export function killSession(runDir: string, session: string): boolean {
+  const pf = pidPath(runDir, session)
+  if (!existsSync(pf)) return false
+  const pid = Number(readFileSync(pf, 'utf8'))
+  try {
+    process.kill(pid, 'SIGTERM')
+  } catch {
+    /* already gone */
+  }
+  return true
+}
+
+/** Parse a `--run-dir <dir>` flag out of an argv slice; returns the value or the default. */
+function runDirFrom(args: string[]): string {
+  const i = args.indexOf('--run-dir')
+  return i >= 0 && args[i + 1] ? args[i + 1]! : defaultRunDir()
+}
+
+/** CLI dispatch (also the `import.meta.main` entry used by the spawned daemon process). */
+export async function runSupervisorCli(argv: string[]): Promise<number> {
+  const [cmd, a, b] = argv
+  const runDir = runDirFrom(argv)
+  switch (cmd) {
+    case 'daemon':
+      runSupervisorDaemon({ session: a!, runtime: b || 'claude', runDir })
+      // The daemon is event-driven: runSupervisorDaemon RETURNS after wiring the pty + socket
+      // server, and the event loop keeps the process alive. Await a never-resolving promise so the
+      // caller's `process.exit` does NOT fire — shutdown() (child-exit / SIGTERM) owns the exit.
+      await new Promise<never>(() => {})
+      return 0 // unreachable
+    case 'start': {
+      const r = startSupervisorDaemon({ session: a!, runtime: b || 'claude', runDir })
+      console.log(`${r.state}${r.pid ? ` pid=${r.pid}` : ''}${r.detail ? ` — ${r.detail}` : ''}: ${a}`)
+      return r.state === 'failed' ? 1 : 0
+    }
+    case 'attach':
+      await runSupervisorClient(runDir, a!)
+      return 0
+    case 'up': {
+      const r = startSupervisorDaemon({ session: a!, runtime: b || 'claude', runDir })
+      if (r.state === 'failed') {
+        console.error(r.detail)
+        return 1
+      }
+      await runSupervisorClient(runDir, a!)
+      return 0
+    }
+    case 'list':
+      for (const s of listSessions(runDir)) console.log(`${s.session}\t${s.alive ? `running pid=${s.pid}` : 'dead'}`)
+      return 0
+    case 'kill':
+      console.log(killSession(runDir, a!) ? `killed "${a}"` : `no session "${a}"`)
+      return 0
+    default:
+      console.log('usage: supervisor up|start|attach|list|kill <session> [runtime] [--run-dir <dir>]   (detach: Ctrl-])')
+      return 0
+  }
+}
+
+if (import.meta.main) {
+  process.exit(await runSupervisorCli(process.argv.slice(2)))
+}

package/src/supervisor/paths.ts

@@ -0,0 +1,14 @@
+// Supervisor session paths — under a configurable run dir (NOT hardcoded). Prod resolves it to
+// ~/.iapeer/state/supervisor via the storage layer; tests pass a temp dir, so the daemon's
+// socket/pid files never touch a real location.
+import { join } from 'node:path'
+import { pluginStateDir } from '../storage/index.ts'
+
+/** Default run dir for the supervisor's session sockets/pids: ~/.iapeer/state/supervisor. */
+export function defaultRunDir(env: NodeJS.ProcessEnv = process.env): string {
+  return pluginStateDir('supervisor', { env })
+}
+
+export const sockPath = (runDir: string, session: string): string => join(runDir, `${session}.sock`)
+export const pidPath = (runDir: string, session: string): string => join(runDir, `${session}.pid`)
+export const logPath = (runDir: string, session: string): string => join(runDir, `${session}.log`)

package/src/supervisor/protocol.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  BackpressureWriter,
+  FRAME_DATA,
+  FRAME_RESIZE,
+  TERM_RESET,
+  capabilityResponses,
+  frame,
+  makeFramer,
+  parseSize,
+  sizePayload,
+  stripQueries,
+} from './protocol.ts'
+
+describe('frame protocol', () => {
+  test('frame() lays out [type][len:u32be][payload]', () => {
+    const f = frame(FRAME_DATA, 'hi')
+    expect(f[0]).toBe(FRAME_DATA)
+    expect(f.readUInt32BE(1)).toBe(2)
+    expect(f.subarray(5).toString()).toBe('hi')
+  })
+
+  test('makeFramer reassembles a frame split across chunk boundaries', () => {
+    const got: Array<{ t: number; p: string }> = []
+    const fr = makeFramer((t, p) => got.push({ t, p: p.toString() }))
+    const f = frame(FRAME_DATA, 'hello world')
+    fr(f.subarray(0, 3)) // partial header
+    fr(f.subarray(3, 8)) // rest of header + part of payload
+    expect(got).toHaveLength(0) // nothing complete yet
+    fr(f.subarray(8)) // tail
+    expect(got).toEqual([{ t: FRAME_DATA, p: 'hello world' }])
+  })
+
+  test('makeFramer splits multiple coalesced frames', () => {
+    const got: string[] = []
+    const fr = makeFramer((_t, p) => got.push(p.toString()))
+    fr(Buffer.concat([frame(FRAME_DATA, 'a'), frame(FRAME_DATA, 'bb'), frame(FRAME_DATA, 'ccc')]))
+    expect(got).toEqual(['a', 'bb', 'ccc'])
+  })
+
+  test('sizePayload/parseSize round-trip', () => {
+    expect(parseSize(sizePayload(132, 50))).toEqual({ cols: 132, rows: 50 })
+    expect(frame(FRAME_RESIZE, sizePayload(80, 24))[0]).toBe(FRAME_RESIZE)
+  })
+})
+
+describe('capability responder (the queries @xterm does not auto-answer)', () => {
+  test('secondary-DA-style XTVERSION query → version report', () => {
+    expect(capabilityResponses('\x1b[>0q')).toEqual(['\x1bP>|iapeer-pts(0.1)\x1b\\'])
+  })
+  test('OSC-11 theme query → an rgb background report', () => {
+    expect(capabilityResponses('\x1b]11;?\x07')[0]).toContain('\x1b]11;rgb:')
+  })
+  test('secondary DA (>c) → a DA2 report', () => {
+    expect(capabilityResponses('\x1b[>0c')).toEqual(['\x1b[>0;276;0c'])
+  })
+  test('plain output → no responses', () => {
+    expect(capabilityResponses('just some text\r\n')).toEqual([])
+  })
+  test('stripQueries removes DA1/DSR/theme but keeps real output', () => {
+    const s = 'before\x1b[0c\x1b[6nmid\x1b]11;?\x07after'
+    const out = stripQueries(s)
+    expect(out).toBe('beforemidafter')
+    expect(out).not.toContain('\x1b[6n')
+  })
+})
+
+describe('TERM_RESET (port-dep #1: clean every client exit path)', () => {
+  test('resets the leak-prone app-modes', () => {
+    expect(TERM_RESET).toContain('\x1b[?1049l') // leave alt-screen
+    expect(TERM_RESET).toContain('\x1b[?1000l') // mouse tracking off
+    expect(TERM_RESET).toContain('\x1b[?25h') // show cursor
+    expect(TERM_RESET).toContain('\x1b[<u') // pop kitty-keyboard
+  })
+})
+
+describe('BackpressureWriter (port-dep #2: the ~90 KB-over-8 KB truncation that staled reattach)', () => {
+  test('a fully-accepted write leaves nothing queued', () => {
+    const w = new BackpressureWriter(b => b.length)
+    expect(w.send(Buffer.alloc(100))).toBe(true)
+    expect(w.queuedBytes).toBe(0)
+  })
+
+  test('a heavy frame past the socket buffer is QUEUED, then fully delivered across drains', () => {
+    const CAP = 8192
+    let delivered = 0
+    const w = new BackpressureWriter(b => {
+      const n = Math.min(CAP, b.length)
+      delivered += n
+      return n
+    })
+    const heavy = Buffer.alloc(89305, 0x41) // the measured heavy-claude serialize size
+    expect(w.send(heavy)).toBe(true)
+    expect(delivered).toBe(CAP) // first write took only the socket buffer
+    expect(w.queuedBytes).toBe(89305 - CAP) // the rest is queued, NOT dropped
+    let guard = 0
+    while (w.queuedBytes > 0 && guard++ < 1000) w.flush() // drain events
+    expect(delivered).toBe(89305) // every byte eventually delivered (no truncation)
+    expect(w.queuedBytes).toBe(0)
+    expect(w.isDead).toBe(false)
+  })
+
+  test('coalesces a new send onto the pending tail (ordering preserved)', () => {
+    const CAP = 4
+    const chunks: string[] = []
+    const w = new BackpressureWriter(b => {
+      const n = Math.min(CAP, b.length)
+      chunks.push(b.subarray(0, n).toString())
+      return n
+    })
+    w.send(Buffer.from('ABCDEF')) // 'ABCD' written, 'EF' queued
+    w.send(Buffer.from('GH')) // coalesced onto 'EF' → 'EFGH'
+    let guard = 0
+    while (w.queuedBytes > 0 && guard++ < 100) w.flush()
+    expect(chunks.join('')).toBe('ABCDEFGH')
+  })
+
+  test('a dead socket (write throws) → send returns false and the writer is dead', () => {
+    const w = new BackpressureWriter(() => {
+      throw new Error('EPIPE')
+    })
+    expect(w.send(Buffer.alloc(10))).toBe(false)
+    expect(w.isDead).toBe(true)
+  })
+
+  test('a negative write count → dead', () => {
+    const w = new BackpressureWriter(() => -1)
+    expect(w.send(Buffer.alloc(10))).toBe(false)
+    expect(w.isDead).toBe(true)
+  })
+})

package/src/supervisor/protocol.ts

@@ -0,0 +1,155 @@
+// Supervisor wire/terminal PRIMITIVES — the pure, hermetically-testable core of the
+// detach-persistent pty-supervisor (cutover Block 2, ported from the validated PoC pts.mjs).
+//
+// PURE: no Bun, no @xterm, no socket — frames, the capability responder, the backpressure
+// writer (port-dep #2), and the terminal-reset string (port-dep #1) are all data-in/data-out,
+// so the two reattach port-deps that bit the PoC are unit-provable without spawning anything.
+
+const EMPTY = Buffer.alloc(0)
+
+// ── client/daemon frame protocol: [type:u8][len:u32be][payload] ──
+export const FRAME_DATA = 0
+export const FRAME_RESIZE = 1
+
+export function frame(type: number, payload: Buffer | string): Buffer {
+  const p = Buffer.isBuffer(payload) ? payload : Buffer.from(payload)
+  const h = Buffer.alloc(5)
+  h[0] = type
+  h.writeUInt32BE(p.length, 1)
+  return Buffer.concat([h, p])
+}
+
+/** Streaming frame de-chunker: reassembles frames across arbitrary TCP/unix chunk boundaries
+ *  (a frame may arrive split, or several may arrive coalesced). Calls onFrame per complete frame. */
+export function makeFramer(onFrame: (type: number, payload: Buffer) => void): (chunk: Uint8Array | Buffer) => void {
+  let buf: Buffer = EMPTY
+  return chunk => {
+    buf = buf.length ? Buffer.concat([buf, Buffer.from(chunk)]) : Buffer.from(chunk)
+    while (buf.length >= 5) {
+      const type = buf[0]!
+      const len = buf.readUInt32BE(1)
+      if (buf.length < 5 + len) break
+      onFrame(type, buf.subarray(5, 5 + len))
+      buf = buf.subarray(5 + len)
+    }
+  }
+}
+
+export function sizePayload(cols: number, rows: number): Buffer {
+  const b = Buffer.alloc(4)
+  b.writeUInt16BE(cols || 80, 0)
+  b.writeUInt16BE(rows || 24, 2)
+  return b
+}
+
+export function parseSize(payload: Buffer): { cols: number; rows: number } {
+  return { cols: payload.readUInt16BE(0), rows: payload.readUInt16BE(2) }
+}
+
+// ── capability responder ──────────────────────────────────────────────────────
+// The child (claude/codex TUI) emits terminal capability QUERIES (device attributes, cursor
+// position, theme) and BLOCKS its first paint until they are answered. tmux answers them; the
+// supervisor daemon must too. @xterm/headless auto-answers DA1/DSR via onData; these are the
+// ones it does NOT: secondary/tertiary DA (`>q`, `>c`) and the OSC-11 theme query.
+
+export const QUERY_RE = /\x1b\[0?c|\x1b\[>\d*[qc]|\x1b\[6n|\x1b\]11;\?(?:\x07|\x1b\\)/g
+
+/** Supplementary capability answers to write back INTO the child for queries @xterm does not
+ *  auto-answer. Returns the response strings (possibly empty). Pure — testable without a pty. */
+export function capabilityResponses(s: string): string[] {
+  const out: string[] = []
+  if (/\x1b\[>\d*q/.test(s)) out.push('\x1bP>|iapeer-pts(0.1)\x1b\\') // XTVERSION (DA2-style)
+  if (/\x1b\]11;\?(\x07|\x1b\\)/.test(s)) out.push('\x1b]11;rgb:1e1e/1e1e/1e1e\x07') // OSC-11 theme
+  if (/\x1b\[>\d*c/.test(s)) out.push('\x1b[>0;276;0c') // secondary DA
+  return out
+}
+
+/** Strip capability queries from a child-output chunk before forwarding to clients (the daemon
+ *  is the authoritative responder — clients must not see/answer the queries themselves). */
+export function stripQueries(s: string): string {
+  return s.replace(QUERY_RE, '')
+}
+
+// ── port-dep #1: terminal reset on every client exit path ───────────────────────
+// The child sets a STACK of app-modes on the live terminal (alt-screen, bracketed-paste,
+// focus-events, theme-update, ALL mouse tracking, kitty-keyboard, scroll-region, hidden cursor).
+// They persist in the window after the client goes. A SIGHUP/window-close client that ran NOTHING
+// leaked them → broke the NEXT reattach (mouse tracking eats the scroll wheel, kitty garbles keys,
+// leftover modes freeze the render). Reset to a clean base on EVERY exit path; the next attach's
+// repaint + the child's live re-render re-assert whatever the session actually needs.
+export const TERM_RESET =
+  '\x1b[?1049l' + // leave alt-screen (normal buffer)
+  '\x1b[?2004l' + // bracketed-paste off
+  '\x1b[?1004l' + // focus-event reporting off
+  '\x1b[?2031l' + // theme/color-scheme-update off
+  '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1015l' + // ALL mouse tracking off
+  '\x1b[<u' + // pop kitty-keyboard flags
+  '\x1b[r' + // reset scroll region (DECSTBM) to full
+  '\x1b[?25h' + // show cursor
+  '\x1b[?7h' // wraparound on (default)
+
+// ── port-dep #2: backpressure-safe socket writer ────────────────────────────────
+// Bun's sock.write() of a large buffer accepts only the socket buffer (~8 KB) and RETURNS the
+// count actually taken — the rest is DROPPED unless queued and re-sent on `drain`. The PoC's old
+// code ignored the return, so a heavy-claude repaint frame (~90 KB serialize) arrived TRUNCATED
+// (measured live: len=89305, only 8192 delivered) → the client's framer waited forever for a
+// frame that never completed → reattach showed the STALE close-moment frame. This writer queues
+// the unwritten tail and flushes it on drain, for BOTH the repaint snapshot and live forward.
+
+export interface SocketWrite {
+  /** Write up to buf.length bytes; return the count ACCEPTED (Bun semantics), or <0 on a dead socket. */
+  (buf: Buffer): number
+}
+
+/** Per-socket backpressure queue. send() coalesces+writes and queues the unaccepted tail;
+ *  flush() (call on the socket `drain` event) drains the queue. Dead once write throws / returns <0. */
+export class BackpressureWriter {
+  private pending: Buffer = EMPTY
+  private dead = false
+  constructor(private readonly write: SocketWrite) {}
+
+  /** Queue and send `buf`. Returns false iff the socket is dead (caller should drop the client). */
+  send(buf: Buffer): boolean {
+    if (this.dead) return false
+    const data = this.pending.length ? Buffer.concat([this.pending, buf]) : buf
+    let n: number
+    try {
+      n = this.write(data)
+    } catch {
+      this.dead = true
+      return false
+    }
+    if (n < 0) {
+      this.dead = true
+      return false
+    }
+    this.pending = n < data.length ? data.subarray(n) : EMPTY
+    return true
+  }
+
+  /** Flush the queued tail (call on `drain`). Returns false iff the socket died flushing. */
+  flush(): boolean {
+    if (this.dead) return false
+    if (!this.pending.length) return true
+    let n: number
+    try {
+      n = this.write(this.pending)
+    } catch {
+      this.dead = true
+      return false
+    }
+    if (n < 0) {
+      this.dead = true
+      return false
+    }
+    this.pending = n < this.pending.length ? this.pending.subarray(n) : EMPTY
+    return true
+  }
+
+  get isDead(): boolean {
+    return this.dead
+  }
+  get queuedBytes(): number {
+    return this.pending.length
+  }
+}