Files
PaperClipAI/packages/adapter-utils
Devin FoleyandPaperclip eaf6461cee fix(server): give a slow remote more time to exclude agent files from Git (#22039)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Before a remote run starts, Paperclip runs a short Node program in
the sandbox that keeps the reserved runtime directory out of task Git
staging
> - That program had one 15 second attempt. A freshly created sandbox is
sometimes slow, so the attempt timed out
> - The run then failed before any provider work started, with the
generic `adapter_failed` code. Nothing retried it, and the wake that
started the run was lost
> - This pull request gives each attempt 30 seconds and retries a
timed-out attempt, up to three attempts
> - The benefit is that a slow sandbox no longer stops a task, while a
real failure still fails at once and names its reason

## Linked Issues or Issue Description

Builds on #21499 (merged), which adds the closed `reason=` code to this
error.

**What happened?**
A run failed during preparation with "Could not exclude agent files from
task Git staging". The sandbox lease was acquired about 50 seconds
before the agent-file copy was registered (3 to 7 seconds on the same
stack's earlier runs). The copy failed 20 seconds after it was
registered, which matches the 15 second limit. Earlier failures with
this message all took at least 16 seconds before failing, so they also
match a timeout rather than an error from the program itself.

**Steps to reproduce**
1. Start a remote run on a sandbox that takes more than 15 seconds to
run a short command.
2. The run fails in the preparing stage and is not retried.

**Expected behavior**
A slow sandbox gets more time, and a timed-out attempt is retried.

**Actual behavior**
One 15 second attempt, then the run fails.

## What Changed

- `agent-instruction-files.ts`: add `excludeRuntimeFromRemoteGit`. Each
attempt gets 30 seconds. A timed-out attempt is retried, up to three
attempts. Any other failure throws at once. The error keeps the closed
`reason=` code from #21499.
- `agent-directory-working-copies.ts` and
`agent-instruction-working-copies.ts`: both remote call sites use the
helper, so the private instruction copy also names a reason.
- `execution-target.ts`: `runSshCommand` rejects a command its timeout
killed with `code: null` and `killed: true`, but only `ETIMEDOUT` was
treated as a timeout, so an SSH timeout was thrown instead of returned.
A killed command now returns `timedOut: true`, as the sandbox path
already does.
- Tests: a timeout followed by success stages the agent files; three
timeouts fail with `reason=timed_out`; a non-timeout failure is
attempted once. An adapter-utils test covers the real SSH timeout
rejection.

## Verification

- `npx vitest run` on the agent-directory, instruction working-copy, Git
exclusion, copy retry backoff, instruction-working-copy and remote
checkpoint lock suites: 217/217 pass.
- adapter-utils `execution-target` and sandbox suites: 173/173 pass.
adapter-utils SSH suites: 65 pass, 2 skipped. Server adapter registry
suite: 67/67 pass.
- The new cases fail without this change.
- `npx tsc --noEmit` passes for server and adapter-utils.

## Risks

- Low. A sandbox that never answers now takes up to 90 seconds to fail
instead of 15 seconds.
- An SSH shell command that times out is now returned as `timedOut`
instead of thrown. Every caller that checks the result already treats
`timedOut` as a failure. The home-directory probe and the empty-file
helper ignore the result, so for them an SSH timeout now behaves as a
sandbox timeout already did.
- The exclusion program is idempotent: it writes its file through a
temporary name and a rename, so a retry after a late first attempt
leaves the same result.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution
in Claude Code.

## 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
- [ ] All Paperclip CI gates are green
- [ ] 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 14:28:27 -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.