# Runs

**Runs** are single, bounded executions of an **Intent** under explicit guardrails (**Context**, **User ID**, **Integration Selection**, **Approval Strategy**). A run plans, calls tools, streams events, and produces a final state and optional result.

### Why Runs exist

* Provide a durable unit of work you can audit and reason about.
* Keep actions tenant - and user-scoped (tokens tied to `userId`).
* Enforce safety via approvals and allow-listed integrations per run.
* Offer live observability via SSE and a consistent state model.

### Anatomy of a Run

* **Identity**: `runId` (UUID)
* **Intent**: outcome you want (natural language)
* **Context**: hidden execution parameters (timezone, filters, IDs, flags)
* **User ID**: whose permissions/tokens apply (act-as-user)
* **Integration Selection**: `selectedCustomerIntegrationIds` allow-list or `"*"` (all active)
* **Approval Strategy**: `NONE` | `ON_START` | `ON_TOOL_CALL`
* **Plan**: `text` or `json` (returned in `CreateRunResponse`)
* **Events (SSE)**: realtime lifecycle & step logs
* **Result**: optional structured output on completion

### Lifecycle

QUEUED → RUNNING → (AUTH\_REQUIRED | PAUSED)\* → (SUCCESS | FAILED | CANCELED)

* **QUEUED** — accepted, waiting to start
* **RUNNING** — planning/executing; events stream over SSE
* **AUTH\_REQUIRED** — needs user authorization (OAuth/token); auth link appears in SSE and Run events
* **PAUSED** — waiting for approval decision (`GET /v1/runs/approval?token=...`)
* **SUCCESS/FAILED/CANCELED** — terminal states; inspect logs, `stepsFinished`, and `result`

### Planning vs Execution

* **Planner** builds a plan (text/json) from Intent & Context within the limits of selected integrations and approval strategy.
* **Executor** performs tool calls, enforces approvals, rate limits, and emits events.

### Approvals (human‑in‑the‑loop)

* `NONE` — fire-and-forget.
* `ON_START` — approve the plan before any calls.
* `ON_TOOL_CALL` — approve each external call (recommended for production writes).

### Identity & Scope

* `userId` defines which tokens are used. Choose least privilege.
* `selectedCustomerIntegrationIds` limits which tools are callable this run.

### Observability

* Subscribe to `GET /v1/runs/{runId}/sse` for: `status`, `step.started`, `step.completed`, `approval.required`, `approval.resolved`, `result`, `error`.
* Use `GET /v1/runs/{runId}` to fetch the latest state; `stepsFinished` summarizes work done.

### Cancellation & retries

* Abort queued/running runs: `DELETE /v1/runs/{runId}`.
* To retry after failure or cancellation, create a **new run** with corrected context/auth.

### Best practices

* Write **declarative** intents; avoid how-to steps.
* Put sensitive/technical details in **Context** (not user-visible).
* Start strict with `ON_TOOL_CALL`; relax as confidence grows.
* Prefer explicit allow-lists over `"*"` in production.
* Batch responsibly (limits in Context), and watch SSE during rollout.