0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-06 10:48:12 +02:00

Files

T

Devin Foley ffd62a4cbb fix(adapter-utils): carry the workspace origin remote into transported git workspaces (#10873 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - When an agent runs on a different host (sandbox or SSH), the adapter
transport copies the local git execution workspace to that host and
syncs changes back after the run
> - The transport materializes the remote copy with `git init` plus a
depth-1 or bundle fetch, so the copy has no `origin` remote and its head
reads as a parentless snapshot commit
> - An agent asked to publish its branch (push it, open a pull request)
sees "no remote, root snapshot" and must hand the publish step back to a
human operator, even when the branch base is a commit the upstream
remote already holds
> - This pull request carries the workspace's `origin` URL
(credential-scrubbed) onto the transported copy as metadata
> - The benefit is that branches produced in transported workspaces stay
publishable by any actor with credentials, while the transport itself
still never fetches or pushes

## Linked Issues or Issue Description

No public issue exists. Description follows the enhancement template:

**What existing behavior does this improve?**

The workspace transport in `@paperclipai/adapter-utils` already copies a
git workspace to the execution host and back. This change improves the
fidelity of that copy: the transported repo keeps the workspace's
`origin` remote instead of losing it.

**Subsystem affected**

Adapter utilities — the sandbox transport
(`withShallowGitWorkspaceClone` in
`packages/adapter-utils/src/git-workspace-sync.ts`) and the SSH
transport (`importGitWorkspaceToSsh` in
`packages/adapter-utils/src/ssh.ts`).

**Current behavior**

The transported copy is built with `git init` plus a depth-1 (sandbox)
or bundle (SSH) fetch. It has no remotes. `git remote -v` is empty and
the head commit reads as a root snapshot with no visible ancestry.
Agents and operators inside the execution host cannot fetch real
ancestry or push a branch, even when the branch base is a commit the
upstream remote already holds.

**Proposed behavior**

The transport reads the source workspace's `origin` URL, scrubs
credentials from it, and configures it on the transported copy. The
sandbox path adds the remote to the fresh clone. The SSH path sets or
adds the remote in the remote setup script, which also covers reused
workspace directories. A workspace with no `origin` transports exactly
as before.

**Reason and benefit**

A branch committed in a transported workspace becomes publishable in
place: the shallow boundary commit already exists on the remote, so a
push pack closes without full local ancestry (a new test locks in this
property). Fetching real ancestry also becomes possible for whoever
holds credentials. Without this, agents must describe their change in a
handoff document and a human must reconstruct the branch by hand.

**Breaking changes**

None. The URL copy is best-effort and metadata-only. The transport never
fetches from or pushes to the remote. The no-remote-git contract holds:
sync-back through the local cwd stays the only cross-run persistence
path, and `packages/adapters/AUTHORING.md` gains a paragraph that makes
the carried-remote nuance explicit.

## What Changed

- `packages/adapter-utils/src/git-workspace-sync.ts`: new
`sanitizeGitRemoteUrl` (strips http(s) userinfo, where tokens can be
embedded; scp-like/ssh forms and filesystem paths pass through) and
`readSanitizedOriginRemoteUrl`; `withShallowGitWorkspaceClone`
configures the scrubbed `origin` on the fresh clone, best-effort.
- `packages/adapter-utils/src/ssh.ts`: `importGitWorkspaceToSsh` sets or
adds the scrubbed `origin` in the remote setup script, non-fatal under
`set -e`.
- `packages/adapter-utils/src/git-workspace-sync.test.ts`: four new
integration cases (remote copied, credentials scrubbed, no-origin
unchanged, push from the shallow clone to an origin that holds the base
commit) plus `sanitizeGitRemoteUrl` unit tests.
- `packages/adapters/AUTHORING.md`: documents that a transported copy
may carry a credential-scrubbed `origin` as metadata, and why this does
not weaken the no-remote-git contract.

## Verification

- `npx vitest run packages/adapter-utils/src/git-workspace-sync.test.ts`
— 12/12 pass (4 new integration cases + sanitizer unit tests).
- `npx vitest run
packages/adapter-utils/src/sandbox-managed-runtime.test.ts` — 24/24
pass.
- `npx vitest run packages/adapter-utils/src/ssh-fixture.test.ts` —
16/16 pass, including the `no-remote-git contract` case (a workspace
without `origin` still round-trips with no remote introduced at any
point).
- `node scripts/check-no-git-push.mjs` — passes; this change adds no
push or fetch to adapter/runtime code.
- `pnpm typecheck` in `packages/adapter-utils` — clean.

## Risks

- Low risk. The change is additive metadata on the transported copy
only; failure to record the remote never fails the transport.
- Credential exposure is the real hazard and is handled: http(s)
userinfo is stripped before the URL leaves the host. Non-http forms
(scp-like, `ssh://`) carry no secret in the URL and pass through.
- A reused SSH workspace whose project `origin` changed now gets the
current URL via `set-url` instead of keeping a stale one.

## Model Used

Claude Fable 5 (`claude-fable-5`), Anthropic — extended thinking,
agentic tool use via Claude Code CLI.

## 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

2026-08-05 10:24:01 -07:00

4.1 KiB

Raw Permalink Blame History

Adapter Authoring Notes

In-repo notes for adapter authors. The user-facing guide lives at docs/adapters/creating-an-adapter.md; this file holds invariants that are easy to violate from inside the adapter package itself.

No-remote-git contract (cross-run persistence)

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

Why: Paperclip resolves a local execution workspace (a worktree) for each heartbeat. Code state is carried forward by syncing that local cwd to wherever the agent actually runs — over ssh, into a sandbox, into a managed runtime — and then syncing changes back when the run finishes. Treating a git remote as the source of truth (git push from inside the agent, fetch on the next wake) breaks dependent issues that are gated on the local worktree being caught up, and breaks isolated execution workspaces that have no remote configured at all.

How to apply:

Never git push from adapter runtime code. Never assume the local worktree has any git remote configured. If you need data from the previous run, read it from the local cwd Paperclip handed you.
If your adapter runs the agent on a different host (ssh, sandbox, remote container), use the round-trip helpers in @paperclipai/adapter-utils: prepareWorkspaceForSshExecution bundles the local cwd to the remote dir before the run, and restoreWorkspaceFromSshExecution syncs remote-side changes (including new git commits) back into the local cwd after the run. Both run with no git remote configured.
If your adapter runs the agent locally, you can read and write the cwd directly — same invariant applies: changes that future runs need must live in the local cwd by the time execute() returns.
A failed sync-back is a run-level error. The heartbeat records workspace_finalize=failed on the execution workspace, which gates dependent issue wakes until the next successful finalize. Do not swallow restore errors.
A transported workspace copy may carry the local workspace's origin remote URL so that branches in the copy stay publishable by the agent or an operator who holds credentials — the transport helpers copy the URL as metadata only. The copy is allowlist-based and fails closed (sanitizeGitRemoteUrl): http(s) URLs are stripped of userinfo, query, and fragment; ssh:/git: scheme URLs are stripped of password and query; scp-like user@host:path passes through (the syntax has no password slot); every other shape — filesystem paths, unknown schemes — is dropped rather than risk persisting an embedded secret. This does not weaken the contract: sync-back through the local cwd remains the only cross-run persistence path, the helpers never fetch from or push to that remote, and a workspace without an origin transports exactly as before.

The invariant is pinned by the no-remote-git contract case in packages/adapter-utils/src/ssh-fixture.test.ts, which asserts that a remote-only commit propagates to the local worktree through prepareWorkspaceForSshExecution → restoreWorkspaceFromSshExecution with no git remote configured at any point.

A static check enforces the rule before runtime ever sees it: scripts/check-no-git-push.mjs scans adapter and runtime source (packages/adapters/, packages/adapter-utils/, server/src/, cli/src/) and fails the policy CI job if any unapproved git push invocation is added. If you are building an operator-configured path that legitimately must push, add a // paperclip:allow-git-push: <reason> comment on the line (or the line above) so the opt-in shows up in code review.

For the architecture-level write-up of cross-run persistence, see docs/guides/board-operator/execution-workspaces-and-runtime-services.md.

4.1 KiB Raw Permalink Blame History

Adapter Authoring Notes

No-remote-git contract (cross-run persistence)

4.1 KiB

Raw Permalink Blame History