# Cursor Runs

> Run lifecycle, streaming, follow-ups, and conversation introspection in the Cursor SDK. Use when consuming agent output, handling progress events, or chaining turns.

- Skill: `hktitan/cursor-runs` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add hktitan/cursor-runs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hktitan/cursor-runs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: HKTITAN (https://skillmd.com/u/hktitan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hktitan/cursor-runs

---


# cursor-runs

Everything you do after `Agent.create` flows through a `Run`. This skill covers how to issue work, stream events, await results, cancel, and inspect conversation history.

## When to use

- Consuming streamed `SDKMessage` events
- Implementing follow-up turns on the same agent
- Cancelling or reattaching to a long-running cloud run
- Parsing tool calls, thinking blocks, or assistant text

## Sending work

- [[references/send]] — `agent.send(message, options)` and `SendOptions`
- [[references/send-options]] — per-run model override, MCP override, callbacks, `force`
- [[references/follow-ups]] — multi-turn conversations on one agent

## Run object

- [[references/run-interface]] — `id`, `status`, `result`, `git`, `model`, `durationMs`
- [[references/wait]] — `await run.wait()` and `RunResult`
- [[references/cancel]] — `run.cancel()` and cancellation semantics
- [[references/status-events]] — `onDidChangeStatus` listener
- [[references/operation-support]] — `run.supports(op)` and `unsupportedReason`

## Streaming

- [[references/stream]] — `for await` over `run.stream()`
- [[references/sdk-message-types]] — full union: system, user, assistant, thinking, tool_use, status, task, request
- [[references/interaction-updates]] — `onDelta` updates: text, thinking, tool calls, tokens, steps, summaries, shell
- [[references/on-step]] — `onStep` step-level callback

## Conversation

- [[references/conversation]] — `run.conversation()` returns `ConversationTurn[]`
- [[references/conversation-shapes]] — `agentConversationTurn` vs `shellConversationTurn`, step types

## Where to go next

- Lifecycle and creation → [[../cursor-sdk/SKILL]]
- Cloud-specific run features (PRs, artifacts) → [[../cursor-cloud/SKILL]]
- Error classification → [[../cursor-errors/SKILL]]