@agenticmail/enterprise 0.5.75 → 0.5.77

package/src/agent-tools/tools/google/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Google Workspace Tools — Index
+ *
+ * All Google Workspace API tools for enterprise agents.
+ * Requires agent to have Google OAuth configured with appropriate scopes.
+ */
+
+export { createGmailTools } from './gmail.js';
+export { createGoogleCalendarTools } from './calendar.js';
+export { createGoogleDriveTools } from './drive.js';
+export { createGoogleSheetsTools } from './sheets.js';
+export { createGoogleDocsTools } from './docs.js';
+export { createGoogleContactsTools } from './contacts.js';
+
+import type { AnyAgentTool, ToolCreationOptions } from '../../types.js';
+import type { TokenProvider } from '../oauth-token-provider.js';
+import { createGmailTools } from './gmail.js';
+import { createGoogleCalendarTools } from './calendar.js';
+import { createGoogleDriveTools } from './drive.js';
+import { createGoogleSheetsTools } from './sheets.js';
+import { createGoogleDocsTools } from './docs.js';
+import { createGoogleContactsTools } from './contacts.js';
+
+export interface GoogleToolsConfig {
+  tokenProvider: TokenProvider;
+}
+
+/**
+ * Create all Google Workspace tools for an agent.
+ * Returns ~30 tools covering Calendar, Drive, Sheets, Docs, and Contacts.
+ */
+/**
+ * Create all Google Workspace tools for an agent.
+ * Returns ~40 tools covering Gmail, Calendar, Drive, Sheets, Docs, and Contacts.
+ */
+export function createAllGoogleTools(config: GoogleToolsConfig, options?: ToolCreationOptions): AnyAgentTool[] {
+  return [
+    ...createGmailTools(config, options),
+    ...createGoogleCalendarTools(config, options),
+    ...createGoogleDriveTools(config, options),
+    ...createGoogleSheetsTools(config, options),
+    ...createGoogleDocsTools(config, options),
+    ...createGoogleContactsTools(config, options),
+  ];
+}

package/src/agent-tools/tools/google/sheets.ts

