Skip to content

feat: HTTP quota and session-status endpoints for remote clients - #59

Merged
william0wang merged 1 commit into
mainfrom
feat/http-quota-status
Aug 20, 2026
Merged

feat: HTTP quota and session-status endpoints for remote clients#59
william0wang merged 1 commit into
mainfrom
feat/http-quota-status

Conversation

@william0wang

Copy link
Copy Markdown
Owner

Background

Remote clients (the mobile app) had to open a full ACP WebSocket — connect, initialize, request, disconnect — to read account quota or per-session running status. Both are poor fits for the session protocol: quota is account-level (the machine's credentials, not any session/instance), and running status is a polling concern, not a stream.

Changes

  • GET /api/quota (hub): queries accountUsageStats() directly — the same function behind the /quota command and the account/usage_stats ACP method — with a ~30s TTL cache plus a single in-flight slot so polling can't hammer the upstream. Response body is identical to the ACP method's result, so clients reuse one parser. The ACP method stays for attached editors.
  • GET /status (bridge loopback, new src/remote/status-endpoint.ts): pure in-memory assembly — sessionSummaries membership + pendingTurns derivation (same turnActive logic as session/load), no backend RPC, safe to poll at 1–2s.
  • GET /api/instances/{id}/status (hub): byte-level proxy to the bridge route, same pattern and error semantics as /fs (401 / 404 unknown instance / 502 unreachable).
  • Heartbeat status field: sessions[] entries carry a coarse running | idle; hub validSessions passes valid values through and strips invalid ones. Compatible both directions (older hub drops the field; older bridge omits it).
  • Docs: new endpoint chapters + 502 troubleshooting row in REMOTE-CLIENTS.md, architecture summary, and docs/adr/0005-http-quota-and-status-endpoints.md recording why the hub queries quota directly (machine-level concern, must answer with zero bridges alive; version drift covered by the existing self-upgrade handshake).

Out of scope (noted in the ADR as additive extensions): waiting_permission status, background-task details.

Test plan

  • pnpm typecheck, pnpm lint, full suite green (644 tests, +17 new)
  • hub quota: 401, payload passthrough, TTL cache hit, 502 without caching the failure, non-GET falls through to 404
  • hub status proxy: byte passthrough, 401, 404 unknown instance, 502 dead bridge
  • discovery status field: valid passes through, invalid stripped
  • bridge /status: running/idle derivation incl. cancelled-but-finalising parity, membership gates, ordering, HEAD/405

- GET /api/quota on the hub queries accountUsageStats directly (machine-level
  concern, no ACP round-trip) with a 30s TTL cache and in-flight dedupe
- bridge GET /status (in-memory pendingTurns derivation, no backend RPC)
  byte-proxied by the hub at GET /api/instances/{id}/status
- heartbeat sessions[] carries a coarse status field; hub validSessions
  passes valid values through and strips invalid ones
- docs: REMOTE-CLIENTS endpoints/chapters, ARCHITECTURE summary, ADR-0005
@william0wang
william0wang merged commit 8b113bf into main Aug 20, 2026
1 check passed
@william0wang
william0wang deleted the feat/http-quota-status branch August 20, 2026 02:04
@william0wang william0wang mentioned this pull request Aug 20, 2026
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