fix: document tools invoke + honor main session key (#1575) (thanks @vignesh07)

src/gateway/tools-invoke-http.test.ts

@@ -1,15 +1,12 @@
 import { describe, expect, it } from "vitest";
 
-import { installGatewayTestHooks, getFreePort } from "./test-helpers.server.js";
-import { startGatewayServer } from "./server.js";
+import { installGatewayTestHooks, getFreePort, startGatewayServer } from "./test-helpers.server.js";
 import { testState } from "./test-helpers.mocks.js";
 
 installGatewayTestHooks({ scope: "suite" });
 
 describe("POST /tools/invoke", () => {
   it("invokes a tool and returns {ok:true,result}", async () => {
-    testState.gatewayAuth = { mode: "none" } as any;
-
     // Allow the sessions_list tool for main agent.
     testState.agentsConfig = {
       list: [
@@ -41,8 +38,7 @@ describe("POST /tools/invoke", () => {
     await server.close();
   });
 
-  it("rejects unauthorized when auth mode is token and header is missing", async () => {
-    testState.gatewayAuth = { mode: "token", token: "t" } as any;
+  it("accepts password auth when bearer token matches", async () => {
     testState.agentsConfig = {
       list: [
         {
@@ -55,7 +51,42 @@ describe("POST /tools/invoke", () => {
     } as any;
 
     const port = await getFreePort();
-    const server = await startGatewayServer(port, { bind: "loopback" });
+    const server = await startGatewayServer(port, {
+      bind: "loopback",
+      auth: { mode: "password", password: "secret" },
+    });
+
+    const res = await fetch(`http://127.0.0.1:${port}/tools/invoke`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: "Bearer secret",
+      },
+      body: JSON.stringify({ tool: "sessions_list", action: "json", args: {}, sessionKey: "main" }),
+    });
+
+    expect(res.status).toBe(200);
+
+    await server.close();
+  });
+
+  it("rejects unauthorized when auth mode is token and header is missing", async () => {
+    testState.agentsConfig = {
+      list: [
+        {
+          id: "main",
+          tools: {
+            allow: ["sessions_list"],
+          },
+        },
+      ],
+    } as any;
+
+    const port = await getFreePort();
+    const server = await startGatewayServer(port, {
+      bind: "loopback",
+      auth: { mode: "token", token: "t" },
+    });
 
     const res = await fetch(`http://127.0.0.1:${port}/tools/invoke`, {
       method: "POST",
@@ -69,7 +100,6 @@ describe("POST /tools/invoke", () => {
   });
 
   it("returns 404 when tool is not allowlisted", async () => {
-    testState.gatewayAuth = { mode: "none" } as any;
     testState.agentsConfig = {
       list: [
         {
@@ -94,4 +124,77 @@ describe("POST /tools/invoke", () => {
 
     await server.close();
   });
+
+  it("respects tools.profile allowlist", async () => {
+    testState.agentsConfig = {
+      list: [
+        {
+          id: "main",
+          tools: {
+            allow: ["sessions_list"],
+          },
+        },
+      ],
+    } as any;
+
+    const { writeConfigFile } = await import("../config/config.js");
+    await writeConfigFile({
+      tools: { profile: "minimal" },
+    } as any);
+
+    const port = await getFreePort();
+    const server = await startGatewayServer(port, { bind: "loopback" });
+
+    const res = await fetch(`http://127.0.0.1:${port}/tools/invoke`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ tool: "sessions_list", action: "json", args: {}, sessionKey: "main" }),
+    });
+
+    expect(res.status).toBe(404);
+
+    await server.close();
+  });
+
+  it("uses the configured main session key when sessionKey is missing or main", async () => {
+    testState.agentsConfig = {
+      list: [
+        {
+          id: "main",
+          tools: {
+            deny: ["sessions_list"],
+          },
+        },
+        {
+          id: "ops",
+          default: true,
+          tools: {
+            allow: ["sessions_list"],
+          },
+        },
+      ],
+    } as any;
+    testState.sessionConfig = { mainKey: "primary" };
+
+    const port = await getFreePort();
+    const server = await startGatewayServer(port, { bind: "loopback" });
+
+    const payload = { tool: "sessions_list", action: "json", args: {} };
+
+    const resDefault = await fetch(`http://127.0.0.1:${port}/tools/invoke`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    expect(resDefault.status).toBe(200);
+
+    const resMain = await fetch(`http://127.0.0.1:${port}/tools/invoke`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ ...payload, sessionKey: "main" }),
+    });
+    expect(resMain.status).toBe(200);
+
+    await server.close();
+  });
 });