@poolzin/pool-bot 2026.2.21 → 2026.2.23

package/dist/agents/tools/message-tool.js

@@ -1,18 +1,19 @@
 import { Type } from "@sinclair/typebox";
-import { listChannelMessageActions, supportsChannelMessageButtons, supportsChannelMessageCards, } from "../../channels/plugins/message-actions.js";
-import { CHANNEL_MESSAGE_ACTION_NAMES, } from "../../channels/plugins/types.js";
 import { BLUEBUBBLES_GROUP_ACTIONS } from "../../channels/plugins/bluebubbles-actions.js";
+import { listChannelMessageActions, supportsChannelMessageButtons, supportsChannelMessageButtonsForChannel, supportsChannelMessageCards, supportsChannelMessageCardsForChannel, } from "../../channels/plugins/message-actions.js";
+import { CHANNEL_MESSAGE_ACTION_NAMES, } from "../../channels/plugins/types.js";
 import { loadConfig } from "../../config/config.js";
 import { GATEWAY_CLIENT_IDS, GATEWAY_CLIENT_MODES } from "../../gateway/protocol/client-info.js";
-import { normalizeTargetForProvider } from "../../infra/outbound/target-normalization.js";
 import { getToolResult, runMessageAction } from "../../infra/outbound/message-action-runner.js";
-import { resolveSessionAgentId } from "../agent-scope.js";
+import { normalizeTargetForProvider } from "../../infra/outbound/target-normalization.js";
 import { normalizeAccountId } from "../../routing/session-key.js";
-import { channelTargetSchema, channelTargetsSchema, stringEnum } from "../schema/typebox.js";
-import { listChannelSupportedActions } from "../channel-tools.js";
-import { normalizeMessageChannel } from "../../utils/message-channel.js";
 import { stripReasoningTagsFromText } from "../../shared/text/reasoning-tags.js";
+import { normalizeMessageChannel } from "../../utils/message-channel.js";
+import { resolveSessionAgentId } from "../agent-scope.js";
+import { listChannelSupportedActions } from "../channel-tools.js";
+import { channelTargetSchema, channelTargetsSchema, stringEnum } from "../schema/typebox.js";
 import { jsonResult, readNumberParam, readStringParam } from "./common.js";
