@swarmclawai/swarmclaw 0.7.1 → 0.7.3

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

@@ -5,7 +5,7 @@ import { getPluginManager } from '../plugins'
 import type { Plugin, PluginHooks, ClawHubSkill } from '@/types'
 import { searchClawHub } from '../clawhub-client'
 import { normalizeToolInputArgs } from './normalize-tool-args'
-import { toolIdMatches } from '../tool-aliases'
+import { pluginIdMatches } from '../tool-aliases'
 import { loadSessions } from '../storage'
 
 /**
@@ -88,7 +88,7 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
         if (bctx?.ctx?.sessionId) {
           const allSessions = loadSessions()
           const currentSession = allSessions[bctx.ctx.sessionId]
-          if (currentSession && toolIdMatches(currentSession.tools, pluginId)) {
+          if (currentSession && pluginIdMatches(currentSession.tools, pluginId)) {
             return JSON.stringify({
               alreadyGranted: true,
               pluginId,
@@ -96,8 +96,8 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
             })
           }
         }
-        const { requestApproval } = await import('../approvals')
-        requestApproval({
+        const { requestApprovalMaybeAutoApprove } = await import('../approvals')
+        const approval = await requestApprovalMaybeAutoApprove({
           category: 'tool_access',
           title: `Enable Plugin: ${pluginId}`,
           description: reason || `Agent is requesting access to the "${pluginId}" plugin.`,
@@ -105,6 +105,15 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
           agentId: bctx?.ctx?.agentId,
           sessionId: bctx?.ctx?.sessionId,
         })
+        if (approval.status === 'approved') {
+          return JSON.stringify({
+            alreadyGranted: true,
+            pluginId,
+            toolId: pluginId,
+            autoApproved: true,
+            message: `Access to "${pluginId}" was auto-approved and granted. Proceed to use it directly.`,
+          })
+        }
         return JSON.stringify({
           type: 'plugin_request',
           pluginId,
@@ -118,8 +127,8 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
           return JSON.stringify({ error: 'url is required for install_request.' })
         }
         if (approved !== true) {
-          const { requestApproval } = await import('../approvals')
-          requestApproval({
+          const { requestApprovalMaybeAutoApprove } = await import('../approvals')
+          const approval = await requestApprovalMaybeAutoApprove({
             category: 'plugin_install',
             title: `Install Plugin${pluginId ? `: ${pluginId}` : ' from URL'}`,
             description: reason || `Agent wants to install a plugin${url ? ` from ${url}` : ''}.`,
@@ -127,6 +136,15 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
             agentId: bctx?.ctx?.agentId,
             sessionId: bctx?.ctx?.sessionId,
           })
+          if (approval.status === 'approved') {
+            return JSON.stringify({
+              type: 'plugin_install_request',
+              url,
+              pluginId,
+              autoApproved: true,
+              message: `Plugin install from ${url} was auto-approved and has been applied.`,
+            })
+          }
           return JSON.stringify({
             type: 'plugin_install_request',
             url,

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

@@ -0,0 +1,283 @@
+import path from 'path'
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import { genId } from '@/lib/id'
+import type { DocumentEntry, Plugin, PluginHooks } from '@/types'
+import { getPluginManager } from '../plugins'
+import { loadDocuments, saveDocuments } from '../storage'
+import { extractDocumentArtifact } from '../document-utils'
+import type { ToolBuildContext } from './context'
+import { findBinaryOnPath, safePath } from './context'
+import { normalizeToolInputArgs } from './normalize-tool-args'
+
+function parseMetadataInput(value: unknown): Record<string, unknown> {
+  if (!value) return {}
+  if (typeof value === 'object' && !Array.isArray(value)) return value as Record<string, unknown>
+  if (typeof value === 'string' && value.trim()) {
+    try {
+      const parsed = JSON.parse(value)
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as Record<string, unknown>
+    } catch {
+      return {}
+    }
+  }
+  return {}
+}
+
+function resolveFilePath(cwd: string, value: unknown): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('filePath is required.')
+  return path.isAbsolute(value) ? path.resolve(value) : safePath(cwd, value)
+}
+
+function previewTables(tables: Awaited<ReturnType<typeof extractDocumentArtifact>>['tables']) {
+  return tables.map((table) => ({
+    name: table.name,
+    headers: table.headers,
+    rowCount: table.rowCount,
+    rows: table.rows.slice(0, 20),
+    truncated: table.rowCount > 20,
+  }))
+}
+
+function searchStoredDocuments(documents: Record<string, DocumentEntry>, query: string, limit: number) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean)
+  return Object.values(documents)
+    .map((doc) => {
+      const hay = `${doc.title}\n${doc.fileName}\n${doc.content}`.toLowerCase()
+      if (!terms.every((term) => hay.includes(term))) return null
+      let score = hay.includes(query.toLowerCase()) ? 10 : 0
+      for (const term of terms) {
+        let at = hay.indexOf(term)
+        while (at !== -1) {
+          score += 1
+          at = hay.indexOf(term, at + term.length)
+        }
+      }
+      const firstTerm = terms[0] || query
+      const at = hay.indexOf(firstTerm.toLowerCase())
+      const start = at >= 0 ? Math.max(0, at - 120) : 0
+      const end = Math.min(doc.content.length, start + 360)
+      return {
+        id: doc.id,
+        title: doc.title,
+        fileName: doc.fileName,
+        score,
+        snippet: doc.content.slice(start, end).replace(/\s+/g, ' ').trim(),
+        updatedAt: doc.updatedAt,
+      }
+    })
+    .filter((entry): entry is NonNullable<typeof entry> => !!entry)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+}
+
+async function executeDocumentAction(
+  args: Record<string, unknown>,
+  bctx: { cwd: string; sessionId?: string | null; agentId?: string | null },
+) {
+  const normalized = normalizeToolInputArgs(args)
+  const action = String(normalized.action || 'status').trim().toLowerCase()
+
+  try {
+    if (action === 'status') {
+      return JSON.stringify({
+        pdftotext: findBinaryOnPath('pdftotext') || null,
+        textutil: findBinaryOnPath('textutil') || null,
+        tesseract: findBinaryOnPath('tesseract') || null,
+        supports: ['read', 'metadata', 'ocr', 'extract_tables', 'store', 'list', 'search', 'get', 'delete'],
+      })
+    }
+
+    if (action === 'list' || action === 'list_stored') {
+      const documents = loadDocuments() as Record<string, DocumentEntry>
+      const limit = typeof normalized.limit === 'number' ? Math.max(1, Math.min(normalized.limit, 200)) : 50
+      return JSON.stringify(
+        Object.values(documents)
+          .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0))
+          .slice(0, limit)
+          .map((doc) => ({
+            id: doc.id,
+            title: doc.title,
+            fileName: doc.fileName,
+            sourcePath: doc.sourcePath,
+            textLength: doc.textLength,
+            method: doc.method,
+            metadata: doc.metadata || {},
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+          })),
+      )
+    }
+
+    if (action === 'search' || action === 'search_stored') {
+      const query = typeof normalized.query === 'string' ? normalized.query.trim() : ''
+      if (!query) return 'Error: query is required.'
+      const documents = loadDocuments() as Record<string, DocumentEntry>
+      const limit = typeof normalized.limit === 'number' ? Math.max(1, Math.min(normalized.limit, 50)) : 10
+      const matches = searchStoredDocuments(documents, query, limit)
+      return JSON.stringify({ query, total: matches.length, matches })
+    }
+
+    if (action === 'get' || action === 'get_stored') {
+      const id = typeof normalized.id === 'string' ? normalized.id.trim() : ''
+      if (!id) return 'Error: id is required.'
+      const documents = loadDocuments() as Record<string, DocumentEntry>
+      const doc = documents[id]
+      if (!doc) return `Error: document "${id}" not found.`
+      return JSON.stringify({
+        ...doc,
+        content: doc.content.length > 80_000 ? `${doc.content.slice(0, 80_000)}\n... [truncated]` : doc.content,
+      })
+    }
+
+    if (action === 'delete' || action === 'delete_stored') {
+      const id = typeof normalized.id === 'string' ? normalized.id.trim() : ''
+      if (!id) return 'Error: id is required.'
+      const documents = loadDocuments() as Record<string, DocumentEntry>
+      if (!documents[id]) return `Error: document "${id}" not found.`
+      delete documents[id]
+      saveDocuments(documents)
+      return JSON.stringify({ ok: true, id })
+    }
+
+    const filePath = resolveFilePath(bctx.cwd, normalized.filePath ?? normalized.path)
+    const artifact = await extractDocumentArtifact(filePath, {
+      preferOcr: action === 'ocr' || normalized.preferOcr === true,
+      maxChars: typeof normalized.maxChars === 'number' ? Math.max(5_000, normalized.maxChars) : undefined,
+    })
+
+    if (action === 'metadata') {
+      return JSON.stringify({
+        filePath: artifact.filePath,
+        fileName: artifact.fileName,
+        ext: artifact.ext,
+        method: artifact.method,
+        metadata: artifact.metadata,
+        textLength: artifact.text.length,
+        tableCount: artifact.tables.length,
+      })
+    }
+
+    if (action === 'extract_tables') {
+      return JSON.stringify({
+        filePath: artifact.filePath,
+        fileName: artifact.fileName,
+        tableCount: artifact.tables.length,
+        tables: previewTables(artifact.tables),
+      })
+    }
+
+    if (action === 'store') {
+      if (!artifact.text.trim()) return 'Error: extracted document text is empty.'
+      const documents = loadDocuments() as Record<string, DocumentEntry>
+      const now = Date.now()
+      const docId = genId(8)
+      const entry: DocumentEntry = {
+        id: docId,
+        title: typeof normalized.title === 'string' && normalized.title.trim() ? normalized.title.trim() : artifact.fileName,
+        fileName: artifact.fileName,
+        sourcePath: artifact.filePath,
+        content: artifact.text,
+        method: artifact.method,
+        textLength: artifact.text.length,
+        metadata: {
+          ...artifact.metadata,
+          ...parseMetadataInput(normalized.metadata),
+          ext: artifact.ext,
+          tableCount: artifact.tables.length,
+          storedByAgentId: bctx.agentId || null,
+          storedInSessionId: bctx.sessionId || null,
+        },
+        createdAt: now,
+        updatedAt: now,
+      }
+      documents[entry.id] = entry
+      saveDocuments(documents)
+      return JSON.stringify({
+        id: entry.id,
+        title: entry.title,
+        fileName: entry.fileName,
+        textLength: entry.textLength,
+        method: entry.method,
+        metadata: entry.metadata,
+      })
+    }
+
+    if (action === 'read' || action === 'ocr') {
+      return JSON.stringify({
+        filePath: artifact.filePath,
+        fileName: artifact.fileName,
+        ext: artifact.ext,
+        method: artifact.method,
+        text: artifact.text,
+        textLength: artifact.text.length,
+        metadata: artifact.metadata,
+        tableCount: artifact.tables.length,
+        tables: previewTables(artifact.tables),
+      })
+    }
+
+    return `Error: Unknown action "${action}".`
+  } catch (err: unknown) {
+    return `Error: ${err instanceof Error ? err.message : String(err)}`
+  }
+}
+
+const DocumentPlugin: Plugin = {
+  name: 'Document',
+  enabledByDefault: false,
+  description: 'Extract text/tables/OCR from local documents and optionally store them for later retrieval.',
+  hooks: {
+    getCapabilityDescription: () =>
+      'I can parse local documents with `document`, including PDFs, office docs, OCR-able images, CSV/XLSX tables, and stored document search.',
+  } as PluginHooks,
+  tools: [
+    {
+      name: 'document',
+      description: 'Document parsing tool. Actions: status, read, metadata, ocr, extract_tables, store, list, list_stored, search, search_stored, get, get_stored, delete, delete_stored.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'read', 'metadata', 'ocr', 'extract_tables', 'store', 'list', 'list_stored', 'search', 'search_stored', 'get', 'get_stored', 'delete', 'delete_stored'],
+          },
+          filePath: { type: 'string' },
+          id: { type: 'string' },
+          title: { type: 'string' },
+          query: { type: 'string' },
+          metadata: {},
+          limit: { type: 'number' },
+          maxChars: { type: 'number' },
+          preferOcr: { type: 'boolean' },
+        },
+        required: ['action'],
+      },
+      execute: async (args, context) => executeDocumentAction(args, {
+        cwd: context.session.cwd || process.cwd(),
+        sessionId: context.session.id,
+        agentId: context.session.agentId || null,
+      }),
+    },
+  ],
+}
+
+getPluginManager().registerBuiltin('document', DocumentPlugin)
+
+export function buildDocumentTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  if (!bctx.hasPlugin('document')) return []
+  return [
+    tool(
+      async (args) => executeDocumentAction(args, {
+        cwd: bctx.cwd,
+        sessionId: bctx.ctx?.sessionId || null,
+        agentId: bctx.ctx?.agentId || null,
+      }),
+      {
+        name: 'document',
+        description: DocumentPlugin.tools![0].description,
+        schema: z.object({}).passthrough(),
+      },
+    ),
+  ]
+}

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

@@ -43,7 +43,9 @@ async function executeEditFile(args: { filePath: string; oldString: string; newS
 const EditFilePlugin: Plugin = {
   name: 'Core Edit File',
   description: 'Surgical search-and-replace within existing files.',
-  hooks: {} as PluginHooks,
+  hooks: {
+    getCapabilityDescription: () => 'I can make precise edits to files (`edit_file`) — surgical find-and-replace without rewriting the whole file.',
+  } as PluginHooks,
   tools: [
     {
       name: 'edit_file',
@@ -68,7 +70,7 @@ getPluginManager().registerBuiltin('edit_file', EditFilePlugin)
  * Legacy Bridge
  */
 export function buildEditFileTools(bctx: ToolBuildContext): StructuredToolInterface[] {
-  if (!bctx.hasTool('edit_file')) return []
+  if (!bctx.hasPlugin('edit_file')) return []
   return [
     tool(
       async (args) => executeEditFile(args as any, { cwd: bctx.cwd }),

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

@@ -0,0 +1,320 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import type { Plugin, PluginHooks } from '@/types'
+import { getPluginManager } from '../plugins'
+import { normalizeToolInputArgs } from './normalize-tool-args'
+import type { ToolBuildContext } from './context'
+
+interface SmtpConfig {
+  host: string
+  port: number
+  secure: boolean
+  username: string
+  password: string
+  fromAddress: string
+  fromName: string
+}
+
+function getSmtpConfig(): SmtpConfig {
+  const ps = getPluginManager().getPluginSettings('email')
+  return {
+    host: (ps.host as string) || '',
+    port: Number(ps.port) || 587,
+    secure: ps.secure === true || ps.secure === 'true',
+    username: (ps.username as string) || '',
+    password: (ps.password as string) || '',
+    fromAddress: (ps.fromAddress as string) || '',
+    fromName: (ps.fromName as string) || 'SwarmClaw Agent',
+  }
+}
+
+/**
+ * Minimal SMTP client using raw sockets.
+ * Avoids nodemailer dependency — uses Node's built-in net/tls.
+ */
+async function sendSmtpEmail(cfg: SmtpConfig, to: string[], subject: string, body: string, html?: string): Promise<string> {
+  const net = await import('net')
+  const tls = await import('tls')
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('SMTP timeout (30s)')), 30_000)
+    let socket: import('net').Socket
+    const lines: string[] = []
+    let phase = 'connect'
+
+    const cleanup = () => { clearTimeout(timeout); try { socket.destroy() } catch { /* ok */ } }
+
+    const readLine = (data: Buffer) => {
+      const text = data.toString()
+      lines.push(text)
+      const code = parseInt(text.slice(0, 3), 10)
+      return { text, code }
+    }
+
+    const send = (cmd: string) => { socket.write(cmd + '\r\n') }
+
+    // Build MIME message
+    const boundary = `----=_Part_${Date.now()}_${Math.random().toString(36).slice(2)}`
+    const date = new Date().toUTCString()
+    const msgId = `<${Date.now()}.${Math.random().toString(36).slice(2)}@${cfg.host}>`
+    const toHeader = to.join(', ')
+
+    let message = `From: ${cfg.fromName ? `"${cfg.fromName}" ` : ''}<${cfg.fromAddress}>\r\n`
+    message += `To: ${toHeader}\r\n`
+    message += `Subject: ${subject}\r\n`
+    message += `Date: ${date}\r\n`
+    message += `Message-ID: ${msgId}\r\n`
+    message += `MIME-Version: 1.0\r\n`
+
+    if (html) {
+      message += `Content-Type: multipart/alternative; boundary="${boundary}"\r\n\r\n`
+      message += `--${boundary}\r\n`
+      message += `Content-Type: text/plain; charset=utf-8\r\n\r\n`
+      message += body + '\r\n'
+      message += `--${boundary}\r\n`
+      message += `Content-Type: text/html; charset=utf-8\r\n\r\n`
+      message += html + '\r\n'
+      message += `--${boundary}--\r\n`
+    } else {
+      message += `Content-Type: text/plain; charset=utf-8\r\n\r\n`
+      message += body + '\r\n'
+    }
+
+    const connectOpts = { host: cfg.host, port: cfg.port }
+
+    const handleData = (data: Buffer) => {
+      const { code } = readLine(data)
+
+      switch (phase) {
+        case 'connect':
+          if (code === 220) { phase = 'ehlo'; send(`EHLO ${cfg.host}`) }
+          else { cleanup(); reject(new Error(`SMTP connect failed: ${data.toString().trim()}`)) }
+          break
+        case 'ehlo':
+          if (code === 250) {
+            if (cfg.secure && !('encrypted' in socket)) {
+              phase = 'starttls'; send('STARTTLS')
+            } else if (cfg.username) {
+              phase = 'auth'; send('AUTH LOGIN')
+            } else {
+              phase = 'mail_from'; send(`MAIL FROM:<${cfg.fromAddress}>`)
+            }
+          }
+          break
+        case 'starttls':
+          if (code === 220) {
+            const tlsSocket = tls.connect({ socket, host: cfg.host, rejectUnauthorized: false }, () => {
+              socket = tlsSocket as unknown as import('net').Socket
+              socket.on('data', handleData)
+              phase = 'ehlo2'; send(`EHLO ${cfg.host}`)
+            })
+            tlsSocket.on('error', (err: Error) => { cleanup(); reject(err) })
+          }
+          break
+        case 'ehlo2':
+          if (code === 250) {
+            if (cfg.username) { phase = 'auth'; send('AUTH LOGIN') }
+            else { phase = 'mail_from'; send(`MAIL FROM:<${cfg.fromAddress}>`) }
+          }
+          break
+        case 'auth':
+          if (code === 334) { phase = 'auth_user'; send(Buffer.from(cfg.username).toString('base64')) }
+          else { cleanup(); reject(new Error(`SMTP AUTH failed: ${data.toString().trim()}`)) }
+          break
+        case 'auth_user':
+          if (code === 334) { phase = 'auth_pass'; send(Buffer.from(cfg.password).toString('base64')) }
+          break
+        case 'auth_pass':
+          if (code === 235) { phase = 'mail_from'; send(`MAIL FROM:<${cfg.fromAddress}>`) }
+          else { cleanup(); reject(new Error(`SMTP auth failed: ${data.toString().trim()}`)) }
+          break
+        case 'mail_from':
+          if (code === 250) { phase = 'rcpt_to'; send(`RCPT TO:<${to[0]}>`) }
+          break
+        case 'rcpt_to':
+          if (code === 250) { phase = 'data'; send('DATA') }
+          else { cleanup(); reject(new Error(`SMTP RCPT rejected: ${data.toString().trim()}`)) }
+          break
+        case 'data':
+          if (code === 354) { phase = 'message'; send(message + '\r\n.') }
+          break
+        case 'message':
+          if (code === 250) { phase = 'quit'; send('QUIT'); cleanup(); resolve('Email sent successfully.') }
+          else { cleanup(); reject(new Error(`SMTP send failed: ${data.toString().trim()}`)) }
+          break
+        case 'quit':
+          cleanup()
+          break
+      }
+    }
+
+    if (cfg.secure && cfg.port === 465) {
+      socket = tls.connect({ ...connectOpts, rejectUnauthorized: false }, () => {
+        (socket as unknown as Record<string, boolean>).encrypted = true
+      }) as unknown as import('net').Socket
+    } else {
+      socket = net.createConnection(connectOpts)
+    }
+
+    socket.on('data', handleData)
+    socket.on('error', (err: Error) => { cleanup(); reject(err) })
+  })
+}
+
+async function executeEmail(args: Record<string, unknown>): Promise<string> {
+  const normalized = normalizeToolInputArgs(args)
+  const action = String(normalized.action || 'send')
+
+  if (action === 'send') {
+    const to = normalized.to
+    const recipients: string[] = Array.isArray(to) ? to.map(String) : typeof to === 'string' ? to.split(/[,;\s]+/).filter(Boolean) : []
+    if (recipients.length === 0) return 'Error: "to" (recipient email addresses) is required.'
+
+    const subject = String(normalized.subject || '').trim()
+    if (!subject) return 'Error: "subject" is required.'
+
+    const body = String(normalized.body || '').trim()
+    if (!body) return 'Error: "body" (plain text content) is required.'
+
+    const html = typeof normalized.html === 'string' ? normalized.html : undefined
+
+    const cfg = getSmtpConfig()
+    if (!cfg.host) return 'Error: SMTP host not configured. Ask the user to configure email in Plugin Settings > Email.'
+    if (!cfg.fromAddress) return 'Error: From address not configured in email plugin settings.'
+
+    try {
+      const result = await sendSmtpEmail(cfg, recipients, subject, body, html)
+      return `${result}\nTo: ${recipients.join(', ')}\nSubject: ${subject}`
+    } catch (err: unknown) {
+      return `Error sending email: ${err instanceof Error ? err.message : String(err)}`
+    }
+  }
+
+  if (action === 'status') {
+    const cfg = getSmtpConfig()
+    if (!cfg.host) return 'Email plugin not configured. No SMTP host set.'
+    return JSON.stringify({
+      configured: true,
+      host: cfg.host,
+      port: cfg.port,
+      secure: cfg.secure,
+      from: cfg.fromAddress,
+      fromName: cfg.fromName,
+    })
+  }
+
+  return `Error: Unknown action "${action}". Use "send" or "status".`
+}
+
+const EmailPlugin: Plugin = {
+  name: 'Email',
+  enabledByDefault: false,
+  description: 'Send emails via SMTP. Supports plain text and HTML, multiple recipients.',
+  hooks: {
+    getCapabilityDescription: () =>
+      'I can send emails using `email`. Supports plain text and HTML bodies, multiple recipients.',
+  } as PluginHooks,
+  tools: [
+    {
+      name: 'email',
+      description: 'Send an email or check email configuration status. For sending: provide to, subject, and body. Optionally include html for rich formatting.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['send', 'status'], description: 'Action to perform (default: send)' },
+          to: {
+            anyOf: [
+              { type: 'string', description: 'Recipient email address(es), comma-separated' },
+              { type: 'array', items: { type: 'string' }, description: 'Array of recipient email addresses' },
+            ],
+          },
+          subject: { type: 'string', description: 'Email subject line' },
+          body: { type: 'string', description: 'Plain text email body' },
+          html: { type: 'string', description: 'Optional HTML email body (sent as multipart/alternative alongside plain text)' },
+        },
+        required: ['action'],
+      },
+      execute: async (args) => executeEmail(args),
+    },
+  ],
+  ui: {
+    settingsFields: [
+      {
+        key: 'host',
+        label: 'SMTP Host',
+        type: 'text',
+        required: true,
+        placeholder: 'smtp.gmail.com',
+        help: 'SMTP server hostname.',
+      },
+      {
+        key: 'port',
+        label: 'SMTP Port',
+        type: 'number',
+        defaultValue: 587,
+        help: '587 for STARTTLS, 465 for SSL, 25 for unencrypted.',
+      },
+      {
+        key: 'secure',
+        label: 'Use SSL/TLS (port 465)',
+        type: 'boolean',
+        defaultValue: false,
+        help: 'Enable for direct TLS connections (port 465). Leave off for STARTTLS (port 587).',
+      },
+      {
+        key: 'username',
+        label: 'Username',
+        type: 'text',
+        placeholder: 'you@gmail.com',
+        help: 'SMTP authentication username (usually your email address).',
+      },
+      {
+        key: 'password',
+        label: 'Password',
+        type: 'secret',
+        required: true,
+        placeholder: 'App password or SMTP password',
+        help: 'SMTP password. For Gmail, use an App Password.',
+      },
+      {
+        key: 'fromAddress',
+        label: 'From Address',
+        type: 'text',
+        required: true,
+        placeholder: 'agent@example.com',
+        help: 'The sender email address.',
+      },
+      {
+        key: 'fromName',
+        label: 'From Name',
+        type: 'text',
+        defaultValue: 'SwarmClaw Agent',
+        placeholder: 'SwarmClaw Agent',
+        help: 'Display name shown to recipients.',
+      },
+    ],
+  },
+}
+
+getPluginManager().registerBuiltin('email', EmailPlugin)
+
+export function buildEmailTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  if (!bctx.hasPlugin('email')) return []
+
+  return [
+    tool(
+      async (args) => executeEmail(args),
+      {
+        name: 'email',
+        description: EmailPlugin.tools![0].description,
+        schema: z.object({
+          action: z.enum(['send', 'status']).optional().describe('Action (default: send)'),
+          to: z.union([z.string(), z.array(z.string())]).optional().describe('Recipient email address(es)'),
+          subject: z.string().optional().describe('Email subject line'),
+          body: z.string().optional().describe('Plain text email body'),
+          html: z.string().optional().describe('Optional HTML body'),
+        }),
+      },
+    ),
+  ]
+}