@huynle/hub 0.9.2 → 0.10.1

package/README.md

@@ -41,8 +41,10 @@ Formerly **opencode-voice** and, briefly, **opencode-hub**
 - **Running detection**: a session counts as working while OpenCode reports it busy or retrying, or while a
   shell or terminal it started still runs (e.g. a background `sleep 60 &` or build script), also when it was
   already running before the plugin started.
-- **Voice** (optional feature, `/voice`): dictation and a hands-free conversation mode with a voice agent
-  that answers in short spoken sentences on a fast model and hands real work to background subagents.
+- **Voice** (optional feature, `/voice`): dictation and a hands-free conversation mode. Voice mode always talks
+  through a **voice front**: a hidden, fast voice agent that says what it understood and relays your request to
+  the session, which keeps its own agent, model and tools (Settings → Voice → Voice front; on by default, off
+  talks to the session directly).
   Bring your own speech: OpenRouter or any OpenAI-compatible STT/TTS service (including self-hosted).
   A developer **recording mode** (Settings → Voice, off by default) keeps your voice segments, transcripts,
   replies and timing on the hub for 7 days, private to you, with Export and Delete
@@ -58,6 +60,9 @@ Formerly **opencode-voice** and, briefly, **opencode-hub**
 - **Agent messaging**: sessions, scripts and you message each other through the hub (`hub msg @reviewer …`,
   `hub ask`, the OpenCode `hub` tool, `/msg`, `hub mcp`); asks to `@me` become Decisions you answer from the
   console ([Agent messaging](#agent-messaging)).
+- **Session subscriptions**: a session follows others (`hub subscribe @builder --type state:idle`, a role, a
+  `#team` or its subagents) and gets one batched hub message per window to react to, waking it when idle, with
+  loop protection and rate limits ([docs/subscriptions.md](docs/subscriptions.md)).
 - **Launches**: you, a script or an app start a session on one of your machines (`hub launch --branch feat/x
   --prompt "…"`): a `hub node` daemon prepares a git worktree, the session gets its name, roles, labels and first
   prompt, and ends by itself when it is done, with signed webhooks for apps ([docs/launches.md](docs/launches.md)).
@@ -148,7 +153,7 @@ Then, in OpenCode:
 |---|---|
 | **`/hub`** | Configures this harness's hub connection: the server URL, connect and approve (enroll) this machine, which sessions to share (mode), pair a phone, and open the hub in the browser. The first time it offers **Set up Hub** with two paths (below). |
 | **`/voice`** | The Voice feature: talks to the session on screen. It connects (running the setup first when needed), shares the session for Voice and opens it in the browser with Voice mode starting. |
-| **`/who [project \| @@role]`** | Lists the hub's named and role-holding sessions (name, project, state, online, roles), asked as the session on screen. |
+| **`/who [project \| #team \| @@role]`** | Lists the sessions the hub shows the session on screen: every online one (named or not; an unnamed one by its ID and title) and the named or role-holding ones while offline, with project, state, online and roles. A `You: @name · project` line heads the dialog (`You: ses_… (unnamed…)` until it has a name: ask the agent to name itself, or run `hub name @name --session ses_…` in a logged-in terminal; a `!` command gets no session token), its own row is marked `(you)` and listed first, then online before offline. |
 | **`/msg @name text`** | Sends the text word for word to another session (`@name`, `@@role`, `@name.project`, `ses_…`, or `@me` for you) as the session on screen. Needs a shared, connected session. |
 
 ### Local: everything on this computer
@@ -181,9 +186,12 @@ Pre-configured machines: with `"server": "https://hub.example.com"` in
 `~/.config/hub/config.json`, `/hub` leads with **Connect to hub.example.com**.
 `/hub` → **Server** → **Set up again…** switches between local and a hosted hub later.
 
-Optional: put the voice agent on a fast model in `~/.config/hub/config.json`:
-`"voiceModel": "anthropic/claude-haiku-4-5"` (any `provider/model` you have). Subagents keep the
-session's model.
+Recommended for Voice mode: put the voice front on a fast, paid model in `~/.config/hub/config.json`:
+`"voiceModel": "anthropic/claude-haiku-4-5"` (any `provider/model` you have; a session's Voice model in the
+console wins). Claude Haiku 4.5 measured fastest (0.7–0.8 s to the first token through OmniRoute), with Haiku 5.5
+as the alternative. The front never thinks: the hub turns its model's thinking off, whatever the model or variant.
+Avoid free models: when one runs out of quota the front fails and Voice mode talks to the session directly. The
+session itself keeps its own agent and model.
 
 ## Set up a machine (one line)
 
@@ -360,7 +368,8 @@ foreground with `hub.json`; `scripts/io.github.huynle.hub.plist` is a launchd te
 **Security:** the hub can drive your OpenCode sessions, which can run tools. Every API call needs a
 paired device or a signed-in user; spokes need machine tokens; nothing trusts the client IP. For a public
 hostname, consider [sign-in with Google](#multi-user-sign-in-with-google) or an authenticating proxy in
-front of the web app, and leave `/spoke/*`, `/auth/*`, `/healthz`, `/.well-known/hub`, `/install.sh`,
+front of the web app, and leave `/spoke/*`, `/auth/*`, `/healthz`, `/.well-known/hub`, `/connect/*` (connected apps' token
+endpoints), `/.well-known/oauth-authorization-server`, `/install.sh`,
 `/install.ps1`, the manifest and icons reachable for spokes, sign-in, app discovery, [machine
 setup](#set-up-a-machine-one-line) and the PWA (and `/mcp`, bearer-authenticated, if MCP clients
 or gateways use [MCP over HTTP](#over-http-mcp)).
@@ -410,9 +419,15 @@ conversation mode and utterances (403 `not_exposed` for sessions not shared with
 | `POST /api/sessions/:id/rename` | `{title}` → `{title}`: renames the session in OpenCode (`session.update`), through the process that owns it, else any other process that reports it. The title is trimmed and must be 1–200 characters (400 otherwise). Works with Voice off; the new title shows in every console at once (the spoke reports it before answering) |
 | `POST /api/sessions/:id/fork {messageID}` · `GET …/revert/preview?messageID=` · `POST …/revert {messageID, files?}` · `POST …/revert/restore` · `POST …/revert/commit` | fork before one of the session's user messages (201 `{sessionID, text, attachments}`), or stage, undo and commit a revert from it (409 `busy` while it runs); console only, audited; needs a spoke announcing `fork`/`revert` (409 `unsupported` otherwise). Contract: [docs/session-view.md](docs/session-view.md#fork-and-revert-a-message) |
 | `POST /api/sessions/:id/stop` | interrupts running descendants deepest first, then the root; idempotent. Also releases the hub's turn lock for the tree: a turn request still waiting answers `{outcome: "interrupted"}` and the next turn can start (`/interrupt` does the same) |
-| `GET /api/sessions/:id/summary` | context usage, todos, MCP status (at most 100 servers), branch and working-tree change stats (each part optional). `changes` lists at most 500 files, most-changed first, with `totalFiles` and `truncated`; its `additions`/`deletions` cover every file |
+| `PUT /api/sessions/:id/model {model: {providerID, modelID, variant?}}` | (feature `setModel`; console only, same access as a prompt: the session's owner) sets the session's own model: its next turn and every later one run on it, whoever prompts (the console, the TUI, a Voice relay). The spoke calls OpenCode's `session.switchModel`, which stores it on the session. Answers `{model}` (the summary's `model`, source `chosen`). 400 malformed or not in the session's catalog (`GET …/models`), 409 `unsupported` from an older spoke. Audited `session.model`. The Voice model (`…/model-prefs`) is separate |
+| `GET /api/sessions/:id/summary` | context usage, the model the session runs on (`model`: chosen, else its latest reply's, else the default; with `source`), todos, MCP status (at most 100 servers), branch and working-tree change stats (each part optional). `changes` lists at most 500 files, most-changed first, with `totalFiles` and `truncated`; its `additions`/`deletions` cover every file |
+| `GET /api/sessions/:id/context-cards` · `POST …/context-cards/:provider/refresh` | the session's [context cards](docs/context-cards.md) (`{cards, providers, enabled, configured}`), and running one provider now (`{force?}` → `{outcome: "generated", card}` · `{outcome: "skipped", reason}` · `{outcome: "failed"}`; 404 unknown provider; 429 with `Retry-After`: one per card per 30 s, 10 per user per minute). Live: SSE `{type: "contextCard", sessionID, provider, primary?, generatedAt}` (never the text) |
+| `GET /api/context-cards/primary?sessions=a,b` | the primary context cards of up to 200 sessions (`{cards: {sessionID: card}}`): the session list's second line |
+| `GET /api/settings/context-cards` · `PUT {enabled}` | your context card setting, whether the hub allows them and has a model (`{enabled, available, configured, model?, usage}`, never the key); off until you opt in |
 | `GET /api/sessions/:id/diff?file=` | one file's patch, on demand (capped at 400 KB as JSON, then `truncated: true`); never stored in the hub |
-| `POST /api/sessions/:id/read` · `GET /api/reads` | per-user read marks, synced to your other devices |
+| `POST /api/sessions/:id/read {open?}` · `GET /api/reads` | per-user read marks, synced to your other devices; `open: true` (the console sends it when you open the session, not for its automatic marks) also counts as touching it |
+| `GET /api/activity/mine` | per-user "touched by me" and the activity meter: `{activity: {sessionID: {at?, kind?, last?, buckets}}}`. `at` (ms) and `kind` (`prompt-tui`, `prompt-web`, `voice`, `answer`, `view`) say what the root session shows (your last action, else your last open), `last` your latest touch of any kind; `buckets` are `[start, yourActions, agentTurns, agentToolCalls]` per 30 minutes of the last 24 h. Changes stream as SSE `{type: "activity", sessionID, activity}`. Kept 30 days, at most 2000 sessions per user. See [docs/session-view.md](docs/session-view.md#finding-your-sessions) |
+| `GET /api/intents/mine` | the stored intents of your sessions, `{intents: {sessionID: {text, source}}}` (never the title fallback): the second line under titles in the session list |
 | `GET /api/events?lite=1&session=<id>&last=<id>` | the live stream (SSE). Every message has an `id:`; reconnecting with `Last-Event-ID` (EventSource does it) or `?last=` replays what was missed when the hub still has it (last 2000 events or 5 minutes per user; one fresh `catalog` stands for any catalog changes), else sends the catalog then `{type: "resync"}` (the page refetches what it shows). Ids are `<epoch>.<n>`; a hub restart starts a new epoch. `lite=1` leaves out `delta`/`reasoning` except of `session`'s tree (status, activity, catalog, turns and the rest still come). Split panes add `sessions=<id>,<id>` (at most 4 with `session`, else 400): each listed tree streams, each event once, and the stream starts with `{type: "scope", sessions}` naming the ones accepted (your own only); without `sessions` nothing changes. Heartbeat: `event: ping` every 20 s |
 | `GET /api/push/prefs?endpoint=` | `{prefs, quietHours, activityMinutes, muted, subscriptions, subscribed?}`: this device's toggles (`handoff, question, permission, done, failed, turn, stopped, retry, subagentDone, subagentFailed, jobDone, jobFailed, longTool, say, activity`; `PUT` also accepts the legacy `finished` → `done` and `blocked` → question + permission), activity update interval and quiet hours, the user's muted sessions, how many subscriptions the hub holds for this device, and whether it holds `endpoint` |
 | `PUT /api/push/prefs {toggles…, quietHours?, activityMinutes?}` | boolean toggles (a 0.5.0 `blocked` sets question and permission); `quietHours` `{start: "HH:MM", end: "HH:MM", timeZone}` or `null`; `activityMinutes` a whole number 1–60 (400 when invalid) |
@@ -451,9 +466,20 @@ the console shows it in the session's Details rail, with Edit (live: the console
 Retention: every 6 h one hub drops the intents of deleted sessions and of sessions neither seen nor written for 30
 days; an online session's intent is always kept. A dropped intent's revision starts over at 0.
 
+**Context cards.** Beside the intent, the hub keeps short, automatically updated [context cards](docs/context-cards.md)
+per session, from a registry of providers: `pickup` (primary; a light model the hub calls writes "pick up where you
+left off": a ≤ 90-character headline and a short summary) and `changes` (the working tree, no model). They are **opt-in per
+user** (off until you turn them on in Settings › Concierge; nothing is sent to a model before). Then they run on turn
+end, when a session gets blocked, when you come back to it, on a 30-minute sweep and on Refresh, only for sessions you
+touched in the last 24 h, throttled, skipped when nothing changed and capped per user per day.
+`GET /api/agent/sessions/:addr/context-cards` answers `{sessionID, cards, providers}` (users, `sessions:read`,
+session tokens, like the intent read). New cards are `session.contextCard {provider, version, primary}` events,
+never the text; the Concierge board shows each root's primary headline (`pick up «…»`).
+
 **Events.** `GET /api/agent/events?cursor=&wait=&limit=&type=&session=` reads a bounded per-user journal (24 h or
 10,000 events) of compact events: `session.added/removed/changed`, `blocker.opened/closed`, `machine.changed`,
-`message.changed`, `launch.changed`, `session.archived`, `session.named`, `session.intent`, `role.claimed`, `role.released`. Each is `{id, at, type, subject, data}` with IDs and states
+`message.changed`, `launch.changed`, `session.archived`, `session.named`, `session.intent`, `session.contextCard`, `role.claimed`, `role.released`,
+`subscription.created/removed`. Each is `{id, at, type, subject, data}` with IDs and states
 only: never prompts, message bodies, titles, blocker summaries, launch reasons or labels. Without a cursor the answer
 is empty with a cursor at the latest event; pass the returned `cursor` back to get what came after. `wait` (0–60 s)
 holds the request while nothing matches; `limit` is 1–200 (default 50); `type` (exact, or `launch.*`) and `session`
@@ -518,21 +544,28 @@ cookie and a hub bearer token (400).
 | `GET /api/agent/status` | ✓ | ✓ | ✓ | machines → projects → sessions, each with name, roles, state, harness, activity and blockers, plus `attention` |
 | `GET /api/agent/sessions?project=&state=&machine=&label=k=v&q=` | ✓ | ✓ | ✓ | the same sessions as a flat list; `q` (≤ 200 characters): every word must appear in the title or @name (case, `@` and punctuation ignored) |
 | `GET /api/agent/sessions/:addr` | ✓ | ✓ | ✓ | one session with full blockers and the spoke's summary (`unsupported` when its harness lacks it) |
-| `GET /api/agent/sessions/:addr/log?n=20` | ✓ | ✓ | ✓ | newest timeline rows (1–200); `422 unsupported {feature, harness}` when the spoke has no timeline, `503 offline` |
+| `GET /api/agent/sessions/:addr/log?n=20` | ✓ | ✓ | ✓ (or `conversation:read` for [the app's sessions](docs/app-front.md#conversation-for-apps)) | newest timeline rows (1–200); `422 unsupported {feature, harness}` when the spoke has no timeline, `503 offline` |
 | `GET /api/agent/watch?blocked=1&session=<addr>&cursor=` | ✓ | ✓ | ✓ (+ each family's scope) | SSE of the same compact events as `/api/agent/events` (see **Events**), after `ready`; each frame's `id:` is a cursor to resume with (`?cursor=` or `Last-Event-ID`); `reset` when it is no longer covered |
 | `GET /api/agent/events?cursor=&wait=&limit=&type=&session=` | ✓ | ✓ | `events:subscribe` (+ each family's scope) | compact events after a resumable cursor (see **Events** above) |
 | `GET /api/agent/who?project=&role=` | ✓ | ✓ | ✓ | named, role-holding and online sessions |
+| `POST /api/agent/subscriptions {subscriber?, to, types?, delivery?, batch?, maxPerHour?, expires?, note?}` · `GET …/subscriptions?session=` · `GET`/`DELETE …/subscriptions/:id` | ✓ | itself only | `events:subscribe` + `sessions:read` (+ `messages:send` unless `delivery: "silent"`, + family scopes); its own | a session follows other sessions' events as batched hub messages ([docs/subscriptions.md](docs/subscriptions.md)) |
 | `POST /api/agent/name {name, session?}` | ✓ | own session | `sessions:manage` | names a session (`409 name_taken`) |
 | `POST /api/agent/roles/claim {role, exclusive?, project?, session?}` · `…/roles/release` | ✓ | own session | `sessions:manage` + `roles` grant | claims (with a new `generation`) or releases a role; never a reserved role for an app |
 | `POST /api/agent/msg {to, text, wake?, urgent?, all?}`; `Idempotency-Key` | ✓ | ✓ | `messages:send` | tells a session (`all`: every holder of a role); never yourself |
 | `POST /api/agent/ask {to, text, expiresIn?, wait?}`; `Idempotency-Key` | ✓ | ✓ | `messages:send` | an ask, open until answered, declined or expired; `wait` (≤ 60 s) returns the `answer` |
 | `POST /api/agent/ask {to: "@me", text, options?, recommendation?, urgency?, tier?, deadline?, onTimeout?, about?, wait?}` | – | ✓ | `messages:send` | opens a **Decision** for the user (below): `{message, decision, answer?}` |
 | `GET /api/agent/decisions?state=` · `…/decisions/:id` | ✓ (all) | own | `messages:read` (own) | the Decisions the caller asked |
+| `GET /api/agent/decisions?answerable=1[&state=]` · `POST /api/agent/decisions/:id/answer {option?, text?}` | – | – | `decisions:answer` | [Decisions from apps](docs/app-front.md#decisions-from-apps): confirm-tier Decisions without an action of a session the app launched or holds a grant allowing `answer` for (others `404`); `410 gone` when not open or another answer won, `403` tap tier / any action / Concierge-asked / a lasting option, `400` with `via`, `423 paused` |
 | `POST /api/agent/reply {replyTo, text}` · `…/decline {replyTo, why}` | ✓ | ✓ | `messages:send` | answers a message you received (to its real sender); not a Decision's ask |
 | `GET /api/agent/inbox` · `GET /api/agent/messages/:id?wait=` | ✓ | ✓ | `messages:read` | open asks, your waiting asks, recent messages, mutes · one message and its answer |
 | `POST /api/agent/mute {session}` · `…/unmute` | ✓ | ✓ | `messages:send` | refuses (or allows again) messages from a session |
 | `GET` · `PUT /api/agent/messaging {enabled}` | ✓ | – | – | the per-user messaging switch (off: `423 paused`) |
 | `POST /api/agent/app-tokens {label?, scopes?}` · `GET` · `DELETE …/:id` | ✓ | – | – | creates (token shown once), lists, revokes app tokens |
+| `GET` · `POST /api/agent/app-clients {name, redirectURIs, scopes, audience?}` · `PATCH`/`DELETE …/:id` · `POST …/:id/secret` | ✓ | – | – | registered app clients ([connect an app](docs/app-front.md#connect-an-app)): admins register hub-wide ones, anyone their own (`audience: "user"`); the secret is shown at create and rotate only |
+| `GET /api/agent/connections` · `DELETE …/:id` | ✓ | – | – | your connected apps (scopes, created, last refresh); delete revokes one (its tokens, grants and webhooks) |
+| `POST /api/agent/speech/transcribe` (raw audio) · `POST /api/agent/speech/speak {text}` | – (console: `/api/transcribe`, `/api/speak`) | – | `speech:use` | [speech for apps](docs/app-front.md#speech-for-apps): `{text}` · `audio/mpeg`, with the user's own speech provider and key; per-credential quotas (`429 rate_limited`), `422 unsupported` without a provider, `502 upstream_failed`; nothing recorded |
+| `GET /api/agent/sessions/:addr/stream` (SSE; `Last-Event-ID`) | ✓ | – | `conversation:read` | [conversation for apps](docs/app-front.md#conversation-for-apps): `ready`, `delta`, `say`, `heard`, `status`, `conversation`, `reset`, `end` of a session the app launched or holds a grant allowing `prompt` for (others `404`); 4 streams per app, 20 per user (`429`) |
+| `POST /api/agent/sessions/:addr/conversation {on, front?}` · `…/utterance {text}` · `…/interrupt` | ✓ | – | `conversation:write` + a grant allowing `prompt` | conversation mode (the voice front with `front: true`) · `202 {inboxID}` (counts against `maxActionsPerHour`, marked as the app's prompt) · `204`; kill switch `423 paused` |
 
 Sends to a session (`msg`, `ask`, `reply`, `decline`) answer `{message, delivery, woke, wakeSkipped?}`: `woke` says
 whether the hub sent it to wake the recipient, and when not, `wakeSkipped` says why (`wake_false`, `subagent`,
@@ -567,7 +600,26 @@ decision}` on every open, answer, timeout, escalation and expiry); a `decision`
 Reads come from the hub's catalog; only `show` (summary) and `log` (timeline) ask the session's spoke, so they
 depend on what its harness supports. A session token reads all of its user's sessions but names and claims roles
 only for itself; an app token reads, and messages only with the `messages:*` scopes. `GET /.well-known/hub` (public) answers `{publicURL, version,
-minClientVersion, auth, features}` for apps and CLIs.
+minClientVersion, auth, features}` for apps and CLIs; `features` lists `app-connect` (apps connect with consent:
+[docs/app-front.md](docs/app-front.md#connect-an-app)), `app-speech` (speech for apps:
+[docs/app-front.md](docs/app-front.md#speech-for-apps)), `app-conversation`
+([conversation for apps](docs/app-front.md#conversation-for-apps)) and `app-decisions`
+([Decisions from apps](docs/app-front.md#decisions-from-apps)).
+
+**Connected apps.** A web app's server connects to a user's account with an OAuth 2.1-style consent flow instead of a
+hand-made token: `GET /connect/authorize` (PKCE S256) → the hub's consent page, where the user can narrow the scopes →
+`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).
+
+**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.
+Always through the app's **own server** (a BFF): hub tokens never reach a browser, and the hub sends no CORS headers.
+The guide: [docs/app-front.md](docs/app-front.md) (the BFF pattern, scopes, the grants each feature needs, limits,
+the refresh rule, security rules). The SDK (`packages/sdk`: `HubConnect`, `ConnectionTokens`, `hub.speech`,
+`hub.conversation`, `hub.appDecisions`) and the voice loop's `appTransport` (`packages/voice-client`) do the work; a
+reference BFF lives in [examples/app-front-bff](examples/app-front-bff/README.md), and the
+[app fixture](docs/app-integration-testing.md) runs a real hub to test an app against.
 
 **Apps.** A native app links with a code from Settings → Devices → **Add app** (`POST /api/devices/link`, then
 `POST /api/devices/redeem` from the app; see [Multi-user](#multi-user-sign-in-with-google)) and uses the device
@@ -592,7 +644,7 @@ you. Addresses resolve among your own sessions only; another user's sessions do
 | `reply <msgID> "text"` · `decline <msgID> --why "…"` | answers a message you received; it goes to the message's real sender, never through the role |
 | `inbox` | asks waiting for your answer, your own open asks, recent messages, mutes |
 | `mute <addr>` · `unmute <addr>` | refuses (or accepts again) messages from a session (`forbidden`, exit 5) |
-| `who` | named and role-holding sessions |
+| `who` | online sessions, and named or role-holding ones while offline |
 
 `--no-wake` admits a message without starting a turn and `--urgent` steers it into a running turn. Texts are at
 most 10,000 characters (a decline's reason 1,000).
@@ -643,7 +695,8 @@ sessions or apps; see [Decisions and `@me`](#agent-identity-agent-api) for the r
 **Where agents send from.**
 - In a shell of an OpenCode session: `hub msg @reviewer "…"` acts as that session ([hub CLI](#hub-cli)).
 - The model itself: the plugin's `hub` tool (verbs `msg`, `ask`, `reply`, `decline`, `inbox`, `who`, `status`,
-  `whoami`, the [team intake](docs/teams-intake.md) verbs `intake` and `intake_update`, `name`, `role_claim` and
+  `whoami`, the [team intake](docs/teams-intake.md) verbs `intake` and `intake_update`, the
+  [subscription](docs/subscriptions.md) verbs `subscribe`, `unsubscribe` and `subscriptions`, `name`, `role_claim` and
   `role_release` for its own @name and roles, and the [act verbs](#agent-actions-and-grants)), as the calling session ([Spoke](#spoke-opencode-plugin)).
 - You, in the OpenCode TUI: `/msg @name text` (as the session on screen) and `/who`.
 - Other agents and tools: [`hub mcp`](#hub-mcp-mcp-server), as the app token you logged in with, or the hub's
@@ -792,7 +845,7 @@ and the SDK. Only you manage grants: the console (Settings → Agents) or the CL
 | `POST /api/agent/sessions/:addr/approve {requestID, always?, why?}` | ✓ | under a grant | under a grant |
 | `POST /api/agent/sessions/:addr/deny {requestID, why?}` | ✓ | under a grant | under a grant |
 | `POST /api/agent/sessions/:addr/answer {formID, answer \| cancel: true, why?}` | ✓ | under a grant | under a grant |
-| `POST /api/agent/sessions/:addr/prompt {text, delivery?, why?}` (users: `images?`) | ✓ | under a grant | under a grant |
+| `POST /api/agent/sessions/:addr/prompt {text, delivery?, why?}` (users: `images?`) | ✓ | under a grant | under a grant (or `conversation:write`, the app's own sessions) |
 | `POST /api/agent/sessions/:addr/stop {why?}` | ✓ | under a grant | under a grant |
 | `POST /api/agent/grants` · `GET` · `GET`/`PUT`/`DELETE …/grants/:id` | ✓ | – | – |
 | `POST /api/agent/grants/requests {grant, why}` | – | ✓ (any token) | `messages:send` |
@@ -867,7 +920,7 @@ hub show <addr>                           state, blockers, activity, summary
 hub log <addr> [-n 20]                    newest timeline rows (1–200), printed oldest first
 hub watch [--blocked] [--session <addr>]  events as JSON lines until Ctrl-C (pings skipped)
 hub whoami                                who this credential is
-hub who [--project P] [--role R | @@role] named and role-holding sessions
+hub who [--project P] [--role R | @@role] online sessions, and named or role-holding ones while offline
 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>]
@@ -881,6 +934,9 @@ hub ask @me "question" [--option id=label[:safe]]... [--recommend id [--why "…
 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
+hub subscribe <addr|@@role|#team|children>... [--type T]... [--delivery queue|steer|silent] [--batch 30s]
+        [--expires 1d] [--max-per-hour N] [--subscriber <addr>]   batched hub messages about their events
+hub subscriptions [--session <addr>] · hub unsubscribe <subID>
 hub approve <addr> <requestID> [--always] [--why "…"]   answer a permission request (once, or always)
 hub deny <addr> <requestID> [--why "…"]   reject it; the reason reaches the harness
 hub answer <addr> <formID> key=value… | --json '{…}' | --json - | --cancel [--why "…"]
@@ -1113,7 +1169,7 @@ event stream comes back) it asks its own server what runs now (`session.active`
 
 | Entry | File | Role |
 |---|---|---|
-| server | `server.ts` → `src/index.ts` | Starts the process-wide spoke (`src/spoke/`), `hub.*` RPC (also under the legacy id `voice.*`), the `voice` agent, short-reply and orchestrator `context` hook |
+| server | `server.ts` → `src/index.ts` | Starts the process-wide spoke (`src/spoke/`), `hub.*` RPC (also under the legacy id `voice.*`), the hidden `voice-front` and `concierge` agents, and the `context` hook (short spoken replies, the voice front's note and tools) |
 | tui | `tui.ts` → `src/tui.ts` | `/hub` dialog and the feature commands (`/voice`), registered through `src/tui-commands.ts` (ids `hub.<id>`, palette group "Hub"); reports the sessions it shows (`hub.presence`) |
 | rpc | `rpc.ts` → `src/rpc.ts` | `HubRpc` (id `hub`; `VoiceRpc` is the deprecated id `voice`): `status / setServer / checkServer / enroll / startLocalHub / setMode / setSession / pairCode / handoff / openLink / conversation / presence` |
 
@@ -1122,10 +1178,12 @@ The plugin ids are `hub` (server) and `hub.tui`. OpenCode resolves a local plugi
 
 - **Config**: `~/.config/hub/config.json` (or `$HUB_SPOKE_CONFIG`), shared by all
   processes on the machine, mode 0600, watched live. Holds the server URL, mode, machine token,
-  `subagent` (the agent conversation mode delegates to; default `general`, `[A-Za-z0-9_.-]+`),
+  `voiceModel` (the voice front's model, `provider/model[#variant]`; pick a fast paid one),
   `autoStartLocalHub` (default `true`; see [Local only](#local-only)), `herdr` (default `true`; read open
   sessions and workspaces from [Herdr](#open-sessions-herdr-and-tuis)), and `list` (the history window,
   default `{"days": 30, "max": 100}`; days 1–365, max 1–500; out-of-range values fall back per field).
+  `subagent` and `workModel` (the removed voice agent's delegate agent and worker model) are obsolete: read
+  without error, ignored, logged once per process, and dropped the next time the plugin saves the file.
 - **Modes**: `off` (no connection), `always` (every session this process knows, Voice on for all),
   `session` (Voice only for sessions switched on in `/hub` or from the phone, plus their subagent
   sessions). Every reported session can be inspected and controlled in both modes; in `session` mode the
@@ -1194,20 +1252,34 @@ Sessions open in a terminal are reported with `open: true` and `terminal` (`src/
 
 ## Conversation mode (OpenCode side)
 
-In conversation mode the session's main agent becomes a voice orchestrator: it answers in one or two
-spoken sentences, handles quick answers and up to two low-risk tool calls directly, and hands multi-step
-work to a background subagent. Routine workers inherit the fast voice model; coding, debugging,
-architecture and risky work use the configured full work model. Successful workers finish with a short
-speech-ready result that the hub reads directly, without waiting for another voice-agent summary. You
-can keep talking while work runs; related follow-ups continue the active worker and unrelated tasks start
-a fresh one. Several independent requests in one breath ("check the deploy and update the changelog") start
-one background worker each, in parallel, in the same turn; each worker gets a short name ("Deploy check") that
-the task board and announcements use.
-
-The phone composer exposes separate **Voice** and **Worker** model controls for each session. Each picker
-lists the connected OpenCode process's available models and variants. Choices are saved per user and
-session, apply to the next turn or newly started worker, and fall back to the machine's `voiceModel` and
-`workModel` when unset.
+Voice mode (conversation mode) always uses the **voice front** when it can: a hidden, hub-managed OpenCode session
+on the fast `voiceModel`, one per conversation (design: `docs/plans/2026-11-06-voice-front-design.md`, contract:
+`docs/plans/2026-11-06-voice-front-p1-contract.md`). Every reply starts with a short echo of what it understood;
+it relays your request to the session (a new turn when the session is idle, steering when it is busy, queued for
+an unrelated request) or stops it, and speaks the session's results, questions and failures. It has no shell, no
+edits and no subagents. The session you talk to keeps its own agent, model, tools and subagents.
+
+The front's model requests are kept short so its echo starts at once (`src/spoke/voice-front.ts`, applied by the
+`context` hook to linked fronts only):
+- **No thinking:** an Anthropic-API model (also through a gateway such as OmniRoute) gets `thinking: {type:
+  "disabled"}`, overriding a model's own thinking setting or a `#variant`. An OpenAI-style model gets the lowest
+  reasoning effort it lists (`none`, else `minimal`); one that lists neither gets nothing, because a non-reasoning
+  model may reject `reasoning_effort`. Other providers keep their default.
+- **Lean system prompt:** only the front's own prompt. OpenCode's instruction files (`AGENTS.md`, `CLAUDE.md`,
+  `instructions`), model, date, environment and worktree blocks are left out; the front gets its two tools, the
+  per-turn note and its conversation.
+
+Without a front the hub talks to the session directly and the session answers in short spoken replies (the
+`context` hook adds a voice style to its turns): when the device turned **Voice front** off (Settings → Voice), when
+the machine's plugin is older or cannot create the front, after the front failed (`front_failed`, e.g. a free model
+out of quota), and when an older hub sends `conversation {on}` without `front`. In no case is the session's agent or
+model switched. Earlier versions switched the session to a `voice` agent on the fast model that delegated work to
+background subagents; that agent, its orchestrator prompt, the `hub_task_stop` tool and the `subagent` /
+`workModel` settings are gone.
+
+The phone composer has one **Voice** model control per session: the voice front's model. The picker lists the
+connected OpenCode process's models and variants; the choice is saved per user and session, applies the next
+time Voice mode starts, and falls back to the machine's `voiceModel` when unset. Pick a fast, paid model.
 
 The conversation is an inline execution timeline: streamed thinking, tools and nested subagents appear
 between messages as compact expandable rows. Rows keep the session's order, never wall-clock order: history
@@ -1220,26 +1292,19 @@ not persist those potentially sensitive details.
 
 **Spoke side** (`src/spoke/conversation.ts`, `src/spoke/spoke.ts`):
 
-- The plugin registers a primary agent **`voice`** through `ctx.agent.transform` (the agent editor's
-  `update()` creates missing agents). Its system prompt is the orchestrator prompt; it inherits the
-  default `build` agent's permissions so your rules still apply. A `voice` agent you define yourself
-  (e.g. `~/.config/opencode/agents/voice.md`) takes precedence and is left untouched.
-- `conversation on` remembers the session's current agent and switches it to `voice`; `off` switches
-  back (or to the default agent), unless you picked another agent in the meantime. If no `voice`
-  agent exists, the session keeps its agent and the `context` hook adds the orchestrator prompt instead.
-- The delegate agent (`subagent` in the config) is added per request by the `context` hook, so changing
-  it needs no restart.
-- **Task board**: the `context` hook also gives the voice agent (and a conversation on another agent) a live
-  list of the workers it started (`src/spoke/taskboard.ts`, from this process's events): title, sessionID,
-  state (working, blocked with what it waits for, done with its latest text, failed with the reason, stopped)
-  and for how long, at most 8 (live ones first) of at most 200 characters each. So "what's running?" or "how's
-  the deploy going?" needs no tool call. A session without workers gets no board.
-- **Stopping one task by voice**: the plugin adds a tool `hub_task_stop {sessionID} | {all: true}`. The voice
-  agent calls it for "cancel the deploy one" (that worker and whatever runs below it are interrupted, deepest
-  first) or "stop all the workers" (every running worker of the session). It only reaches sessions below the
-  calling session (never the caller itself, its siblings or another session's workers), so the voice agent
-  keeps listening. The phone's stop words ("stop", "cancel", "never mind", "stop that", "hold on") still
-  interrupt the root turn at once.
+- The plugin registers the hidden primary agent **`voice-front`** through `ctx.agent.transform` (everything denied
+  but its two relay tools, `voice_main_send` and `voice_main_stop`, which the `context` hook offers only to a linked
+  front). It registers no `voice` agent: a session an older plugin left on one (a crash mid-conversation) is moved
+  to the default agent before the hub's next prompt, or after a turn fails with "Agent not found", because OpenCode
+  2.2.3 fails every turn on a missing agent. A `voice` agent you define yourself is left alone.
+- `conversation on` with `front` creates (or re-links) the front; `on` without it, or when no front can be made,
+  marks the session's turns as voice turns. `off` deletes the front. Both answer with the session's current agent
+  and never switch it.
+- **Task board**: the front's per-turn note about its session lists the session's workers (`src/spoke/taskboard.ts`,
+  from this process's events): title, state (working, blocked with what it waits for, done with its latest text,
+  failed with the reason, stopped) and for how long, at most 8 (live ones first) of at most 200 characters each.
+  So "what's running?" or "how's the deploy going?" needs no tool call. The phone's stop words ("stop", "cancel",
+  "never mind", "stop that", "hold on") still interrupt the turn at once.
 - **Messaging other sessions**: the plugin adds a tool `hub {verb, …}` with the verbs `msg`, `ask`, `reply`,
   `decline`, `inbox`, `who`, `status`, `whoami`, `intake` and `intake_update` (`src/spoke/hub-tool.ts`). It acts as the calling session
   with that session's own hub token (the token never appears in the tool's output). `name {name}` sets the
@@ -1251,8 +1316,9 @@ not persist those potentially sensitive details.
 - Child text and execution events are paired by the hub. The latest assistant message of a successful
   child is emitted as root-session speech; interruptions and stale partial results are not. **Announcements**
   (hub, `src/central/registry.ts`): while another worker of the session runs or waits, or one was announced in
-  the last minute, a result starts with the task's title ("Deploy check finished: …"); a result the voice agent
-  already said in the last two minutes is not read again. A failed worker is announced once with its reason
+  the last minute, a result starts with the task's title ("Deploy check finished: …"); a result the session
+  already said in the last two minutes is not read again (with a voice front, worker results are the front's to
+  report and the hub does not read them). A failed worker is announced once with its reason
   ("Lint failed: rate limit exceeded."), a worker's permission request or question once per request ("Cleanup
   needs your permission.", "… has a question."); a stopped worker is not. Announcements are ordinary `say`s
   without `seq` (`messageID` `announce:failed:<session>`, `announce:permission:<id>`, `announce:form:<id>`),
@@ -1260,13 +1326,13 @@ not persist those potentially sensitive details.
 - Server ops: `steer` sends the text with `delivery: "steer"` (metadata `{source: "hub", mode:
   "conversation"}`, or `mode: "remote"` for a session not shared with Voice; 0.5 wrote `source:
   "opencode-hub"` and 0.4 and earlier `source: "opencode-voice"`, and readers accept all three) and returns the inbox ID at once; `interrupt`
-  interrupts the session; `conversation` turns the mode on/off and returns the agent now in effect, and
-  is refused for sessions not shared with Voice. Replies reach the hub as forwarded
+  interrupts the session; `conversation` turns the mode on/off and returns the session's agent (never
+  switched), and is refused for sessions not shared with Voice. Replies reach the hub as forwarded
   `session.text.ended`, `session.inbox.delivered` and `session.agent.selected` events.
 - State is per process and in memory; the hub re-sends `conversation on` after a reconnect.
-- From the terminal: `/voice` opens the current session in the browser with Voice mode starting; `/hub →
-  Conversation mode` toggles conversation mode only (same code path as the phone), then offers to send the
-  session to your phone.
+- From the terminal: `/voice` opens the current session in the browser with Voice mode starting (with the voice
+  front, unless that browser turned it off); `/hub → Conversation mode` only toggles short spoken replies for the
+  session in this process (no front), then offers to send the session to your phone.
 
 ## Central server
 
@@ -1293,8 +1359,10 @@ holds the startup (`bin/hub.ts` serves `web/` from disk; the compiled binaries e
 | `HUB_RELEASE_BASE` | `https://github.com/huynle/hub-releases/releases/download/v<version>` | where `/install.sh` and `/install.ps1` download hubctl ([Set up a machine](#set-up-a-machine-one-line)): https, or plain http on loopback or a private-network IP address; the hub refuses to start with any other value. Without it a development version (not a plain `x.y.z`) answers 503 |
 | `HUB_CSP` | `enforce` | `report-only` sends the console's Content-Security-Policy as `Content-Security-Policy-Report-Only` (violations are only logged in the browser console); see [Content-Security-Policy](#content-security-policy) |
 | `HUB_REMOTE_FETCH` | `on`; `off` when `HTTP_PROXY`/`HTTPS_PROXY` (either case) is set and `NO_PROXY` is not `*` | `on` or `off`. A proxy could re-resolve hostnames and undo the fetcher's address pinning, so with a proxy in the environment remote fetch stays off (with a startup warning) unless you set `NO_PROXY=*` for the hub process (direct fetches) or `HUB_REMOTE_FETCH=on` (accept proxying knowingly). `off` turns off the hub fetching web images and link previews for the console (`GET /api/media/remote` and `GET /api/media/unfurl` answer `403 disabled`). Signed-in users only (session and app tokens are refused); http/https on default ports, private and reserved addresses refused, 8 MiB, never decompressed (compressed responses are refused), PNG/JPEG/WebP/GIF only, 30 a minute and 4 at once per user (images and link previews together); the audit log keeps the host, never the URL. Any other value stops the hub at start. Threat model and residual risks: [docs/media-security.md](docs/media-security.md) |
+| `HUB_TRUSTED_PROXIES` | | comma list of reverse-proxy addresses or CIDRs whose `X-Forwarded-For` names the client for per-address rate limits ([connect an app](docs/app-front.md#connect-an-app)); unset: the TCP peer is the client and `X-Forwarded-For` is never read; an invalid entry stops the hub at start |
 | `HUB_FETCH_DENY_CIDRS` | | comma list of extra IPv4 or IPv6 CIDRs the hub never fetches from (`GET /api/media/remote`, `GET /api/media/unfurl`), on top of the built-in loopback, private, link-local (cloud metadata), CGNAT, multicast, reserved, ULA and mapped ranges (e.g. your Kubernetes pod and service CIDRs: `10.42.0.0/16,10.43.0.0/16`); an invalid entry stops the hub at start |
-| `OPENROUTER_API_KEY` | | default key for the `openrouter` speech provider (never sent to other providers) |
+| `OPENROUTER_API_KEY` | | default key for the `openrouter` speech provider (never sent to other providers); [context cards](docs/context-cards.md) on OpenRouter reuse it |
+| `HUB_CONTEXT_CARDS` | on | `off` (or `false`, `0`, `no`) turns [context cards](docs/context-cards.md) off for every user (the kill switch over `hub.json` `contextCards.enabled`); `on` (`true`, `1`, `yes`) overrides it. Any other value stops startup |
 | `HUB_STT_MODEL`, `HUB_TTS_MODEL`, `HUB_VOICE`, `HUB_MAX_*` | see `src/central/config.ts` | speech defaults; the phone's speech settings override them |
 
 The Docker image installs only the hub's runtime packages (web-push and its dependencies, pinned by
@@ -1344,8 +1412,10 @@ recent activity.
 `web/` is the Hub console, a Solid + Vite + TypeScript PWA built to `web/dist` (`npm run build:web`;
 the Docker image, npm package and binaries ship the build). One store fed by the hub's SSE stream drives:
 
-- **Sidebar** (⌘B collapses; a drawer on phones): search, New session, Needs you, Running, Pinned, sessions open in a
-  terminal grouped by project (or server) with `+`, Recents. Each section collapses from its heading (remembered on
+- **Sidebar** (⌘B collapses; a drawer on phones): search, New session, Needs you, **Working set** (your pinned
+  sessions and the 7 you touched most recently within 7 days; Pinned when you touched none), Running, sessions open
+  in a terminal grouped by project (or server) with `+`, Recents. Rows show the session's intent as a muted second
+  line, and Needs you rows how long they have waited. Each section collapses from its heading (remembered on
   the device, `hub.sidebar.sections.collapsed`), showing its count; Needs you always shows its count. Rows show status, a pulsing green dot left of the
   title for the session live in Voice (in Voice mode here, or in a conversation), an unread dot and a `⋯` menu
   (rename, pin, archive, stop, Allow/Disallow Voice).
@@ -1400,7 +1470,8 @@ the Docker image, npm package and binaries ship the build). One store fed by the
   recording cancels it; each session keeps its own unsent draft), Voice mode (hands-free, see below; a toggle that
   turns Voice on first when needed; one session at a time, so turning it on elsewhere turns the first one off; it
   keeps running while you look at other sessions, which show a "Voice: <session>" pill with End) with a
-  microphone picker, and the Voice/Worker model menus. The right rail (a bottom sheet on phones) has
+  microphone picker, the Voice model menu (the voice front's model) and the Model chip (the session's own model; where
+  the machine's plugin serves `setModel` it opens the same menu and sets the model every later turn runs on). The right rail (a bottom sheet on phones) has
   cards that collapse from their header (remembered per device): **Environment** (machine with
   online/offline/Connecting, project folder with the full path as tooltip, branch, and where it is open:
   TUI, Herdr or background), Context, **Connectors · N connected** (MCP servers) and Changes with a diff
@@ -1685,7 +1756,7 @@ public URL, `localhost`, `127.0.0.1` and `[::1]` with the same scheme and port c
 |---|---|---|
 | `POST /api/sessions/:id/utterance {text}` | `steer` | `202 {inboxID}`; allowed while the session is busy (no turn lock). 400 empty or over 4000 chars, 404 no machine of yours reports the session, 502 spoke error, 504 no answer in 15 s |
 | `POST /api/sessions/:id/interrupt` | `interrupt` | `204` |
-| `POST /api/sessions/:id/conversation {on}` | `conversation` | `200 {on, agent}`. 404 when no machine of yours reports the session |
+| `POST /api/sessions/:id/conversation {on, front?}` | `conversation` | `200 {on, agent, front?}`. `on: true` asks for the voice front unless `front: false` (the device opted out); the front is used when the session's machine serves it (`voiceFront`), and `front` in the answer says whether one answers. `agent` is the session's own agent (never switched). 404 when no machine of yours reports the session |
 | `GET /api/sessions/:id` | | `{id, title, directory, parentID?, project?, projectName?, updated, exposed, state, blockers, now?, busy, conversation, status, activity}`; catalog sessions also carry `conversation` |
 | `POST /api/sessions/:id/presence {visible}` | | `204`; the phone posts on `visibilitychange` and every 30 s while visible. A root session is *watched* while any device reported it (or one of its subagent sessions) visible within 45 s |
 | `POST /api/sessions/:id/permission {requestID, decision}` | `permission` | `204`. `decision` is `once`, `always` or `reject`; `:id` is the session or any ancestor. Tried on every process that forwarded the request (OpenCode keeps pending permissions per process and per location; the spoke replies through the plugin instance of the location that holds it). `409 {code: "gone"}` "This request was already answered or expired" when none holds it (its card is dropped). 400 bad decision |
@@ -1779,10 +1850,13 @@ around the mic with the current state: Listening, Hearing you, Transcribing, Sen
 it again, say "pause listening", or leave the page to turn it off. Leaving the page calls
 `{on:false}` with `keepalive`. While conversation mode is off, tap-to-talk works as before.
 
-- **Speech detection** (`web/src/core/speech-vad.ts`; ~20 ms frames from `web/public/vad-worklet.js`, with a
+The loop is the package `packages/voice-client` (a `VoiceTransport` over the console's routes and SSE,
+`web/src/voice/console-transport.ts`); other web apps can embed it ([docs/app-front.md](docs/app-front.md#voice-in-an-app-packagesvoice-client)).
+
+- **Speech detection** (`packages/voice-client/src/core/speech-vad.ts`; ~20 ms frames from `web/public/vad-worklet.js`, with a
   ScriptProcessor fallback): on-device [Silero VAD](https://github.com/snakers4/silero-vad) v5 (MIT) through
   onnxruntime-web (MIT, wasm, single-threaded, so no COOP/COEP headers are needed) in a Web Worker
-  (`web/src/voice/silero-worker.ts`). The mic audio is resampled to 16 kHz and cut into 32 ms chunks; each
+  (`packages/voice-client/src/silero-worker.ts`). The mic audio is resampled to 16 kHz and cut into 32 ms chunks; each
   chunk's speech probability starts speech at ≥ 0.6 sustained for 250 ms (most of the onset voiced, so
   isolated clicks never add up) and ends it after 350 ms below 0.35. Typing, a fan, clatter, beeps and hum
   score low; speech scores high at any loudness. An energy detector stays as a cheap pre-gate (chunks within
@@ -1798,7 +1872,7 @@ it again, say "pause listening", or leave the page to turn it off. Leaving the p
 - **Echo guard**: while a reply or a progress cue plays, and 400 ms after, a barge-in needs more: the model's
   probability ≥ 0.85 (Low 0.92, High 0.75) and 8 dB more energy. The browser's echo cancellation removes most
   of the reply from the mic first.
-- **Noise transcripts** (`web/src/core/junk-transcript.ts`): what speech-to-text makes of noise is dropped
+- **Noise transcripts** (`packages/voice-client/src/core/junk-transcript.ts`): what speech-to-text makes of noise is dropped
   before it reaches the agent and shown dim in the Voice bar for 3 s ("ignored: “Thank you.”"): empty or
   punctuation-only text, sound tags ("[Music]", "(applause)", "♪"), Whisper's stock phrases ("Thank you.",
   "you", "Bye.", "Thanks for watching!", "Subtitles by …", "Amara.org" …), one word repeated, and one or two
@@ -1814,10 +1888,10 @@ it again, say "pause listening", or leave the page to turn it off. Leaving the p
 - **Turn detection (experimental, Settings → Voice → Turn detection, per device)**: "Timers (current)" is the
   default and works as above. "Smart Turn (experimental)" decides the end of a turn from the audio: on-device
   [Pipecat Smart Turn v3](https://huggingface.co/pipecat-ai/smart-turn-v3) (v3.2 int8, BSD-2-Clause, 8.7 MB, loaded on
-  first use as a hashed asset; license in `web/src/voice/turn/LICENSE`) in its own Web Worker
-  (`web/src/voice/smart-turn-worker.ts`, onnxruntime-web as for Silero, so the console policy needs nothing new). The
+  first use as a hashed asset; license in `packages/voice-client/src/turn/LICENSE`) in its own Web Worker
+  (`packages/voice-client/src/smart-turn-worker.ts`, onnxruntime-web as for Silero, so the console policy needs nothing new). The
   console keeps the last 8 s of the turn's 16 kHz mic audio, pauses included (from the turn's first speech start),
-  computes Whisper's log-mel features in TS (`web/src/core/smart-turn-features.ts`, matched to transformers'
+  computes Whisper's log-mel features in TS (`packages/voice-client/src/core/smart-turn-features.ts`, matched to transformers'
   `WhisperFeatureExtractor` within 1e-5) and scores it at each segment end: a score ≥ 0.5 sends 150 ms after the
   score once the transcripts are in; a lower one holds and is re-scored every 400 ms of quiet, with a fallback after
   3 s. Speech resuming cancels the send as with the timers; commands, the 60 s cap and noise transcripts are
@@ -1837,7 +1911,7 @@ it again, say "pause listening", or leave the page to turn it off. Leaving the p
   list items are handled, and fenced code becomes "(code omitted)". Each sentence goes to `/api/speak`,
   up to two ahead of playback, and plays through one `<audio>` element while its MP3 is still downloading:
   through MediaSource (`audio/mpeg` SourceBuffer; Chrome, Android, Firefox), appending bytes as they arrive
-  (`web/src/core/audio-stream.ts`). Browsers without MP3 in MediaSource (some iOS Safari versions) play each
+  (`packages/voice-client/src/core/audio-stream.ts`). Browsers without MP3 in MediaSource (some iOS Safari versions) play each
   sentence once it has fully downloaded, as before. Prefetched sentences keep downloading while they wait. Speech while a reply plays
   (barge-in, past the echo guard) pauses playback, clears the queue and mutes the rest of the replies that were speaking, also a reply still
   being written whose next sentence has not arrived yet (their later sentences still show in the transcript); a
@@ -1876,7 +1950,7 @@ it again, say "pause listening", or leave the page to turn it off. Leaving the p
 
 ### Voice feedback (phone)
 
-Pure logic is in `web/src/core/feedback-core.ts` (tested with bun); `web/src/core/cues.ts` plays cues.
+Pure logic is in `packages/voice-client/src/core/feedback-core.ts` (tested with bun); `packages/voice-client/src/core/cues.ts` plays cues.
 
 - **Voice speed**: 0.75×–2.0× in 0.05 steps, next to "Read replies aloud" and in Settings → Voice
   (default 1.0×, stored per device in `localStorage`). It is applied on the phone as the audio
@@ -1896,7 +1970,8 @@ Pure logic is in `web/src/core/feedback-core.ts` (tested with bun); `web/src/cor
   newest are at the bottom, and it keeps about 30. The agent's reply streams into its bubble (one bubble per
   assistant message); in conversation mode the spoken `say` text is merged into the bubble of the same message.
   The home list shows the same "now" text with a spinner for working sessions.
-- **Progress cues** (conversation mode; Settings → Voice → "Progress cues", on by default): a soft
+- **Progress cues** (conversation mode; Settings → Voice → "Progress cues", on by default; with the voice front
+  only the tones play, its echo replaces the spoken phrases below): a soft
   tone as soon as you stop speaking (the moment the segment goes to transcription; typed text gets it when
   the agent receives it), then a short acknowledgement ("On it.", "One moment.", "Let me check." …) if the
   session is working and the agent has not spoken within 2.5 s of the end of your speech. A hand-off phrase
@@ -1905,7 +1980,7 @@ Pure logic is in `web/src/core/feedback-core.ts` (tested with bun); `web/src/cor
   speech while work continues, and a double tone plays when a subagent finishes. Failed tools are not spoken (they show in the feed). Cues never
   play while you are talking or the agent's speech is playing; they wait, and are dropped once the agent
   speaks. Cues are event-driven: one timer for the next deadline (no polling), re-armed on speech, status and
-  playback changes. Each cue has several variants (`CUE_VARIANTS` in `web/src/core/feedback-core.ts`), chosen
+  playback changes. Each cue has several variants (`CUE_VARIANTS` in `packages/voice-client/src/core/feedback-core.ts`), chosen
   from a shuffle-bag: every variant once before any repeats, never the same phrase twice in a row, and a variant
   whose audio is already loaded wins. All variants are synthesized, 2 at a time, when Voice mode starts (ending Voice mode
   cancels what is left) and kept in memory and in the browser's Cache Storage (`hub-cues-v2`, keyed by TTS provider, model, voice, speed and server, so a later
@@ -1921,7 +1996,7 @@ Pure logic is in `web/src/core/feedback-core.ts` (tested with bun); `web/src/cor
   (`localStorage` `voice.replyLoudness`, clamped to −26…−14 LUFS) becomes the target. Audio that cannot be decoded
   plays as synthesized. Cues and replies keep their plain `<audio>` elements (no Web Audio playback graph, which
   would break background and iOS playback), both at volume 1 and the chosen speed. Pure parts:
-  `web/src/core/loudness.ts`; browser decoding: `web/src/voice/cue-loudness.ts`.
+  `packages/voice-client/src/core/loudness.ts`; browser decoding: `packages/voice-client/src/cue-loudness.ts`.
 - **Presence**: while a session view is open, the phone posts `POST /api/sessions/:id/presence
   {visible}` on visibility changes and every 30 s while visible, and `{visible:false}` on `pagehide` and
   when leaving the view. The hub uses this to decide when to push.
@@ -1946,7 +2021,7 @@ Pure logic is in `web/src/core/feedback-core.ts` (tested with bun); `web/src/cor
   device cookie. It closes when Voice mode ends or the page goes away. It needs notification permission:
   without it the Voice bar shows **Allow notifications**. The Media Session shows "Voice mode on" with the
   session title on the lock screen while Voice audio plays; its pause and stop end Voice mode (logic in
-  `web/src/core/voice-notifier.ts`).
+  `packages/voice-client/src/core/voice-notifier.ts`).
 - **Settings → Speech** (your own settings; admins also edit the server default): cards for Speech-to-text and Text-to-speech, with provider
   (OpenRouter / OpenAI-compatible), base URL (OpenAI-compatible only), model, voice (TTS), language (STT,
   optional), server-side speed (TTS, optional, 0.25–4) and API key. Model and voice are buttons that open a
@@ -1995,6 +2070,8 @@ in the file).
 | `agents.never` | permission patterns (`action[:glob]`) no agent may ever approve, for every user, checked before any grant; see [Agent actions and grants](#agent-actions-and-grants) |
 | `agents.launches` | per-user launch caps `{maxQueued?, maxActive?, perHour?}` (defaults 50, 4, 60) and `lostAfterMinutes?` (0–1440 or false, default 5: a running launch the same node instance stops reporting, with its session gone, ends lost; 0/false: never); see [docs/launches.md](docs/launches.md#placement-and-caps) |
 | `agents.webhooks.allowPrivate` | `true` lets webhooks target `http://`, loopback and private hosts (self-hosted receivers); see [docs/launches.md](docs/launches.md#where-webhooks-may-go) |
+| `contextCards` | `{enabled?, model?: {provider?, model?, baseURL?, apiKey?}, budget?: {calls?, tokens?}}`: the light model the hub calls for [context cards](docs/context-cards.md#configuration) (default OpenRouter `anthropic/claude-haiku-4.5` with the speech OpenRouter key; 200 calls and 400,000 tokens per user per day) |
+| `agents.speechQuotas` | per-credential quotas of [speech for apps](docs/app-front.md#speech-for-apps), any subset of `{transcribe: {perMinute, perHour}, speak: {perMinute, perHour, charsPerHour}}` (defaults 20, 300; 60, 1000, 100000), whole numbers from 1 |
 | `agents.webhooks.allowPrivateHosts` | exact hostnames (at most 50) whose `https://` webhook URLs may resolve to private addresses, e.g. a LAN-hosted app behind split DNS; nothing else is opened; see [docs/launches.md](docs/launches.md#where-webhooks-may-go) |
 
 Server fields: env vars (`HUB_HOST`, `HUB_PORT`, `HUB_PUBLIC_URL`, `HUB_STATE_DIR`) > hub.json >
@@ -2283,7 +2360,7 @@ apart:
 - Stop on a subagent session's page stops its whole tree (as on the root's page).
 - Listening with the phone screen off depends on the browser (best-effort on Android Chrome; not
   possible on iOS). Replies and alerts still arrive as push notifications.
-- The voice agent registers as a visible primary agent (`voice`) in OpenCode's agent list.
+- The voice front registers as a hidden primary agent (`voice-front`); OpenCode lists it with its hidden agents.
 - A catalog change still sends every machine's full catalog to each stream (about 1 KB per few sessions); the
   replay buffer is in memory (a hub restart means a full catalog + `resync`).
 - Running shells are seeded from the spoke's own server (`shell.list` for the 20 most recent session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub",
-  "version": "0.9.2",
+  "version": "0.10.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",
@@ -71,7 +71,8 @@
     "packages/codex/package.json",
     "bin",
     "web/dist",
-    "web/src/voice/turn/LICENSE",
+    "packages/voice-client/src/vad/LICENSE",
+    "packages/voice-client/src/turn/LICENSE",
     "docker",
     "Dockerfile",
     "scripts/hub-local.sh",
@@ -98,7 +99,8 @@
     "packages/claude-code",
     "packages/conformance",
     "packages/preset",
-    "packages/codex"
+    "packages/codex",
+    "packages/voice-client"
   ],
   "engines": {
     "bun": ">=1.4.4"
@@ -108,8 +110,9 @@
   },
   "scripts": {
     "test": "bun test",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p web",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p web && tsc --noEmit -p packages/voice-client",
     "build:web": "vite build --config web/vite.config.ts",
+    "build:voice-client": "vite build --config packages/voice-client/vite.config.ts",
     "build:cli": "bun build packages/cli/src/main.ts --target=node --outfile=packages/cli/dist/hub-cli.js",
     "dev:web": "vite --config web/vite.config.ts",
     "test:e2e": "bash scripts/test-e2e.sh",

package/packages/claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-claude-code",
-  "version": "0.9.2",
+  "version": "0.10.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",