@openclaw/acpx 2026.8.1 → 2026.8.2

package/dist/config-v8M2tNu6.js

@@ -0,0 +1,185 @@
+import { t as AcpxPluginConfigSchema } from "./config-schema-DN_uAi4R.js";
+import { createRequire } from "node:module";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { formatPluginConfigIssue } from "openclaw/plugin-sdk/extension-shared";
+//#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 = createRequire(import.meta.url);
+function isAcpxPluginRoot(dir) {
+	return fs.existsSync(path.join(dir, "openclaw.plugin.json")) && fs.existsSync(path.join(dir, "package.json"));
+}
+function resolveNearestAcpxPluginRoot(moduleUrl) {
+	let cursor = path.dirname(fileURLToPath(moduleUrl));
+	for (let i = 0; i < 3; i += 1) {
+		if (isAcpxPluginRoot(cursor)) return cursor;
+		const parent = path.dirname(cursor);
+		if (parent === cursor) break;
+		cursor = parent;
+	}
+	return path.resolve(path.dirname(fileURLToPath(moduleUrl)), "..");
+}
+function resolveWorkspaceAcpxPluginRoot(currentRoot) {
+	if (path.basename(currentRoot) !== "acpx" || path.basename(path.dirname(currentRoot)) !== "extensions" || path.basename(path.dirname(path.dirname(currentRoot))) !== "dist") return null;
+	const workspaceRoot = path.resolve(currentRoot, "..", "..", "..", "extensions", "acpx");
+	return isAcpxPluginRoot(workspaceRoot) ? workspaceRoot : null;
+}
+function resolveRepoAcpxPluginRoot(currentRoot) {
+	const workspaceRoot = path.join(currentRoot, "extensions", "acpx");
+	return isAcpxPluginRoot(workspaceRoot) ? workspaceRoot : null;
+}
+function resolveAcpxPluginRootFromOpenClawLayout(moduleUrl) {
+	let cursor = path.dirname(fileURLToPath(moduleUrl));
+	for (let i = 0; i < 5; i += 1) {
+		const candidates = [
+			path.join(cursor, "extensions", "acpx"),
+			path.join(cursor, "dist", "extensions", "acpx"),
+			path.join(cursor, "dist-runtime", "extensions", "acpx")
+		];
+		for (const candidate of candidates) if (isAcpxPluginRoot(candidate)) return candidate;
+		const parent = path.dirname(cursor);
+		if (parent === cursor) break;
+		cursor = parent;
+	}
+	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;
+}
+const DEFAULT_PERMISSION_MODE = "approve-reads";
+const DEFAULT_NON_INTERACTIVE_POLICY = "fail";
+function parseAcpxPluginConfig(value) {
+	if (value === void 0) return {
+		ok: true,
+		value: void 0
+	};
+	const parsed = AcpxPluginConfigSchema.safeParse(value);
+	if (!parsed.success) return {
+		ok: false,
+		message: formatPluginConfigIssue(parsed.error.issues[0])
+	};
+	return {
+		ok: true,
+		value: parsed.data
+	};
+}
+function resolveOpenClawRoot(currentRoot) {
+	if (path.basename(currentRoot) === "acpx" && path.basename(path.dirname(currentRoot)) === "extensions") {
+		const parent = path.dirname(path.dirname(currentRoot));
+		if (path.basename(parent) === "dist") return path.dirname(parent);
+		return parent;
+	}
+	return path.resolve(currentRoot, "..");
+}
+function resolveTsxImportSpecifier() {
+	try {
+		return requireFromHere.resolve("tsx");
+	} catch {
+		return "tsx";
+	}
+}
+function shellQuoteCommandArg(arg) {
+	if (!/[\s'"\\$|&;<>{}()*?[\]~`]/.test(arg)) return arg;
+	return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+}
+function resolvePluginToolsMcpServerConfig(moduleUrl = import.meta.url) {
+	const openClawRoot = resolveOpenClawRoot(resolveAcpxPluginRoot(moduleUrl));
+	const distEntry = path.join(openClawRoot, "dist", "mcp", "plugin-tools-serve.js");
+	if (fs.existsSync(distEntry)) return {
+		command: process.execPath,
+		args: [distEntry]
+	};
+	const sourceEntry = path.join(openClawRoot, "src", "mcp", "plugin-tools-serve.ts");
+	return {
+		command: process.execPath,
+		args: [
+			"--import",
+			resolveTsxImportSpecifier(),
+			sourceEntry
+		]
+	};
+}
+function resolveOpenClawToolsMcpServerConfig(moduleUrl = import.meta.url) {
+	const openClawRoot = resolveOpenClawRoot(resolveAcpxPluginRoot(moduleUrl));
+	const distEntry = path.join(openClawRoot, "dist", "mcp", "openclaw-tools-serve.js");
+	if (fs.existsSync(distEntry)) return {
+		command: process.execPath,
+		args: [distEntry]
+	};
+	const sourceEntry = path.join(openClawRoot, "src", "mcp", "openclaw-tools-serve.ts");
+	return {
+		command: process.execPath,
+		args: [
+			"--import",
+			resolveTsxImportSpecifier(),
+			sourceEntry
+		]
+	};
+}
+function resolveConfiguredMcpServers(params) {
+	const resolved = { ...params.mcpServers };
+	if (params.pluginToolsMcpBridge && resolved[ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME]) throw new Error(`mcpServers.${ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME} is reserved when pluginToolsMcpBridge=true`);
+	if (params.openClawToolsMcpBridge && resolved[ACPX_OPENCLAW_TOOLS_MCP_SERVER_NAME]) throw new Error(`mcpServers.${ACPX_OPENCLAW_TOOLS_MCP_SERVER_NAME} is reserved when openClawToolsMcpBridge=true`);
+	if (params.pluginToolsMcpBridge) resolved[ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME] = resolvePluginToolsMcpServerConfig(params.moduleUrl);
+	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,
+		command: server.command,
+		args: [...server.args ?? []],
+		env: Object.entries(server.env ?? {}).map(([envName, value]) => ({
+			name: envName,
+			value
+		}))
+	}));
+}
+/** 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);
+	const normalized = parsed.value ?? {};
+	const workspaceDir = params.workspaceDir?.trim() || process.cwd();
+	const fallbackCwd = workspaceDir;
+	const cwd = path.resolve(normalized.cwd?.trim() || fallbackCwd);
+	const stateDir = path.resolve(normalized.stateDir?.trim() || path.join(workspaceDir, "state"));
+	const pluginToolsMcpBridge = normalized.pluginToolsMcpBridge === true;
+	const openClawToolsMcpBridge = normalized.openClawToolsMcpBridge === true;
+	const mcpServers = resolveConfiguredMcpServers({
+		mcpServers: normalized.mcpServers,
+		pluginToolsMcpBridge,
+		openClawToolsMcpBridge,
+		moduleUrl: params.moduleUrl
+	});
+	const agents = Object.fromEntries(Object.entries(normalized.agents ?? {}).map(([name, entry]) => {
+		const cmd = entry.command.trim();
+		const cmdArgs = entry.args ?? [];
+		const fullCommand = cmdArgs.length > 0 ? `${cmd} ${cmdArgs.map(shellQuoteCommandArg).join(" ")}` : cmd;
+		return [normalizeLowercaseStringOrEmpty(name), fullCommand];
+	}));
+	return {
+		cwd,
+		stateDir,
+		probeAgent: normalized.probeAgent,
+		permissionMode: normalized.permissionMode ?? DEFAULT_PERMISSION_MODE,
+		nonInteractivePermissions: normalized.nonInteractivePermissions ?? DEFAULT_NON_INTERACTIVE_POLICY,
+		pluginToolsMcpBridge,
+		openClawToolsMcpBridge,
+		timeoutSeconds: normalized.timeoutSeconds ?? 120,
+		mcpServers,
+		agents
+	};
+}
+//#endregion
+export { resolveAcpxPluginRoot as n, toAcpMcpServers as r, resolveAcpxPluginConfig as t };

package/dist/doctor-contract-api.js

@@ -17,14 +17,16 @@ const legacyConfigRules = RETIRED_ACPX_CONFIG_KEYS.map((key) => ({
 }));
 /** Removes retired plugin-owned config without keeping runtime compatibility keys. */
 function normalizeCompatibilityConfig({ cfg }) {
-	const pluginConfig = asObjectRecord(asObjectRecord(cfg.plugins?.entries?.acpx)?.config);
+	const entry = asObjectRecord(cfg.plugins?.entries?.acpx);
+	const pluginConfig = asObjectRecord(entry?.config);
 	const retiredKeys = RETIRED_ACPX_CONFIG_KEYS.filter((key) => Object.hasOwn(pluginConfig ?? {}, key));
 	if (!pluginConfig || retiredKeys.length === 0) return {
 		config: cfg,
 		changes: []
 	};
 	const nextConfig = structuredClone(cfg);
-	const nextPluginConfig = asObjectRecord(asObjectRecord(nextConfig.plugins?.entries?.acpx)?.config);
+	const nextEntry = asObjectRecord(nextConfig.plugins?.entries?.acpx);
+	const nextPluginConfig = asObjectRecord(nextEntry?.config);
 	if (!nextPluginConfig) return {
 		config: cfg,
 		changes: []
@@ -129,6 +131,17 @@ const stateMigrations = [{
 			warnings
 		};
 	}
+}, {
+	id: "acpx-session-owner-resources",
+	label: "ACP session owners",
+	doctorOnly: true,
+	phase: "after-session-repair",
+	async detectLegacyState(input) {
+		return (await import("./session-owner-migration-Dt5yf0xJ.js")).acpxSessionOwnerMigration.detectLegacyState(input);
+	},
+	async migrateLegacyState(input) {
+		return (await import("./session-owner-migration-Dt5yf0xJ.js")).acpxSessionOwnerMigration.migrateLegacyState(input);
+	}
 }];
 //#endregion
 export { legacyConfigRules, normalizeCompatibilityConfig, stateMigrations };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { t as createAcpxRuntimeService } from "./register.runtime-DFRkXzZ_.js";
