@agenticmail/enterprise 0.5.319 → 0.5.321

package/dist/task-queue-O7IVZYUO.js

@@ -0,0 +1,9 @@
+import {
+  TaskQueueManager,
+  init_task_queue
+} from "./chunk-Z6K5FKAB.js";
+import "./chunk-KFQGP6VL.js";
+init_task_queue();
+export {
+  TaskQueueManager
+};

package/dist/transport-encryption-2T7PIXKG.js

@@ -0,0 +1,25 @@
+import {
+  DEFAULT_SENSITIVE_ENDPOINTS,
+  decryptPayload,
+  encryptPayload,
+  getConfig,
+  init_transport_encryption,
+  loadConfig,
+  resetKeys,
+  setSettingsDb,
+  setTransportEncryptionConfig,
+  transportEncryptionMiddleware
+} from "./chunk-FLQ5FLHW.js";
+import "./chunk-KFQGP6VL.js";
+init_transport_encryption();
+export {
+  DEFAULT_SENSITIVE_ENDPOINTS,
+  decryptPayload,
+  encryptPayload,
+  getConfig,
+  loadConfig,
+  resetKeys,
+  setSettingsDb,
+  setTransportEncryptionConfig,
+  transportEncryptionMiddleware
+};

package/logs/cloudflared-error.log

