@huynle/hub 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 ## Unreleased
 
+## 0.7.3
+
+Session errors are visible: a quota, auth or rate-limit error in an OpenCode session now shows up in the hub.
+
+- **Retries with OpenCode 2.2**: OpenCode 2.2 no longer sends `session.status`; the plugin translates
+  `session.retry.scheduled` into a `session.status` retry with `next` (time of the next try), `errorType` and
+  `errorStatus`, so older hubs keep working. `session.execution.failed` errors go out as `{message, type, status}` (no
+  provider response body). A pending retry and the last failure are re-sent after a reconnect.
+- **Console**: an alert banner in the session header ("Quota exceeded (HTTP 429): …"), error and retry rows in the
+  transcript (with a live countdown), a "!" badge in session lists; a failed session is listed under Needs you until
+  it runs again or is archived.
+- **Where a session runs**: the session header names machine · project › folder · git branch (a line under the
+  header on phones).
+- **Notifications**: new `providerError` ("Model provider error", on by default) for quota, billing, auth, no-route
+  and unknown provider errors in any session of the tree, once per session per run. Devices with it off still get
+  `failed`. A root's and a subagent's notifications no longer replace each other on the phone.
+
+## 0.7.2
+
+First release with signed standalone `hubctl` binaries (`hubctl-<target>`, `hubctl-manifest.json` signed by `hub-release-1`, `HUBCTL_SHA256SUMS`) and pinned OpenCode 2.2.0 for `hubctl setup`.
+
+- **`hub login` with a device code**: without `--token`, `hub login [--url URL] [--scope S]... [--name N]` prints an
+  approval link and code; you approve it in the console as yourself (`/approve`: "CLI login for <name>", every
+  scope as a checkbox, the requested ones ticked) and get an app token with the scopes you chose (default
+  `sessions:read`, `messages:send`, `messages:read`; `--scope sessions:launch` or ticking it for launching, which
+  also needs a grant with verb `launch`, as the output says). Stored like `--token` (owner-only, now written
+  atomically); the URL defaults to this machine's enrollment. `--token` and a piped token still work. New hub routes:
+  `POST /cli/login`, `/cli/login/poll`, `GET /api/cli-logins/:code`, `POST …/approve|deny` (devices only; single-use,
+  10-minute codes; audited `cli-login.approve|deny`, never the token).
+- On an enrolled machine without a user login, `hub launch`, `whoami` and the other user commands now say that the
+  machine enrollment (`mch_…`) is not a user login and to run `hub login`; a forbidden `hub launch` with an app token
+  says it needs a grant with verb `launch`.
+- **`hub` on PATH for plugin-only installs**: the OpenCode plugin links `~/.local/bin/hub` to its launcher (only when
+  nothing of yours is there and no other `hub` is on PATH; the setup's `hub` → `hubctl` link is kept), with one hint
+  when `~/.local/bin` is not on PATH.
+
+- **hubctl bootstrap**: `hubctl machine enroll|status` and `hubctl setup discover|preview|apply|verify|drift|
+  rollback|recover|ansible` (also as `hub …`; the program name grants nothing). A standalone hubctl enrolls the
+  machine with the device code, previews a deterministic typed plan (writes nothing; `--out` keeps it for apply),
+  and applies exactly that plan after rediscovering and re-planning: pinned OpenCode, Claude Code and Codex installs
+  from the signed release manifest (`--manifest`), lossless config edits, hub's user services (loaded only with
+  `--confirm-activation`), an optional bounded verification launch (`--verify-launch`), all journaled and undone
+  with `setup rollback`. Readiness comes from real probes (`setup verify`, exit 15 when not ready). `--json` prints
+  one `hub.bootstrap.result` envelope; exits 10–15 are new (docs/bootstrap-contracts.md §3.11).
+- **hubctl bootstrap, install is not readiness (contract v1.2)**: `setup apply` on a fresh host no longer rolls
+  back because you have not logged in to a provider or started the harness yet (which needs the installed harness).
+  Readiness probes are classified: a broken install (missing or wrong binary, version mismatch, container shim, a
+  binary that does not run) still rolls back; a harness that only waits on you is committed as "installed, not
+  ready", with each probe's status and the next steps (`--json`: `data.harnesses`). `--require-ready` keeps the
+  strict behaviour (exit 15, rolled back); `setup verify` stays the strict gate; `--verify-launch` keeps its
+  harness strict. A rollback now also removes the root directories the apply created (e.g. `~/.local/bin`), and a
+  directory hub created that something else wrote into is kept as a note, not a conflict. The Ansible role passes
+  `--require-ready` only with `hub_bootstrap_apply_require_ready` and gates readiness at its verify step.
+- **hubctl bootstrap, HBS-12 acceptance fixes**: `machine enroll` turns sharing on (`mode: "always"`) when
+  `config.json` has no mode, so the OpenCode spoke of a hubctl-enrolled machine connects (an explicit `"off"` is kept
+  and reported); a rerun on a converged host plans only verification (the installed hubctl is compared by digest, not
+  path); a hub-installed OpenCode, Claude Code or Codex is linked into `~/.local/bin` when no other one is on PATH
+  (with a hint when `~/.local/bin` is not on PATH); the OpenCode probes retry once when a cold OpenCode service has
+  not finished activating its plugins (HTTP 503); and the plugin no longer loads `@opencode/plugin`'s runtime, so it
+  activates faster on a cold start. Units for a standalone hubctl no longer set `BUN_BE_BUN=1` (it made the compiled
+  binary act as the bun CLI and crash-loop), and `--confirm-activation` now checks that each activated service stays
+  running: a failed or crash-looping service fails the apply with `service_failed` (exit 15), is unloaded and rolled
+  back, and the message points at `journalctl --user -u <unit>` or the agent's log.
+- **Hub API**: `GET /spoke/presence` (machine token only, read-only) lists which harness spokes of the caller's own
+  machine are connected (harness, evidence, features), for `hubctl setup verify`.
+- `hub node install`, `hub claude-code install` and `hub codex-spoke install` render their units from templates
+  embedded in the program (so a standalone hubctl can install them); a standalone hubctl's units start the binary
+  itself. The hints for an unenrolled machine now say `hubctl machine enroll`.
+- The `hub`/`hubctl` launchers run `~/.local/bin/hubctl` when it is installed. `hub claude`, the Claude Code daemon
+  and the node run the Claude Code `hubctl setup` installed (HUB_CLAUDE_BIN, else hub's `claude-code.json`
+  `binary`, else PATH); `hub codex`, the Codex spoke and its unit the hub-installed Codex (HUB_CODEX_BIN, else
+  `~/.local/share/hub/harnesses/codex/current/bin/codex`, else PATH). The node's host runtime now offers `codex`
+  when the Codex CLI is found.
+
+- **Archive through MCP**: `archive` and `unarchive` (and the narrow agent API
+  `PUT /api/agent/sessions/:addr/archive`) change the Hub's archived state without deleting a harness session.
+  App tokens use the new explicit `sessions:manage` scope, selectable in Settings → Agents. Existing tokens do
+  not gain the scope; operations are idempotent and preserve unrelated view preferences.
+
+- Add App token management to Settings → Agents: create scoped tokens, copy the one-time bearer secret and grant-holder ID, list existing tokens and revoke them.
+
+- **MCP over HTTP**: the hub serves `hub mcp`'s tools at `POST /mcp` (MCP Streamable HTTP, stateless JSON
+  responses) for MCP clients and gateways. Auth is `Authorization: Bearer <token>` (an app token with the tools'
+  scopes; device, session and act tokens too); a missing or bad token answers `401` with `WWW-Authenticate: Bearer`.
+  The tools run as that token through the agent API in process, so scopes, grants, tenancy and the audit apply.
+  Packages now ship `packages/cli/src` (the image copies it too).
+
 ## 0.7.1
 
 - **Release**: the npm package is published again. 0.7.0's publish step had no Bun for the CLI bundle, so 0.7.0 is

