@openclaw/acpx 2026.10.10 → 2026.11.5-beta.1

package/dist/.setup/{session-owner-migration-WmiXoSmh.mjs → session-owner-migration-CQA7L68K.mjs}

@@ -1,5 +1,5 @@
 import { t as runtime_doctor_migrations_exports } from "./runtime-doctor-migrations-CSvRANPN.mjs";
-import { c as renderAgentCommand, t as resolveAcpxPluginConfig, u as splitCommandParts } from "./config-CE-ej7LM.mjs";
+import { c as renderAgentCommand, t as resolveAcpxPluginConfig, u as splitCommandParts } from "./config-Cplh34lQ.mjs";
 import path from "node:path";
 import { asFiniteNumber, asOptionalObjectRecord, normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { createHash } from "node:crypto";
@@ -228,7 +228,7 @@ async function legacyRecords(input, directory = sessionDirectory(input)) {
 		directory,
 		ids
 	};
-	const { resolveAcpxSessionResource } = await import("./session-resource-Cv-RAA6y.mjs").then((n) => n.n);
+	const { resolveAcpxSessionResource } = await import("./session-resource-D_tXKvcv.mjs").then((n) => n.n);
 	const evidence = await input.context.inspectAcpSessionClaims?.();
 	const { decodeAcpxRuntimeHandleState } = await import("acpx/runtime");
 	return {
@@ -267,11 +267,11 @@ function matchesClaimRecord(claim, raw, oldId, resource, decode) {
 }
 async function migrateRecord(input, directory, oldId, claims, changes, warnings) {
 	const sourcePath = recordPath(directory, oldId);
-	const sourceBytes = await fs.readFile(sourcePath, "utf8");
-	const raw = (0, runtime_doctor_migrations_exports.asObjectRecord)(JSON.parse(sourceBytes));
+	const sourceBytes = await fs.readFile(sourcePath);
+	const raw = (0, runtime_doctor_migrations_exports.asObjectRecord)(JSON.parse((0, runtime_doctor_migrations_exports.decodeUtf8Input)(sourceBytes, `ACP record ${sourcePath}`)));
 	if (!raw || raw.acpx_record_id !== oldId || typeof raw.name !== "string" || !raw.name.trim() || raw.name !== oldId && !oldId.startsWith(`${raw.name}:oneshot:`)) throw new Error("record ID/name is not a recognized ACPX locator");
 	requireStoppedPid(raw.pid);
-	const { resolveAcpxSessionResource } = await import("./session-resource-Cv-RAA6y.mjs").then((n) => n.n);
+	const { resolveAcpxSessionResource } = await import("./session-resource-D_tXKvcv.mjs").then((n) => n.n);
 	const { createFileSessionStore, decodeAcpxRuntimeHandleState, encodeAcpxRuntimeHandleState } = await import("acpx/runtime");
 	const candidates = claims.filter((claim) => matchesClaimRecord(claim, raw, oldId, resolveAcpxSessionResource(claim), decodeAcpxRuntimeHandleState));
 	if (candidates.length !== 1) throw new Error("exactly one current owner claim is required");
@@ -321,13 +321,13 @@ async function migrateRecord(input, directory, oldId, claims, changes, warnings)
 			acpxRecordId: resource,
 			name: resource
 		})) throw new Error("rekey would alter interpreted history/event references; source retained");
