@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/credentials.ts

@@ -0,0 +1,75 @@
+// Which hub and token the CLI uses: HUB_URL + HUB_SESSION_TOKEN (a session's identity, set by the spoke in its
+// shells) win; else the login file written by `hub login` ($XDG_CONFIG_HOME or ~/.config, then hub/cli.json,
+// mode 0600) with an app token.
+import { randomBytes } from "node:crypto"
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import type { Fetch } from "../../sdk/src/index.ts"
+
+export type Env = Record<string, string | undefined>
+
+export interface Credentials {
+  readonly url: string
+  readonly token: string
+  /** env: HUB_URL + HUB_SESSION_TOKEN; login: the login file; http: the caller of the hub's POST /mcp. */
+  readonly source: "env" | "login" | "http"
+  /** How to reach the hub (default: the global fetch); POST /mcp dispatches in process. */
+  readonly fetch?: Fetch
+}
+
+export interface Login {
+  readonly url: string
+  readonly token: string
+}
+
+export const loginFile = (env: Env, home: string): string => path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "hub", "cli.json")
+
+export function readLogin(file: string): Login | undefined {
+  let raw: string
+  try {
+    raw = readFileSync(file, "utf8")
+  } catch {
+    return undefined
+  }
+  try {
+    const value = JSON.parse(raw) as Partial<Login>
+    if (typeof value.url === "string" && value.url && typeof value.token === "string" && value.token) return { url: value.url, token: value.token }
+  } catch {
+    // unreadable: treated as logged out
+  }
+  return undefined
+}
+
+/**
+ * Writes the login file, owner-only (0600; its directory 0700 when created), atomically: a private temporary file
+ * next to it is renamed over it, so a reader never sees half a file and a failed write leaves the old one.
+ */
+export function writeLogin(file: string, login: Login): void {
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`
+  try {
+    writeFileSync(tmp, `${JSON.stringify({ url: login.url, token: login.token }, null, 2)}\n`, { mode: 0o600, flag: "wx" })
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, file)
+  } catch (cause) {
+    rmSync(tmp, { force: true })
+    throw cause
+  }
+}
+
+/** Deletes the login file; true when there was one. */
+export function removeLogin(file: string): boolean {
+  try {
+    readFileSync(file)
+  } catch {
+    return false
+  }
+  rmSync(file, { force: true })
+  return true
+}
+
+export function resolveCredentials(env: Env, home: string): Credentials | undefined {
+  if (env.HUB_URL && env.HUB_SESSION_TOKEN) return { url: env.HUB_URL, token: env.HUB_SESSION_TOKEN, source: "env" }
+  const login = readLogin(loginFile(env, home))
+  return login ? { ...login, source: "login" } : undefined
+}

package/packages/cli/src/decisions.ts

@@ -0,0 +1,106 @@
+// Decisions in the CLI (design §12.1): the `hub ask @me` options (--option id=label[:safe], --recommend id --why,
+// --urgency, --deadline, --on-timeout, --tier, --about) and the text of a Decision (ask @me, `hub decisions list`).
+// The shapes are packages/sdk's types (src/central/agent/decisions.ts).
+import type { AskOptions, Decision, DecisionOption, DecisionState } from "../../sdk/src/index.ts"
+import { str, UsageError, type FlagKind, type Parsed } from "./args"
+import { oneLine } from "./format"
+import { durationArg, partyText } from "./messaging"
+
+/** The ask flags that make a Decision (only for asks to @me). */
+export const DECISION_FLAGS: Readonly<Record<string, FlagKind>> = {
+  option: "multi",
+  recommend: "string",
+  why: "string",
+  urgency: "string",
+  deadline: "string",
+  "on-timeout": "string",
+  tier: "string",
+  about: "multi",
+}
+
+const URGENCIES = ["low", "normal", "high"]
+const TIERS = ["confirm", "tap"]
+const STATES: readonly DecisionState[] = ["open", "answered", "expired", "closed"]
+export const DECISION_STATES = STATES
+
+/** `id=label` or `id=label:safe` (the label may contain colons; only a trailing `:safe` marks it safe). */
+export function optionArg(value: string): DecisionOption {
+  const eq = value.indexOf("=")
+  if (eq <= 0) throw new UsageError(`--option takes id=label[:safe] (got "${value}")`)
+  const id = value.slice(0, eq)
+  let label = value.slice(eq + 1)
+  const safe = label.endsWith(":safe")
+  if (safe) label = label.slice(0, -":safe".length)
+  if (!label.trim()) throw new UsageError(`--option ${id}: the label is empty`)
+  return { id, label, ...(safe ? { safe: true } : {}) }
+}
+
+const oneOf = (value: string | undefined, allowed: readonly string[], flag: string) => {
+  if (value !== undefined && !allowed.includes(value)) throw new UsageError(`${flag} is one of ${allowed.join(", ")}`)
+  return value
+}
+
+/** The Decision fields of `hub ask` (empty when none is given); usage errors for bad ones or a non-@me ask. */
+export function decisionOptions(flags: Parsed["flags"], to: string): Partial<AskOptions> {
+  const given = Object.keys(DECISION_FLAGS).filter((flag) => flags[flag] !== undefined)
+  if (!given.length) return {}
+  if (to !== "@me") throw new UsageError(`${given.map((f) => `--${f}`).join(", ")}: only for asks to @me`)
+  const recommend = str(flags, "recommend")
+  const why = str(flags, "why")
+  if (why !== undefined && recommend === undefined) throw new UsageError("--why explains --recommend")
+  const deadline = str(flags, "deadline")
+  const urgency = oneOf(str(flags, "urgency"), URGENCIES, "--urgency") as AskOptions["urgency"]
+  const tier = oneOf(str(flags, "tier"), TIERS, "--tier") as AskOptions["tier"]
+  const onTimeout = str(flags, "on-timeout")
+  const options = flags.option as string[] | undefined
+  const about = flags.about as string[] | undefined
+  return {
+    ...(options ? { options: options.map(optionArg) } : {}),
+    ...(recommend !== undefined ? { recommendation: { option: recommend, ...(why !== undefined ? { why } : {}) } } : {}),
+    ...(urgency ? { urgency } : {}),
+    ...(tier ? { tier } : {}),
+    ...(deadline !== undefined ? { deadline: durationArg(deadline, "--deadline") } : {}),
+    ...(onTimeout !== undefined ? { onTimeout } : {}),
+    ...(about ? { about } : {}),
+  }
+}
+
+/** The --state filter of `hub decisions list`. */
+export function stateArg(value: string | undefined): DecisionState | undefined {
+  return oneOf(value, STATES, "--state") as DecisionState | undefined
+}
+
+const iso = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z")
+
+/** `go Proceed · hold Hold (safe) — recommended: hold (why)`; empty for a free-text Decision without one. */
+function choicesText(decision: Decision): string {
+  const options = decision.options.map((o) => `${o.id} ${oneLine(o.label, 80)}${o.safe ? " (safe)" : ""}`).join(" · ")
+  const r = decision.recommendation
+  const recommended = r ? `recommended: ${r.option}${r.why ? ` (${oneLine(r.why, 200)})` : ""}` : ""
+  return [options, recommended].filter(Boolean).join(" — ")
+}
+
+function stateText(decision: Decision): string {
+  if (decision.state === "answered") {
+    const a = decision.answer
+    return `answered${a?.option ? ` ${a.option}` : ""}${a?.answeredBy === "timeout" ? " (timeout)" : ""}`
+  }
+  if (decision.state === "open" && decision.deadline !== undefined) return `open (deadline ${iso(decision.deadline)})`
+  return decision.state
+}
+
+/** One Decision: `dec_1  open  high  from @api  Question` and its choices on the next line. */
+export function decisionText(decision: Decision): string {
+  const head = `${decision.id}  ${stateText(decision)}  ${decision.urgency}  from ${partyText(decision.from)}  ${oneLine(decision.question, 160)}`
+  const choices = choicesText(decision)
+  return choices ? `${head}\n  ${choices}` : head
+}
+
+export const decisionsText = (decisions: readonly Decision[]): string => (decisions.length ? decisions.map(decisionText).join("\n") : "no decisions")
+
+/** What `hub ask @me` adds: the Decision it opened. */
+export function openedText(decision: Decision): string {
+  const tier = decision.tier === "tap" ? ", tap in the console" : ""
+  const choices = choicesText(decision)
+  return `decision ${decision.id} (${decision.urgency}${tier}): ${oneLine(decision.question, 160)}${choices ? `\n  ${choices}` : ""}\n  the user answers it in the console`
+}

package/packages/cli/src/format.ts

@@ -0,0 +1,185 @@
+// Short human text for the CLI's default output (--json prints the hub's answers unchanged). The shapes are those
+// of src/central/agent/read-routes.ts and directory.ts; unknown fields are ignored, missing ones skipped.
+
+export interface Blocker {
+  readonly kind: string
+  readonly id?: string
+  readonly summary: string
+}
+
+export interface SessionView {
+  readonly id: string
+  readonly name?: string
+  readonly roles?: readonly string[]
+  readonly title?: string
+  readonly state: string
+  readonly harness?: string
+  readonly now?: string
+  readonly blockers?: readonly Blocker[]
+}
+
+const at = (name: string) => `@${name.replace(/^@+/, "")}`
+export const oneLine = (text: string, max = 160): string => {
+  const flat = text.replace(/\s+/g, " ").trim()
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat
+}
+const blockerText = (b: Blocker) => `${b.kind}: ${oneLine(b.summary, 100)}`
+
+/** `@name ses_…  state  harness  now  [kind: summary; …]` */
+export function sessionLine(s: SessionView): string {
+  const parts = [[s.name ? at(s.name) : undefined, s.id].filter(Boolean).join(" "), s.state]
+  if (s.harness) parts.push(s.harness)
+  if (s.now) parts.push(oneLine(s.now, 80))
+  if (s.blockers?.length) parts.push(`[${s.blockers.map(blockerText).join("; ")}]`)
+  return parts.join("  ")
+}
+
+interface Snapshot {
+  readonly machines: readonly {
+    id: string
+    name?: string
+    online: boolean
+    harnesses?: readonly string[]
+    projects: readonly { root: string; name: string; sessions: readonly SessionView[] }[]
+  }[]
+  readonly attention: readonly { kind: string; sessionID: string; name?: string; id?: string; summary: string }[]
+}
+
+export function statusText(snapshot: Snapshot): string {
+  const lines: string[] = []
+  for (const m of snapshot.machines) {
+    lines.push([m.name ?? m.id, m.online ? "online" : "offline", ...(m.harnesses ?? [])].join("  "))
+    for (const p of m.projects) {
+      lines.push(`  ${p.name}`)
+      for (const s of p.sessions) lines.push(`    ${sessionLine(s)}`)
+    }
+  }
+  if (lines.length === 0) lines.push("no machines")
+  if (snapshot.attention.length) {
+    lines.push("attention:")
+    for (const a of snapshot.attention) lines.push(`  ${[a.name ? at(a.name) : undefined, a.sessionID].filter(Boolean).join(" ")}  ${a.kind}${a.id ? ` ${a.id}` : ""}: ${oneLine(a.summary, 100)}`)
+  }
+  return lines.join("\n")
+}
+
+export const sessionsText = (sessions: readonly SessionView[]): string => (sessions.length ? sessions.map(sessionLine).join("\n") : "no sessions")
+
+interface Shown extends SessionView {
+  readonly online?: boolean
+  readonly project?: string
+  readonly directory?: string
+  readonly machineID?: string
+  readonly parentID?: string
+  readonly lastSeen?: number
+  readonly children?: number
+  readonly summary?: {
+    branch?: string
+    context?: { used: number; limit?: number; percent?: number; model?: string }
+    changes?: { additions: number; deletions: number; totalFiles: number }
+    mcp?: readonly { name: string; status: string }[]
+  }
+  readonly unsupported?: readonly { feature?: string; harness?: string }[]
+  readonly failed?: readonly { feature?: string }[]
+}
+
+export function showText(s: Shown): string {
+  const lines = [[s.name ? at(s.name) : undefined, s.id].filter(Boolean).join(" ")]
+  const field = (label: string, value: string | number | undefined) => {
+    if (value !== undefined && value !== "") lines.push(`${label}: ${value}`)
+  }
+  field("title", s.title)
+  field("state", [s.state, s.harness].filter(Boolean).join("  "))
+  field("project", [s.project, s.directory && s.directory !== s.project ? `(${s.directory})` : undefined].filter(Boolean).join(" ") || undefined)
+  field("machine", s.machineID)
+  field("parent", s.parentID)
+  if (s.roles?.length) field("roles", s.roles.map((r) => `@${at(r)}`).join(" "))
+  field("now", s.now)
+  if (s.children) field("subagents", s.children)
+  if (s.online === false && s.lastSeen !== undefined) field("last seen", new Date(s.lastSeen).toISOString())
+  if (s.blockers?.length) {
+    lines.push("blockers:")
+    for (const b of s.blockers) lines.push(`  ${b.kind}${b.id ? ` ${b.id}` : ""}: ${oneLine(b.summary, 200)}`)
+  }
+  const sum = s.summary
+  if (sum) {
+    field("branch", sum.branch)
+    if (sum.context) field("context", `${sum.context.used} tokens${sum.context.percent !== undefined ? ` (${sum.context.percent}%)` : ""}${sum.context.model ? ` ${sum.context.model}` : ""}`)
+    if (sum.changes) field("changes", `${sum.changes.totalFiles} files +${sum.changes.additions} -${sum.changes.deletions}`)
+    if (sum.mcp?.length) field("mcp", sum.mcp.map((m) => `${m.name} ${m.status}`).join(", "))
+  }
+  for (const u of s.unsupported ?? []) lines.push(`unsupported: ${u.feature ?? "?"}${u.harness ? ` (${u.harness})` : ""}`)
+  for (const f of s.failed ?? []) lines.push(`failed: ${f.feature ?? "?"}`)
+  return lines.join("\n")
+}
+
+interface Row {
+  readonly kind: string
+  readonly text?: string
+  readonly name?: string
+  readonly state?: string
+  readonly title?: string
+  readonly at?: number
+}
+
+const time = (ms: number | undefined) => (ms === undefined ? "--:--:--" : new Date(ms).toISOString().slice(11, 19))
+
+/** Timeline rows (the hub sends newest first), printed oldest first. */
+export function logText(rows: readonly Row[]): string {
+  if (!rows.length) return "no rows"
+  return [...rows]
+    .reverse()
+    .map((r) => {
+      const head = r.kind === "tool" ? `tool ${r.name ?? "?"}${r.state ? ` (${r.state})` : ""}` : r.kind
+      const body = oneLine(r.text ?? r.title ?? "", 200)
+      return `${time(r.at)}  ${head}${body ? `  ${body}` : ""}`
+    })
+    .join("\n")
+}
+
+interface WhoEntry {
+  readonly sessionID: string
+  readonly name?: string
+  readonly project?: string
+  readonly title?: string
+  readonly state?: string
+  readonly online: boolean
+  readonly roles: readonly { role: string; project?: string }[]
+}
+
+export function whoText(entries: readonly WhoEntry[]): string {
+  if (!entries.length) return "no sessions"
+  return entries
+    .map((e) => {
+      const parts = [[e.name ? at(e.name) : undefined, e.sessionID].filter(Boolean).join(" "), e.online ? (e.state ?? "online") : "offline"]
+      if (e.roles.length) parts.push(e.roles.map((r) => `@@${r.role}${r.project !== undefined ? `.${r.project}` : ""}`).join(" "))
+      if (e.project) parts.push(e.project)
+      if (e.title) parts.push(oneLine(e.title, 60))
+      return parts.join("  ")
+    })
+    .join("\n")
+}
+
+/** A caller as whoami / status `you` report it. */
+export interface Actor {
+  readonly kind: string
+  readonly sessionID?: string
+  readonly machineID?: string
+  readonly tokenID?: string
+  readonly label?: string
+  readonly scopes?: readonly string[]
+  readonly deviceID?: string
+}
+
+export function whoamiText(body: { actor: Actor; user: { id: string; name?: string; email?: string; role?: string } }): string {
+  const { actor, user } = body
+  const lines: string[] = []
+  if (actor.kind === "session") lines.push(`session ${actor.sessionID}${actor.machineID ? ` on machine ${actor.machineID}` : ""}`)
+  else if (actor.kind === "app") lines.push(`app token ${actor.tokenID}${actor.label ? ` (${actor.label})` : ""}${actor.scopes?.length ? ` scopes ${actor.scopes.join(",")}` : ""}`)
+  else lines.push(`user${actor.deviceID ? ` (device ${actor.deviceID})` : ""}`)
+  const who = [user.name, user.email ? `<${user.email}>` : undefined].filter(Boolean).join(" ") || user.id
+  lines.push(`user ${who}${user.role ? ` (${user.role})` : ""}`)
+  return lines.join("\n")
+}
+
+export const roleText = (r: { role: string; project?: string }) => `@@${r.role}${r.project !== undefined ? `.${r.project}` : ""}`
+export { at as atName }

package/packages/cli/src/grants.ts

@@ -0,0 +1,105 @@
+// `hub grant list | show | create | revoke | request` (design §5): the spec of `hub grant create` (flags, or --json
+// '{…}' / --json -) and the text of grants. Only the user manages grants (src/central/agent/grant-routes.ts); a
+// session's own credential is refused here without asking the hub, any other the hub refuses (forbidden, exit 5).
+// Agents (a session, an app token with messages:send) `hub grant request` one instead: the same flags (the holder
+// defaults to the requester) and a --why; the user's tap in the console creates it.
+import type { Grant, GrantRequested, GrantRequestSpec, GrantSpec, GrantVerb } from "../../sdk/src/index.ts"
+import { jsonObjectArg, str, UsageError, type FlagKind, type Parsed } from "./args"
+import { CliError, EXIT } from "./http"
+
+/** The flags of `hub grant create`. */
+export const GRANT_FLAGS: Readonly<Record<string, FlagKind>> = {
+  json: "json",
+  holder: "string",
+  project: "multi",
+  allow: "multi",
+  permit: "multi",
+  never: "multi",
+  expires: "string",
+  "max-per-hour": "string",
+  "allow-always": "bool",
+}
+
+/** The flags of `hub grant request`: create's, --permission-allow (as --permit), and the reason the user reads. */
+export const GRANT_REQUEST_FLAGS: Readonly<Record<string, FlagKind>> = { ...GRANT_FLAGS, "permission-allow": "multi", why: "string" }
+
+export const GRANT_USER_HINT = "only the user manages grants: use the console, or `hub login` with the user's device token"
+
+/** Refuses a session's own credential (HUB_SESSION_TOKEN): a session never creates or revokes a grant. */
+export function userOnly(source: string, what: string): void {
+  if (source === "env") throw new CliError(EXIT.forbidden, `only the user can ${what} a grant, not a session`, GRANT_USER_HINT)
+}
+
+/** A forbidden from the grant routes, with the hint of who may manage grants. */
+export function grantError(error: unknown): unknown {
+  if (error instanceof CliError && error.exit === EXIT.forbidden) return new CliError(error.exit, error.message, [error.hint, GRANT_USER_HINT].filter(Boolean).join("; "), error.envelope)
+  return error
+}
+
+/** Comma-separated and repeated values, in order. */
+const listOf = (flags: Parsed["flags"], name: string): string[] => ((flags[name] as string[] | undefined) ?? []).flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean)
+
+/** The grant of `hub grant create`: a JSON spec (--json), or the flags. */
+export async function grantSpecArg(flags: Parsed["flags"], stdin: (() => Promise<string>) | undefined): Promise<GrantSpec> {
+  return (await grantArg(flags, stdin, true)) as GrantSpec
+}
+
+/** The grant of `hub grant request`: as create's, the holder optional (the requester by default). */
+export function grantRequestArg(flags: Parsed["flags"], stdin: (() => Promise<string>) | undefined): Promise<GrantRequestSpec> {
+  return grantArg(flags, stdin, false)
+}
+
+async function grantArg(flags: Parsed["flags"], stdin: (() => Promise<string>) | undefined, holderRequired: boolean): Promise<GrantRequestSpec> {
+  const json = typeof flags.json === "string" ? flags.json : undefined
+  const flagged = Object.keys(GRANT_REQUEST_FLAGS).filter((name) => name !== "json" && name !== "why" && flags[name] !== undefined)
+  if (json !== undefined) {
+    if (flagged.length) throw new UsageError(`give either --json '{…}' or ${flagged.map((f) => `--${f}`).join(", ")}`)
+    return (await jsonObjectArg(json, stdin, "grant")) as unknown as GrantRequestSpec
+  }
+  const holder = str(flags, "holder")
+  if (holder === undefined && holderRequired) throw new UsageError("needs --holder (ses_…, @name, @@orchestrator…, or app:<token id>)")
+  const projects = listOf(flags, "project")
+  if (!projects.length) throw new UsageError("needs --project <path> (repeatable)")
+  const allow = listOf(flags, "allow") as GrantVerb[]
+  if (!allow.length) throw new UsageError("needs --allow <verbs> (approve, deny, answer, prompt, stop, roles, launch)")
+  const permit = [...listOf(flags, "permit"), ...listOf(flags, "permission-allow")]
+  const never = listOf(flags, "never")
+  const expires = str(flags, "expires")
+  const cap = str(flags, "max-per-hour")
+  if (cap !== undefined && !/^\d+$/.test(cap)) throw new UsageError("--max-per-hour is a whole number")
+  return {
+    ...(holder !== undefined ? { holder } : {}),
+    scope: { projects },
+    allow,
+    ...(permit.length || never.length ? { permissions: { ...(permit.length ? { allow: permit } : {}), ...(never.length ? { never } : {}) } } : {}),
+    ...(expires !== undefined ? { expires } : {}),
+    ...(cap !== undefined ? { maxActionsPerHour: Number(cap) } : {}),
+    ...(flags["allow-always"] === true ? { allowAlways: true } : {}),
+  }
+}
+
+const iso = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z")
+
+/** `g_1  active  @@orchestrator  approve,deny  /p  until 2026-…Z` */
+export const grantLine = (g: Grant): string => [g.id, g.state, g.holder, g.allow.join(","), g.scope.projects.join(","), `until ${iso(g.expiresAt)}`].join("  ")
+
+export const grantsText = (grants: readonly Grant[]): string => (grants.length ? grants.map(grantLine).join("\n") : "no grants")
+
+/** One grant in full. */
+export function grantText(g: Grant): string {
+  const list = (values: readonly string[]) => (values.length ? values.join(", ") : "none")
+  return [
+    `${g.id}  ${g.state}`,
+    `holder: ${g.holder}${g.holderSessionID && g.holderSessionID !== g.holder ? ` (${g.holderSessionID})` : ""}`,
+    `projects: ${list(g.scope.projects)}`,
+    `verbs: ${list(g.allow)}`,
+    `permissions allow: ${list(g.permissions.allow)}`,
+    `permissions never: ${list(g.permissions.never)}`,
+    `always: ${g.allowAlways ? "yes" : "no"}`,
+    `max actions per hour: ${g.maxActionsPerHour}`,
+    g.revokedAt !== undefined ? `revoked: ${iso(g.revokedAt)}` : `expires: ${iso(g.expiresAt)}`,
+  ].join("\n")
+}
+
+/** `requested; waiting for the user (Decision dec_…)` */
+export const requestedText = (body: GrantRequested): string => `requested; waiting for the user (Decision ${body.decision.id})`

package/packages/cli/src/http.ts

@@ -0,0 +1,86 @@
+// The CLI's side of talking to the hub: a HubClient (packages/sdk) for the resolved credentials, and the SDK's
+// errors turned into CliErrors with the exit code of each error code (design §8, plus usage and unauthorized) and
+// a hint for credential errors.
+import { HubClient, HubError, HubTransportError, type Envelope } from "../../sdk/src/index.ts"
+import type { Credentials } from "./credentials"
+
+export type { Envelope } from "../../sdk/src/index.ts"
+
+export const EXIT = {
+  ok: 0,
+  other: 1,
+  usage: 2,
+  notFound: 3,
+  needsUser: 4,
+  forbidden: 5,
+  rateLimited: 6,
+  unavailable: 7,
+  gone: 8,
+  unauthorized: 9,
+} as const
+
+const EXIT_OF: Record<string, number> = {
+  invalid: EXIT.usage,
+  not_found: EXIT.notFound,
+  ambiguous: EXIT.notFound,
+  name_taken: EXIT.notFound,
+  needs_user: EXIT.needsUser,
+  forbidden: EXIT.forbidden,
+  paused: EXIT.forbidden,
+  rate_limited: EXIT.rateLimited,
+  unsupported: EXIT.unavailable,
+  offline: EXIT.unavailable,
+  gone: EXIT.gone,
+  unauthorized: EXIT.unauthorized,
+  token_expired: EXIT.unauthorized,
+}
+
+/** A failure to report: message (and hint) on stderr, the envelope on stdout with --json, then exit. */
+export class CliError extends Error {
+  constructor(
+    readonly exit: number,
+    message: string,
+    readonly hint?: string,
+    readonly envelope?: Envelope,
+  ) {
+    super(message)
+  }
+}
+
+export const exitOf = (code: string): number => EXIT_OF[code] ?? EXIT.other
+
+/** The hub's hint, plus what to do about a credential error from here. */
+function hintFor(envelope: Envelope, credentials: Credentials): string | undefined {
+  const own =
+    credentials.source === "http"
+      ? undefined // a POST /mcp caller has no CLI login or shell to fix
+      : envelope.code === "token_expired"
+      ? credentials.source === "env"
+        ? "session tokens are renewed for new shells: start a new shell"
+        : "run `hub login` with a new app token"
+      : envelope.code === "unauthorized"
+        ? credentials.source === "env"
+          ? "HUB_SESSION_TOKEN is not valid here (is the session still live?)"
+          : "run `hub login` again"
+        : undefined
+  return [envelope.hint, own].filter(Boolean).join("; ") || undefined
+}
+
+/** An SDK error as the CLI reports it; anything else is returned unchanged. */
+export function cliError(error: unknown, credentials: Credentials): unknown {
+  if (error instanceof HubError) return new CliError(exitOf(error.code), error.message, hintFor(error.envelope, credentials), error.envelope)
+  if (error instanceof HubTransportError) return new CliError(EXIT.other, error.message, error.kind === "unreachable" ? "Check HUB_URL or the URL given to `hub login`" : undefined)
+  return error
+}
+
+export const clientFor = (credentials: Credentials): HubClient =>
+  new HubClient({ url: credentials.url, token: credentials.token, ...(credentials.fetch ? { fetch: credentials.fetch } : {}) })
+
+/** Runs `use` with a client for `credentials`; SDK errors become CliErrors. */
+export async function withHub<T>(credentials: Credentials, use: (hub: HubClient) => Promise<T>): Promise<T> {
+  try {
+    return await use(clientFor(credentials))
+  } catch (error) {
+    throw cliError(error, credentials)
+  }
+}