cursor-sdk-e2e-dev
Skill1 starsChanged 4 months agoApache-2.0View on GitHub
Spin up a live local OmniCraft server and exercise the Cursor SDK harness end-to-end — build cursor agents, run real turns, smoke-test, and bug-bash. Load when developing, testing, or debugging the cursor harness (omnicraft/inner/cursor_executor.py, cursor_harness.py, cursor_auth.py) or its auth / model / tool-bridge behavior.
- Reads credentials
- Deletes or force-pushes
- Commits and pushes
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- omnigent-ai/omnigentedited, first seen Oct 21, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- omnigent-ai/omnigent★ 11k93% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- antigravity-native-e2e-devSkill
- antigravity-sdk-e2e-devSkill
- cli-setup-verifySkill
- copilot-sdk-e2e-devSkill
- fucho-e2e-devSkill
- harness-integration-guideSkill
- pi-native-e2e-devSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
If both are False, run omni setup and register a Cursor key, or export CURSOR_API_KEY=crsr_….
- Very specific: line 42
Use the printed URL below as $SERVER.
- Very specific: line 81
Shell / file tools: add --tools coding.
- Very specific: line 82
Specific model: add --model gpt-5 (or composer-1, auto, databricks-claude-opus-4-8, …).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cursor SDK harness: end-to-end dev & testing
The cursor harness drives the Cursor Python SDK (cursor_sdk, an
AsyncAgent over a local bridge) and bridges OmniCraft's sys_* tools into
Cursor as SDK custom_tools. This skill is the proven recipe for running it
for real against a live local server — not just the unit tests.
The harness runs as a local runner from your current checkout, so
omni run <bundle> --server <url>exercises exactly the code you're on.
Prerequisites (check these first)
- You're on the branch you want to test. The cursor harness merged to
main(#203/#204). Test onmainunless validating a specific branch. - A Cursor API key is configured. The SDK requires an API key
(
crsr_…); there is nocursor-agent loginpath. Verify (booleans only — never print the key):
If both are.venv/bin/python -c "from omnicraft.onboarding.cursor_auth import cursor_api_key_configured; import os; print('config:', cursor_api_key_configured(), 'env:', bool(os.environ.get('CURSOR_API_KEY')))"False, runomni setupand register a Cursor key, orexport CURSOR_API_KEY=crsr_…. cursor-sdkis installed (a baseline dependency):.venv/bin/python -c "import cursor_sdk; print(cursor_sdk.__file__)".- Network egress to Cursor's backend. The bridge subprocess talks to Cursor's own API; a turn that hangs or fails to connect on a locked-down host is usually an egress problem, not a harness bug.
Step 1 — start a local server
cd /path/to/omnicraft
.venv/bin/omni server start # spawns a detached server on a free loopback port
.venv/bin/omni server status # prints the URL, e.g. http://127.0.0.1:6767Use the printed URL below as $SERVER. (You can also run a foreground
server on a fixed port with omnicraft server --port 7777 --no-open.)
Step 2 — build a cursor agent bundle
A spec with spec_version must be a directory containing config.yaml —
not a single .yaml file. Minimal cursor agent:
mkdir -p /tmp/cursor-dev
cat > /tmp/cursor-dev/config.yaml <<'YAML'
spec_version: 1
name: cursor-dev
description: Cursor SDK dev/test agent.
executor:
type: omnicraft
config:
harness: cursor
# model: gpt-5 # optional; omit for cursor "auto"
prompt: |
You are a terse test agent. Answer in as few words as possible.
YAMLFor sub-agents, tools, guardrails/policies, copy the field shapes from
examples/fucho/config.yaml and examples/lilo/config.yaml.
Step 3 — run a turn (and smoke-test)
SERVER=http://127.0.0.1:6767 # the URL from `omni server status`
timeout 280 .venv/bin/omni run /tmp/cursor-dev \
-p "Reply with exactly the single word: PONG" \
--server "$SERVER" 2>&1A healthy run prints connection lines then the assistant reply (PONG). If
that works, the full stack is good: key, egress, bridge, harness.
- Shell / file tools: add
--tools coding. - Specific model: add
--model gpt-5(orcomposer-1,auto,databricks-claude-opus-4-8, …).
Targeted scenarios
| Goal | How | |
| Native tools (shell/edit/read) | --tools coding, prompt to create→read→edit a file and run a shell command; confirm it actually touches disk | |
Bridged sys_* / sub-agent dispatch | declare a sub-agent (tools.agents/spawn), prompt the cursor agent to delegate — exercises the custom_tools daemon-thread bridge (run_coroutine_threadsafe) | |
| Model routing | run the same bundle with several --model values; note which actually runs | |
| Policy / guardrail | add a guardrail that denies a keyword; confirm PHASE_LLM_REQUEST/PHASE_LLM_RESPONSE blocks it | |
| Concurrency / leaks | fire several omni run … & at once; then `pgrep -af "cursor-sdk-bridge | cursor_sdk"` to check for orphaned bridge subprocesses |
Gotchas (these cost real time)
config.yaml'sserver:defaults to a remote server (e.g. a Databricks Apps URL). Omitting--serversends your turn to that remote deploy — which may be stale and reject the cursor harness withexecutor.config.harness: must be one of […], got 'cursor'. Always pass--server http://127.0.0.1:<port>for local testing. (That allowlist isomnicraft/spec/_omnicraft_compat.py; if a local server rejectscursor, it's running stale code — restart it from your checkout.)- A spec with
spec_versionmust be a directory +config.yaml, never a single.yamlfile. - Cursor needs a
crsr_API key (no CLI login). Resolution precedence: specexecutor.auth(api_key) > storedcursor:config block (omni setup) > ambientCURSOR_API_KEY. - No Databricks gateway. Cursor talks only to Cursor's backend, so a
databricks-*model is silently resolved to cursorauto— it will not route through the AI Gateway like claude-sdk/codex/pi. - Use a model id from the account's catalog. Bare
gpt-5is not valid; the SDK rejects unknown ids. Valid examples seen live:default,composer-2.5,claude-opus-4-8,gpt-5.5. Run with--modeland read the SDK'sAvailable models:list to discover the live set. - Turns take 30–90s — always wrap in
timeout 280. - Local-runner topology:
omni run <bundle> --server <url>runs the harness from your current checkout; the server only holds state. The managedomni server startserver runs from whatever venv launched it. - Never print/echo the Cursor key in logs or commands.
Code & tests
- Executor (SDK bridge):
omnicraft/inner/cursor_executor.py - Wrap (HARNESS_CURSOR_ env → executor):*
omnicraft/inner/cursor_harness.py - Auth / key resolution:
omnicraft/onboarding/cursor_auth.py - Spawn env:
_build_cursor_spawn_envinomnicraft/runtime/workflow.py
# Unit tests (use --frozen; the cwsandbox extra is unsatisfiable on public PyPI here)
uv run --frozen --extra dev python -m pytest \
tests/inner/test_cursor_executor.py \
tests/runtime/test_cursor_spawn_env.py \
tests/onboarding/test_cursor_auth.py -q
# Gated end-to-end harness test
uv run --frozen --extra dev python -m pytest tests/e2e/omnicraft/test_per_harness_cursor.py -qBug-bash (fan out)
To stress the harness, run several scenario probes in parallel — each builds a
bundle and runs real turns against the same $SERVER, then reports what broke.
Highest-value targets: the custom_tools bridge (hangs / lost tool results /
errors reported as success), model routing, policy enforcement, streamed-output
rendering, and orphaned bridge processes after teardown.
Known sharp edges (found via live bug-bash — "as of this writing")
Live-observed cursor-harness behaviors to watch for while testing (some may be fixed by the time you read this — verify):
- Start failures are swallowed. An invalid/unavailable
--model(or any bridge start error) makesomni run -pexit 0 with empty output, while the server records afailedsession + aRuntimeErroritem the user never sees. If a turn returns nothing, check the session status / items (GET /v1/sessions/{id}/items) — don't assume success. (claude-sdk surfaces such errors; cursor doesn't yet.) - Built-in coding tools bypass
on:[tool_call]policies. Cursor's native shell/file tools (--tools coding) don't emittool_callevents, soon:[tool_call]guardrails (e.g.blast_radius) never see them — a built-in shell can rungit push --forceeven under a DENY policy. Bridgedsys_*tools are gated correctly. Don't rely onon:[tool_call]guardrails for cursor built-in tools. - Run-on assistant text. Adjacent assistant text blocks are concatenated with no separator, so pre-tool narration can glue onto the post-tool answer.
- Non-graceful exit orphans the bridge. Graceful teardown reaps it (the
#221
aclosefix works), but aSIGKILL/hard-exit leaves an orphanedcursor-sdk-bridge. After hard kills, sweeppgrep -af cursor-sdk-bridge.
Cleanup
.venv/bin/omni server stop # stop the managed background server
rm -rf /tmp/cursor-dev # remove scratch bundles
pgrep -af "cursor-sdk-bridge" # confirm no orphaned bridge subprocesses lingerDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

