@opencode-cockpit/daemon 0.1.0

package/src/modules/shell/ids.ts

@@ -0,0 +1,8 @@
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz234567"
+
+export function newShellId(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(8))
+  let id = "sh_"
+  for (const byte of bytes) id += ALPHABET[byte % 32]
+  return id
+}

package/src/modules/shell/module.ts

@@ -0,0 +1,323 @@
+import type { ShellInfo, StartParams } from "@opencode-cockpit/protocol/shell"
+import { invalidParams, invalidState, notFound } from "../../core/errors.ts"
+import type { Logger } from "../../core/logger.ts"
+import { silentLogger } from "../../core/logger.ts"
+import type { MethodTable, Module, ModuleContext, Peer } from "../../core/module.ts"
+import { newShellId } from "./ids.ts"
+import { bunPtyBackend, type PtyBackend } from "./pty.ts"
+import { ProcessRegistry } from "./registry.ts"
+import { Shell, type ShellLimits } from "./shell.ts"
+import { waitFor } from "./wait.ts"
+
+export interface ShellModuleOptions {
+  backend?: PtyBackend
+  limits?: Partial<ShellLimits>
+  /** Oldest finished shells are forgotten beyond this many. */
+  maxFinished?: number
+  /** Base environment for spawned processes (defaults to the daemon's). */
+  baseEnv?: Record<string, string | undefined>
+  /** Coalesce output events per attached peer for this long. */
+  outputFlushMs?: number
+  /** Where to record owned process groups so a restarted daemon can reap orphans. */
+  registryFile?: string
+}
+
+const DEFAULT_LIMITS: ShellLimits = { logChars: 4_000_000, rawBytes: 1_000_000, scrollback: 2000 }
+
+export class ShellModule implements Module<"shell"> {
+  readonly name = "shell" as const
+  private readonly shells = new Map<string, Shell>()
+  private readonly attachments = new Map<string, () => void>() // `${peer.id}:${shellId}` → detach
+  private readonly backend: PtyBackend
+  private readonly limits: ShellLimits
+  private log: Logger = silentLogger
+  private registry: ProcessRegistry | undefined
+  private emit: ModuleContext["emit"] = () => {}
+
+  constructor(private readonly options: ShellModuleOptions = {}) {
+    this.backend = options.backend ?? bunPtyBackend
+    this.limits = { ...DEFAULT_LIMITS, ...options.limits }
+  }
+
+  async start(ctx: ModuleContext): Promise<void> {
+    this.log = ctx.log
+    this.emit = ctx.emit
+    if (this.options.registryFile) {
+      this.registry = new ProcessRegistry(this.options.registryFile, ctx.log)
+      const reaped = this.registry.reap()
+      if (reaped > 0) ctx.log.warn("cleaned up shells left by a previous daemon", { reaped })
+    }
+  }
+
+  async stop(): Promise<void> {
+    await Promise.all([...this.shells.values()].map((s) => s.stop("SIGTERM", 2000).catch(() => {})))
+    for (const detach of this.attachments.values()) detach()
+    for (const shell of this.shells.values()) shell.dispose()
+    this.attachments.clear()
+    this.shells.clear()
+  }
+
+  busy(): boolean {
+    for (const shell of this.shells.values()) if (shell.running) return true
+    return false
+  }
+
+  readonly methods: MethodTable<"shell"> = {
+    start: (params) => this.startShell(params),
+
+    list: (params) => {
+      const owner = params.owner
+      return [...this.shells.values()]
+        .filter((s) => params.includeExited || s.running)
+        .filter((s) => !owner?.project || s.spec.owner.project === owner.project)
+        .filter((s) => !owner?.session || s.spec.owner.session === owner.session)
+        .map((s) => s.info())
+    },
+
+    get: ({ id }) => this.require(id).info(),
+
+    read: ({ id, after, tail, limit, grep, ignoreCase }) => {
+      const shell = this.require(id)
+      const page = shell.log.read({
+        after,
+        tail,
+        limit,
+        grep: grep === undefined ? undefined : compilePattern(grep, ignoreCase),
+      })
+      return { ...page, status: shell.status }
+    },
+
+    screen: ({ id }) => this.require(id).snapshot(),
+
+    write: ({ id, data }) => {
+      const shell = this.require(id)
+      if (!shell.running) throw invalidState(`shell ${id} is ${shell.status}`)
+      return { bytes: shell.write(data) }
+    },
+
+    resize: ({ id, cols, rows }) => {
+      this.require(id).resize(cols, rows)
+      return {}
+    },
+
+    wait: async (params) => {
+      const shell = this.require(params.id)
+      const outcome = await waitFor(shell, params, compilePattern)
+      return { ...outcome, info: shell.info() }
+    },
+
+    stop: async ({ id, signal, graceMs }) => {
+      const shell = this.require(id)
+      await shell.stop(signal, graceMs)
+      await shell.exited
+      return shell.info()
+    },
+
+    restart: async ({ id }) => {
+      const shell = this.require(id)
+      if (shell.running) {
+        await shell.stop("SIGTERM", 3000)
+        await shell.exited
+      }
+      this.spawn(shell)
+      return shell.info()
+    },
+
+    remove: async ({ id }) => {
+      const shell = this.require(id)
+      if (shell.running) {
+        await shell.stop("SIGTERM", 3000)
+        await shell.exited
+      }
+      this.forget(shell)
+      return {}
+    },
+
+    attach: ({ id, fromOffset }, { peer }) => {
+      const shell = this.require(id)
+      this.detach(peer, id)
+      const replay = shell.raw.since(fromOffset ?? 0)
+      this.attachStream(peer, shell)
+      return { offset: replay.offset, replay: Buffer.from(replay.bytes).toString("base64") }
+    },
+
+    clear: ({ owner, finishedBeforeMs }) => {
+      const cutoff = Date.now() - (finishedBeforeMs ?? 0)
+      const removed: string[] = []
+      for (const shell of [...this.shells.values()]) {
+        if (shell.running) continue
+        const info = shell.info()
+        if (owner?.project && info.owner.project !== owner.project) continue
+        if (owner?.session && info.owner.session !== owner.session) continue
+        if ((info.endedAt ?? 0) > cutoff) continue
+        this.forget(shell)
+        removed.push(info.id)
+      }
+      return { removed }
+    },
+
+    detach: ({ id }, { peer }) => {
+      this.detach(peer, id)
+      return {}
+    },
+  }
+
+  private startShell(params: StartParams): ShellInfo {
+    if (params.reuse) {
+      const previous = this.findReusable(params)
+      if (previous) {
+        Object.assign(previous.spec, {
+          env: this.environment(params.env),
+          title: params.title ?? previous.spec.title,
+          timeoutMs: params.timeoutMs,
+          owner: params.owner,
+        })
+        this.spawn(previous)
+        return previous.info()
+      }
+    }
+    const shell = new Shell(
+      {
+        id: this.uniqueId(),
+        command: params.command,
+        args: params.args,
+        cwd: params.cwd,
+        env: this.environment(params.env),
+        title: params.title ?? [params.command, ...params.args].join(" ").slice(0, 200),
+        cols: params.cols,
+        rows: params.rows,
+        owner: params.owner,
+        timeoutMs: params.timeoutMs,
+      },
+      this.backend,
+      this.limits,
+    )
+    this.shells.set(shell.id, shell)
+    shell.subscribe({ exit: (info) => this.onExit(info) })
+    this.spawn(shell)
+    this.pruneFinished()
+    return shell.info()
+  }
+
+  private findReusable(params: StartParams): Shell | undefined {
+    const args = JSON.stringify(params.args)
+    let match: Shell | undefined
+    for (const shell of this.shells.values()) {
+      const spec = shell.spec
+      if (
+        !shell.running &&
+        spec.command === params.command &&
+        JSON.stringify(spec.args) === args &&
+        spec.cwd === params.cwd &&
+        spec.owner.project === params.owner.project &&
+        spec.owner.session === params.owner.session &&
+        (!match || shell.info().startedAt > match.info().startedAt)
+      ) {
+        match = shell
+      }
+    }
+    return match
+  }
+
+  private spawn(shell: Shell): void {
+    try {
+      shell.start()
+    } catch (err) {
+      const info = shell.info()
+      this.log.warn("spawn failed", { id: shell.id, command: shell.spec.command, err: String(err) })
+      this.emit("shell.exited", info)
+      return
+    }
+    const pid = shell.info().pid
+    if (pid) this.registry?.add(shell.id, pid, shell.spec.command)
+    this.log.info("shell started", { id: shell.id, command: shell.spec.command, pid })
+    this.emit("shell.started", shell.info())
+  }
+
+  private onExit(info: ShellInfo): void {
+    this.registry?.remove(info.id)
+    this.log.info("shell ended", {
+      id: info.id,
+      status: info.status,
+      exitCode: info.exitCode,
+      signal: info.signal,
+    })
+    this.emit("shell.exited", info)
+  }
+
+  private attachStream(peer: Peer, shell: Shell): void {
+    const key = `${peer.id}:${shell.id}`
+    const flushMs = this.options.outputFlushMs ?? 16
+    let pending: Uint8Array[] = []
+    let pendingOffset = 0
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const flush = () => {
+      timer = undefined
+      if (pending.length === 0) return
+      const data = Buffer.concat(pending).toString("base64")
+      peer.send("shell.output", { id: shell.id, offset: pendingOffset, data })
+      pending = []
+    }
+    const unsubscribe = shell.subscribe({
+      data(offset, chunk) {
+        if (pending.length === 0) pendingOffset = offset
+        pending.push(chunk)
+        timer ??= setTimeout(flush, flushMs)
+      },
+    })
+    const detach = () => {
+      clearTimeout(timer)
+      flush()
+      unsubscribe()
+      this.attachments.delete(key)
+    }
+    this.attachments.set(key, detach)
+    peer.onClose(detach)
+  }
+
+  private detach(peer: Peer, id: string): void {
+    this.attachments.get(`${peer.id}:${id}`)?.()
+  }
+
+  private forget(shell: Shell): void {
+    for (const [key, detach] of this.attachments) if (key.endsWith(`:${shell.id}`)) detach()
+    shell.dispose()
+    this.shells.delete(shell.id)
+    this.emit("shell.removed", { id: shell.id })
+  }
+
+  private pruneFinished(): void {
+    const max = this.options.maxFinished ?? 50
+    const finished = [...this.shells.values()].filter((s) => !s.running)
+    for (const shell of finished.slice(0, Math.max(0, finished.length - max))) this.forget(shell)
+  }
+
+  private require(id: string): Shell {
+    const shell = this.shells.get(id)
+    if (!shell) throw notFound(`shell ${id}`)
+    return shell
+  }
+
+  private uniqueId(): string {
+    let id = newShellId()
+    while (this.shells.has(id)) id = newShellId()
+    return id
+  }
+
+  private environment(extra: Record<string, string> | undefined): Record<string, string> {
+    const env: Record<string, string> = {}
+    for (const [k, v] of Object.entries(this.options.baseEnv ?? process.env)) if (v !== undefined) env[k] = v
+    env.TERM ??= "xterm-256color"
+    env.COLORTERM ??= "truecolor"
+    Object.assign(env, extra)
+    return env
+  }
+}
+
+export function compilePattern(pattern: string, ignoreCase: boolean): RegExp {
+  try {
+    return new RegExp(pattern, ignoreCase ? "i" : "")
+  } catch (err) {
+    throw invalidParams(`invalid pattern: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}

package/src/modules/shell/output/line-log.ts

@@ -0,0 +1,92 @@
+import type { LogLine } from "@opencode-cockpit/protocol/shell"
+
+export interface ReadQuery {
+  after?: number
+  tail: number
+  limit: number
+  grep?: RegExp
+}
+
+export interface ReadPage {
+  lines: LogLine[]
+  firstLine: number
+  lastLine: number
+  nextCursor: number
+  truncated: boolean
+  hasMore: boolean
+}
+
+/**
+ * Committed lines with monotonic numbering (1-based) and a character budget.
+ * Eviction drops the oldest lines and advances `firstLine`; numbers are never reused, so cursors
+ * held by clients stay meaningful after eviction.
+ */
+export class LineLog {
+  private lines: string[] = []
+  private head = 0
+  private chars = 0
+  private first = 1
+
+  constructor(private readonly maxChars = 4_000_000) {}
+
+  /** Number of the oldest retained line (equals `lastLine + 1` when empty). */
+  get firstLine(): number {
+    return this.first
+  }
+
+  /** Number of the newest line, or `firstLine - 1` when empty. */
+  get lastLine(): number {
+    return this.first + (this.lines.length - this.head) - 1
+  }
+
+  append(text: string): LogLine {
+    this.lines.push(text)
+    this.chars += text.length + 1
+    const line = { n: this.lastLine, text }
+    this.evict()
+    return line
+  }
+
+  get(n: number): string | undefined {
+    if (n < this.first || n > this.lastLine) return undefined
+    return this.lines[this.head + (n - this.first)]
+  }
+
+  read(query: ReadQuery): ReadPage {
+    const last = this.lastLine
+    const requestedStart = query.after !== undefined ? query.after + 1 : Math.max(1, last - query.tail + 1)
+    const start = Math.max(requestedStart, this.first)
+    const truncated = requestedStart < this.first && last >= requestedStart
+
+    const out: LogLine[] = []
+    let n = start
+    for (; n <= last && out.length < query.limit; n++) {
+      const text = this.lines[this.head + (n - this.first)] as string
+      if (query.grep && !query.grep.test(text)) continue
+      out.push({ n, text })
+    }
+    const scannedTo = n - 1
+    return {
+      lines: out,
+      firstLine: this.first,
+      lastLine: last,
+      nextCursor: Math.max(scannedTo, start - 1),
+      truncated,
+      hasMore: scannedTo < last,
+    }
+  }
+
+  private evict(): void {
+    while (this.chars > this.maxChars && this.head < this.lines.length - 1) {
+      const dropped = this.lines[this.head] as string
+      this.chars -= dropped.length + 1
+      this.head++
+      this.first++
+    }
+    // Compact occasionally so the backing array does not grow without bound.
+    if (this.head > 4096 && this.head * 2 > this.lines.length) {
+      this.lines = this.lines.slice(this.head)
+      this.head = 0
+    }
+  }
+}

package/src/modules/shell/output/normalizer.ts

@@ -0,0 +1,172 @@
+/**
+ * Streaming terminal-output normalizer (ADR 0003).
+ *
+ * Turns a PTY byte stream into committed plain-text lines, applying the parts of terminal
+ * semantics that matter for a single line: carriage return and backspace overwrite, tabs, erase
+ * in line, and horizontal cursor moves. Escape sequences are consumed and dropped. Anything that
+ * moves between lines (cursor up, scroll regions) is out of scope; the screen view handles those.
+ */
+
+const ESC = 0x1b
+const BEL = 0x07
+const TAB_WIDTH = 8
+
+enum State {
+  Ground,
+  Escape,
+  EscapeIntermediate,
+  Csi,
+  Osc,
+  OscEscape,
+}
+
+export interface NormalizerOptions {
+  /** Force a commit when a line grows past this many characters. */
+  maxLineLength?: number
+}
+
+export class OutputNormalizer {
+  private readonly decoder = new TextDecoder()
+  private readonly maxLineLength: number
+  private state = State.Ground
+  private csiParams = ""
+  private cells: string[] = []
+  private col = 0
+
+  constructor(
+    private readonly commit: (text: string) => void,
+    options: NormalizerOptions = {},
+  ) {
+    this.maxLineLength = options.maxLineLength ?? 10_000
+  }
+
+  /** Text of the line currently being written (not yet terminated by a newline). */
+  get partial(): string {
+    return this.render()
+  }
+
+  push(chunk: Uint8Array | string): void {
+    const text = typeof chunk === "string" ? chunk : this.decoder.decode(chunk, { stream: true })
+    for (const char of text) this.step(char)
+  }
+
+  /** Commit the partial line, if any. Call when the stream ends. */
+  flush(): void {
+    const tail = this.render()
+    if (tail.length > 0) this.commit(tail)
+    this.cells = []
+    this.col = 0
+  }
+
+  private step(char: string): void {
+    const code = char.codePointAt(0) ?? 0
+    switch (this.state) {
+      case State.Ground:
+        this.ground(char, code)
+        return
+      case State.Escape:
+        if (code === 0x5b) {
+          this.state = State.Csi
+          this.csiParams = ""
+        } else if (code === 0x5d) {
+          this.state = State.Osc
+        } else if (code >= 0x20 && code <= 0x2f) {
+          this.state = State.EscapeIntermediate
+        } else {
+          this.state = State.Ground
+        }
+        return
+      case State.EscapeIntermediate:
+        if (code >= 0x30 && code <= 0x7e) this.state = State.Ground
+        return
+      case State.Csi:
+        if (code >= 0x40 && code <= 0x7e) {
+          this.csi(char, this.csiParams)
+          this.state = State.Ground
+        } else {
+          this.csiParams += char
+        }
+        return
+      case State.Osc:
+        if (code === BEL) this.state = State.Ground
+        else if (code === ESC) this.state = State.OscEscape
+        return
+      case State.OscEscape:
+        this.state = code === 0x5c ? State.Ground : State.Osc
+        return
+    }
+  }
+
+  private ground(char: string, code: number): void {
+    if (code === ESC) {
+      this.state = State.Escape
+      return
+    }
+    if (char === "\n") {
+      this.commit(this.render())
+      this.cells = []
+      this.col = 0
+      return
+    }
+    if (char === "\r") {
+      this.col = 0
+      return
+    }
+    if (char === "\b") {
+      this.col = Math.max(0, this.col - 1)
+      return
+    }
+    if (char === "\t") {
+      const next = (Math.floor(this.col / TAB_WIDTH) + 1) * TAB_WIDTH
+      while (this.col < next) this.put(" ")
+      return
+    }
+    if (code < 0x20 || code === 0x7f) return
+    this.put(char)
+  }
+
+  private csi(final: string, raw: string): void {
+    const params = raw.replace(/^[?>=!]/, "")
+    const first = Number.parseInt(params.split(";")[0] ?? "", 10)
+    const n = Number.isNaN(first) ? undefined : first
+    switch (final) {
+      case "K": // erase in line
+        if (n === undefined || n === 0) this.cells.length = Math.min(this.cells.length, this.col)
+        else if (n === 1) for (let i = 0; i <= this.col && i < this.cells.length; i++) this.cells[i] = " "
+        else if (n === 2) this.cells = []
+        return
+      case "G": // cursor horizontal absolute (1-based)
+        this.col = Math.max(0, (n ?? 1) - 1)
+        return
+      case "C": // cursor forward
+        this.col += Math.max(1, n ?? 1)
+        return
+      case "D": // cursor back
+        this.col = Math.max(0, this.col - Math.max(1, n ?? 1))
+        return
+      case "J": // erase display: the current line is all this view can clear
+        if (n === 2 || n === 3) {
+          this.cells = []
+          this.col = 0
+        }
+        return
+      default:
+        return // colours (m) and everything else carry no line text
+    }
+  }
+
+  private put(char: string): void {
+    while (this.cells.length < this.col) this.cells.push(" ")
+    this.cells[this.col] = char
+    this.col++
+    if (this.cells.length >= this.maxLineLength) {
+      this.commit(this.render())
+      this.cells = []
+      this.col = 0
+    }
+  }
+
+  private render(): string {
+    return this.cells.join("").trimEnd()
+  }
+}

package/src/modules/shell/output/raw-ring.ts

@@ -0,0 +1,46 @@
+/**
+ * Bounded store of raw PTY bytes addressed by absolute offset, for replaying output to UIs that
+ * attach after the fact. Evicts whole chunks from the front.
+ */
+export class RawRing {
+  private chunks: Uint8Array[] = []
+  private size = 0
+  private start = 0
+
+  constructor(private readonly maxBytes = 1_000_000) {}
+
+  /** Absolute offset one past the last byte ever written. */
+  get end(): number {
+    return this.start + this.size
+  }
+
+  append(chunk: Uint8Array): number {
+    const offset = this.end
+    this.chunks.push(chunk)
+    this.size += chunk.byteLength
+    while (this.size > this.maxBytes && this.chunks.length > 1) {
+      const dropped = this.chunks.shift() as Uint8Array
+      this.size -= dropped.byteLength
+      this.start += dropped.byteLength
+    }
+    return offset
+  }
+
+  /** Bytes from `offset` (clamped to what is retained) to the end. */
+  since(offset = 0): { offset: number; bytes: Uint8Array } {
+    const from = Math.max(offset, this.start)
+    const out = new Uint8Array(this.end - from)
+    let cursor = this.start
+    let written = 0
+    for (const chunk of this.chunks) {
+      const chunkEnd = cursor + chunk.byteLength
+      if (chunkEnd > from) {
+        const slice = chunk.subarray(Math.max(0, from - cursor))
+        out.set(slice, written)
+        written += slice.byteLength
+      }
+      cursor = chunkEnd
+    }
+    return { offset: from, bytes: out }
+  }
+}

package/src/modules/shell/output/screen.ts

@@ -0,0 +1,44 @@
+import type { ScreenResult } from "@opencode-cockpit/protocol/shell"
+import { Terminal } from "@xterm/headless"
+
+/** Full VT emulation of a shell's output: what a human would see right now (ADR 0003). */
+export class Screen {
+  private readonly term: Terminal
+
+  constructor(cols: number, rows: number, scrollback = 2000) {
+    this.term = new Terminal({ cols, rows, scrollback, allowProposedApi: true })
+  }
+
+  write(chunk: Uint8Array): void {
+    this.term.write(chunk)
+  }
+
+  resize(cols: number, rows: number): void {
+    this.term.resize(cols, rows)
+  }
+
+  reset(): void {
+    this.term.reset()
+  }
+
+  /** Waits until every pending write has been parsed, then renders the viewport. */
+  async snapshot(): Promise<ScreenResult> {
+    await new Promise<void>((resolve) => this.term.write("", resolve))
+    const buffer = this.term.buffer.active
+    const rows: string[] = []
+    for (let y = 0; y < this.term.rows; y++) {
+      rows.push(buffer.getLine(buffer.baseY + y)?.translateToString(true) ?? "")
+    }
+    while (rows.length > 0 && rows[rows.length - 1] === "") rows.pop()
+    return {
+      text: rows.join("\n"),
+      cols: this.term.cols,
+      rows: this.term.rows,
+      cursor: { x: buffer.cursorX, y: buffer.cursorY },
+    }
+  }
+
+  dispose(): void {
+    this.term.dispose()
+  }
+}