openclawWrapperRoot?: string;

openclawGatewayInstanceId?: string;

openclawProcessLeaseStore?: AcpxProcessLeaseStore;

openclawToolsMcpBridgeEnabled?: boolean;

};

type AcpxRuntimeTestOptions = Record<string, unknown> & {

openclawProcessCleanup?: AcpxProcessCleanupDeps;

};

type OpenClawRuntimeTurnInput = Parameters<NonNullable<AcpRuntime["startTurn"]>>[0];

type OpenClawRuntimeEnsureInput = Parameters<AcpRuntime["ensureSession"]>[0];

type AcpxDelegateEnsureInput = Parameters<BaseAcpxRuntime["ensureSession"]>[0];

type AcpxMcpServer = NonNullable<AcpRuntimeOptions["mcpServers"]>[number];

const ACPX_OPENCLAW_TOOLS_MCP_SERVER_NAME = "openclaw-tools";

const OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY_ENV = "OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY";

type ResetAwareSessionStore = AcpSessionStore & {

markFresh: (sessionKey: string) => void;

return Array.isArray(mcpServers) && mcpServers.length > 0;

}

function withOpenClawToolsMcpSessionEnv(params: {

enabled: boolean | undefined;

mcpServers: AcpRuntimeOptions["mcpServers"];

sessionKey: string;

}): AcpRuntimeOptions["mcpServers"] {

const sessionKey = params.sessionKey.trim();

if (!params.enabled || !sessionKey || !params.mcpServers?.length) {

return params.mcpServers;

}

let changed = false;

const nextServers = params.mcpServers.map((server): AcpxMcpServer => {

if (server.name !== ACPX_OPENCLAW_TOOLS_MCP_SERVER_NAME || !("command" in server)) {

return server;

}

changed = true;

const env = [

...server.env.filter((entry) => entry.name !== OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY_ENV),

{

name: OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY_ENV,

value: sessionKey,

},

];

return { ...server, env };

});

return changed ? nextServers : params.mcpServers;

}

/** OpenClaw-managed ACP runtime implementation backed by the upstream acpx runtime. */

