@huynle/hub 0.6.0 → 0.7.1

package/packages/codex/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@huynle/hub-codex",
+  "version": "0.7.1",
+  "private": true,
+  "description": "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  }
+}

package/packages/codex/src/app-server.ts

@@ -0,0 +1,44 @@
+// One initialized connection to a Codex app-server: JSON-RPC over a channel, the initialize handshake (with the
+// experimental API, which thread/inject_items and turn/steer's clientUserMessageId need) and the client's name.
+import { JsonRpcPeer, type Channel, type PeerHandlers, type RpcID } from "./jsonrpc.ts"
+import type { AppServerPort } from "./sessions.ts"
+
+export interface AppServerConnection extends AppServerPort {
+  readonly peer: JsonRpcPeer
+  /** Resolves with the reason when the connection closed. */
+  readonly closed: Promise<string>
+  readonly isClosed: boolean
+  close(): void
+}
+
+export interface OpenOptions extends PeerHandlers {
+  /** The connection's name (keeps its JSON-RPC request IDs apart from another connection's). */
+  readonly name: string
+  readonly clientVersion: string
+  readonly timeoutMs?: number
+}
+
+const INIT_TIMEOUT_MS = 20_000
+
+/** Opens the connection: initialize, then the initialized notification. Closes the channel when that fails. */
+export async function openAppServer(channel: Channel, options: OpenOptions): Promise<AppServerConnection> {
+  const peer = new JsonRpcPeer(channel, options)
+  try {
+    await peer.request("initialize", { clientInfo: { name: "hub", title: "Hub", version: options.clientVersion }, capabilities: { experimentalApi: true } }, { timeoutMs: options.timeoutMs ?? INIT_TIMEOUT_MS })
+  } catch (cause) {
+    peer.close()
+    throw cause
+  }
+  peer.notify("initialized")
+  return {
+    name: options.name,
+    peer,
+    closed: peer.closed,
+    get isClosed() {
+      return peer.isClosed
+    },
+    request: (method: string, params?: unknown) => peer.request(method, params),
+    respond: (id: RpcID, result: unknown) => peer.respond(id, result),
+    close: () => peer.close(),
+  }
+}

package/packages/codex/src/ids.ts

@@ -0,0 +1,28 @@
+// Hub IDs for Codex's native IDs (decision fx04e42c point 2). A thread ID (UUIDv7) maps to the reversible
+// ses_cx<32 hex> (spoke-sdk hubSessionID, namespace "cx"). Other IDs the hub sees (approval requests, items, turns,
+// inbox entries) are plain IDs (protocol wire.ts ID).
+import { randomBytes } from "node:crypto"
+import { hubSessionID, nativeSessionID } from "../../spoke-sdk/src/index.ts"
+
+/** The session namespace of Codex in hub session IDs. */
+export const CODEX_NAMESPACE = "cx"
+
+const PLAIN_MAX = 300
+
+/** The hub session ID of a Codex thread. */
+export const codexSessionID = (threadID: string): string => hubSessionID(CODEX_NAMESPACE, threadID)
+
+/** The Codex thread a hub session ID stands for; undefined when it is not a Codex one. */
+export const codexThreadID = (sessionID: string): string | undefined => nativeSessionID(CODEX_NAMESPACE, sessionID)
+
+/** `raw` as a plain hub ID (letters, digits and _.:@/+~- only, at most 300 characters); a fresh one when empty. */
+export function plainID(raw: string, prefix = "id"): string {
+  const clean = (typeof raw === "string" ? raw : "").replace(/[^A-Za-z0-9_.:@/+~-]/g, "_").slice(0, PLAIN_MAX)
+  return clean || `${prefix}_${randomBytes(8).toString("hex")}`
+}
+
+/**
+ * The hub's ID for an app-server request to clients (an approval): the connection's name and the JSON-RPC id, typed
+ * (n: number, s: string) so 0 and "0" stay apart. JSON-RPC ids are per connection.
+ */
+export const requestKey = (connection: string, id: number | string): string => plainID(`per_${connection}_${typeof id === "number" ? "n" : "s"}${id}`)