@@ -0,0 +1,61 @@
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Starting tunnel tunnelID=18dbfae9-fe5c-4380-a5c7-e5e875255b06
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Version 2026.2.0 (Checksum dc6e60da390e702c4db3332d0cc9cf4e98a88df99f17273e9b3d83f435695fb4)
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF GOOS: darwin, GOVersion: go1.25.7, GoArch: arm64
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Settings: map[cred-file:/Users/ope/.cloudflared/18dbfae9-fe5c-4380-a5c7-e5e875255b06.json credentials-file:/Users/ope/.cloudflared/18dbfae9-fe5c-4380-a5c7-e5e875255b06.json]
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF cloudflared will not automatically update if installed by a package manager.
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Generated Connector ID: 5680022c-ff41-4224-8d2f-238ae9392416
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Initial protocol quic
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF ICMP proxy will use 192.168.86.21 as source for IPv4
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF ICMP proxy will use fe80::1c9c:15a9:2404:3154 in zone en1 as source for IPv6
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Created ICMP proxy listening on 192.168.86.21:0
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF ICMP proxy will use 192.168.86.21 as source for IPv4
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF ICMP proxy will use fe80::1c9c:15a9:2404:3154 in zone en1 as source for IPv6
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Starting metrics server on 127.0.0.1:20241/metrics
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Tunnel connection curve preferences: [X25519MLKEM768 CurveP256] connIndex=0 event=0 ip=198.41.200.63
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Registered tunnel connection connIndex=0 connection=4853aaeb-0b59-40b7-adab-55225c98aaa2 event=0 ip=198.41.200.63 location=atl10 protocol=quic
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Tunnel connection curve preferences: [X25519MLKEM768 CurveP256] connIndex=1 event=0 ip=198.41.192.7
+2026-03-05 06:30:17: 2026-03-05T05:30:17Z INF Registered tunnel connection connIndex=1 connection=721bad3b-ceeb-4173-8af3-61ef604bef42 event=0 ip=198.41.192.7 location=atl06 protocol=quic
+2026-03-05 06:30:18: 2026-03-05T05:30:18Z INF Tunnel connection curve preferences: [X25519MLKEM768 CurveP256] connIndex=2 event=0 ip=198.41.192.167
+2026-03-05 06:30:18: 2026-03-05T05:30:18Z INF Registered tunnel connection connIndex=2 connection=2c61322a-dbcd-4842-bc5a-24abb5dd04e7 event=0 ip=198.41.192.167 location=atl01 protocol=quic
+2026-03-05 06:30:19: 2026-03-05T05:30:19Z INF Tunnel connection curve preferences: [X25519MLKEM768 CurveP256] connIndex=3 event=0 ip=198.41.200.43
+2026-03-05 06:30:19: 2026-03-05T05:30:19Z INF Registered tunnel connection connIndex=3 connection=3f85a46d-7759-4483-a267-f9e342905648 event=0 ip=198.41.200.43 location=atl14 protocol=quic
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z INF Initiating graceful shutdown due to signal interrupt ...
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR failed to run the datagram handler error="Application error 0x0 (remote)" connIndex=0 event=0 ip=198.41.200.63
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR failed to serve tunnel connection error="accept stream listener encountered a failure while serving" connIndex=0 event=0 ip=198.41.200.63
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR Serve tunnel error error="accept stream listener encountered a failure while serving" connIndex=0 event=0 ip=198.41.200.63
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z INF Retrying connection in up to 1s connIndex=0 event=0 ip=198.41.200.63
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR Connection terminated connIndex=0
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR failed to run the datagram handler error="Application error 0x0 (remote)" connIndex=2 event=0 ip=198.41.192.167
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR failed to serve tunnel connection error="accept stream listener encountered a failure while serving" connIndex=2 event=0 ip=198.41.192.167
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR Serve tunnel error error="accept stream listener encountered a failure while serving" connIndex=2 event=0 ip=198.41.192.167
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z INF Retrying connection in up to 1s connIndex=2 event=0 ip=198.41.192.167
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR Connection terminated connIndex=2
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR failed to run the datagram handler error="context canceled" connIndex=1 event=0 ip=198.41.192.7
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR failed to serve tunnel connection error="accept stream listener encountered a failure while serving" connIndex=1 event=0 ip=198.41.192.7
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR Serve tunnel error error="accept stream listener encountered a failure while serving" connIndex=1 event=0 ip=198.41.192.7
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z INF Retrying connection in up to 1s connIndex=1 event=0 ip=198.41.192.7
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z ERR Connection terminated connIndex=1
+2026-03-05 06:31:03: 2026-03-05T05:31:03Z INF Unregistered tunnel connection connIndex=3 event=0 ip=198.41.200.43
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF Starting tunnel tunnelID=18dbfae9-fe5c-4380-a5c7-e5e875255b06
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF Version 2026.2.0 (Checksum dc6e60da390e702c4db3332d0cc9cf4e98a88df99f17273e9b3d83f435695fb4)
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF GOOS: darwin, GOVersion: go1.25.7, GoArch: arm64
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF Settings: map[cred-file:/Users/ope/.cloudflared/18dbfae9-fe5c-4380-a5c7-e5e875255b06.json credentials-file:/Users/ope/.cloudflared/18dbfae9-fe5c-4380-a5c7-e5e875255b06.json]
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF cloudflared will not automatically update if installed by a package manager.
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF Generated Connector ID: cc6e6cb6-caac-477f-a1a2-d86368d41607
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF Initial protocol quic
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF ICMP proxy will use 192.168.86.21 as source for IPv4
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF ICMP proxy will use fe80::1c9c:15a9:2404:3154 in zone en1 as source for IPv6
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF Created ICMP proxy listening on 192.168.86.21:0
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF ICMP proxy will use 192.168.86.21 as source for IPv4
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF ICMP proxy will use fe80::1c9c:15a9:2404:3154 in zone en1 as source for IPv6
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF Starting metrics server on 127.0.0.1:20241/metrics
+2026-03-05 06:31:08: 2026-03-05T05:31:08Z INF Tunnel connection curve preferences: [X25519MLKEM768 CurveP256] connIndex=0 event=0 ip=198.41.192.107
+2026-03-05 06:31:09: 2026-03-05T05:31:09Z INF Registered tunnel connection connIndex=0 connection=edb70b98-0105-4afd-bb75-6c2ec9ca0a53 event=0 ip=198.41.192.107 location=atl12 protocol=quic
+2026-03-05 06:31:09: 2026-03-05T05:31:09Z INF Tunnel connection curve preferences: [X25519MLKEM768 CurveP256] connIndex=1 event=0 ip=198.41.200.63
+2026-03-05 06:31:09: 2026-03-05T05:31:09Z INF Registered tunnel connection connIndex=1 connection=826299ab-8cff-4806-8890-55db7e5620d0 event=0 ip=198.41.200.63 location=atl11 protocol=quic
+2026-03-05 06:31:10: 2026-03-05T05:31:10Z INF Tunnel connection curve preferences: [X25519MLKEM768 CurveP256] connIndex=2 event=0 ip=198.41.192.57
+2026-03-05 06:31:10: 2026-03-05T05:31:10Z INF Registered tunnel connection connIndex=2 connection=9ceb7c37-a55c-4516-bbd0-e69f4f0c1152 event=0 ip=198.41.192.57 location=atl12 protocol=quic
+2026-03-05 06:31:11: 2026-03-05T05:31:11Z INF Tunnel connection curve preferences: [X25519MLKEM768 CurveP256] connIndex=3 event=0 ip=198.41.200.53
+2026-03-05 06:31:11: 2026-03-05T05:31:11Z INF Registered tunnel connection connIndex=3 connection=3b74716b-204c-459d-b533-31e1307e1ea8 event=0 ip=198.41.200.53 location=atl11 protocol=quic
+2026-03-05 06:35:14: 2026-03-05T05:35:14Z ERR  error="unexpected EOF" connIndex=3 event=1 ingressRule=0 originService=http://localhost:3100
+2026-03-05 06:35:14: 2026-03-05T05:35:14Z ERR Request failed error="unexpected EOF" connIndex=3 dest=https://enterprise.agenticmail.io/api/engine/task-pipeline/stream event=0 ip=198.41.200.53 type=http

