@agenticmail/enterprise 0.5.50 → 0.5.51

package/src/agent-tools/tools/agenticmail.ts

@@ -0,0 +1,785 @@
+/**
+ * AgenticMail Agent Tools — Enterprise Adapter
+ *
+ * Wraps the self-contained agenticmail-core tool handlers into
+ * the enterprise AgentTool format so they integrate with the
+ * enterprise tool system (middleware, audit, security, etc.).
+ *
+ * The core tools.ts was written for OpenClaw's registerTool() API.
+ * This adapter intercepts those registrations and produces AgentTool[].
+ */
+
+import type { AnyAgentTool, ToolCreationOptions, ToolParameterSchema } from '../types.js';
+import { jsonResult, errorResult } from '../common.js';
+
+/** AgenticMail API connection config */
+export interface AgenticMailConnectionConfig {
+  /** AgenticMail API base URL (e.g. http://localhost:3141) */
+  apiUrl: string;
+  /** Agent API key */
+  apiKey: string;
+  /** Master key for admin operations (optional) */
+  masterKey?: string;
+  /** Display name for the agent */
+  ownerName?: string;
+}
+
+/**
+ * Create all AgenticMail tools as enterprise AgentTool objects.
+ *
+ * These tools make HTTP calls to the AgenticMail API server.
+ * They need a running AgenticMail instance to function.
+ *
+ * @param connection - AgenticMail API connection config
+ * @param options    - Standard enterprise tool creation options
+ */
+export function createAgenticMailTools(
+  connection: AgenticMailConnectionConfig,
+  options?: ToolCreationOptions,
+): AnyAgentTool[] {
+  const tools: AnyAgentTool[] = [];
+
+  // ─── HTTP helper (same as agenticmail-core/tools.ts apiRequest) ────
+
+  async function apiRequest(
+    method: string,
+    path: string,
+    body?: unknown,
+    useMasterKey = false,
+    timeoutMs = 30_000,
+  ): Promise<any> {
+    const key = useMasterKey && connection.masterKey
+      ? connection.masterKey
+      : connection.apiKey;
+    if (!key) {
+      throw new Error(
+        useMasterKey
+          ? 'Master key is required for this operation but was not configured'
+          : 'API key is not configured',
+      );
+    }
+
+    const headers: Record<string, string> = { Authorization: `Bearer ${key}` };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+    const response = await fetch(`${connection.apiUrl}/api/agenticmail${path}`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+
+    if (!response.ok) {
+      let text: string;
+      try {
+        text = await response.text();
+      } catch {
+        text = '(could not read response body)';
+      }
+      throw new Error(`AgenticMail API error ${response.status}: ${text}`);
+    }
+
+    const contentType = response.headers.get('content-type');
+    if (contentType?.includes('application/json')) {
+      try {
+        return await response.json();
+      } catch {
+        throw new Error(`API returned invalid JSON from ${path}`);
+      }
+    }
+    return null;
+  }
+
+  // ─── Helper: define an agenticmail tool ────────────────────────────
+
+  function defTool(
+    name: string,
+    label: string,
+    description: string,
+    params: ToolParameterSchema,
+    risk: 'low' | 'medium' | 'high' | 'critical',
+    handler: (args: Record<string, unknown>) => Promise<any>,
+  ): void {
+    tools.push({
+      name,
+      label,
+      description,
+      category: 'utility',
+      risk,
+      parameters: params,
+      execute: async (_toolCallId, args) => {
+        try {
+          const result = await handler(args as Record<string, unknown>);
+          return jsonResult(result);
+        } catch (err: any) {
+          return errorResult(err.message || String(err));
+        }
+      },
+    });
+  }
+
+  // Helper for simple params
+  function p(props: Record<string, any>, required?: string[]): ToolParameterSchema {
+    return { type: 'object', properties: props, required };
+  }
+
+  // ─── Email Core ───────────────────────────────────────────────────
+
+  defTool('agenticmail_send', 'Send Email',
+    'Send an email from the agent mailbox. Outbound guard scans for PII/credentials.',
+    p({
+      to: { type: 'string', description: 'Recipient email' },
+      subject: { type: 'string', description: 'Email subject' },
+      text: { type: 'string', description: 'Plain text body' },
+      html: { type: 'string', description: 'HTML body' },
+      cc: { type: 'string', description: 'CC recipients' },
+    }, ['to', 'subject']),
+    'high',
+    async (args) => apiRequest('POST', '/mail/send', args),
+  );
+
+  defTool('agenticmail_reply', 'Reply to Email',
+    'Reply to an email by UID.',
+    p({
+      uid: { type: 'number', description: 'Email UID to reply to' },
+      text: { type: 'string', description: 'Reply text' },
+      replyAll: { type: 'boolean', description: 'Reply to all recipients' },
+    }, ['uid', 'text']),
+    'high',
+    async (args) => apiRequest('POST', `/mail/${args.uid}/reply`, { text: args.text, replyAll: args.replyAll }),
+  );
+
+  defTool('agenticmail_forward', 'Forward Email',
+    'Forward an email to another recipient.',
+    p({
+      uid: { type: 'number', description: 'Email UID to forward' },
+      to: { type: 'string', description: 'Recipient to forward to' },
+      text: { type: 'string', description: 'Additional message' },
+    }, ['uid', 'to']),
+    'high',
+    async (args) => apiRequest('POST', `/mail/${args.uid}/forward`, { to: args.to, text: args.text }),
+  );
+
+  defTool('agenticmail_inbox', 'List Inbox',
+    'List recent emails in the inbox.',
+    p({
+      limit: { type: 'number', description: 'Max messages (default 20)' },
+      offset: { type: 'number', description: 'Skip messages (default 0)' },
+    }),
+    'low',
+    async (args) => {
+      const qs = new URLSearchParams();
+      if (args.limit) qs.set('limit', String(args.limit));
+      if (args.offset) qs.set('offset', String(args.offset));
+      const q = qs.toString();
+      return apiRequest('GET', `/mail/inbox${q ? '?' + q : ''}`);
+    },
+  );
+
+  defTool('agenticmail_read', 'Read Email',
+    'Read a specific email by UID.',
+    p({ uid: { type: 'number', description: 'Email UID' } }, ['uid']),
+    'low',
+    async (args) => apiRequest('GET', `/mail/${args.uid}`),
+  );
+
+  defTool('agenticmail_search', 'Search Emails',
+    'Search emails by criteria.',
+    p({
+      from: { type: 'string', description: 'Sender address' },
+      to: { type: 'string', description: 'Recipient address' },
+      subject: { type: 'string', description: 'Subject keyword' },
+      text: { type: 'string', description: 'Body text' },
+      since: { type: 'string', description: 'Since date (ISO 8601)' },
+      before: { type: 'string', description: 'Before date (ISO 8601)' },
+      seen: { type: 'boolean', description: 'Filter by read/unread' },
+      searchRelay: { type: 'boolean', description: 'Also search connected Gmail/Outlook' },
+    }),
+    'low',
+    async (args) => apiRequest('POST', '/mail/search', args),
+  );
+
+  defTool('agenticmail_digest', 'Inbox Digest',
+    'Compact inbox digest with subject, sender, date, and preview.',
+    p({
+      limit: { type: 'number', description: 'Max messages (default 20)' },
+      folder: { type: 'string', description: 'Folder (default INBOX)' },
+      previewLength: { type: 'number', description: 'Preview text length (default 200)' },
+    }),
+    'low',
+    async (args) => apiRequest('POST', '/mail/digest', args),
+  );
+
+  defTool('agenticmail_delete', 'Delete Email',
+    'Delete an email by UID.',
+    p({ uid: { type: 'number', description: 'Email UID' } }, ['uid']),
+    'medium',
+    async (args) => apiRequest('DELETE', `/mail/${args.uid}`),
+  );
+
+  defTool('agenticmail_move', 'Move Email',
+    'Move an email to another folder.',
+    p({
+      uid: { type: 'number', description: 'Email UID' },
+      to: { type: 'string', description: 'Destination folder' },
+      from: { type: 'string', description: 'Source folder (default INBOX)' },
+    }, ['uid', 'to']),
+    'low',
+    async (args) => apiRequest('POST', `/mail/${args.uid}/move`, { to: args.to, from: args.from }),
+  );
+
+  defTool('agenticmail_mark_read', 'Mark Read',
+    'Mark an email as read.',
+    p({ uid: { type: 'number', description: 'Email UID' } }, ['uid']),
+    'low',
+    async (args) => apiRequest('POST', `/mail/${args.uid}/read`),
+  );
+
+  defTool('agenticmail_mark_unread', 'Mark Unread',
+    'Mark an email as unread.',
+    p({ uid: { type: 'number', description: 'Email UID' } }, ['uid']),
+    'low',
+    async (args) => apiRequest('POST', `/mail/${args.uid}/unread`),
+  );
+
+  defTool('agenticmail_folders', 'List Folders',
+    'List all mail folders.',
+    p({}),
+    'low',
+    async () => apiRequest('GET', '/mail/folders'),
+  );
+
+  defTool('agenticmail_list_folder', 'List Folder',
+    'List messages in a specific folder.',
+    p({
+      folder: { type: 'string', description: 'Folder path (e.g. Sent, Trash)' },
+      limit: { type: 'number', description: 'Max messages (default 20)' },
+      offset: { type: 'number', description: 'Skip messages (default 0)' },
+    }, ['folder']),
+    'low',
+    async (args) => {
+      const qs = new URLSearchParams();
+      qs.set('folder', String(args.folder));
+      if (args.limit) qs.set('limit', String(args.limit));
+      if (args.offset) qs.set('offset', String(args.offset));
+      return apiRequest('GET', `/mail/list?${qs}`);
+    },
+  );
+
+  defTool('agenticmail_create_folder', 'Create Folder',
+    'Create a new mail folder.',
+    p({ name: { type: 'string', description: 'Folder name' } }, ['name']),
+    'low',
+    async (args) => apiRequest('POST', '/mail/folders', { name: args.name }),
+  );
+
+  // ─── Batch Operations ──────────────────────────────────────────────
+
+  defTool('agenticmail_batch_read', 'Batch Read',
+    'Read multiple emails at once by UIDs.',
+    p({
+      uids: { type: 'array', description: 'Array of UIDs to read' },
+      folder: { type: 'string', description: 'Folder (default INBOX)' },
+    }, ['uids']),
+    'low',
+    async (args) => apiRequest('POST', '/mail/batch/read', args),
+  );
+
+  defTool('agenticmail_batch_delete', 'Batch Delete',
+    'Delete multiple emails by UIDs.',
+    p({
+      uids: { type: 'array', description: 'UIDs to delete' },
+      folder: { type: 'string', description: 'Folder (default INBOX)' },
+    }, ['uids']),
+    'medium',
+    async (args) => apiRequest('POST', '/mail/batch/delete', args),
+  );
+
+  defTool('agenticmail_batch_move', 'Batch Move',
+    'Move multiple emails to another folder.',
+    p({
+      uids: { type: 'array', description: 'UIDs to move' },
+      to: { type: 'string', description: 'Destination folder' },
+      from: { type: 'string', description: 'Source folder (default INBOX)' },
+    }, ['uids', 'to']),
+    'low',
+    async (args) => apiRequest('POST', '/mail/batch/move', args),
+  );
+
+  defTool('agenticmail_batch_mark_read', 'Batch Mark Read',
+    'Mark multiple emails as read.',
+    p({
+      uids: { type: 'array', description: 'UIDs to mark as read' },
+      folder: { type: 'string', description: 'Folder (default INBOX)' },
+    }, ['uids']),
+    'low',
+    async (args) => apiRequest('POST', '/mail/batch/mark-read', args),
+  );
+
+  defTool('agenticmail_batch_mark_unread', 'Batch Mark Unread',
+    'Mark multiple emails as unread.',
+    p({
+      uids: { type: 'array', description: 'UIDs to mark as unread' },
+      folder: { type: 'string', description: 'Folder (default INBOX)' },
+    }, ['uids']),
+    'low',
+    async (args) => apiRequest('POST', '/mail/batch/mark-unread', args),
+  );
+
+  // ─── Agent Communication ──────────────────────────────────────────
+
+  defTool('agenticmail_list_agents', 'List Agents',
+    'List all AI agents in the system.',
+    p({}),
+    'low',
+    async () => apiRequest('GET', '/agents'),
+  );
+
+  defTool('agenticmail_message_agent', 'Message Agent',
+    'Send a message to another AI agent by name.',
+    p({
+      agent: { type: 'string', description: 'Recipient agent name' },
+      subject: { type: 'string', description: 'Message subject' },
+      text: { type: 'string', description: 'Message body' },
+      priority: { type: 'string', description: 'Priority: normal, high, urgent' },
+    }, ['agent', 'subject', 'text']),
+    'medium',
+    async (args) => apiRequest('POST', '/agents/message', args),
+  );
+
+  defTool('agenticmail_call_agent', 'Call Agent',
+    'Call another agent with a task. Supports sync and async modes.',
+    p({
+      target: { type: 'string', description: 'Agent name to call' },
+      task: { type: 'string', description: 'Task description' },
+      mode: { type: 'string', description: 'light, standard, or full' },
+      async: { type: 'boolean', description: 'Fire-and-forget (default false)' },
+      timeout: { type: 'number', description: 'Max seconds to wait (sync only)' },
+    }, ['target', 'task']),
+    'medium',
+    async (args) => apiRequest('POST', '/agents/call', args, false, 600_000),
+  );
+
+  defTool('agenticmail_check_messages', 'Check Messages',
+    'Check for new unread messages from other agents or external senders.',
+    p({}),
+    'low',
+    async () => apiRequest('GET', '/agents/messages'),
+  );
+
+  defTool('agenticmail_check_tasks', 'Check Tasks',
+    'Check for pending tasks assigned to you.',
+    p({
+      direction: { type: 'string', description: 'incoming or outgoing (default incoming)' },
+      assignee: { type: 'string', description: 'Check tasks for a specific agent' },
+    }),
+    'low',
+    async (args) => apiRequest('POST', '/tasks/check', args),
+  );
+
+  defTool('agenticmail_claim_task', 'Claim Task',
+    'Claim a pending task.',
+    p({ id: { type: 'string', description: 'Task ID' } }, ['id']),
+    'low',
+    async (args) => apiRequest('POST', `/tasks/${args.id}/claim`),
+  );
+
+  defTool('agenticmail_submit_result', 'Submit Task Result',
+    'Submit result for a claimed task.',
+    p({
+      id: { type: 'string', description: 'Task ID' },
+      result: { type: 'object', description: 'Task result data' },
+    }, ['id']),
+    'low',
+    async (args) => apiRequest('POST', `/tasks/${args.id}/result`, { result: args.result }),
+  );
+
+  defTool('agenticmail_complete_task', 'Complete Task',
+    'Claim and submit result in one call.',
+    p({
+      id: { type: 'string', description: 'Task ID' },
+      result: { type: 'object', description: 'Task result data' },
+    }, ['id']),
+    'low',
+    async (args) => apiRequest('POST', `/tasks/${args.id}/complete`, { result: args.result }),
+  );
+
+  defTool('agenticmail_wait_for_email', 'Wait for Email',
+    'Wait for a new email or task notification (push-based, SSE).',
+    p({ timeout: { type: 'number', description: 'Max seconds to wait (default 120)' } }),
+    'low',
+    async (args) => apiRequest('GET', `/mail/wait?timeout=${args.timeout || 120}`, undefined, false, 310_000),
+  );
+
+  // ─── Account Management ───────────────────────────────────────────
+
+  defTool('agenticmail_whoami', 'Who Am I',
+    'Get current agent account info.',
+    p({}),
+    'low',
+    async () => apiRequest('GET', '/accounts/me'),
+  );
+
+  defTool('agenticmail_update_metadata', 'Update Metadata',
+    'Update current agent metadata.',
+    p({ metadata: { type: 'object', description: 'Key-value pairs to set' } }, ['metadata']),
+    'low',
+    async (args) => apiRequest('PATCH', '/accounts/me/metadata', { metadata: args.metadata }),
+  );
+
+  defTool('agenticmail_contacts', 'Manage Contacts',
+    'List, add, or delete contacts.',
+    p({
+      action: { type: 'string', description: 'list, add, or delete' },
+      name: { type: 'string', description: 'Contact name (for add)' },
+      email: { type: 'string', description: 'Contact email (for add)' },
+      id: { type: 'string', description: 'Contact ID (for delete)' },
+    }, ['action']),
+    'low',
+    async (args) => apiRequest('POST', '/contacts', args),
+  );
+
+  // ─── Tags & Labels ────────────────────────────────────────────────
+
+  defTool('agenticmail_tags', 'Manage Tags',
+    'List, create, delete tags; tag/untag messages.',
+    p({
+      action: { type: 'string', description: 'list, create, delete, tag_message, untag_message, get_messages, get_message_tags' },
+      name: { type: 'string', description: 'Tag name (for create)' },
+      color: { type: 'string', description: 'Tag color hex (for create)' },
+      id: { type: 'string', description: 'Tag ID' },
+      uid: { type: 'number', description: 'Message UID' },
+      folder: { type: 'string', description: 'Folder (default INBOX)' },
+    }, ['action']),
+    'low',
+    async (args) => apiRequest('POST', '/tags', args),
+  );
+
+  // ─── Drafts ────────────────────────────────────────────────────────
+
+  defTool('agenticmail_drafts', 'Manage Drafts',
+    'List, create, update, delete, or send drafts.',
+    p({
+      action: { type: 'string', description: 'list, create, update, delete, send' },
+      id: { type: 'string', description: 'Draft ID (for update/delete/send)' },
+      to: { type: 'string', description: 'Recipient (for create/update)' },
+      subject: { type: 'string', description: 'Subject (for create/update)' },
+      text: { type: 'string', description: 'Body text (for create/update)' },
+    }, ['action']),
+    'medium',
+    async (args) => apiRequest('POST', '/drafts', args),
+  );
+
+  // ─── Templates ─────────────────────────────────────────────────────
+
+  defTool('agenticmail_templates', 'Manage Templates',
+    'List, create, or delete email templates.',
+    p({
+      action: { type: 'string', description: 'list, create, or delete' },
+      id: { type: 'string', description: 'Template ID (for delete)' },
+      name: { type: 'string', description: 'Template name (for create)' },
+      subject: { type: 'string', description: 'Template subject (for create)' },
+      text: { type: 'string', description: 'Template body (for create)' },
+    }, ['action']),
+    'low',
+    async (args) => apiRequest('POST', '/templates', args),
+  );
+
+  defTool('agenticmail_template_send', 'Send Template',
+    'Send email using a saved template with variable substitution.',
+    p({
+      id: { type: 'string', description: 'Template ID' },
+      to: { type: 'string', description: 'Recipient email' },
+      variables: { type: 'object', description: 'Variables to substitute' },
+      cc: { type: 'string', description: 'CC recipients' },
+    }, ['id', 'to']),
+    'high',
+    async (args) => apiRequest('POST', '/templates/send', args),
+  );
+
+  // ─── Signatures ────────────────────────────────────────────────────
+
+  defTool('agenticmail_signatures', 'Manage Signatures',
+    'List, create, or delete email signatures.',
+    p({
+      action: { type: 'string', description: 'list, create, or delete' },
+      id: { type: 'string', description: 'Signature ID (for delete)' },
+      name: { type: 'string', description: 'Signature name (for create)' },
+      text: { type: 'string', description: 'Signature text (for create)' },
+      isDefault: { type: 'boolean', description: 'Set as default (for create)' },
+    }, ['action']),
+    'low',
+    async (args) => apiRequest('POST', '/signatures', args),
+  );
+
+  // ─── Rules ─────────────────────────────────────────────────────────
+
+  defTool('agenticmail_rules', 'Manage Rules',
+    'Server-side email rules that auto-process incoming messages.',
+    p({
+      action: { type: 'string', description: 'list, create, or delete' },
+      id: { type: 'string', description: 'Rule ID (for delete)' },
+      name: { type: 'string', description: 'Rule name (for create)' },
+      conditions: { type: 'object', description: 'Match conditions' },
+      actions: { type: 'object', description: 'Actions on match' },
+      priority: { type: 'number', description: 'Priority (higher = first)' },
+    }, ['action']),
+    'medium',
+    async (args) => apiRequest('POST', '/rules', args),
+  );
+
+  // ─── Scheduled Emails ──────────────────────────────────────────────
+
+  defTool('agenticmail_schedule', 'Scheduled Emails',
+    'Create, list, or cancel scheduled emails.',
+    p({
+      action: { type: 'string', description: 'create, list, or cancel' },
+      id: { type: 'string', description: 'Scheduled email ID (for cancel)' },
+      to: { type: 'string', description: 'Recipient (for create)' },
+      subject: { type: 'string', description: 'Subject (for create)' },
+      text: { type: 'string', description: 'Body (for create)' },
+      sendAt: { type: 'string', description: 'When to send (for create)' },
+    }, ['action']),
+    'medium',
+    async (args) => apiRequest('POST', '/schedule', args),
+  );
+
+  // ─── Spam Management ───────────────────────────────────────────────
+
+  defTool('agenticmail_spam', 'Spam Management',
+    'List spam, report spam, mark not-spam, or get spam score.',
+    p({
+      action: { type: 'string', description: 'list, report, not_spam, or score' },
+      uid: { type: 'number', description: 'Message UID (for report/not_spam/score)' },
+      folder: { type: 'string', description: 'Source folder (for report/score)' },
+      limit: { type: 'number', description: 'Max messages (for list)' },
+    }, ['action']),
+    'low',
+    async (args) => apiRequest('POST', '/spam', args),
+  );
+
+  // ─── Pending Emails ────────────────────────────────────────────────
+
+  defTool('agenticmail_pending_emails', 'Pending Emails',
+    'Check status of blocked outbound emails.',
+    p({
+      action: { type: 'string', description: 'list or get' },
+      id: { type: 'string', description: 'Pending email ID (for get)' },
+    }, ['action']),
+    'low',
+    async (args) => apiRequest('POST', '/mail/pending', args),
+  );
+
+  // ─── Storage (Database) ────────────────────────────────────────────
+
+  defTool('agenticmail_storage', 'Agent Storage',
+    'Full database management — tables, CRUD, aggregations, SQL.',
+    p({
+      action: { type: 'string', description: 'create_table, query, insert, update, delete_rows, sql, etc.' },
+      table: { type: 'string', description: 'Table name' },
+      columns: { type: 'array', description: 'Column definitions (for create_table)' },
+      rows: { type: 'array', description: 'Row data (for insert/upsert/import)' },
+      where: { type: 'object', description: 'Filter conditions' },
+      set: { type: 'object', description: 'Update values' },
+      sql: { type: 'string', description: 'Raw SQL (for sql action)' },
+      orderBy: { type: 'string', description: 'ORDER BY clause' },
+      limit: { type: 'number', description: 'Max rows' },
+      offset: { type: 'number', description: 'Skip rows' },
+      selectColumns: { type: 'array', description: 'Columns to select' },
+      operations: { type: 'array', description: 'Aggregate operations' },
+      groupBy: { type: 'string', description: 'GROUP BY clause' },
+    }, ['action']),
+    'medium',
+    async (args) => apiRequest('POST', '/storage', args),
+  );
+
+  // ─── SMS ───────────────────────────────────────────────────────────
+
+  defTool('agenticmail_sms_setup', 'SMS Setup',
+    'Configure SMS/phone via Google Voice.',
+    p({
+      phoneNumber: { type: 'string', description: 'Google Voice phone number' },
+      forwardingEmail: { type: 'string', description: 'Email for SMS forwarding' },
+    }, ['phoneNumber']),
+    'medium',
+    async (args) => apiRequest('POST', '/sms/setup', args, true),
+  );
+
+  defTool('agenticmail_sms_send', 'Send SMS',
+    'Send an SMS via Google Voice.',
+    p({
+      to: { type: 'string', description: 'Recipient phone number' },
+      body: { type: 'string', description: 'Message text' },
+    }, ['to', 'body']),
+    'high',
+    async (args) => apiRequest('POST', '/sms/send', args),
+  );
+
+  defTool('agenticmail_sms_messages', 'SMS Messages',
+    'List SMS messages.',
+    p({
+      direction: { type: 'string', description: 'inbound, outbound, or both' },
+      limit: { type: 'number', description: 'Max messages (default 20)' },
+    }),
+    'low',
+    async (args) => apiRequest('POST', '/sms/messages', args),
+  );
+
+  defTool('agenticmail_sms_check_code', 'SMS Check Code',
+    'Check for recent verification/OTP codes.',
+    p({ minutes: { type: 'number', description: 'How many minutes back (default 10)' } }),
+    'low',
+    async (args) => apiRequest('POST', '/sms/check-code', args),
+  );
+
+  defTool('agenticmail_sms_config', 'SMS Config',
+    'Get current SMS/phone configuration.',
+    p({}),
+    'low',
+    async () => apiRequest('GET', '/sms/config'),
+  );
+
+  defTool('agenticmail_sms_record', 'Record SMS',
+    'Record an SMS message from an external source.',
+    p({
+      from: { type: 'string', description: 'Sender phone number' },
+      body: { type: 'string', description: 'Message text' },
+    }, ['from', 'body']),
+    'low',
+    async (args) => apiRequest('POST', '/sms/record', args),
+  );
+
+  defTool('agenticmail_sms_parse_email', 'Parse SMS Email',
+    'Parse SMS from a forwarded Google Voice email.',
+    p({
+      emailBody: { type: 'string', description: 'Email body text' },
+      emailFrom: { type: 'string', description: 'Email sender address' },
+    }, ['emailBody']),
+    'low',
+    async (args) => apiRequest('POST', '/sms/parse-email', args),
+  );
+
+  // ─── Admin Operations (require master key) ────────────────────────
+
+  defTool('agenticmail_create_account', 'Create Agent Account',
+    'Create a new agent email account.',
+    p({
+      name: { type: 'string', description: 'Agent name' },
+      domain: { type: 'string', description: 'Email domain' },
+      role: { type: 'string', description: 'Agent role' },
+    }, ['name']),
+    'high',
+    async (args) => apiRequest('POST', '/accounts', args, true),
+  );
+
+  defTool('agenticmail_delete_agent', 'Delete Agent',
+    'Delete an agent account permanently.',
+    p({
+      name: { type: 'string', description: 'Agent name to delete' },
+      reason: { type: 'string', description: 'Reason for deletion' },
+    }, ['name']),
+    'critical',
+    async (args) => apiRequest('DELETE', `/accounts/${encodeURIComponent(String(args.name))}`, { reason: args.reason }, true),
+  );
+
+  defTool('agenticmail_cleanup', 'Cleanup Agents',
+    'List or remove inactive agent accounts.',
+    p({
+      action: { type: 'string', description: 'list_inactive, cleanup, or set_persistent' },
+      hours: { type: 'number', description: 'Inactivity threshold (default 24)' },
+      dryRun: { type: 'boolean', description: 'Preview only' },
+      agentId: { type: 'string', description: 'Agent ID (for set_persistent)' },
+      persistent: { type: 'boolean', description: 'Set persistent flag' },
+    }, ['action']),
+    'high',
+    async (args) => apiRequest('POST', '/accounts/cleanup', args, true),
+  );
+
+  defTool('agenticmail_status', 'Server Status',
+    'Check AgenticMail server health.',
+    p({}),
+    'low',
+    async () => apiRequest('GET', '/status'),
+  );
+
+  // ─── Gateway & Setup ──────────────────────────────────────────────
+
+  defTool('agenticmail_gateway_status', 'Gateway Status',
+    'Check email gateway status (relay, domain, or none).',
+    p({}),
+    'low',
+    async () => apiRequest('GET', '/gateway/status', undefined, true),
+  );
+
+  defTool('agenticmail_setup_relay', 'Setup Relay',
+    'Configure Gmail/Outlook relay for internet email.',
+    p({
+      provider: { type: 'string', description: 'gmail, outlook, or custom' },
+      email: { type: 'string', description: 'Your real email' },
+      password: { type: 'string', description: 'App password' },
+    }, ['provider', 'email', 'password']),
+    'critical',
+    async (args) => apiRequest('POST', '/gateway/setup-relay', args, true),
+  );
+
+  defTool('agenticmail_setup_domain', 'Setup Domain',
+    'Set up custom domain via Cloudflare for internet email.',
+    p({
+      cloudflareToken: { type: 'string', description: 'Cloudflare API token' },
+      cloudflareAccountId: { type: 'string', description: 'Cloudflare account ID' },
+      domain: { type: 'string', description: 'Domain to use' },
+    }, ['cloudflareToken', 'cloudflareAccountId']),
+    'critical',
+    async (args) => apiRequest('POST', '/gateway/setup-domain', args, true),
+  );
+
+  defTool('agenticmail_import_relay', 'Import Relay Email',
+    'Import an email from connected Gmail/Outlook into local inbox.',
+    p({ uid: { type: 'number', description: 'Relay UID to import' } }, ['uid']),
+    'low',
+    async (args) => apiRequest('POST', '/mail/import-relay', { uid: args.uid }),
+  );
+
+  defTool('agenticmail_test_email', 'Test Email',
+    'Send a test email to verify configuration.',
+    p({ to: { type: 'string', description: 'Test recipient' } }, ['to']),
+    'medium',
+    async (args) => apiRequest('POST', '/gateway/test', { to: args.to }, true),
+  );
+
+  defTool('agenticmail_deletion_reports', 'Deletion Reports',
+    'List or get agent deletion reports.',
+    p({ id: { type: 'string', description: 'Report ID (omit to list all)' } }),
+    'low',
+    async (args) => apiRequest('GET', args.id ? `/accounts/deletion-reports/${args.id}` : '/accounts/deletion-reports', undefined, true),
+  );
+
+  defTool('agenticmail_setup_guide', 'Setup Guide',
+    'Get comparison of email setup modes.',
+    p({}),
+    'low',
+    async () => apiRequest('GET', '/gateway/setup-guide', undefined, true),
+  );
+
+  defTool('agenticmail_setup_gmail_alias', 'Gmail Alias Setup',
+    'Get instructions for adding agent email as Gmail Send-As alias.',
+    p({
+      agentEmail: { type: 'string', description: 'Agent email to add as alias' },
+      agentDisplayName: { type: 'string', description: 'Display name for alias' },
+    }, ['agentEmail']),
+    'low',
+    async (args) => apiRequest('POST', '/gateway/gmail-alias', args, true),
+  );
+
+  defTool('agenticmail_purchase_domain', 'Search Domains',
+    'Search for available domains via Cloudflare.',
+    p({
+      keywords: { type: 'array', description: 'Search keywords' },
+      tld: { type: 'string', description: 'Preferred TLD' },
+    }, ['keywords']),
+    'low',
+    async (args) => apiRequest('POST', '/gateway/search-domains', args, true),
+  );
+
+  return tools;
+}