wushenghua/hapi
1
0
Fork 0
mirror of https://github.com/wu736139669/hapi.git synced 2026-08-05 06:24:37 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
2ab3b398875a05298acd140754facf2db819260d
hapi/hub
T
History
HeavyGeeGitHubCursor
 2ab3b39887 fix(hub,cli): four hub-restart-cascade cleanup bugs (#913 #914 #916 #919) (#923) 
* fix(hub,cli): four hub-restart-cascade cleanup bugs (#913 #914 #916 #919)

These four contained bugs were uncovered by a 2026-06-15 hub-restart
incident where `hapi-restart-hub` SIGTERMed 23 cursor ACP sessions.
Each fix lands independently of the architectural #915 (hub-restart
cascade-archive) and the hypothesis-pending #917 (reopen creates dead
session); audit-trail correctness and idempotency wins stand on their
own.

  Fresh ACP sessions could be SIGTERMed during the async `update-metadata`
  ACK round-trip, stranding the on-disk ACP store with no DB handle. Add
  `ApiSessionClient.flushMetadata()` and await it after `onSessionFoundWithProtocol`
  on the fresh-session branch. Resume-path pre-registration (PR #834) is
  unchanged.

  Hub-restart-cascade SIGTERMs went through the same path as web-UI
  Archive clicks, both writing archiveReason='User terminated'. New
  default is 'Hub restart'; the KillSession RPC handler (the
  authoritative user-archive signal) now explicitly stamps
  'User terminated' before cleanupAndExit. SIGINT (local-terminal Ctrl-C)
  keeps the 'User terminated' label too.

  `rpcGateway.killSession` threw a generic Error when no target socket
  was registered, and the archive route surfaced that as 500. Add typed
  `RpcTargetMissingError`, narrow on it in `syncEngine.archiveSession`,
  fall back to a hub-side `markSessionArchivedFromHub` write so
  lifecycleState still flips to 'archived'. Drop the requireActive
  guard on the route and 2xx-noop for already-archived rows.

  without refresh, producing forever-409 on rename/reopen until an
  unrelated event triggered a cache refresh. `renameSession`,
  `clearSessionArchiveMetadata`, `restoreSessionArchiveMetadata` now
  retry-with-refresh (5 attempts, then throw) mirroring the existing
  good pattern in `mergeSessions`.

Refs tiann/hapi#913
Refs tiann/hapi#914
Refs tiann/hapi#916
Refs tiann/hapi#919

AI disclosure: implementation by Claude Sonnet 4.5 (Cursor agent peer)
under operator supervision. Issue triage by a sibling discovery agent.
Per CONTRIBUTING.md AI-assisted contributions policy.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(cli): runner-spawned children use 'Stopped by runner' as default archive reason

Addresses bot review of #923: with the #914 default-archiveReason flip to
'Hub restart', runner-driven SIGTERM paths (`hapi runner stop-session`,
webhook-timeout cleanup at run.ts:587, orphan-cleanup at run.ts:267) all
mislabel as 'Hub restart' which is also inaccurate audit-trail noise.

Smallest defensible change: parameterise the lifecycle default via
HAPI_DEFAULT_ARCHIVE_REASON env, and have the runner set
'Stopped by runner' on spawn. Terminal-launched sessions (no runner
parent, no env var) still default to 'Hub restart' since hub-restart
cascade documented at #915 is the most plausible SIGTERM source for
those. Explicit overrides via setArchiveReason (KillSession RPC, SIGINT
Ctrl-C, markCrash uncaught exception) still win.

Two new unit tests cover the env-var default and the override
precedence.

Refs tiann/hapi#914.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(hub): markSessionArchivedFromHub surfaces persistence failures as 5xx

Addresses second-round bot review of #923 (Major): `markSessionArchivedFromHub`
silently returned on DB write errors and on exhausted version-retry
attempts, which would let `/archive` claim 200 OK while the row stayed
unarchived. That regresses the #916 acceptance criterion that non-RPC
errors during archive must still propagate as 5xx.

Both fall-through paths now throw, matching the contract of the
sibling writers in this file (renameSession, mergeSessions). The
sessionModel test suite gains two cases that spy on
`store.sessions.updateSessionMetadata` to force `error` and
`version-mismatch` shapes and asserts the helper throws. The existing
route test at `hub/src/web/routes/sessions.test.ts:1015` already
covers the route-level 500 propagation for any error thrown out of
`archiveSession`, so no new route test is needed.

Imports `spyOn` from `bun:test` to match this test file's runtime
(the rest of the hub package uses bun:test, not vitest).

Refs tiann/hapi#916.

Co-authored-by: Cursor <cursoragent@cursor.com>

* revert(cli): drop HAPI_DEFAULT_ARCHIVE_REASON env override

Reverts `1c8972a3`. Bot review round 3 surfaced that the env-on-spawn
approach (the bot's own round-1 suggestion shape) mislabels
hub-restart-cascade SIGTERMs against runner-spawned children: systemd
killcgroup on `hapi-runner.service` stop sends SIGTERM to all
runner-children directly, and those would archive as 'Stopped by runner'
instead of 'Hub restart'.

The two suggestions are mutually incompatible without adding an IPC
channel (stdio: 'ipc' on spawn) so the runner can stamp
setArchiveReason via childProcess.send() before SIGTERMing. That is a
refactor, not a smallest-defensible change.

Going back to the simple shape: SIGTERM default is 'Hub restart' for
everyone, runner-internal stop paths share that label. The
audit-trail-correctness criterion from the #914 issue is met
(SIGTERM no longer falsely labels as 'User terminated'). Finer
attribution between cascade vs runner-stop is deferred as a follow-up.

Refs tiann/hapi#914.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(cli): clean completions get 'Session completed', not 'Hub restart'

Addresses bot review round 4 of #923 (Major): every agent runner
(runClaude, runCodex, runCursor, runGemini, runKimi, runOpencode)
calls setSessionEndReason('completed') on the natural exit path
without touching archiveReason. With the SIGTERM default flipped to
'Hub restart', clean completions were now archived as restart
cascades.

Fix: setSessionEndReason flips archiveReason to 'Session completed'
when it transitions to 'completed' AND no caller has already overridden
the archive reason. This covers all six agent runners with a single
setter change (no per-runner edits).

Two new tests cover the natural-completion default and the override
precedence (explicit setArchiveReason still wins).

Refs tiann/hapi#914.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(hub): restore inactive-session guard on /archive except split-brain

Addresses post-rebase bot review Major on #923: dropping requireActive
entirely let normal inactive non-archived rows (completed stubs, UI
Delete/Reopen targets) fall through to archiveSession, which could stamp
archivedBy=hub on sessions that were never active.

Restore the 409 for inactive rows unless metadata.lifecycleState is
still 'running' (hub-restart split-brain cleanup case from #916).
Two route tests cover the guard and the exception.

Refs tiann/hapi#916.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(cli): merge runnerLifecycle tests after upstream rebase

Post-rebase fix: Session completed tests referenced makeFakeSession
which was renamed to createMockApiSessionWithMetadataCapture when
merging upstream hasExplicitSessionEndReason tests with #914 archive
reason coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(cli): pass lifecycle object to KillSession handler in Pi runner

Upstream #862 (Pi agent) landed after this branch was cut. runPi.ts
still registered the legacy bare cleanupAndExit callback, so web
Archive for Pi sessions would persist archiveReason: Hub restart
instead of User terminated. One-line fix matching the other six
agent runners.

Refs tiann/hapi#914.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-19 17:37:32 +08:00
..
scripts
Clean up cross-package build coupling
2026-05-20 19:29:43 +08:00
src
fix(hub,cli): four hub-restart-cascade cleanup bugs (#913 #914 #916 #919) (#923)
2026-06-19 17:37:32 +08:00
package.json
Clean up cross-package build coupling
2026-05-20 19:29:43 +08:00
README.md
fix(hub+cli): defer mergeSessions on cursor ACP reopen until session/load succeeds (closes #939) (#948)
2026-06-18 10:10:10 +08:00
tsconfig.json
feat: rename server package to hub
2026-01-27 19:51:21 +08:00

README.md

hapi-hub

Telegram bot + HTTP API + realtime updates for hapi hub.

What it does

  • Telegram bot for notifications and the Mini App entrypoint.
  • HTTP API for sessions, messages, permissions, machines, and files.
  • Server-Sent Events stream for live updates in the web app.
  • Socket.IO channel for CLI connections.
  • Serves the web app from web/dist or embedded assets in the single binary.
  • Persists state in SQLite.

Configuration

See src/configuration.ts for all options.

Required

  • CLI_API_TOKEN - Base shared secret used by CLI and web login. Clients append :<namespace> for isolation. Auto-generated on first run if not set.

Optional (Telegram)

  • TELEGRAM_BOT_TOKEN - Token from @BotFather.
  • HAPI_PUBLIC_URL - Public HTTPS URL for Telegram Mini App access. Also used to derive default CORS origins for the web app.

Optional (Voice)

  • ELEVENLABS_API_KEY - ElevenLabs API key for voice assistant.
  • ELEVENLABS_AGENT_ID - Custom ElevenLabs agent ID (auto-created if not set).

Optional

  • HAPI_LISTEN_HOST - HTTP bind address (default: 127.0.0.1).
  • HAPI_LISTEN_PORT - HTTP port (default: 3006).
  • CORS_ORIGINS - Comma-separated origins, or *.
  • HAPI_HOME - Data directory (default: ~/.hapi).
  • DB_PATH - SQLite database path (default: HAPI_HOME/hapi.db).
  • TELEGRAM_NOTIFICATION - Enable/disable Telegram notifications (default: true).
  • HAPI_RELAY_API - Relay API domain (default: relay.hapi.run).
  • HAPI_RELAY_AUTH - Relay auth key (default: hapi).
  • HAPI_RELAY_FORCE_TCP - Force TCP relay mode (true/1).
  • VAPID_SUBJECT - Contact email/URL for Web Push.

Running

Binary (single executable):

export TELEGRAM_BOT_TOKEN="..."
export CLI_API_TOKEN="shared-secret"
export HAPI_PUBLIC_URL="https://your-domain.example"

hapi hub

hapi server remains supported as an alias.

If you only need web + CLI, you can omit TELEGRAM_BOT_TOKEN. To enable Telegram, set TELEGRAM_BOT_TOKEN and HAPI_PUBLIC_URL, start the hub, open /app in the bot chat, and bind the Mini App with CLI_API_TOKEN:<namespace> when prompted.

From source:

bun install
bun run dev:hub

HTTP API

See src/web/routes/ for all endpoints.

Authentication (src/web/routes/auth.ts)

  • POST /api/auth - Get JWT token (Telegram initData or CLI_API_TOKEN[:namespace]).
  • POST /api/bind - Bind a Telegram account using initData + CLI_API_TOKEN:<namespace>.

Sessions (src/web/routes/sessions.ts)

  • GET /api/sessions - List all sessions.
  • GET /api/sessions/:id - Get session details.
  • POST /api/sessions/:id/abort - Abort session.
  • POST /api/sessions/:id/switch - Switch session to remote mode.
  • POST /api/sessions/:id/resume - Resume inactive session.
  • POST /api/sessions/:id/upload - Upload file (base64, max 50MB).
  • POST /api/sessions/:id/upload/delete - Delete uploaded file.
  • POST /api/sessions/:id/archive - Archive active session.
  • PATCH /api/sessions/:id - Rename session.
  • DELETE /api/sessions/:id - Delete inactive session.
  • GET /api/sessions/:id/slash-commands - List slash commands.
  • GET /api/sessions/:id/skills - List skills.
  • POST /api/sessions/:id/permission-mode - Set permission mode.
  • POST /api/sessions/:id/model - Set model preference.
  • POST /api/sessions/:id/effort - Set Claude effort preference.

Messages (src/web/routes/messages.ts)

  • GET /api/sessions/:id/messages - Get messages (paginated).
  • POST /api/sessions/:id/messages - Send message.

Permissions (src/web/routes/permissions.ts)

  • POST /api/sessions/:id/permissions/:requestId/approve - Approve permission.
  • POST /api/sessions/:id/permissions/:requestId/deny - Deny permission.

Machines (src/web/routes/machines.ts)

  • GET /api/machines - List online machines.
  • POST /api/machines/:id/spawn - Spawn new session on machine.
  • POST /api/machines/:id/paths/exists - Check if path exists.

Git/Files (src/web/routes/git.ts)

  • GET /api/sessions/:id/git-status - Git status.
  • GET /api/sessions/:id/git-diff-numstat - Diff summary.
  • GET /api/sessions/:id/git-diff-file - File-specific diff.
  • GET /api/sessions/:id/file - Read file content.
  • GET /api/sessions/:id/files - File search with ripgrep.

Events (src/web/routes/events.ts)

  • GET /api/events - SSE stream for live updates.
  • POST /api/visibility - Report client visibility state.

Voice (src/web/routes/voice.ts)

  • POST /api/voice/token - Get ElevenLabs conversation token.

Push Notifications (src/web/routes/push.ts)

  • GET /api/push/vapid-public-key - Get VAPID public key.
  • POST /api/push/subscribe - Subscribe to push notifications.
  • DELETE /api/push/subscribe - Unsubscribe.

CLI (src/web/routes/cli.ts)

  • POST /cli/sessions - Create/load session.
  • GET /cli/sessions/:id - Get session by ID.
  • POST /cli/machines - Create/load machine.
  • GET /cli/machines/:id - Get machine by ID.

Socket.IO

See src/socket/handlers/cli.ts for event handlers.

Namespace: /cli

Client events (CLI to hub)

  • message - Send message to session.
  • update-metadata - Update session metadata.
  • update-state - Update agent state.
  • session-alive - Keep session active.
  • session-ready - Cursor ACP session/load (or newSession) succeeded; hub defers merge/dedup until this arrives on reopen.
  • session-end - Mark session ended.
  • machine-alive - Keep machine online.
  • rpc-register - Register RPC handler.
  • rpc-unregister - Unregister RPC handler.

Terminal events (web to hub)

  • terminal:create - Open terminal for session.
  • terminal:write - Send input.
  • terminal:resize - Resize dimensions.
  • terminal:close - Close terminal.

Hub events (hub to clients)

  • update - Broadcast session/message updates.
  • rpc-request - Incoming RPC call.

See src/socket/rpcRegistry.ts for RPC routing.

Telegram Bot

See src/telegram/bot.ts for bot implementation.

Commands

  • /start - Welcome message with Mini App link.
  • /app - Open Mini App.

Features

  • Permission request notifications with approve/deny buttons.
  • Session ready notifications.
  • Deep links to Mini App sessions.

See src/telegram/callbacks.ts for button handlers.

Core Logic

See src/sync/syncEngine.ts for the main session/message manager:

  • In-memory session cache with versioning.
  • Message pagination and retrieval.
  • Permission approval/denial.
  • RPC method routing via Socket.IO.
  • Event publishing to SSE and Telegram.
  • Git operations and file search.
  • Activity tracking and timeouts.

Storage

See src/store/index.ts for SQLite persistence:

  • Sessions with metadata and agent state.
  • Messages with pagination support.
  • Machines with runner state.
  • Todo extraction from messages.
  • Users table for Telegram bindings (includes namespace).

Source structure

  • src/web/ - HTTP service and routes.
  • src/socket/ - Socket.IO setup and handlers.
  • src/socket/handlers/cli/ - Modular CLI handlers.
  • src/telegram/ - Telegram bot.
  • src/sync/ - Core session/message logic.
  • src/store/ - SQLite persistence.
  • src/sse/ - Server-Sent Events.
  • src/config/ - Configuration loading and generation.
  • src/notifications/ - Push and Telegram notifications.
  • src/visibility/ - Client visibility tracking.

Security model

Access is controlled by:

  • Telegram initData verification plus bound Telegram users (bound via CLI_API_TOKEN:<namespace>).
  • CLI_API_TOKEN base secret for CLI and browser access (namespace is appended by clients).

Transport security depends on HTTPS in front of the hub.

Build for deployment

From the repo root:

bun run build:hub
bun run build:web

The hub build output is hub/dist/index.js, and the web assets are in web/dist.

Networking notes

  • Telegram Mini Apps require HTTPS and a public URL. If the hub has no public IP, use Cloudflare Tunnel or Tailscale and set HAPI_PUBLIC_URL to the HTTPS endpoint.
  • If the web app is hosted on a different origin, set CORS_ORIGINS (or HAPI_PUBLIC_URL) to include that static host origin.

Standalone web hosting

The web UI can be hosted separately from the hub (for example on GitHub Pages or Cloudflare Pages):

  1. Build and deploy web/dist from the repo root.
  2. Set CORS_ORIGINS (or HAPI_PUBLIC_URL) to the static host origin.
  3. Open the static site, click the Hub button on the login screen, and enter the hapi hub origin.

Leaving the hub override empty preserves the default same-origin behavior when the hub serves the web assets directly.

Reference in New Issue View Git Blame Copy Permalink