@huynle/hub 0.10.1 → 0.11.1

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-cli",
-  "version": "0.10.1",
+  "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/grants-mcp.ts

@@ -0,0 +1,65 @@
+// MCP grant tools: the server owns authority. Requests use the existing tap Decision route; /mine never widens
+// the user-only grant administration routes. A user credential may create directly but has no /mine holder.
+import type { HubClient } from "../../sdk/src/client.ts"
+import type { GrantRequestSpec, GrantSpec } from "../../sdk/src/types.ts"
+import { grantError, grantText, grantsText, GRANT_USER_HINT, requestedText } from "./grants"
+import { CliError, EXIT } from "./http"
+import { ToolArgError } from "./tool-args"
+
+type Args = Record<string, unknown>
+export interface GrantTool {
+  readonly name: string
+  readonly description: string
+  readonly properties: Record<string, unknown>
+  readonly required?: readonly string[]
+  readonly readOnly: boolean
+  readonly organizes?: boolean
+  run(hub: HubClient, args: Args, signal: AbortSignal): Promise<string>
+}
+
+const STRING = { type: "string" } as const
+const GRANT = { type: "object", description: "The grant spec accepted by POST /api/agent/grants: holder (optional for a request), scope.projects, allow, permissions, allowAlways, maxActionsPerHour and expires. The server validates all fields.", additionalProperties: true } as const
+const need = (args: Args, key: string): string => {
+  if (typeof args[key] !== "string" || !(args[key] as string).trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
+  return args[key] as string
+}
+const spec = (args: Args): Record<string, unknown> => {
+  if (typeof args.grant !== "object" || args.grant === null || Array.isArray(args.grant)) throw new ToolArgError('"grant" is required (an object)')
+  return args.grant as Record<string, unknown>
+}
+
+export const grantTools: readonly GrantTool[] = [
+  {
+    name: "grant_request", description: "Ask the user for a grant: opens one tap Decision for @me (approve or deny). Sessions and apps with messages:send only; one open request and at most five per hour. Only the user's answer creates authority.",
+    properties: { grant: GRANT, why: STRING }, required: ["grant", "why"], readOnly: false,
+    run: async (hub, args, signal) => requestedText(await hub.requestGrant(spec(args) as GrantRequestSpec, need(args, "why"), { signal })),
+  },
+  {
+    name: "grant_list", description: "List grants (active, expired or revoked) whose holder is this session or app, including grants for roles it holds now. Apps need messages:read. A user credential has no holder: use the console or hub grant list for administration.",
+    properties: {}, readOnly: true,
+    run: async (hub, _args, signal) => grantsText((await hub.heldGrants({ signal })).grants),
+  },
+  {
+    name: "grant_show", description: "Show one grant only if this credential currently holds it. Apps need messages:read; another holder's ID answers not_found.",
+    properties: { id: STRING }, required: ["id"], readOnly: true,
+    run: async (hub, args, signal) => grantText((await hub.heldGrant(need(args, "id"), { signal })).grant),
+  },
+  {
+    name: "grant_revoke", description: "Irreversibly revoke a grant held by this session or app (including a held role shared with other holders). Apps need messages:send; another holder's ID answers not_found.",
+    properties: { id: STRING }, required: ["id"], readOnly: false,
+    run: async (hub, args, signal) => grantText((await hub.revokeHeldGrant(need(args, "id"), { signal })).grant),
+  },
+  {
+    name: "grant_create", description: `Create a grant directly ONLY with the user's device credential. Sessions and apps must use grant_request and wait for the user's tap. ${GRANT_USER_HINT}.`,
+    properties: { grant: GRANT }, required: ["grant"], readOnly: false,
+    run: async (hub, args, signal) => {
+      const actor = (await hub.whoami({ signal })).actor
+      if (actor.kind !== "user") throw new CliError(EXIT.forbidden, "only the user can create a grant, not a session or app", GRANT_USER_HINT)
+      try {
+        return grantText((await hub.createGrant(spec(args) as unknown as GrantSpec, { signal })).grant)
+      } catch (cause) {
+        throw grantError(cause)
+      }
+    },
+  },
+]

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

@@ -0,0 +1,49 @@
+// User-only MCP access to the existing console session-model route and owner-scoped machine/node snapshots.
+// No agent or app model-setting authority: the server's model route remains console user-only.
+import type { HubClient } from "../../sdk/src/client.ts"
+import { CliError, EXIT } from "./http"
+import { ToolArgError } from "./tool-args"
+
+type Args = Record<string, unknown>
+interface Tool {
+  readonly name: string
+  readonly description: string
+  readonly properties: Record<string, unknown>
+  readonly required?: readonly string[]
+  readonly readOnly: boolean
+  run(hub: HubClient, args: Args, signal: AbortSignal): Promise<string>
+}
+const STRING = { type: "string" } as const
+const need = (args: Args, key: string) => {
+  const v = args[key]
+  if (typeof v !== "string" || !v.trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
+  return v
+}
+const userOnly = async (hub: HubClient, signal: AbortSignal) => {
+  if ((await hub.whoami({ signal })).actor.kind !== "user") throw new CliError(EXIT.forbidden, "only the user can use this tool", "Use the user's device credential")
+}
+
+export const operationTools: readonly Tool[] = [
+  {
+    name: "session_model_set", description: "Set one existing session's model (providerID, modelID and optional variant), exactly as the console Model chip does. User device credential only; the console route checks ownership, catalog, availability and audit. An app or session cannot set it.",
+    properties: { session: STRING, model: { type: "object", properties: { providerID: STRING, modelID: STRING, variant: STRING }, required: ["providerID", "modelID"] } },
+    required: ["session", "model"], readOnly: false,
+    run: async (hub, args, signal) => {
+      await userOnly(hub, signal)
+      const model = args.model
+      if (typeof model !== "object" || model === null || Array.isArray(model)) throw new ToolArgError('"model" is required (providerID, modelID, variant?)')
+      const result = await hub.call<{ model: unknown }>("PUT", `/api/sessions/${encodeURIComponent(need(args, "session"))}/model`, { body: { model }, signal })
+      return JSON.stringify(result)
+    },
+  },
+  {
+    name: "machines", description: "The user's own enrolled machines, online status and processes. User device credential only; wraps GET /api/machines. No machine tokens or secrets.",
+    properties: {}, readOnly: true,
+    run: async (hub, _args, signal) => { await userOnly(hub, signal); return JSON.stringify(await hub.call("GET", "/api/machines", { signal })) },
+  },
+  {
+    name: "launch_nodes", description: "The user's connected launch nodes: machine, workspace roots, capacity/used/free slots, runtimes (harnesses) and labels. User device credential only; no tokens, connection IDs or mutation.",
+    properties: {}, readOnly: true,
+    run: async (hub, _args, signal) => { await userOnly(hub, signal); return JSON.stringify(await hub.call("GET", "/api/agent/launch-nodes", { signal })) },
+  },
+]

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"
@@ -25,8 +25,11 @@ import { launchedText, launchesText, launchText, stoppedLaunchText } from "./lau
 import { artifactTools } from "./artifacts-mcp"
 import { artifactJobTools } from "./artifact-jobs-mcp"
 import { teamIntakeTools } from "./team-intake-mcp"
+import { subscriptionTools } from "./subscriptions-mcp"
+import { operationTools } from "./mcp-operations"
 import { teamTools } from "./teams-mcp"
 import { profileLifecycleTools } from "./profiles-mcp"
+import { grantTools } from "./grants-mcp"
 import { ToolArgError } from "./tool-args"
 import { watchlistTools } from "./watchlist"
 
@@ -123,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. */
@@ -235,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)." },
@@ -755,12 +760,22 @@ const TOOLS: readonly Tool[] = [
   ...webhookTools,
   ...profileTools,
   ...profileLifecycleTools,
+  ...grantTools,
   ...workspaceTools,
   ...artifactTools,
   ...artifactJobTools,
   ...teamIntakeTools,
+  ...subscriptionTools,
+  ...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.",
@@ -840,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,
@@ -856,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/subscriptions-mcp.ts

@@ -0,0 +1,76 @@
+// MCP wrappers over the existing subscription routes; authorization and delivery caps remain on the server.
+import type { HubClient } from "../../sdk/src/client.ts"
+import type { SubscribeInput } from "../../sdk/src/types.ts"
+import { subscribedText, subscriptionsText } from "./subscriptions"
+import { ToolArgError } from "./tool-args"
+
+type Args = Record<string, unknown>
+export interface SubscriptionTool {
+  readonly name: string
+  readonly description: string
+  readonly properties: Record<string, unknown>
+  readonly required?: readonly string[]
+  readonly readOnly: boolean
+  readonly organizes?: boolean
+  run(hub: HubClient, args: Args, signal: AbortSignal): Promise<string>
+}
+const STRING = { type: "string" } as const
+const need = (args: Args, key: string): string => {
+  const value = args[key]
+  if (typeof value !== "string" || !value.trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
+  return value
+}
+const optional = (args: Args, key: string): string | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "string") throw new ToolArgError(`"${key}" must be a string`)
+  return value.trim() || undefined
+}
+const array = (args: Args, key: string): string[] | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) throw new ToolArgError(`"${key}" must be a list of strings`)
+  return value
+}
+const number = (args: Args, key: string, min: number, max: number): number | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) throw new ToolArgError(`"${key}" must be a whole number from ${min} to ${max}`)
+  return value
+}
+
+export const subscriptionTools: readonly SubscriptionTool[] = [
+  {
+    name: "subscribe", description: "Follow journal events for a subscriber session. A session subscribes itself; users and apps name subscriber. Apps need events:subscribe, sessions:read, relevant type scopes and messages:send unless silent. Hub checks visibility, rates and loops.",
+    properties: {
+      to: { type: ["string", "array"], items: STRING, description: "One or more session/role/team addresses, or children." },
+      subscriber: STRING, types: { type: "array", items: STRING }, delivery: { type: "string", enum: ["queue", "steer", "silent"] },
+      batch: { type: "number", description: "Seconds per batch (1–3600)." }, expires: { type: "number", description: "Seconds until expiry." },
+      maxPerHour: { type: "integer", minimum: 1, maximum: 120 }, note: STRING,
+    }, required: ["to"], readOnly: false,
+    run: async (hub, args, signal) => {
+      const to = typeof args.to === "string" && args.to.trim() ? args.to : array(args, "to")
+      if (!to || (Array.isArray(to) && !to.length)) throw new ToolArgError('"to" needs at least one address')
+      const delivery = optional(args, "delivery")
+      if (delivery && !["queue", "steer", "silent"].includes(delivery)) throw new ToolArgError('"delivery" is queue, steer or silent')
+      const subscriber = optional(args, "subscriber")
+      const types = array(args, "types")
+      const batch = number(args, "batch", 1, 3600)
+      const expires = number(args, "expires", 1, 30 * 86400)
+      const maxPerHour = number(args, "maxPerHour", 1, 120)
+      const note = optional(args, "note")
+      const input: SubscribeInput = { to, ...(subscriber ? { subscriber } : {}), ...(types ? { types } : {}), ...(delivery ? { delivery: delivery as SubscribeInput["delivery"] } : {}), ...(batch ? { batch } : {}), ...(expires ? { expires } : {}), ...(maxPerHour ? { maxPerHour } : {}), ...(note ? { note } : {}) }
+      return subscribedText(await hub.subscribe(input, { signal }))
+    },
+  },
+  {
+    name: "subscriptions", description: "List subscriptions visible to this credential (session: its own; app: created by it; user: all). Optional session filter; route enforces scopes and tenancy.",
+    properties: { session: STRING }, readOnly: true,
+    run: async (hub, args, signal) => subscriptionsText(await hub.subscriptions({ ...(optional(args, "session") ? { session: optional(args, "session") } : {}), signal })),
+  },
+  {
+    name: "unsubscribe", description: "Remove a subscription this credential owns. An unknown or another caller's ID answers not_found.",
+    properties: { id: STRING }, required: ["id"], readOnly: false, organizes: true,
+    run: async (hub, args, signal) => { const id = need(args, "id"); await hub.unsubscribe(id, { signal }); return `unsubscribed ${id}` },
+  },
+]

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,6 +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: 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)." },
@@ -176,6 +179,9 @@ function specLines(spec: TeamSpec): string[] {
     `  ${r.name}${r.name === spec.entryRole ? " (entry)" : ""}${r.label ? `  "${one(r.label)}"` : ""}${r.externalContact ? "  external contact" : ""}${r.minMembers !== undefined || r.maxMembers !== undefined ? `  members ${r.minMembers ?? 0}–${r.maxMembers ?? 16}` : ""}${r.profile ? `  profile ${r.profile.profileID}${r.profile.version ? `@${r.profile.version}` : ""}` : ""}`
   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),
