Runs (workflow)

The run.* family (6 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.

Cancelrun.cancel

Cancel an in-flight run (fires the AbortSignal a connector honours). { runId }. Idempotent: re-cancel of a terminal run is a no-op (INV-2). Only QUEUED|RUNNING cancels.

Call POST /v/run.cancel with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool run.cancel.

Listrun.list

List runs (filter status?). { status?, limit? }. RLS-scoped; paginated.

Call POST /v/run.list with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool run.list.

Resumerun.resume

Re-drive a FAILED run from its resume_token (M7 recovery; the resume-from-checkpoint twin of run.retry). { runId }. The token is read from the run row itself (never trusted from caller input - it is the durable checkpoint the executor wrote), so a resume cannot smuggle a forged checkpoint. Guarded WHERE status='FAILED' AND resume_token IS NOT NULL: a FAILED run WITH a checkpoint returns to RUNNING (resuming in place, token preserved). A FAILED run with NO resume_token is refused (nothing to resume from - retry from the start via run.retry); a non-FAILED run is refused (no resuming live or done work). RLS-scoped + explicit ws predicate.

Call POST /v/run.resume with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool run.resume.

Retryrun.retry

Re-drive a FAILED run from its resume-token (M7 recovery). { runId }. Idempotent: a retry of a non-FAILED run is refused (only FAILED is re-drivable) - a double-retry is safe.

Call POST /v/run.retry with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool run.retry.

Startrun.start

Pick up a QUEUED run into execution (QUEUED -> RUNNING). { runId }. The forward transition the run-executor takes off the queue: a guarded WHERE status='QUEUED' flip, TOCTOU-safe (exactly one starter wins; a concurrent second start finds a non-QUEUED row). RLS-scoped WITH the explicit workspace predicate (defence-in-depth). A run already RUNNING is the idempotent-OK no-op (already started); any other state (terminal/cancelled) is a Conflict (a done/cancelled run is not re-startable - only a fresh resume re-drives a FAILED one). Clears any stale last_error on start.

Call POST /v/run.start with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool run.start.

Statusrun.status

Read one run’s state + error. { runId }. RLS-scoped + explicit ws pred.

Call POST /v/run.status with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool run.status.