@huynle/hub 0.8.6 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,144 @@
 # Changelog
 
+## 0.9.0
+
+Three things in one release: **media in sessions** (screenshots, images, Mermaid diagrams, safe HTML previews, and
+web images and link previews for the sites you allow), **app delivery** for hub apps (idempotent messages, delivery
+deadlines, and team-intake webhooks), and two **voice experiments** that were prepared as 0.8.8 (Smart Turn and the
+Voice front, both off by default). Session images, local image paths, HTML previews and the Voice front need the
+0.9.0 plugin on the machine (the OpenCode harness; other harnesses keep file chips and today's Voice mode); Mermaid
+diagrams, web images and link previews work in any reply. No migration is needed.
+[docs/session-view.md → Media in sessions](docs/session-view.md#media-in-sessions),
+[docs/media-security.md](docs/media-security.md),
+[docs/plans/2026-11-06-app-delivery-contracts.md](docs/plans/2026-11-06-app-delivery-contracts.md).
+
+### Media in sessions
+- **Tool screenshots and attachments in the transcript.** A tool group shows its images as a strip of thumbnails
+  under its head (also while folded; 8, then "+N"), so a screenshot is no longer just a `[image/png, 1.2 MB — not
+  shown]` placeholder, and your attachments load the same way. Images keep their space while loading, load once on screen, and on a phone
+  over cellular, 2g or Save-Data an image over 512 KB waits for a tap ("Screenshot · 1.8 MB · Tap to load").
+- **Image files a reply names** (`![chart](./out/chart.png)`) show inline, read from the agent's machine only when
+  the path is in that message's text and inside the session's folder (its `.worktrees/` too) or a file the session
+  itself read, wrote or edited; never dotfiles (`.git/`, `.env`, `.ssh/`) it did not touch, never `~`.
+- **Full-screen viewer** for any image or diagram: pinch, wheel or double tap to zoom, drag to pan, ←/→ between a
+  message's images, Download, Escape to close.
+- **A failed image says why** on its chip: the machine is offline, not in this session's files, too large, not an
+  image, this harness can't share images, or try again (one quiet retry, then Retry).
+- **Artifact images in replies**: `![alt](/artifacts/<id>)` (or a revision) shows the artifact's image inline with a
+  caption link, in session replies, the Concierge panel and artifact Markdown.
+- **Mermaid diagrams**: ```` ```mermaid ```` and ```` ```mmd ```` blocks draw as diagrams (in the session, the
+  Concierge panel and artifacts) with a Diagram / Source toggle, Copy source and Download SVG, themed to light or
+  dark. They draw once the fence has closed, when scrolled into view; a broken or unsupported diagram shows its code
+  with the reason, one over 50 KB stays code. Voice says "a diagram" instead of reading the source.
+- **HTML previews**: an ```` ```html ```` block, or a code span or link naming a local `.html` page, gets a
+  **Preview** button. The page (with its scripts, styles and images) opens beside the session in the isolated
+  artifact host, where external resources are blocked; a local page lists the files it left out and has
+  **Refresh**. Previews are private artifacts: **Keep** one to make it a normal artifact, else it is archived a day
+  after you last opened it and deleted a week later. Artifacts → **Show: Previews** lists them.
+- **Web images**: Settings → **Media** holds the sites whose images load by themselves (`github.com`,
+  `*.githubusercontent.com`; empty at first). Any other site's image is a card naming the domain, with **Load
+  image**, **Always allow <domain>** and "Load all from this domain in this session". The hub fetches the image, not
+  your browser.
+- **Link previews**: a link to an allowed site gets a card (title, description, image) under its paragraph, at most
+  3 per message; other links get a small preview button that fetches only when you tap it. No favicons.
+
+### Security
+- **Agent media is untrusted everywhere.** The console's CSP is unchanged. Raster images show only as `blob:` URLs of
+  bytes the hub checked; SVG (files, artifacts, diagrams) only as a `data:` URL in an `<img>`, never in the page and
+  never as a `blob:` (the viewer offers SVG as a download only); diagrams with active content are not shown; raw HTML
+  in a reply still never renders, and HTML runs only in the isolated artifact host.
+- **The spoke decides which local files can be shown**, never the console: the path must be in the message's own
+  text; realpath under the session's folder or in its touched set (completed read/write/edit only); no unvisited
+  dotfiles; regular files whose open handle is the checked file (Linux also through `/proc/self/fd`, macOS 11+ with
+  `O_NOFOLLOW_ANY`); magic bytes PNG/JPEG/WebP/GIF/SVG, ≤ 8 MiB, ≤ 40 MP, ≤ 16,384 px per side. The hub re-sniffs
+  every image and checks its length and SHA-256 before answering.
+- **A safe outbound fetcher** for web images and link previews: signed-in users only (session and app tokens are
+  refused, so agents cannot use the hub as a fetcher), http/https on default ports without userinfo, private,
+  loopback, link-local (cloud metadata), CGNAT, reserved, ULA and mapped/translated/tunnelled IPv6 addresses refused,
+  the checked address pinned (DNS rebinding), redirects re-checked (3 at most), no cookies, 3 s / 8 s timeouts,
+  bodies capped and never decompressed (gzip bombs), web images PNG/JPEG/WebP/GIF only (no SVG from the web), 30
+  fetches a minute and 4 at once per user. The audit log keeps the host and outcome, never the URL (it may hold the
+  leaked data).
+- **Allowlist rules**: no IP addresses, ports, paths, bare `*` or public suffixes alone (`*.com`, `*.github.io`); a
+  URL with userinfo never loads by itself. Settings warns that an allowed site hosting other people's content can
+  still receive data an agent puts in an image URL.
+- Known residual risks (Windows/macOS < 11 directory-swap race, hard links inside the workspace, per-pod limits in
+  cluster mode, a Bun wildcard-certificate quirk) are listed in [docs/media-security.md](docs/media-security.md#residual-risks).
+
+### For operators
+- **`HUB_REMOTE_FETCH`** (`on` | `off`): `off` turns off web images and link previews (cards say so). Default `on`,
+  but **off when `HTTP_PROXY`/`HTTPS_PROXY` is set** and `NO_PROXY` is not `*` (a proxy could undo the fetcher's
+  address pinning), with a startup warning; set `NO_PROXY=*` for the hub process or `HUB_REMOTE_FETCH=on` knowingly.
+- **`HUB_FETCH_DENY_CIDRS`**: extra CIDRs the fetcher never connects to, on top of the built-in ranges. In Kubernetes
+  add your pod and service CIDRs (e.g. `10.42.0.0/16,10.43.0.0/16`); an invalid entry stops the hub at start.
+- New routes (README route table): `GET /api/sessions/:id/timeline/messages/:message/media/:ref` (`…/files/:index`
+  is its alias on new spokes), `GET /api/media/remote?url=`, `GET /api/media/unfurl?url=`, `GET`/`PUT
+  /api/settings/media`, `POST /api/sessions/:id/previews`; artifacts gain `origin` (`GET /api/agent/artifacts?origin=preview|all`,
+  previews hidden by default) and `POST /api/agent/artifacts/:id/keep`.
+- The hub now makes outbound HTTP(S) requests for users (when allowed): permit egress to the public internet, or set
+  `HUB_REMOTE_FETCH=off`. Caches and rate limits are in memory per pod in cluster mode.
+- CI and releases run on the org's self-hosted runner (`CI_RUNNER`). The release's Windows smoke test of hubctl runs
+  on a self-hosted Windows runner when the `WINDOWS_RUNNER` variable is set (JSON labels), else GitHub-hosted
+  `windows-latest`.
+
+### For harness authors
+- **Two new optional spoke ops**, announced as features of their own and never implied (also not for OpenCode
+  hellos): `timelineMedia` (one timeline image by ref `f<n>` / `t<part>.<item>` / `p:<base64url path>`, in 512 KiB
+  chunks, `MEDIA_LIMITS`) and `previewBundle` (a local HTML page and its files: a manifest, then chunks,
+  `PREVIEW_BUNDLE_LIMITS`). Timeline rows of a spoke with `timelineMedia` carry `ref`/`bytes`/`width`/`height` on
+  user files and `media` on tool and assistant rows. With HarnessSpoke, a `timelineMedia` or `previewBundle` handler
+  announces it; the conformance suite checks both answers' shapes. Spokes without them get `422 unsupported
+  {feature, harness}` from the hub and file chips in the console. Contract:
+  [docs/spoke-sdk.md](docs/spoke-sdk.md#media-ops-timelinemedia-and-previewbundle).
+- The console's Markdown parser moved to `packages/protocol/src/markdown.ts` (re-exported by the web app), so the
+  hub, the spokes and the console agree on what is an image source, an HTML block or a page link.
+
+### App delivery (for hub apps)
+- **`Idempotency-Key` on `POST /api/agent/msg` and `/ask`**: a retry with the same key and body replays the first
+  answer (200) instead of sending twice; the same key with a different body is `409 conflict`.
+- **`notAfter` delivery deadlines** (epoch ms, at most 30 days ahead; the CLI and MCP also take ISO 8601) on msg/ask,
+  launches and team intake. A deadline already passed is `422 expired` and nothing is stored; a pending message
+  that misses it ends `expired` with reason `not_after`, a queued launch ends with outcome `expired`, a queued
+  intake item is cancelled with `reasonCode: "not_after"`. It is a delivery/start deadline, never a work deadline.
+- **`team.intake` webhooks for apps**: an app holding `teams:submit` gets signed `team.intake` webhooks for the items
+  it submitted.
+- **A machine-checkable contract**: `packages/protocol/schema/app-delivery/v1.schema.json` (JSON Schema, shipped in
+  the npm package) is checked against real route answers, events and webhook bodies in the test suite, so the two
+  cannot drift. A test fixture runs a real hub with simulated machines for app integration tests.
+
+### Voice front (experimental)
+- **A hidden, fast voice agent in front of the session** (Settings → Voice & speech → Voice front). It starts every
+  reply by saying what it understood and what it is doing, then relays to the session (steering a running turn,
+  queueing an unrelated request, or stopping it). The session's agent and model are never switched. Its result,
+  questions, permissions and failures are spoken once; no spoken "On it." phrases (the tones stay). Concierge
+  conversations keep today's path. If the front is unavailable, Voice mode talks to the session directly.
+- The front runs on the machine's voice model (`voiceModel` in `~/.config/hub/config.json`, or the session's voice
+  model). Pick a fast model; free models can hit usage limits.
+- Spoken and pushed failure reasons now hide credentials ("[redacted: api key]"), for workers too.
+
+### Experiments
+- **Smart Turn (experimental) turn detection in Voice mode** (Settings → Voice → Turn detection, per device; the
+  timers stay the default): Pipecat Smart Turn v3.2 (BSD-2-Clause) scores the turn's audio on the device at each
+  pause; a confident "finished" sends at once, otherwise Voice mode waits (re-scoring) up to 3 s. The Voice bar shows
+  the score; the recording mode records it (`turn.predict`, a hub feature an older hub never receives). Tunable with
+  `voiceTurn.*` (URL or localStorage). The model (8.7 MB) loads only when the mode is on.
+
+### Fixes
+- **Hub messages now show in the OpenCode TUI.** A message, ask, reply or prompt the hub delivers to a session used
+  to be invisible in the terminal UI: you only saw the agent react to it. It now shows as a one-line notice where it
+  arrived (`hub · ask from @api: Which release order?`). The agent still sees only the full message. Needs the
+  0.9.0 plugin on the machine.
+
+## 0.8.7
+
+The one-liner now installs OpenCode on Windows when a machine does not have it yet (the reviewed OpenCode 2.2.0 pin for
+windows-x64 is in the signed release manifest). No migration is needed.
+
+### Machine setup
+- **hubctl installs OpenCode on Windows** too: the reviewed pin for OpenCode 2.2.0 `windows-x64`
+  (`opencode-windows-x64-baseline.zip`) is in the signed release manifest, so a Windows machine without OpenCode gets
+  it from the one-liner, like macOS and Linux.
+
 ## 0.8.6
 
 A Windows fix release: OpenCode with the hub plugin no longer flashes a console window every few seconds on Windows,

package/README.md

@@ -61,6 +61,8 @@ Formerly **opencode-voice** and, briefly, **opencode-hub**
 - **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)).
+  Test an app against a real hub with simulated machines: the app fixture
+  ([docs/app-integration-testing.md](docs/app-integration-testing.md)).
 - **More harnesses**: Claude Code (`hub claude`, through its hooks), Codex (`hub codex`, through its app-server)
   and any terminal agent described by a data-only preset (`hub preset run`); the console shows only the controls
   each harness's spoke serves, with an evidence badge and honest delivery labels
@@ -83,6 +85,10 @@ Formerly **opencode-voice** and, briefly, **opencode-hub**
   [intake](docs/teams-intake.md)).
 - **Watchtower** (formerly Bird's-eye view): a 3D, 2D or list picture of machines, sessions, teams and live
   message flow, with a team editor ([docs/watchtower.md](docs/watchtower.md)).
+- **Media in sessions**: tool screenshots, attachments and image files a reply names show in the transcript (with a
+  full-screen viewer), Mermaid diagrams draw, HTML blocks and local pages preview in the isolated host, and web images
+  and link previews load through the hub for sites you allow, without loosening the console's CSP
+  ([docs/session-view.md](docs/session-view.md#media-in-sessions), security: [docs/media-security.md](docs/media-security.md)).
 - **Session details**: context usage, todos, MCP status, branch and per-file diffs, on demand; unread
   marks synced per user.
 - **Self-hostable**: a hub on your computer with nothing extra to install, or your own hub for phones
@@ -390,7 +396,14 @@ conversation mode and utterances (403 `not_exposed` for sessions not shared with
 |---|---|
 | `POST /api/sessions/:id/turn {text, images?}` | sends a turn; while the session tree is running it steers instead (202 `{mode: "steer", inboxID}`). An idle turn answers its `TurnResult` (`{outcome, reply, message?}`) when it ends; with `Prefer: respond-async` (the console sends it) a turn still running after 1.5 s answers 202 `{mode: "turn"}` (`Preference-Applied: respond-async`) and its result follows as an SSE `turn` event `{sessionID, outcome, reply, message?}`, so no proxy cuts a long request. The session stays busy until the turn ends either way. `images` is up to 4 `{mime, data, name?}` (PNG, JPEG, WebP or GIF; canonical base64 whose bytes match the type; each at most 512 KB decoded, together at most 750,000 base64 characters); `text` may be empty when images are attached. They reach OpenCode as inline file attachments. 400 empty, over 100,000 characters or invalid images (with the reason); 409 "A turn is already running for this session" |
 | `GET /api/sessions/:id/timeline?limit=N&order=desc` · `?limit=N&before=<older>` | the conversation as timeline rows, newest first: the latest `limit` rows (1–200, default 50) in chronological order, plus `older` (the cursor of the rows before them) while there are more. `before=<older>` returns the page before that cursor. Cursors are row keys, so they stay valid while new messages arrive. A page starts at a message boundary when it can (it may be up to twice `limit` then). 400 for an unknown cursor (history reverted or compacted: start again from the newest page). The forward mode `?limit=N&cursor=` (oldest rows first, `cursor` for the next page) still works; it cannot be combined with `before` or `order=desc`. The spoke reads OpenCode's history for a first page and serves the following pages from a short-lived per-session cache (30 s, dropped when the session changes) |
-| `GET /api/sessions/:id/timeline/messages/:message/files/:index` | one image attached to a user message, as bytes with its type (`cache-control: private, no-store`). Timeline user items list their attachments as `files: [{index, mime, name?}]` (never the bytes). Every timeline row carries `pos` (ordering position: session message order, then part order; derived from the message's creation time, kept increasing, so it does not change as pages move); tool rows `callID`, subagent tool rows `childSessionID` and `title` (the task description), assistant text rows `ordinal`. Only PNG, JPEG, WebP and GIF are served (404 otherwise or when missing); 413 when the image would not fit in a protocol frame (about 650 KB) |
+| `GET /api/sessions/:id/timeline/messages/:message/files/:index` | one image attached to a user message, as bytes with its type (`cache-control: private, no-store`). On a spoke that announces `timelineMedia` it is an alias of `…/media/f<index>` below (its headers, cache and limits). Timeline user items list their attachments as `files: [{index, mime, name?}]` (never the bytes). Every timeline row carries `pos` (ordering position: session message order, then part order; derived from the message's creation time, kept increasing, so it does not change as pages move); tool rows `callID`, subagent tool rows `childSessionID` and `title` (the task description), assistant text rows `ordinal`. Only PNG, JPEG, WebP and GIF are served (404 otherwise or when missing); 413 when the image would not fit in a protocol frame (about 650 KB) |
+| `GET /api/sessions/:id/timeline/messages/:message/media/:ref` | (feature `timelineMedia`) one timeline image by ref: `f<n>` (a user attachment), `t<part>.<item>` (a tool content item), `p:<base64url path>` (an image path in an assistant message, served under the spoke's path policy). Pulled from the spoke in 512 KiB chunks and collected whole (≤ 8 MiB, 60 s in all) before anything is answered; the hub re-sniffs the magic bytes (PNG, JPEG, WebP, GIF, SVG) and verifies the length and SHA-256 (a mismatch is 502 `integrity`, never a partial body or a 304). Headers: `ETag: "sha256-<hex>"`, `cache-control: private, no-cache`, `nosniff`, `content-security-policy: default-src 'none'; sandbox`, CORP same-origin, `referrer-policy: no-referrer`, `content-disposition` inline (SVG always `attachment`; `?download=1` for any type). Cached per user on the pod (64 MiB): `f`/`t` images answer `If-None-Match` with 304 without contacting the spoke; `p:` refs are revalidated with one first-chunk call; entries live at most 10 min and are dropped when the session's committed revert (as its spoke reports it, seen from any pod) differs from when they were cached; a staged revert bypasses the cache, a deleted session clears it. The message ID may not contain `/` or `..`. 400 bad ref, 404 `not_found`/`path`/`hidden`, 409 offline, 413 `too_large {bytes,max}`/`dimensions`, 415 `type`, 422 `unsupported {feature, harness}`, 429 `rate_limited` (4 in flight per user, 2 per spoke connection; `Retry-After`), 502 `integrity`, 504 `timeout` |
+| `GET /api/media/remote?url=` | (signed-in users only: session and app tokens get 403) a web image through the hub's safe fetcher ([docs/media-security.md](docs/media-security.md#what-each-layer-does)): http/https on default ports, no userinfo, private and reserved addresses refused (plus `HUB_FETCH_DENY_CIDRS`), the checked address pinned, at most 3 redirects each re-checked, no cookies, 3 s to headers and 8 s in all, never decompressed. Only PNG, JPEG, WebP or GIF by magic bytes (never SVG), ≤ 8 MiB, ≤ 40 MP, ≤ 16,384 px per side, with the media headers of the timeline route and an `ETag` (304 on `If-None-Match`). Cached per user for the site's lifetime clamped to 1–24 h, failures for 5 min. 400 `bad_url`, 403 `refused`/`disabled` (`HUB_REMOTE_FETCH=off`), 413 `too_large`, 415 `not_image`, 429 `rate_limited` (30 fetches a minute and 4 at once per user, shared with `GET /api/media/unfurl`; `Retry-After`), 502 `upstream`, 504 `timeout`. Audited as `media.remote` with the host and outcome, never the URL |
+| `GET /api/settings/media` | (signed-in users only: session and app tokens get 403) `{allowlist: string[], remoteFetch: boolean}`: the caller's media allowlist (hostnames like `github.com` or suffixes like `*.githubusercontent.com`, stored lowercase without a trailing dot, IDNs as punycode; empty by default) and whether this hub fetches web images (`HUB_REMOTE_FETCH`). In a session reply (and the Concierge panel) a web image from an allowlisted site loads at once through `GET /api/media/remote`; any other site's is a card naming the domain with **Load image**, **Always allow <domain>** and "Load all from this domain in this session" (that last one is kept in the page only), and nothing is fetched until a tap. The hub's own origin is never sent to the remote route |
+| `PUT /api/settings/media {allowlist}` | replaces the list, answers like GET. 400 (naming the entry) for more than 100 entries, entries over 253 characters, IP addresses, ports, schemes, paths, userinfo, a bare `*`, a wildcard anywhere but a leading `*.`, and public suffixes alone (`*.com`, `*.co.uk`, `*.github.io`, `co.uk`; a small built-in list). A `*.` entry matches subdomains only. Settings → Media edits it and warns that an allowed site hosting other people's content can still receive data an agent puts in an image URL |
+| `GET /api/media/unfurl?url=` | (signed-in users only: session and app tokens get 403) a link's preview through the hub's safe fetcher: `{url, title?, description?, siteName?, image?}` (`url` is the final URL after redirects; plain text, entities decoded, title ≤ 200, description ≤ 300, site name ≤ 100 characters; `image` resolved against the final URL, http/https on the default port without userinfo, else left out). Reads at most the first 512 KiB; only a 2xx `text/html` or `application/xhtml+xml` answer counts (else `415 not_html`). `cache-control: private, max-age` ≤ 1 h; the hub caches previews per user for the site's lifetime clamped to 1–24 h and failures for 5 min. Shares the per-user budget of `GET /api/media/remote` (30 fetches a minute and 4 at once for both together, `429` with `Retry-After`); `403 disabled` with `HUB_REMOTE_FETCH=off`; the audit log keeps the host and outcome, never the URL. In a session reply (and the Concierge panel) a link to an allowlisted site gets a preview card under its paragraph (at most 3 per message, never for links in code or same-origin links; the card's image loads through `GET /api/media/remote` only when the image's host is allowlisted too); any other link gets a small preview button that fetches only on a tap |
+| `POST /api/sessions/:id/previews {messageID, block}` · `{messageID, path}` | (console only) an HTML preview of the message's `block`-th (0-based) ```` ```html ````/```` ```htm ```` block, or of a local `.html`/`.htm` page the message names with the files it refers to (spoke feature `previewBundle`, read under the media path policy; ≤ 200 files, 5 MiB each, 20 MiB in all). The hub reads the content from the message, never from the request, and stores it as a private `html` artifact with `origin: "preview"`: `{artifact, revision, reused, host}` (+ `skipped`, `skippedMore` for a page), 201 stored, 200 unchanged (`reused`); `POST host` opens it in the isolated artifact host. 400, 404 `not_found`/`too_old`/`refused`, 409 offline/`changed`, 413 `too_large`, 422 `unsupported` (no artifacts, or a spoke without `previewBundle`), 502 `bad_bundle`. Previews are archived 24 h after their last view and purged 7 days later. Contract: [docs/artifacts.md](docs/artifacts.md#html-previews) |
+| `GET /api/agent/artifacts?origin=preview\|all` · `POST /api/agent/artifacts/:id/keep {expectedRevision}` | the library leaves previews out unless `origin` asks for them (`preview`: only previews, `all`: both); **Keep** turns a preview into a normal artifact (`409` on a stale `expectedRevision`; no change for other artifacts). Users and apps with `artifacts:write`, never sessions. See [docs/artifacts.md](docs/artifacts.md#http-api-apiagent) |
 | `POST /api/sessions/:id/rename` `{auto: true}` | Auto-name: OpenCode regenerates the title with its Title agent (`session.update` with an empty title on the process's own server). 200 `{title}` (or `{title, unchanged: true}` when OpenCode kept it), 202 `{pending: true}` when it is still generating after 20 s (the catalog updates when it lands), 409 `plugin_outdated` when no process reporting the session supports it, 502 when the process cannot reach its server or the title model failed |
 | `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) |
@@ -509,8 +522,8 @@ cookie and a hub bearer token (400).
 | `GET /api/agent/who?project=&role=` | ✓ | ✓ | ✓ | named, role-holding and online sessions |
 | `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/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 |
 | `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 |
@@ -524,6 +537,15 @@ whether the hub sent it to wake the recipient, and when not, `wakeSkipped` says
 `hop_cap`, `budget`; see **Limits**). The CLI and MCP tools print it, e.g. `queued (read at its next turn) — wake
 skipped: hop limit reached`. Hubs before 0.8.1 send neither field.
 
