@openclaw/acpx 2026.6.2-beta.1 → 2026.6.5-beta.1

package/dist/index.js

@@ -1,6 +1,10 @@
-import { t as createAcpxRuntimeService } from "./register.runtime-BhLDvIMd.js";
+import { t as createAcpxRuntimeService } from "./register.runtime-DVYJo9yv.js";
 import { tryDispatchAcpReplyHook } from "openclaw/plugin-sdk/acp-runtime-backend";
 //#region extensions/acpx/index.ts
+/**
+* ACPX runtime plugin entry. It registers the embedded ACP backend service and
+* wires reply-dispatch hooks into the plugin SDK runtime.
+*/
 const plugin = {
 	id: "acpx",
 	name: "ACPX Runtime",

package/dist/mcp-command-line.mjs

@@ -1,3 +1,7 @@
+/**
+ * Command-line parser for ACPX MCP proxy targets. It handles simple quoting and
+ * Windows executable paths before spawning the configured MCP target.
+ */
 const WINDOWS_DIRECT_EXECUTABLE_PATH_RE =
   /^(?<command>(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+[\\/]).*?\.(?:exe|com))(?=\s|$)(?:\s+(?<rest>.*))?$/i;
 
@@ -106,6 +110,7 @@ function assertSupportedWindowsCommand(command, platform = process.platform) {
   );
 }
 
+/** Split a configured command string into `{ command, args }` for child_process.spawn. */
 export function splitCommandLine(value, platform = process.platform) {
   const windowsCommand = splitWindowsExecutableCommand(value, platform);
   const parts = windowsCommand ?? splitCommandParts(value, platform);

package/dist/mcp-proxy.mjs

@@ -1,5 +1,9 @@
 #!/usr/bin/env node
 
+/**
+ * Stdio MCP proxy used by ACPX wrappers. It injects OpenClaw-provided MCP
+ * servers into session creation/load/fork requests before forwarding to target.
+ */
 import { spawn } from "node:child_process";
 import path from "node:path";
 import { createInterface } from "node:readline";
@@ -70,6 +74,7 @@ function rewriteLine(line, mcpServers) {
   }
 }
 