package/logs/enterprise-out.log

@@ -0,0 +1,3 @@
+2026-03-05 06:30:17: Loaded config from /Users/ope/Desktop/projects/agenticmail/enterprise/.env
+2026-03-05 06:31:08: Loaded config from /Users/ope/Desktop/projects/agenticmail/enterprise/.env
+2026-03-05 06:35:14: Loaded config from /Users/ope/Desktop/projects/agenticmail/enterprise/.env

package/logs/john-error.log

@@ -0,0 +1,8 @@
+2026-03-05 06:30:17: ERROR: DATABASE_URL is required
+2026-03-05 06:30:19: ERROR: DATABASE_URL is required
+2026-03-05 06:30:22: ERROR: DATABASE_URL is required
+2026-03-05 06:30:27: ERROR: DATABASE_URL is required
+2026-03-05 06:30:34: ERROR: DATABASE_URL is required
+2026-03-05 06:30:44: ERROR: DATABASE_URL is required
+2026-03-05 06:30:59: ERROR: DATABASE_URL is required
+2026-03-05 06:31:11: Fatal error: current transaction is aborted, commands ignored until end of transaction block

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/enterprise",
-  "version": "0.5.319",
+  "version": "0.5.321",
   "description": "AgenticMail Enterprise — cloud-hosted AI agent identity, email, auth & compliance for organizations",
   "type": "module",
   "bin": {
@@ -28,10 +28,31 @@
     "saml",
     "oidc",
     "scim",
-    "identity"
+    "identity",
+    "ai-agents",
+    "agent-platform",
+    "microsoft-365",
+    "google-workspace",
+    "compliance",
+    "soc2",
+    "gdpr",
+    "dlp",
+    "data-loss-prevention",
+    "oauth",
+    "multi-tenant",
+    "workforce-management",
+    "task-pipeline",
+    "telegram-bot",
+    "whatsapp-bot",
+    "voice-ai",
+    "google-meet",
+    "dependency-management",
+    "audit-log",
+    "rbac",
+    "encryption"
   ],
   "author": "Ope Olatunji (https://github.com/ope-olatunji)",
