Proposal: Cursor Composer agent adapter (headless repo tasks via @cursor/sdk)

[jtorelli-metalworks]

Summary

We have a working Cursor Composer integration for headless repo tasks on a public fork and would like to offer it upstream if it fits your roadmap.

Optio already supports multiple coding agents (Claude Code, Codex, Copilot, Gemini, OpenCode). Composer fits the same “multi-vendor, self-hosted” story described in the README—teams that want Cursor’s models but cannot use hosted background agents in their environment.

There are no existing open issues on this repo for Cursor/Composer support, so we wanted to start the conversation here before opening a large PR.

What we built (reference implementation)

Fork: https://github.com/jtorelli-metalworks/optio (main)

Guide: https://github.com/jtorelli-metalworks/optio/blob/main/docs/guides/cursor-agent.md

High-level shape:

• New agent type cursor in the agent adapter layer (packages/agent-adapters/src/cursor.ts)
• Repo fields: defaultAgentType: cursor, cursorModel (e.g. composer-2.5)
• Headless runner in agent pods: node /opt/optio/run-cursor-agent.mjs using @cursor/sdk (Agent.create() + run.stream())
• OpenClaw-compatible NDJSON output, including session_id from OPTIO_TASK_ID for stall detection / session tracking
• Secret: CURSOR_API_KEY (workspace global or per-repo via secret proxy)
• DB migration for cursor-related repo columns
• Agent base image includes @cursor/sdk for ESM resolution in pods

Review lane: Composer is used for implement tasks only in v1; review tasks still run on another supported agent (e.g. Claude Code), matching how other vendors are split today.

Known limitations (v1):

• Resume / multi-turn is one-shot agent.send() rather than full multi-turn resume
• Requires a cursor-enabled agent image build (images/base.Dockerfile)

Why upstream?

• Keeps Optio’s “pick your agent vendor per repo” positioning coherent
• Avoids a permanent fork divergence for a feature that is mostly additive (adapter + runner + image dep + migration)
• Lets you set policy on image size, API key handling, and maintenance expectations

Offer

Happy to open a focused upstream PR (adapter, runner, migration, docs, image changes—no unrelated fork-only release-line changes) if you want this. We can also trim or adjust based on your preferences (e.g. feature flag, experimental agent type, docs-only first step).

Questions for maintainers

1. Is Cursor/Composer agent support something you want in core Optio?
2. Any constraints we should design for upfront (agent image size, GHCR publishing, review-agent split, experimental vs stable)?
3. Preferred contribution path: issue discussion → PR, or smaller incremental PRs?

Thanks for building Optio—happy to collaborate on whatever shape works best for the project.