opencode-cursor-proxy 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Morse Wayne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# OpenCode Cursor Proxy
+
+**English** | [中文](README.zh-CN.md)
+
+> **Disclaimer**
+>
+> This is an **experimental** community project that integrates with Cursor via **unofficial** interfaces.
+>
+> - **May break at any time** if Cursor changes upstream behavior
+> - **No guarantees** on stability, compatibility, or long-term support
+> - **Not affiliated with / endorsed by Cursor**
+> - May violate [Cursor Terms of Service](https://www.cursor.com/terms-of-service); **your account could be suspended/terminated**
+>
+> By using this project, you acknowledge these risks and accept full responsibility. For educational and research purposes only.
+
+An OpenCode plugin that lets you use Cursor's AI backend with **OAuth authentication**, **dynamic model discovery**, and **full tool-calling support**.
+
+## Documentation
+
+- 🚀 [Getting Started](docs/getting-started.md) - Installation and setup guide
+- ⚙️ [Configuration](docs/configuration.md) - All configuration options
+- 🔧 [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
+- 🏗️ [Architecture](docs/development/architecture.md) - Technical deep dive
+
+## Features
+
+- **OpenCode plugin integration** via OAuth
+- **Full tool-calling support** (bash/read/write/ls/glob/grep, etc.)
+- **Dynamic model discovery** from Cursor APIs
+- **Streaming support** via SSE
+
+## Quick start (OpenCode plugin)
+
+### 1) Configure `opencode.json`
+
+Add the plugin and provider to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-cursor-proxy@latest"],
+  "provider": {
+    "cursor": { "name": "Cursor" }
+  }
+}
+```
+
+### 2) Authenticate
+
+Run OpenCode and authenticate:
+
+```bash
+opencode auth login
+```
+
+Then:
+
+1. Select **"other"** from the provider list
+2. Enter **"cursor"** as the provider name
+3. Select **"OAuth with Cursor"**
+4. Complete the browser-based OAuth flow
+
+## Standalone proxy server (optional, for development)
+
+> The standalone proxy server is primarily a dev artifact for testing/debugging. Most users should prefer the OpenCode plugin flow above.
+
+### Prerequisites
+
+- [Bun](https://bun.sh)
+- A Cursor account with valid credentials
+
+### Run
+
+```bash
+git clone https://github.com/MorseWayne/opencode-cursor-proxy.git
+cd opencode-cursor-proxy
+bun install
+
+# authenticate (script name is auth)
+bun run auth:login
+
+# start server
+bun run server
+```
+
+Default listen address: `http://localhost:18741`
+
+### Environment variables
+
+#### Basic
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | `18741` |
+| `HOST` | Server host | `localhost` |
+| `CURSOR_ACCESS_TOKEN` | Provide an access token directly | - |
+
+#### Debug & Logging
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CURSOR_DEBUG` | Enable debug logging | `0` |
+| `CURSOR_TIMING` | Enable performance timing logs | `0` |
+| `CURSOR_LOG_LEVEL` | Log level: `error`, `warn`, `info`, `debug` | `info` |
+| `CURSOR_LOG_JSON` | Output logs in JSON format | `0` |
+| `CURSOR_REQUEST_LOGGING` | Enable request/response logging | `0` |
+| `CURSOR_LOG_FILTERED_IDS` | Log filtered message IDs | `0` |
+| `CURSOR_LOG_MULTIMODAL` | Log multimodal content detection | `0` |
+
+#### Session & Cache
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CURSOR_SESSION_REUSE` | Enable session reuse for tool-calling | `1` |
+| `CURSOR_SESSION_TIMEOUT_MS` | Session timeout (ms) | `900000` (15min) |
+| `CURSOR_MAX_SESSIONS` | Maximum cached sessions | `100` |
+| `CURSOR_MODEL_CACHE_TTL_MS` | Model cache TTL (ms) | `300000` (5min) |
+
+#### Network
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CURSOR_REQUEST_TIMEOUT_MS` | Request timeout (ms) | `120000` (2min) |
+| `CURSOR_MAX_RETRIES` | Max retry attempts | `3` |
+| `CURSOR_RETRY_ENABLED` | Enable automatic retry | `1` |
+| `CURSOR_RETRY_BASE_DELAY_MS` | Base delay for exponential backoff (ms) | `1000` |
+| `CURSOR_RETRY_MAX_DELAY_MS` | Max delay between retries (ms) | `30000` |
+
+#### API
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CURSOR_API_URL` | Cursor API base URL | `https://api2.cursor.sh` |
+| `CURSOR_PRIVACY_MODE` | Enable privacy mode | `1` |
+| `CURSOR_CLIENT_VERSION` | Override client version header | - |
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,136 @@
+# OpenCode Cursor Proxy
+
+[English](README.md) | **中文**
+
+> **免责声明**
+>
+> 这是一个**实验性**社区项目，通过 **非官方接口** 与 Cursor 服务集成。
+>
+> - **随时可能中断**：Cursor 上游变更可能导致不可用
+> - **不提供任何保证**：稳定性、兼容性与长期可用性均不承诺
+> - **与 Cursor 无关且未获认可**
+> - 可能违反 [Cursor 的服务条款](https://www.cursor.com/terms-of-service)，**存在封号/终止服务的风险**
+>
+> 使用本项目即表示您理解并自行承担全部风险。本项目仅用于教育与研究目的。
+
+一个 OpenCode 插件，支持在 OpenCode 中使用 Cursor 的 AI 后端，具备 OAuth 认证、动态模型发现和完整的工具调用支持。
+
+## 文档
+
+- 🚀 [快速入门](docs/getting-started.md) - 安装和设置指南
+- ⚙️ [配置说明](docs/configuration.md) - 所有配置选项
+- 🔧 [故障排除](docs/troubleshooting.md) - 常见问题与解决方案
+- 🏗️ [架构设计](docs/development/architecture.md) - 技术深度解析
+
+## 功能特性
+
+- **OpenCode 插件**：通过 OAuth 认证实现与 OpenCode 的原生集成
+- **完整的工具调用支持**：支持 bash、read、write、list、glob/grep 等函数调用
+- **动态模型发现**：自动从 Cursor 的 API 获取可用模型
+- **流式支持**：通过 SSE 实现实时流式响应
+
+## 快速开始（OpenCode 插件）
+
+### 1) 配置 `opencode.json`
+
+将插件和 Cursor 提供商添加到您的 `opencode.json`：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-cursor-proxy@latest"],
+  "provider": {
+    "cursor": { "name": "Cursor" }
+  }
+}
+```
+
+### 2) 认证
+
+运行 OpenCode 并进行认证：
+
+```bash
+opencode auth login
+```
+
+然后：
+
+1. 从提供商列表中选择 **"other"**
+2. 输入 **"cursor"** 作为提供商名称
+3. 选择 **"OAuth with Cursor"**
+4. 完成基于浏览器的 OAuth 流程
+
+## 开发：独立代理服务器（可选）
+
+> 独立代理服务器主要是用于测试/调试的开发产物。大多数用户应该优先使用上面的 OpenCode 插件。
+
+### 先决条件
+
+- [Bun](https://bun.sh)
+- 一个具有有效凭据的 Cursor 账户
+
+### 运行
+
+```bash
+git clone https://github.com/MorseWayne/opencode-cursor-proxy.git
+cd opencode-cursor-proxy
+bun install
+
+# 先进行身份验证（脚本名为 auth）
+bun run auth:login
+
+# 启动服务器
+bun run server
+```
+
+默认监听：`http://localhost:18741`
+
+### 环境变量
+
+#### 基础配置
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `PORT` | 服务器端口 | `18741` |
+| `HOST` | 服务器主机 | `localhost` |
+| `CURSOR_ACCESS_TOKEN` | 直接提供访问令牌 | - |
+
+#### 调试与日志
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `CURSOR_DEBUG` | 启用调试日志 | `0` |
+| `CURSOR_TIMING` | 启用性能计时日志 | `0` |
+| `CURSOR_LOG_LEVEL` | 日志级别：`error`, `warn`, `info`, `debug` | `info` |
+| `CURSOR_LOG_JSON` | 以 JSON 格式输出日志 | `0` |
+
+#### 会话与缓存
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `CURSOR_SESSION_REUSE` | 启用工具调用的会话复用 | `1` |
+| `CURSOR_SESSION_TIMEOUT_MS` | 会话超时时间 (毫秒) | `900000` (15分钟) |
+| `CURSOR_MAX_SESSIONS` | 最大缓存会话数 | `100` |
+| `CURSOR_MODEL_CACHE_TTL_MS` | 模型缓存 TTL (毫秒) | `300000` (5分钟) |
+
+#### 网络
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `CURSOR_REQUEST_TIMEOUT_MS` | 请求超时时间 (毫秒) | `120000` (2分钟) |
+| `CURSOR_MAX_RETRIES` | 最大重试次数 | `3` |
+| `CURSOR_RETRY_ENABLED` | 启用自动重试 | `1` |
+| `CURSOR_RETRY_BASE_DELAY_MS` | 指数退避基础延迟 (毫秒) | `1000` |
+| `CURSOR_RETRY_MAX_DELAY_MS` | 重试最大延迟 (毫秒) | `30000` |
+
+#### API
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `CURSOR_API_URL` | Cursor API 基础 URL | `https://api2.cursor.sh` |
+| `CURSOR_PRIVACY_MODE` | 启用隐私模式 | `1` |
+| `CURSOR_CLIENT_VERSION` | 覆盖客户端版本头 | - |
+
+## 许可证
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { CursorOAuthPlugin as default } from "./plugin/plugin.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { CursorOAuthPlugin as default } from "./plugin/plugin.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,IAAI,OAAO,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/lib/api/agent-service.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Cursor Agent Service Client
+ *
+ * Implements the AgentService API for chat functionality.
+ * Uses the BidiSse pattern:
+ * - RunSSE (server-streaming) to receive responses
+ * - BidiAppend (unary) to send client messages
+ *
+ * Proto structure:
+ * AgentClientMessage:
+ *   field 1: run_request (AgentRunRequest)
+ *   field 2: exec_client_message (ExecClientMessage)
+ *   field 3: kv_client_message (KvClientMessage)
+ *   field 4: conversation_action (ConversationAction)
+ *   field 5: exec_client_control_message
+ *   field 6: interaction_response
+ *
+ * AgentServerMessage:
+ *   field 1: interaction_update (InteractionUpdate)
+ *   field 2: exec_server_message (ExecServerMessage)
+ *   field 3: conversation_checkpoint_update (completion signal)
+ *   field 4: kv_server_message (KvServerMessage)
+ *   field 5: exec_server_control_message
+ *   field 7: interaction_query
+ *
+ * InteractionUpdate.message:
+ *   field 1: text_delta
+ *   field 4: thinking_delta
+ *   field 8: token_delta
+ *   field 13: heartbeat
+ *   field 14: turn_ended
+ */
+import { AgentMode } from "./proto";
+import type { OpenAIToolDefinition, McpExecRequest, ExecRequest, AgentServiceOptions, AgentChatRequest, ToolCallInfo, AgentStreamChunk as AgentStreamChunkType } from "./proto/types";
+export { AgentMode };
+export type AgentStreamChunk = AgentStreamChunkType;
+export type { ExecRequest, McpExecRequest, ToolCallInfo, OpenAIToolDefinition };
+export declare const CURSOR_API_URL: string;
+export declare const AGENT_PRIVACY_URL: string;
+export declare const AGENT_NON_PRIVACY_URL: string;
+export declare class AgentServiceClient {
+    private baseUrl;
+    private accessToken;
+    private workspacePath;
+    private blobStore;
+    private privacyMode;
+    private clientVersionHeader;
+    private baseUrlAttempts;
+    private currentRequestId;
+    private currentAppendSeqno;
+    private pendingAssistantBlobs;
+    constructor(accessToken: string, options?: AgentServiceOptions);
+    private getHeaders;
+    private getBaseUrlAttempts;
+    private blobIdToKey;
+    /**
+     * Build the AgentClientMessage for a chat request
+     */
+    private buildChatMessage;
+    /**
+     * Call BidiAppend to send a client message
+     */
+    private bidiAppend;
+    private handleKvMessage;
+    /**
+     * Send a tool result back to the server (for MCP tools only)
+     * This must be called during an active chat stream when an exec_request chunk is received
+     */
+    sendToolResult(execRequest: McpExecRequest & {
+        type: 'mcp';
+    }, result: {
+        success?: {
+            content: string;
+            isError?: boolean;
+        };
+        error?: string;
+    }): Promise<void>;
+    /**
+     * Send a shell execution result back to the server
+     */
+    sendShellResult(id: number, execId: string | undefined, command: string, cwd: string, stdout: string, stderr: string, exitCode: number, executionTimeMs?: number): Promise<void>;
+    /**
+     * Send an LS result back to the server
+     */
+    sendLsResult(id: number, execId: string | undefined, filesString: string): Promise<void>;
+    /**
+     * Send a request context result back to the server
+     */
+    sendRequestContextResult(id: number, execId: string | undefined): Promise<void>;
+    /**
+     * Send a file read result back to the server
+     */
+    sendReadResult(id: number, execId: string | undefined, content: string, path: string, totalLines?: number, fileSize?: bigint, truncated?: boolean): Promise<void>;
+    /**
+     * Send a grep/glob result back to the server
+     */
+    sendGrepResult(id: number, execId: string | undefined, pattern: string, path: string, files: string[]): Promise<void>;
+    /**
+     * Send a file write result back to the server
+     */
+    sendWriteResult(id: number, execId: string | undefined, result: {
+        success?: {
+            path: string;
+            linesCreated: number;
+            fileSize: number;
+            fileContentAfterWrite?: string;
+        };
+        error?: {
+            path: string;
+            error: string;
+        };
+    }): Promise<void>;
+    /**
+     * Send a ResumeAction to signal the server to continue after tool results
+     * Based on Cursor CLI analysis: after sending tool results, send ConversationAction with resume_action
+     * to tell the server to resume streaming instead of storing responses in KV blobs
+     */
+    sendResumeAction(): Promise<void>;
+    /**
+     * Send a streaming chat request.
+     *
+     * Cursor periodically migrates AgentService/BidiService to different backends.
+     * If a request fails before any meaningful output, retry against known agent
+     * backends before surfacing the error.
+     */
+    chatStream(request: AgentChatRequest): AsyncGenerator<AgentStreamChunkType>;
+    private chatStreamOnce;
+    /**
+     * Send a non-streaming chat request (collects all chunks)
+     */
+    chat(request: AgentChatRequest): Promise<string>;
+}
+/**
+ * Create an Agent Service client
+ */
+export declare function createAgentServiceClient(accessToken: string, options?: AgentServiceOptions): AgentServiceClient;