RomanNum3ral
/
paperclip
mirror of https://github.com/paperclipai/paperclip.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
paperclip/packages/adapter-utils
History
Priya Raman dd6742f7d0
fix(sandbox): reset step store for long-lived bridge work 
A run-time `sandbox.exec` span attached to a dead startup step. Two bridge
startup steps start long-lived work inside their measured step body: a poll
timer, socket handlers, and a callback-bridge worker loop. Node snapshots the
active-step store on each async resource at creation time, so this work kept
the ended step store. Each later run-time exec then read that store and opened
its span under the ended step, and it copied a wrong `criticalPath: false` flag.

Add an exported `runWithoutActiveStep` helper in startup-timing and wrap the
long-lived poll timer, the socket handlers, and the callback-bridge worker loop
of both bridge lanes. Each continuation now reads an empty store, so each
run-time exec opens an unparented span with no stale `criticalPath` flag.
Control flow is unchanged and the change adds no new dependency.

Co-authored-by: Paperclip <noreply@paperclip.ing>
 		2026-08-04 06:22:17 +00:00
..
src fix(sandbox): reset step store for long-lived bridge work 2026-08-04 06:22:17 +00:00
CHANGELOG.md chore: release v0.3.1 2026-03-12 13:09:22 -05:00
README.md PAPA-430: workspace finalize gates + no-remote-git enforcement (#6969) 2026-05-29 08:25:29 -07:00
package.json build(deps-dev): bump @types/node from 22.19.21 to 22.20.1 (#10304) 2026-07-28 10:48:45 -07:00
tsconfig.json Fix root TypeScript solution config 2026-03-09 14:09:30 -05:00

README.md

@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.

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.