package/packages/codex/src/index.ts

@@ -0,0 +1,11 @@
+// @huynle/hub-codex: the Codex app-server spoke (design §1.2, §13.3; decision fx04e42c point 5 as corrected by the
+// P7-T0 spike, report v0hsdqhm). The spoke attaches to Codex's app-server as one of its clients: its own
+// `codex app-server` over stdio for the sessions it starts, and the shared daemon's socket when present (the TUI's
+// threads live there). `hub codex` runs the Codex TUI so its threads land on the daemon.
+export * from "./ids.ts"
+export * from "./jsonrpc.ts"
+export * from "./stdio.ts"
+export * from "./websocket.ts"
+export * from "./sessions.ts"
+export * from "./app-server.ts"
+export * from "./spoke.ts"

package/packages/codex/src/jsonrpc.ts

@@ -0,0 +1,168 @@
+// JSON-RPC as Codex's app-server speaks it (codex app-server, P7-T0 spike v0hsdqhm): one JSON object per message,
+// without a "jsonrpc" member. Requests both ways: the client calls methods (thread/start, turn/start …) and the
+// server asks its clients (approvals), each side numbering its own ids. Notifications carry the thread's events.
+// The channel is any transport of whole text messages: lines over a child's stdio (stdio.ts) or WebSocket text frames
+// over the shared daemon's Unix socket (websocket.ts).
+
+/** A transport of whole text messages. */
+export interface Channel {
+  send(text: string): void
+  close(): void
+  onMessage(cb: (text: string) => void): void
+  /** Called once, when the channel closed (either side). */
+  onClose(cb: (reason: string) => void): void
+}
+
+export type RpcID = number | string
+
+export class RpcError extends Error {
+  constructor(
+    message: string,
+    readonly code: number,
+    readonly method?: string,
+  ) {
+    super(message)
+    this.name = "RpcError"
+  }
+}
+
+/** JSON-RPC's code for a request that could not be sent or answered (this side's own failures). */
+export const LOCAL_ERROR = -32000
+
+export interface PeerHandlers {
+  onNotification?(method: string, params: unknown): void
+  onRequest?(id: RpcID, method: string, params: unknown): void
+}
+
+const DEFAULT_TIMEOUT_MS = 60_000
+
+interface Pending {
+  readonly method: string
+  resolve(value: unknown): void
+  reject(error: Error): void
+  readonly timer: ReturnType<typeof setTimeout>
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const isID = (v: unknown): v is RpcID => typeof v === "number" || typeof v === "string"
+
+export class JsonRpcPeer {
+  readonly closed: Promise<string>
+  #closedReason: string | undefined
+  #next = 0
+  readonly #pending = new Map<RpcID, Pending>()
+  readonly #channel: Channel
+  readonly #handlers: PeerHandlers
+
+  constructor(channel: Channel, handlers: PeerHandlers = {}) {
+    this.#channel = channel
+    this.#handlers = handlers
+    let done!: (reason: string) => void
+    this.closed = new Promise((resolve) => (done = resolve))
+    channel.onMessage((text) => this.#receive(text))
+    channel.onClose((reason) => {
+      if (this.#closedReason !== undefined) return
+      this.#closedReason = reason || "closed"
+      for (const [id, call] of this.#pending) {
+        clearTimeout(call.timer)
+        call.reject(new RpcError(`The app-server connection closed before it answered ${call.method} (${this.#closedReason})`, LOCAL_ERROR, call.method))
+        this.#pending.delete(id)
+      }
+      done(this.#closedReason)
+    })
+  }
+
+  get isClosed(): boolean {
+    return this.#closedReason !== undefined
+  }
+
+  request(method: string, params?: unknown, options: { readonly timeoutMs?: number } = {}): Promise<any> {
+    if (this.#closedReason !== undefined) return Promise.reject(new RpcError(`The app-server connection is closed (${this.#closedReason})`, LOCAL_ERROR, method))
+    const id = ++this.#next
+    return new Promise((resolve, reject) => {
+      const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+      const timer = setTimeout(() => {
+        this.#pending.delete(id)
+        reject(new RpcError(`${method}: the app-server did not answer within ${timeoutMs} ms`, LOCAL_ERROR, method))
+      }, timeoutMs)
+      this.#pending.set(id, { method, resolve, reject, timer })
+      this.#send(params === undefined ? { id, method } : { id, method, params })
+    })
+  }
+
+  notify(method: string, params?: unknown): void {
+    this.#send(params === undefined ? { method } : { method, params })
+  }
+
+  /** Answers a server request. */
+  respond(id: RpcID, result: unknown): void {
+    this.#send({ id, result })
+  }
+
+  respondError(id: RpcID, code: number, message: string): void {
+    this.#send({ id, error: { code, message } })
+  }
+
+  close(): void {
+    this.#channel.close()
+  }
+
+  #send(message: object): void {
+    if (this.#closedReason !== undefined) return
+    try {
+      this.#channel.send(JSON.stringify(message))
+    } catch {
+      // The channel reports its own close; a request then fails there.
+    }
+  }
+
+  #receive(text: string): void {
+    let message: unknown
+    try {
+      message = JSON.parse(text)
+    } catch {
+      return
+    }
+    if (!isObj(message)) return
+    if (typeof message.method === "string") {
+      if (isID(message.id)) this.#handlers.onRequest?.(message.id, message.method, message.params)
+      else this.#handlers.onNotification?.(message.method, message.params)
+      return
+    }
+    if (!isID(message.id)) return
+    const call = this.#pending.get(message.id)
+    if (!call) return
+    this.#pending.delete(message.id)
+    clearTimeout(call.timer)
+    if (isObj(message.error)) {
+      const code = typeof message.error.code === "number" ? message.error.code : LOCAL_ERROR
+      call.reject(new RpcError(`${call.method}: ${typeof message.error.message === "string" ? message.error.message : "error"}`, code, call.method))
+    } else call.resolve(message.result)
+  }
+}
+
+/** Two connected in-memory channels (tests, and in-process fakes). */
+export function memoryChannelPair(): [Channel, Channel] {
+  type End = { listeners: ((t: string) => void)[]; closers: ((r: string) => void)[]; closed: boolean }
+  const ends: [End, End] = [
+    { listeners: [], closers: [], closed: false },
+    { listeners: [], closers: [], closed: false },
+  ]
+  const close = (reason: string) => {
+    for (const end of ends) {
+      if (end.closed) continue
+      end.closed = true
+      for (const cb of end.closers) cb(reason)
+    }
+  }
+  const channel = (self: End, other: End): Channel => ({
+    send(text) {
+      if (self.closed) throw new Error("channel closed")
+      for (const cb of other.listeners) cb(text)
+    },
+    close: () => close("closed"),
+    onMessage: (cb) => void self.listeners.push(cb),
+    onClose: (cb) => void self.closers.push(cb),
+  })
+  return [channel(ends[0], ends[1]), channel(ends[1], ends[0])]
+}

package/packages/codex/src/main.ts

@@ -0,0 +1,122 @@
+// `hub codex-spoke serve`: the per-user Codex spoke service until SIGINT/SIGTERM (main.ts aborts io.signal), started
+// in the background by `hub codex` and never typed by hand in normal use. It needs an enrolled machine (the machine
+// token in the spoke's config.json, read-only), keeps a pid file in <hub state dir>/codex/spoke.pid (one service per
+// user: a second one refuses while the first runs) and attaches to the shared Codex daemon's socket when present.
+//
+// Settings (environment): HUB_CODEX_BIN (default `codex` on PATH), HUB_CODEX_DAEMON_SOCKET (another socket, or
+// "off"), HUB_CODEX_CONFIG (Codex config overrides for the app-server the spoke starts, one key=value per line,
+// passed as -c; Codex's files are never written).
+import { spawnSync } from "node:child_process"
+import { openSync, closeSync, readFileSync, rmSync, writeSync } from "node:fs"
+import { configPath } from "../../../src/config.ts"
+import { readSpokeCredentials } from "../../node/src/config.ts"
+import pkg from "../package.json" with { type: "json" }
+import { codexStateDir, ensurePrivateDir, daemonSocketPath, pidFile, readServicePid } from "./paths.ts"
+import { startCodexSpoke } from "./spoke.ts"
+
+export const VERSION: string = pkg.version
+
+export interface CodexMainIo {
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly home: string
+  stdout(s: string): void
+  stderr(s: string): void
+  readonly signal?: AbortSignal
+}
+
+export const CODEX_SPOKE_USAGE = "Usage: hub codex-spoke serve | install [--dry-run] | uninstall [--dry-run] | status"
+
+/** `codex --version` → "0.160.0", or "" when it cannot be told. */
+export function codexVersion(bin: string, env: CodexMainIo["env"]): string {
+  try {
+    const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 5000, env: env as NodeJS.ProcessEnv })
+    return /\d+\.\d+\.\d+[\w.+-]*/.exec(r.stdout ?? "")?.[0]?.slice(0, 100) ?? ""
+  } catch {
+    return ""
+  }
+}
+
+/** HUB_CODEX_CONFIG's lines as `-c key=value` arguments. */
+export function configOverrides(value: string | undefined): string[] {
+  return (value ?? "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "" && line.includes("="))
+    .flatMap((line) => ["-c", line])
+}
+
+/** Claims the pid file for this process; false when another live service holds it. */
+function claimPidFile(file: string, env: CodexMainIo["env"], home: string): boolean {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = openSync(file, "wx", 0o600)
+      try {
+        writeSync(fd, `${process.pid}\n`)
+      } finally {
+        closeSync(fd)
+      }
+      return true
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== "EEXIST") throw cause
+      if (readServicePid(env, home) !== undefined) return false
+      rmSync(file, { force: true }) // a stale file: its process is gone
+    }
+  }
+  return false
+}
+
+function releasePidFile(file: string): void {
+  try {
+    if (readFileSync(file, "utf8").trim() === String(process.pid)) rmSync(file, { force: true })
+  } catch {}
+}
+
+async function serve(io: CodexMainIo): Promise<number> {
+  const credentials = readSpokeCredentials(io.env, io.home)
+  if (!credentials) {
+    io.stderr(`hub codex-spoke serve: this machine is not enrolled with a hub (no machine token in ${configPath(io.env, io.home)})\n`)
+    return 1
+  }
+  const log = (line: string) => io.stderr(`[hub codex-spoke] ${new Date().toISOString()} ${line}\n`)
+  ensurePrivateDir(codexStateDir(io.env, io.home))
+  const file = pidFile(io.env, io.home)
+  if (!claimPidFile(file, io.env, io.home)) {
+    io.stderr(`hub codex-spoke serve: already running (pid ${readServicePid(io.env, io.home) ?? "?"})\n`)
+    return 1
+  }
+  try {
+    const codexBin = io.env.HUB_CODEX_BIN || "codex"
+    const env: Record<string, string | undefined> = { ...io.env }
+    delete env.BUN_BE_BUN
+    const daemonSocket = daemonSocketPath(io.env, io.home)
+    const running = startCodexSpoke({
+      server: credentials.server,
+      token: credentials.token,
+      harnessVersion: codexVersion(codexBin, env),
+      pluginVersion: VERSION,
+      directory: io.home,
+      codexBin,
+      codexArgs: configOverrides(io.env.HUB_CODEX_CONFIG),
+      env,
+      ...(daemonSocket ? { daemonSocket } : {}),
+      log,
+    })
+    log(daemonSocket ? `serving; the Codex daemon socket is ${daemonSocket}` : "serving; not attaching to a Codex daemon")
+    await new Promise<void>((resolve) => {
+      if (!io.signal) return
+      if (io.signal.aborted) return resolve()
+      io.signal.addEventListener("abort", () => resolve(), { once: true })
+    })
+    await running.stop()
+    return 0
+  } finally {
+    releasePidFile(file)
+  }
+}
+
+export async function codexMain(argv: readonly string[], io: CodexMainIo): Promise<number> {
+  const [command] = argv
+  if (command === "serve") return serve(io)
+  io.stderr(`${CODEX_SPOKE_USAGE}\n`)
+  return 2
+}