+`msg` and `ask` (also to `@me`, also with `all`) accept an `Idempotency-Key` header (1–200 of `A-Z a-z 0-9 _ . : -`),
+so a client that retries after a timeout never delivers, pushes or opens a Decision twice. Keys are per sender (the
+user, each app token, each session). The same key and body within 24 h answer `200` with the original body
+(`{message, delivery?, …}`, `{sent: [...]}`, or `{message, decision, …}`) and `idempotent-replayed: true`, sending
+nothing; another body under the key is `409 conflict`, and so is a repeat while the first is still running. A
+malformed key is `400 invalid`. The keys are kept in the hub's state store, so a replay works across restarts.
+SDK: `hub.msg(to, text, {idempotencyKey})`, `hub.ask(…, {idempotencyKey})`; CLI: `hub msg|ask … --key K`; MCP:
+the `idempotencyKey` argument of `msg` and `ask`.
+
 The act verbs, grants, kill switches and the agent audit are in [Agent actions and grants](#agent-actions-and-grants).
 
 **Decisions and `@me`.** `@me` addresses the user: `msg @me` is stored in the user's inbox (push kind `message`);
@@ -573,6 +595,14 @@ you. Addresses resolve among your own sessions only; another user's sessions do
 `--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).
 
+**Not after.** `msg` and `ask` take `notAfter`: never deliver the message after that time. REST and the SDK take
+epoch milliseconds; the CLI (`--not-after`) and `hub mcp` (`notAfter`) also take an ISO 8601 date-time such as
+`2027-01-15T12:00:00Z`. It must lie in the future and at most 30 days ahead (else `invalid`, exit 2); one that has
+already passed answers `422 expired` (exit 8) and nothing is stored, delivered or pushed. A message pending for an
+offline or busy session expires at the earlier of its 24 h hold and `notAfter` (its sender is told as below, and the
+`message.changed` event says why: `reason` `not_after` or `pending_timeout`); an ask expires at the earlier of its
+`expiresIn` and `notAfter`. Messages to `@me` are stored at once, so for them `notAfter` is only checked when sent.
+
 **Delivery.** A message reaches an OpenCode session as a hub message in its conversation (the spoke's `deliver`,
 OpenCode's synthetic message; it shows in the console's conversation as a message row). An idle session gets a
 turn; a busy one gets a plain `msg` after its running turn and an `ask` steered into it. A `--no-wake` message never
@@ -840,8 +870,8 @@ hub name <@name> [--session <addr>]
 hub intent <addr> [text… | --clear]       what the session is for (one line, ≤ 280 characters)
 hub role claim <role[.project]> [--exclusive] [--session <addr>]
 hub role release <role[.project]> [--session <addr>]
-hub msg <addr> "text" [--all] [--no-wake] [--urgent]     tell: fire and forget
-hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--all] [--no-wake] [--urgent]
+hub msg <addr> "text" [--all] [--no-wake] [--urgent] [--key K]     tell: fire and forget
+hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--all] [--no-wake] [--urgent] [--key K]
 hub reply <msgID> "text" [--no-wake]      to the message's real sender, never via the role
 hub decline <msgID> --why "reason"
 hub ask @me "question" [--option id=label[:safe]]... [--recommend id [--why "…"]] [--urgency low|normal|high]
@@ -888,7 +918,8 @@ message, any candidates or retry time, a missing feature, and the hint on stderr
 the running turn, `queued` for its next turn, `retained` while it has a question open, `pending` while offline (or,
 for a `--no-wake` message, while the recipient's turn runs), or
 `stored` in a user's or app's inbox); `--all` sends to every session the address names (each holder of a role),
-`--no-wake` admits without starting a turn, `--urgent` steers into a running turn. A text (or `--why`) of `-` is
+`--no-wake` admits without starting a turn, `--urgent` steers into a running turn, `--key K` sends an
+`Idempotency-Key` (a retry with the same key and text answers the first send again and sends nothing). A text (or `--why`) of `-` is
 read from stdin, so long or quoted bodies need no escaping: `git diff | hub msg @reviewer -`. `--expires` and
 `--wait` take seconds or `30s`, `5m`, `2h`, `1d` (asks expire after 1 minute to 7 days, default 24 h). `ask --wait N`
 waits up to N seconds for the answer (the CLI loops on the hub's 60 s long poll); a bare `--wait` waits until the
@@ -925,8 +956,10 @@ repository on the node and must be under that node's workspace roots. `--label k
 (`hub launches list --label brain.task=abc` finds it again); `--node-label k=v` and `--machine` pick nodes, required
 unless `--prefer`. `--prompt -` reads the first prompt from stdin. `--key` makes retries safe: the same key and
 flags answer the existing launch (`… was already launched with key …`), the same key with other flags is invalid
-(exit 2). It prints the launch and its state (`queued`, `placing`, `provisioning`, `running` with the session,
-`ended` with an outcome: `idle`, `needs_user`, `failed`, `timeout`, `stopped`, `lost`); `hub launches show` adds the
+(exit 2). `--not-after <ms|ISO time>` sets a deadline: a launch still waiting for a machine then is never started
+and ends `expired` (already passed: nothing is launched, exit 8). It prints the launch and its state (`queued`,
+`placing`, `provisioning`, `running` with the session, `ended` with an outcome: `idle`, `needs_user`, `failed`,
+`timeout`, `stopped`, `lost`, `expired`); `hub launches show` adds the
 workspace, steps and artifacts (branch, head, commits). `hub launches stop` ends a launch (`stopped`); one that
 already ended exits 8 (`gone`). The user may always launch; an app token needs scope `sessions:launch` **and** a
 grant with verb `launch` covering the repo (exit 5 otherwise; the kill switch pauses it); sessions launch only
@@ -989,7 +1022,7 @@ is set and the credential is not that session. The CLI removes `BUN_BE_BUN` from
 | 5 | `forbidden`, `paused` |
 | 6 | `rate_limited` (with `retryAfter`) |
 | 7 | `unsupported`, `offline`, `busy` |
-| 8 | `gone`; an `ask --wait` that expired |
+| 8 | `gone`, `expired` (a `--not-after` already passed); an `ask --wait` that expired |
 | 9 | `unauthorized`, `token_expired` (a session token: start a new shell), or not logged in |
 
 ### hub mcp (MCP server)
@@ -1015,7 +1048,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`; `ask @me` reports the
+most 60 s (one long poll; a longer wait is cut to 60) and `expires` in seconds or as `2h`; `msg` and `ask` take
+`notAfter` as epoch milliseconds or an ISO 8601 date-time; `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),
@@ -1256,6 +1290,8 @@ holds the startup (`bin/hub.ts` serves `web/` from disk; the compiled binaries e
 | `HUB_VAPID_SUBJECT` | the https public URL, else `mailto:hub@localhost` | contact sent to push services |
 | `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_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) |
 | `HUB_STT_MODEL`, `HUB_TTS_MODEL`, `HUB_VOICE`, `HUB_MAX_*` | see `src/central/config.ts` | speech defaults; the phone's speech settings override them |
 
@@ -1277,11 +1313,14 @@ Nothing inline and no `eval`: scripts and styles come only from the built bundle
 that runs before the first paint is `/theme-boot.js` (not an inline script), components use classes or style
 properties (never a `style="…"` attribute in markup), and the stylesheets 3d-force-graph would inject for the
 Watchtower are stripped at build time and shipped as `web/src/app/watchtower/force-graph.css`. `data:`/`blob:`
-images are attachments and pasted images, `blob:` media is Voice playback. `connect-src 'self'` covers the API, the
+images are attachments, pasted images and session media (screenshots, local images, artifact images and web images
+the hub fetched, as `blob:` URLs of checked raster bytes; SVG and Mermaid diagrams only as `data:` URLs in an
+`<img>`, never DOM; [docs/media-security.md](docs/media-security.md)), `blob:` media is Voice playback. Mermaid draws
+in a same-origin worker (`worker-src 'self'`). `connect-src 'self'` covers the API, the
 SSE stream and same-origin WebSockets. The only frames are the isolated artifact host's (`/artifact-host/v1/…`, same
 origin), which keeps its own sandboxing policy ([docs/artifact-host.md](docs/artifact-host.md)); nothing may frame the
 console. Sign-in (OIDC) is a navigation, not a form post, so `form-action 'self'` does not affect it. The Silero VAD
-worker compiles its WebAssembly inside the worker, so no `'wasm-unsafe-eval'` is needed.
+and Smart Turn workers compile their WebAssembly inside the worker, so no `'wasm-unsafe-eval'` is needed.
 
 API responses carry no console policy (JSON is never rendered as a page; downloads, the sign-in result pages and the
 artifact host send their own). If a deployment hits a violation (the browser console says `Refused to …`), set
@@ -1770,6 +1809,24 @@ it again, say "pause listening", or leave the page to turn it off. Leaving the p
   it ends in `. ? !`, or has 3+ words and doesn't end in "and", "but", "so", "um", "the" and the like.
   Otherwise it waits up to 0.8 s. If you speak again during the wait, the next segment's transcript
   is joined to it. Empty and filler-only transcripts are dropped. Utterances are capped at 60 s.
+- **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
+  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'
+  `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
+  unchanged. A model that cannot load, or a score slower than the slow cap, leaves that turn to the timers (one
+  console warning). The slow cap is 1.5 s, or twice the median of the recent score times when the device is slower,
+  at most 5 s; the model runs once on silence right after it loads, so the first turn is not the slow one. The Voice bar shows the latest score ("turn 6%", "turn 91% → sending"), or why there is none ("turn: model
+  loading", "turn: timers (slow)"). A turn buffer without speech (silence scores about 0.99 "complete") is never
+  scored. Tuning per device: Settings →
+  Voice → Advanced (threshold, grace, fallback, slow cap; clamped to their ranges, each with the value in use), or `voiceTurn.threshold`, `voiceTurn.grace`, `voiceTurn.recheck`,
+  `voiceTurn.fallback`, `voiceTurn.slow` as URL query parameters (one visit) or localStorage keys. The recording
+  mode records each score as `turn.predict` ([docs/voice-recording.md](docs/voice-recording.md)).
 - **Commands**: an utterance that is only "stop", "cancel", "never mind", "stop that" or "hold on"
   calls `POST …/interrupt` and stops speech. "Pause listening" turns the mode off.
 - **Speech out**: root replies arrive one sentence at a time while they are written (`say` with `seq`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "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",
@@ -47,6 +47,7 @@
     "src",
     "packages/protocol/src",
     "packages/protocol/package.json",
+    "packages/protocol/schema",
     "packages/sdk/src",
     "packages/sdk/package.json",
     "packages/cli/src",
@@ -70,6 +71,7 @@
     "packages/codex/package.json",
     "bin",
     "web/dist",
+    "web/src/voice/turn/LICENSE",
     "docker",
     "Dockerfile",
     "scripts/hub-local.sh",
@@ -124,7 +126,9 @@
     "@types/three": "0.186.0",
     "@types/web-push": "^3.6.4",
     "3d-force-graph": "1.80.1",
+    "ajv": "^8.20.0",
     "onnxruntime-web": "1.23.2",
+    "pele": "1.13.0",
     "playwright-core": "^1.64.1",
     "solid-js": "^1.9.17",
     "typescript": "^5.9.3",

package/packages/claude-code/package.json

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