airaknit 1.1.2-rc.9

package/src/server/claude-pty/pty-instance-registry.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, test } from "bun:test"
+import {
+  createPtyInstanceRegistry,
+  type PtyInstanceDelta,
+  type PtyInstanceState,
+} from "./pty-instance-registry"
+
+function baseline(overrides: Partial<PtyInstanceState> = {}): Omit<PtyInstanceState, "chatId"> {
+  return {
+    sessionId: null,
+    pid: null,
+    cwd: "/tmp",
+    model: "claude-opus-4-7",
+    accountLabel: null,
+    oauthMasked: null,
+    phase: "spawning",
+    startedAt: 1_000,
+    lastEventAt: 1_000,
+    turnCount: 0,
+    tokensIn: 0,
+    tokensOut: 0,
+    planMode: null,
+    smokeTest: null,
+    outputRingTail: null,
+    exitedAt: null,
+    exitCode: null,
+    rssBytes: null,
+    rssPeakBytes: null,
+    cpuPercent: null,
+    cpuPeakPercent: null,
+    ...overrides,
+  }
+}
+
+describe("PtyInstanceRegistry", () => {
+  test("upsert with new chatId fires added", () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0 })
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d))
+    registry.upsert("c1", baseline())
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({ type: "added", instance: { chatId: "c1" } })
+  })
+
+  test("upsert with existing chatId fires updated and merges patch", () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0 })
+    registry.upsert("c1", baseline())
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d))
+    registry.upsert("c1", { phase: "ready", pid: 42 })
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      type: "updated",
+      instance: { chatId: "c1", phase: "ready", pid: 42, cwd: "/tmp" },
+    })
+  })
+
+  test("remove fires removed event and drops state", () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0 })
+    registry.upsert("c1", baseline())
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d))
+    registry.remove("c1")
+    expect(events).toEqual([{ type: "removed", chatId: "c1" }])
+    expect(registry.snapshot()).toEqual([])
+  })
+
+  test("remove for unknown chatId is a no-op", () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0 })
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d))
+    registry.remove("nope")
+    expect(events).toEqual([])
+  })
+
+  test("snapshot returns clones, not references", () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0 })
+    registry.upsert("c1", baseline())
+    const a = registry.snapshot()
+    const b = registry.snapshot()
+    expect(a[0]).not.toBe(b[0])
+    a[0]!.phase = "exited"
+    expect(registry.snapshot()[0]!.phase).toBe("spawning")
+  })
+
+  test("unsubscribe stops further events", () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0 })
+    const events: PtyInstanceDelta[] = []
+    const off = registry.subscribe((d) => events.push(d))
+    off()
+    registry.upsert("c1", baseline())
+    expect(events).toEqual([])
+  })
+
+  test("coalesce: rapid updates within window emit one trailing delta", async () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 30 })
+    registry.upsert("c1", baseline())
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d))
+    registry.upsert("c1", { tokensIn: 1 })
+    registry.upsert("c1", { tokensIn: 2 })
+    registry.upsert("c1", { tokensIn: 3 })
+    expect(events).toEqual([])
+    await new Promise((r) => setTimeout(r, 50))
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({ type: "updated", instance: { tokensIn: 3 } })
+  })
+
+  test("coalesce: added events are not delayed", () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 30 })
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d))
+    registry.upsert("c1", baseline())
+    expect(events).toHaveLength(1)
+    expect(events[0]!.type).toBe("added")
+  })
+
+  test("coalesce: removed flushes pending update for same chatId", async () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 30 })
+    registry.upsert("c1", baseline())
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d))
+    registry.upsert("c1", { phase: "streaming" })
+    registry.remove("c1")
+    await new Promise((r) => setTimeout(r, 50))
+    expect(events.map((e) => e.type)).toEqual(["removed"])
+  })
+
+  test("exitedTtlMs: entry auto-removed after TTL when phase becomes exited", async () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0, exitedTtlMs: 30 })
+    registry.upsert("c1", baseline({ phase: "ready" }))
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d))
+    registry.upsert("c1", { phase: "exited", exitedAt: 2_000 })
+    expect(events.map((e) => e.type)).toEqual(["updated"])
+    expect(registry.snapshot()).toHaveLength(1)
+    await new Promise((r) => setTimeout(r, 60))
+    expect(events.map((e) => e.type)).toEqual(["updated", "removed"])
+    expect(registry.snapshot()).toEqual([])
+  })
+
+  test("exitedTtlMs: prune cancelled if phase moves away from exited before TTL", async () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0, exitedTtlMs: 30 })
+    registry.upsert("c1", baseline({ phase: "exited", exitedAt: 1_000 }))
+    registry.upsert("c1", { phase: "ready", exitedAt: null })
+    await new Promise((r) => setTimeout(r, 60))
+    expect(registry.snapshot()).toHaveLength(1)
+    expect(registry.snapshot()[0]!.phase).toBe("ready")
+  })
+
+  test("exitedTtlMs: 0 disables auto-prune", async () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0, exitedTtlMs: 0 })
+    registry.upsert("c1", baseline({ phase: "exited", exitedAt: 1_000 }))
+    await new Promise((r) => setTimeout(r, 30))
+    expect(registry.snapshot()).toHaveLength(1)
+  })
+
+  test("exitedTtlMs: manual remove cancels pending prune", async () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0, exitedTtlMs: 30 })
+    registry.upsert("c1", baseline({ phase: "exited", exitedAt: 1_000 }))
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d))
+    registry.remove("c1")
+    await new Promise((r) => setTimeout(r, 60))
+    expect(events.map((e) => e.type)).toEqual(["removed"])
+  })
+
+  test("subscribe replay seeds listener with current state", () => {
+    const registry = createPtyInstanceRegistry({ coalesceMs: 0 })
+    registry.upsert("c1", baseline())
+    registry.upsert("c2", baseline({ phase: "ready" }))
+    const events: PtyInstanceDelta[] = []
+    registry.subscribe((d) => events.push(d), { replay: true })
+    expect(events).toHaveLength(2)
+    expect(events.every((e) => e.type === "added")).toBe(true)
+  })
+})

