@huynle/hub 0.7.1 → 0.7.3

package/packages/cli/src/messaging.ts

@@ -0,0 +1,108 @@
+// The messaging verbs' helpers (design §3): text arguments (or "-" for stdin) and the short text of what the hub
+// answers to msg, ask, reply, decline, inbox and mute. The shapes are packages/sdk's types (message-routes.ts).
+import type { AgentMessage, Asked, Inbox, MessageDelivery, Party, Replied, Sent } from "../../sdk/src/index.ts"
+import { UsageError } from "./args"
+import { oneLine } from "./format"
+
+/** A text argument: the value, or all of stdin for "-" (one trailing newline dropped); never empty. */
+export async function textArg(value: string, stdin: (() => Promise<string>) | undefined, what = "text"): Promise<string> {
+  let text = value
+  if (value === "-") {
+    if (!stdin) throw new UsageError(`cannot read the ${what} from stdin here`)
+    text = (await stdin()).replace(/\r?\n$/, "")
+  }
+  if (!text.trim()) throw new UsageError(`the ${what} is empty`)
+  return text
+}
+
+/** `@name`, the session ID, `@me`, or the app token. */
+export function partyText(party: Party): string {
+  if (party.kind === "session") return party.name ? `@${party.name.replace(/^@+/, "")}` : party.sessionID
+  if (party.kind === "user") return "@me"
+  return `app ${party.label ?? party.tokenID}`
+}
+
+const DELIVERY: Record<MessageDelivery, string> = {
+  turn: "delivered (started a turn)",
+  steer: "delivered (into the running turn)",
+  queued: "queued (read at its next turn)",
+  retained: "retained (held until its open question is answered)",
+  pending: "pending (offline; delivered when it reconnects, for 24 h)",
+}
+
+export const deliveryText = (delivery: MessageDelivery | undefined): string => (delivery ? (DELIVERY[delivery] ?? delivery) : "stored (in its inbox)")
+
+/** `to @@reviewer → @api` when the address is not the recipient's own name. */
+function toText(message: AgentMessage): string {
+  const recipient = partyText(message.recipient)
+  return message.to === recipient || message.to === (message.recipient as { sessionID?: string }).sessionID ? recipient : `${message.to} → ${recipient}`
+}
+
+/** `msg_… to @web-work: delivered (started a turn)` */
+export const sentText = ({ message, delivery }: Sent): string => `${message.kind} ${message.id} to ${toText(message)}: ${deliveryText(delivery)}`
+
+/** How long an ask stays open when --expires is not given (the hub's default). */
+export const ASK_EXPIRES_DEFAULT_S = 24 * 60 * 60
+
+const UNIT_S: Record<string, number> = { "": 1, s: 1, m: 60, h: 3600, d: 86400 }
+
+/** Seconds from `90`, `30s`, `5m`, `1.5h` or `1d`. */
+export function durationArg(value: string, flag: string): number {
+  const match = /^(\d+(?:\.\d+)?)([smhd]?)$/.exec(value)
+  if (!match) throw new UsageError(`${flag} takes seconds or a duration like 30s, 5m, 2h, 1d (got "${value}")`)
+  return Number(match[1]) * UNIT_S[match[2]!]!
+}
+
+const iso = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z")
+
+/** What an ask came to, its text, and the exit code: answered 0, declined 1, open after a wait 1, expired 8. */
+export function askOutcome(asked: Asked, waited: number | undefined): { text: string; exit: number; note?: string } {
+  const { message, answer } = asked
+  const head = sentText(asked)
+  const by = answer ? partyText(answer.from) : partyText(message.recipient)
+  switch (message.state) {
+    case "answered":
+      return { text: `${head}\nanswer ${answer?.id ?? "?"} from ${by}:\n${answer?.text ?? ""}`, exit: 0 }
+    case "declined":
+      return { text: `${head}\ndeclined by ${by}: ${answer?.text ?? ""}`, exit: 1 }
+    case "expired":
+      return { text: `${head}\nexpired without an answer`, exit: 8 }
+    default: {
+      const until = message.expiresAt !== undefined ? `open until ${iso(message.expiresAt)}` : "open"
+      const text = `${head}\n${until}; the answer shows in \`hub inbox\``
+      if (waited === undefined) return { text, exit: 0 }
+      return { text, exit: 1, note: `no answer within ${waited} s; ${message.id} is still open (see \`hub inbox\`)` }
+    }
+  }
+}
+
+/** `reply msg_r to @api: delivered (started a turn) (answers msg_1)` */
+export const repliedText = (replied: Replied): string => `${sentText(replied)} (answers ${replied.original.id})`
+
+/** `declined msg_1 (decline msg_d to @api: queued …)` */
+export const declinedText = (replied: Replied): string => `declined ${replied.original.id} (${sentText(replied)})`
+
+/** Open asks to answer (with how), the caller's own open asks, recent messages, mutes. */
+export function inboxText(inbox: Inbox): string {
+  const lines: string[] = []
+  const until = (m: AgentMessage) => (m.expiresAt !== undefined ? `  (open until ${iso(m.expiresAt)})` : "")
+  if (inbox.asks.length) {
+    lines.push("asks to answer:")
+    for (const m of inbox.asks) {
+      lines.push(`  ${m.id} from ${partyText(m.from)}  ${iso(m.at)}: ${oneLine(m.text, 200)}${until(m)}`)
+      lines.push(`    ↩ hub reply ${m.id} "…" · hub decline ${m.id} --why "…"`)
+    }
+  }
+  if (inbox.waiting.length) {
+    lines.push("waiting for answers:")
+    for (const m of inbox.waiting) lines.push(`  ${m.id} to ${toText(m)}  ${iso(m.at)}: ${oneLine(m.text, 200)}${until(m)}`)
+  }
+  if (inbox.messages.length) {
+    lines.push("messages:")
+    for (const m of inbox.messages) lines.push(`  ${m.id} ${m.kind} from ${partyText(m.from)}  ${iso(m.at)}${m.replyTo ? ` (re ${m.replyTo})` : ""}: ${oneLine(m.text, 200)}`)
+  }
+  if (inbox.muted.length) lines.push(mutedText(inbox.muted))
+  return lines.length ? lines.join("\n") : "inbox empty"
+}
+
+export const mutedText = (muted: readonly string[]): string => `muted: ${muted.length ? muted.join(", ") : "nobody"}`

