Add native Cursor support to SkillOpt-Sleep

[jamesmdavies88]

Summary

Adds native Cursor support to SkillOpt-Sleep:

• harvest local Cursor Agent transcripts with --source cursor
• run Sleep through a native Cursor command and skill
• optionally use an authenticated Cursor Agent CLI with --backend cursor

Cursor remains opt-in. --source auto keeps its existing Codex-then-Claude precedence.

The separate core cursor_exec benchmark target has been split into #160.

Changes

Transcript harvesting

Adds Cursor transcript harvesting from ~/.cursor/projects/<workspace>/agent-transcripts/ with:

• invoked-project and all-workspace scoping
• workspace metadata and sanitized-slug fallback matching
• user/assistant text, safe tool names, and explicit turn-error extraction
• secret-pattern redaction and exact replay-session filtering
• malformed-record tolerance, mtime filtering, ordering, and limits

Tool arguments, tool outputs, and unrelated records are excluded.

Cursor Agent backend

Ordinary mining, replay, judging, and reflection calls:

• send prompts through stdin and parse the terminal JSON result
• use read-only Ask mode in a new empty temporary workspace
• deny project file reads, writes, and MCP access through an isolated Cursor configuration
• retry once only for a timeout or zero-exit malformed response
• surface redacted authentication, timeout, process, nonzero-exit, and malformed-output failures

The target skill is inserted into prompts as text. It is not invoked as a native Cursor skill, and ordinary calls cannot inspect the target repository or run its tools.

Cursor Agent-mode tool-aware replay is temporarily disabled pending live permission-boundary validation. A task containing a tool_called check fails nonzero before Agent mode starts. The failed replay does not add a cache entry, stage, adopt, persist state, or advance the harvest checkpoint. Users must select another backend for those tasks.

Restoring tool-aware Cursor replay requires a separate future PR with the requested real-CLI adversarial matrix covering allowlisted shims, command chaining, external reads/writes, WebFetch, MCP, and user-configuration isolation.

Cursor plugin

Adds plugins/cursor/ with:

• native /skillopt-sleep command
• standalone skillopt-sleep skill
• plugin manifest and repository marketplace registration
• macOS/Linux and Windows local installers
• installation, scheduling, and data-boundary documentation

The learned skill target is .cursor/skills/skillopt-sleep-learned/SKILL.md.

The plugin installs no session-end hook and does not run Sleep automatically. Runs remain user-triggered or explicitly scheduled, and adoption remains separate unless deliberately enabled.

CLI and configuration

Adds:

• --source cursor
• --backend cursor
• --cursor-home PATH
• --cursor-path PATH
• cursor_home
• cursor_path
• SKILLOPT_SLEEP_CURSOR_PATH
• SKILLOPT_SLEEP_CURSOR_MODEL

No existing defaults or auto source behavior change.

Operational notes

• Real Cursor runs send prompt content to Cursor and its selected model provider.
• Both run and dry-run make provider calls with --backend cursor; dry-run prevents staging and state persistence, not provider spend.
• Session and task limits are workload controls, not hard call, token, time, or cost limits.
• Redaction reduces accidental secret exposure but is not a data-loss-prevention guarantee.
• Cursor's local transcript layout is undocumented and may change.
• Public Cursor Marketplace submission remains outside this repository change.

Validation

• focused Sleep/plugin/schema suite: 107 passed, 1 skipped
• full suite: 340 passed, 5 skipped
• python -m mkdocs build --strict: passed
• Cursor installer shell syntax: passed
• Cursor-focused Ruff checks: passed
• git diff --check: passed

Live Cursor Agent Ask-mode execution was previously exercised on macOS. Windows packaging and transcript behavior remain covered by offline tests.

[jamesmdavies88]

@jamesmdavies88 please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

@microsoft-github-policy-service agree

[Yif-Yang]

Thanks for the thorough Cursor integration and the new core SkillOpt target support. We reviewed the latest head and re-ran it locally: the focused suite reports 99 passed / 1 skipped / 5 subtests, the full suite reports 350 passed / 6 skipped / 5 subtests, and the diff check is clean. We also verified the new stream-json, --mode ask, --sandbox, --workspace, --add-dir, and --force arguments against the official 2026.07.17 Cursor Agent CLI. The new target-only core cursor_exec work in 81d4d05 looks useful and is substantially test-backed.

The remaining blocker is in the earlier SkillOpt-Sleep tool-replay path, which the latest commit does not change. Agent-mode replay runs with --sandbox disabled and relies on the isolated Cursor configuration plus the local-shim allowlist. The current tests validate generated arguments/configuration and use a fake Cursor executable, but they do not demonstrate that a real Cursor Agent rejects actions outside that allowlist. Because task, skill, and memory text can contain untrusted instructions, this is a host-safety boundary rather than a minor follow-up.

