{"record":{"id":"db2a94b313e98658","repo":"paperclipai/paperclip","slug":"native-acpx-backend-for-pi-is-unavailable-until-de","errorCode":null,"errorMessage":"Native ACPX backend for pi is unavailable until descriptor-confined verified launch is implemented","messagePattern":"Native ACPX backend for pi is unavailable until descriptor-confined verified launch is implemented","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/backends/codex-native-backend.ts","lineNumber":85,"sourceCode":"        kind: \"opencode_server\",\n        displayName: \"OpenCode server\",\n        version: \"1.18.29\",\n      };\n    case \"claude_managed\":\n      return {\n        kind: \"claude_managed_agents_api\",\n        displayName: \"Claude Managed Agent\",\n        version: input.provider.managedProfile.betaVersion,\n      };\n    case \"aws_agentcore\":\n      return {\n        kind: \"aws_agentcore_harness_api\",\n        displayName: \"AWS AgentCore Harness\",\n        version: input.provider.agentCoreProfile.qualificationRevision,\n      };\n    case \"acpx\":\n      if (input.provider.agent === \"pi\") {\n        throw new Error(\n          \"Native ACPX backend for pi is unavailable until descriptor-confined verified launch is implemented\",\n        );\n      }\n      return {\n        kind: \"acpx_runtime\",\n        displayName: `${input.provider.agent === \"claude\" ? \"Claude\" : \"Codex\"} via ACPX`,\n        version: \"0.13.1\",\n      };\n    default:\n      throw new Error(\n        \"Native provider is not available through the local runnerd transport\",\n      );\n  }\n}\n\nfunction createTransportBackedNativeSessionBackend(\n  input: NativeExecutionInput,\n  options: CodexNativeSessionBackendOptions,","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/backends/codex-native-backend.ts#L67-L103","documentation":"transportDriverIdentity maps a NativeExecutionInput's provider.kind to a driver identity. When kind is 'acpx' and provider.agent is 'pi', it throws a plain Error stating the native ACPX backend for the pi agent is unavailable until descriptor-confined verified launch is implemented. This is an intentional, permanent-for-now capability gate, not a transient failure — the code path is unimplemented for pi.","triggerScenarios":"Calling createTransportBackedNativeSessionBackend (or driverIdentity) with input.provider.kind === 'acpx' and input.provider.agent === 'pi'.","commonSituations":"Configuring a provider descriptor that selects the ACPX transport with agent 'pi'; a misconfigured provider catalog entry defaulting agent to 'pi'; testing pi support expecting ACPX to work when the feature has not shipped; version drift where a newer config schema emits pi+acpx that this backend cannot honor.","solutions":["Select a supported agent for the acpx provider kind — 'claude' or 'codex' — instead of 'pi'.","Route pi through a different provider kind that supports it (e.g. its native/default transport) rather than the native ACPX backend.","Remove or correct the provider configuration that pairs agent 'pi' with kind 'acpx' in the provider descriptor/catalog.","If pi+acpx is genuinely required, implement descriptor-confined verified launch for the pi agent in codex-native-backend.ts and update this guard."],"exampleFix":"// before\nconst provider = { kind: \"acpx\", agent: \"pi\", model: \"pi-model\" }; // throws\n// after\nconst provider = { kind: \"acpx\", agent: \"codex\", model: \"codex-model\" }; // supported\n// or use a provider kind that supports pi natively","handlingStrategy":"type-guard","validationCode":"function isAcpxPi(provider) {\n  return provider?.kind === \"acpx\" && provider?.agent === \"pi\";\n}\n// before calling the native backend:\nif (isAcpxPi(input.provider)) {\n  throw new Error(\"pi agent is not supported on the native ACPX backend; use 'claude'/'codex' or another provider kind\");\n}","typeGuard":"function supportsNativeBackend(provider) {\n  if (provider?.kind === \"acpx\") return provider?.agent !== \"pi\";\n  return [\"codex\", \"opencode\", \"claude_managed\", \"aws_agentcore\"].includes(provider?.kind);\n}","tryCatchPattern":"try {\n  const backend = createTransportBackedNativeSessionBackend(input, options);\n} catch (err) {\n  if (/Native ACPX backend for pi is unavailable/.test(err.message)) {\n    console.error(\"pi is gated on descriptor-confined verified launch; falling back to a supported agent/provider.\");\n    return createTransportBackedNativeSessionBackend({ ...input, provider: { ...input.provider, agent: \"codex\" } }, options);\n  }\n  throw err;\n}","preventionTips":["Never configure agent 'pi' with provider kind 'acpx'; use 'claude' or 'codex' for ACPX.","Check provider descriptors/catalog entries for pi+acpx pairings before deployment.","Validate provider.kind/agent combinations against a supported-matrix constant before calling the backend.","If pi support is needed, track the descriptor-confined verified launch work item instead of working around the throw.","Wrap backend creation in a guard so the error surfaces as an actionable config message rather than a raw stack trace."],"tags":["unsupported-agent","acpx","capability-gate","unimplemented"],"backgroundTag":"unsupported-provider-agent","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-02T18:44:00.616Z","contentChangedAt":"2026-09-02T18:44:00.616Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}