@agenticmail/enterprise 0.5.50 → 0.5.52

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

@@ -0,0 +1,459 @@
+/**
+ * AgenticMail Agent Tools — Enterprise Native
+ *
+ * These tools give enterprise agents email capabilities by calling
+ * the org's email provider (Microsoft Graph / Gmail API) directly.
+ * No separate AgenticMail server needed — agents authenticate via
+ * the org's OAuth/SSO identity.
+ *
+ * Architecture:
+ *   Agent tool call
+ *     → AgenticMailManager.getProvider(agentId)
+ *       → IEmailProvider (MS Graph / Gmail / IMAP)
+ *         → Org mailbox
+ */
+
+import type { AnyAgentTool, ToolCreationOptions, ToolParameterSchema } from '../types.js';
+import { jsonResult, errorResult } from '../common.js';
+import type { IEmailProvider, SendEmailOptions, SearchCriteria, AgentMessage, AgentTask } from '../../agenticmail/types.js';
+
+/** Manager interface — we only need getProvider() */
+export interface AgenticMailManagerRef {
+  getProvider(agentId: string): IEmailProvider;
+  getIdentity?(agentId: string): { email: string; name: string } | undefined;
+  /** Inter-agent messaging (if available) */
+  sendAgentMessage?(msg: Omit<AgentMessage, 'id' | 'createdAt' | 'read'>): Promise<AgentMessage>;
+  listAgentMessages?(agentId: string): Promise<AgentMessage[]>;
+  /** Task management (if available) */
+  createTask?(task: Omit<AgentTask, 'id' | 'createdAt' | 'updatedAt'>): Promise<AgentTask>;
+  listTasks?(agentId: string, direction?: 'incoming' | 'outgoing'): Promise<AgentTask[]>;
+  claimTask?(taskId: string): Promise<AgentTask>;
+  completeTask?(taskId: string, result: any): Promise<AgentTask>;
+}
+
+export interface AgenticMailToolsConfig {
+  /** The AgenticMailManager instance */
+  manager: AgenticMailManagerRef;
+  /** The agent ID these tools are for */
+  agentId: string;
+}
+
+/**
+ * Create all AgenticMail tools backed by the org's email provider.
+ * Tools operate on the agent's mailbox via OAuth — no API keys needed.
+ */
+export function createAgenticMailTools(
+  config: AgenticMailToolsConfig,
+  options?: ToolCreationOptions,
+): AnyAgentTool[] {
+  const { manager, agentId } = config;
+  const tools: AnyAgentTool[] = [];
+
+  // ─── Helpers ──────────────────────────────────────────────────────
+
+  function getProvider(): IEmailProvider {
+    return manager.getProvider(agentId);
+  }
+
+  function p(props: Record<string, any>, required?: string[]): ToolParameterSchema {
+    return { type: 'object', properties: props, required };
+  }
+
+  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 ?? { success: true });
+        } catch (err: any) {
+          return errorResult(err.message || String(err));
+        }
+      },
+    });
+  }
+
+  // ─── Email Core ───────────────────────────────────────────────────
+
+  defTool('agenticmail_send', 'Send Email',
+    'Send an email from your org mailbox.',
+    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' },
+      bcc: { type: 'string', description: 'BCC recipients' },
+      replyTo: { type: 'string', description: 'Reply-to address' },
+      inReplyTo: { type: 'string', description: 'Message-ID to reply to' },
+      references: { type: 'array', description: 'Message-IDs for threading' },
+    }, ['to', 'subject']),
+    'high',
+    async (args) => {
+      const provider = getProvider();
+      const opts: SendEmailOptions = {
+        to: String(args.to),
+        subject: String(args.subject),
+        body: String(args.text || ''),
+        html: args.html ? String(args.html) : undefined,
+        cc: args.cc ? String(args.cc) : undefined,
+        bcc: args.bcc ? String(args.bcc) : undefined,
+        replyTo: args.replyTo ? String(args.replyTo) : undefined,
+        inReplyTo: args.inReplyTo ? String(args.inReplyTo) : undefined,
+        references: args.references as string[] | undefined,
+      };
+      return provider.send(opts);
+    },
+  );
+
+  defTool('agenticmail_reply', 'Reply to Email',
+    'Reply to an email by UID.',
+    p({
+      uid: { type: 'string', 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) => {
+      const provider = getProvider();
+      return provider.reply(String(args.uid), String(args.text), !!args.replyAll);
+    },
+  );
+
+  defTool('agenticmail_forward', 'Forward Email',
+    'Forward an email to another recipient.',
+    p({
+      uid: { type: 'string', description: 'Email UID to forward' },
+      to: { type: 'string', description: 'Recipient to forward to' },
+      text: { type: 'string', description: 'Additional message' },
+    }, ['uid', 'to']),
+    'high',
+    async (args) => {
+      const provider = getProvider();
+      return provider.forward(String(args.uid), String(args.to), args.text ? String(args.text) : undefined);
+    },
+  );
+
+  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 provider = getProvider();
+      return provider.listMessages('INBOX', {
+        limit: args.limit ? Number(args.limit) : 20,
+        offset: args.offset ? Number(args.offset) : 0,
+      });
+    },
+  );
+
+  defTool('agenticmail_read', 'Read Email',
+    'Read a specific email by UID.',
+    p({
+      uid: { type: 'string', description: 'Email UID' },
+      folder: { type: 'string', description: 'Folder (default INBOX)' },
+    }, ['uid']),
+    'low',
+    async (args) => {
+      const provider = getProvider();
+      return provider.readMessage(String(args.uid), args.folder ? String(args.folder) : undefined);
+    },
+  );
+
+  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' },
+    }),
+    'low',
+    async (args) => {
+      const provider = getProvider();
+      const criteria: SearchCriteria = {};
+      if (args.from) criteria.from = String(args.from);
+      if (args.to) criteria.to = String(args.to);
+      if (args.subject) criteria.subject = String(args.subject);
+      if (args.text) criteria.text = String(args.text);
+      if (args.since) criteria.since = String(args.since);
+      if (args.before) criteria.before = String(args.before);
+      if (args.seen !== undefined) criteria.seen = !!args.seen;
+      return provider.searchMessages(criteria);
+    },
+  );
+
+  defTool('agenticmail_delete', 'Delete Email',
+    'Delete an email by UID.',
+    p({
+      uid: { type: 'string', description: 'Email UID' },
+      folder: { type: 'string', description: 'Folder (default INBOX)' },
+    }, ['uid']),
+    'medium',
+    async (args) => {
+      const provider = getProvider();
+      await provider.deleteMessage(String(args.uid), args.folder ? String(args.folder) : undefined);
+      return { success: true };
+    },
+  );
+
+  defTool('agenticmail_move', 'Move Email',
+    'Move an email to another folder.',
+    p({
+      uid: { type: 'string', description: 'Email UID' },
+      to: { type: 'string', description: 'Destination folder' },
+      from: { type: 'string', description: 'Source folder (default INBOX)' },
+    }, ['uid', 'to']),
+    'low',
+    async (args) => {
+      const provider = getProvider();
+      await provider.moveMessage(String(args.uid), String(args.to), args.from ? String(args.from) : undefined);
+      return { success: true };
+    },
+  );
+
+  defTool('agenticmail_mark_read', 'Mark Read',
+    'Mark an email as read.',
+    p({ uid: { type: 'string', description: 'Email UID' } }, ['uid']),
+    'low',
+    async (args) => {
+      const provider = getProvider();
+      await provider.markRead(String(args.uid));
+      return { success: true };
+    },
+  );
+
+  defTool('agenticmail_mark_unread', 'Mark Unread',
+    'Mark an email as unread.',
+    p({ uid: { type: 'string', description: 'Email UID' } }, ['uid']),
+    'low',
+    async (args) => {
+      const provider = getProvider();
+      await provider.markUnread(String(args.uid));
+      return { success: true };
+    },
+  );
+
+  defTool('agenticmail_folders', 'List Folders',
+    'List all mail folders.',
+    p({}),
+    'low',
+    async () => {
+      const provider = getProvider();
+      return provider.listFolders();
+    },
+  );
+
+  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 provider = getProvider();
+      return provider.listMessages(String(args.folder), {
+        limit: args.limit ? Number(args.limit) : 20,
+        offset: args.offset ? Number(args.offset) : 0,
+      });
+    },
+  );
+
+  defTool('agenticmail_create_folder', 'Create Folder',
+    'Create a new mail folder.',
+    p({ name: { type: 'string', description: 'Folder name' } }, ['name']),
+    'low',
+    async (args) => {
+      const provider = getProvider();
+      await provider.createFolder(String(args.name));
+      return { success: true };
+    },
+  );
+
+  // ─── 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) => {
+      const provider = getProvider();
+      const uids = (args.uids as string[]).map(String);
+      const folder = args.folder ? String(args.folder) : undefined;
+      const results = await Promise.all(uids.map(uid => provider.readMessage(uid, folder).catch(err => ({ uid, error: err.message }))));
+      return results;
+    },
+  );
+
+  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) => {
+      const provider = getProvider();
+      const uids = (args.uids as string[]).map(String);
+      const folder = args.folder ? String(args.folder) : undefined;
+      await provider.batchDelete(uids, folder);
+      return { success: true, count: uids.length };
+    },
+  );
+
+  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) => {
+      const provider = getProvider();
+      const uids = (args.uids as string[]).map(String);
+      await provider.batchMove(uids, String(args.to), args.from ? String(args.from) : undefined);
+      return { success: true, count: uids.length };
+    },
+  );
+
+  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) => {
+      const provider = getProvider();
+      const uids = (args.uids as string[]).map(String);
+      await provider.batchMarkRead(uids, args.folder ? String(args.folder) : undefined);
+      return { success: true, count: uids.length };
+    },
+  );
+
+  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) => {
+      const provider = getProvider();
+      const uids = (args.uids as string[]).map(String);
+      await provider.batchMarkUnread(uids, args.folder ? String(args.folder) : undefined);
+      return { success: true, count: uids.length };
+    },
+  );
+
+  // ─── Agent Identity ────────────────────────────────────────────────
+
+  defTool('agenticmail_whoami', 'Who Am I',
+    'Get your email identity and account info.',
+    p({}),
+    'low',
+    async () => {
+      const identity = manager.getIdentity?.(agentId);
+      if (!identity) return { agentId, note: 'Identity details not available' };
+      return { agentId, email: identity.email, name: identity.name };
+    },
+  );
+
+  // ─── Inter-Agent Communication ─────────────────────────────────────
+
+  if (manager.sendAgentMessage) {
+    defTool('agenticmail_message_agent', 'Message Agent',
+      'Send a message to another AI agent.',
+      p({
+        agent: { type: 'string', description: 'Recipient agent ID' },
+        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) => {
+        return manager.sendAgentMessage!({
+          from: agentId,
+          to: String(args.agent),
+          subject: String(args.subject),
+          body: String(args.text),
+          priority: (args.priority as any) || 'normal',
+          status: 'pending',
+        });
+      },
+    );
+  }
+
+  if (manager.listAgentMessages) {
+    defTool('agenticmail_check_messages', 'Check Messages',
+      'Check for new messages from other agents.',
+      p({}),
+      'low',
+      async () => {
+        return manager.listAgentMessages!(agentId);
+      },
+    );
+  }
+
+  // ─── Task Management ───────────────────────────────────────────────
+
+  if (manager.listTasks) {
+    defTool('agenticmail_check_tasks', 'Check Tasks',
+      'Check for pending tasks assigned to you.',
+      p({
+        direction: { type: 'string', description: 'incoming or outgoing (default incoming)' },
+      }),
+      'low',
+      async (args) => {
+        return manager.listTasks!(agentId, (args.direction as any) || 'incoming');
+      },
+    );
+  }
+
+  if (manager.claimTask) {
+    defTool('agenticmail_claim_task', 'Claim Task',
+      'Claim a pending task.',
+      p({ id: { type: 'string', description: 'Task ID' } }, ['id']),
+      'low',
+      async (args) => manager.claimTask!(String(args.id)),
+    );
+  }
+
+  if (manager.completeTask) {
+    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) => manager.completeTask!(String(args.id), args.result),
+    );
+  }
+
+  return tools;
+}