Could you please take one of these paths?

1. Preferred: split the final core cursor_exec commit into a separate PR so we can review and likely merge that independently while this PR finishes the Sleep security validation; or
2. Temporarily remove/disable the Agent-mode tool-aware Sleep replay, keeping the Ask-mode backend and harvester, until its boundary is verified.

For the Sleep tool replay, please provide a small live adversarial matrix against a stated Cursor Agent version showing:

• the allowlisted generated shim succeeds;
• an unlisted shell command and a compound command such as ./search; <other command> are rejected;
• reads/writes outside the temporary workspace are rejected;
• WebFetch and MCP calls are rejected; and
• user-level Cursor permissions/MCP configuration are not inherited.

Sanitized commands and results are sufficient; this does not need to run in public CI. For the core backend, the explicit sandbox=disabled plus file-edit/--force combination should also carry a prominent warning or guard, but that need not block an otherwise clean split PR.

We appreciate the scope and care in this contribution and want to retain it under your authorship. A split would let the already-useful core backend move forward without weakening the review of the separate Sleep execution boundary.

[jamesmdavies88]

Thanks for the thorough Cursor integration and the new core SkillOpt target support. We reviewed the latest head and re-ran it locally: the focused suite reports 99 passed / 1 skipped / 5 subtests, the full suite reports 350 passed / 6 skipped / 5 subtests, and the diff check is clean. We also verified the new stream-json, --mode ask, --sandbox, --workspace, --add-dir, and --force arguments against the official 2026.07.17 Cursor Agent CLI. The new target-only core cursor_exec work in 81d4d05 looks useful and is substantially test-backed.

The remaining blocker is in the earlier SkillOpt-Sleep tool-replay path, which the latest commit does not change. Agent-mode replay runs with --sandbox disabled and relies on the isolated Cursor configuration plus the local-shim allowlist. The current tests validate generated arguments/configuration and use a fake Cursor executable, but they do not demonstrate that a real Cursor Agent rejects actions outside that allowlist. Because task, skill, and memory text can contain untrusted instructions, this is a host-safety boundary rather than a minor follow-up.

Could you please take one of these paths?

1. Preferred: split the final core cursor_exec commit into a separate PR so we can review and likely merge that independently while this PR finishes the Sleep security validation; or
2. Temporarily remove/disable the Agent-mode tool-aware Sleep replay, keeping the Ask-mode backend and harvester, until its boundary is verified.

For the Sleep tool replay, please provide a small live adversarial matrix against a stated Cursor Agent version showing:

• the allowlisted generated shim succeeds;
• an unlisted shell command and a compound command such as ./search; <other command> are rejected;
• reads/writes outside the temporary workspace are rejected;
• WebFetch and MCP calls are rejected; and
• user-level Cursor permissions/MCP configuration are not inherited.

Sanitized commands and results are sufficient; this does not need to run in public CI. For the core backend, the explicit sandbox=disabled plus file-edit/--force combination should also carry a prominent warning or guard, but that need not block an otherwise clean split PR.

We appreciate the scope and care in this contribution and want to retain it under your authorship. A split would let the already-useful core backend move forward without weakening the review of the separate Sleep execution boundary.

Thank you for the detailed review and for verifying the current Cursor Agent CLI behavior.

I agree that the Agent-mode Sleep replay is enforcing a host-safety boundary that should not rely solely on generated configuration and mocked process tests.

I’ll take the preferred split:

1. Move 81d4d05 into a separate PR based on main, preserving the core target-only cursor_exec implementation and tests.
2. Remove that commit from this SkillOpt-Sleep PR.
3. Temporarily disable the Agent-mode tool-aware Cursor Sleep replay while retaining:
   • Cursor transcript harvesting;
   • the read-only Ask-mode backend;
   • the native Cursor plugin and skill; and
   • the existing adoption and scheduling boundaries.
4. Update the Sleep documentation and tests to make the temporary limitation explicit.

For the core PR, I’ll also add a guard preventing file-edit rollouts from combining --force with cursor_exec_sandbox=disabled.

I’ll treat re-enabling Sleep tool-aware replay as a separate follow-up requiring the live adversarial matrix described above against a stated Cursor Agent version.

Thanks again for identifying a path that allows the independently useful core support to move forward without weakening the Sleep security review.

[jamesmdavies88]

Implemented the requested split and fail-closed path.

