[jacobprall]

Fixes #68. Depends on #71, which depends on #70; their commits are included until they merge. Review the last commit.

cursor({ model: { id: "composer-2.5" } }) runs an agent on a local Cursor agent inside the Sandbox, with Cursor-hosted models and CURSOR_API_KEY delivered on stdin.

Design

• Tools: the factory's only. Cursor's built-in tools are off (tools: ["mcp"]). The model gets the factory's five tools and submit as custom tools, the only MCP server it sees. So tool authority and the read-only shell policy match pi and Pydantic AI. This differs from Add a Cursor SDK harness adapter #68's plan, which kept Cursor's native file tools: the SDK has no native write, and the extension runbook in Run agents on imported harness adapters #70 says a harness offers only factory tools.
• Ambient config: off. settingSources: []. The spike confirmed that a canary rule, an AGENTS.md instruction, and a hook in the checkout's .cursor/ all had no effect.
• System prompt: not replaced by default. Cursor enables system-prompt replacement per account, and our test account doesn't have it ("Custom system prompt is not enabled for this account"). By default the agent's prompt leads the first message, under Cursor's own system prompt; replaceSystemPrompt: true opts in.
• Limits: turns are counted per tool-call batch. A run stops at max_turns, at its time budget, after the last rejected submission, or when work continues past an accepted one. A run that ends without submitting gets one reminder, as on pi.
• Runtime: local only, inside the Sandbox. The cloud runtime isn't offered: it runs outside the Sandbox and can write to GitHub itself.

Packaging

In 1.0.40, the SDK's flat build doesn't load on Node: it imports bun:sqlite and calls Bun-only code. Its default build lazy-loads its own files, so it can't be single-file bundled. So:

• the runner bundle leaves @cursor/sdk external;
• the adapter's provision (from Add a Pydantic AI harness adapter #71) ships cursor/package.json and cursor/package-lock.json, and runs npm ci with the base image's npm into a root-owned APP_DIR/cursor-sdk, about 2.5 seconds. The Linux platform package comes from the lockfile.
• Node 22.13+ is checked in the adapter's self-test; the base image ships Node v24.14.1.

Tests

• Static checks, always run: the adapter declares CURSOR_API_KEY and ships the locked runtime; the pins in cursor/package.json, package.json, and CURSOR_SDK_VERSION agree; --test-stub runs are refused.
• Live checks, on request: Cursor's models can't be scripted, so the contract tests run with CURSOR_LIVE=1 CURSOR_API_KEY=… npx vitest run tests/harness-cursor.test.ts. The agent reads a file and submits valid output; a read-only agent's git push is rejected by the factory's policy; no key appears in the output or the tool environment. Both live tests pass on Composer 2.5.

Verification

• npm run check passes: 165 tests, plus 2 live tests skipped by default.
• One autopilot run on the test deployment covered all three harnesses: Triage on Pydantic AI, the spec writer on pi, then the implementer and PR Reviewer on Cursor. It verified the change, opened a draft PR adding one file, and posted a COMMENT review, in under five minutes.
• A snapshot refresh applied both provisions at build time.

Known gaps

• No Cursor cost in telemetry. The SDK reports tokens but not dollars, so costUsd is 0 for Cursor agents. Spend shows in Cursor's dashboard.
• The Cursor conversation store lives in scratch. The harness keeps its run store in the Sandbox's scratch directory, which the agent's tools can write. This is listed in the residual risks.

Deploying

Deploy factory-workflows, add CURSOR_API_KEY to .env, and run npm run setup:render; the key is derived from the agents' harnesses. Use a team service-account key with a spend limit. Then refresh snapshots so Sandboxes don't each reinstall the SDK.

[jacobprall]

Consolidated into #73.