@@ -0,0 +1,215 @@
+/**
+ * Google Sheets Tools
+ *
+ * Read, write, and manipulate spreadsheets via Google Sheets API v4.
+ */
+
+import type { AnyAgentTool, ToolCreationOptions } from '../../types.js';
+import { jsonResult, errorResult } from '../../common.js';
+import type { GoogleToolsConfig } from './index.js';
+
+const BASE = 'https://sheets.googleapis.com/v4/spreadsheets';
+
+async function sapi(token: string, path: string, opts?: { method?: string; body?: any; query?: Record<string, string> }): Promise<any> {
+  const method = opts?.method || 'GET';
+  const url = new URL(BASE + path);
+  if (opts?.query) for (const [k, v] of Object.entries(opts.query)) { if (v) url.searchParams.set(k, v); }
+  const res = await fetch(url.toString(), {
+    method,
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: opts?.body ? JSON.stringify(opts.body) : undefined,
+  });
+  if (!res.ok) { const err = await res.text(); throw new Error(`Google Sheets API ${res.status}: ${err}`); }
+  if (res.status === 204) return {};
+  return res.json();
+}
+
+export function createGoogleSheetsTools(config: GoogleToolsConfig, _options?: ToolCreationOptions): AnyAgentTool[] {
+  const tp = config.tokenProvider;
+  return [
+    {
+      name: 'google_sheets_get',
+      description: 'Get spreadsheet metadata: title, sheets/tabs, row counts.',
+      category: 'utility' as const,
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          spreadsheetId: { type: 'string', description: 'Spreadsheet ID (required — from the URL)' },
+        },
+        required: ['spreadsheetId'],
+      },
+      async execute(_id: string, params: any) {
+        try {
+          const token = await tp.getAccessToken();
+          const data = await sapi(token, `/${params.spreadsheetId}`, {
+            query: { fields: 'spreadsheetId,properties.title,sheets.properties' },
+          });
+          const sheets = (data.sheets || []).map((s: any) => ({
+            sheetId: s.properties.sheetId, title: s.properties.title,
+            rowCount: s.properties.gridProperties?.rowCount,
+            columnCount: s.properties.gridProperties?.columnCount,
+          }));
+          return jsonResult({ spreadsheetId: data.spreadsheetId, title: data.properties?.title, sheets });
+        } catch (e: any) { return errorResult(e.message); }
+      },
+    },
+    {
+      name: 'google_sheets_read',
+      description: 'Read cell values from a sheet range. Returns a 2D array of values.',
+      category: 'utility' as const,
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          spreadsheetId: { type: 'string', description: 'Spreadsheet ID (required)' },
+          range: { type: 'string', description: 'A1 notation range, e.g. "Sheet1!A1:D10" or "Sheet1" for entire sheet (required)' },
+          majorDimension: { type: 'string', description: '"ROWS" (default) or "COLUMNS"' },
+        },
+        required: ['spreadsheetId', 'range'],
+      },
+      async execute(_id: string, params: any) {
+        try {
+          const token = await tp.getAccessToken();
+          const query: Record<string, string> = {};
+          if (params.majorDimension) query.majorDimension = params.majorDimension;
+          const data = await sapi(token, `/${params.spreadsheetId}/values/${encodeURIComponent(params.range)}`, { query });
+          const values = data.values || [];
+          return jsonResult({
+            range: data.range, majorDimension: data.majorDimension || 'ROWS',
+            values, rowCount: values.length, columnCount: values[0]?.length || 0,
+          });
+        } catch (e: any) { return errorResult(e.message); }
+      },
+    },
+    {
+      name: 'google_sheets_write',
+      description: 'Write values to a sheet range. Provide rows as JSON array of arrays.',
+      category: 'utility' as const,
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          spreadsheetId: { type: 'string', description: 'Spreadsheet ID (required)' },
+          range: { type: 'string', description: 'A1 notation range to write to, e.g. "Sheet1!A1" (required)' },
+          values: { type: 'string', description: 'JSON array of arrays, e.g. [["Name","Score"],["Alice",95],["Bob",87]] (required)' },
+          inputOption: { type: 'string', description: '"RAW" or "USER_ENTERED" (default: "USER_ENTERED" — parses formulas/numbers)' },
+        },
+        required: ['spreadsheetId', 'range', 'values'],
+      },
+      async execute(_id: string, params: any) {
+        try {
+          const token = await tp.getAccessToken();
+          let values: any[][];
+          try { values = JSON.parse(params.values); } catch { return errorResult('Invalid JSON for values — must be array of arrays'); }
+          const data = await sapi(token, `/${params.spreadsheetId}/values/${encodeURIComponent(params.range)}`, {
+            method: 'PUT',
+            query: { valueInputOption: params.inputOption || 'USER_ENTERED' },
+            body: { range: params.range, majorDimension: 'ROWS', values },
+          });
+          return jsonResult({ updated: true, updatedRange: data.updatedRange, updatedRows: data.updatedRows, updatedColumns: data.updatedColumns, updatedCells: data.updatedCells });
+        } catch (e: any) { return errorResult(e.message); }
+      },
+    },
+    {
+      name: 'google_sheets_append',
+      description: 'Append rows to the end of a sheet (after existing data).',
+      category: 'utility' as const,
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          spreadsheetId: { type: 'string', description: 'Spreadsheet ID (required)' },
+          range: { type: 'string', description: 'Sheet range to append to, e.g. "Sheet1" (required)' },
+          values: { type: 'string', description: 'JSON array of arrays to append (required)' },
+          inputOption: { type: 'string', description: '"RAW" or "USER_ENTERED" (default: "USER_ENTERED")' },
+        },
+        required: ['spreadsheetId', 'range', 'values'],
+      },
+      async execute(_id: string, params: any) {
+        try {
+          const token = await tp.getAccessToken();
+          let values: any[][];
+          try { values = JSON.parse(params.values); } catch { return errorResult('Invalid JSON for values'); }
+          const data = await sapi(token, `/${params.spreadsheetId}/values/${encodeURIComponent(params.range)}:append`, {
+            method: 'POST',
+            query: { valueInputOption: params.inputOption || 'USER_ENTERED', insertDataOption: 'INSERT_ROWS' },
+            body: { range: params.range, majorDimension: 'ROWS', values },
+          });
+          return jsonResult({ appended: true, updatedRange: data.updates?.updatedRange, updatedRows: data.updates?.updatedRows, updatedCells: data.updates?.updatedCells });
+        } catch (e: any) { return errorResult(e.message); }
+      },
+    },
+    {
+      name: 'google_sheets_clear',
+      description: 'Clear values from a range (keeps formatting).',
+      category: 'utility' as const,
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          spreadsheetId: { type: 'string', description: 'Spreadsheet ID (required)' },
+          range: { type: 'string', description: 'Range to clear, e.g. "Sheet1!A2:D100" (required)' },
+        },
+        required: ['spreadsheetId', 'range'],
+      },
+      async execute(_id: string, params: any) {
+        try {
+          const token = await tp.getAccessToken();
+          const data = await sapi(token, `/${params.spreadsheetId}/values/${encodeURIComponent(params.range)}:clear`, { method: 'POST', body: {} });
+          return jsonResult({ cleared: true, clearedRange: data.clearedRange });
+        } catch (e: any) { return errorResult(e.message); }
+      },
+    },
+    {
+      name: 'google_sheets_create',
+      description: 'Create a new spreadsheet.',
+      category: 'utility' as const,
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          title: { type: 'string', description: 'Spreadsheet title (required)' },
+          sheetTitles: { type: 'string', description: 'Comma-separated sheet/tab names (default: "Sheet1")' },
+        },
+        required: ['title'],
+      },
+      async execute(_id: string, params: any) {
+        try {
+          const token = await tp.getAccessToken();
+          const sheets = (params.sheetTitles || 'Sheet1').split(',').map((t: string, i: number) => ({
+            properties: { title: t.trim(), index: i },
+          }));
+          const data = await sapi(token, '', {
+            method: 'POST',
+            body: { properties: { title: params.title }, sheets },
+          });
+          return jsonResult({
+            created: true, spreadsheetId: data.spreadsheetId,
+            title: data.properties?.title,
+            url: data.spreadsheetUrl,
+            sheets: (data.sheets || []).map((s: any) => s.properties?.title),
+          });
+        } catch (e: any) { return errorResult(e.message); }
+      },
+    },
+    {
+      name: 'google_sheets_add_sheet',
+      description: 'Add a new sheet/tab to an existing spreadsheet.',
+      category: 'utility' as const,
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          spreadsheetId: { type: 'string', description: 'Spreadsheet ID (required)' },
+          title: { type: 'string', description: 'New sheet/tab name (required)' },
+        },
+        required: ['spreadsheetId', 'title'],
+      },
+      async execute(_id: string, params: any) {
+        try {
+          const token = await tp.getAccessToken();
+          const data = await sapi(token, `/${params.spreadsheetId}:batchUpdate`, {
+            method: 'POST',
+            body: { requests: [{ addSheet: { properties: { title: params.title } } }] },
+          });
+          const reply = data.replies?.[0]?.addSheet?.properties;
+          return jsonResult({ added: true, sheetId: reply?.sheetId, title: reply?.title });
+        } catch (e: any) { return errorResult(e.message); }
+      },
+    },
+  ];
+}

