@sma1lboy/rove 0.8.89

package/dist/web-ui/pty-server.mjs

@@ -0,0 +1,212 @@
+/**
+ * PTY server — the node half of the web terminal (node-pty doesn't work under
+ * bun, so the live terminals run here as a separate node process).
+ *
+ * Model: each web PTY tab is identified by a client-generated `tab` id. Its
+ * PTY is spawned lazily on first attach (launch spec fetched from daemon web
+ * transport by taskId + mode) and kept alive across WebSocket reconnects, so a
+ * page refresh re-attaches to the same process. Closing a tab (POST
+ * /pty/close) kills its PTY.
+ *
+ *   ws  /pty?tab=<id>&taskId=<id>&mode=engine|shell&cols=<n>&rows=<n>
+ *   POST /pty/close   { tab }                          kill the tab process
+ *   POST /pty/send    { tab, taskId, text }            paste text + Enter into the tab's engine
+ */
+
+import { createServer } from "node:http"
+import { spawn } from "node-pty"
+import { WebSocketServer } from "ws"
+import { allowedHostForBindHost, originAllowed } from "./origin-policy.mjs"
+import { ptyEnv } from "./pty-env.mjs"
+import { createScrollback } from "./pty-scrollback.mjs"
+import { createPtySessionManager } from "./pty-session-lifecycle.mjs"
+
+const PORT = Number.parseInt(process.env.KOBE_PTY_PORT ?? "5175", 10)
+const DAEMON_WEB_PORT = Number.parseInt(process.env.KOBE_DAEMON_WEB_PORT ?? "45174", 10)
+const SCROLLBACK_CAP = 256 * 1024 // bytes of recent output replayed on (re)attach
+const HEALTH_PATH = "/__kobe_web"
+const HEALTH_MARKER = "kobe-web"
+const HOST = process.env.KOBE_WEB_HOST?.trim() || "127.0.0.1"
+const ALLOWED_HOST = allowedHostForBindHost(HOST)
+
+async function fetchSpec(taskId, mode) {
+  // e2e/dev harness override: run an arbitrary TUI (dev:mock / dev:sandbox) in
+  // the PTY instead of resolving a task's engine via the daemon — so a Playwright
+  // test can drive the real TUI through the web terminal with no daemon or task.
+  if (process.env.KOBE_PTY_DEV_COMMAND) {
+    return {
+      cwd: process.env.KOBE_PTY_DEV_CWD ?? process.cwd(),
+      command: ["/bin/sh", "-lc", process.env.KOBE_PTY_DEV_COMMAND],
+    }
+  }
+  const path = mode === "shell" ? "/api/terminal-spec" : "/api/engine-spec"
+  const res = await fetch(`http://localhost:${DAEMON_WEB_PORT}${path}?taskId=${encodeURIComponent(taskId)}`)
+  const json = await res.json()
+  if (!res.ok || json.error) throw new Error(json.error ?? `engine-spec failed (${res.status})`)
+  return json // { cwd, command: string[] }
+}
+
+const ptySessions = createPtySessionManager({
+  fetchSpec,
+  spawnPty: spawn,
+  createScrollback,
+  scrollbackCap: SCROLLBACK_CAP,
+  env: ptyEnv,
+})
+
+const server = createServer((req, res) => {
+  const url = new URL(req.url ?? "/", "http://localhost")
+  if (url.pathname === HEALTH_PATH) {
+    res.writeHead(200, { "content-type": "text/plain" })
+    res.end(HEALTH_MARKER)
+    return
+  }
+  if (req.method === "OPTIONS") {
+    res.writeHead(204, {
+      "access-control-allow-origin": "*",
+      "access-control-allow-methods": "POST, OPTIONS",
+      "access-control-allow-headers": "content-type",
+    })
+    res.end()
+    return
+  }
+  if (req.method === "POST" && url.pathname === "/pty/send") {
+    // Sending text DRIVES the engine like a keyboard, so unlike /pty/close
+    // (best-effort kill) this holds the same origin policy as the WS attach:
+    // localhost pages or non-browser clients only.
+    if (!originAllowed(req.headers.origin, { allowedHost: ALLOWED_HOST })) {
+      res.writeHead(403)
+      res.end()
+      return
+    }
+    let body = ""
+    req.on("data", (c) => {
+      body += c
+    })
+    req.on("end", async () => {
+      let tab
+      let taskId
+      let text
+      try {
+        ;({ tab, taskId, text } = JSON.parse(body || "{}"))
+      } catch {
+        /* ignore */
+      }
+      const respond = (status, payload) => {
+        res.writeHead(status, {
+          "content-type": "application/json",
+          "access-control-allow-origin": "*",
+        })
+        res.end(JSON.stringify(payload))
+      }
+      if (typeof tab !== "string" || !tab || typeof text !== "string" || !text) {
+        respond(400, { sent: false, error: "tab and text are required" })
+        return
+      }
+      let result
+      try {
+        // Spawn-on-send: a board action can fire without the terminal ever
+        // opening — output lands in the scrollback ring for the next attach.
+        result = await ptySessions.sendText({
+          tabId: tab,
+          taskId: typeof taskId === "string" && taskId ? taskId : null,
+          text,
+        })
+      } catch (err) {
+        respond(500, { sent: false, error: `failed to start engine: ${err?.message ?? err}` })
+        return
+      }
+      if (!result.sent) {
+        respond(404, { sent: false, error: "no such tab" })
+        return
+      }
+      respond(200, { sent: true, spawned: result.spawned })
+    })
+    return
+  }
+  if (req.method === "POST" && url.pathname === "/pty/close") {
+    // Killing a tab is a side effect a cross-origin local page could abuse to
+    // DoS the session (tab ids are client-generated/observable), so hold the
+    // same origin policy as /pty/send and the WS attach: localhost pages or
+    // non-browser clients (no Origin) only.
+    if (!originAllowed(req.headers.origin, { allowedHost: ALLOWED_HOST })) {
+      res.writeHead(403)
+      res.end()
+      return
+    }
+    let body = ""
+    req.on("data", (c) => {
+      body += c
+    })
+    req.on("end", () => {
+      let tab
+      try {
+        tab = JSON.parse(body || "{}").tab
+      } catch {
+        /* ignore */
+      }
+      const ok = tab ? ptySessions.closeSession(tab) : false
+      res.writeHead(200, {
+        "content-type": "application/json",
+        "access-control-allow-origin": "*",
+      })
+      res.end(JSON.stringify({ closed: ok }))
+    })
+    return
+  }
+  res.writeHead(404)
+  res.end()
+})
+
+// A PTY WS is arbitrary command exec in the worktree, so reject cross-origin
+// upgrades: a browser sends an Origin header, and only loopback pages (or the
+// deliberately configured LAN host) may attach. This defends a malicious local
+// page / DNS-rebinding even on the loopback bind. Non-browser clients (no
+// Origin) are allowed — there's no browser to forge their request.
+const wss = new WebSocketServer({
+  server,
+  path: "/pty",
+  verifyClient: ({ origin }) => originAllowed(origin, { allowedHost: ALLOWED_HOST }),
+})
+
+wss.on("connection", (ws, req) => {
+  const url = new URL(req.url ?? "/", "http://localhost")
+  const tabId = url.searchParams.get("tab")
+  const taskId = url.searchParams.get("taskId")
+  const cols = Number.parseInt(url.searchParams.get("cols") ?? "80", 10) || 80
+  const rows = Number.parseInt(url.searchParams.get("rows") ?? "24", 10) || 24
+  const mode = url.searchParams.get("mode") === "shell" ? "shell" : "engine"
+
+  if (!tabId || !taskId) {
+    ws.close(1008, "missing tab/taskId")
+    return
+  }
+
+  void (async () => {
+    try {
+      // Single-flight spawn: concurrent attaches for this tab share one PTY.
+      await ptySessions.attachSocket({ ws, tabId, taskId, mode, cols, rows })
+    } catch (err) {
+      if (ws.readyState === ws.OPEN) {
+        ws.send(`\r\nfailed to start ${mode}: ${err?.message ?? err}\r\n`)
+        ws.close(1011, "spawn failed")
+      }
+      return
+    }
+  })()
+})
+
+// Bind loopback by default — a PTY is an arbitrary shell/engine in the
+// worktree, so it must never listen on all interfaces. KOBE_WEB_HOST overrides.
+server.listen(PORT, HOST, () => {
+  process.stdout.write(`kobe pty-server listening on ${HOST}:${PORT} (daemon-web :${DAEMON_WEB_PORT})\n`)
+})
+
+const shutdown = () => {
+  ptySessions.shutdown()
+  wss.close()
+  server.close()
+  process.exit(0)
+}
+process.on("SIGINT", shutdown)
+process.on("SIGTERM", shutdown)

