paperclip/packages/adapter-utils/src
Devin Foley f9cf1d2f6a
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
..
billing.test.ts feat(costs): add billing, quota, and budget control plane 2026-03-16 15:11:01 -05:00
billing.ts feat(costs): add billing, quota, and budget control plane 2026-03-16 15:11:01 -05:00
command-managed-runtime.ts Add sandbox environment support (#4415) 2026-04-24 12:15:53 -07:00
execution-target-sandbox.test.ts Add sandbox environment support (#4415) 2026-04-24 12:15:53 -07:00
execution-target.test.ts Add dedicated environment settings page and test-in-environment (#4798) 2026-04-29 15:56:13 -07:00
execution-target.ts Add dedicated environment settings page and test-in-environment (#4798) 2026-04-29 15:56:13 -07:00
index.ts feat(adapters): declarative config-schema API and UI for plugin adapters 2026-04-03 21:11:22 +01:00
log-redaction.ts fix(ui): external adapter selection, config field placement, and transcript parser freshness 2026-04-03 21:11:22 +01:00
remote-managed-runtime.ts Add SSH environment support (#4358) 2026-04-23 19:15:22 -07:00
sandbox-managed-runtime.test.ts Add sandbox environment support (#4415) 2026-04-24 12:15:53 -07:00
sandbox-managed-runtime.ts Add sandbox environment support (#4415) 2026-04-24 12:15:53 -07:00
server-utils.test.ts Fix CEO AGENT_HOME paths and centralize workspace env propagation (#4551) 2026-04-26 13:57:35 -07:00
server-utils.ts Fix CEO AGENT_HOME paths and centralize workspace env propagation (#4551) 2026-04-26 13:57:35 -07:00
session-compaction.ts feat: add hermes_local session management and show provider/model in run details 2026-04-03 21:11:23 +01:00
ssh-fixture.test.ts Add SSH environment support (#4358) 2026-04-23 19:15:22 -07:00
ssh.ts Add cursor sandbox support and fix SSH workspace sync (#4803) 2026-04-29 16:12:06 -07:00
types.ts Add dedicated environment settings page and test-in-environment (#4798) 2026-04-29 15:56:13 -07:00