package/packages/codex/src/paths.ts

@@ -0,0 +1,65 @@
+// Where the Codex spoke looks and keeps its files. It only reads Codex's home (CODEX_HOME, default ~/.codex) to find
+// the shared daemon's socket; its own files live in <hub state dir>/codex (the hub state dir is $HUB_STATE_DIR, else
+// ~/.local/state/hub), a private (0700) directory holding the service's pid file (spoke.pid) and its log.
+// $HUB_CODEX_DAEMON_SOCKET names another daemon socket, or "off" for none.
+import { chmodSync, lstatSync, mkdirSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import path from "node:path"
+import { hubEnv, type Env } from "../../../src/env.ts"
+import { APP_DIR, stateBase } from "../../../src/migrate.ts"
+
+export function codexHome(env: Env = process.env, home: string = homedir()): string {
+  return env.CODEX_HOME || path.join(home, ".codex")
+}
+
+/** The shared daemon's control socket, or undefined when attaching to it is turned off. */
+export function daemonSocketPath(env: Env = process.env, home: string = homedir()): string | undefined {
+  const override = env.HUB_CODEX_DAEMON_SOCKET
+  if (override === "off") return undefined
+  return override || path.join(codexHome(env, home), "app-server-control", "app-server-control.sock")
+}
+
+export function codexStateDir(env: Env = process.env, home: string = homedir()): string {
+  return path.join(hubEnv(env).HUB_STATE_DIR || path.join(stateBase(home), APP_DIR), "codex")
+}
+
+export const pidFile = (env: Env = process.env, home: string = homedir()) => path.join(codexStateDir(env, home), "spoke.pid")
+
+/** A usable process ID: an integer above 1 (0 and negative IDs signal process groups or every process). */
+export const isPid = (n: unknown): n is number => typeof n === "number" && Number.isInteger(n) && n > 1
+
+export function isAlive(pid: number): boolean {
+  if (!isPid(pid)) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM"
+  }
+}
+
+/** The running service's pid from its pid file, or undefined when there is none or that process is gone. */
+export function readServicePid(env: Env = process.env, home: string = homedir()): number | undefined {
+  let text: string
+  try {
+    text = readFileSync(pidFile(env, home), "utf8").trim()
+  } catch {
+    return undefined
+  }
+  const pid = /^\d+$/.test(text) ? Number(text) : NaN
+  return isPid(pid) && isAlive(pid) ? pid : undefined
+}
+
+/**
+ * Makes `dir` (and its parents) and checks it is a real directory of this user that nobody else can reach: a
+ * symlink or someone else's directory is refused, group or other permissions are removed (0700).
+ */
+export function ensurePrivateDir(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const stat = lstatSync(dir)
+  if (stat.isSymbolicLink()) throw new Error(`${dir} is a symlink; the Codex spoke needs a real directory there`)
+  if (!stat.isDirectory()) throw new Error(`${dir} is not a directory`)
+  const uid = process.getuid?.()
+  if (uid !== undefined && stat.uid !== uid) throw new Error(`${dir} belongs to another user`)
+  if ((stat.mode & 0o777) !== 0o700) chmodSync(dir, 0o700)
+}