mirror of https://github.com/wu736139669/hapi.git synced 2026-11-12 02:28:05 +00:00

Files

T

SSU-WEI HUANGandGitHub f0e5ba9c0f feat(codex): mid-turn Steer via app-server turn/steer (#888 ) (#1606 )

* feat(shared): steer capability gates and live steered signal schemas

- STEERING_SUPPORTED_FLAVORS / isSteeringSupportedForSession gate which
  agents can deliver queued messages into the active turn (pi, codex,
  cursor ACP; legacy stream-json cursor excluded)
- AgentState.steeringActive, DecryptedMessage.steered and
  messages-consumed  live signal (never persisted by the hub)

* feat(cli): queue reservations and steered messages-consumed option

- MessageQueue2 gains takeByLocalId/restoreReservation/
  beginReservationDispatch/commitReservation so an async steer can reserve
  a queued row without racing the main loop's turn/start drain
- emitMessagesConsumed accepts steered: true to mark mid-turn delivery

* feat(codex): mid-turn steer via app-server turn/steer (#888)

- CodexAppServerClient.steerTurn + TurnSteerParams/Response types
- CodexRemoteLauncher registers the steer-queued-message RPC handler:
  reserves the queued row, validates it against the active turn (no
  control commands, matching mode hash), injects via turn/steer with an
  epoch guard that invalidates in-flight steers on abort/cleanup
- steeringActive agent state tracks the active-turn window
- hub syncEngine gate opens to codex; messages-consumed relays steered

* feat(web): Steered badge and steer gating for codex sessions

- HappyUserMessage shows a ↳ Steered badge fed by the live
  messages-consumed steered signal, preserved across server echoes and
  refetches (mergeMessages carries the optimistic marker)
- SessionChat gates canSteer via isSteeringSupportedForSession instead of
  the pi-only check
- clearStaleQueuedStatus normalizes a queued status on an invoked message
- fix(web): drop duplicate showSessionSummaryInChat in markdown test
  (upstream typecheck breakage)

* fix(codex,shared): address bot findings on steer gate and ambiguous turn/steer

- STEERING_SUPPORTED_FLAVORS / isSteeringSupportedForSession advertise
  codex and pi only; cursor joins when its soft-steer handler lands (#1609)
- turn/steer now splits dispatch (stdin accepted) from completion (turn
  finished): the hub RPC acks once dispatch succeeds — never on the
  concurrent turn's completion, which can exceed the 30s RPC window
- queue row commits only after the turn settles; a rejected/aborted steer
  restores the row so the message still delivers via turn/start, and a
  dispatched steer is never restored (no duplicate delivery)
- steer carries clientUserMessageId (echoed as userMessage.clientId) so
  ambiguous transport failures can reconcile the thread later
- client tests cover dispatch/complete split and stdin-write failure

* fix(codex): reconcile dispatched steers before restoring; align error copy

- A dispatched turn/steer whose completion fails (disconnect / protocol
  error) is now reconciled via thread/read by clientUserMessageId before
  the queued row is restored — the instruction is only re-delivered by
  turn/start when the thread never received it
- Reconcile targets the pinned steer thread, not whichever turn is
  current when completion fails
- syncEngine unsupported-flavor error now matches the capability gate
  (Pi and Codex only until the cursor handler lands)
- launcher tests cover steer success (ack on dispatch), reconcile-accepted
  and reconcile-rejected outcomes

* fix(codex): consume the row at dispatch; drop background reconcile

- The hub RPC acks and the queue row is consumed as soon as stdin accepts
  turn/steer; completion is background-only logging. A dispatched steer is
  never restored, so the same localId cannot be re-delivered via turn/start
  after the caller was told the steer succeeded
- Dispatch failure (stdin write error) still restores the row and reports
  failure
- steer.completed rejection is always handled (no unhandled rejection on
  the dispatch-failure path)
- tests updated: completion failure after dispatch keeps the row consumed;
  dispatch failure restores it

* fix(codex): distinguish definite rejection from indeterminate completion

- Transport-level failures (timeout, abort, disconnect, spawn, protocol)
  carry an indeterminate marker; explicit JSON-RPC error responses do not
- After a dispatched steer, turn completion resolves → commit + consumed;
  a definite app-server rejection restores the row (instruction was never
  accepted, so turn/start cannot duplicate it); an indeterminate outcome
  leaves the row reserved so it can never be delivered twice
- Completion handling registers before awaiting dispatch so the
  dispatch-failure path cannot leak an unhandled rejection
- client/launcher tests cover explicit rejection (restore), indeterminate
  outcome (row stays reserved) and dispatch failure

* fix(codex): reconcile indeterminate steers instead of a permanent reservation

- After an indeterminate completion (disconnect/protocol), reconcile the
  thread by clientUserMessageId immediately: accepted → commit + consumed,
  provably rejected → restore, still unreadable → keep the reservation and
  retry from the main-loop top on later passes (post-reconnect)
- A row never sits in dispatching forever: the hub cannot stamp it invoked
  while the instruction may never have been accepted
- tests: indeterminate keeps reserved while thread unreadable; accepted
  reconciliation consumes; rejected path restores

* fix(codex): accept all thread item shapes; retry reconcile; ack through abort

- Reconcile matcher accepts userMessage/user_message with clientId/
  client_id, matching the shapes the thread parser supports — an accepted
  steer can no longer be misclassified as rejected
- A pending reconciliation schedules a wakeLoop retry, so a temporary
  app-server outage cannot strand the reservation behind waitForTurnOrRecovery
- The success-path ACK no longer checks the steer epoch: the hub already
  reported steered on dispatch, so commit + messages-consumed must reach
  it even when an abort resets the queue in between

* fix(codex): reinit reconnected app-server; keep reconcile retries alive

- thread/read after a disconnect auto-connects a fresh app-server, which
  must be initialized before any request — reconcile now ensures
  connect + initialize (isConnected getter added to the client)
- every still-unknown loop-top reconciliation schedules the next retry,
  so recovery without external traffic is eventually observed
- launcher mock gains isConnected

* fix(codex): timer-driven reconciliation; init tracking; abort-safe ACK

- Reconciliation runs on a self-rescheduling 1s timer independent of the
  main loop (wakes it too), so idle loops and waitForTurnOrRecovery still
  observe app-server recovery; abort clears nothing implicitly — the ACK
  path commits and consumes even when the reservation was cancelled
- Absence of a durable client id is ambiguous: unmatched reads stay
  'unknown' and keep retrying instead of restoring the row
- CodexAppServerClient tracks initialized state (reset on disconnect/exit)
  so ensureAppServerInitialized re-initializes a fresh process before
  thread/read; initialize failures leave the flag false for the next retry
- tests: accepted reconciliation via scheduled timer, indeterminate
  keeps reserved, explicit rejection restores

* fix(codex): bind reconciliation to the launcher lifecycle

- runSteerReconciliation clears any armed retry timer on entry and never
  installs a second one, so loop-top and timer-driven passes cannot
  multiply
- shuttingDown is set when the main loop ends: timers are cleared and the
  pending map is dropped, so an unresolved steer can never respawn an
  app-server after cleanup (remote-to-local switch included)

* fix(codex): report steered only after app-server acceptance

- The handler now awaits steer.completed (the inject-acceptance response):
  an explicit JSON-RPC rejection surfaces as failed and restores the row
  for the normal turn/start path instead of a false steered
- Transport failure after dispatch reports 'Steer outcome is being
  reconciled' and keeps the row reserved while the timer-driven thread
  reconciliation runs
- dispatch-failure path also swallows the paired completion rejection

* fix(steer): tri-state cancel, clear-safe reservations, bounded acceptance wait

- MessageQueue2.cancelByLocalId returns 'in-flight' for a dispatching
  steer reservation: the hub neither deletes the row nor stamps invoked_at
  (new CancelMessageResponse 'busy' status; web restores the optimistic
  row); pushIsolateAndClear and reset/close share cancelReservations so
  /clear-style commands cannot have a rejected steer resurrect a discarded
  prompt
- turn/steer acceptance wait bounded at 25s (< hub 30s RPC timeout): a
  lost response is indeterminate and funnels into thread reconciliation
  instead of stranding the reservation
- tests updated for the tri-state cancel contract

* fix(codex,web): busy-aware edit flow; bound reconciliation reads

- QueuedMessagesBar edit flow treats a 'busy' cancel as unsuccessful: it
  never prefills the composer when the row is inside an async steer, so a
  second client cannot send a duplicate
- reconcileSteerByClientId bounds thread/read with a 5s timeout so a
  connected-but-silent app-server cannot hold the reservation in-flight
  indefinitely

* fix(steer): inFlight-dominated cancel acks; bounded reconciliation

- hub cancel-queued-message acks check inFlight before removed: a stale
  duplicate socket reporting removed can no longer delete the durable row
  while another socket is dispatching the steer
- reconciliation entries expire after 60s and mark delivered: after the
  rejection window, a dispatched steer that the app-server never proved
  (client ids dropped on restart) is committed instead of polling
  thread/read forever
- pre-dispatch failures (abort before write included) never enter
  reconciliation — they restore the row and report failure

* fix(steer): persist indeterminate outcomes without replay

* fix(steer): make ambiguous delivery restart-safe

* fix(steer): recover crash-held rows and preserve retry dedup

* fix(steer): ack retries and bound stdin dispatch

* fix(steer): reconcile indeterminate dispatches and serialize retries

* fix(codex): classify stdin callback failures as indeterminate

* fix(steer): recheck indeterminate cancels after ACK

* fix(steer): close retry and abort races

* fix(steer): serialize live retries and abort admission

* fix(steer): distinguish live dispatching from unknown

* fix(steer): keep ACK failures held and reconcile busy cancel

* fix(steer): distinguish held cancel from removal

* fix(store): combine schema v24 migrations

* fix(store): reserve schema v25 for steer delivery state

* fix(steer): keep held cancel state and notify requeue

* fix(steer): release explicitly cancelled unknown reservations

* fix(codex): reject cancelled reservations before native steer

* fix(codex): make reservation restore atomic with state

* fix(codex): terminate abandoned transport writes

* fix(steer): own abandoned app-server lifecycle and consume races

* fix(codex): confirm dispatch and recover abandoned turns

* test(codex): mock abandoned transport callback

* fix(codex): clear visible turn state on transport loss

* fix(steer): claim retries and cover native delivery state

* fix(native): preserve indeterminate state on Android hydration

* fix(steer): make retry claims single-winner

* fix(steer): serialize concurrent retry claims

* fix(socket): tolerate missing steer-state ACK callbacks

* fix(native): serialize retry operations

* docs(web): document unknown steer delivery and retry controls

* fix(steer): handle retry failures and abort-before-connect

* fix(steer): reinitialize after transport loss and finish iOS retry errors

* fix(steer): preserve indeterminate rows across reconnect gaps

* test(web): mock indeterminate queued recovery state

* fix(steer): recover consumed ACK tombstones

* fix(steer): expose consumed cancel tombstones

2026-08-19 20:07:39 +08:00

scripts

feat(hub): add message content codec for storage optimization

2026-08-02 13:21:32 +08:00

src

feat(codex): mid-turn Steer via app-server turn/steer (#888 ) (#1606 )

2026-08-19 20:07:39 +08:00

package.json

Clean up cross-package build coupling

2026-05-20 19:29:43 +08:00

README.md

feat(settings): onboard hub provider credentials for dictation and voice (#1392 )

2026-08-07 13:20:03 +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)

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

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.

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

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

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

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

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):

Build and deploy web/dist from the repo root.
Set CORS_ORIGINS (or HAPI_PUBLIC_URL) to the static host origin.
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.

README.md

hapi-hub

What it does

Configuration

Required

Optional (Telegram)

Optional (Voice)

Optional

Running

HTTP API

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

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

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

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

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

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

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

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

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

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

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

Socket.IO

Client events (CLI to hub)

Terminal events (web to hub)

Hub events (hub to clients)

Telegram Bot

Commands

Features

Core Logic

Storage

Source structure

Security model

Build for deployment

Networking notes

Standalone web hosting

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

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

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

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

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

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

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

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

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

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

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