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 preserves useful agent semantics such as 404, 409, and readiness-oriented failures where possible.

Agent contract alignment already done

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

Still true

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