package/src/agent-tools/tools/oauth-token-provider.ts

@@ -0,0 +1,101 @@
+/**
+ * OAuth Token Provider
+ *
+ * Shared abstraction for getting valid OAuth access tokens for agent tools.
+ * Handles token refresh automatically when tokens expire.
+ * Used by both Google Workspace and Microsoft Graph tool suites.
+ */
+
+export interface OAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: string; // ISO timestamp
+  provider: 'google' | 'microsoft';
+  clientId: string;
+  clientSecret: string;
+  scopes?: string[];
+}
+
+export interface TokenProvider {
+  /** Get a valid access token, refreshing if necessary */
+  getAccessToken(): Promise<string>;
+  /** Get the provider type */
+  getProvider(): 'google' | 'microsoft';
+  /** Get the agent's email */
+  getEmail(): string | undefined;
+}
+
+export interface TokenProviderConfig {
+  getTokens: () => OAuthTokens | null;
+  saveTokens: (tokens: Partial<OAuthTokens>) => void;
+  getEmail?: () => string | undefined;
+}
+
+const TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1000; // Refresh 5 min before expiry
+
+export function createTokenProvider(config: TokenProviderConfig): TokenProvider {
+  return {
+    async getAccessToken(): Promise<string> {
+      const tokens = config.getTokens();
+      if (!tokens) throw new Error('No OAuth tokens configured. Connect email via the agent Email tab first.');
+      if (!tokens.accessToken) throw new Error('No access token available. Re-authorize via the Email tab.');
+
+      // Check if token is expired or about to expire
+      if (tokens.expiresAt) {
+        const expiresAt = new Date(tokens.expiresAt).getTime();
+        if (Date.now() > expiresAt - TOKEN_REFRESH_BUFFER_MS) {
+          // Need to refresh
+          if (!tokens.refreshToken) throw new Error('Access token expired and no refresh token available. Re-authorize via the Email tab.');
+          return await refreshAccessToken(tokens, config);
+        }
+      }
+
+      return tokens.accessToken;
+    },
+
+    getProvider(): 'google' | 'microsoft' {
+      const tokens = config.getTokens();
+      return tokens?.provider || 'google';
+    },
+
+    getEmail(): string | undefined {
+      return config.getEmail?.();
+    },
+  };
+}
+
+async function refreshAccessToken(tokens: OAuthTokens, config: TokenProviderConfig): Promise<string> {
+  const tokenUrl = tokens.provider === 'google'
+    ? 'https://oauth2.googleapis.com/token'
+    : `https://login.microsoftonline.com/common/oauth2/v2.0/token`;
+
+  const body = new URLSearchParams({
+    client_id: tokens.clientId,
+    client_secret: tokens.clientSecret,
+    refresh_token: tokens.refreshToken!,
+    grant_type: 'refresh_token',
+  });
+
+  const res = await fetch(tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+
+  if (!res.ok) {
+    const errText = await res.text();
+    throw new Error(`Token refresh failed (${res.status}): ${errText}`);
+  }
+
+  const data = await res.json() as any;
+  const newTokens: Partial<OAuthTokens> = {
+    accessToken: data.access_token,
+    expiresAt: data.expires_in
+      ? new Date(Date.now() + data.expires_in * 1000).toISOString()
+      : undefined,
+  };
+  if (data.refresh_token) newTokens.refreshToken = data.refresh_token;
+
+  config.saveTokens(newTokens);
+  return data.access_token;
+}

package/src/runtime/index.ts

@@ -131,6 +131,26 @@ export class AgentRuntime {
     });
   }
 