+import { resolveGatewayOptions } from "./gateway.js";
 const AllMessageActions = CHANNEL_MESSAGE_ACTION_NAMES;
 const EXPLICIT_TARGET_ACTIONS = new Set([
     "send",
@@ -34,6 +35,90 @@ function buildRoutingSchema() {
         dryRun: Type.Optional(Type.Boolean()),
     };
 }
+const discordComponentEmojiSchema = Type.Object({
+    name: Type.String(),
+    id: Type.Optional(Type.String()),
+    animated: Type.Optional(Type.Boolean()),
+});
+const discordComponentOptionSchema = Type.Object({
+    label: Type.String(),
+    value: Type.String(),
+    description: Type.Optional(Type.String()),
+    emoji: Type.Optional(discordComponentEmojiSchema),
+    default: Type.Optional(Type.Boolean()),
+});
+const discordComponentButtonSchema = Type.Object({
+    label: Type.String(),
+    style: Type.Optional(stringEnum(["primary", "secondary", "success", "danger", "link"])),
+    url: Type.Optional(Type.String()),
+    emoji: Type.Optional(discordComponentEmojiSchema),
+    disabled: Type.Optional(Type.Boolean()),
+    allowedUsers: Type.Optional(Type.Array(Type.String({
+        description: "Discord user ids or names allowed to interact with this button.",
+    }))),
+});
+const discordComponentSelectSchema = Type.Object({
+    type: Type.Optional(stringEnum(["string", "user", "role", "mentionable", "channel"])),
+    placeholder: Type.Optional(Type.String()),
+    minValues: Type.Optional(Type.Number()),
+    maxValues: Type.Optional(Type.Number()),
+    options: Type.Optional(Type.Array(discordComponentOptionSchema)),
+});
+const discordComponentBlockSchema = Type.Object({
+    type: Type.String(),
+    text: Type.Optional(Type.String()),
+    texts: Type.Optional(Type.Array(Type.String())),
+    accessory: Type.Optional(Type.Object({
+        type: Type.String(),
+        url: Type.Optional(Type.String()),
+        button: Type.Optional(discordComponentButtonSchema),
+    })),
+    spacing: Type.Optional(stringEnum(["small", "large"])),
+    divider: Type.Optional(Type.Boolean()),
+    buttons: Type.Optional(Type.Array(discordComponentButtonSchema)),
+    select: Type.Optional(discordComponentSelectSchema),
+    items: Type.Optional(Type.Array(Type.Object({
+        url: Type.String(),
+        description: Type.Optional(Type.String()),
+        spoiler: Type.Optional(Type.Boolean()),
+    }))),
+    file: Type.Optional(Type.String()),
+    spoiler: Type.Optional(Type.Boolean()),
+});
+const discordComponentModalFieldSchema = Type.Object({
+    type: Type.String(),
+    name: Type.Optional(Type.String()),
+    label: Type.String(),
+    description: Type.Optional(Type.String()),
+    placeholder: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+    options: Type.Optional(Type.Array(discordComponentOptionSchema)),
+    minValues: Type.Optional(Type.Number()),
+    maxValues: Type.Optional(Type.Number()),
+    minLength: Type.Optional(Type.Number()),
+    maxLength: Type.Optional(Type.Number()),
+    style: Type.Optional(stringEnum(["short", "paragraph"])),
+});
+const discordComponentModalSchema = Type.Object({
+    title: Type.String(),
+    triggerLabel: Type.Optional(Type.String()),
+    triggerStyle: Type.Optional(stringEnum(["primary", "secondary", "success", "danger", "link"])),
+    fields: Type.Array(discordComponentModalFieldSchema),
+});
+const discordComponentMessageSchema = Type.Object({
+    text: Type.Optional(Type.String()),
+    reusable: Type.Optional(Type.Boolean({
+        description: "Allow components to be used multiple times until they expire.",
+    })),
+    container: Type.Optional(Type.Object({
+        accentColor: Type.Optional(Type.String()),
+        spoiler: Type.Optional(Type.Boolean()),
+    })),
+    blocks: Type.Optional(Type.Array(discordComponentBlockSchema)),
+    modal: Type.Optional(discordComponentModalSchema),
+}, {
+    description: "Discord components v2 payload. Set reusable=true to keep buttons, selects, and forms active until expiry.",
+});
 function buildSendSchema(options) {
     const props = {
         message: Type.Optional(Type.String()),
@@ -57,12 +142,13 @@ function buildSendSchema(options) {
         threadId: Type.Optional(Type.String()),
         asVoice: Type.Optional(Type.Boolean()),
         silent: Type.Optional(Type.Boolean()),
+        quoteText: Type.Optional(Type.String({ description: "Quote text for Telegram reply_parameters" })),
         bestEffort: Type.Optional(Type.Boolean()),
         gifPlayback: Type.Optional(Type.Boolean()),
-        quoteText: Type.Optional(Type.String({ description: "Quote text for Telegram reply_parameters" })),
         buttons: Type.Optional(Type.Array(Type.Array(Type.Object({
             text: Type.String(),
             callback_data: Type.String(),
+            style: Type.Optional(stringEnum(["danger", "success", "primary"])),
         })), {
             description: "Telegram inline keyboard buttons (array of button rows)",
         })),
@@ -70,11 +156,17 @@ function buildSendSchema(options) {
             additionalProperties: true,
             description: "Adaptive Card JSON object (when supported by the channel)",
         })),
+        components: Type.Optional(discordComponentMessageSchema),
     };
-    if (!options.includeButtons)
+    if (!options.includeButtons) {
         delete props.buttons;
-    if (!options.includeCards)
+    }
+    if (!options.includeCards) {
         delete props.card;
+    }
+    if (!options.includeComponents) {
+        delete props.components;
+    }
     return props;
 }
 function buildReactionSchema() {
@@ -159,21 +251,6 @@ function buildGatewaySchema() {
         timeoutMs: Type.Optional(Type.Number()),
     };
 }