-  "homepage": "https://github.com/agenticmail/enterprise",
+  "homepage": "https://agenticmail.io",
   "repository": {
     "type": "git",
     "url": "https://github.com/agenticmail/enterprise.git"
@@ -90,5 +111,12 @@
     "mongodb": "^6.3.0",
     "mysql2": "^3.9.0",
     "postgres": "^3.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://agenticmail.io"
   }
 }

package/src/agent-tools/tool-resolver.ts

@@ -81,7 +81,10 @@ export type ToolSet =
   // Management (hierarchy, delegation, escalation)
   | 'management'
   // Integrations
-  | 'mcp_bridge';
+  | 'mcp_bridge'
+  // Aliases (legacy/shorthand)
+  | 'filesystem'
+  | 'web';
 
 // ─── Tier Classification ─────────────────────────────────
 
@@ -131,6 +134,8 @@ const TIER_MAP: Record<ToolSet, ToolTier> = {
   msg_whatsapp: 2,
   msg_telegram: 2,
   mcp_bridge: 3,
+  filesystem: 2,
+  web: 2,
 };
 
 // ─── Exhaustive Tool Registry ────────────────────────────
@@ -501,67 +506,28 @@ export function clearSessionToolState(sessionId: string): void {
 // Which Tier 2 sets get auto-loaded for each context.
 // Tier 1 is ALWAYS loaded. Tier 3 is NEVER auto-loaded (must be requested).
 
+const _ALL_SETS = Object.keys(TIER_MAP) as ToolSet[];
+
+// Tier 2 sets that are commonly needed — loaded for most contexts
+const _COMMON_T2: ToolSet[] = ['local_filesystem', 'local_shell', 'browser', 'system', 'ent_knowledge'];
+
 const CONTEXT_PROMOTIONS: Record<SessionContext, ToolSet[]> = {
-  // Meeting: voice + calendar (check schedule)
-  meeting: [
-    'meeting_voice',
-    'gws_calendar',
-  ],
-
-  // Chat (Google Chat): GWS chat tools + browser + calendar + knowledge
-  chat: [
-    'gws_chat',
-    'browser',
-    'gws_calendar',
-    'ent_knowledge',
-  ],
-
-  // WhatsApp: messaging + essential file/shell tools for media processing
-  whatsapp: [
-    'msg_whatsapp',
-    'browser',
-    'local_shell',
-    'filesystem',
-    'web',
-  ],
-
-  // Telegram: messaging + essential file/shell tools for media processing
-  telegram: [
-    'msg_telegram',
-    'browser',
-    'local_shell',
-    'filesystem',
-    'web',
-  ],
-
-  // Email handler: focused email + lookups
-  email: [
-    'system',
-    'gws_gmail',
-    'gws_calendar',
-    'gws_contacts',
-    'gws_drive',
-    'gws_tasks',
-    'agenticmail',
-    'ent_documents',
-    'ent_knowledge',
-  ],
-
-  // Task: broad access for autonomous work
-  task: [
-    'browser', 'system',
-    'visual_memory',
-    'meeting_lifecycle',
-    'gws_gmail', 'gws_calendar', 'gws_drive',
-    'gws_docs', 'gws_sheets', 'gws_contacts',
-    'gws_tasks', 'gws_maps',
-    'ent_database', 'ent_spreadsheet', 'ent_documents',
-    'ent_http', 'ent_security', 'ent_code', 'ent_diff',
-    'agenticmail', 'mcp_bridge',
-  ],
-
-  // Full: everything
-  full: Object.keys(TIER_MAP) as ToolSet[],
+  // Meeting: voice + lifecycle essential, plus common tools
+  meeting: ['meeting_voice', 'meeting_lifecycle', ..._COMMON_T2],
+
+  // Chat (webchat/generic): common tools only — rest loaded on demand via signals or request_tools
+  chat: _COMMON_T2,
+
+  // Messaging channels: load the relevant channel's tools + common tools
+  // The agent's OWN channel tools are essential (Tier 1-like for that session)
+  // Other channel tools and specialist tools load on demand
+  whatsapp: ['msg_whatsapp', ..._COMMON_T2],
+  telegram: ['msg_telegram', ..._COMMON_T2],
+  email: ['agenticmail', 'gws_gmail', ..._COMMON_T2],
+
+  // Task/full: broader set for agent-to-agent work
+  task: ['agenticmail', ..._COMMON_T2],
+  full: _ALL_SETS,
 };
 
 // ─── Conversation Signal Detection ───────────────────────
@@ -619,6 +585,27 @@ const SIGNAL_RULES: SignalRule[] = [
   // Knowledge base / hub
   { patterns: [/\bknowledge\s*base\b/i, /\bknowledge\s*hub\b/i, /\bfaq\b/i, /\bdocumentation\b/i, /\bwiki\b/i, /\bhow\s+do\s+(we|i)\b/i, /\bwhat.*(policy|process|procedure)\b/i, /\bcompany.*(guide|handbook)\b/i],
     sets: ['ent_knowledge'] },
+  // WhatsApp (cross-channel)
+  { patterns: [/\bwhatsapp\b/i, /\bsend.*whatsapp\b/i, /\bwa\s+message\b/i],
+    sets: ['msg_whatsapp'] },
+  // Telegram (cross-channel)
+  { patterns: [/\btelegram\b/i, /\bsend.*telegram\b/i, /\btg\s+message\b/i],
+    sets: ['msg_telegram'] },
+  // Spreadsheet / CSV
+  { patterns: [/\bcsv\b/i, /\bspreadsheet\b/i, /\btransform.*data\b/i, /\bpivot\b/i],
+    sets: ['ent_spreadsheet'] },
+  // Diff
+  { patterns: [/\bdiff\b/i, /\bcompare.*files?\b/i, /\bwhat.*changed\b/i],
+    sets: ['ent_diff'] },
+  // Tasks (Google)
+  { patterns: [/\bgoogle\s*tasks?\b/i, /\btask\s*list\b/i, /\btodo\b/i],
+    sets: ['gws_tasks'] },
+  // Visual memory
+  { patterns: [/\bscreenshot\b/i, /\bcapture\b/i, /\bvision\b/i, /\bwhat.*see\b/i, /\blook\s*at\b/i],
+    sets: ['visual_memory'] },
+  // AgenticMail (broader)
+  { patterns: [/\bsend.*email\b/i, /\bwrite.*email\b/i, /\bdraft\b/i, /\binbox\b/i, /\bcheck.*mail\b/i],
+    sets: ['agenticmail'] },
 ];
 
 /**
@@ -823,6 +810,8 @@ const SET_DESCRIPTIONS: Record<ToolSet, string> = {
   msg_telegram: 'Telegram messaging, media, and file download (5 tools)',
   management: 'Team management — delegate tasks, escalate, org chart (10 tools)',
   mcp_bridge: 'MCP integration adapters',
+  filesystem: 'File system tools (alias)',
+  web: 'Web tools (alias)',
 };
 
 function createRequestToolsTool(

package/src/agent-tools/tools/enterprise-database.ts

@@ -52,7 +52,7 @@ export function createDatabaseTools(options?: ToolCreationOptions): AnyAgentTool
   var entDbQuery: AnyAgentTool = {
     name: 'ent_db_query',
     label: 'Database Query',
-    description: 'Execute a read-only SQL query against a database connection.',
+    description: 'Execute a read-only SQL query against a LOCAL SQLite database file. For external/cloud databases, use db_query instead.',
     category: 'utility',
     risk: 'medium',
     parameters: {
@@ -220,8 +220,8 @@ export function createDatabaseTools(options?: ToolCreationOptions): AnyAgentTool
 
   var entDbConnections: AnyAgentTool = {
     name: 'ent_db_connections',
-    label: 'List Database Connections',
-    description: 'List all available database connections that can be used with other database ...',
+    label: 'List Local Database Files',
+    description: 'List LOCAL SQLite database files found in the workspace directory. ONLY for local .db/.sqlite files on this machine. For external/cloud databases (Postgres, MySQL, Supabase, etc.) granted by your admin, use db_list_connections instead.',
     category: 'utility',
     risk: 'low',
     parameters: {
@@ -265,8 +265,8 @@ export function createDatabaseTools(options?: ToolCreationOptions): AnyAgentTool
 
   var entDbTables: AnyAgentTool = {
     name: 'ent_db_tables',
-    label: 'List Tables',
-    description: 'List all tables in a database connection.',
+    label: 'List Local DB Tables',
+    description: 'List all tables in a LOCAL SQLite database file. For external/cloud databases, use db_list_tables instead.',
     category: 'utility',
     risk: 'low',
     parameters: {

package/src/agent-tools/tools/local/dependency-manager.ts

@@ -426,8 +426,8 @@ export function createDependencyManagerTools(): ToolDefinition[] {
           else {
             // Try to figure out a manager
             var mgrs = await detectPackageManagers();
-            var fallback: PkgManager = IS_WINDOWS ? (mgrs.includes('choco') ? 'choco' : mgrs.includes('winget') ? 'winget' : 'npm') : IS_MAC ? 'brew' : (mgrs.includes('apt') ? 'apt' : 'npm');
-            resolved = { mgr: fallback, pkg: input.package, isLocal: fallback === 'npm' || fallback === 'pip' };
+            var fallback = (IS_WINDOWS ? (mgrs.includes('choco') ? 'choco' : mgrs.includes('winget') ? 'winget' : 'npm') : IS_MAC ? 'brew' : (mgrs.includes('apt') ? 'apt' : 'npm')) as PkgManager;
+            resolved = { mgr: fallback, pkg: input.package, isLocal: fallback === 'npm' || (fallback as string) === 'pip' };
           }
         }
         if (!resolved) {

package/src/agent-tools/tools/microsoft/graph-api.ts

@@ -1,26 +1,32 @@
 /**
- * Microsoft Graph API helper
+ * Microsoft Graph API Helper
  *
- * Shared fetch wrapper for all Microsoft 365 tools.
- * Uses Microsoft Graph API v1.0.
+ * Enhanced shared fetch wrapper for all Microsoft 365 tools.
+ * Supports pagination, batch requests, retry with backoff, and rate limiting.
  */
 
 const GRAPH_BASE = 'https://graph.microsoft.com/v1.0';
+const GRAPH_BETA = 'https://graph.microsoft.com/beta';
 
-export async function graph(
-  token: string,
-  path: string,
-  opts?: {
-    method?: string;
-    body?: any;
-    query?: Record<string, string>;
-    rawBody?: BodyInit;
-    headers?: Record<string, string>;
-    beta?: boolean;
-  }
-): Promise<any> {
+export interface GraphOptions {
+  method?: string;
+  body?: any;
+  query?: Record<string, string>;
+  rawBody?: BodyInit;
+  headers?: Record<string, string>;
+  beta?: boolean;
+  /** Max retries on 429/5xx (default: 3) */
+  retries?: number;
+  /** Return raw Response instead of parsed JSON */
+  raw?: boolean;
+}
+
+/**
+ * Core Graph API fetch — handles auth, JSON, retries, rate-limit backoff.
+ */
+export async function graph(token: string, path: string, opts?: GraphOptions): Promise<any> {
   const method = opts?.method || 'GET';
-  const base = opts?.beta ? 'https://graph.microsoft.com/beta' : GRAPH_BASE;
+  const base = opts?.beta ? GRAPH_BETA : GRAPH_BASE;
   const url = new URL(base + path);
   if (opts?.query) {
     for (const [k, v] of Object.entries(opts.query)) {
@@ -34,17 +40,122 @@ export async function graph(
   if (!opts?.rawBody && !opts?.headers?.['Content-Type']) {
     headers['Content-Type'] = 'application/json';
   }
-  const res = await fetch(url.toString(), {
-    method,
-    headers,
-    body: opts?.rawBody || (opts?.body ? JSON.stringify(opts.body) : undefined),
+
+  const maxRetries = opts?.retries ?? 3;
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const res = await fetch(url.toString(), {
+        method,
+        headers,
+        body: opts?.rawBody || (opts?.body ? JSON.stringify(opts.body) : undefined),
+      });
+
+      // Rate limited — back off using Retry-After header
+      if (res.status === 429 && attempt < maxRetries) {
+        const retryAfter = parseInt(res.headers.get('Retry-After') || '5', 10);
+        await sleep(retryAfter * 1000);
+        continue;
+      }
+
+      // Server error — exponential backoff
+      if (res.status >= 500 && attempt < maxRetries) {
+        await sleep(Math.pow(2, attempt) * 1000);
+        continue;
+      }
+
+      if (opts?.raw) return res;
+
+      if (!res.ok) {
+        const err = await res.text();
+        throw new Error(`Graph ${method} ${path} ${res.status}: ${err}`);
+      }
+      if (res.status === 204 || res.status === 202) return {};
+      const ct = res.headers.get('content-type') || '';
+      if (ct.includes('application/json')) return res.json();
+      return { content: await res.text() };
+    } catch (e: any) {
+      lastError = e;
+      if (attempt < maxRetries && e.message?.includes('fetch failed')) {
+        await sleep(Math.pow(2, attempt) * 1000);
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw lastError || new Error('Graph request failed after retries');
+}
+
+/**
+ * Auto-paginate a Graph API collection. Follows @odata.nextLink up to maxPages.
+ * Returns all items concatenated.
+ */
+export async function graphPaginate(
+  token: string,
+  path: string,
+  opts?: GraphOptions & { maxPages?: number; maxItems?: number }
+): Promise<any[]> {
+  const maxPages = opts?.maxPages ?? 10;
+  const maxItems = opts?.maxItems ?? 500;
+  const items: any[] = [];
+  let nextUrl: string | null = null;
+  let page = 0;
+
+  // First request
+  const first = await graph(token, path, opts);
+  items.push(...(first.value || []));
+  nextUrl = first['@odata.nextLink'] || null;
+
+  // Follow pagination
+  while (nextUrl && ++page < maxPages && items.length < maxItems) {
+    const res = await fetch(nextUrl, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) break;
+    const data = await res.json();
+    items.push(...(data.value || []));
+    nextUrl = data['@odata.nextLink'] || null;
+  }
+
+  return items.slice(0, maxItems);
+}
+
+/**
+ * Execute a JSON batch request (up to 20 requests per batch).
+ * https://learn.microsoft.com/en-us/graph/json-batching
+ */
+export async function graphBatch(
+  token: string,
+  requests: Array<{
+    id: string;
+    method: string;
+    url: string;
+    body?: any;
+    headers?: Record<string, string>;
+  }>,
+  opts?: { beta?: boolean }
+): Promise<Map<string, { status: number; body: any }>> {
+  const base = opts?.beta ? GRAPH_BETA : GRAPH_BASE;
+  const res = await fetch(`${base}/$batch`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ requests }),
   });
   if (!res.ok) {
-    const err = await res.text();
-    throw new Error(`Microsoft Graph ${res.status}: ${err}`);
+    throw new Error(`Graph batch ${res.status}: ${await res.text()}`);
+  }
+  const data = await res.json();
+  const results = new Map<string, { status: number; body: any }>();
+  for (const r of data.responses || []) {
+    results.set(r.id, { status: r.status, body: r.body });
   }
-  if (res.status === 204) return {};
-  const ct = res.headers.get('content-type') || '';
-  if (ct.includes('application/json')) return res.json();
-  return { content: await res.text() };
+  return results;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
 }