+  /** Build tool options for a given agent, including OAuth email config if available */
+  private buildToolOptions(agentId: string): any {
+    const base: any = {
+      agentId,
+      workspaceDir: process.cwd(),
+      agenticmailManager: this.config.agenticmailManager,
+    };
+    if (this.config.getEmailConfig) {
+      const ec = this.config.getEmailConfig(agentId);
+      if (ec?.oauthAccessToken) {
+        base.emailConfig = ec;
+        if (this.config.onTokenRefresh) {
+          const onRefresh = this.config.onTokenRefresh;
+          base.onTokenRefresh = (tokens: any) => onRefresh(agentId, tokens);
+        }
+      }
+    }
+    return base;
+  }
+
   /**
    * Start the runtime — initializes session manager, gateway, schedulers,
    * heartbeat, stale detection, and resumes active sessions.
@@ -236,11 +256,7 @@ export class AgentRuntime {
     var session = await this.sessionManager!.createSession(agentId, orgId, opts.parentSessionId);
 
     // Build agent config
-    var tools = opts.tools || createAllTools({
-      agentId,
-      workspaceDir: process.cwd(),
-      agenticmailManager: this.config.agenticmailManager,
-    });
+    var tools = opts.tools || createAllTools(this.buildToolOptions(agentId));
 
     var systemPrompt = opts.systemPrompt || buildDefaultSystemPrompt(agentId);
 
@@ -282,7 +298,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(), agenticmailManager: this.config.agenticmailManager });
+    var tools = createAllTools(this.buildToolOptions(session.agentId));
 
     var agentConfig: AgentConfig = {
       agentId: session.agentId,
@@ -573,7 +589,7 @@ export class AgentRuntime {
             continue;
           }
 
-          var tools = createAllTools({ agentId: session.agentId, workspaceDir: process.cwd(), agenticmailManager: this.config.agenticmailManager });
+          var tools = createAllTools(this.buildToolOptions(session.agentId));
 
           var agentConfig: AgentConfig = {
             agentId: session.agentId,

package/src/runtime/types.ts

@@ -118,6 +118,10 @@ export interface RuntimeConfig {
   gatewayEnabled?: boolean;
   /** AgenticMail manager for org email access (optional — enables agenticmail_* tools) */
   agenticmailManager?: import('../agent-tools/tools/agenticmail.js').AgenticMailManagerRef;
