@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/setup/state.ts

@@ -0,0 +1,244 @@
+// What `hubctl setup` keeps between commands (HBS-13 integration item 7). Everything is secret-free, validated when
+// read and written, and reached only through symlink-checked paths under the state root (next to the applier's own
+// journal, contract LOCK_PATH):
+//
+//   the setup request    `setup preview --out <file>`: the SetupPreview plus the profile and choices apply must
+//                        re-plan with, so `setup apply --preview <file>` needs nothing else (the Ansible role's argv)
+//   state:hub/bootstrap/state.json
+//                        the applied profile, its choices and catalog revision, the last committed transaction and
+//                        plan digest, and the security floors this machine has seen (hubctl and each harness's
+//                        pinned minimumVersion), which only rise
+//   state:hub/bootstrap/requests/<hex>.json
+//                        the request each applied plan was made from, by plan digest (resume, drift and verify
+//                        re-plan from it); the plan itself is the engine's journal/<txID>.plan.json
+//
+// The journals stay the record of used preview nonces (the engine reads them).
+import {
+  bool,
+  Checker,
+  compareVersions,
+  digest,
+  ENROLLMENT_MODES,
+  findSecrets,
+  HARNESS_ORDER,
+  header,
+  int,
+  isRecord,
+  oneOf,
+  semver,
+  shape,
+  text,
+  validatePathRef,
+  validateSetupPreview,
+  type ArtifactManifest,
+  type EnrollmentMode,
+  type HarnessID,
+  type PathRef,
+  type Profile,
+  type Result,
+  type RootMapping,
+  type SetupPreview,
+} from "../bootstrap/contracts/index.ts"
+import { loadProfile } from "../bootstrap/profiles/versions.ts"
+import { nodeFs, type TxFs } from "../bootstrap/transaction/fs.ts"
+import { resolveTarget } from "../bootstrap/transaction/resolve.ts"
+import { errnoOf } from "../bootstrap/transaction/result.ts"
+
+export const SETUP_REQUEST_SCHEMA = "hub.setup-request"
+export const BOOTSTRAP_STATE_SCHEMA = "hub.bootstrap-state"
+
+/** What the user chose at preview, besides the profile; apply re-plans with exactly these. */
+export interface SetupChoices {
+  /** Inline (a planned enroll-machine, with `server`) or separate (`hubctl machine enroll`). */
+  readonly enrollment?: EnrollmentMode
+  /** --confirm-activation at preview: plan loading the services (apply needs the flag again). */
+  readonly activate?: boolean
+  /** --allow-downgrade at preview (apply needs the flag again). */
+  readonly allowDowngrade?: boolean
+  /** node.json settings for a launch node. */
+  readonly node?: { readonly workspaceRoots: readonly string[]; readonly slots?: number; readonly labels?: Readonly<Record<string, string>> }
+  /** One bounded verification launch. */
+  readonly launch?: { readonly harness: HarnessID; readonly workspace: PathRef }
+  /** The hub to enroll with inline. */
+  readonly server?: string
+  readonly machineName?: string
+}
+
+export interface SetupRequest {
+  readonly schema: typeof SETUP_REQUEST_SCHEMA
+  readonly version: 1
+  readonly preview: SetupPreview
+  readonly profile: Profile
+  readonly choices: SetupChoices
+}
+
+export interface Floors {
+  readonly hubctl?: string
+  readonly harnesses: Partial<Record<HarnessID, string>>
+}
+
+export interface BootstrapState {
+  readonly schema: typeof BOOTSTRAP_STATE_SCHEMA
+  readonly version: 1
+  /** The profile of the last committed apply. */
+  readonly profile?: Profile
+  readonly choices?: SetupChoices
+  /** The built-in catalog revision that profile was made from (profile.revision). */
+  readonly catalogRevision?: number
+  readonly txID?: string
+  readonly planDigest?: string
+  readonly floors: Floors
+}
+
+const EMPTY: BootstrapState = { schema: BOOTSTRAP_STATE_SCHEMA, version: 1, floors: { harnesses: {} } }
+
+function checkChoices(c: Checker, path: string, value: unknown): void {
+  const r = shape(c, path, value, [], ["enrollment", "activate", "allowDowngrade", "node", "launch", "server", "machineName"])
+  if (!r) return
+  oneOf(c, `${path}/enrollment`, r.enrollment, ENROLLMENT_MODES)
+  bool(c, `${path}/activate`, r.activate)
+  bool(c, `${path}/allowDowngrade`, r.allowDowngrade)
+  if (r.node !== undefined) {
+    const n = shape(c, `${path}/node`, r.node, ["workspaceRoots"], ["slots", "labels"])
+    if (n) {
+      if (!Array.isArray(n.workspaceRoots) || n.workspaceRoots.length > 64) c.add(`${path}/node/workspaceRoots`, "invalid_value", "expected a list of at most 64 paths")
+      else n.workspaceRoots.forEach((w, i) => text(c, `${path}/node/workspaceRoots/${i}`, w, 4096))
+      int(c, `${path}/node/slots`, n.slots, 1, 64)
+      if (n.labels !== undefined && (!isRecord(n.labels) || Object.values(n.labels).some((v) => typeof v !== "string"))) c.add(`${path}/node/labels`, "invalid_value", "labels are strings")
+    }
+  }
+  if (r.launch !== undefined) {
+    const l = shape(c, `${path}/launch`, r.launch, ["harness", "workspace"])
+    if (l) {
+      oneOf(c, `${path}/launch/harness`, l.harness, HARNESS_ORDER)
+      c.merge(`${path}/launch/workspace`, validatePathRef(l.workspace))
+    }
+  }
+  text(c, `${path}/server`, r.server, 2048)
+  text(c, `${path}/machineName`, r.machineName, 64)
+}
+
+/** A setup request read back from a file: validated, never cast; the profile is migrated to the current version. */
+export function validateSetupRequest(value: unknown): Result<SetupRequest> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "preview", "profile", "choices"])
+  if (!r) return c.result(undefined)
+  header(c, "", r, SETUP_REQUEST_SCHEMA, 1)
+  c.merge("/preview", validateSetupPreview(r.preview))
+  const profile = loadProfile(r.profile)
+  c.merge("/profile", profile)
+  checkChoices(c, "/choices", r.choices)
+  // The preview is checked by its own validator (its token field is a preview token, not a credential).
+  for (const p of findSecrets({ profile: r.profile, choices: r.choices })) c.add(p, "secret", "setup requests never carry credentials")
+  if (c.issues.length > 0) return c.result(undefined)
+  return c.result({ ...r, profile: profile.ok ? profile.value.profile : r.profile })
+}
+
+function validateState(value: unknown): Result<BootstrapState> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "floors"], ["profile", "choices", "catalogRevision", "txID", "planDigest"])
+  if (!r) return c.result(undefined)
+  header(c, "", r, BOOTSTRAP_STATE_SCHEMA, 1)
+  if (r.profile !== undefined) c.merge("/profile", loadProfile(r.profile))
+  if (r.choices !== undefined) checkChoices(c, "/choices", r.choices)
+  int(c, "/catalogRevision", r.catalogRevision, 1, 1_000_000)
+  text(c, "/txID", r.txID, 64, /^tx_[A-Za-z0-9_-]+$/)
+  if (r.planDigest !== undefined) digest(c, "/planDigest", r.planDigest)
+  const f = shape(c, "/floors", r.floors, ["harnesses"], ["hubctl"])
+  if (f) {
+    if (f.hubctl !== undefined) semver(c, "/floors/hubctl", f.hubctl)
+    const h = shape(c, "/floors/harnesses", f.harnesses, [], HARNESS_ORDER)
+    if (h) for (const id of HARNESS_ORDER) if (h[id] !== undefined) semver(c, `/floors/harnesses/${id}`, h[id])
+  }
+  for (const p of findSecrets(value)) c.add(p, "secret", "the bootstrap state never carries credentials")
+  return c.result(value)
+}
+
+const max = (a: string | undefined, b: string | undefined) => (a === undefined ? b : b === undefined ? a : compareVersions(a, b) >= 0 ? a : b)
+
+/** The floors after seeing a verified manifest: the highest of what was seen and what it pins for `target`. */
+export function raiseFloors(floors: Floors, manifest: Pick<ArtifactManifest, "minimumVersion" | "harnesses">, target: string): Floors {
+  const harnesses: Partial<Record<HarnessID, string>> = { ...floors.harnesses }
+  for (const pin of manifest.harnesses) if (pin.target === target && pin.minimumVersion) harnesses[pin.harness] = max(harnesses[pin.harness], pin.minimumVersion)
+  const hubctl = max(floors.hubctl, manifest.minimumVersion)
+  return { ...(hubctl ? { hubctl } : {}), harnesses }
+}
+
+const decode = (bytes: Uint8Array) => new TextDecoder().decode(bytes)
+
+export class BootstrapStateStore {
+  readonly statePath: string
+  private readonly requestDir: string
+
+  constructor(
+    private readonly roots: readonly RootMapping[],
+    private readonly fs: TxFs = nodeFs,
+  ) {
+    const state = this.resolve("hub/bootstrap/state.json")
+    this.statePath = state
+    this.requestDir = `${state.slice(0, state.lastIndexOf("/"))}/requests`
+  }
+
+  private resolve(rel: string): string {
+    const r = resolveTarget({ root: "state", rel }, this.roots, this.fs)
+    if (!r.ok) throw new Error(`the hub state directory is unusable: ${r.message}`)
+    return r.value
+  }
+
+  read(): BootstrapState {
+    const info = this.fs.lstat(this.resolve("hub/bootstrap/state.json"))
+    if (!info) return EMPTY
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(decode(this.fs.readFile(this.statePath)))
+    } catch {
+      throw new Error(`the bootstrap state ${this.statePath} cannot be read; inspect it before setting up again`)
+    }
+    const checked = validateState(parsed)
+    if (!checked.ok) throw new Error(`the bootstrap state ${this.statePath} is not valid (${checked.issues[0]!.message})`)
+    return checked.value
+  }
+
+  write(state: BootstrapState): void {
+    const checked = validateState(state)
+    if (!checked.ok) throw new Error(`refusing to write an invalid bootstrap state: ${checked.issues[0]!.path} ${checked.issues[0]!.message}`)
+    this.writeAtomic(this.resolve("hub/bootstrap/state.json"), state)
+  }
+
+  /** Records the request a plan was made from, under its plan digest. */
+  writeRequest(request: SetupRequest): void {
+    const checked = validateSetupRequest(request)
+    if (!checked.ok) throw new Error(`refusing to store an invalid setup request: ${checked.issues[0]!.message}`)
+    this.writeAtomic(this.resolve(`hub/bootstrap/requests/${request.preview.planDigest.slice("sha256:".length)}.json`), request)
+  }
+
+  readRequest(planDigest: string): SetupRequest | undefined {
+    if (!/^sha256:[0-9a-f]{64}$/.test(planDigest)) return undefined
+    const path = this.resolve(`hub/bootstrap/requests/${planDigest.slice("sha256:".length)}.json`)
+    if (!this.fs.lstat(path)) return undefined
+    try {
+      const r = validateSetupRequest(JSON.parse(decode(this.fs.readFile(path))))
+      return r.ok && r.value.preview.planDigest === planDigest ? r.value : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  private writeAtomic(path: string, value: unknown): void {
+    const dir = path.slice(0, path.lastIndexOf("/"))
+    if (!this.fs.lstat(dir)) this.fs.mkdirp(dir, 0o700)
+    else if (this.fs.lstat(dir)?.kind !== "directory") throw new Error(`${dir} is not a directory`)
+    const tmp = `${path}.tmp`
+    try {
+      if (this.fs.lstat(tmp)) this.fs.unlink(tmp)
+      this.fs.writeExclusive(tmp, `${JSON.stringify(value, null, 2)}\n`, 0o600)
+      this.fs.rename(tmp, path)
+      this.fs.fsyncDir(dir)
+    } catch (error) {
+      try {
+        if (this.fs.lstat(tmp)) this.fs.unlink(tmp)
+      } catch {}
+      throw errnoOf(error) ? new Error(`cannot write ${path} (${errnoOf(error)})`) : error
+    }
+  }
+}

package/packages/cli/src/setup/user-bin.ts

@@ -0,0 +1,39 @@
+// The user-bin link rule (contract §7.6 A6, HBS-12 E4), shared by the setup's harness links (contributors.ts) and
+// the OpenCode plugin's `hub` link (src/spoke/launchers.ts): hub links a command into user-bin (~/.local/bin) only
+// when nothing is there or what is there is a link of hub's own, and only when no other command of that name is on
+// PATH. A user's binary is never shadowed or replaced. Pure: callers read the facts (lstat, readlink, PATH).
+
+/** What is at the link path now, not following a final symlink. */
+export type UserBinEntry = "missing" | "file" | "directory" | "symlink" | "other"
+
+/**
+ * - in-place: the link is already there, pointing at the target.
+ * - create: nothing there: link it.
+ * - replace: a link of hub's own pointing elsewhere: re-point it.
+ * - foreign: something of the user's is there: leave it.
+ * - shadowed: another command of that name comes first on PATH: leave it.
+ */
+export type UserBinLinkDecision = "in-place" | "create" | "replace" | "foreign" | "shadowed"
+
+export interface UserBinLinkFacts {
+  readonly entry: UserBinEntry
+  /** The absolute path a symlink at the link path points to. */
+  readonly pointsTo?: string
+  /** The absolute path the link should point to. */
+  readonly target: string
+  /** The link path itself. */
+  readonly linkPath: string
+  /** Whether a link pointing here is hub's own (its harness directory, its launchers). */
+  readonly hubOwned: (pointsTo: string) => boolean
+  /** The first command of that name on PATH, as found (not followed); undefined when none. */
+  readonly foundOnPath?: string
+}
+
+export function userBinLinkDecision(facts: UserBinLinkFacts): UserBinLinkDecision {
+  const { entry, pointsTo } = facts
+  if (entry === "symlink" && pointsTo === facts.target) return "in-place"
+  const hubOwned = entry === "symlink" && pointsTo !== undefined && facts.hubOwned(pointsTo)
+  if (entry !== "missing" && !hubOwned) return "foreign"
+  if (facts.foundOnPath !== undefined && facts.foundOnPath !== facts.linkPath) return "shadowed"
+  return entry === "missing" ? "create" : "replace"
+}

package/packages/cli/src/spoke-services.ts

@@ -0,0 +1,109 @@
+// `hub claude-code install | uninstall | status` and `hub codex-spoke install | uninstall | status`: the harness
+// spokes' per-user services (`hub claude-code daemon`, `hub codex-spoke serve`) as a launchd agent (macOS) or a
+// systemd user unit (Linux), rendered from the templates embedded in this program the way `hub node install` writes
+// the node's (node.ts). `hub claude` and `hub codex` start these processes on demand; installed, they keep running, so the hub
+// can place claude-code and codex launches on the machine without a wrapper run first. Like `hub node install`,
+// nothing here starts a process: loading, unloading and inspecting the service are printed for the user, never run.
+import path from "node:path"
+import { claudeBinary, codexBinary, findExecutable } from "../../node/src/harnesses.ts"
+import { readSpokeCredentials } from "../../node/src/config.ts"
+import { socketPath } from "../../claude-code/src/paths.ts"
+import { daemonSocketPath, readServicePid } from "../../codex/src/paths.ts"
+import type { Env } from "./credentials"
+import { installService, serviceCheckLines, serviceState, serviceStateLine, uninstallService, type ExtraEnvironment, type NodeCommandOutput, type NodeIo, type ServiceSpec, type ServiceState } from "./node"
+
+/** The subcommands `hub claude-code` and `hub codex-spoke` take for their service (the others are the spokes' own). */
+export const SERVICE_VERBS = ["install", "uninstall", "status"] as const
+export type ServiceVerb = (typeof SERVICE_VERBS)[number]
+export const isServiceVerb = (verb: string | undefined): verb is ServiceVerb => (SERVICE_VERBS as readonly string[]).includes(verb ?? "")
+
+/** Where config.json and the hub state dir are (shared by every hub spoke). */
+const HUB_PLACES = ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR"] as const
+
+export const CLAUDE_CODE_SERVICE: ServiceSpec = {
+  service: "claude-code",
+  command: "hub claude-code",
+  label: "io.github.huynle.hub-claude-code",
+  unit: "hub-claude-code.service",
+  log: "claude-code.log",
+  // The hooks find the daemon by HUB_CLAUDE_SOCKET / HUB_STATE_DIR: the service must listen where they look.
+  carried: [...HUB_PLACES, "HUB_CLAUDE_SOCKET", "HUB_CLAUDE_BIN"],
+  elsewhere: "Run `hub claude-code daemon` under your own service manager (or let `hub claude` start it)",
+}
+
+export const CODEX_SPOKE_SERVICE: ServiceSpec = {
+  service: "codex-spoke",
+  command: "hub codex-spoke",
+  label: "io.github.huynle.hub-codex-spoke",
+  unit: "hub-codex-spoke.service",
+  log: "codex-spoke.log",
+  // HUB_CODEX_CONFIG (one override per line) is not carried: a unit's Environment= cannot hold several lines.
+  carried: [...HUB_PLACES, "CODEX_HOME", "HUB_CODEX_BIN", "HUB_CODEX_DAEMON_SOCKET"],
+  elsewhere: "Run `hub codex-spoke serve` under your own service manager (or let `hub codex` start it)",
+}
+
+const SPECS = { "claude-code": CLAUDE_CODE_SERVICE, "codex-spoke": CODEX_SPOKE_SERVICE } as const
+
+/** The codex-spoke unit runs the Codex `hubctl setup` installed (HUB_CODEX_BIN), unless the shell names another. */
+const codexEnvironment: ExtraEnvironment = (io): Record<string, string> => {
+  const bin = codexBinary(io.env, io.home)
+  return path.isAbsolute(bin) && !io.env.HUB_CODEX_BIN ? { HUB_CODEX_BIN: bin } : {}
+}
+const EXTRA: Partial<Record<keyof typeof SPECS, ExtraEnvironment>> = { "codex-spoke": codexEnvironment }
+export type SpokeServiceName = keyof typeof SPECS
+export const spokeServiceSpec = (name: SpokeServiceName): ServiceSpec => SPECS[name]
+
+/** Why the installed service would not do anything yet (never the token). */
+function readiness(env: Env, home: string): string[] {
+  return readSpokeCredentials(env, home) ? [] : ["this machine is not enrolled with a hub yet (no machine token in config.json): enroll it with `hubctl machine enroll --server <hub URL>`; until then the service exits and is restarted"]
+}
+
+export function installSpokeService(name: SpokeServiceName, io: NodeIo, options: { readonly dryRun: boolean }): NodeCommandOutput {
+  return installService(SPECS[name], io, options, readiness(io.env, io.home), EXTRA[name])
+}
+
+export function uninstallSpokeService(name: SpokeServiceName, io: NodeIo, options: { readonly dryRun: boolean }): NodeCommandOutput {
+  return uninstallService(SPECS[name], io, options)
+}
+
+export interface SpokeServiceStatus {
+  readonly service: ServiceState
+  readonly enrolled?: { readonly server: string; readonly machineID?: string }
+  /** The harness CLI as this shell finds it (the service looks on its own PATH, see the unit). */
+  readonly harness: { readonly bin: string; readonly found?: string }
+  /** claude-code: the daemon's socket (hooks look there). */
+  readonly socket?: string
+  /** codex-spoke: the running service's pid (its pid file), and the Codex daemon socket it attaches to. */
+  readonly running?: number
+  readonly daemonSocket?: string
+}
+
+export function spokeServiceStatus(name: SpokeServiceName, io: NodeIo): SpokeServiceStatus {
+  const credentials = readSpokeCredentials(io.env, io.home)
+  const bin = name === "claude-code" ? claudeBinary(io.env, io.home) : codexBinary(io.env, io.home)
+  const found = findExecutable(bin, io.env)
+  const base = {
+    service: serviceState(SPECS[name], io, EXTRA[name]),
+    ...(credentials ? { enrolled: { server: credentials.server, ...(credentials.machineID ? { machineID: credentials.machineID } : {}) } } : {}),
+    harness: { bin, ...(found ? { found } : {}) },
+  }
+  if (name === "claude-code") return { ...base, socket: socketPath(io.env, io.home) }
+  const running = readServicePid(io.env, io.home)
+  const daemonSocket = daemonSocketPath(io.env, io.home)
+  return { ...base, ...(running !== undefined ? { running } : {}), ...(daemonSocket ? { daemonSocket } : {}) }
+}
+
+export function spokeServiceStatusText(name: SpokeServiceName, status: SpokeServiceStatus): string {
+  const spec = SPECS[name]
+  const lines = [serviceStateLine(spec, status.service)]
+  lines.push(status.enrolled ? `machine: enrolled with ${status.enrolled.server}${status.enrolled.machineID ? ` as ${status.enrolled.machineID}` : ""}` : "machine: not enrolled (enroll it with `hubctl machine enroll --server <hub URL>`)")
+  const what = name === "claude-code" ? "Claude Code CLI" : "Codex CLI"
+  lines.push(status.harness.found ? `${what}: ${status.harness.found}` : `${what}: ${status.harness.bin} not found on this shell's PATH (no hub launches${name === "claude-code" ? "" : " of new threads"} until it is)`)
+  if (status.socket) lines.push(`daemon socket: ${status.socket}`)
+  if (name === "codex-spoke") {
+    lines.push(status.running !== undefined ? `running: pid ${status.running}` : "running: no")
+    lines.push(`Codex daemon socket: ${status.daemonSocket ?? "off"}`)
+  }
+  lines.push(...serviceCheckLines(status.service))
+  return lines.join("\n")
+}

package/packages/cli/src/watch.ts

@@ -0,0 +1,28 @@
+// `hub watch`: GET /api/agent/watch (SSE, through the SDK) printed as JSON lines, one per event, until interrupted.
+// Heartbeats are skipped (the SDK does). The hub closing the stream or the stream breaking is an error.
+import { HubTransportError } from "../../sdk/src/index.ts"
+import type { Credentials } from "./credentials"
+import { CliError, cliError, clientFor, EXIT } from "./http"
+
+/** One compact JSON line per event (non-JSON data is printed as is). */
+const line = (data: string) => {
+  try {
+    return JSON.stringify(JSON.parse(data))
+  } catch {
+    return data
+  }
+}
+
+const AGAIN = "Run `hub watch` again"
+
+export async function watch(credentials: Credentials, options: { blocked?: boolean; session?: string }, write: (line: string) => void, signal?: AbortSignal): Promise<void> {
+  try {
+    for await (const event of clientFor(credentials).watch({ ...options, ...(signal ? { signal } : {}) })) write(`${line(event.data)}\n`)
+  } catch (cause) {
+    if (signal?.aborted) return
+    if (cause instanceof HubTransportError && cause.kind === "stream") throw new CliError(EXIT.other, cause.message, AGAIN)
+    throw cliError(cause, credentials)
+  }
+  if (signal?.aborted) return
+  throw new CliError(EXIT.other, "the watch stream ended (the hub closed it)", AGAIN)
+}

package/packages/codex/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@huynle/hub-codex",
+  "version": "0.7.2",
+  "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"