mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
fix(claude-local): fail Opus 5.5 ACP runs early when the bundled Claude Code is too old (#13927)
Thanks @spaceshipmike for the clear report in #13889 and the `CLAUDE_CODE_EXECUTABLE` workaround, and thanks @chen97 for the follow-up. ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `claude_local` defaults to the ACP lane, which runs the ACP bridge's bundled Claude Code > - npm installs get Claude Code 2.1.257, because the root pnpm override does not reach them > - Opus 5.5 needs 2.1.280, so each run fails with only "terminal service failure" > - This pull request adds the CLI lane version check to the ACP lane > - The error then names both versions and the fix ## Linked Issues or Issue Description Refs #13889. This PR adds the clear failure the issue asks for. The bridge bump stays with maintainers (#13838 moved the workspace override to 0.3.280). Bridge 0.81.0 is the first stable release on SDK 0.3.280. ## What Changed - `acp.ts`: before launch, compare the bundled `claudeCodeVersion` with `minimumClaudeCliVersionForModel()`. Return `claude_cli_version_incompatible` with the CLI lane fields. - `cli-capabilities.ts`: `readBundledClaudeCodeVersion()` resolves the SDK through the bridge, like `build-provider-pack.mjs`. - Match the `jp.` and `au.` Bedrock prefixes. Opus 5.5 has both profiles. ## Verification Default ACP lane on Bedrock, published `2026.924.0-canary.0`. After = that install with this branch's build. | Case | Before | After | |---|---|---| | `us.anthropic.claude-opus-5-5` | ❌ `acpx_turn_failed`, "ACP agent reported a terminal service failure." (6.9 s) | ✅ clear `claude_cli_version_incompatible` before launch (0 s) | | `jp.anthropic.claude-opus-5-5` (ap-northeast-1) | ❌ same generic failure | ✅ same clear error | | `us.anthropic.claude-opus-5` (no minimum) | ✅ runs | ✅ runs, unchanged | | Opus 5.5 + `CLAUDE_CODE_EXECUTABLE` in agent env (2.1.281) | ✅ runs | ✅ runs, check skipped | | `engine=cli` + Claude Code 2.1.281, `jp.` profile | ✅ runs | ✅ runs, version probe passes | | Source checkout (override, bundled 2.1.280), `us.` Opus 5.5 | ✅ runs | ✅ runs, unchanged | ```text us.anthropic.claude-opus-5-5 requires Claude Code 2.1.280 or newer; the ACP lane runs the bundled Claude Code 2.1.257. Set CLAUDE_CODE_EXECUTABLE in the agent env to a newer Claude Code, or set engine=cli, before retrying. ``` ```text # source reverted, new tests kept Tests 7 failed | 4 passed | 40 skipped (51) # this branch (includes npm-style trees: SDK hoisted, and SDK nested under the bridge) Tests 11 passed | 40 skipped (51) # claude-local project (was 314 passed) Tests 322 passed | 1 skipped (323) # also: claude-local typecheck, check-forbidden-tokens, check-module-boundaries, UI effort tests (97), server adapter tests (34) ``` ## Risks Low risk. The check reads one `package.json`, only for models with a minimum. It skips remote targets, custom `agentCommand`, `CLAUDE_CODE_EXECUTABLE`, and an unreadable SDK. ## Model Used Claude via Claude Code (tool use, code execution). <details><summary>Root cause, raw runs, checklist</summary> - `claude-agent-acp@0.73.0` pins SDK `0.3.257` (`claudeCodeVersion: "2.1.257"`). The override at `pnpm-workspace.yaml:36` changes only the workspace lockfile (see `installation-integrity.ts:96`). - The CLI lane checks at `execute.ts:1263`. The ACP engine keeps provider text out of results (`acpx-engine/execute.ts:4757`). - A server-level `CLAUDE_CODE_EXECUTABLE` is not in the host env allowlists (`acpx-engine/execute.ts:556`, `:588`). The agent env works. This can explain what @chen97 saw. - The `CLAUDE_CODE_EXECUTABLE` test also passes on master. It guards the workaround. ```text claude 2.1.257 --model us.anthropic.claude-opus-5-5 (us-east-1): api_error_status=400 API Error: 400 Claude Code 2.1.257 does not support this model; version 2.1.280 or newer is required. claude 2.1.257 --model jp./au.anthropic.claude-opus-5-5 (ap-northeast-1 / ap-southeast-2): same 400 claude 2.1.281 --model jp.anthropic.claude-opus-5-5 (ap-northeast-1): Hello! before, server env CLAUDE_CODE_EXECUTABLE | us.anthropic.claude-opus-5-5: errorCode=acpx_turn_failed before, agent env CLAUDE_CODE_EXECUTABLE | us.anthropic.claude-opus-5-5: exitCode=0 hello ``` - [x] I used Claude Code to search GitHub for duplicate or related PRs (none references #13889) - [x] Thinking path, `Refs #13889`, tests, and risks included; public references only; descriptive branch name - [x] I used Claude Code to run the tests locally, and they pass - [ ] Model version listed, ROADMAP.md checked, docs updated - [ ] CI green, Greptile 5/5, reviewer comments addressed </details> --------- Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
1 parent
2e795628eb
commit
8d3dfab52c
5 files changed
+164
-7
No files matched your search
@@ -3,7 +3,13 @@ import { claudeLocalReasoningEffortsForModel, DEFAULT_CLAUDE_LOCAL_MODEL, resolv
|
||||
import { minimumClaudeCliVersionForModel } from "./server/cli-capabilities.js";
|
||||
|
||||
describe("Claude model defaults", () => {
|
||||
it.each(["claude-opus-5-5", "us.anthropic.claude-opus-5-5", "global.anthropic.claude-opus-5-5[1m]"])("requires a current CLI and offers all efforts for %s", (model) => {
|
||||
it.each([
|
||||
"claude-opus-5-5",
|
||||
"us.anthropic.claude-opus-5-5",
|
||||
"global.anthropic.claude-opus-5-5[1m]",
|
||||
"jp.anthropic.claude-opus-5-5",
|
||||
"au.anthropic.claude-opus-5-5",
|
||||
])("requires a current CLI and offers all efforts for %s", (model) => {
|
||||
expect(minimumClaudeCliVersionForModel(model)).toBe("2.1.280");
|
||||
expect(claudeLocalReasoningEffortsForModel(model)).toEqual(["low", "medium", "high", "xhigh", "max"]);
|
||||
});
|
||||
|
||||
@@ -24,7 +24,7 @@ export function resolveClaudeModel(
|
||||
export const type = "claude_local";
|
||||
|
||||
export function claudeLocalReasoningEffortsForModel(model: string): readonly string[] {
|
||||
const id = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global)\.)?anthropic\./, "");
|
||||
const id = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global|jp|au)\.)?anthropic\./, "");
|
||||
if (/^claude-haiku-/.test(id)) return [];
|
||||
if (/^claude-(?:opus-5(?:-5)?|opus-4-[78]|sonnet-5(?:-5)?|fable-5(?:-1)?)$/.test(id)) {
|
||||
return ["low", "medium", "high", "xhigh", "max"];
|
||||
|
||||
@@ -19,6 +19,11 @@ vi.mock("@paperclipai/adapter-utils/execution-target", async (importActual) => {
|
||||
};
|
||||
});
|
||||
import { prepareAdapterExecutionTargetRuntime } from "@paperclipai/adapter-utils/execution-target";
|
||||
vi.mock("./cli-capabilities.js", async (importActual) => {
|
||||
const actual = await importActual<typeof import("./cli-capabilities.js")>();
|
||||
return { ...actual, readBundledClaudeCodeVersion: vi.fn(actual.readBundledClaudeCodeVersion) };
|
||||
});
|
||||
import { readBundledClaudeCodeVersion } from "./cli-capabilities.js";
|
||||
import {
|
||||
buildClaudeAcpConfig,
|
||||
createClaudeAcpExecutor,
|
||||
@@ -800,6 +805,82 @@ describe("claude_local ACP lane", () => {
|
||||
expect(meta[0]?.env?.ANTHROPIC_MODEL).toBe("claude-fable-5-1");
|
||||
});
|
||||
|
||||
it("reads the Claude Code version bundled with the ACP bridge", async () => {
|
||||
await expect(readBundledClaudeCodeVersion()).resolves.toMatch(/^\d+\.\d+\.\d+$/);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["hoisted", { "node_modules/@anthropic-ai/claude-agent-sdk": "2.1.257" }],
|
||||
// npm nests the bridge's pinned SDK when another SDK version is hoisted.
|
||||
["nested under the bridge", {
|
||||
"node_modules/@anthropic-ai/claude-agent-sdk": "2.1.280",
|
||||
"node_modules/@agentclientprotocol/claude-agent-acp/node_modules/@anthropic-ai/claude-agent-sdk": "2.1.257",
|
||||
}],
|
||||
])("reads the bridge's Claude Code version from an npm install with the SDK %s", async (_layout, sdkDirs) => {
|
||||
const root = await makeTempRoot("paperclip-claude-acp-npm-layout-");
|
||||
const writePackage = async (dir: string, manifest: Record<string, unknown>) => {
|
||||
await fs.mkdir(path.join(root, dir), { recursive: true });
|
||||
await fs.writeFile(path.join(root, dir, "package.json"), JSON.stringify(manifest));
|
||||
};
|
||||
// Export maps as published: the bridge exports ./*, the SDK exports only ".".
|
||||
await writePackage("node_modules/@agentclientprotocol/claude-agent-acp", { exports: { "./*": "./*" } });
|
||||
for (const [dir, claudeCodeVersion] of Object.entries(sdkDirs)) {
|
||||
await writePackage(dir, { exports: { ".": { default: "./sdk.mjs" } }, claudeCodeVersion });
|
||||
await fs.writeFile(path.join(root, dir, "sdk.mjs"), "");
|
||||
}
|
||||
|
||||
const adapterModule = path.join(root, "node_modules/@paperclipai/adapter-claude-local/dist/server/cli-capabilities.js");
|
||||
await expect(readBundledClaudeCodeVersion(adapterModule)).resolves.toBe("2.1.257");
|
||||
});
|
||||
|
||||
it.each([
|
||||
["claude-opus-5-5", {}],
|
||||
["us.anthropic.claude-opus-5-5", { CLAUDE_CODE_USE_BEDROCK: "1" }],
|
||||
])("rejects %s before launch when the bundled Claude Code is too old", async (model, env) => {
|
||||
vi.mocked(readBundledClaudeCodeVersion).mockResolvedValueOnce("2.1.257");
|
||||
const root = await makeTempRoot("paperclip-claude-acp-old-bundle-");
|
||||
const runtimes: FakeRuntime[] = [];
|
||||
const execute = createClaudeAcpExecutor({
|
||||
createRuntime: (options: FakeRuntimeOptions) => {
|
||||
const runtime = new FakeRuntime(options);
|
||||
runtimes.push(runtime);
|
||||
return runtime as never;
|
||||
},
|
||||
});
|
||||
|
||||
const context = buildContext(root);
|
||||
const result = await execute({ ...context, config: { ...context.config, model, env } });
|
||||
|
||||
expect(runtimes.flatMap((runtime) => runtime.startInputs)).toEqual([]);
|
||||
expect(result.errorCode).toBe("claude_cli_version_incompatible");
|
||||
expect(result.errorMessage).toContain(`${model} requires Claude Code 2.1.280 or newer`);
|
||||
expect(result.resultJson).toMatchObject({
|
||||
requiredClaudeCodeVersion: "2.1.280",
|
||||
detectedClaudeCodeVersion: "2.1.257",
|
||||
});
|
||||
});
|
||||
|
||||
it("leaves Opus 5.5 to an explicit CLAUDE_CODE_EXECUTABLE on the ACP lane", async () => {
|
||||
vi.mocked(readBundledClaudeCodeVersion).mockClear();
|
||||
const root = await makeTempRoot("paperclip-claude-acp-executable-");
|
||||
const execute = createClaudeAcpExecutor({
|
||||
createRuntime: (options: FakeRuntimeOptions) => new FakeRuntime(options) as never,
|
||||
});
|
||||
|
||||
const context = buildContext(root);
|
||||
const result = await execute({
|
||||
...context,
|
||||
config: {
|
||||
...context.config,
|
||||
model: "claude-opus-5-5",
|
||||
env: { CLAUDE_CODE_EXECUTABLE: path.join(root, "claude") },
|
||||
},
|
||||
});
|
||||
|
||||
expect(result.exitCode).toBe(0);
|
||||
expect(readBundledClaudeCodeVersion).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("creates the ACP session on the in-sandbox workspace cwd for runner-backed remote runs", async () => {
|
||||
const root = await makeTempRoot("paperclip-claude-acp-remote-cwd-");
|
||||
const localCwd = path.join(root, "worktree");
|
||||
|
||||
@@ -58,6 +58,11 @@ import { buildLocalAdapterTestProbeEnv } from "./probe-env.js";
|
||||
import { detectClaudeLoginRequired, extractClaudeRetryNotBefore, isClaudeProviderQuotaError, parseClaudeStreamJson } from "./parse.js";
|
||||
import { buildClaudeProbePermissionArgs, claudeSandboxPermissionEnv } from "./permissions.js";
|
||||
import { ADAPTER_AUTH_MISSING_CHECK_CODE } from "./auth-check.js";
|
||||
import {
|
||||
claudeCliVersionAtLeast,
|
||||
minimumClaudeCliVersionForModel,
|
||||
readBundledClaudeCodeVersion,
|
||||
} from "./cli-capabilities.js";
|
||||
import { resolveClaudeModel, SANDBOX_INSTALL_COMMAND } from "../index.js";
|
||||
|
||||
const moduleDir = path.dirname(fileURLToPath(import.meta.url));
|
||||
@@ -431,6 +436,49 @@ export function mapClaudeAcpAuthErrorCode(
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Mirror the CLI lane's minimum-version check (`execute.ts`) for the Claude
|
||||
* Code bundled with the local ACP bridge. Without it an unsupported model
|
||||
* fails only as a generic terminal service failure. A remote target, a custom
|
||||
* agentCommand, or CLAUDE_CODE_EXECUTABLE brings its own Claude Code.
|
||||
*/
|
||||
async function bundledClaudeCodeVersionFailure(
|
||||
ctx: AdapterExecutionContext,
|
||||
config: Record<string, unknown>,
|
||||
target: ReturnType<typeof readAdapterExecutionTarget>,
|
||||
): Promise<AdapterExecutionResult | null> {
|
||||
const model = asString(config.model, "");
|
||||
const minimumCliVersion = minimumClaudeCliVersionForModel(model);
|
||||
if (
|
||||
!minimumCliVersion ||
|
||||
target?.kind === "remote" ||
|
||||
firstNonEmptyString(config.agentCommand) ||
|
||||
firstNonEmptyString(parseObject(config.env).CLAUDE_CODE_EXECUTABLE)
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
const bundledCliVersion = await readBundledClaudeCodeVersion();
|
||||
if (!bundledCliVersion || claudeCliVersionAtLeast(bundledCliVersion, minimumCliVersion)) return null;
|
||||
const errorMessage =
|
||||
`${model} requires Claude Code ${minimumCliVersion} or newer; the ACP lane runs the bundled Claude Code ${bundledCliVersion}. ` +
|
||||
"Set CLAUDE_CODE_EXECUTABLE in the agent env to a newer Claude Code, or set engine=cli, before retrying.";
|
||||
await ctx.onLog("stderr", `[paperclip] ${errorMessage}\n`);
|
||||
return {
|
||||
exitCode: 1,
|
||||
signal: null,
|
||||
timedOut: false,
|
||||
errorMessage,
|
||||
errorCode: "claude_cli_version_incompatible",
|
||||
...resolveClaudeAcpBillingIdentity(ctx),
|
||||
model,
|
||||
resultJson: {
|
||||
stopReason: "claude_cli_version_incompatible",
|
||||
requiredClaudeCodeVersion: minimumCliVersion,
|
||||
detectedClaudeCodeVersion: bundledCliVersion,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export function createClaudeAcpExecutor(options: ClaudeAcpExecutorOptions = {}): ClaudeAcpExecutor {
|
||||
let executor: ClaudeAcpExecutor | null = null;
|
||||
return async (ctx) => {
|
||||
@@ -444,10 +492,10 @@ export function createClaudeAcpExecutor(options: ClaudeAcpExecutorOptions = {}):
|
||||
executionTarget: ctx.executionTarget,
|
||||
legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
|
||||
});
|
||||
const result = await currentExecutor({
|
||||
...ctx,
|
||||
config: buildClaudeAcpConfig(ctx.config, target?.kind === "remote" ? {} : process.env),
|
||||
});
|
||||
const config = buildClaudeAcpConfig(ctx.config, target?.kind === "remote" ? {} : process.env);
|
||||
const versionFailure = await bundledClaudeCodeVersionFailure(ctx, config, target);
|
||||
if (versionFailure) return versionFailure;
|
||||
const result = await currentExecutor({ ...ctx, config });
|
||||
return mapClaudeAcpAuthErrorCode(result);
|
||||
};
|
||||
}
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
import type { AdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
|
||||
import { runAdapterExecutionTargetProcess } from "@paperclipai/adapter-utils/execution-target";
|
||||
import fs from "node:fs/promises";
|
||||
import { createRequire } from "node:module";
|
||||
import path from "node:path";
|
||||
|
||||
const effortFlagSupportCache = new Map<string, Promise<boolean | null>>();
|
||||
@@ -36,7 +38,7 @@ function cacheKeyForTarget(command: string, target: AdapterExecutionTarget | nul
|
||||
}
|
||||
|
||||
export function minimumClaudeCliVersionForModel(model: string): string | null {
|
||||
const modelId = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global)\.)?anthropic\./, "");
|
||||
const modelId = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global|jp|au)\.)?anthropic\./, "");
|
||||
if (modelId === "claude-opus-5-5") return "2.1.280";
|
||||
if (modelId === "claude-sonnet-5-5") return "2.1.284";
|
||||
return modelId === "claude-fable-5-1"
|
||||
@@ -48,6 +50,26 @@ export function parseClaudeCliVersion(output: string): string | null {
|
||||
return output.match(/\b(\d+)\.(\d+)\.(\d+)\b/)?.[0] ?? null;
|
||||
}
|
||||
|
||||
/**
|
||||
* The Claude Code version bundled with the ACP bridge's SDK dependency, which
|
||||
* the bridge launches unless CLAUDE_CODE_EXECUTABLE is set. Resolved through
|
||||
* the bridge like `build-provider-pack.mjs`, so workspace overrides count.
|
||||
* `from` is where resolution starts; tests point it into an npm-style tree.
|
||||
*/
|
||||
export async function readBundledClaudeCodeVersion(from: string | URL = import.meta.url): Promise<string | null> {
|
||||
try {
|
||||
const acpRequire = createRequire(
|
||||
createRequire(from).resolve("@agentclientprotocol/claude-agent-acp/package.json"),
|
||||
);
|
||||
// The SDK does not export ./package.json; its entry sits at the package root.
|
||||
const sdkDir = path.dirname(acpRequire.resolve("@anthropic-ai/claude-agent-sdk"));
|
||||
const sdkPackage = JSON.parse(await fs.readFile(path.join(sdkDir, "package.json"), "utf8"));
|
||||
return parseClaudeCliVersion(String(sdkPackage.claudeCodeVersion ?? ""));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function claudeCliVersionAtLeast(version: string, minimum: string): boolean {
|
||||
const parsedVersion = version.split(".").map(Number);
|
||||
const parsedMinimum = minimum.split(".").map(Number);
|
||||
|
||||
Reference in new issue
Block a user