@huynle/hub 0.11.0 → 0.11.1

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-cli",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "private": true,
   "description": "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/cli/src/cli.ts

@@ -82,19 +82,22 @@ Identity
   hub role release <role[.project]> [--session <addr>]
 
 Messaging (text "-" reads it from stdin)
-  hub msg <addr> "text" [--all] [--no-wake] [--urgent] [--not-after <ms|ISO time>] [--key K]
+  hub msg <addr> "text" [--all] [--no-wake] [--urgent] [--item itk_…] [--not-after <ms|ISO time>] [--key K]
                                       tell: fire and forget; --not-after: never delivered after that time
-  hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--not-after <ms|ISO time>] [--all] [--no-wake] [--urgent] [--key K]
+  hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--item itk_…] [--not-after <ms|ISO time>] [--all] [--no-wake] [--urgent] [--key K]
                                       tracked until answered, declined or expired; --wait alone waits until
                                       it expires; exit 0 answered, 1 declined or no answer yet, 8 expired;
                                       --key (Idempotency-Key): a retry with the same key and text answers
-                                      the first send again and sends nothing (24 h, per credential)
+                                      the first send again and sends nothing (24 h, per credential);
+                                      --item: open team intake item, both members seated (older hubs ignore it)
   hub reply <msgID> "text" [--no-wake]   goes to the real sender
   hub decline <msgID> --why "reason"
   hub ask @me "question" [--option id=label[:safe]]... [--recommend id [--why "…"]] [--urgency low|normal|high]
          [--deadline 2h [--on-timeout <safe id>]] [--tier confirm|tap] [--about <addr>]...
+         [--choice "D1=Label:a=Option*,b=Option"]... [--kind question|plan|merge|release]
                                       opens a Decision for the user (answered in the console; the answer
-                                      comes back as a reply); --on-timeout picks a safe option at the deadline
+                                      comes back as a reply); --on-timeout picks a safe option at the deadline;
+                                      --choice (instead of --option) asks several points, * marks the recommendation
   hub decisions list [--state open|answered|expired|closed]   the Decisions you asked
   hub inbox                           asks to answer, your open asks, recent messages, mutes
   hub mute <addr> · hub unmute <addr>    refuse (or accept again) messages from a session
@@ -292,15 +295,17 @@ const whyOf = (flags: Parsed["flags"]) => {
   return why !== undefined ? { why } : {}
 }
 
-/** --no-wake, --urgent, --not-after and --key as SDK send options. */
+/** --no-wake, --urgent, --not-after, --item and --key as SDK send options. */
 const sendFlags = (flags: Parsed["flags"]) => {
   const notAfter = str(flags, "not-after")
   const key = str(flags, "key")
+  const item = str(flags, "item")
   return {
     ...(flags["no-wake"] === true ? { wake: false } : {}),
     ...(flags.urgent === true ? { urgent: true } : {}),
     ...(notAfter === undefined ? {} : { notAfter: notAfterArg(notAfter, "--not-after") }),
     ...(key !== undefined ? { idempotencyKey: key } : {}),
+    ...(item !== undefined ? { item } : {}),
   }
 }
 
