cursor_api_sdk

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 15, 2026 License: AGPL-3.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultAPIBaseURL = "https://api2.cursor.sh"
	DefaultClientType = "cli"
)

Variables

View Source 
var (
	ErrRateLimited      = errors.New("cursor rate limited")
	ErrUnauthorized     = errors.New("cursor unauthorized")
	ErrUpstream         = errors.New("cursor upstream error")
	ErrIncompleteRun    = errors.New("cursor run ended without turn_ended")
	ErrModelUnavailable = errors.New("cursor model unavailable for agent")
	ErrBadModelName     = errors.New("cursor bad model name")
	// ErrMissingBlob is a client payload bug (Structure bytes were not blob ids).
	// Account failover must not rotate — the same payload will fail again.
	ErrMissingBlob = errors.New("cursor missing blob")
)

Functions

func BuildMcpToolDefinitions 

func BuildMcpToolDefinitions(tools []OpenAIToolDef) ([]*cursorProto.McpToolDefinition, error)

BuildMcpToolDefinitions maps OpenAI tool defs to Cursor MCP descriptors.

func ChecksumHeader 

func ChecksumHeader(ids DeviceIDs, now time.Time) string

ChecksumHeader builds x-cursor-checksum for the given device ids.

func DecodeMcpArgsMap 

func DecodeMcpArgsMap(args map[string][]byte) (string, error)

DecodeMcpArgsMap decodes Cursor MCP arg Value bytes into JSON object text.

func DeriveBridgeKey 

func DeriveBridgeKey(modelID string, messages []ChatMessage) string

DeriveBridgeKey builds a stable key for parking/resuming a Run across tool turns.

func EncodeMcpError 

func EncodeMcpError(msg string) *cursorProto.McpResult

EncodeMcpError builds an mcpResult error payload.

func EncodeMcpSuccess 

func EncodeMcpSuccess(text string) *cursorProto.McpResult

EncodeMcpSuccess builds a text mcpResult success payload.

func FormatModelParameters 

func FormatModelParameters(params []ModelParameter) string

FormatModelParameters renders selection parameters as id=value pairs for logs/headers.

func FrameConnect 

func FrameConnect(payload []byte, flags byte) []byte

FrameConnect wraps a protobuf payload in a Connect data frame.

func IsMissingBlob added in v1.3.0 

func IsMissingBlob(err error) bool

IsMissingBlob reports whether err looks like Cursor "Blob not found" (inlined Structure bytes treated as sha256 ids).

func ResolveModelID 

func ResolveModelID(modelID string) string

ResolveModelID maps client-facing aliases to Cursor wire ids.

func WithModelID 

func WithModelID(err error, modelID string) error

WithModelID annotates an APIError with the requested model id when present.

Types

type APIError 

type APIError struct {
	Status     int
	Code       string
	Message    string
	ModelID    string
	DebugError string // e.g. ERROR_BAD_MODEL_NAME from aiserver.v1.ErrorDetails
	Title      string
	Detail     string
	Err        error
}

APIError carries HTTP status and optional Connect error details.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) Unwrap 

func (e *APIError) Unwrap() error

type ChatMessage 

type ChatMessage struct {
	Role       string           `json:"role"`
	Content    string           `json:"content"`
	ToolCallID string           `json:"tool_call_id,omitempty"`
	ToolCalls  []OpenAIToolCall `json:"tool_calls,omitempty"`
	// Images are decoded from multipart content (data/base64 only); not serialized.
	Images []Image `json:"-"`
}

ChatMessage is a minimal OpenAI chat message (tools-aware).

func (*ChatMessage) UnmarshalJSON added in v1.3.0 