package/dist/web-ui/pty-session-lifecycle.mjs

@@ -0,0 +1,282 @@
+/**
+ * PTY session lifecycle manager for the web sidecar.
+ *
+ * The HTTP/WebSocket server is transport glue; this module owns the deeper
+ * lifecycle state for tab-keyed PTY sessions: single-flight spawn, attach,
+ * scrollback replay, resize/input, close, process-exit cleanup, and shutdown.
+ */
+
+const DEFAULT_SUBMIT_DELAYS = {
+  spawnedPasteMs: 2500,
+  existingPasteMs: 0,
+  enterMs: 150,
+}
+
+// A browser opening /pty?tab=<id> with ever-new tab ids would otherwise spawn
+// node-pty processes without bound. Cap concurrent sessions; spawning past the
+// cap evicts the oldest session with no attached sockets, and rejects when every
+// session is being actively viewed.
+const DEFAULT_MAX_SESSIONS = 64
+
+// PTY→WebSocket backpressure: a flooding pty (`yes`) outruns a slow browser, so
+// node buffers the unsent bytes (ws.bufferedAmount) without bound. Pause the pty
+// once any socket's buffer crosses the high-water mark and resume once every
+// socket has drained back under the low-water mark.
+const DEFAULT_BACKPRESSURE = {
+  highWaterBytes: 1 << 20, // 1 MiB queued to a socket → pause the pty
+  lowWaterBytes: 1 << 18, // 256 KiB → resume once all sockets are back under
+  drainPollMs: 50,
+}
+
+/** First session (insertion order) with no attached sockets — the safest to
+ *  evict under cap pressure since no browser is watching it. Returns null when
+ *  every session is actively viewed (caller rejects the new spawn). Exported
+ *  for tests. */
+export function pickEvictableTab(sessions) {
+  for (const [tabId, entry] of sessions) {
+    if (entry.sockets.size === 0) return tabId
+  }
+  return null
+}
+
+/** Pause the pty when ANY open socket has more than `highWaterBytes` queued —
+ *  one slow client is enough to grow node memory unbounded. Exported for tests. */
+export function shouldPausePty(sockets, highWaterBytes) {
+  for (const ws of sockets) {
+    if (ws.readyState === ws.OPEN && ws.bufferedAmount > highWaterBytes) {
+      return true
+    }
+  }
+  return false
+}
+
+/** Resume only when EVERY open socket has drained back under `lowWaterBytes`
+ *  (an empty socket set resumes immediately). Exported for tests. */
+export function shouldResumePty(sockets, lowWaterBytes) {
+  for (const ws of sockets) {
+    if (ws.readyState === ws.OPEN && ws.bufferedAmount > lowWaterBytes) {
+      return false
+    }
+  }
+  return true
+}
+
+export function createPtySessionManager({
+  fetchSpec,
+  spawnPty,
+  createScrollback,
+  scrollbackCap,
+  env,
+  setTimeoutFn = setTimeout,
+  setIntervalFn = setInterval,
+  clearIntervalFn = clearInterval,
+  submitDelays = DEFAULT_SUBMIT_DELAYS,
+  maxSessions = DEFAULT_MAX_SESSIONS,
+  backpressure = DEFAULT_BACKPRESSURE,
+}) {
+  /** @type {Map<string, { pty: any, scrollback: ReturnType<createScrollback>, sockets: Set<any> }>} */
+  const sessions = new Map()
+  /** @type {Map<string, Promise<any>>} */
+  const pendingSpawns = new Map()
+
+  /** Pause the pty once a socket is saturated and poll for drain to resume.
+   *  Idempotent: a second saturation while already paused is a no-op. */
+  function applyBackpressure(entry) {
+    if (entry.paused) return
+    if (!shouldPausePty(entry.sockets, backpressure.highWaterBytes)) return
+    entry.paused = true
+    try {
+      entry.pty.pause?.()
+    } catch {
+      /* engine died — onExit clears the entry */
+    }
+    if (entry.drainTimer !== null) return
+    entry.drainTimer = setIntervalFn(() => {
+      if (!shouldResumePty(entry.sockets, backpressure.lowWaterBytes)) return
+      clearDrainTimer(entry)
+      entry.paused = false
+      try {
+        entry.pty.resume?.()
+      } catch {
+        /* engine died — onExit clears the entry */
+      }
+    }, backpressure.drainPollMs)
+  }
+
+  function clearDrainTimer(entry) {
+    if (entry.drainTimer !== null) {
+      clearIntervalFn(entry.drainTimer)
+      entry.drainTimer = null
+    }
+  }
+
+  function spawnSession(tabId, spec, cols, rows) {
+    // Enforce the session cap before allocating another process: evict the
+    // oldest unwatched session, or reject when every session is in active use.
+    if (sessions.size >= maxSessions && !sessions.has(tabId)) {
+      const victim = pickEvictableTab(sessions)
+      if (victim === null) {
+        throw new Error(`pty session limit reached (${maxSessions})`)
+      }
+      closeSession(victim)
+    }
+    const [cmd, ...args] = spec.command
+    const spawnEnv = typeof env === "function" ? env() : env
+    let pty
+    try {
+      pty = spawnPty(cmd, args, {
+        name: "xterm-256color",
+        cols,
+        rows,
+        cwd: spec.cwd,
+        env: spawnEnv,
+      })
+    } catch (error) {
+      const path = typeof spawnEnv.PATH === "string" && spawnEnv.PATH ? "set" : "missing"
+      throw new Error(`PTY spawn failed (command ${cmd}, cwd ${spec.cwd}, PATH ${path}): ${error instanceof Error ? error.message : String(error)}`)
+    }
+    const entry = {
+      pty,
+      scrollback: createScrollback(scrollbackCap),
+      sockets: new Set(),
+      paused: false,
+      drainTimer: null,
+    }
+    pty.onData((data) => {
+      entry.scrollback.push(data)
+      for (const ws of entry.sockets) {
+        if (ws.readyState === ws.OPEN) ws.send(data)
+      }
+      applyBackpressure(entry)
+    })
+    pty.onExit(() => {
+      clearDrainTimer(entry)
+      for (const ws of entry.sockets) {
+        if (ws.readyState === ws.OPEN) ws.close(1000, "engine exited")
+      }
+      if (sessions.get(tabId) === entry) sessions.delete(tabId)
+    })
+    sessions.set(tabId, entry)
+    return entry
+  }
+
+  async function ensureSession(tabId, taskId, mode, cols, rows) {
+    const existing = sessions.get(tabId)
+    if (existing) return existing
+    const inflight = pendingSpawns.get(tabId)
+    if (inflight) return inflight
+    const p = (async () => {
+      const spec = await fetchSpec(taskId, mode)
+      return sessions.get(tabId) ?? spawnSession(tabId, spec, cols, rows)
+    })()
+    pendingSpawns.set(tabId, p)
+    try {
+      return await p
+    } finally {
+      pendingSpawns.delete(tabId)
+    }
+  }
+
+  function safePty(tabId, entry, fn) {
+    if (sessions.get(tabId) !== entry) return
+    try {
+      fn(entry.pty)
+    } catch {
+      /* engine died — its onExit closes sockets and clears the entry */
+    }
+  }
+
+  async function attachSocket({ ws, tabId, taskId, mode, cols, rows }) {
+    const entry = await ensureSession(tabId, taskId, mode, cols, rows)
+    const replay = entry.scrollback.length() > 0 ? entry.scrollback.replay() : ""
+    entry.sockets.add(ws)
+    if (replay && ws.readyState === ws.OPEN) ws.send(replay)
+    safePty(tabId, entry, (pty) => pty.resize(cols, rows))
+
+    ws.on("message", (raw) => {
+      const text = raw.toString()
+      if (text.startsWith("{")) {
+        try {
+          const msg = JSON.parse(text)
+          if (msg && msg.type === "resize" && Number.isFinite(msg.cols) && Number.isFinite(msg.rows)) {
+            safePty(tabId, entry, (pty) => pty.resize(Math.max(1, msg.cols | 0), Math.max(1, msg.rows | 0)))
+            return
+          }
+        } catch {
+          /* fall through to raw write */
+        }
+      }
+      safePty(tabId, entry, (pty) => pty.write(text))
+    })
+
+    ws.on("close", () => {
+      entry.sockets.delete(ws)
+    })
+
+    return entry
+  }
+
+  function closeSession(tabId) {
+    const entry = sessions.get(tabId)
+    if (!entry) return false
+    clearDrainTimer(entry)
+    try {
+      entry.pty.kill()
+    } catch {
+      /* already gone */
+    }
+    if (sessions.get(tabId) === entry) sessions.delete(tabId)
+    return true
+  }
+
+  async function sendText({ tabId, taskId, text }) {
+    let entry = sessions.get(tabId)
+    let spawned = false
+    if (!entry && taskId) {
+      entry = await ensureSession(tabId, taskId, "engine", 80, 24)
+      spawned = true
+    }
+    if (!entry) return { sent: false, spawned: false, missing: true }
+
+    const target = entry
+    const pasteDelay = spawned ? submitDelays.spawnedPasteMs : submitDelays.existingPasteMs
+    setTimeoutFn(() => {
+      try {
+        target.pty.write(`\x1b[200~${text}\x1b[201~`)
+      } catch {
+        return
+      }
+      setTimeoutFn(() => {
+        try {
+          target.pty.write("\r")
+        } catch {
+          /* best-effort */
+        }
+      }, submitDelays.enterMs)
+    }, pasteDelay)
+    return { sent: true, spawned }
+  }
+
+  function shutdown() {
+    for (const entry of sessions.values()) {
+      clearDrainTimer(entry)
+      try {
+        entry.pty.kill()
+      } catch {
+        /* ignore */
+      }
+    }
+    sessions.clear()
+    pendingSpawns.clear()
+  }
+
+  return {
+    attachSocket,
+    closeSession,
+    ensureSession,
+    sendText,
+    shutdown,
+    sessionCount: () => sessions.size,
+    pendingSpawnCount: () => pendingSpawns.size,
+  }
+}

