@huynle/hub 0.9.1 → 0.10.0

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-cli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "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

@@ -23,6 +23,7 @@ import { currentProgram, installNode, nodeStatus, nodeStatusText, runNodeCommand
 import { checkOpenShell, openShellCheckText } from "./openshell"
 import { LAUNCH_FLAGS, launchedText, launchesText, launchSpecArg, launchText, stoppedLaunchText } from "./launches"
 import { watchlistText, watchlistVerbText } from "./watchlist"
+import { SUBSCRIBE_FLAGS, subscribeInput, subscribedText, subscriptionsText } from "./subscriptions"
 import { claudeCodeMain } from "../../claude-code/src/main.ts"
 import { runClaude } from "../../claude-code/src/wrapper.ts"
 import { presetMain } from "../../preset/src/main.ts"
@@ -73,7 +74,7 @@ Reading
 
 Identity
   hub whoami                          who this credential is
-  hub who [--project P] [--role R] [--team T]  named and role-holding sessions (team members: their teams)
+  hub who [--project P] [--role R] [--team T]  online, named and role-holding sessions (team members: their teams)
   hub name <@name> [--session <addr>]
   hub intent <addr> [text… | --clear]  what the session is for (one line, ≤ 280 characters, untrusted);
                                       no text: show it (else its title); a session token sets only its own
@@ -190,6 +191,15 @@ Codex (app-server spoke)
   hub codex-spoke install|uninstall [--dry-run] | status
                                       the spoke service as a launchd agent / systemd user unit (printed, never loaded)
 
+Subscriptions (a session hears other sessions' events as batched hub messages; docs/subscriptions.md)
+  hub subscribe <addr|@@role|#team|children>... [--type T]... [--delivery queue|steer|silent] [--batch 30s]
+         [--expires 1d] [--max-per-hour N] [--subscriber <addr>] [--note "…"]
+                                      types: state, state:idle, blocker, message, launch, naming, presence,
+                                      manage, exact types or * (default state, blocker); in a session's shell it
+                                      subscribes itself, a login names --subscriber (app tokens: events:subscribe)
+  hub subscriptions [--session <addr>]   yours (or what a session subscribes to and what follows it)
+  hub unsubscribe <subID>
+
 Concierge watchlist (users; app tokens: sessions:read to show, sessions:manage to change)
   hub watchlist [show]                what the Concierge watches now, and why; its config and revision
   hub watchlist watch|unwatch <addr>  watch a session (a subagent: its root), or stop
@@ -781,6 +791,31 @@ const COMMANDS: Record<string, Command> = {
       answer(context, body, (b) => watchlistVerbText("unmute", b))
     },
   },
+  subscribe: {
+    args: ["addr..."],
+    flags: SUBSCRIBE_FLAGS,
+    async handle(context) {
+      const input = subscribeInput(context.parsed.args, context.parsed.flags)
+      const body = await context.hub((hub) => hub.subscribe(input))
+      answer(context, body, subscribedText)
+    },
+  },
+  subscriptions: {
+    flags: { session: "string" },
+    async handle(context) {
+      const session = str(context.parsed.flags, "session")
+      const body = await context.hub((hub) => hub.subscriptions(session !== undefined ? { session } : {}))
+      answer(context, body, subscriptionsText)
+    },
+  },
+  unsubscribe: {
+    args: ["<subID>"],
+    async handle(context) {
+      const id = context.parsed.args[0]!
+      await context.hub((hub) => hub.unsubscribe(id))
+      answer(context, { removed: id }, () => `removed ${id}`)
+    },
+  },
   logout: {
     async handle(context) {
       const file = loginFile(context.io.env, context.io.home)

package/packages/cli/src/subscriptions.ts

@@ -0,0 +1,49 @@
+// `hub subscribe <addr>…`, `hub unsubscribe <id>` and `hub subscriptions [--session <addr>]` (decision 74qawely;
+// docs/subscriptions.md): flags to a SubscribeInput and the text output. In a session's shell the session subscribes
+// itself; a user or app login names the subscriber with --subscriber.
+import { sanitizeLabel } from "../../sdk/src/envelope.ts"
+import type { SubscribeInput, SubscriptionView } from "../../sdk/src/index.ts"
+import { type Parsed, str, UsageError } from "./args"
+import { durationArg } from "./messaging"
+
+export const SUBSCRIBE_FLAGS = { type: "multi", delivery: "string", batch: "string", expires: "string", "max-per-hour": "string", subscriber: "string", note: "string" } as const
+
+const DELIVERIES = ["queue", "steer", "silent"]
+const safe = (v: unknown, max = 120) => sanitizeLabel(String(v), max)
+
+/** The body of `hub subscribe <addr>… [flags]`; throws UsageError. */
+export function subscribeInput(addrs: readonly string[], flags: Parsed["flags"]): SubscribeInput {
+  if (!addrs.length) throw new UsageError("needs at least one address (a session, @@role, #team or children)")
+  const delivery = str(flags, "delivery")
+  if (delivery !== undefined && !DELIVERIES.includes(delivery)) throw new UsageError(`--delivery is one of ${DELIVERIES.join(", ")}`)
+  const batch = str(flags, "batch")
+  const expires = str(flags, "expires")
+  const max = str(flags, "max-per-hour")
+  if (max !== undefined && !/^\d+$/.test(max)) throw new UsageError("--max-per-hour takes a whole number (1–120)")
+  const types = flags.type as string[] | undefined
+  const subscriber = str(flags, "subscriber")
+  const note = str(flags, "note")
+  return {
+    to: addrs.length === 1 ? addrs[0]! : [...addrs],
+    ...(types?.length ? { types: types.flatMap((t) => t.split(",")).map((t) => t.trim()).filter(Boolean) } : {}),
+    ...(delivery !== undefined ? { delivery: delivery as SubscribeInput["delivery"] } : {}),
+    ...(batch !== undefined ? { batch: durationArg(batch, "--batch") } : {}),
+    ...(expires !== undefined ? { expires: durationArg(expires, "--expires") } : {}),
+    ...(max !== undefined ? { maxPerHour: Number(max) } : {}),
+    ...(subscriber !== undefined ? { subscriber } : {}),
+    ...(note !== undefined ? { note } : {}),
+  }
+}
+
+const targets = (s: SubscriptionView) => s.targets.map((t) => (t.kind === "children" ? "its subagents" : safe(t.addr, 80))).join(", ")
+const iso = (ms: number) => new Date(ms).toISOString().slice(0, 16) + "Z"
+
+export function subscriptionLine(s: SubscriptionView): string {
+  const extra = [safe(s.delivery, 10), `batch ${Math.round(s.batchMs / 1000)}s`, `≤${s.maxPerHour}/h`, `expires ${iso(s.expiresAt)}`, `${s.stats.delivered} delivered`, ...(s.pending ? [`${s.pending} pending`] : []), ...(s.stats.dropped ? [`${s.stats.dropped} dropped`] : []), ...(s.stats.suppressed ? [`${s.stats.suppressed} loop-suppressed`] : [])]
+  return `${safe(s.id, 40)}  ${safe(s.subscriber, 80)} ← ${targets(s)}  [${s.types.map((t) => safe(t, 40)).join(",")}]  ${extra.join(" · ")}${s.note ? `  "${safe(s.note, 200)}"` : ""}`
+}
+
+export const subscribedText = (b: { subscription: SubscriptionView }) =>
+  `subscribed ${subscriptionLine(b.subscription)}\nthe subscriber gets one hub message per batch window; stop with \`hub unsubscribe ${safe(b.subscription.id, 40)}\``
+
+export const subscriptionsText = (b: { subscriptions: SubscriptionView[] }) => (b.subscriptions.length ? b.subscriptions.map(subscriptionLine).join("\n") : "no subscriptions")

package/packages/codex/package.json

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

@@ -8,8 +8,9 @@
 //   turn/completed → the reply (session.text.ended: the turn's last agent message), then succeeded, failed or
 //   interrupted, as Codex confirms it (the spoke announces turnEvents: the hub trusts its rpc evidence for idle).
 // - item/started userMessage → session.inbox.delivered: origin "hub" for input the spoke sent for a hub message
-//   (matched by clientUserMessageId, which Codex echoes as the item's clientId), else "user" (typed in the TUI, or
-//   the hub's own turn/steer ops, which are the user's).
+//   (matched by clientUserMessageId, which Codex echoes as the item's clientId), else "user": typed in the TUI, or
+//   the hub's own turn/steer ops (the user's, marked `carried: true` so the hub never counts them again as typed in
+//   the TUI; feature inboxCarried).
 // - tool items (commands, file changes, MCP and dynamic tools, web searches) → session.tool.called/success/failed,
 //   compacted to an ID and a short summary.
 // - thread/name/updated → session.renamed; thread/archived|deleted → session.deleted; closed → no longer reported.
@@ -89,7 +90,8 @@ const TOOL_ITEMS = new Set(["commandExecution", "fileChange", "mcpToolCall", "dy
 const APPROVALS: Record<string, "shell" | "edit"> = { "item/commandExecution/requestApproval": "shell", "item/fileChange/requestApproval": "edit" }
 const RECENT_TURNS = 50
 
-type Origin = "user" | "hub"
+/** 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 }
 
 interface TurnWaiter {
@@ -366,7 +368,7 @@ export class CodexSessions {
   async turn(req: Extract<ServerRequest, { op: "turn" }>): Promise<TurnResult> {
     const thread = this.#thread(req.sessionID)
     if (thread.turnID) throw new Error("The Codex session is busy (a turn is running); steer it instead")
-    const turnID = await this.#startTurn(thread, input(req.text, req.images), "user")
+    const turnID = await this.#startTurn(thread, input(req.text, req.images), "carried")
     const end = await this.#waitTurn(thread, turnID)
     const reply = thread.reply?.text ?? ""
     if (!end) return { outcome: "timeout", reply }
@@ -377,7 +379,7 @@ export class CodexSessions {
   async steer(req: Extract<ServerRequest, { op: "steer" }>): Promise<ResultFor["steer"]> {
     const thread = this.#thread(req.sessionID)
     const id = inboxID()
-    await this.#steerOrStart(thread, input(req.text, req.images), "user", id)
+    await this.#steerOrStart(thread, input(req.text, req.images), "carried", id)
     return { inboxID: id }
   }
 
@@ -552,7 +554,9 @@ export class CodexSessions {
       const clientID = str(item.clientId)
       const origin = clientID ? thread.inputs.get(clientID) : undefined
       if (clientID) thread.inputs.delete(clientID)
-      this.#emit({ type: "session.inbox.delivered", data: { sessionID: thread.hubID, inboxID: plainID(clientID && origin ? clientID : item.id), origin: origin ?? "user" } })
+      const inboxID = plainID(clientID && origin ? clientID : item.id)
+      const data = origin === "hub" ? { origin: "hub" as const } : origin === "carried" ? { origin: "user" as const, carried: true as const } : { origin: "user" as const }
+      this.#emit({ type: "session.inbox.delivered", data: { sessionID: thread.hubID, inboxID, ...data } })
       return
     }
     if (!TOOL_ITEMS.has(item.type)) return

package/packages/codex/src/spoke.ts

@@ -115,7 +115,8 @@ export function startCodexSpoke(options: CodexSpokeOptions): CodexSpoke {
       profileApply: profiles.handle,
     },
     deliver: (req) => sessions.deliver(req),
-    features: ["hubPrompt", "launch", "turnEvents"],
+    // inboxCarried: the hub's turn/steer inputs are reported carried (sessions.ts #itemStarted).
+    features: ["hubPrompt", "launch", "turnEvents", "inboxCarried"],
     onState: (state, error) => log(`hub connection ${state}${error ? `: ${error}` : ""}`),
     ...(options.socket ? { socket: options.socket } : {}),
     ...(options.backoff ? { backoff: options.backoff } : {}),

package/packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-node",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "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.9.1",
+  "version": "0.10.0",
   "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.9.1",
+  "version": "0.10.0",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/schema/app-delivery/v1.schema.json

@@ -28,11 +28,11 @@
     "ReplayedHeader": { "description": "Value of the response header `idempotent-replayed` on an idempotent replay.", "const": "true" },
 
     "ErrorCode": {
-      "description": "The /api/agent error codes (AGENT_ERROR_STATUS in src/central/agent/errors.ts; `expired` shipped with H2).",
-      "enum": ["invalid", "invalid_cursor", "unauthorized", "token_expired", "needs_user", "forbidden", "not_found", "ambiguous", "name_taken", "conflict", "gone", "unsupported", "expired", "paused", "rate_limited", "internal", "offline", "busy"]
+      "description": "The /api/agent error codes (AGENT_ERROR_STATUS in src/central/agent/errors.ts; `expired` shipped with H2, `upstream_failed` with the app front's speech, AF2).",
+      "enum": ["invalid", "invalid_cursor", "unauthorized", "token_expired", "needs_user", "forbidden", "not_found", "ambiguous", "name_taken", "conflict", "gone", "unsupported", "expired", "paused", "rate_limited", "internal", "upstream_failed", "offline", "busy"]
     },
     "ErrorCodeStatus": {
-      "description": "The HTTP status of each error code (AGENT_ERROR_STATUS). `expired` is 422 like `unsupported`.",
+      "description": "The HTTP status of each error code (AGENT_ERROR_STATUS). `expired` is 422 like `unsupported`; `upstream_failed` (AF2: the user's speech provider failed) is 502.",
       "const": {
         "invalid": 400,
         "invalid_cursor": 400,
@@ -50,6 +50,7 @@
         "paused": 423,
         "rate_limited": 429,
         "internal": 500,
+        "upstream_failed": 502,
         "offline": 503,
         "busy": 503
       }
@@ -198,7 +199,7 @@
     "DecisionUrgency": { "enum": ["low", "normal", "high"] },
     "DecisionTier": { "enum": ["confirm", "tap"] },
     "Decision": {
-      "description": "An ask to @me (Decision in src/central/agent/decisions.ts). Answered only by the user on the console.",
+      "description": "An ask to @me (Decision in src/central/agent/decisions.ts). Answered by the user on the console, or (AF4, app-front contract §6) a confirm-tier one without an action by an app for its own session's ask (POST /api/agent/decisions/:id/answer, decisions:answer).",
       "type": "object",
       "required": ["id", "messageID", "from", "about", "question", "options", "urgency", "tier", "state", "at", "expiresAt"],
       "properties": {
@@ -224,7 +225,8 @@
         "answer": {
           "type": "object",
           "required": ["answeredBy", "at"],
-          "properties": { "option": { "type": "string" }, "text": { "type": "string" }, "answeredBy": { "enum": ["user", "timeout"] }, "at": { "$ref": "#/$defs/EpochMs" } }
+          "description": "answeredBy: user (the console), timeout (the safe onTimeout option), or (AF4, app-front contract §6) app: an app holding decisions:answer answered a confirm-tier Decision of its own session; then `app` is its party (app:<tokenID>) and `appLabel` its label.",
+          "properties": { "option": { "type": "string" }, "text": { "type": "string" }, "answeredBy": { "enum": ["user", "timeout", "app"] }, "at": { "$ref": "#/$defs/EpochMs" }, "app": { "type": "string", "pattern": "^app:[0-9a-f]{16}$" }, "appLabel": { "type": "string" } }
         },
         "closed": { "type": "object", "required": ["at", "reason"], "properties": { "at": { "$ref": "#/$defs/EpochMs" }, "reason": { "type": "string" } } }
       }