export class AcpxRuntime implements AcpRuntime {

private readonly sessionStore: ResetAwareSessionStore;

private readonly delegate: BaseAcpxRuntime;

private readonly bridgeSafeDelegate: BaseAcpxRuntime;

private readonly probeDelegate: BaseAcpxRuntime;

private readonly delegateOptions: AcpRuntimeOptions;

private readonly delegateTestOptions: BaseAcpxRuntimeTestOptions;

private readonly openclawToolsMcpBridgeEnabled: boolean;

private readonly openclawToolsSessionDelegates = new Map<string, BaseAcpxRuntime>();

private readonly processCleanupDeps: AcpxProcessCleanupDeps | undefined;

private readonly wrapperRoot: string | undefined;

private readonly gatewayInstanceId: string | undefined;

this.wrapperRoot = options.openclawWrapperRoot;

this.gatewayInstanceId = options.openclawGatewayInstanceId;

this.processLeaseStore = options.openclawProcessLeaseStore;

this.openclawToolsMcpBridgeEnabled = options.openclawToolsMcpBridgeEnabled === true;

this.cwd = options.cwd;

this.sessionStore = createResetAwareSessionStore(options.sessionStore, {

gatewayInstanceId: this.gatewayInstanceId,

sessionStore: this.sessionStore,

agentRegistry: this.scopedAgentRegistry,

};

this.delegate = new BaseAcpxRuntime(

sharedOptions,

delegateTestOptions as BaseAcpxRuntimeTestOptions,

);

this.delegateOptions = sharedOptions;

this.delegateTestOptions = delegateTestOptions as BaseAcpxRuntimeTestOptions;

this.delegate = new BaseAcpxRuntime(sharedOptions, this.delegateTestOptions);

this.bridgeSafeDelegate = shouldUseDistinctBridgeDelegate(options)

? new BaseAcpxRuntime(

{

...sharedOptions,

mcpServers: [],

},

delegateTestOptions as BaseAcpxRuntimeTestOptions,

this.delegateTestOptions,

)

: this.delegate;

this.probeDelegate = this.resolveDelegateForAgent(resolveProbeAgentName(options));

this.probeDelegate = this.openclawToolsMcpBridgeEnabled

? this.bridgeSafeDelegate

: this.resolveDelegateForAgent(resolveProbeAgentName(options));

}

private resolveDelegateForAgent(agentName: string | undefined): BaseAcpxRuntime {

return shouldUseBridgeSafeDelegateForCommand(command) ? this.bridgeSafeDelegate : this.delegate;

}

private resolveDelegateForSession(params: {

command: string | undefined;

sessionKey: string;

}): BaseAcpxRuntime {

if (shouldUseBridgeSafeDelegateForCommand(params.command)) {

return this.bridgeSafeDelegate;

}

return this.resolveOpenClawToolsDelegateForSession(params.sessionKey);

}

private resolveOpenClawToolsDelegateForSession(sessionKey: string): BaseAcpxRuntime {

if (!this.openclawToolsMcpBridgeEnabled) {

return this.delegate;

}

const normalizedSessionKey = sessionKey.trim();

if (!normalizedSessionKey) {

return this.delegate;

}

const cached = this.openclawToolsSessionDelegates.get(normalizedSessionKey);

if (cached) {

return cached;

}

// Upstream acpx captures mcpServers at runtime construction. The managed

// OpenClaw tools bridge needs per-session identity, so cache one delegate

// per session with the scoped MCP env already embedded.

const delegate = new BaseAcpxRuntime(

{

...this.delegateOptions,

mcpServers: withOpenClawToolsMcpSessionEnv({

enabled: this.openclawToolsMcpBridgeEnabled,

mcpServers: this.delegateOptions.mcpServers,

sessionKey: normalizedSessionKey,

}),

},

this.delegateTestOptions,

);

this.openclawToolsSessionDelegates.set(normalizedSessionKey, delegate);

return delegate;

}

private releaseOpenClawToolsDelegateForSession(sessionKey: string): void {

if (!this.openclawToolsMcpBridgeEnabled) {

return;

}

const normalizedSessionKey = sessionKey.trim();

if (!normalizedSessionKey) {

return;

}

this.openclawToolsSessionDelegates.delete(normalizedSessionKey);

}

private async resolveDelegateForHandle(handle: AcpRuntimeHandle): Promise<BaseAcpxRuntime> {

const record = await this.sessionStore.load(handle.acpxRecordId ?? handle.sessionKey);

return this.resolveDelegateForLoadedRecord(handle, record);

): BaseAcpxRuntime {

const recordCommand = readAgentCommandFromRecord(record);

if (recordCommand) {

return this.resolveDelegateForCommand(recordCommand);

return this.resolveDelegateForSession({

command: recordCommand,

sessionKey: handle.sessionKey,

});

}

return this.resolveDelegateForAgent(readAgentFromHandle(handle));

const agentName = readAgentFromHandle(handle);

const command = resolveAgentCommandForName({

agentName,

agentRegistry: this.agentRegistry,

});

return this.resolveDelegateForSession({ command, sessionKey: handle.sessionKey });

}

private async resolveCommandForHandle(handle: AcpRuntimeHandle): Promise<string | undefined> {

agentName: input.agent,

agentRegistry: this.agentRegistry,

});

const delegate = this.resolveDelegateForCommand(command);

const delegate = this.resolveDelegateForSession({ command, sessionKey: input.sessionKey });

const claudeModelOverride = isClaudeAcpCommand(command)

? normalizeClaudeAcpModelOverride(input.model)

: undefined;

}

async prepareFreshSession(input: { sessionKey: string }): Promise<void> {

// Fresh reset has no ACP handle to close the delegate's upstream client.

// Keep the scoped delegate reachable so the next ensure can replace it;

// close() owns cache release when the session lifecycle ends.

this.sessionStore.markFresh(input.sessionKey);

}

input.handle.acpxRecordId ?? input.handle.sessionKey,

);

let closeSucceeded;

const delegate = this.resolveDelegateForLoadedRecord(input.handle, record);

try {

await this.resolveDelegateForLoadedRecord(input.handle, record).close({

await delegate.close({

handle: input.handle,

reason: input.reason,

discardPersistentState: input.discardPersistentState,

} finally {

await this.cleanupProcessTreeForRecord(input.handle, record);

}

if (closeSucceeded) {

this.releaseOpenClawToolsDelegateForSession(input.handle.sessionKey);

}

if (closeSucceeded && input.discardPersistentState) {

this.sessionStore.markFresh(input.handle.sessionKey);

}