cursor-agent-a2a 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jeffkit
+
+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,306 @@
+# Cursor Agent A2A Service
+
+[![npm version](https://img.shields.io/npm/v/cursor-agent-a2a)](https://www.npmjs.com/package/cursor-agent-a2a)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Independent A2A-compatible service wrapping Cursor CLI agent command. This service provides a standard A2A (Agent-to-Agent) protocol interface for Cursor CLI, allowing it to be called from other A2A-compatible services like AgentStudio.
+
+## Features
+
+- ✅ **A2A Protocol Compliant** - Full support for A2A protocol endpoints
+- ✅ **Multi-turn Conversations** - Session management with workspace persistence
+- ✅ **Streaming Responses** - Server-Sent Events (SSE) for real-time updates
+- ✅ **Async Task Management** - Long-running task support with status polling
+- ✅ **Workspace Management** - Automatic workspace handling in multi-turn conversations
+- ✅ **Session Persistence** - Workspace is automatically retrieved from session context
+
+## Installation
+
+### As a Standalone Service
+
+```bash
+# Clone the repository
+git clone https://github.com/jeffkit/cursor-agent-a2a.git
+cd cursor-agent-a2a
+
+# Install dependencies
+pnpm install
+```
+
+### As an NPM Package
+
+```bash
+npm install cursor-agent-a2a
+# or
+pnpm add cursor-agent-a2a
+```
+
+## Prerequisites
+
+### Cursor CLI Setup
+
+Make sure Cursor CLI is installed and authenticated:
+
+```bash
+# Install Cursor CLI
+curl https://cursor.com/install -fsS | bash
+
+# Login (or set CURSOR_API_KEY environment variable)
+cursor agent login
+
+# Verify authentication
+cursor agent status
+```
+
+## Configuration
+
+Set environment variables:
+
+```bash
+# API Key for A2A authentication (default: cursor-agent-demo-key)
+export CURSOR_AGENT_API_KEY=your-secure-api-key
+
+# Server port (default: 4937)
+export PORT=4937
+
+# Server host (default: 0.0.0.0)
+export HOST=0.0.0.0
+
+# Cursor API Key (optional, uses local login if not set)
+export CURSOR_API_KEY=sk_your_cursor_api_key
+```
+
+## Running
+
+### Development Mode
+
+```bash
+pnpm run dev
+```
+
+### Production Mode
+
+```bash
+# Build
+pnpm run build
+
+# Start
+pnpm start
+```
+
+The service will start on `http://localhost:4937` (or your configured port).
+
+## API Endpoints
+
+All endpoints require API key authentication via `Authorization: Bearer <api-key>` header.
+
+### Agent Card Discovery
+
+Get the agent's capabilities and metadata.
+
+```bash
+GET /.well-known/agent-card.json
+Authorization: Bearer <api-key>
+```
+
+**Response:**
+```json
+{
+  "name": "Cursor Agent",
+  "description": "AI-powered code assistant via Cursor CLI...",
+  "version": "1.0.0",
+  "url": "http://localhost:4937",
+  "skills": [...],
+  "securitySchemes": [...]
+}
+```
+
+### Send Message (Synchronous)
+
+Send a message and get an immediate response.
+
+```bash
+POST /messages
+Authorization: Bearer <api-key>
+Content-Type: application/json
+
+{
+  "message": "Say hello",
+  "workspace": "/path/to/project",
+  "sessionId": "optional-session-id"
+}
+```
+
+**Response:**
+```json
+{
+  "response": "Hello! I'm Claude, an AI programming assistant...",
+  "sessionId": "chat-12345",
+  "metadata": {
+    "processingTimeMs": 1234
+  }
+}
+```
+
+**Streaming Mode:**
+
+Add `?stream=true` or `Accept: text/event-stream` header:
+
+```bash
+POST /messages?stream=true
+Authorization: Bearer <api-key>
+Accept: text/event-stream
+```
+
+### Create Async Task
+
+Create a long-running task and poll for status.
+
+```bash
+POST /tasks
+Authorization: Bearer <api-key>
+Content-Type: application/json
+
+{
+  "message": "Long running task",
+  "workspace": "/path/to/project",
+  "timeout": 600000,
+  "sessionId": "optional-session-id"
+}
+```
+
+**Response:**
+```json
+{
+  "taskId": "task-uuid",
+  "status": "pending",
+  "checkUrl": "/tasks/task-uuid"
+}
+```
+
+### Query Task Status
+
+```bash
+GET /tasks/:taskId
+Authorization: Bearer <api-key>
+```
+
+**Response:**
+```json
+{
+  "taskId": "task-uuid",
+  "status": "completed",
+  "output": {
+    "result": "Task completed successfully"
+  },
+  "createdAt": "2026-01-24T...",
+  "completedAt": "2026-01-24T..."
+}
+```
+
+### Cancel Task
+
+```bash
+DELETE /tasks/:taskId
+Authorization: Bearer <api-key>
+```
+
+## Multi-turn Conversations
+
+The service supports multi-turn conversations with automatic workspace management:
+
+1. **First message** - Provide `workspace` parameter:
+   ```json
+   {
+     "message": "Create a hello.js file",
+     "workspace": "/path/to/project"
+   }
+   ```
+   Response includes `sessionId`.
+
+2. **Subsequent messages** - Only need `sessionId`, workspace is automatically retrieved:
+   ```json
+   {
+     "message": "Modify the file to add a function",
+     "sessionId": "chat-12345"
+   }
+   ```
+
+## Usage Examples
+
+### Using with AgentStudio
+
+Add to your project's `a2a-config.json`:
+
+```json
+{
+  "allowedAgents": [
+    {
+      "name": "Cursor Agent",
+      "url": "http://localhost:4937",
+      "apiKey": "your-api-key",
+      "description": "Cursor CLI agent via A2A",
+      "enabled": true
+    }
+  ]
+}
+```
+
+Then use it in AgentStudio agents via the A2A client tool.
+
+### Using with curl
+
+```bash
+# Get agent card
+curl -X GET "http://localhost:4937/.well-known/agent-card.json" \
+  -H "Authorization: Bearer your-api-key"
+
+# Send message
+curl -X POST "http://localhost:4937/messages" \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Say hello",
+    "workspace": "/path/to/project"
+  }'
+
+# Continue conversation
+curl -X POST "http://localhost:4937/messages" \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Continue",
+    "sessionId": "chat-12345"
+  }'
+```
+
+## Development
+
+```bash
+# Type checking
+pnpm run type-check
+
+# Build
+pnpm run build
+
+# Development with hot reload
+pnpm run dev
+```
+
+## License
+
+MIT
+
+## Author
+
+jeffkit (bbmyth@gmail.com)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- [GitHub Repository](https://github.com/jeffkit/cursor-agent-a2a)
+- [NPM Package](https://www.npmjs.com/package/cursor-agent-a2a)
+- [Cursor CLI Documentation](https://cursor.com/docs/cli)

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cursor Agent A2A Service - Independent Service
+ *
+ * Standalone A2A-compatible service wrapping Cursor CLI agent command.
+ * Can be run independently or called from other services like AgentStudio.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * Cursor Agent A2A Service - Independent Service
+ *
+ * Standalone A2A-compatible service wrapping Cursor CLI agent command.
+ * Can be run independently or called from other services like AgentStudio.
+ */
+import express from 'express';
+import cors from 'cors';
+import dotenv from 'dotenv';
+import cursorAgentRouter from './routes/cursorAgent.js';
+dotenv.config();
+const app = express();
+const PORT = Number(process.env.PORT) || 4937;
+const HOST = process.env.HOST || '0.0.0.0';
+// Middleware
+app.use(cors());
+app.use(express.json({ limit: '10mb' }));
+app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+// Health check
+app.get('/health', (req, res) => {
+    res.json({
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+        service: 'cursor-agent-a2a',
+        version: '1.0.0',
+    });
+});
+// A2A Protocol routes
+app.use('/', cursorAgentRouter);
+// Start server
+app.listen(PORT, HOST, () => {
+    console.log(`🚀 Cursor Agent A2A Service running on http://${HOST}:${PORT}`);
+    console.log(`📋 Agent Card: http://${HOST}:${PORT}/.well-known/agent-card.json`);
+    console.log(`💬 Messages: http://${HOST}:${PORT}/messages`);
+    console.log(`📦 Tasks: http://${HOST}:${PORT}/tasks`);
+});
+//# 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;;;;;GAKG;AAEH,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,iBAAiB,MAAM,yBAAyB,CAAC;AAExD,MAAM,CAAC,MAAM,EAAE,CAAC;AAEhB,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;AACtB,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,SAAS,CAAC;AAE3C,aAAa;AACb,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;AAChB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AACzC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAE/D,eAAe;AACf,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IAC9B,GAAG,CAAC,IAAI,CAAC;QACP,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO,EAAE,kBAAkB;QAC3B,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,sBAAsB;AACtB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;AAEhC,eAAe;AACf,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE;IAC1B,OAAO,CAAC,GAAG,CAAC,iDAAiD,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC;IAC7E,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,IAAI,IAAI,8BAA8B,CAAC,CAAC;IACjF,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,IAAI,IAAI,WAAW,CAAC,CAAC;IAC5D,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,IAAI,IAAI,QAAQ,CAAC,CAAC;AACxD,CAAC,CAAC,CAAC"}

package/dist/routes/__tests__/cursorAgent.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Unit tests for cursorAgent.ts - Cursor Agent A2A Routes
+ *
+ * Tests cover:
+ * - Homepage endpoint
+ * - Agent Card discovery
+ * - Message endpoints (sync and streaming)
+ * - Task management (create, query, cancel)
+ * - Authentication
+ * - Session management
+ * - Webhook callbacks
+ */
+export {};
+//# sourceMappingURL=cursorAgent.test.d.ts.map

package/dist/routes/__tests__/cursorAgent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursorAgent.test.d.ts","sourceRoot":"","sources":["../../../src/routes/__tests__/cursorAgent.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}