+  /** Get OAuth email config for an agent (enables Google/Microsoft Workspace tools) */
+  getEmailConfig?: (agentId: string) => any;
+  /** Callback to persist refreshed OAuth tokens */
+  onTokenRefresh?: (agentId: string, tokens: any) => void;
   /** Resume active sessions on startup (default: true) */
   resumeOnStartup?: boolean;
   /** Heartbeat interval in ms (default: 30000 = 30s) */

package/src/server.ts

@@ -265,12 +265,35 @@ export function createServer(config: ServerConfig): ServerInstance {
           try {
             const { createAgentRuntime } = await import('./runtime/index.js');
             const { mountRuntimeApp } = await import('./engine/routes.js');
+            // Import lifecycle for email config access
+            let getEmailConfig: ((agentId: string) => any) | undefined;
+            let onTokenRefresh: ((agentId: string, tokens: any) => void) | undefined;
+            try {
+              const { lifecycle: lc } = await import('./engine/routes.js');
+              if (lc) {
+                getEmailConfig = (agentId: string) => {
+                  const managed = lc.getAgent(agentId);
+                  return managed?.config?.emailConfig || null;
+                };
+                onTokenRefresh = (agentId: string, tokens: any) => {
+                  const managed = lc.getAgent(agentId);
+                  if (managed?.config?.emailConfig) {
+                    if (tokens.accessToken) managed.config.emailConfig.oauthAccessToken = tokens.accessToken;
+                    if (tokens.refreshToken) managed.config.emailConfig.oauthRefreshToken = tokens.refreshToken;
+                    if (tokens.expiresAt) managed.config.emailConfig.oauthTokenExpiry = tokens.expiresAt;
+                    lc.saveAgent(agentId).catch(() => {});
+                  }
+                };
+              }
+            } catch {}
             const runtime = createAgentRuntime({
               engineDb,
               adminDb: config.db,
               defaultModel: config.runtime.defaultModel as any,
               apiKeys: config.runtime.apiKeys,
               gatewayEnabled: true,
+              getEmailConfig,
+              onTokenRefresh,
             });
             await runtime.start();
             const runtimeApp = runtime.getApp();