Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Feature]: Add Cursor SDK (`@cursor/sdk`) as a core agent backend [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#75044•Fetched 2026-05-01 05:38:47
View on GitHub
Comments
1
Participants
2
Timeline
9
Reactions
2
Author
a-tokyoa-tokyo
Participants
a-tokyoa-tokyoclawsweeper[bot]clawsweeper[bot]
Timeline (top)
mentioned ×3subscribed ×3commented ×1cross-referenced ×1

Add Cursor SDK (@cursor/sdk) as an agent backend for OpenClaw, enabling task delegation to Cursor's local and cloud agent runtimes via the existing AgentHarness plugin system.

Error Message

  • Timeout enforcement, run status checking, error classification, and agent disposal

Root Cause

Add Cursor SDK (@cursor/sdk) as an agent backend for OpenClaw, enabling task delegation to Cursor's local and cloud agent runtimes via the existing AgentHarness plugin system.

Fix Action

Fix / Workaround

  1. Core dispatch integration (rejected): Adds @cursor/sdk to root package.json, pollutes dependency tree for all installs, requires core dispatch branches in 5+ files. Conflicts with VISION.md ("core stays lean").
  2. ACP/acpx route (deferred): Existing ACP path uses cursor-agent acp CLI. The SDK provides a richer programmatic interface with cloud VM support that ACP doesn't expose.
  3. CLI backend (rejected): The Cursor SDK is an API library, not a subprocess. registerCliBackend is the wrong contract.

PR fix notes

PR #75046: feat: add Cursor SDK agent harness plugin (extensions/cursor-sdk)

Description (problem / solution / changelog)

Closes #75044

Summary

  • Problem: OpenClaw lacks a Cursor SDK agent backend — users cannot delegate tasks to Cursor's local or cloud agent runtimes.
  • Why it matters: The Cursor SDK (@cursor/sdk) provides a TypeScript-native interface for Cursor agents with local and cloud execution modes, expanding the agent backend ecosystem alongside Claude CLI and Codex.
  • What changed: Added cursor-sdk as a self-contained extension plugin at extensions/cursor-sdk/, following the AgentHarness pattern established by the Codex plugin. The plugin registers via definePluginEntry + api.registerAgentHarness() and is activated on-demand when cursor-sdk is configured as the agent runtime.
  • Architecture: The @cursor/sdk dependency lives only in the extension's own package.json — zero impact on root dependency tree. Core dispatch, config types, and auth pipelines are untouched; routing is handled by the generic harness selection layer.
  • What did NOT change: No existing providers, CLI backends, embedded Pi runner, auth profiles, or core files were modified. The Cursor SDK agent already has its full built-in harness (codebase indexing, file editing, terminal, MCP servers, subagents) — same as how Claude CLI ships with its own tools.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

Root Cause (if applicable)

N/A — new feature.

Regression Test Plan (if applicable)

  • Coverage level that should have caught this:
    • Unit test
    • Seam / integration test
    • End-to-end test
    • Existing coverage already sufficient
  • Target test or file: extensions/cursor-sdk/harness.test.ts, extensions/cursor-sdk/src/error-classification.test.ts
  • Scenario the test should lock in: Provider detection (supports() for cursor-sdk), error classification (SDK AuthenticationError → auth, RateLimitError → rate_limit, timeout by elapsed/message, billing patterns), case-insensitive provider matching, rejection of non-cursor-sdk providers.
  • Why this is the smallest reliable guardrail: Tests validate the harness contract and error classification without requiring a live API key or SDK connection.
  • Existing test that already covers this (if any): None — new extension.

Implementation Details

Extension structure (extensions/cursor-sdk/)

FilePurpose
package.jsonOwns @cursor/sdk dependency in isolation
openclaw.plugin.jsonManifest: providers, activation, configSchema
index.tsdefinePluginEntry + registerAgentHarness
harness.tsAgentHarness with supports() and lazy runAttempt()
src/run-attempt.tsRunner: timeout enforcement, run status checking, streaming, disposal
src/error-classification.tsSDK error → reason mapping

Key design decisions

  1. Plugin, not core: Follows VISION.md guidance ("core stays lean, optional capability ships as plugins"). No core dispatch branches, no root dependency pollution.
  2. AgentHarness pattern: Same registration contract as Codex (api.registerAgentHarness), activated via onAgentHarnesses: ["cursor-sdk"].
  3. Dependency isolation: @cursor/sdk and its transitive deps (undici, connectrpc) live only in extensions/cursor-sdk/node_modules — not in root install.
  4. Timeout + status: setTimeout + run.cancel() for timeout enforcement; RunResult.status checked for error/cancelled terminal states.
  5. Config via plugin schema: Runtime (local/cloud), model, cloud repos, local cwd — all via openclaw.plugin.json configSchema.

Auth

Users set CURSOR_API_KEY in their environment. The harness receives the resolved key via params.resolvedApiKey from the runtime auth plan.

Checklist

  • Extension-only change (zero core modifications)
  • Tests pass locally (13 tests, oxlint clean)
  • pnpm-lock.yaml regenerated with isolated deps
  • No security advisories in extension deps
  • Follows existing plugin patterns (Codex reference)

Changed files

  • extensions/cursor-sdk/harness.test.ts (added, +34/-0)
  • extensions/cursor-sdk/harness.ts (added, +25/-0)
  • extensions/cursor-sdk/index.ts (added, +11/-0)
  • extensions/cursor-sdk/openclaw.plugin.json (added, +80/-0)
  • extensions/cursor-sdk/package.json (added, +20/-0)
  • extensions/cursor-sdk/src/error-classification.test.ts (added, +54/-0)
  • extensions/cursor-sdk/src/error-classification.ts (added, +39/-0)
  • extensions/cursor-sdk/src/run-attempt.ts (added, +241/-0)
  • package.json (modified, +2/-1)
  • pnpm-lock.yaml (modified, +768/-48)
  • src/config/zod-schema.agent-defaults.ts (modified, +1/-3)
RAW_BUFFERClick to expand / collapse

Summary

Add Cursor SDK (@cursor/sdk) as an agent backend for OpenClaw, enabling task delegation to Cursor's local and cloud agent runtimes via the existing AgentHarness plugin system.

Problem to solve

OpenClaw supports multiple agent backends (embedded Pi, Codex, Claude CLI, ACP/acpx) but has no native integration with the Cursor SDK, which was released as a TypeScript library ~24h ago. Users who want to delegate agentic coding tasks to Cursor's agent runtime currently have no direct path within OpenClaw's harness ecosystem.

Proposed solution

Implement Cursor SDK support as a self-contained extension plugin at extensions/cursor-sdk/, following the AgentHarness pattern established by the Codex plugin:

  • Register via definePluginEntry + api.registerAgentHarness()
  • Activated on-demand via activation.onAgentHarnesses: ["cursor-sdk"]
  • @cursor/sdk dependency isolated in the extension's own package.json (zero root dep impact)
  • Supports both local execution (user's machine) and cloud execution (Cursor VM)
  • Plugin-owned config schema for runtime, model, cloud repos, local cwd
  • Timeout enforcement, run status checking, error classification, and agent disposal

Alternatives considered

  1. Core dispatch integration (rejected): Adds @cursor/sdk to root package.json, pollutes dependency tree for all installs, requires core dispatch branches in 5+ files. Conflicts with VISION.md ("core stays lean").
  2. ACP/acpx route (deferred): Existing ACP path uses cursor-agent acp CLI. The SDK provides a richer programmatic interface with cloud VM support that ACP doesn't expose.
  3. CLI backend (rejected): The Cursor SDK is an API library, not a subprocess. registerCliBackend is the wrong contract.

Impact

  • Users can configure cursor-sdk as their agent runtime to delegate tasks to Cursor agents
  • No impact on existing installs (extension deps are isolated)
  • No core files modified

Evidence/examples

Additional information

Out of scope for initial implementation:

  • Persistent sessions across messages (analogous to Claude CLI "live session" mode)
  • Injecting OpenClaw-specific tools into the Cursor agent sandbox
  • Full onboarding wizard plugin (env var CURSOR_API_KEY is sufficient for early adopters)
  • Publishing to ClawHub (can follow once the extension stabilizes)

extent analysis

TL;DR

Implement the Cursor SDK as a self-contained extension plugin within OpenClaw to enable task delegation to Cursor's agent runtime.

Guidance

  • Create a new directory extensions/cursor-sdk/ and initialize a new package.json file to isolate the @cursor/sdk dependency.
  • Register the Cursor SDK plugin using definePluginEntry and api.registerAgentHarness(), following the pattern established by the Codex plugin.
  • Implement plugin-owned config schema for runtime, model, cloud repos, and local cwd, as well as timeout enforcement, run status checking, error classification, and agent disposal.
  • Activate the plugin on-demand via activation.onAgentHarnesses: ["cursor-sdk"].

Example

// extensions/cursor-sdk/index.js
import { definePluginEntry } from '@openclaw/core';
import { api } from '@openclaw/api';

definePluginEntry(() => {
  api.registerAgentHarness('cursor-sdk', {
    // implementation details
  });
});

Notes

The initial implementation will not include features like persistent sessions, injecting OpenClaw-specific tools, or a full onboarding wizard. These features can be added in subsequent iterations.

Recommendation

Apply the proposed solution by implementing the Cursor SDK as a self-contained extension plugin, as it allows for a clean and isolated integration without impacting the core codebase or existing installs.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#embedding generation#cache error#pipeline error#runtime error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix [Feature]: Add Cursor SDK (`@cursor/sdk`) as a core agent backend [1 pull requests, 1 comments, 2 participants]