@swarmclawai/swarmclaw 0.2.0

package/src/lib/server/session-tools/shell.ts

@@ -0,0 +1,171 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import {
+  clearManagedProcess,
+  getManagedProcess,
+  killManagedProcess,
+  listManagedProcesses,
+  pollManagedProcess,
+  readManagedProcessLog,
+  removeManagedProcess,
+  startManagedProcess,
+  writeManagedProcessStdin,
+} from '../process-manager'
+import type { ToolBuildContext } from './context'
+import { safePath, truncate, coerceEnvMap, MAX_OUTPUT } from './context'
+
+export function buildShellTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  const tools: StructuredToolInterface[] = []
+  const { cwd, ctx, hasTool, commandTimeoutMs } = bctx
+
+  if (hasTool('shell')) {
+    tools.push(
+      tool(
+        async ({ command, background, yieldMs, timeoutSec, env, workdir }) => {
+          try {
+            const result = await startManagedProcess({
+              command,
+              cwd: workdir ? safePath(cwd, workdir) : cwd,
+              env: coerceEnvMap(env),
+              agentId: ctx?.agentId || null,
+              sessionId: ctx?.sessionId || null,
+              background: !!background,
+              yieldMs: typeof yieldMs === 'number' ? yieldMs : undefined,
+              timeoutMs: typeof timeoutSec === 'number'
+                ? Math.max(1, Math.trunc(timeoutSec)) * 1000
+                : commandTimeoutMs,
+            })
+            if (result.status === 'completed') {
+              return truncate(result.output || '(no output)', MAX_OUTPUT)
+            }
+            return JSON.stringify({
+              status: 'running',
+              processId: result.processId,
+              tail: result.tail || '',
+            }, null, 2)
+          } catch (err: any) {
+            return truncate(`Error: ${err.message || String(err)}`, MAX_OUTPUT)
+          }
+        },
+        {
+          name: 'execute_command',
+          description: 'Execute a shell command in the session working directory. Supports background mode and timeout/yield controls.',
+          schema: z.object({
+            command: z.string().describe('The shell command to execute'),
+            background: z.boolean().optional().describe('If true, start command in background immediately'),
+            yieldMs: z.number().optional().describe('If command runs longer than this, return a running process id instead of blocking'),
+            timeoutSec: z.number().optional().describe('Per-command timeout in seconds'),
+            workdir: z.string().optional().describe('Relative working directory override'),
+            env: z.record(z.string(), z.string()).optional().describe('Environment variable overrides'),
+          }),
+        },
+      ),
+    )
+  }
+
+  if (hasTool('process')) {
+    tools.push(
+      tool(
+        async ({ action, processId, offset, limit, data, eof, signal }) => {
+          try {
+            if (action === 'list') {
+              return JSON.stringify(listManagedProcesses(ctx?.agentId || null).map((p) => ({
+                id: p.id,
+                command: p.command,
+                status: p.status,
+                pid: p.pid,
+                startedAt: p.startedAt,
+                endedAt: p.endedAt,
+                exitCode: p.exitCode,
+                signal: p.signal,
+              })), null, 2)
+            }
+
+            if (!processId) return 'Error: processId is required for this action.'
+
+            const ownerCheck = getManagedProcess(processId)
+            if (ownerCheck && ctx?.sessionId && ownerCheck.sessionId && ownerCheck.sessionId !== ctx.sessionId) {
+              return `Error: process ${processId} belongs to a different session.`
+            }
+
+            if (action === 'poll') {
+              const res = pollManagedProcess(processId)
+              if (!res) return `Process not found: ${processId}`
+              return JSON.stringify({
+                id: res.process.id,
+                status: res.process.status,
+                exitCode: res.process.exitCode,
+                signal: res.process.signal,
+                chunk: res.chunk,
+              }, null, 2)
+            }
+
+            if (action === 'log') {
+              const res = readManagedProcessLog(processId, offset, limit)
+              if (!res) return `Process not found: ${processId}`
+              return JSON.stringify({
+                id: res.process.id,
+                status: res.process.status,
+                totalLines: res.totalLines,
+                text: res.text,
+              }, null, 2)
+            }
+
+            if (action === 'write') {
+              const out = writeManagedProcessStdin(processId, data || '', !!eof)
+              return out.ok ? `Wrote to process ${processId}` : `Error: ${out.error}`
+            }
+
+            if (action === 'kill') {
+              const out = killManagedProcess(processId, (signal as NodeJS.Signals) || 'SIGTERM')
+              return out.ok ? `Killed process ${processId}` : `Error: ${out.error}`
+            }
+
+            if (action === 'clear') {
+              const out = clearManagedProcess(processId)
+              return out.ok ? `Cleared process ${processId}` : `Error: ${out.error}`
+            }
+
+            if (action === 'remove') {
+              const out = removeManagedProcess(processId)
+              return out.ok ? `Removed process ${processId}` : `Error: ${out.error}`
+            }
+
+            if (action === 'status') {
+              const p = getManagedProcess(processId)
+              if (!p) return `Process not found: ${processId}`
+              return JSON.stringify({
+                id: p.id,
+                status: p.status,
+                pid: p.pid,
+                startedAt: p.startedAt,
+                endedAt: p.endedAt,
+                exitCode: p.exitCode,
+                signal: p.signal,
+              }, null, 2)
+            }
+
+            return `Unknown action "${action}".`
+          } catch (err: any) {
+            return `Error: ${err.message || String(err)}`
+          }
+        },
+        {
+          name: 'process_tool',
+          description: 'Manage long-running shell processes started by execute_command. Supports list, status, poll, log, write, kill, clear, and remove.',
+          schema: z.object({
+            action: z.enum(['list', 'status', 'poll', 'log', 'write', 'kill', 'clear', 'remove']),
+            processId: z.string().optional(),
+            offset: z.number().optional(),
+            limit: z.number().optional(),
+            data: z.string().optional(),
+            eof: z.boolean().optional(),
+            signal: z.string().optional().describe('Signal for kill action, e.g. SIGTERM or SIGKILL'),
+          }),
+        },
+      ),
+    )
+  }
+
+  return tools
+}

