mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
fix(execution-target): give a failed Git context probe a stable error code (#22093)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Before an agent run starts on a remote execution target (sandbox or SSH), Paperclip runs a small probe that reads the Git context of the remote workspace > - When that probe fails, it throws a plain `Error` with one fixed message and no code > - Run-failure reporting groups failures by error code, never by message. So these failures share one Sentry group with every other setup failure that has no code > - The thrown error also drops the exit facts of the probe. Nobody can see from the run why the probe failed > - This pull request gives the probe failure a stable code and a bounded reason > - The benefit is a separate, correctly named Sentry group for this failure, and run records that show why the probe failed ## Linked Issues or Issue Description **What happened?** On staging, many runs failed during setup with "Could not read execution-target Git context". The burst occurred during a sandbox provider outage. These failures had no error code. The Sentry fingerprint for run failures uses the error code, the adapter, the phase and the root error code or class name. Because the message is deliberately not in the fingerprint, these failures went into the same group as unrelated setup failures. The probe also discarded its exit code, timeout and signal, so the cause of each failure was not recorded. **Expected behavior** A failed Git context probe has a stable error code, so it gets its own Sentry group. The error message names a bounded reason (exit code, timeout, signal, or incomplete or invalid output), so the run record shows why the probe failed. The probe output is never included, because it can contain credentials and paths. **Steps to reproduce** Run `prepareGitHubExecutionEnvironment` with a remote target whose command runner returns a non-zero exit code, a timeout, a signal, or output without the probe frame. On current master the error has no `code` and no reason. ## What Changed - `packages/adapter-utils/src/execution-target.ts`: add `EXECUTION_TARGET_GIT_CONTEXT_UNAVAILABLE_CODE` (`execution_target_git_context_unavailable`). The three probe failure paths now throw an `Error` with this code. The message keeps the old prefix and adds a bounded reason: exit code, timeout, signal, or incomplete or invalid output. - The probe output is never put in the message. - An error that the command runner throws itself (for example a provider HTTP error) is not changed. It keeps its own code and status. - The success condition is not changed. - `packages/adapter-utils/src/github-launcher-environment.test.ts`: add tests for each failure reason, a test that the probe output does not leak into the message, and a test that a runner error passes through unchanged. ## Verification - `vitest run packages/adapter-utils/src/github-launcher-environment.test.ts packages/adapter-utils/src/execution-target*`: 273 tests pass, including the 6 new tests. - Red/green: on the unfixed source, 5 of the 6 new tests fail. The runner-error test passes on both, as intended, because it checks behavior that must not change. - `tsc --noEmit -p packages/adapter-utils/tsconfig.json` passes (sources and tests). - One existing test, "preserves local host credential helpers and validates worktree metadata", fails in my local sandbox on unmodified master too. It depends on the local Git configuration. CI covers it. ## Risks - Low risk. Only the error that the probe throws changes. The success path and the conditions for failure do not change. - `resultJson.failureCause` for these runs becomes `execution_target_git_context_unavailable` instead of `Error`. No code compares `failureCause` with `Error`. - New Sentry events for this failure go to a new group. The old shared group stops receiving them. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used as an agent with tool use and code execution (shell, Git, Vitest). ## 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 - [ ] 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2 files changed
+49
-3
No files matched your search
@@ -1721,6 +1721,20 @@ async function githubOperationLauncherBasePath(
|
||||
return remotePath;
|
||||
}
|
||||
|
||||
export const EXECUTION_TARGET_GIT_CONTEXT_UNAVAILABLE_CODE = "execution_target_git_context_unavailable";
|
||||
|
||||
function gitContextUnavailable(reason: string): Error {
|
||||
return Object.assign(new Error(`Could not read execution-target Git context: ${reason}`),
|
||||
{ code: EXECUTION_TARGET_GIT_CONTEXT_UNAVAILABLE_CODE });
|
||||
}
|
||||
|
||||
function gitContextProbeFailureReason(result: Pick<RunProcessResult, "exitCode" | "signal" | "timedOut">): string {
|
||||
if (result.timedOut) return "the probe timed out";
|
||||
if (typeof result.signal === "string" && /^SIG[A-Z0-9]{1,12}$/.test(result.signal)) return `the probe was stopped by ${result.signal}`;
|
||||
if (Number.isSafeInteger(result.exitCode)) return `the probe exited with code ${result.exitCode}`;
|
||||
return "the probe reported no exit status";
|
||||
}
|
||||
|
||||
/** Read only execution-target Git context; never import the controller's credentials into SSH. */
|
||||
export async function prepareGitHubExecutionEnvironment(input: {
|
||||
target: AdapterExecutionTarget | null | undefined;
|
||||
@@ -1807,9 +1821,9 @@ printf '\0PAPERCLIP_GIT_CONTEXT_END\0'
|
||||
// workspaces can live at a different path on the execution target.
|
||||
cwd: remote.remoteCwd, timeoutMs: 15_000,
|
||||
});
|
||||
if (result.exitCode !== 0) throw new Error("Could not read execution-target Git context");
|
||||
if (result.exitCode !== 0) throw gitContextUnavailable(gitContextProbeFailureReason(result));
|
||||
const payload = result.stdout.split("\0PAPERCLIP_GIT_CONTEXT_V1\0")[1]?.split("\0PAPERCLIP_GIT_CONTEXT_END\0")[0];
|
||||
if (payload === undefined) throw new Error("Could not read execution-target Git context");
|
||||
if (payload === undefined) throw gitContextUnavailable("the probe output was incomplete");
|
||||
discovered = {};
|
||||
const records = payload.split("\0");
|
||||
const roots: string[] = [];
|
||||
@@ -1826,7 +1840,7 @@ printf '\0PAPERCLIP_GIT_CONTEXT_END\0'
|
||||
} else {
|
||||
const result = await promisify(execFile)(process.execPath, args, { cwd: input.cwd, timeout: 15_000, maxBuffer: 1024 * 1024 });
|
||||
try { discovered = JSON.parse(result.stdout.split("\0")[1] ?? ""); }
|
||||
catch { throw new Error("Could not read execution-target Git context"); }
|
||||
catch { throw gitContextUnavailable("the probe output was not valid"); }
|
||||
}
|
||||
// Controller-derived roots and mode must not be replaced by agent bindings.
|
||||
return { ...discovered, ...input.env,
|
||||
|
||||
@@ -15,6 +15,7 @@ import {
|
||||
cleanupGitHubOperationLaunchers,
|
||||
prepareGitHubExecutionEnvironment,
|
||||
runAdapterExecutionTargetProcess,
|
||||
EXECUTION_TARGET_GIT_CONTEXT_UNAVAILABLE_CODE,
|
||||
} from "./execution-target.js";
|
||||
|
||||
const exec = promisify(execFile);
|
||||
@@ -361,6 +362,37 @@ describe("managed GitHub launcher environment", () => {
|
||||
expect(fixture.runner.execute).toHaveBeenCalledWith(expect.objectContaining({ cwd: fixture.root }));
|
||||
});
|
||||
|
||||
it.each([
|
||||
[{ exitCode: 2, signal: null, timedOut: false, stdout: "" }, "the probe exited with code 2"],
|
||||
[{ exitCode: null, signal: null, timedOut: true, stdout: "" }, "the probe timed out"],
|
||||
[{ exitCode: null, signal: "SIGKILL", timedOut: false, stdout: "" }, "the probe was stopped by SIGKILL"],
|
||||
[{ exitCode: null, signal: null, timedOut: false, stdout: "" }, "the probe reported no exit status"],
|
||||
[{ exitCode: 0, signal: null, timedOut: false, stdout: "login banner only" }, "the probe output was incomplete"],
|
||||
])("reports an incomplete remote Git context probe with a stable code: %o", async (outcome, reason) => {
|
||||
const fixture = await sandbox("usr/bin");
|
||||
fixture.runner.execute.mockResolvedValue({ ...outcome, stderr: "fatal: GH_TOKEN=probe-secret /private/path",
|
||||
pid: null, startedAt: new Date().toISOString() });
|
||||
|
||||
const failure = await prepareGitHubExecutionEnvironment({
|
||||
target: fixture.target, cwd: fixture.root, env: {}, hostCredentials: false, networkAccess: true,
|
||||
}).catch((error: unknown) => error);
|
||||
|
||||
expect(failure).toBeInstanceOf(Error);
|
||||
expect(failure).toMatchObject({ code: EXECUTION_TARGET_GIT_CONTEXT_UNAVAILABLE_CODE,
|
||||
message: `Could not read execution-target Git context: ${reason}` });
|
||||
expect((failure as Error).message).not.toMatch(/probe-secret|private|banner/);
|
||||
});
|
||||
|
||||
it("leaves a runner that cannot execute the probe with its own error", async () => {
|
||||
const fixture = await sandbox("usr/bin");
|
||||
const unavailable = Object.assign(new Error("Daytona exec failed"), { status: 503 });
|
||||
fixture.runner.execute.mockRejectedValue(unavailable);
|
||||
|
||||
await expect(prepareGitHubExecutionEnvironment({
|
||||
target: fixture.target, cwd: fixture.root, env: {}, hostCredentials: false, networkAccess: true,
|
||||
})).rejects.toBe(unavailable);
|
||||
});
|
||||
|
||||
it("reads Git metadata from the SSH workspace instead of an existing controller directory", async () => {
|
||||
const fixture = await sandbox("ssh-toolchain/bin");
|
||||
// Use real Git for the probe, not the launcher fixture's stub.
|
||||
|
||||
Reference in new issue
Block a user