@wingman-ai/gateway 0.4.0 → 0.4.2

package/dist/tests/gateway-node-mode.test.cjs

@@ -0,0 +1,174 @@
+"use strict";
+var __webpack_exports__ = {};
+const external_node_fs_namespaceObject = require("node:fs");
+const external_node_os_namespaceObject = require("node:os");
+const external_node_path_namespaceObject = require("node:path");
+const external_vitest_namespaceObject = require("vitest");
+const server_cjs_namespaceObject = require("../gateway/server.cjs");
+const isBun = void 0 !== globalThis.Bun;
+const describeIfBun = isBun ? external_vitest_namespaceObject.describe : external_vitest_namespaceObject.describe.skip;
+describeIfBun("Gateway node enablement", ()=>{
+    let server;
+    let port = 0;
+    let workspace;
+    (0, external_vitest_namespaceObject.beforeAll)(async ()=>{
+        workspace = (0, external_node_fs_namespaceObject.mkdtempSync)((0, external_node_path_namespaceObject.join)((0, external_node_os_namespaceObject.tmpdir)(), "wingman-gateway-node-mode-"));
+        server = new server_cjs_namespaceObject.GatewayServer({
+            port: 0,
+            host: "localhost",
+            requireAuth: false,
+            auth: {
+                mode: "none"
+            },
+            logLevel: "silent",
+            workspace,
+            configDir: ".wingman-node-test-config",
+            stateDir: ".wingman-node-test-state"
+        });
+        await server.start();
+        port = server.getPort();
+        if (!port) throw new Error("Unable to determine gateway port");
+    });
+    (0, external_vitest_namespaceObject.afterAll)(async ()=>{
+        await server.stop();
+        (0, external_node_fs_namespaceObject.rmSync)(workspace, {
+            recursive: true,
+            force: true
+        });
+    });
+    const connectClient = (instanceId, clientType = "desktop")=>new Promise((resolve, reject)=>{
+            const ws = new WebSocket(`ws://localhost:${port}/ws`);
+            const connectId = `connect-${instanceId}-${Date.now()}`;
+            const timeout = setTimeout(()=>reject(new Error("Connect timeout")), 5000);
+            ws.addEventListener("open", ()=>{
+                ws.send(JSON.stringify({
+                    type: "connect",
+                    id: connectId,
+                    client: {
+                        instanceId,
+                        clientType,
+                        version: "test"
+                    },
+                    timestamp: Date.now()
+                }));
+            });
+            ws.addEventListener("message", (event)=>{
+                const msg = JSON.parse(event.data);
+                if ("res" === msg.type && msg.id === connectId && msg.ok) {
+                    clearTimeout(timeout);
+                    resolve(ws);
+                }
+            });
+            ws.addEventListener("error", ()=>{
+                clearTimeout(timeout);
+                reject(new Error("WebSocket error"));
+            });
+        });
+    const waitForMessage = (ws, predicate, timeoutMs = 5000)=>new Promise((resolve, reject)=>{
+            const timeout = setTimeout(()=>reject(new Error("Message timeout")), timeoutMs);
+            const handler = (event)=>{
+                const data = event.data;
+                if ("string" != typeof data) return;
+                let msg;
+                try {
+                    msg = JSON.parse(data);
+                } catch  {
+                    return;
+                }
+                if (!predicate(msg)) return;
+                clearTimeout(timeout);
+                ws.removeEventListener("message", handler);
+                resolve(msg);
+            };
+            ws.addEventListener("message", handler);
+        });
+    (0, external_vitest_namespaceObject.it)("blocks node registration before device enablement", async ()=>{
+        const ws = await connectClient("desktop-node-blocked");
+        ws.send(JSON.stringify({
+            type: "register",
+            payload: {
+                name: "Blocked Node",
+                capabilities: [
+                    "system.notify"
+                ]
+            },
+            timestamp: Date.now()
+        }));
+        const errorMessage = await waitForMessage(ws, (msg)=>"error" === msg.type && msg.payload?.code === "NODE_NOT_ENABLED");
+        (0, external_vitest_namespaceObject.expect)(errorMessage.payload?.message).toContain("not approved");
+        ws.close();
+    });
+    (0, external_vitest_namespaceObject.it)("allows enabled devices to register, execute, and revoke", async ()=>{
+        const enableResponse = await fetch(`http://localhost:${port}/api/nodes/${encodeURIComponent("desktop-node-enabled")}`, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                enabled: true,
+                name: "Enabled Desktop"
+            })
+        });
+        (0, external_vitest_namespaceObject.expect)(enableResponse.ok).toBe(true);
+        const nodeWs = await connectClient("desktop-node-enabled");
+        nodeWs.send(JSON.stringify({
+            type: "register",
+            payload: {
+                name: "Enabled Desktop",
+                capabilities: [
+                    "system.notify"
+                ]
+            },
+            timestamp: Date.now()
+        }));
+        const registrationAck = await waitForMessage(nodeWs, (msg)=>"ack" === msg.type && "string" == typeof msg.payload?.nodeId);
+        const nodeId = registrationAck.payload.nodeId;
+        (0, external_vitest_namespaceObject.expect)(nodeId).toBeTruthy();
+        const requesterWs = await connectClient("desktop-requester");
+        requesterWs.send(JSON.stringify({
+            type: "req:node",
+            id: "node-req-1",
+            targetNodeId: nodeId,
+            payload: {
+                tool: "system.notify",
+                args: {
+                    title: "Hello",
+                    body: "Node test"
+                }
+            },
+            timestamp: Date.now()
+        }));
+        const forwardedToNode = await waitForMessage(nodeWs, (msg)=>"req:node" === msg.type && "node-req-1" === msg.id);
+        (0, external_vitest_namespaceObject.expect)(forwardedToNode.targetNodeId).toBe(nodeId);
+        nodeWs.send(JSON.stringify({
+            type: "res",
+            id: "node-req-1",
+            ok: true,
+            payload: {
+                delivered: true
+            },
+            timestamp: Date.now()
+        }));
+        const returnedToRequester = await waitForMessage(requesterWs, (msg)=>"res" === msg.type && "node-req-1" === msg.id);
+        (0, external_vitest_namespaceObject.expect)(returnedToRequester.ok).toBe(true);
+        (0, external_vitest_namespaceObject.expect)(returnedToRequester.nodeId).toBe(nodeId);
+        const closePromise = new Promise((resolve)=>{
+            nodeWs.addEventListener("close", ()=>{
+                resolve();
+            }, {
+                once: true
+            });
+        });
+        const revokeResponse = await fetch(`http://localhost:${port}/api/nodes/${encodeURIComponent("desktop-node-enabled")}`, {
+            method: "DELETE"
+        });
+        (0, external_vitest_namespaceObject.expect)(revokeResponse.ok).toBe(true);
+        await closePromise;
+        requesterWs.close();
+        nodeWs.close();
+    });
+});
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/tests/gateway-node-mode.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/gateway-node-mode.test.js

