0 Fork 0

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

Files

T

History

Devin FoleyandPaperclip eedf25655b test(adapter-utils): publish bridge queue fixtures atomically (#15792 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Remote agents send API requests through a callback bridge queue.
> - Queue readers reserve memory from each published file's measured
size.
> - Several tests wrote directly into visible queue files while the
reader was active.
> - A reader could measure an empty file and then reject its completed
contents with HTTP 503.
> - This pull request makes those fixtures use the existing atomic
publisher and proves the race without timing guesses.

## Linked Issues or Issue Description

**What happened?**

The public readiness run
[38035333062](https://github.com/paperclipai/paperclip/actions/runs/38035333062)
failed the schema-discovery bridge test. It expected HTTP 200 but
received 503. The same test logged `Bridge envelope exceeded the
configured size limit.`

The fixture wrote requests directly to visible `.json` files. If a
writer completed between the reader's size measurement and bounded read,
the reader correctly rejected the changed file. The production gateway
and filesystem queue client already publish complete files by renaming a
temporary file.

**Expected behavior**

Queue fixtures must publish requests with the same atomic contract as
the production writer. Schema assertions must observe completed
responses. The runtime must still reject a request that grows beyond the
size reserved for its read.

**Steps to reproduce**

Create an empty visible request file. Have the worker measure its size.
Complete the write before the bounded read. The new deterministic
regression produces the exact error and HTTP 503, with no handler
dispatch. A separate publication test polls during an incomplete write
and verifies that the real atomic writer keeps it invisible.

**Paperclip version or commit**

The failing run used `de042e79efbb7bb88e9716835407882e3ebab188`. The
same fixture and reader are present in the base of this PR,
`7e10dbe652ef0104f0a688a196fe8ea47b6f4b8e`.

**Deployment mode**

Local filesystem fixtures in the adapter-utils readiness tests. No
external provider is required.

Related PRs #15003 and #15696 address shutdown listing and idle polling.
This is a separate fixture-publication race. This PR does not adopt or
change their runtime work.

## What Changed

- Use the existing filesystem queue client's atomic publisher at seven
live-worker publication sites in five tests.
- Wait for all seven schema responses within the existing single
five-second bound, then assert the GET response and all six denials.
Worker shutdown remains cleanup for that test.
- Add a deterministic incomplete-write publication regression and a real
worker regression for the bounded reader's existing HTTP 503 recovery.
- Keep intentional malformed fixtures, dedicated drain assertions,
runtime limits and runtime source unchanged. Test comments explain the
publication contract; no product documentation changes are needed.

## Verification

- Full bridge file: 68/68 tests passed on Node 25.6.1.
- Seven focused publication, schema, authorization, drain and recovery
cases passed.
- Negative control: replacing the fixture helper with a direct write
makes the publication test fail in milliseconds with the exact
bounded-reader error. Restoring atomic publication passes.
- Broader adapter-utils run: 1,690 passed, 12 skipped, one unchanged
GitHub-launcher identity test exceeded its existing five-second limit.
That exact case passed unchanged in isolation. This is not claimed as a
full aggregate pass; no timeout or launcher source was changed.
- Full workspace `pnpm -r typecheck` and `pnpm build` passed.
- Independent review passed all 68 bridge tests and adapter-utils
typecheck, plus three negative controls: both forms of direct
publication fail, and removing the bounded read fails the expected-503
regression. The original source was restored and targeted positives
passed again.
- Hosted [CI
38038772400](https://github.com/paperclipai/paperclip/actions/runs/38038772400)
passed at `aa4bcd8c1729e8ce098f2eb0143502ab34237d01`, including the full
workspaces-b suite that originally failed. The PR has 53 successful
checks and two expected Storybook skips.
- Greptile scored that same commit 5/5; independent source review is
approved, no review threads remain open, and GitHub reports no merge
conflicts.

## Risks

This change only affects tests. The new filesystem spy is limited to its
own temporary directory and is restored in `finally`. A producer
regression must still fail the publication test. The schema test retains
all authorization checks and a single five-second response bound. The
bridge's size limits, failure recovery, request handling and shutdown
policy are unchanged.

## Model Used

OpenAI GPT-6 through Codex, with reasoning, repository tools and
independent agent review. The exact service model identifier and
context-window size are not exposed in this session.

## 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-10-10 01:55:29 -07:00

src

test(adapter-utils): publish bridge queue fixtures atomically (#15792 )

2026-10-10 01:55:29 -07:00

CHANGELOG.md

…

package.json

…

README.md

fix: bound sandbox bridge waits and flag silent runs sooner (#14979 )

2026-10-02 15:29:41 -07:00

tsconfig.json

…

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.

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.

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.