pi-cursor-bridge 0.1.0

package/extensions/index.ts

@@ -0,0 +1,15 @@
+// @ts-nocheck
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createStdioMcpExtension } from "./mcp-stdio.ts";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export default createStdioMcpExtension({
+  label: "Cursor Bridge",
+  clientName: "pi-cursor-bridge",
+  packageVersion: "0.1.0",
+  serverName: "cursor-bridge",
+  serverScript: join(packageRoot, "dist", "cursor-bridge.mjs"),
+  cwd: packageRoot,
+});

package/extensions/mcp-stdio.ts

@@ -0,0 +1,83 @@
+// @ts-nocheck
+import { existsSync } from "node:fs";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+function stringEnvironment(extra = {}) {
+  return Object.fromEntries(
+    Object.entries({ ...process.env, ...extra })
+      .filter(([, value]) => typeof value === "string"),
+  );
+}
+
+function toolContent(result) {
+  const items = Array.isArray(result?.content) ? result.content : [];
+  if (items.length === 0) {
+    return [{ type: "text", text: JSON.stringify(result ?? null) }];
+  }
+  return items.map((item) => {
+    if (item?.type === "text" && typeof item.text === "string") {
+      return { type: "text", text: item.text };
+    }
+    return { type: "text", text: JSON.stringify(item) };
+  });
+}
+
+export function createStdioMcpExtension(options) {
+  return async function registerStdioMcp(pi) {
+    if (!existsSync(options.serverScript)) {
+      throw new Error(`${options.label} MCP entrypoint is missing: ${options.serverScript}`);
+    }
+
+    const client = new Client(
+      { name: options.clientName, version: options.packageVersion },
+      { capabilities: {} },
+    );
+    const transport = new StdioClientTransport({
+      command: options.nodeCommand || "node",
+      args: [options.serverScript],
+      cwd: options.cwd,
+      env: stringEnvironment(options.env),
+      stderr: "pipe",
+    });
+
+    try {
+      await client.connect(transport);
+      const listed = await client.listTools();
+      for (const tool of listed.tools || []) {
+        if (!tool?.name || !tool?.inputSchema) continue;
+        pi.registerTool({
+          name: tool.name,
+          label: tool.title || tool.name,
+          description: tool.description || `${options.label} MCP tool ${tool.name}`,
+          parameters: tool.inputSchema,
+          async execute(_toolCallId, params, signal) {
+            const result = await client.callTool(
+              { name: tool.name, arguments: params || {} },
+              undefined,
+              { signal },
+            );
+            return {
+              content: toolContent(result),
+              details: {
+                mcpServer: options.serverName,
+                mcpTool: tool.name,
+                isError: result?.isError === true,
+              },
+            };
+          },
+        });
+      }
+    } catch (error) {
+      await client.close().catch(() => {});
+      throw new Error(`${options.label} MCP startup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    let closed = false;
+    pi.on("session_shutdown", async () => {
+      if (closed) return;
+      closed = true;
+      await client.close().catch(() => {});
+    });
+  };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pi-cursor-bridge",
+  "version": "0.1.0",
+  "description": "Use Cursor Context Engine and bounded Cursor Agent execution from the Pi coding agent.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Vanyangyang",
+  "homepage": "https://github.com/Vanyangyang/cursor-bridge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vanyangyang/cursor-bridge.git",
+    "directory": "pi-packages/pi-cursor-bridge"
+  },
+  "bugs": {
+    "url": "https://github.com/Vanyangyang/cursor-bridge/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "cursor",
+    "mcp",
+    "semantic-search",
+    "coding-agent"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills/cce-routing",
+      "./skills/cursor-delegate"
+    ]
+  },
+  "files": [
+    "extensions/",
+    "dist/",
+    "skills/",
+    ".codex-plugin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0"
+  },
+  "piPackage": {
+    "embeddedProduct": "Cursor Bridge",
+    "embeddedProductVersion": "5.4.2"
+  }
+}

package/skills/cce-routing/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: cce-routing
+description: "Use Cursor Bridge's read-only cursor_context_engine for unfamiliar project understanding when the exact code location is unknown or the task requires tracing behavior, symbols, callers and callees, data flow, registrations, interface implementations, ownership boundaries, or cross-module relationships. Trigger for questions such as where something is implemented, what owns state, how a project flow works, or when local search would otherwise guess paths or repeat blind queries; for these semantic questions, try CCE before generic context-mode or grep discovery. Do not use when a known exact file or symbol can answer the question through direct reading or exact search, for content already loaded in context, trivial single-file edits, tests, logs, builds, Git work, external documentation, or when the user opts out of Cursor. Verify returned path:line evidence in the real files."
+---
+
+# CCE Routing
+
+Route project-understanding questions to the cheapest evidence surface that can answer them without guessing.
+
+## Choose CCE for project semantics
+
+Call `cursor_context_engine` when one or more of these are true:
+
+- The implementation location is unknown and finding it locally would require guessing directories or repeating broad searches.
+- The question asks where or how a project behavior is implemented, what owns a state or responsibility, or why a flow behaves as it does.
+- The answer requires tracing callers and callees, producer-consumer flow, configuration and registration, interface implementations, data ownership, or relationships across modules.
+- An unfamiliar indexed project needs semantic context before a safe edit or review can begin.
+
+Prefer one CCE investigation over starting an Explore subagent merely to locate or understand project code. Let Cursor choose focused or extended depth from what it discovers.
+
+When these semantic conditions match, make CCE the first project-discovery surface. Do not establish the answer through generic context-mode, grep, or blind local exploration before trying CCE. If Claude Code denies an initial context-mode collection call with a CCE routing message, call `cursor_context_engine` once instead of retrying another `ctx_*` tool. A failed, denied, unavailable, or `NOT_FOUND` CCE attempt releases this priority and allows a bounded local fallback.
+
+## Keep deterministic work local
+
+Do not call CCE when any of these apply:
+
+- The exact file, symbol, or location is already known and a direct read or exact search is sufficient.
+- The needed code is already present in the current context.
+- The work is a trivial single-file edit or only requires running tests, inspecting logs, checking a build, or examining Git state.
+- The question concerns external libraries, APIs, current documentation, or the public web.
+- The user opted out of Cursor, CCE is unavailable, or the workspace is not initialized.
+
+Do not submit the same lookup to CCE and another semantic system in parallel. Use a second evidence surface only to close a specific gap or verify a consequential claim.
+
+## Submit one natural-language intent
+
+Call `cursor_context_engine` once with the question's real intent. Include a known symbol, subsystem, or path only when it is a useful lead.
+
+- Describe the relationship or behavior to establish and the evidence needed.
+- Do not prescribe Cursor's internal search sequence, harness, Explore usage, or number of files.
+- Do not invent hidden parameters; the public input is only `query`.
+- Allow a cold or large workspace enough time to complete its serialized Cursor UI turn.
+
+## Verify and continue
+
+Treat CCE output as evidence leads, not final authority.
+
+1. Read the returned workspace-relative `path:line` anchors in the real working tree before relying on them.
+2. Distinguish exact references and demonstrated flows from semantic similarity.
+3. If CCE returns `NOT_FOUND` or names gaps, report those gaps or perform one bounded fallback search; do not guess from framework convention.
+4. Keep edits, final review, tests, and acceptance with the primary agent unless a separate bounded delegation is appropriate.
+
+CCE is strongly prompted and audited for read-only investigation, but it is not a filesystem sandbox. Preserve user changes and normal workspace safety boundaries.

package/skills/cce-routing/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "CCE Routing"
+  short_description: "Route unfamiliar project questions to Cursor CCE"
+  default_prompt: "Use $cce-routing to locate and verify unfamiliar project behavior with Cursor CCE."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "cursor-bridge"
+      description: "Use Cursor CCE to find and verify project context"
+
+policy:
+  allow_implicit_invocation: true

package/skills/cursor-delegate/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: cursor-delegate
+description: "Delegate bounded light-to-medium implementation, limited investigation, documentation, configuration, testing, and tooling work to Cursor Bridge after the primary agent owns the direction and risk boundaries. Use when a bounded Cursor pass can save primary-agent time, reduce omissions, or run alongside non-conflicting work; the task needs a clear purpose, allowed scope, invariants, and checkable outcome, but not a fully pre-solved implementation. Collect work by task_id or agent_id and verify it in the primary agent. Do not use when the user opts out, cursor_do is unavailable or administrator-disabled, or for product direction, architecture decisions, exclusive GUI operations, formal verification verdicts, governance state decisions, or unbounded investigation."
+---
+
+# Cursor Delegate
+
+Use Cursor as an execution partner. Keep direction, scope decisions, risk ownership, result review, and final verification with the primary agent.
+
+## Respect execution controls
+
+- Do not call `cursor_do` when the user explicitly says not to use Cursor or not to delegate. A direct user opt-out always wins.
+- If `cursor_do` is unavailable, or `cursor_status` reports delegation as disabled, do not bypass the setting, repeatedly retry, or ask Cursor to re-enable itself. Complete the work in the primary agent.
+- Treat `CURSOR_BRIDGE_DELEGATION=off` as an administrator-level host switch. It disables delegated execution but does not by itself disable `cursor_context_engine`, `cursor_init`, or `cursor_status`.
+- Cursor Bridge exposes one fixed delegation contract. Do not invent participation levels, call-frequency controls, or slash commands.
+
+## Follow the default workflow
+
+Use this responsibility chain:
+
+`primary agent defines purpose, invariants, and risk boundaries -> form a bounded task envelope -> Cursor investigates locally and executes within the envelope -> collect by task_id -> primary agent inspects the real changes and verifies them`
+
+- Decide what should be achieved, why it matters, what must not change, where Cursor may work, and what evidence makes the result acceptable. Do not delegate product direction, architecture boundaries, or state verdicts.
+- Allow Cursor to locate relevant implementation, compare local approaches, and complete code, documentation, configuration, scripts, tests, and tooling inside those boundaries. Do not require the primary agent to pre-solve the task line by line.
+- Once a task has been selected for delegation, normally call `cursor_do` once with `background=true`, then continue non-conflicting primary-agent work. Bridge starts FIFO work in a clean chat automatically.
+- Prefer `execution=fifo` unless the parallel contract is clearly satisfied.
+- Do not inject a unique completion marker or impose a minimum response length. Rely on task state, stable `task_id` or `agent_id`, and the actual result.
+
+## Decide whether this task should go to Cursor
+
+Send a bounded part of the task to Cursor when one or more of these are true:
+
+- The task can be bounded to a path set or subsystem and checked through a diff, test, count, or documentation assertion.
+- The work includes repeated lookup, mechanical edits, test or documentation completion, adapter wiring, configuration cleanup, or an independent second pass.
+- The primary agent has higher-value design, cross-system judgment, or non-conflicting work to continue.
+- Delegation value is uncertain, but a small `read_only=true` implementation-location probe or single-path task can measure it without transferring an unresolved product decision.
+
+Keep the work in the primary agent when any of these are true:
+
+- The user said not to use Cursor or not to delegate.
+- It is a tiny direct edit whose dispatch and review would cost more than doing it locally.
+- Cursor would have to decide product direction, architecture, creative intent, or governance state.
+- The task requires exclusive GUI state or shared mutable runtime state.
+- A safe scope, path boundary, checkable result, or way to preserve existing user changes cannot be established.
+
+Before dispatch, make sure the purpose, invariants, allowed scope, and checkable outcome are reasonably clear. Cursor may resolve local implementation details inside that envelope; the primary agent does not need to prescribe every step.
+
+For an exact known-file or known-symbol lookup, establish the cheapest deterministic local baseline first. For unknown ownership, behavior, call chains, data flow, registrations, or cross-module relationships, follow `cce-routing` and try `cursor_context_engine` before generic local discovery. Do not submit the same exact lookup through multiple systems.
+
+## Choose the execution mode
+
+- Use `execution=fifo` for one ordinary task, dependent tasks, overlapping write scopes, shared mutable state, or any case where independence is uncertain. Submit the next dependent task only after accepting the previous result.
+- Use `execution=parallel_agent` only for at least two independent, separately verifiable tasks whose write paths do not overlap.
+- Set `read_only=true` for analysis-only work. Do not run read-only tasks in parallel against the same mutable external state.
+- Set `read_only=false` only with a non-empty set of workspace-relative `allowed_paths` that contains no globs and cannot escape the workspace. Keep the set as small as practical. It is a scheduling declaration and prompt constraint, not a filesystem sandbox.
+
+Do not choose parallel execution merely because there are many tasks. When dependency or path relationships are unclear, use `fifo`.
+
+## Dispatch a task
+
+1. Record the relevant pre-dispatch workspace state so later review can distinguish existing user changes.
+2. Form one independent task envelope per task using [delegation-contract.md](references/delegation-contract.md).
+3. Call `cursor_do` with `background=true`; do not invent a chat-selection parameter.
+4. Save each returned `task_id`; also save `agent_id` whenever `cursor_status` publishes one.
+5. If a parallel submission does not return a usable `agent_id`, stop expanding the parallel batch and use `fifo` or report the ambiguous state.
+
+The envelope may contain a small number of local implementation `open_questions`, but it must also provide `fixed_decisions`, `allowed_paths`, prohibitions, and acceptance checks. Cursor may solve local questions; it must stop and report any branch that would change product direction, architecture, or scope.
+
+## Collect and verify
+
+1. Always query `cursor_status(task_id)` for the exact task. Do not treat the currently visible Cursor chat as task identity.
+2. Treat `submitting`, `running`, and `collecting` as normal in-progress states. More than two minutes is not itself a failure; wait for an explicit terminal state.
+3. Compare Cursor's claimed work with the real diff, `allowed_paths`, and acceptance contract.
+4. Run risk-proportionate verification in the primary agent. Cursor's response alone cannot support a formal pass, verified state, or governance transition.
+5. Record each task as complete, partial, failed, timed out, or ambiguous before summarizing the batch.
+
+Read [delegation-contract.md](references/delegation-contract.md) for state interpretation and recovery details.
+
+## Handle abnormal states
+
+- For `needs_attention`, `orphaned`, ambiguous state, or an unbound session, assume the real Cursor Agent may still be running. Preserve path ownership and never resubmit automatically.
+- For a parallel orphan with a bound `agent_id`, first call `cursor_task_control(action=reap)`. This explicitly rechecks and, when possible, resumes monitoring or collects that exact Agent. `cursor_status` is read-only and does not reap automatically.
+- For an unbound FIFO or any orphan without an `agent_id`, do not call `reap` as if an identity existed. It globally blocks delegation; manually verify Cursor has stopped, then use the explicitly acknowledged `abandon` path.
+- To stop a bound task, use `cursor_task_control(action=cancel, confirm=true, expected_agent_id=<exact id>)`. This includes FIFO tasks that have published an Agent ID. If Stop cannot be confirmed, the reservation remains held.
+- Use `action=abandon` only after manual verification and an explicit user decision to accept the risk. It requires `confirm=true`, a non-empty reason, `acknowledge_may_still_write=true`, and the exact `expected_agent_id` when one is already bound; report that the underlying Agent may still run or write.
+- If Cursor shows a final UI response but Bridge has not collected it, use explicit `reap` against the original bound task. A `terminal_uncollected` result keeps the reservation for retry. Do not add a completion marker, increase a response-length requirement, or submit the same task again.
+- Task identity and reservations are process-local. After an MCP/Codex restart, do not claim the old `task_id` is recoverable; inspect Cursor Agent History and workspace changes manually before overlapping work.
+- If a timed-out task changed files, inspect the changes before deciding whether to continue, retry, or revert.
+- If changes exceed `allowed_paths`, stop accepting the result and report the scope violation.
+- If parallel tasks conflict, stop further integration and return to primary-agent review or serial execution.

package/skills/cursor-delegate/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "Cursor Delegation"
+  short_description: "Give Cursor a useful bounded task, then review what it did"
+  default_prompt: "Use $cursor-delegate to decide whether Cursor can take a useful, clearly bounded part of this work. If it can, give Cursor a clear task, collect the result, inspect the real changes, and keep final approval with the primary agent."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "cursor-bridge"
+      description: "Send work to Cursor, follow each task, and collect the result"
+
+policy:
+  allow_implicit_invocation: true

package/skills/cursor-delegate/references/delegation-contract.md

@@ -0,0 +1,107 @@
+# Cursor Delegation Contract
+
+Read this file only when constructing a task envelope, choosing an `execution` mode, or recovering from an abnormal state.
+
+## Delegation controls
+
+- When `CURSOR_BRIDGE_DELEGATION=off`, Bridge does not expose `cursor_do`, and direct invocation must fail. Initialization, search, and status tools remain available.
+- When the user opts out, `cursor_do` is unavailable, or `cursor_status.delegationMode=off`, complete the task in the primary agent. Do not ask the user to re-enable delegation or bypass the setting through another call.
+- Re-enable the environment-level kill switch by starting a new MCP server process with `CURSOR_BRIDGE_DELEGATION=on` or with the variable unset. A running process does not dynamically change this environment setting.
+- There is one fixed public delegation contract. No participation levels or call-frequency settings exist. `CURSOR_BRIDGE_DELEGATION=off` is an administrator-level compatibility switch and never relaxes the task-envelope, path, independence, or verification contracts below.
+
+## Task envelope
+
+Provide every task independently:
+
+| Field | Requirement |
+|---|---|
+| `prompt` | State one objective, the necessary context, prohibited actions, and the expected report. Do not ask Cursor to repeat the primary agent's scope decision. |
+| `execution` | Use only `fifo` or `parallel_agent`. Use `fifo` when safe parallelism cannot be demonstrated. |
+| `read_only` | Use `true` for lookup and analysis; use `false` for any file modification. |
+| `allowed_paths` | Required when `read_only=false`. Provide the smallest workspace-relative path set, with no glob, absolute path, or workspace-escaping `..`. Omit it when `read_only=true`. This is not a filesystem sandbox. |
+| `completion_contract` | State the deliverables, validation commands, permitted incomplete items, and final report format. |
+| `background` | Default to `true` so the primary agent may continue independent work. |
+
+## Routing contract
+
+Choose `parallel_agent` only when all conditions hold:
+
+1. Tasks have no data, ordering, or decision dependency.
+2. Normalized `allowed_paths` for write tasks are pairwise non-overlapping.
+3. Tasks do not share Unity, browser, database, or other mutable runtime state.
+4. Each result can be accepted independently; one failure does not invalidate the other results.
+
+Use `fifo` when any condition fails. For ordered work, do not pre-submit the full queue. Collect and accept the predecessor before deciding whether to submit its dependent task.
+
+## Call examples
+
+Parallel read-only task:
+
+```json
+{
+  "prompt": "Read the specified files and return conclusions without modifying any file.",
+  "execution": "parallel_agent",
+  "read_only": true,
+  "background": true,
+  "completion_contract": "Return conclusions, evidence files, and unresolved questions."
+}
+```
+
+Bounded write task:
+
+```json
+{
+  "prompt": "Implement the specified tool script under the fixed design without expanding scope.",
+  "execution": "parallel_agent",
+  "read_only": false,
+  "background": true,
+  "allowed_paths": ["Tools/Example/"],
+  "completion_contract": "List changed files and run the specified static check; preserve the original error when validation fails."
+}
+```
+
+For dependent or path-overlapping work, change `execution` to `fifo` and submit the next task only after accepting its predecessor.
+
+## Identity and collection contract
+
+- `task_id` is the stable identity used by the primary agent to query and summarize a task. Save it immediately after dispatch.
+- `agent_id` binds a task to one specific Agents Window session when Bridge publishes it. `parallel_agent` always needs this identity. FIFO may also publish one; if it does not, do not assume a safe Stop target.
+- Determine task state only through `cursor_status(task_id)`, not the currently selected chat or latest visible response.
+- A collected result should include at least task state, summary, changed files, validation performed, failures or blockers, and the raw Cursor response.
+- Do not require a unique completion marker or minimum response length. Bridge determines completion from Agent state, stopped generation, and response stability.
+
+### State table
+
+| State or phase | Primary-agent action |
+|---|---|
+| `queued/submitting/running/collecting` | Keep the original task and continue polling by `task_id`. More than two minutes is not a failure. |
+| `completed` | Read the raw response, then inspect the real diff, allowed paths, and completion contract. |
+| `failed` | Read the explicit error and determine whether the Cursor Agent actually failed before deciding to rework. |
+| `needs_attention/orphaned` with bound `agent_id` | Preserve path ownership and explicitly call `cursor_task_control(action=reap)` for the same in-memory task. Do not resubmit automatically. |
+| FIFO or unbound orphan | A global reservation blocks all new delegation. If an `agent_id` was published, use targeted `cancel`. Otherwise manually verify Cursor has stopped, then use explicitly acknowledged `abandon`; there is no safe `reap` target. |
+| `terminal_uncollected` | Agent History is stably terminal but the final response extraction failed. Keep the reservation and retry explicit `reap`; do not release on one DOM failure. |
+| `cancelled` | The exact Agent Stop action or an unsent queued cancellation was confirmed; the reservation is released. |
+| `abandoned` | The reservation was explicitly released without proof that the underlying Agent stopped. Treat the warning as live risk and inspect workspace changes before any overlapping write. |
+
+For an R6-style false negative, continue querying the original `task_id` when Agent History already contains a complete final response but automatic collection has not finished. Bridge should retry extraction against the original `agent_id`. Do not work around collection by requiring a longer reply, injecting a completion marker, or submitting the same task again.
+
+## Primary-agent acceptance contract
+
+Cursor's completion statement means only that delegated execution ended; it is not project verification. The primary agent must:
+
+1. Inspect the actual diff against `allowed_paths`.
+2. Separate delegated changes from pre-existing workspace changes.
+3. Independently run appropriate compile checks, static checks, tests, or journey validation.
+4. Decide whether to accept, request rework, continue serially, or record a blocker.
+5. Retain formal verification, governance state, and product decision authority.
+
+## Failure and fallback
+
+- If `agent_id` is missing and the task has not been sent, stop expanding the parallel batch and safely fall back to `fifo`. If it may have been sent or is `needs_attention/orphaned`, continue treating its paths as occupied and inspect the Agents Window instead of resubmitting.
+- If a timed-out task changed the workspace, inspect the changes before submitting the same task again.
+- Reject and report any result that modifies files outside `allowed_paths`.
+- Stop automatic integration when parallel tasks conflict and return the batch to primary-agent review.
+- If Agent History or the response DOM is temporarily unreadable, let Bridge wait and retry against the same `agent_id`. Enter `needs_attention` after persistent failure; do not incorrectly mark the task complete or create a duplicate Agent.
+- For a bound orphan, use `reap` before `cancel`. `cancel` requires the exact `expected_agent_id` and only releases after stable Stop evidence. `abandon` requires explicit confirmation, a reason, acknowledgement that the Agent may still write, and the exact `expected_agent_id` when one is bound.
+- `cursor_status` is a pure snapshot. Reconciliation happens only through explicit `cursor_task_control`.
+- Task records and reservations live only for the current Bridge MCP process. After restart, inspect Cursor Agent History and the workspace manually; persistent cross-process task leases are outside the current contract.