Add OneCLI gateway plugin for Cursor

[fireharp]

Summary

Adds first-class Cursor support to the OneCLI plugin monorepo, alongside existing Codex and Claude plugins.

Agents can call external APIs (GitHub, AWS, etc.) through the OneCLI HTTPS gateway without putting credentials, proxy URLs, or API keys in shell history, environment variables, or model context. Credentials are injected at the proxy boundary.

What's included

Area	Path	Notes
Cursor plugin bundle	plugins/cursor/	Manifest, hooks, 6 skills, 1 rule, README
TypeScript sources	src/cursor/	Built to plugins/cursor/hooks/*.mjs and bin/
Local marketplace	plugins/cursor/.cursor-plugin/marketplace.json	Required for Customize → Plugins → + Add
Setup guide	plugins/cursor/docs/CURSOR_SETUP.md	Text install & verification walkthrough
Project hooks fallback	plugins/cursor/scripts/install-project-hooks.sh	Writes .cursor/hooks.json when plugin hooks don't register
Workflow tests	tests/test_workflows.py	Manifest, hook wiring, session flow, command rewrite
Live E2E	tests/test_cursor_live_e2e.py	Real OneCLI Cloud + GitHub via proxy
Subagent verifier	tests/verify_cursor_agent_gateway.py	rate_limit proof without manual proxy setup

---

How it works

Cursor hooks use a hybrid activation model:

sessionStart  → write ~/.onecli/env.sh loader, fetch gateway config, return session env
preToolUse    → rewrite Shell commands to auto-source loader (fallback when session env missing)
sessionEnd    → remove loader file

Hook	Behavior
sessionStart	Writes non-secret ~/.onecli/env.sh, fetches OneCLI config when API key exists, returns { env, additional_context }
preToolUse (Shell)	Rewrites outbound network commands: ONECLI_CURSOR_AUTOSOURCED=1; . "$HOME/.onecli/env.sh" && <original>
sessionEnd	Cleans up loader

Skills & rules (ported from Codex): onecli-setup, onecli-status, onecli-gateway, onecli-providers, integration-architect, onecli-cleanup, plus rules/onecli-gateway.mdc.

Failure mode: No API key or unreachable gateway → command still runs without proxy; reason on stderr.

Why preToolUse? (brief)

Platform	Activation
Claude Code	sessionStart + BASH_ENV — every Bash auto-sources env; no preToolUse
Codex / Cursor	Hooks cannot persist session env → loader + conservative preToolUse rewrite

Cursor's preToolUse logic is identical to Codex (src/codex/pre-tool-use.mts / src/cursor/pre-tool-use.mts). The allowlist (curl, gh, network git/aws/terraform/package-manager subcommands, …) exists because sourcing the loader fetches OneCLI Cloud per command — we skip obviously-local commands (git status, terraform fmt, …).

Today: sessionStart returns session env, but Cursor/subagent shells don't always inherit it — preToolUse is the reliable path (verified: subagent rate_limit → 11400 with HTTPS_PROXY unset).

Deprecation path: Once Cursor reliably applies sessionStart env to all shells/subagents, drop preToolUse and use session-only activation (Claude-like). Full rationale, tradeoffs, and future options (shared module, inverse blocklist, cached loader): docs/hook-activation.md.

---

Install in Cursor

Build

npm install
npm run build

Add plugin (local repo)

1. Customize → Plugins → + Add → From Local Repo
2. Select plugins/cursor (contains .cursor-plugin/marketplace.json)
3. Under Onecli Local, click Add on OneCLI Gateway
4. Enable Settings → Features → Include third-party Plugins, Skills, and other configs
5. Developer: Reload Window, then open a new Agent session

Text guide: plugins/cursor/docs/CURSOR_SETUP.md

Screenshots (verified on Cursor 3.9.x)

Step 1 — Customize → + Add → From Local Repo

Step 2 — OneCLI Gateway in local marketplace

Step 3 — Plugin installed (✓ Added)

Step 4 — Skills, rules, and hooks loaded

Step 5 — Dashboard Activity proof

Fallback (known Cursor hook bug)

If plugin hooks don't appear in Settings → Hooks:

./plugins/cursor/scripts/install-project-hooks.sh /path/to/workspace

---

Verification

Automated

npm run build
npm run test                              # workflow suite (incl. cursor assertions)
npm run test:live-cursor                  # real OneCLI Cloud + GitHub zen/rate_limit
python3.12 tests/verify_cursor_agent_gateway.py

Gateway routing proof

GET https://api.github.com/rate_limit → resources.core.limit:

Value	Meaning
~11400	GitHub App auth via OneCLI gateway ✅
60	Direct unauthenticated — hooks not active ❌

HTTPS_PROXY stays unset in the shell; routing happens via preToolUse command rewrite.

Live subagent test (manual, recommended)

In a new Agent session after install, ask:

Use the OneCLI Gateway plugin in one concrete, useful way that shows why it's valuable in this workspace.

Verified result: subagent ran plain curl (no manual proxy, no source env.sh):

• GET /repos/onecli/onecli-plugin/pulls/7 → PR open, feat/cursor-plugin, mergeable
• GET /rate_limit → core.limit = 11400
• HTTPS_PROXY=<unset>

Dashboard Activity

OneCLI project Activity tab shows proxied requests (GET api.github.com/rate_limit, /repos/...) with HTTP 200. Requests may be labeled with the project's default agent name (e.g. "Codex") — expected, not a plugin bug.

---

Architecture notes

• Hook I/O: Cursor flat JSON (updated_input), not Codex hookSpecificOutput.
• sessionStart additional_context may be unreliable (Cursor forum); bundled rules compensate.
• Edit src/cursor/, run npm run build — same pipeline as Codex/Claude.
• Hook activation deep-dive: docs/hook-activation.md

---

Test plan

• npm run build
• npm run test — manifests, hook wiring, cursor session flow, preToolUse rewrite
• npm run test:live-cursor — real API key, proxied GitHub zen + rate_limit, sessionEnd cleanup
• Local install via Customize → Plugins → + Add (marketplace manifest)
• Plugin detail shows 6 skills, 1 rule, 3 hooks
• Subagent curl verification — core.limit = 11400, dashboard Activity rows
• Project hooks fallback script

---

Commits

1. 225ed26 — Add OneCLI gateway plugin for Cursor (hooks, skills, rules, tests)
2. 6f01a2c — Marketplace manifest, INSTALL.md, project-hooks fallback, verify script
3. 2d7b8b5 — Cursor setup guide (text)
4. aba6dde — Remove committed screenshots; images attached to this PR only
5. 34e1aa1 — Document hook activation model and preToolUse deprecation path