Sitelet https://github.com/cursor/sdk-bridge/commit/d03bb7e50d83119245f354cd8d6b8c3e110f8c0b
Skip to content

Commit d03bb7e

Browse files
sdk-bridge-publish[bot]sdk-bridge-publish[bot]
committed
Sync sdk.v1 protos from Cursor SDK release 1.0.27
Source: anysphere/everysphere@3402a40eb1bec97091fbf86dbc605e6083091b96
1 parent 35b36b0 commit d03bb7e

8 files changed

Lines changed: 174 additions & 46 deletions

‎proto/manifest.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"protocol": "sdk.v1",
3-
"sdkVersion": "1.0.26",
3+
"sdkVersion": "1.0.27",
44
"sourceRepo": "anysphere/everysphere",
5-
"sourceCommit": "6cd5e0a2c5046b08d2bc59f8d25f3a0a5bebbcd3"
5+
"sourceCommit": "3402a40eb1bec97091fbf86dbc605e6083091b96"
66
}

‎proto/sdk/v1/sdk_agent_service.proto‎

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,34 +11,54 @@ option java_package = "com.cursor.sdk.v1";
1111
option ruby_package = "Cursor::Sdk::V1";
1212
option swift_prefix = "CursorSdkV1";
1313

14-
// Agent, run, streaming, cancellation, and artifact APIs.
14+
// Agent lifecycle, run streaming, cancellation, and artifact APIs.
1515
service SdkAgentService {
16+
// Create a new local or cloud agent.
1617
rpc CreateAgent(CreateAgentRequest) returns (CreateAgentResponse);
18+
// Re-attach to an existing agent and apply updated options.
1719
rpc ResumeAgent(ResumeAgentRequest) returns (ResumeAgentResponse);
20+
// Reload an agent's durable state from its store without sending a message.
1821
rpc ReloadAgent(ReloadAgentRequest) returns (ReloadAgentResponse);
22+
// Release local resources for an agent. Does not delete durable cloud state.
1923
rpc CloseAgent(CloseAgentRequest) returns (CloseAgentResponse);
24+
// Send a user message and stream run events until the run completes.
2025
rpc Send(SendRequest) returns (stream RunStreamMessage);
26+
// Block until a live run reaches a terminal status and return its result.
2127
rpc WaitLiveRun(WaitLiveRunRequest) returns (WaitLiveRunResponse);
28+
// Fetch a point-in-time snapshot of a run.
2229
rpc GetRun(GetRunRequest) returns (GetRunResponse);
30+
// List runs for an agent, newest first unless otherwise noted by the bridge.
2331
rpc ListRuns(ListRunsRequest) returns (ListRunsResponse);
32+
// Fetch the conversation JSON associated with a run.
2433
rpc GetRunConversation(GetRunConversationRequest) returns (GetRunConversationResponse);
34+
// Subscribe to durable run events, optionally resuming after a prior offset.
2535
rpc ObserveRun(ObserveRunRequest) returns (stream RunStreamMessage);
36+
// Request cancellation of an in-flight run.
2637
rpc CancelRun(CancelRunRequest) returns (CancelRunResponse);
38+
// Fetch metadata for a single agent.
2739
rpc GetAgent(GetAgentRequest) returns (GetAgentResponse);
40+
// List agents visible to the caller.
2841
rpc ListAgents(ListAgentsRequest) returns (ListAgentsResponse);
42+
// Archive an agent so it no longer appears in default listings.
2943
rpc ArchiveAgent(ArchiveAgentRequest) returns (ArchiveAgentResponse);
44+
// Restore an archived agent.
3045
rpc UnarchiveAgent(UnarchiveAgentRequest) returns (UnarchiveAgentResponse);
46+
// Permanently delete an agent and its durable data.
3147
rpc DeleteAgent(DeleteAgentRequest) returns (DeleteAgentResponse);
48+
// List messages recorded for an agent.
3249
rpc ListAgentMessages(ListAgentMessagesRequest) returns (ListAgentMessagesResponse);
50+
// List artifacts produced by a cloud agent.
3351
rpc ListArtifacts(ListArtifactsRequest) returns (ListArtifactsResponse);
52+
// Download an artifact as a stream of bytes.
3453
rpc DownloadArtifact(DownloadArtifactRequest) returns (stream DownloadArtifactChunk);
35-
// Billed token usage and dollar cost for an agent's runs. Cloud-only for
36-
// now; local agents fail with the SDK's cloud-only error.
54+
// Billed token usage and dollar cost for an agent's runs.
55+
// Cloud agents only; local agents fail with a cloud-only / unavailable error.
3756
rpc GetUsage(GetUsageRequest) returns (GetUsageResponse);
3857
}
3958

4059
message CreateAgentRequest {
4160
AgentOptions options = 1;
61+
// Optional key that makes CreateAgent retries safe for cloud agents.
4262
optional string idempotency_key = 2;
4363
}
4464

