nothumanallowed 6.0.1 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nothumanallowed",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "NotHumanAllowed — 38 AI agents for security, code, DevOps, data & daily ops. Per-agent memory, Telegram + Discord auto-responder, proactive intelligence daemon, voice chat, plugin system.",
   "type": "module",
   "bin": {

package/src/commands/chat.mjs

@@ -115,12 +115,24 @@ TOOLS:
 15. notify_remind(message: string, atTime: string)
     Set a desktop reminder. atTime is ISO 8601 or relative like "in 30 minutes".
 
+16. calendar_week(startDate?: string)
+    List all events for a full week starting from startDate (YYYY-MM-DD). Defaults to current week.
+
+17. schedule_meeting(clientName: string, subject: string, location: string, durationMinutes: number, dateFrom: string, dateTo: string)
+    Find optimal meeting slots considering existing calendar, locations, and travel time between appointments.
+    Returns ranked slots with travel estimates. Use this when the user wants to schedule a new meeting.
+
+18. schedule_draft_email(clientName: string, subject: string, location: string, durationMinutes: number, dateFrom: string, dateTo: string)
+    Same as schedule_meeting but also generates a professional email proposing the top 3 slots to the client.
+
 RULES:
 - For search/read operations, execute immediately and present results conversationally.
 - For write/send/delete operations (gmail_send, gmail_reply, calendar_create, calendar_move, task_done, notify_remind), DESCRIBE what you're about to do and include the JSON block so the system can ask the user for confirmation.
+- For schedule_meeting and schedule_draft_email, execute immediately — these are read operations that suggest slots.
 - When presenting email results, show From, Subject, Date, and a brief snippet. Never dump raw JSON.
 - When presenting calendar events, show Time, Title, Location/Link. Format times in a human-readable way.
 - When presenting tasks, show ID, Description, Priority, Status.
+- When presenting slot proposals, show day, date, time range, and travel info clearly.
 - If you need multiple actions in sequence (e.g., read an email then reply), do them ONE AT A TIME — wait for the result of each before proceeding.
 - Dates: today is {{TODAY}}. Infer relative dates from this.
 - The user's timezone is {{TIMEZONE}}.
@@ -282,6 +294,63 @@ async function executeTool(action, params, config) {
       return `Reminder set for ${formatTime(atTime.toISOString())} (in ~${minutes} min): "${params.message}"`;
     }
 
+    // ── Smart Scheduling ──────────────────────────────────────────────────
+    case 'calendar_week': {
+      const { listEvents: listEventsRouter } = await import('../services/mail-router.mjs');
+      const startDate = params.startDate || new Date().toISOString().split('T')[0];
+      const from = new Date(startDate + 'T00:00:00');
+      const to = new Date(from.getTime() + 7 * 86400000);
+      const events = await listEventsRouter(config, 'primary', from, to);
+      if (events.length === 0) return `No events for the week starting ${startDate}.`;
+      const byDay = new Map();
+      for (const e of events) {
+        const day = e.start.split('T')[0];
+        if (!byDay.has(day)) byDay.set(day, []);
+        byDay.get(day).push(e);
+      }
+      const lines = [];
+      for (const [day, dayEvents] of [...byDay.entries()].sort()) {
+        const dayName = new Date(day).toLocaleDateString('en-US', { weekday: 'long' });
+        lines.push(`\n${dayName} ${day} (${dayEvents.length} events):`);
+        for (const e of dayEvents) {
+          const time = e.isAllDay ? 'All day' : `${formatTime(e.start)} - ${formatTime(e.end)}`;
+          const loc = e.location ? ` @ ${e.location}` : '';
+          lines.push(`  ${time} — ${e.summary}${loc}`);
+        }
+      }
+      return lines.join('\n');
+    }
+
+    case 'schedule_meeting': {
+      const { findAvailableSlots, formatSlotProposal } = await import('../services/smart-scheduler.mjs');
+      const slots = await findAvailableSlots(config, {
+        meetingLocation: params.location || '',
+        durationMinutes: params.durationMinutes || 60,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo,
+        workdayStart: params.workdayStart || 9,
+        workdayEnd: params.workdayEnd || 18,
+        maxSlots: 5,
+      });
+      return formatSlotProposal(slots, params.clientName || 'the client', params.subject || 'meeting');
+    }
+
+    case 'schedule_draft_email': {
+      const { findAvailableSlots: findSlots, formatSlotProposal: fmtProposal, generateSlotMessage } = await import('../services/smart-scheduler.mjs');
+      const slots = await findSlots(config, {
+        meetingLocation: params.location || '',
+        durationMinutes: params.durationMinutes || 60,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo,
+        workdayStart: 9,
+        workdayEnd: 18,
+        maxSlots: 5,
+      });
+      const proposal = fmtProposal(slots, params.clientName || 'the client', params.subject || 'meeting');
+      const email = generateSlotMessage(slots, params.clientName || 'the client', params.subject || 'meeting');
+      return `${proposal}\n\n--- DRAFT EMAIL ---\n\n${email}`;
+    }
+
     default:
       return `Unknown action: ${action}`;
   }