@@ -196,7 +202,7 @@ function rosterLines(roster: TeamRoster): string[] {
     const flags = [r.vacant ? "vacant" : "", r.understaffed ? `understaffed (min ${r.minMembers})` : "", r.launching ? `${r.launching} launching` : ""].filter(Boolean)
     lines.push(`  ${r.role}${r.entry ? " (entry)" : ""}  ${r.seats.length}/${r.maxMembers}  ${r.online} online${flags.length ? `  ${flags.join(", ")}` : ""}`)
     for (const s of r.seats)
-      lines.push(`    ${s.staffing.id}  ${s.staffing.sessionID}  ${s.presence}  gen ${s.staffing.generation} r${s.staffing.revision}${s.profile ? `  profile ${s.profile.status}${s.profile.matches ? "" : " (mismatch)"}` : ""}`)
+      lines.push(`    ${s.staffing.id}  ${s.staffing.sessionID}  ${s.presence}${s.stalled ? `  stalled: ${s.stalled}` : ""}  gen ${s.staffing.generation} r${s.staffing.revision}${s.profile ? `  profile ${s.profile.status}${s.profile.matches ? "" : " (mismatch)"}` : ""}`)
   }
   const failed = roster.requests.filter((q) => q.state !== "staffed").slice(-5)
   for (const q of failed) lines.push(`  launch ${q.id}  ${q.role}  ${q.state}${q.reason ? `: ${one(q.reason)}` : ""}`)
@@ -347,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", "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")
     },
@@ -362,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", "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.10.1",
+  "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.10.1",
+  "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.10.1",
+  "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.10.1",
+  "version": "0.11.1",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",