package/src/server/claude-pty/pty-instance-registry.ts

@@ -0,0 +1,166 @@
+import type { PtyInstanceDelta, PtyInstanceState } from "../../shared/pty-instance"
+
+export type { PtyInstanceDelta, PtyInstanceState }
+
+export type PtyInstanceListener = (delta: PtyInstanceDelta) => void
+
+export interface PtyInstanceSubscribeOptions {
+  replay?: boolean
+}
+
+export interface PtyInstanceRegistry {
+  snapshot(): PtyInstanceState[]
+  subscribe(listener: PtyInstanceListener, options?: PtyInstanceSubscribeOptions): () => void
+  upsert(chatId: string, patch: Partial<Omit<PtyInstanceState, "chatId">>): void
+  remove(chatId: string): void
+}
+
+export interface CreatePtyInstanceRegistryOptions {
+  /** Trailing-edge coalesce window for "updated" deltas, in ms. 0 disables. */
+  coalesceMs?: number
+  /**
+   * TTL after which entries that enter `phase: "exited"` are auto-removed
+   * to bound in-memory growth. 0 disables auto-prune.
+   */
+  exitedTtlMs?: number
+}
+
+const DEFAULT_COALESCE_MS = 100
+const DEFAULT_EXITED_TTL_MS = 60_000
+
+export function createPtyInstanceRegistry(
+  options: CreatePtyInstanceRegistryOptions = {},
+): PtyInstanceRegistry {
+  const coalesceMs = options.coalesceMs ?? DEFAULT_COALESCE_MS
+  const exitedTtlMs = options.exitedTtlMs ?? DEFAULT_EXITED_TTL_MS
+  const states = new Map<string, PtyInstanceState>()
+  const listeners = new Set<PtyInstanceListener>()
+  const pendingFlushes = new Map<string, ReturnType<typeof setTimeout>>()
+  const exitedPrunes = new Map<string, ReturnType<typeof setTimeout>>()
+
+  function emit(delta: PtyInstanceDelta): void {
+    for (const listener of listeners) listener(delta)
+  }
+
+  function clone(state: PtyInstanceState): PtyInstanceState {
+    return { ...state }
+  }
+
+  function cancelPendingFlush(chatId: string): void {
+    const handle = pendingFlushes.get(chatId)
+    if (handle) {
+      clearTimeout(handle)
+      pendingFlushes.delete(chatId)
+    }
+  }
+
+  function cancelExitedPrune(chatId: string): void {
+    const handle = exitedPrunes.get(chatId)
+    if (handle) {
+      clearTimeout(handle)
+      exitedPrunes.delete(chatId)
+    }
+  }
+
+  function scheduleExitedPrune(chatId: string): void {
+    if (exitedTtlMs <= 0) return
+    cancelExitedPrune(chatId)
+    exitedPrunes.set(
+      chatId,
+      setTimeout(() => {
+        exitedPrunes.delete(chatId)
+        removeInternal(chatId)
+      }, exitedTtlMs),
+    )
+  }
+
+  function reconcileExitedTimer(chatId: string, phase: PtyInstanceState["phase"]): void {
+    if (phase === "exited") scheduleExitedPrune(chatId)
+    else cancelExitedPrune(chatId)
+  }
+
+  function flushUpdate(chatId: string): void {
+    pendingFlushes.delete(chatId)
+    const state = states.get(chatId)
+    if (!state) return
+    emit({ type: "updated", instance: clone(state) })
+  }
+
+  function removeInternal(chatId: string): void {
+    if (!states.has(chatId)) return
+    cancelPendingFlush(chatId)
+    cancelExitedPrune(chatId)
+    states.delete(chatId)
+    emit({ type: "removed", chatId })
+  }
+
+  return {
+    snapshot(): PtyInstanceState[] {
+      return Array.from(states.values(), clone)
+    },
+
+    subscribe(listener, opts): () => void {
+      listeners.add(listener)
+      if (opts?.replay) {
+        for (const state of states.values()) {
+          listener({ type: "added", instance: clone(state) })
+        }
+      }
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+
+    upsert(chatId, patch): void {
+      const existing = states.get(chatId)
+      if (existing) {
+        const next: PtyInstanceState = { ...existing, ...patch, chatId }
+        states.set(chatId, next)
+        reconcileExitedTimer(chatId, next.phase)
+        if (coalesceMs <= 0) {
+          emit({ type: "updated", instance: clone(next) })
+          return
+        }
+        if (!pendingFlushes.has(chatId)) {
+          pendingFlushes.set(
+            chatId,
+            setTimeout(() => flushUpdate(chatId), coalesceMs),
+          )
+        }
+        return
+      }
+      const baseline: PtyInstanceState = {
+        chatId,
+        sessionId: null,
+        pid: null,
+        cwd: "",
+        model: "",
+        accountLabel: null,
+        oauthMasked: null,
+        phase: "spawning",
+        startedAt: 0,
+        lastEventAt: 0,
+        turnCount: 0,
+        tokensIn: 0,
+        tokensOut: 0,
+        planMode: null,
+        smokeTest: null,
+        outputRingTail: null,
+        exitedAt: null,
+        exitCode: null,
+        rssBytes: null,
+        rssPeakBytes: null,
+        cpuPercent: null,
+        cpuPeakPercent: null,
+        ...patch,
+      }
+      states.set(chatId, baseline)
+      reconcileExitedTimer(chatId, baseline.phase)
+      emit({ type: "added", instance: clone(baseline) })
+    },
+
+    remove(chatId): void {
+      removeInternal(chatId)
+    },
+  }
+}

package/src/server/claude-pty/pty-memory-sampler.adapter.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test"
+import process from "node:process"
+import {
+  collectTreePids,
+  parsePsOutput,
+  sampleProcessTreeUsage,
+  sumTreeUsage,
+  type PsProcessRow,
+} from "./pty-memory-sampler.adapter"
+
+describe("parsePsOutput", () => {
+  test("parses normal ps output with pid/ppid/rss/pcpu", () => {
+    const out = [
+      "    1     0    1024   0.0",
+      "  100     1    2048   5.2",
+      "  101   100    4096  12.5",
+      "",
+      "  102   100    8192  99.9",
+    ].join("\n")
+    expect(parsePsOutput(out)).toEqual([
+      { pid: 1, ppid: 0, rssKb: 1024, cpuPercent: 0.0 },
+      { pid: 100, ppid: 1, rssKb: 2048, cpuPercent: 5.2 },
+      { pid: 101, ppid: 100, rssKb: 4096, cpuPercent: 12.5 },
+      { pid: 102, ppid: 100, rssKb: 8192, cpuPercent: 99.9 },
+    ])
+  })
+
+  test("skips malformed rows without throwing", () => {
+    const out = [
+      "100 1 1024 3.0",
+      "garbage line here",
+      "abc def ghi jkl",
+      "200 1 2048 7.5",
+      " ",
+      "300 1 100",
+    ].join("\n")
+    expect(parsePsOutput(out)).toEqual([
+      { pid: 100, ppid: 1, rssKb: 1024, cpuPercent: 3.0 },
+      { pid: 200, ppid: 1, rssKb: 2048, cpuPercent: 7.5 },
+    ])
+  })
+
+  test("returns empty array for empty input", () => {
+    expect(parsePsOutput("")).toEqual([])
+    expect(parsePsOutput("\n\n\n")).toEqual([])
+  })
+})
+
+describe("collectTreePids", () => {
+  const rows: PsProcessRow[] = [
+    { pid: 1, ppid: 0, rssKb: 0, cpuPercent: 0 },
+    { pid: 100, ppid: 1, rssKb: 0, cpuPercent: 0 },
+    { pid: 101, ppid: 100, rssKb: 0, cpuPercent: 0 },
+    { pid: 102, ppid: 100, rssKb: 0, cpuPercent: 0 },
+    { pid: 103, ppid: 101, rssKb: 0, cpuPercent: 0 },
+    { pid: 200, ppid: 1, rssKb: 0, cpuPercent: 0 },
+  ]
+
+  test("collects root + descendants transitively", () => {
+    expect(collectTreePids(rows, 100)).toEqual(new Set([100, 101, 102, 103]))
+  })
+
+  test("returns only root when no children", () => {
+    expect(collectTreePids(rows, 200)).toEqual(new Set([200]))
+  })
+
+  test("returns only root when root absent from rows", () => {
+    expect(collectTreePids(rows, 999)).toEqual(new Set([999]))
+  })
+})
+
+describe("sumTreeUsage", () => {
+  const rows: PsProcessRow[] = [
+    { pid: 1, ppid: 0, rssKb: 100, cpuPercent: 1.0 },
+    { pid: 100, ppid: 1, rssKb: 200, cpuPercent: 25.0 },
+    { pid: 101, ppid: 100, rssKb: 300, cpuPercent: 50.5 },
+  ]
+
+  test("sums rss (kb->bytes) + cpu for pids in tree", () => {
+    const tree = new Set<number>([100, 101])
+    expect(sumTreeUsage(rows, tree)).toEqual({
+      rssBytes: (200 + 300) * 1024,
+      cpuPercent: 25.0 + 50.5,
+    })
+  })
+
+  test("returns zeros for empty tree", () => {
+    expect(sumTreeUsage(rows, new Set())).toEqual({ rssBytes: 0, cpuPercent: 0 })
+  })
+})
+
+describe("sampleProcessTreeUsage", () => {
+  test("returns positive rss + finite cpu for current process", async () => {
+    const sample = await sampleProcessTreeUsage(process.pid)
+    expect(sample).not.toBeNull()
+    expect(sample?.rssBytes).toBeGreaterThan(0)
+    expect(Number.isFinite(sample?.cpuPercent ?? Number.NaN)).toBe(true)
+  }, 5_000)
+
+  test("returns null for pid that does not exist", async () => {
+    expect(await sampleProcessTreeUsage(2_147_483_646)).toBeNull()
+  }, 5_000)
+})

package/src/server/claude-pty/pty-memory-sampler.adapter.ts

@@ -0,0 +1,85 @@
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+
+const execFileAsync = promisify(execFile)
+
+const PS_TIMEOUT_MS = 2000
+
+export interface PsProcessRow {
+  pid: number
+  ppid: number
+  rssKb: number
+  cpuPercent: number
+}
+
+export interface ProcessTreeSample {
+  rssBytes: number
+  cpuPercent: number
+}
+
+export function parsePsOutput(stdout: string): PsProcessRow[] {
+  const rows: PsProcessRow[] = []
+  for (const rawLine of stdout.split("\n")) {
+    const line = rawLine.trim()
+    if (!line) continue
+    const parts = line.split(/\s+/)
+    if (parts.length < 4) continue
+    const pid = Number(parts[0])
+    const ppid = Number(parts[1])
+    const rssKb = Number(parts[2])
+    const cpuPercent = Number(parts[3])
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid) || !Number.isFinite(rssKb) || !Number.isFinite(cpuPercent)) continue
+    rows.push({ pid, ppid, rssKb, cpuPercent })
+  }
+  return rows
+}
+
+export function collectTreePids(rows: readonly PsProcessRow[], rootPid: number): Set<number> {
+  const childrenByParent = new Map<number, number[]>()
+  for (const row of rows) {
+    const list = childrenByParent.get(row.ppid)
+    if (list) list.push(row.pid)
+    else childrenByParent.set(row.ppid, [row.pid])
+  }
+  const tree = new Set<number>([rootPid])
+  const queue: number[] = [rootPid]
+  while (queue.length > 0) {
+    const next = queue.shift() as number
+    const kids = childrenByParent.get(next)
+    if (!kids) continue
+    for (const kid of kids) {
+      if (tree.has(kid)) continue
+      tree.add(kid)
+      queue.push(kid)
+    }
+  }
+  return tree
+}
+
+export function sumTreeUsage(rows: readonly PsProcessRow[], tree: ReadonlySet<number>): ProcessTreeSample {
+  let totalKb = 0
+  let totalCpu = 0
+  for (const row of rows) {
+    if (!tree.has(row.pid)) continue
+    totalKb += row.rssKb
+    totalCpu += row.cpuPercent
+  }
+  return { rssBytes: totalKb * 1024, cpuPercent: totalCpu }
+}
+
+export async function sampleProcessTreeUsage(rootPid: number): Promise<ProcessTreeSample | null> {
+  let stdout: string
+  try {
+    const result = await execFileAsync("ps", ["-A", "-o", "pid=,ppid=,rss=,pcpu="], {
+      timeout: PS_TIMEOUT_MS,
+      maxBuffer: 4 * 1024 * 1024,
+    })
+    stdout = result.stdout
+  } catch {
+    return null
+  }
+  const rows = parsePsOutput(stdout)
+  if (!rows.some((r) => r.pid === rootPid)) return null
+  const tree = collectTreePids(rows, rootPid)
+  return sumTreeUsage(rows, tree)
+}