package/src/lib/server/session-tools/web.ts

@@ -0,0 +1,408 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import fs from 'fs'
+import path from 'path'
+import * as cheerio from 'cheerio'
+import { UPLOAD_DIR } from '../storage'
+import type { ToolBuildContext } from './context'
+import { safePath, truncate, MAX_OUTPUT } from './context'
+
+// ---------------------------------------------------------------------------
+// DuckDuckGo redirect-URL decoder
+// ---------------------------------------------------------------------------
+
+function decodeDuckDuckGoUrl(rawUrl: string): string {
+  if (!rawUrl) return rawUrl
+  try {
+    const url = rawUrl.startsWith('http')
+      ? new URL(rawUrl)
+      : new URL(rawUrl, 'https://duckduckgo.com')
+    const uddg = url.searchParams.get('uddg')
+    if (uddg) return decodeURIComponent(uddg)
+    return url.toString()
+  } catch {
+    const fromQuery = rawUrl.match(/[?&]uddg=([^&]+)/)?.[1]
+    if (fromQuery) {
+      try { return decodeURIComponent(fromQuery) } catch { /* noop */ }
+    }
+    return rawUrl
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Global registry of active browser instances for cleanup sweeps
+// ---------------------------------------------------------------------------
+
+export const activeBrowsers = new Map<string, { client: any; server: any; createdAt: number }>()
+
+/** Kill all browser instances that have been alive longer than maxAge (default 30 min) */
+export function sweepOrphanedBrowsers(maxAgeMs = 30 * 60 * 1000): number {
+  const now = Date.now()
+  let cleaned = 0
+  for (const [key, entry] of activeBrowsers) {
+    if (now - entry.createdAt > maxAgeMs) {
+      try { entry.client?.close?.() } catch { /* ignore */ }
+      try { entry.server?.close?.() } catch { /* ignore */ }
+      activeBrowsers.delete(key)
+      cleaned++
+    }
+  }
+  return cleaned
+}
+
+/** Kill a specific session's browser instance */
+export function cleanupSessionBrowser(sessionId: string): void {
+  const entry = activeBrowsers.get(sessionId)
+  if (entry) {
+    try { entry.client?.close?.() } catch { /* ignore */ }
+    try { entry.server?.close?.() } catch { /* ignore */ }
+    activeBrowsers.delete(sessionId)
+  }
+}
+
+/** Get count of active browser instances */
+export function getActiveBrowserCount(): number {
+  return activeBrowsers.size
+}
+
+/** Check if a specific session has an active browser */
+export function hasActiveBrowser(sessionId: string): boolean {
+  return activeBrowsers.has(sessionId)
+}
+
+// ---------------------------------------------------------------------------
+// buildWebTools
+// ---------------------------------------------------------------------------
+
+export function buildWebTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  const tools: StructuredToolInterface[] = []
+  const { cwd, ctx, cleanupFns } = bctx
+
+  // ---- web_search --------------------------------------------------------
+
+  if (bctx.hasTool('web_search')) {
+    tools.push(
+      tool(
+        async ({ query, maxResults }) => {
+          try {
+            const limit = Math.min(maxResults || 5, 10)
+            const url = `https://duckduckgo.com/html/?q=${encodeURIComponent(query)}`
+            const res = await fetch(url, {
+              headers: { 'User-Agent': 'Mozilla/5.0 (compatible; SwarmClaw/1.0)' },
+              signal: AbortSignal.timeout(15000),
+            })
+            if (!res.ok) {
+              return `Error searching web: HTTP ${res.status} ${res.statusText}`
+            }
+            const html = await res.text()
+            const $ = cheerio.load(html)
+            const results: { title: string; url: string; snippet: string }[] = []
+
+            // Primary parser: DuckDuckGo result cards
+            $('.result').each((_i, el) => {
+              if (results.length >= limit) return false
+              const link = $(el).find('a.result__a').first()
+              const rawHref = link.attr('href') || ''
+              const title = link.text().replace(/\s+/g, ' ').trim()
+              if (!rawHref || !title) return
+              const snippet = $(el).find('.result__snippet').first().text().replace(/\s+/g, ' ').trim()
+              results.push({
+                title,
+                url: decodeDuckDuckGoUrl(rawHref),
+                snippet,
+              })
+            })
+
+            // Fallback parser: any result__a anchors
+            if (results.length === 0) {
+              $('a.result__a').each((_i, el) => {
+                if (results.length >= limit) return false
+                const rawHref = $(el).attr('href') || ''
+                const title = $(el).text().replace(/\s+/g, ' ').trim()
+                if (!rawHref || !title) return
+                results.push({
+                  title,
+                  url: decodeDuckDuckGoUrl(rawHref),
+                  snippet: '',
+                })
+              })
+            }
+
+            return results.length > 0
+              ? JSON.stringify(results, null, 2)
+              : 'No results found.'
+          } catch (err: any) {
+            return `Error searching web: ${err.message}`
+          }
+        },
+        {
+          name: 'web_search',
+          description: 'Search the web using DuckDuckGo. Returns an array of results with title, url, and snippet.',
+          schema: z.object({
+            query: z.string().describe('Search query'),
+            maxResults: z.number().optional().describe('Maximum results to return (default 5, max 10)'),
+          }),
+        },
+      ),
+    )
+  }
+
+  // ---- web_fetch ---------------------------------------------------------
+
+  if (bctx.hasTool('web_fetch')) {
+    tools.push(
+      tool(
+        async ({ url }) => {
+          try {
+            const res = await fetch(url, {
+              headers: { 'User-Agent': 'Mozilla/5.0 (compatible; SwarmClaw/1.0)' },
+              signal: AbortSignal.timeout(15000),
+            })
+            if (!res.ok) return `HTTP ${res.status}: ${res.statusText}`
+            const html = await res.text()
+            // Use cheerio for robust HTML text extraction
+            const $ = cheerio.load(html)
+            $('script, style, noscript, nav, footer, header').remove()
+            // Prefer article/main content if available
+            const main = $('article, main, [role="main"]').first()
+            let text = (main.length ? main.text() : $('body').text())
+              .replace(/\s+/g, ' ')
+              .trim()
+            return truncate(text, MAX_OUTPUT)
+          } catch (err: any) {
+            return `Error fetching URL: ${err.message}`
+          }
+        },
+        {
+          name: 'web_fetch',
+          description: 'Fetch a URL and return its text content (HTML stripped). Useful for reading web pages.',
+          schema: z.object({
+            url: z.string().describe('The URL to fetch'),
+          }),
+        },
+      ),
+    )
+  }
+
+  // ---- browser -----------------------------------------------------------
+
+  if (bctx.hasTool('browser')) {
+    // In-process Playwright MCP client via @playwright/mcp programmatic API
+    const sessionKey = ctx?.sessionId || `anon-${Date.now()}`
+    let mcpClient: any = null
+    let mcpServer: any = null
+    let mcpInitializing: Promise<void> | null = null
+
+    const ensureMcp = (): Promise<void> => {
+      if (mcpClient) return Promise.resolve()
+      if (mcpInitializing) return mcpInitializing
+      mcpInitializing = (async () => {
+        const { createConnection } = await import('@playwright/mcp')
+        const { Client } = await import('@modelcontextprotocol/sdk/client/index.js')
+        const { InMemoryTransport } = await import('@modelcontextprotocol/sdk/inMemory.js')
+
+        const server = await createConnection({
+          browser: {
+            launchOptions: { headless: true },
+            isolated: true,
+          },
+          imageResponses: 'allow',
+          capabilities: ['core', 'pdf', 'vision', 'network'],
+        })
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+        const client = new Client({ name: 'swarmclaw', version: '1.0' })
+        await Promise.all([
+          client.connect(clientTransport),
+          server.connect(serverTransport),
+        ])
+        mcpClient = client
+        mcpServer = server
+        // Register in global tracker
+        activeBrowsers.set(sessionKey, { client, server, createdAt: Date.now() })
+      })()
+      return mcpInitializing
+    }
+
+    // Register cleanup for this session's browser
+    cleanupFns.push(async () => {
+      try { mcpClient?.close?.() } catch { /* ignore */ }
+      try { mcpServer?.close?.() } catch { /* ignore */ }
+      activeBrowsers.delete(sessionKey)
+      mcpClient = null
+      mcpServer = null
+    })
+
+    /** Strip Playwright debug noise — keep page context for the LLM */
+    const cleanPlaywrightOutput = (text: string): string => {
+      // Remove "### Ran Playwright code" blocks (internal debug)
+      text = text.replace(/### Ran Playwright code[\s\S]*?(?=###|$)/g, '')
+      // Truncate snapshot to first 40 lines so LLM has page context without flooding
+      text = text.replace(/### Snapshot\n([\s\S]*?)(?=###|$)/g, (_match, snapshot) => {
+        const lines = (snapshot as string).split('\n')
+        if (lines.length > 40) {
+          return 'Page elements:\n' + lines.slice(0, 40).join('\n') + '\n... (truncated)\n'
+        }
+        return 'Page elements:\n' + snapshot
+      })
+      // Clean headers
+      text = text.replace(/^### Result\n/gm, '')
+      text = text.replace(/^### Page\n/gm, '')
+      return text.replace(/\n{3,}/g, '\n').trim()
+    }
+
+    const callMcpTool = async (
+      toolName: string,
+      args: Record<string, any>,
+      options?: { saveTo?: string },
+    ): Promise<string> => {
+      await ensureMcp()
+      const result = await mcpClient.callTool({ name: toolName, arguments: args })
+      const isError = result?.isError === true
+      const content = result?.content
+      const savedPaths: string[] = []
+
+      const saveArtifact = (buffer: Buffer, suggestedExt: string): void => {
+        const rawSaveTo = options?.saveTo?.trim()
+        if (!rawSaveTo) return
+        let resolved = safePath(cwd, rawSaveTo)
+        if (!path.extname(resolved) && suggestedExt) {
+          resolved = `${resolved}.${suggestedExt}`
+        }
+        fs.mkdirSync(path.dirname(resolved), { recursive: true })
+        fs.writeFileSync(resolved, buffer)
+        savedPaths.push(resolved)
+      }
+
+      if (Array.isArray(content)) {
+        const parts: string[] = []
+        let hasBinaryImage = false
+        for (const c of content) {
+          if (c.type === 'image' && c.data) {
+            hasBinaryImage = true
+            const imageBuffer = Buffer.from(c.data, 'base64')
+            const filename = `screenshot-${Date.now()}.png`
+            const filepath = path.join(UPLOAD_DIR, filename)
+            fs.writeFileSync(filepath, imageBuffer)
+            saveArtifact(imageBuffer, 'png')
+            parts.push(`![Screenshot](/api/uploads/${filename})`)
+          } else if (c.type === 'resource' && c.resource?.blob) {
+            const ext = c.resource.mimeType?.includes('pdf') ? 'pdf' : 'bin'
+            const resourceBuffer = Buffer.from(c.resource.blob, 'base64')
+            const filename = `browser-${Date.now()}.${ext}`
+            const filepath = path.join(UPLOAD_DIR, filename)
+            fs.writeFileSync(filepath, resourceBuffer)
+            saveArtifact(resourceBuffer, ext)
+            parts.push(`[Download ${filename}](/api/uploads/${filename})`)
+          } else {
+            let text = c.text || ''
+            // Detect file paths in output (e.g. PDF save returns a local path)
+            const fileMatch = text.match(/\]\((\.\.\/[^\s)]+|\/[^\s)]+\.(pdf|png|jpg|jpeg|gif|webp|html|mp4|webm))\)/)
+            if (fileMatch) {
+              const rawPath = fileMatch[1]
+              const srcPath = rawPath.startsWith('/') ? rawPath : path.resolve(process.cwd(), rawPath)
+              if (fs.existsSync(srcPath)) {
+                const ext = path.extname(srcPath).slice(1).toLowerCase()
+                const IMAGE_EXTS = ['png', 'jpg', 'jpeg', 'gif', 'webp']
+                // Skip file-path images if we already have a binary image (avoids duplicates)
+                if (IMAGE_EXTS.includes(ext) && hasBinaryImage) {
+                  parts.push(isError ? text : cleanPlaywrightOutput(text))
+                } else {
+                  const filename = `browser-${Date.now()}.${ext}`
+                  const destPath = path.join(UPLOAD_DIR, filename)
+                  fs.copyFileSync(srcPath, destPath)
+                  if (options?.saveTo?.trim()) {
+                    const raw = options.saveTo.trim()
+                    let targetPath = safePath(cwd, raw)
+                    if (!path.extname(targetPath)) targetPath = `${targetPath}.${ext}`
+                    fs.mkdirSync(path.dirname(targetPath), { recursive: true })
+                    fs.copyFileSync(srcPath, targetPath)
+                    savedPaths.push(targetPath)
+                  }
+                  if (IMAGE_EXTS.includes(ext)) {
+                    parts.push(`![Screenshot](/api/uploads/${filename})`)
+                  } else {
+                    parts.push(`[Download ${filename}](/api/uploads/${filename})`)
+                  }
+                }
+              } else {
+                parts.push(isError ? text : cleanPlaywrightOutput(text))
+              }
+            } else {
+              parts.push(isError ? text : cleanPlaywrightOutput(text))
+            }
+          }
+        }
+        if (savedPaths.length > 0) {
+          const unique = Array.from(new Set(savedPaths))
+          const rendered = unique.map((p) => path.relative(cwd, p) || '.').join(', ')
+          parts.push(`Saved to: ${rendered}`)
+        }
+        return parts.join('\n')
+      }
+      return JSON.stringify(result)
+    }
+
+    // Action-to-MCP tool mapping
+    const MCP_TOOL_MAP: Record<string, string> = {
+      navigate: 'browser_navigate',
+      screenshot: 'browser_take_screenshot',
+      snapshot: 'browser_snapshot',
+      click: 'browser_click',
+      type: 'browser_type',
+      press_key: 'browser_press_key',
+      select: 'browser_select_option',
+      evaluate: 'browser_evaluate',
+      pdf: 'browser_pdf_save',
+      upload: 'browser_file_upload',
+      wait: 'browser_wait_for',
+    }
+
+    tools.push(
+      tool(
+        async (params) => {
+          try {
+            const { action, ...rest } = params
+            // Build MCP args based on action
+            const mcpTool = MCP_TOOL_MAP[action]
+            if (!mcpTool) return `Unknown browser action: "${action}". Valid: ${Object.keys(MCP_TOOL_MAP).join(', ')}`
+            // Pass only defined (non-undefined) params to MCP
+            const args: Record<string, any> = {}
+            for (const [k, v] of Object.entries(rest)) {
+              if (v !== undefined && v !== null && v !== '') args[k] = v
+            }
+            const saveTo = typeof params.saveTo === 'string' && params.saveTo.trim()
+              ? params.saveTo.trim()
+              : undefined
+            return await callMcpTool(mcpTool, args, { saveTo })
+          } catch (err: any) {
+            return `Error: ${err.message}`
+          }
+        },
+        {
+          name: 'browser',
+          description: [
+            'Control the browser. Use action to specify what to do.',
+            'Actions: navigate (url), screenshot, snapshot (get page elements), click (element/ref), type (element/ref, text), press_key (key), select (element/ref, option), evaluate (expression), pdf, upload (paths, ref), wait (text/timeout).',
+            'Workflow: use snapshot to see the page and get element refs, then use click/type/select with those refs.',
+            'Screenshots are returned as images visible to the user. Use saveTo to persist screenshot/PDF artifacts to disk.',
+          ].join(' '),
+          schema: z.object({
+            action: z.enum(['navigate', 'screenshot', 'snapshot', 'click', 'type', 'press_key', 'select', 'evaluate', 'pdf', 'upload', 'wait']).describe('The browser action to perform'),
+            url: z.string().optional().describe('URL to navigate to (for navigate action)'),
+            element: z.string().optional().describe('CSS selector or description of an element (for click/type/select)'),
+            ref: z.string().optional().describe('Element reference from a previous snapshot (for click/type/select/upload)'),
+            text: z.string().optional().describe('Text to type (for type action) or text to wait for (for wait action)'),
+            key: z.string().optional().describe('Key to press, e.g. Enter, Tab, Escape (for press_key action)'),
+            option: z.string().optional().describe('Option value or label to select (for select action)'),
+            expression: z.string().optional().describe('JavaScript expression to evaluate (for evaluate action)'),
+            paths: z.array(z.string()).optional().describe('File paths to upload (for upload action)'),
+            timeout: z.number().optional().describe('Timeout in milliseconds (for wait action, default 30000)'),
+            saveTo: z.string().optional().describe('Optional output path for screenshot/pdf artifacts (relative to working directory).'),
+          }),
+        },
+      ),
+    )
+  }
+
+  return tools
+}

package/src/lib/server/session-tools.ts

@@ -0,0 +1,9 @@
+export {
+  buildSessionTools,
+  sweepOrphanedBrowsers,
+  cleanupSessionBrowser,
+  getActiveBrowserCount,
+  hasActiveBrowser,
+  type SessionToolsResult,
+  type ToolContext,
+} from './session-tools/index'