-function buildChannelManagementSchema() {
-    return {
-        name: Type.Optional(Type.String()),
-        type: Type.Optional(Type.Number()),
-        parentId: Type.Optional(Type.String()),
-        topic: Type.Optional(Type.String()),
-        position: Type.Optional(Type.Number()),
-        nsfw: Type.Optional(Type.Boolean()),
-        rateLimitPerUser: Type.Optional(Type.Number()),
-        categoryId: Type.Optional(Type.String()),
-        clearParent: Type.Optional(Type.Boolean({
-            description: "Clear the parent/category when supported by the provider.",
-        })),
-    };
-}
 function buildPresenceSchema() {
     return {
         activityType: Type.Optional(Type.String({
@@ -191,6 +268,21 @@ function buildPresenceSchema() {
         status: Type.Optional(Type.String({ description: "Bot status: online, dnd, idle, invisible." })),
     };
 }
+function buildChannelManagementSchema() {
+    return {
+        name: Type.Optional(Type.String()),
+        type: Type.Optional(Type.Number()),
+        parentId: Type.Optional(Type.String()),
+        topic: Type.Optional(Type.String()),
+        position: Type.Optional(Type.Number()),
+        nsfw: Type.Optional(Type.Boolean()),
+        rateLimitPerUser: Type.Optional(Type.Number()),
+        categoryId: Type.Optional(Type.String()),
+        clearParent: Type.Optional(Type.Boolean({
+            description: "Clear the parent/category when supported by the provider.",
+        })),
+    };
+}
 function buildMessageToolSchemaProps(options) {
     return {
         ...buildRoutingSchema(),
@@ -218,37 +310,74 @@ function buildMessageToolSchemaFromActions(actions, options) {
 const MessageToolSchema = buildMessageToolSchemaFromActions(AllMessageActions, {
     includeButtons: true,
     includeCards: true,
+    includeComponents: true,
 });
-function buildMessageToolSchema(cfg) {
-    const actions = listChannelMessageActions(cfg);
-    const includeButtons = supportsChannelMessageButtons(cfg);
-    const includeCards = supportsChannelMessageCards(cfg);
+function resolveMessageToolSchemaActions(params) {
+    const currentChannel = normalizeMessageChannel(params.currentChannelProvider);
+    if (currentChannel) {
+        const scopedActions = filterActionsForContext({
+            actions: listChannelSupportedActions({
+                cfg: params.cfg,
+                channel: currentChannel,
+            }),
+            channel: currentChannel,
+            currentChannelId: params.currentChannelId,
+        });
+        const withSend = new Set(["send", ...scopedActions]);
+        return Array.from(withSend);
+    }
+    const actions = listChannelMessageActions(params.cfg);
+    return actions.length > 0 ? actions : ["send"];
+}
+function resolveIncludeComponents(params) {
+    const currentChannel = normalizeMessageChannel(params.currentChannelProvider);
+    if (currentChannel) {
+        return currentChannel === "discord";
+    }
+    // Components are currently Discord-specific.
+    return listChannelSupportedActions({ cfg: params.cfg, channel: "discord" }).length > 0;
+}
+function buildMessageToolSchema(params) {
+    const currentChannel = normalizeMessageChannel(params.currentChannelProvider);
+    const actions = resolveMessageToolSchemaActions(params);
+    const includeButtons = currentChannel
+        ? supportsChannelMessageButtonsForChannel({ cfg: params.cfg, channel: currentChannel })
+        : supportsChannelMessageButtons(params.cfg);
+    const includeCards = currentChannel
+        ? supportsChannelMessageCardsForChannel({ cfg: params.cfg, channel: currentChannel })
+        : supportsChannelMessageCards(params.cfg);
+    const includeComponents = resolveIncludeComponents(params);
     return buildMessageToolSchemaFromActions(actions.length > 0 ? actions : ["send"], {
         includeButtons,
         includeCards,
+        includeComponents,
     });
 }
 function resolveAgentAccountId(value) {
     const trimmed = value?.trim();
-    if (!trimmed)
+    if (!trimmed) {
         return undefined;
+    }
     return normalizeAccountId(trimmed);
 }
 function filterActionsForContext(params) {
     const channel = normalizeMessageChannel(params.channel);
-    if (!channel || channel !== "bluebubbles")
+    if (!channel || channel !== "bluebubbles") {
         return params.actions;
+    }
     const currentChannelId = params.currentChannelId?.trim();
-    if (!currentChannelId)
+    if (!currentChannelId) {
         return params.actions;
+    }
     const normalizedTarget = normalizeTargetForProvider(channel, currentChannelId) ?? currentChannelId;
     const lowered = normalizedTarget.trim().toLowerCase();
     const isGroupTarget = lowered.startsWith("chat_guid:") ||
         lowered.startsWith("chat_id:") ||
         lowered.startsWith("chat_identifier:") ||
         lowered.startsWith("group:");
-    if (isGroupTarget)
+    if (isGroupTarget) {
         return params.actions;
+    }
     return params.actions.filter((action) => !BLUEBUBBLES_GROUP_ACTIONS.has(action));
 }
 function buildMessageToolDescription(options) {
@@ -266,7 +395,7 @@ function buildMessageToolDescription(options) {
         if (channelActions.length > 0) {
             // Always include "send" as a base action
             const allActions = new Set(["send", ...channelActions]);
-            const actionList = Array.from(allActions).sort().join(", ");
+            const actionList = Array.from(allActions).toSorted().join(", ");
             return `${baseDescription} Current channel (${options.currentChannel}) supports: ${actionList}.`;
         }
     }
@@ -281,7 +410,13 @@ function buildMessageToolDescription(options) {
 }
 export function createMessageTool(options) {
     const agentAccountId = resolveAgentAccountId(options?.agentAccountId);
-    const schema = options?.config ? buildMessageToolSchema(options.config) : MessageToolSchema;
+    const schema = options?.config
+        ? buildMessageToolSchema({
+            cfg: options.config,
+            currentChannelProvider: options.currentChannelProvider,
+            currentChannelId: options.currentChannelId,
+        })
+        : MessageToolSchema;
     const description = buildMessageToolDescription({
         config: options?.config,
         currentChannel: options?.currentChannelProvider,
@@ -312,7 +447,6 @@ export function createMessageTool(options) {
             const action = readStringParam(params, "action", {
                 required: true,
             });
-            // Enforce explicit target when required (e.g. cron/hook-initiated runs).
             const requireExplicitTarget = options?.requireExplicitTarget === true;
             if (requireExplicitTarget && actionNeedsExplicitTarget(action)) {
                 const explicitTarget = (typeof params.target === "string" && params.target.trim().length > 0) ||
@@ -328,10 +462,15 @@ export function createMessageTool(options) {
             if (accountId) {
                 params.accountId = accountId;
             }
-            const gateway = {
-                url: readStringParam(params, "gatewayUrl", { trim: false }),
-                token: readStringParam(params, "gatewayToken", { trim: false }),
+            const gatewayResolved = resolveGatewayOptions({
+                gatewayUrl: readStringParam(params, "gatewayUrl", { trim: false }),
+                gatewayToken: readStringParam(params, "gatewayToken", { trim: false }),
                 timeoutMs: readNumberParam(params, "timeoutMs"),
+            });
+            const gateway = {
+                url: gatewayResolved.url,
+                token: gatewayResolved.token,
+                timeoutMs: gatewayResolved.timeoutMs,
                 clientName: GATEWAY_CLIENT_IDS.GATEWAY_CLIENT,
                 clientDisplayName: "agent",
                 mode: GATEWAY_CLIENT_MODES.BACKEND,
@@ -359,6 +498,7 @@ export function createMessageTool(options) {
                 defaultAccountId: accountId ?? undefined,
                 gateway,
                 toolContext,
+                sessionKey: options?.agentSessionKey,
                 agentId: options?.agentSessionKey
                     ? resolveSessionAgentId({ sessionKey: options.agentSessionKey, config: cfg })
                     : undefined,
@@ -366,8 +506,9 @@ export function createMessageTool(options) {
                 abortSignal: signal,
             });
             const toolResult = getToolResult(result);
-            if (toolResult)
+            if (toolResult) {
                 return toolResult;
+            }
             return jsonResult(result.payload);
         },
     };

package/dist/agents/tools/nodes-tool.js

@@ -1,15 +1,16 @@
 import crypto from "node:crypto";
 import { Type } from "@sinclair/typebox";
-import { cameraTempPath, parseCameraClipPayload, parseCameraSnapPayload, writeBase64ToFile, } from "../../cli/nodes-camera.js";
+import { cameraTempPath, parseCameraClipPayload, parseCameraSnapPayload, writeBase64ToFile, writeUrlToFile, } from "../../cli/nodes-camera.js";
 import { parseEnvPairs, parseTimeoutMs } from "../../cli/nodes-run.js";
 import { parseScreenRecordPayload, screenRecordTempPath, writeScreenRecordToFile, } from "../../cli/nodes-screen.js";
 import { parseDurationMs } from "../../cli/parse-duration.js";
 import { imageMimeFromFormat } from "../../media/mime.js";
 import { resolveSessionAgentId } from "../agent-scope.js";
+import { resolveImageSanitizationLimits } from "../image-sanitization.js";
 import { optionalStringEnum, stringEnum } from "../schema/typebox.js";
 import { sanitizeToolResultImages } from "../tool-images.js";
 import { jsonResult, readStringParam } from "./common.js";
-import { callGatewayTool } from "./gateway.js";
+import { callGatewayTool, readGatewayCallOptions } from "./gateway.js";
 import { listNodes, resolveNodeIdFromList, resolveNodeId } from "./nodes-utils.js";
 const NODES_TOOL_ACTIONS = [
     "status",
@@ -24,6 +25,7 @@ const NODES_TOOL_ACTIONS = [
     "screen_record",
     "location_get",
     "run",
+    "invoke",
 ];
 const NOTIFY_PRIORITIES = ["passive", "active", "timeSensitive"];
 const NOTIFY_DELIVERIES = ["system", "overlay", "auto"];
@@ -69,6 +71,9 @@ const NodesToolSchema = Type.Object({
     commandTimeoutMs: Type.Optional(Type.Number()),
     invokeTimeoutMs: Type.Optional(Type.Number()),
     needsScreenRecording: Type.Optional(Type.Boolean()),
+    // invoke
+    invokeCommand: Type.Optional(Type.String()),
+    invokeParamsJson: Type.Optional(Type.String()),
 });
 export function createNodesTool(options) {
     const sessionKey = options?.agentSessionKey?.trim() || undefined;
@@ -76,19 +81,16 @@ export function createNodesTool(options) {
         sessionKey: options?.agentSessionKey,
         config: options?.config,
     });
+    const imageSanitization = resolveImageSanitizationLimits(options?.config);
     return {
         label: "Nodes",
         name: "nodes",
-        description: "Discover and control paired nodes (status/describe/pairing/notify/camera/screen/location/run).",
+        description: "Discover and control paired nodes (status/describe/pairing/notify/camera/screen/location/run/invoke).",
         parameters: NodesToolSchema,
         execute: async (_toolCallId, args) => {
             const params = args;
             const action = readStringParam(params, "action", { required: true });
-            const gatewayOpts = {
-                gatewayUrl: readStringParam(params, "gatewayUrl", { trim: false }),
-                gatewayToken: readStringParam(params, "gatewayToken", { trim: false }),
-                timeoutMs: typeof params.timeoutMs === "number" ? params.timeoutMs : undefined,
-            };
+            const gatewayOpts = readGatewayCallOptions(params);
             try {
                 switch (action) {
                     case "status":
@@ -164,7 +166,7 @@ export function createNodesTool(options) {
                         const content = [];
                         const details = [];
                         for (const facing of facings) {
-                            const raw = (await callGatewayTool("node.invoke", gatewayOpts, {
+                            const raw = await callGatewayTool("node.invoke", gatewayOpts, {
                                 nodeId,
                                 command: "camera.snap",
                                 params: {
@@ -176,7 +178,7 @@ export function createNodesTool(options) {
                                     deviceId,
                                 },
                                 idempotencyKey: crypto.randomUUID(),
-                            }));
+                            });
                             const payload = parseCameraSnapPayload(raw?.payload);
                             const normalizedFormat = payload.format.toLowerCase();
                             if (normalizedFormat !== "jpg" &&
@@ -190,13 +192,20 @@ export function createNodesTool(options) {
                                 facing,
                                 ext: isJpeg ? "jpg" : "png",
                             });
-                            await writeBase64ToFile(filePath, payload.base64);
+                            if (payload.url) {
+                                await writeUrlToFile(filePath, payload.url);
+                            }
+                            else if (payload.base64) {
+                                await writeBase64ToFile(filePath, payload.base64);
+                            }
                             content.push({ type: "text", text: `MEDIA:${filePath}` });
-                            content.push({
-                                type: "image",
-                                data: payload.base64,
-                                mimeType: imageMimeFromFormat(payload.format) ?? (isJpeg ? "image/jpeg" : "image/png"),
-                            });
+                            if (payload.base64) {
+                                content.push({
+                                    type: "image",
+                                    data: payload.base64,
+                                    mimeType: imageMimeFromFormat(payload.format) ?? (isJpeg ? "image/jpeg" : "image/png"),
+                                });
+                            }
                             details.push({
                                 facing,
                                 path: filePath,
@@ -205,17 +214,17 @@ export function createNodesTool(options) {
                             });
                         }
                         const result = { content, details };
-                        return await sanitizeToolResultImages(result, "nodes:camera_snap");
+                        return await sanitizeToolResultImages(result, "nodes:camera_snap", imageSanitization);
                     }
                     case "camera_list": {
                         const node = readStringParam(params, "node", { required: true });
                         const nodeId = await resolveNodeId(gatewayOpts, node);
-                        const raw = (await callGatewayTool("node.invoke", gatewayOpts, {
+                        const raw = await callGatewayTool("node.invoke", gatewayOpts, {
                             nodeId,
                             command: "camera.list",
                             params: {},
                             idempotencyKey: crypto.randomUUID(),
-                        }));
+                        });
                         const payload = raw && typeof raw.payload === "object" && raw.payload !== null ? raw.payload : {};
                         return jsonResult(payload);
                     }
@@ -235,7 +244,7 @@ export function createNodesTool(options) {
                         const deviceId = typeof params.deviceId === "string" && params.deviceId.trim()
                             ? params.deviceId.trim()
                             : undefined;
-                        const raw = (await callGatewayTool("node.invoke", gatewayOpts, {
+                        const raw = await callGatewayTool("node.invoke", gatewayOpts, {
                             nodeId,
                             command: "camera.clip",
                             params: {
@@ -246,14 +255,19 @@ export function createNodesTool(options) {
                                 deviceId,
                             },
                             idempotencyKey: crypto.randomUUID(),
-                        }));
+                        });
                         const payload = parseCameraClipPayload(raw?.payload);
                         const filePath = cameraTempPath({
                             kind: "clip",
                             facing,
                             ext: payload.format,
                         });
-                        await writeBase64ToFile(filePath, payload.base64);
+                        if (payload.url) {
+                            await writeUrlToFile(filePath, payload.url);
+                        }
+                        else if (payload.base64) {
+                            await writeBase64ToFile(filePath, payload.base64);
+                        }
                         return {
                             content: [{ type: "text", text: `FILE:${filePath}` }],
                             details: {
@@ -277,7 +291,7 @@ export function createNodesTool(options) {
                             ? params.screenIndex
                             : 0;
                         const includeAudio = typeof params.includeAudio === "boolean" ? params.includeAudio : true;
-                        const raw = (await callGatewayTool("node.invoke", gatewayOpts, {
+                        const raw = await callGatewayTool("node.invoke", gatewayOpts, {
                             nodeId,
                             command: "screen.record",
                             params: {
@@ -288,7 +302,7 @@ export function createNodesTool(options) {
                                 includeAudio,
                             },
                             idempotencyKey: crypto.randomUUID(),
-                        }));
+                        });
                         const payload = parseScreenRecordPayload(raw?.payload);
                         const filePath = typeof params.outPath === "string" && params.outPath.trim()
                             ? params.outPath.trim()
@@ -320,7 +334,7 @@ export function createNodesTool(options) {
                             Number.isFinite(params.locationTimeoutMs)
                             ? params.locationTimeoutMs
                             : undefined;
-                        const raw = (await callGatewayTool("node.invoke", gatewayOpts, {
+                        const raw = await callGatewayTool("node.invoke", gatewayOpts, {
                             nodeId,
                             command: "location.get",
                             params: {
@@ -329,7 +343,7 @@ export function createNodesTool(options) {
                                 timeoutMs: locationTimeoutMs,
                             },
                             idempotencyKey: crypto.randomUUID(),
-                        }));
+                        });
                         return jsonResult(raw?.payload ?? {});
                     }
                     case "run": {
@@ -364,23 +378,101 @@ export function createNodesTool(options) {
                         const needsScreenRecording = typeof params.needsScreenRecording === "boolean"
                             ? params.needsScreenRecording
                             : undefined;
-                        const raw = (await callGatewayTool("node.invoke", gatewayOpts, {
+                        const runParams = {
+                            command,
+                            cwd,
+                            env,
+                            timeoutMs: commandTimeoutMs,
+                            needsScreenRecording,
+                            agentId,
+                            sessionKey,
+                        };
+                        // First attempt without approval flags.
+                        try {
+                            const raw = await callGatewayTool("node.invoke", gatewayOpts, {
+                                nodeId,
+                                command: "system.run",
+                                params: runParams,
+                                timeoutMs: invokeTimeoutMs,
+                                idempotencyKey: crypto.randomUUID(),
+                            });
+                            return jsonResult(raw?.payload ?? {});
+                        }
+                        catch (firstErr) {
+                            const msg = firstErr instanceof Error ? firstErr.message : String(firstErr);
+                            if (!msg.includes("SYSTEM_RUN_DENIED: approval required")) {
+                                throw firstErr;
+                            }
+                        }
+                        // Node requires approval – create a pending approval request on
+                        // the gateway and wait for the user to approve/deny via the UI.
+                        const APPROVAL_TIMEOUT_MS = 120_000;
+                        const cmdText = command.join(" ");
+                        const approvalId = crypto.randomUUID();
+                        const approvalResult = await callGatewayTool("exec.approval.request", { ...gatewayOpts, timeoutMs: APPROVAL_TIMEOUT_MS + 5_000 }, {
+                            id: approvalId,
+                            command: cmdText,
+                            cwd,
+                            host: "node",
+                            agentId,
+                            sessionKey,
+                            timeoutMs: APPROVAL_TIMEOUT_MS,
+                        });
+                        const decisionRaw = approvalResult && typeof approvalResult === "object"
+                            ? approvalResult.decision
+                            : undefined;
+                        const approvalDecision = decisionRaw === "allow-once" || decisionRaw === "allow-always" ? decisionRaw : null;
+                        if (!approvalDecision) {
+                            if (decisionRaw === "deny") {
+                                throw new Error("exec denied: user denied");
+                            }
+                            if (decisionRaw === undefined || decisionRaw === null) {
+                                throw new Error("exec denied: approval timed out");
+                            }
+                            throw new Error("exec denied: invalid approval decision");
+                        }
+                        // Retry with the approval decision.
+                        const raw = await callGatewayTool("node.invoke", gatewayOpts, {
                             nodeId,
                             command: "system.run",
                             params: {
-                                command,
-                                cwd,
-                                env,
-                                timeoutMs: commandTimeoutMs,
-                                needsScreenRecording,
-                                agentId,
-                                sessionKey,
+                                ...runParams,
+                                runId: approvalId,
+                                approved: true,
+                                approvalDecision,
                             },
                             timeoutMs: invokeTimeoutMs,
                             idempotencyKey: crypto.randomUUID(),
-                        }));
+                        });
                         return jsonResult(raw?.payload ?? {});
                     }
+                    case "invoke": {
+                        const node = readStringParam(params, "node", { required: true });
+                        const nodeId = await resolveNodeId(gatewayOpts, node);
+                        const invokeCommand = readStringParam(params, "invokeCommand", { required: true });
+                        const invokeParamsJson = typeof params.invokeParamsJson === "string" ? params.invokeParamsJson.trim() : "";
+                        let invokeParams = {};
+                        if (invokeParamsJson) {
+                            try {
+                                invokeParams = JSON.parse(invokeParamsJson);
+                            }
+                            catch (err) {
+                                const message = err instanceof Error ? err.message : String(err);
+                                throw new Error(`invokeParamsJson must be valid JSON: ${message}`, {
+                                    cause: err,
+                                });
+                            }
+                        }
+                        const invokeTimeoutMs = parseTimeoutMs(params.invokeTimeoutMs);
+                        const raw = await callGatewayTool("node.invoke", gatewayOpts, {
+                            nodeId,
+                            command: invokeCommand,
+                            params: invokeParams,
+                            timeoutMs: invokeTimeoutMs,
+                            idempotencyKey: crypto.randomUUID(),
+                        });
+                        return jsonResult(raw ?? {});
+                    }
                     default:
                         throw new Error(`Unknown action: ${action}`);
                 }
@@ -392,7 +484,7 @@ export function createNodesTool(options) {
                     : "default";
                 const agentLabel = agentId ?? "unknown";
                 const message = err instanceof Error ? err.message : String(err);
-                throw new Error(`agent=${agentLabel} node=${nodeLabel} gateway=${gatewayLabel} action=${action}: ${message}`);
+                throw new Error(`agent=${agentLabel} node=${nodeLabel} gateway=${gatewayLabel} action=${action}: ${message}`, { cause: err });
             }
         },
     };