kernelbot 1.0.33 → 1.0.35

package/src/tools/monitor.js

@@ -1,17 +1,8 @@
-import { exec } from 'child_process';
 import { platform } from 'os';
+import { shellRun as run, shellEscape } from '../utils/shell.js';
 
 const isMac = platform() === 'darwin';
 
-function run(cmd, timeout = 10000) {
-  return new Promise((resolve) => {
-    exec(cmd, { timeout }, (error, stdout, stderr) => {
-      if (error) return resolve({ error: stderr || error.message });
-      resolve({ output: stdout.trim() });
-    });
-  });
-}
-
 export const definitions = [
   {
     name: 'disk_usage',
@@ -68,17 +59,24 @@ export const handlers = {
   },
 
   system_logs: async (params) => {
-    const lines = params.lines || 50;
+    let finalLines = 50;
+    if (params.lines != null) {
+      const lines = parseInt(params.lines, 10);
+      if (!Number.isFinite(lines) || lines <= 0 || lines > 10000) {
+        return { error: 'Invalid lines value: must be between 1 and 10000' };
+      }
+      finalLines = lines;
+    }
     const source = params.source || 'journalctl';
     const filter = params.filter;
 
     if (source === 'journalctl') {
-      const filterArg = filter ? ` -g "${filter}"` : '';
-      return await run(`journalctl -n ${lines}${filterArg} --no-pager`);
+      const filterArg = filter ? ` -g ${shellEscape(filter)}` : '';
+      return await run(`journalctl -n ${finalLines}${filterArg} --no-pager`);
     }
 
     // Reading a log file
-    const filterCmd = filter ? ` | grep -i "${filter}"` : '';
-    return await run(`tail -n ${lines} "${source}"${filterCmd}`);
+    const filterCmd = filter ? ` | grep -i ${shellEscape(filter)}` : '';
+    return await run(`tail -n ${finalLines} ${shellEscape(source)}${filterCmd}`);
   },
 };

package/src/tools/network.js

@@ -1,14 +1,7 @@
-import { exec } from 'child_process';
-import { platform } from 'os';
-
-function run(cmd, timeout = 15000) {
-  return new Promise((resolve) => {
-    exec(cmd, { timeout }, (error, stdout, stderr) => {
-      if (error) return resolve({ error: stderr || error.message });
-      resolve({ output: stdout.trim() });
-    });
-  });
-}
+import { shellRun, shellEscape } from '../utils/shell.js';
+import { getLogger } from '../utils/logger.js';
+
+const run = (cmd, timeout = 15000) => shellRun(cmd, timeout);
 
 export const definitions = [
   {
@@ -46,13 +39,17 @@ export const definitions = [
 
 export const handlers = {
   check_port: async (params) => {
+    const logger = getLogger();
     const host = params.host || 'localhost';
-    const { port } = params;
+    const port = parseInt(params.port, 10);
+    if (!Number.isFinite(port) || port <= 0 || port > 65535) return { error: 'Invalid port number' };
 
+    logger.debug(`check_port: checking ${host}:${port}`);
     // Use nc (netcat) for port check — works on both macOS and Linux
-    const result = await run(`nc -z -w 3 ${host} ${port} 2>&1 && echo "OPEN" || echo "CLOSED"`, 5000);
+    const result = await run(`nc -z -w 3 ${shellEscape(host)} ${port} 2>&1 && echo "OPEN" || echo "CLOSED"`, 5000);
 
     if (result.error) {
+      logger.error(`check_port failed for ${host}:${port}: ${result.error}`);
       return { port, host, status: 'closed', detail: result.error };
     }
 
@@ -63,19 +60,19 @@ export const handlers = {
   curl_url: async (params) => {
     const { url, method = 'GET', headers, body } = params;
 
-    let cmd = `curl -s -w "\\n---HTTP_STATUS:%{http_code}" -X ${method}`;
+    let cmd = `curl -s -w "\\n---HTTP_STATUS:%{http_code}" -X ${shellEscape(method)}`;
 
     if (headers) {
       for (const [key, val] of Object.entries(headers)) {
-        cmd += ` -H "${key}: ${val}"`;
+        cmd += ` -H ${shellEscape(`${key}: ${val}`)}`;
       }
     }
 
     if (body) {
-      cmd += ` -d '${body.replace(/'/g, "'\\''")}'`;
+      cmd += ` -d ${shellEscape(body)}`;
     }
 
-    cmd += ` "${url}"`;
+    cmd += ` ${shellEscape(url)}`;
 
     const result = await run(cmd);
 
@@ -89,15 +86,22 @@ export const handlers = {
   },
 
   nginx_reload: async () => {
+    const logger = getLogger();
     // Test config first
+    logger.debug('nginx_reload: testing configuration');
     const test = await run('nginx -t 2>&1');
     if (test.error || (test.output && test.output.includes('failed'))) {
+      logger.error(`nginx_reload: config test failed: ${test.error || test.output}`);
       return { error: `Config test failed: ${test.error || test.output}` };
     }
 
     const reload = await run('nginx -s reload 2>&1');
-    if (reload.error) return reload;
+    if (reload.error) {
+      logger.error(`nginx_reload failed: ${reload.error}`);
+      return reload;
+    }
 
+    logger.debug('nginx_reload: successfully reloaded');
     return { success: true, test_output: test.output };
   },
 };

package/src/tools/os.js

@@ -2,12 +2,24 @@ import { exec } from 'child_process';
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { dirname, resolve, join } from 'path';
 import { homedir } from 'os';
+import { getLogger } from '../utils/logger.js';
 
+/**
+ * Expand a file path, resolving `~` to the user's home directory.
+ * @param {string} p - The path to expand.
+ * @returns {string} The resolved absolute path.
+ */
 function expandPath(p) {
   if (p.startsWith('~')) return join(homedir(), p.slice(1));
   return resolve(p);
 }
 
+/**
+ * Check whether a file path falls within any blocked path defined in config.
+ * @param {string} filePath - The path to check.
+ * @param {object} config - The bot configuration object.
+ * @returns {boolean} True if the path is blocked.
+ */
 function isBlocked(filePath, config) {
   const expanded = expandPath(filePath);
   const blockedPaths = config.security?.blocked_paths || [];
@@ -94,14 +106,25 @@ export const definitions = [
   },
 ];
 
-function listRecursive(dirPath, base = '') {
+/** Maximum recursion depth for directory listing to prevent stack overflow. */
+const MAX_RECURSIVE_DEPTH = 10;
+
+/**
+ * Recursively list all files and directories under a given path.
+ * @param {string} dirPath - Absolute path to the directory to list.
+ * @param {string} [base=''] - Relative path prefix for nested entries.
+ * @param {number} [depth=0] - Current recursion depth (internal).
+ * @returns {Array<{name: string, type: string}>} Flat array of entries.
+ */
+function listRecursive(dirPath, base = '', depth = 0) {
+  if (depth >= MAX_RECURSIVE_DEPTH) return [];
   const entries = [];
   for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
     const rel = base ? `${base}/${entry.name}` : entry.name;
     const type = entry.isDirectory() ? 'directory' : 'file';
     entries.push({ name: rel, type });
     if (entry.isDirectory()) {
-      entries.push(...listRecursive(join(dirPath, entry.name), rel));
+      entries.push(...listRecursive(join(dirPath, entry.name), rel, depth + 1));
     }
   }
   return entries;
@@ -109,6 +132,7 @@ function listRecursive(dirPath, base = '') {
 
 export const handlers = {
   execute_command: async (params, context) => {
+    const logger = getLogger();
     const { command, timeout_seconds = 30 } = params;
     const { config } = context;
     const blockedPaths = config.security?.blocked_paths || [];
@@ -117,10 +141,13 @@ export const handlers = {
     for (const bp of blockedPaths) {
       const expanded = expandPath(bp);
       if (command.includes(expanded)) {
+        logger.warn(`execute_command blocked: command references restricted path ${bp}`);
         return { error: `Blocked: command references restricted path ${bp}` };
       }
     }
 
+    logger.debug(`execute_command: ${command.slice(0, 120)}`);
+
     return new Promise((res) => {
       let abortHandler = null;
 
@@ -164,8 +191,10 @@ export const handlers = {
   },
 
   read_file: async (params, context) => {
+    const logger = getLogger();
     const { path: filePath, max_lines } = params;
     if (isBlocked(filePath, context.config)) {
+      logger.warn(`read_file blocked: access to ${filePath} is restricted`);
       return { error: `Blocked: access to ${filePath} is restricted` };
     }
 
@@ -184,8 +213,10 @@ export const handlers = {
   },
 
   write_file: async (params, context) => {
+    const logger = getLogger();
     const { path: filePath, content } = params;
     if (isBlocked(filePath, context.config)) {
+      logger.warn(`write_file blocked: access to ${filePath} is restricted`);
       return { error: `Blocked: access to ${filePath} is restricted` };
     }
 
@@ -193,15 +224,19 @@ export const handlers = {
       const expanded = expandPath(filePath);
       mkdirSync(dirname(expanded), { recursive: true });
       writeFileSync(expanded, content, 'utf-8');
+      logger.debug(`write_file: wrote ${content.length} bytes to ${expanded}`);
       return { success: true, path: expanded };
     } catch (err) {
+      logger.error(`write_file error for ${filePath}: ${err.message}`);
       return { error: err.message };
     }
   },
 
   list_directory: async (params, context) => {
+    const logger = getLogger();
     const { path: dirPath, recursive = false } = params;
     if (isBlocked(dirPath, context.config)) {
+      logger.warn(`list_directory blocked: access to ${dirPath} is restricted`);
       return { error: `Blocked: access to ${dirPath} is restricted` };
     }
 

package/src/tools/process.js

@@ -1,13 +1,5 @@
-import { exec } from 'child_process';
-
-function run(cmd, timeout = 10000) {
-  return new Promise((resolve) => {
-    exec(cmd, { timeout }, (error, stdout, stderr) => {
-      if (error) return resolve({ error: stderr || error.message });
-      resolve({ output: stdout.trim() });
-    });
-  });
-}
+import { shellRun as run, shellEscape } from '../utils/shell.js';
+import { getLogger } from '../utils/logger.js';
 
 export const definitions = [
   {
@@ -51,23 +43,38 @@ export const definitions = [
 
 export const handlers = {
   process_list: async (params) => {
+    const logger = getLogger();
     const filter = params.filter;
-    const cmd = filter ? `ps aux | head -1 && ps aux | grep -i "${filter}" | grep -v grep` : 'ps aux';
+    logger.debug(`process_list: ${filter ? `filtering by "${filter}"` : 'listing all'}`);
+    const cmd = filter ? `ps aux | head -1 && ps aux | grep -i ${shellEscape(filter)} | grep -v grep` : 'ps aux';
     return await run(cmd);
   },
 
   kill_process: async (params) => {
+    const logger = getLogger();
     if (params.pid) {
-      return await run(`kill ${params.pid}`);
+      const pid = parseInt(params.pid, 10);
+      if (!Number.isFinite(pid) || pid <= 0) return { error: 'Invalid PID' };
+      logger.debug(`kill_process: killing PID ${pid}`);
+      const result = await run(`kill ${pid}`);
+      if (result.error) logger.error(`kill_process failed for PID ${pid}: ${result.error}`);
+      return result;
     }
     if (params.name) {
-      return await run(`pkill -f "${params.name}"`);
+      logger.debug(`kill_process: killing processes matching "${params.name}"`);
+      const result = await run(`pkill -f ${shellEscape(params.name)}`);
+      if (result.error) logger.error(`kill_process failed for name "${params.name}": ${result.error}`);
+      return result;
     }
     return { error: 'Provide either pid or name' };
   },
 
   service_control: async (params) => {
+    const logger = getLogger();
     const { service, action } = params;
-    return await run(`systemctl ${action} ${service}`);
+    logger.debug(`service_control: ${action} ${service}`);
+    const result = await run(`systemctl ${shellEscape(action)} ${shellEscape(service)}`);
+    if (result.error) logger.error(`service_control failed: ${action} ${service}: ${result.error}`);
+    return result;
   },
 };

package/src/utils/config.js

@@ -270,6 +270,65 @@ export function saveClaudeCodeAuth(config, mode, value) {
   // mode === 'system' — no credentials to save
 }
 
+/**
+ * Full interactive flow: change orchestrator model + optionally enter API key.
+ */
+export async function changeOrchestratorModel(config, rl) {
+  const { createProvider } = await import('../providers/index.js');
+  const { providerKey, modelId } = await promptProviderSelection(rl);
+
+  const providerDef = PROVIDERS[providerKey];
+
+  // Resolve API key
+  const envKey = providerDef.envKey;
+  let apiKey = process.env[envKey];
+  if (!apiKey) {
+    const key = await ask(rl, chalk.cyan(`\n  ${providerDef.name} API key (${envKey}): `));
+    if (!key.trim()) {
+      console.log(chalk.yellow('\n  No API key provided. Orchestrator not changed.\n'));
+      return config;
+    }
+    apiKey = key.trim();
+  }
+
+  // Validate the new provider before saving anything
+  console.log(chalk.dim(`\n  Verifying ${providerDef.name} / ${modelId}...`));
+  const testConfig = {
+    brain: {
+      provider: providerKey,
+      model: modelId,
+      max_tokens: config.orchestrator.max_tokens,
+      temperature: config.orchestrator.temperature,
+      api_key: apiKey,
+    },
+  };
+  try {
+    const testProvider = createProvider(testConfig);
+    await testProvider.ping();
+  } catch (err) {
+    console.log(chalk.red(`\n  ✖ Verification failed: ${err.message}`));
+    console.log(chalk.yellow(`  Orchestrator not changed. Keeping current model.\n`));
+    return config;
+  }
+
+  // Validation passed — save everything
+  const savedPath = saveOrchestratorToYaml(providerKey, modelId);
+  console.log(chalk.dim(`  Saved to ${savedPath}`));
+
+  config.orchestrator.provider = providerKey;
+  config.orchestrator.model = modelId;
+  config.orchestrator.api_key = apiKey;
+
+  // Save the key if it was newly entered
+  if (!process.env[envKey]) {
+    saveCredential(config, envKey, apiKey);
+    console.log(chalk.dim('  API key saved.\n'));
+  }
+
+  console.log(chalk.green(`  ✔ Orchestrator switched to ${providerDef.name} / ${modelId}\n`));
+  return config;
+}
+
 /**
  * Full interactive flow: change brain model + optionally enter API key.
  */
@@ -432,6 +491,13 @@ export function loadConfig() {
   if (process.env.TELEGRAM_BOT_TOKEN) {
     config.telegram.bot_token = process.env.TELEGRAM_BOT_TOKEN;
   }
+  // Merge OWNER_TELEGRAM_ID into allowed_users if set
+  if (process.env.OWNER_TELEGRAM_ID) {
+    const ownerId = Number(process.env.OWNER_TELEGRAM_ID);
+    if (!config.telegram.allowed_users.includes(ownerId)) {
+      config.telegram.allowed_users.push(ownerId);
+    }
+  }
   if (process.env.GITHUB_TOKEN) {
     if (!config.github) config.github = {};
     config.github.token = process.env.GITHUB_TOKEN;

package/src/utils/date.js

@@ -0,0 +1,19 @@
+/**
+ * Get the millisecond timestamp for the start of today (midnight 00:00:00.000).
+ *
+ * @returns {number} Epoch ms at the start of today
+ */
+export function getStartOfDayMs() {
+  const d = new Date();
+  d.setHours(0, 0, 0, 0);
+  return d.getTime();
+}
+
+/**
+ * Get today's date as an ISO date string (YYYY-MM-DD).
+ *
+ * @returns {string} e.g. "2026-02-21"
+ */
+export function todayDateStr() {
+  return new Date().toISOString().slice(0, 10);
+}

package/src/utils/display.js

@@ -46,7 +46,7 @@ export function showLogo() {
             'It can execute commands, read/write files, manage processes,\n' +
             'and interact with external services on your behalf.\n\n' +
             'Only run this on machines you control.\n' +
-            'Set allowed_users in config.yaml to restrict access.',
+            'Set OWNER_TELEGRAM_ID in .env or allowed_users in config.yaml.',
         ),
       {
         padding: 1,

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/shell.js

@@ -0,0 +1,31 @@
+import { exec } from 'child_process';
+
+/**
+ * Escape a string for safe use as a shell argument.
+ * Wraps the value in single quotes and escapes any embedded single quotes.
+ *
+ * @param {string} arg - The value to escape
+ * @returns {string} Shell-safe quoted string
+ */
+export function shellEscape(arg) {
+  if (arg === undefined || arg === null) return "''";
+  return "'" + String(arg).replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * Run a shell command and return { output } on success or { error } on failure.
+ * Resolves (never rejects) so callers can handle errors via the result object.
+ *
+ * @param {string} cmd - The shell command to execute
+ * @param {number} [timeout=10000] - Max execution time in milliseconds
+ * @param {{ maxBuffer?: number }} [opts] - Optional exec options
+ * @returns {Promise<{ output: string } | { error: string }>}
+ */
+export function shellRun(cmd, timeout = 10000, opts = {}) {
+  return new Promise((resolve) => {
+    exec(cmd, { timeout, maxBuffer: opts.maxBuffer, ...opts }, (error, stdout, stderr) => {
+      if (error) return resolve({ error: stderr || error.message });
+      resolve({ output: stdout.trim() });
+    });
+  });
+}

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;
+}