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
c404008072b88fd556660f55f954a0fbfc8e960b
hapi/hub
T
History
HeavyGeeGitHubCursor
 4c203f17cb feat(web,hub): scratchlist v2.2 hub attachment storage (#921) (#1205) 
* feat(hub,shared): scratchlist v2.2 hub attachment storage foundation (#921)

Hub stores scratchlist attachment bytes on filesystem; SQLite holds
AttachmentMetadata[] JSON via session_scratchlist.attachments (v11→v12).
Upstream ladder: v10→v11 text-only scratchlist table (#896), v11→v12
attachments column. Configurable limits via HAPI_SCRATCHLIST_* env vars.
Upload, serve, and limits REST routes; delete entry cleans hub files.

Web promote/rehydrate still TODO. Soup renumber branch follows.

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

* feat(web): scratchlist v2.2 attachment UX (#921)

Route scratchlist-mode composer submits with attachments to hub storage,
show image thumbnails in the drawer, and rehydrate attachments on promote
to composer or queue (hub fetch → CLI upload for send).

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

* fix(web): scratchlist attach submit, float thumbs, copy tooltip (#921)

Hub upload adapter now sets path on ready attachments so the composer send
button unlocks in scratchlist mode; routing label matches attachments too.
Entry thumbnails float left with text wrap; copy tooltip clarifies text-only.

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

* fix(hub): adapt scratchlist update tests to patch API (#921)

update() now takes { text?, attachments? }; v12 CRUD tests still passed a string.

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

* fix(hub,web): harden scratchlist attachment ownership and orphan cleanup

Resolve claimed hub paths against the current session before persist,
count on-disk session bytes for upload caps, delete blobs dropped on
entry update, and DELETE pending uploads when composer remove runs.

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

* chore: drop accidental .cursor files from attachment PR

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

* fix(web): exit scratchlist mode before rehydrate; delete raced uploads

Promote-to-composer flushes mode exit so attachments use the chat adapter.
Cancel-during-upload deletes the hub blob once upload returns.

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

* fix(hub,web): exact UUID delete match; stage hub paths on chat send

Reject partial attachment ids on disk delete, and restage scratchlist hub
attachments through uploadFile when sending after leaving scratchlist mode.

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

* fix(hub): skip text-only PUT resolve; cleanup session attachment dirs

Text-only edits keep existing attachment metadata after session-id transfer.
Require full UUID on resolve. Delete scratchlist attachment files when a
session is deleted.

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

* fix(hub,web): scratchlist attach route, PUT bytes, orphan deletes

Park only hub-resident attachments; subtract removed blobs from the PUT
session cap; delete attachment files only when no other entry still
references them.

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

* fix(hub): canonicalize scratchlist attachment filenames

Resolve stores the on-disk sanitized name (not claimed.filename) and
hardens Content-Disposition against CR/LF/quote injection.

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

* test(hub): cover toxic filename canonicalize on resolve

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

* fix(hub,web): serialize scratchlist uploads; drop hub blobs after chat stage

Per-session upload lock keeps disk byte caps honest under concurrency.
After a successful toggle-off chat send, delete the staged hub copies so
they no longer count against the session attachment budget.

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

* fix(shared,web): allow clearing scratchlist attachments; cleanup staged uploads

PUT may send attachments:[] without a text change. Staging to chat rolls
back partial normal-upload copies on failure.

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

* fix(hub): re-key scratchlist attachment files on session merge

Move hub blobs when scratchlist rows transfer between session ids so
quota and path ownership stay correct. Reject PUT that would leave an
empty textless entry after clearing attachments.

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

* fix(web): reuse restored scratchlist hub attachments without re-upload

Composer draft remount was re-uploading blobs that already had a
hapi-hub:scratchlist path, orphaning the originals against session quota.

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

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-29 10:05:24 +08:00
..
scripts
Clean up cross-package build coupling
2026-05-20 19:29:43 +08:00
src
feat(web,hub): scratchlist v2.2 hub attachment storage (#921) (#1205)
2026-07-29 10:05:24 +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