package/dist/web-ui/robots.txt

@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:

package/package.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@sma1lboy/rove",
+  "version": "0.8.89",
+  "description": "Rove — the terminal-native agent multiplexer",
+  "type": "module",
+  "packageManager": "bun@1.3.13",
+  "bin": {
+    "kobe": "dist/cli/kobe.js",
+    "rove": "dist/cli/rove.js"
+  },
+  "files": [
+    "dist/cli",
+    "dist/web-ui",
+    "dist/skills",
+    "dist/*.wav",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sma1lboy/rove.git"
+  },
+  "homepage": "https://github.com/Sma1lboy/rove#readme",
+  "bugs": {
+    "url": "https://github.com/Sma1lboy/rove/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.11"
+  },
+  "scripts": {
+    "dev": "KOBE_DEV=1 bun --conditions=browser ./src/cli/kobe.ts",
+    "dev:rove": "ROVE_DEV=1 bun --conditions=browser ./src/cli/rove.ts",
+    "dev:mock": "KOBE_DEV=1 bun ./src/tui-react/mock/host.tsx",
+    "dev:mock-react": "KOBE_DEV=1 bun ./src/tui-react/mock/host.tsx",
+    "dev:mock-react-task-dialogs": "KOBE_DEV=1 bun ./src/tui-react/component/mock-dialogs-host.tsx",
+    "dev:mock-react-filetree": "KOBE_DEV=1 bun ./src/tui-react/panes/filetree/mock-host.tsx",
+    "dev:mock-react-sidebar": "KOBE_DEV=1 bun ./src/tui-react/panes/sidebar/mock-host.tsx",
+    "dev:mock-react-terminal": "KOBE_DEV=1 bun ./src/tui-react/panes/terminal/mock-host.tsx",
+    "dev:mock-react-dialogs": "KOBE_DEV=1 bun ./src/tui-react/mock/dialogs-host.tsx",
+    "dev:mock-react-workspace": "KOBE_DEV=1 bun ./src/tui-react/workspace/mock-host.tsx",
+    "dev:sandbox": "bun run scripts/dev-sandbox.ts run",
+    "dev:sandbox:reset": "bun run scripts/dev-sandbox.ts reset",
+    "build": "bun run scripts/build.ts",
+    "build:with-web": "bun run build",
+    "compile": "bun run scripts/compile.ts",
+    "typecheck": "tsc --noEmit",
+    "check-i18n": "bun run scripts/check-i18n.ts",
+    "test": "bun run test:fast && bun run test:socket",
+    "perf:golden": "bun scripts/perf-golden.ts",
+    "pty:soak": "bun scripts/pty-soak.ts",
+    "test:fast": "vitest run --passWithNoTests --minWorkers=1 --maxWorkers=8",
+    "test:socket": "KOBE_INCLUDE_SOCKET=1 vitest run test/daemon --pool forks --minWorkers=1 --maxWorkers=4 --passWithNoTests",
+    "test:socket:coverage": "KOBE_INCLUDE_SOCKET=1 KOBE_COVERAGE_DAEMON=1 vitest run test/daemon --coverage --pool forks --minWorkers=1 --maxWorkers=4 --passWithNoTests",
+    "test:behavior": "KOBE_INCLUDE_BEHAVIOR=1 vitest run test/behavior --pool forks --minWorkers=1 --maxWorkers=1 --retry=2 --passWithNoTests",
+    "test:render": "bun test test/render --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage-render",
+    "coverage": "vitest run --coverage --passWithNoTests",
+    "bench": "vitest bench --run",
+    "lint": "biome check .",
+    "knip": "knip-bun",
+    "postinstall": "bun run scripts/check-preview-deps.ts || true",
+    "prepublishOnly": "bun run typecheck && bun run build"
+  },
+  "//": "biome.json + bunfig.toml live at the monorepo root since they apply repo-wide; bun.lock also lives at root (workspace-shared).",
+  "dependencies": {
+    "@ansi-tools/parser": "^1.0.15",
+    "@opentui/core": "0.4.3",
+    "@opentui/react": "0.4.3",
+    "@xterm/addon-serialize": "^0.14.0",
+    "@xterm/addon-unicode11": "^0.9.0",
+    "@xterm/headless": "^6.0.0",
+    "node-pty": "^1.1.0",
+    "react": "^19.2.8",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@sma1lboy/kobe-daemon": "0.7.12",
+    "@tsconfig/bun": "1.0.10",
+    "@types/bun": "1.3.14",
+    "@types/node": "25.6.2",
+    "@types/react": "^19.2.0",
+    "@vitest/coverage-v8": "2.1.9",
+    "knip": "^6.14.2",
+    "kobe-web": "workspace:*",
+    "react-devtools-core": "^7.0.1",
+    "typescript": "5.8.2",
+    "vitest": "2.1.9"
+  },
+  "trustedDependencies": []
+}