The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(runner): include Claude ACP in the server package (#15912)
Dottadb2f00947b08
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex 6fc8fa4f26..ae811577a1 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -1457,6 +1457,19 @@ Claude, which can reject unavailable models. Package/version verification isindependent 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 insteadof Linux `/proc` descriptors. Dependency isolation, process ownership, anddiff --git a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_sidecar_transport.rs b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_sidecar_transport.rsindex 331f6ed17f..ff99355038 100644--- a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_sidecar_transport.rs+++ b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_sidecar_transport.rs@@ -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"),diff --git a/packages/paperclip-runner/src/cli/acpx-sidecar-input.test.ts b/packages/paperclip-runner/src/cli/acpx-sidecar-input.test.tsindex 12c80c4922..0b6a280bdb 100644--- a/packages/paperclip-runner/src/cli/acpx-sidecar-input.test.ts+++ b/packages/paperclip-runner/src/cli/acpx-sidecar-input.test.ts@@ -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");+});diff --git a/packages/paperclip-runner/src/cli/acpx-sidecar-input.ts b/packages/paperclip-runner/src/cli/acpx-sidecar-input.tsindex 6aeee58ca1..e9f4c64502 100644--- a/packages/paperclip-runner/src/cli/acpx-sidecar-input.ts+++ b/packages/paperclip-runner/src/cli/acpx-sidecar-input.ts@@ -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",diff --git a/packages/paperclip-runner/src/drivers/acpx/installation-integrity.test.ts b/packages/paperclip-runner/src/drivers/acpx/installation-integrity.test.tsindex 089aeec06b..f9f014ee7b 100644--- a/packages/paperclip-runner/src/drivers/acpx/installation-integrity.test.ts+++ b/packages/paperclip-runner/src/drivers/acpx/installation-integrity.test.ts@@ -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);diff --git a/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts b/packages/paperclip-runner/src/drivers/acpx/installation-integrity.tsindex 05fd89fdc4..e96722c975 100644--- a/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts+++ b/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts@@ -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`,diff --git a/packages/paperclip-runner/src/live/runnerd-codex-transport.test.ts b/packages/paperclip-runner/src/live/runnerd-codex-transport.test.tsindex debd0c6e3f..a64c51c26e 100644--- a/packages/paperclip-runner/src/live/runnerd-codex-transport.test.ts+++ b/packages/paperclip-runner/src/live/runnerd-codex-transport.test.ts@@ -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-"),diff --git a/packages/paperclip-runner/src/live/runnerd-codex-transport.ts b/packages/paperclip-runner/src/live/runnerd-codex-transport.tsindex 71103812f2..4d7be0fbe6 100644--- a/packages/paperclip-runner/src/live/runnerd-codex-transport.ts+++ b/packages/paperclip-runner/src/live/runnerd-codex-transport.ts@@ -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 (diff --git a/scripts/acpx-patch-packaging.test.mjs b/scripts/acpx-patch-packaging.test.mjsindex fb7086946e..d502eaebab 100644--- a/scripts/acpx-patch-packaging.test.mjs+++ b/scripts/acpx-patch-packaging.test.mjs@@ -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/[email protected]${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/[email protected]"], {+ "@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 consumeassert.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 pipefailprintf '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/distnode -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);diff --git a/scripts/prepare-bundled-package.mjs b/scripts/prepare-bundled-package.mjsindex cdc0338790..528ece8bfb 100644--- a/scripts/prepare-bundled-package.mjs+++ b/scripts/prepare-bundled-package.mjs@@ -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, bundledDependif (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");+ if (!profiles.length || new Set(profiles.map(profile => profile.agent)).size !== profiles.length) {+ throw new Error("Bundled provider graph must contain distinct qualified profiles");+ }+ 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 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");+ 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");}- 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);+ 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;}- } 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");+ 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`);}- 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);+ 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); }}- const vendor = resolve(packageDirectory, "vendor");- if (lstatExists(vendor)) { ownedDirectory(vendor); remove.add(vendor); }}- }- 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;+ 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, publishfor (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;diff --git a/server/package.json b/server/package.jsonindex ae6ce5ab0b..657e961e72 100644--- a/server/package.json+++ b/server/package.json@@ -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",diff --git a/server/scripts/verify-runner-vendor-dependencies.mjs b/server/scripts/verify-runner-vendor-dependencies.mjsindex 26bf6f3918..78d855d021 100644--- a/server/scripts/verify-runner-vendor-dependencies.mjs+++ b/server/scripts/verify-runner-vendor-dependencies.mjs@@ -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(diff --git a/server/scripts/verify-runner-vendor-dependencies.test.mjs b/server/scripts/verify-runner-vendor-dependencies.test.mjsindex 07bbbcef3b..3ffca3e2cf 100644--- a/server/scripts/verify-runner-vendor-dependencies.test.mjs+++ b/server/scripts/verify-runner-vendor-dependencies.test.mjs@@ -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);+});diff --git a/server/src/adapters/registry.test.ts b/server/src/adapters/registry.test.tsindex d86b014421..b59f7ffc87 100644--- a/server/src/adapters/registry.test.ts+++ b/server/src/adapters/registry.test.ts@@ -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");diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.tsindex 54b72aa3bd..1754f81e3d 100644--- a/server/src/adapters/registry.ts+++ b/server/src/adapters/registry.ts@@ -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.",+ }],};}}diff --git a/server/src/services/native-runtime/native-session-executor.test.ts b/server/src/services/native-runtime/native-session-executor.test.tsindex 375cbf61cc..a78296fc18 100644--- a/server/src/services/native-runtime/native-session-executor.test.ts+++ b/server/src/services/native-runtime/native-session-executor.test.ts@@ -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 });+});diff --git a/server/src/services/native-runtime/native-session-executor.ts b/server/src/services/native-runtime/native-session-executor.tsindex 9a823b4e95..92501cfa94 100644--- a/server/src/services/native-runtime/native-session-executor.ts+++ b/server/src/services/native-runtime/native-session-executor.ts@@ -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)) {diff --git a/ui/src/components/RuntimeTestCard.test.tsx b/ui/src/components/RuntimeTestCard.test.tsxnew file mode 100644index 0000000000..b7ca0538ec--- /dev/null+++ b/ui/src/components/RuntimeTestCard.test.tsx@@ -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());+ }+});diff --git a/ui/src/components/RuntimeTestCard.tsx b/ui/src/components/RuntimeTestCard.tsxindex 24398642b1..66c4b033d9 100644--- a/ui/src/components/RuntimeTestCard.tsx+++ b/ui/src/components/RuntimeTestCard.tsx@@ -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"? Loader2diff --git a/ui/src/components/TaskChatThread.test.tsx b/ui/src/components/TaskChatThread.test.tsxindex b05b403b43..d7d255d6d8 100644--- a/ui/src/components/TaskChatThread.test.tsx+++ b/ui/src/components/TaskChatThread.test.tsx@@ -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");+});diff --git a/ui/src/components/TaskChatThread.tsx b/ui/src/components/TaskChatThread.tsxindex bf497109f9..c1425f56e7 100644--- a/ui/src/components/TaskChatThread.tsx+++ b/ui/src/components/TaskChatThread.tsx@@ -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"