package/packages/cli/src/node.ts

@@ -0,0 +1,279 @@
+// `hub node run | install | uninstall | status` (design §6.3; decision znbg8xa5 #6): `run` is the node daemon
+// (packages/node runNode) until SIGINT/SIGTERM. `install` renders the service template embedded in this program (a
+// launchd agent on macOS, a systemd user unit on Linux; renderServiceUnit, the same renderer `hubctl setup` uses)
+// with the argv of what runs this command (programLayout: the standalone hubctl itself, or the runtime and the CLI
+// entry), writes the file, and prints the launchctl / systemctl commands that load it. Nothing here starts a process:
+// loading, unloading and inspecting the service are always left to the user (printed, never run). --dry-run
+// prints the file instead of writing it. The same machinery (ServiceSpec) installs the harness spokes' services
+// (spoke-services.ts: `hub claude-code install`, `hub codex-spoke install`).
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { nodeConfigPath, readNodeConfig, readSpokeCredentials, runNode } from "../../node/src/index.ts"
+import { renderServiceUnit } from "./bootstrap/adapters/node-services/render.ts"
+import { isAbsolutePath, programLayout, type ServiceID, type ServiceManagerID } from "./bootstrap/contracts/index.ts"
+import type { Env } from "./credentials"
+import { CliError, EXIT } from "./http"
+
+export const NODE_LABEL = "io.github.huynle.hub-node"
+export const NODE_UNIT = "hub-node.service"
+
+/** A per-user hub service installed from the embedded templates (hub node, and the harness spokes' services). */
+export interface ServiceSpec {
+  /** The service (its embedded template and the subcommand the unit runs). */
+  readonly service: ServiceID
+  /** The CLI command that installs it ("hub node"), for the written files' header and messages. */
+  readonly command: string
+  /** The launchd label; the macOS template is scripts/<label>.plist. */
+  readonly label: string
+  /** The systemd unit name; the Linux template is scripts/<unit>. */
+  readonly unit: string
+  /** Its log file in ~/.local/state/hub (launchd). */
+  readonly log: string
+  /** Settings the service must see as this shell does (where its config and state live). */
+  readonly carried: readonly string[]
+  /** What to tell users on platforms without launchd or systemd. */
+  readonly elsewhere: string
+}
+
+export const NODE_SERVICE: ServiceSpec = {
+  service: "node",
+  command: "hub node",
+  label: NODE_LABEL,
+  unit: NODE_UNIT,
+  log: "node.log",
+  carried: ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME"],
+  elsewhere: "Run `hub node run` under your own service manager",
+}
+
+/** What runs the CLI: the runtime binary and the CLI's entry file. */
+export interface Program {
+  readonly execPath: string
+  readonly entry: string
+}
+
+export interface NodeIo {
+  readonly env: Env
+  readonly home: string
+  readonly platform: NodeJS.Platform
+  readonly uid: number
+  readonly program: Program
+}
+
+export type ServiceKind = "launchd" | "systemd"
+
+export interface NodeService {
+  readonly kind: ServiceKind
+  /** Where the unit file goes. */
+  readonly file: string
+  /** Its content, as install writes it. */
+  readonly content: string
+  /** Directories the service needs (its log). */
+  readonly dirs: readonly string[]
+  /** Commands that load (or reload) it, for the user to run. */
+  readonly load: readonly string[]
+  /** Commands that stop it once the file is removed. */
+  readonly unload: readonly string[]
+  /** How to see its state and logs. */
+  readonly check: readonly string[]
+  /** Settings this shell has that the unit cannot carry (not an absolute path). */
+  readonly skipped: readonly string[]
+}
+
+/** Extra settings a service's unit carries beyond the shell's (spoke-services.ts: the hub-installed Codex). */
+export type ExtraEnvironment = (io: NodeIo) => Readonly<Record<string, string>>
+
+/** This process as a Program: the runtime and the real path of the entry it runs. */
+export function currentProgram(): Program {
+  const entry = process.argv[1] ?? ""
+  let real = entry
+  try {
+    real = realpathSync(entry)
+  } catch {}
+  return { execPath: process.execPath, entry: real }
+}
+
+/** A path quoted for sh (printed commands). */
+const sh = (word: string) => `'${word.replaceAll("'", `'\\''`)}'`
+
+/** The settings this shell has that the unit carries (absolute, single-line paths only), and those it cannot. */
+function carried(spec: ServiceSpec, io: NodeIo, extra?: ExtraEnvironment): { environment: Record<string, string>; skipped: string[] } {
+  const environment: Record<string, string> = { ...(extra?.(io) ?? {}) }
+  const skipped: string[] = []
+  for (const key of spec.carried) {
+    const value = io.env[key]
+    if (!value) continue
+    if (isAbsolutePath(value)) environment[key] = value
+    else skipped.push(key)
+  }
+  return { environment, skipped }
+}
+
+/** The unit's text: the embedded template rendered with this program's argv (one word per <string> / ExecStart word). */
+function render(spec: ServiceSpec, io: NodeIo, manager: ServiceManagerID, extra?: ExtraEnvironment): { content: string; skipped: string[] } {
+  const { environment, skipped } = carried(spec, io, extra)
+  const r = renderServiceUnit({ service: spec.service, manager, layout: programLayout(io.program), home: io.home, environment, writtenBy: spec.command })
+  if (!r.ok) throw new CliError(EXIT.usage, `cannot write the ${spec.command} service: ${r.issues.map((i) => `${i.path ? `${i.path}: ` : ""}${i.message}`).join("; ")}`)
+  return { content: r.value.text, skipped }
+}
+
+function launchd(spec: ServiceSpec, io: NodeIo, extra?: ExtraEnvironment): NodeService {
+  const file = path.join(io.home, "Library", "LaunchAgents", `${spec.label}.plist`)
+  const domain = `gui/${io.uid}`
+  const { content, skipped } = render(spec, io, "launchd", extra)
+  const log = path.join(io.home, ".local", "state", "hub")
+  return {
+    kind: "launchd",
+    file,
+    content,
+    skipped,
+    dirs: [log],
+    load: [`launchctl bootout ${domain}/${spec.label} 2>/dev/null || true`, `launchctl bootstrap ${domain} ${sh(file)}`],
+    unload: [`launchctl bootout ${domain}/${spec.label}`],
+    check: [`launchctl print ${domain}/${spec.label}`, `tail -f ${sh(path.join(log, spec.log))}`],
+  }
+}
+
+function systemd(spec: ServiceSpec, io: NodeIo, extra?: ExtraEnvironment): NodeService {
+  const unit = spec.unit
+  const dir = path.join(io.env.XDG_CONFIG_HOME || path.join(io.home, ".config"), "systemd", "user")
+  const file = path.join(dir, unit)
+  const { content, skipped } = render(spec, io, "systemd-user", extra)
+  return {
+    kind: "systemd",
+    file,
+    content,
+    skipped,
+    dirs: [],
+    load: ["systemctl --user daemon-reload", `systemctl --user enable --now ${unit}`, `systemctl --user restart ${unit}   # when it was already running`, 'loginctl enable-linger "$USER"   # optional: keep it running while you are logged out'],
+    unload: [`systemctl --user stop ${unit}`, `rm -f ${sh(path.join(dir, "default.target.wants", unit))}`, "systemctl --user daemon-reload"],
+    check: [`systemctl --user status ${unit}`, `journalctl --user -u ${unit} -f`],
+  }
+}
+
+/** `spec`'s service for this platform; unsupported (exit 7) elsewhere. */
+export function serviceFor(spec: ServiceSpec, io: NodeIo, extra?: ExtraEnvironment): NodeService {
+  if (io.platform === "darwin") return launchd(spec, io, extra)
+  if (io.platform === "linux") return systemd(spec, io, extra)
+  throw new CliError(EXIT.unavailable, `${spec.command} install supports macOS (launchd) and Linux (systemd), not ${io.platform}`, spec.elsewhere)
+}
+
+/** The node's service for this platform; unsupported (exit 7) elsewhere. */
+export const nodeService = (io: NodeIo): NodeService => serviceFor(NODE_SERVICE, io)
+
+const readText = (file: string): string | undefined => {
+  try {
+    return readFileSync(file, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
+/** Why the installed service would not do anything yet (never the token). */
+export function readinessProblems(env: Env, home: string): string[] {
+  const problems: string[] = []
+  if (!readSpokeCredentials(env, home)) problems.push("this machine is not enrolled with a hub yet (no machine token in config.json): enroll it with `hubctl machine enroll --server <hub URL>`")
+  const file = nodeConfigPath(env, home)
+  const { config, problems: found } = readNodeConfig(file)
+  problems.push(...found.map((p) => `${file}: ${p}`))
+  if (config.workspaceRoots.length === 0) problems.push(`${file} lists no workspaceRoots, so the service would exit 78; add e.g. {"workspaceRoots": ["${home}/projects"]}`)
+  return problems
+}
+
+const commands = (title: string, lines: readonly string[]) => [title, ...lines.map((l) => `  ${l}`)].join("\n")
+const NOT_RUN = "(not run by hub; run them yourself)"
+
+export interface NodeCommandOutput {
+  readonly stdout: string
+  readonly warnings: readonly string[]
+}
+
+export function installNode(io: NodeIo, options: { readonly dryRun: boolean }): NodeCommandOutput {
+  return installService(NODE_SERVICE, io, options, readinessProblems(io.env, io.home))
+}
+
+/** Writes `spec`'s service file (or prints it, dry run) and prints the commands that load it; `warnings` go to stderr. */
+export function installService(spec: ServiceSpec, io: NodeIo, options: { readonly dryRun: boolean }, given: readonly string[], extra?: ExtraEnvironment): NodeCommandOutput {
+  const service = serviceFor(spec, io, extra)
+  const warnings = [...given, ...service.skipped.map((key) => `${key} is not an absolute path, so the service does not carry it`)]
+  const load = commands(`Load it ${NOT_RUN}:`, service.load)
+  if (options.dryRun) return { stdout: `would write ${service.file}:\n\n${service.content}\n${load}`, warnings }
+  const current = readText(service.file)
+  for (const dir of service.dirs) mkdirSync(dir, { recursive: true })
+  if (current === service.content) return { stdout: `${service.file} is up to date\n${load}`, warnings }
+  mkdirSync(path.dirname(service.file), { recursive: true })
+  writeFileSync(service.file, service.content, { mode: 0o644 })
+  return { stdout: `${current === undefined ? "wrote" : "updated"} ${service.file}\n${load}`, warnings }
+}
+
+export function uninstallNode(io: NodeIo, options: { readonly dryRun: boolean }): NodeCommandOutput {
+  return uninstallService(NODE_SERVICE, io, options)
+}
+
+/** Removes `spec`'s service file (dry run: says it would) and prints the commands that stop it. */
+export function uninstallService(spec: ServiceSpec, io: NodeIo, options: { readonly dryRun: boolean }): NodeCommandOutput {
+  const service = serviceFor(spec, io)
+  if (!existsSync(service.file)) return { stdout: `not installed (no ${service.file})`, warnings: [] }
+  const stop = commands(`Stop the service ${NOT_RUN}:`, service.unload)
+  if (options.dryRun) return { stdout: `would remove ${service.file}\n${stop}`, warnings: [] }
+  rmSync(service.file)
+  return { stdout: `removed ${service.file}\n${stop}`, warnings: [] }
+}
+
+export type ServiceState = { readonly kind: ServiceKind; readonly file: string; readonly installed: boolean; readonly current: boolean; readonly check: readonly string[] } | { readonly kind: "unsupported"; readonly platform: string }
+
+/** Whether `spec`'s service file is there and is what install would write now. */
+export function serviceState(spec: ServiceSpec, io: NodeIo, extra?: ExtraEnvironment): ServiceState {
+  try {
+    const s = serviceFor(spec, io, extra)
+    const text = readText(s.file)
+    return { kind: s.kind, file: s.file, installed: text !== undefined, current: text === s.content, check: s.check }
+  } catch {
+    return { kind: "unsupported", platform: io.platform }
+  }
+}
+
+/** The status lines about `spec`'s service file. */
+export function serviceStateLine(spec: ServiceSpec, s: ServiceState): string {
+  if (s.kind === "unsupported") return `service: ${spec.command} install does not support ${s.platform}`
+  if (!s.installed) return `service: not installed (${spec.command} install)`
+  return `service: installed, ${s.current ? "up to date" : `differs from what this CLI writes (${spec.command} install updates it)`} (${s.file})`
+}
+
+/** How to see an installed service (not run). */
+export const serviceCheckLines = (s: ServiceState): string[] => (s.kind !== "unsupported" && s.installed ? [commands(`See the service ${NOT_RUN}:`, s.check)] : [])
+
+export interface NodeStatus {
+  readonly service: ServiceState
+  readonly enrolled?: { readonly server: string; readonly machineID?: string }
+  readonly config: { readonly file: string; readonly workspaceRoots: readonly string[]; readonly slots: number; readonly labels: Readonly<Record<string, string>>; readonly problems: readonly string[] }
+}
+
+export function nodeStatus(io: NodeIo): NodeStatus {
+  const service = serviceState(NODE_SERVICE, io)
+  const credentials = readSpokeCredentials(io.env, io.home)
+  const file = nodeConfigPath(io.env, io.home)
+  const { config, problems } = readNodeConfig(file)
+  return {
+    service,
+    ...(credentials ? { enrolled: { server: credentials.server, ...(credentials.machineID ? { machineID: credentials.machineID } : {}) } } : {}),
+    config: { file, workspaceRoots: config.workspaceRoots, slots: config.slots, labels: config.labels, problems },
+  }
+}
+
+export function nodeStatusText(status: NodeStatus): string {
+  const s = status.service
+  const lines: string[] = [serviceStateLine(NODE_SERVICE, s)]
+  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 c = status.config
+  lines.push(`node.json: ${c.file}`, `  workspace roots: ${c.workspaceRoots.length ? c.workspaceRoots.join(", ") : "none (the node would exit 78)"}`, `  slots: ${c.slots}`)
+  const labels = Object.entries(c.labels).map(([k, v]) => `${k}=${v}`)
+  if (labels.length) lines.push(`  labels: ${labels.join(" ")}`)
+  for (const p of c.problems) lines.push(`  problem: ${p}`)
+  lines.push(...serviceCheckLines(s))
+  return lines.join("\n")
+}
+
+/** `hub node run`: the daemon until `signal` aborts; runNode's exit code. */
+export function runNodeCommand(io: { readonly env: Env; readonly home: string; readonly signal?: AbortSignal; stderr(s: string): void }): Promise<number> {
+  return runNode({ env: io.env, home: io.home, signal: io.signal ?? new AbortController().signal, log: (line) => io.stderr(`[hub node] ${line}\n`) })
+}

package/packages/cli/src/openshell.ts

@@ -0,0 +1,166 @@
+// `hub node openshell check` (design §6.4, decision lk6gn3u7, spike report gut64rwq): can this node run sandboxed
+// launches? It reads node.json's `openshell` section and asks the openshell CLI only read-only questions (--version,
+// status, workspace list, provider list), in the order a launch needs them. It never creates or changes anything:
+// for a missing workspace it prints the command to run. A `fail` is something that stops sandboxed launches (exit 1);
+// a `warn` is something that likely makes them useless (no model provider, an image the gateway cannot pull).
+import { nodeConfigPath, readNodeConfig } from "../../node/src/index.ts"
+import { OpenShellCli, OpenShellError, OPENSHELL_WORKSPACE, SUPPORTED_VERSIONS, type OpenShellClient } from "../../runtime-openshell/src/cli.ts"
+import { DEFAULT_PROFILE } from "../../runtime-openshell/src/profiles.ts"
+import { DEFAULT_SANDBOX_IMAGE } from "../../runtime-openshell/src/runtime.ts"
+import type { Env } from "./credentials"
+
+export type CheckStatus = "ok" | "warn" | "fail" | "skip"
+
+export interface CheckItem {
+  /** config, profiles, default-providers, image, cli, gateway, workspace, providers */
+  readonly check: string
+  readonly status: CheckStatus
+  readonly message: string
+  readonly hint?: string
+}
+
+export interface OpenShellCheckReport {
+  /** No `fail` (warnings allowed). */
+  readonly ok: boolean
+  /** The node.json read. */
+  readonly file: string
+  readonly checks: readonly CheckItem[]
+}
+
+export interface OpenShellCheckOptions {
+  readonly env: Env
+  readonly home: string
+  /** The openshell executable (default "openshell" on PATH). */
+  readonly binary?: string
+  /** Instead of the CLI (tests). */
+  readonly client?: OpenShellClient
+}
+
+const EXAMPLE = `{"openshell": {"enabled": true, "image": "ghcr.io/<owner>/hub-sandbox:<tag>", "profiles": {"default": {"providers": ["<provider>"]}}}}`
+const errorText = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
+const item = (check: string, status: CheckStatus, message: string, hint?: string): CheckItem => ({ check, status, message, ...(hint ? { hint } : {}) })
+
+/** Why an image reference likely cannot be pulled by OpenShell's vm driver (HTTPS registries only); undefined: fine. */
+export function imageConcern(image: string): string | undefined {
+  const slash = image.indexOf("/")
+  const first = slash < 0 ? "" : image.slice(0, slash)
+  const hasHost = first === "localhost" || first.includes(".") || first.includes(":")
+  if (!hasHost) return `${image} has no registry host, so the gateway looks for it on Docker Hub; OpenShell's vm driver does not use local Docker images, so it must be published to an HTTPS registry`
+  const host = first.replace(/:\d+$/, "")
+  if (host === "localhost" || /^127\./.test(host) || host === "[::1]" || host.endsWith(".local")) return `${image} is on a local registry; OpenShell's vm driver pulls over HTTPS only and refuses plain-http local registries`
+  return undefined
+}
+
+/** The checks node.json alone can answer. */
+function configChecks(env: Env, home: string): { file: string; checks: CheckItem[]; providers: Map<string, string[]>; usable: boolean; gateway?: string } {
+  const file = nodeConfigPath(env, home)
+  const { config, problems } = readNodeConfig(file)
+  const checks: CheckItem[] = []
+  const providers = new Map<string, string[]>()
+  const openshell = config.openshell
+  const configProblems = problems.filter((p) => !/^openshell\.profiles\.[^:]+: unsupported \(/.test(p))
+  for (const p of configProblems) checks.push(item("config", "fail", p))
+  if (!openshell) {
+    checks.push(item("config", "fail", `${file} has no openshell section`, `add one, e.g. ${EXAMPLE}`))
+    return { file, checks, providers, usable: false }
+  }
+  if (configProblems.length === 0) {
+    if (openshell.enabled) checks.push(item("config", "ok", `${file}: openshell enabled${openshell.gateway ? ` (gateway ${openshell.gateway})` : ""}`))
+    else checks.push(item("config", "warn", `${file}: openshell.enabled is not true, so the node does not offer sandboxes`, 'set "enabled": true in the openshell section'))
+  }
+
+  const set = openshell.profiles
+  const names = Object.keys(set.profiles).sort()
+  checks.push(item("profiles", "ok", `usable profiles: ${names.join(", ") || "none"}`))
+  for (const [name, reason] of Object.entries(set.unsupported)) checks.push(item("profiles", "fail", `profile ${name} is unsupported: ${reason}`, "remove mounts, cpu and memory from it"))
+
+  const fallback = set.profiles[DEFAULT_PROFILE]
+  if (!fallback) checks.push(item("default-providers", "skip", `no usable ${DEFAULT_PROFILE} profile`))
+  else if (fallback.providers.length === 0)
+    checks.push(item("default-providers", "warn", `the ${DEFAULT_PROFILE} profile names no providers, so a sandboxed agent cannot reach a model`, `create a provider in workspace ${OPENSHELL_WORKSPACE} (openshell --workspace ${OPENSHELL_WORKSPACE} provider create --name <name> --type <type> …) and list it in openshell.profiles.${DEFAULT_PROFILE}.providers`))
+  else checks.push(item("default-providers", "ok", `the ${DEFAULT_PROFILE} profile uses ${fallback.providers.join(", ")}`))
+
+  const images = new Map<string, string[]>()
+  for (const name of names) {
+    const profile = set.profiles[name]!
+    const image = profile.image ?? openshell.image ?? DEFAULT_SANDBOX_IMAGE
+    images.set(image, [...(images.get(image) ?? []), name])
+    for (const provider of profile.providers) providers.set(provider, [...(providers.get(provider) ?? []), name])
+  }
+  for (const [image, users] of images) {
+    const concern = imageConcern(image)
+    const who = `profile${users.length > 1 ? "s" : ""} ${users.join(", ")}`
+    if (image === DEFAULT_SANDBOX_IMAGE && !openshell.image && !users.some((u) => set.profiles[u]!.image))
+      checks.push(item("image", "warn", `no image configured (${who} get ${image}, a local build name)`, "publish the sandbox image to an HTTPS registry and set openshell.image"))
+    else if (concern) checks.push(item("image", "warn", `${concern} (${who})`, "publish it to an HTTPS registry (e.g. ghcr.io) and point openshell.image at it"))
+    else checks.push(item("image", "ok", `${image} (${who})`))
+  }
+  return { file, checks, providers, usable: true, ...(openshell.gateway ? { gateway: openshell.gateway } : {}) }
+}
+
+export async function checkOpenShell(options: OpenShellCheckOptions): Promise<OpenShellCheckReport> {
+  const local = configChecks(options.env, options.home)
+  const checks = [...local.checks]
+  const client: OpenShellClient =
+    options.client ?? new OpenShellCli({ ...(options.binary ? { binary: options.binary } : {}), ...(local.gateway ? { gateway: local.gateway } : {}), env: options.env })
+  const skip = (check: string, why: string) => checks.push(item(check, "skip", why))
+
+  let reachable = false
+  try {
+    const version = await client.version()
+    checks.push(item("cli", "ok", `openshell ${version} (supported ${SUPPORTED_VERSIONS})`))
+    try {
+      const status = await client.status()
+      if (status.connected && status.authenticated) {
+        reachable = true
+        checks.push(item("gateway", "ok", `gateway ${status.gateway || "(active)"} at ${status.server} is connected`))
+      } else checks.push(item("gateway", "fail", `gateway ${status.gateway || "(active)"} is ${status.connected ? "connected but not authenticated" : "not connected"}`, "see `openshell status` and `openshell gateway --help`"))
+    } catch (cause) {
+      checks.push(item("gateway", "fail", errorText(cause), "see `openshell status`"))
+    }
+  } catch (cause) {
+    const notInstalled = cause instanceof OpenShellError && cause.code === "not_installed"
+    checks.push(item("cli", "fail", errorText(cause), notInstalled ? "install the NVIDIA OpenShell CLI (and its gateway) on this machine" : `this hub speaks openshell ${SUPPORTED_VERSIONS}`))
+    skip("gateway", "the openshell CLI is not usable")
+  }
+
+  if (!reachable) {
+    skip("workspace", "the gateway is not reachable")
+    skip("providers", "the gateway is not reachable")
+  } else {
+    try {
+      const workspaces = client.workspaces ? await client.workspaces() : []
+      if (workspaces.includes(OPENSHELL_WORKSPACE)) checks.push(item("workspace", "ok", `${OPENSHELL_WORKSPACE} exists`))
+      else checks.push(item("workspace", "fail", `the gateway has no workspace ${OPENSHELL_WORKSPACE} (the hub's sandboxes live there)`, `create it (not run by hub): openshell workspace create --name ${OPENSHELL_WORKSPACE}`))
+    } catch (cause) {
+      checks.push(item("workspace", "fail", errorText(cause)))
+    }
+    if (local.providers.size === 0) skip("providers", "no profile names a provider")
+    else {
+      try {
+        const existing = new Set(client.providers ? await client.providers() : [])
+        const missing = [...local.providers].filter(([name]) => !existing.has(name))
+        for (const [name, users] of missing)
+          checks.push(item("providers", "fail", `provider ${name} (profile${users.length > 1 ? "s" : ""} ${users.join(", ")}) does not exist in workspace ${OPENSHELL_WORKSPACE}`, `create it: openshell --workspace ${OPENSHELL_WORKSPACE} provider create --name ${name} --type <type> …`))
+        if (missing.length === 0) checks.push(item("providers", "ok", `found ${[...local.providers.keys()].join(", ")}`))
+      } catch (cause) {
+        checks.push(item("providers", "fail", errorText(cause)))
+      }
+    }
+  }
+  return { ok: !checks.some((c) => c.status === "fail"), file: local.file, checks }
+}
+
+const MARK: Record<CheckStatus, string> = { ok: "ok  ", warn: "warn", fail: "FAIL", skip: "skip" }
+
+export function openShellCheckText(report: OpenShellCheckReport): string {
+  const lines: string[] = []
+  for (const c of report.checks) {
+    lines.push(`${MARK[c.status]}  ${c.check}: ${c.message}`)
+    if (c.hint && c.status !== "ok") lines.push(`        hint: ${c.hint}`)
+  }
+  const fails = report.checks.filter((c) => c.status === "fail").length
+  const warns = report.checks.filter((c) => c.status === "warn").length
+  lines.push(fails ? `${fails} problem${fails > 1 ? "s" : ""}${warns ? `, ${warns} warning${warns > 1 ? "s" : ""}` : ""}` : `no problems${warns ? `, ${warns} warning${warns > 1 ? "s" : ""}` : ""}`)
+  return lines.join("\n")
+}