paperclipai/paperclip · error

ACPX runtime does not expose extension requests

Error message

ACPX runtime does not expose extension requests

What it means

After the goal action passes the capability check, controlGoal() requires runtime.requestExtension to forward the control method to the ACPX runtime. When the runtime object lacks a requestExtension function (the pinned runtime interface does not implement the extension-request surface), the adapter throws this error. It signals an adapter/runtime version incompatibility rather than a user input problem: the negotiated capability exists but there is no transport to exercise it.

Source

Thrown at packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts:1106

      return await persistedRuntimeStatus(sessionStore, handle, identity);
    },
    goalCapability() {
      return goalState.capability === null
        ? null
        : structuredClone(goalState.capability);
    },
    goalSnapshot() {
      return goalState.snapshot === null
        ? null
        : structuredClone(goalState.snapshot);
    },
    async controlGoal(action, objective) {
      const capability = goalState.capability;
      if (!capability || !capability.actions.includes(action)) {
        throw new Error(`ACPX session goal action ${action} is unavailable`);
      }
      if (!runtime.requestExtension) {
        throw new Error("ACPX runtime does not expose extension requests");
      }
      const revisionBeforeControl = goalState.revision;
      await runtime.requestExtension({
        handle,
        method: capability.controlMethod,
        params: {
          sessionId: identity.agentSessionId,
          action,
          ...(action === "set" ? { objective } : {}),
        },
        sessionMode: "persistent",
      });
      const shouldRepairMissingSetSnapshot =
        action === "set" &&
        Boolean(objective?.trim()) &&
        goalState.snapshot === null;
      const shouldRepairStaleClearSnapshot =
        action === "clear" && goalState.snapshot !== null;

View on GitHub (pinned to 01ad858492)

Solutions

1. Upgrade the ACPX runtime package so the pinned runtime exposes requestExtension.
2. Verify the runtime object used to build the port is the real runtime, not a stub missing requestExtension.
3. Guard callers: skip goal control when requestExtension is unavailable, mirroring how setModel is conditionally exposed (see runtime.setConfigOption check).
4. Align adapter and runtime versions so capability negotiation and the extension transport are both present.

Example fix

// before
const port = createPort(runtimeWithoutExtensions);
await port.controlGoal("set", { text: "do it" }); // throws
// after
if (typeof runtime.requestExtension !== "function") {
  throw new Error("upgrade ACPX runtime: goal control needs requestExtension");
}
await port.controlGoal("set", { text: "do it" });

if (typeof runtime.requestExtension !== "function") {
  throw new Error("runtime lacks extension request support; upgrade ACPX runtime");
}

function supportsExtensionRequests(runtime) {
  return typeof runtime?.requestExtension === "function";
}

try {
  await port.controlGoal(action, objective);
} catch (e) {
  if (e.message === "ACPX runtime does not expose extension requests") {
    logRuntimeIncompatibility();
    fallbackToLocalGoalTracking();
  } else throw e;
}

When it happens

Trigger: port.controlGoal(action, objective) invoked with a valid capability whose runtime instance was created without a requestExtension implementation (runtime.requestExtension is undefined).

Common situations: Running against an older ACPX/Codex runtime build that predates extension requests; a test stub or mock runtime implementing startTurn but omitting requestExtension; partial interface drift after upgrading the adapter without the runtime library.

Related errors

• ACPX claude package dependency mismatch for ${expected.packa
• ACPX claude dependency package version mismatch for ${expect
• ACPX ${input.profile.agent} runtime does not match its quali
• ACPX ${input.profile.agent} runtime executable package versi
• Native ACPX backend for pi is unavailable until descriptor-c

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