@@ -0,0 +1,168 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { GatewayServer } from "../gateway/server.js";
+const isBun = void 0 !== globalThis.Bun;
+const describeIfBun = isBun ? describe : describe.skip;
+describeIfBun("Gateway node enablement", ()=>{
+    let server;
+    let port = 0;
+    let workspace;
+    beforeAll(async ()=>{
+        workspace = mkdtempSync(join(tmpdir(), "wingman-gateway-node-mode-"));
+        server = new GatewayServer({
+            port: 0,
+            host: "localhost",
+            requireAuth: false,
+            auth: {
+                mode: "none"
+            },
+            logLevel: "silent",
+            workspace,
+            configDir: ".wingman-node-test-config",
+            stateDir: ".wingman-node-test-state"
+        });
+        await server.start();
+        port = server.getPort();
+        if (!port) throw new Error("Unable to determine gateway port");
+    });
+    afterAll(async ()=>{
+        await server.stop();
+        rmSync(workspace, {
+            recursive: true,
+            force: true
+        });
+    });
+    const connectClient = (instanceId, clientType = "desktop")=>new Promise((resolve, reject)=>{
+            const ws = new WebSocket(`ws://localhost:${port}/ws`);
+            const connectId = `connect-${instanceId}-${Date.now()}`;
+            const timeout = setTimeout(()=>reject(new Error("Connect timeout")), 5000);
+            ws.addEventListener("open", ()=>{
+                ws.send(JSON.stringify({
+                    type: "connect",
+                    id: connectId,
+                    client: {
+                        instanceId,
+                        clientType,
+                        version: "test"
+                    },
+                    timestamp: Date.now()
+                }));
+            });
+            ws.addEventListener("message", (event)=>{
+                const msg = JSON.parse(event.data);
+                if ("res" === msg.type && msg.id === connectId && msg.ok) {
+                    clearTimeout(timeout);
+                    resolve(ws);
+                }
+            });
+            ws.addEventListener("error", ()=>{
+                clearTimeout(timeout);
+                reject(new Error("WebSocket error"));
+            });
+        });
+    const waitForMessage = (ws, predicate, timeoutMs = 5000)=>new Promise((resolve, reject)=>{
+            const timeout = setTimeout(()=>reject(new Error("Message timeout")), timeoutMs);
+            const handler = (event)=>{
+                const data = event.data;
+                if ("string" != typeof data) return;
+                let msg;
+                try {
+                    msg = JSON.parse(data);
+                } catch  {
+                    return;
+                }
+                if (!predicate(msg)) return;
+                clearTimeout(timeout);
+                ws.removeEventListener("message", handler);
+                resolve(msg);
+            };
+            ws.addEventListener("message", handler);
+        });
+    it("blocks node registration before device enablement", async ()=>{
+        const ws = await connectClient("desktop-node-blocked");
+        ws.send(JSON.stringify({
+            type: "register",
+            payload: {
+                name: "Blocked Node",
+                capabilities: [
+                    "system.notify"
+                ]
+            },
+            timestamp: Date.now()
+        }));
+        const errorMessage = await waitForMessage(ws, (msg)=>"error" === msg.type && msg.payload?.code === "NODE_NOT_ENABLED");
+        expect(errorMessage.payload?.message).toContain("not approved");
+        ws.close();
+    });
+    it("allows enabled devices to register, execute, and revoke", async ()=>{
+        const enableResponse = await fetch(`http://localhost:${port}/api/nodes/${encodeURIComponent("desktop-node-enabled")}`, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                enabled: true,
+                name: "Enabled Desktop"
+            })
+        });
+        expect(enableResponse.ok).toBe(true);
+        const nodeWs = await connectClient("desktop-node-enabled");
+        nodeWs.send(JSON.stringify({
+            type: "register",
+            payload: {
+                name: "Enabled Desktop",
+                capabilities: [
+                    "system.notify"
+                ]
+            },
+            timestamp: Date.now()
+        }));
+        const registrationAck = await waitForMessage(nodeWs, (msg)=>"ack" === msg.type && "string" == typeof msg.payload?.nodeId);
+        const nodeId = registrationAck.payload.nodeId;
+        expect(nodeId).toBeTruthy();
+        const requesterWs = await connectClient("desktop-requester");
+        requesterWs.send(JSON.stringify({
+            type: "req:node",
+            id: "node-req-1",
+            targetNodeId: nodeId,
+            payload: {
+                tool: "system.notify",
+                args: {
+                    title: "Hello",
+                    body: "Node test"
+                }
+            },
+            timestamp: Date.now()
+        }));
+        const forwardedToNode = await waitForMessage(nodeWs, (msg)=>"req:node" === msg.type && "node-req-1" === msg.id);
+        expect(forwardedToNode.targetNodeId).toBe(nodeId);
+        nodeWs.send(JSON.stringify({
+            type: "res",
+            id: "node-req-1",
+            ok: true,
+            payload: {
+                delivered: true
+            },
+            timestamp: Date.now()
+        }));
+        const returnedToRequester = await waitForMessage(requesterWs, (msg)=>"res" === msg.type && "node-req-1" === msg.id);
+        expect(returnedToRequester.ok).toBe(true);
+        expect(returnedToRequester.nodeId).toBe(nodeId);
+        const closePromise = new Promise((resolve)=>{
+            nodeWs.addEventListener("close", ()=>{
+                resolve();
+            }, {
+                once: true
+            });
+        });
+        const revokeResponse = await fetch(`http://localhost:${port}/api/nodes/${encodeURIComponent("desktop-node-enabled")}`, {
+            method: "DELETE"
+        });
+        expect(revokeResponse.ok).toBe(true);
+        await closePromise;
+        requesterWs.close();
+        nodeWs.close();
+    });
+});