package/Dockerfile

@@ -63,6 +63,9 @@ COPY packages/protocol/src ./packages/protocol/src
 # The SDK's pure envelope and address helpers (src/central/agent/envelope.ts and names.ts re-export them).
 COPY packages/sdk/package.json ./packages/sdk/
 COPY packages/sdk/src ./packages/sdk/src
+# The CLI's MCP tool table (POST /mcp serves it; src/central/mcp-http.ts imports packages/cli/src/mcp.ts).
+COPY packages/cli/package.json ./packages/cli/
+COPY packages/cli/src ./packages/cli/src
 COPY --from=web /build/web/dist ./web/dist
 
 ENV HUB_HOST=0.0.0.0 \

package/README.md

@@ -133,6 +133,75 @@ 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.
 
+## Quick start (hubctl, before any harness)
+
+`hubctl` is a standalone, signed program (Bun and the CLI compiled into one file; no bun, node or harness needed)
+that bootstraps a machine into Hub: it enrolls the machine, then previews and applies a typed plan that installs
+pinned harnesses, edits their configs losslessly and writes hub's user services. `hub` and `hubctl` are the same
+program; the name grants nothing (only the machine credential and your consent flags do). Nothing is run through a
+shell, and the hub never gets a way to run commands here.
+
+```sh
+# 1. Download hubctl for your platform (darwin-arm64, darwin-x64, linux-x64, linux-arm64) and the signed manifest
+#    from the release, then install the binary yourself (the first apply installs the release's copy as
+#    ~/.local/bin/hubctl, with `hub` linked to it):
+curl -fsSLo hubctl https://github.com/huynle/hub/releases/download/v<version>/hubctl-darwin-arm64 && chmod +x hubctl
+curl -fsSLO https://github.com/huynle/hub/releases/download/v<version>/hubctl-manifest.json
+
+# 2. Enroll this machine (device code: approve it on the hub; Ctrl-C cancels). One identity for every spoke here.
+./hubctl machine enroll --server https://hub.example.com
+./hubctl machine status          # verified | revoked (exit 9) | offline (exit 7) | insecure (plain-http hub)
+
+# 3. Preview: discover the host and print the exact plan and any manual edits. It writes nothing.
+./hubctl setup preview --profile session-only --manifest hubctl-manifest.json --out preview.json
+
+# 4. Apply exactly that plan (rediscovered and re-planned; refused when the host changed since, exit 12). A harness
+#    that is installed and runs but still waits on you (provider login, spoke not started) is committed as
+#    "installed, not ready" with the next steps; --require-ready fails (exit 15) and rolls back instead.
+./hubctl setup apply --preview preview.json --manifest hubctl-manifest.json
+
+# 5. Do the next steps it printed (e.g. `opencode auth login`, start OpenCode), then check readiness with real
+#    probes (version, provider login, spoke connected; exit 15 when not ready), and undo whenever you like.
+hubctl setup verify
+hubctl setup rollback            # or --to <txID>; files you changed since are kept and reported
+```
+
+- Profiles: `session-only` (OpenCode), `launch-node` (+ `hub node` as a user service; give
+  `--workspace-root <dir>`), `full-harness` (OpenCode, Claude Code, Codex and their spokes), or a profile file
+  (`--profile <file>` or `-` for stdin).
+- Consent is explicit and never a default: `--confirm-activation` (load the user services; give it at preview and
+  again at apply), `--escalate` (system locations), `--allow-downgrade`.
+- `--enrollment separate` leaves enrollment to `hubctl machine enroll` (the default is inline when you pass
+  `--server` to preview). A config behind a symlink (dotfiles) is never written through: the preview prints the
+  exact edit and the file it belongs in.
+- `hubctl setup drift` reports hub's managed fields (in sync, missing, outdated, changed by you);
+  `hubctl setup recover [--resume]` finishes or rolls back an interrupted apply.
+- With `--json`, every command prints one `hub.bootstrap.result` envelope; exit codes are listed in
+  [docs/bootstrap-contracts.md](docs/bootstrap-contracts.md#311-output-envelope-and-exit-codes) (10 conflict,
+  11 artifact rejected, 12 preview invalid, 13 locked, 14 recovery required, 15 not ready).
+- Many machines: the optional Ansible role in [contrib/ansible](contrib/ansible/roles/hub_bootstrap/README.md)
+  runs the same preview and apply (`hubctl setup ansible` renders its vars; enrollment stays a separate step).
+
+### Start a launch from a terminal
+
+On a machine set up with `hubctl setup` (or the OpenCode plugin), `hub` is on your PATH: `~/.local/bin/hub` links to
+hubctl, or (plugin only) to the plugin's launcher; if `~/.local/bin` is not on your PATH, both say so once. A machine
+enrollment identifies the **machine**, never you, so launching from your own shell needs a user login first:
+
+```sh
+hub login --scope sessions:launch        # prints a link and a code; approve it in the console as yourself
+                                          # (the page lists the scopes; tick "sessions:launch" if you did not ask)
+hub launch --repo ~/projects/app --branch feat/x --prompt "Fix the flaky test"
+```
+
+`hub login` without `--token` is a device code (Ctrl-C cancels); its URL defaults to `HUB_URL`, your last login, else
+this machine's enrollment. You get an app token with the scopes you approved (default `sessions:read`,
+`messages:send`, `messages:read`), stored owner-only in `~/.config/hub/cli.json`, and revocable in Settings → Agents.
+An app token launches only under a **grant** with verb `launch` covering the repo: create it in Settings → Agents, or
+ask for it from the terminal (`hub grant request --project ~/projects/app --allow launch --why "…"`) and approve it.
+Without a user login, `hub launch` on an enrolled machine says so (`this machine is enrolled (mch_…), but launching
+needs a user login: run hub login`). `hub login --token <app token>` (or a token piped on stdin) still works.
+
 ## Running the hub
 
 The hub serves the web app, pairs devices, enrolls machines, and does push and (for Voice) speech. Pick one:
