commitperclip[bot]
a00109aa35
> [!NOTE] > Opened by Prospector's automated issue-fix pipeline. A maintainer reviews and decides; nothing here merges on its own. > [!WARNING] > This change crosses a trust boundary. See Risks. ## Thinking Path - Issue #16034 reports a defect in paperclipai/paperclip. - Root cause, as the fixing agent read it: emitAcpxFailure in packages/adapter-utils/src/acpx-engine/execute.ts built the run error, summary, and acpx.error message from Error.message alone. It ignored the JSON-RPC error's 'data' explanation and numeric 'code', so every ACP phase failure (create runtime, ensure session, configure session, turn) showed only 'Internal error'. - This pull request: Preserve sanitized ACP JSON-RPC error details and numeric codes in run errors, summaries, and acpx.error records ## What Changed - `packages/adapter-utils/src/acpx-engine/execute.ts`: This change is kept from the earlier attempt. The shared failure handler reads the explanation from a string 'data', 'data.details', or 'data.message'. It appends that text to the message unless the message already contains it, and runs the result through sanitizeTerminalSessionFailure. A numeric JSON-RPC code is recorded as errorMeta.rpcCode. Errors without these fields keep their old message. - `packages/adapter-utils/src/acpx-engine/execute.test.ts`: The existing harness keeps the earlier it.each case, which covers all four phases, all three detail shapes, redaction, and rpcCode in the acpx.error record. A new case in the same harness covers the checks that only the separate file had: detail text already in the message is not repeated, and a plain Error stays unchanged with no rpcCode. - `doc/run-log-events.md`: Documents the change to the acpx.error record: which detail formats are read and in what order, the rule against repeating detail text, the redaction and 4,096-character title limit applied through the existing sanitizer, and the optional integer 'rpcCode' field. ## Verification - Reproducing test(s), added in this PR: `packages/adapter-utils/src/acpx-engine/execute.test.ts` - They fail on the base commit and pass with the fix, each twice in a fresh sandbox. - The repository's compile command passes with the fix applied. - 9 existing test file(s) near the change passed. - The full test suite passes except for the 11 file(s) that already fail on the base commit. ## Risks - Written by an automated pipeline, not a person: review it as you would an outside contribution. - Risk tier of the touched paths: 2. - The scope reviewer found it also changes, beyond the report: Plain Error, non-object throw, string or Node errors with string codes (ENOENT), and data that is empty, missing, non-string or malformed - The scope reviewer found it also changes, beyond the report: messageOverride callers (turn timeout, handshake guard) - It crosses a trust boundary. Check each crossing against what the issue asked for, and against who asked: - data-exposure (packages/adapter-utils/src/acpx-engine/execute.ts:3626): Text the ACP child process controls (JSON-RPC error 'data', 'data.details' or 'data.message') is now added to the run error message and summary that users see; it passes through sanitizeTerminalSessionFailure redaction first. - logging (packages/adapter-utils/src/acpx-engine/execute.ts:3651): The 'acpx.error' run-log record now carries the provider's explanation in 'message' and a new integer 'rpcCode' field, both supplied by the child, on every failure route that calls emitAcpxFailure without a messageOverride, including the handshake-guard route that suppresses stderr. - data-exposure (packages/adapter-utils/src/acpx-engine/execute.ts:3639): The numeric JSON-RPC error code from the child is now copied into 'classified.errorMeta.rpcCode', which reaches the adapter result's errorMeta and the places that store or show it. ## Model Used - opus (Anthropic Claude, via Claude Code), writing and checking the change in an isolated sandbox. - opus (Anthropic Claude, via Claude Code), reviewing it independently. ## Linked Issues Fixes #16034 A search of paperclipai/paperclip's open and closed pull requests found no other pull request that names #16034. ## 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) - [ ] 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) - [ ] 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 - [ ] 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 - [ ] I will address all Greptile and reviewer comments before requesting merge <!-- prospector:issue-fix v1 issue=16034 base=5cfa2bf26d3e report=1b07160d9492357f --> Co-authored-by: commitperclip[bot] <284812584+commitperclip[bot]@users.noreply.github.com>
@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) toremoteDirbefore the run starts. Runs with nogit remoteconfigured.restoreWorkspaceFromSshExecution({ spec, localDir, remoteDir, ... })— syncs the remote cwd back intolocalDirafter the run, including any new commits the agent created. Also runs with nogit remoteconfigured.
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.