mirror of
https://github.com/wu736139669/hapi.git
synced 2026-08-05 06:24:37 +00:00
Junmo KimandGitHub
08fbea5311
* feat(cli): allocate a loopback port for the OpenCode ACP subprocess
opencode does not announce which port it bound when launched with
--port 0 (verified: not present in stdout/stderr even at DEBUG level),
so pick a free loopback port ourselves and pass it explicitly via
--port/--hostname. This makes the ACP subprocess's internal HTTP API
reachable at a known baseUrl for follow-up work (native /compact
bridging).
* feat(cli): add REST bridge for OpenCode native session compaction
opencode's ACP method table has no session/compact RPC, but the
opencode acp subprocess also runs an internal HTTP API. That API's
POST /api/session/:id/compact route is an unimplemented v2 stub
(always 503); the route that actually performs native AI compaction
is the legacy POST /session/:id/summarize, which requires providerID
and modelID in its payload. This adds a small client for that route
plus a helper to split ACP's combined "provider/model" wire id.
Not wired into the slash-command flow yet.
* feat(cli): trigger native OpenCode compaction from /compact
Wires the REST bridge into the OpenCode slash-command flow so /compact
performs real context compaction instead of returning a "not yet
supported" message.
- slashCommands.ts: /compact now resolves to its own `kind: 'compact'`
(the synchronous 'handled' shape can't carry an async REST round
trip). /clear is unchanged.
- opencodeRemoteLauncher.ts: registers a compact trigger callback once
the ACP backend + internal HTTP baseUrl are ready, reading the
session's current provider/model on every call so it reflects
inline model switches. A `runExclusive` promise-chain mutex
serializes the compact trigger against `backend.prompt()` so a
still-in-flight prompt and a `/compact` sent moments later can't
race against the same OpenCode session concurrently, in either
arrival order.
- runOpencode.ts: on /compact, emits "Compaction started" as a session
event (the same `sendSessionEvent({ type: 'message', ... })` status-
line channel Claude/Codex already use for compaction and other
transient state, rather than a chat message), awaits the bridge with
no artificial timeout (compaction on a reasoning model can take
90s+), then emits "Compaction completed" or "Compaction failed:
<reason>" the same way. Falls back to the previous not-yet-supported
chat message when no trigger is registered (local mode has no ACP
backend, so this is unreachable there today). If the user cancels
the message while compaction is queued or in flight, the eventual
result is suppressed instead of surfacing a stray status message
for an action the user already considered cancelled (aborting the
in-flight HTTP call itself is left as follow-up scope).
- help text now notes /compact is remote-sessions only, since local
mode has no ACP backend to bridge through.
Also fixes a runOpencode.test.ts fixture gap: the mocked
OpencodeSession was missing onThinkingChange, so any exception in that
call path was silently swallowed by the handler's outer catch instead
of failing the test.
* feat(cli): show compaction summary as a reasoning block
After a native OpenCode compaction succeeds, OpenCode's session
history gains a `role: "user"` marker message (a `{type:"compaction"}`
part with no text) followed by a normal assistant message holding the
actual generated summary in a `text` part. Left alone, neither is
visible in HAPI — the bridge only checked success/failure and never
looked at the resulting messages.
- opencodeCompactBridge.ts: `fetchCompactionSummary()` does one more
GET against the session's message list after a successful compact,
finds the most recent `type:"compaction"` marker, and extracts the
following assistant message's text — preferring a match via the
marker's `parentID` (order-safe) and falling back to simple array
adjacency, both gated on `role === 'assistant'` so an unrelated
same-shaped sibling can't be silently misattributed as the summary.
Concatenates every `text` part in case a summary spans more than
one. Never throws: any unexpected shape or request failure just
yields "not found" so the caller can skip showing anything.
- opencodeRemoteLauncher.ts / runOpencode.ts: on a successful compact,
forward the extracted summary as a `{ type: 'reasoning', text, id }`
AgentMessage through the same `handleAgentMessage()` /
`convertAgentMessage()` path OpenCode's own live thought-chunk
streaming already uses, so it renders in the existing collapsible
"Reasoning" block — no new UI component or schema field. The
`role:"user"` marker is never constructed or forwarded at all, so
there's nothing to filter (unlike Claude's compact summary, which
is hidden after the fact via an `isCompactSummary` flag).
* fix(cli): disable Bun's hardcoded fetch timeout for OpenCode compaction
Isolated E2E against a real OpenCode session showed compaction always
failing with "Compaction failed: The operation timed out." after
~250s, even though session/prompt-style unlimited waits were intended.
Root cause: Bun's global fetch() hardcodes an internal ~5 minute
timeout that fires independently of any AbortSignal (or its absence) —
see oven-sh/bun#16682. The only documented workaround is passing the
non-standard `timeout: false` fetch option that Bun itself recognizes.
Cast through a local `BunFetchInit = RequestInit & { timeout?: false }`
type alias rather than `Record<string, unknown>`, so the option stays
structurally checked against the rest of the fetch call's shape.
* fix(cli): serialize /compact through the message queue instead of a mutex
HAPI Bot flagged two Major correctness issues on the PR:
- `/compact` bypassed `MessageQueue2` and entered a `runExclusive` mutex
directly from the user-message handler. If prompt A was in flight and
prompt B already queued behind it, `/compact` sent afterward could
still reach the mutex before B did, running compaction ahead of an
earlier-queued user prompt.
- `compactTriggerRef` (a closure capturing the remote backend) was
never cleared on a remote→local handoff, so `/compact` typed after
switching to local mode could call a stale closure targeting an
already-disposed backend instead of the intended local-mode fallback.
Removes the mutex entirely and routes `/compact` through the same
`messageQueue` regular prompts use (a new `operation?: 'compact'` field
on `OpencodeMode`, dequeued by the launcher's single sequential
consumer loop, which branches to a new `runCompactOperation()` instead
of `backend.prompt()`). Ordering is now enforced by construction (one
queue item in flight at a time) rather than a second bolted-on lock.
Replaces the closure-based `onCompactTriggerReady` callback with a
boolean-flag `onCompactAvailabilityChange`, reset to `false` on every
entry into local mode (cold-start and handoff alike) before the remote
backend is even disposed, so there is no window where the flag says
available but the backend underneath it is gone.
* fix(cli): let /compact's cancel ack fire at dequeue time, not on queue
A follow-up HAPI Bot review caught a Major issue this PR's queue-based
/compact serialization (previous commit) left open: runOpencode.ts
still called session.emitMessagesConsumed manually and synchronously
the instant /compact was pushed onto the queue -- a leftover from
before /compact was routed through the queue at all. That beat
MessageQueue2's automatic dequeue-time ack (onBatchConsumed, wired in
sessionBase.ts, already used by every regular prompt) to the hub, so a
/compact sitting behind other queued prompts was marked "invoked"
immediately and could never actually be cancelled from the UI.
Removes the manual ack; the queue's own dequeue-time ack now covers
/compact exactly like any other queued operation. Adds a deterministic
test for the reported scenario: prompt A generating, /compact queued
behind it, cancelled before A finishes -- the compact REST bridge must
never be called.
* fix(cli): suppress live ACP updates while a compact REST call runs
Found via live use: OpenCode keeps streaming session/update
notifications (thought chunks, etc.) over the ACP transport while
/compact's REST call runs outside prompt(), and
AcpSdkBackend.handleSessionUpdate forwarded them unconditionally to
whatever messageHandler was still installed from the last real prompt
turn -- rendering the compaction summary a second time as a plain
assistant message, alongside the explicit Reasoning block this PR
already sends for the same content.
Adds a narrow, opt-in AcpSdkBackend.suppressUpdatesDuring() (shared
with Gemini, but a pure addition with no behavior change for existing
prompt() callers) that temporarily swaps out the message handler for
the duration of an async callback, restoring it afterward. Wraps the
compact bridge's REST call with it so the live stream produces no
output during that window -- the Reasoning block built from the
explicit GET response becomes the only place the summary appears.
* fix(cli): let Stop/switch-to-local interrupt an in-flight /compact REST call
triggerOpencodeCompact's HTTP request is intentionally unbounded (a
real compaction can take minutes), but the launcher awaited it with no
way to interrupt it once dequeued and running. handleAbort() only
cancels the ACP prompt() turn and resets the queue -- neither touches
this raw HTTP call -- so Stop (and switch-to-local, which routes
through the same handler) stayed blocked until the request settled on
its own: a stale "Compaction completed/failed" could still surface
afterward, queued prompts behind it were delayed, and remote->local
handoff couldn't proceed.
Add a per-call AbortController (compactAbortController) that
handleAbort() aborts before cancelling the prompt, and thread it
through triggerOpencodeCompact's new optional `signal` (kept separate
from the existing timeout:false Bun workaround, which stays
unconditional). An aborted call now folds into the same isCancelled()
check that already suppresses a stale result for the existing
queue-cancel race, so either kind of interruption behaves the same
way.
* fix(cli): structurally close remaining /compact abort/lifecycle races
Two more narrow races surfaced in review, both symptoms of ad hoc
per-site fixes rather than a shared mechanism:
1. The signal threaded through triggerOpencodeCompact (the POST) did
not also reach fetchCompactionSummary (the GET runCompactOperation
makes right after it), so Stop/switch-to-local could still block on
that call alone. Introduce OpencodeCompactCallOpts with `signal`
required (not optional) so every HTTP step opencodeCompactBridge.ts
makes on behalf of one /compact operation is forced by the compiler
to accept it, not left to remembering to wire it in per call site.
2. /compact availability (runOpencode.ts's compactSupported flag) was
only reset to false on the *next* local-mode entry (loop.ts's
runLocal callback), leaving a window between "switch/exit was
requested" and "local mode actually started" where a /compact
arriving mid-transition could still queue, and -- since local mode
hands straight back to remote when it finds a non-empty queue --
run anyway despite the user having already left remote mode. Add an
onLeavingRemote() hook to RemoteLauncherBase (no-op default, so the
other six flavors built on it are unaffected) called synchronously
as the very first action of requestExit() -- closing the race at
its source -- and again unconditionally in start()'s finally block
as a backstop for exit paths that never call requestExit() at all
(an exception thrown from runMainLoop, for instance).
OpencodeRemoteLauncher overrides it to flip availability false;
loop.ts's local-entry reset is removed as redundant now that
leaving remote is what's authoritative.
* fix(cli): create compactAbortController before the inline model/effort switch
A hostile-review whole-feature sweep of the /compact abort/lifecycle
surface (round 5) found that the dequeue loop applied the per-batch
inline model/effort switch (real async ACP round-trips that yield to
the event loop) *before* branching into runCompactOperation(), which
is where compactAbortController used to get created. An abort firing
during that switch hit a still-null controller (a no-op), and by the
time the switch resolved and runCompactOperation() created a fresh
one, the abort was forgotten -- the compact's unbounded REST call
would then run to completion despite the user having already pressed
Stop/switch/exit.
Move controller creation to the top of the loop iteration, as soon as
the batch is known to be a compact operation, and pass it into
runCompactOperation() rather than having that function create its
own. Also: soften an overstated doc comment about what the required
`signal` field actually guarantees, and add a regression test locking
in that two sequential compact operations each get an independent
controller (no leak or cross-clearing).
* fix(cli): drain quietly before restoring the handler in suppressUpdatesDuring
A 5th PR-review round found that suppressUpdatesDuring restored the
suppressed messageHandler the instant its callback settled, but
aborting the client-side HTTP call (e.g. OpenCode's compact bridge
aborting via compactAbortController) does not necessarily stop the
agent from continuing that operation server-side -- session/update is
a separate notification channel from the HTTP request's lifecycle.
A late straggler notification from a still-running server-side
operation could leak straight into the restored handler (or into a
new one prompt() installs right after).
Reuse the same quiet-drain prompt() already runs before installing a
new handler for the next turn (waitForSessionUpdateQuiet with the
PRE_PROMPT_* constants) -- same class of race, same validated
mechanism, just on the way back in instead of the way out. No new
state or Stop-vs-switch branching: the wait is internal to
suppressUpdatesDuring and the handler stays suppressed throughout it.
* fix(cli): queue /compact during remote-mode initialization instead of rejecting it
compactSupported alone conflated two different situations: a
genuinely local-mode session (compact fundamentally can't run) versus
a session that's already in remote mode but hasn't finished ACP
initialize + session load/new yet (onCompactAvailabilityChange(true)
hasn't fired yet, but will shortly). A regular prompt sent in that
same startup window queues normally and just waits its turn; /compact
sent in the identical window instead got an immediate
not-yet-supported reply.
Check sessionWrapperRef.current?.mode (the actual OpencodeSession
instance's mode, synced synchronously by onModeChange before either
launcher starts) alongside compactSupported: only genuinely local mode
now gets the not-yet-supported reply. A session already in remote mode
but still initializing queues /compact exactly like a prompt and lets
it settle into its real FIFO position once the launcher is ready.
* fix(cli): don't let the remote-init /compact queuing fix reopen the teardown race
A hostile-review whole-feature sweep found that gating /compact
queuing on sessionWrapperRef.current?.mode alone (26344118) fixed the
startup window but silently reopened the exact race
OpencodeRemoteLauncher's onLeavingRemote() exists to close: mode stays
'remote' for the entire teardown window too (it only flips back to
'local' once runMainLoop() fully unwinds), so a /compact arriving
after switch/exit was requested -- while compactSupported has already
gone false -- queued anyway instead of getting rejected, and could
still run once local mode bounced back to remote to drain a non-empty
queue.
Add compactTeardownInProgress, true from the moment
onCompactAvailabilityChange(false) fires (which -- since the old
reset-on-local-entry was removed -- only ever means "leaving remote",
never "not ready yet") until the session next re-enters remote mode.
Wrap the onModeChange callback opencodeLoop already receives to reset
it back to false on that re-entry. The existing "stops queuing /compact
once availability is reset to false" test didn't catch this because
its mock never set mode to 'remote' during the simulated teardown,
unlike real production timing -- fixed to match.
* fix(cli): keep the dequeue loop blocked on a compact until it really finishes on plain Stop
A 6th PR-review round rejected the quiet-drain mitigation from the
previous round (bounded at ~1.2s) and asked for the originally
proposed fix instead: quiet-drain cannot guarantee a multi-minute
server-side compaction has actually finished, since session/update is
a separate notification channel from the aborted HTTP request's
lifecycle. Unconditionally aborting compactAbortController on any
abort (the previous fix) let the dequeue loop move on to the next
queued prompt while the agent could still be compacting the same
OpenCode session server-side -- breaking the core invariant this
feature's whole queue-based redesign depends on: compact and a prompt
must never touch the same session concurrently.
handleAbort() now takes a leavingRemote parameter. Plain Stop
(leavingRemote=false, the default) only sets compactResultSuppressed
-- the eventual result gets hidden, but compactAbortController is left
alone, so runCompactOperation()'s own awaits keep blocking the dequeue
loop until the real HTTP response arrives, i.e. until the server
actually finishes. Switch-to-local/exit (leavingRemote=true) still
abort the controller for real, since cleanup() disconnects the whole
ACP subprocess right after regardless -- there's no shared session left
to protect there, and the responsiveness fixed in an earlier round
still matters for that path.
The quiet-drain from the previous round (AcpSdkBackend.suppressUpdatesDuring)
is left in place -- it still helps for a compaction that finishes
quickly and for trailing session/update stragglers right after a real
completion, it's just no longer the thing plain Stop relies on for
correctness.
* fix(cli): close 3 gaps a hostile-review pass expected the next bot round to flag
Pre-emptively addresses findings a hostile-review final pass on
65729bb7 judged likely for the next external bot round, since a
communication round-trip costs more than fixing them now:
1. No dedicated test existed for the Stop/switch-to-local RPC-overlap
message-ordering fix (handleAbort() re-reading compactAbortController's
abort state instead of a stale snapshot). The test harness has no way
to observe MessageBuffer/Ink content, so the decision logic that
picks the status message and whether to clear `thinking` is extracted
into a pure, exported selectAbortStatusMessage() function and unit
tested directly against all four (hasCompactInFlight, leavingRemote,
compactAborted) combinations, including the exact overlap case.
2. No test verified compactResultSuppressed doesn't leak between two
sequential compact operations. Added a regression test: a Stop-suppressed
compact #1 finishing for real must not silence a normally-completed
compact #2 queued after it.
3. The "Stop requested — waiting..." status message didn't tell the user
how to actually leave the session (switch-to-local/exit) while a
compaction is deliberately left running. Appended that guidance.
* fix(cli): skip a compact cancelled before its request ever went out
A plain Stop landing during the inline model/effort switch that
precedes a compact batch only set compactResultSuppressed; it never
stopped the dequeue loop from calling runCompactOperation()
unconditionally once that switch resolved, so a cancelled-before-start
compact would still fire a brand new REST request and block the loop
for however long that call takes.
Skip starting the operation when compactResultSuppressed is set and
the controller was never actually aborted (plain Stop leaves the
signal alone by design). Deliberately excludes the
compactAbortController.signal.aborted case (switch/exit) and
isLocalIdCancelled: both must keep falling through to
runCompactOperation() as before, per Round 5's and the
isLocalIdCancelled suite's existing coverage.
* fix(cli): also skip a compact cancelled-before-start via isLocalIdCancelled
Round 7's pre-start skip check only covered compactResultSuppressed
(plain Stop), deliberately leaving isLocalIdCancelled out so as not
to disturb the "Compaction started is never suppressed" tests that
predated that check. But isLocalIdCancelled's backing Set can only
ever be populated during the brief ack-vs-hub-DB-write race before a
queued item's REST call is sent, never while it's actually running
(see runOpencode.ts's cancelledBeforeEnqueue doc comment) — so a true
result here unconditionally means the same "cancelled before it ever
went out" situation Round 7 already handles for plain Stop, and
deserves the same treatment: skip starting the operation instead of
sending "Compaction started" for a request already known to be
discarded.
Updates the two tests that had encoded the old "started is never
suppressed" behavior for this specific signal to their corrected
expectation, and removes a no-longer-consumed mockImplementationOnce
that would otherwise have leaked its failure response into the next
test that actually calls the REST bridge.
* fix(cli): don't resurrect /compact availability after a startup-time switch/exit
onCompactAvailabilityChange(true) fired unconditionally right after
newSession/loadSession resolved, with no way to know a terminal
switch-to-local/exit had already run during that pending ACP round
trip (RemoteLauncherBase.requestExit() sets shouldExit synchronously
before awaiting its handler, so the flag is already accurate at that
point). runOpencode.ts's compactSupported/compactTeardownInProgress
gate treats compactSupported flipping true as reason enough to ignore
compactTeardownInProgress entirely, so this belated true could let a
/compact arriving right after slip into the queue mid-teardown.
Guard the call with the same shouldExit flag requestExit() already
set. The race can only be reached via the terminal UI's onExit/
onSwitchToLocal callbacks (wired up before runMainLoop starts, well
before the RPC 'abort'/'switch' handlers exist), so the regression
test forces isTTY and captures ink's render() props to invoke them
directly.
* fix(cli): clear the hub's queued-thinking grace when a compact is skipped pre-start
The cancelledBeforeStart skip path never calls session.onThinkingChange(true)
(the whole point of skipping), but also never told the hub the queued
item was done. The hub's 15s queued-thinking grace (markMessageQueued,
sessionCache.ts) keeps thinking pinned true regardless of keepalives
until a messages-consumed ack with clearQueuedThinkingGrace arrives,
so the web UI spinner could sit stuck for the full grace window.
Applies the same pattern already used by runOpencode.ts's synchronous
slash.kind === 'handled' path (e.g. /model): an emitMessagesConsumed
ack with clearQueuedThinkingGrace, then an immediate thinking=false
keepalive. This is additive to, not a replacement for, the queue's own
unflagged onBatchConsumed ack — a second ack for an already-invoked
localId is a no-op on the hub's first-write-wins protocol, and
clearQueuedThinkingGrace is keyed by session, not localId, so both are
idempotent.
HAPI
Run official Claude Code / Codex / Cursor Agent / Grok Build / OpenCode sessions locally and control them remotely through a Web / PWA / Telegram Mini App.
Why HAPI? HAPI is a local-first alternative to Happy. See Why Not Happy? for the key differences.
Features
- Seamless Handoff - Work locally, switch to remote when needed, switch back anytime. No context loss, no session restart.
- Native First - HAPI wraps your AI agent instead of replacing it. Same terminal, same experience, same muscle memory.
- AFK Without Stopping - Step away from your desk? Approve AI requests from your phone with one tap.
- Your AI, Your Choice - Claude Code, Codex, Cursor Agent, Grok Build, OpenCode—different agents, one unified workflow.
- Terminal Anywhere - Run commands from your phone or browser, directly connected to the working machine.
- Voice Control - Talk to your AI agent hands-free using the built-in voice assistant.
- Workspace Browser - Opt-in via one or more
hapi runner start --workspace-root <path>flags: browse scoped file trees from the web and start sessions in allowed subdirectories.
Demo
https://github.com/user-attachments/assets/38230353-94c6-4dbe-9c29-b2a2cc457546
Getting Started
npx @twsxtd/hapi hub --relay # start hub with E2E encrypted relay
npx @twsxtd/hapi # run claude code
hapi server remains supported as an alias.
The terminal will display a URL and QR code. Scan the QR code with your phone or open the URL to access.
The relay uses WireGuard + TLS for end-to-end encryption. Your data is encrypted from your device to your machine.
For self-hosted options (Cloudflare Tunnel, Tailscale), see Installation
Docs
Build from source
bun install
bun run build:single-exe
Credits
HAPI means "哈皮" a Chinese transliteration of Happy. Great credit to the original project.