@huynle/hub 0.10.1 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 0.11.1
+
+Agents can send structured asks to `@me` (choices, kind, recommendation) from the OpenCode `hub` tool, MCP, the SDK
+and the CLI, and teams tag work items. Also since 0.11.0: team autonomy phase 2 (per-item wake budgets with an
+Extend/Stop Decision, loop detection, progress resets), session health on session reads, a configurable hub hop
+ceiling, the team Renew button, live agent-limit pins and a startup retry, and typed wake-skip limits. Update the
+plugin (npm `@huynle/hub`) and restart OpenCode to get the new hub tool.
+
+- Teams: each team card and team page shows `hops N/limit`, a `stalled: hop cap` badge and a **Renew** button that
+  resets every current seat's hop depth and closes an open Renew Decision (console cookie only, audited as
+  `team.hops.reset` kind `manual`); `GET /api/teams/:id/hops` reads the depths.
+- Agents can send structured asks to `@me`: the OpenCode `hub` tool and the MCP `ask` tool take `options`,
+  `recommendation`, `urgency`, `tier`, `kind` and `choices`; the SDK's `AskOptions` take `choices` and `kind` (and
+  `answerDecision` takes `picks`); the CLI adds `hub ask @me --choice "D1=Label:a=Option*,b=Option" --kind plan`.
+- Decisions: an ask to `@me` may carry structured `choices` (1–12 groups of 2–6 options, at most one recommended
+  per group; not with `options`) and a `kind` (question, plan, merge, release). The user answers with `picks`, one
+  option per group, or with text alone; the asker reads one `D1: label [a]` line per group. The API schemas and the
+  recording events `decision.answered` and `decision.voice` carry the picks.
+- Hub text sanitising (message text, labels, Decision questions and choices) now also removes every Unicode format
+  character (`\p{Cf}`), including TAG characters (U+E0000–E007F) and the soft hyphen. Side effect: emoji built
+  from tag sequences, such as the England and Scotland flags, show as a plain black flag. Zero-width joiners and
+  directional marks (U+200B–200F) were already removed, so compound emoji split up and RTL marks are dropped in
+  labels as before.
+- Wake-skip replies now carry `wakeLimit` for the effective team/hub hop cap or recipient wake budget. The CLI, MCP
+  tools and OpenCode hub tool show that number instead of a fixed default; older hubs show a number-free reason.
+
+## 0.11.0
+
+Voice recording's Developer mode and the richer `capture.v2` recording events (below), plus the fixes and team
+tools merged since 0.10.1: a launch's `end.cleanup: keep` is honoured when an ended host launch is reconciled, and
+the applied cleanup policy is stored before a launch ends, so kept, `needs_user` and lost workspaces are no longer
+deleted later; a per-team agent message hop limit with a user-only Renew Decision when a team chain stalls (and
+orphaned stall claims expire); team member names show without graph interactions; holder-scoped grant tools and
+read-only subscription, session-model and machine/node tools over MCP; the console's Launch new member form sets
+the model, end policy and timeout; the sandbox entry publishes its PID atomically, so a second start no longer
+starts a duplicate harness. CI cancels superseded test runs without interrupting an image release and can reuse a
+PR's passing result for the same tree.
+
+### Voice recording (developer)
+- **Developer mode** (Settings → Voice, per user, off by default; user request, 2026-11-10). One more field of the
+  recording settings record (`developer`, the same revision and `PUT /api/settings/recording {developer}`): on turns
+  recording on, recording off turns it off, older consoles' `{enabled}` keep it. While a developer recording runs it
+  also keeps, behind the new hub feature `dev.v1` (start answer `developer: true`):
+  - **raw microphone audio clips** (3 s before to 2 s after) around near-misses and marks, from a ring buffer of the
+    detector's input (`audio.clip`, `PUT/GET /api/recordings/:id/clips/:n`, ≤ 200 per recording);
+  - the detector's **frame traces** around speech starts, ends and near-misses (`vad.trace`);
+  - **device and network facts** on start and on change (`device.info`: audio devices, mic track processing,
+    Network Information, visibility, wake lock, battery), **Resource Timing** of the voice routes
+    (`resource.timing`) and **console errors and warnings** (`console.log`, scrubbed, rate-limited);
+  - hub side: per turn the **model, provider, agent and context token counts** and each tool call's start and end
+    (`turn.detail`; never prompt text), **request lines** of the voice routes (`request`), and the **reply audio**
+    kept from `/api/speak` as it streams (`reply.audio`, `GET /api/recordings/:id/replies/:n`).
+  The extras count against the same caps; their audio stops first (50 MiB below the user's cap, 15 MiB below the
+  recording's; `cap.reached {what: "extras"}`), segments and events go on. Exports add `clips/` and `replies/`,
+  listed in the manifest. Turning Developer mode off stops the extras at once. The indicator says
+  "● Recording · developer"; `scripts/voice-eval.ts` reports models per turn, devices, routes, clips and errors.
+- **More of what happens is recorded**, so "I talked and nothing happened" and lost words leave a trace. New console
+  events, sent only to a hub whose recording start lists the new feature `capture.v2` (an older hub refuses a whole
+  batch with an unknown kind, value or field, so toward it the console drops them before they take a `seq`):
+  - `vad.near`: what the speech detector almost took for speech: an onset abandoned before it started
+    (`short-onset`, `voiced-ratio`) or ≥ 150 ms just under the start threshold (`below-threshold`), with its peak, the
+    threshold that applied and whether the echo guard was up (the agent speaking). At most one per 500 ms of audio
+    and 20 per minute (the rest are counted in the next summary).
+  - `vad.summary`: every 10 s of listening, the detector's frames, max and p90 speech probability, loudest frame,
+    noise floor, frames over the start and echo-guard thresholds, time under the echo guard, mode and sensitivity
+    (quiet windows after a quiet summary are skipped).
+  - `stt.received` adds `junkReason` (why a transcript was dropped as noise), `held` (the text held at that moment)
+    and `speechMs`.
+  - `stt.slow`: a transcription still unanswered after 2 s (once per segment).
+  - `mark`: a bookmark. Say **"mark"**, **"mark that"** or **"bookmark"** alone (not sent to the agent; the held
+    text waits on), or press the Voice bar's new **Mark** button (shown only while recording on such a hub). The
+    Voice bar notes "Marked".
+- The hub's `stt.result` adds the provider's `httpStatus`, `responseBytes` and `headersMs` (time to the response's
+  headers; `providerMs` stays the total).
+- **`scripts/voice-eval.ts`** reads a recording export (zip or folder) and reports, across all its recordings,
+  per-turn latency by stage (median / p90 / max, by recording kind and device), dropped segments with their reason
+  and held text, early sends, STT stalls over 3 s with the provider's share, near-misses with the echo-guard share
+  and marks with ±15 s of context (`--json`, `--no-text`). Older exports work: what they lack is reported as not
+  recorded.
+
 ## 0.10.1
 
 Clicking the composer's Model chip changes the session's model. No migration is needed. Machines need the new

package/README.md

@@ -88,6 +88,9 @@ Formerly **opencode-voice** and, briefly, **opencode-hub**
   mode), staffed with sessions from any machine. The console's **Teams** page lists them and shows each team's
   members, work (live intake status) and communication ([docs/teams.md](docs/teams.md),
   [intake](docs/teams-intake.md)).