package/src/server/claude-pty/pty-process.adapter.ts

@@ -0,0 +1,66 @@
+export interface PtyProcess {
+  /** OS pid of the spawned child (== pgid because Bun.Terminal setsid). */
+  pid: number
+  sendInput(data: string): Promise<void>
+  resize(cols: number, rows: number): void
+  exited: Promise<number>
+  /** Default terminate: SIGTERM (gives the child a chance to flush). */
+  close(): void
+  /**
+   * Force kill (SIGKILL) — use after SIGTERM has had a grace window and
+   * the process still hasn't exited. Bypasses any child cleanup.
+   */
+  kill(signal?: NodeJS.Signals | number): void
+}
+
+export interface SpawnPtyProcessArgs {
+  command: string
+  args: string[]
+  cwd: string
+  env: NodeJS.ProcessEnv
+  cols?: number
+  rows?: number
+  onOutput?: (chunk: string) => void
+}
+
+export async function spawnPtyProcess(opts: SpawnPtyProcessArgs): Promise<PtyProcess> {
+  if (typeof Bun.Terminal !== "function") {
+    throw new Error("Bun.Terminal not available — requires Bun 1.3.5+")
+  }
+
+  const cols = opts.cols ?? 120
+  const rows = opts.rows ?? 40
+
+  const terminal = new Bun.Terminal({
+    cols,
+    rows,
+    name: "xterm-256color",
+    data: (_t, data) => {
+      if (opts.onOutput) {
+        const chunk = Buffer.from(data).toString("utf8")
+        opts.onOutput(chunk)
+      }
+    },
+  })
+
+  const proc = Bun.spawn([opts.command, ...opts.args], {
+    cwd: opts.cwd,
+    env: opts.env,
+    terminal,
+  })
+
+  return {
+    pid: proc.pid,
+    async sendInput(data) { terminal.write(data) },
+    resize(newCols, newRows) { terminal.resize(newCols, newRows) },
+    exited: proc.exited,
+    close() {
+      try { terminal.close() } catch { /* swallow */ }
+      try { proc.kill("SIGTERM") } catch { /* swallow */ }
+    },
+    kill(signal) {
+      try { terminal.close() } catch { /* swallow */ }
+      try { proc.kill(signal ?? "SIGKILL") } catch { /* swallow */ }
+    },
+  }
+}

