Add Cursor agent provider

[dichioniccolo]

Problem Statement

Sandcastle currently supports multiple agent providers, but Cursor Agent is not available as a first-class option.

Solution

Add Cursor as a built-in Sandcastle provider with full scaffold and runtime integration. Ensure users can initialize projects with Cursor defaults, stream output in a parseable format, run interactive sessions, configure auth via environment variables, and consume the provider via public exports.

User Stories

1. As a Sandcastle user, I want Cursor to be selectable during setup, so that I can use the same agent stack as my team.
2. As a developer, I want generated projects to include Cursor-ready runtime configuration, so that I can run without manual bootstrapping.
3. As a maintainer, I want Cursor to implement the same provider interface as existing agents, so that runtime orchestration remains uniform.
4. As a user, I want print-mode output to be emitted in structured JSON events, so that downstream parsing is reliable.
5. As a developer, I want prompts sent over stdin in print mode, so that shell escaping edge cases are minimized.
6. As a user, I want interactive mode argument construction to be deterministic, so that local debugging is predictable.
7. As a security-conscious user, I want API credentials represented through environment templates, so that secrets stay out of source code.
8. As a scaffold consumer, I want a provider-specific Dockerfile, so that required tools are preinstalled in sandbox environments.
9. As an integrator, I want Cursor exported from the package API, so that I can import it directly in custom setups.
10. As a test maintainer, I want coverage for provider behavior and scaffold output, so that regressions are caught before release.
11. As a maintainer, I want Cursor listed in the agent registry, so that agent discovery works consistently.
12. As a user, I want generated .env.example guidance for Cursor auth, so that setup steps are clear.
13. As a developer, I want non-supported features (like session usage parsing) to be explicit, so that behavior is unsurprising.
14. As a CI owner, I want scaffold snapshots/assertions to include Cursor paths, so that template drift is detected early.
15. As a contributor, I want provider defaults (name/model/import) centralized in registry metadata, so that updates are low-risk.

Implementation Decisions

• Introduce a dedicated Cursor provider factory that conforms to the existing AgentProvider contract.
• Add Cursor-specific options for environment variable injection to align with existing provider customization patterns.
• Use stream-JSON output mode for print execution and parse emitted events through the established stream parsing flow.
• Keep print execution prompt transport via stdin and interactive execution via argv-based prompt argument.
• Register Cursor in the scaffold agent catalog with explicit metadata (display label, default model, factory import token, env template, Dockerfile template).
• Add a Cursor-focused Dockerfile scaffold template that installs required base tools plus Cursor Agent CLI.
• Extend package exports to include Cursor factory and Cursor option types.
• Maintain parity with non-Claude providers by leaving session capture/usage parsing behavior disabled where unsupported.
• Preserve current architecture by extending existing module boundaries rather than introducing new orchestration layers.

Testing Decisions

• Favor behavior-driven tests that assert observable outputs (commands, args, parsed events, generated scaffold files) rather than internal implementation details.
• Add provider-level tests for:
  • identity and capability flags,
  • print command composition and stdin behavior,
  • interactive args with and without prompt,
  • stream event parsing for assistant text, tool-use, and result payloads,
  • env option pass-through behavior,
  • unsupported resume/session-usage semantics.
• Add scaffold-level tests for:
  • Cursor presence in agent registry and expected metadata,
  • .env.example containing Cursor auth key template,
  • generated Dockerfile containing Cursor installation steps,
  • generated main scaffold file importing/initializing Cursor provider.
• Reuse existing testing patterns already established for other providers and scaffold generation assertions.

[vercel]

@dichioniccolo is attempting to deploy a commit to the Matt Pocock's projects Team on Vercel.

A member of the Team first needs to authorize it.