@@ -73,6 +93,7 @@ message SendRequest {
7393
string agent_id = 1;
7494
UserMessage message = 2;
7595
SendOptions options = 3;
96+
// Optional key that makes Send retries safe for cloud agents.
7697
optional string idempotency_key = 4;
7798
}
7899

@@ -100,6 +121,7 @@ message ListRunsRequest {
100121

101122
message ListRunsResponse {
102123
repeated RunSnapshot items = 1;
124+
// Opaque pagination cursor. Empty when there are no further pages.
103125
string next_cursor = 2;
104126
}
105127

@@ -108,16 +130,20 @@ message GetRunConversationRequest {
108130
}
109131

110132
message GetRunConversationResponse {
133+
// Opaque conversation document encoded as JSON.
111134
string conversation_json = 1;
112135
}
113136

114137
message ObserveRunRequest {
115138
string run_id = 1;
139+
// Resume after this exclusive offset from a prior ObserveRun / Send stream.
140+
// When unset, the stream starts from the beginning of durable events.
116141
optional string after_offset = 2;
117142
}
118143

119144
message CancelRunRequest {
120145
string run_id = 1;
146+
// Optional agent hint used by some bridge deployments for routing.
121147
optional string agent_id = 2;
122148
}
123149

@@ -138,6 +164,7 @@ message ListAgentsRequest {
138164

139165
message ListAgentsResponse {
140166
repeated SdkAgentInfo items = 1;
167+
// Opaque pagination cursor. Empty when there are no further pages.
141168
string next_cursor = 2;
142169
}
143170

@@ -181,6 +208,7 @@ message ListArtifactsResponse {
181208

182209
message DownloadArtifactRequest {
183210
string agent_id = 1;
211+
// Artifact path as returned by ListArtifacts.
184212
string path = 2;
185213
}
186214

@@ -199,6 +227,7 @@ message ListAgentsOptions {
199227
string cursor = 2;
200228
Runtime runtime = 3;
201229
string cwd = 4;
230+
// Filter cloud agents associated with this pull-request URL.
202231
string pr_url = 5;
203232
optional bool include_archived = 6;
204233
string api_key = 7;

‎proto/sdk/v1/sdk_bridge_control_service.proto‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,19 @@ option ruby_package = "Cursor::Sdk::V1";
1010
option swift_prefix = "CursorSdkV1";
1111

1212
// Bridge-local health, version, and lifecycle APIs.
13+
//
14+
// These RPCs manage the bridge process itself. They are not agent or run
15+
// operations; use SdkAgentService and SdkCursorService for those.
1316
service SdkBridgeControlService {
17+
// Liveness check. Returns a fixed message when the bridge is accepting RPCs.
1418
rpc Ping(PingRequest) returns (PingResponse);
19+
// Request a graceful shutdown of the bridge process.
1520
rpc Shutdown(ShutdownRequest) returns (ShutdownResponse);
21+
// Bridge build version, protocol version, and advertised capabilities.
1622
rpc GetVersion(GetVersionRequest) returns (GetVersionResponse);
1723
// Point the bridge at a host-process custom-tool callback server after
18-
// startup. Lets SDK clients that attach to an already-running bridge
19-
// (Client.connect) register host execute handlers. Same-host (loopback) only.
24+
// startup. Lets clients that attach to an already-running bridge register
25+
// host execute handlers. Same-host (loopback) only.
2026
rpc SetToolCallback(SetToolCallbackRequest) returns (SetToolCallbackResponse);
2127
}
2228

@@ -27,6 +33,8 @@ message PingResponse {
2733
}
2834

2935
message ShutdownRequest {
36+
// Seconds to wait for in-flight RPCs before forcing exit. Zero means
37+
// immediate shutdown.
3038
uint32 grace_seconds = 1;
3139
}
3240

@@ -35,8 +43,11 @@ message ShutdownResponse {}
3543
message GetVersionRequest {}
3644

3745
message GetVersionResponse {
46+
// Semver (or equivalent) of the bridge binary.
3847
string bridge_version = 1;
48+
// Version of this sdk.v1 protocol contract the bridge implements.
3949
string protocol_version = 2;
50+
// Feature strings the bridge supports (for client capability negotiation).
4051
repeated string capabilities = 3;
4152
}
4253

‎proto/sdk/v1/sdk_cursor_service.proto‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,22 @@ option java_package = "com.cursor.sdk.v1";
1111
option ruby_package = "Cursor::Sdk::V1";
1212
option swift_prefix = "CursorSdkV1";
1313

14-
// Cloud-only Cursor account and catalog APIs.
14+
// Cloud account and catalog APIs.
15+
//
16+
// These RPCs talk to Cursor Cloud using the caller's API key. They do not
17+
// require a local agent runtime.
1518
service SdkCursorService {
19+
// Authenticated account identity for the supplied API key.
1620
rpc Me(MeRequest) returns (MeResponse);
21+
// Models available to the authenticated account.
1722
rpc ListModels(ListModelsRequest) returns (ListModelsResponse);
23+
// Repositories the authenticated account can use with cloud agents.
1824
rpc ListRepositories(ListRepositoriesRequest) returns (ListRepositoriesResponse);
1925
}
2026

2127
message CursorRequestOptions {
28+
// Cursor API key. When empty, the bridge may fall back to process env
29+
// (e.g. CURSOR_API_KEY) depending on how it was launched.
2230
string api_key = 1;
2331
}
2432

‎proto/sdk/v1/sdk_custom_tool_callback_service.proto‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,25 +11,32 @@ option java_package = "com.cursor.sdk.v1";
1111
option ruby_package = "Cursor::Sdk::V1";
1212
option swift_prefix = "CursorSdkV1";
1313

14-
// Custom-tool callbacks from the Node bridge to a Python (or other) host process.
14+
// Custom-tool callbacks from the bridge to a host process.
1515
//
16-
// The bridge forwards in-process SDK custom-tool executions to the host over
17-
// `CallCustomTool`, mirroring `@cursor/sdk` `local.customTools` execute
18-
// callbacks. Tool metadata crosses CreateAgent/Send options; only execution
19-
// round-trips to the host.
16+
// When a local agent defines custom tools, the bridge forwards each tool
17+
// execution to the host over CallCustomTool. Tool metadata travels with
18+
// CreateAgent / Send options; only execution round-trips to the host.
19+
//
20+
// Hosts implement this service and register it with the bridge via
21+
// SdkBridgeControlService.SetToolCallback (or an equivalent launch-time
22+
// configuration).
2023
service SdkCustomToolCallbackService {
2124
rpc CallCustomTool(CallCustomToolRequest) returns (CallCustomToolResponse);
2225
}
2326

2427
message CallCustomToolRequest {
2528
string tool_name = 1;
29+
// Tool arguments as a JSON object.
2630
google.protobuf.Struct args = 2;
31+
// Optional ID for correlating this invocation with stream events.
2732
optional string tool_call_id = 3;
28-
// Agent that owns the tool definition (CreateAgent / ResumeAgent local.custom_tools).
33+
// Agent that owns the tool definition (from CreateAgent / ResumeAgent
34+
// local.custom_tools).
2935
string agent_id = 4;
3036
}
3137

3238
message CallCustomToolResponse {
33-
// SDKCustomToolResult wire shape (string, object, or content envelope).
39+
// Tool result as a JSON object. Common shapes include a plain string value,
40+
// a structured object, or a content envelope recognized by the SDK.
3441
google.protobuf.Struct result = 1;
3542
}

‎proto/sdk/v1/sdk_errors.proto‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,10 @@ option java_package = "com.cursor.sdk.v1";
1111
option ruby_package = "Cursor::Sdk::V1";
1212
option swift_prefix = "CursorSdkV1";
1313

14-
// Public SDK error codes returned by the bridge.
14+
// Stable error codes returned by the bridge on failed RPCs.
15+
//
16+
// Codes are attached to Connect/gRPC errors via SdkErrorDetails so language
17+
// SDKs can branch on a stable taxonomy instead of parsing free-form messages.
1518
enum SdkErrorCode {
1619
SDK_ERROR_CODE_UNSPECIFIED = 0;
1720
SDK_ERROR_CODE_UNAUTHORIZED = 1;
@@ -37,21 +40,27 @@ enum SdkErrorCode {
3740
SDK_ERROR_CODE_CLIENT_CANCELLED = 21;
3841
}
3942

40-
// Rate-limit metadata surfaced from Cursor Cloud responses.
43+
// Rate-limit metadata when the upstream response includes it.
4144
message RateLimitInfo {
4245
optional uint64 limit = 1;
4346
optional uint64 remaining = 2;
47+
// Unix epoch seconds when the rate-limit window resets.
4448
optional uint64 reset_epoch_seconds = 3;
4549
}
4650

47-
// Stable, public error details attached to Connect errors.
51+
// Structured error details attached to Connect/gRPC errors from the bridge.
4852
message SdkErrorDetails {
49-
// Full request ID from Cursor Cloud, if one is available. Never truncate this.
53+
// Full request ID from Cursor Cloud, when available. Prefer logging and
54+
// displaying the complete value.
5055
optional string request_id = 1;
5156
SdkErrorCode sdk_error_code = 2;
57+
// Human-readable summary suitable for display or logs.
5258
string message = 3;
59+
// Optional link to docs or remediation guidance.
5360
optional string help_url = 4;
61+
// Upstream provider name when the failure originated outside Cursor.
5462
optional string provider = 5;
63+
// Suggested wait before retrying, when known.
5564
optional google.protobuf.Duration retry_after = 6;
5665
optional RateLimitInfo rate_limit = 7;
5766
}

0 commit comments

Comments
 (0)