@wingman-ai/gateway 0.4.0 → 0.4.2

package/dist/agent/middleware/additional-messages.js

@@ -2,6 +2,7 @@ import { isAbsolute, relative } from "node:path";
 import { HumanMessage, MIDDLEWARE_BRAND } from "langchain";
 import { getConfidentialityNotice } from "../utils.js";
 import { loadUiRegistry, resolveUiRegistryPath, summarizeUiRegistry } from "../uiRegistry.js";
+const INJECTION_SOURCE = "additional-message-middleware";
 const normalizeRelativePath = (value)=>value.replace(/\\/g, "/");
 const toSafeRelativePath = (workspaceRoot, targetPath)=>{
     if (!workspaceRoot) return null;
@@ -28,12 +29,108 @@ const buildWorkingDirectoryMessage = (context)=>{
     if (!context.workspaceRoot) return null;
     return "** Working Directory **\n- Treat `./` as the current working directory for file and tool operations in this session.\n- Use relative paths such as `./test.md`; do not prepend the working directory absolute path.";
 };
+const resolveConnectedNodeIds = async (context)=>{
+    if (context.nodeConnectedTargetsProvider) try {
+        const rawTargets = await context.nodeConnectedTargetsProvider();
+        if (!Array.isArray(rawTargets)) return [];
+        const seen = new Set();
+        const normalized = [];
+        for (const target of rawTargets){
+            if (!target || "object" != typeof target) continue;
+            const nodeId = target.nodeId?.trim();
+            if (!(!nodeId || seen.has(nodeId))) {
+                seen.add(nodeId);
+                normalized.push(nodeId);
+            }
+        }
+        return normalized;
+    } catch  {
+        return [];
+    }
+    if (!context.nodeConnectedIdsProvider) return [];
+    try {
+        const rawIds = await context.nodeConnectedIdsProvider();
+        if (!Array.isArray(rawIds)) return [];
+        const seen = new Set();
+        const normalized = [];
+        for (const value of rawIds){
+            if ("string" != typeof value) continue;
+            const trimmed = value.trim();
+            if (!(!trimmed || seen.has(trimmed))) {
+                seen.add(trimmed);
+                normalized.push(trimmed);
+            }
+        }
+        return normalized;
+    } catch  {
+        return [];
+    }
+};
+const resolveConnectedNodeTargets = async (context)=>{
+    if (context.nodeConnectedTargetsProvider) try {
+        const rawTargets = await context.nodeConnectedTargetsProvider();
+        if (!Array.isArray(rawTargets)) return [];
+        const seen = new Set();
+        const normalized = [];
+        for (const target of rawTargets){
+            if (!target || "object" != typeof target) continue;
+            const typedTarget = target;
+            const nodeId = typedTarget.nodeId?.trim();
+            if (!nodeId || seen.has(nodeId)) continue;
+            seen.add(nodeId);
+            const rawCapabilities = typedTarget.capabilities;
+            const capabilities = Array.isArray(rawCapabilities) ? rawCapabilities.filter((value)=>"string" == typeof value).map((value)=>value.trim()).filter(Boolean) : [];
+            normalized.push({
+                nodeId,
+                clientId: typedTarget.clientId?.trim() || void 0,
+                name: typedTarget.name?.trim() || void 0,
+                capabilities: capabilities.length > 0 ? capabilities : void 0
+            });
+        }
+        return normalized;
+    } catch  {
+        return [];
+    }
+    const nodeIds = await resolveConnectedNodeIds(context);
+    return nodeIds.map((nodeId)=>({
+            nodeId
+        }));
+};
+const buildNodeTargetsMessage = async (context)=>{
+    const connectedNodeTargets = await resolveConnectedNodeTargets(context);
+    const connectedNodeIds = connectedNodeTargets.map((target)=>target.nodeId);
+    const defaultClientId = context.defaultNodeTargetClientId?.trim();
+    if (0 === connectedNodeIds.length && !defaultClientId) return null;
+    const lines = [
+        "** Connected Node Targets **"
+    ];
+    if (connectedNodeIds.length > 0) lines.push(`- Connected node IDs: ${connectedNodeIds.join(", ")}`);
+    else lines.push("- Connected node IDs: (none currently connected)");
+    const withMetadata = connectedNodeTargets.filter((target)=>Boolean(target.clientId) || Boolean(target.name) || target.capabilities && target.capabilities.length > 0);
+    if (withMetadata.length > 0) {
+        lines.push("- Connected node metadata:");
+        for (const target of withMetadata.slice(0, 8)){
+            const details = [];
+            if (target.clientId) details.push(`clientId: ${target.clientId}`);
+            if (target.name) details.push(`name: ${target.name}`);
+            if (target.capabilities && target.capabilities.length > 0) {
+                const preview = target.capabilities.slice(0, 6).join(", ");
+                const remaining = target.capabilities.length - 6;
+                details.push(remaining > 0 ? `capabilities: ${preview} (+${remaining} more)` : `capabilities: ${preview}`);
+            }
+            if (details.length > 0) lines.push(`  - ${target.nodeId} (${details.join("; ")})`);
+        }
+        if (withMetadata.length > 8) lines.push(`  - ... ${withMetadata.length - 8} more connected node(s)`);
+    }
+    if (defaultClientId) lines.push(`- Default node target clientId for this request: ${defaultClientId}`);
+    lines.push("- For node_notify/node_run, set target.nodeId or target.clientId when the user specifies a device.");
+    return lines.join("\n");
+};
 const additionalMessageMiddleware = (context = {})=>({
-        name: "additional-message-middleware",
+        name: INJECTION_SOURCE,
         [MIDDLEWARE_BRAND]: true,
         beforeAgent: async (input)=>{
-            const alreadyInjected = input.messages.some((message)=>message?.additional_kwargs?.source === "additional-message-middleware");
-            if (alreadyInjected) return input;
+            const messagesWithoutInjected = input.messages.filter((message)=>message?.additional_kwargs?.source !== INJECTION_SOURCE);
             const lines = [
                 getConfidentialityNotice(),
                 `** Current Date Time (UTC): ${new Date().toISOString()} **`
@@ -42,6 +139,8 @@ const additionalMessageMiddleware = (context = {})=>({
             if (outputLocation) lines.push(outputLocation);
             const workingDirectory = buildWorkingDirectoryMessage(context);
             if (workingDirectory) lines.push(workingDirectory);
+            const nodeTargets = await buildNodeTargetsMessage(context);
+            if (nodeTargets) lines.push(nodeTargets);
             lines.push("** Long-term memory **\n- Use /memories/ for durable notes across threads.\n- Store stable preferences, project context, decisions, and research notes.\n- Avoid transient logs; keep entries concise and organized.\n- Suggested paths: /memories/preferences.md, /memories/projects/<name>/context.md, /memories/projects/<name>/decisions.md");
             if (false === context.dynamicUiEnabled) lines.push("** Dynamic UI **\n- Dynamic UI rendering is disabled for this gateway.\n- Respond with plain text and avoid calling UI presentation tools.");
             else {
@@ -54,14 +153,19 @@ const additionalMessageMiddleware = (context = {})=>({
                     lines.push("** Dynamic UI Registry **\n" + summaryLines + "\n- Use ui_registry_get for schema details, then ui_present with textFallback.");
                 }
             }
-            input.messages.unshift(new HumanMessage({
-                content: lines.join("\n\n"),
-                additional_kwargs: {
-                    ui_hidden: true,
-                    source: "additional-message-middleware"
-                }
-            }));
-            return input;
+            return {
+                ...input,
+                messages: [
+                    new HumanMessage({
+                        content: lines.join("\n\n"),
+                        additional_kwargs: {
+                            ui_hidden: true,
+                            source: INJECTION_SOURCE
+                        }
+                    }),
+                    ...messagesWithoutInjected
+                ]
+            };
         }
     });
 export { additionalMessageMiddleware };

package/dist/agent/tests/agentLoader.test.cjs

@@ -197,6 +197,51 @@ Markdown agent`;
         });
     });
     (0, external_vitest_namespaceObject.describe)("loadAgent", ()=>{
+        (0, external_vitest_namespaceObject.it)("should always inject node tools for top-level agents", async ()=>{
+            const agentDir = (0, external_node_path_namespaceObject.join)(TEST_CONFIG_DIR, "agents", "node-enabled-agent");
+            (0, external_node_fs_namespaceObject.mkdirSync)(agentDir, {
+                recursive: true
+            });
+            const config = {
+                name: "node-enabled-agent",
+                description: "Agent with default node tools",
+                systemPrompt: "You are node capable"
+            };
+            (0, external_node_fs_namespaceObject.writeFileSync)((0, external_node_path_namespaceObject.join)(agentDir, "agent.json"), JSON.stringify(config));
+            const loader = new agentLoader_cjs_namespaceObject.AgentLoader(TEST_CONFIG_DIR);
+            const agent = await loader.loadAgent("node-enabled-agent");
+            const toolNames = (agent?.tools || []).map((tool)=>tool.name);
+            (0, external_vitest_namespaceObject.expect)(toolNames).toContain("node_notify");
+            (0, external_vitest_namespaceObject.expect)(toolNames).toContain("node_run");
+        });
+        (0, external_vitest_namespaceObject.it)("should always inject and deduplicate node tools for subagents", async ()=>{
+            const agentDir = (0, external_node_path_namespaceObject.join)(TEST_CONFIG_DIR, "agents", "node-subagent-parent");
+            (0, external_node_fs_namespaceObject.mkdirSync)(agentDir, {
+                recursive: true
+            });
+            const config = {
+                name: "node-subagent-parent",
+                description: "Parent agent",
+                systemPrompt: "You are the parent",
+                subAgents: [
+                    {
+                        name: "node-subagent",
+                        description: "Subagent",
+                        systemPrompt: "You are a subagent",
+                        tools: [
+                            "node_run"
+                        ]
+                    }
+                ]
+            };
+            (0, external_node_fs_namespaceObject.writeFileSync)((0, external_node_path_namespaceObject.join)(agentDir, "agent.json"), JSON.stringify(config));
+            const loader = new agentLoader_cjs_namespaceObject.AgentLoader(TEST_CONFIG_DIR);
+            const agent = await loader.loadAgent("node-subagent-parent");
+            const sub = agent?.subagents?.[0];
+            const toolNames = (sub?.tools || []).map((tool)=>tool.name);
+            (0, external_vitest_namespaceObject.expect)(toolNames).toContain("node_notify");
+            (0, external_vitest_namespaceObject.expect)(toolNames.filter((name)=>"node_run" === name)).toHaveLength(1);
+        });
         (0, external_vitest_namespaceObject.it)("should hydrate subagent tools for runtime use", async ()=>{
             const agentDir = (0, external_node_path_namespaceObject.join)(TEST_CONFIG_DIR, "agents", "parent-agent");
             (0, external_node_fs_namespaceObject.mkdirSync)(agentDir, {

package/dist/agent/tests/agentLoader.test.js

@@ -195,6 +195,51 @@ Markdown agent`;
         });
     });
     describe("loadAgent", ()=>{
+        it("should always inject node tools for top-level agents", async ()=>{
+            const agentDir = join(TEST_CONFIG_DIR, "agents", "node-enabled-agent");
+            mkdirSync(agentDir, {
+                recursive: true
+            });
+            const config = {
+                name: "node-enabled-agent",
+                description: "Agent with default node tools",
+                systemPrompt: "You are node capable"
+            };
+            writeFileSync(join(agentDir, "agent.json"), JSON.stringify(config));
+            const loader = new AgentLoader(TEST_CONFIG_DIR);
+            const agent = await loader.loadAgent("node-enabled-agent");
+            const toolNames = (agent?.tools || []).map((tool)=>tool.name);
+            expect(toolNames).toContain("node_notify");
+            expect(toolNames).toContain("node_run");
+        });
+        it("should always inject and deduplicate node tools for subagents", async ()=>{
+            const agentDir = join(TEST_CONFIG_DIR, "agents", "node-subagent-parent");
+            mkdirSync(agentDir, {
+                recursive: true
+            });
+            const config = {
+                name: "node-subagent-parent",
+                description: "Parent agent",
+                systemPrompt: "You are the parent",
+                subAgents: [
+                    {
+                        name: "node-subagent",
+                        description: "Subagent",
+                        systemPrompt: "You are a subagent",
+                        tools: [
+                            "node_run"
+                        ]
+                    }
+                ]
+            };
+            writeFileSync(join(agentDir, "agent.json"), JSON.stringify(config));
+            const loader = new AgentLoader(TEST_CONFIG_DIR);
+            const agent = await loader.loadAgent("node-subagent-parent");
+            const sub = agent?.subagents?.[0];
+            const toolNames = (sub?.tools || []).map((tool)=>tool.name);
+            expect(toolNames).toContain("node_notify");
+            expect(toolNames.filter((name)=>"node_run" === name)).toHaveLength(1);
+        });
         it("should hydrate subagent tools for runtime use", async ()=>{
             const agentDir = join(TEST_CONFIG_DIR, "agents", "parent-agent");
             mkdirSync(agentDir, {

package/dist/agent/tests/toolRegistry.test.cjs

@@ -124,6 +124,8 @@ const terminal_session_manager_cjs_namespaceObject = require("../tools/terminal_
                 "browser_control",
                 "command_execute",
                 "background_terminal",
+                "node_notify",
+                "node_run",
                 "think",
                 "code_search",
                 "git_status",

package/dist/agent/tests/toolRegistry.test.js

@@ -122,6 +122,8 @@ describe("Tool Registry", ()=>{
                 "browser_control",
                 "command_execute",
                 "background_terminal",
+                "node_notify",
+                "node_run",
                 "think",
                 "code_search",
                 "git_status",

package/dist/agent/tools/node_invoke.cjs

@@ -0,0 +1,146 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    createNodeNotifyTool: ()=>createNodeNotifyTool,
+    createNodeRunTool: ()=>createNodeRunTool
+});
+const external_langchain_namespaceObject = require("langchain");
+const external_zod_namespaceObject = require("zod");
+const DEFAULT_NODE_TIMEOUT_MS = 30000;
+const TargetSchema = external_zod_namespaceObject.object({
+    nodeId: external_zod_namespaceObject.string().min(1).optional(),
+    clientId: external_zod_namespaceObject.string().min(1).optional()
+}).optional();
+function resolveTarget(target, defaultTargetClientId) {
+    const targetNodeId = target?.nodeId?.trim();
+    if (targetNodeId) return {
+        targetNodeId
+    };
+    const targetClientId = target?.clientId?.trim() || defaultTargetClientId?.trim();
+    if (targetClientId) return {
+        targetClientId
+    };
+    return {};
+}
+function missingInvokerResult(toolName) {
+    return {
+        ok: false,
+        error: `${toolName} is only available when invoked through Wingman Gateway.`
+    };
+}
+const createNodeNotifyTool = (options = {})=>{
+    const { nodeInvoker, defaultTargetClientId } = options;
+    return (0, external_langchain_namespaceObject.tool)(async ({ body, title, target, timeoutMs })=>{
+        if (!nodeInvoker) return missingInvokerResult("node_notify");
+        try {
+            const { targetNodeId, targetClientId } = resolveTarget(target, defaultTargetClientId);
+            const result = await nodeInvoker({
+                tool: "system.notify",
+                args: {
+                    title: title?.trim() || "Wingman",
+                    body: body.trim()
+                },
+                timeoutMs: timeoutMs ?? DEFAULT_NODE_TIMEOUT_MS,
+                targetNodeId,
+                targetClientId,
+                capability: "system.notify"
+            });
+            const payload = result.payload && "object" == typeof result.payload ? result.payload : null;
+            return {
+                ok: true,
+                nodeId: result.nodeId,
+                delivered: payload?.delivered === true,
+                payload: result.payload
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }, {
+        name: "node_notify",
+        description: "Send a user-visible notification on an approved connected node device via system.notify.",
+        schema: external_zod_namespaceObject.object({
+            body: external_zod_namespaceObject.string().min(1).describe("Notification body text shown on the node device"),
+            title: external_zod_namespaceObject.string().min(1).optional().describe("Optional notification title"),
+            target: TargetSchema.describe("Optional target selector. Use nodeId for a specific node or clientId for a paired device."),
+            timeoutMs: external_zod_namespaceObject.number().int().min(1000).max(120000).optional().describe("Optional timeout for node execution in milliseconds")
+        })
+    });
+};
+const createNodeRunTool = (options = {})=>{
+    const { nodeInvoker, defaultTargetClientId } = options;
+    return (0, external_langchain_namespaceObject.tool)(async ({ command, args, target, timeoutMs })=>{
+        if (!nodeInvoker) return missingInvokerResult("node_run");
+        try {
+            const { targetNodeId, targetClientId } = resolveTarget(target, defaultTargetClientId);
+            const result = await nodeInvoker({
+                tool: "system.run",
+                args: {
+                    command: command.trim(),
+                    args: Array.isArray(args) ? args : []
+                },
+                timeoutMs: timeoutMs ?? DEFAULT_NODE_TIMEOUT_MS,
+                targetNodeId,
+                targetClientId,
+                capability: "system.run"
+            });
+            const payload = result.payload && "object" == typeof result.payload ? result.payload : null;
+            return {
+                ok: true,
+                nodeId: result.nodeId,
+                exitCode: "number" == typeof payload?.exitCode ? payload.exitCode : void 0,
+                stdout: "string" == typeof payload?.stdout ? payload.stdout : "",
+                stderr: "string" == typeof payload?.stderr ? payload.stderr : "",
+                payload: result.payload
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }, {
+        name: "node_run",
+        description: "Run a command on an approved connected node device via system.run and return exitCode/stdout/stderr.",
+        schema: external_zod_namespaceObject.object({
+            command: external_zod_namespaceObject.string().min(1).describe("Executable command path/name to run on the node device"),
+            args: external_zod_namespaceObject.array(external_zod_namespaceObject.string()).optional().describe("Optional command arguments"),
+            target: TargetSchema.describe("Optional target selector. Use nodeId for a specific node or clientId for a paired device."),
+            timeoutMs: external_zod_namespaceObject.number().int().min(1000).max(120000).optional().describe("Optional timeout for node execution in milliseconds")
+        })
+    });
+};
+exports.createNodeNotifyTool = __webpack_exports__.createNodeNotifyTool;
+exports.createNodeRunTool = __webpack_exports__.createNodeRunTool;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createNodeNotifyTool",
+    "createNodeRunTool"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/agent/tools/node_invoke.d.ts

@@ -0,0 +1,86 @@
+import * as z from "zod";
+export type NodeInvokeRequest = {
+    tool: "system.notify" | "system.run";
+    args?: Record<string, unknown>;
+    timeoutMs?: number;
+    targetNodeId?: string;
+    targetClientId?: string;
+    capability?: string;
+};
+export type NodeInvokeResult = {
+    nodeId: string;
+    payload: unknown;
+};
+export type NodeInvoker = (request: NodeInvokeRequest) => Promise<NodeInvokeResult>;
+export interface NodeToolOptions {
+    nodeInvoker?: NodeInvoker;
+    defaultTargetClientId?: string;
+}
+export declare const createNodeNotifyTool: (options?: NodeToolOptions) => import("langchain").DynamicStructuredTool<z.ZodObject<{
+    body: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodObject<{
+        nodeId: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, {
+    body: string;
+    title?: string;
+    target?: {
+        nodeId?: string;
+        clientId?: string;
+    };
+    timeoutMs?: number;
+}, {
+    body: string;
+    title?: string | undefined;
+    target?: {
+        nodeId?: string | undefined;
+        clientId?: string | undefined;
+    } | undefined;
+    timeoutMs?: number | undefined;
+}, {
+    ok: boolean;
+    error: string;
+} | {
+    ok: boolean;
+    nodeId: string;
+    delivered: boolean;
+    payload: unknown;
+}, "node_notify">;
+export declare const createNodeRunTool: (options?: NodeToolOptions) => import("langchain").DynamicStructuredTool<z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    target: z.ZodOptional<z.ZodObject<{
+        nodeId: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, {
+    command: string;
+    args?: string[];
+    target?: {
+        nodeId?: string;
+        clientId?: string;
+    };
+    timeoutMs?: number;
+}, {
+    command: string;
+    args?: string[] | undefined;
+    target?: {
+        nodeId?: string | undefined;
+        clientId?: string | undefined;
+    } | undefined;
+    timeoutMs?: number | undefined;
+}, {
+    ok: boolean;
+    error: string;
+} | {
+    ok: boolean;
+    nodeId: string;
+    exitCode: number | undefined;
+    stdout: string;
+    stderr: string;
+    payload: unknown;
+}, "node_run">;

package/dist/agent/tools/node_invoke.js

@@ -0,0 +1,109 @@
+import { tool } from "langchain";
+import { array, number, object, string } from "zod";
+const DEFAULT_NODE_TIMEOUT_MS = 30000;
+const TargetSchema = object({
+    nodeId: string().min(1).optional(),
+    clientId: string().min(1).optional()
+}).optional();
+function resolveTarget(target, defaultTargetClientId) {
+    const targetNodeId = target?.nodeId?.trim();
+    if (targetNodeId) return {
+        targetNodeId
+    };
+    const targetClientId = target?.clientId?.trim() || defaultTargetClientId?.trim();
+    if (targetClientId) return {
+        targetClientId
+    };
+    return {};
+}
+function missingInvokerResult(toolName) {
+    return {
+        ok: false,
+        error: `${toolName} is only available when invoked through Wingman Gateway.`
+    };
+}
+const createNodeNotifyTool = (options = {})=>{
+    const { nodeInvoker, defaultTargetClientId } = options;
+    return tool(async ({ body, title, target, timeoutMs })=>{
+        if (!nodeInvoker) return missingInvokerResult("node_notify");
+        try {
+            const { targetNodeId, targetClientId } = resolveTarget(target, defaultTargetClientId);
+            const result = await nodeInvoker({
+                tool: "system.notify",
+                args: {
+                    title: title?.trim() || "Wingman",
+                    body: body.trim()
+                },
+                timeoutMs: timeoutMs ?? DEFAULT_NODE_TIMEOUT_MS,
+                targetNodeId,
+                targetClientId,
+                capability: "system.notify"
+            });
+            const payload = result.payload && "object" == typeof result.payload ? result.payload : null;
+            return {
+                ok: true,
+                nodeId: result.nodeId,
+                delivered: payload?.delivered === true,
+                payload: result.payload
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }, {
+        name: "node_notify",
+        description: "Send a user-visible notification on an approved connected node device via system.notify.",
+        schema: object({
+            body: string().min(1).describe("Notification body text shown on the node device"),
+            title: string().min(1).optional().describe("Optional notification title"),
+            target: TargetSchema.describe("Optional target selector. Use nodeId for a specific node or clientId for a paired device."),
+            timeoutMs: number().int().min(1000).max(120000).optional().describe("Optional timeout for node execution in milliseconds")
+        })
+    });
+};
+const createNodeRunTool = (options = {})=>{
+    const { nodeInvoker, defaultTargetClientId } = options;
+    return tool(async ({ command, args, target, timeoutMs })=>{
+        if (!nodeInvoker) return missingInvokerResult("node_run");
+        try {
+            const { targetNodeId, targetClientId } = resolveTarget(target, defaultTargetClientId);
+            const result = await nodeInvoker({
+                tool: "system.run",
+                args: {
+                    command: command.trim(),
+                    args: Array.isArray(args) ? args : []
+                },
+                timeoutMs: timeoutMs ?? DEFAULT_NODE_TIMEOUT_MS,
+                targetNodeId,
+                targetClientId,
+                capability: "system.run"
+            });
+            const payload = result.payload && "object" == typeof result.payload ? result.payload : null;
+            return {
+                ok: true,
+                nodeId: result.nodeId,
+                exitCode: "number" == typeof payload?.exitCode ? payload.exitCode : void 0,
+                stdout: "string" == typeof payload?.stdout ? payload.stdout : "",
+                stderr: "string" == typeof payload?.stderr ? payload.stderr : "",
+                payload: result.payload
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }, {
+        name: "node_run",
+        description: "Run a command on an approved connected node device via system.run and return exitCode/stdout/stderr.",
+        schema: object({
+            command: string().min(1).describe("Executable command path/name to run on the node device"),
+            args: array(string()).optional().describe("Optional command arguments"),
+            target: TargetSchema.describe("Optional target selector. Use nodeId for a specific node or clientId for a paired device."),
+            timeoutMs: number().int().min(1000).max(120000).optional().describe("Optional timeout for node execution in milliseconds")
+        })
+    });
+};
+export { createNodeNotifyTool, createNodeRunTool };

package/dist/cli/commands/gateway.cjs

@@ -600,7 +600,7 @@ Examples:
 Deployment:
   Local:      Run on localhost or LAN
   Tailscale:  Accessible over Tailscale network
-  Cloudflare: Deploy to Cloudflare Workers (see cloudflare/README.md)
+  Cloudflare: Deploy to Cloudflare Workers (see apps/cloudflare/README.md)
   `);
 }
 exports.executeGatewayCommand = __webpack_exports__.executeGatewayCommand;

package/dist/cli/commands/gateway.js

@@ -572,7 +572,7 @@ Examples:
 Deployment:
   Local:      Run on localhost or LAN
   Tailscale:  Accessible over Tailscale network
-  Cloudflare: Deploy to Cloudflare Workers (see cloudflare/README.md)
+  Cloudflare: Deploy to Cloudflare Workers (see apps/cloudflare/README.md)
   `);
 }
 export { executeGatewayCommand };