+/** Build spawn options for the proxied MCP target process. */
 export function createTargetSpawnOptions(platform = process.platform) {
   const options = {
     stdio: ["pipe", "pipe", "inherit"],

package/dist/{process-reaper-Dr6ilvUG.js → process-reaper-CEUqe0IY.js}

@@ -11,9 +11,15 @@ import { fileURLToPath } from "node:url";
 import { formatPluginConfigIssue } from "openclaw/plugin-sdk/extension-shared";
 import { z } from "zod";
 //#region extensions/acpx/src/command-line.ts
+/**
+* Small shell-command helpers for ACPX-launched processes. Splitting supports
+* simple quoted command strings from config without invoking a shell parser.
+*/
+/** Quote one command argument for display or config serialization. */
 function quoteCommandPart(value) {
 	return JSON.stringify(value);
 }
+/** Split a command string into argv-like parts using simple quote/backslash rules. */
 function splitCommandParts(value) {
 	const parts = [];
 	let current = "";
@@ -53,9 +59,17 @@ function splitCommandParts(value) {
 }
 //#endregion
 //#region extensions/acpx/src/process-lease.ts
+/**
+* Persistent lease store for ACPX wrapper processes. Leases let OpenClaw attach
+* gateway/session identity to spawned ACP processes and clean them up later.
+*/
+/** Environment variable carrying the ACPX process lease id. */
 const OPENCLAW_ACPX_LEASE_ID_ENV = "OPENCLAW_ACPX_LEASE_ID";
+/** Environment variable carrying the owning gateway instance id. */
 const OPENCLAW_GATEWAY_INSTANCE_ID_ENV = "OPENCLAW_GATEWAY_INSTANCE_ID";
+/** CLI argument carrying the ACPX process lease id for platforms without env wrapping. */
 const OPENCLAW_ACPX_LEASE_ID_ARG = "--openclaw-acpx-lease-id";
+/** CLI argument carrying the owning gateway instance id. */
 const OPENCLAW_GATEWAY_INSTANCE_ID_ARG = "--openclaw-gateway-instance-id";
 const LEASE_FILE = "process-leases.json";
 function normalizeLease(value) {
@@ -93,6 +107,7 @@ async function readLeaseFile(filePath) {
 function writeLeaseFile(filePath, value) {
 	return writeJsonFileAtomically(filePath, value);
 }
+/** Create a serialized JSON-backed ACPX process lease store. */
 function createAcpxProcessLeaseStore(params) {
 	const filePath = path.join(params.stateDir, LEASE_FILE);
 	let updateQueue = Promise.resolve();
@@ -129,9 +144,11 @@ function createAcpxProcessLeaseStore(params) {
 		}
 	};
 }
+/** Create a unique lease id for one ACPX wrapper process. */
 function createAcpxProcessLeaseId() {
 	return randomUUID();
 }
+/** Hash a wrapper command so process leases can detect command drift. */
 function hashAcpxProcessCommand(command) {
 	return createHash("sha256").update(command).digest("hex");
 }
@@ -147,6 +164,7 @@ function appendAcpxLeaseArgs(params) {
 		quoteEnvValue(params.gatewayInstanceId)
 	].join(" ");
 }
+/** Add ACPX lease identity to a command through env vars and portable args. */
 function withAcpxLeaseEnvironment(params) {
 	if ((params.platform ?? process.platform) === "win32") return appendAcpxLeaseArgs(params);
 	return [
@@ -158,6 +176,10 @@ function withAcpxLeaseEnvironment(params) {
 }
 //#endregion
 //#region extensions/acpx/src/config-schema.ts
+/**
+* ACPX plugin configuration schema and public config types. Runtime setup uses
+* this file as the single source of truth for validation and defaulting.
+*/
 const ACPX_PERMISSION_MODES = [
 	"approve-all",
 	"approve-reads",
@@ -170,6 +192,7 @@ const McpServerConfigSchema = z.object({
 	args: z.array(z.string({ error: "args must be an array of strings" }), { error: "args must be an array of strings" }).optional().describe("Arguments to pass to the command"),
 	env: z.record(z.string(), z.string({ error: "env values must be strings" }), { error: "env must be an object of strings" }).optional().describe("Environment variables for the MCP server")
 });
+/** Zod schema for validating raw ACPX plugin config from OpenClaw config. */
 const AcpxPluginConfigSchema = z.strictObject({
 	cwd: nonEmptyTrimmedString("cwd must be a non-empty string").optional(),
 	stateDir: nonEmptyTrimmedString("stateDir must be a non-empty string").optional(),
@@ -189,6 +212,10 @@ const AcpxPluginConfigSchema = z.strictObject({
 });
 //#endregion
 //#region extensions/acpx/src/config.ts
+/**
+* Resolves ACPX plugin config from raw user configuration. It locates the
+* plugin root, injects optional MCP bridge servers, and applies runtime defaults.
+*/
 const ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME = "openclaw-plugin-tools";
 const ACPX_OPENCLAW_TOOLS_MCP_SERVER_NAME = "openclaw-tools";
 const requireFromHere$1 = createRequire(import.meta.url);
@@ -229,6 +256,7 @@ function resolveAcpxPluginRootFromOpenClawLayout(moduleUrl) {
 	}
 	return null;
 }
+/** Resolve the ACPX plugin root across source, dist, and dist-runtime layouts. */
 function resolveAcpxPluginRoot(moduleUrl = import.meta.url) {
 	const resolvedRoot = resolveNearestAcpxPluginRoot(moduleUrl);
 	return resolveWorkspaceAcpxPluginRoot(resolvedRoot) ?? resolveRepoAcpxPluginRoot(resolvedRoot) ?? resolveAcpxPluginRootFromOpenClawLayout(moduleUrl) ?? resolvedRoot;
@@ -313,6 +341,7 @@ function resolveConfiguredMcpServers(params) {
 	if (params.openClawToolsMcpBridge) resolved[ACPX_OPENCLAW_TOOLS_MCP_SERVER_NAME] = resolveOpenClawToolsMcpServerConfig(params.moduleUrl);
 	return resolved;
 }
+/** Convert OpenClaw MCP server config into ACPX runtime MCP server entries. */
 function toAcpMcpServers(mcpServers) {
 	return Object.entries(mcpServers).map(([name, server]) => ({
 		name,
@@ -324,6 +353,7 @@ function toAcpMcpServers(mcpServers) {
 		}))
 	}));
 }
+/** Validate and normalize raw ACPX plugin config for runtime startup. */
 function resolveAcpxPluginConfig(params) {
 	const parsed = parseAcpxPluginConfig(params.rawConfig);
 	if (!parsed.ok) throw new Error(parsed.message);
@@ -367,6 +397,10 @@ function resolveAcpxPluginConfig(params) {
 }
 //#endregion
 //#region extensions/acpx/src/process-reaper.ts
+/**
+* ACPX process ownership checks and cleanup. The reaper only terminates
+* OpenClaw-owned wrapper trees after validating paths, packages, and lease ids.
+*/
 const execFileAsync = promisify(execFile);
 const requireFromHere = createRequire(import.meta.url);
 const GENERATED_WRAPPER_BASENAMES = new Set(["codex-acp-wrapper.mjs", "claude-agent-acp-wrapper.mjs"]);
@@ -422,6 +456,7 @@ function commandWrapperBelongsToRoot(command, wrapperRoot) {
 	const normalizedRoot = normalizePathLike(wrapperRoot).replace(/\/+$/, "");
 	return Array.from(GENERATED_WRAPPER_BASENAMES).some((basename) => normalizedCommand.includes(`${normalizedRoot}/${basename}`));
 }
+/** Check whether a command references an OpenClaw-generated ACPX wrapper path. */
 function isOpenClawLeaseAwareAcpxProcessCommand(params) {
 	const command = params.command?.trim();
 	if (!command) return false;
@@ -442,6 +477,7 @@ function liveCommandMatchesLeaseIdentity(params) {
 	const parts = splitCommandParts(params.command ?? "");
 	return commandOptionEquals(parts, "--openclaw-acpx-lease-id", params.expectedLeaseId) && commandOptionEquals(parts, "--openclaw-gateway-instance-id", params.expectedGatewayInstanceId);
 }
+/** Check whether a command is owned by OpenClaw ACPX runtime packages or wrappers. */
 function isOpenClawOwnedAcpxProcessCommand(params) {
 	const command = params.command?.trim();
 	if (!command) return false;
@@ -467,6 +503,7 @@ function parseProcessList(stdout) {
 	}
 	return processes;
 }
+/** List host processes in the compact shape needed by ACPX cleanup. */
 async function listPlatformProcesses() {
 	if (process.platform === "win32") return [];
 	const { stdout } = await execFileAsync("ps", ["-axo", "pid=,ppid=,command="], { maxBuffer: 8 * 1024 * 1024 });
@@ -519,6 +556,7 @@ async function terminatePids(pids, deps) {
 	} catch {}
 	return terminated;
 }
+/** Terminate one validated OpenClaw-owned ACPX wrapper process tree. */
 async function cleanupOpenClawOwnedAcpxProcessTree(params) {
 	const rootPid = params.rootPid;
 	if (!rootPid || rootPid <= 0 || rootPid === process.pid) return {
@@ -574,6 +612,7 @@ async function cleanupOpenClawOwnedAcpxProcessTree(params) {
 		terminatedPids: await terminatePids(pids, params.deps)
 	};
 }
+/** Reap orphaned OpenClaw-owned ACPX wrapper trees during runtime startup. */
 async function reapStaleOpenClawOwnedAcpxOrphans(params) {
 	if (process.platform === "win32") return {
 		inspectedPids: [],

package/dist/{register.runtime-BhLDvIMd.js → register.runtime-DVYJo9yv.js}

@@ -125,9 +125,11 @@ function legacyRunTurnAsStartTurn(runtime, input) {
 		}
 	};
 }
+/** Start an ACP turn, adapting legacy runTurn-only runtimes when needed. */
 function startRuntimeTurn(runtime, input) {
 	return runtime.startTurn?.(input) ?? legacyRunTurnAsStartTurn(runtime, input);
 }
+/** Start an ACP turn through a lazy runtime resolver. */
 function lazyStartRuntimeTurn(resolveRuntime, input) {
 	const turnPromise = resolveRuntime().then((runtime) => startRuntimeTurn(runtime, input));
 	return {
@@ -153,6 +155,7 @@ function toLintErrorObject(value, fallbackMessage) {
 }
 //#endregion
 //#region extensions/acpx/src/runtime-proxy.ts
+/** Create an ACP runtime facade backed by an async runtime resolver. */
 function createLazyAcpRuntimeProxy(resolveRuntime) {
 	return {
 		async ensureSession(input) {
@@ -195,10 +198,14 @@ function createLazyAcpRuntimeProxy(resolveRuntime) {
 }
 //#endregion
 //#region extensions/acpx/register.runtime.ts
+/**
+* Lazy ACPX runtime service registration. The plugin exposes an ACP backend
+* immediately, then imports the heavier service only when a session needs it.
+*/
 const ACPX_BACKEND_ID = "acpx";
 let serviceModulePromise = null;
 function loadServiceModule() {
-	serviceModulePromise ??= import("./service-DnQfb40X.js");
+	serviceModulePromise ??= import("./service-8gUnMlij.js");
 	return serviceModulePromise;
 }
 async function startRealService(state) {
@@ -226,6 +233,7 @@ function createDeferredRuntime(state) {
 	const resolveRuntime = () => startRealService(state);
 	return createLazyAcpRuntimeProxy(resolveRuntime);
 }
+/** Creates the plugin service that registers ACPX as an ACP runtime backend. */
 function createAcpxRuntimeService(params = {}) {
 	const state = {
 		ctx: null,

package/dist/register.runtime.js

@@ -1,2 +1,2 @@
-import { t as createAcpxRuntimeService } from "./register.runtime-BhLDvIMd.js";
+import { t as createAcpxRuntimeService } from "./register.runtime-DVYJo9yv.js";
 export { createAcpxRuntimeService };

package/dist/{runtime-DqAsRsX9.js → runtime-COFrLvHN.js}

@@ -1,5 +1,5 @@
 import { AcpRuntimeError } from "./runtime-api.js";
-import { f as hashAcpxProcessCommand, h as splitCommandParts, n as isOpenClawLeaseAwareAcpxProcessCommand, p as withAcpxLeaseEnvironment, t as cleanupOpenClawOwnedAcpxProcessTree, u as createAcpxProcessLeaseId } from "./process-reaper-Dr6ilvUG.js";
+import { f as hashAcpxProcessCommand, h as splitCommandParts, n as isOpenClawLeaseAwareAcpxProcessCommand, p as withAcpxLeaseEnvironment, t as cleanupOpenClawOwnedAcpxProcessTree, u as createAcpxProcessLeaseId } from "./process-reaper-CEUqe0IY.js";
 import { normalizeStringEntries } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { AsyncLocalStorage } from "node:async_hooks";
 import fs from "node:fs/promises";
@@ -8,6 +8,10 @@ import { ACPX_BACKEND_ID, AcpxRuntime as AcpxRuntime$1, createAcpRuntime, create
 import { parseStrictPositiveInteger } from "openclaw/plugin-sdk/number-runtime";
 import { redactSensitiveText } from "openclaw/plugin-sdk/security-runtime";
 //#region extensions/acpx/src/runtime.ts
+/**
+* OpenClaw ACPX runtime adapter. It wraps the upstream acpx runtime with
+* OpenClaw session metadata, lease tracking, model scoping, and cleanup policy.
+*/
 function withOpenClawManagedTurnTimeout(input) {
 	return {
 		...input,
@@ -343,6 +347,7 @@ function shouldUseDistinctBridgeDelegate(options) {
 	const { mcpServers } = options;
 	return Array.isArray(mcpServers) && mcpServers.length > 0;
 }
+/** OpenClaw-managed ACP runtime implementation backed by the upstream acpx runtime. */
 var AcpxRuntime = class {
 	constructor(options, testOptions) {
 		this.codexAcpModelOverrideScope = new AsyncLocalStorage();
@@ -712,6 +717,7 @@ var AcpxRuntime = class {
 		if (closeSucceeded && input.discardPersistentState) this.sessionStore.markFresh(input.handle.sessionKey);
 	}
 };
+/** Test-only hooks for ACPX runtime behavior that is otherwise private. */
 const testing = {
 	appendCodexAcpConfigOverrides,
 	assertSupportedRuntimeSessionMode,

package/dist/{service-DnQfb40X.js → service-8gUnMlij.js}

@@ -1,6 +1,6 @@
-import { n as createLazyAcpRuntimeProxy } from "./register.runtime-BhLDvIMd.js";
+import { n as createLazyAcpRuntimeProxy } from "./register.runtime-DVYJo9yv.js";
 import { registerAcpRuntimeBackend, unregisterAcpRuntimeBackend } from "./runtime-api.js";
-import { a as resolveAcpxPluginRoot, c as OPENCLAW_ACPX_LEASE_ID_ENV, d as createAcpxProcessLeaseStore, h as splitCommandParts, i as resolveAcpxPluginConfig, l as OPENCLAW_GATEWAY_INSTANCE_ID_ARG, m as quoteCommandPart, o as toAcpMcpServers, r as reapStaleOpenClawOwnedAcpxOrphans, s as OPENCLAW_ACPX_LEASE_ID_ARG, t as cleanupOpenClawOwnedAcpxProcessTree } from "./process-reaper-Dr6ilvUG.js";
+import { a as resolveAcpxPluginRoot, c as OPENCLAW_ACPX_LEASE_ID_ENV, d as createAcpxProcessLeaseStore, h as splitCommandParts, i as resolveAcpxPluginConfig, l as OPENCLAW_GATEWAY_INSTANCE_ID_ARG, m as quoteCommandPart, o as toAcpMcpServers, r as reapStaleOpenClawOwnedAcpxOrphans, s as OPENCLAW_ACPX_LEASE_ID_ARG, t as cleanupOpenClawOwnedAcpxProcessTree } from "./process-reaper-CEUqe0IY.js";
 import { createRequire } from "node:module";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -12,6 +12,10 @@ import fsSync from "node:fs";
 import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import os from "node:os";
 //#region extensions/acpx/src/codex-trust-config.ts
+/**
+* Builds isolated Codex config for ACPX sessions. It preserves safe inherited
+* runtime options while rendering only trusted project entries for the session.
+*/
 function stripTomlComment(line) {
 	let quote = null;
 	let escaping = false;
@@ -99,6 +103,7 @@ function parseTrustedInlineProjectEntries(value) {
 	}
 	return trusted;
 }
+/** Extract trusted project paths from Codex TOML config. */
 function extractTrustedCodexProjectPaths(configToml) {
 	const trusted = /* @__PURE__ */ new Set();
 	let currentProjectPath;
@@ -194,6 +199,7 @@ function extractInheritedCodexRuntimeConfig(configToml) {
 	while (inheritedLines.length > 0 && inheritedLines[inheritedLines.length - 1] === "") inheritedLines.pop();
 	return inheritedLines.join("\n");
 }
+/** Render a session-local Codex config with inherited runtime settings and trust entries. */
 function renderIsolatedCodexConfig(params) {
 	const normalized = Array.from(new Set(params.projectPaths.map((projectPath) => projectPath.trim()).filter(Boolean).map((projectPath) => path.resolve(projectPath)))).toSorted((left, right) => left.localeCompare(right));
 	return [
@@ -209,6 +215,10 @@ function renderIsolatedCodexConfig(params) {
 }
 //#endregion
 //#region extensions/acpx/src/codex-auth-bridge.ts
+/**
+* Prepares isolated Codex and Claude ACP wrapper commands for ACPX. The bridge
+* copies safe auth/config state into plugin-owned homes and redacts diagnostics.
+*/
 const CODEX_ACP_PACKAGE = "@zed-industries/codex-acp";
 const CODEX_ACP_BIN = "codex-acp";
 const CLAUDE_ACP_PACKAGE = "@agentclientprotocol/claude-agent-acp";
@@ -802,6 +812,7 @@ function buildClaudeAcpWrapperCommand(wrapperPath, configuredCommand) {
 	if (configuredAdapterArgs) return buildWrapperCommand(wrapperPath, configuredAdapterArgs);
 	return configuredCommand?.trim() || buildWrapperCommand(wrapperPath);
 }
+/** Prepare ACPX agent commands and isolated auth homes for Codex/Claude adapters. */
 async function prepareAcpxCodexAuthConfig(params) {
 	params.logger;
 	const codexBaseDir = path.join(params.stateDir, "acpx");
@@ -826,14 +837,19 @@ async function prepareAcpxCodexAuthConfig(params) {
 }
 //#endregion
 //#region extensions/acpx/src/service.ts
+/**
+* ACPX plugin service lifecycle. It resolves config, prepares isolated adapter
+* wrappers, registers the ACP backend, and manages startup/cleanup probes.
+*/
 const ENABLE_STARTUP_PROBE_ENV = "OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE";
 const SKIP_RUNTIME_PROBE_ENV = "OPENCLAW_SKIP_ACPX_RUNTIME_PROBE";
 const ACPX_BACKEND_ID = "acpx";
 let runtimeModulePromise = null;
 function loadRuntimeModule() {
-	runtimeModulePromise ??= import("./runtime-DqAsRsX9.js");
+	runtimeModulePromise ??= import("./runtime-COFrLvHN.js");
 	return runtimeModulePromise;
 }
+/** Convert ACPX timeout seconds into timer-safe milliseconds. */
 function resolveAcpxTimerTimeoutMs(timeoutSeconds) {
 	if (timeoutSeconds === void 0) return;
 	return finiteSecondsToTimerSafeMilliseconds(timeoutSeconds) ?? 1;
@@ -990,6 +1006,7 @@ async function reapOpenAcpxProcessLeases(params) {
 		terminatedPids
 	};
 }
+/** Create the ACPX plugin service that owns runtime registration and cleanup. */
 function createAcpxRuntimeService(params = {}) {
 	let runtime = null;
 	let lifecycleRevision = 0;

package/dist/setup-api.js

@@ -1,6 +1,10 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 //#region extensions/acpx/setup-api.ts
+/**
+* ACPX setup plugin entry. It auto-enables setup when ACP config already points
+* at the embedded ACPX runtime backend.
+*/
 var setup_api_default = definePluginEntry({
 	id: "acpx",
 	name: "ACPX Setup",

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@openclaw/acpx",
-  "version": "2026.6.2-beta.1",
+  "version": "2026.6.5-beta.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@openclaw/acpx",
-      "version": "2026.6.2-beta.1",
+      "version": "2026.6.5-beta.1",
       "dependencies": {
         "@agentclientprotocol/claude-agent-acp": "0.39.0",
         "@zed-industries/codex-acp": "0.15.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/acpx",
-  "version": "2026.6.2-beta.1",
+  "version": "2026.6.5-beta.1",
   "description": "OpenClaw ACP runtime backend with plugin-owned session and transport management.",
   "repository": {
     "type": "git",
@@ -26,10 +26,10 @@
       "minHostVersion": ">=2026.4.25"
     },
     "compat": {
-      "pluginApi": ">=2026.6.2-beta.1"
+      "pluginApi": ">=2026.6.5-beta.1"
     },
     "build": {
-      "openclawVersion": "2026.6.2-beta.1",
+      "openclawVersion": "2026.6.5-beta.1",
       "staticAssets": [
         {
           "source": "./src/runtime-internals/mcp-proxy.mjs",
@@ -58,7 +58,7 @@
     "skills/**"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.6.2-beta.1"
+    "openclaw": ">=2026.6.5-beta.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {