paperclipai/paperclip · error · Error

Native ACPX backend for pi is unavailable until descriptor-c

Error message

Native ACPX backend for pi is unavailable until descriptor-confined verified launch is implemented

What it means

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.

Source

Thrown at packages/paperclip-runner/src/backends/codex-native-backend.ts:85

        kind: "opencode_server",
        displayName: "OpenCode server",
        version: "1.18.29",
      };
    case "claude_managed":
      return {
        kind: "claude_managed_agents_api",
        displayName: "Claude Managed Agent",
        version: input.provider.managedProfile.betaVersion,
      };
    case "aws_agentcore":
      return {
        kind: "aws_agentcore_harness_api",
        displayName: "AWS AgentCore Harness",
        version: input.provider.agentCoreProfile.qualificationRevision,
      };
    case "acpx":
      if (input.provider.agent === "pi") {
        throw new Error(
          "Native ACPX backend for pi is unavailable until descriptor-confined verified launch is implemented",
        );
      }
      return {
        kind: "acpx_runtime",
        displayName: `${input.provider.agent === "claude" ? "Claude" : "Codex"} via ACPX`,
        version: "0.13.1",
      };
    default:
      throw new Error(
        "Native provider is not available through the local runnerd transport",
      );
  }
}

function createTransportBackedNativeSessionBackend(
  input: NativeExecutionInput,
  options: CodexNativeSessionBackendOptions,

View on GitHub (pinned to 01ad858492)

Solutions

1. Select a supported agent for the acpx provider kind — 'claude' or 'codex' — instead of 'pi'.
2. Route pi through a different provider kind that supports it (e.g. its native/default transport) rather than the native ACPX backend.
3. Remove or correct the provider configuration that pairs agent 'pi' with kind 'acpx' in the provider descriptor/catalog.
4. If pi+acpx is genuinely required, implement descriptor-confined verified launch for the pi agent in codex-native-backend.ts and update this guard.

Example fix

// before
const provider = { kind: "acpx", agent: "pi", model: "pi-model" }; // throws
// after
const provider = { kind: "acpx", agent: "codex", model: "codex-model" }; // supported
// or use a provider kind that supports pi natively

function isAcpxPi(provider) {
  return provider?.kind === "acpx" && provider?.agent === "pi";
}
// before calling the native backend:
if (isAcpxPi(input.provider)) {
  throw new Error("pi agent is not supported on the native ACPX backend; use 'claude'/'codex' or another provider kind");
}

function supportsNativeBackend(provider) {
  if (provider?.kind === "acpx") return provider?.agent !== "pi";
  return ["codex", "opencode", "claude_managed", "aws_agentcore"].includes(provider?.kind);
}

try {
  const backend = createTransportBackedNativeSessionBackend(input, options);
} catch (err) {
  if (/Native ACPX backend for pi is unavailable/.test(err.message)) {
    console.error("pi is gated on descriptor-confined verified launch; falling back to a supported agent/provider.");
    return createTransportBackedNativeSessionBackend({ ...input, provider: { ...input.provider, agent: "codex" } }, options);
  }
  throw err;
}

When it happens

Trigger: Calling createTransportBackedNativeSessionBackend (or driverIdentity) with input.provider.kind === 'acpx' and input.provider.agent === 'pi'.

Common situations: 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.

Related errors

• The Pi ACPX profile is not available
• initialize the ACPX sidecar first
• ACPX session profile differs from its initialization
• ACPX sidecar runtime context must be pre-materialized
• run.result.proposed

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-02). Data as JSON: /api/errors/db2a94b313e98658. Report an issue: GitHub.