CSE Roadmap

Core tier · about 3 hours · 12 parts

Part 10 of 12 · 1 min read

Quick notes

  • An agent run can take minutes, so a single blocking HTTP request is the wrong interface. Use a job API: POST /runs returns 202 with a job id, the client polls or receives a webhook, and DELETE /runs/{id} cancels.
  • Sync fails twice over: proxies time out before the run ends, and client retries make the server run the same job again.
  • Idempotency keys stop duplicate jobs. Same owner, key and body returns the original job; same key with a different body returns 409.
  • The job is a state machine (queued -> running -> succeeded | failed | cancelled), terminal states never change, and the status endpoint returns Retry-After while running and 404 for another owner's job.
  • Webhooks are far cheaper than polling but are at-least-once, so sign them, check the timestamp, and dedupe by a stable event id. Users must be able to cancel.