package/src/commands/ui.mjs

@@ -81,6 +81,15 @@ TOOLS:
 11. task_done(id: number)
     Mark a task as completed.
 
+12. calendar_week(startDate?: string)
+    List all events for a full week starting from startDate (YYYY-MM-DD). Defaults to current week.
+
+13. schedule_meeting(clientName: string, subject: string, location: string, durationMinutes: number, dateFrom: string, dateTo: string)
+    Find optimal meeting slots considering existing calendar, locations, and travel time between appointments.
+
+14. schedule_draft_email(clientName: string, subject: string, location: string, durationMinutes: number, dateFrom: string, dateTo: string)
+    Same as schedule_meeting but also generates a professional email proposing the top 3 slots.
+
 RULES:
 - For search/read operations, execute immediately and present results conversationally.
 - For write/send/delete operations, describe what you're about to do and include the JSON block.
@@ -233,6 +242,63 @@ async function executeTool(action, params, config) {
       const success = completeTask(params.id);
       return success ? `Task #${params.id} marked as done.` : `Task #${params.id} not found.`;
     }
+
+    case 'calendar_week': {
+      const { listEvents: listEventsRouter } = await import('../services/mail-router.mjs');
+      const startDate = params.startDate || new Date().toISOString().split('T')[0];
+      const from = new Date(startDate + 'T00:00:00');
+      const to = new Date(from.getTime() + 7 * 86400000);
+      const events = await listEventsRouter(config, 'primary', from, to);
+      if (events.length === 0) return `No events for the week starting ${startDate}.`;
+      const byDay = new Map();
+      for (const e of events) {
+        const day = e.start.split('T')[0];
+        if (!byDay.has(day)) byDay.set(day, []);
+        byDay.get(day).push(e);
+      }
+      const lines = [];
+      for (const [day, dayEvents] of [...byDay.entries()].sort()) {
+        const dayName = new Date(day).toLocaleDateString('en-US', { weekday: 'long' });
+        lines.push(`\n${dayName} ${day} (${dayEvents.length} events):`);
+        for (const e of dayEvents) {
+          const time = e.isAllDay ? 'All day' : `${fmtTime(e.start)} - ${fmtTime(e.end)}`;
+          const loc = e.location ? ` @ ${e.location}` : '';
+          lines.push(`  ${time} — ${e.summary}${loc}`);
+        }
+      }
+      return lines.join('\n');
+    }
+
+    case 'schedule_meeting': {
+      const { findAvailableSlots, formatSlotProposal } = await import('../services/smart-scheduler.mjs');
+      const slots = await findAvailableSlots(config, {
+        meetingLocation: params.location || '',
+        durationMinutes: params.durationMinutes || 60,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo,
+        workdayStart: params.workdayStart || 9,
+        workdayEnd: params.workdayEnd || 18,
+        maxSlots: 5,
+      });
+      return formatSlotProposal(slots, params.clientName || 'the client', params.subject || 'meeting');
+    }
+
+    case 'schedule_draft_email': {
+      const { findAvailableSlots: findSlots, formatSlotProposal: fmtProposal, generateSlotMessage } = await import('../services/smart-scheduler.mjs');
+      const slots = await findSlots(config, {
+        meetingLocation: params.location || '',
+        durationMinutes: params.durationMinutes || 60,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo,
+        workdayStart: 9,
+        workdayEnd: 18,
+        maxSlots: 5,
+      });
+      const proposal = fmtProposal(slots, params.clientName || 'the client', params.subject || 'meeting');
+      const email = generateSlotMessage(slots, params.clientName || 'the client', params.subject || 'meeting');
+      return `${proposal}\n\n--- DRAFT EMAIL ---\n\n${email}`;
+    }
+
     default:
       return `Unknown action: ${action}`;
   }

package/src/commands/voice.mjs

@@ -71,6 +71,12 @@ TOOLS:
 10. task_done(id: number)
     Mark a task as completed.
 
+11. calendar_week(startDate?: string)
+    List all events for a full week. Defaults to current week.
+
+12. schedule_meeting(clientName: string, subject: string, location: string, durationMinutes: number, dateFrom: string, dateTo: string)
+    Find optimal meeting slots considering calendar, locations, and travel time.
+
 RULES:
 - For search/read operations, execute immediately and present results conversationally.
 - For write/send/delete operations, describe what you're about to do and include the JSON block.
@@ -184,6 +190,28 @@ async function executeTool(action, params, config) {
       const success = completeTask(params.id);
       return success ? `Task ${params.id} marked as done.` : `Task ${params.id} not found.`;
     }
+    case 'calendar_week': {
+      const { listEvents: lr } = await import('../services/mail-router.mjs');
+      const startDate = params.startDate || new Date().toISOString().split('T')[0];
+      const from = new Date(startDate + 'T00:00:00');
+      const to = new Date(from.getTime() + 7 * 86400000);
+      const events = await lr(config, 'primary', from, to);
+      if (events.length === 0) return `No events for the week starting ${startDate}.`;
+      return events.map((e, i) => `${i + 1}. ${e.start.split('T')[0]} ${fmtTime(e.start)}, ${e.summary}${e.location ? ' at ' + e.location : ''}`).join('\n');
+    }
+    case 'schedule_meeting': {
+      const { findAvailableSlots, formatSlotProposal } = await import('../services/smart-scheduler.mjs');
+      const slots = await findAvailableSlots(config, {
+        meetingLocation: params.location || '',
+        durationMinutes: params.durationMinutes || 60,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo,
+        workdayStart: 9,
+        workdayEnd: 18,
+        maxSlots: 3,
+      });
+      return formatSlotProposal(slots, params.clientName || 'the client', params.subject || 'meeting');
+    }
     default:
       return `Unknown action: ${action}`;
   }

package/src/constants.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-export const VERSION = '6.0.1';
+export const VERSION = '6.1.0';
 export const BASE_URL = 'https://nothumanallowed.com/cli';
 export const API_BASE = 'https://nothumanallowed.com/api/v1';
 

package/src/services/smart-scheduler.mjs

@@ -0,0 +1,409 @@
+/**
+ * Smart Scheduler — finds optimal meeting slots considering existing calendar
+ * events, locations, and travel time estimates.
+ *
+ * Zero dependencies. Uses Google Calendar / Outlook data already fetched
+ * via mail-router.mjs.
+ *
+ * Travel time estimation:
+ * - Same city: 30 min buffer
+ * - Different city (< 200km): 90 min buffer
+ * - Different city (> 200km): 180 min buffer
+ * - Remote/virtual (no location): 15 min buffer
+ * - No location on both: 0 min buffer
+ */
+
+import { listEvents } from './mail-router.mjs';
+
+// ── Travel Time Estimation ──────────────────────────────────────────────────
+
+/**
+ * Well-known Italian cities with approximate lat/lon for distance estimation.
+ * Covers the major cities. Falls back to "different city" for unknown locations.
+ */
+const CITY_COORDS = {
+  'milano': { lat: 45.46, lon: 9.19 },
+  'milan': { lat: 45.46, lon: 9.19 },
+  'roma': { lat: 41.90, lon: 12.50 },
+  'rome': { lat: 41.90, lon: 12.50 },
+  'napoli': { lat: 40.85, lon: 14.27 },
+  'naples': { lat: 40.85, lon: 14.27 },
+  'torino': { lat: 45.07, lon: 7.69 },
+  'turin': { lat: 45.07, lon: 7.69 },
+  'firenze': { lat: 43.77, lon: 11.25 },
+  'florence': { lat: 43.77, lon: 11.25 },
+  'bologna': { lat: 44.49, lon: 11.34 },
+  'genova': { lat: 44.41, lon: 8.93 },
+  'genoa': { lat: 44.41, lon: 8.93 },
+  'venezia': { lat: 45.44, lon: 12.32 },
+  'venice': { lat: 45.44, lon: 12.32 },
+  'verona': { lat: 45.44, lon: 10.99 },
+  'padova': { lat: 45.41, lon: 11.88 },
+  'trieste': { lat: 45.65, lon: 13.78 },
+  'brescia': { lat: 45.54, lon: 10.21 },
+  'parma': { lat: 44.80, lon: 10.33 },
+  'modena': { lat: 44.65, lon: 10.93 },
+  'reggio emilia': { lat: 44.70, lon: 10.63 },
+  'reggio': { lat: 44.70, lon: 10.63 },
+  'piacenza': { lat: 45.05, lon: 9.69 },
+  'ferrara': { lat: 44.84, lon: 11.62 },
+  'ravenna': { lat: 44.42, lon: 12.20 },
+  'rimini': { lat: 44.06, lon: 12.57 },
+  'perugia': { lat: 43.11, lon: 12.39 },
+  'bari': { lat: 41.13, lon: 16.87 },
+  'catania': { lat: 37.50, lon: 15.09 },
+  'palermo': { lat: 38.12, lon: 13.36 },
+  'cagliari': { lat: 39.22, lon: 9.12 },
+  'bergamo': { lat: 45.69, lon: 9.67 },
+  'como': { lat: 45.81, lon: 9.08 },
+  'monza': { lat: 45.58, lon: 9.27 },
+  'vicenza': { lat: 45.55, lon: 11.55 },
+  'treviso': { lat: 45.67, lon: 12.24 },
+  'udine': { lat: 46.07, lon: 13.24 },
+  'ancona': { lat: 43.62, lon: 13.52 },
+  'pescara': { lat: 42.46, lon: 14.21 },
+  'lecce': { lat: 40.35, lon: 18.17 },
+  'salerno': { lat: 40.68, lon: 14.77 },
+  'sassari': { lat: 40.73, lon: 8.56 },
+  'trento': { lat: 46.07, lon: 11.12 },
+  'bolzano': { lat: 46.50, lon: 11.35 },
+  'aosta': { lat: 45.74, lon: 7.32 },
+  'london': { lat: 51.51, lon: -0.13 },
+  'paris': { lat: 48.86, lon: 2.35 },
+  'berlin': { lat: 52.52, lon: 13.41 },
+  'amsterdam': { lat: 52.37, lon: 4.90 },
+  'zurich': { lat: 47.38, lon: 8.54 },
+  'munich': { lat: 48.14, lon: 11.58 },
+  'vienna': { lat: 48.21, lon: 16.37 },
+  'barcelona': { lat: 41.39, lon: 2.17 },
+  'madrid': { lat: 40.42, lon: -3.70 },
+  'lisbon': { lat: 38.72, lon: -9.14 },
+  'new york': { lat: 40.71, lon: -74.01 },
+  'san francisco': { lat: 37.77, lon: -122.42 },
+};
+
+const VIRTUAL_KEYWORDS = [
+  'zoom', 'meet', 'teams', 'webex', 'hangout', 'remote', 'online',
+  'virtual', 'call', 'video', 'teleconferenza', 'videocall',
+  'google meet', 'skype', 'slack huddle',
+];
+
+/**
+ * Extract city name from a location string.
+ * @param {string} location
+ * @returns {string|null}
+ */
+function extractCity(location) {
+  if (!location) return null;
+  const lower = location.toLowerCase();
+
+  // Check for virtual meeting
+  for (const kw of VIRTUAL_KEYWORDS) {
+    if (lower.includes(kw)) return '__virtual__';
+  }
+
+  // Try to find a known city in the location string
+  for (const [city] of Object.entries(CITY_COORDS)) {
+    if (lower.includes(city)) return city;
+  }
+
+  // Try comma-separated parts (e.g., "Via Roma 123, Milano, MI")
+  const parts = location.split(',').map(p => p.trim().toLowerCase());
+  for (const part of parts) {
+    for (const [city] of Object.entries(CITY_COORDS)) {
+      if (part === city || part.startsWith(city + ' ') || part.endsWith(' ' + city)) {
+        return city;
+      }
+    }
+  }
+
+  // Unknown location — treat as physical but unknown city
+  return '__unknown__';
+}
+
+/**
+ * Haversine distance between two lat/lon points in km.
+ */
+function haversineKm(lat1, lon1, lat2, lon2) {
+  const R = 6371;
+  const dLat = (lat2 - lat1) * Math.PI / 180;
+  const dLon = (lon2 - lon1) * Math.PI / 180;
+  const a = Math.sin(dLat / 2) ** 2 +
+    Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
+    Math.sin(dLon / 2) ** 2;
+  return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+
+/**
+ * Estimate travel time in minutes between two locations.
+ * @param {string} fromLocation
+ * @param {string} toLocation
+ * @returns {{ minutes: number, label: string }}
+ */
+export function estimateTravelTime(fromLocation, toLocation) {
+  const fromCity = extractCity(fromLocation);
+  const toCity = extractCity(toLocation);
+
+  // No location on either side — no buffer needed
+  if (!fromCity && !toCity) return { minutes: 0, label: 'no travel' };
+
+  // Virtual meetings — minimal buffer
+  if (fromCity === '__virtual__' || toCity === '__virtual__') {
+    return { minutes: 15, label: '15 min buffer (virtual)' };
+  }
+
+  // One side has no location — assume 30 min buffer
+  if (!fromCity || !toCity || fromCity === '__unknown__' || toCity === '__unknown__') {
+    return { minutes: 30, label: '30 min buffer (location unknown)' };
+  }
+
+  // Same city
+  if (fromCity === toCity) {
+    return { minutes: 30, label: `30 min (same city: ${fromCity})` };
+  }
+
+  // Different known cities — calculate distance
+  const fromCoords = CITY_COORDS[fromCity];
+  const toCoords = CITY_COORDS[toCity];
+
+  if (fromCoords && toCoords) {
+    const km = haversineKm(fromCoords.lat, fromCoords.lon, toCoords.lat, toCoords.lon);
+
+    if (km < 50) return { minutes: 45, label: `45 min (~${Math.round(km)}km: ${fromCity} → ${toCity})` };
+    if (km < 150) return { minutes: 90, label: `90 min (~${Math.round(km)}km: ${fromCity} → ${toCity})` };
+    if (km < 400) return { minutes: 150, label: `2.5h (~${Math.round(km)}km: ${fromCity} → ${toCity})` };
+    return { minutes: 240, label: `4h+ (~${Math.round(km)}km: ${fromCity} → ${toCity}) — consider video call` };
+  }
+
+  // Fallback: different city, unknown distance
+  return { minutes: 90, label: `90 min (${fromCity} → ${toCity})` };
+}
+
+// ── Slot Finder ─────────────────────────────────────────────────────────────
+
+/**
+ * Find available meeting slots in a date range, considering travel time.
+ *
+ * @param {object} config — NHA config (for calendar API access)
+ * @param {object} params
+ * @param {string} params.meetingLocation — where the new meeting will be
+ * @param {number} params.durationMinutes — meeting duration
+ * @param {string} params.dateFrom — YYYY-MM-DD start of search range
+ * @param {string} params.dateTo — YYYY-MM-DD end of search range
+ * @param {number} [params.workdayStart=9] — earliest hour (0-23)
+ * @param {number} [params.workdayEnd=18] — latest hour (0-23)
+ * @param {number} [params.maxSlots=5] — max slots to return
+ * @returns {Promise<Array<{start: string, end: string, date: string, day: string, travelBefore: object, travelAfter: object, score: number}>>}
+ */
+export async function findAvailableSlots(config, params) {
+  const {
+    meetingLocation = '',
+    durationMinutes = 60,
+    dateFrom,
+    dateTo,
+    workdayStart = 9,
+    workdayEnd = 18,
+    maxSlots = 5,
+  } = params;
+
+  // Fetch all events in the date range
+  const from = new Date(dateFrom + 'T00:00:00');
+  const to = new Date(dateTo + 'T23:59:59');
+  const events = await listEvents(config, 'primary', from, to);
+
+  // Group events by date
+  const eventsByDate = new Map();
+  for (const event of events) {
+    if (event.isAllDay) continue; // skip all-day events
+    const dateKey = event.start.split('T')[0];
+    if (!eventsByDate.has(dateKey)) eventsByDate.set(dateKey, []);
+    eventsByDate.get(dateKey).push(event);
+  }
+
+  const slots = [];
+  const durationMs = durationMinutes * 60000;
+
+  // Iterate each day in range
+  const current = new Date(from);
+  while (current <= to && slots.length < maxSlots * 2) {
+    const dayOfWeek = current.getDay();
+    // Skip weekends
+    if (dayOfWeek === 0 || dayOfWeek === 6) {
+      current.setDate(current.getDate() + 1);
+      continue;
+    }
+
+    const dateKey = current.toISOString().split('T')[0];
+    const dayName = current.toLocaleDateString('en-US', { weekday: 'long' });
+    const dayEvents = (eventsByDate.get(dateKey) || [])
+      .sort((a, b) => new Date(a.start).getTime() - new Date(b.start).getTime());
+
+    // Build busy blocks with travel buffers
+    const busyBlocks = [];
+    for (const event of dayEvents) {
+      const eventStart = new Date(event.start).getTime();
+      const eventEnd = new Date(event.end).getTime();
+
+      // Travel time FROM previous location TO this event
+      const travelTo = estimateTravelTime(meetingLocation, event.location);
+      // Travel time FROM this event TO meeting location
+      const travelFrom = estimateTravelTime(event.location, meetingLocation);
+
+      busyBlocks.push({
+        start: eventStart - travelTo.minutes * 60000, // need to arrive before
+        end: eventEnd + travelFrom.minutes * 60000,   // need travel time after
+        eventStart,
+        eventEnd,
+        summary: event.summary,
+        location: event.location,
+        travelTo,
+        travelFrom,
+      });
+    }
+
+    // Find free windows in the workday
+    const workStart = new Date(dateKey + `T${String(workdayStart).padStart(2, '0')}:00:00`).getTime();
+    const workEnd = new Date(dateKey + `T${String(workdayEnd).padStart(2, '0')}:00:00`).getTime();
+
+    // Merge overlapping busy blocks
+    const merged = [];
+    for (const block of busyBlocks.sort((a, b) => a.start - b.start)) {
+      if (merged.length > 0 && block.start <= merged[merged.length - 1].end) {
+        merged[merged.length - 1].end = Math.max(merged[merged.length - 1].end, block.end);
+      } else {
+        merged.push({ ...block });
+      }
+    }
+
+    // Find gaps
+    let cursor = workStart;
+    for (const block of merged) {
+      if (block.start > cursor) {
+        const gapDuration = block.start - cursor;
+        if (gapDuration >= durationMs) {
+          // Find the event BEFORE this gap (for travel info)
+          const prevEvent = dayEvents.find(e => new Date(e.end).getTime() <= cursor + 60000);
+          const nextEvent = dayEvents.find(e => new Date(e.start).getTime() >= block.eventStart - 60000);
+
+          const travelBefore = prevEvent
+            ? estimateTravelTime(prevEvent.location, meetingLocation)
+            : { minutes: 0, label: 'no previous event' };
+          const travelAfter = nextEvent
+            ? estimateTravelTime(meetingLocation, nextEvent.location)
+            : { minutes: 0, label: 'no next event' };
+
+          const slotStart = new Date(cursor + travelBefore.minutes * 60000);
+          const slotEnd = new Date(slotStart.getTime() + durationMs);
+
+          // Make sure slot fits before the next busy block
+          if (slotEnd.getTime() + travelAfter.minutes * 60000 <= block.start) {
+            // Score: prefer morning, prefer no travel, prefer earlier in the week
+            const hour = slotStart.getHours();
+            const hourScore = hour >= 9 && hour <= 11 ? 10 : hour >= 14 && hour <= 16 ? 8 : 5;
+            const travelScore = Math.max(0, 10 - (travelBefore.minutes + travelAfter.minutes) / 15);
+            const score = hourScore + travelScore;
+
+            slots.push({
+              start: slotStart.toISOString(),
+              end: slotEnd.toISOString(),
+              date: dateKey,
+              day: dayName,
+              startTime: slotStart.toLocaleTimeString('it-IT', { hour: '2-digit', minute: '2-digit' }),
+              endTime: slotEnd.toLocaleTimeString('it-IT', { hour: '2-digit', minute: '2-digit' }),
+              travelBefore,
+              travelAfter,
+              score,
+            });
+          }
+        }
+      }
+      cursor = Math.max(cursor, block.end);
+    }
+
+    // Check gap after last event
+    if (cursor < workEnd) {
+      const gapDuration = workEnd - cursor;
+      if (gapDuration >= durationMs) {
+        const lastEvent = dayEvents[dayEvents.length - 1];
+        const travelBefore = lastEvent
+          ? estimateTravelTime(lastEvent.location, meetingLocation)
+          : { minutes: 0, label: 'no previous event' };
+
+        const slotStart = new Date(cursor + travelBefore.minutes * 60000);
+        const slotEnd = new Date(slotStart.getTime() + durationMs);
+
+        if (slotEnd.getTime() <= workEnd) {
+          const hour = slotStart.getHours();
+          const hourScore = hour >= 9 && hour <= 11 ? 10 : hour >= 14 && hour <= 16 ? 8 : 5;
+          const travelScore = Math.max(0, 10 - travelBefore.minutes / 15);
+
+          slots.push({
+            start: slotStart.toISOString(),
+            end: slotEnd.toISOString(),
+            date: dateKey,
+            day: dayName,
+            startTime: slotStart.toLocaleTimeString('it-IT', { hour: '2-digit', minute: '2-digit' }),
+            endTime: slotEnd.toLocaleTimeString('it-IT', { hour: '2-digit', minute: '2-digit' }),
+            travelBefore,
+            travelAfter: { minutes: 0, label: 'end of day' },
+            score: hourScore + travelScore,
+          });
+        }
+      }
+    }
+
+    current.setDate(current.getDate() + 1);
+  }
+
+  // Sort by score (highest first), take top N
+  slots.sort((a, b) => b.score - a.score);
+  return slots.slice(0, maxSlots);
+}
+
+/**
+ * Format slots into a human-readable proposal string.
+ */
+export function formatSlotProposal(slots, clientName, meetingSubject) {
+  if (slots.length === 0) {
+    return 'No available slots found in the requested date range. Try expanding the range or shortening the meeting duration.';
+  }
+
+  const lines = [`Found ${slots.length} optimal slot${slots.length > 1 ? 's' : ''} for "${meetingSubject}" with ${clientName}:\n`];
+
+  for (let i = 0; i < slots.length; i++) {
+    const s = slots[i];
+    lines.push(`${i + 1}. ${s.day} ${s.date} — ${s.startTime} to ${s.endTime}`);
+    if (s.travelBefore.minutes > 0) {
+      lines.push(`   Travel before: ${s.travelBefore.label}`);
+    }
+    if (s.travelAfter.minutes > 0) {
+      lines.push(`   Travel after: ${s.travelAfter.label}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate a professional email/message proposing slots to a client.
+ */
+export function generateSlotMessage(slots, clientName, meetingSubject, senderName) {
+  if (slots.length === 0) return '';
+
+  const slotLines = slots.slice(0, 3).map((s, i) => {
+    return `  ${i + 1}. ${s.day} ${s.date}, ${s.startTime} - ${s.endTime}`;
+  });
+
+  return `Gentile ${clientName},
+
+Le scrivo per fissare un incontro riguardo "${meetingSubject}".
+
+In base alla mia disponibilità, Le propongo le seguenti opzioni:
+
+${slotLines.join('\n')}
+
+Mi faccia sapere quale opzione Le è più comoda, o se preferisce suggerire un orario alternativo.
+
+Cordiali saluti,
+${senderName || 'Il team'}`;
+}

package/src/services/tool-executor.mjs

@@ -18,8 +18,15 @@ import {
   getEventsForDate,
   createEvent,
   updateEvent,
+  listEvents,
 } from './mail-router.mjs';
 
+import {
+  findAvailableSlots,
+  formatSlotProposal,
+  generateSlotMessage,
+} from './smart-scheduler.mjs';
+
 import {
   getTasks,
   addTask,
@@ -107,6 +114,15 @@ TOOLS:
 15. notify_remind(message: string, atTime: string)
     Set a desktop reminder. atTime is ISO 8601 or relative like "in 30 minutes".
 
+16. calendar_week(startDate?: string)
+    List all events for a full week starting from startDate (YYYY-MM-DD). Defaults to current week.
+
+17. schedule_meeting(clientName: string, subject: string, location: string, durationMinutes: number, dateFrom: string, dateTo: string, workdayStart?: number, workdayEnd?: number)
+    Find optimal meeting slots considering existing calendar events, locations, and estimated travel time between appointments. Returns ranked slots with travel info. dateFrom and dateTo are YYYY-MM-DD.
+
+18. schedule_draft_email(clientName: string, subject: string, location: string, durationMinutes: number, dateFrom: string, dateTo: string)
+    Same as schedule_meeting, but also generates a professional email proposing the top 3 slots to the client. Returns both the slots and a ready-to-send email draft.
+
 RULES:
 - For search/read operations, execute immediately and present results conversationally.
 - For write/send/delete operations (gmail_send, gmail_reply, calendar_create, calendar_move, task_done, notify_remind), DESCRIBE what you're about to do and include the JSON block so the system can ask the user for confirmation.
@@ -386,6 +402,66 @@ export async function executeTool(action, params, config) {
       return `Reminder set for ${formatTime(atTime.toISOString())} (in ~${minutes} min): "${params.message}"`;
     }
 
+    // ── Calendar Week ───────────────────────────────────────────────────
+    case 'calendar_week': {
+      const startDate = params.startDate || new Date().toISOString().split('T')[0];
+      const from = new Date(startDate + 'T00:00:00');
+      const to = new Date(from.getTime() + 7 * 86400000);
+      const events = await listEvents(config, 'primary', from, to);
+      if (events.length === 0) return `No events found for the week starting ${startDate}.`;
+
+      // Group by day
+      const byDay = new Map();
+      for (const e of events) {
+        const day = e.start.split('T')[0];
+        if (!byDay.has(day)) byDay.set(day, []);
+        byDay.get(day).push(e);
+      }
+
+      const lines = [];
+      for (const [day, dayEvents] of [...byDay.entries()].sort()) {
+        const dayName = new Date(day).toLocaleDateString('en-US', { weekday: 'long' });
+        lines.push(`\n${dayName} ${day} (${dayEvents.length} events):`);
+        for (const e of dayEvents) {
+          const time = e.isAllDay ? 'All day' : `${formatTime(e.start)} - ${formatTime(e.end)}`;
+          const loc = e.location ? ` @ ${e.location}` : '';
+          lines.push(`  ${time} — ${e.summary}${loc}`);
+        }
+      }
+      return lines.join('\n');
+    }
+
+    // ── Smart Scheduling ──────────────────────────────────────────────────
+    case 'schedule_meeting': {
+      const slots = await findAvailableSlots(config, {
+        meetingLocation: params.location || '',
+        durationMinutes: params.durationMinutes || 60,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo,
+        workdayStart: params.workdayStart || 9,
+        workdayEnd: params.workdayEnd || 18,
+        maxSlots: 5,
+      });
+      return formatSlotProposal(slots, params.clientName || 'the client', params.subject || 'meeting');
+    }
+
+    case 'schedule_draft_email': {
+      const slots = await findAvailableSlots(config, {
+        meetingLocation: params.location || '',
+        durationMinutes: params.durationMinutes || 60,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo,
+        workdayStart: 9,
+        workdayEnd: 18,
+        maxSlots: 5,
+      });
+
+      const proposal = formatSlotProposal(slots, params.clientName || 'the client', params.subject || 'meeting');
+      const email = generateSlotMessage(slots, params.clientName || 'the client', params.subject || 'meeting');
+
+      return `${proposal}\n\n--- DRAFT EMAIL ---\n\n${email}`;
+    }
+
     default:
       return `Unknown action: ${action}`;
   }