wushenghua/hapi
1
0
Fork 0
mirror of https://github.com/wu736139669/hapi.git synced 2026-10-26 22:30:50 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
efc9004fda5c8fd30f876efdebd8f47aaa1b64ff
hapi/hub
T
History
HeavyGeeGitHubCursor
 86c88df93b fix(runner,hub): cross-platform orphan reap on archive / tracking loss (#1911) 
* fix(runner,hub): reap detached driver CLI on archive and tracking loss

Archive always verifies via stopRunnerSession; runner stopSession scans
argv orphans and awaits webhook-timeout tree-kill so PPID=1 children
cannot accumulate after KillSession miss or map drop.

Fixes #1910

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

* fix(cli): keep --hapi-session-id reap-only; test orphan kill path

Claude/cursor swallow the stamp without bootstrap reuse, and
reapRunnerSpawnedOrphans is unit-tested as the stopSession map-miss path.

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

* fix(cli,hub): address #1911 CI and bot Majors

Use Vitest in orphanReap tests, add Pi session.on mock, refuse archive
when machine StopSession is unreachable, trust full tree-kill results,
and argv-sweep orphans after every mapped stop.

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

* fix(runner): gate late-webhook kill on timeout orphans; fail closed on scan error

Track webhook-timeout PIDs separately so recovered shared roots are not
killed, and treat ps-list failures as still_alive rather than empty.

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

* fix(runner): keep shared Codex wrapper alive when archiving one root

StopSession must detach a single shared root without tree-killing the
wrapper PID while sibling roots remain, including after KillSession has
already marked the runtime inactive.

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

* fix(runner): keep shared Codex siblings after restart tracking loss

Before persisted-PID or argv orphan kills, consult the durable runtime
registry for active sibling roots on the same wrapper PID so archiving
one root after a runner restart cannot tree-kill live shared sessions.

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

* fix(hub,cli): deliver hub-authored archive metadata to reconnecting CLIs

When KillSession misses and archive is written via markSessionArchivedFromHub,
emit Socket.IO update-session to the session room. On reconnect, ApiSessionClient
reconciles GET /cli/sessions/:id metadata so hub-archived still fires.

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

* fix(runner): argv-scan orphans even when shared siblings remain

Remove session-wide early returns that skipped orphan reaping whenever any
shared wrapper had active siblings. Keep only the PID-specific filter so
older untracked CLIs with the same HAPI id are still reaped.

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

* fix(runner): protect tracked shared wrappers when runtime registry is empty

Argv orphan sweeps must exclude in-memory shared wrapper PIDs that still
host sibling roots, not only durable registry siblings — otherwise a missing
runtime record lets the sweep tree-kill the wrapper while archiving one root.

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

* fix(runner): adopt untracked nonshared CLIs after runner restart

When a runner-spawned Claude webhook arrives with no TrackedSession (typical
after restart mid-bootstrap), durably adopt the PID instead of ignoring it so
StopSession can reap. Keep killing only nonshared timeout orphans; never kill
shared Codex wrappers on late webhooks.

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

* fix(runner): keep recovered shared wrappers for registry siblings

After restart adoption tracks only a newly reported Codex root, archiving
it must consult the durable registry before tree-killing the wrapper PID
so older active sibling roots survive.

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

* fix(hub): do not archive on KillSession ack when StopSession is unknown

KillSession returns before cleanupAndExit finishes. When the runner cannot
find the PID (unknown), wait for the session KillSession handler to drop
before archiving; refuse if the CLI socket remains reachable.

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

* fix(hub,cli): confirm KillSession pid via StopSession before archive

KillSession now returns the CLI pid. When session-id StopSession is
unknown, archive confirms that OS pid (without treating socket loss as
exit) and still refuses when confirmation stays unknown or still_alive.

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

* fix(runner,hub): tree-kill adopted CLIs and require PID start markers

Adopted post-restart runner sessions now use killProcessTreeByPid when no
ChildProcess handle exists. KillSession carries a process-start marker so
raw PID confirmation cannot tree-kill a reused OS pid.

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

* fix(runner,hub): verify adopted PID markers and hub-archive after stop

Adopted sessions compare the persisted start marker before tree-kill and
drop stale tracking on mismatch. After confirmed StopSession, hub-authors
archive metadata when the CLI did not finish its flush.

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

* fix(runner): refuse unconfirmed shared/adopted stops

Keep shared wrappers when siblings remain, but return unknown unless
runtimeControl already ended the root. Adopted PIDs without a start
marker no longer tree-kill by tracked PID alone.

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

* fix(runner): require inactive binding before sibling-kept archive

Siblings alone must not flip StopSession to stopped on retry, while an
acknowledged inactive Codex registry binding remains stop proof. Handle
PID- markers before any tracked kill so reuse cannot nuke strangers.

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

* fix(runner): distinguish orphan reap from unknown keep-wrapper base

Pass unknown into finishWithOrphanSweep so a successful argv reap stays
stopped instead of being overwritten by an absent registry binding.

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

* fix(runner): honor orphan reap when adopted PID lacks a start marker

finishWithOrphanSweep with an unknown base lets a successful argv kill
report stopped instead of forcing unknown after the marker probe fails.

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

* fix(hub): confirm archive via metadata.hostPid tombstone

When StopSession(sessionId) is unknown and KillSession supplies no
confirmable pid+marker, probe PID-<metadata.hostPid>. already_gone
allows archive; still_alive/unknown still refuse (#1911 Peer #1820).

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

* fix(cli): escalate Windows taskkill to /F like SIGTERM→SIGKILL

Soft taskkill /T is refused on win32 console trees; orphanReap left
orphans still_alive. waitForProcessToDie now force-escalates on both
platforms so cross-platform reaping matches.

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

* fix(cli): widen process.kill mock signal to string | number

Match @types/node process.kill(pid, signal?: string | number) so the
Windows taskkill escalation mocks typecheck on tip 54f141368.

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

* fix(cli): tasklist liveness + immediate /F after soft taskkill refuse

Windows orphan reap still failed in 5ms on Teemo: soft taskkill refused
but escalate waited on an unreliable process.kill(0) probe. Prefer
tasklist for win32 liveness and escalate to /F as soon as the PID is
still live after soft kill.

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

* fix(cli): coerce win32 ps-list PIDs and escalate soft taskkill to /F

String PIDs from ps-list made Number.isFinite fail so orphan kill
returned still_alive without calling taskkill. Coerce PIDs, prefer
tasklist liveness, and escalate soft taskkill to /F like SIGTERM→SIGKILL.

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

* fix(cli): Windows orphan scan via CIM CommandLine + taskkill /F escalate

ps-list/fastlist is missing CommandLine and often missing from single-exe
bundles, so Teemo orphan reap returned scan_failed (logged as live PIDs).
List via Win32_Process CIM, coerce PIDs, escalate soft taskkill to /F.

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

* fix(cli): grace-wait after successful soft taskkill before /F

Escalate immediately only when soft taskkill is refused. When soft
succeeds but the PID is still draining, honor the existing grace period
before force (Codex Major on #1911).

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

* fix(runner): re-verify start marker before orphan argv tree-kill

Capture getProcessStartMarker after the argv match list, re-check
immediately before killTree, and skip on mismatch/null-while-alive so
PID reuse cannot tree-kill an unrelated process on the orphan fallback.

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

* fix(hub): preallocate HAPI id before fresh machine spawn

Fresh POST /machines/:id/spawn omitted existingSessionId, so argv never
got a reap stamp. Preallocate the hub row (fork/clear pattern) and pass
that id so a runner restart before the first webhook remains reapeable.

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

* fix(cli,hub): close three post-prealloc unreapable paths

Pass --hapi-session-id into Claude/cursor/kimi/copilot bootstrap so the
preallocated hub row is used. Treat null marker re-check while alive as
still_alive (not stopped). Keep the preallocated stub when spawn-fail
StopSession cannot confirm the child is gone.

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

* fix(cli): adopt-stub via reservedSessionId, not existingSessionId

`--hapi-session-id` binds a fresh create bootstrap to a hub-preallocated
UUID (getOrCreateSession id) without taking the reopen path. Non-UUID
stamps stay reap-only to match hub create schema. Restores integration
spawn invariants broken by mapping hapi→existingSessionId.

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

* fix(cli,hub): close Opus cold-read B1–B3 for #1911

B1: capture start markers from the same process snapshot as argv
match (POSIX ps lstart / Win32 CreationDate); re-check before kill.
Continue other orphans when one target is unconfirmed.

B2: Windows killProcessTreeByPid verifies every collected descendant,
not root-only — taskkill /T exit 0 is signalled, not gone.

B3: runner sets childStarted:false on pre-exec rejection; hub deletes
the preallocated stub without StopSession. Post-exec ambiguity still
keeps the row until stop confirms. Terminal archives no longer refuse
when no runner is connected.

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

* fix(cli,hub): explicit adopt for hub-preallocated session stubs

Fresh machine spawn preallocates with tag machine-spawn:<uuid>; CLI
create with a different tag and the same id 409'd on identity conflict.
Add adoptPreallocatedSession (hub-internal stub check) and POST
/cli/sessions { adopt: true, id } so create binds the reserved row and
overwrites tag/metadata without guessing the hub tag. Tests fail-first
on the real prealloc→CLI create path.

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

* fix(cli): preserve snapshot markers + unify Windows CIM start markers

Runner stopSession was still on findOrphans (PID-only), discarding same-snapshot
markers and reopening the PID-reuse kill window. Switch both call sites to
findTargets. Force UTC ISO 'o' CreationDate for list and single-PID probe so
ConvertTo-Json cannot disagree with getProcessStartMarker on WinPS 5.1.

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

* fix(cli): exercise production orphan sweep wiring in tests

Extract findStopSessionOrphanTargets as the stopSession discovery path both
run.ts sweeps call. Add tests that drive that helper end-to-end (not an
injected findOrphans seam), assert run.ts source wiring, and cover CIM-list
ISO vs probe ISO agreement plus the broken WinPS shape mismatch.

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

* fix(hub,cli): never delete live spawn on RPC timeout; release stub tags

Ambiguous machine-spawn failures (timeout / unset childStarted) no longer
call stopRunnerSession or deleteSession — that path killed healthy late
boots and CASCADE-wiped transcripts. Pre-exec delete still requires a real
machine-spawn stub (store tag check). Metadata updates release the stub
tag so reopen flavors are not permanently adoptable; adopt refuses
archived stubs. POSIX pgrep ENOENT fails closed instead of root-only verify.

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

* fix(cli): parseable Windows tree scan + fail closed on CIM failure

Space-joined PowerShell for collectWindowsProcessTree was a WinPS parse
error ($seen=@{} $bfs=@()), so every scan fell open to [root] and B2
false-stopped again. Join with newlines; return scan_failed on error/empty;
killProcessTreeByPid refuses root-only verify. Assert on generated command
text (Teemo-confirmed) so mocks cannot hide the next malformed script.

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

* fix(cli,hub): reopen stamps existing-session-id; scan-fail signals root

Opus Critical on #1911: runner always stamps --existing-session-id for
known hub ids so Claude/Kimi/Copilot reopen does not hit adopt-stub 409.
On pgrep/CIM tree-scan failure still signal the verified root but never
claim stopped. Archive when both KillSession and machine RPC are missing.
Empty Win process-list stdout and strict Codex registry reads fail closed.

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

* fix(cli,hub): OK: sentinel for Windows tree scan; adopt CAS

CIM failure under SilentlyContinue printed root-only with exit 0 —
byte-identical to a healthy childless tree, so scan_failed never fired
and killProcessTreeByPid false-stopped (#1911 Overseer B1). Require
ErrorActionPreference=Stop, trap exit 1, and an OK: success sentinel;
parse anything else as scan_failed. Same Stop/trap on the machine-wide
list command. Execute the generated scripts under Docker pwsh in CI
when the image is present. Treat pgrep status=null as scan_failed;
coarsen Windows tasklist poll; wrap adoptPreallocatedSession in a
transaction with stub-tag CAS.

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

* fix(cli,hub): reservedSessionId for fresh prealloc; signal Win survivors

Fresh machine-spawn stubs must not stamp --existing-session-id — that
sends Codex down reopen without a thread binding (#1911 bot Major) and
re-broke local HTTP non-UUID hints as reopen (round-4). Hub passes
prealloc as reservedSessionId; buildCliArgs stamps --hapi-session-id
for reserved/sessionId and --existing-session-id only for live reopen.
Codex parses --hapi-session-id and adopts via bootstrapSession.

Windows tree kill now taskkills surviving pre-scan PIDs after /T misses
broken intermediate links.

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

* fix(cli,hub): fail-loud Docker pwsh CI; scope Codex registry; stub leak

CI skipped all four windowsProcessTree.pwsh tests on 48bb (image inspect
without pull). Pull the image in test.yml and throw under CI when missing.
Scope strict runtime-registry failure to Codex stop contexts so one bad
JSON cannot block archive machine-wide. Stamp childStarted:false on
machine RPC outside_workspace_roots. Add Codex reservedSessionId prealloc
and runSharedCodex regression coverage for the #1911 Critical.

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

* fix(cli,hub): single-use reservedSessionId; skip UUID HTTP hints

Consume the machine-spawn reservation on first prepare() so a second
Codex root/fork cannot re-adopt a consumed stub (409). Stop stamping
UUID local-HTTP sessionId as --hapi-session-id (adopt hard-fail). Update
stale hub spawn mocks for the reservedSessionId arity.

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

* fix(hub): archive never-started machine-spawn stubs on unknown

Ambiguous keep-stubs (startedBy=runner, no hostPid, still machine-spawn
tagged) made StopSession return unknown forever while the runner was
online, so archive threw permanently. Treat unknown + prealloc stub +
no hostPid as already_gone. Also reject spawn success when the runner
reports a different id than the preallocated stub.

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

* fix(hub,cli): refuse dual-RPC-miss archive; generation-check Win survivors

Both KillSession and StopSession missing is not proof a detached CLI exited —
keep the row unconfirmed until the runner reconnects. Windows tree kill now
re-checks process-start markers before individually signalling survivors so
PID reuse is not killed.

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

* fix(cli): refuse archived reopen in bootstrapExistingSession

Hub-archived rows could be resurrected when a late-booting child hit
--existing-session-id: buildSessionMetadata stamped lifecycleState=running
and updateMetadata overwrote the archive. Adopt already rejected archived
stubs; reopen now matches. Intentional revive still goes through hub
reopenSession first. Correct stub-hatch comment (no post-archive argv sweep).

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

* fix(hub,cli): reject un-archive in updateSessionMetadata CAS

Hub-side transactional guard (Discovery #1911 M1): refuse metadata writes
that clear archived lifecycle unless allowUnarchive (reopen clear). Client
stops infinite updateMetadata backoff when mismatch applies archived.
Clear archive immediately before spawn so Pi/PTY attempt snapshots stay valid.

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

* fix(hub,cli): success+preserve hub archive; M3 reservedSessionId split

Replace version-mismatch refuse (livelock in CAS backoff) with success +
merge-preserve of hub-archived fields unless allowUnarchive. Ack path
routes through noteHubArchived so the CLI exits (criterion 6). Clear-
before-spawn remains the authorized revive. Thread --hapi-session-id to
reservedSessionId for shared-parser flavors (adopt≠reopen).

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

* fix(cli): fail-closed orphan ps signal; PID- registry; spawn timeouts

Overseer B1: signalled ps (status null) is scan_failed, not empty table.
B2: unreadable registry on PID-* stops returns null (no soft []).
B3: 10s timeout on process/orphanReap spawn.sync. Narrow bootstrap
archived belt to archivedBy=hub to match hub merge-preserve.

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

* fix(cli,hub): hubArchived latch; PTY archiveSnapshot durability

Criterion 6: noteHubArchived latches hubArchived so late
registerKillSessionHandler registrations still EXIT (EventEmitter
does not replay). Mirror Pi: persist archiveSnapshot on
ptyResumeAttempt across clear-before-spawn and quarantine, restore
on failed-resume cleanup (#1911 Discovery Majors).

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

* fix(cli): Codex hub-archived exit; AC6 latch test production order

C2: SharedCodexRoot registers hub-archived (and latch check) beside
its private KillSession — Codex never called registerKillSessionHandler.
C1: keep latch+subscribe; test write-then-register order Discovery proved.

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

* fix(cli): type Codex hub-archived end mock for tsc

vi.fn(async () => {}) inferred zero-arg calls; RootHost['end']
signature unblocks end.mock.calls[0][0] (TS2493).

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

* fix(cli): catch hub-archived Codex host.end rejection

void this.host.end() discarded archive-RPC failures as unhandled
rejections; Codex has no unhandledRejection handler, so Node can
exit the shared wrapper and kill sibling roots mid-turn.

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

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-25 09:15:08 +01:00
..
scripts
feat(hub): add message content codec for storage optimization
2026-08-02 13:21:32 +08:00
src
fix(runner,hub): cross-platform orphan reap on archive / tracking loss (#1911)
2026-09-25 09:15:08 +01:00
package.json
chore: upgrade Bun to 1.4.0
2026-08-25 13:31:59 +08:00
README.md
fix(hub): keepalive-only sessions reconcile to an idle lifecycle (#1820) (#1821)
2026-09-16 08:11:54 +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 web and native clients.
  • Socket.IO channel for CLI connections.
  • Serves the web app from web/dist or embedded assets in the single binary; network-relay mode uses the separately hosted official web app.
  • Persists state in SQLite via bun:sqlite.

Configuration

See src/configuration.ts for all options.

Required

  • CLI_API_TOKEN - Base shared secret used by CLI, web login and native pairing. 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)

Dictation and voice-assistant provider keys can also be added from Settings → Voice (stored in settings.json under providerCredentials; env vars still win when set at process start).

  • ELEVENLABS_API_KEY - ElevenLabs API key for voice assistant + dictation.
  • ELEVENLABS_AGENT_ID - Custom ElevenLabs agent ID (auto-created if not set).
  • GEMINI_API_KEY / GOOGLE_API_KEY - Gemini Live voice assistant.
  • DASHSCOPE_API_KEY / QWEN_API_KEY - Qwen Realtime voice assistant.
  • VOICE_BACKEND - Default assistant backend (elevenlabs, gemini-live, or qwen-realtime).
  • OPENAI_API_KEY - OpenAI dictation (gpt-transcribe / gpt-live-transcribe).
  • DEEPGRAM_API_KEY - Deepgram dictation (nova-3, standard and realtime).
  • GROQ_API_KEY - Groq dictation (whisper-large-v3).
  • TRANSCRIPTION_BASE_URL and TRANSCRIPTION_MODEL - OpenAI-compatible/local transcription endpoint and model.
  • TRANSCRIPTION_API_KEY - Optional bearer token for the OpenAI-compatible endpoint.

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 - Explicit relay auth key. By default the hub obtains and persists an individually revocable key from the relay. A persisted key rejected with HTTP 403 is discarded and reissued once; an explicitly configured environment key must be updated manually.
  • HAPI_RELAY_FORCE_TCP - Force TCP relay mode (true/1).
  • VAPID_SUBJECT - Contact email/URL for Web Push.
  • HAPI_ANDROID_PUSH - auto (default: direct FCM when credentials are configured, otherwise relay), relay, fcm, or off.
  • FCM_SERVICE_ACCOUNT_PATH - Service-account JSON for private Firebase builds; the app must use the same project. Invalid configured credentials disable Android push instead of switching projects.
  • HAPI_IOS_PUSH - relay (default), apns, or off.
  • HAPI_PUSH_RELAY_URL - Shared Android/iOS push relay (default: https://push.hapi.run; persisted as iosPushRelayUrl). Independent of the --relay network tunnel.
  • HAPI_SESSION_IDLE_TIMEOUT_MS - Keep-alive-idle window in ms (default: 43200000 / 12 h; 0 disables). See "Session liveness" below.

Official native apps register their encryption keys automatically; no push provider setup is needed on a fresh hub. See the native companion push contract.

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.

For web/native clients + 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

The following is an overview. See the client contract for request/response shapes and error semantics, and src/web/routes/ for all endpoints.

Authentication (src/web/routes/auth.ts, src/web/routes/bind.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. Each summary includes hasConversationContent, derived from stored conversation messages (not titles or lifecycle events); full session SSE updates carry changes to this flag.
  • GET /api/sessions/:id - Get session details.
  • POST /api/sessions/:id/abort - Abort session.
  • POST /api/sessions/:id/switch - Hand off session control to the web.
  • POST /api/sessions/:id/resume - Resume inactive session.
  • POST /api/sessions/:id/reopen - Reopen a session; follow the returned session ID.
  • POST /api/sessions/:id/clear - Start a fresh conversation when supported.
  • 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 effort for Claude, Grok, or Pi; other config controls are flavor/capability-gated (see the client contract).
  • GET/POST /api/sessions/:id/scratchlist - Read/create Hub-persisted scratchlist entries; update/delete and attachment routes share this prefix.

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

  • GET /api/sessions/:id/messages - Get messages (paginated).
  • POST /api/sessions/:id/messages - Send message.
  • POST /api/sessions/:id/messages/queued-state - Reconcile queued, indeterminate, and invoked local IDs.
  • DELETE /api/sessions/:id/messages/:messageId - Cancel a queued message.
  • POST /api/sessions/:id/messages/:messageId/steer - Steer a queued message when the session supports it.
  • POST /api/sessions/:id/messages/:messageId/retry - Explicitly retry indeterminate delivery when safe; never auto-replay.

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.
  • PATCH /api/machines/:id - Set/clear the machine display name.
  • GET /api/machines/:id/agent-availability - List installed/configured Agents.
  • POST /api/machines/:id/spawn - Spawn new session on machine.
  • POST /api/machines/:id/list-directory - Browse runner-scoped directories.
  • POST /api/machines/:id/paths/exists - Check if path exists.
  • POST /api/machines/:id/restart-runner - Request runner restart (requires an available restart path).

Usage (src/web/routes/usage.ts)

  • GET /api/usage/summary - Get cache-aware token usage for the owner namespace (range=7d|30d|all).

Storage (src/web/routes/storage.ts)

  • GET /api/storage/sqlite - SQLite database/WAL/SHM sizes for the owner namespace.

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.
  • GET /api/voice/backend - Discover configured assistant backends.
  • GET /api/voice/voices - List voices for the selected backend.
  • GET/PUT /api/voice/transcription/credentials - Read masked provider settings or update credentials (owner-only).
  • GET /api/voice/transcription/providers - List configured providers and supported modes.
  • POST /api/voice/transcription - Transcribe a bounded recording.
  • POST /api/voice/transcription/realtime-token - Mint a short-lived OpenAI, ElevenLabs, or Deepgram credential.

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.

Native Android/iOS registration uses POST/DELETE /api/devices/register (src/web/routes/devices.ts); see the native push contract.

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/index.ts and src/socket/handlers/terminal.ts for event handlers.

Namespaces: /cli (raw CLI access token) and /terminal (client JWT). Ordinary web/native session updates use SSE, not the CLI Socket.IO namespace.

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)

  • terminal:create - Open terminal for session.
  • terminal:write - Send input.
  • terminal:resize - Resize dimensions.
  • terminal:close - Close terminal.
  • agent-terminal:subscribe / agent-terminal:unsubscribe - Attach/detach the wrapped agent's terminal stream.
  • agent-terminal:input / agent-terminal:resize - Interact with that terminal when supported.

Hub events (hub to CLI clients, /cli)

  • 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.

Session liveness

Two separate signals, deliberately (tiann/hapi#1820):

  • active / activeAt - transport. The CLI socket is connected; session-alive refreshes it every ~2 s. sessionCache.expireInactive drops active after 30 s of silence.
  • metadata.lifecycleState - agent health. running -> idle -> running, plus archived.

Keep-alives prove a socket, not an agent. A session can therefore heartbeat for days with no messages, no thinking and no background tasks - active: true forever, which expireInactive can never catch. sessionCache.reconcileKeepaliveIdle (same 5 s tick) closes that gap: after HAPI_SESSION_IDLE_TIMEOUT_MS with no agent progress it moves lifecycleState running -> idle.

  • active is left alone on purpose. The CLI really is reachable, and flipping it would let resumeSession spawn a second agent against a live process, and unlock dedup-merge / delete on it.
  • Progress means a message in either direction, a queued prompt, or a background task - never a keep-alive. Sessions that are thinking, running background tasks or holding a pending permission request are never marked.
  • idle reverts to running on the next progress, within one tick.
  • metadata.idleReconcileExempt: true opts a session out entirely.

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).
  • Scratchlist entries/attachments, usage, work graph, and push registrations.

Message content is stored via src/store/contentCodec.ts: oversized strings inside agent messages (giant tool output) are head+tail truncated at ingest, and payloads ≥256 chars are zstd-compressed (TEXT = plaintext JSON, BLOB = zstd). User prompts are never truncated — queued rows are delivered to the CLI verbatim.

Maintenance scripts (run with the hub stopped before swapping files):

  • scripts/compact-db.ts — retroactively truncate + compress + VACUUM an existing DB into a new file (the source is only opened read-only).
  • scripts/cleanup-sessions.ts — bulk-delete sessions by message count, path glob, or first-message pattern.

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