Add persistent Run control stream

2026-08-26 23:05:40 +08:00
parent 3b4e857ef7
commit ac14f80306
8 changed files with 245 additions and 9 deletions
@@ -6,6 +6,7 @@ Control is the lightweight high-priority channel between run and platform.

 - `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

@@ -13,12 +14,15 @@ Control is the lightweight high-priority channel between run and platform.
 - `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, log upload, and artifact transfer.
 - Heartbeat capacity summaries must remain metadata-only and must not mention or carry heavy channel payloads.