refactor(pty): streamline server URL handling and add port conflict resolution

Remove the separate pty_server_url tool and handle the 'background-pty-server-url' command directly in the plugin's command.execute.before hook. This simplifies the implementation and removes unnecessary files.

Modify startWebServer to handle port conflicts by falling back to an OS-assigned port (port 0) if the default port is in use. Add getServerUrl utility function for retrieving the current server URL.

These changes improve code maintainability and system reliability without altering the user-facing functionality.

Author: MBanucu

src/plugin.ts

@@ -6,8 +6,7 @@ import { ptyWrite } from './plugin/pty/tools/write.ts'
 import { ptyRead } from './plugin/pty/tools/read.ts'
 import { ptyList } from './plugin/pty/tools/list.ts'
 import { ptyKill } from './plugin/pty/tools/kill.ts'
-import { ptyServerUrl } from './plugin/pty/tools/server-url.ts'
-import { startWebServer } from './web/server/server.ts'
+import { getServerUrl, startWebServer } from './web/server/server.ts'
 
 interface SessionDeletedEvent {
   type: 'session.deleted'
@@ -17,30 +16,45 @@ interface SessionDeletedEvent {
     }
   }
 }
+const ptyServerUrlCommand = 'background-pty-server-url'
 
 export const PTYPlugin = async ({ client, directory }: PluginContext): Promise<PluginResult> => {
   initPermissions(client, directory)
   initManager(client)
 
   return {
+    "command.execute.before": async (input) => {
+      if (input.command === ptyServerUrlCommand) {
+        const serverUrl = getServerUrl()
+        client.session.prompt({
+          path: { id: input.sessionID },
+          body: {
+            parts: [{
+              type: 'text',
+              text: serverUrl ? `PTY Web Server URL: ${serverUrl}` : 'PTY Web Server is not running.',
+            }],
+            noReply: true,
+          }
+        })
+        throw new Error('Command handled by PTY plugin')
+      }
+    },
     tool: {
       pty_spawn: ptySpawn,
       pty_write: ptyWrite,
       pty_read: ptyRead,
       pty_list: ptyList,
       pty_kill: ptyKill,
-      pty_server_url: ptyServerUrl,
     },
     config: async (input) => {
       if (!input.command) {
         input.command = {}
       }
-      input.command['background-pty-server-url'] = {
-        template:
-          'Get the URL of the running PTY web server instance by calling the pty_server_url tool and display it.',
-        description: 'Get the link to the running PTY web server',
+      const serverUrl = await startWebServer()
+      input.command[ptyServerUrlCommand] = {
+        template: `${serverUrl}`,
+        description: 'print link to PTY web server',
       }
-      await startWebServer()
     },
     event: async ({ event }) => {
       if (!event) {

src/plugin/pty/tools/server-url.ts

@@ -176,69 +176,81 @@ export async function startWebServer(config: Partial<ServerConfig> = {}): Promis
 
   const staticRoutes = await buildStaticRoutes()
 
-  server = Bun.serve({
-    hostname: finalConfig.hostname,
-    port: finalConfig.port,
-
-    routes: {
-      ...staticRoutes,
-      '/': wrapWithSecurityHeaders(
-        () => new Response(null, { status: 302, headers: { Location: '/index.html' } })
-      ),
-      '/ws': (req: Request) => {
-        if (req.headers.get('upgrade') === 'websocket') {
-          const success = server!.upgrade(req)
-          if (success) {
-            return undefined // Upgrade succeeded, Bun sends 101 automatically
+  const createServer = (port: number) => {
+    return Bun.serve({
+      hostname: finalConfig.hostname,
+      port,
+
+      routes: {
+        ...staticRoutes,
+        '/': wrapWithSecurityHeaders(
+          () => new Response(null, { status: 302, headers: { Location: '/index.html' } })
+        ),
+        '/ws': (req: Request) => {
+          if (req.headers.get('upgrade') === 'websocket') {
+            const success = server!.upgrade(req)
+            if (success) {
+              return undefined // Upgrade succeeded, Bun sends 101 automatically
+            }
+            return new Response('WebSocket upgrade failed', { status: 400 })
+          } else {
+            return new Response('WebSocket endpoint - use WebSocket upgrade', { status: 426 })
           }
-          return new Response('WebSocket upgrade failed', { status: 400 })
-        } else {
-          return new Response('WebSocket endpoint - use WebSocket upgrade', { status: 426 })
-        }
+        },
+        '/health': wrapWithSecurityHeaders(handleHealth),
+        '/api/sessions': wrapWithSecurityHeaders(async (req: Request) => {
+          if (req.method === 'GET') return getSessions()
+          if (req.method === 'POST') return createSession(req)
+          return new Response('Method not allowed', { status: 405 })
+        }),
+        '/api/sessions/clear': wrapWithSecurityHeaders(async (req: Request) => {
+          if (req.method === 'POST') return clearSessions()
+          return new Response('Method not allowed', { status: 405 })
+        }),
+        '/api/sessions/:id': wrapWithSecurityHeaders(async (req: Request) => {
+          if (req.method === 'GET') return getSession(req as BunRequest<'/api/sessions/:id'>)
+          return new Response('Method not allowed', { status: 405 })
+        }),
+        '/api/sessions/:id/input': wrapWithSecurityHeaders(async (req: Request) => {
+          if (req.method === 'POST') return sendInput(req as BunRequest<'/api/sessions/:id/input'>)
+          return new Response('Method not allowed', { status: 405 })
+        }),
+        '/api/sessions/:id/kill': wrapWithSecurityHeaders(async (req: Request) => {
+          if (req.method === 'POST') return killSession(req as BunRequest<'/api/sessions/:id/kill'>)
+          return new Response('Method not allowed', { status: 405 })
+        }),
+        '/api/sessions/:id/buffer/raw': wrapWithSecurityHeaders(async (req: Request) => {
+          if (req.method === 'GET')
+            return getRawBuffer(req as BunRequest<'/api/sessions/:id/buffer/raw'>)
+          return new Response('Method not allowed', { status: 405 })
+        }),
+        '/api/sessions/:id/buffer/plain': wrapWithSecurityHeaders(async (req: Request) => {
+          if (req.method === 'GET')
+            return getPlainBuffer(req as BunRequest<'/api/sessions/:id/buffer/plain'>)
+          return new Response('Method not allowed', { status: 405 })
+        }),
       },
-      '/health': wrapWithSecurityHeaders(handleHealth),
-      '/api/sessions': wrapWithSecurityHeaders(async (req: Request) => {
-        if (req.method === 'GET') return getSessions()
-        if (req.method === 'POST') return createSession(req)
-        return new Response('Method not allowed', { status: 405 })
-      }),
-      '/api/sessions/clear': wrapWithSecurityHeaders(async (req: Request) => {
-        if (req.method === 'POST') return clearSessions()
-        return new Response('Method not allowed', { status: 405 })
-      }),
-      '/api/sessions/:id': wrapWithSecurityHeaders(async (req: Request) => {
-        if (req.method === 'GET') return getSession(req as BunRequest<'/api/sessions/:id'>)
-        return new Response('Method not allowed', { status: 405 })
-      }),
-      '/api/sessions/:id/input': wrapWithSecurityHeaders(async (req: Request) => {
-        if (req.method === 'POST') return sendInput(req as BunRequest<'/api/sessions/:id/input'>)
-        return new Response('Method not allowed', { status: 405 })
-      }),
-      '/api/sessions/:id/kill': wrapWithSecurityHeaders(async (req: Request) => {
-        if (req.method === 'POST') return killSession(req as BunRequest<'/api/sessions/:id/kill'>)
-        return new Response('Method not allowed', { status: 405 })
-      }),
-      '/api/sessions/:id/buffer/raw': wrapWithSecurityHeaders(async (req: Request) => {
-        if (req.method === 'GET')
-          return getRawBuffer(req as BunRequest<'/api/sessions/:id/buffer/raw'>)
-        return new Response('Method not allowed', { status: 405 })
-      }),
-      '/api/sessions/:id/buffer/plain': wrapWithSecurityHeaders(async (req: Request) => {
-        if (req.method === 'GET')
-          return getPlainBuffer(req as BunRequest<'/api/sessions/:id/buffer/plain'>)
-        return new Response('Method not allowed', { status: 405 })
-      }),
-    },
-
-    websocket: {
-      perMessageDeflate: true,
-      ...wsHandler,
-    },
-
-    fetch: handleRequest,
-  })
 
-  return `http://${finalConfig.hostname}:${finalConfig.port}`
+      websocket: {
+        perMessageDeflate: true,
+        ...wsHandler,
+      },
+
+      fetch: handleRequest,
+    })
+  }
+
+  try {
+    server = createServer(finalConfig.port)
+  } catch (error: any) {
+    if (error.code === 'EADDRINUSE' || error.message?.includes('EADDRINUSE')) {
+      server = createServer(0)
+    } else {
+      throw error
+    }
+  }
+
+  return `http://${server.hostname}:${server.port}`
 }
 
 export function stopWebServer(): void {