Skip to content

feat: remote access for mobile clients via zcode-acp-hub - #49

Merged
william0wang merged 18 commits into
mainfrom
feat/remote-access
Aug 17, 2026
Merged

feat: remote access for mobile clients via zcode-acp-hub#49
william0wang merged 18 commits into
mainfrom
feat/remote-access

Conversation

@william0wang

Copy link
Copy Markdown
Owner

Summary

Opt-in remote access so a mobile client can discover and drive editor-hosted
bridge sessions over a single authenticated entry point, plus the client-facing
APIs and replay hardening that came out of live testing.

What's in here

Remote access core (opt-in via ZCODE_ACP_REMOTE=1)

  • Loopback ACP endpoint serving the same AgentApp as the stdio editor
    (remote/endpoint.ts, ADR-0001: bridge lifetime still follows the editor)
  • zcode-acp-hub machine-level singleton: token auth, instance discovery,
    byte-level WS proxying, heartbeat-TTL pruning, idle exit (ADR-0002)
  • Multi-client broadcast registry: notifications fan out to all attached
    clients; requests are first-response-wins with loser cancellation
  • Hub lifecycle: version handshake (stale hub self-exits and is re-spawned
    from the upgraded install) and on-demand ?probe=1 liveness so a client
    refresh gets an immediately-honest instance list

Client-facing APIs

  • session/load tail replay with _meta.zcode.limit, replayMeta, and
    session/load_earlier cursor pagination (Proposal 0001 / ADR-0003)
  • account/usage_stats plan quota (GLM + Opencode Go combined), pull-only,
    failures degrade gracefully (Proposal 0002)

Hardening from live testing

  • Slash prompts that are not advertised commands are neutralized and sent as
    plain text (fixes path-like /dir inputs killing the turn)
  • Replayed user messages strip harness <system-reminder> blocks so clients
    never render them as user input
  • Stored session titles adopted on load/resume for discovery

Verification

  • 568 tests passing across 37 files; typecheck, lint, build clean
  • Manually verified end-to-end: hub registration/respawn, proxied initialize,
    backend-death → unregister chain, probe pruning

Docs

docs/REMOTE-CLIENTS.md (client integration contract), ADR-0001/0002/0003,
proposals 0001/0002, architecture updates.

@william0wang
william0wang merged commit 59c5bbb into main Aug 17, 2026
1 check passed
@william0wang
william0wang deleted the feat/remote-access branch August 17, 2026 10:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant