@agenticmail/enterprise 0.5.312 → 0.5.313

package/src/dashboard/pages/login.js

@@ -382,6 +382,118 @@ export function OnboardingWizard({ onComplete }) {
 
   var set = function(k, v) { setForm(function(f) { return Object.assign({}, f, { [k]: v }); }); };
 
+  // ─── Smart DB URL Analysis & Auto-Optimization ─────
+
+  var analyzeDbUrl = function(url) {
+    if (!url) return null;
+    try {
+      var u = new URL(url);
+      var port = u.port || '5432';
+      var host = u.hostname || '';
+      var info = {
+        host: host, port: port, provider: null, isPooler: false, poolerMode: null,
+        directUrl: null, optimizedUrl: null, warnings: [], tips: [], autoFixed: []
+      };
+
+      // ── Supabase Detection ──────────────────────────
+      if (host.includes('.supabase.co') || host.includes('pooler.supabase.com')) {
+        info.provider = 'supabase';
+        var projectRef = u.username.replace('postgres.', '');
+
+        if (host.includes('pooler.supabase.com')) {
+          info.isPooler = true;
+          info.poolerMode = port === '6543' ? 'transaction' : port === '5432' ? 'session' : 'unknown';
+
+          // Build direct URL: db.{ref}.supabase.co:5432
+          var directU = new URL(url);
+          directU.hostname = 'db.' + projectRef + '.supabase.co';
+          directU.port = '5432';
+          directU.searchParams.delete('pgbouncer');
+          info.directUrl = directU.toString();
+
+          if (port === '5432') {
+            // Auto-fix: switch from session mode (5432) to transaction mode (6543)
+            var fixedU = new URL(url);
+            fixedU.port = '6543';
+            fixedU.searchParams.set('pgbouncer', 'true');
+            info.optimizedUrl = fixedU.toString();
+            info.autoFixed.push('Switched from session mode (port 5432) to transaction mode (port 6543) — higher connection limits and better for multi-process setups.');
+            info.autoFixed.push('Added ?pgbouncer=true for proper connection pooling.');
+          } else if (port === '6543') {
+            // Already on transaction mode — ensure pgbouncer param is set
+            if (!u.searchParams.get('pgbouncer')) {
+              var optU = new URL(url);
+              optU.searchParams.set('pgbouncer', 'true');
+              info.optimizedUrl = optU.toString();
+              info.autoFixed.push('Added ?pgbouncer=true parameter for proper PgBouncer transaction mode handling.');
+            }
+            info.tips.push('Transaction mode pooler detected — optimal for production.');
+          }
+          info.tips.push('Direct URL auto-generated for migrations (bypasses pooler for DDL operations).');
+
+        } else if (host.startsWith('db.') || host.includes('.supabase.co')) {
+          // Direct connection — build pooler URL for them
+          info.directUrl = url;
+          var region = host.match(/db\.([^.]+)\.supabase\.co/)?.[1] || projectRef;
+          // Try to detect region from hostname pattern
+          var poolerU = new URL(url);
+          // Supabase pooler format: aws-0-{region}.pooler.supabase.com
+          poolerU.hostname = 'aws-0-us-east-1.pooler.supabase.com'; // default, user may need to adjust
+          poolerU.port = '6543';
+          poolerU.username = 'postgres.' + region;
+          poolerU.searchParams.set('pgbouncer', 'true');
+          info.warnings.push('Direct connection detected. For production with multiple agents, use the Supabase connection pooler.');
+          info.tips.push('Go to Supabase Dashboard > Settings > Database > Connection string > URI, and select "Transaction mode" to get the correct pooler URL.');
+        }
+      }
+      // ── Neon Detection ──────────────────────────────
+      else if (host.includes('.neon.tech')) {
+        info.provider = 'neon';
+        info.isPooler = host.includes('-pooler');
+        if (!info.isPooler) {
+          // Auto-fix: add -pooler to hostname
+          var neonFixedU = new URL(url);
+          var parts = neonFixedU.hostname.split('.');
+          if (parts[0] && !parts[0].endsWith('-pooler')) {
+            parts[0] = parts[0] + '-pooler';
+            neonFixedU.hostname = parts.join('.');
+            info.optimizedUrl = neonFixedU.toString();
+            info.autoFixed.push('Added connection pooler endpoint (-pooler) for better connection handling.');
+          }
+          // Direct URL is the original
+          info.directUrl = url;
+          info.tips.push('Direct URL saved for migrations.');
+        } else {
+          // Already pooled — generate direct URL
+          var neonDirectU = new URL(url);
+          var neonParts = neonDirectU.hostname.split('.');
+          if (neonParts[0]) {
+            neonParts[0] = neonParts[0].replace(/-pooler$/, '');
+            neonDirectU.hostname = neonParts.join('.');
+          }
+          info.directUrl = neonDirectU.toString();
+          info.tips.push('Neon pooler detected — optimal for production. Direct URL auto-generated for migrations.');
+        }
+      }
+      // ── Generic Postgres ────────────────────────────
+      else {
+        info.provider = 'postgres';
+        // Check for common PgBouncer indicators
+        if (port === '6432' || port === '6543' || u.searchParams.get('pgbouncer') === 'true') {
+          info.isPooler = true;
+          info.poolerMode = 'transaction';
+          info.tips.push('PgBouncer detected. Connection pooling will be configured automatically.');
+        }
+      }
+
+      return info;
+    } catch { return null; }
+  };
+
+  var dbUrlInfo = useMemo(function() {
+    return analyzeDbUrl(form.dbConnectionString);
+  }, [form.dbConnectionString]);
+
   // ─── DB Config Builder ──────────────────────────────
 
   var buildDbConfig = function() {
@@ -389,7 +501,17 @@ export function OnboardingWizard({ onComplete }) {
     if (t === 'sqlite') return { type: 'sqlite' };
     if (t === 'turso') return { type: 'turso', connectionString: form.dbConnectionString, authToken: form.dbAuthToken };
     if (t === 'dynamodb') return { type: 'dynamodb', region: form.dbRegion, accessKeyId: form.dbAccessKey, secretAccessKey: form.dbSecretKey };
-    return { type: t, connectionString: form.dbConnectionString };
+    // Use optimized URL if available (auto-fixed pooler mode, pgbouncer param, etc.)
+    var connStr = (dbUrlInfo && dbUrlInfo.optimizedUrl) ? dbUrlInfo.optimizedUrl : form.dbConnectionString;
+    var config = { type: t, connectionString: connStr };
+    // Auto-attach smart DB metadata for Postgres-family databases
+    if (dbUrlInfo) {
+      config.poolerDetected = dbUrlInfo.isPooler || !!dbUrlInfo.optimizedUrl;
+      config.poolerMode = dbUrlInfo.poolerMode || (dbUrlInfo.optimizedUrl ? 'transaction' : null);
+      config.directUrl = dbUrlInfo.directUrl;
+      config.provider = dbUrlInfo.provider;
+    }
+    return config;
   };
 
   // ─── Actions ────────────────────────────────────────
@@ -528,9 +650,43 @@ export function OnboardingWizard({ onComplete }) {
       );
     }
     // Connection string types: postgres, mysql, mongodb, supabase, neon, planetscale, cockroachdb
-    return h('div', { className: 'form-group' },
-      h('label', { className: 'form-label' }, 'Connection String'),
-      h('input', { className: 'input', value: form.dbConnectionString, onChange: function(e) { set('dbConnectionString', e.target.value); }, placeholder: currentDbType ? currentDbType.placeholder : '' })
+    var urlHints = dbUrlInfo && form.dbConnectionString.length > 10;
+    return h(Fragment, null,
+      h('div', { className: 'form-group' },
+        h('label', { className: 'form-label' }, 'Connection String'),
+        h('input', { className: 'input', value: form.dbConnectionString, onChange: function(e) { set('dbConnectionString', e.target.value); }, placeholder: currentDbType ? currentDbType.placeholder : '' })
+      ),
+      // Smart URL analysis hints
+      urlHints && h('div', { style: { margin: '-8px 0 12px', fontSize: 12, lineHeight: 1.6 } },
+        dbUrlInfo.provider && dbUrlInfo.provider !== 'postgres' && h('div', { style: { color: 'var(--accent)', fontWeight: 500, marginBottom: 4 } },
+          dbUrlInfo.provider === 'supabase' ? '\uD83D\uDFE2 Supabase' : dbUrlInfo.provider === 'neon' ? '\uD83D\uDFE2 Neon' : dbUrlInfo.provider,
+          ' detected',
+          dbUrlInfo.isPooler || dbUrlInfo.optimizedUrl ? ' \u2014 connection will be auto-optimized' : ' (direct connection)'
+        ),
+        // Auto-fix notifications (green — things we fixed for them)
+        dbUrlInfo.autoFixed && dbUrlInfo.autoFixed.map(function(f, i) {
+          return h('div', { key: 'f' + i, style: { color: '#10b981', padding: '4px 8px', background: 'rgba(16,185,129,0.08)', borderRadius: 6, marginBottom: 4 } },
+            '\u2728 Auto-configured: ', f
+          );
+        }),
+        // Warnings (yellow — things they need to act on)
+        dbUrlInfo.warnings.map(function(w, i) {
+          return h('div', { key: 'w' + i, style: { color: 'var(--warning, #f59e0b)', padding: '4px 8px', background: 'rgba(245,158,11,0.1)', borderRadius: 6, marginBottom: 4 } },
+            '\u26A0\uFE0F ', w
+          );
+        }),
+        // Tips (informational)
+        dbUrlInfo.tips.map(function(t, i) {
+          return h('div', { key: 't' + i, style: { color: 'var(--text-secondary)', padding: '2px 0' } },
+            '\u2714\uFE0F ', t
+          );
+        }),
+        // Summary of what will be sent
+        (dbUrlInfo.directUrl || dbUrlInfo.optimizedUrl) && h('div', { style: { color: 'var(--text-secondary)', padding: '6px 8px', background: 'var(--bg-secondary)', borderRadius: 6, marginTop: 4, fontSize: 11 } },
+          dbUrlInfo.optimizedUrl && h('div', null, '\uD83D\uDD17 Pooler URL: ', h('code', { style: { fontSize: 10 } }, dbUrlInfo.optimizedUrl.substring(0, 60) + '...')),
+          dbUrlInfo.directUrl && h('div', null, '\uD83D\uDD17 Direct URL (migrations): ', h('code', { style: { fontSize: 10 } }, dbUrlInfo.directUrl.substring(0, 60) + '...'))
+        )
+      )
     );
   };
 

package/src/dashboard/pages/task-pipeline.js

@@ -231,6 +231,7 @@ var ACTIVITY_TYPE_COLORS = {
   created: '#6366f1', assigned: '#991b1b', started: '#06b6d4', in_progress: '#06b6d4',
   completed: '#15803d', failed: '#ef4444', cancelled: '#6b7394', delegated: '#a855f7',
   compaction: '#8b5cf6', error: '#ef4444',
+  crash: '#dc2626', recovery: '#f59e0b', note: '#3b82f6',
 };
 
 function ActivityLog(props) {
@@ -1084,7 +1085,6 @@ export function AgentTaskPipeline(props) {
   }
 
   return h(Fragment, null,
-    h(orgCtx.Switcher),
     active.length > 0 && h('div', { style: { marginBottom: 12 } },
       h('div', { style: { fontSize: 11, fontWeight: 600, color: STATUS_COLORS.in_progress, marginBottom: 6, display: 'flex', alignItems: 'center', gap: 4 } },
         h('div', { style: { width: 6, height: 6, borderRadius: '50%', background: STATUS_COLORS.in_progress, animation: 'flowPulse 2s infinite' } }),

package/src/db/adapter.ts

@@ -28,6 +28,8 @@ export interface DatabaseConfig {
   secretAccessKey?: string;
   /** Turso-specific */
   authToken?: string;
+  /** Direct connection URL (bypasses PgBouncer) — used for migrations */
+  directUrl?: string;
   /** Extra driver options */
   options?: Record<string, unknown>;
 }

package/src/db/factory.ts

@@ -35,6 +35,84 @@ export async function createAdapter(config: DatabaseConfig): Promise<DatabaseAda
   return adapter;
 }
 
+/**
+ * Smart config builder: auto-detects Supabase/Neon pooler URLs,
+ * sets optimal connection params, and derives a directUrl for migrations.
+ * Call this when building config from a raw DATABASE_URL env var.
+ */
+export function smartDbConfig(connectionString: string, typeHint?: DatabaseType): DatabaseConfig {
+  const type: DatabaseType = typeHint || (connectionString.startsWith('postgres') ? 'postgres' : 'sqlite');
+  const config: DatabaseConfig = { type, connectionString };
+
+  if (type === 'sqlite') return config;
+
+  try {
+    const u = new URL(connectionString);
+    const host = u.hostname || '';
+    const port = u.port || '5432';
+
+    // ── Supabase detection ──────────────────────────
+    if (host.includes('pooler.supabase.com') || host.includes('.supabase.co')) {
+      const projectRef = u.username.replace('postgres.', '');
+
+      if (host.includes('pooler.supabase.com')) {
+        // Generate direct URL for migrations
+        const directU = new URL(connectionString);
+        directU.hostname = 'db.' + projectRef + '.supabase.co';
+        directU.port = '5432';
+        directU.searchParams.delete('pgbouncer');
+        config.directUrl = directU.toString();
+
+        // Auto-switch to transaction mode if on session mode
+        if (port === '5432') {
+          const fixedU = new URL(connectionString);
+          fixedU.port = '6543';
+          fixedU.searchParams.set('pgbouncer', 'true');
+          config.connectionString = fixedU.toString();
+          console.log('[db] Auto-optimized: Supabase session mode (5432) → transaction mode (6543)');
+        } else if (!u.searchParams.get('pgbouncer')) {
+          const fixedU = new URL(connectionString);
+          fixedU.searchParams.set('pgbouncer', 'true');
+          config.connectionString = fixedU.toString();
+          console.log('[db] Auto-configured: Added ?pgbouncer=true for Supabase transaction mode');
+        }
+      } else if (host.startsWith('db.')) {
+        // Direct connection — save as directUrl, but warn
+        config.directUrl = connectionString;
+        console.log('[db] Supabase direct connection detected. For production, use the pooler URL (port 6543).');
+      }
+    }
+    // ── Neon detection ──────────────────────────────
+    else if (host.includes('.neon.tech')) {
+      if (!host.includes('-pooler')) {
+        // Direct endpoint — save as directUrl, generate pooler
+        config.directUrl = connectionString;
+        const poolerU = new URL(connectionString);
+        const parts = poolerU.hostname.split('.');
+        if (parts[0] && !parts[0].endsWith('-pooler')) {
+          parts[0] = parts[0] + '-pooler';
+          poolerU.hostname = parts.join('.');
+          config.connectionString = poolerU.toString();
+          console.log('[db] Auto-optimized: Neon direct → pooler endpoint');
+        }
+      } else {
+        // Pooler endpoint — derive direct URL
+        const directU = new URL(connectionString);
+        const parts = directU.hostname.split('.');
+        if (parts[0]) {
+          parts[0] = parts[0].replace(/-pooler$/, '');
+          directU.hostname = parts.join('.');
+        }
+        config.directUrl = directU.toString();
+      }
+    }
+  } catch {
+    // Invalid URL — just pass through as-is
+  }
+
+  return config;
+}
+
 export function getSupportedDatabases(): { type: DatabaseType; label: string; group: string }[] {
   return [
     { type: 'postgres',    label: 'PostgreSQL',                  group: 'SQL' },

package/src/db/postgres.ts

@@ -31,16 +31,27 @@ export class PostgresAdapter extends DatabaseAdapter {
   readonly type = 'postgres' as const;
   private pool: any = null;
   private ended = false;
+  private _directUrl?: string;
+  private _connectionString?: string;
+  private _isPgBouncer = false;
 
   async connect(config: DatabaseConfig): Promise<void> {
     this.ended = false;
     const { Pool } = await getPg();
 
     // ── Smart pool sizing ──────────────────────────────
-    // Detect if using PgBouncer/Supabase pooler (port 6543) vs direct (5432)
-    // and auto-configure pool size accordingly.
-    const port = config.port || (config.connectionString ? new URL(config.connectionString).port : '5432');
-    const isPgBouncer = String(port) === '6543' || String(port) === '5433';
+    // Detect if using PgBouncer/Supabase pooler from port, hostname, or query params
+    const connUrl = config.connectionString ? new URL(config.connectionString) : null;
+    const port = config.port || (connUrl ? connUrl.port : '5432');
+    const hostname = connUrl?.hostname || config.host || '';
+    const isPgBouncer = String(port) === '6543' || String(port) === '5433'
+      || hostname.includes('.pooler.supabase.') || hostname.includes('.pooler.')
+      || connUrl?.searchParams.get('pgbouncer') === 'true';
+
+    // Store for migrations and reconnection
+    this._directUrl = config.directUrl || undefined;
+    this._connectionString = config.connectionString;
+    this._isPgBouncer = isPgBouncer;
 
     // Pool size logic:
     // - PgBouncer (Supabase pooler): conservative — shared across processes
@@ -49,11 +60,11 @@ export class PostgresAdapter extends DatabaseAdapter {
     // - Direct connection: more generous
     // - Override via DB_POOL_MAX env var
     const envMax = process.env.DB_POOL_MAX ? parseInt(process.env.DB_POOL_MAX, 10) : 0;
-    const defaultMax = isPgBouncer ? 4 : 10;
+    const defaultMax = isPgBouncer ? 3 : 10;
     const poolMax = envMax || defaultMax;
 
     // PgBouncer transaction mode: short idle timeout to release connections fast
-    const idleTimeout = isPgBouncer ? 5000 : 30000;
+    const idleTimeout = isPgBouncer ? 2000 : 30000;
 
     this.pool = new Pool({
       connectionString: config.connectionString,
@@ -105,16 +116,21 @@ export class PostgresAdapter extends DatabaseAdapter {
    * admin shutdown (57P01), connection refused, client already released.
    */
   private async _query(sql: string, params?: any[]): Promise<any> {
-    const RETRYABLE = new Set(['XX000', '53300', '57P01', 'ECONNREFUSED', 'ECONNRESET', '57P03']);
-    for (let attempt = 0; attempt < 2; attempt++) {
+    const RETRYABLE = new Set(['XX000', '53300', '57P01', 'ECONNREFUSED', 'ECONNRESET', '57P03', '25P02']);
+    for (let attempt = 0; attempt < 3; attempt++) {
       try {
         return await this.pool.query(sql, params);
       } catch (err: any) {
         const code = err.code || '';
         const msg = err.message || '';
-        const isRetryable = RETRYABLE.has(code) || msg.includes('remaining connection') || msg.includes('terminating connection') || msg.includes('Connection terminated');
-        if (isRetryable && attempt === 0) {
-          await new Promise(r => setTimeout(r, 500 + Math.random() * 500));
+        const isAbortedTx = code === '25P02' || msg.includes('current transaction is aborted');
+        const isRetryable = RETRYABLE.has(code) || msg.includes('remaining connection') || msg.includes('terminating connection') || msg.includes('Connection terminated') || msg.includes('MaxClientsInSessionMode');
+        if ((isRetryable || isAbortedTx) && attempt < 2) {
+          // For aborted transaction state, try to reset the connection by issuing ROLLBACK
+          if (isAbortedTx) {
+            try { await this.pool.query('ROLLBACK'); } catch {}
+          }
+          await new Promise(r => setTimeout(r, 500 + Math.random() * 1000));
           continue;
         }
         throw err;
@@ -154,7 +170,33 @@ export class PostgresAdapter extends DatabaseAdapter {
 
   async migrate(): Promise<void> {
     const stmts = getAllCreateStatements();
-    const client = await this.pool.connect();
+
+    // For PgBouncer setups, try direct URL for migrations (DDL needs real transactions)
+    // Falls back to pooler connection if direct URL is unreachable
+    let directPool: any = null;
+    let client: any;
+    if (this._isPgBouncer && this._directUrl) {
+      try {
+        const { Pool } = await getPg();
+        directPool = new Pool({
+          connectionString: this._directUrl,
+          ssl: { rejectUnauthorized: false },
+          max: 1,
+          idleTimeoutMillis: 5000,
+          connectionTimeoutMillis: 8000,
+        });
+        directPool.on('error', () => {}); // Suppress stderr noise during fallback
+        client = await directPool.connect();
+        console.log('[postgres] Using direct connection for migrations (bypassing PgBouncer)');
+      } catch (err: any) {
+        console.warn(`[postgres] Direct connection unavailable (${err.message?.slice(0, 80)}), using pooler for migrations`);
+        if (directPool) { try { await directPool.end(); } catch {} }
+        directPool = null;
+        client = await this.pool.connect();
+      }
+    } else {
+      client = await this.pool.connect();
+    }
     try {
       await client.query('BEGIN');
       for (const stmt of stmts) {
@@ -247,6 +289,9 @@ export class PostgresAdapter extends DatabaseAdapter {
       throw err;
     } finally {
       client.release();
+      if (directPool) {
+        try { await directPool.end(); } catch {}
+      }
     }
   }
 

package/src/engine/agent-autonomy.ts

@@ -360,7 +360,7 @@ export class AgentAutonomyManager {
 - ${failedChats} chat message(s) may be unanswered
 
 Your morning routine:
-1. Check your inbox with gmail_list (unread only) — scan subjects and senders
+1. Check your inbox with gmail_search (unread only) — scan subjects and senders
 2. For each important email, create a Google Task: google_tasks_create with title, notes, and priority
 3. Check Google Chat for any unanswered messages: google_chat_list_messages
 4. For any failed sessions that look important, add them as tasks too

package/src/engine/agent-heartbeat.ts

@@ -693,7 +693,7 @@ export class AgentHeartbeatManager {
 ${summaries}
 
 For each item, take the appropriate action:
-- For unread emails: Check your inbox with gmail_list and respond to any urgent ones.
+- For unread emails: Check your inbox with gmail_search and respond to any urgent ones.
 - For upcoming events: Check google_calendar_list for the next 2 hours and prepare.
 - For stale sessions: Review and close any stuck sessions.
 - For unanswered chats: Check Google Chat and respond.

package/src/engine/messaging-poller.ts

@@ -35,6 +35,7 @@ interface AgentEndpoint {
   displayName: string;
   host: string;
   port: number;
+  dataDir?: string;
 }
 
 export class MessagingPoller {
@@ -108,7 +109,8 @@ export class MessagingPoller {
           var agTgToken = chanCfg?.telegram?.botToken;
           if (agTgToken) {
             tgToken = agTgToken;
-            defaultAgent = { id: ag2.id, displayName: ag2.displayName || ag2.name || 'Agent', host: ag2.host || 'localhost', port: ag2.port || 3100 };
+            var _dataDir2 = process.env.DATA_DIR || '/tmp/agenticmail-data';
+            defaultAgent = { id: ag2.id, displayName: ag2.displayName || ag2.name || 'Agent', host: ag2.host || 'localhost', port: ag2.port || 3100, dataDir: `${_dataDir2}/agents/${ag2.id}` };
             break;
           }
         }
@@ -186,6 +188,12 @@ export class MessagingPoller {
     try {
       var { onWhatsAppMessage } = await import('../agent-tools/tools/messaging/whatsapp.js');
       var unsub = onWhatsAppMessage(agent.id, (msg) => {
+        // Build mediaFiles array for multimodal processing
+        var waMediaFiles: Array<{ path: string; type: string; mimeType?: string }> | undefined;
+        if (msg.mediaPath && msg.mediaType) {
+          var waMime = msg.mediaType === 'photo' ? 'image/jpeg' : msg.mediaType === 'video' ? 'video/mp4' : msg.mediaType === 'audio' ? 'audio/ogg' : 'application/octet-stream';
+          waMediaFiles = [{ path: msg.mediaPath, type: msg.mediaType, mimeType: waMime }];
+        }
         this.dispatch(agent, {
           source: 'whatsapp',
           senderName: msg.pushName || (msg.from?.includes('@') ? msg.from.split('@')[0] : msg.from) || 'Unknown',
@@ -194,6 +202,7 @@ export class MessagingPoller {
           isGroup: msg.isGroup,
           messageId: msg.messageId,
           isSelfChat: msg.isSelfChat,
+          mediaFiles: waMediaFiles,
         });
       });
       this.cleanups.push(unsub);
@@ -302,16 +311,140 @@ export class MessagingPoller {
 
   private handleTelegramUpdate(update: any, agent: AgentEndpoint) {
     var msg = update.message;
-    if (!msg?.text) return;
-    this.dispatch(agent, {
-      source: 'telegram',
-      senderName: [msg.from?.first_name, msg.from?.last_name].filter(Boolean).join(' ') || 'Unknown',
-      senderId: String(msg.from?.id || ''),
-      messageText: msg.text,
-      isGroup: msg.chat?.type === 'group' || msg.chat?.type === 'supergroup',
-      chatId: String(msg.chat?.id),
-      messageId: String(msg.message_id),
-    });
+    if (!msg) return;
+
+    // Extract text — could be text, caption, or empty (media-only)
+    var text = msg.text || msg.caption || '';
+
+    // Detect media
+    var mediaType: string | undefined;
+    var fileId: string | undefined;
+    var fileName: string | undefined;
+    var mimeType: string | undefined;
+
+    if (msg.photo && msg.photo.length > 0) {
+      // photo is an array of PhotoSize, pick the largest
+      mediaType = 'photo';
+      fileId = msg.photo[msg.photo.length - 1].file_id;
+    } else if (msg.video) {
+      mediaType = 'video';
+      fileId = msg.video.file_id;
+      fileName = msg.video.file_name;
+      mimeType = msg.video.mime_type;
+    } else if (msg.document) {
+      mediaType = 'document';
+      fileId = msg.document.file_id;
+      fileName = msg.document.file_name;
+      mimeType = msg.document.mime_type;
+    } else if (msg.audio) {
+      mediaType = 'audio';
+      fileId = msg.audio.file_id;
+      fileName = msg.audio.file_name;
+      mimeType = msg.audio.mime_type;
+    } else if (msg.voice) {
+      mediaType = 'voice';
+      fileId = msg.voice.file_id;
+      mimeType = msg.voice.mime_type;
+    } else if (msg.video_note) {
+      mediaType = 'video_note';
+      fileId = msg.video_note.file_id;
+    } else if (msg.sticker) {
+      mediaType = 'sticker';
+      fileId = msg.sticker.file_id;
+      text = text || `[Sticker: ${msg.sticker.emoji || ''}]`;
+    }
+
+    // Skip if no text AND no media
+    if (!text && !fileId) return;
+
+    // If we have media, download it asynchronously and build a description
+    if (fileId) {
+      this.downloadTelegramMedia(agent, fileId, mediaType!, fileName, mimeType).then((mediaInfo) => {
+        var mediaText = text;
+        var mediaFiles: Array<{ path: string; type: string; mimeType?: string }> | undefined;
+        if (mediaInfo?.localPath) {
+          var desc = `[${mediaType}${fileName ? ': ' + fileName : ''}] saved to: ${mediaInfo.localPath}`;
+          mediaText = text ? `${text}\n\n${desc}` : desc;
+          // Include media files for multimodal processing
+          var detectedMime = mimeType || (mediaType === 'photo' ? 'image/jpeg' : mediaType === 'video' ? 'video/mp4' : 'application/octet-stream');
+          mediaFiles = [{ path: mediaInfo.localPath, type: mediaType!, mimeType: detectedMime }];
+        } else if (!text) {
+          mediaText = `[${mediaType} received${fileName ? ': ' + fileName : ''}]`;
+        }
+        this.dispatch(agent, {
+          source: 'telegram',
+          senderName: [msg.from?.first_name, msg.from?.last_name].filter(Boolean).join(' ') || 'Unknown',
+          senderId: String(msg.from?.id || ''),
+          messageText: mediaText,
+          isGroup: msg.chat?.type === 'group' || msg.chat?.type === 'supergroup',
+          chatId: String(msg.chat?.id),
+          messageId: String(msg.message_id),
+          mediaFiles,
+        });
+      }).catch((dlErr) => {
+        console.error(`[messaging] Telegram media download failed:`, dlErr?.message || dlErr);
+        // Fallback: dispatch with just text description
+        this.dispatch(agent, {
+          source: 'telegram',
+          senderName: [msg.from?.first_name, msg.from?.last_name].filter(Boolean).join(' ') || 'Unknown',
+          senderId: String(msg.from?.id || ''),
+          messageText: text || `[${mediaType} received — download failed]`,
+          isGroup: msg.chat?.type === 'group' || msg.chat?.type === 'supergroup',
+          chatId: String(msg.chat?.id),
+          messageId: String(msg.message_id),
+        });
+      });
+    } else {
+      // Text-only message
+      this.dispatch(agent, {
+        source: 'telegram',
+        senderName: [msg.from?.first_name, msg.from?.last_name].filter(Boolean).join(' ') || 'Unknown',
+        senderId: String(msg.from?.id || ''),
+        messageText: text,
+        isGroup: msg.chat?.type === 'group' || msg.chat?.type === 'supergroup',
+        chatId: String(msg.chat?.id),
+        messageId: String(msg.message_id),
+      });
+    }
+  }
+
+  private async downloadTelegramMedia(agent: AgentEndpoint, fileId: string, mediaType: string, fileName?: string, mimeType?: string): Promise<{ localPath: string } | null> {
+    try {
+      var channelConfig = this.config.getAgentChannelConfig(agent.id);
+      var botToken = channelConfig?.telegram?.botToken;
+      if (!botToken) return null;
+
+      // Get file path from Telegram
+      var fileRes = await fetch(`https://api.telegram.org/bot${botToken}/getFile?file_id=${fileId}`);
+      if (!fileRes.ok) return null;
+      var fileData = await fileRes.json() as any;
+      var filePath = fileData.result?.file_path;
+      if (!filePath) return null;
+
+      // Download the file
+      var downloadUrl = `https://api.telegram.org/file/bot${botToken}/${filePath}`;
+      var response = await fetch(downloadUrl);
+      if (!response.ok) return null;
+
+      // Determine local path
+      var { join, dirname } = await import('path');
+      var { mkdirSync, writeFileSync } = await import('fs');
+      var mediaDir = join(agent.dataDir || `/tmp/agents/${agent.id}`, 'media');
+      try { mkdirSync(mediaDir, { recursive: true }); } catch {}
+
+      var ext = filePath.split('.').pop() || (mediaType === 'photo' ? 'jpg' : 'bin');
+      var localName = fileName || `${mediaType}-${Date.now()}.${ext}`;
+      var localPath = join(mediaDir, localName);
+
+      var buffer = Buffer.from(await response.arrayBuffer());
+      writeFileSync(localPath, buffer);
+
+      console.log(`[messaging] Telegram media downloaded: ${localPath} (${buffer.length} bytes)`);
+      return { localPath };
+    } catch (err: any) {
+      console.error(`[messaging] Telegram media download failed: ${err.message}`);
+      return null;
+    }
   }
 
   // ─── Trust / Authorization ─────────────────────────
@@ -369,6 +502,7 @@ export class MessagingPoller {
     source: string; senderName: string; senderId: string;
     messageText: string; isGroup?: boolean; chatId?: string; messageId?: string;
     isSelfChat?: boolean;
+    mediaFiles?: Array<{ path: string; type: string; mimeType?: string }>;
   }) {
     // Self-chat is always trusted (owner messaging themselves to talk to agent)
     if (ctx.isSelfChat) {
@@ -470,6 +604,7 @@ export class MessagingPoller {
           isCustomer: isCustomer,
           customerSystemPrompt: isCustomer ? bizCfg.customerSystemPrompt : undefined,
           restrictTools: isCustomer && bizCfg.restrictCustomerTools !== false,
+          ...(ctx.mediaFiles && ctx.mediaFiles.length > 0 ? { mediaFiles: ctx.mediaFiles } : {}),
         }),
         signal: AbortSignal.timeout(trust.isManager ? 30000 : 10000), // Manager gets longer timeout
       });