+import { t as createAcpxRuntimeService } from "./register.runtime-BHFSFWWK.js";
 import "./config-schema-DN_uAi4R.js";
 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 "./pi-session-paths-EMbd4Hkz.js";
 import { tryDispatchAcpReplyHook } from "openclaw/plugin-sdk/acp-runtime-backend";
@@ -8,7 +8,7 @@ import { resolveNodeHostExecutable } from "openclaw/plugin-sdk/node-host";
 import { createSessionCatalogNodeHostBindings } from "openclaw/plugin-sdk/session-catalog";
 import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
 //#region extensions/acpx/src/pi-session-catalog-plugin.ts
-const loadPiSessionCatalogModule = createLazyRuntimeModule(() => import("./pi-session-catalog-runtime-g6A6ADEf.js"));
+const loadPiSessionCatalogModule = createLazyRuntimeModule(() => import("./pi-session-catalog-runtime-C0HodUWT.js"));
 function fullConfigCatalogEnabled(config) {
 	if (!isRecord(config) || !isRecord(config.plugins) || !isRecord(config.plugins.entries)) return true;
 	const entry = config.plugins.entries.acpx;

package/dist/{pi-session-catalog-runtime-g6A6ADEf.js → pi-session-catalog-runtime-C0HodUWT.js}

@@ -22,9 +22,9 @@ function parsePiSessionTimestampMs(value) {
 const MAX_DISCOVERY_FILES = 1e4;
 const SUMMARY_SCAN_BATCH_SIZE = 100;
 const MAX_SUMMARY_CACHE_ENTRIES = 256;
-const MAX_SESSION_BYTES = 32 * 1024 * 1024;
-const MAX_SUMMARY_LINE_BYTES = 1024 * 1024;
-const APPEND_PROOF_EDGE_BYTES = 64 * 1024;
+const MAX_SESSION_BYTES = 33554432;
+const MAX_SUMMARY_LINE_BYTES = 1048576;
+const APPEND_PROOF_EDGE_BYTES = 65536;
 const IO_CONCURRENCY = 8;
 const PI_FILE_CANDIDATE_CACHE_TTL_MS = 32e3;
 const PI_FILE_CANDIDATE_CACHE_MAX_ENTRIES = 8;
@@ -316,8 +316,9 @@ async function listPiSummaryPage(env, params) {
 	const matches = [];
 	const needle = params.searchTerm?.toLocaleLowerCase();
 	for (let index = 0; index < candidates.length && matches.length < target; index += SUMMARY_SCAN_BATCH_SIZE) {
+		const batch = candidates.slice(index, index + SUMMARY_SCAN_BATCH_SIZE);
 		const { results: summaries } = await runTasksWithConcurrency({
-			tasks: candidates.slice(index, index + SUMMARY_SCAN_BATCH_SIZE).map((candidate) => () => readPiSessionSummary(candidate)),
+			tasks: batch.map((candidate) => () => readPiSessionSummary(candidate)),
 			limit: IO_CONCURRENCY,
 			throwOnError: true
 		});
@@ -584,7 +585,7 @@ async function readLocalPiTranscriptPage(value) {
 }
 //#endregion
 //#region extensions/acpx/src/pi-session-upstream-activity.ts
-const MAX_PI_UPSTREAM_SCAN_BYTES = 1024 * 1024;
+const MAX_PI_UPSTREAM_SCAN_BYTES = 1048576;
 async function readFileRange(handle, position, length) {
 	const buffer = Buffer.alloc(length);
 	let offset = 0;
@@ -671,7 +672,8 @@ async function checkPiSessionUpstreamActivity(probe) {
 		let occurredAt;
 		for (const entry of entries) {
 			if (entry.type !== "message" || !isRecord(entry.message) || entry.message.role !== "user") continue;
-			if (!isExternalUserText(probe, textFromContent(entry.message.content))) continue;
+			const text = textFromContent(entry.message.content);
+			if (!isExternalUserText(probe, text)) continue;
 			humanTurns += 1;
 			occurredAt = Math.max(occurredAt ?? 0, parsePiSessionTimestampMs(entry.message.timestamp) ?? parsePiSessionTimestampMs(entry.timestamp) ?? stat.mtimeMs);
 		}

package/dist/{register.runtime-DFRkXzZ_.js → register.runtime-BHFSFWWK.js}

@@ -24,6 +24,7 @@ function lazyStartRuntimeTurn(resolveRuntime, input) {
 /** Create an ACP runtime facade backed by an async runtime resolver. */
 function createLazyAcpRuntimeProxy(resolveRuntime) {
 	return {
+		ownerAwareSessions: 1,
 		async ensureSession(input) {
 			return await (await resolveRuntime()).ensureSession(input);
 		},
@@ -66,7 +67,7 @@ function createLazyAcpRuntimeProxy(resolveRuntime) {
 * immediately, then imports the heavier service only when a session needs it.
 */
 const ACPX_BACKEND_ID = "acpx";
-const loadServiceModule = createLazyRuntimeModule(() => import("./service-BFWEiHbQ.js"));
+const loadServiceModule = createLazyRuntimeModule(() => import("./service-DLjjP2kv.js").then((n) => n.t));
 function unregisterOwnedRuntime(runtime) {
 	if (runtime && getAcpRuntimeBackend(ACPX_BACKEND_ID)?.runtime === runtime) unregisterAcpRuntimeBackend(ACPX_BACKEND_ID);
 }

package/dist/register.runtime.js

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

package/dist/{runtime-mnaLaFBR.js → runtime-D47jdCKR.js}

@@ -1,14 +1,45 @@
 import { d as withAcpxLeaseEnvironment, i as createAcpxProcessLeaseId, o as hashAcpxProcessCommand, t as ACPX_PROBE_LEASE_SESSION_KEY, u as readAcpxProcessLeaseIdentity, v as splitCommandParts } from "./process-lease-Cwvj7WGe.js";
 import { AcpRuntimeError } from "./runtime-api.js";
-import { d as OPENCLAW_CODEX_CONFIG_ARG, l as CODEX_ACP_PACKAGE, n as cleanupOpenClawOwnedAcpxProcessTree, r as isOpenClawLeaseAwareAcpxProcessCommand, t as cleanupOpenClawOwnedAcpxPendingLease } from "./process-reaper-DduWm_7N.js";
+import { t as resolveAcpxSessionResource } from "./session-resource-CRWvFl2-.js";
+import { a as CODEX_ACP_PACKAGE, i as isOpenClawLeaseAwareAcpxProcessCommand, n as cleanupOpenClawOwnedAcpxPendingLease, o as OPENCLAW_CODEX_CONFIG_ARG, r as cleanupOpenClawOwnedAcpxProcessTree } from "./service-DLjjP2kv.js";
 import { parseStrictPositiveInteger } from "openclaw/plugin-sdk/number-runtime";
 import { normalizeStringEntries } from "openclaw/plugin-sdk/string-coerce-runtime";
 import path, { resolve } from "node:path";
 import fs from "node:fs/promises";
 import { sliceUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { ACPX_BACKEND_ID, AcpxRuntime as AcpxRuntime$1, createAcpRuntime, createAgentRegistry, createFileSessionStore, decodeAcpxRuntimeHandleState, encodeAcpxRuntimeHandleState, isRequestedModelUnsupportedError } from "acpx/runtime";
+import { ACPX_BACKEND_ID, AcpxRuntime as AcpxRuntime$1, createAcpRuntime, createAgentRegistry, createFileSessionStore, decodeAcpxRuntimeHandleState, decodeAcpxRuntimeHandleState as decodeAcpxRuntimeHandleState$1, encodeAcpxRuntimeHandleState, isRequestedModelUnsupportedError } from "acpx/runtime";
 import { redactSensitiveText } from "openclaw/plugin-sdk/security-runtime";
+//#region extensions/acpx/src/session-owner.ts
+function requireAcpxOwnerMigration(sessionKey) {
+	throw new AcpRuntimeError("ACP_SESSION_INIT_FAILED", `ACP session "${sessionKey}" has an unqualified or unverifiable backend locator. Stop the Gateway and run "openclaw doctor --fix" to migrate ownership without losing history, then restart.`, { detailCode: "SESSION_OWNER_MIGRATION_REQUIRED" });
+}
+function assertAcpxSessionOwnerLocator(target, legacyBareSessionKeys) {
+	const resource = resolveAcpxSessionResource(target);
+	const qualified = resource === target.sessionKey.trim().toLowerCase();
+	const persisted = target.persistedHandle;
+	if (!qualified && (legacyBareSessionKeys?.has(target.sessionKey.trim().toLowerCase()) || legacyBareSessionKeys?.has(resource) && !persisted)) requireAcpxOwnerMigration(target.sessionKey);
+	if (persisted) {
+		const decoded = decodeAcpxRuntimeHandleState$1(persisted.runtimeSessionName);
+		if (!qualified && !decoded || decoded && (decoded.name !== resource || persisted.acpxRecordId && decoded.acpxRecordId !== persisted.acpxRecordId)) requireAcpxOwnerMigration(target.sessionKey);
+	}
+	return resource;
+}
+/** Preserve physical oneshot record IDs and the upstream-encoded runtime handle. */
+function toAcpxResourceInput(input) {
+	const sessionKey = assertAcpxSessionOwnerLocator({
+		...input.handle,
+		persistedHandle: input.handle
+	});
+	return {
+		...input,
+		handle: {
+			...input.handle,
+			sessionKey
+		}
+	};
+}
+//#endregion
 //#region extensions/acpx/src/runtime.ts
 /**
 * OpenClaw ACPX runtime adapter. It wraps the upstream acpx runtime with
@@ -50,7 +81,8 @@ function isGenericInternalAcpError(error) {
 async function readCodexWrapperStderrTail(params) {
 	if (!params.wrapperRoot || !params.leaseId) return "";
 	try {
-		return compactDiagnosticText(redactSensitiveText(sliceUtf16Safe(await fs.readFile(path.join(params.wrapperRoot, codexWrapperStderrLogFileName(params.leaseId)), "utf8"), -6e3)));
+		const text = await fs.readFile(path.join(params.wrapperRoot, codexWrapperStderrLogFileName(params.leaseId)), "utf8");
+		return compactDiagnosticText(redactSensitiveText(sliceUtf16Safe(text, -6e3)));
 	} catch {
 		return "";
 	}
@@ -427,7 +459,12 @@ function withManagedToolsMcpSessionEnv(params) {
 		}];
 		return {
 			...server,
-			env
+			env,
+			args: params.agentId ? [
+				...server.args,
+				"--openclaw-agent-id",
+				params.agentId
+			] : server.args
 		};
 	});
 	return changed ? nextServers : params.mcpServers;
@@ -435,6 +472,7 @@ function withManagedToolsMcpSessionEnv(params) {
 /** OpenClaw-managed ACP runtime implementation backed by the upstream acpx runtime. */
 var AcpxRuntime = class {
 	constructor(options, testOptions) {
+		this.ownerAwareSessions = 1;
 		this.codexAcpModelOverrideScope = new AsyncLocalStorage();
 		this.managedToolsSessionDelegates = /* @__PURE__ */ new Map();
 		this.launchLeaseScope = new AsyncLocalStorage();
@@ -442,6 +480,7 @@ var AcpxRuntime = class {
 		this.processLeaseTransitionTails = /* @__PURE__ */ new Map();
 		this.processLeaseOperationCounts = /* @__PURE__ */ new Map();
 		this.uncertainProcessLeaseIds = /* @__PURE__ */ new Set();
+		this.legacyBareSessionKeys = new Set(options.openclawLegacyBareSessionKeys);
 		const { openclawProcessCleanup, ...delegateTestOptions } = testOptions ?? {};
 		this.processCleanupDeps = openclawProcessCleanup;
 		this.wrapperRoot = options.openclawWrapperRoot;
@@ -485,12 +524,11 @@ var AcpxRuntime = class {
 	}
 	resolveDelegateForSession(params) {
 		if (shouldUseBridgeSafeDelegateForCommand(params.command)) return this.bridgeSafeDelegate;
-		return this.resolveManagedToolsDelegateForSession(params.sessionKey);
+		return this.resolveManagedToolsDelegateForSession(params);
 	}
-	resolveManagedToolsDelegateForSession(sessionKey) {
+	resolveManagedToolsDelegateForSession(target) {
 		if (!this.managedToolsMcpBridgeEnabled) return this.delegate;
-		const normalizedSessionKey = sessionKey.trim();
-		if (!normalizedSessionKey) return this.delegate;
+		const normalizedSessionKey = resolveAcpxSessionResource(target);
 		const cached = this.managedToolsSessionDelegates.get(normalizedSessionKey);
 		if (cached) return cached;
 		const delegate = new AcpxRuntime$1({
@@ -499,7 +537,8 @@ var AcpxRuntime = class {
 				pluginToolsEnabled: this.pluginToolsMcpBridgeEnabled,
 				openclawToolsEnabled: this.openclawToolsMcpBridgeEnabled,
 				mcpServers: this.delegateOptions.mcpServers,
-				sessionKey: normalizedSessionKey
+				sessionKey: target.sessionKey,
+				agentId: target.agentId
 			})
 		}, this.delegateTestOptions);
 		this.managedToolsSessionDelegates.set(normalizedSessionKey, delegate);
@@ -512,7 +551,11 @@ var AcpxRuntime = class {
 		this.managedToolsSessionDelegates.delete(normalizedSessionKey);
 	}
 	async loadOperationSnapshotForHandle(handle) {
-		const record = await this.sessionStore.load(handle.acpxRecordId ?? handle.sessionKey);
+		assertAcpxSessionOwnerLocator({
+			...handle,
+			persistedHandle: handle
+		}, this.legacyBareSessionKeys);
+		const record = await this.sessionStore.load(handle.acpxRecordId ?? resolveAcpxSessionResource(handle));
 		return {
 			record,
 			command: readAgentCommandFromRecord(record) ?? resolveAgentCommand({
@@ -524,7 +567,8 @@ var AcpxRuntime = class {
 	resolveDelegateForOperationSnapshot(handle, snapshot) {
 		return this.resolveDelegateForSession({
 			command: snapshot.command,
-			sessionKey: handle.sessionKey
+			sessionKey: handle.sessionKey,
+			agentId: handle.agentId
 		});
 	}
 	commandWithLaunchLease(command) {
@@ -623,7 +667,7 @@ var AcpxRuntime = class {
 				await processLeaseStore.save({
 					leaseId: identity.leaseId,
 					gatewayInstanceId: identity.gatewayInstanceId,
-					sessionKey: handle.sessionKey,
+					sessionKey: resolveAcpxSessionResource(handle),
 					wrapperRoot,
 					wrapperPath: extractGeneratedWrapperPath(command),
 					rootPid: recordPid ?? 0,
@@ -633,7 +677,7 @@ var AcpxRuntime = class {
 				});
 				return;
 			}
-			if (existing.gatewayInstanceId !== identity.gatewayInstanceId || existing.sessionKey !== handle.sessionKey || existing.wrapperRoot !== wrapperRoot) throw new AcpRuntimeError("ACP_TURN_FAILED", `ACPX process lease ${identity.leaseId} belongs to another session`);
+			if (existing.gatewayInstanceId !== identity.gatewayInstanceId || existing.sessionKey !== resolveAcpxSessionResource(handle) || existing.wrapperRoot !== wrapperRoot) throw new AcpRuntimeError("ACP_TURN_FAILED", `ACPX process lease ${identity.leaseId} belongs to another session`);
 		});
 		return identity;
 	}
@@ -673,7 +717,7 @@ var AcpxRuntime = class {
 		});
 	}
 	async finalizeProcessLeaseForOperation(handle, identity) {
-		await this.finalizeProcessLeaseForSession(handle.acpxRecordId ?? handle.sessionKey, identity);
+		await this.finalizeProcessLeaseForSession(handle.acpxRecordId ?? resolveAcpxSessionResource(handle), identity);
 	}
 	async finalizeProcessLeaseForSession(sessionId, identity) {
 		if (!identity || !this.processLeaseStore) return;
@@ -688,7 +732,8 @@ var AcpxRuntime = class {
 			}
 			this.uncertainProcessLeaseIds.delete(identity.leaseId);
 			try {
-				const recordIdentity = readAcpxProcessLeaseIdentity(readAgentCommandFromRecord(await this.sessionStore.load(sessionId)));
+				const record = await this.sessionStore.load(sessionId);
+				const recordIdentity = readAcpxProcessLeaseIdentity(readAgentCommandFromRecord(record));
 				if (recordIdentity?.leaseId !== identity.leaseId || recordIdentity.gatewayInstanceId !== identity.gatewayInstanceId) await processLeaseStore.markState(identity.leaseId, "lost");
 			} catch {}
 		});
@@ -764,7 +809,7 @@ var AcpxRuntime = class {
 		}
 	}
 	async readCodexTurnFailureStderr(params) {
-		const record = await this.sessionStore.load(params.handle.acpxRecordId ?? params.handle.sessionKey);
+		const record = await this.sessionStore.load(params.handle.acpxRecordId ?? resolveAcpxSessionResource(params.handle));
 		return readCodexWrapperStderrTail({
 			wrapperRoot: this.wrapperRoot,
 			leaseId: readOpenClawLeaseIdFromRecord(record)
@@ -773,7 +818,7 @@ var AcpxRuntime = class {
 	async cleanupProcessTreeForRecord(handle, record) {
 		const leaseId = readOpenClawLeaseIdFromRecord(record);
 		const rootPid = readAgentPidFromRecord(record);
-		const sessionKeys = [handle.sessionKey, readSessionRecordName(record)];
+		const sessionKeys = [resolveAcpxSessionResource(handle), readSessionRecordName(record)];
 		const selectedLease = selectCurrentSessionLease({
 			leases: this.gatewayInstanceId && this.processLeaseStore ? await this.processLeaseStore.listOpen(this.gatewayInstanceId) : [],
 			sessionKeys,
@@ -829,18 +874,28 @@ var AcpxRuntime = class {
 		});
 	}
 	async ensureSession(input) {
-		return await this.runSerializedSessionEnsure(input.sessionKey, () => this.ensureSessionUnlocked(input));
+		const resource = assertAcpxSessionOwnerLocator(input, this.legacyBareSessionKeys);
+		return await this.runSerializedSessionEnsure(resource, () => this.ensureSessionUnlocked(input));
 	}
-	async ensureSessionUnlocked(input) {
-		assertSupportedRuntimeSessionMode(input.mode);
+	async ensureSessionUnlocked(logicalInput) {
+		assertSupportedRuntimeSessionMode(logicalInput.mode);
 		const command = resolveAgentCommand({
-			agentName: input.agent,
+			agentName: logicalInput.agent,
 			agentRegistry: this.agentRegistry
 		});
 		const delegate = this.resolveDelegateForSession({
 			command,
-			sessionKey: input.sessionKey
+			sessionKey: logicalInput.sessionKey,
+			agentId: logicalInput.agentId
 		});
+		const logicalTarget = {
+			sessionKey: logicalInput.sessionKey,
+			agentId: logicalInput.agentId
+		};
+		const input = {
+			...logicalInput,
+			sessionKey: resolveAcpxSessionResource(logicalInput)
+		};
 		const isCodexAcp = normalizeAgentName(input.agent) === CODEX_ACP_AGENT_ID && isCodexAcpCommand(command);
 		const claudeModelOverride = isClaudeAcpCommand(command) ? normalizeClaudeAcpModelOverride(input.model) : void 0;
 		const codexClassification = isCodexAcp ? classifyCodexAcpModelRequest(input.model, input.thinking) : void 0;
@@ -864,38 +919,42 @@ var AcpxRuntime = class {
 			command: stableLaunchCommand,
 			resumeSessionId: input.resumeSessionId
 		});
-		const handle = !codexModelOverride ? await this.runWithLaunchLease({
-			sessionKey: ensureInput.sessionKey,
-			command: stableLaunchCommand,
-			reusableCommand,
-			run: () => this.withCodexWrapperDiagnostics({
+		return {
+			...!codexModelOverride ? await this.runWithLaunchLease({
+				sessionKey: ensureInput.sessionKey,
 				command: stableLaunchCommand,
-				fallbackCode: "ACP_SESSION_INIT_FAILED",
-				run: () => ensureDelegateSessionWithModelFallback(delegate, ensureInput)
-			})
-		}) : await this.runWithLaunchLease({
-			sessionKey: input.sessionKey,
-			command: stableLaunchCommand,
-			reusableCommand,
-			run: () => this.codexAcpModelOverrideScope.run(codexModelOverride, () => this.withCodexWrapperDiagnostics({
+				reusableCommand,
+				run: () => this.withCodexWrapperDiagnostics({
+					command: stableLaunchCommand,
+					fallbackCode: "ACP_SESSION_INIT_FAILED",
+					run: () => ensureDelegateSessionWithModelFallback(delegate, ensureInput)
+				})
+			}) : await this.runWithLaunchLease({
+				sessionKey: input.sessionKey,
 				command: stableLaunchCommand,
-				fallbackCode: "ACP_SESSION_INIT_FAILED",
-				run: () => delegate.ensureSession(withAcpxSessionOptions(ensureInput))
-			}))
-		});
-		return appliedModel ? {
-			...handle,
-			appliedModel
-		} : handle;
+				reusableCommand,
+				run: () => this.codexAcpModelOverrideScope.run(codexModelOverride, () => this.withCodexWrapperDiagnostics({
+					command: stableLaunchCommand,
+					fallbackCode: "ACP_SESSION_INIT_FAILED",
+					run: () => delegate.ensureSession(withAcpxSessionOptions(ensureInput))
+				}))
+			}),
+			...logicalTarget,
+			...appliedModel ? { appliedModel } : {}
+		};
 	}
 	async *runTurn(input) {
-		const record = await this.sessionStore.load(input.handle.acpxRecordId ?? input.handle.sessionKey);
+		assertAcpxSessionOwnerLocator({
+			...input.handle,
+			persistedHandle: input.handle
+		}, this.legacyBareSessionKeys);
+		const record = await this.sessionStore.load(input.handle.acpxRecordId ?? resolveAcpxSessionResource(input.handle));
 		const turnLease = await this.prepareProcessLeaseForOperation(input.handle, record);
 		let command;
 		try {
 			command = (await this.loadOperationSnapshotForHandle(input.handle)).command;
 			const delegate = this.resolveDelegateForOperationSnapshot(input.handle, await this.loadOperationSnapshotForHandle(input.handle));
-			for await (const event of delegate.runTurn(withOpenClawManagedTurnTimeout(input))) {
+			for await (const event of delegate.runTurn(withOpenClawManagedTurnTimeout(toAcpxResourceInput(input)))) {
 				if (event.type !== "error" || !isCodexAcpCommand(command) || !isGenericInternalAcpErrorMessage(event.message)) {
 					yield event;
 					continue;
@@ -930,7 +989,7 @@ var AcpxRuntime = class {
 			try {
 				return {
 					command,
-					turn: delegate.startTurn(withOpenClawManagedTurnTimeout(input))
+					turn: delegate.startTurn(withOpenClawManagedTurnTimeout(toAcpxResourceInput(input)))
 				};
 			} catch (error) {
 				if (!isCodexAcpCommand(command) || !isGenericInternalAcpError(error)) throw error;
@@ -1000,23 +1059,24 @@ var AcpxRuntime = class {
 		};
 	}
 	getCapabilities(input) {
-		return this.delegate.getCapabilities(input);
+		return this.delegate.getCapabilities(input?.handle ? toAcpxResourceInput({ handle: input.handle }) : input);
 	}
 	async getStatus(input) {
 		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
-		return this.resolveDelegateForOperationSnapshot(input.handle, snapshot).getStatus(input);
+		return this.resolveDelegateForOperationSnapshot(input.handle, snapshot).getStatus(toAcpxResourceInput(input));
 	}
 	async setMode(input) {
 		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
-		await this.runWithProcessLeaseForHandle(input.handle, snapshot.record, () => this.resolveDelegateForOperationSnapshot(input.handle, snapshot).setMode(input));
+		await this.runWithProcessLeaseForHandle(input.handle, snapshot.record, () => this.resolveDelegateForOperationSnapshot(input.handle, snapshot).setMode(toAcpxResourceInput(input)));
 	}
 	async setConfigOption(input) {
 		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
 		return await this.runWithProcessLeaseForHandle(input.handle, snapshot.record, () => this.setConfigOptionUnlocked(input, snapshot));
 	}
-	async setConfigOptionUnlocked(input, snapshot) {
+	async setConfigOptionUnlocked(logicalInput, snapshot) {
 		const { command } = snapshot;
-		const delegate = this.resolveDelegateForOperationSnapshot(input.handle, snapshot);
+		const delegate = this.resolveDelegateForOperationSnapshot(logicalInput.handle, snapshot);
+		const input = toAcpxResourceInput(logicalInput);
 		const key = input.key.trim().toLowerCase();
 		const isCodexAcp = isCodexAcpCommand(command);
 		if (WIRE_TIMEOUT_CONFIG_KEYS.has(key) && (isCodexAcp || isClaudeAcpCommand(command))) return;
@@ -1056,10 +1116,12 @@ var AcpxRuntime = class {
 	}
 	async cancel(input) {
 		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
-		await this.resolveDelegateForOperationSnapshot(input.handle, snapshot).cancel(input);
+		await this.resolveDelegateForOperationSnapshot(input.handle, snapshot).cancel(toAcpxResourceInput(input));
 	}
 	async prepareFreshSession(input) {
-		this.sessionStore.markFresh(input.sessionKey);
+		const resource = assertAcpxSessionOwnerLocator(input, this.legacyBareSessionKeys);
+		this.sessionStore.markFresh(resource);
+		this.legacyBareSessionKeys.delete(resource);
 	}
 	async close(input) {
 		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
@@ -1070,7 +1132,7 @@ var AcpxRuntime = class {
 			let closeSucceeded;
 			try {
 				await delegate.close({
-					handle: input.handle,
+					handle: toAcpxResourceInput(input).handle,
 					reason: input.reason,
 					discardPersistentState: input.discardPersistentState
 				});
@@ -1079,8 +1141,11 @@ var AcpxRuntime = class {
 				await this.cleanupProcessTreeForRecord(input.handle, snapshot.record);
 				cleanupSucceeded = true;
 			}
-			if (closeSucceeded) this.releaseManagedToolsDelegateForSession(input.handle.sessionKey);
-			if (closeSucceeded && input.discardPersistentState) this.sessionStore.markFresh(input.handle.sessionKey);
+			if (closeSucceeded) this.releaseManagedToolsDelegateForSession(resolveAcpxSessionResource(input.handle));
+			if (closeSucceeded && input.discardPersistentState) await this.prepareFreshSession({
+				...input.handle,
+				persistedHandle: input.handle
+			});
 		} finally {
 			if (cleanupSucceeded) await this.finalizeProcessLeaseForOperation(input.handle, closeLease);
 			else await this.releaseProcessLeaseAfterUncertainFailure(closeLease);