* feat(cli): spawn-peer with required remit and MCP spawn_peer Machine spawn creates an empty composer; stuffing message into that JSON is stripped. Add hapi spawn-peer and MCP spawn_peer that spawn, rename, deliver via the ping-peer path, and fail closed unless the remit is on the new session. Reject message/prompt/text on machine spawn with 400. Do not auto-approve spawn_peer in default/read-only. Fixes #1509 Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): reject overlong spawn-peer names before spawn Hub rename max is 255; continuing past PATCH 400 left a live session under a different title. MCP/steer copy now says the hub 400s a spawn-body remit instead of stripping it. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): wait for fresh spawn-peer child instead of resuming it Machine spawn can return while the hub row is still inactive. ping-peer then POSTed /resume, which can launch a second agent because the original spawn has no existingSessionId for runner dedupe. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): reject flavor-illegal permissionMode before spawn-peer Codex + bypassPermissions (and Pi + any mode) used to reach the runner and fail after a child existed, or silently drop the mode. Check isPermissionModeAllowedForFlavor when both agent and mode are explicit. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): treat omitted spawn-peer agent as Claude for permissionMode Hub and runner default agent to claude when spawn omits it. Validate permissionMode against that effective flavor so yolo/read-only fail closed before a child starts. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): resolve spawn-peer dir locally and archive failed children Relative --dir values were forwarded unchanged, so the runner resolved them against daemon cwd. Remit delivery failures also left the new session running, so a retry spawned a duplicate. Resolve in the caller and best-effort archive the child before rethrowing. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): verify remit before archiving a failed spawn-peer child A timed-out ping-peer POST can still land the remit. Check the transcript before archive, and only say the child was archived when the hub returns ok. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): swallow spawn-peer transcript GET errors and skip unapplied names A thrown messages GET after spawn skipped archive and leaked a live child. Treat transport errors as a miss so the verify loop can retry, then clean up. Also do not return a requested name the hub never applied. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(spawn-peer): hub peerSpawnDefaults + model/effort spawn surface Add hub settings peerSpawnDefaults (agent, permissionMode, per-flavor models) with stock claude/yolo/sonnet fallbacks. spawnPeer resolves explicit args → hub settings → stock, maps yolo to flavor equivalents, and forwards model/effort into machine spawn. Settings UI under General → Agents; MCP/CLI optional overrides. Co-authored-by: Cursor <cursoragent@cursor.com> * test(hub): use cursor-valid permission mode in peer spawn defaults test Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): teach spawn_peer that omit permissionMode means yolo MCP copy said "pass permissionMode only when the operator asked", so agents omitted it and got hub/stock whatever was stored — often approval-gated default. Clarify omit = yolo via peerSpawnDefaults/stock; pass only to tighten. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(hub,web): apply peerSpawnDefaults to machine spawn and New Session POST /api/machines/:id/spawn now resolves omitted agent/permissionMode/model from hub Settings, and New Session seeds from the same peerSpawnDefaults so UI create and peer spawn share one authoritative default (stock yolo). Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): NewSession hub seed respects sticky prefs + QueryClient in tests Sticky localStorage last-used agent wins over hub seed; machine spawn still applies peerSpawnDefaults server-side. Tests provide QueryClientProvider. Co-authored-by: Cursor <cursoragent@cursor.com> * test(web): mock CREATABLE_AGENT_FLAVORS for settings general peerSpawn UI Co-authored-by: Cursor <cursoragent@cursor.com> * test(web): stabilize NewSession tests after hub peerSpawnDefaults seed Wrap remaining mounts in QueryClientProvider, pre-seed hub settings so a late useQuery resolve cannot wipe in-test model picks, and use neutral stock permission defaults in the fixture. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(spawn-peer): address tip Codex Majors for peerSpawnDefaults Preserve explicit yolo booleans on machine spawn, fail closed when hub defaults cannot load, validate permission modes against the resolved agent, remap auto-approval across flavors, and stop late hub settings from wiping New Session edits. Reject retired agents in spawn defaults and restore the CLI executable build docs. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(spawn-peer): address follow-up tip Codex Majors Stop absent Yolo localStorage from beating hub defaults, track New Session edits before late hub seed, reject incompatible machine-spawn permissions, resolve MCP spawn_peer paths against the session working directory, and hide unsupported Codex safe-yolo from Settings spawn defaults. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(spawn-peer): clear tip-2 CI and follow-up Codex Majors Omit permissionMode for Pi/DSH, preserve explicit Yolo-off across delayed hub seed, fix settings test mocks for launch permission helpers, and restore unrelated CLI README lifecycle/ACP docs. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(spawn-peer): tip-3 Majors for seed edits and launchable modes Skip hub agent seed after permission edits, resolve inherited modes via the launch catalog (AGY request-review fallback), preserve hub Cursor models through preference restore, and restore Codex auth README nuance. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): tip Minors for Cursor/Grok hub permission seeding Give Cursor the native permission select so Plan/Ask survive machine spawn, and re-apply Grok hub permissions after agent-init resets. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(spawn-peer): tip Minors for Cursor select and hub seed remap Map hub permission through resolvePermissionModeForFlavor, keep native Default when agent is explicit without a model, and assert Cursor Plan/Ask Mode labels. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): tip Minors for delayed hub seed and Default model Apply hub permission/model to unset fields even with a sticky agent, preserve explicitly saved auto models, and seed OpenCode/AGY selectors from hub defaults. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(spawn-peer): tip Minors for model edit sticky and clear override Mark OpenCode/AGY model picks as edited so delayed hub seed cannot overwrite them, and treat empty hub model values as clear sentinels. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(spawn-peer): tip Majors for models patch typing and remit page scan Type the models patch as NonNullable and paginate transcript verification oldest-ward so a busy child is not archived when the remit leaves page 1. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): tip Minor — keep agent after explicit model pick Do not apply a late hub default agent when the operator already chose a model; otherwise preference restore drops that selection. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(spawn-peer): tip Cursor YOLO migrate and Codex effort map Bridge Cursor's saved YOLO toggle (incl. false) into native Default over hub yolo, and send Codex/OpenCode --effort as modelReasoningEffort. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): tip Majors — scoped YOLO bridge and catalog fallback Keep unsupported saved permission modes at Default instead of hub yolo, and apply delayed YOLO migration only when the sticky bridge agent matches. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): drop rebase conflict markers in startHappyServer Both sessionDisplayRename and spawnPeer imports are required after rebasing onto upstream rename work; markers had slipped into tip. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): wrap Kimi NewSession tests in QueryClientProvider Hub settings useQuery requires a provider; upstream Kimi catalog tests rendered bare and broke after the spawn-peer rebase onto main. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(peer): rename-proof Parent UUID stamp on spawn remits Orchestrated spawn_peer / spawn-peer remits now auto-stamp a durable [title](/sessions/<uuid>) Parent chip (fail-closed in-session). MCP copy forbids inventing titles; UUID stays identity after parent rename. Refs heavygee/hapi#175 Co-authored-by: Cursor <cursoragent@cursor.com> * style(peer): plain hyphen in Parent-stamp warning and test comment Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): reject blank remit before Parent stamp Codex review on #1922: stamping first turned empty remits non-empty and bypassed the idle-session guard. Also only treat ## Parent blocks as already-present so bare /sessions citations still get the chip. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): gate New Session Create on hub defaults; require Parent chip Codex tip review on #1922: block Create while getHubSettings is pending so stock mount defaults cannot bypass restrictive hub peerSpawnDefaults; skip Parent stamp only when ## Parent already has a markdown session chip; clarify codex resume takes a native thread id. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): resolve MCP spawn cwd; Agents settings section Codex Major on #1922: spawn_peer relative directories now prefer the launcher cwd (Codex --cd), then skillLookup, then session metadata.path. Move peerSpawnDefaults UI into the unused Agents settings section. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): pass session cwd to MCP spawn_peer; Agents settings section Codex tip review on #1922: resolve relative spawn_peer directories from the launcher working directory (Codex --cd), skillLookup, then metadata.path; move peerSpawnDefaults UI into the Agents settings section. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): skip archive on unread transcript; validate startingMode after hub agent Codex tip review: do not archive a child when remit verification cannot read the transcript; run AGY/DSH remote-only startingMode checks against the resolved hub agent; update MCP bridge test expectations for workingDirectory. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): treat exhausted remit pagination as unverifiable Hitting the messages page cap with hasMore still true must not count as an observed-empty transcript — that would archive a child whose remit may still exist on older pages. Co-authored-by: Cursor <cursoragent@cursor.com> * docs(cli): list HAPI_API_URL as optional with localhost default Codex tip review: the README had moved HAPI_API_URL under Required even though configuration defaults it to http://localhost:3006 (and settings can supply a URL). Also drop trailing whitespace flagged by git diff --check. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): re-verify empty transcript before archiving failed spawn An earlier observed-absent page plus later unread GETs must not archive a child whose remit may have landed after the first empty read. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): never auto-archive on spawnPeer failure path Timed-out remit POSTs and empty-read/archive TOCTOU races can still land work on the child. Leave the session running with its id for inspection instead of terminating an in-flight peer. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): classify empty_session from final remit verify An earlier empty transcript read must not stick as empty_session once later message GETs become unavailable — report verify_failed instead. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): recognize escaped brackets in Parent chip labels Titles with ] were escaped in the chip label but the idempotency regex stopped at the first raw bracket and re-stamped a second Parent block. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): avoid Parent chip regex backtracking on backslashes Exclude \\ from the single-char label alternative so escaped pairs have one parse path — long nonmatching backslash runs no longer explode. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(cli): MCP/CLI spawn_peer --machine for cross-host remits Wire optional machine (UUID or hostname via GET /api/machines) through MCP spawn_peer and hapi spawn-peer into existing spawnPeer({ machineId }). Skip local directory existence checks for cross-host targets to match the estate wrapper; keep fail-closed remit verify. Fixes tiann/hapi#1931 Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): reject ambiguous spawn --machine label matches Tip bot Major on #1922: hostname/displayName selectors that match more than one online runner now fail closed with ambiguous + UUID guidance. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): preserve cross-OS absolute dirs for spawn --machine path.resolve on the caller OS was rewriting foreign absolute roots (C:\… on Linux, /srv/… on Windows) before the hub spawn POST. Detect POSIX or Windows absolute paths and only resolve relative directories. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(peer): resolve spawn dirs after local vs remote is known Defer directory resolution until the target machine is selected. Remote spawns still preserve foreign absolute roots; local spawns use native path.resolve so Windows drive-less paths like \repo bind to the caller drive. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): apply delayed DSH model defaults without replacing edits * fix(web): preserve hub permission defaults across form remounts --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: weishu <twsxtd@gmail.com>
hapi-web
React Mini App / PWA for monitoring and controlling hapi sessions.
What it does
- Session list with status, pending approvals, todos, and summaries.
- Chat view with streaming updates and message sending.
- Permission approval and denial workflows.
- Codex
request_user_inputchoices honorisOther: None of the above focuses optional notes, supports empty notes, and preserves the canonical wire value across languages. Recorded other answers and notes remain visible in live and historical cards; Pi/MCP forms without the flag are unchanged. - Permission mode and model selection.
- Machine list and remote session spawn.
- File browser and git status/diff views.
- PWA install prompt and offline banner.
- Optional unread-session count on the Windows taskbar when installed as an Edge/Chrome PWA (toggleable in Display settings; off by default).
Runtime behavior
- When opened inside Telegram, auth uses Telegram WebApp init data.
- When opened in a normal browser, you can log in with
CLI_API_TOKEN:<namespace>(orCLI_API_TOKENfor the default namespace). - The login screen includes a top-right hub picker; if unset, the app uses the same origin it was loaded from.
- Live updates come from the hub via SSE.
- Session
@suggestions require conversation content, including untitled conversations. Names and directory labels affect display/search, not eligibility; empty stubs stay excluded. See the session list behavior guide for search and picker rules.
Routes
See src/router.tsx for route definitions.
/- Redirect to /sessions./sessions- Session list./sessions/$sessionId- Chat interface./sessions/new- Create new session./sessions/$sessionId/files- File browser with git status./sessions/$sessionId/file- File viewer with diff support./sessions/$sessionId/terminal- Terminal interface./browse- Workspace browser, enabled by the runner's configured workspace roots./share- Share-target landing (Web Share Target POST →?id=, or native/share#url=&text=&title=)./settings- Settings category hub (mobile) and responsive master-detail shell./settings/general- Language preferences./settings/display- Appearance, typography, colors, and session list preferences./settings/chat- Message input, tool card, and conversation color preferences./settings/voice- Everyday voice assistant preferences./settings/voice/voices- Full-page voice picker./settings/voice/advanced- Voice persona, tuning, and diagnostics./settings/machines- Machine management and runner status./settings/storage- SQLite storage sizes for the hub owner./settings/usage- Cache-aware token usage dashboard for the hub owner./settings/about- Application links and version information.
Features
Session list (src/components/SessionList.tsx)
- Active/inactive status indicator.
- Session title from name, summary, or path.
- Todo progress display.
- Pending permission request count.
- Agent name and model display.
- Metadata search with relevance ranking, wildcard matching, and date/unread/machine filters.
- Stable user-input ordering across sessions and machine/project groups; agent output and status updates do not reorder ordinary rows.
- Machine/project grouping, pinned and in-progress sections, and configurable collapsed previews.
Session title lock
The rename dialog has a per-session lock beside the title input. New and existing sessions are unlocked by default. Saving a manual name does not automatically lock it: agents may still rename an unlocked session. Locking prevents agent title updates; users can still edit or generate a title and save it while locked. Save applies the title and lock together; Cancel discards both changes. Unlocking allows future agent title updates without immediately changing the current title. The Hub persists and enforces the lock across clients, restarts, and resume.
Chat interface (src/components/SessionChat.tsx)
- Message thread with infinite scroll.
- Composer for sending messages.
- Permission mode and model selection for supported agents.
Cursor Auto uses CLI Auto for new/resumed sessions configured with Auto. Switching a live session to Auto when ACP does not advertise a literal Auto option relaunches the Cursor ACP process in place under
--model autowhile preserving the hub session id. - Session abort and handoff controls.
- Codex Continue planning hides the current proposal's action menu locally and focuses the composer without sending a message or replacing its draft. The plan document remains readable; recycled cards stay dismissed and new proposals get fresh action menus.
- Context size display.
- Per-session scratchlist (
src/components/AssistantChat/ScratchlistPanel.tsx)- Workbench panel for held notes/drafts; distinct from the queue.
- Add/delete/reorder entries; promote to composer (copy) or queue (send).
- Entries and attachments saved on the hub and synced across devices.
- Reordering affects only the current view and resets when entries refresh.
- Keyboard shortcut: Ctrl/Cmd+Shift+S to focus the add-input.
File browser (src/routes/sessions/files.tsx)
- Git status view (staged/unstaged files).
- File search with ripgrep.
- Navigate to file viewer.
File viewer (src/routes/sessions/file.tsx)
- File content display with syntax highlighting.
- Staged/unstaged diff view.
Terminal (src/routes/sessions/terminal.tsx)
- Remote terminal via xterm.js
- Real-time via Socket.IO
/terminal - Resize handling
Voice assistant
- ElevenLabs (@elevenlabs/react), Gemini Live, and Qwen Realtime backends
- Real-time voice control
- Standard and realtime composer dictation with provider capability selection
New session (src/components/NewSession/)
Modular session creation:
- Machine selector
- Directory input with recent paths. The path tail is revealed after loading or selecting a path and after leaving the editor. Unfocused inputs support horizontal touch scrolling; focused inputs retain native editing and text selection.
- Agent type selector
- Model selector
- Per-agent permission, effort, and collaboration controls when supported
First-User-Experience (FUE)
For a new, non-essential feature whose affordance would otherwise be hard to discover, consider the existing FUE primitive rather than a permanent UI block. Optional, not a requirement for every feature or a reason to expand a bug fix.
src/lib/use-fue.ts:useFue(featureId)returns{ status, engage, dismiss }; acknowledgement is isolated per feature inhapi.fue.v1.<featureId>localStorage keys.src/components/Fue.tsx:FueDotmarks the affordance;FueCalloutexplains it whilestatus === 'engaging'.- Dismissal requires an affirmative user action ("Got it"), never an auto-timeout.
- The FUE dot and feature-specific badges/counters are mutually exclusive; onboarding wins until acknowledged.
- Opt in per feature; skip the wrapper if an upstream component already supplies onboarding.
- Working example:
ScratchlistToggleButtoninsrc/components/AssistantChat/ComposerButtons.tsx. Use the source rather than maintaining a copied example here.
Authentication
See src/hooks/useAuth.ts and src/hooks/useAuthSource.ts.
- Telegram Mini App: Uses initData from WebApp SDK.
- Browser: Uses CLI_API_TOKEN from login prompt.
- JWT tokens with auto-refresh.
Data fetching
See src/hooks/queries/ for query hooks and src/hooks/mutations/ for mutations.
- Sessions, messages, machines via TanStack Query.
- Git status and file operations.
- Optimistic updates for message sending.
Real-time updates
See src/hooks/useSSE.ts.
- SSE connection to
/api/events. - Session/message/machine update events.
- Automatic cache invalidation on events.
Stack
React 19 + Vite + TanStack Router/Query + Tailwind + @assistant-ui/react + xterm.js + @elevenlabs/react + socket.io-client + workbox + shiki.
Source structure
src/router.tsx- Route definitions.src/components/- UI components.src/hooks/- Data fetching and state hooks.src/api/client.ts- API client.src/types/api.ts- Type definitions.
Development
From the repo root:
bun install
bun run dev:web
If testing in Telegram, set:
HAPI_PUBLIC_URLto the public HTTPS URL of the dev server.CORS_ORIGINSto include the dev server origin.
Tests
Unit tests run under vitest + jsdom:
bun run test:web
End-to-end browser tests for the scratchlist component (real Chromium, real
inert focus blocking, real localStorage round-trips) live at the repo root
under e2e/:
bun run test:e2e # headless
bun run test:e2e:ui # Playwright UI mode (debug)
The spec drives a Vite-served fixture page (web/e2e-fixtures/scratchlist-fixture.html)
that mounts the production ScratchlistPanel in isolation, so no hub /
auth / socket setup is required.
Build
bun run build:web
The built assets land in web/dist and are served by hapi-hub. The single executable can embed these assets.
Standalone hosting
You can host web/dist on a static host (GitHub Pages, Cloudflare Pages) and point it at any hapi hub:
- Build the web app. If your static host uses a subpath, set the Vite base:
bun run build:web -- --base /<repo>/
- Deploy
web/distto your static host. - Set hub CORS to allow the static origin (
HAPI_PUBLIC_URLorCORS_ORIGINS). - Open the static site, click the top-right Hub button on the login screen, and enter the hapi hub origin.
Clear the hub override in the same dialog to return to same-origin behavior.