• Core cursor_exec is now in Add Cursor Agent as a core SkillOpt target backend #160, based on main. It includes the requested guard: allow_file_edits=True with cursor_exec_sandbox=disabled raises before spawning Cursor Agent.
• This PR now contains only SkillOpt-Sleep Cursor support. The Agent-mode local-shim replay path, shim generation, permission allowlist, Windows shim handling, and call-log detection have been removed.
• A Cursor Sleep task with a tool_called check now fails nonzero before Agent mode starts with: Cursor tool-aware replay is temporarily disabled pending live Cursor permission-boundary validation.
• End-to-end coverage verifies no Cursor subprocess, cache entry, staging, adoption, state persistence, or harvest-checkpoint advancement for that failure.
• Cursor transcript harvesting, the read-only Ask-mode backend, plugin/skill, scheduling, redaction, and explicit adoption remain unchanged.

Validation after the split:

• Sleep focused suite: 107 passed, 1 skipped
• Sleep full suite: 340 passed, 5 skipped
• Core focused suite: 15 passed
• Core full suite: 333 passed, 5 skipped
• Strict MkDocs builds, targeted Ruff, installer shell syntax, and diff checks passed

The live adversarial matrix is intentionally deferred. It will be required in a separate future PR before Cursor Sleep tool-aware replay can be restored.

[Copilot]

Pull request overview

Adds opt-in native Cursor support to the SkillOpt-Sleep “shared engine” by introducing a Cursor transcript source, a Cursor Agent CLI backend, and a Cursor plugin packaging/install flow, along with supporting docs and tests.

Changes:

• Add --source cursor transcript harvesting from local Cursor Agent JSONL transcripts, including scoping, mtime filtering, replay-session filtering, and redaction.
• Add a cursor backend that drives authenticated cursor-agent in isolated Ask-mode workspaces, with explicit failure behavior for tool-aware replay.
• Add plugins/cursor/ (manifest, command, skill, installers, docs) plus documentation updates and parity tests.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_sleep_engine.py	Adds unit tests for Cursor harvesting behavior and Cursor backend behavior (including retries, redaction, and disabled tool-aware replay).
tests/test_plugin_sync.py	Extends parity tests to cover the new Cursor plugin assets and docs expectations.
skillopt_sleep/types.py	Updates SessionDigest docstring to include Cursor as a transcript source.
skillopt_sleep/replay.py	Clarifies documentation around tool-aware replay expectations and failure behavior.
skillopt_sleep/mine.py	Ensures CursorBackendError from LLM mining isn’t swallowed by the generic exception handler.
skillopt_sleep/harvest_sources.py	Wires --source cursor into harvest_for_config.
skillopt_sleep/harvest_cursor.py	Implements Cursor transcript parsing/digesting and workspace/session discovery logic.
skillopt_sleep/cycle.py	Passes cursor_path through to backend selection.
skillopt_sleep/config.py	Adds cursor_home and cursor_path defaults/config plumbing.
skillopt_sleep/backend.py	Adds Cursor CLI path resolution, CursorBackendError, and CursorCliBackend implementation + backend routing updates.
skillopt_sleep/main.py	Adds CLI flags for Cursor home/path, enables cursor in backend/source choices, and surfaces Cursor backend failures cleanly.
plugins/README.md	Documents Cursor as an additional shared-engine integration and describes Cursor-specific boundaries/behavior.
plugins/openclaw/run_sleep.py	Updates OpenClaw wrapper to pass through new backend parameters (cursor_path/project_dir).
plugins/cursor/skills/skillopt-sleep/SKILL.md	Adds Cursor skill guidance, including target path conventions and safety boundaries.
plugins/cursor/README.md	Adds Cursor integration documentation, install instructions, and workflow guidance.
plugins/cursor/LICENSE	Adds per-plugin license file (mirrors repo license).
plugins/cursor/install.sh	Adds macOS/Linux installer for local Cursor plugin installation.
plugins/cursor/install.ps1	Adds Windows installer for local Cursor plugin installation.
plugins/cursor/commands/skillopt-sleep.md	Adds native /skillopt-sleep command definition and safety defaults.
plugins/cursor/.cursor-plugin/plugin.json	Adds Cursor plugin manifest for local install.
docs/sleep/README.md	Documents Cursor source/backend boundaries and usage guidance.
docs/reference/cli.md	Adds Cursor flags and Cursor-specific source/backend documentation.
docs/guideline.html	Updates rendered guideline to reflect Cursor options and constraints.
docs/guide/installation.md	Documents Cursor backend prerequisites and environment/config controls.
CHANGELOG.md	Adds an unreleased changelog entry for Cursor SkillOpt-Sleep support.
.cursor-plugin/marketplace.json	Adds repository marketplace registration metadata for the Cursor plugin.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.