-		const existing = await fs.readFile(destinationPath, "utf8").catch((error) => {
+		const existing = await fs.readFile(destinationPath).catch((error) => {
 			if ((0, runtime_doctor_migrations_exports.asObjectRecord)(error)?.code === "ENOENT") return;
 			throw error;
 		});
 		const originalLocator = decodeAcpxRuntimeHandleState(claim.meta.runtimeSessionName);
 		if (!oneshot && originalLocator.name === resource && existing === void 0) throw new Error("migrated metadata has no published destination; source retained");
-		if (existing !== void 0 && !isDeepStrictEqual(JSON.parse(existing), candidate)) throw new Error("destination conflicts; no files were overwritten");
+		if (existing !== void 0 && !isDeepStrictEqual(JSON.parse((0, runtime_doctor_migrations_exports.decodeUtf8Input)(existing, `ACP record ${destinationPath}`)), candidate)) throw new Error("destination conflicts; no files were overwritten");
 		if (existing === void 0) await fs.link(temporaryPath, destinationPath);
 		const publicationDirectory = await fs.open(directory, "r");
 		try {
@@ -335,8 +335,8 @@ async function migrateRecord(input, directory, oldId, claims, changes, warnings)
 		} finally {
 			await publicationDirectory.close();
 		}
-		if (await fs.readFile(sourcePath, "utf8") !== sourceBytes) throw new Error("source changed during repair");
-		if (!isDeepStrictEqual(JSON.parse(await fs.readFile(destinationPath, "utf8")), candidate)) throw new Error("destination changed during repair");
+		if (!(await fs.readFile(sourcePath)).equals(sourceBytes)) throw new Error("source changed during repair");
+		if (!isDeepStrictEqual(JSON.parse((0, runtime_doctor_migrations_exports.decodeUtf8Input)(await fs.readFile(destinationPath), `ACP record ${destinationPath}`)), candidate)) throw new Error("destination changed during repair");
 		for (const { row } of matchingLeases) {
 			if (!isDeepStrictEqual(await leaseStore.lookup(row.key), row.value)) throw new Error("lease changed during repair");
 			await leaseStore.register(row.key, {
@@ -412,16 +412,19 @@ const acpxSessionOwnerMigration = {
 			changes,
 			warnings: [`ACP owner evidence is incomplete; all records retained: ${evidence.incomplete.join("; ")}`]
 		};
+		let recoverableWarnings = 0;
 		for (const oldId of ids) try {
 			const current = await input.context.inspectAcpSessionClaims();
 			if (current.incomplete.length) throw new Error("current ownership evidence became incomplete");
 			await migrateRecord(input, directory, oldId, current.claims, changes, warnings);
 		} catch (error) {
+			if (error instanceof runtime_doctor_migrations_exports.Utf8InputError) recoverableWarnings++;
 			warnings.push(`ACP record ${oldId} retained: ${String(error)}`);
 		}
 		return {
 			changes,
-			warnings
+			warnings,
+			...warnings.length > 0 && warnings.length === recoverableWarnings ? { warningDisposition: "recoverable" } : {}
 		};
 	}
 };

package/dist/.setup/{session-resource-Cv-RAA6y.mjs → session-resource-D_tXKvcv.mjs}

@@ -1,6 +1,6 @@
 import { n as __exportAll } from "./runtime-doctor-migrations-CSvRANPN.mjs";
 import { AcpRuntimeError } from "../runtime-api.js";
-import { createHash } from "node:crypto";
+import { sha256Hex } from "openclaw/plugin-sdk/node-crypto-runtime";
 import { normalizeAgentId, parseAgentSessionKey } from "openclaw/plugin-sdk/routing";
 // extensions/acpx/src/session-resource.ts
 var session_resource_exports = /* @__PURE__ */ __exportAll({ resolveAcpxSessionResource: () => resolveAcpxSessionResource });
@@ -11,6 +11,6 @@ function resolveAcpxSessionResource(target) {
 	const agentId = target.agentId?.trim() ? normalizeAgentId(target.agentId) : encodedOwner;
 	if (!sessionKey || encodedOwner && agentId !== encodedOwner || !encodedOwner && !agentId) throw new AcpRuntimeError("ACP_SESSION_INIT_FAILED", "ACP session owner is missing or disagrees with its logical key. Pass the OpenClaw agentId that owns this session.", { detailCode: "SESSION_OWNER_UNSUPPORTED" });
 	if (encodedOwner) return sessionKey;
-	return `openclaw-owner-v1-${createHash("sha256").update(JSON.stringify([agentId, sessionKey])).digest("hex")}`;
+	return `openclaw-owner-v1-${sha256Hex(JSON.stringify([agentId, sessionKey]))}`;
 }
 export { session_resource_exports as n, resolveAcpxSessionResource as t };

package/dist/.source-module-urls/9369b1b274d2ba70ea21d859abb3415ad8d63d0a1022a301763b953a5798469e.json

@@ -0,0 +1 @@
+{"version":3,"entries":[{"output":"doctor-contract-api.js","source":"extensions/acpx/doctor-contract-api.ts"},{"output":"index.js","source":"extensions/acpx/index.ts"},{"output":"runtime-api.js","source":"extensions/acpx/runtime-api.ts"},{"output":"setup-api.js","source":"extensions/acpx/setup-api.ts"}],"chunks":[{"output":".setup/config-Cplh34lQ.mjs","sha256":"d26588a4061ab1327c1c8f3b226d58b18f32167dae0c6cc88f39008eabab7a5d","facadeSource":null,"sources":["extensions/acpx/src/codex-adapter.ts","extensions/acpx/src/command-line.ts","extensions/acpx/src/config-schema.ts","extensions/acpx/src/config.ts"]},{"output":".setup/harness-attempt-Co9oLpPg.mjs","sha256":"1f4ff7f279f78641c8b0160aad3be6062ae981c184bc2a15088678e2db4d6add","facadeSource":"extensions/acpx/src/harness-attempt.ts","sources":["extensions/acpx/src/harness-attempt.ts"]},{"output":".setup/pi-session-catalog-runtime-DgzkbadO.mjs","sha256":"52b9233beb364ff104c8e7a6044cc746aaa883c49fa915ce39bbd32d0b9dd90d","facadeSource":"extensions/acpx/src/pi-session-catalog-runtime.ts","sources":["extensions/acpx/src/pi-session-catalog-runtime.ts","extensions/acpx/src/pi-session-catalog.ts","extensions/acpx/src/pi-session-store.ts","extensions/acpx/src/pi-session-upstream-activity.ts"]},{"output":".setup/pi-session-paths-pUr6hnVA.mjs","sha256":"da9568f3f583d68ff895d109855b4e61cb680e6550019dc3b7c643d08696dab0","facadeSource":null,"sources":["extensions/acpx/src/pi-session-catalog-shared.ts","extensions/acpx/src/pi-session-paths.ts"]},{"output":".setup/runtime-doctor-migrations-CSvRANPN.mjs","sha256":"0f9941caf2101d12539e47fd11f7da27fd330dd82bf8e80cdc11d8fd81ae2c6f","facadeSource":null,"sources":["packages/normalization-core/src/record-coerce.ts","src/config/channel-config-normalization.ts","src/plugin-sdk/legacy-webhook-listener-migration.ts"]},{"output":".setup/service-DmgP1gPb.mjs","sha256":"36916a546c59602225008bd4dbb4e88482a78f3b4dde9a9239d23f335ad00832","facadeSource":"extensions/acpx/src/service.ts","sources":["extensions/acpx/src/adapter-wrapper-script.ts","extensions/acpx/src/codex-auth-bridge.ts","extensions/acpx/src/codex-trust-config.ts","extensions/acpx/src/model-ref.ts","extensions/acpx/src/process-reaper.ts","extensions/acpx/src/runtime-generations.ts","extensions/acpx/src/runtime-probe.ts","extensions/acpx/src/runtime-process-cleanup.ts","extensions/acpx/src/runtime-session-store.ts","extensions/acpx/src/runtime.ts","extensions/acpx/src/service.ts","extensions/acpx/src/session-owner.ts"]},{"output":".setup/session-owner-migration-CQA7L68K.mjs","sha256":"26ed540907ae4bed933ec1c0c7211e8a3d5225ed17385bf047cf597a2c83c836","facadeSource":"extensions/acpx/src/session-owner-migration.ts","sources":["extensions/acpx/src/process-lease.ts","extensions/acpx/src/session-owner-migration.ts","extensions/acpx/src/state.ts"]},{"output":".setup/session-resource-D_tXKvcv.mjs","sha256":"dc4ea50fd410b0dadaf6c5fe5924a7e95d4c109d3128825d5bf999b668ac52f2","facadeSource":null,"sources":["extensions/acpx/src/session-resource.ts"]},{"output":"doctor-contract-api.js","sha256":"b93f9058efbf3d385e9a5168c563e68cdcb6caecf6e7e9fc4d15f7da0bb75070","facadeSource":"extensions/acpx/doctor-contract-api.ts","sources":["extensions/acpx/doctor-contract-api.ts"]},{"output":"index.js","sha256":"6a9615e8a9892102569672a50c1e63b6594b8edebe0f6ba9f286053af1b45399","facadeSource":"extensions/acpx/index.ts","sources":["extensions/acpx/index.ts","extensions/acpx/src/harness.ts","extensions/acpx/src/native-agents.ts","extensions/acpx/src/pi-session-catalog-plugin.ts","extensions/acpx/src/runtime-proxy.ts"]},{"output":"runtime-api.js","sha256":"fc9734d9dfabafe7281fca6ede1415215a44ac03bd0aa798fce919d11ae68605","facadeSource":"extensions/acpx/runtime-api.ts","sources":[]},{"output":"setup-api.js","sha256":"8251d1074687501cbbb6aee52f51d74113118f5c93570733c3a2544f9beeac31","facadeSource":"extensions/acpx/setup-api.ts","sources":["extensions/acpx/setup-api.ts"]}],"unrenderedSources":["extensions/acpx/runtime-api.ts"]}

package/dist/doctor-contract-api.js

@@ -21,16 +21,22 @@ function normalizeCompatibilityConfig({ cfg }) {
 		config: cfg,
 		changes: []
 	};
-	const nextConfig = structuredClone(cfg);
-	const nextEntry = (0, runtime_doctor_migrations_exports.asObjectRecord)(nextConfig.plugins?.entries?.acpx);
-	const nextPluginConfig = (0, runtime_doctor_migrations_exports.asObjectRecord)(nextEntry?.config);
-	if (!nextPluginConfig) return {
-		config: cfg,
-		changes: []
-	};
+	const nextPluginConfig = { ...pluginConfig };
 	for (const key of retiredKeys) delete nextPluginConfig[key];
 	return {
-		config: nextConfig,
+		config: {
+			...cfg,
+			plugins: {
+				...cfg.plugins,
+				entries: {
+					...cfg.plugins?.entries,
+					acpx: {
+						...entry,
+						config: nextPluginConfig
+					}
+				}
+			}
+		},
 		changes: [`Removed retired ACPX plugin config: ${retiredKeys.map((key) => [...ACPX_CONFIG_PATH, key].join(".")).join(", ")}.`]
 	};
 }
@@ -40,13 +46,13 @@ const stateMigrations = [{
 	doctorOnly: true,
 	phase: "after-session-repair",
 	async collectBackupResources(input) {
-		return (await import("./.setup/session-owner-migration-WmiXoSmh.mjs")).acpxSessionOwnerMigration.collectBackupResources(input);
+		return (await import("./.setup/session-owner-migration-CQA7L68K.mjs")).acpxSessionOwnerMigration.collectBackupResources(input);
 	},
 	async detectLegacyState(input) {
-		return (await import("./.setup/session-owner-migration-WmiXoSmh.mjs")).acpxSessionOwnerMigration.detectLegacyState(input);
+		return (await import("./.setup/session-owner-migration-CQA7L68K.mjs")).acpxSessionOwnerMigration.detectLegacyState(input);
 	},
 	async migrateLegacyState(input) {
-		return (await import("./.setup/session-owner-migration-WmiXoSmh.mjs")).acpxSessionOwnerMigration.migrateLegacyState(input);
+		return (await import("./.setup/session-owner-migration-CQA7L68K.mjs")).acpxSessionOwnerMigration.migrateLegacyState(input);
 	}
 }];
 export { legacyConfigRules, normalizeCompatibilityConfig, stateMigrations };

package/dist/index.js

@@ -1,9 +1,8 @@
-import { t as createAcpxRuntimeService } from "./.setup/register.runtime-CSJY10FS.mjs";
-import { g as AcpxNativeAgentsSchema, h as ACPX_NATIVE_AGENT_IDS, t as resolveAcpxPluginConfig } from "./.setup/config-CE-ej7LM.mjs";
-import { a as PI_SESSIONS_CAPABILITY, c as PI_SESSION_READ_COMMAND, l as PI_TERMINAL_RESUME_COMMAND, o as PI_SESSIONS_LIST_COMMAND, r as piSessionStoreAvailable, s as PI_SESSION_ID_PATTERN } from "./.setup/pi-session-paths-Co5515li.mjs";
+import { g as AcpxNativeAgentsSchema, h as ACPX_NATIVE_AGENT_IDS, t as resolveAcpxPluginConfig } from "./.setup/config-Cplh34lQ.mjs";
+import { a as PI_SESSIONS_CAPABILITY, c as PI_SESSION_READ_COMMAND, l as PI_TERMINAL_RESUME_COMMAND, o as PI_SESSIONS_LIST_COMMAND, r as piSessionStoreAvailable, s as PI_SESSION_ID_PATTERN } from "./.setup/pi-session-paths-pUr6hnVA.mjs";
 import { createAgentRegistry } from "acpx/agent-registry";
-import { tryDispatchAcpReplyHook } from "openclaw/plugin-sdk/acp-runtime-backend";
-import { createLazyRuntimeModule, createLazyRuntimeSurface } from "openclaw/plugin-sdk/lazy-runtime";
+import { getAcpRuntimeBackend, registerAcpRuntimeBackend, requireAcpRuntimeBackend, tryDispatchAcpReplyHook, unregisterAcpRuntimeBackend } from "openclaw/plugin-sdk/acp-runtime-backend";
+import { createLazyRuntimeMethodBinder, createLazyRuntimeModule, createLazyRuntimeSurface } from "openclaw/plugin-sdk/lazy-runtime";
 import { finiteSecondsToTimerSafeMilliseconds } from "openclaw/plugin-sdk/number-runtime";
 import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { resolveNodeHostExecutable } from "openclaw/plugin-sdk/node-host";
@@ -168,6 +167,8 @@ function createAcpAgentHarness(params) {
 					agentCommand: inspection.launch.argv,
 					cwd: input.workspaceDir ?? config.cwd,
 					signal: generation.signal,
+					agentProcessEnvAllow: config.agentProcessEnvAllow,
+					agentProcessEnvBlock: config.agentProcessEnvBlock,
 					timeoutMs: config.timeoutSeconds === void 0 ? void 0 : finiteSecondsToTimerSafeMilliseconds(config.timeoutSeconds) ?? 1
 				});
 				generation.signal.throwIfAborted();
@@ -203,7 +204,7 @@ function createAcpAgentHarness(params) {
 			if (inspection?.launch.kind !== "installed") throw new Error(`${params.label} is not installed; refresh the model catalog`);
 			const runtime = await runtimeFor(input.workspaceDir);
 			generation.signal.throwIfAborted();
-			const { runAcpHarnessAttempt } = await import("./.setup/harness-attempt-Bgcm-zBR.mjs");
+			const { runAcpHarnessAttempt } = await import("./.setup/harness-attempt-Co9oLpPg.mjs");
 			return await runAcpHarnessAttempt({
 				input,
 				runtime,
@@ -244,7 +245,7 @@ function createAcpAgentHarness(params) {
 	};
 }
 // extensions/acpx/src/pi-session-catalog-plugin.ts
-const loadPiSessionCatalogModule = createLazyRuntimeModule(() => import("./.setup/pi-session-catalog-runtime-Cdf46b05.mjs"));
+const loadPiSessionCatalogModule = createLazyRuntimeModule(() => import("./.setup/pi-session-catalog-runtime-DgzkbadO.mjs"));
 function fullConfigCatalogEnabled(config) {
 	if (!isRecord(config) || !isRecord(config.plugins) || !isRecord(config.plugins.entries)) return true;
 	const entry = config.plugins.entries.acpx;
@@ -306,22 +307,210 @@ function registerPiSessionCatalog(api) {
 	for (const command of nodeHost.commands) api.registerNodeHostCommand(command);
 	for (const policy of nodeHost.policies) api.registerNodeInvokePolicy(policy);
 }
+// extensions/acpx/src/runtime-proxy.ts
+/** Start an ACP turn through a lazy runtime resolver without awaiting resolution up front. */
+function lazyStartRuntimeTurn(resolveRuntime, input) {
+	const turnPromise = resolveRuntime().then((runtime) => runtime.startTurn(input));
+	return {
+		requestId: input.requestId,
+		get promptStarted() {
+			return turnPromise.then((turn) => turn.promptStarted);
+		},
+		events: { async *[Symbol.asyncIterator]() {
+			yield* (await turnPromise).events;
+		} },
+		result: turnPromise.then((turn) => turn.result),
+		cancel(inputArgs) {
+			return turnPromise.then((turn) => turn.cancel(inputArgs));
+		},
+		closeStream(inputArgs) {
+			return turnPromise.then((turn) => turn.closeStream(inputArgs));
+		}
+	};
+}
+/** Create an ACP runtime facade backed by an async runtime resolver. */
+function createLazyAcpRuntimeProxy(resolveRuntime) {
+	const bind = createLazyRuntimeMethodBinder(resolveRuntime);
+	return {
+		ownerAwareSessions: 1,
+		findSession: bind((runtime) => runtime.findSession.bind(runtime)),
+		shutdown: bind((runtime) => runtime.shutdown.bind(runtime)),
+		ensureSession: bind((runtime) => runtime.ensureSession.bind(runtime)),
+		startTurn(input) {
+			return lazyStartRuntimeTurn(resolveRuntime, input);
+		},
+		async *runTurn(input) {
+			yield* (await resolveRuntime()).runTurn(input);
+		},
+		getCapabilities: bind((runtime) => runtime.getCapabilities.bind(runtime)),
+		getStatus: bind((runtime) => runtime.getStatus.bind(runtime)),
+		setMode: bind((runtime) => runtime.setMode.bind(runtime)),
+		setModel: bind((runtime) => runtime.setModel.bind(runtime)),
+		setConfigOption: bind((runtime) => runtime.setConfigOption.bind(runtime)),
+		doctor: bind((runtime) => runtime.doctor.bind(runtime)),
+		prepareFreshSession: bind((runtime) => runtime.prepareFreshSession.bind(runtime)),
+		cancel: bind((runtime) => runtime.cancel.bind(runtime)),
+		close: bind((runtime) => runtime.close.bind(runtime))
+	};
+}
 // 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 ACPX_BACKEND_ID = "acpx";
+const loadServiceModule = createLazyRuntimeModule(() => import("./.setup/service-DmgP1gPb.mjs"));
+function unregisterOwnedRuntime(runtime) {
+	if (runtime && getAcpRuntimeBackend(ACPX_BACKEND_ID)?.runtime === runtime) unregisterAcpRuntimeBackend(ACPX_BACKEND_ID);
+}
 const plugin = {
 	id: "acpx",
 	name: "ACPX Runtime",
 	description: "Embedded ACP runtime backend with plugin-owned session and transport management.",
 	register(api) {
 		registerPiSessionCatalog(api);
-		const service = createAcpxRuntimeService({
-			pluginConfig: api.pluginConfig,
-			getAllowedAgents: () => api.runtime.config.current().acp?.allowedAgents,
-			openKeyedStore: (options) => api.runtime.state.openKeyedStoreV2(options)
-		});
+		const pluginConfig = api.pluginConfig;
+		let ctx = null;
+		let published = false;
+		let lifecycleRevision = 0;
+		let ownedRuntime = null;
+		let realService = null;
+		let startPromise = null;
+		let stopPromise = null;
+		async function startRealService(expectedRevision, deferredRuntime, purpose = "gateway", probeAtStartup = purpose === "gateway") {
+			if (lifecycleRevision !== expectedRevision || !ctx) throw new Error("ACPX runtime service is not started");
+			if (startPromise) return await startPromise;
+			const activeContext = ctx;
+			let starting = true;
+			startPromise = (async () => {
+				let publishedRuntime = null;
+				const { createAcpxRuntimeService: createAcpxRuntimeServiceLocal } = await loadServiceModule();
+				const activeService = createAcpxRuntimeServiceLocal({
+					pluginConfig,
+					getAllowedAgents: () => api.runtime.config.current().acp?.allowedAgents,
+					openKeyedStore: (options) => api.runtime.state.openKeyedStoreV2(options),
+					probeAtStartup,
+					startupPurpose: purpose,
+					assertCurrent: () => {
+						if (lifecycleRevision !== expectedRevision || ctx !== activeContext || published && getAcpRuntimeBackend(ACPX_BACKEND_ID)?.runtime !== ownedRuntime) throw new Error("ACPX runtime service lost recovery ownership");
+					},
+					backendLifecycle: {
+						publish(backend) {
+							if (lifecycleRevision !== expectedRevision || ctx !== activeContext) throw new Error("ACPX runtime service stopped during activation");
+							if (published && getAcpRuntimeBackend(ACPX_BACKEND_ID)?.runtime !== deferredRuntime) throw new Error("ACPX runtime service lost registry ownership during activation");
+							if (published) {
+								const { healthy } = backend;
+								registerAcpRuntimeBackend({
+									id: ACPX_BACKEND_ID,
+									...backend,
+									runtime: deferredRuntime,
+									...healthy ? { healthy: () => starting || healthy() } : {}
+								});
+							}
+							publishedRuntime = backend.runtime;
+						},
+						retract() {}
+					}
+				});
+				realService = activeService;
+				await activeService.start(activeContext);
+				if (lifecycleRevision !== expectedRevision || ctx !== activeContext) throw new Error("ACPX runtime service stopped during activation");
+				if (!publishedRuntime) throw new Error("ACPX runtime service did not register an ACP backend");
+				if (published && getAcpRuntimeBackend(ACPX_BACKEND_ID)?.runtime !== deferredRuntime) throw new Error("ACPX runtime service lost registry ownership during activation");
+				return publishedRuntime;
+			})().finally(() => {
+				starting = false;
+			});
+			try {
+				return await startPromise;
+			} catch (error) {
+				if (lifecycleRevision === expectedRevision) {
+					startPromise = null;
+					realService = null;
+				}
+				throw error;
+			}
+		}
+		function createDeferredRuntime(expectedRevision) {
+			const deferredRuntime = {
+				...createLazyAcpRuntimeProxy(() => startRealService(expectedRevision, deferredRuntime)),
+				async ensureSession(input) {
+					const runtime = await startRealService(expectedRevision, deferredRuntime);
+					requireAcpRuntimeBackend(ACPX_BACKEND_ID);
+					return await runtime.ensureSession(input);
+				}
+			};
+			return deferredRuntime;
+		}
+		const service = {
+			id: "acpx-runtime",
+			async getRuntime(serviceContext) {
+				if (stopPromise) await stopPromise;
+				if (!ctx) {
+					ctx = serviceContext;
+					lifecycleRevision += 1;
+					ownedRuntime = createDeferredRuntime(lifecycleRevision);
+				}
+				if (!ownedRuntime) throw new Error("ACPX runtime service lost its runtime owner");
+				return await startRealService(lifecycleRevision, ownedRuntime, published ? "gateway" : "inspection", false);
+			},
+			async start(serviceContext) {
+				if (process.env.OPENCLAW_SKIP_ACPX_RUNTIME === "1") {
+					serviceContext.logger.info("skipping embedded acpx runtime backend (OPENCLAW_SKIP_ACPX_RUNTIME=1)");
+					return;
+				}
+				if (stopPromise) await stopPromise;
+				if (ctx && ownedRuntime) {
+					const revision = lifecycleRevision;
+					const previous = getAcpRuntimeBackend(ACPX_BACKEND_ID)?.runtime;
+					const assertCurrent = () => {
+						const current = getAcpRuntimeBackend(ACPX_BACKEND_ID)?.runtime;
+						if (lifecycleRevision !== revision || !ctx || current !== previous && current !== ownedRuntime) throw new Error("ACPX runtime service lost promotion ownership");
+					};
+					await startPromise;
+					assertCurrent();
+					await realService?.promote(serviceContext, assertCurrent);
+					assertCurrent();
+					published = true;
+					registerAcpRuntimeBackend({
+						id: ACPX_BACKEND_ID,
+						runtime: ownedRuntime
+					});
+					return;
+				}
+				published = true;
+				lifecycleRevision += 1;
+				ctx = serviceContext;
+				const deferredRuntime = createDeferredRuntime(lifecycleRevision);
+				ownedRuntime = deferredRuntime;
+				registerAcpRuntimeBackend({
+					id: ACPX_BACKEND_ID,
+					runtime: deferredRuntime
+				});
+				serviceContext.logger.info("embedded acpx runtime backend registered lazily");
+			},
+			async stop(serviceContext) {
+				if (stopPromise) return await stopPromise;
+				lifecycleRevision += 1;
+				ctx = null;
+				published = false;
+				const stoppingRuntime = ownedRuntime;
+				unregisterOwnedRuntime(stoppingRuntime);
+				const startingPromise = startPromise;
+				stopPromise = (async () => {
+					await startingPromise?.catch(() => void 0);
+					try {
+						await realService?.stop?.(serviceContext);
+					} finally {
+						unregisterOwnedRuntime(stoppingRuntime);
+						ownedRuntime = null;
+						realService = null;
+						startPromise = null;
+					}
+				})();
+				try {
+					await stopPromise;
+				} finally {
+					stopPromise = null;
+				}
+			}
+		};
 		api.registerService(service);
 		const currentConfig = () => api.runtime.config.current().plugins?.entries?.acpx?.config;
 		const registry = createAgentRegistry();
@@ -334,11 +523,7 @@ const plugin = {
 				isEnabled: () => isAcpxNativeAgentEnabled(currentConfig()?.nativeAgents, agentId),
 				api,
 				getRuntime: service.getRuntime,
-				shutdown: () => service.stop?.({
-					config: api.config,
-					stateDir: api.runtime.state.resolveStateDir(),
-					logger: api.logger
-				})
+				shutdown: () => stopPromise ?? (ctx ? service.stop?.(ctx) : void 0)
 			}));
 			return {
 				id: agentId,

package/openclaw.plugin.json

@@ -36,7 +36,16 @@
       "id": "agent-runtime",
       "title": "Agent runtime",
       "order": 10,
-      "properties": ["cwd", "stateDir", "probeAgent", "agents", "timeoutSeconds", "nativeAgents"]
+      "properties": [
+        "cwd",
+        "stateDir",
+        "probeAgent",
+        "agents",
+        "timeoutSeconds",
+        "nativeAgents",
+        "agentProcessEnvAllow",
+        "agentProcessEnvBlock"
+      ]
     },
     {
       "id": "permissions",
@@ -92,6 +101,14 @@
         "minimum": 0.001,
         "default": 120
       },
+      "agentProcessEnvAllow": {
+        "type": "array",
+        "items": { "type": "string", "pattern": "^[^=\\s]+$" }
+      },
+      "agentProcessEnvBlock": {
+        "type": "array",
+        "items": { "type": "string", "pattern": "^[^=\\s]+$" }
+      },
       "piSessionCatalog": {
         "type": "object",
         "additionalProperties": false,
@@ -189,6 +206,16 @@
       "help": "Timeout for embedded ACP runtime startup and control operations. ACP turns use OpenClaw agent/run timeouts.",
       "advanced": true
     },
+    "agentProcessEnvAllow": {
+      "label": "Agent Environment Allowlist",
+      "help": "Default unset (agents inherit the Gateway environment). When set, ACP agents, their command probes, and terminals inherit only process essentials (PATH, HOME, locale, temp, XDG_*), these names, and ACPX_AUTH_* grants.",
+      "advanced": true
+    },
+    "agentProcessEnvBlock": {
+      "label": "Agent Environment Blocklist",
+      "help": "Default unset. Gateway environment variable names that ACP agents, their command probes, and terminals do not inherit, for example OPENCLAW_GATEWAY_TOKEN. Applied after the allowlist; explicit grants such as ACPX_AUTH_* still apply.",
+      "advanced": true
+    },
     "piSessionCatalog.enabled": {
       "label": "Pi Session Catalog",
       "help": "Auto-detect Pi sessions on the Gateway and paired nodes, then show them in the sessions sidebar."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/acpx",
-  "version": "2026.10.10",
+  "version": "2026.11.5-beta.1",
   "description": "OpenClaw ACP runtime backend with plugin-owned session and transport management.",
   "repository": {
     "type": "git",
@@ -9,11 +9,11 @@
   "type": "module",
   "dependencies": {
     "@agentclientprotocol/claude-agent-acp": "0.95.0",
-    "@agentclientprotocol/codex-acp": "2.1.1",
-    "@openclaw/fs-safe": "0.26.5",
-    "acpx": "0.19.4",
-    "smol-toml": "1.9.0",
-    "zod": "4.6.5"
+    "@agentclientprotocol/codex-acp": "2.2.2",
+    "@openclaw/fs-safe": "0.26.13",
+    "acpx": "0.21.0",
+    "smol-toml": "1.9.1",
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@openclaw/plugin-sdk": "workspace:*"
@@ -45,10 +45,10 @@
       ]
     },
     "compat": {
-      "pluginApi": ">=2026.10.10"
+      "pluginApi": ">=2026.11.5-beta.1"
     },
     "build": {
-      "openclawVersion": "2026.10.10"
+      "openclawVersion": "2026.11.5-beta.1"
     },
     "release": {
       "publishToClawHub": true,
@@ -68,7 +68,7 @@
     "skills/**"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.10.10"
+    "openclaw": ">=2026.11.5-beta.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {