@huynle/hub 0.6.0 → 0.7.1

package/packages/codex/src/spoke.ts

@@ -0,0 +1,249 @@
+// The Codex app-server spoke (P7-T7a; decision fx04e42c point 5 as corrected by spike v0hsdqhm): one HarnessSpoke
+// (harness "codex", evidence "rpc", announcing turnEvents: every turn's end is Codex's own turn/completed) over
+// CodexSessions and up to two app-server connections, each as one client among others:
+//
+// - "own": `codex app-server --listen stdio://`, started on the first create, for the threads the hub starts
+//   (thread/start). It is a child of the spoke: when the spoke stops, so do those threads.
+// - "daemon": the shared daemon's Unix socket (CODEX_HOME/app-server-control/app-server-control.sock, WebSocket
+//   framing), when present. The TUI and the desktop app keep their threads there; the spoke lists the loaded threads
+//   every pollMs (and on thread/started) and subscribes to each new one (thread/resume, excludeTurns). The spoke
+//   never starts the daemon: it connects when the socket answers and tries again every pollMs when it does not.
+//
+// Nothing here writes Codex's files (CODEX_HOME): configuration goes in as -c overrides (codexArgs) and environment.
+import { HarnessSpoke, type HarnessSpokeOptions } from "../../spoke-sdk/src/index.ts"
+import { openAppServer, type AppServerConnection } from "./app-server.ts"
+import type { RpcID } from "./jsonrpc.ts"
+import { CodexSessions, type ThreadDescription } from "./sessions.ts"
+import { spawnStdioChannel } from "./stdio.ts"
+import { connectUnixWebSocket } from "./websocket.ts"
+
+export const HARNESS = "codex"
+export const DEFAULT_POLL_MS = 2000
+const LIST_PAGES_MAX = 20
+const METHOD_NOT_FOUND = -32601
+
+export interface CodexSpokeOptions {
+  readonly server: string
+  /** The machine token (never logged). */
+  readonly token: string
+  readonly harnessVersion: string
+  readonly pluginVersion: string
+  readonly directory: string
+  /** The codex executable (default "codex" on PATH, see main.ts). */
+  readonly codexBin: string
+  /** Arguments before `app-server` (tests: the fake app-server's script). */
+  readonly codexBinArgs?: readonly string[]
+  /** Arguments after `app-server --listen stdio://` (e.g. -c overrides). */
+  readonly codexArgs?: readonly string[]
+  /** The own app-server's whole environment. */
+  readonly env: Readonly<Record<string, string | undefined>>
+  /** The shared daemon's socket; absent: no daemon attach. */
+  readonly daemonSocket?: string
+  readonly pollMs?: number
+  readonly threadDefaults?: Readonly<Record<string, unknown>>
+  readonly turnTimeoutMs?: number
+  readonly log?: (line: string) => void
+  readonly socket?: HarnessSpokeOptions["socket"]
+  readonly backoff?: HarnessSpokeOptions["backoff"]
+}
+
+export interface CodexSpoke {
+  readonly spoke: HarnessSpoke
+  readonly sessions: CodexSessions
+  readonly daemonConnected: boolean
+  stop(): Promise<void>
+}
+
+const message = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
+const isObj = (v: unknown): v is Record<string, any> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+export function startCodexSpoke(options: CodexSpokeOptions): CodexSpoke {
+  const log = options.log ?? (() => {})
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS
+  let stopped = false
+  let own: Promise<AppServerConnection> | undefined
+  let daemon: AppServerConnection | undefined
+  let connecting = false
+  let discovering = false
+  const resuming = new Set<string>()
+
+  const sessions: CodexSessions = new CodexSessions({
+    spoke: { upsertSession: (info) => spoke.upsertSession(info), endSession: (id) => spoke.endSession(id), emit: (event) => spoke.emit(event) },
+    createServer: () => ownServer(),
+    ...(options.threadDefaults ? { threadDefaults: options.threadDefaults } : {}),
+    ...(options.turnTimeoutMs !== undefined ? { turnTimeoutMs: options.turnTimeoutMs } : {}),
+    log,
+  })
+
+  const spoke = new HarnessSpoke({
+    server: options.server,
+    token: options.token,
+    harness: HARNESS,
+    harnessVersion: options.harnessVersion,
+    evidence: "rpc",
+    pluginVersion: options.pluginVersion,
+    directory: options.directory,
+    kind: "service",
+    mode: "always",
+    handlers: {
+      turn: (req) => sessions.turn(req),
+      steer: (req) => sessions.steer(req),
+      interrupt: (req) => sessions.interrupt(req),
+      stop: (req) => sessions.stop(req),
+      permission: (req) => sessions.permission(req),
+      create: (req) => sessions.create(req),
+    },
+    deliver: (req) => sessions.deliver(req),
+    features: ["hubPrompt", "launch", "turnEvents"],
+    onState: (state, error) => log(`hub connection ${state}${error ? `: ${error}` : ""}`),
+    ...(options.socket ? { socket: options.socket } : {}),
+    ...(options.backoff ? { backoff: options.backoff } : {}),
+  })
+
+  /** Routes a connection's notifications and server requests (`conn` is set once initialize answered). */
+  function handlers(get: () => AppServerConnection | undefined, onThreadStarted?: (thread: unknown) => void) {
+    return {
+      onNotification(method: string, params: unknown) {
+        const conn = get()
+        if (!conn) return
+        if (method === "thread/started" && onThreadStarted) onThreadStarted(isObj(params) ? params.thread : undefined)
+        sessions.notification(conn, method, params)
+      },
+      onRequest(id: RpcID, method: string, params: unknown) {
+        const conn = get()
+        if (!conn) return
+        if (sessions.serverRequest(conn, id, method, params)) return
+        // On its own app-server the spoke is the only client: nobody else would answer.
+        if (conn.name === "own") conn.peer.respondError(id, METHOD_NOT_FOUND, `The hub's Codex spoke does not handle ${method}`)
+      },
+    }
+  }
+
+  function ownServer(): Promise<AppServerConnection> {
+    if (stopped) return Promise.reject(new Error("The Codex spoke is stopping"))
+    own ??= (async () => {
+      const child = spawnStdioChannel({
+        command: options.codexBin,
+        args: [...(options.codexBinArgs ?? []), "app-server", "--listen", "stdio://", ...(options.codexArgs ?? [])],
+        env: options.env,
+        log: (line) => log(`codex app-server: ${line}`),
+      })
+      let conn: AppServerConnection | undefined
+      try {
+        conn = await openAppServer(child.channel, { name: "own", clientVersion: options.pluginVersion, ...handlers(() => conn) })
+      } catch (cause) {
+        own = undefined
+        child.channel.close()
+        throw new Error(`Cannot start codex app-server (${options.codexBin}): ${message(cause)}`)
+      }
+      const opened = conn
+      void opened.closed.then((reason) => {
+        log(`own app-server closed: ${reason}`)
+        sessions.connectionClosed(opened)
+        own = undefined
+      })
+      return opened
+    })()
+    return own
+  }
+
+  async function resume(conn: AppServerConnection, threadID: string): Promise<void> {
+    if (resuming.has(threadID) || sessions.hasThread(threadID)) return
+    resuming.add(threadID)
+    try {
+      const res = await conn.request("thread/resume", { threadId: threadID, excludeTurns: true })
+      const thread = isObj(res) && isObj(res.thread) ? (res.thread as unknown as ThreadDescription) : undefined
+      if (thread && typeof thread.id === "string" && !conn.isClosed && daemon === conn) sessions.attach(conn, { ...thread, cwd: thread.cwd ?? (isObj(res) ? res.cwd : undefined) })
+    } catch (cause) {
+      log(`thread/resume ${threadID}: ${message(cause)}`)
+    } finally {
+      resuming.delete(threadID)
+    }
+  }
+
+  async function discover(conn: AppServerConnection): Promise<void> {
+    if (discovering) return
+    discovering = true
+    try {
+      let cursor: string | undefined
+      for (let page = 0; page < LIST_PAGES_MAX; page++) {
+        const res = await conn.request("thread/loaded/list", cursor ? { cursor } : {})
+        const ids: unknown[] = isObj(res) && Array.isArray(res.data) ? res.data : []
+        await Promise.all(ids.filter((id): id is string => typeof id === "string").map((id) => resume(conn, id)))
+        cursor = isObj(res) && typeof res.nextCursor === "string" ? res.nextCursor : undefined
+        if (!cursor) break
+      }
+    } catch (cause) {
+      if (!conn.isClosed) log(`thread/loaded/list: ${message(cause)}`)
+    } finally {
+      discovering = false
+    }
+  }
+
+  async function connectDaemon(socketPath: string): Promise<void> {
+    if (daemon || connecting || stopped) return
+    connecting = true
+    try {
+      const channel = await connectUnixWebSocket(socketPath, { timeoutMs: Math.max(1000, pollMs) })
+      let conn: AppServerConnection | undefined
+      conn = await openAppServer(channel, {
+        name: "daemon",
+        clientVersion: options.pluginVersion,
+        ...handlers(
+          () => conn,
+          (thread) => {
+            if (conn && isObj(thread) && typeof thread.id === "string") void resume(conn, thread.id)
+          },
+        ),
+      })
+      if (stopped) return conn.close()
+      const opened = conn
+      daemon = opened
+      log(`attached to the Codex daemon at ${socketPath}`)
+      void opened.closed.then((reason) => {
+        log(`Codex daemon connection closed: ${reason}`)
+        sessions.connectionClosed(opened)
+        if (daemon === opened) daemon = undefined
+      })
+    } catch {
+      // No daemon (yet): try again at the next poll.
+    } finally {
+      connecting = false
+    }
+  }
+
+  let timer: ReturnType<typeof setInterval> | undefined
+  if (options.daemonSocket) {
+    const socketPath = options.daemonSocket
+    const tick = async () => {
+      await connectDaemon(socketPath)
+      if (daemon && !stopped) await discover(daemon)
+    }
+    timer = setInterval(() => void tick(), pollMs)
+    timer.unref?.()
+    void tick()
+  }
+
+  spoke.start()
+  return {
+    spoke,
+    sessions,
+    get daemonConnected() {
+      return daemon !== undefined
+    },
+    async stop() {
+      if (stopped) return
+      stopped = true
+      if (timer) clearInterval(timer)
+      spoke.stop()
+      daemon?.close()
+      const pending = own
+      own = undefined
+      if (pending) {
+        const conn = await pending.catch(() => undefined)
+        conn?.close()
+        if (conn) await Promise.race([conn.closed, new Promise((r) => setTimeout(r, 3000))])
+      }
+    },
+  }
+}