package/src/server/claude-pty/pty-process.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test"
+import { spawnPtyProcess } from "./pty-process.adapter"
+
+describe("spawnPtyProcess", () => {
+  test(
+    "spawns a child process and exits cleanly",
+    async () => {
+      if (process.platform === "win32") {
+        console.log("skip: PTY not supported on Windows")
+        return
+      }
+      if (typeof Bun.Terminal !== "function") {
+        console.log("skip: Bun.Terminal not available")
+        return
+      }
+      const handle = await spawnPtyProcess({
+        command: "/bin/sh",
+        args: ["-c", "echo hello"],
+        cwd: "/tmp",
+        env: process.env,
+        cols: 80,
+        rows: 24,
+      })
+      const exitCode = await handle.exited
+      expect(exitCode).toBe(0)
+      handle.close()
+    },
+    30_000,
+  )
+
+  test(
+    "captures output via onOutput callback",
+    async () => {
+      if (process.platform === "win32" || typeof Bun.Terminal !== "function") return
+      const chunks: string[] = []
+      const handle = await spawnPtyProcess({
+        command: "/bin/sh",
+        args: ["-c", "echo hi"],
+        cwd: "/tmp",
+        env: process.env,
+        onOutput: (chunk) => chunks.push(chunk),
+      })
+      await handle.exited
+      handle.close()
+      expect(chunks.join("")).toContain("hi")
+    },
+    30_000,
+  )
+})