@@ -422,7 +427,7 @@ const COMMANDS: Record<string, Command> = {
   },
   msg: {
     args: ["<addr>", "<text>"],
-    flags: { all: "bool", "no-wake": "bool", urgent: "bool", "not-after": "string", key: "string" },
+    flags: { all: "bool", "no-wake": "bool", urgent: "bool", "not-after": "string", item: "string", key: "string" },
     async handle(context) {
       const { flags, args } = context.parsed
       const text = await textArg(args[1]!, context.io.stdin)
@@ -433,7 +438,7 @@ const COMMANDS: Record<string, Command> = {
   },
   ask: {
     args: ["<addr>", "<text>"],
-    flags: { all: "bool", "no-wake": "bool", urgent: "bool", "not-after": "string", key: "string", expires: "string", wait: "optional", ...DECISION_FLAGS },
+    flags: { all: "bool", "no-wake": "bool", urgent: "bool", "not-after": "string", item: "string", key: "string", expires: "string", wait: "optional", ...DECISION_FLAGS },
     async handle(context) {
       const { flags, args } = context.parsed
       const decision = decisionOptions(flags, args[0]!)

package/packages/cli/src/decisions.ts

@@ -1,7 +1,8 @@
 // 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`).
+// --urgency, --deadline, --on-timeout, --tier, --about; DC-4: --choice 'D1=Label:a=Yes*,b=No' and --kind) 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 type { AskOptions, Decision, DecisionChoice, DecisionKind, 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"
@@ -16,9 +17,12 @@ export const DECISION_FLAGS: Readonly<Record<string, FlagKind>> = {
   "on-timeout": "string",
   tier: "string",
   about: "multi",
+  choice: "multi",
+  kind: "string",
 }
 
 const URGENCIES = ["low", "normal", "high"]
+const KINDS: readonly DecisionKind[] = ["question", "plan", "merge", "release"]
 const TIERS = ["confirm", "tap"]
 const STATES: readonly DecisionState[] = ["open", "answered", "expired", "closed"]
 export const DECISION_STATES = STATES
@@ -35,6 +39,38 @@ export function optionArg(value: string): DecisionOption {
   return { id, label, ...(safe ? { safe: true } : {}) }
 }
 
+/**
+ * `D1=Label:a=Yes*,b=No`: a choice group, its label (it may contain colons), then its options (`id=label`, comma
+ * separated; a trailing `*` marks the recommended one). The hub checks ids and sizes.
+ */
+export function choiceArg(value: string): DecisionChoice {
+  const usage = `--choice takes GROUP=Label:a=Option*,b=Option (got "${value}")`
+  const eq = value.indexOf("=")
+  if (eq <= 0) throw new UsageError(usage)
+  const id = value.slice(0, eq)
+  const rest = value.slice(eq + 1)
+  // The options start after the last colon followed by `id=`.
+  let split = -1
+  for (let i = rest.lastIndexOf(":"); i >= 0; i = rest.lastIndexOf(":", i - 1)) {
+    if (/^[^=,:\s][^=,:]*=/.test(rest.slice(i + 1))) {
+      split = i
+      break
+    }
+  }
+  if (split < 0) throw new UsageError(usage)
+  const label = rest.slice(0, split)
+  if (!label.trim()) throw new UsageError(`--choice ${id}: the label is empty`)
+  const options = rest.slice(split + 1).split(",").map((option) => {
+    const at = option.indexOf("=")
+    if (at <= 0) throw new UsageError(usage)
+    const recommended = option.endsWith("*")
+    const text = option.slice(at + 1, recommended ? -1 : undefined)
+    if (!text.trim()) throw new UsageError(`--choice ${id}: option ${option.slice(0, at)} has an empty label`)
+    return { id: option.slice(0, at), label: text, ...(recommended ? { recommended: true } : {}) }
+  })
+  return { id, label, options }
+}
+
 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
@@ -54,8 +90,13 @@ export function decisionOptions(flags: Parsed["flags"], to: string): Partial<Ask
   const onTimeout = str(flags, "on-timeout")
   const options = flags.option as string[] | undefined
   const about = flags.about as string[] | undefined
+  const choices = flags.choice as string[] | undefined
+  if (choices && options) throw new UsageError("--choice and --option don't mix: give one or the other")
+  const kind = oneOf(str(flags, "kind"), KINDS, "--kind") as DecisionKind | undefined
   return {
     ...(options ? { options: options.map(optionArg) } : {}),
+    ...(choices ? { choices: choices.map(choiceArg) } : {}),
+    ...(kind ? { kind } : {}),
     ...(recommend !== undefined ? { recommendation: { option: recommend, ...(why !== undefined ? { why } : {}) } } : {}),
     ...(urgency ? { urgency } : {}),
     ...(tier ? { tier } : {}),
@@ -72,8 +113,14 @@ export function stateArg(value: string | undefined): 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. */
+/**
+ * `go Proceed · hold Hold (safe) — recommended: hold (why)`; with choices, one line per group
+ * (`D1 Order: a First (recommended) · b Second`); empty for a free-text Decision without one.
+ */
 function choicesText(decision: Decision): string {
+  if (decision.choices?.length) {
+    return decision.choices.map((g) => `${g.id} ${oneLine(g.label, 120)}: ${g.options.map((o) => `${o.id} ${oneLine(o.label, 80)}${o.recommended ? " (recommended)" : ""}`).join(" · ")}`).join("\n  ")
+  }
   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)})` : ""}` : ""
@@ -83,7 +130,8 @@ function choicesText(decision: Decision): string {
 function stateText(decision: Decision): string {
   if (decision.state === "answered") {
     const a = decision.answer
-    return `answered${a?.option ? ` ${a.option}` : ""}${a?.answeredBy === "timeout" ? " (timeout)" : ""}`
+    const picks = a?.picks ? ` ${Object.entries(a.picks).map(([group, option]) => `${group}=${option}`).join(" ")}` : ""
+    return `answered${a?.option ? ` ${a.option}` : ""}${picks}${a?.answeredBy === "timeout" ? " (timeout)" : ""}`
   }
   if (decision.state === "open" && decision.deadline !== undefined) return `open (deadline ${iso(decision.deadline)})`
   return decision.state

package/packages/cli/src/format.ts

@@ -16,6 +16,8 @@ export interface SessionView {
   readonly harness?: string
   readonly now?: string
   readonly blockers?: readonly Blocker[]
+  /** (SS-1) Why the session is not making progress; absent: ok (or an older hub). */
+  readonly health?: { readonly kind: string; readonly since?: number; readonly resetAt?: number; readonly attempt?: number; readonly detail?: string }
 }
 
 const at = (name: string) => `@${name.replace(/^@+/, "")}`
@@ -94,6 +96,13 @@ export function showText(s: Shown): string {
   field("parent", s.parentID)
   if (s.roles?.length) field("roles", s.roles.map((r) => `@${at(r)}`).join(" "))
   field("now", s.now)
+  if (s.health && s.health.kind !== "ok") {
+    const h = s.health
+    // A hub's value is data: a resetAt that is no valid date is left out, never thrown on.
+    const reset = typeof h.resetAt === "number" && Number.isFinite(h.resetAt) && Math.abs(h.resetAt) <= 8.64e15 ? new Date(h.resetAt).toISOString() : undefined
+    const facts = [h.kind, reset ? `resets ${reset}` : undefined, h.attempt !== undefined ? `attempt ${h.attempt}` : undefined].filter(Boolean).join(", ")
+    field("health", h.detail ? `${facts} — ${oneLine(h.detail, 200)}` : facts)
+  }
   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) {

package/packages/cli/src/mcp.ts

@@ -11,7 +11,7 @@
 // the profile lifecycle (profile_show, profile_create, profile_update, profile_version_create, profile_skill_set, …,
 // profile_assign; scopes profiles:read|manage|assign: profiles-mcp.ts), and the Concierge watchlist (watchlist_get,
 // watchlist_update, watchlist_watch, watchlist_mute: watchlist.ts).
-import { renderEnvelope, sanitizeText, WAIT_POLL_MAX_S, type AgentMessage, type Asked, type DecisionState, type FormAnswer, type HubClient, type LaunchSpec, type LaunchState, type PromptDelivery, type Inbox, type Sent, type SentAll } from "../../sdk/src/index.ts"
+import { DECISION_ASK_PROPERTIES, decisionAskFields, renderEnvelope, sanitizeText, WAIT_POLL_MAX_S, type AgentMessage, type Asked, type DecisionState, type FormAnswer, type HubClient, type LaunchSpec, type LaunchState, type PromptDelivery, type Inbox, type Sent, type SentAll } from "../../sdk/src/index.ts"
 import { answeredText, approvedText, DELIVERIES, deniedText, needsUserLines, promptedText, stoppedText } from "./acting"
 import { UsageError } from "./args"
 import { intentLine, writeIntent } from "./intents"
@@ -126,7 +126,8 @@ const sendOptions = (args: Args) => {
   const wake = optionalBool(args, "wake")
   const urgent = optionalBool(args, "urgent")
   const notAfter = optionalNotAfter(args)
-  return { ...(wake !== undefined ? { wake } : {}), ...(urgent !== undefined ? { urgent } : {}), ...(notAfter !== undefined ? { notAfter } : {}) }
+  const item = optional(args, "item")
+  return { ...(wake !== undefined ? { wake } : {}), ...(urgent !== undefined ? { urgent } : {}), ...(notAfter !== undefined ? { notAfter } : {}), ...(item !== undefined ? { item } : {}) }
 }
 
 /** The why argument as SDK act options. */
@@ -238,6 +239,7 @@ const DECISIONS_NOTE = "Decisions are asked by sessions: the question and option
 
 const STRING = { type: "string" } as const
 const SEND = {
+  item: { type: "string", description: "msg/ask: optional itk_ ID of an open item; sender and recipient must hold current seats in the item's team (older hubs ignore it)." },
   wake: { type: "boolean", description: "false: admit the message without starting a turn." },
   urgent: { type: "boolean", description: "Steer into the recipient's running turn." },
   notAfter: { type: ["number", "string"], description: "Never deliver after this time: epoch milliseconds or an ISO 8601 date-time (at most 30 days ahead). Already passed: nothing is sent (expired)." },
@@ -767,6 +769,13 @@ const TOOLS: readonly Tool[] = [
   ...operationTools,
   ...teamTools,
   ...watchlistTools,
+  {
+    name: "agent_limits",
+    description: "Read the hub-wide agent hop limit, the hop ceiling (the highest hop limit the hub accepts) and launch caps, their sources and revision. Read-only; only an admin may change them in the console.",
+    properties: {},
+    readOnly: true,
+    run: async (hub, _args, signal) => JSON.stringify(await hub.call("GET", "/api/agent/agent-limits", { signal }), null, 2),
+  },
   {
     name: "whoami",
     description: "Who this hub credential is: the app token of `hub login` (or the session of HUB_SESSION_TOKEN) and its user.",
@@ -846,10 +855,11 @@ const TOOLS: readonly Tool[] = [
   },
   {
     name: "ask",
-    description: `Ask a session a question, tracked until answered, declined or expired. wait (at most ${WAIT_POLL_MAX_S} s) blocks for the answer; otherwise it shows up in the inbox tool.`,
+    description: `Ask a session a question, tracked until answered, declined or expired. wait (at most ${WAIT_POLL_MAX_S} s) blocks for the answer; otherwise it shows up in the inbox tool. To @me it opens a Decision for the user: give options (buttons) with a recommendation, or choices (several points in one ask), and urgency, tier and kind.`,
     properties: {
       to: TO,
       text: { ...STRING, description: "The question." },
+      ...DECISION_ASK_PROPERTIES,
       wait: { type: "number", minimum: 0, maximum: WAIT_POLL_MAX_S, description: `Seconds to wait for the answer (0–${WAIT_POLL_MAX_S}).` },
       expires: { type: ["number", "string"], description: "When the ask expires: seconds, or 30s, 5m, 2h, 1d (1 minute to 7 days; default 24 h)." },
       ...SEND,
@@ -862,7 +872,13 @@ const TOOLS: readonly Tool[] = [
       const text = need(args, "text")
       const wait = optionalWait(args)
       const expires = optionalExpires(args)
-      const options = { ...sendOptions(args), ...(expires !== undefined ? { expires } : {}), ...idemOption(args), signal }
+      let decision: ReturnType<typeof decisionAskFields>
+      try {
+        decision = decisionAskFields(args)
+      } catch (cause) {
+        throw new ArgError((cause as Error).message)
+      }
+      const options = { ...sendOptions(args), ...(expires !== undefined ? { expires } : {}), ...idemOption(args), ...decision, signal }
       if (optionalBool(args, "all")) {
         if (wait !== undefined) throw new ArgError(`"wait" cannot be combined with "all"`)
         return sentAllText(await hub.ask(to, text, { ...options, all: true }))

package/packages/cli/src/team-intake-mcp.ts

@@ -79,7 +79,7 @@ function notAfterOf(args: Args): number | undefined {
 }
 
 const line = (i: TeamIntake) =>
-  `${i.id}  ${i.status}${i.progress ? `/${i.progress}` : ""}  ${i.priority}  r${i.revision}  ${sanitizeText(i.title).replace(/\s+/g, " ")}`
+  `${i.id}  ${i.status}${i.progress ? `/${i.progress}` : ""}  ${i.priority}  r${i.revision}  ${sanitizeText(i.title).replace(/\s+/g, " ")}${i.usage ? `  wakes ${i.usage.wakes}/${i.usage.budget.wakes} · ${i.usage.hours.toFixed(1)}/${i.usage.budget.hours}h` : ""}`
 
 function intakeText(i: TeamIntake): string {
   const from = i.source.kind === "user" ? "the user" : i.source.kind === "app" ? `app ${i.source.tokenID}` : `session ${i.source.sessionID}`
@@ -95,6 +95,7 @@ function intakeText(i: TeamIntake): string {
     ...(i.ref ? [`ref: ${sanitizeText(i.ref)}`] : []),
     ...(i.reason ? [`reason: ${sanitizeText(i.reason)}`] : []),
     ...(i.lastError ? [`last routing error: ${i.lastError} (retried)`] : []),
+    ...(i.usage ? [`usage: ${i.usage.wakes}/${i.usage.budget.wakes} wakes · ${i.usage.hours.toFixed(1)}/${i.usage.budget.hours} hours (paused and blocked time counts)${i.usage.chargedTo ? `; last charged to ${i.usage.chargedTo}` : ""}`] : []),
   ].join("\n")
 }
 

package/packages/cli/src/teams-mcp.ts

@@ -51,7 +51,9 @@ const SPEC_FIELDS = {
   title: { ...STRING, description: "1–120 characters." },
   description: STRING,
   mode: { type: "string", enum: ["open", "restricted"], description: "open: every member may msg/ask every other member. restricted: only the drawn paths (edges)." },
-  hopLimit: { type: "integer", minimum: 1, maximum: 100, description: "Agent-only wake hop limit between this team's seats; may not exceed the hub-wide agents.hopLimit. Unset uses the global limit." },
+  hopLimit: { type: "integer", minimum: 1, maximum: 10_000, description: "Agent-only wake hop limit between this team's seats; at most the hub's hop ceiling (agent_limits hopCeiling, default 100). The effective limit is the lower of this and the hub-wide hopLimit. Unset uses the hub-wide limit." },
+  itemBudget: { type: "object", properties: { wakes: { type: "integer", minimum: 10, maximum: 5000 }, hours: { type: "integer", minimum: 1, maximum: 720 } }, required: ["wakes", "hours"], description: "User-only per-item budget override: agent wakes and hours in progress." },
+  loop: { type: "object", properties: { messages: { type: "integer", minimum: 4, maximum: 200 }, windowMinutes: { type: "integer", minimum: 5, maximum: 240 } }, required: ["messages", "windowMinutes"], description: "User-only no-progress pair-message threshold and window." },
   roles: { type: "array", items: ROLE, description: "1–32 roles." },
   entryRole: { ...STRING, description: "The role that receives submitted work (e.g. pm) and supervises members." },
   edges: { type: "array", items: EDGE, description: "Communication paths between roles (restricted mode)." },
@@ -178,6 +180,8 @@ function specLines(spec: TeamSpec): string[] {
   return [
     `mode: ${spec.mode}${spec.mode === "open" ? " (every member may msg/ask every other)" : " (only the paths below)"}`,
     ...(spec.hopLimit !== undefined ? [`hop limit: ${spec.hopLimit}`] : []),
+    ...(spec.itemBudget ? [`item budget: ${spec.itemBudget.wakes} wakes, ${spec.itemBudget.hours} hours`] : []),
+    ...(spec.loop ? [`loop: ${spec.loop.messages} messages per ${spec.loop.windowMinutes} minutes`] : []),
     `entry role: ${spec.entryRole}`,
     "roles:",
     ...spec.roles.map(role),
@@ -349,7 +353,7 @@ export const teamTools: readonly TeamTool[] = [
       need(args, "name")
       need(args, "title")
       const key = optional(args, "idempotencyKey")
-      const spec = picked(args, ["name", "title", "description", "mode", "hopLimit", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as unknown as TeamSpec
+      const spec = picked(args, ["name", "title", "description", "mode", "hopLimit", "itemBudget", "loop", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as unknown as TeamSpec
       const { team, created } = await hub.teams.create({ ...spec, edges: spec.edges ?? [] }, { signal, ...(key ? { idempotencyKey: key } : {}) })
       return [`${created ? "created" : "already created (same key)"}: ${teamLine(team)}`, ...specLines(team)].join("\n")
     },
@@ -364,7 +368,7 @@ export const teamTools: readonly TeamTool[] = [
     idempotent: true,
     run: async (hub, args, signal) => {
       const expectedRevision = revision(args)
-      const patch = picked(args, ["title", "description", "mode", "hopLimit", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as TeamPatch
+      const patch = picked(args, ["title", "description", "mode", "hopLimit", "itemBudget", "loop", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as TeamPatch
       if (Object.keys(patch).length === 0) throw new ArgError("give at least one field to change")
       const id = need(args, "team")
       const { team } = await hub.teams.update(id, patch, expectedRevision, { signal })

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.11.0",
+  "version": "0.11.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",

package/packages/codex/src/sessions.ts

@@ -92,7 +92,17 @@ const RECENT_TURNS = 50
 
 /** Who an input the spoke sent is from: the hub's turn/steer ops are the user's, carried by the hub. */
 type Origin = "carried" | "hub"
-type TurnEnd = { readonly status: string; readonly error?: string }
+type TurnEnd = { readonly status: string; readonly error?: string; readonly errorType?: string }
+
+/**
+ * (SS-9) A failed turn's codexErrorInfo as error.type "codex.<snake_case>": a camelCase string ("usageLimitExceeded",
+ * "other") or a one-key object ({httpConnectionFailed: {httpStatusCode}}). Anything else gives no type.
+ */
+function codexErrorType(info: unknown): string | undefined {
+  const name = typeof info === "string" ? info : isObj(info) && Object.keys(info).length === 1 ? Object.keys(info)[0] : undefined
+  if (!name || !/^[a-z][A-Za-z0-9]{0,40}$/.test(name)) return undefined
+  return `codex.${name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`)}`
+}
 
 interface TurnWaiter {
   resolve(end: TurnEnd): void
@@ -529,7 +539,8 @@ export class CodexSessions {
     if (!turnID) return
     const status = typeof turn.status === "string" ? turn.status : "completed"
     const error = isObj(turn.error) && typeof turn.error.message === "string" ? cut(turn.error.message, HARNESS_ERROR_MAX) : undefined
-    const end: TurnEnd = { status, ...(error !== undefined ? { error } : {}) }
+    const errorType = isObj(turn.error) ? codexErrorType(turn.error.codexErrorInfo) : undefined
+    const end: TurnEnd = { status, ...(error !== undefined ? { error } : {}), ...(errorType !== undefined ? { errorType } : {}) }
     if (thread.turnID === turnID) thread.turnID = undefined
     thread.ended.set(turnID, end)
     while (thread.ended.size > RECENT_TURNS) thread.ended.delete(thread.ended.keys().next().value!)
@@ -537,7 +548,7 @@ export class CodexSessions {
     if (thread.reply) this.#emit({ type: "session.text.ended", data: { sessionID, assistantMessageID: plainID(thread.reply.id), ordinal: 0, text: cut(thread.reply.text, HARNESS_TEXT_MAX) } })
     const data = { sessionID, turnID: plainID(turnID) }
     if (status === "interrupted") this.#emit({ type: "session.execution.interrupted", data })
-    else if (status === "failed") this.#emit({ type: "session.execution.failed", data: { ...data, ...(error !== undefined ? { error: { message: error } } : {}) } })
+    else if (status === "failed") this.#emit({ type: "session.execution.failed", data: { ...data, ...(error !== undefined ? { error: { message: error, ...(end.errorType ? { type: end.errorType } : {}) } } : {}) } })
     else this.#emit({ type: "session.execution.succeeded", data })
     thread.items.clear()
     const waiter = thread.waiters.get(turnID)

package/packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-node",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "private": true,
   "description": "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-preset",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "private": true,
   "description": "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-protocol",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/schema/api/v1/_root.json

@@ -0,0 +1,119 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Hub API",
+    "version": "1",
+    "description": "The versioned HTTP API of a Hub: every route of the console and agent tables under /api/v1. v1 changes only by addition: clients ignore fields they do not know, treat a value outside an `x-hub-known` list as unknown, and skip a variant of an `x-hub-union` they do not know. Every error is one envelope: {error: {code, message, hint?}}."
+  },
+  "servers": [
+    {
+      "url": "https://hub.example",
+      "description": "A placeholder: the address of your hub."
+    }
+  ],
+  "security": [
+    {
+      "deviceToken": []
+    }
+  ],
+  "components": {
+    "securitySchemes": {
+      "deviceToken": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "A device token: what a native app gets when it redeems a link code (POST /api/v1/devices/redeem). A request with a bearer token needs no Origin."
+      },
+      "deviceCookie": {
+        "type": "apiKey",
+        "in": "cookie",
+        "name": "voice_device",
+        "description": "The browser's credential: the same secret as the device token, as an HttpOnly cookie set when a browser pairs or signs in. A write with the cookie must be same-origin. Send the cookie or a bearer token, never both. Declared here for readers and never listed as a requirement: a generated client sends the bearer token only."
+      }
+    },
+    "responses": {
+      "Error": {
+        "description": "Any error (status 400 and up): the one envelope of /api/v1.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorBody"
+            }
+          }
+        }
+      }
+    },
+    "schemas": {
+      "ErrorBody": {
+        "type": "object",
+        "required": ["error"],
+        "properties": {
+          "error": {
+            "$ref": "#/components/schemas/ErrorDetail"
+          }
+        }
+      },
+      "ErrorDetail": {
+        "type": "object",
+        "description": "What went wrong. A code may come with more fields (for example retryAfter, currentRevision, candidates, feature, limit).",
+        "required": ["code", "message"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Stable and machine-readable. A route that names no code of its own gets one from the status (400 invalid, 401 unauthorized, 403 forbidden, 404 not_found, 408 and 504 timeout, 409 conflict, 410 gone, 413 too_large, 422 unsupported, 429 rate_limited, 500 internal, 502 upstream_failed, 503 unavailable).",
+            "x-hub-known": [
+              "ambiguous",
+              "bad_answer",
+              "bad_bundle",
+              "busy",
+              "changed",
+              "conflict",
+              "developer_off",
+              "dimensions",
+              "expired",
+              "forbidden",
+              "gone",
+              "hidden",
+              "integrity",
+              "internal",
+              "invalid",
+              "invalid_cursor",
+              "limit",
+              "name_taken",
+              "needs_user",
+              "not_exposed",
+              "not_found",
+              "offline",
+              "path",
+              "paused",
+              "plugin_outdated",
+              "rate_limited",
+              "recording_ended",
+              "recording_off",
+              "refused",
+              "timeout",
+              "token_expired",
+              "too_large",
+              "too_old",
+              "type",
+              "unauthorized",
+              "unavailable",
+              "unsupported",
+              "upstream_failed"
+            ]
+          },
+          "message": {
+            "type": "string",
+            "description": "For people."
+          },
+          "hint": {
+            "type": "string",
+            "description": "What to do about it, when the hub knows."
+          }
+        }
+      },
+      "JsonValue": {
+        "description": "Any JSON value: an object, an array, a string, a number, a boolean or null. For data whose shape the hub does not define (a tool's input, a harness's own metadata). Clients map it to their JSON element type."
+      }
+    }
+  }
+}