package/dist/tests/gateway-origin-policy.test.cjs

@@ -0,0 +1,60 @@
+"use strict";
+var __webpack_exports__ = {};
+const external_vitest_namespaceObject = require("vitest");
+const server_cjs_namespaceObject = require("../gateway/server.cjs");
+(0, external_vitest_namespaceObject.describe)("gateway origin policy", ()=>{
+    (0, external_vitest_namespaceObject.it)("identifies loopback hostnames", ()=>{
+        (0, external_vitest_namespaceObject.expect)((0, server_cjs_namespaceObject.isLoopbackHostname)("127.0.0.1")).toBe(true);
+        (0, external_vitest_namespaceObject.expect)((0, server_cjs_namespaceObject.isLoopbackHostname)("localhost")).toBe(true);
+        (0, external_vitest_namespaceObject.expect)((0, server_cjs_namespaceObject.isLoopbackHostname)("[::1]")).toBe(true);
+        (0, external_vitest_namespaceObject.expect)((0, server_cjs_namespaceObject.isLoopbackHostname)("example.com")).toBe(false);
+    });
+    (0, external_vitest_namespaceObject.it)("allows loopback development origins", ()=>{
+        const allowed = (0, server_cjs_namespaceObject.isGatewayOriginAllowed)({
+            origin: "http://localhost:5173",
+            requestUrl: "http://127.0.0.1:18789/api/sessions",
+            gatewayHost: "127.0.0.1",
+            gatewayPort: 18789,
+            controlUiEnabled: true,
+            controlUiPort: 18790
+        });
+        (0, external_vitest_namespaceObject.expect)(allowed).toBe(true);
+    });
+    (0, external_vitest_namespaceObject.it)("rejects unrelated internet origins", ()=>{
+        const allowed = (0, server_cjs_namespaceObject.isGatewayOriginAllowed)({
+            origin: "https://evil.example",
+            requestUrl: "http://127.0.0.1:18789/api/sessions",
+            gatewayHost: "127.0.0.1",
+            gatewayPort: 18789,
+            controlUiEnabled: true,
+            controlUiPort: 18790
+        });
+        (0, external_vitest_namespaceObject.expect)(allowed).toBe(false);
+    });
+    (0, external_vitest_namespaceObject.it)("allows same-host control UI origin on configured port", ()=>{
+        const allowed = (0, server_cjs_namespaceObject.isGatewayOriginAllowed)({
+            origin: "http://192.168.1.50:18790",
+            requestUrl: "http://192.168.1.50:18789/api/sessions",
+            gatewayHost: "0.0.0.0",
+            gatewayPort: 18789,
+            controlUiEnabled: true,
+            controlUiPort: 18790
+        });
+        (0, external_vitest_namespaceObject.expect)(allowed).toBe(true);
+    });
+    (0, external_vitest_namespaceObject.it)("rejects same-host origins on unapproved ports", ()=>{
+        const allowed = (0, server_cjs_namespaceObject.isGatewayOriginAllowed)({
+            origin: "http://192.168.1.50:9999",
+            requestUrl: "http://192.168.1.50:18789/api/sessions",
+            gatewayHost: "0.0.0.0",
+            gatewayPort: 18789,
+            controlUiEnabled: true,
+            controlUiPort: 18790
+        });
+        (0, external_vitest_namespaceObject.expect)(allowed).toBe(false);
+    });
+});
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/tests/gateway-origin-policy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/gateway-origin-policy.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { isGatewayOriginAllowed, isLoopbackHostname } from "../gateway/server.js";
+describe("gateway origin policy", ()=>{
+    it("identifies loopback hostnames", ()=>{
+        expect(isLoopbackHostname("127.0.0.1")).toBe(true);
+        expect(isLoopbackHostname("localhost")).toBe(true);
+        expect(isLoopbackHostname("[::1]")).toBe(true);
+        expect(isLoopbackHostname("example.com")).toBe(false);
+    });
+    it("allows loopback development origins", ()=>{
+        const allowed = isGatewayOriginAllowed({
+            origin: "http://localhost:5173",
+            requestUrl: "http://127.0.0.1:18789/api/sessions",
+            gatewayHost: "127.0.0.1",
+            gatewayPort: 18789,
+            controlUiEnabled: true,
+            controlUiPort: 18790
+        });
+        expect(allowed).toBe(true);
+    });
+    it("rejects unrelated internet origins", ()=>{
+        const allowed = isGatewayOriginAllowed({
+            origin: "https://evil.example",
+            requestUrl: "http://127.0.0.1:18789/api/sessions",
+            gatewayHost: "127.0.0.1",
+            gatewayPort: 18789,
+            controlUiEnabled: true,
+            controlUiPort: 18790
+        });
+        expect(allowed).toBe(false);
+    });
+    it("allows same-host control UI origin on configured port", ()=>{
+        const allowed = isGatewayOriginAllowed({
+            origin: "http://192.168.1.50:18790",
+            requestUrl: "http://192.168.1.50:18789/api/sessions",
+            gatewayHost: "0.0.0.0",
+            gatewayPort: 18789,
+            controlUiEnabled: true,
+            controlUiPort: 18790
+        });
+        expect(allowed).toBe(true);
+    });
+    it("rejects same-host origins on unapproved ports", ()=>{
+        const allowed = isGatewayOriginAllowed({
+            origin: "http://192.168.1.50:9999",
+            requestUrl: "http://192.168.1.50:18789/api/sessions",
+            gatewayHost: "0.0.0.0",
+            gatewayPort: 18789,
+            controlUiEnabled: true,
+            controlUiPort: 18790
+        });
+        expect(allowed).toBe(false);
+    });
+});

