@agenticmail/enterprise 0.5.49 → 0.5.51

package/src/agenticmail/index.ts

@@ -0,0 +1,32 @@
+/**
+ * AgenticMail Enterprise
+ *
+ * Embedded email & communication system for enterprise agents.
+ * No separate server — agents use their org email via OAuth.
+ *
+ * Usage:
+ *   import { AgenticMailManager } from './agenticmail/index.js';
+ *   const mail = new AgenticMailManager({ db: engineDb });
+ *   await mail.registerAgent({ agentId, email, accessToken, provider: 'microsoft', ... });
+ *   const provider = mail.getProvider(agentId);
+ *   await provider.send({ to: 'user@company.com', subject: 'Hello', body: '...' });
+ */
+
+export { AgenticMailManager } from './manager.js';
+export type { AgenticMailManagerOptions } from './manager.js';
+export { createEmailProvider } from './providers/index.js';
+export { MicrosoftEmailProvider } from './providers/microsoft.js';
+export { GoogleEmailProvider } from './providers/google.js';
+export type {
+  IEmailProvider,
+  AgentEmailIdentity,
+  EmailProvider,
+  EmailMessage,
+  EmailEnvelope,
+  EmailFolder,
+  SendEmailOptions,
+  SearchCriteria,
+  EmailAttachment,
+  AgentMessage,
+  AgentTask,
+} from './types.js';

package/src/agenticmail/manager.ts

