mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-21 16:27:18 +02:00
fix(runner): include Claude ACP in the server package (#15912)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The server ships a copy of Paperclip Runner for native agent execution. > - The Claude ACP bridge is a runner dependency, but it was absent from the server package. > - The runner resolves this bridge dynamically, so the import-based packaging check missed it. > - A Claude session then failed before startup and showed a generic connection error. > - This pull request ships the qualified bridge and reports a missing runtime with repair steps. ## Linked Issues or Issue Description **What happened?** A server install with the vendored runner could not load `@agentclientprotocol/claude-agent-acp/package.json`. The runtime test suggested checking the model or provider connection. The task reported an interrupted runner session. **Expected behavior** The server package includes its qualified Claude ACP runtime. A missing bundled runtime reports an installation error and explains how to repair it. **Steps to reproduce** 1. Use a server install with the vendored runner and no Claude ACP bridge. 2. Select the Paperclip Runner ACP harness and the Claude provider. 3. Run the runtime test or open a session. 4. Observe a missing-module failure before Claude starts. **Paperclip version or commit** Reproduced on `e733bddc45`. This branch is based on current master. **Deployment mode** Self-hosted server built from source. Related: #15224 upgrades the Claude bridge. This PR fixes its omission from the server package and keeps the current qualified version. A future bridge upgrade must update the server pin too. ## What Changed - Add Claude ACP `0.73.0` to the server dependencies and bundled dependencies. - Pin the qualified Claude SDK and bridge dependencies in the npm bundle producer graph. Publish its native packages as consumer optional dependencies instead of shipping the producer executable. - Bind source-built vendored runners to the shared pnpm dependency store while retaining the server manifest as the provider authority. Keep published npm and self-rooted deployment roots unchanged. - Include dynamically resolved Claude and Codex bridges in the vendor dependency check. - Preserve the missing-package category through the sidecar, Rust transport, and native session executor. Stop automatic retries for this installation failure. - Show **Runtime missing** in the runtime test and task thread. Explain the reinstall or rebuild, server restart, and runtime test steps. - Add regression tests and document the repair procedure. ## Verification - Red/green comparison with the production sidecar: the same missing-package setup returns a raw require-stack error on the original code and an actionable, non-retryable missing-runtime error on this branch. - The rebuilt server's vendored Claude installation probe passes using the source-server authority selected by the launcher, without starting a provider or making a model request. - Focused server verification: 830 tests passed. Runner installation and sidecar error tests: 83 passed, with 6 platform-specific skips. Packaging tests: 28 passed. Rust transport tests: 7 passed. - Source/deployment authority tests: 3 passed. Red/green packaging tests include a Linux-produced Claude SDK bundle, actual npm pack, and closed executable admission on Linux x64 and macOS ARM64/x64. - Full UI suite: 8,113 tests passed. - `pnpm -r typecheck` and `pnpm build` passed on the rebased branch. - Full current-head CI passed, including all general and serialized test lanes, Runner Rust/Vitest verification, typecheck, build, and all eight e2e shards. Greptile reviewed `d6a2741834ff922956560f2f689382827bbaf9e0` at 5/5 with no unresolved threads. - Local full-suite limitation: an earlier parallel attempt hit Postgres startup failures and timeouts; the affected server tests and a database fixture passed in isolation. The subsequent serial `pnpm test:run` was stopped while still running after complete CI passed. Focused local tests, full UI tests, typecheck, and build completed as listed above. - Token gates and `git diff --check` passed. ## Risks - Bundling the Claude bridge increases the server package size. The producer graph retains the qualified SDK version and existing isolation patch. Native platform declarations move to the published server manifest, while the runtime keeps its exact version, declared-slot, no-follow, and executable digest checks. - The new failure category is permanent. Operators must repair the server installation before they retry the task. - Existing failed runs retain their recorded error. The clearer message applies to new runtime tests and runs. - No database schema or migration changes. ## Model Used OpenAI GPT-6 through Codex. The system reports the model family; the exact deployment ID and context-window size are not exposed in this session. Used reasoning, browser inspection, tool use, and code execution. ## 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>
This commit is contained in:
DottaandPaperclip authored and GitHub committed
1 parent
1b4c803816
commit
db2f00947b
21 files changed
+471
-103
No files matched your search
@@ -1457,6 +1457,19 @@ Claude, which can reject unavailable models. Package/version verification is
|
||||
independent of model selection. Environment tests verify runtime installation;
|
||||
a successful provider run additionally verifies credentials and model access.
|
||||
|
||||
The server must install and bundle `@agentclientprotocol/claude-agent-acp`
|
||||
at the qualified version, including the patched bridge and pinned SDK. The
|
||||
vendor dependency check covers this dynamic lookup as well as ordinary imports.
|
||||
Source builds bind the vendored runner to the workspace's pnpm store while
|
||||
keeping the server manifest as its provider authority. Published npm bundles
|
||||
retain the pinned SDK JavaScript and declare its native packages as server
|
||||
optional dependencies, so npm installs the executable for the consumer's
|
||||
platform. Runtime admission still checks the exact version and executable digest.
|
||||
A missing provider package is reported as **Runtime missing**, with automatic
|
||||
retries stopped. Reinstall or rebuild Paperclip with its provider dependencies,
|
||||
restart the server, and run the agent's runtime test before retrying the task.
|
||||
Changing the model or signing in again cannot repair a missing runtime package.
|
||||
|
||||
ACPX Claude supports Linux x64 and macOS ARM64/x64 with pinned SDK executables.
|
||||
On macOS the launcher uses private verified module/executable snapshots instead
|
||||
of Linux `/proc` descriptors. Dependency isolation, process ownership, and
|
||||
|
||||
@@ -844,6 +844,7 @@ fn stderr_diagnostic_categories(value: &str) -> BTreeSet<&'static str> {
|
||||
|
||||
fn response_error_classification(error: &ResponseError) -> &'static str {
|
||||
match error.code.as_str() {
|
||||
"ACPX_RUNTIME_PACKAGE_MISSING" => return "runtime_package_missing",
|
||||
"ACP_MODEL_UNSUPPORTED" => return "requested_model_unsupported",
|
||||
"AGENT_STARTUP_FAILED" => return "agent_startup_failed",
|
||||
"AGENT_STARTUP_FAILED.UNVERIFIED_MODULE" => return "agent_startup_unverified_module",
|
||||
@@ -1038,6 +1039,7 @@ mod tests {
|
||||
#[test]
|
||||
fn candidate_auth_diagnostics_use_only_closed_codes_and_never_provider_text() {
|
||||
for (code, expected) in [
|
||||
("ACPX_RUNTIME_PACKAGE_MISSING", "runtime_package_missing"),
|
||||
("ACPX_TOOL_CALL_STALE", "provider_tool_call_retired"),
|
||||
("ACPX_TOOL_CALL_STALE_EXTRA", "unclassified"),
|
||||
("COPILOT_AUTH_REQUIRED", "authentication_required"),
|
||||
|
||||
@@ -186,3 +186,9 @@ describe("ACPX sidecar input sequencing", () => {
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
it("preserves a missing runtime package category across wrapped bootstrap errors", () => {
|
||||
const error = Object.assign(new Error("private resolver stack"), { code: "ACPX_RUNTIME_PACKAGE_MISSING" });
|
||||
expect(acpxSidecarErrorCode(new Error("bootstrap failed", { cause: error }))).toBe("ACPX_RUNTIME_PACKAGE_MISSING");
|
||||
expect(acpxSidecarErrorCode(acpxBootstrapBlockedError(error, "session.read")!)).toBe("ACPX_RUNTIME_PACKAGE_MISSING");
|
||||
});
|
||||
@@ -25,6 +25,7 @@ export function acpxBootstrapBlockedError(
|
||||
return failure
|
||||
? new Error(
|
||||
`ACPX provider bootstrap failed before ${command}: ${failure.message}`,
|
||||
{ cause: failure },
|
||||
)
|
||||
: null;
|
||||
}
|
||||
@@ -130,6 +131,7 @@ const GENERIC_ACPX_OUTPUT_CODES = new Set([
|
||||
]);
|
||||
|
||||
const STABLE_ACPX_SIDECAR_CODES = new Set([
|
||||
"ACPX_RUNTIME_PACKAGE_MISSING",
|
||||
"COPILOT_POLICY_VIOLATION",
|
||||
"COPILOT_DETACHED_WORK_UNSUPPORTED",
|
||||
"ACP_MODEL_UNSUPPORTED",
|
||||
|
||||
@@ -54,6 +54,77 @@ afterEach(async () => {
|
||||
});
|
||||
|
||||
describe("ACPX installation integrity", () => {
|
||||
it.each([["linux", "x64"], ["darwin", "arm64"], ["darwin", "x64"]] as const)(
|
||||
"retains Claude executable admission for a published bundle on %s %s", async (os, cpu) => {
|
||||
const parent = await realpath(await mkdtemp(join(tmpdir(), "paperclip-claude-npm-admission-")));
|
||||
temporaryDirectories.push(parent);
|
||||
const root = join(parent, "node_modules/@paperclipai/server");
|
||||
const bridge = join(root, "node_modules/@agentclientprotocol/claude-agent-acp");
|
||||
const runtime = join(bridge, "node_modules/@anthropic-ai/claude-agent-sdk");
|
||||
const name = `@anthropic-ai/claude-agent-sdk-${os}-${cpu}`;
|
||||
const platformRoot = join(parent, "node_modules", name);
|
||||
const optionalDependencies = { [name]: "0.3.286" };
|
||||
const runtimeMetadata = { name: "@anthropic-ai/claude-agent-sdk", version: "0.3.286" };
|
||||
const platformMetadata = { name, version: "0.3.286", os: [os], cpu: [cpu] };
|
||||
await Promise.all([mkdir(runtime, { recursive: true }), mkdir(platformRoot, { recursive: true })]);
|
||||
const command = 'process.stdout.write("unexecuted fixture");';
|
||||
const reset = () => Promise.all([
|
||||
writeFile(join(root, "package.json"), JSON.stringify({ name: "@paperclipai/server", optionalDependencies })),
|
||||
writeFile(join(runtime, "package.json"), JSON.stringify(runtimeMetadata)),
|
||||
writeFile(join(platformRoot, "package.json"), JSON.stringify(platformMetadata)),
|
||||
]);
|
||||
await reset();
|
||||
await Promise.all([
|
||||
writeFile(join(bridge, "package.json"), JSON.stringify({ name: "@agentclientprotocol/claude-agent-acp", version: "0.73.0", bin: "server.js" })),
|
||||
writeFile(join(bridge, "server.js"), command),
|
||||
writeFile(join(platformRoot, "claude"), "unqualified native bytes", { mode: 0o755 }),
|
||||
]);
|
||||
const profile = { ...resolveQualifiedAcpxProfile("claude", "claude-opus-5-5"), commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}` };
|
||||
const resolver = createAcpxPackageJsonResolver(root);
|
||||
expect(resolver(name, join(runtime, "package.json"))).toBe(join(platformRoot, "package.json"));
|
||||
expect(() => resolver(name)).toThrow("outside the selected provider root");
|
||||
for (const [file, metadata] of [
|
||||
[join(root, "package.json"), { name: "@paperclipai/server", optionalDependencies: { [name]: "latest" } }],
|
||||
[join(runtime, "package.json"), { ...runtimeMetadata, version: "0.3.285" }],
|
||||
[join(runtime, "package.json"), { ...runtimeMetadata, optionalDependencies: {} }],
|
||||
[join(platformRoot, "package.json"), { ...platformMetadata, name: "unqualified-provider" }],
|
||||
[join(platformRoot, "package.json"), { ...platformMetadata, version: "0.3.285" }],
|
||||
[join(platformRoot, "package.json"), { ...platformMetadata, cpu: ["ia32"] }],
|
||||
] as const) {
|
||||
await writeFile(file, JSON.stringify(metadata));
|
||||
expect(() => resolver(name, join(runtime, "package.json"))).toThrow("outside the selected provider root");
|
||||
await reset();
|
||||
}
|
||||
const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue(os);
|
||||
const archSpy = vi.spyOn(process, "arch", "get").mockReturnValue(cpu);
|
||||
try {
|
||||
await expect(verifyQualifiedAcpxInstallation(profile, (...args) => resolver(...args))).rejects.toThrow("runtime omitted its verified platform executable package");
|
||||
await expect(verifyQualifiedAcpxInstallation(profile, resolver)).rejects.toThrow(/digest mismatch/);
|
||||
vi.stubEnv("PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT", root);
|
||||
vi.stubEnv("PAPERCLIP_ACPX_PROVIDER_PACKAGE_MANIFEST", undefined);
|
||||
await expect(verifyQualifiedAcpxInstallation(profile)).rejects.toThrow(/digest mismatch/);
|
||||
} finally {
|
||||
vi.unstubAllEnvs();
|
||||
platformSpy.mockRestore();
|
||||
archSpy.mockRestore();
|
||||
}
|
||||
},
|
||||
);
|
||||
it("explains a missing Claude ACP installation without leaking the resolver stack", async () => {
|
||||
const missingPackage = Object.assign(new Error(
|
||||
"Cannot find module '@agentclientprotocol/claude-agent-acp/package.json'\nRequire stack: /srv/private/server.js",
|
||||
), { code: "MODULE_NOT_FOUND" });
|
||||
const error = await verifyQualifiedAcpxInstallation(
|
||||
resolveQualifiedAcpxProfile("claude", "claude-opus-5-5"),
|
||||
() => { throw missingPackage; },
|
||||
).catch(error => error);
|
||||
expect(error).toMatchObject({ code: "ACPX_RUNTIME_PACKAGE_MISSING" });
|
||||
expect(error.message).toContain("@agentclientprotocol/claude-agent-acp");
|
||||
expect(error.message).toContain("Reinstall or rebuild");
|
||||
expect(error.message).not.toContain("/srv/private");
|
||||
expect(error.message).not.toContain("Require stack");
|
||||
});
|
||||
|
||||
it.each([false, true])("admits only the declared qualified Codex platform in its npm-hoisted slot (published platform declaration: %s)", async (publishedDeclaration) => {
|
||||
const parent = await realpath(await mkdtemp(join(tmpdir(), "paperclip-codex-npm-hoist-")));
|
||||
temporaryDirectories.push(parent);
|
||||
|
||||
@@ -354,7 +354,7 @@ export function createAcpxPackageJsonResolver(
|
||||
resolvePackageJsonFromIssuer(packageName, canonicalIssuer),
|
||||
);
|
||||
if (!pathIsInside(canonicalNodeModules, packageJsonPath)
|
||||
&& !isDeclaredHoistedCodexPlatform(canonicalRoot, canonicalManifest, canonicalIssuer, packageName, packageJsonPath)) {
|
||||
&& !isDeclaredHoistedProviderPlatform(canonicalRoot, canonicalManifest, canonicalIssuer, packageName, packageJsonPath)) {
|
||||
throw new Error(
|
||||
`ACPX provider package ${packageName} resolves outside the selected provider root`,
|
||||
);
|
||||
@@ -365,25 +365,35 @@ export function createAcpxPackageJsonResolver(
|
||||
return resolver;
|
||||
}
|
||||
|
||||
function hasPublishedCodexPlatformDeclaration(resolver: AcpxPackageJsonResolver, runtimeManifest: string): boolean {
|
||||
function hasPublishedProviderPlatformDeclaration(
|
||||
resolver: AcpxPackageJsonResolver,
|
||||
runtimeManifest: string,
|
||||
qualified: { runtimePackageName: string; runtimePackageVersion: string; packageName: string; dependencyDeclaration: string },
|
||||
): boolean {
|
||||
const authority = rootedPackageResolvers.get(resolver);
|
||||
if (!authority || !pathIsInside(authority.root, runtimeManifest)) return false;
|
||||
const selected = readResolverPackageJson(authority.manifest);
|
||||
const runtime = readResolverPackageJson(runtimeManifest);
|
||||
const declarations = selected.optionalDependencies as Record<string, unknown> | undefined;
|
||||
return selected.name === "@paperclipai/server"
|
||||
&& runtime.name === QUALIFIED_CODEX_LINUX_X64_RUNTIME.runtimePackageName
|
||||
&& runtime.version === QUALIFIED_CODEX_LINUX_X64_RUNTIME.runtimePackageVersion
|
||||
&& runtime.name === qualified.runtimePackageName
|
||||
&& runtime.version === qualified.runtimePackageVersion
|
||||
&& runtime.optionalDependencies === undefined
|
||||
&& declarations?.[QUALIFIED_CODEX_LINUX_X64_RUNTIME.packageName] === QUALIFIED_CODEX_LINUX_X64_RUNTIME.dependencyDeclaration;
|
||||
&& declarations?.[qualified.packageName] === qualified.dependencyDeclaration;
|
||||
}
|
||||
|
||||
// npm installs an optional platform alias outside a bundled server graph.
|
||||
// Admit only the qualified executable package through its declared npm slot;
|
||||
// all executable bytes still pass the existing digest/no-follow admission.
|
||||
function isDeclaredHoistedCodexPlatform(root: string, manifest: string, issuer: string, packageName: string, packageJsonPath: string): boolean {
|
||||
const qualified = QUALIFIED_CODEX_LINUX_X64_RUNTIME;
|
||||
if (packageName !== qualified.packageName || issuer === manifest) return false;
|
||||
function isDeclaredHoistedProviderPlatform(root: string, manifest: string, issuer: string, packageName: string, packageJsonPath: string): boolean {
|
||||
const platformQualification = [
|
||||
{ qualified: QUALIFIED_CODEX_LINUX_X64_RUNTIME, os: "linux", cpu: "x64", alias: true },
|
||||
{ qualified: QUALIFIED_CLAUDE_LINUX_X64_RUNTIME, os: "linux", cpu: "x64", alias: false },
|
||||
{ qualified: QUALIFIED_CLAUDE_DARWIN_RUNTIMES.arm64, os: "darwin", cpu: "arm64", alias: false },
|
||||
{ qualified: QUALIFIED_CLAUDE_DARWIN_RUNTIMES.x64, os: "darwin", cpu: "x64", alias: false },
|
||||
].find(value => value.qualified.packageName === packageName);
|
||||
if (!platformQualification || issuer === manifest) return false;
|
||||
const { qualified, os, cpu, alias } = platformQualification;
|
||||
try {
|
||||
const selected = readResolverPackageJson(manifest);
|
||||
const runtime = readResolverPackageJson(issuer);
|
||||
@@ -404,10 +414,10 @@ function isDeclaredHoistedCodexPlatform(root: string, manifest: string, issuer:
|
||||
});
|
||||
if (!declaredSlot) return false;
|
||||
const platform = readResolverPackageJson(packageJsonPath);
|
||||
return (platform.name === qualified.packageName || platform.name === qualified.runtimePackageName)
|
||||
return (platform.name === qualified.packageName || (alias && platform.name === qualified.runtimePackageName))
|
||||
&& platform.version === qualified.packageVersion
|
||||
&& Array.isArray(platform.os) && platform.os.includes("linux")
|
||||
&& Array.isArray(platform.cpu) && platform.cpu.includes("x64");
|
||||
&& Array.isArray(platform.os) && platform.os.includes(os)
|
||||
&& Array.isArray(platform.cpu) && platform.cpu.includes(cpu);
|
||||
} catch { return false; }
|
||||
}
|
||||
|
||||
@@ -633,9 +643,9 @@ export async function verifyQualifiedAcpxInstallation(
|
||||
profile: QualifiedAcpxProfile,
|
||||
resolvePackageJson: AcpxPackageJsonResolver = defaultPackageJsonResolver,
|
||||
): Promise<VerifiedAcpxInstallation> {
|
||||
// Keep the selected package authority available when its bundled Codex
|
||||
// Keep the selected package authority available when its bundled provider
|
||||
// wrapper delegates platform installation to the published server manifest.
|
||||
if (profile.agent === "codex" && resolvePackageJson === defaultPackageJsonResolver && process.env.PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT !== undefined) {
|
||||
if ((profile.agent === "codex" || profile.agent === "claude") && resolvePackageJson === defaultPackageJsonResolver && process.env.PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT !== undefined) {
|
||||
resolvePackageJson = createAcpxPackageJsonResolver(
|
||||
process.env.PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT,
|
||||
process.env.PAPERCLIP_ACPX_PROVIDER_PACKAGE_MANIFEST,
|
||||
@@ -645,7 +655,22 @@ export async function verifyQualifiedAcpxInstallation(
|
||||
if (builtin && (profile.agentServerPackage !== "builtin:grok-acp" || profile.agentServerVersion !== "1" || profile.agentRuntimePackage !== "native:grok" || profile.agentRuntimeVersion !== "1.0.13")) {
|
||||
throw new Error("Grok builtin profile identity mismatch");
|
||||
}
|
||||
const serverPackageJsonPath = builtin ? null : await realpath(resolvePackageJson(profile.agentServerPackage));
|
||||
let serverPackageJsonPath: string | null = null;
|
||||
if (!builtin) {
|
||||
try {
|
||||
serverPackageJsonPath = await realpath(resolvePackageJson(profile.agentServerPackage));
|
||||
} catch (error) {
|
||||
if ((profile.agent === "claude" || profile.agent === "codex") &&
|
||||
error instanceof Error && "code" in error &&
|
||||
(error.code === "MODULE_NOT_FOUND" || error.code === "ERR_MODULE_NOT_FOUND")) {
|
||||
throw Object.assign(new Error(
|
||||
`The ACPX ${profile.agent} runtime is incomplete: required package ${profile.agentServerPackage} is missing. ` +
|
||||
"Reinstall or rebuild Paperclip with its bundled provider dependencies, restart the server, then test the agent's runtime before retrying.",
|
||||
), { code: "ACPX_RUNTIME_PACKAGE_MISSING" });
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
const serverPackage: AcpxPackageMetadata = builtin
|
||||
? { version: "1", bin: "launcher.cjs", type: "commonjs" }
|
||||
: await readPackageJson(serverPackageJsonPath!, profile.agentServerPackage);
|
||||
@@ -1019,8 +1044,8 @@ async function verifyQualifiedRuntimeExecutable(input: {
|
||||
const ownDeclaration = typeof optionalDependencies === "object"
|
||||
&& optionalDependencies !== null && !Array.isArray(optionalDependencies)
|
||||
&& (optionalDependencies as Record<string, unknown>)[qualification.packageName] === qualification.dependencyDeclaration;
|
||||
const publishedDeclaration = input.profile.agent === "codex" && optionalDependencies === undefined
|
||||
&& hasPublishedCodexPlatformDeclaration(input.resolvePackageJson, input.runtimePackageJsonPath);
|
||||
const publishedDeclaration = optionalDependencies === undefined
|
||||
&& hasPublishedProviderPlatformDeclaration(input.resolvePackageJson, input.runtimePackageJsonPath, qualification);
|
||||
if (!ownDeclaration && !publishedDeclaration) {
|
||||
throw new Error(
|
||||
`ACPX ${input.profile.agent} runtime omitted its verified platform executable package`,
|
||||
|
||||
@@ -1633,6 +1633,23 @@ it("uses the public server npm package as the authority for vendored sidecars",
|
||||
});
|
||||
});
|
||||
|
||||
it.each([false, true])("binds a vendored source server to its pnpm dependency root (self-rooted: %s)", async selfRooted => {
|
||||
const workspace = await mkdtemp(join(tmpdir(), "paperclip-vendored-source-"));
|
||||
const server = join(workspace, "server");
|
||||
await mkdir(join(workspace, "node_modules", ".pnpm"), { recursive: true });
|
||||
await mkdir(join(server, "node_modules", ...(selfRooted ? [".pnpm"] : [])), { recursive: true });
|
||||
await writeFile(join(workspace, "package.json"), JSON.stringify({ name: "paperclip", private: true }));
|
||||
await writeFile(join(workspace, "pnpm-workspace.yaml"), "packages:\n - server\n");
|
||||
await writeFile(join(server, "package.json"), JSON.stringify({ name: "@paperclipai/server" }));
|
||||
try {
|
||||
expect(runnerdLaunchProfileInternals.acpxProviderPackageAuthority(
|
||||
join(server, "dist/vendor/paperclip-runner/cli/acpx-runtime-sidecar.cjs"),
|
||||
)).toEqual({ root: selfRooted ? server : workspace, manifest: join(server, "package.json") });
|
||||
} finally {
|
||||
await rm(workspace, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it("keeps a self-rooted pnpm deployment inside its dependency authority", async () => {
|
||||
const deploymentRoot = await mkdtemp(
|
||||
join(tmpdir(), "paperclip-deployed-provider-root-"),
|
||||
|
||||
@@ -3030,6 +3030,20 @@ function acpxProviderPackageAuthority(
|
||||
basename(resolve(cliDirectory, "../..")) === "vendor" &&
|
||||
basename(resolve(cliDirectory, "../../..")) === "dist") {
|
||||
const serverRoot = resolve(cliDirectory, "../../../..");
|
||||
const workspaceRoot = dirname(serverRoot);
|
||||
// Source/Docker builds share the workspace's pnpm store. Published npm
|
||||
// bundles and self-rooted pnpm deployments retain their server authority.
|
||||
if (basename(serverRoot) === "server" &&
|
||||
!existsSync(resolve(serverRoot, "node_modules/.pnpm")) &&
|
||||
existsSync(resolve(workspaceRoot, "node_modules/.pnpm")) &&
|
||||
existsSync(resolve(workspaceRoot, "pnpm-workspace.yaml")) &&
|
||||
existsSync(resolve(workspaceRoot, "package.json"))) {
|
||||
const workspace = JSON.parse(readFileSync(resolve(workspaceRoot, "package.json"), "utf8"));
|
||||
const server = JSON.parse(readFileSync(resolve(serverRoot, "package.json"), "utf8"));
|
||||
if (workspace.name === "paperclip" && workspace.private === true && server.name === "@paperclipai/server") {
|
||||
return { root: workspaceRoot, manifest: resolve(serverRoot, "package.json") };
|
||||
}
|
||||
}
|
||||
return { root: serverRoot, manifest: resolve(serverRoot, "package.json") };
|
||||
}
|
||||
if (
|
||||
|
||||
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
|
||||
import { execFileSync } from "node:child_process";
|
||||
import {
|
||||
existsSync,
|
||||
cpSync,
|
||||
lstatSync,
|
||||
mkdirSync,
|
||||
mkdtempSync,
|
||||
@@ -56,6 +57,33 @@ function esbuildFixture(t) {
|
||||
}
|
||||
const codexTargets = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64", "win32-arm64"];
|
||||
const codexOptional = Object.fromEntries(codexTargets.map(target => [`@openai/codex-${target}`, `npm:@openai/codex@0.160.0-${target}`]));
|
||||
const claudeTargets = [...codexTargets, "linux-x64-musl", "linux-arm64-musl"];
|
||||
const claudeOptional = Object.fromEntries(claudeTargets.map(target => [`@anthropic-ai/claude-agent-sdk-${target}`, "0.3.286"]));
|
||||
function claudeFixture(t) {
|
||||
const directory = realpathSync(mkdtempSync(join(tmpdir(), "paperclip-bundled-claude-")));
|
||||
t.after(() => rmSync(directory, { recursive: true, force: true }));
|
||||
const graph = join(directory, "node_modules");
|
||||
const writePackage = (location, metadata) => {
|
||||
mkdirSync(location, { recursive: true });
|
||||
writeFileSync(join(location, "package.json"), JSON.stringify(metadata));
|
||||
return location;
|
||||
};
|
||||
const bridge = writePackage(join(graph, "@agentclientprotocol/claude-agent-acp"), {
|
||||
name: "@agentclientprotocol/claude-agent-acp", version: "0.73.0", dependencies: { "@anthropic-ai/claude-agent-sdk": "0.3.286" },
|
||||
});
|
||||
writeFileSync(join(bridge, "index.js"), "export {};\n");
|
||||
const runtime = writePackage(join(graph, "@anthropic-ai/claude-agent-sdk"), {
|
||||
name: "@anthropic-ai/claude-agent-sdk", version: "0.3.286", exports: { ".": "./sdk.mjs" }, optionalDependencies: claudeOptional,
|
||||
});
|
||||
writeFileSync(join(runtime, "sdk.mjs"), "// official JavaScript fixture, never executed\n");
|
||||
const producer = writePackage(join(graph, "@anthropic-ai/claude-agent-sdk-linux-x64"), {
|
||||
name: "@anthropic-ai/claude-agent-sdk-linux-x64", version: "0.3.286", os: ["linux"], cpu: ["x64"],
|
||||
});
|
||||
writeFileSync(join(producer, "claude"), "producer native fixture, never executed");
|
||||
const profiles = [{ agent: "claude", ...profileData.profiles.claude }];
|
||||
const publish = { name: "paperclip-claude-pack-fixture", version: "1.0.0", dependencies: { "@agentclientprotocol/claude-agent-acp": "0.73.0" }, bundleDependencies: ["@agentclientprotocol/claude-agent-acp"] };
|
||||
return { directory, graph, bridge, runtime, producer, profiles, publish, writePackage };
|
||||
}
|
||||
function codexFixture(t) {
|
||||
const directory = realpathSync(mkdtempSync(join(tmpdir(), "paperclip-bundled-codex-")));
|
||||
t.after(() => rmSync(directory, { recursive: true, force: true }));
|
||||
@@ -176,13 +204,26 @@ test("published packages preserve the patched ACPX runtime", () => {
|
||||
assert.equal(cliEsbuildConfig.external.includes("acpx"), false);
|
||||
});
|
||||
|
||||
test("published Claude bridge pins its qualified SDK and provider dependency closure", () => {
|
||||
const published = materializePublishManifest(serverPackage);
|
||||
const { installManifest } = configureBundledProviderOverrides(
|
||||
createBundledInstallManifest(published, serverPackage.bundleDependencies),
|
||||
serverPackage.bundleDependencies, rootPackage, profileData,
|
||||
);
|
||||
assert.deepEqual(installManifest.overrides["@agentclientprotocol/claude-agent-acp@0.73.0"], {
|
||||
"@anthropic-ai/claude-agent-sdk": "0.3.286",
|
||||
"@agentclientprotocol/sdk": "1.4.0",
|
||||
zod: "4.4.3",
|
||||
});
|
||||
});
|
||||
|
||||
test("published Codex bridge uses its qualified producer closure without consumer overrides", () => {
|
||||
const published = materializePublishManifest(serverPackage);
|
||||
const { installManifest, profiles } = configureBundledProviderOverrides(
|
||||
createBundledInstallManifest(published, serverPackage.bundleDependencies),
|
||||
serverPackage.bundleDependencies, rootPackage, profileData,
|
||||
);
|
||||
assert.equal(profiles.length, 1);
|
||||
assert.deepEqual(profiles.map(profile => profile.agent), ["codex", "claude"]);
|
||||
for (const profile of profiles) {
|
||||
assert.equal(published.dependencies[profile.agentServerPackage], profile.agentServerVersion);
|
||||
assert.ok(published.bundleDependencies.includes(profile.agentServerPackage));
|
||||
@@ -201,6 +242,58 @@ test("published Codex bridge uses its qualified producer closure without consume
|
||||
assert.throws(() => configureBundledProviderOverrides(conflict, serverPackage.bundleDependencies, rootPackage, profileData), /conflicting producer override/);
|
||||
});
|
||||
|
||||
test("Linux-produced Claude bundles retain the SDK and install native packages for the consumer platform", (t) => {
|
||||
const { directory, bridge, runtime, producer, profiles, publish } = claudeFixture(t);
|
||||
const bridgeBefore = readFileSync(join(bridge, "package.json"), "utf8");
|
||||
const staged = stageBundledProviderOptionalDependencies(directory, publish, profiles);
|
||||
assert.deepEqual(staged.optionalDependencies, claudeOptional);
|
||||
assert.equal(existsSync(producer), false);
|
||||
assert.equal(JSON.parse(readFileSync(join(runtime, "package.json"), "utf8")).optionalDependencies, undefined);
|
||||
assert.equal(readFileSync(join(bridge, "package.json"), "utf8"), bridgeBefore);
|
||||
assert.deepEqual(stageBundledProviderOptionalDependencies(directory, staged, profiles), staged);
|
||||
writeFileSync(join(directory, "package.json"), JSON.stringify(staged));
|
||||
const packs = JSON.parse(execFileSync("npm", ["pack", "--ignore-scripts", "--offline", "--json"], {
|
||||
cwd: directory, encoding: "utf8", timeout: 30_000,
|
||||
env: { ...process.env, HOME: directory, npm_config_cache: join(directory, "cache"), npm_config_update_notifier: "false" },
|
||||
}));
|
||||
const paths = packs[0].files.map(file => file.path);
|
||||
assert.ok(paths.some(path => path.endsWith("@anthropic-ai/claude-agent-sdk/sdk.mjs")));
|
||||
assert.equal(paths.some(path => /@anthropic-ai\/claude-agent-sdk-(?:linux|darwin|win32)-/.test(path)), false);
|
||||
});
|
||||
|
||||
test("Claude bundle validation rejects unqualified declarations before removing native payloads", (t) => {
|
||||
const { directory, runtime, producer, profiles, publish } = claudeFixture(t);
|
||||
const file = join(runtime, "package.json"), original = JSON.parse(readFileSync(file, "utf8"));
|
||||
for (const metadata of [
|
||||
{ ...original, version: "0.3.285" },
|
||||
{ ...original, optionalDependencies: { ...claudeOptional, "@anthropic-ai/claude-agent-sdk-darwin-arm64": "latest" } },
|
||||
{ ...original, optionalDependencies: {} },
|
||||
]) {
|
||||
writeFileSync(file, JSON.stringify(metadata));
|
||||
assert.throws(() => stageBundledProviderOptionalDependencies(directory, publish, profiles), /version mismatch|not qualified/);
|
||||
assert.equal(existsSync(producer), true);
|
||||
}
|
||||
});
|
||||
|
||||
test("mixed provider bundles validate both runtimes before removing either producer executable", (t) => {
|
||||
const codex = codexFixture(t), claude = claudeFixture(t);
|
||||
for (const name of ["@agentclientprotocol/claude-agent-acp", "@anthropic-ai/claude-agent-sdk", "@anthropic-ai/claude-agent-sdk-linux-x64"]) {
|
||||
cpSync(join(claude.graph, name), join(codex.graph, name), { recursive: true });
|
||||
}
|
||||
const profiles = [...codex.profiles, ...claude.profiles];
|
||||
const publish = { ...codex.publish, dependencies: { ...codex.publish.dependencies, ...claude.publish.dependencies },
|
||||
bundleDependencies: [...codex.publish.bundleDependencies, ...claude.publish.bundleDependencies] };
|
||||
const file = join(codex.graph, "@anthropic-ai/claude-agent-sdk/package.json");
|
||||
const metadata = JSON.parse(readFileSync(file, "utf8"));
|
||||
writeFileSync(file, JSON.stringify({ ...metadata, version: "0.3.285" }));
|
||||
assert.throws(() => stageBundledProviderOptionalDependencies(codex.directory, publish, profiles), /Claude runtime version mismatch/);
|
||||
assert.equal(existsSync(codex.producer), true);
|
||||
assert.deepEqual(JSON.parse(readFileSync(join(codex.runtime, "package.json"), "utf8")).optionalDependencies, codexOptional);
|
||||
writeFileSync(file, JSON.stringify(metadata));
|
||||
const staged = stageBundledProviderOptionalDependencies(codex.directory, publish, profiles);
|
||||
assert.deepEqual(staged.optionalDependencies, { ...codexOptional, ...claudeOptional });
|
||||
});
|
||||
|
||||
test("Codex bundles retain pinned JavaScript and delegate official consumer platform aliases without native payloads", (t) => {
|
||||
const { directory, graph, bridge, runtime, producer, nested, profiles, publish } = codexFixture(t);
|
||||
const before = [bridge, runtime].map(path => readFileSync(join(path, "package.json"), "utf8"));
|
||||
@@ -530,7 +623,7 @@ mkdir -p "$destination/node_modules/.pnpm"
|
||||
set -euo pipefail
|
||||
printf 'npm %s\\n' "$*" >> "$FAKE_CALL_LOG"
|
||||
[ "$*" = "install --omit=dev --ignore-scripts --no-audit --no-fund" ]
|
||||
node -e 'const fs = require("node:fs"); const pkg = require("./package.json"); if ("devDependencies" in pkg) process.exit(1); for (const [name, version] of Object.entries(pkg.dependencies)) { const dir = "node_modules/" + name; fs.mkdirSync(dir + "/dist", { recursive: true }); fs.writeFileSync(dir + "/package.json", JSON.stringify({ name, version })); } for (const [bridge, runtimes] of Object.entries(pkg.overrides ?? {})) { for (const [name, version] of Object.entries(runtimes)) { const dir = "node_modules/" + name; fs.mkdirSync(dir, { recursive: true }); const native = name === "@openai/codex"; const optionalDependencies = native ? Object.fromEntries(["linux-x64","linux-arm64","darwin-x64","darwin-arm64","win32-x64","win32-arm64"].map(target => [name+"-"+target,"npm:"+name+"@"+version+"-"+target])) : undefined; fs.writeFileSync(dir + "/package.json", JSON.stringify({ name, version, optionalDependencies })); } }'
|
||||
node -e 'const fs = require("node:fs"); const pkg = require("./package.json"); if ("devDependencies" in pkg) process.exit(1); for (const [name, version] of Object.entries(pkg.dependencies)) { const dir = "node_modules/" + name; fs.mkdirSync(dir + "/dist", { recursive: true }); fs.writeFileSync(dir + "/package.json", JSON.stringify({ name, version })); } for (const [bridge, runtimes] of Object.entries(pkg.overrides ?? {})) { for (const [name, version] of Object.entries(runtimes)) { const dir = "node_modules/" + name; fs.mkdirSync(dir, { recursive: true }); const native = name === "@openai/codex"; const targets = ["linux-x64","linux-arm64","darwin-x64","darwin-arm64","win32-x64","win32-arm64"]; const optionalDependencies = native ? Object.fromEntries(targets.map(target => [name+"-"+target,"npm:"+name+"@"+version+"-"+target])) : name === "@anthropic-ai/claude-agent-sdk" ? Object.fromEntries([...targets,"linux-x64-musl","linux-arm64-musl"].map(target => [name+"-"+target,version])) : undefined; fs.writeFileSync(dir + "/package.json", JSON.stringify({ name, version, optionalDependencies })); } }'
|
||||
node -e 'const fs=require("node:fs");fs.cpSync(process.env.FAKE_NATIVE_ARTIFACTS+"/@openai/codex-linux-x64","node_modules/@openai/codex-linux-x64",{recursive:true});fs.mkdirSync("node_modules/@openai/codex/vendor",{recursive:true});fs.writeFileSync("node_modules/@openai/codex/vendor/codex","producer fallback fixture");'
|
||||
mkdir -p node_modules/acpx/dist
|
||||
node -e 'const fs=require("node:fs");fs.mkdirSync("node_modules/esbuild",{recursive:true});fs.writeFileSync("node_modules/esbuild/package.json",JSON.stringify({name:"esbuild",version:"0.28.2",scripts:{postinstall:"node install.js"},optionalDependencies:Object.fromEntries(["linux-x64","darwin-arm64","darwin-x64"].map(target=>["@esbuild/"+target,"0.28.2"]))}));fs.mkdirSync("node_modules/@esbuild/linux-x64",{recursive:true});fs.writeFileSync("node_modules/@esbuild/linux-x64/package.json",JSON.stringify({name:"@esbuild/linux-x64",version:"0.28.2",os:["linux"],cpu:["x64"]}));'
|
||||
@@ -590,7 +683,7 @@ printf 'patched spawnEnvironment runtime\\n' > "$target/dist/runtime.js"
|
||||
assert.equal(lstatSync(stagedAcpxDir).isSymbolicLink(), false);
|
||||
assert.equal(existsSync(join(destinationDir, "node_modules/.pnpm")), false);
|
||||
const stagedManifest = JSON.parse(readFileSync(join(destinationDir, "package.json"), "utf8"));
|
||||
for (const [name, version] of Object.entries(codexOptional)) {
|
||||
for (const [name, version] of Object.entries({ ...codexOptional, ...claudeOptional })) {
|
||||
assert.equal(stagedManifest.optionalDependencies[name], version);
|
||||
assert.equal(existsSync(join(destinationDir, "node_modules", name)), false);
|
||||
assert.equal(stagedManifest.bundleDependencies.includes(name), false);
|
||||
|
||||
@@ -51,13 +51,14 @@ export function createBundledInstallManifest(publishManifest, bundledDependencie
|
||||
}
|
||||
|
||||
// npm consumers cannot inherit the workspace's pnpm overrides or patches.
|
||||
// Materialize the already-qualified Codex bridge closure in the tarball,
|
||||
// Materialize the already-qualified provider bridge closures in the tarball,
|
||||
// with overrides confined to the temporary, scripts-disabled producer graph.
|
||||
export function configureBundledProviderOverrides(installManifest, bundledDependencies, rootPackage, profileData) {
|
||||
const result = structuredClone(installManifest);
|
||||
const selected = [];
|
||||
for (const [agent, serverPackage, runtimePackage] of [
|
||||
["codex", "@agentclientprotocol/codex-acp", "@openai/codex"],
|
||||
["claude", "@agentclientprotocol/claude-agent-acp", "@anthropic-ai/claude-agent-sdk"],
|
||||
]) {
|
||||
if (!bundledDependencies.includes(serverPackage)) continue;
|
||||
const profile = profileData?.profiles?.[agent];
|
||||
@@ -75,7 +76,9 @@ export function configureBundledProviderOverrides(installManifest, bundledDepend
|
||||
if (result.overrides?.[npmSelector] !== undefined) {
|
||||
throw new Error(`Bundled ${agent} runtime has a conflicting producer override`);
|
||||
}
|
||||
const overrides = { [runtimePackage]: profile.agentRuntimeVersion };
|
||||
const overrides = { [runtimePackage]: profile.agentRuntimeVersion,
|
||||
...(agent === "claude" ? { "@agentclientprotocol/sdk": "1.4.0", zod: "4.4.3" } : {}),
|
||||
};
|
||||
result.overrides = { ...result.overrides, [npmSelector]: overrides };
|
||||
selected.push({ agent, ...profile });
|
||||
}
|
||||
@@ -87,88 +90,105 @@ const inside = (root, candidate) => {
|
||||
return value !== "" && value !== ".." && !value.startsWith(`..${sep}`) && !isAbsolute(value);
|
||||
};
|
||||
|
||||
// Bundle the pinned JavaScript closure, never the producer's Codex executable.
|
||||
// Bundle the pinned JavaScript closure, never the producer's executable.
|
||||
// npm installs the official optional package for the consumer's own platform.
|
||||
export function stageBundledProviderOptionalDependencies(destinationDir, publishManifest, profiles) {
|
||||
const graphRoot = resolve(destinationDir, "node_modules");
|
||||
if (realpathSync(graphRoot) !== graphRoot) throw new Error("Bundled Codex graph must be a canonical owned directory");
|
||||
const result = structuredClone(publishManifest), remove = new Set(), optional = {}, normalize = new Map();
|
||||
const profile = profiles.find(value => value.agent === "codex");
|
||||
if (profiles.length !== 1 || !profile) throw new Error("Bundled provider graph must contain its qualified Codex profile");
|
||||
const targets = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64", "win32-arm64"];
|
||||
const declarations = Object.fromEntries(targets.map(target => [`${profile.agentRuntimePackage}-${target}`,
|
||||
`npm:${profile.agentRuntimePackage}@${profile.agentRuntimeVersion}-${target}`]));
|
||||
const ownedDirectory = directory => {
|
||||
const stat = lstatSync(directory);
|
||||
if (!stat.isDirectory() || stat.isSymbolicLink() || !inside(graphRoot, realpathSync(directory))) {
|
||||
throw new Error("Bundled Codex dependency escapes its producer graph");
|
||||
}
|
||||
};
|
||||
const manifestAt = directory => {
|
||||
const path = resolve(directory, "package.json"), stat = lstatSync(path);
|
||||
if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 256 * 1024) {
|
||||
throw new Error("Bundled Codex dependency manifest must be a bounded regular file");
|
||||
}
|
||||
return JSON.parse(readFileSync(path, "utf8"));
|
||||
};
|
||||
const bridgeDirectory = resolve(graphRoot, profile.agentServerPackage);
|
||||
ownedDirectory(bridgeDirectory);
|
||||
const bridge = manifestAt(bridgeDirectory);
|
||||
if (bridge.name !== profile.agentServerPackage || bridge.version !== profile.agentServerVersion) throw new Error("Bundled Codex bridge version mismatch");
|
||||
const issuer = createRequire(resolve(bridgeDirectory, "package.json"));
|
||||
const runtimeManifest = realpathSync(issuer.resolve(`${profile.agentRuntimePackage}/package.json`));
|
||||
if (!inside(graphRoot, runtimeManifest)) throw new Error("Bundled Codex runtime escapes its producer graph");
|
||||
let runtimeCount = 0, packageCount = 0;
|
||||
const pending = [{ directory: graphRoot, depth: 0 }];
|
||||
while (pending.length) {
|
||||
const { directory, depth } = pending.pop();
|
||||
if (depth > 64) throw new Error("Bundled Codex graph exceeds its depth limit");
|
||||
const packages = [];
|
||||
for (const entry of readdirSync(directory)) {
|
||||
if (entry.startsWith(".")) continue;
|
||||
const candidate = resolve(directory, entry); ownedDirectory(candidate);
|
||||
if (entry.startsWith("@")) {
|
||||
for (const child of readdirSync(candidate)) {
|
||||
const scoped = resolve(candidate, child); ownedDirectory(scoped); packages.push(scoped);
|
||||
}
|
||||
} else packages.push(candidate);
|
||||
}
|
||||
for (const packageDirectory of packages) {
|
||||
if (++packageCount > 20_000) throw new Error("Bundled Codex graph exceeds its package limit");
|
||||
const metadata = manifestAt(packageDirectory);
|
||||
const binding = basename(dirname(packageDirectory)) === "@openai" ? `@openai/${basename(packageDirectory)}` : null;
|
||||
if (binding?.startsWith("@openai/codex-")) {
|
||||
const target = binding.slice("@openai/codex-".length), [os, cpu] = target.split("-");
|
||||
if (!Object.hasOwn(declarations, binding) || ![binding, profile.agentRuntimePackage].includes(metadata.name)
|
||||
|| metadata.version !== `${profile.agentRuntimeVersion}-${target}` || !metadata.os?.includes(os) || !metadata.cpu?.includes(cpu)) {
|
||||
throw new Error("Bundled Codex installed platform identity mismatch");
|
||||
}
|
||||
remove.add(packageDirectory);
|
||||
continue;
|
||||
}
|
||||
const nested = resolve(packageDirectory, "node_modules");
|
||||
if (lstatExists(nested)) { ownedDirectory(nested); pending.push({ directory: nested, depth: depth + 1 }); }
|
||||
if (binding !== profile.agentRuntimePackage) continue;
|
||||
if (metadata.name !== profile.agentRuntimePackage || metadata.version !== profile.agentRuntimeVersion) throw new Error("Bundled Codex runtime version mismatch");
|
||||
runtimeCount++;
|
||||
const delegated = metadata.optionalDependencies === undefined
|
||||
&& Object.entries(declarations).every(([name, specifier]) => result.optionalDependencies?.[name] === specifier);
|
||||
if (!delegated && (Object.keys(metadata.optionalDependencies ?? {}).length !== targets.length
|
||||
|| targets.some(target => metadata.optionalDependencies?.[`${profile.agentRuntimePackage}-${target}`] !== declarations[`${profile.agentRuntimePackage}-${target}`]))) {
|
||||
throw new Error("Bundled Codex platform declaration is not qualified");
|
||||
}
|
||||
if (!delegated) {
|
||||
const normalized = { ...metadata }; delete normalized.optionalDependencies;
|
||||
normalize.set(resolve(packageDirectory, "package.json"), normalized);
|
||||
}
|
||||
const vendor = resolve(packageDirectory, "vendor");
|
||||
if (lstatExists(vendor)) { ownedDirectory(vendor); remove.add(vendor); }
|
||||
}
|
||||
if (!profiles.length || new Set(profiles.map(profile => profile.agent)).size !== profiles.length) {
|
||||
throw new Error("Bundled provider graph must contain distinct qualified profiles");
|
||||
}
|
||||
if (!runtimeCount) throw new Error("Bundled Codex runtime omitted its platform declarations");
|
||||
for (const [name, specifier] of Object.entries(declarations)) {
|
||||
if (result.optionalDependencies?.[name] !== undefined && result.optionalDependencies[name] !== specifier) throw new Error(`Bundled Codex platform conflicts with published dependency: ${name}`);
|
||||
optional[name] = specifier;
|
||||
for (const profile of profiles) {
|
||||
const expected = profile.agent === "codex" ? ["@agentclientprotocol/codex-acp", "@openai/codex"]
|
||||
: profile.agent === "claude" ? ["@agentclientprotocol/claude-agent-acp", "@anthropic-ai/claude-agent-sdk"] : null;
|
||||
if (!expected || profile.agentServerPackage !== expected[0] || profile.agentRuntimePackage !== expected[1]) {
|
||||
throw new Error("Bundled provider graph contains an unknown provider profile");
|
||||
}
|
||||
const label = profile.agent === "codex" ? "Codex" : "Claude";
|
||||
const targets = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64", "win32-arm64",
|
||||
...(profile.agent === "claude" ? ["linux-x64-musl", "linux-arm64-musl"] : [])];
|
||||
const declarations = Object.fromEntries(targets.map(target => [`${profile.agentRuntimePackage}-${target}`,
|
||||
profile.agent === "codex" ? `npm:${profile.agentRuntimePackage}@${profile.agentRuntimeVersion}-${target}` : profile.agentRuntimeVersion]));
|
||||
const ownedDirectory = directory => {
|
||||
const stat = lstatSync(directory);
|
||||
if (!stat.isDirectory() || stat.isSymbolicLink() || !inside(graphRoot, realpathSync(directory))) {
|
||||
throw new Error(`Bundled ${label} dependency escapes its producer graph`);
|
||||
}
|
||||
};
|
||||
const manifestAt = directory => {
|
||||
const path = resolve(directory, "package.json"), stat = lstatSync(path);
|
||||
if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 256 * 1024) {
|
||||
throw new Error(`Bundled ${label} dependency manifest must be a bounded regular file`);
|
||||
}
|
||||
return JSON.parse(readFileSync(path, "utf8"));
|
||||
};
|
||||
const bridgeDirectory = resolve(graphRoot, profile.agentServerPackage);
|
||||
ownedDirectory(bridgeDirectory);
|
||||
const bridge = manifestAt(bridgeDirectory);
|
||||
if (bridge.name !== profile.agentServerPackage || bridge.version !== profile.agentServerVersion) throw new Error(`Bundled ${label} bridge version mismatch`);
|
||||
const issuer = createRequire(resolve(bridgeDirectory, "package.json"));
|
||||
let runtimeManifest;
|
||||
try { runtimeManifest = issuer.resolve(`${profile.agentRuntimePackage}/package.json`); }
|
||||
catch (error) {
|
||||
if (error.code !== "ERR_PACKAGE_PATH_NOT_EXPORTED") throw error;
|
||||
runtimeManifest = resolve(dirname(issuer.resolve(profile.agentRuntimePackage)), "package.json");
|
||||
}
|
||||
runtimeManifest = realpathSync(runtimeManifest);
|
||||
if (!inside(graphRoot, runtimeManifest)) throw new Error(`Bundled ${label} runtime escapes its producer graph`);
|
||||
let runtimeCount = 0, packageCount = 0;
|
||||
const pending = [{ directory: graphRoot, depth: 0 }];
|
||||
while (pending.length) {
|
||||
const { directory, depth } = pending.pop();
|
||||
if (depth > 64) throw new Error(`Bundled ${label} graph exceeds its depth limit`);
|
||||
const packages = [];
|
||||
for (const entry of readdirSync(directory)) {
|
||||
if (entry.startsWith(".")) continue;
|
||||
const candidate = resolve(directory, entry); ownedDirectory(candidate);
|
||||
if (entry.startsWith("@")) {
|
||||
for (const child of readdirSync(candidate)) {
|
||||
const scoped = resolve(candidate, child); ownedDirectory(scoped); packages.push(scoped);
|
||||
}
|
||||
} else packages.push(candidate);
|
||||
}
|
||||
for (const packageDirectory of packages) {
|
||||
if (++packageCount > 20_000) throw new Error(`Bundled ${label} graph exceeds its package limit`);
|
||||
const metadata = manifestAt(packageDirectory);
|
||||
const scope = basename(dirname(packageDirectory));
|
||||
const binding = scope.startsWith("@") ? `${scope}/${basename(packageDirectory)}` : basename(packageDirectory);
|
||||
if (binding.startsWith(`${profile.agentRuntimePackage}-`)) {
|
||||
const target = binding.slice(profile.agentRuntimePackage.length + 1), [os, cpu] = target.split("-");
|
||||
if (!Object.hasOwn(declarations, binding) || !(metadata.name === binding || (profile.agent === "codex" && metadata.name === profile.agentRuntimePackage))
|
||||
|| metadata.version !== (profile.agent === "codex" ? `${profile.agentRuntimeVersion}-${target}` : profile.agentRuntimeVersion) || !metadata.os?.includes(os) || !metadata.cpu?.includes(cpu)) {
|
||||
throw new Error(`Bundled ${label} installed platform identity mismatch`);
|
||||
}
|
||||
remove.add(packageDirectory);
|
||||
continue;
|
||||
}
|
||||
const nested = resolve(packageDirectory, "node_modules");
|
||||
if (lstatExists(nested)) { ownedDirectory(nested); pending.push({ directory: nested, depth: depth + 1 }); }
|
||||
if (binding !== profile.agentRuntimePackage) continue;
|
||||
if (metadata.name !== profile.agentRuntimePackage || metadata.version !== profile.agentRuntimeVersion) throw new Error(`Bundled ${label} runtime version mismatch`);
|
||||
runtimeCount++;
|
||||
const delegated = metadata.optionalDependencies === undefined
|
||||
&& Object.entries(declarations).every(([name, specifier]) => result.optionalDependencies?.[name] === specifier);
|
||||
if (!delegated && (Object.keys(metadata.optionalDependencies ?? {}).length !== targets.length
|
||||
|| targets.some(target => metadata.optionalDependencies?.[`${profile.agentRuntimePackage}-${target}`] !== declarations[`${profile.agentRuntimePackage}-${target}`]))) {
|
||||
throw new Error(`Bundled ${label} platform declaration is not qualified`);
|
||||
}
|
||||
if (!delegated) {
|
||||
const normalized = { ...metadata }; delete normalized.optionalDependencies;
|
||||
normalize.set(resolve(packageDirectory, "package.json"), normalized);
|
||||
}
|
||||
const vendor = resolve(packageDirectory, "vendor");
|
||||
if (profile.agent === "codex" && lstatExists(vendor)) { ownedDirectory(vendor); remove.add(vendor); }
|
||||
}
|
||||
}
|
||||
if (!runtimeCount) throw new Error(`Bundled ${label} runtime omitted its platform declarations`);
|
||||
for (const [name, specifier] of Object.entries(declarations)) {
|
||||
if (result.optionalDependencies?.[name] !== undefined && result.optionalDependencies[name] !== specifier) throw new Error(`Bundled ${label} platform conflicts with published dependency: ${name}`);
|
||||
optional[name] = specifier;
|
||||
}
|
||||
}
|
||||
// A bundled wrapper's optional edges make npm treat missing platform slots
|
||||
// as bundled too. Delegate those exact declarations to the unbundled server
|
||||
@@ -178,7 +198,7 @@ export function stageBundledProviderOptionalDependencies(destinationDir, publish
|
||||
for (const directory of remove) rmSync(directory, { recursive: true, force: true });
|
||||
result.optionalDependencies = { ...result.optionalDependencies, ...optional };
|
||||
for (const field of ["bundleDependencies", "bundledDependencies"]) {
|
||||
if (Array.isArray(result[field])) result[field] = result[field].filter(name => !Object.hasOwn(declarations, name));
|
||||
if (Array.isArray(result[field])) result[field] = result[field].filter(name => !Object.hasOwn(optional, name));
|
||||
}
|
||||
delete result.paperclipProviderArtifacts;
|
||||
return result;
|
||||
|
||||
@@ -44,6 +44,7 @@
|
||||
"typecheck": "pnpm run prepare:runner-vendor && pnpm --filter @paperclipai/plugin-sdk ensure-build-deps && tsc --noEmit"
|
||||
},
|
||||
"dependencies": {
|
||||
"@agentclientprotocol/claude-agent-acp": "0.73.0",
|
||||
"@agentclientprotocol/codex-acp": "1.6.2",
|
||||
"@ai-sdk/amazon-bedrock": "5.0.113",
|
||||
"@ai-sdk/anthropic": "4.0.78",
|
||||
@@ -113,6 +114,7 @@
|
||||
"zod": "^4.4.3"
|
||||
},
|
||||
"bundleDependencies": [
|
||||
"@agentclientprotocol/claude-agent-acp",
|
||||
"@agentclientprotocol/codex-acp",
|
||||
"@chat-adapter/discord",
|
||||
"@chat-adapter/github",
|
||||
|
||||
@@ -100,6 +100,21 @@ export async function findRunnerExternalPackages(entryPoints) {
|
||||
return externalPackageNames;
|
||||
}
|
||||
|
||||
// Provider entrypoints are resolved with createRequire from profile metadata,
|
||||
// so esbuild cannot see them. These two bridges ship in the server package;
|
||||
// other ACP agents use separately provisioned provider packs.
|
||||
export async function findRunnerRuntimePackages(entryPoints, profileData) {
|
||||
const packages = await findRunnerExternalPackages(entryPoints);
|
||||
for (const agent of ["claude", "codex"]) {
|
||||
const profile = profileData?.profiles?.[agent];
|
||||
if (profileData?.schema !== "paperclip.acpx-profiles.v1" || !profile?.agentServerPackage) {
|
||||
throw new Error(`paperclip-runner vendor check: missing ${agent} provider profile.`);
|
||||
}
|
||||
packages.add(profile.agentServerPackage);
|
||||
}
|
||||
return packages;
|
||||
}
|
||||
|
||||
function readDependencyNames(packageJsonPath) {
|
||||
const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
|
||||
return new Map(Object.entries(packageJson.dependencies ?? {}));
|
||||
@@ -125,7 +140,8 @@ function explainMissingDependencies(missing, runnerDependencyNames) {
|
||||
|
||||
async function main() {
|
||||
const entryPoints = ENTRY_POINT_NAMES.map((name) => resolve(runnerDist, name));
|
||||
const externalPackageNames = await findRunnerExternalPackages(entryPoints);
|
||||
const profileData = JSON.parse(readFileSync(resolve(runnerRoot, "acpx-profiles.json"), "utf8"));
|
||||
const externalPackageNames = await findRunnerRuntimePackages(entryPoints, profileData);
|
||||
const serverDependencyNames = readDependencyNames(resolve(serverRoot, "package.json"));
|
||||
|
||||
const missing = findMissingVendorDependencies(
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
|
||||
@@ -7,6 +7,7 @@ import { afterEach, describe, expect, it } from "vitest";
|
||||
import {
|
||||
findMissingVendorDependencies,
|
||||
findRunnerExternalPackages,
|
||||
findRunnerRuntimePackages,
|
||||
} from "./verify-runner-vendor-dependencies.mjs";
|
||||
|
||||
describe("findMissingVendorDependencies", () => {
|
||||
@@ -87,6 +88,15 @@ describe("findRunnerExternalPackages", () => {
|
||||
expect(externalPackageNames).toEqual(new Set(["smol-toml"]));
|
||||
});
|
||||
|
||||
it("checks dynamically resolved bundled providers even without a JavaScript import", async () => {
|
||||
const entryPoints = writeFixture();
|
||||
const profiles = JSON.parse(readFileSync(new URL("../../packages/paperclip-runner/acpx-profiles.json", import.meta.url), "utf8"));
|
||||
const packages = await findRunnerRuntimePackages(entryPoints, profiles);
|
||||
expect(findMissingVendorDependencies(packages, new Set(["smol-toml", "@agentclientprotocol/codex-acp"])))
|
||||
.toEqual(["@agentclientprotocol/claude-agent-acp"]);
|
||||
expect(packages.has("pi-acp")).toBe(false);
|
||||
});
|
||||
|
||||
it("throws a clear, actionable error when an entry point is missing", async () => {
|
||||
fixtureDir = mkdtempSync(join(tmpdir(), "paperclip-runner-vendor-fixture-"));
|
||||
const missingEntryPoint = join(fixtureDir, "index.js");
|
||||
@@ -96,3 +106,12 @@ describe("findRunnerExternalPackages", () => {
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
// Claude is resolved through createRequire at runtime, outside esbuild's graph.
|
||||
it("ships the qualified Claude ACP server with the vendored runner", () => {
|
||||
const server = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
|
||||
const profiles = JSON.parse(readFileSync(new URL("../../packages/paperclip-runner/acpx-profiles.json", import.meta.url), "utf8"));
|
||||
const claude = profiles.profiles.claude;
|
||||
expect(server.dependencies[claude.agentServerPackage]).toBe(claude.agentServerVersion);
|
||||
expect(server.bundleDependencies).toContain(claude.agentServerPackage);
|
||||
});
|
||||
@@ -118,6 +118,13 @@ describe("native ACPX environment checks", () => {
|
||||
})]);
|
||||
});
|
||||
|
||||
it("identifies an incomplete installation and gives the operator a repair", async () => {
|
||||
probeInstallation.mockRejectedValue(Object.assign(new Error("The Claude ACP runtime package is missing. Reinstall or rebuild Paperclip."), { code: "ACPX_RUNTIME_PACKAGE_MISSING" }));
|
||||
const result = await requireServerAdapter("paperclip_runner").testEnvironment!(context);
|
||||
expect(result.status).toBe("fail");
|
||||
expect(result.checks[0]).toMatchObject({ code: "acpx_runtime_package_missing", message: expect.stringContaining("Reinstall or rebuild") });
|
||||
});
|
||||
|
||||
it("requires a successful installed runtime probe", async () => {
|
||||
const result = await requireServerAdapter("paperclip_runner").testEnvironment!(context);
|
||||
expect(result.status).toBe("pass");
|
||||
|
||||
@@ -447,7 +447,12 @@ const paperclipRunnerAdapter: ServerAdapterModule = {
|
||||
} catch (error) {
|
||||
return {
|
||||
adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(),
|
||||
checks: [{ code: "acpx_runtime_unavailable", level: "error" as const, message: error instanceof Error ? error.message : "ACPX Claude runtime could not be verified." }],
|
||||
checks: [{
|
||||
code: error instanceof Error && "code" in error && error.code === "ACPX_RUNTIME_PACKAGE_MISSING"
|
||||
? "acpx_runtime_package_missing" : "acpx_runtime_unavailable",
|
||||
level: "error" as const,
|
||||
message: error instanceof Error ? error.message : "The ACPX runtime could not be verified.",
|
||||
}],
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
@@ -13156,3 +13156,10 @@ it.each([
|
||||
),
|
||||
).toBe("native_event_replay_conflict");
|
||||
});
|
||||
|
||||
it("keeps an ACPX missing runtime package failure actionable and stops automatic retries", () => {
|
||||
const failure = new Error('PRP command session.open failed: {"result":{"code":"command_execution_failed","message":"failed to start ACPX provider: ACPX sidecar command session.open was rejected (retryable=false, classification=runtime_package_missing)"},"status":"failed"}');
|
||||
const code = nativeSessionFailureSourceCode(failure);
|
||||
expect(code).toBe("native_provider_runtime_missing");
|
||||
expect(nativeSessionFailureDisposition(1, new Date(), code)).toEqual({ phase: "terminal_failure", failureCode: code, nextAttemptAt: null });
|
||||
});
|
||||
@@ -6198,6 +6198,7 @@ export function nativeSessionFailureDisposition(
|
||||
sourceFailureCode?: ReturnType<typeof nativeSessionFailureSourceCode>,
|
||||
) {
|
||||
const permanentFailure =
|
||||
sourceFailureCode === "native_provider_runtime_missing" ||
|
||||
sourceFailureCode === "native_provider_model_rejected" ||
|
||||
sourceFailureCode === "native_provider_approval_required" ||
|
||||
sourceFailureCode === "native_event_replay_conflict" ||
|
||||
@@ -6271,6 +6272,7 @@ export function nativeSessionFailureSourceCode(
|
||||
| "native_runner_process_exited"
|
||||
| "planning_mode_unsupported"
|
||||
| "native_event_replay_conflict"
|
||||
| "native_provider_runtime_missing"
|
||||
| "native_provider_model_rejected"
|
||||
| "native_current_wake_comments_unread"
|
||||
| "native_current_wake_comments_changed_after_read"
|
||||
@@ -6293,6 +6295,8 @@ export function nativeSessionFailureSourceCode(
|
||||
if (error instanceof NativeSessionCleanupQuarantinedError)
|
||||
return "native_session_cleanup_quarantined";
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
if (/classification=runtime_package_missing\)/.test(message))
|
||||
return "native_provider_runtime_missing";
|
||||
if (/native_provider_model_rejected/i.test(message))
|
||||
return "native_provider_model_rejected";
|
||||
if (/native_adopted_runner_authentication_timeout/i.test(message)) {
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import { flushSync } from "react-dom";
|
||||
import { createRoot } from "react-dom/client";
|
||||
import { expect, it } from "vitest";
|
||||
import { RuntimeTestCard } from "./RuntimeTestCard";
|
||||
|
||||
it("shows the installation repair directly on a missing runtime test", () => {
|
||||
const container = document.createElement("div");
|
||||
const root = createRoot(container);
|
||||
const message = "The ACPX claude runtime is incomplete: required package @agentclientprotocol/claude-agent-acp is missing. Reinstall or rebuild Paperclip with its bundled provider dependencies, restart the server, then test the agent's runtime before retrying.";
|
||||
try {
|
||||
flushSync(() => root.render(<RuntimeTestCard state="fail" onTest={() => {}} result={{
|
||||
adapterType: "paperclip_runner", status: "fail", testedAt: "2026-10-11T11:19:14Z",
|
||||
checks: [{ code: "acpx_runtime_package_missing", level: "error", message }],
|
||||
}} />));
|
||||
expect(container.querySelector('[role="alert"]')?.textContent).toContain("Runtime missing");
|
||||
expect(container.querySelector('[role="alert"]')?.textContent).toContain(message);
|
||||
expect(container.textContent).not.toContain("Check your model and provider connection");
|
||||
} finally {
|
||||
flushSync(() => root.unmount());
|
||||
}
|
||||
});
|
||||
@@ -61,7 +61,12 @@ export function RuntimeTestCard({
|
||||
disabled?: boolean;
|
||||
variant?: "connection" | "prerequisites";
|
||||
}) {
|
||||
const content = (variant === "prerequisites" ? prerequisiteCopy : copy)[state];
|
||||
const missingRuntime = state === "fail"
|
||||
? result?.checks.find(check => check.code === "acpx_runtime_package_missing")
|
||||
: undefined;
|
||||
const content = missingRuntime
|
||||
? { ...copy.fail, title: "Runtime missing", description: missingRuntime.message }
|
||||
: (variant === "prerequisites" ? prerequisiteCopy : copy)[state];
|
||||
const Icon =
|
||||
state === "running"
|
||||
? Loader2
|
||||
|
||||
@@ -4658,3 +4658,16 @@ describe("TaskChatThread composer execution controls", () => {
|
||||
expect(container.querySelector('[data-testid="task-chat-composer-stop"]')).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
it("explains a missing provider runtime with an installation repair", () => {
|
||||
render(<TaskChatThread comments={[]} onAdd={async () => {}} linkedRuns={[{
|
||||
runId: "missing-runtime", runtimeMode: "native", status: "failed", errorCode: "native_provider_runtime_missing",
|
||||
agentId: "agent-1", agentName: "Content Strategist", adapterType: "paperclip_runner",
|
||||
createdAt: "2026-10-11T11:19:08Z", startedAt: "2026-10-11T11:19:08Z", finishedAt: "2026-10-11T11:19:14Z",
|
||||
}]} />);
|
||||
expect(container.textContent).toContain("Runtime missing");
|
||||
const toggle = container.querySelector<HTMLButtonElement>('[data-testid="task-chat-collapsible-marker"] button[aria-expanded]')!;
|
||||
flushSync(() => toggle.click());
|
||||
expect(container.textContent).toContain("Reinstall or rebuild Paperclip");
|
||||
expect(container.textContent).toContain("test the agent's runtime");
|
||||
});
|
||||
@@ -1646,7 +1646,9 @@ export function TaskChatThread(props: TaskChatThreadProps) {
|
||||
? "native_runner_timed_out"
|
||||
: "native_runner_process_exited");
|
||||
const label =
|
||||
code === "native_provider_model_rejected" && source.status === "failed"
|
||||
code === "native_provider_runtime_missing" && source.status === "failed"
|
||||
? "Runtime missing"
|
||||
: code === "native_provider_model_rejected" && source.status === "failed"
|
||||
? "Model unavailable"
|
||||
: code === "native_provider_approval_required" && source.status === "failed"
|
||||
? "Approval required"
|
||||
@@ -1667,6 +1669,8 @@ export function TaskChatThread(props: TaskChatThreadProps) {
|
||||
? `The run was cancelled${responseBoundary}.`
|
||||
: source.status === "interrupted"
|
||||
? `The run was interrupted${responseBoundary}.`
|
||||
: code === "native_provider_runtime_missing"
|
||||
? "The selected provider runtime is missing a required package. Reinstall or rebuild Paperclip with its bundled provider dependencies, restart the server, then test the agent's runtime before retrying."
|
||||
: code === "native_provider_approval_required"
|
||||
? "This operation requires approval, but this runner has no interactive approval handler. Review the operation and update the agent's permission setting before retrying."
|
||||
: code === "native_provider_model_rejected"
|
||||
|
||||
Reference in new issue
Block a user