@scotthuang/agent-knock-knock 0.12.15 → 0.12.16

package/dist/src/openclaw-plugin-command-adapter.js

@@ -1,4 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { executorDefinitionForKind } from "./executors.js";
@@ -12,9 +13,37 @@ const OPENCLAW_RECONCILE_BINDING_AUTHORITY_KIND = "reconcile_binding";
 const CALLBACK_METHOD = AKK_CALLBACK_METHOD;
 export const defaultOpenClawRelayPath = fileURLToPath(new URL("./cli.js", import.meta.url));
 const relayPathByApi = new WeakMap();
+const relayEnvironmentByApi = new WeakMap();
+const hostBridgePresentationApis = new WeakSet();
+const hostBridgeAsyncRelayApis = new WeakSet();
+const hostBridgeInvocationStorage = new AsyncLocalStorage();
 export function bindOpenClawRelayPath(api, relayPath) {
     relayPathByApi.set(api, relayPath);
 }
+/** Bind a private child-process environment for a Host adapter instance. */
+export function bindOpenClawRelayEnvironment(api, environment) {
+    relayEnvironmentByApi.set(api, Object.freeze({ ...environment }));
+}
+/** Keep one shared tool implementation while selecting Host-neutral output. */
+export function bindHostBridgeToolPresentation(api) {
+    hostBridgePresentationApis.add(api);
+}
+/**
+ * Keep an embedding Host's event loop responsive while AKK CLI work runs.
+ *
+ * OpenClaw deliberately retains its established synchronous relay behavior;
+ * only public Host adapters opt into the asynchronous child-process runner.
+ */
+export function bindHostBridgeAsyncRelay(api) {
+    hostBridgeAsyncRelayApis.add(api);
+}
+/** Scope one Host invocation's cancellation without sharing mutable state. */
+export function withHostBridgeInvocationSignal(signal, operation) {
+    if (signal?.aborted) {
+        return Promise.reject(hostBridgeAbortError());
+    }
+    return hostBridgeInvocationStorage.run({ signal }, async () => operation());
+}
 export function registerOpenClawCommands(api, displayedResumeSnapshots) {
     api.registerCommand?.({
         name: "akk",
@@ -112,14 +141,14 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
         description: "Execute one closed, exact-version native status inspection in an exact Codex or Claude Code terminal. Pass only terminal_id and inspection=status; AKK refreshes binding authority privately. Arbitrary slash commands remain unavailable. This creates no AKK Session, Turn, receipt, monitor, or callback.",
         parameters: nativeInspectParameters,
         normalizeTurnIdentity: false,
-        buildArgs: (params) => {
+        buildArgs: async (params) => {
             const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
             const inspection = requiredString(params.inspection, "inspection");
             if (inspection !== "status") {
                 throw new Error("inspection must be status");
             }
             const terminalId = requiredString(params.terminal_id, "terminal_id");
-            const action = privateTerminalActionArguments(api, terminalId, "agent_knock_knock_native_inspect");
+            const action = await privateTerminalActionArguments(api, terminalId, "agent_knock_knock_native_inspect");
             const args = [
                 "native-inspect",
                 "--terminal",
@@ -140,10 +169,10 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
         parameters: newThreadParameters,
         normalizeTurnIdentity: false,
         isErrorResult: (result) => !isAkkThreadTransitionSuccess(result),
-        buildArgs: (params) => {
+        buildArgs: async (params) => {
             const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
             const terminalId = requiredString(params.terminal_id, "terminal_id");
-            const action = privateTerminalActionArguments(api, terminalId, "agent_knock_knock_new_thread");
+            const action = await privateTerminalActionArguments(api, terminalId, "agent_knock_knock_new_thread");
             const args = [
                 "new-thread",
                 "--terminal",
@@ -161,11 +190,11 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
         description: "Detach one exact conflicting managed Session binding without adopting the live replacement thread. Pass only the advertised terminal_id and conflicting_session_id after explicit user confirmation; AKK refreshes all revision and binding authority privately. This sends no coding-agent input and creates no Turn.",
         parameters: reconcileBindingParameters,
         normalizeTurnIdentity: false,
-        buildArgs: (params, toolContext) => {
+        buildArgs: async (params, toolContext) => {
             const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
             const terminalId = requiredString(params.terminal_id, "terminal_id");
             const conflictingSessionId = requiredString(params.conflicting_session_id, "conflicting_session_id");
-            const action = consumeDisplayedPrivateAction(api, {
+            const action = await consumeDisplayedPrivateAction(api, {
                 sessionKey: requiredOpenClawSessionKey(toolContext?.sessionKey),
                 sessionId: requiredOpenClawSessionId(toolContext?.sessionId),
                 kind: OPENCLAW_RECONCILE_BINDING_AUTHORITY_KIND,
@@ -204,11 +233,11 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
         parameters: resumeThreadParameters,
         normalizeTurnIdentity: false,
         isErrorResult: (result) => !isAkkThreadTransitionSuccess(result),
-        buildArgs: (params) => {
+        buildArgs: async (params) => {
             const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
             const terminalId = requiredString(params.terminal_id, "terminal_id");
             const nativeThreadId = requiredString(params.native_thread_id, "native_thread_id");
-            const discovery = privateThreadDiscovery(api, terminalId);
+            const discovery = await privateThreadDiscovery(api, terminalId);
             const candidate = Array.isArray(discovery.threads)
                 ? discovery.threads.find((thread) => isRecord(thread) &&
                     thread.resumable === true &&
@@ -240,7 +269,7 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
         parameters: statusParameters,
         async execute(_toolCallId, params) {
             try {
-                const result = runCli(api, buildStatusCliArgs(api, isRecord(params) ? params : {}));
+                const result = await runHostAwareCli(api, buildStatusCliArgs(api, isRecord(params) ? params : {}));
                 const rendered = toolResult(result);
                 rememberDisplayedApprovalOffer(api, toolContext?.sessionKey, toolContext?.sessionId, result);
                 return rendered;
@@ -319,7 +348,7 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
     });
     registerCliTool(api, {
         name: "agent_knock_knock_retry_callback",
-        description: "Retry a persisted AKK callback for an exact turn that failed before reaching OpenClaw. The original callback message id and turn identity are reused for idempotent delivery.",
+        description: "Retry a persisted AKK callback for an exact turn that failed before reaching the controller Host. The original callback message id and turn identity are reused for idempotent delivery.",
         parameters: retryCallbackParameters,
         buildArgs: (params) => {
             const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
@@ -361,14 +390,14 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
     });
 }
 function resumeSelectionScope(sessionKey, sessionId) {
-    const key = requiredString(sessionKey, "OpenClaw session identity is required for snapshot-bound Resume");
+    const key = requiredString(sessionKey, "Controller session identity is required for snapshot-bound Resume");
     const incarnation = stringValue(sessionId) ?? null;
     return `openclaw:${createHash("sha256")
         .update(JSON.stringify([key, incarnation]))
         .digest("hex")}`;
 }
 function resumeSnapshotCacheKey(sessionKey, sessionId, terminalId) {
-    const key = requiredString(sessionKey, "OpenClaw session identity is required for snapshot-bound Resume");
+    const key = requiredString(sessionKey, "Controller session identity is required for snapshot-bound Resume");
     return JSON.stringify([key, stringValue(sessionId) ?? null, terminalId]);
 }
 function rememberDisplayedResumeSnapshot(snapshots, key, snapshotId, expiresAtMs) {
@@ -430,7 +459,7 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
             return await handleAkkLifecycleCommand(api, ctx, parsed, config, displayedResumeSnapshots);
         }
         const args = parsed.action === "approve"
-            ? buildPrivateApprovalArgs(api, { turn_id: parsed.turnId }, {
+            ? await buildPrivateApprovalArgs(api, { turn_id: parsed.turnId }, {
                 sessionKey: requiredOpenClawSessionKey(ctx.sessionKey),
                 sessionId: requiredOpenClawSessionId(ctx.sessionId)
             })
@@ -447,7 +476,7 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
         // check. Keep the Gateway event loop free while that child CLI runs.
         const result = parsed.action === "doctor"
             ? await runCliAsync(api, args, { allowNonzeroJson: true })
-            : runCli(api, args);
+            : await runHostAwareCli(api, args);
         switch (parsed.action) {
             case "doctor":
                 return {
@@ -485,6 +514,9 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
         }
     }
     catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw error;
+        }
         const message = modelFacingErrorMessage(error);
         return {
             text: `AKK command failed: ${message}`,
@@ -506,7 +538,7 @@ async function handleAkkLifecycleCommand(api, ctx, parsed, config, displayedResu
     if (parsed.action === "resume-thread" &&
         parsed.selection &&
         ["number", "short-id"].includes(parsed.selection.kind)) {
-        requiredString(ctx.sessionId, "OpenClaw conversation incarnation is required for number or short-id Resume; run /akk threads again in the current conversation or use the complete UUID");
+        requiredString(ctx.sessionId, "Controller conversation incarnation is required for number or short-id Resume; run /akk threads again in the current conversation or use the complete UUID");
         const mutationArgs = buildAkkCommandCliArgs(parsed, config, {
             sessionKey: ctx.sessionKey,
             selectionScope,
@@ -515,7 +547,7 @@ async function handleAkkLifecycleCommand(api, ctx, parsed, config, displayedResu
         if (!mutationArgs) {
             throw new Error("could not build snapshot-bound resume command");
         }
-        const transitionResult = runCli(api, mutationArgs);
+        const transitionResult = await runHostAwareCli(api, mutationArgs);
         if (isAkkThreadTransitionSuccess(transitionResult)) {
             displayedResumeSnapshots.delete(snapshotCacheKey);
         }
@@ -531,7 +563,7 @@ async function handleAkkLifecycleCommand(api, ctx, parsed, config, displayedResu
     if (!discoveryArgs) {
         throw new Error("could not build native-thread discovery command");
     }
-    const discovery = runCli(api, discoveryArgs);
+    const discovery = await runHostAwareCli(api, discoveryArgs);
     if (parsed.action === "list-resumable-threads" ||
         (parsed.action === "resume-thread" &&
             !parsed.selection)) {
@@ -601,7 +633,7 @@ async function handleAkkLifecycleCommand(api, ctx, parsed, config, displayedResu
     if (!mutationArgs) {
         throw new Error("could not build native-thread lifecycle command");
     }
-    const transitionResult = runCli(api, mutationArgs);
+    const transitionResult = await runHostAwareCli(api, mutationArgs);
     if (isAkkThreadTransitionSuccess(transitionResult)) {
         displayedResumeSnapshots.delete(snapshotCacheKey);
     }
@@ -661,7 +693,7 @@ function formatDelegateCommandResult(result) {
         `session: ${sessionId}`,
         `turn: ${turnId}`,
         `status: ${result.conversation_status ?? result.status ?? "unknown"}`,
-        "The result will return to this OpenClaw session through the callback."
+        "The result will return to this controller session through the callback."
     ].join("\n");
 }
 function executorDisplayName(kind) {
@@ -1053,7 +1085,7 @@ async function runSendRequest(api, params, toolContext, messageId) {
             throw new Error("send retry_submission accepts exactly turn_id; do not pass request, terminal_id, session_id, timeout overrides, or callback route data");
         }
         const turnId = authoritativeManagedId(params.turn_id, "turn_id");
-        privateActionArguments(api, {
+        await privateActionArguments(api, {
             tool: "agent_knock_knock_send",
             matches: (argumentsValue) => Object.keys(argumentsValue).length === 1 &&
                 stringValue(argumentsValue.turn_id) === turnId
@@ -1061,7 +1093,7 @@ async function runSendRequest(api, params, toolContext, messageId) {
         const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
         const args = ["send", "--turn", turnId];
         pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-        return runCli(api, args);
+        return runHostAwareCli(api, args);
     }
     const requestedType = Object.hasOwn(params, "type")
         ? stringValue(params.type)
@@ -1085,7 +1117,7 @@ async function runSendRequest(api, params, toolContext, messageId) {
         return runDelegate(api, { ...params, messageId }, toolContext);
     }
     const terminalAction = terminalId
-        ? privateActionArguments(api, {
+        ? await privateActionArguments(api, {
             tool: "agent_knock_knock_send",
             terminalId,
             matches: (argumentsValue) => stringValue(argumentsValue.selector) === terminalId ||
@@ -1122,7 +1154,7 @@ async function runSendRequest(api, params, toolContext, messageId) {
     pushOptional(args, "--gateway-method", CALLBACK_METHOD);
     pushOptional(args, "--gateway-session", openclawSession);
     pushOptional(args, "--openclaw-bin", stringValue(config.openclawBin));
-    return runCli(api, args);
+    return runHostAwareCli(api, args);
 }
 function toolResult(result, { submissionErrors = false, normalizeTurnIdentity = true, forceError = false } = {}) {
     const normalized = normalizeTurnIdentity ? withTurnIdentity(result) : result;
@@ -1139,14 +1171,14 @@ function toolResult(result, { submissionErrors = false, normalizeTurnIdentity =
         ...(submissionError || forceError ? { isError: true } : {})
     };
 }
-function privateList(api) {
+async function privateList(api) {
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
     const args = ["list", "--reconcile"];
     pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
     pushOptional(args, "--idle-timeout-minutes", numberString(config.idleTimeoutMinutes));
-    return runCli(api, args);
+    return runHostAwareCli(api, args);
 }
-function privateThreadDiscovery(api, terminalId) {
+async function privateThreadDiscovery(api, terminalId) {
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
     const args = [
         "list-resumable-threads",
@@ -1155,17 +1187,17 @@ function privateThreadDiscovery(api, terminalId) {
     ];
     pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
     pushOptional(args, "--codex-home", stringValue(config.codexHome));
-    return runCli(api, args);
+    return runHostAwareCli(api, args);
 }
-function privateTerminalActionArguments(api, terminalId, tool) {
+async function privateTerminalActionArguments(api, terminalId, tool) {
     return privateActionArguments(api, {
         tool,
         terminalId,
         matches: (argumentsValue) => stringValue(argumentsValue.terminal_id) === terminalId
     });
 }
-function privateActionArguments(api, input) {
-    const result = privateList(api);
+async function privateActionArguments(api, input) {
+    const result = await privateList(api);
     const terminals = input.terminalId
         ? terminalRows(result).filter((terminal) => stringValue(terminal.id) === input.terminalId)
         : terminalRows(result);
@@ -1247,7 +1279,7 @@ function uniqueArgumentObjects(candidates) {
 function privateAuthorityOfferKey(sessionKey, sessionId, kind, target) {
     return { sessionKey, sessionId, kind, target };
 }
-function consumeDisplayedPrivateAction(api, input) {
+async function consumeDisplayedPrivateAction(api, input) {
     const offered = consumeOpenClawPrivateAuthorityOffer(api, {
         sessionKey: input.sessionKey,
         sessionId: input.sessionId,
@@ -1255,9 +1287,9 @@ function consumeDisplayedPrivateAction(api, input) {
         target: input.target
     });
     if (!offered || !isRecord(offered.args)) {
-        throw new Error(`${input.tool} requires a current action shown by AKK list in this OpenClaw session; refresh list, review it, and explicitly confirm again`);
+        throw new Error(`${input.tool} requires a current action shown by AKK list in this controller session; refresh list, review it, and explicitly confirm again`);
     }
-    const current = privateActionArguments(api, input);
+    const current = await privateActionArguments(api, input);
     if (JSON.stringify(current) !== JSON.stringify(offered.args)) {
         throw new Error(`${input.tool} authority changed after it was shown; refresh AKK list, review the current action, and explicitly confirm again`);
     }
@@ -1303,7 +1335,7 @@ function currentApprovalFingerprint(result) {
     }
     return unique[0];
 }
-function buildPrivateApprovalArgs(api, params, { sessionKey, sessionId }) {
+async function buildPrivateApprovalArgs(api, params, { sessionKey, sessionId }) {
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
     const turnId = stringValue(params.turn_id);
     const terminalId = stringValue(params.terminal_id);
@@ -1319,10 +1351,10 @@ function buildPrivateApprovalArgs(api, params, { sessionKey, sessionId }) {
             ? stringValue(offered.args.expected_approval_fingerprint)
             : undefined);
     if (!isExactApprovalFingerprint(offeredFingerprint)) {
-        throw new Error("approve requires a current approval request shown by agent_knock_knock_status in this OpenClaw conversation; refresh status, ask the user to review it, and explicitly confirm again");
+        throw new Error("approve requires a current approval request shown by agent_knock_knock_status in this controller conversation; refresh status, ask the user to review it, and explicitly confirm again");
     }
     const action = terminalId
-        ? privateActionArguments(api, {
+        ? await privateActionArguments(api, {
             tool: "agent_knock_knock_approve",
             terminalId,
             matches: (argumentsValue) => stringValue(argumentsValue.terminal_id ?? argumentsValue.conversation_id) === terminalId
@@ -1343,7 +1375,7 @@ function buildPrivateApprovalArgs(api, params, { sessionKey, sessionId }) {
     else {
         args.push("--turn", requiredString(turnId, "turn_id"));
     }
-    const currentFingerprint = currentApprovalFingerprint(runCli(api, statusArgs));
+    const currentFingerprint = currentApprovalFingerprint(await runHostAwareCli(api, statusArgs));
     if (currentFingerprint !== offeredFingerprint) {
         throw new Error("the approval request changed after it was shown; refresh AKK status, ask the user to review the current request, and explicitly confirm again");
     }
@@ -1442,6 +1474,9 @@ function isLegacyAuthorityInstructionPath(path) {
     return callbackMessageBody || normalized.includes("recentevents");
 }
 function modelFacingToolError(error) {
+    if (error instanceof Error && error.name === "AbortError") {
+        return error;
+    }
     return new Error(modelFacingErrorMessage(error));
 }
 function modelFacingErrorMessage(error) {
@@ -1644,7 +1679,9 @@ async function runDelegate(api, params, toolContext) {
         replayed: parsed.replayed === true,
         background: parsed.background === true,
         pid: parsed.pid ?? parsedTerminalControl?.panePid ?? null,
-        callback_method: CALLBACK_METHOD,
+        callback_method: hostBridgePresentationApis.has(api)
+            ? "command_json_v1"
+            : CALLBACK_METHOD,
         ...(submissionUnfenced
             ? {
                 submission_outcome: "submitted",
@@ -1698,11 +1735,11 @@ async function runDelegate(api, params, toolContext) {
                             : {
                                 openclaw_next_action: {
                                     action: "yield",
-                                    reason: "The coding agent is working in the shared terminal. End this OpenClaw turn now and wait for an Agent Knock Knock callback.",
+                                    reason: "The coding agent is working in the shared terminal. End this controller turn now and wait for an Agent Knock Knock callback.",
                                     do_not: "Do not poll terminal internals while waiting. Further communication must use Agent Knock Knock tools so the same shared terminal remains authoritative.",
-                                    expected_callback: "The callback will be injected and scheduled into this OpenClaw session by the agent-knock-knock.callback Gateway method."
+                                    expected_callback: "The callback will be injected into this controller session by its configured callback transport."
                                 },
-                                note: "The task was sent to the shared terminal. OpenClaw should yield now and wait for the scheduled callback turn."
+                                note: "The task was sent to the shared terminal. The controller Host should yield now and wait for the callback turn."
                             })
     };
 }
@@ -1729,7 +1766,7 @@ function registerCliTool(api, { name, description, parameters, buildArgs, normal
         parameters,
         async execute(toolCallId, params) {
             try {
-                const result = runCli(api, buildArgs(isRecord(params) ? params : {}, toolContext, toolCallId));
+                const result = await runHostAwareCli(api, await buildArgs(isRecord(params) ? params : {}, toolContext, toolCallId));
                 const rendered = toolResult(result, {
                     submissionErrors: name === "agent_knock_knock_respond",
                     normalizeTurnIdentity,
@@ -1760,7 +1797,8 @@ export function runCli(api, cliArgs, { cwd = process.cwd(), allowNonzeroJson = f
     const spawned = spawnSync(process.execPath, [binPath, ...cliArgs], {
         encoding: "utf8",
         maxBuffer: 1024 * 1024 * 10,
-        cwd
+        cwd,
+        env: relayEnvironmentForApi(api)
     });
     if (spawned.error) {
         throw new Error(`agent-knock-knock ${cliArgs[0]} failed to start: ${spawned.error.message}`);
@@ -1776,9 +1814,14 @@ export function runCli(api, cliArgs, { cwd = process.cwd(), allowNonzeroJson = f
 export function runCliAsync(api, cliArgs, { cwd = process.cwd(), allowNonzeroJson = false, timeoutMs = 90_000 } = {}) {
     const binPath = relayPathForApi(api);
     const maxBuffer = 10 * 1024 * 1024;
+    const signal = hostBridgeInvocationStorage.getStore()?.signal;
+    if (signal?.aborted) {
+        return Promise.reject(hostBridgeAbortError());
+    }
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, [binPath, ...cliArgs], {
             cwd,
+            env: relayEnvironmentForApi(api),
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true
         });
@@ -1788,6 +1831,15 @@ export function runCliAsync(api, cliArgs, { cwd = process.cwd(), allowNonzeroJso
         let stderr = "";
         let overflow = false;
         let timedOut = false;
+        let aborted = false;
+        const onAbort = () => {
+            aborted = true;
+            child.kill("SIGKILL");
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            signal?.removeEventListener("abort", onAbort);
+        };
         const append = (current, chunk) => {
             const next = current + chunk;
             if (Buffer.byteLength(next, "utf8") > maxBuffer) {
@@ -1807,12 +1859,24 @@ export function runCliAsync(api, cliArgs, { cwd = process.cwd(), allowNonzeroJso
             child.kill("SIGKILL");
         }, timeoutMs);
         timeout.unref();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted) {
+            onAbort();
+        }
         child.once("error", (error) => {
-            clearTimeout(timeout);
+            cleanup();
+            if (aborted) {
+                reject(hostBridgeAbortError());
+                return;
+            }
             reject(new Error(`agent-knock-knock ${cliArgs[0]} failed to start: ${error.message}`));
         });
         child.once("close", (status) => {
-            clearTimeout(timeout);
+            cleanup();
+            if (aborted) {
+                reject(hostBridgeAbortError());
+                return;
+            }
             if (timedOut) {
                 reject(new Error(`agent-knock-knock ${cliArgs[0]} timed out`));
                 return;
@@ -1845,9 +1909,23 @@ export function runCliAsync(api, cliArgs, { cwd = process.cwd(), allowNonzeroJso
         });
     });
 }
+function hostBridgeAbortError() {
+    const error = new Error("agent-knock-knock Host invocation was aborted");
+    error.name = "AbortError";
+    return error;
+}
+async function runHostAwareCli(api, cliArgs, options = {}) {
+    if (hostBridgeAsyncRelayApis.has(api)) {
+        return runCliAsync(api, cliArgs, options);
+    }
+    return runCli(api, cliArgs, options);
+}
 function relayPathForApi(api) {
     return relayPathByApi.get(api) ?? defaultOpenClawRelayPath;
 }
+function relayEnvironmentForApi(api) {
+    return relayEnvironmentByApi.get(api) ?? process.env;
+}
 function pushTurnTarget(args, params) {
     if (Object.hasOwn(params, "turn_id") && Object.hasOwn(params, "conversation_id")) {
         throw new Error("turn-target tools accept only one of turn_id or conversation_id");
@@ -1903,10 +1981,10 @@ function requiredString(value, name) {
     return value;
 }
 function requiredOpenClawSessionKey(value) {
-    return requiredString(value, "OpenClaw session identity for this confirmed action");
+    return requiredString(value, "Controller session identity for this confirmed action");
 }
 function requiredOpenClawSessionId(value) {
-    return requiredString(value, "OpenClaw conversation incarnation for this confirmed action");
+    return requiredString(value, "Controller conversation incarnation for this confirmed action");
 }
 function parseJson(text) {
     try {