@@ -198,7 +267,8 @@ foreground with `hub.json`; `scripts/io.github.huynle.hub.plist` is a launchd te
 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`, the manifest and
-icons reachable for spokes, sign-in, app discovery and the PWA.
+icons reachable for spokes, sign-in, app discovery and the PWA (and `/mcp`, bearer-authenticated, if MCP clients
+or gateways use [MCP over HTTP](#over-http-mcp)).
 
 ## Configuration
 
@@ -244,6 +314,32 @@ conversation mode and utterances (403 `not_exposed` for sessions not shared with
 
 ## Agent identity (agent API)
 
+**Organization.** `PUT /api/agent/sessions/:addr/archive {archived: true|false}` archives or unarchives one
+session in Hub views without deleting it in its harness. Users always may; app tokens need `sessions:manage`.
+The operation is idempotent, returns `{sessionID, archived, changed}`, and preserves unrelated view preferences.
+MCP exposes the same operations as `archive` and `unarchive`. Naming (`POST /api/agent/name`) also takes an app
+token with `sessions:manage`; role claims and releases take one with `sessions:manage` **and** a grant allowing
+`roles` whose projects cover the session's directory (the session must be online), under the kill switch and hourly
+cap, with every outcome in the agent audit (verbs `roles` and `roles.release`). Reserved roles stay yours to assign.
+Apps and users name the session (`session`); foreign and unknown sessions are both `404 not_found`. MCP: `name`,
+`role_claim` and `role_release`. Each change is one `session.named`, `role.claimed` or `role.released` event.
+
+**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`, `role.claimed`, `role.released`. 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`
+may repeat and still advance the cursor over what they skip. At most 1,000 events are inspected per request; `more`
+means some remain. A cursor the journal no longer covers (expired, trimmed, hub restarted) answers
+`{events: [], cursor, more: false, reset: true, refresh: ["status", "sessions", "inbox", "decisions", "launches"]}`:
+re-read those, then continue with the new cursor. `GET /api/agent/watch` streams the same events live over SSE
+(`{type: "ready"}` first, `{type: "reset", refresh}` when its cursor is no longer covered, `event: ping` while
+idle), with the same visibility and filters (`blocked=1` is `type=blocker.*`). A malformed, forged or another user's cursor is
+`400 invalid_cursor`. Unknown event types are valid; ignore them. App tokens need `events:subscribe`, and see each
+family only with its scope: session and machine events with `sessions:read`, archive, name and role events with `sessions:manage`,
+messages they are a party to with `messages:read`, launches they started with `sessions:launch`. MCP: `events`.
+
 Agents, scripts and apps talk to the hub through `/api/agent/*`, a small API with its own credentials, separate
 from the console's routes. Every request resolves to exactly one **actor**:
 
@@ -251,7 +347,7 @@ from the console's routes. Every request resolves to exactly one **actor**:
 |---|---|---|
 | user | the device cookie (browsers) or the same secret as `Authorization: Bearer <device token>` (apps, CLIs; [linked with a code](#multi-user-sign-in-with-google)) | you, on one of your devices |
 | session | a **session token** `hst1.…` the hub mints for each session a spoke reports | that session's shells (`HUB_SESSION_TOKEN`) |
-| app | an **app token** `hat_…` you create (scopes `sessions:read`, `messages:send`, `messages:read`, `sessions:act`) | a script or tool outside a session (`hub login`) |
+| app | an **app token** `hat_…` you create (scopes `sessions:read`, `sessions:manage`, `messages:send`, `messages:read`, `sessions:act`, `sessions:launch`, `events:subscribe`) | a script or tool outside a session (`hub login`) |
 
 **Session tokens in shells.** The hub mints a 24 h token for every session (subagents included) its spokes report
 for you and pushes it to the spoke, which keeps it in memory only. Every shell an agent starts through OpenCode's
@@ -296,10 +392,11 @@ cookie and a hub bearer token (400).
 | `GET /api/agent/sessions?project=&state=&machine=&label=k=v` | ✓ | ✓ | ✓ | the same sessions as a flat list |
 | `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/watch?blocked=1&session=<addr>` | ✓ | ✓ | ✓ | SSE of compact events (`ready`, `state`, `blocker.opened/closed`, `session.added/removed`, `message`; no text) |
+| `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/name {name, session?}` | ✓ | own session | – | names a session (`409 name_taken`) |
-| `POST /api/agent/roles/claim {role, exclusive?, project?, session?}` · `…/roles/release` | ✓ | own session | – | claims (with a new `generation`) or releases a role |
+| `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?}` | ✓ | ✓ | `messages:send` | tells a session (`all`: every holder of a role); never yourself |
 | `POST /api/agent/ask {to, text, expiresIn?, wait?}` | ✓ | ✓ | `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?}` |
@@ -396,7 +493,8 @@ sessions or apps; see [Decisions and `@me`](#agent-identity-agent-api) for the r
 - The model itself: the plugin's `hub` tool (verbs `msg`, `ask`, `reply`, `decline`, `inbox`, `who`, `status`,
   `whoami`, 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.
+- Other agents and tools: [`hub mcp`](#hub-mcp-mcp-server), as the app token you logged in with, or the hub's
+  [`POST /mcp`](#over-http-mcp) as the bearer token sent.
 - Scripts: `hub login` with an app token that has the `messages:send` (and `messages:read`) scopes.
 
 **Limits.** Per 10 minutes: 20 messages per sender→recipient pair and 300 per user (`rate_limited`, exit 6, with
@@ -448,7 +546,7 @@ where the call is visible and audited.
   reserved roles), or `app:<token id>` (one of your app tokens).
 - **scope.projects**: 1–20 absolute project directories; a session is in scope when its directory is one of them or
   inside one (on a path boundary, after resolving `.`/`..`; worktrees inside the project count).
-- **allow**: the verbs (`approve`, `deny`, `answer`, `prompt`, `stop`; `roles` is accepted for role management).
+- **allow**: the verbs (`approve`, `deny`, `answer`, `prompt`, `stop`; `roles` lets an app token with `sessions:manage` claim and release roles of sessions in scope).
   `deny`, `answer`, `prompt` and `stop` need only the verb; `approve` also needs the request to pass the patterns.
 - **permissions**: patterns `action[:glob]` in OpenCode's wildcard syntax (`*` any run, `?` one character, a trailing
   ` *` optional; `bash` is OpenCode's `shell`; the action alone means every resource). A request is allowed only
@@ -579,6 +677,12 @@ for agents and scripts. The OpenCode plugin writes both launchers into the hub b
 session `hub` just works. A launcher runs the CLI bundle shipped in this package (`packages/cli/dist/hub-cli.js`)
 with the OpenCode binary itself (`BUN_BE_BUN=1 exec <opencode> hub-cli.js "$@"`), so neither bun nor node has to
 be installed; without Bun it falls back to `node`. The launchers are rewritten only when their content changes.
+When a standalone hubctl is installed as `~/.local/bin/hubctl` (what `hubctl setup` installs), the launchers run it
+instead, so shells, services and MCP clients all use that one signed program. For your own terminals the plugin also
+links `~/.local/bin/hub` to its `hub` launcher, with the setup's rule for `~/.local/bin`: only when nothing is there or
+it is hub's own link, never when another `hub` is on PATH (then it prints where hub's is), and only from the default
+state dir (not with `HUB_STATE_DIR`). `hubctl setup`'s `hub` → `hubctl` link is kept; `~/.local/bin/hubctl` is left to
+`hubctl setup`. When `~/.local/bin` is not on PATH it prints one hint.
 
 **Name clash:** GitHub's old `hub` CLI (github/hub) uses the same name. In hub sessions ours comes first on PATH;
 elsewhere use `hubctl`, or call the bundle directly (`bun …/packages/cli/dist/hub-cli.js`).
@@ -628,7 +732,8 @@ hub codex-spoke install|uninstall [--dry-run] · hub codex-spoke status   the Co
 hub preset list · hub preset check <name|file>
 hub preset run <name|file> [--socket <name> | --current] [--cwd <dir>] [--resume <id>] [--no-hub] [-- args…]
 hub mcp                                   an MCP server on stdio (see below)
-hub login [--url URL] [--token APP_TOKEN] · hub logout
+hub login [--url URL] [--scope S]... [--name N]   device code: approve it in the console, choose the scopes
+hub login [--url URL] --token APP_TOKEN|- · hub logout
 hub help · hub --version
 ```
 
@@ -742,7 +847,12 @@ OpenCode (Claude Desktop, Cursor, other agents). It speaks JSON-RPC 2.0, one mes
 transport; protocol revisions `2025-06-18`, `2025-03-26` and `2024-11-05`), and answers `initialize`, `ping`,
 `tools/list` and `tools/call`; notifications (`notifications/initialized`, `notifications/cancelled`, which aborts
 the call) get no answer, other methods answer `-32601`. Its tools are the CLI's verbs: `whoami`, `status`,
-`sessions`, `show`, `log`, `who`, `msg`, `ask`, `reply`, `decline`, `inbox` and the act verbs `approve`, `deny`,
+`sessions`, `show`, `log`, `who`, `archive`, `unarchive`, `pin`, `unpin` (`addr`), `archive_inactive`
+(`preview`, `inactiveFor`, `limit`, then `previewToken`, `confirm`), `msg`, `ask`, `reply`, `decline`, `inbox`, `message_show` (`id`, `wait`),
+`mute` and `unmute` (`addr`; agent-message mutes, not console notifications), `decisions` (`state`) and
+`decision_show` (`id`) (reading the Decisions you asked; no tool answers one, only the user does), and
+`webhook_create` (`url`, `events`, `label`), `webhooks`, `webhook_show` (`id`) and `webhook_delete` (`id`). Webhooks
+carry the same canonical compact events as `events`; their signing secret appears only in `webhook_create`. The act verbs are `approve`, `deny`,
 `answer` (`answer` object or `cancel`), `prompt` (`delivery`) and `stop`, and the launch tools `launch` (`repo`
 required and absolute; `mode`, `branch`, `base`, `remote`, `key`, `name`, `roles`, `harness`, `agent`, `model`,
 `runtime`, `profile`, `machine`, `nodeLabels` and `labels` objects, `prefer`, `prompt`, `end`, `timeout`,
@@ -750,7 +860,8 @@ required and absolute; `mode`, `branch`, `base`, `remote`, `key`, `name`, `roles
 (`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
-most 60 s (one long poll; a longer wait is cut to 60) and `expires` in seconds or as `2h`. Answers are the CLI's
+most 60 s (one long poll; a longer wait is cut to 60) and `expires` in seconds or as `2h`; `ask @me` reports the
+Decision it opened. Answers are the CLI's
 short text; messages and answers from other sessions come in the hub's envelope and are marked as not from the
 user. Hub errors are tool results with `isError: true` and the hub's `code: message` (plus candidates and hint),
 never protocol errors. Only protocol frames go to stdout; the server ends when stdin closes (after answering the
@@ -766,9 +877,35 @@ calls in flight) or on SIGINT/SIGTERM.
 set, else the `hub login` file. MCP clients start servers without a hub session's shell environment, so in practice
 it acts as the **app token** you logged in with (needs `sessions:read`, `messages:send` and `messages:read`), not
 as an OpenCode session: messages are sent from the app, and replies to them land in its inbox (the `inbox` tool),
-not in a session. Naming and roles stay out (app tokens cannot use them). Inside OpenCode, agents use the plugin's
+not in a session. App tokens can archive, unarchive and name sessions with `sessions:manage`, and claim or release roles with it plus a `roles` grant. Inside OpenCode, agents use the plugin's
 `hub` tool instead, which acts as the calling session.
 
+#### Over HTTP (/mcp)
+
+The hub serves the same tools at **`POST /mcp`** ([Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http)),
+for MCP clients and gateways that take a remote server URL. It is stateless: one JSON-RPC message per POST, answered
+as `application/json` (no SSE stream, no `Mcp-Session-Id`); notifications and responses get `202` with no body;
+batches answer `-32600`; `GET`/`DELETE` answer `405` (`Allow: POST`). `initialize` also returns short
+`instructions`. Requests need `Content-Type: application/json`, an `Accept` that allows `application/json` (or
+none), a body of at most 1 MiB (else `413`) and, when sent, a supported `MCP-Protocol-Version` (else `400`). A
+browser `Origin` other than the hub's own is refused (`403`); requests without one (servers, gateways) are fine.
+
+**Auth.** `Authorization: Bearer <token>`: any credential the agent API takes, in practice an **app token**
+(Settings → Agents, or `POST /api/agent/app-tokens`) with the scopes the tools need: `sessions:read` (reading), `sessions:manage` (archive/unarchive, name; roles also need a `roles` grant), `events:subscribe` (events),
+`messages:send` and `messages:read` (messaging), `sessions:act` plus a grant (act tools), `sessions:launch` plus a
+launch grant (launch tools). Device, session and act tokens work too. No or a bad token answers `401` with
+`WWW-Authenticate: Bearer realm="hub"` (no OAuth discovery). The tools call `/api/agent` as that token, inside the
+hub process: scopes, grants, tenancy, kill switches and the agent audit apply as on the HTTP API, and a scope the
+token lacks is an `isError` tool result. Cookies never authenticate `/mcp`.
+
+Add it to an MCP client or gateway as a remote (HTTP) server with bearer auth, one token per user:
+
+```json
+{ "mcpServers": { "hub": { "type": "http", "url": "https://hub.example.com/mcp", "headers": { "Authorization": "Bearer hat_…" } } } }
+```
+
+(an MCP gateway: URL `https://<hub>/mcp`, auth kind bearer, per-user credential: each user pastes their own app token).
+
 ## Spoke (OpenCode plugin)
 
 The plugin is a thin client ("spoke") of the hub. Every OpenCode process that loads

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "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",
@@ -49,6 +49,8 @@
     "packages/protocol/package.json",
     "packages/sdk/src",
     "packages/sdk/package.json",
+    "packages/cli/src",
+    "packages/cli/package.json",
     "packages/cli/dist/hub-cli.js",
     "packages/runtime-sdk/src",
     "packages/runtime-sdk/package.json",

package/packages/claude-code/package.json

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

@@ -9,7 +9,7 @@ import { spawnSync } from "node:child_process"
 import { realpathSync } from "node:fs"
 import { configPath } from "../../../src/config.ts"
 import { nodeConfigPath, readNodeConfig, readSpokeCredentials } from "../../node/src/config.ts"
-import { findExecutable } from "../../node/src/harnesses.ts"
+import { claudeBinary, findExecutable } from "../../node/src/harnesses.ts"
 import { runHook } from "./bridge.ts"
 import { startDaemon, type DaemonLaunchOptions } from "./daemon.ts"
 import { runMcpPipe } from "./mcp.ts"
@@ -42,12 +42,12 @@ export function claudeVersion(bin: string, env: ClaudeCodeIo["env"]): string {
 
 /**
  * How the daemon starts Claude Code for hub launches, or undefined when it does not: the Claude Code CLI must be
- * found (HUB_CLAUDE_BIN, else `claude` on PATH) and node.json must not withhold claude-code (harnesses). Launch
+ * found (claudeBinary: HUB_CLAUDE_BIN, hub's claude-code.json, else `claude` on PATH) and node.json must not withhold claude-code (harnesses). Launch
  * directories must be under node.json's workspaceRoots (read again at each create); launched sessions load the hub
  * plugin `hub claude` loads (written when the first launch needs it).
  */
 export function daemonLaunchOptions(io: { readonly env: ClaudeCodeIo["env"]; readonly home: string; readonly program: Program }): DaemonLaunchOptions | undefined {
-  const bin = findExecutable(io.env.HUB_CLAUDE_BIN || "claude", io.env)
+  const bin = findExecutable(claudeBinary(io.env, io.home), io.env)
   if (!bin) return undefined
   const file = nodeConfigPath(io.env, io.home)
   if (readNodeConfig(file).config.harnesses?.["claude-code"] === false) return undefined
@@ -83,7 +83,7 @@ async function daemon(io: ClaudeCodeIo): Promise<number> {
       socketPath: socketPath(io.env, io.home),
       server: credentials.server,
       token: credentials.token,
-      harnessVersion: claudeVersion(io.env.HUB_CLAUDE_BIN || "claude", io.env),
+      harnessVersion: claudeVersion(claudeBinary(io.env, io.home), io.env),
       pluginVersion: VERSION,
       directory: io.home,
       log,

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

@@ -7,7 +7,7 @@
 // asyncRewake Stop hook would hold the run until its timeout). On a machine that is not enrolled (no machine token) or when the daemon
 // cannot be started, Claude Code runs without the hub, and the command says why.
 //
-// Settings (environment): HUB_CLAUDE_BIN (default `claude` on PATH), HUB_CLAUDE_PERMISSION_WAIT (seconds a
+// Settings (environment): HUB_CLAUDE_BIN (default: hub's claude-code.json `binary`, else `claude` on PATH), HUB_CLAUDE_PERMISSION_WAIT (seconds a
 // permission request waits for the hub, default 120; 0: report only), HUB_CLAUDE_REWAKE_TIMEOUT (seconds the
 // asyncRewake Stop hook may wait for a message, default 3600).
 import { spawn } from "node:child_process"
@@ -16,6 +16,7 @@ import { closeSync, openSync } from "node:fs"
 import path from "node:path"
 import { configPath } from "../../../src/config.ts"
 import { readSpokeCredentials } from "../../node/src/config.ts"
+import { claudeBinary } from "../../node/src/harnesses.ts"
 import pkg from "../package.json" with { type: "json" }
 import { writePlugin } from "./plugin.ts"
 import { claudeStateDir, ensurePrivateDir, socketPath } from "./paths.ts"
@@ -149,7 +150,7 @@ export async function runClaude(args: readonly string[], io: ClaudeIo): Promise<
     if (printWithoutStreamingInput(args)) env.HUB_CLAUDE_REWAKE = "off"
     await ask(socket, { v: WIRE_VERSION, kind: "launch", launch, pid: process.pid }, { timeoutMs: ASK_MS })
   }
-  const code = await spawnClaude(io.env.HUB_CLAUDE_BIN || "claude", plugin ? ["--plugin-dir", plugin, ...args] : [...args], env, io.stderr)
+  const code = await spawnClaude(claudeBinary(io.env, io.home), plugin ? ["--plugin-dir", plugin, ...args] : [...args], env, io.stderr)
   if (plugin) await ask(socket, { v: WIRE_VERSION, kind: "exit", launch }, { timeoutMs: ASK_MS })
   return code
 }