func (m *ChatMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts OpenAI content as a string, null, or array of parts (OpenCode / Chat Completions multipart): flattens text and extracts images.

type Client 

type Client struct {
	HTTP          *http.Client
	BaseURL       string // default api2.cursor.sh
	ClientVersion string // e.g. cli-YYYY.MM.DD-hash
	Device        DeviceIDs
	// contains filtered or unexported fields
}

Client is a Cursor upstream API client. Safe for concurrent use.

func (*Client) CachedModels added in v1.3.0 

func (c *Client) CachedModels() []Model

CachedModels returns a copy of the in-process catalog when the TTL is still valid.

func (*Client) CollectText 

func (c *Client) CollectText(ctx context.Context, accessToken string, payload *RunPayload) (string, error)

CollectText runs a chat and buffers the full assistant text (non-streaming helper).

func (*Client) ListModels 

func (c *Client) ListModels(ctx context.Context, accessToken string) ([]Model, error)

ListModels calls AiService/AvailableModels; on failure returns a small fallback list.

func (*Client) ResolveAgentOrigin 

func (c *Client) ResolveAgentOrigin(ctx context.Context, accessToken string) (string, error)

ResolveAgentOrigin returns the HTTPS origin for AgentService/Run. Uses GetServerConfig when possible; falls back to BaseURL / api2.

func (*Client) ResolveModelSelection 

func (c *Client) ResolveModelSelection(ctx context.Context, accessToken, modelID string) (ModelSelection, error)

ResolveModelSelection maps an OpenAI model id onto Cursor ModelDetails/RequestedModel fields.

func (*Client) RunChat 

func (c *Client) RunChat(ctx context.Context, accessToken string, payload *RunPayload) (<-chan StreamEvent, error)

RunChat opens AgentService/Run, handles KV/heartbeats, and emits text events. MCP tool calls without a bridge callback get an immediate error reply. The returned channel is closed when the run finishes.

func (*Client) StartRun 

func (c *Client) StartRun(ctx context.Context, accessToken string, payload *RunPayload, bridgeTools bool) (*RunControl, error)

StartRun opens AgentService/Run. When bridgeTools is true, mcpArgs emit ToolCall events and the HTTP layer must park the RunControl and later SubmitMcpResults.

type ConversationTurn 

type ConversationTurn struct {
	UserText      string
	AssistantText string
}

ConversationTurn is a prior user/assistant pair.

type DeviceIDs 

type DeviceIDs struct {
	MachineID    string
	MacMachineID string // empty if no MAC
}

DeviceIDs are stable fingerprints embedded in x-cursor-checksum.

func GetDeviceIDs 

func GetDeviceIDs() DeviceIDs

GetDeviceIDs returns process-cached stable device fingerprints.

type Image added in v1.3.0 

type Image struct {
	Bytes    []byte
	MimeType string
	Filename string
}

Image is a decoded OpenAI/OpenCode image attachment (data-URL or raw base64 only).

type Model 

type Model struct {
	ID               string           `json:"id"`
	Name             string           `json:"name,omitempty"`
	ServerModelName  string           `json:"server_model_name,omitempty"`
	LegacySlug       string           `json:"legacy_slug,omitempty"`
	Aliases          []string         `json:"aliases,omitempty"`
	SupportsThinking bool             `json:"supports_thinking,omitempty"`
	SupportsAgent    *bool            `json:"supports_agent,omitempty"`
	MaxMode          bool             `json:"max_mode,omitempty"`
	Parameters       []ModelParameter `json:"parameters,omitempty"`
}

Model is a Cursor picker catalog entry mapped for OpenAI /v1/models.

type ModelParameter 

type ModelParameter struct {
	ID    string `json:"id"`
	Value string `json:"value"`
}

ModelParameter is a Cursor RequestedModel parameter (context, reasoning, …).

type ModelSelection 

type ModelSelection struct {
	PublicID      string
	WireModelID   string
	DisplayName   string
	Parameters    []ModelParameter
	MaxMode       bool
	SupportsAgent *bool
}

ModelSelection is the wire identity used for AgentService/Run.

func LiteralModelSelection 

func LiteralModelSelection(modelID string) ModelSelection

LiteralModelSelection is used when the catalog has no entry for modelID.

func SelectionFromModel 

func SelectionFromModel(m Model) ModelSelection

SelectionFromModel builds a Run selection from a catalog entry. AgentService/Run validates ModelDetails.model_id against legacy slugs for some vendors (e.g. Anthropic), so WireModelID prefers variant legacySlug.

type OpenAIToolCall 

type OpenAIToolCall struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

OpenAIToolCall is an assistant tool_calls[] entry.

type OpenAIToolDef 

type OpenAIToolDef struct {
	Type     string `json:"type"`
	Function struct {
		Name        string          `json:"name"`
		Description string          `json:"description"`
		Parameters  json.RawMessage `json:"parameters"`
	} `json:"function"`
}

OpenAIToolDef is the OpenAI tools[] entry we accept.

type ParsedChat 

type ParsedChat struct {
	SystemPrompt string
	Turns        []ConversationTurn
	UserText     string
	// UserImages are action-turn attachments only (history stays text-only).
	UserImages  []Image
	ToolResults []ToolResultInfo
}

ParsedChat is the OpenAI → Cursor mapping of a chat request.

func ParseChatMessages 

func ParseChatMessages(messages []ChatMessage) ParsedChat

ParseChatMessages splits OpenAI messages into system / history / current user / tool results. Image parts on the action user are kept; prior user images are dropped (history text-only).

type PendingExec 

type PendingExec struct {
	ExecID      string
	ExecMsgID   uint32
	ToolCallID  string
	ToolName    string
	DecodedArgs string
}

PendingExec is a Cursor mcpArgs call waiting for an OpenAI tool result.

type RunControl 

type RunControl struct {
	Events <-chan StreamEvent
	// contains filtered or unexported fields
}

RunControl owns a live AgentService/Run stream that can pause for tool results.

func (*RunControl) Close 

func (r *RunControl) Close()

Close cancels the run and closes the request pipe.

func (*RunControl) Pending 

func (r *RunControl) Pending() []PendingExec

Pending returns a copy of mcpArgs waiting for OpenAI tool results.

func (*RunControl) Recv 

func (r *RunControl) Recv() (StreamEvent, bool)

Recv returns the next stream event, preferring any unread preface events.

func (*RunControl) SubmitMcpResults 

func (r *RunControl) SubmitMcpResults(results []ToolResultInfo) error

SubmitMcpResults writes mcpResult frames for parked pending execs and clears them.

func (*RunControl) TryRecv 

func (r *RunControl) TryRecv() (StreamEvent, bool)

TryRecv returns a buffered/preface event without blocking.

func (*RunControl) Unread 

func (r *RunControl) Unread(ev StreamEvent)

Unread pushes an event so the next Recv observes it first (FIFO among unread).

func (*RunControl) Usage added in v1.3.0 

func (r *RunControl) Usage() Usage

Usage returns the Path A token meter accumulated on this run so far.

type RunPayload 

type RunPayload struct {
	RequestBytes []byte
	BlobStore    map[string][]byte // hex(blobID) → bytes
	Conversation string
	ModelID      string
	// Tools is echoed into exec request_context replies (may be empty).
	Tools []*cursorProto.McpToolDefinition
}

RunPayload is a framed-ready AgentClientMessage plus local blob store for KV.

func BuildRunPayload 

func BuildRunPayload(modelID string, parsed ParsedChat) (*RunPayload, error)

BuildRunPayload builds an AgentClientMessage run_request (blob system prompt strategy).

func BuildRunPayloadSelection 

func BuildRunPayloadSelection(sel ModelSelection, parsed ParsedChat) (*RunPayload, error)

BuildRunPayloadSelection builds a run request using catalog-resolved model identity. ModelDetails.model_id and RequestedModel.model_id use the agent wire id (legacy slug when present). OpenAI response model id stays the public/catalog id.

Every ConversationState Structure `bytes` field is a 32-byte sha256 blob id; raw bytes live only in RunPayload.BlobStore (served by handleKV getBlob).

type StreamEvent 

type StreamEvent struct {
	Text       string
	Thinking   bool
	TurnEnded  bool
	ToolCall   *PendingExec
	Err        error
	HTTPStatus int
}

StreamEvent is a high-level event from AgentService/Run.

type ToolResultInfo 

type ToolResultInfo struct {
	ToolCallID string
	Content    string
}

ToolResultInfo is a role=tool message payload.

type Usage added in v1.3.0 

type Usage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

Usage is the OpenAI chat/completions token meter (Path A / otto). prompt = max(checkpoint.usedTokens); completion = Σ token_delta; total = sum.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.