cursor-runs

name	cursor-runs
description	Run lifecycle, streaming, follow-ups, and conversation introspection in the Cursor SDK. Use when consuming agent output, handling progress events, or chaining turns.
metadata	{"internal":false,"source":"https://cursor.com/docs/sdk/typescript"}

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]]