Two protocols

Clients never speak Runner Protocol. Runners never expose Agent Protocol.

Agent Protocol (front door)

Threads, runs, streaming — the public, framework-agnostic client API. SDKs and HTTP clients live here. This is what product UIs and automations call.

• Create thread → create run → wait or stream
• Cancel / interrupt / resume for HITL
• No knowledge of which runner pod holds the job

Runner Protocol (back door)

Runkite’s internal contract: pull job, stream events, heartbeat, reclaim/fencing. Workers authenticate with runner tokens and never publish a public Agent surface.

• Dequeue assignment with generation / fencing token
• Heartbeat; on superseded: true cancel local work
• Report status / stream events; stale generation is ignored

Why not one protocol

Collapsing them either leaks reclaim/fencing internals to every client, or starves workers of the semantics they need to fail closed under partition. Keep the seam.

Chapter: two protocols · getrunkite/runner-protocol · runner-protocol/PROTOCOL.md · docs/api.md