@meetopenbot/cursor 0.0.1

package/README.md

@@ -0,0 +1,52 @@
+# @meetopenbot/cursor
+
+OpenBot agent plugin powered by the [Cursor TypeScript SDK](https://cursor.com/docs/sdk/typescript).
+
+Cursor provides a full agent runtime with built-in tools (shell, read, edit, write, grep, and more), session management, and local or cloud execution. This plugin wraps Cursor as an OpenBot **agent runtime** — each `agent:invoke` runs a Cursor turn and streams progress back via `agent:output`.
+
+## Installation
+
+```bash
+npm install @meetopenbot/cursor
+```
+
+Add the plugin to your agent in `AGENT.md`:
+
+```yaml
+plugins:
+  - id: '@meetopenbot/cursor'
+    config:
+      model: composer-2.5
+      thinking: high
+      runtime: local
+```
+
+## Configuration
+
+| Option | Description |
+|--------|-------------|
+| `apiKey` | Cursor API key. Falls back to `CURSOR_API_KEY`. |
+| `runtime` | `local` (default) or `cloud`. |
+| `model` | Model id (default: `composer-2.5`). |
+| `thinking` | Reasoning effort for models that support it (e.g. `low`, `high`). |
+| `mode` | `agent` (default) or `plan`. |
+| `cwd` | Working directory for local agents. Defaults to the OpenBot channel `cwd`, then `process.cwd()`. |
+| `repoUrl` | Git repository URL for cloud agents. |
+| `startingRef` | Git ref to clone for cloud agents (e.g. `main`). |
+| `autoCreatePR` | Open a pull request when a cloud run finishes. |
+| `workOnCurrentBranch` | Push cloud commits to the existing branch. |
+| `settingSources` | Comma-separated local settings layers: `project`, `user`, `team`, `mdm`, `plugins`, `all`. |
+| `sandbox` | Enable the local agent sandbox. |
+| `autoReview` | Route local tool calls through Auto-review. |
+
+## API Keys
+
+Set `CURSOR_API_KEY` in the environment or pass `apiKey` in plugin config. Generate a key from [Cursor Dashboard → API Keys](https://cursor.com/dashboard/api).
+
+## Sessions
+
+Each OpenBot thread gets its own Cursor agent. The Cursor `agentId` is stored in thread state so conversations continue across turns. The plugin uses `Agent.resume()` to reconnect after restarts.
+
+## License
+
+MIT

package/dist/config.js

@@ -0,0 +1,44 @@
+const RUNTIMES = new Set(['local', 'cloud']);
+const MODES = new Set(['agent', 'plan']);
+const SETTING_SOURCES = new Set([
+    'project',
+    'user',
+    'team',
+    'mdm',
+    'plugins',
+    'all',
+]);
+export const CURSOR_API_KEY_ENV_VAR = 'CURSOR_API_KEY';
+export const resolveConfig = (context, channelCwd) => {
+    const config = context.config;
+    const runtime = config.runtime && RUNTIMES.has(config.runtime) ? config.runtime : 'local';
+    const mode = config.mode && MODES.has(config.mode) ? config.mode : undefined;
+    const settingSources = config.settingSources
+        ?.split(',')
+        .map((source) => source.trim())
+        .filter((source) => SETTING_SOURCES.has(source));
+    return {
+        apiKey: (typeof config.apiKey === 'string' && config.apiKey.trim()) ||
+            process.env[CURSOR_API_KEY_ENV_VAR],
+        runtime,
+        model: (typeof config.model === 'string' && config.model.trim()) || 'composer-2.5',
+        thinking: typeof config.thinking === 'string' && config.thinking.trim()
+            ? config.thinking.trim()
+            : undefined,
+        mode,
+        cwd: channelCwd || config.cwd,
+        repoUrl: config.repoUrl?.trim() || undefined,
+        startingRef: config.startingRef?.trim() || undefined,
+        autoCreatePR: config.autoCreatePR === true,
+        workOnCurrentBranch: config.workOnCurrentBranch === true,
+        settingSources: settingSources?.length ? settingSources : undefined,
+        sandbox: config.sandbox === true,
+        autoReview: config.autoReview === true,
+    };
+};
+export const buildModelSelection = (config) => ({
+    id: config.model,
+    ...(config.thinking
+        ? { params: [{ id: 'thinking', value: config.thinking }] }
+        : {}),
+});

package/dist/format.js

@@ -0,0 +1,161 @@
+import { CursorSdkError } from '@cursor/sdk';
+export const createStreamState = () => ({
+    assistantText: '',
+});
+const truncate = (text, max = 80) => text.length > max ? `${text.slice(0, max - 3)}…` : text;
+const quoteDetail = (detail) => detail.includes('`') ? `"${detail}"` : `\`${detail}\``;
+const strArg = (args, ...keys) => {
+    if (!args || typeof args !== 'object')
+        return undefined;
+    const record = args;
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+        if (typeof value === 'number' && Number.isFinite(value))
+            return String(value);
+    }
+    return undefined;
+};
+const formatToolDetail = (toolName, args) => {
+    switch (toolName) {
+        case 'Shell':
+        case 'shell': {
+            const command = strArg(args, 'command');
+            return command ? truncate(command.replace(/\s+/g, ' ')) : undefined;
+        }
+        case 'Read':
+        case 'read': {
+            const path = strArg(args, 'path', 'target_file', 'file_path');
+            return path ? truncate(path, 120) : undefined;
+        }
+        case 'Write':
+        case 'write':
+        case 'Edit':
+        case 'edit':
+        case 'StrReplace':
+        case 'strReplace': {
+            const path = strArg(args, 'path', 'target_file', 'file_path');
+            return path ? truncate(path, 120) : undefined;
+        }
+        case 'Grep':
+        case 'grep': {
+            const pattern = strArg(args, 'pattern');
+            const path = strArg(args, 'path') ?? '.';
+            if (!pattern)
+                return undefined;
+            return `${truncate(pattern)} in ${truncate(path, 60)}`;
+        }
+        case 'Glob':
+        case 'glob':
+        case 'GlobFileSearch':
+        case 'globFileSearch': {
+            const pattern = strArg(args, 'glob_pattern', 'pattern');
+            return pattern ? truncate(pattern) : undefined;
+        }
+        case 'LS':
+        case 'ls':
+        case 'ListDir':
+        case 'listDir': {
+            const path = strArg(args, 'path', 'target_directory') ?? '.';
+            return truncate(path, 120);
+        }
+        default:
+            return undefined;
+    }
+};
+const formatToolStart = (toolName, args) => {
+    const detail = formatToolDetail(toolName, args);
+    if (detail)
+        return `Running **${toolName}** (${quoteDetail(detail)})…`;
+    return `Running **${toolName}**…`;
+};
+const formatCloudStatus = (status, message, config) => {
+    const isCloud = config?.runtime === 'cloud';
+    switch (status) {
+        case 'CREATING':
+            return isCloud ? 'Starting cloud agent…' : 'Starting local agent…';
+        case 'RUNNING':
+            return message ? truncate(message) : undefined;
+        case 'ERROR':
+            return message
+                ? `**Cursor error:** ${message}`
+                : isCloud
+                    ? '**Cursor error:** Cloud run failed.'
+                    : '**Cursor error:** Local run failed.';
+        case 'CANCELLED':
+            return isCloud ? 'Cloud run cancelled.' : 'Local run cancelled.';
+        case 'EXPIRED':
+            return isCloud ? 'Cloud run expired.' : 'Local run expired.';
+        case 'FINISHED':
+            return undefined;
+        default:
+            return message ? truncate(message) : undefined;
+    }
+};
+/** Map Cursor SDK stream events to user-visible output chunks. */
+export const formatCursorEvent = (event, state, config) => {
+    switch (event.type) {
+        case 'assistant': {
+            const text = event.message.content
+                .filter((block) => block.type === 'text')
+                .map((block) => block.text)
+                .join('');
+            if (text)
+                state.assistantText += text;
+            return undefined;
+        }
+        case 'tool_call': {
+            if (event.status === 'running') {
+                return formatToolStart(event.name, event.args);
+            }
+            if (event.status === 'error') {
+                const details = JSON.stringify(event);
+                return `Tool **${event.name}** failed. Details: \`${details}\``;
+            }
+            return undefined;
+        }
+        case 'status': {
+            if (event.status === 'ERROR') {
+                const details = JSON.stringify(event);
+                const isCloud = config?.runtime === 'cloud';
+                const prefix = isCloud ? 'Cloud run failed' : 'Local run failed';
+                return `**Cursor error:** ${prefix}. Event details: \`${details}\``;
+            }
+            return formatCloudStatus(event.status, event.message, config);
+        }
+        case 'task': {
+            if (!event.text?.trim())
+                return undefined;
+            return truncate(event.text);
+        }
+        default:
+            return undefined;
+    }
+};
+export const formatCursorError = (error) => {
+    if (error instanceof CursorSdkError) {
+        const parts = [error.message];
+        if (error.requestId)
+            parts.push(`(requestId: ${error.requestId})`);
+        const helpUrl = error.helpUrl;
+        if (helpUrl)
+            parts.push(`See ${helpUrl}`);
+        return parts.join(' ');
+    }
+    if (error instanceof Error) {
+        const extra = { ...error };
+        if (Object.keys(extra).length > 0) {
+            return `${error.message} (details: ${JSON.stringify(extra)})`;
+        }
+        return error.message;
+    }
+    try {
+        return typeof error === 'object' && error !== null
+            ? JSON.stringify(error)
+            : String(error);
+    }
+    catch {
+        return String(error);
+    }
+};

package/dist/index.js

@@ -0,0 +1,132 @@
+import { agentOutput, definePlugin, shouldHandleInvoke, } from '@meetopenbot/plugin-sdk';
+import { CURSOR_API_KEY_ENV_VAR, resolveConfig, } from './config.js';
+import { formatCursorError } from './format.js';
+import { getOrCreateCursorAgent } from './session.js';
+import { streamCursorPrompt } from './stream.js';
+export default definePlugin({
+    id: 'cursor',
+    name: 'Cursor',
+    description: 'Cursor coding agent — read, edit, and run code via the Cursor SDK.',
+    configSchema: {
+        type: 'object',
+        properties: {
+            apiKey: {
+                type: 'string',
+                description: 'Cursor API key. Falls back to CURSOR_API_KEY.',
+                format: 'password',
+            },
+            runtime: {
+                type: 'string',
+                description: 'Agent runtime: local (default) or cloud.',
+                enum: ['local', 'cloud'],
+                default: 'local',
+            },
+            model: {
+                type: 'string',
+                description: 'Cursor model id (default: composer-2.5).',
+                default: 'composer-2.5',
+            },
+            thinking: {
+                type: 'string',
+                description: 'Reasoning effort for models that support it (e.g. low, high).',
+            },
+            mode: {
+                type: 'string',
+                description: 'Conversation mode: agent (default) or plan.',
+                enum: ['agent', 'plan'],
+            },
+            cwd: {
+                type: 'string',
+                description: 'Working directory for local agents.',
+            },
+            repoUrl: {
+                type: 'string',
+                description: 'Git repository URL for cloud agents.',
+                format: 'url',
+            },
+            startingRef: {
+                type: 'string',
+                description: 'Git ref to clone for cloud agents (e.g. main).',
+            },
+            autoCreatePR: {
+                type: 'boolean',
+                description: 'Open a pull request when a cloud run finishes.',
+                default: false,
+            },
+            workOnCurrentBranch: {
+                type: 'boolean',
+                description: 'Push cloud commits to the existing branch instead of a new one.',
+                default: false,
+            },
+            settingSources: {
+                type: 'string',
+                description: 'Comma-separated local settings layers: project,user,team,mdm,plugins,all.',
+            },
+            sandbox: {
+                type: 'boolean',
+                description: 'Enable the local agent sandbox.',
+                default: false,
+            },
+            autoReview: {
+                type: 'boolean',
+                description: 'Route local tool calls through Auto-review.',
+                default: false,
+            },
+        },
+    },
+    factory: (context) => (builder) => {
+        builder.on('agent:invoke', async function* (event, handlerCtx) {
+            if (!shouldHandleInvoke(event, context.agentId))
+                return;
+            const threadId = event.meta?.threadId ?? handlerCtx.state.threadId;
+            const prompt = (event.data.content ?? '').trim();
+            if (!prompt) {
+                yield agentOutput({
+                    agentId: context.agentId,
+                    content: 'Send a message to run Cursor in this workspace — for example, "Summarize this repo" or "Fix the failing test in src/foo.test.ts".',
+                    threadId,
+                });
+                return;
+            }
+            const channelCwd = handlerCtx.state.channelDetails?.cwd;
+            const config = resolveConfig(context, channelCwd);
+            if (!config.apiKey) {
+                yield agentOutput({
+                    agentId: context.agentId,
+                    content: `Set a Cursor API key in plugin config (\`apiKey\`) or the \`${CURSOR_API_KEY_ENV_VAR}\` environment variable. Get a key from https://cursor.com/dashboard/api`,
+                    threadId,
+                });
+                return;
+            }
+            if (config.runtime === 'local' && !config.cwd && !channelCwd) {
+                yield agentOutput({
+                    agentId: context.agentId,
+                    content: 'Local Cursor agents need a working directory. Set `cwd` in plugin config or configure a channel `cwd`.',
+                    threadId,
+                });
+                return;
+            }
+            try {
+                const { agent } = await getOrCreateCursorAgent({
+                    config,
+                    state: handlerCtx.state,
+                    storage: context.storage,
+                });
+                for await (const chunk of streamCursorPrompt(agent, prompt, config)) {
+                    yield agentOutput({
+                        agentId: context.agentId,
+                        content: chunk,
+                        threadId,
+                    });
+                }
+            }
+            catch (error) {
+                yield agentOutput({
+                    agentId: context.agentId,
+                    content: `**Cursor error:** ${formatCursorError(error)}`,
+                    threadId,
+                });
+            }
+        });
+    },
+});

package/dist/session.js

@@ -0,0 +1,78 @@
+import { Agent, } from '@cursor/sdk';
+import { buildModelSelection, } from './config.js';
+import { formatCursorError } from './format.js';
+import { persistCursorState, readPersistedState } from './state.js';
+const sessionCache = new Map();
+const buildSessionKey = (state) => state.threadId ? `${state.channelId}:${state.threadId}` : state.channelId;
+const buildAgentOptions = (config) => {
+    const options = {
+        apiKey: config.apiKey,
+        model: buildModelSelection(config),
+        ...(config.mode ? { mode: config.mode } : {}),
+    };
+    if (config.runtime === 'cloud') {
+        options.cloud = {
+            ...(config.repoUrl
+                ? {
+                    repos: [
+                        {
+                            url: config.repoUrl,
+                            ...(config.startingRef ? { startingRef: config.startingRef } : {}),
+                        },
+                    ],
+                }
+                : {}),
+            autoCreatePR: config.autoCreatePR,
+            workOnCurrentBranch: config.workOnCurrentBranch,
+        };
+    }
+    else {
+        options.local = {
+            cwd: config.cwd || process.cwd(),
+            ...(config.settingSources ? { settingSources: config.settingSources } : {}),
+            ...(config.sandbox ? { sandboxOptions: { enabled: true } } : {}),
+            ...(config.autoReview ? { autoReview: true } : {}),
+        };
+    }
+    return options;
+};
+const resumeOptions = (config) => ({
+    apiKey: config.apiKey,
+    model: buildModelSelection(config),
+    ...(config.mode ? { mode: config.mode } : {}),
+});
+const createAgent = async (config) => Agent.create(buildAgentOptions(config));
+const resumeAgent = async (cursorAgentId, config) => Agent.resume(cursorAgentId, resumeOptions(config));
+export const getOrCreateCursorAgent = async (args) => {
+    const { config, state, storage } = args;
+    const sessionKey = buildSessionKey(state);
+    const cached = sessionCache.get(sessionKey);
+    if (cached)
+        return cached;
+    const persisted = readPersistedState(state);
+    let agent;
+    if (persisted.cursorAgentId) {
+        try {
+            agent = await resumeAgent(persisted.cursorAgentId, config);
+        }
+        catch (error) {
+            console.warn(`[cursor-plugin] Failed to resume ${persisted.cursorAgentId}: ${formatCursorError(error)}`);
+        }
+    }
+    if (!agent) {
+        agent = await createAgent(config);
+        if (agent.agentId !== persisted.cursorAgentId) {
+            await persistCursorState(state, storage, { cursorAgentId: agent.agentId });
+        }
+    }
+    const handle = { agent, sessionKey };
+    sessionCache.set(sessionKey, handle);
+    return handle;
+};
+export const disposeCursorAgent = async (sessionKey) => {
+    const cached = sessionCache.get(sessionKey);
+    if (!cached)
+        return;
+    await cached.agent[Symbol.asyncDispose]();
+    sessionCache.delete(sessionKey);
+};

package/dist/state.js

@@ -0,0 +1,21 @@
+const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+export const readPersistedState = (state) => {
+    const source = state.threadDetails?.state ?? state.channelDetails?.state;
+    const record = asRecord(source);
+    return typeof record.cursorAgentId === 'string'
+        ? { cursorAgentId: record.cursorAgentId }
+        : {};
+};
+export const persistCursorState = async (state, storage, patch) => {
+    if (state.threadId) {
+        await storage.patchThreadState({
+            channelId: state.channelId,
+            threadId: state.threadId,
+            state: patch,
+        });
+        return;
+    }
+    await storage.patchChannelState({ channelId: state.channelId, state: patch });
+};

package/dist/stream.js

@@ -0,0 +1,76 @@
+import { buildModelSelection } from './config.js';
+import { createStreamState, formatCursorEvent } from './format.js';
+/** Bridge Cursor SDK run events into an async generator of output chunks. */
+export async function* streamCursorPrompt(agent, prompt, config) {
+    const state = createStreamState();
+    const pending = [];
+    let wake;
+    let finished = false;
+    let error;
+    const wakeUp = () => {
+        wake?.();
+        wake = undefined;
+    };
+    const run = await agent.send(prompt, {
+        ...(config.mode ? { mode: config.mode } : {}),
+        model: buildModelSelection(config),
+    });
+    const streamTask = (async () => {
+        try {
+            for await (const event of run.stream()) {
+                const chunk = formatCursorEvent(event, state, config);
+                if (chunk) {
+                    pending.push(chunk);
+                    wakeUp();
+                }
+            }
+            const result = await run.wait();
+            const finalText = (result.result ?? state.assistantText).trim();
+            if (finalText) {
+                pending.push(finalText);
+            }
+            if (result.status === 'error') {
+                const details = JSON.stringify(result);
+                pending.push(`**Cursor error:** Run finished with error status. Details: \`${details}\``);
+            }
+            else if (result.status === 'cancelled') {
+                pending.push('**Cursor:** Run cancelled.');
+            }
+            if (result.git?.branches?.length) {
+                const branches = result.git.branches
+                    .map((branch) => {
+                    const parts = [branch.branch, branch.prUrl].filter(Boolean);
+                    return parts.join(' — ');
+                })
+                    .filter(Boolean);
+                if (branches.length) {
+                    pending.push(`Git: ${branches.join('; ')}`);
+                }
+            }
+        }
+        catch (err) {
+            error = err instanceof Error ? err : new Error(String(err));
+        }
+        finally {
+            finished = true;
+            wakeUp();
+        }
+    })();
+    try {
+        while (!finished || pending.length > 0) {
+            if (pending.length === 0) {
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+                continue;
+            }
+            yield pending.shift();
+        }
+        await streamTask;
+        if (error)
+            throw error;
+    }
+    finally {
+        // no-op: keep the Cursor agent alive for follow-ups
+    }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@meetopenbot/cursor",
+  "version": "0.0.1",
+  "description": "OpenBot agent plugin powered by the Cursor SDK.",
+  "type": "module",
+  "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@cursor/sdk": "^1.0.18",
+    "@meetopenbot/plugin-sdk": "^0.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3"
+  }
+}