Files
PaperClipAI/packages/adapter-utils
Devin FoleyandPaperclip 84b75502c0 fix(ssh): support ACP with durable Cloud workspaces (#22063)
## Thinking Path

> - Paperclip coordinates agents that run on local and remote computers.
> - SSH environments use the harness installed on a computer the
operator controls.
> - Cloud SSH tasks now use durable remote workspaces.
> - Claude and Codex default to ACP, but ACP rejects those in-place SSH
workspaces.
> - The shared ACP engine already has SSH process bridges and managed
account delivery.
> - This pull request lets that engine use the remote task directory and
stage runtime assets separately.
> - The benefit is ACP execution with the selected Paperclip account and
the existing SSH environment.

## Linked Issues or Issue Description

**What happened?**

A Claude or Codex agent using the default ACP engine cannot run in a
volume-free Cloud SSH environment. The adapter rejects its in-place
workspace before execution. Setting the engine to CLI works around that
restriction.

**Expected behavior**

ACP runs directly in the authoritative remote task directory. Paperclip
keeps using the selected account, permission settings, process bridges,
and durable workspace owner.

**Steps to reproduce**

1. Create an SSH environment with agent-managed authentication on a
volume-free server.
2. Select a Paperclip AI account for a Claude or Codex agent and leave
its engine at the default.
3. Assign a task to the agent.
4. Observe the ACP in-place workspace rejection.

Related: #21957 adds durable Cloud SSH workspaces. #21248 adds
agent-selected SSH accounts. A search for SSH ACP work found #21248 and
no open duplicate. ROADMAP.md has no overlapping item.

## What Changed

- Admit managed SSH ACP with an in-place workspace in both adapters.
- Keep ACP's session directory and fingerprint bound to the remote task
directory.
- Stage private runtime assets with workspace copying disabled. The
remote workspace owner still saves task files.
- Retain the copy-mode SSH path and existing account, confinement, and
command availability checks. No engine fallback or permission change is
added.
- Extend the existing lifecycle tests for in-place staging, session
reuse, current credentials, account changes, and cleanup after bridge or
turn failures.
- Extend the real OpenSSH/Postgres heartbeat test to the default ACP
engine. Its protocol fixture creates a file and verifies conversation
history on a follow-up.
- Update the SSH setup documentation.

Workspace placement belongs to the shared ACP engine. The adapter
changes remove their explicit SSH admission refusals. The server test
exercises the existing heartbeat path; no server execution logic
changes. Existing large test files retain their shared harnesses instead
of adding a second lifecycle mock graph.

## Verification

- 418 focused tests pass across 7 suites: 411 adapter/ACP lifecycle
tests, all 4 real SSH workspace tests, and 3 real ACP host-spawn smoke
tests.
- Typechecks pass for adapter-utils, Claude, Codex, and the server.
- `pnpm verify` returns 2 because this touches shared runtime code and
deployment documentation. Required CI supplies the broader build,
browser, and release coverage.
- Tested head: `33b17a9a21c0a5929523702ebed9c8faa3b22955`.
- `git diff --check` and the local secret/PII scan pass. Greptile
reviewed the tested head at 5/5 with no actionable findings. Final-head
[CI attempt
2](https://github.com/paperclipai/paperclip/actions/runs/44167483231/attempts/2)
passes on `33b17a9a21c0a5929523702ebed9c8faa3b22955`: 58 checks pass and
6 are skipped, with no failures or pending checks. Both required gates
pass. Four first-attempt jobs were cancelled after their runners
received shutdown signals, confirmed in each job log; automatic recovery
reran those jobs successfully. No source change was needed for that
recovery. Greptile is 5/5 with no unresolved findings, and the branch
has no merge conflicts. GitHub still requires code-owner review before
merge.

```sh
pnpm exec vitest run --maxWorkers=2 \
  packages/adapter-utils/src/acpx-engine/execute.test.ts \
  packages/adapters/claude-local/src/server/execute.remote.test.ts \
  packages/adapters/codex-local/src/server/execute.remote.test.ts \
  packages/adapters/claude-local/src/server/acp.test.ts \
  packages/adapters/codex-local/src/server/acp.test.ts
PAPERCLIP_ENABLE_DARWIN_SSH_ENV_LAB=1 pnpm exec vitest run --maxWorkers=2 \
  server/src/services/ssh-remote-workspace.integration.test.ts
pnpm exec vitest run packages/adapter-utils/src/acpx-engine/remote-spawn-smoke.test.ts
pnpm --filter @paperclipai/adapter-utils typecheck
pnpm --filter @paperclipai/adapter-claude-local typecheck
pnpm --filter @paperclipai/adapter-codex-local typecheck
pnpm --filter @paperclipai/server typecheck
```

The new admission and staging cases failed before the source fix. The
first whole-heartbeat follow-up test also changed an agent setting
between turns. That correctly reset the session. The fixture now keeps
those settings unchanged and verifies the resumed conversation. Running
both engine cases together also exposed duplicate company prefixes and
environment names in the fixture; each case now uses its own names.

The SSH qualification uses a real isolated OpenSSH server, real
Postgres, real ACPX runtime and bridges, and a synthetic ACP provider
with a selected test account. It does not call a live provider or run an
agent on a user's computer.

## Risks

The change affects the shared ACP staging path, restricted to SSH
targets that declare in-place realization. Sandbox staging retains its
prior behavior, including the existing Codex in-place refusal. Copy-mode
SSH sessions retain their prior directory layout. Previously saved
sessions keep their format; this adds no migration or session reset.

ACP still requires its server command on the remote login PATH. Host
authentication and local confinement remain CLI-only. Cold
controller/provider reconnection and live Claude/Codex provider
acceptance are not qualified by this test. No staging deployment or
existing agent configuration is changed by this pull request.

## Model Used

OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) through the Codex harness, with xhigh
reasoning effort and code tools.

## 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 searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-17 13:18:26 -08:00
..

@paperclipai/adapter-utils

Shared utilities for Paperclip adapters: process spawning, environment injection, sandbox/SSH transport, workspace sync, and the round-trip helpers that move code between the local execution-workspace cwd and wherever the agent actually runs.

For the adapter-author guide see docs/adapters/creating-an-adapter.md and the in-repo notes at packages/adapters/AUTHORING.md.

Sandbox bridge deadlines

Command-managed bridge control operations (queue reads, input delivery, setup, and cleanup) have a host-enforced deadline of at most 30 seconds per shell command. A shorter configured timeout still applies. These operations cannot inherit the agent run's hours-long lifetime or wait forever on a provider that ignores its timeout. Long-lived agent session commands keep their own limits.

A control timeout reports a transport failure. It does not prove that the remote command stopped and does not replay an uncertain write. The process session closes failed input delivery and uses its existing shutdown path; normal execution settlement must still verify termination.

Native archive transfer deadlines

Native syncIn and syncOut calls accept an optional minimumTimeoutMs budget. The server validates this budget and extends the worker RPC deadline. Providers can honor this field for file transfers without changing their configuration. Daytona uses the larger of this minimum and its configured timeout. Other providers keep their existing behavior. The minimum is limited to 30 minutes and does not change sandbox lifetimes, stored settings or the timeout for other commands.

The remote-workspace archive path uses the verified capture size for downloads and the local archive size for uploads. Large archives get one second per MiB plus 60 seconds, capped at 30 minutes. Small archives keep the existing provider timeout when that calculation is no greater than five minutes. Archive size, checksum, confinement and host space checks still apply.

An exact retained-sandbox resume keeps its recorded provider timeout and RPC overhead. It uses the normal one-minute fallback only when no timeout was recorded. A five-minute cold restore must not be cut off by that fallback. Resume still targets the recorded allocation and does not acquire a replacement.

No-remote-git contract

The local execution-workspace cwd is the only persistence boundary across runs. No adapter may depend on a git remote for cross-run state.

Adapters that run the agent on a different host should use the SSH round-trip helpers in src/ssh.ts:

  • prepareWorkspaceForSshExecution({ spec, localDir, remoteDir }) — bundles the local cwd (tracked files, dirty edits, untracked additions, and the git history needed to reconstruct it) to remoteDir before the run starts. Runs with no git remote configured.
  • restoreWorkspaceFromSshExecution({ spec, localDir, remoteDir, ... }) — syncs the remote cwd back into localDir after the run, including any new commits the agent created. Also runs with no git remote configured.

prepareRemoteManagedRuntime in src/remote-managed-runtime.ts wraps both calls for adapters that want a per-run remote workspace and an automatic restoreWorkspace() finally hook.

The invariant is pinned by the no-remote-git contract case in src/ssh-fixture.test.ts, which asserts that a remote-only commit propagates to the local worktree through the prepare → restore round-trip with no git remote configured at any point. Do not regress that test.