+  Team members can attach an open intake item to a message with `hub msg|ask --item itk_…`, MCP `msg`/`ask`'s `item`,
+  or the OpenCode hub tool's `item`. Both endpoints must hold current seats in that item's team; replies inherit it
+  while the item stays open.
 - **Watchtower** (formerly Bird's-eye view): a 3D, 2D or list picture of machines, sessions, teams and live
   message flow, with a team editor ([docs/watchtower.md](docs/watchtower.md)).
 - **Media in sessions**: tool screenshots, attachments and image files a reply names show in the transcript (with a
@@ -312,7 +315,7 @@ The hub serves the web app, pairs devices, enrolls machines, and does push and (
 |---|---|---|
 | **`/hub` → On this computer** | Local use; nothing to install (plugin from npm) | started by the plugin with OpenCode's own runtime (`BUN_BE_BUN=1 opencode bin/hub.ts`), or `bun` when installed |
 | **Standalone binary** | Any server or laptop, no runtime needed | `hub-<os>-<arch>` from the [releases](https://github.com/huynle/hub-releases/releases) (the source repository is private; releases are mirrored to the public `huynle/hub-releases`) |
-| **Docker** | Servers | `ghcr.io/huynle/hub` (linux/amd64, linux/arm64) |
+| **Docker** | Servers | `ghcr.io/huynle/hub` (linux/amd64, linux/arm64 for `v*` releases and `latest`; per-commit `git-…` tags from `main` are linux/amd64 only) |
 | **bunx / from source** | Bun users, development | `bunx --package @huynle/hub hub-server` · `bun bin/hub.ts` |
 | **Kubernetes (cluster mode)** | Several pods on Postgres + Valkey, rolling updates | [docs/cluster.md](docs/cluster.md), manifests in [`deploy/k8s/`](deploy/k8s/) |
 
@@ -611,6 +614,13 @@ hand-made token: `GET /connect/authorize` (PKCE S256) → the hub's consent page
 `POST /connect/token` → a 1-hour `hca_` access token and a rotating `hcr_` refresh token; `POST /connect/revoke` ends
 it. Clients are registered in Settings → Agents & access. See [docs/app-front.md](docs/app-front.md#connect-an-app).
 
+An administrator can adjust the hub-wide hop cap, its ceiling (`agents.hopCeiling`, default 100, at most 10,000; a
+raise asks for confirmation), launch limits, per-item wake/time budgets and no-progress loop threshold under
+**Settings → Admin → Agent limits** without restarting the hub. `hub.json` remains each limit group's default until a console value changes it; the UI shows each source separately. Agents may read the effective
+limits with `hub mcp` tool `agent_limits` but cannot change them; see [team hop limits](docs/teams-intake.md#team-message-hop-cap-and-renew)
+and [per-item budgets and progress](docs/teams-intake.md#per-item-budgets-attribution-and-progress), plus
+[launch caps](docs/launches.md#how-the-caps-count).
+
 **Hub as an app's AI layer (app front).** A web app can use Hub as its AI layer for its users: connect (above), launch
 helper sessions, follow and talk to them (a conversation stream, voice turns through the voice front), speak and
 transcribe with the user's own speech provider, and answer the everyday confirm-tier Decisions its own sessions ask.
@@ -705,16 +715,19 @@ sessions or apps; see [Decisions and `@me`](#agent-identity-agent-api) for the r
 
 **Limits.** Per 10 minutes: 20 messages per sender→recipient pair and 300 per user (`rate_limited`, exit 6, with
 `retryAfter`), and 30 turns started per recipient (more messages are still delivered, without waking it). A chain of
-messages between sessions may run 8 hops without a human turn; past that, messages are delivered without waking and
+messages between sessions may run up to the hub's configured hop limit (`agents.hopLimit` in Settings → Admin,
+default 8, at most the hop ceiling; a team's
+limit may be lower) without a human turn; past that, messages are delivered without waking and
 you are notified once. Typing into a session (console, Voice, the harness) starts its chain over. Apps (an app
 token, and the hub's own Concierge, workspace coordinator and team intake) count hops per conversation: a new `msg`
 or `ask` from an app starts at hop 1 and replies to an app do not count against it, so an app's 5th (or 50th) ask
 still wakes the session it talks to. Two guards keep apps from restarting chains: a reply or decline counts up from
 the message it answers (reply ping-pong through an app is capped like any other chain), and for 5 minutes after a
 session sends an app something, the app's new messages to *other* sessions continue from that hop (a relay A → app →
-B → app → A reaches the cap after about 8 hops; spaced-out work starts at hop 1 again). An app answering one session
+B → app → A reaches the configured cap; spaced-out work starts at hop 1 again). An app answering one session
 with new messages forever is held by the pair limit and the wake budget. A team intake submitted by a session
-continues that session's chain. A send's answer says when and why it did not wake (`woke`, `wakeSkipped`); the CLI,
+continues that session's chain. A send's answer says when and why it did not wake (`woke`, `wakeSkipped`, and
+`wakeLimit` for the effective hop or wake budget); the CLI,
 `hub mcp` and the OpenCode `hub` tool print it.
 
 **Never give agents an app token.** A session that holds one (in its environment, an MCP config, a gateway) can send
@@ -819,6 +832,13 @@ the requester and may only be the requester itself or a reserved role it holds.
 the grant; approving creates it as yours, and the requester is told the grant id in a reply. One open request per
 requester, 5 an hour.
 
+`hub mcp` exposes `grant_request` (the same request route and limits), `grant_list`, `grant_show` and
+`grant_revoke` (grants held by the calling session or app; apps need `messages:read` to list/show and
+`messages:send` to revoke), and
+`grant_create` (user device credential only; an agent must request and wait for your tap). A user credential on
+the holder-scoped tools has no holder; manage all grants in the console or with `hub grant` instead. Pinning a
+profile as an app also requires a `prompt` grant on the target session, not only `profiles:assign`.
+
 **Prompts.** An agent's prompt reaches the session as the hub's, never as yours: the spoke wraps it in a provenance
 envelope (`[hub] prompt from @lead · grant g_… · msg_…`, the body between boundary lines) and admits it as a hub
 message, so it never resets the loop protection's hop chain the way your own typing does. Agents may prompt root
@@ -925,12 +945,13 @@ hub name <@name> [--session <addr>]
 hub intent <addr> [text… | --clear]       what the session is for (one line, ≤ 280 characters)
 hub role claim <role[.project]> [--exclusive] [--session <addr>]
 hub role release <role[.project]> [--session <addr>]
-hub msg <addr> "text" [--all] [--no-wake] [--urgent] [--key K]     tell: fire and forget
-hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--all] [--no-wake] [--urgent] [--key K]
+hub msg <addr> "text" [--all] [--no-wake] [--urgent] [--item itk_…] [--key K]     tell: fire and forget
+hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--all] [--no-wake] [--urgent] [--item itk_…] [--key K]
 hub reply <msgID> "text" [--no-wake]      to the message's real sender, never via the role
 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>]...   a Decision for the user
+        [--choice "D1=Label:a=Option*,b=Option"]... [--kind question|plan|merge|release]   several points (* recommended)
 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
@@ -1102,7 +1123,12 @@ required and absolute; `mode`, `branch`, `base`, `remote`, `key`, `name`, `roles
 `cleanup`), `launches` (`state`, `label`), `launch_show` and `launch_stop` (`id`); the profile tools (`profiles`,
 `profile_show`, `profile_create`, `profile_version_create`, `profile_skill_set`, `profile_command_set`,
 `profile_assign`, …; [docs/profiles.md](docs/profiles.md#sdk-and-mcp)), the workspace, artifact and team tools
-([docs/teams.md](docs/teams.md#mcp-tools); `team_staff` takes the nested launch spec), with the same arguments
+([docs/teams.md](docs/teams.md#mcp-tools); `team_staff` takes the nested launch spec), subscription tools
+(`subscribe`, `subscriptions`, `unsubscribe`; [docs/subscriptions.md](docs/subscriptions.md#surfaces)),
+the grant tools (`grant_request`, `grant_list`, `grant_show`, `grant_revoke`, `grant_create`;
+[docs/multi-user.md](docs/multi-user.md#grants-tenancy)), `session_model_set` (user device credential only, same
+catalog checks as the console), and read-only `machines` and `launch_nodes` (user device credential only; connected
+node roots, slots, runtimes and labels; [docs/mcp-operations.md](docs/mcp-operations.md)), with the same arguments
 (`to`, `text`, `addr`, `id`, `requestID`, `formID`, `why`, `n`, `wake`, `urgent`, `all`, `project`, `role`, …). The act
 tools need an app token with scope `sessions:act` and a grant, the launch tools scope `sessions:launch` and a
 launch grant; `needs_user` results include the evaluation. `ask` takes `wait` of at
@@ -1904,7 +1930,9 @@ The loop is the package `packages/voice-client` (a `VoiceTransport` over the con
   `voiceTurn.fallback`, `voiceTurn.slow` as URL query parameters (one visit) or localStorage keys. The recording
   mode records each score as `turn.predict` ([docs/voice-recording.md](docs/voice-recording.md)).
 - **Commands**: an utterance that is only "stop", "cancel", "never mind", "stop that" or "hold on"
-  calls `POST …/interrupt` and stops speech. "Pause listening" turns the mode off.
+  calls `POST …/interrupt` and stops speech. "Pause listening" turns the mode off. While the recording mode records
+  (on a hub with its `capture.v2` feature), "mark", "mark that" or "bookmark" alone bookmarks the recording instead
+  of reaching the agent ([docs/voice-recording.md](docs/voice-recording.md)).
 - **Speech out**: root replies arrive one sentence at a time while they are written (`say` with `seq`);
   the phone plays them in `seq` order per text part and drops duplicates (`SayAssembler`). A `say` without
   `seq` (a subagent's result) is split into sentences. Abbreviations, decimals, file names and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Hub: a harness-agnostic central hub your AI agent harnesses connect to (OpenCode first). Follow, steer and stop sessions from your phone or browser, with notifications, optional hands-free Voice and a self-hostable server.",
   "license": "MIT",
   "author": "Huy Le",

package/packages/claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-claude-code",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "private": true,
   "description": "The Claude Code hooks spoke: per-user daemon, hook bridge, plugin dir, `hub claude` wrapper and daemon-backed MCP server (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/claude-code/src/sessions.ts

@@ -470,9 +470,12 @@ export class ClaudeSessions {
     this.#settle(s, undefined, true)
     s.stopRequested = false
     const detail = [input.error_details, input.error].find((v): v is string => typeof v === "string" && v.length > 0) ?? "the turn failed"
+    // (SS-9) The StopFailure error type (rate_limit, billing_error, authentication_failed, …) as error.type
+    // "claude.<token>", so the hub classifies a typed error instead of guessing from the text. Only a token-shaped value.
+    const token = typeof input.error === "string" && /^[a-z][a-z0-9_]{0,40}$/.test(input.error) ? input.error : undefined
     const turnID = s.turnID
     s.busy = false
-    this.#emit({ type: "session.execution.failed", data: { sessionID: s.hubID, ...(turnID ? { turnID } : {}), error: { message: cut(detail, HARNESS_ERROR_MAX) } } })
+    this.#emit({ type: "session.execution.failed", data: { sessionID: s.hubID, ...(turnID ? { turnID } : {}), error: { message: cut(detail, HARNESS_ERROR_MAX), ...(token ? { type: `claude.${token}` } : {}) } } })
     return {}
   }