package/dist/tests/gateway.test.cjs

@@ -459,6 +459,7 @@ describeIfBun("Gateway", ()=>{
         const lastOptions = invokerConstructOptions.at(-1) || {};
         (0, external_vitest_namespaceObject.expect)(lastOptions.workspace).toBe(workspaceOverride);
         (0, external_vitest_namespaceObject.expect)(lastOptions.configDir).toBe(configDirOverride);
+        (0, external_vitest_namespaceObject.expect)(typeof lastOptions.nodeInvoker).toBe("function");
         requester.close();
     });
     (0, external_vitest_namespaceObject.it)("should cancel an in-flight agent request", async ()=>{

package/dist/tests/gateway.test.js

@@ -457,6 +457,7 @@ describeIfBun("Gateway", ()=>{
         const lastOptions = invokerConstructOptions.at(-1) || {};
         expect(lastOptions.workspace).toBe(workspaceOverride);
         expect(lastOptions.configDir).toBe(configDirOverride);
+        expect(typeof lastOptions.nodeInvoker).toBe("function");
         requester.close();
     });
     it("should cancel an in-flight agent request", async ()=>{

package/dist/tests/node-tools.test.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __webpack_exports__ = {};
+const external_vitest_namespaceObject = require("vitest");
+const toolRegistry_cjs_namespaceObject = require("../agent/config/toolRegistry.cjs");
+const node_invoke_cjs_namespaceObject = require("../agent/tools/node_invoke.cjs");
+(0, external_vitest_namespaceObject.describe)("node tools", ()=>{
+    (0, external_vitest_namespaceObject.it)("exposes node tools in available tool names", ()=>{
+        const tools = (0, toolRegistry_cjs_namespaceObject.getAvailableTools)();
+        (0, external_vitest_namespaceObject.expect)(tools).toContain("node_notify");
+        (0, external_vitest_namespaceObject.expect)(tools).toContain("node_run");
+    });
+    (0, external_vitest_namespaceObject.it)("routes node_notify through the injected node invoker", async ()=>{
+        const nodeInvoker = external_vitest_namespaceObject.vi.fn(async ()=>({
+                nodeId: "node-123",
+                payload: {
+                    delivered: true
+                }
+            }));
+        const tool = (0, node_invoke_cjs_namespaceObject.createNodeNotifyTool)({
+            nodeInvoker,
+            defaultTargetClientId: "desktop-abc"
+        });
+        const result = await tool.invoke({
+            body: "Build finished"
+        });
+        (0, external_vitest_namespaceObject.expect)(result.ok).toBe(true);
+        (0, external_vitest_namespaceObject.expect)(result.nodeId).toBe("node-123");
+        (0, external_vitest_namespaceObject.expect)(result.delivered).toBe(true);
+        (0, external_vitest_namespaceObject.expect)(nodeInvoker).toHaveBeenCalledWith(external_vitest_namespaceObject.expect.objectContaining({
+            tool: "system.notify",
+            targetClientId: "desktop-abc"
+        }));
+    });
+    (0, external_vitest_namespaceObject.it)("returns command result fields from node_run", async ()=>{
+        const nodeInvoker = external_vitest_namespaceObject.vi.fn(async ()=>({
+                nodeId: "node-789",
+                payload: {
+                    exitCode: 0,
+                    stdout: "ok",
+                    stderr: ""
+                }
+            }));
+        const tool = (0, node_invoke_cjs_namespaceObject.createNodeRunTool)({
+            nodeInvoker
+        });
+        const result = await tool.invoke({
+            command: "/bin/echo",
+            args: [
+                "hello"
+            ],
+            target: {
+                nodeId: "node-789"
+            }
+        });
+        (0, external_vitest_namespaceObject.expect)(result.ok).toBe(true);
+        (0, external_vitest_namespaceObject.expect)(result.nodeId).toBe("node-789");
+        (0, external_vitest_namespaceObject.expect)(result.exitCode).toBe(0);
+        (0, external_vitest_namespaceObject.expect)(result.stdout).toBe("ok");
+        (0, external_vitest_namespaceObject.expect)(result.stderr).toBe("");
+        (0, external_vitest_namespaceObject.expect)(nodeInvoker).toHaveBeenCalledWith(external_vitest_namespaceObject.expect.objectContaining({
+            tool: "system.run",
+            targetNodeId: "node-789"
+        }));
+    });
+    (0, external_vitest_namespaceObject.it)("returns an availability error outside gateway runtime", async ()=>{
+        const tool = (0, node_invoke_cjs_namespaceObject.createNodeRunTool)();
+        const result = await tool.invoke({
+            command: "pwd"
+        });
+        (0, external_vitest_namespaceObject.expect)(result.ok).toBe(false);
+        (0, external_vitest_namespaceObject.expect)(result.error).toContain("only available");
+    });
+});
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/tests/node-tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/node-tools.test.js

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+import { getAvailableTools } from "../agent/config/toolRegistry.js";
+import { createNodeNotifyTool, createNodeRunTool } from "../agent/tools/node_invoke.js";
+describe("node tools", ()=>{
+    it("exposes node tools in available tool names", ()=>{
+        const tools = getAvailableTools();
+        expect(tools).toContain("node_notify");
+        expect(tools).toContain("node_run");
+    });
+    it("routes node_notify through the injected node invoker", async ()=>{
+        const nodeInvoker = vi.fn(async ()=>({
+                nodeId: "node-123",
+                payload: {
+                    delivered: true
+                }
+            }));
+        const tool = createNodeNotifyTool({
+            nodeInvoker,
+            defaultTargetClientId: "desktop-abc"
+        });
+        const result = await tool.invoke({
+            body: "Build finished"
+        });
+        expect(result.ok).toBe(true);
+        expect(result.nodeId).toBe("node-123");
+        expect(result.delivered).toBe(true);
+        expect(nodeInvoker).toHaveBeenCalledWith(expect.objectContaining({
+            tool: "system.notify",
+            targetClientId: "desktop-abc"
+        }));
+    });
+    it("returns command result fields from node_run", async ()=>{
+        const nodeInvoker = vi.fn(async ()=>({
+                nodeId: "node-789",
+                payload: {
+                    exitCode: 0,
+                    stdout: "ok",
+                    stderr: ""
+                }
+            }));
+        const tool = createNodeRunTool({
+            nodeInvoker
+        });
+        const result = await tool.invoke({
+            command: "/bin/echo",
+            args: [
+                "hello"
+            ],
+            target: {
+                nodeId: "node-789"
+            }
+        });
+        expect(result.ok).toBe(true);
+        expect(result.nodeId).toBe("node-789");
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toBe("ok");
+        expect(result.stderr).toBe("");
+        expect(nodeInvoker).toHaveBeenCalledWith(expect.objectContaining({
+            tool: "system.run",
+            targetNodeId: "node-789"
+        }));
+    });
+    it("returns an availability error outside gateway runtime", async ()=>{
+        const tool = createNodeRunTool();
+        const result = await tool.invoke({
+            command: "pwd"
+        });
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("only available");
+    });
+});