@@ -0,0 +1,253 @@
+/**
+ * AgenticMail Enterprise Manager
+ *
+ * Central orchestrator that connects agents to their org email.
+ * Manages email provider instances per agent and provides the
+ * tool handler interface for the enterprise agent system.
+ *
+ * Architecture:
+ *   Agent (from org directory via OAuth)
+ *     → AgenticMailManager.getProvider(agentId)
+ *       → IEmailProvider (Microsoft Graph / Gmail API)
+ *         → Org's email system
+ *
+ * No separate AgenticMail server. No API keys. No relay setup.
+ * The agent IS the org identity.
+ */
+
+import type { EngineDatabase } from '../engine/db-adapter.js';
+import type {
+  IEmailProvider, AgentEmailIdentity, EmailProvider,
+  AgentMessage, AgentTask,
+} from './types.js';
+import { createEmailProvider } from './providers/index.js';
+
+export interface AgenticMailManagerOptions {
+  db?: EngineDatabase;
+}
+
+export class AgenticMailManager {
+  private providers = new Map<string, IEmailProvider>();
+  private identities = new Map<string, AgentEmailIdentity>();
+  private db?: EngineDatabase;
+
+  constructor(opts?: AgenticMailManagerOptions) {
+    this.db = opts?.db;
+  }
+
+  setDb(db: EngineDatabase): void {
+    this.db = db;
+  }
+
+  // ─── Agent Registration ─────────────────────────────
+
+  /**
+   * Register an agent's email identity from the org's OAuth/SSO.
+   * Called when an agent is created or when its OAuth token is refreshed.
+   */
+  async registerAgent(identity: AgentEmailIdentity): Promise<void> {
+    this.identities.set(identity.agentId, identity);
+
+    // Create and connect the email provider
+    const provider = createEmailProvider(identity.provider);
+    await provider.connect(identity);
+    this.providers.set(identity.agentId, provider);
+  }
+
+  /**
+   * Unregister an agent (on deletion or token revocation).
+   */
+  async unregisterAgent(agentId: string): Promise<void> {
+    const provider = this.providers.get(agentId);
+    if (provider) {
+      await provider.disconnect().catch(() => {});
+      this.providers.delete(agentId);
+    }
+    this.identities.delete(agentId);
+  }
+
+  /**
+   * Get the email provider for an agent.
+   * Throws if agent is not registered.
+   */
+  getProvider(agentId: string): IEmailProvider {
+    const provider = this.providers.get(agentId);
+    if (!provider) throw new Error(`Agent ${agentId} has no email provider registered. Ensure the agent has been connected via org OAuth.`);
+    return provider;
+  }
+
+  /**
+   * Get the email identity for an agent.
+   */
+  getIdentity(agentId: string): AgentEmailIdentity | undefined {
+    return this.identities.get(agentId);
+  }
+
+  /**
+   * Check if an agent has email access.
+   */
+  hasEmail(agentId: string): boolean {
+    return this.providers.has(agentId);
+  }
+
+  // ─── Inter-Agent Messaging ──────────────────────────
+  // These use the enterprise DB directly, not email.
+  // Agents in the same org can message each other without email.
+
+  /**
+   * Send a message from one agent to another (internal, no email).
+   */
+  async sendAgentMessage(from: string, to: string, subject: string, body: string, priority: 'normal' | 'high' | 'urgent' = 'normal'): Promise<AgentMessage> {
+    const msg: AgentMessage = {
+      id: crypto.randomUUID(),
+      from,
+      to,
+      subject,
+      body,
+      priority,
+      createdAt: new Date().toISOString(),
+      read: false,
+    };
+
+    if (this.db) {
+      await this.db.execute(
+        `INSERT INTO agent_messages (id, from_agent, to_agent, subject, body, priority, created_at, read)
+         VALUES (?, ?, ?, ?, ?, ?, ?, 0)`,
+        [msg.id, msg.from, msg.to, msg.subject, msg.body, msg.priority, msg.createdAt]
+      ).catch(() => {});
+    }
+
+    return msg;
+  }
+
+  /**
+   * Get unread messages for an agent.
+   */
+  async getAgentMessages(agentId: string, opts?: { unreadOnly?: boolean; limit?: number }): Promise<AgentMessage[]> {
+    if (!this.db) return [];
+    try {
+      let sql = 'SELECT * FROM agent_messages WHERE to_agent = ?';
+      const params: any[] = [agentId];
+      if (opts?.unreadOnly) {
+        sql += ' AND read = 0';
+      }
+      sql += ' ORDER BY created_at DESC LIMIT ?';
+      params.push(opts?.limit || 20);
+
+      const rows = await this.db.query<any>(sql, params);
+      return rows.map((r: any) => ({
+        id: r.id,
+        from: r.from_agent,
+        to: r.to_agent,
+        subject: r.subject,
+        body: r.body,
+        priority: r.priority,
+        createdAt: r.created_at,
+        read: !!r.read,
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  // ─── Task Management ────────────────────────────────
+  // Tasks also use the enterprise DB directly.
+
+  /**
+   * Create a task assigned to an agent.
+   */
+  async createTask(assigner: string, assignee: string, title: string, description?: string, priority: 'low' | 'normal' | 'high' | 'urgent' = 'normal'): Promise<AgentTask> {
+    const now = new Date().toISOString();
+    const task: AgentTask = {
+      id: crypto.randomUUID(),
+      assigner,
+      assignee,
+      title,
+      description,
+      status: 'pending',
+      priority,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    if (this.db) {
+      await this.db.execute(
+        `INSERT INTO agent_tasks (id, assigner, assignee, title, description, status, priority, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [task.id, task.assigner, task.assignee, task.title, task.description || null, task.status, task.priority, task.createdAt, task.updatedAt]
+      ).catch(() => {});
+    }
+
+    return task;
+  }
+
+  /**
+   * Get tasks for an agent.
+   */
+  async getAgentTasks(agentId: string, direction: 'incoming' | 'outgoing' = 'incoming', status?: string): Promise<AgentTask[]> {
+    if (!this.db) return [];
+    try {
+      const col = direction === 'incoming' ? 'assignee' : 'assigner';
+      let sql = `SELECT * FROM agent_tasks WHERE ${col} = ?`;
+      const params: any[] = [agentId];
+      if (status) {
+        sql += ' AND status = ?';
+        params.push(status);
+      }
+      sql += ' ORDER BY created_at DESC LIMIT 50';
+
+      const rows = await this.db.query<any>(sql, params);
+      return rows.map((r: any) => ({
+        id: r.id,
+        assigner: r.assigner,
+        assignee: r.assignee,
+        title: r.title,
+        description: r.description,
+        status: r.status,
+        priority: r.priority,
+        result: r.result ? JSON.parse(r.result) : undefined,
+        createdAt: r.created_at,
+        updatedAt: r.updated_at,
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Update task status.
+   */
+  async updateTask(taskId: string, updates: { status?: string; result?: any }): Promise<void> {
+    if (!this.db) return;
+    const sets: string[] = ['updated_at = ?'];
+    const params: any[] = [new Date().toISOString()];
+    if (updates.status) { sets.push('status = ?'); params.push(updates.status); }
+    if (updates.result !== undefined) { sets.push('result = ?'); params.push(JSON.stringify(updates.result)); }
+    params.push(taskId);
+    await this.db.execute(`UPDATE agent_tasks SET ${sets.join(', ')} WHERE id = ?`, params).catch(() => {});
+  }
+
+  // ─── Lifecycle ──────────────────────────────────────
+
+  /**
+   * Get all registered agents and their email status.
+   */
+  getRegisteredAgents(): { agentId: string; email: string; provider: EmailProvider }[] {
+    const agents: { agentId: string; email: string; provider: EmailProvider }[] = [];
+    for (const [agentId, identity] of this.identities) {
+      agents.push({ agentId, email: identity.email, provider: identity.provider });
+    }
+    return agents;
+  }
+
+  /**
+   * Shutdown — disconnect all providers.
+   */
+  async shutdown(): Promise<void> {
+    for (const provider of this.providers.values()) {
+      await provider.disconnect().catch(() => {});
+    }
+    this.providers.clear();
+    this.identities.clear();
+  }
+}

package/src/agenticmail/providers/google.ts

@@ -0,0 +1,331 @@
+/**
+ * Gmail API Email Provider
+ *
+ * Implements IEmailProvider using Gmail REST API.
+ * Agent authenticates via org's Google Workspace OAuth.
+ * Email address comes from the org directory.
+ */
+
+import type {
+  IEmailProvider, AgentEmailIdentity, EmailProvider,
+  EmailMessage, EmailEnvelope, EmailFolder,
+  SendEmailOptions, SearchCriteria,
+} from '../types.js';
+
+const GMAIL_BASE = 'https://gmail.googleapis.com/gmail/v1';
+
+export class GoogleEmailProvider implements IEmailProvider {
+  readonly provider: EmailProvider = 'google';
+  private identity: AgentEmailIdentity | null = null;
+  private userId = 'me';
+
+  private get token(): string {
+    if (!this.identity) throw new Error('Not connected');
+    return this.identity.accessToken;
+  }
+
+  private async refreshIfNeeded(): Promise<void> {
+    if (this.identity?.refreshToken) {
+      this.identity.accessToken = await this.identity.refreshToken();
+    }
+  }
+
+  private async gmailFetch(path: string, opts?: RequestInit): Promise<any> {
+    await this.refreshIfNeeded();
+    const res = await fetch(`${GMAIL_BASE}/users/${this.userId}${path}`, {
+      ...opts,
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        'Content-Type': 'application/json',
+        ...opts?.headers,
+      },
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`Gmail API ${res.status}: ${text}`);
+    }
+    if (res.status === 204) return null;
+    return res.json();
+  }
+
+  // ─── Connection ─────────────────────────────────────
+
+  async connect(identity: AgentEmailIdentity): Promise<void> {
+    this.identity = identity;
+    // Validate token
+    await this.gmailFetch('/profile');
+  }
+
+  async disconnect(): Promise<void> {
+    this.identity = null;
+  }
+
+  // ─── List / Read ────────────────────────────────────
+
+  async listMessages(folder: string, opts?: { limit?: number; offset?: number }): Promise<EmailEnvelope[]> {
+    const labelId = this.resolveLabelId(folder);
+    const maxResults = opts?.limit || 20;
+    const q = labelId === 'INBOX' ? '' : '';
+    const data = await this.gmailFetch(`/messages?labelIds=${labelId}&maxResults=${maxResults}${q ? '&q=' + encodeURIComponent(q) : ''}`);
+
+    if (!data.messages?.length) return [];
+
+    // Batch fetch message metadata
+    const envelopes: EmailEnvelope[] = [];
+    for (const msg of data.messages) {
+      try {
+        const detail = await this.gmailFetch(`/messages/${msg.id}?format=metadata&metadataHeaders=From&metadataHeaders=To&metadataHeaders=Subject&metadataHeaders=Date`);
+        envelopes.push(this.metadataToEnvelope(detail));
+      } catch { /* skip individual errors */ }
+    }
+    return envelopes;
+  }
+
+  async readMessage(uid: string): Promise<EmailMessage> {
+    const data = await this.gmailFetch(`/messages/${uid}?format=full`);
+    return this.fullToMessage(data);
+  }
+
+  async searchMessages(criteria: SearchCriteria): Promise<EmailEnvelope[]> {
+    const parts: string[] = [];
+    if (criteria.from) parts.push(`from:${criteria.from}`);
+    if (criteria.to) parts.push(`to:${criteria.to}`);
+    if (criteria.subject) parts.push(`subject:${criteria.subject}`);
+    if (criteria.text) parts.push(criteria.text);
+    if (criteria.since) parts.push(`after:${criteria.since.split('T')[0]}`);
+    if (criteria.before) parts.push(`before:${criteria.before.split('T')[0]}`);
+    if (criteria.seen === true) parts.push('is:read');
+    if (criteria.seen === false) parts.push('is:unread');
+
+    const q = parts.join(' ');
+    const data = await this.gmailFetch(`/messages?q=${encodeURIComponent(q)}&maxResults=50`);
+
+    if (!data.messages?.length) return [];
+
+    const envelopes: EmailEnvelope[] = [];
+    for (const msg of data.messages.slice(0, 20)) {
+      try {
+        const detail = await this.gmailFetch(`/messages/${msg.id}?format=metadata&metadataHeaders=From&metadataHeaders=To&metadataHeaders=Subject&metadataHeaders=Date`);
+        envelopes.push(this.metadataToEnvelope(detail));
+      } catch { /* skip */ }
+    }
+    return envelopes;
+  }
+
+  async listFolders(): Promise<EmailFolder[]> {
+    const data = await this.gmailFetch('/labels');
+    return (data.labels || []).map((l: any) => ({
+      name: l.name,
+      path: l.id,
+      unread: l.messagesUnread || 0,
+      total: l.messagesTotal || 0,
+    }));
+  }
+
+  async createFolder(name: string): Promise<void> {
+    await this.gmailFetch('/labels', {
+      method: 'POST',
+      body: JSON.stringify({ name, labelListVisibility: 'labelShow', messageListVisibility: 'show' }),
+    });
+  }
+
+  // ─── Send ───────────────────────────────────────────
+
+  async send(options: SendEmailOptions): Promise<{ messageId: string }> {
+    const raw = this.buildRawEmail(options);
+    const data = await this.gmailFetch('/messages/send', {
+      method: 'POST',
+      body: JSON.stringify({ raw }),
+    });
+    return { messageId: data.id };
+  }
+
+  async reply(uid: string, body: string, replyAll = false): Promise<{ messageId: string }> {
+    const original = await this.readMessage(uid);
+    const to = replyAll
+      ? [original.from.email, ...(original.to || []).map(t => t.email), ...(original.cc || []).map(c => c.email)].filter(e => e !== this.identity?.email).join(', ')
+      : original.from.email;
+
+    return this.send({
+      to,
+      subject: original.subject.startsWith('Re:') ? original.subject : `Re: ${original.subject}`,
+      body,
+      inReplyTo: original.messageId,
+      references: original.references ? [...original.references, original.messageId!] : [original.messageId!],
+    });
+  }
+
+  async forward(uid: string, to: string, body?: string): Promise<{ messageId: string }> {
+    const original = await this.readMessage(uid);
+    return this.send({
+      to,
+      subject: `Fwd: ${original.subject}`,
+      body: (body ? body + '\n\n' : '') + `---------- Forwarded message ----------\nFrom: ${original.from.email}\nDate: ${original.date}\nSubject: ${original.subject}\n\n${original.body}`,
+    });
+  }
+
+  // ─── Organize ───────────────────────────────────────
+
+  async moveMessage(uid: string, toFolder: string, fromFolder?: string): Promise<void> {
+    const addLabel = this.resolveLabelId(toFolder);
+    const removeLabel = fromFolder ? this.resolveLabelId(fromFolder) : 'INBOX';
+    await this.gmailFetch(`/messages/${uid}/modify`, {
+      method: 'POST',
+      body: JSON.stringify({ addLabelIds: [addLabel], removeLabelIds: [removeLabel] }),
+    });
+  }
+
+  async deleteMessage(uid: string): Promise<void> {
+    await this.gmailFetch(`/messages/${uid}/trash`, { method: 'POST' });
+  }
+
+  async markRead(uid: string): Promise<void> {
+    await this.gmailFetch(`/messages/${uid}/modify`, {
+      method: 'POST',
+      body: JSON.stringify({ removeLabelIds: ['UNREAD'] }),
+    });
+  }
+
+  async markUnread(uid: string): Promise<void> {
+    await this.gmailFetch(`/messages/${uid}/modify`, {
+      method: 'POST',
+      body: JSON.stringify({ addLabelIds: ['UNREAD'] }),
+    });
+  }
+
+  async flagMessage(uid: string): Promise<void> {
+    await this.gmailFetch(`/messages/${uid}/modify`, {
+      method: 'POST',
+      body: JSON.stringify({ addLabelIds: ['STARRED'] }),
+    });
+  }
+
+  async unflagMessage(uid: string): Promise<void> {
+    await this.gmailFetch(`/messages/${uid}/modify`, {
+      method: 'POST',
+      body: JSON.stringify({ removeLabelIds: ['STARRED'] }),
+    });
+  }
+
+  // ─── Batch ──────────────────────────────────────────
+
+  async batchMarkRead(uids: string[]): Promise<void> {
+    await this.gmailFetch('/messages/batchModify', {
+      method: 'POST',
+      body: JSON.stringify({ ids: uids, removeLabelIds: ['UNREAD'] }),
+    });
+  }
+
+  async batchMarkUnread(uids: string[]): Promise<void> {
+    await this.gmailFetch('/messages/batchModify', {
+      method: 'POST',
+      body: JSON.stringify({ ids: uids, addLabelIds: ['UNREAD'] }),
+    });
+  }
+
+  async batchMove(uids: string[], toFolder: string, fromFolder?: string): Promise<void> {
+    const addLabel = this.resolveLabelId(toFolder);
+    const removeLabel = fromFolder ? this.resolveLabelId(fromFolder) : 'INBOX';
+    await this.gmailFetch('/messages/batchModify', {
+      method: 'POST',
+      body: JSON.stringify({ ids: uids, addLabelIds: [addLabel], removeLabelIds: [removeLabel] }),
+    });
+  }
+
+  async batchDelete(uids: string[]): Promise<void> {
+    await Promise.all(uids.map(uid => this.deleteMessage(uid)));
+  }
+
+  // ─── Helpers ────────────────────────────────────────
+
+  private resolveLabelId(folder: string): string {
+    const map: Record<string, string> = {
+      INBOX: 'INBOX', inbox: 'INBOX',
+      Sent: 'SENT', sent: 'SENT',
+      Drafts: 'DRAFT', drafts: 'DRAFT',
+      Trash: 'TRASH', trash: 'TRASH',
+      Spam: 'SPAM', spam: 'SPAM', Junk: 'SPAM', junk: 'SPAM',
+      Starred: 'STARRED', starred: 'STARRED',
+      Important: 'IMPORTANT', important: 'IMPORTANT',
+    };
+    return map[folder] || folder;
+  }
+
+  private buildRawEmail(options: SendEmailOptions): string {
+    const lines = [
+      `To: ${options.to}`,
+      `Subject: ${options.subject}`,
+      `Content-Type: text/plain; charset=utf-8`,
+    ];
+    if (options.cc) lines.splice(1, 0, `Cc: ${options.cc}`);
+    if (options.inReplyTo) lines.push(`In-Reply-To: ${options.inReplyTo}`);
+    if (options.references?.length) lines.push(`References: ${options.references.join(' ')}`);
+    lines.push('', options.body);
+
+    const raw = lines.join('\r\n');
+    // Base64url encode
+    return btoa(unescape(encodeURIComponent(raw)))
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '');
+  }
+
+  private getHeader(msg: any, name: string): string {
+    const headers = msg.payload?.headers || [];
+    const h = headers.find((h: any) => h.name.toLowerCase() === name.toLowerCase());
+    return h?.value || '';
+  }
+
+  private metadataToEnvelope(msg: any): EmailEnvelope {
+    const from = this.getHeader(msg, 'From');
+    const fromMatch = from.match(/^(.*?)\s*<(.+?)>$/) || [null, '', from];
+    return {
+      uid: msg.id,
+      from: { name: fromMatch[1]?.replace(/"/g, '').trim() || undefined, email: fromMatch[2] || from },
+      to: [{ email: this.getHeader(msg, 'To') }],
+      subject: this.getHeader(msg, 'Subject'),
+      date: this.getHeader(msg, 'Date'),
+      read: !(msg.labelIds || []).includes('UNREAD'),
+      flagged: (msg.labelIds || []).includes('STARRED'),
+      hasAttachments: false,
+      preview: msg.snippet || '',
+    };
+  }
+
+  private fullToMessage(msg: any): EmailMessage {
+    const from = this.getHeader(msg, 'From');
+    const fromMatch = from.match(/^(.*?)\s*<(.+?)>$/) || [null, '', from];
+
+    // Extract body from parts
+    let body = '';
+    let html: string | undefined;
+    const extractBody = (payload: any) => {
+      if (payload.mimeType === 'text/plain' && payload.body?.data) {
+        body = Buffer.from(payload.body.data, 'base64url').toString('utf-8');
+      }
+      if (payload.mimeType === 'text/html' && payload.body?.data) {
+        html = Buffer.from(payload.body.data, 'base64url').toString('utf-8');
+      }
+      if (payload.parts) payload.parts.forEach(extractBody);
+    };
+    if (msg.payload) extractBody(msg.payload);
+
+    return {
+      uid: msg.id,
+      from: { name: fromMatch[1]?.replace(/"/g, '').trim() || undefined, email: fromMatch[2] || from },
+      to: [{ email: this.getHeader(msg, 'To') }],
+      cc: this.getHeader(msg, 'Cc') ? [{ email: this.getHeader(msg, 'Cc') }] : undefined,
+      subject: this.getHeader(msg, 'Subject'),
+      body,
+      html,
+      date: this.getHeader(msg, 'Date'),
+      read: !(msg.labelIds || []).includes('UNREAD'),
+      flagged: (msg.labelIds || []).includes('STARRED'),
+      folder: (msg.labelIds || []).includes('INBOX') ? 'inbox' : 'other',
+      messageId: this.getHeader(msg, 'Message-ID'),
+      inReplyTo: this.getHeader(msg, 'In-Reply-To') || undefined,
+      references: this.getHeader(msg, 'References') ? this.getHeader(msg, 'References').split(/\s+/) : undefined,
+      attachments: [],
+    };
+  }
+}

package/src/agenticmail/providers/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Email Provider Factory
+ *
+ * Creates the right email provider based on the org's identity provider.
+ * - Microsoft 365 / Azure AD → Microsoft Graph API
+ * - Google Workspace → Gmail API
+ * - Generic IMAP/SMTP → IMAP provider (future)
+ */
+
+export { MicrosoftEmailProvider } from './microsoft.js';
+export { GoogleEmailProvider } from './google.js';
+
+import type { IEmailProvider, EmailProvider } from '../types.js';
+import { MicrosoftEmailProvider } from './microsoft.js';
+import { GoogleEmailProvider } from './google.js';
+
+export function createEmailProvider(provider: EmailProvider): IEmailProvider {
+  switch (provider) {
+    case 'microsoft': return new MicrosoftEmailProvider();
+    case 'google': return new GoogleEmailProvider();
+    case 'imap':
+      throw new Error('Generic IMAP provider not yet implemented — use Microsoft or Google');
+    default:
+      throw new Error(`Unknown email provider: ${provider}`);
+  }
+}