zlh-grind/Codex/API/CURRENT_STATE.md

API — Current State

This file records what is believed to be implemented now.

Readiness / agent state model

• API is the heartbeat authority by polling agents.
• Agent does not push state to API.
• API consumes:
  • /health for liveness
  • /ready for semantic readiness
  • /status for detailed state snapshot
• Portal should rely on API-normalized state, not direct agent state.

Readiness cleanup already done

• agentClient.js centralizes non-streaming agent transport.
• getAgentReady() remains low-level transport.
• isAgentReadyResult() is the shared semantic readiness helper.
• assertAgentReady() uses semantic readiness.
• Poller only caches ready: true when /ready returns semantic success.
• Provisioning requires semantic readiness before success/persist/publish.

Backup support

• API forwards game backup operations.
• Current API route shape:
  • GET /api/game/servers/:id/backups
  • POST /api/game/servers/:id/backups
  • POST /api/game/servers/:id/backups/restore?id=<backup_id>
  • DELETE /api/game/servers/:id/backups/:backupId
• API forwards agent HTTP status codes for backup responses.
• Successful backup responses currently pass through the agent body.
• Non-OK backup responses currently use the shared agent response envelope: { error: <fallback>, details: <agent_body> }.
• Backup response shape normalization remains open.

Agent contract alignment already done

• /start, /stop, /restart forwarded as POST.
• /console/command forwarded as POST JSON.
• /ready is part of poller/readiness logic.

Billing / auth lifecycle

• API issues access tokens and refresh tokens.
• Password reset tokens are stored hashed and exchanged through API routes.
• Stripe billing routes cover checkout, upgrade, downgrade, portal, and current billing state.
• Stripe webhooks are mounted with raw body parsing before normal JSON middleware.
• Billing scheduler starts in-process and performs limited reminder/reconciliation work.
• Admin users are billing-exempt in billing flows.

Hosted IDE proxy

• POST /api/dev/:id/ide-token issues short-lived IDE proxy tokens.
• IDE proxy supports both tunnel paths under /__ide/:id and hosted dev-<vmid>.<suffix> hosts.
• Hosted IDE tokens can be delivered by query parameter and then persisted as the IDE proxy cookie.
• Hosted URL return is controlled by DEV_IDE_RETURN_HOSTED_URL.
• API exposes code-server controls for owned dev containers:
  • POST /api/dev/:id/codeserver/start -> Agent POST /dev/codeserver/start
  • POST /api/dev/:id/codeserver/stop -> Agent POST /dev/codeserver/stop
  • POST /api/dev/:id/codeserver/restart -> Agent POST /dev/codeserver/restart

Still true

• websocket console proxy wiring remains outside agentClient.js
• raw streaming upload proxy behavior remains outside agentClient.js