package/packages/codex/src/stdio.ts

@@ -0,0 +1,101 @@
+// A child process's stdio as a channel of lines: `codex app-server --listen stdio://` reads one JSON message per line
+// on stdin and writes one per line on stdout. Its stderr goes to `log` line by line (never parsed); its exit (or a
+// failure to start) closes the channel; closing the channel ends the child (SIGTERM, then SIGKILL after a grace).
+import { spawn } from "node:child_process"
+import type { Channel } from "./jsonrpc.ts"
+
+/** Longest stdout line accepted (an app-server message); a longer one ends the child. */
+export const STDIO_MAX_LINE = 16 * 1024 * 1024
+const KILL_GRACE_MS = 2000
+const LOG_LINE_MAX = 2000
+
+export interface StdioOptions {
+  readonly command: string
+  readonly args: readonly string[]
+  /** The child's whole environment (nothing is inherited implicitly). */
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly cwd?: string
+  readonly log?: (line: string) => void
+}
+
+export interface StdioChild {
+  readonly channel: Channel
+  /** 0 when the child could not start. */
+  readonly pid: number
+  readonly exited: Promise<{ code: number | null; signal: string | null }>
+}
+
+export function spawnStdioChannel(options: StdioOptions): StdioChild {
+  const listeners: ((text: string) => void)[] = []
+  const closers: ((reason: string) => void)[] = []
+  let closed = false
+  const finish = (reason: string) => {
+    if (closed) return
+    closed = true
+    for (const cb of closers) cb(reason)
+  }
+  const env = Object.fromEntries(Object.entries(options.env).filter(([, v]) => v !== undefined)) as Record<string, string>
+  const child = spawn(options.command, [...options.args], { cwd: options.cwd, env, stdio: ["pipe", "pipe", "pipe"] })
+  let exitDone!: (v: { code: number | null; signal: string | null }) => void
+  const exited = new Promise<{ code: number | null; signal: string | null }>((resolve) => (exitDone = resolve))
+  child.on("error", (error) => {
+    finish(`cannot run ${options.command}: ${error.message}`)
+    exitDone({ code: null, signal: null })
+  })
+  child.on("exit", (code, signal) => {
+    finish(`${options.command} exited (code ${code ?? "none"}${signal ? `, signal ${signal}` : ""})`)
+    exitDone({ code, signal })
+  })
+  child.stdin.on("error", () => {})
+
+  let out = ""
+  child.stdout.setEncoding("utf8")
+  child.stdout.on("data", (chunk: string) => {
+    out += chunk
+    let end: number
+    while ((end = out.indexOf("\n")) >= 0) {
+      const line = out.slice(0, end).replace(/\r$/, "")
+      out = out.slice(end + 1)
+      if (line.trim()) for (const cb of listeners) cb(line)
+    }
+    if (out.length > STDIO_MAX_LINE) child.kill("SIGKILL")
+  })
+  let err = ""
+  child.stderr.setEncoding("utf8")
+  child.stderr.on("data", (chunk: string) => {
+    err += chunk
+    let end: number
+    while ((end = err.indexOf("\n")) >= 0) {
+      const line = err.slice(0, end)
+      err = err.slice(end + 1)
+      if (line.trim()) options.log?.(line.slice(0, LOG_LINE_MAX))
+    }
+    if (err.length > LOG_LINE_MAX) err = ""
+  })
+
+  const stop = () => {
+    if (child.exitCode !== null || child.signalCode !== null || !child.pid) return
+    child.kill("SIGTERM")
+    const timer = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS)
+    timer.unref?.()
+    void exited.then(() => clearTimeout(timer))
+  }
+
+  return {
+    pid: child.pid ?? 0,
+    exited,
+    channel: {
+      send(text) {
+        if (closed) throw new Error("the app-server process has exited")
+        child.stdin.write(`${text}\n`)
+      },
+      close() {
+        child.stdin.end()
+        stop()
+        finish("closed")
+      },
+      onMessage: (cb) => void listeners.push(cb),
+      onClose: (cb) => void closers.push(cb),
+    },
+  }
+}

package/packages/codex/src/websocket.ts

@@ -0,0 +1,206 @@
+// A minimal WebSocket client (RFC 6455) over a Unix socket. The shared Codex daemon listens on
+// CODEX_HOME/app-server-control/app-server-control.sock and speaks WebSocket there (HTTP Upgrade → 101, then frames;
+// spike v0hsdqhm), so the spoke does the handshake and the framing itself: text messages only, client frames masked,
+// fragmented messages reassembled, pings answered, a close frame (or the socket ending) closes the channel.
+import { createHash, randomBytes } from "node:crypto"
+import { Socket } from "node:net"
+import type { Channel } from "./jsonrpc.ts"
+
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+/** Largest message this client accepts (the daemon announces 16 MiB unfragmented). */
+export const WS_MAX_MESSAGE = 16 * 1024 * 1024
+const HEAD_MAX = 16 * 1024
+
+const OP_CONT = 0x0
+const OP_TEXT = 0x1
+const OP_BINARY = 0x2
+const OP_CLOSE = 0x8
+const OP_PING = 0x9
+const OP_PONG = 0xa
+
+/** One client frame (FIN set, masked). */
+export function encodeFrame(opcode: number, payload: Buffer): Buffer {
+  const length = payload.length
+  const head = length < 126 ? Buffer.alloc(2) : length < 65_536 ? Buffer.alloc(4) : Buffer.alloc(10)
+  head[0] = 0x80 | opcode
+  if (length < 126) head[1] = 0x80 | length
+  else if (length < 65_536) {
+    head[1] = 0x80 | 126
+    head.writeUInt16BE(length, 2)
+  } else {
+    head[1] = 0x80 | 127
+    head.writeBigUInt64BE(BigInt(length), 2)
+  }
+  const mask = randomBytes(4)
+  const body = Buffer.alloc(length)
+  for (let i = 0; i < length; i++) body[i] = payload[i]! ^ mask[i & 3]!
+  return Buffer.concat([head, mask, body])
+}
+
+export interface WebSocketOptions {
+  /** For the connection and the upgrade (default 5 s). */
+  readonly timeoutMs?: number
+  /** The request path (default "/"). */
+  readonly path?: string
+}
+
+/** Connects and upgrades; resolves with a channel of text messages, rejects when either fails. */
+export function connectUnixWebSocket(socketPath: string, options: WebSocketOptions = {}): Promise<Channel> {
+  return new Promise((resolve, reject) => {
+    const key = randomBytes(16).toString("base64")
+    const accept = createHash("sha1").update(key + GUID).digest("base64")
+    // Listeners first: Bun reports a missing socket synchronously, inside connect() (quirk awi4wb9g).
+    const socket = new Socket()
+    let upgraded = false
+    let head = Buffer.alloc(0)
+    const fail = (error: Error) => {
+      if (upgraded) return
+      clearTimeout(timer)
+      socket.destroy()
+      reject(error)
+    }
+    const timer = setTimeout(() => fail(new Error(`No WebSocket upgrade from ${socketPath} within ${options.timeoutMs ?? 5000} ms`)), options.timeoutMs ?? 5000)
+    socket.on("error", (error) => fail(error))
+    socket.on("close", () => fail(new Error(`${socketPath} closed before the WebSocket upgrade`)))
+    socket.on("connect", () => {
+      socket.write(
+        [`GET ${options.path ?? "/"} HTTP/1.1`, "Host: localhost", "Upgrade: websocket", "Connection: Upgrade", `Sec-WebSocket-Key: ${key}`, "Sec-WebSocket-Version: 13", "", ""].join("\r\n"),
+      )
+    })
+    const onHead = (chunk: Buffer) => {
+      head = Buffer.concat([head, chunk])
+      const end = head.indexOf("\r\n\r\n")
+      if (end < 0) {
+        if (head.length > HEAD_MAX) fail(new Error("The WebSocket upgrade response is too long"))
+        return
+      }
+      const lines = head.subarray(0, end).toString("latin1").split("\r\n")
+      const status = /^HTTP\/1\.[01] (\d{3})/.exec(lines[0] ?? "")?.[1]
+      const headers = new Map(lines.slice(1).map((l) => [l.slice(0, l.indexOf(":")).trim().toLowerCase(), l.slice(l.indexOf(":") + 1).trim()] as const))
+      if (status !== "101") return fail(new Error(`No WebSocket upgrade from ${socketPath} (HTTP ${status ?? "?"})`))
+      if (headers.get("sec-websocket-accept") !== accept) return fail(new Error(`Bad Sec-WebSocket-Accept from ${socketPath}`))
+      upgraded = true
+      clearTimeout(timer)
+      socket.off("data", onHead)
+      socket.removeAllListeners("close")
+      socket.removeAllListeners("error")
+      resolve(frameChannel(socket, head.subarray(end + 4)))
+    }
+    socket.on("data", onHead)
+    try {
+      socket.connect(socketPath)
+    } catch (error) {
+      fail(error as Error)
+    }
+  })
+}
+
+/** The channel over an upgraded socket; `rest` is what arrived after the upgrade response. */
+function frameChannel(socket: Socket, rest: Buffer): Channel {
+  const listeners: ((text: string) => void)[] = []
+  const closers: ((reason: string) => void)[] = []
+  let closed = false
+  let buffer: Buffer = Buffer.from(rest)
+  let fragments: Buffer[] = []
+  let fragmentsLength = 0
+  let fragmentText = false
+
+  const finish = (reason: string) => {
+    if (closed) return
+    closed = true
+    socket.destroy()
+    for (const cb of closers) cb(reason)
+  }
+  const write = (opcode: number, payload: Buffer) => {
+    if (!closed && !socket.destroyed) socket.write(encodeFrame(opcode, payload))
+  }
+
+  const parse = () => {
+    for (;;) {
+      if (buffer.length < 2) return
+      const fin = (buffer[0]! & 0x80) !== 0
+      const opcode = buffer[0]! & 0x0f
+      const masked = (buffer[1]! & 0x80) !== 0
+      let length = buffer[1]! & 0x7f
+      let offset = 2
+      if (length === 126) {
+        if (buffer.length < 4) return
+        length = buffer.readUInt16BE(2)
+        offset = 4
+      } else if (length === 127) {
+        if (buffer.length < 10) return
+        const big = buffer.readBigUInt64BE(2)
+        if (big > BigInt(WS_MAX_MESSAGE)) return finish("message too large")
+        length = Number(big)
+        offset = 10
+      }
+      if (length > WS_MAX_MESSAGE) return finish("message too large")
+      const maskAt = offset
+      if (masked) offset += 4
+      if (buffer.length < offset + length) return
+      let payload = buffer.subarray(offset, offset + length)
+      if (masked) {
+        const mask = buffer.subarray(maskAt, maskAt + 4)
+        payload = Buffer.from(payload.map((b, i) => b ^ mask[i & 3]!))
+      }
+      buffer = buffer.subarray(offset + length)
+      switch (opcode) {
+        case OP_PING:
+          write(OP_PONG, Buffer.from(payload))
+          break
+        case OP_PONG:
+          break
+        case OP_CLOSE:
+          write(OP_CLOSE, Buffer.from(payload.subarray(0, 2)))
+          return finish(payload.length > 2 ? payload.subarray(2).toString("utf8") : "closed by the server")
+        case OP_TEXT:
+        case OP_BINARY:
+        case OP_CONT: {
+          if (opcode !== OP_CONT) {
+            fragments = []
+            fragmentsLength = 0
+            fragmentText = opcode === OP_TEXT
+          }
+          fragments.push(Buffer.from(payload))
+          fragmentsLength += payload.length
+          if (fragmentsLength > WS_MAX_MESSAGE) return finish("message too large")
+          if (fin) {
+            const message = Buffer.concat(fragments)
+            fragments = []
+            fragmentsLength = 0
+            if (fragmentText) for (const cb of listeners) cb(message.toString("utf8"))
+          }
+          break
+        }
+        default:
+          return finish(`unknown WebSocket opcode ${opcode}`)
+      }
+    }
+  }
+
+  socket.on("data", (chunk: Buffer) => {
+    buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk
+    parse()
+  })
+  socket.on("close", () => finish("connection closed"))
+  socket.on("error", (error) => finish(error.message))
+
+  return {
+    send(text) {
+      if (closed) throw new Error("WebSocket closed")
+      write(OP_TEXT, Buffer.from(text, "utf8"))
+    },
+    close() {
+      if (closed) return
+      write(OP_CLOSE, Buffer.from([0x03, 0xe8]))
+      socket.end()
+      finish("closed")
+    },
+    onMessage(cb) {
+      listeners.push(cb)
+      // Frames that came with the upgrade response wait for the first listener.
+      if (listeners.length === 1 && buffer.length) parse()
+    },
+    onClose: (cb) => void closers.push(cb),
+  }
+}

package/packages/codex/src/wrapper.ts

@@ -0,0 +1,100 @@
+// `hub codex [codex args…]`: runs Codex so the hub's Codex spoke can see its threads, without touching Codex's files
+// (CODEX_HOME, default ~/.codex). It makes sure the per-user spoke service runs (starting `hub codex-spoke serve` in
+// the background when none does), then runs codex with the shared app-server daemon turned on for this run
+// (`--enable daemon_auto_start`: the TUI's threads live on the daemon, where the spoke attaches) and the user's
+// arguments, its exit code passed through. On a machine that is not enrolled (no machine token) or when the service
+// cannot be started, Codex runs as usual without the hub, and the command says why.
+//
+// Settings (environment): HUB_CODEX_BIN (default `codex` on PATH); see main.ts for the service's.
+import { spawn } from "node:child_process"
+import { closeSync, openSync } from "node:fs"
+import path from "node:path"
+import { configPath } from "../../../src/config.ts"
+import { readSpokeCredentials } from "../../node/src/config.ts"
+import { codexStateDir, ensurePrivateDir, readServicePid } from "./paths.ts"
+
+const SERVICE_START_MS = 8000
+/** Codex's own flag (a feature toggle for this run only; nothing is written). */
+export const DAEMON_ARGS = ["--enable", "daemon_auto_start"] as const
+
+type Env = Readonly<Record<string, string | undefined>>
+
+export interface Program {
+  readonly execPath: string
+  readonly entry: string
+}
+
+export interface CodexIo {
+  readonly env: Env
+  readonly home: string
+  stderr(s: string): void
+  /** What runs the hub CLI (the service runs it too). */
+  readonly program: Program
+}
+
+/** Starts `hub codex-spoke serve` detached, logging to spoke.log in the spoke's state directory. */
+function spawnService(io: CodexIo): void {
+  const dir = codexStateDir(io.env, io.home)
+  ensurePrivateDir(dir)
+  const log = openSync(path.join(dir, "spoke.log"), "a", 0o600)
+  try {
+    const child = spawn(io.program.execPath, [io.program.entry, "codex-spoke", "serve"], { detached: true, stdio: ["ignore", log, log], env: { ...io.env, BUN_BE_BUN: "1" } })
+    child.on("error", () => {})
+    child.unref()
+  } finally {
+    closeSync(log)
+  }
+}
+
+/** True when the spoke service runs (started here when needed); else false with the reason on stderr. */
+async function ensureService(io: CodexIo): Promise<boolean> {
+  if (!readSpokeCredentials(io.env, io.home)) {
+    io.stderr(`hub codex: this machine is not enrolled with a hub (no machine token in ${configPath(io.env, io.home)}); running Codex without the hub\n`)
+    return false
+  }
+  if (readServicePid(io.env, io.home) !== undefined) return true
+  spawnService(io)
+  const deadline = Date.now() + SERVICE_START_MS
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 100))
+    if (readServicePid(io.env, io.home) !== undefined) return true
+  }
+  io.stderr(`hub codex: the Codex spoke did not start (see ${path.join(codexStateDir(io.env, io.home), "spoke.log")}); running Codex without the hub\n`)
+  return false
+}
+
+const SIGNALS: Record<string, number> = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 }
+
+/** Runs `bin` with the terminal; resolves with its exit code (128 + signal number when a signal ended it). */
+function spawnCodex(bin: string, args: readonly string[], env: Env, stderr: (s: string) => void): Promise<number> {
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, { stdio: "inherit", env: env as NodeJS.ProcessEnv })
+    // The terminal sends Ctrl-C to Codex too: it decides what that means; this process keeps waiting.
+    const ignore = () => {}
+    const forward = () => child.kill("SIGTERM")
+    process.on("SIGINT", ignore)
+    process.on("SIGTERM", forward)
+    const done = (code: number) => {
+      process.off("SIGINT", ignore)
+      process.off("SIGTERM", forward)
+      resolve(code)
+    }
+    child.on("error", (cause) => {
+      stderr(`hub codex: cannot run ${bin}: ${cause.message}\n`)
+      done(127)
+    })
+    child.on("exit", (code, signal) => done(code ?? (signal ? 128 + (SIGNALS[signal] ?? 0) : 1)))
+  })
+}
+
+export async function runCodex(args: readonly string[], io: CodexIo): Promise<number> {
+  let hub = false
+  try {
+    hub = await ensureService(io)
+  } catch (cause) {
+    io.stderr(`hub codex: ${cause instanceof Error ? cause.message : String(cause)}; running Codex without the hub\n`)
+  }
+  const env: Record<string, string | undefined> = { ...io.env }
+  delete env.BUN_BE_BUN
+  return spawnCodex(io.env.HUB_CODEX_BIN || "codex", hub ? [...DAEMON_ARGS, ...args] : [...args], env, io.stderr)
+}

package/packages/node/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@huynle/hub-node",
+  "version": "0.7.1",
+  "private": true,
+  "description": "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  }
+}