Add cursor sandbox support and fix SSH workspace sync (#4803)

## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Agents can run inside sandboxed environments like E2B, or on remote hosts via SSH > - The cursor adapter needs to resolve `cursor-agent` inside sandbox environments where it's installed in `~/.local/bin` > - But when using the default `agent` command on a sandbox target, the adapter didn't know to look in `~/.local/bin/cursor-agent`, causing "command not found" failures > - Additionally, repeated SSH runs failed because `git checkout` during workspace sync conflicted with leftover `.paperclip-runtime` files from previous runs > - This PR adds sandbox-aware command resolution for cursor and fixes the SSH workspace sync conflict > - The benefit is cursor works in E2B sandboxes out of the box, and repeated SSH runs don't fail on workspace sync ## What Changed - `cursor-local`: Added `prepareCursorSandboxCommand` — on sandbox targets, reads the remote `$HOME`, prepends `~/.local/bin` to PATH, and prefers `~/.local/bin/cursor-agent` when the default command is requested; tightened the sandbox command probe to validate the binary exists before launching; preserves explicit custom command overrides - `adapter-utils/ssh.ts`: Added `--force` to git checkout in SSH workspace sync to handle `.paperclip-runtime` untracked file conflicts from previous runs ## Verification - `pnpm test` — all existing and new tests pass, including cursor sandbox probe, sandbox execution, and custom command override tests - `pnpm typecheck` — clean - Manual: configure an E2B environment, run a cursor-local task, verify it resolves cursor-agent from the sandbox install path ## Risks - Low-medium. The `--force` flag on git checkout could discard uncommitted changes in the remote workspace, but the workspace is managed by Paperclip and should not contain user edits. ## Model Used Codex GPT 5.4 high via Paperclip. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge
2026-04-29 16:12:06 -07:00
parent a0f5cbffd7
commit f9cf1d2f6a
12 changed files with 507 additions and 23 deletions
@@ -0,0 +1,160 @@
+import path from "node:path";
+import {
+  runAdapterExecutionTargetShellCommand,
+  type AdapterExecutionTarget,
+} from "@paperclipai/adapter-utils/execution-target";
+import { ensurePathInEnv } from "@paperclipai/adapter-utils/server-utils";
+
+const DEFAULT_CURSOR_COMMAND_BASENAMES = new Set(["agent", "cursor-agent"]);
+
+function commandBasename(command: string): string {
+  return command.trim().split(/[\\/]/).pop()?.toLowerCase() ?? "";
+}
+
+function hasPathSeparator(command: string): boolean {
+  return command.includes("/") || command.includes("\\");
+}
+
+function prependPosixPathEntry(pathValue: string, entry: string): string {
+  const parts = pathValue.split(":").filter(Boolean);
+  if (parts.includes(entry)) return pathValue;
+  const cleaned = parts.join(":");
+  return cleaned.length > 0 ? `${entry}:${cleaned}` : entry;
+}
+
+type SandboxCursorRuntimeInfo = {
+  remoteSystemHomeDir: string | null;
+  preferredCommandPath: string | null;
+};
+
+function readMarkedValue(lines: string[], marker: string): string | null {
+  const matchedLine = lines.find((line) => line.startsWith(marker));
+  if (!matchedLine) return null;
+  const value = matchedLine.slice(marker.length).trim();
+  return value.length > 0 ? value : null;
+}
+
+async function readSandboxCursorRuntimeInfo(input: {
+  runId: string;
+  target: AdapterExecutionTarget;
+  command: string;
+  cwd: string;
+  env: Record<string, string>;
+  timeoutSec: number;
+  graceSec: number;
+}): Promise<SandboxCursorRuntimeInfo> {
+  const shouldCheckPreferredCommand = isDefaultCursorCommand(input.command) && !hasPathSeparator(input.command);
+  const homeMarker = "__PAPERCLIP_CURSOR_HOME__:";
+  const preferredMarker = "__PAPERCLIP_CURSOR_AGENT__:";
+  try {
+    const result = await runAdapterExecutionTargetShellCommand(
+      input.runId,
+      input.target,
+      [
+        `printf ${JSON.stringify(`${homeMarker}%s\\n`)} "$HOME"`,
+        shouldCheckPreferredCommand
+          ? `if [ -x "$HOME/.local/bin/cursor-agent" ]; then printf ${JSON.stringify(`${preferredMarker}%s\\n`)} "$HOME/.local/bin/cursor-agent"; fi`
+          : "",
+      ].filter(Boolean).join("; "),
+      {
+        cwd: input.cwd,
+        env: input.env,
+        timeoutSec: input.timeoutSec,
+        graceSec: input.graceSec,
+      },
+    );
+    if (result.timedOut || (result.exitCode ?? 1) !== 0) {
+      return {
+        remoteSystemHomeDir: null,
+        preferredCommandPath: null,
+      };
+    }
+    const lines = result.stdout.split(/\r?\n/);
+    return {
+      remoteSystemHomeDir: readMarkedValue(lines, homeMarker),
+      preferredCommandPath: readMarkedValue(lines, preferredMarker),
+    };
+  } catch {
+    return {
+      remoteSystemHomeDir: null,
+      preferredCommandPath: null,
+    };
+  }
+}
+
+export function isDefaultCursorCommand(command: string): boolean {
+  return DEFAULT_CURSOR_COMMAND_BASENAMES.has(commandBasename(command));
+}
+
+export type PreparedCursorSandboxCommand = {
+  command: string;
+  env: Record<string, string>;
+  remoteSystemHomeDir: string | null;
+  addedPathEntry: string | null;
+  preferredCommandPath: string | null;
+};
+
+export async function prepareCursorSandboxCommand(input: {
+  runId: string;
+  target: AdapterExecutionTarget | null | undefined;
+  command: string;
+  cwd: string;
+  env: Record<string, string>;
+  timeoutSec: number;
+  graceSec: number;
+}): Promise<PreparedCursorSandboxCommand> {
+  if (input.target?.kind !== "remote" || input.target.transport !== "sandbox") {
+    return {
+      command: input.command,
+      env: input.env,
+      remoteSystemHomeDir: null,
+      addedPathEntry: null,
+      preferredCommandPath: null,
+    };
+  }
+
+  const runtimeInfo = await readSandboxCursorRuntimeInfo({
+    runId: input.runId,
+    target: input.target,
+    command: input.command,
+    cwd: input.cwd,
+    env: input.env,
+    timeoutSec: input.timeoutSec,
+    graceSec: input.graceSec,
+  });
+  const remoteSystemHomeDir = runtimeInfo.remoteSystemHomeDir;
+
+  if (!remoteSystemHomeDir) {
+    return {
+      command: input.command,
+      env: input.env,
+      remoteSystemHomeDir: null,
+      addedPathEntry: null,
+      preferredCommandPath: null,
+    };
+  }
+
+  const remoteLocalBinDir = path.posix.join(remoteSystemHomeDir, ".local", "bin");
+  const runtimeEnv = ensurePathInEnv(input.env);
+  const currentPath = runtimeEnv.PATH ?? runtimeEnv.Path ?? "";
+  const nextPath = prependPosixPathEntry(currentPath, remoteLocalBinDir);
+  const env = nextPath === currentPath ? input.env : { ...input.env, PATH: nextPath };
+
+  if (!runtimeInfo.preferredCommandPath) {
+    return {
+      command: input.command,
+      env,
+      remoteSystemHomeDir,
+      addedPathEntry: nextPath === currentPath ? null : remoteLocalBinDir,
+      preferredCommandPath: null,
+    };
+  }
+
+  return {
+    command: runtimeInfo.preferredCommandPath,
+    env,
+    remoteSystemHomeDir,
+    addedPathEntry: nextPath === currentPath ? null : remoteLocalBinDir,
+    preferredCommandPath: runtimeInfo.preferredCommandPath,
+  };
+}