kernelbot 1.0.34 → 1.0.35

package/src/utils/ids.js

@@ -0,0 +1,12 @@
+import { randomBytes } from 'crypto';
+
+/**
+ * Generate a short, unique ID with a given prefix.
+ * Format: `<prefix>_<8-hex-chars>` (e.g. "evo_a3f1b2c4").
+ *
+ * @param {string} prefix - Short prefix for the ID (e.g. 'evo', 'sh', 'imp', 'ep')
+ * @returns {string} Unique identifier
+ */
+export function genId(prefix) {
+  return `${prefix}_${randomBytes(4).toString('hex')}`;
+}

package/src/utils/temporal-awareness.js

@@ -0,0 +1,199 @@
+/**
+ * Temporal & Spatial Awareness Engine
+ *
+ * Reads a local (git-ignored) config file to dynamically inject
+ * the owner's real-time context into every LLM call:
+ *   - Current local time in the owner's timezone
+ *   - Whether they are currently within working hours
+ *   - Location context
+ *   - Day-of-week and date context
+ *
+ * The local config file (local_context.json) is NEVER committed.
+ * Only this generic algorithm ships with the repo.
+ */
+
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { getLogger } from './logger.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LOCAL_CONTEXT_PATH = join(__dirname, '..', '..', 'local_context.json');
+
+/** Cache the loaded config (reloaded on file change via mtime check). */
+let _cache = null;
+let _cacheMtime = 0;
+
+/**
+ * Load the local context config.
+ * Returns null if the file doesn't exist (non-personal deployments).
+ */
+function loadLocalContext() {
+  try {
+    if (!existsSync(LOCAL_CONTEXT_PATH)) return null;
+
+    const stat = statSync(LOCAL_CONTEXT_PATH);
+    if (_cache && stat.mtimeMs === _cacheMtime) return _cache;
+
+    const raw = readFileSync(LOCAL_CONTEXT_PATH, 'utf-8');
+    _cache = JSON.parse(raw);
+    _cacheMtime = stat.mtimeMs;
+    return _cache;
+  } catch (err) {
+    const logger = getLogger();
+    logger.debug(`[TemporalAwareness] Could not load local_context.json: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Format a Date in a human-friendly way for a given timezone.
+ */
+function formatTime(date, timezone, locale = 'en-US') {
+  return date.toLocaleString(locale, {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: true,
+    timeZone: timezone,
+  });
+}
+
+/**
+ * Get the current hour (0-23) in the given timezone.
+ */
+function getCurrentHour(date, timezone) {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    hour: 'numeric',
+    hour12: false,
+    timeZone: timezone,
+  }).formatToParts(date);
+  const hourPart = parts.find(p => p.type === 'hour');
+  return parseInt(hourPart?.value || '0', 10);
+}
+
+/**
+ * Get the current day of week (0=Sun, 1=Mon, ..., 6=Sat) in the given timezone.
+ */
+function getCurrentDayOfWeek(date, timezone) {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    weekday: 'short',
+    timeZone: timezone,
+  }).formatToParts(date);
+  const dayStr = parts.find(p => p.type === 'weekday')?.value || '';
+  const dayMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  return dayMap[dayStr] ?? -1;
+}
+
+/**
+ * Determine the user's current status based on time, day, and working hours.
+ */
+function determineStatus(hour, dayOfWeek, workingHours) {
+  if (!workingHours) return { status: 'unknown', detail: '' };
+
+  const { start, end, days } = workingHours;
+  const isWorkDay = days ? days.includes(dayOfWeek) : (dayOfWeek >= 0 && dayOfWeek <= 4);
+  const isWorkHour = hour >= start && hour < end;
+
+  if (!isWorkDay) {
+    return { status: 'day_off', detail: 'Weekend / day off' };
+  }
+
+  if (isWorkHour) {
+    return { status: 'working', detail: `At work (${workingHours.label || `${start}:00–${end}:00`})` };
+  }
+
+  // Outside working hours on a work day
+  if (hour < start) {
+    const hoursUntilWork = start - hour;
+    return { status: 'before_work', detail: `Before work — starts in ~${hoursUntilWork}h` };
+  }
+
+  return { status: 'after_work', detail: 'Off work for the day' };
+}
+
+/**
+ * Determine the likely activity period for more nuanced awareness.
+ */
+function determineActivityPeriod(hour) {
+  if (hour >= 0 && hour < 5) return 'late_night';
+  if (hour >= 5 && hour < 7) return 'early_morning';
+  if (hour >= 7 && hour < 12) return 'morning';
+  if (hour >= 12 && hour < 14) return 'midday';
+  if (hour >= 14 && hour < 17) return 'afternoon';
+  if (hour >= 17 && hour < 20) return 'evening';
+  if (hour >= 20 && hour < 23) return 'night';
+  return 'late_night';
+}
+
+/**
+ * Build the temporal & spatial awareness string to inject into the system prompt.
+ *
+ * Returns a formatted context block, or null if no local config is found.
+ *
+ * Example output:
+ *   ## Owner's Real-Time Context
+ *   - Local Time: Monday, March 10, 2025, 02:15:30 AM (Asia/Riyadh)
+ *   - Location: Riyadh, Saudi Arabia
+ *   - Status: Off work — next shift at 10:00 AM
+ *   - Period: Late night
+ *
+ *   IMPORTANT: Adjust your tone and assumptions to the owner's current time.
+ *   Do NOT assume they are at work during off-hours or sleeping during work hours.
+ */
+export function buildTemporalAwareness() {
+  const ctx = loadLocalContext();
+  if (!ctx?.owner) return null;
+
+  const logger = getLogger();
+  const { owner } = ctx;
+  const now = new Date();
+
+  const timezone = owner.timezone || 'UTC';
+  const locale = owner.locale || 'en-US';
+  const location = owner.location
+    ? `${owner.location.city}, ${owner.location.country}`
+    : null;
+
+  const formattedTime = formatTime(now, timezone, locale);
+  const currentHour = getCurrentHour(now, timezone);
+  const currentDay = getCurrentDayOfWeek(now, timezone);
+  const { status, detail } = determineStatus(currentHour, currentDay, owner.working_hours);
+  const period = determineActivityPeriod(currentHour);
+
+  const lines = [
+    `## Owner's Real-Time Context`,
+    `- **Local Time**: ${formattedTime}`,
+  ];
+
+  if (location) {
+    lines.push(`- **Location**: ${location}`);
+  }
+
+  if (owner.name) {
+    lines.push(`- **Name**: ${owner.name}`);
+  }
+
+  lines.push(`- **Work Status**: ${detail || status}`);
+  lines.push(`- **Period**: ${period.replace('_', ' ')}`);
+
+  if (owner.working_hours) {
+    const wh = owner.working_hours;
+    lines.push(`- **Working Hours**: ${wh.start}:00–${wh.end}:00${wh.label ? ` (${wh.label})` : ''}`);
+  }
+
+  lines.push('');
+  lines.push('IMPORTANT: Be aware of the owner\'s current local time and status.');
+  lines.push('Do NOT assume they are at work during off-hours, or sleeping during work hours.');
+  lines.push('Adjust greetings, tone, and context to match their real-time situation.');
+
+  const block = lines.join('\n');
+
+  logger.debug(`[TemporalAwareness] ${timezone} | hour=${currentHour} day=${currentDay} | status=${status} period=${period}`);
+
+  return block;
+}

package/src/utils/timeUtils.js

@@ -0,0 +1,110 @@
+/**
+ * Quiet Hours utility — configurable "Do Not Disturb" schedule.
+ *
+ * Resolution order (first defined wins):
+ *   1. Environment variables  QUIET_HOURS_START / QUIET_HOURS_END  (HH:mm)
+ *   2. YAML config values     config.life.quiet_hours.start / .end (integer hour)
+ *   3. Built-in defaults      02:00 – 06:00
+ *
+ * If neither variable is set, quiet hours are disabled (returns false).
+ */
+
+/** Default quiet-hours window (integer hours). */
+const DEFAULT_START = 2;
+const DEFAULT_END = 6;
+
+/**
+ * Resolve the active quiet-hours window into a normalised { startMinutes, endMinutes } pair.
+ * Both values are in "minutes since midnight" (0 – 1439).
+ *
+ * @param {object} [lifeConfig] - Optional `config.life` object from YAML.
+ * @returns {{ startMinutes: number, endMinutes: number }}
+ */
+function resolveWindow(lifeConfig) {
+  const envStart = process.env.QUIET_HOURS_START;
+  const envEnd = process.env.QUIET_HOURS_END;
+
+  if (envStart && envEnd) {
+    const [startH, startM] = envStart.split(':').map(Number);
+    const [endH, endM] = envEnd.split(':').map(Number);
+
+    if (!isNaN(startH) && !isNaN(startM) && !isNaN(endH) && !isNaN(endM)) {
+      return { startMinutes: startH * 60 + startM, endMinutes: endH * 60 + endM };
+    }
+  }
+
+  const startHour = lifeConfig?.quiet_hours?.start ?? DEFAULT_START;
+  const endHour = lifeConfig?.quiet_hours?.end ?? DEFAULT_END;
+  return { startMinutes: startHour * 60, endMinutes: endHour * 60 };
+}
+
+/**
+ * Check whether a given "minutes since midnight" value falls inside a quiet window.
+ *
+ * @param {number} current - Current minutes since midnight.
+ * @param {number} start   - Window start (minutes since midnight).
+ * @param {number} end     - Window end   (minutes since midnight).
+ * @returns {boolean}
+ */
+function insideWindow(current, start, end) {
+  if (start <= end) {
+    return current >= start && current < end;
+  }
+  // Window crosses midnight (e.g. 22:00 – 06:00)
+  return current >= start || current < end;
+}
+
+/**
+ * Check whether the current time falls within "quiet hours".
+ *
+ * @param {object} [lifeConfig] - Optional `config.life` object from YAML.
+ *   When provided, `lifeConfig.quiet_hours.start` / `.end` (integer hours)
+ *   act as the second-priority source before the hardcoded defaults.
+ * @returns {boolean} `true` when the current time is inside the quiet window.
+ */
+export function isQuietHours(lifeConfig) {
+  const { startMinutes, endMinutes } = resolveWindow(lifeConfig);
+  const now = new Date();
+  const currentMinutes = now.getHours() * 60 + now.getMinutes();
+  return insideWindow(currentMinutes, startMinutes, endMinutes);
+}
+
+/**
+ * Return the resolved quiet-hours configuration for logging / status display.
+ *
+ * @param {object} [lifeConfig] - Optional `config.life` object from YAML.
+ * @returns {{ start: string, end: string, active: boolean }}
+ *   `start` / `end` are formatted as "HH:MM", `active` reflects the current state.
+ */
+export function getQuietHoursConfig(lifeConfig) {
+  const { startMinutes, endMinutes } = resolveWindow(lifeConfig);
+  const pad = (n) => String(n).padStart(2, '0');
+  const fmt = (m) => `${pad(Math.floor(m / 60))}:${pad(m % 60)}`;
+  return {
+    start: fmt(startMinutes),
+    end: fmt(endMinutes),
+    active: isQuietHours(lifeConfig),
+  };
+}
+
+/**
+ * Calculate the number of milliseconds remaining until the current quiet-hours
+ * window ends.  Returns `0` when quiet hours are not active.
+ *
+ * Useful for deferring non-essential work until the window closes.
+ *
+ * @param {object} [lifeConfig] - Optional `config.life` object from YAML.
+ * @returns {number} Milliseconds until quiet hours end (0 if not currently quiet).
+ */
+export function msUntilQuietEnd(lifeConfig) {
+  if (!isQuietHours(lifeConfig)) return 0;
+
+  const { endMinutes } = resolveWindow(lifeConfig);
+  const now = new Date();
+  const currentMinutes = now.getHours() * 60 + now.getMinutes();
+
+  let diff = endMinutes - currentMinutes;
+  if (diff <= 0) diff += 24 * 60; // crosses midnight
+
+  return diff * 60_000;
+}