pi-cursor-bridge 0.1.17 → 0.2.1

package/dist/cursor-lifecycle-supervisor.mjs

@@ -81,7 +81,7 @@ function powershellWindowScript(options) {
     `  Remove-Item -LiteralPath '${showFlagPath}' -Force -ErrorAction SilentlyContinue`,
     "}"
   ].join("\n");
-  const apply = lifetime ? lifetimeLoop : loop ? `for ($i = 0; $i -lt ${iterations}; $i++) { ${hideIfAllowed}; Start-Sleep -Milliseconds ${intervalMs} }` : `$changed = [CursorBridgeWindowControl]::Apply(${targetPid}, ${show}); [Console]::Out.Write($changed)`;
+  const apply = lifetime ? lifetimeLoop : loop ? `for ($i = 0; $i -lt ${iterations}; $i++) { ${hideIfAllowed}; Start-Sleep -Milliseconds ${intervalMs} }` : `$changed = [CursorBridgeWindowControl]::Apply(${targetPid}, ${show}${options.scope === "agents" ? ", $true" : ""}); [Console]::Out.Write($changed)`;
   return `$ErrorActionPreference = 'Stop'
 Add-Type -TypeDefinition @'
 ${WINDOW_CONTROL_TYPE}
@@ -95,6 +95,8 @@ function setCursorWindowPresentation(options = {}) {
   const platform = options.platform || process.platform;
   const action = String(options.action || "").trim().toLowerCase();
   if (!["hide", "show"].includes(action)) throw new Error(`unsupported Cursor window action: ${options.action}`);
+  const scope = options.scope ?? "process";
+  if (!["process", "agents"].includes(scope)) throw new Error(`unsupported Cursor window scope: ${scope}`);
   if (platform !== "win32") {
     return { supported: false, applied: false, action, reason: `window control is not implemented for ${platform}` };
   }
@@ -105,12 +107,14 @@ function setCursorWindowPresentation(options = {}) {
   }
   const showFlagPath = resolve(options.showFlagPath || join2(dirname(resolveCursorRuntimeFile()), `show-${pid}.flag`));
   try {
-    if (action === "show") {
-      mkdirSync2(dirname(showFlagPath), { recursive: true });
-      writeFileSync(showFlagPath, `${pid}
+    if (scope === "process") {
+      if (action === "show") {
+        mkdirSync2(dirname(showFlagPath), { recursive: true });
+        writeFileSync(showFlagPath, `${pid}
 `, { encoding: "utf8", mode: 384 });
-    } else {
-      rmSync(showFlagPath, { force: true });
+      } else {
+        rmSync(showFlagPath, { force: true });
+      }
     }
   } catch (error) {
     return {
@@ -124,7 +128,7 @@ function setCursorWindowPresentation(options = {}) {
   }
   const run = options.execFileSyncImpl || execFileSync;
   try {
-    const script = powershellWindowScript({ pid, action });
+    const script = powershellWindowScript({ pid, action, scope });
     const output = run("powershell.exe", [
       "-NoLogo",
       "-NoProfile",
@@ -140,9 +144,18 @@ function setCursorWindowPresentation(options = {}) {
       timeout: Number(options.timeoutMs || 15e3)
     });
     const changedWindows = Number(String(output || "").trim() || 0);
-    return { supported: true, applied: true, action, port, pid, changedWindows, showFlagPath };
+    return {
+      supported: true,
+      applied: scope !== "agents" || changedWindows > 0,
+      action,
+      scope,
+      port,
+      pid,
+      changedWindows,
+      ...scope === "process" ? { showFlagPath } : {}
+    };
   } catch (error) {
-    if (action === "show") rmSync(showFlagPath, { force: true });
+    if (action === "show" && scope === "process") rmSync(showFlagPath, { force: true });
     return {
       supported: true,
       applied: false,
@@ -206,6 +219,7 @@ var init_cursor_runtime = __esm({
 using System;
 using System.Runtime.InteropServices;
 using System.Text;
+using System.Collections.Generic;
 
 public static class CursorBridgeWindowControl {
   [StructLayout(LayoutKind.Sequential)]
@@ -225,6 +239,7 @@ public static class CursorBridgeWindowControl {
   [DllImport("user32.dll", EntryPoint = "IsWindowArranged")] private static extern bool IsWindowArranged(IntPtr hWnd);
   [DllImport("user32.dll")] private static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
   [DllImport("user32.dll", CharSet = CharSet.Unicode)] private static extern int GetWindowTextLengthW(IntPtr hWnd);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] private static extern int GetWindowTextW(IntPtr hWnd, StringBuilder text, int maxCount);
   [DllImport("user32.dll", CharSet = CharSet.Unicode)] private static extern int GetClassNameW(IntPtr hWnd, StringBuilder className, int maxCount);
   [DllImport("user32.dll")] private static extern bool ShowWindowAsync(IntPtr hWnd, int command);
   [DllImport("user32.dll")] private static extern bool SetWindowPos(IntPtr hWnd, IntPtr insertAfter, int x, int y, int width, int height, uint flags);
@@ -248,7 +263,12 @@ public static class CursorBridgeWindowControl {
   }
 
   public static int Apply(int expectedProcessId, bool show) {
+    return Apply(expectedProcessId, show, false);
+  }
+
+  public static int Apply(int expectedProcessId, bool show, bool agentsOnly) {
     int changed = 0;
+    List<IntPtr> windows = new List<IntPtr>();
     EnumWindows((hWnd, lParam) => {
       uint processId;
       GetWindowThreadProcessId(hWnd, out processId);
@@ -256,6 +276,17 @@ public static class CursorBridgeWindowControl {
       StringBuilder className = new StringBuilder(256);
       GetClassNameW(hWnd, className, className.Capacity);
       if (!String.Equals(className.ToString(), "Chrome_WidgetWin_1", StringComparison.Ordinal)) return true;
+      if (agentsOnly) {
+        StringBuilder title = new StringBuilder(GetWindowTextLengthW(hWnd) + 1);
+        GetWindowTextW(hWnd, title, title.Capacity);
+        if (!String.Equals(title.ToString(), "Cursor Agents", StringComparison.Ordinal)) return true;
+      }
+      windows.Add(hWnd);
+      return true;
+    }, IntPtr.Zero);
+    // Automatic recovery must never broaden an absent or ambiguous Agents match.
+    if (agentsOnly && windows.Count != 1) return 0;
+    foreach (IntPtr hWnd in windows) {
       bool visible = IsWindowVisible(hWnd);
       if (show) {
         // SWP_SHOWWINDOW + SWP_NOACTIVATE preserves minimized/maximized/arranged
@@ -283,8 +314,7 @@ public static class CursorBridgeWindowControl {
         if (restored || pulsed || redrawn) changed++;
       }
       if (!show && visible) { if (ShowWindowAsync(hWnd, 0)) changed++; }
-      return true;
-    }, IntPtr.Zero);
+    }
     return changed;
   }
 }

package/extensions/index.ts

@@ -10,7 +10,7 @@ const hostWorkspaceId = hostCwd.replace(/\\/g, "/").toLowerCase();
 export default createStdioMcpExtension({
   label: "Cursor Bridge",
   clientName: "pi-cursor-bridge",
-  packageVersion: "0.1.17",
+  packageVersion: "0.2.1",
   serverName: "cursor-bridge",
   serverScript: join(packageRoot, "dist", "cursor-bridge.mjs"),
   cwd: hostCwd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cursor-bridge",
-  "version": "0.1.17",
+  "version": "0.2.1",
   "description": "Use Cursor Context Engine and bounded, explicitly continuous Cursor Agent execution from the Pi coding agent.",
   "type": "module",
   "license": "MIT",
@@ -47,6 +47,6 @@
   },
   "piPackage": {
     "embeddedProduct": "Cursor Bridge",
-    "embeddedProductVersion": "5.10.1"
+    "embeddedProductVersion": "6.0.1"
   }
 }

package/skills/cursor-delegate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cursor-delegate
-description: "Delegate bounded light-to-medium implementation, investigation, documentation, configuration, testing, and tooling work to Cursor Bridge after the primary agent owns direction and risk boundaries. Also use when the user explicitly asks to create, keep, continue, inspect, or close the same Cursor execution session, including phrases such as '持续会话', '同一个 Cursor 会话', or 'continue the Cursor session'. Generic '继续' is not enough to reuse a session. Collect each turn by task_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."
+description: "Delegate bounded light-to-medium implementation, investigation, documentation, configuration, testing, and tooling work to Cursor Bridge after the primary agent owns direction and risk boundaries. Also use when the user explicitly asks to create, keep, continue, inspect, or close the same Cursor execution session, including phrases such as '持续会话', '同一个 Cursor 会话', or 'continue the Cursor session'. Generic '继续' is not enough to reuse a session. Poll each turn compactly by task_id, then retrieve its normal terminal reply with detail=result 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
@@ -21,11 +21,11 @@ Declare `request_context` for each call: an AI caller uses `sender="model"`; set
 
 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`
+`primary agent defines purpose, invariants, and risk boundaries -> form a bounded task envelope -> Cursor investigates locally and executes within the envelope -> poll compactly and retrieve the normal terminal reply with detail=result -> 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.
+- Once a task has been selected for delegation, normally call `cursor_do` once with `background=true`, receive its compact submission receipt, 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.
 
@@ -75,7 +75,7 @@ Do not choose parallel execution merely because there are many tasks. When depen
 
 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). Write its narrative instructions in the language of the user's current substantive task unless the user explicitly requests another language. Do not persist an inferred language or replace a clear conversational signal with the host/OS locale.
-3. Call `cursor_do` with `background=true`. Use only the documented `session_mode` and `session_id` fields when continuity is explicit; never infer continuity from the visible chat.
+3. Call `cursor_do` with `background=true` and save its compact submission receipt. Use `background=false` only when an immediate synchronous full result is required. Use only the documented `session_mode` and `session_id` fields when continuity is explicit; never infer continuity from the visible chat.
 4. Save each returned `task_id`; for persistent work also save `session_id`. Treat `agent_id` as verification evidence, not the continuation handle.
 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.
 
@@ -83,12 +83,13 @@ The envelope may contain a small number of local implementation `open_questions`
 
 ## 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.
+1. Always query `cursor_status(task_id)` for the exact task. Its default compact view is for normal polling; use `detail="full"` during progress only when detailed diagnostics are needed. 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. When `cursor_status` reports a configured model default, confirm `modelSelection.applied=true` and preserve its configured/effective model and effort fields in any failure report.
-5. Run risk-proportionate verification in the primary agent. Cursor's response alone cannot support a formal pass, verified state, or governance transition.
-6. Record each task as complete, partial, failed, timed out, or ambiguous before summarizing the batch.
+3. After a terminal state, call `cursor_status(task_id, detail="result")`. It returns the raw complete retained reply without a JSON wrapper and records explicit receipt; check `isError` before treating content as a reply. Repeat result reads remain allowed while the task is retained. Use `detail="full"` when the diagnostic task detail is needed.
+4. Compare Cursor's claimed work with the real diff, `allowed_paths`, and acceptance contract.
+5. When `cursor_status` reports a configured model default, confirm `modelSelection.applied=true` and preserve its configured/effective model and effort fields in any failure report.
+6. Run risk-proportionate verification in the primary agent. Cursor's response alone cannot support a formal pass, verified state, or governance transition.
+7. Record each task as complete, partial, failed, timed out, or ambiguous before summarizing the batch.
 
 Report the accepted result in the language of the user's current task. Keep `task_id`, `agent_id`, tool names, states, enum values, paths, commands, hashes, exact permission options, and error/status codes verbatim. If Cursor returned an artifact or report in another language, preserve it and summarize the relevant facts in the current task language.
 
@@ -97,14 +98,14 @@ Read [delegation-contract.md](references/delegation-contract.md) for state inter
 ## 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 a parallel orphan with a bound `agent_id`, first call `cursor_task_control(action=reap)`. This explicitly rechecks and, when possible, resumes monitoring or recovers that task's terminal state. It returns only an action/state summary; after a terminal state, retrieve the normal reply with `cursor_status(task_id, detail="result")` or use `detail="full"` for diagnostics.
 - 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.
+- 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; after recovery reaches a terminal state, retrieve the result through explicit full task status. 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.
 - A ready persistent `session_id` is stored outside the versioned plugin cache and may survive MCP/Codex restart or plugin update. Query `cursor_status(session_id)` before continuing. If it reports `needs_attention`, an expired sender lease, or a missing exact Agent binding, do not resubmit or silently create a replacement session.
-- Use `cursor_session_control(action=reconcile)` to check the exact Agent twice after an interrupted adapter. It may return the session to `ready` only from stable terminal evidence; an interrupted completed reply remains explicitly uncollected.
+- Use `cursor_session_control(action=reconcile)` to check the exact Agent twice after an interrupted adapter. It may return the session to `ready` only from stable terminal evidence; an interrupted completed reply remains explicitly uncollected and `cursor_session_control(action=collect_result)` returns that session reply in full.
 - `cursor_session_control(action=abandon)` is the last resort for an uncertain session and requires `confirm=true`, a non-empty reason, and `acknowledge_may_still_write=true`. It closes only the Bridge mapping and does not prove that Cursor stopped.
 - 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.

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

@@ -21,7 +21,7 @@ Provide every task independently:
 | `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, final report format, and that narrative output should follow the task language. Preserve paths, commands, identifiers, and machine tokens verbatim. |
-| `background` | Default to `true` so the primary agent may continue independent work. |
+| `background` | Default to `true` so the primary agent may continue independent work; it returns a compact submission receipt. Set `false` only to wait synchronously for the full result body. |
 
 ## Routing contract
 
@@ -65,12 +65,20 @@ Bounded write task:
 
 For dependent or path-overlapping work, change `execution` to `fifo` and submit the next task only after accepting its predecessor.
 
+Compact collection flow:
+
+1. After `cursor_do(background=true)`, save the compact receipt's `task_id`.
+2. Poll `cursor_status(task_id)` with its default compact view while the task is active.
+3. Once terminal, call `cursor_status(task_id, detail="result")` to retrieve the raw retained reply and record receipt. It has no JSON wrapper, so check `isError` before treating content as a reply. Use `detail="full"` when task diagnostics are needed; repeat either explicit read is allowed while the task record remains retained.
+
 ## 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.
+- Determine task state only through `cursor_status(task_id)`, not the currently selected chat or latest visible response. Its default compact view never returns a result body or records receipt.
+- After a terminal state, use `cursor_status(task_id, detail="result")` to retrieve the plain complete retained reply and record explicit receipt. Use `detail="full"` when task diagnostics are needed. A collected result should include at least task state, summary, changed files, validation performed, failures or blockers, and the raw Cursor response.
+- `cursor_task_control` returns an action and compact task-state summary without a result body or implicit receipt. Retrieve a terminal reply afterward with `detail="result"`, or use `detail="full"` for diagnostics.
+- `cursor_session_control(action=collect_result)` always returns the full session reply.
 - Do not require a unique completion marker or minimum response length. Bridge determines completion from Agent state, stopped generation, and response stability.
 
 ### State table
@@ -78,15 +86,15 @@ For dependent or path-overlapping work, change `execution` to `fifo` and submit
 | 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. |
+| `completed` | Call `cursor_status(task_id, detail="result")` to read the raw response, then inspect the real diff, allowed paths, and completion contract. Use `detail="full"` when diagnostics are needed. |
 | `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. |
+| `terminal_uncollected` | Agent History is stably terminal but the final response extraction failed. Keep the reservation and retry explicit `reap`; after recovery, use `detail="result"` to retrieve the reply or `detail="full"` for diagnostics. 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.
+For an R6-style false negative, continue compact polling of 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`; once terminal, use `detail="result"` or `detail="full"` for diagnostics. Do not work around collection by requiring a longer reply, injecting a completion marker, or submitting the same task again.
 
 ## Primary-agent acceptance contract
 
@@ -106,5 +114,5 @@ Cursor's completion statement means only that delegated execution ended; it is n
 - 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`.
+- Default compact `cursor_status` is a pure snapshot. `cursor_status(task_id, detail="result")` is the normal explicit result-receipt operation; `detail="full"` also records receipt and retains diagnostic detail. Reconciliation still 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.