Documentation / Runs / Operate

Resolve waits and control Runs

Resolve human decisions, steer active work, and apply pause, resume, interrupt, cancel, Policy, rebind, truncate, or branch controls.

Before you begin

Open the exact namespace, Agent, Session, and Run address. Read current state from Run detail or the open-Wait endpoint; analytics and archived traces are historical evidence and cannot authorize a control. Every mutation needs a caller-stable eventId or documented idempotency key and its specific Policy action. Repeating an accepted identifier returns the recorded outcome rather than applying another control.

Steps

  1. List open waits with GET .../sessions/:session/waits, then exact-read the selected Wait. Resolve it with POST .../waits/:promiseId/resolve and body { "eventId": "approval-42", "value": ... }. The value must satisfy the schema, deadline, and byte bound pinned when Agent code called ctx.await().
  2. Add fresh operator or user direction through POST .../sessions/:session/steers with a bounded eventId, text, and optional data. Actor identity is derived from authentication, never accepted from the body.
  3. Pause at a safe point with POST .../runs/:run/pause; continue through /resume. Resume requires an explicit eventId.
  4. Interrupt with /interrupt. safe-point preserves the normal boundary; abort additionally requires run:abort and stops current work before continuing.
  5. Cancel through /cancel when no future work should run. Committed facts and audit history remain.
  6. Use /policy to change exactly one Policy hash, turn limit, or micro-USD budget at a safe point. For /rebind, use addBindings to attach new exact CRN/hash pins without replacing existing bindings, bindings for a complete fixed map, or neither to refresh scoped assignments from the Run's accepted authority. See Add a Resource during a Run.
  7. Use /truncate to move the same Run’s history to an earlier fact with required steering text. Use /branch when the original history must remain and a new Run should continue from the selected fact.

Verify

Read the control receipt, then refresh the exact Run or Session detail that it identifies. Pause is applied at scheduler=paused; resume at scheduler=dispatchable; cancellation at status=stopped with error=Cancelled; Policy and Resource changes are applied only after their requested safe-point scheduler state clears and the new hash or limit appears. Steering and Wait resolution finish when their exact Session event is durably accepted—they do not wait for the whole Run to finish. Verify a steer by its exact event id, sequence, Run, and payload. Verify Wait resolution by its exact Promise, Run, and completion sequence, followed by 404 Not Found for that same open Wait.

For truncation, require both the completed control/<eventId>/truncate journal entry at the requested Fact and its derived steer. For branching, read the receipt-allocated fork and confirm its parent Run, base Fact, input, Policy hash, and Resources hash. A sibling Run, another event, or an accepted control that still reports a requested safe point is not completion. When a Resource call has an unknown outcome, reconcile it according to the operation contract before resuming.

Next steps

Use Inspect a Run for journal paging and Stream a Run for reconnectable output. Review Durable execution for the Agent-side wait and handle contract.