35 lines
2.0 KiB
Markdown
35 lines
2.0 KiB
Markdown
# Run Control Contract
|
|
|
|
Control is the lightweight high-priority channel between run and platform.
|
|
|
|
## Implemented Routes
|
|
|
|
- `POST /api/v1/run/control/hello`: registers run metadata and receives a platform-issued session token.
|
|
- `POST /api/v1/run/control/heartbeat`: reports status, capacity, and capability fingerprint using the active session token.
|
|
- `POST /api/v1/run/control/events`: opens a signed `text/event-stream` control channel. Platform sends small wake events such as `control.ready`, `control.heartbeat`, and `job.changed`; Run then claims durable jobs through the job channel.
|
|
|
|
## Payloads
|
|
|
|
- `RunHelloRequest`: registration token, run ID, display name, version, status, platform, capability summary, and capacity summary.
|
|
- `RunHelloResponse`: session token, server time, polling hints, and feature flags.
|
|
- `RunHeartbeatRequest`: session token, version, status, capacity, and current capability fingerprint.
|
|
- `RunHeartbeatResponse`: accepted status, next heartbeat interval, and optional capability refresh request.
|
|
- `RunControlStreamRequest`: run ID, session token, and the last event sequence observed by Run.
|
|
- `RunControlEvent`: run ID, monotonic endpoint-local sequence, event type, server time, and reconnect hint.
|
|
- `RunCapabilityReport`: capability names and compact fingerprint metadata.
|
|
- `RunCapacityReport`: max jobs, active jobs, queued jobs, and local resource summary.
|
|
|
|
## Rules
|
|
|
|
- Control payloads must be small.
|
|
- Control events wake Run only; they must not carry job assignments or execution input.
|
|
- Control must not carry logs, artifact chunks, or long job result bodies.
|
|
- Control must have priority over job execution, current live log relay, and artifact transfer.
|
|
- Heartbeat capacity summaries must remain metadata-only and must not mention or carry heavy channel payloads.
|
|
|
|
## Deferred Channels
|
|
|
|
Live log relay, artifact chunk transfer, and the optional game client bridge
|
|
remain separate channels. The job channel is separate from control and uses
|
|
`/api/v1/run/jobs/*` routes.
|