package/src/runtime/index.ts

@@ -239,6 +239,7 @@ export class AgentRuntime {
     var tools = opts.tools || createAllTools({
       agentId,
       workspaceDir: process.cwd(),
+      agenticmailManager: this.config.agenticmailManager,
     });
 
     var systemPrompt = opts.systemPrompt || buildDefaultSystemPrompt(agentId);
@@ -281,7 +282,7 @@ export class AgentRuntime {
     var apiKey = this.resolveApiKey(model.provider);
     if (!apiKey) throw new Error(`No API key for provider: ${model.provider}`);
 
-    var tools = createAllTools({ agentId: session.agentId, workspaceDir: process.cwd() });
+    var tools = createAllTools({ agentId: session.agentId, workspaceDir: process.cwd(), agenticmailManager: this.config.agenticmailManager });
 
     var agentConfig: AgentConfig = {
       agentId: session.agentId,
@@ -572,7 +573,7 @@ export class AgentRuntime {
             continue;
           }
 
-          var tools = createAllTools({ agentId: session.agentId, workspaceDir: process.cwd() });
+          var tools = createAllTools({ agentId: session.agentId, workspaceDir: process.cwd(), agenticmailManager: this.config.agenticmailManager });
 
           var agentConfig: AgentConfig = {
             agentId: session.agentId,

package/src/runtime/types.ts

@@ -116,6 +116,8 @@ export interface RuntimeConfig {
   sessionIdleTimeoutMs?: number;
   /** Enable the runtime gateway (HTTP API) */
   gatewayEnabled?: boolean;
+  /** AgenticMail manager for org email access (optional — enables agenticmail_* tools) */
+  agenticmailManager?: import('../agent-tools/tools/agenticmail.js').AgenticMailManagerRef;
   /** Resume active sessions on startup (default: true) */
   resumeOnStartup?: boolean;
   /** Heartbeat interval in ms (default: 30000 = 30s) */