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. Inspect the authoritative status and pending waits before acting. Every mutation needs a caller-stable eventId or documented idempotency key and its specific Policy action. Repeating that identifier must return the recorded control outcome.

Steps

  1. List open waits with GET .../sessions/:session/waits. Resolve one with POST .../waits/:promiseId/resolve and body { "eventId": "approval-42", "value": ... }. The value must satisfy the schema 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 a Policy hash, turn limit, or micro-USD budget at a safe point. Use /rebind only when every new fixed binding satisfies the deployed contracts; scoped rebind derives assignments from accepted authority.
  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 and refresh Run detail. Confirm the journal records the authenticated actor, event id, operation, mode, payload hash, scheduler transition, and resulting status. 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.