Run control API
Resolve waits, steer sessions, and apply idempotent safe-point or abort controls to exact Runs.
Every route below begins /v1/namespaces/:namespace/agents/:agent/sessions/:session. Controls are durable authenticated events. Supply the exact Run id and caller-stable eventId; do not infer current state from analytics before mutating it.
| Method | Suffix | Required body or purpose |
|---|---|---|
POST | /waits/:promiseId/resolve | { eventId, value }; value must satisfy the pinned wait schema |
POST | /steers | { eventId, text, data? }; append fresh authenticated guidance |
POST | /runs/:run/pause | { eventId } or idempotency header; stop at a safe point |
POST | /runs/:run/resume | { eventId }; resume and drive dispatchable work |
POST | /runs/:run/cancel | { eventId? }; terminally stop future work |
POST | /runs/:run/interrupt | { eventId, mode, payload? }; mode is safe-point or abort |
POST | /runs/:run/policy | { eventId, policyHash }, { eventId, maxTurns }, or { eventId, maxMicroUsd } |
POST | /runs/:run/rebind | { eventId, bindings } for fixed bindings; scoped targets derive from accepted authority |
POST | /runs/:run/truncate | { eventId, to, text, data? }; move the same history head and steer |
POST | /runs/:run/branch | { eventId, at, text, data? }; create and drive a forked Run |
Abort interruption additionally requires run:abort. A fixed rebind supplies the complete map and cannot change the Agent’s logical model identity or leave a Tool need unsatisfied. A scoped rebind rejects caller-selected targets and resolves current assignments for the Run’s already accepted principal/customer authority.
After every operation, persist the receipt and refresh Run detail. An uncertain external effect is reconciled according to the pinned Resource operation recovery contract; a control does not make blind repetition safe.