cipher-security 5.0.0

package/lib/autonomous/scheduler.js

@@ -0,0 +1,615 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * CIPHER Autonomous Scheduler — Idle-aware background task execution.
+ *
+ * Detects system idle state via platform-specific APIs, then runs prioritized
+ * background tasks during idle windows.
+ *
+ * State machine:
+ *   IDLE_WAIT → WINDOW_OPEN → RUNNING → PAUSING → IDLE_WAIT
+ *
+ * @module autonomous/scheduler
+ */
+
+import { execSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Task Priority
+// ---------------------------------------------------------------------------
+
+/** @type {Readonly<{CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3, BACKGROUND: 4}>} */
+export const TaskPriority = Object.freeze({
+  CRITICAL: 0,
+  HIGH: 1,
+  MEDIUM: 2,
+  LOW: 3,
+  BACKGROUND: 4,
+});
+
+// ---------------------------------------------------------------------------
+// Scheduler State
+// ---------------------------------------------------------------------------
+
+/** @type {Readonly<{IDLE_WAIT: 'idle_wait', WINDOW_OPEN: 'window_open', RUNNING: 'running', PAUSING: 'pausing'}>} */
+export const SchedulerState = Object.freeze({
+  IDLE_WAIT: 'idle_wait',
+  WINDOW_OPEN: 'window_open',
+  RUNNING: 'running',
+  PAUSING: 'pausing',
+});
+
+// ---------------------------------------------------------------------------
+// ScheduledTask
+// ---------------------------------------------------------------------------
+
+export class ScheduledTask {
+  /**
+   * @param {object} opts
+   * @param {string} opts.name
+   * @param {string} opts.taskType
+   * @param {number} opts.priority - TaskPriority value
+   * @param {Function} opts.callableFn
+   * @param {Array} [opts.args]
+   * @param {object} [opts.kwargs]
+   * @param {string} [opts.taskId]
+   * @param {number} [opts.intervalSeconds]
+   * @param {number} [opts.lastRun]
+   * @param {number} [opts.nextRun]
+   * @param {number} [opts.runCount]
+   * @param {number} [opts.maxRuns]
+   * @param {boolean} [opts.enabled]
+   * @param {boolean} [opts.requiresIdle]
+   * @param {string} [opts.createdAt]
+   */
+  constructor({
+    name,
+    taskType,
+    priority,
+    callableFn,
+    args = [],
+    kwargs = {},
+    taskId = randomUUID().replace(/-/g, ''),
+    intervalSeconds = 0,
+    lastRun = 0,
+    nextRun = 0,
+    runCount = 0,
+    maxRuns = 0,
+    enabled = true,
+    requiresIdle = true,
+    createdAt = new Date().toISOString(),
+  }) {
+    this.name = name;
+    this.taskType = taskType;
+    this.priority = priority;
+    this.callableFn = callableFn;
+    this.args = args;
+    this.kwargs = kwargs;
+    this.taskId = taskId;
+    this.intervalSeconds = intervalSeconds;
+    this.lastRun = lastRun;
+    this.nextRun = nextRun;
+    this.runCount = runCount;
+    this.maxRuns = maxRuns;
+    this.enabled = enabled;
+    this.requiresIdle = requiresIdle;
+    this.createdAt = createdAt;
+  }
+
+  /**
+   * Return true if the task should run at the given epoch time.
+   * @param {number} [now]
+   * @returns {boolean}
+   */
+  isDue(now) {
+    if (!this.enabled) return false;
+    if (this.maxRuns > 0 && this.runCount >= this.maxRuns) return false;
+    now = now ?? Date.now() / 1000;
+    return now >= this.nextRun;
+  }
+
+  /**
+   * Mark the task as having just executed.
+   * @param {number} [now]
+   */
+  recordRun(now) {
+    now = now ?? Date.now() / 1000;
+    this.lastRun = now;
+    this.runCount += 1;
+    if (this.intervalSeconds > 0) {
+      this.nextRun = now + this.intervalSeconds;
+    } else {
+      // One-shot — disable after run
+      this.enabled = false;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// TaskResult
+// ---------------------------------------------------------------------------
+
+export class TaskResult {
+  /**
+   * @param {object} opts
+   * @param {string} opts.taskId
+   * @param {string} opts.taskName
+   * @param {number} opts.startedAt
+   * @param {number} opts.finishedAt
+   * @param {boolean} opts.success
+   * @param {string|null} [opts.error]
+   * @param {*} [opts.result]
+   */
+  constructor({ taskId, taskName, startedAt, finishedAt, success, error = null, result = null }) {
+    this.taskId = taskId;
+    this.taskName = taskName;
+    this.startedAt = startedAt;
+    this.finishedAt = finishedAt;
+    this.success = success;
+    this.error = error;
+    this.result = result;
+  }
+
+  get durationMs() {
+    return (this.finishedAt - this.startedAt) * 1000;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// LastRequestTracker
+// ---------------------------------------------------------------------------
+
+export class LastRequestTracker {
+  constructor() {
+    this._lastTouch = Date.now() / 1000;
+  }
+
+  /** Record an interaction right now. */
+  touch() {
+    this._lastTouch = Date.now() / 1000;
+  }
+
+  /** Seconds elapsed since the last recorded interaction. */
+  secondsSinceLast() {
+    return Date.now() / 1000 - this._lastTouch;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// IdleDetector
+// ---------------------------------------------------------------------------
+
+export class IdleDetector {
+  /**
+   * @param {LastRequestTracker} [fallbackTracker]
+   */
+  constructor(fallbackTracker) {
+    this._platform = process.platform; // 'darwin', 'linux', 'win32'
+    this._tracker = fallbackTracker || new LastRequestTracker();
+    this._method = this._detectMethod();
+  }
+
+  /** Return estimated seconds the system has been idle. */
+  idleSeconds() {
+    if (this._method === 'ioreg') return this._idleMacos();
+    if (this._method === 'xprintidle') return this._idleLinux();
+    return this._idleFallback();
+  }
+
+  /**
+   * Return true if the system has been idle for at least thresholdMinutes.
+   * @param {number} [thresholdMinutes=15]
+   */
+  isIdle(thresholdMinutes = 15) {
+    return this.idleSeconds() >= thresholdMinutes * 60;
+  }
+
+  /** Expose the underlying request tracker. */
+  get tracker() {
+    return this._tracker;
+  }
+
+  /** @returns {string} */
+  _detectMethod() {
+    if (this._platform === 'darwin') {
+      try {
+        execSync('ioreg -c IOHIDSystem', { timeout: 2000, stdio: 'pipe' });
+        return 'ioreg';
+      } catch { /* fall through */ }
+    } else if (this._platform === 'linux') {
+      try {
+        execSync('xprintidle', { timeout: 2000, stdio: 'pipe' });
+        return 'xprintidle';
+      } catch { /* fall through */ }
+    }
+    return 'fallback';
+  }
+
+  /** macOS: read HIDIdleTime from IOKit registry (nanoseconds). */
+  _idleMacos() {
+    try {
+      const result = execSync('ioreg -c IOHIDSystem -d 4', {
+        timeout: 5000,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      for (const line of result.split('\n')) {
+        if (line.includes('HIDIdleTime')) {
+          const parts = line.split('=');
+          if (parts.length === 2) {
+            const ns = parseInt(parts[1].trim(), 10);
+            if (!isNaN(ns)) return Math.floor(ns / 1_000_000_000);
+          }
+        }
+      }
+    } catch { /* fall through */ }
+    return this._idleFallback();
+  }
+
+  /** Linux: use xprintidle (milliseconds). */
+  _idleLinux() {
+    try {
+      const result = execSync('xprintidle', {
+        timeout: 5000,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const ms = parseInt(result.trim(), 10);
+      if (!isNaN(ms)) return Math.floor(ms / 1000);
+    } catch { /* fall through */ }
+    return this._idleFallback();
+  }
+
+  /** Fallback: use LastRequestTracker as idle proxy. */
+  _idleFallback() {
+    return Math.floor(this._tracker.secondsSinceLast());
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CipherScheduler
+// ---------------------------------------------------------------------------
+
+export class CipherScheduler {
+  static TICK_INTERVAL = 30.0; // seconds
+
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.idleThresholdMinutes=15]
+   * @param {string} [opts.sleepStart='23:00']
+   * @param {string} [opts.sleepEnd='07:00']
+   */
+  constructor({
+    idleThresholdMinutes = 15,
+    sleepStart = '23:00',
+    sleepEnd = '07:00',
+  } = {}) {
+    this._idleThreshold = idleThresholdMinutes;
+    this._sleepStart = CipherScheduler._parseTime(sleepStart);
+    this._sleepEnd = CipherScheduler._parseTime(sleepEnd);
+    this._idleDetector = new IdleDetector();
+    this._state = SchedulerState.IDLE_WAIT;
+    /** @type {Map<string, ScheduledTask>} */
+    this._tasks = new Map();
+    /** @type {TaskResult[]} */
+    this._history = [];
+    this._maxHistory = 200;
+    this._running = false;
+    this._stopRequested = false;
+    this._tickTimer = null;
+  }
+
+  // -- task management ---------------------------------------------------
+
+  /** @param {ScheduledTask} task */
+  addTask(task) {
+    this._tasks.set(task.taskId, task);
+  }
+
+  /**
+   * Remove a task by ID. Returns true if found and removed.
+   * @param {string} taskId
+   * @returns {boolean}
+   */
+  removeTask(taskId) {
+    return this._tasks.delete(taskId);
+  }
+
+  /**
+   * Retrieve a task by ID.
+   * @param {string} taskId
+   * @returns {ScheduledTask|undefined}
+   */
+  getTask(taskId) {
+    return this._tasks.get(taskId);
+  }
+
+  // -- idle window detection ---------------------------------------------
+
+  /**
+   * @param {string} t - 'HH:MM'
+   * @returns {[number, number]}
+   */
+  static _parseTime(t) {
+    const parts = t.trim().split(':');
+    return [parseInt(parts[0], 10), parseInt(parts[1], 10)];
+  }
+
+  /** Return true if current local time is within the sleep window. */
+  _inSleepWindow() {
+    const now = new Date();
+    const currentMinutes = now.getHours() * 60 + now.getMinutes();
+    const startMinutes = this._sleepStart[0] * 60 + this._sleepStart[1];
+    const endMinutes = this._sleepEnd[0] * 60 + this._sleepEnd[1];
+
+    if (startMinutes <= endMinutes) {
+      return currentMinutes >= startMinutes && currentMinutes < endMinutes;
+    }
+    // Overnight window
+    return currentMinutes >= startMinutes || currentMinutes < endMinutes;
+  }
+
+  /** Return true if conditions are right for background work. */
+  _isIdleWindow() {
+    if (this._inSleepWindow()) return true;
+    if (this._idleDetector.isIdle(this._idleThreshold)) {
+      const trackerIdle = this._idleDetector.tracker.secondsSinceLast();
+      return trackerIdle >= this._idleThreshold * 60;
+    }
+    return false;
+  }
+
+  // -- state machine -----------------------------------------------------
+
+  /** Single iteration of the scheduler state machine. */
+  _tick() {
+    const idleNow = this._isIdleWindow();
+
+    if (this._state === SchedulerState.IDLE_WAIT) {
+      if (idleNow) {
+        this._state = SchedulerState.WINDOW_OPEN;
+      }
+    } else if (this._state === SchedulerState.WINDOW_OPEN) {
+      this._state = SchedulerState.RUNNING;
+      this._executeDueTasks();
+      if (!idleNow) {
+        this._state = SchedulerState.PAUSING;
+      } else if (!this._hasDueTasks()) {
+        this._state = SchedulerState.IDLE_WAIT;
+      }
+    } else if (this._state === SchedulerState.RUNNING) {
+      if (!idleNow) {
+        this._state = SchedulerState.PAUSING;
+      } else if (this._hasDueTasks()) {
+        this._executeDueTasks();
+      } else {
+        this._state = SchedulerState.IDLE_WAIT;
+      }
+    } else if (this._state === SchedulerState.PAUSING) {
+      this._state = SchedulerState.IDLE_WAIT;
+    }
+  }
+
+  // -- task execution ----------------------------------------------------
+
+  _hasDueTasks() {
+    const now = Date.now() / 1000;
+    for (const t of this._tasks.values()) {
+      if (t.isDue(now)) return true;
+    }
+    return false;
+  }
+
+  /** @returns {ScheduledTask[]} */
+  _getDueTasksSorted() {
+    const now = Date.now() / 1000;
+    const due = [];
+    for (const t of this._tasks.values()) {
+      if (t.isDue(now)) due.push(t);
+    }
+    due.sort((a, b) => a.priority - b.priority || a.nextRun - b.nextRun);
+    return due;
+  }
+
+  _executeDueTasks() {
+    const dueTasks = this._getDueTasksSorted();
+    for (const task of dueTasks) {
+      if (this._stopRequested) break;
+      if (task.requiresIdle && !this._isIdleWindow()) break;
+      this._runSingleTask(task);
+    }
+  }
+
+  /**
+   * @param {ScheduledTask} task
+   * @returns {TaskResult}
+   */
+  _runSingleTask(task) {
+    const started = Date.now() / 1000;
+    let result;
+
+    try {
+      const resultValue = task.callableFn(...task.args);
+      const finished = Date.now() / 1000;
+      task.recordRun(finished);
+      result = new TaskResult({
+        taskId: task.taskId,
+        taskName: task.name,
+        startedAt: started,
+        finishedAt: finished,
+        success: true,
+        result: resultValue,
+      });
+    } catch (exc) {
+      const finished = Date.now() / 1000;
+      task.recordRun(finished);
+      result = new TaskResult({
+        taskId: task.taskId,
+        taskName: task.name,
+        startedAt: started,
+        finishedAt: finished,
+        success: false,
+        error: `${exc.constructor.name}: ${exc.message}`,
+      });
+    }
+
+    this._recordHistory(result);
+    return result;
+  }
+
+  /** @param {TaskResult} result */
+  _recordHistory(result) {
+    this._history.push(result);
+    if (this._history.length > this._maxHistory) {
+      this._history = this._history.slice(-this._maxHistory);
+    }
+  }
+
+  // -- main loop ---------------------------------------------------------
+
+  /** Start the scheduler tick loop using setInterval. */
+  start() {
+    if (this._running) return;
+    this._running = true;
+    this._stopRequested = false;
+    this._tickTimer = setInterval(() => this._tick(), CipherScheduler.TICK_INTERVAL * 1000);
+    // Unref so it doesn't keep the process alive
+    if (this._tickTimer.unref) this._tickTimer.unref();
+  }
+
+  /** Stop the scheduler. */
+  stop() {
+    this._stopRequested = true;
+    if (this._tickTimer) {
+      clearInterval(this._tickTimer);
+      this._tickTimer = null;
+    }
+    this._running = false;
+  }
+
+  // -- status & introspection --------------------------------------------
+
+  getStatus() {
+    const now = Date.now() / 1000;
+    const taskSummaries = [];
+    for (const t of this._tasks.values()) {
+      taskSummaries.push({
+        taskId: t.taskId,
+        name: t.name,
+        type: t.taskType,
+        priority: t.priority,
+        enabled: t.enabled,
+        runCount: t.runCount,
+        isDue: t.isDue(now),
+        nextRunIn: t.nextRun > 0 ? Math.max(0, t.nextRun - now) : 0,
+        requiresIdle: t.requiresIdle,
+      });
+    }
+    return {
+      state: this._state,
+      running: this._running,
+      idleThresholdMinutes: this._idleThreshold,
+      sleepWindow: `${String(this._sleepStart[0]).padStart(2, '0')}:${String(this._sleepStart[1]).padStart(2, '0')}→${String(this._sleepEnd[0]).padStart(2, '0')}:${String(this._sleepEnd[1]).padStart(2, '0')}`,
+      isIdleWindow: this._isIdleWindow(),
+      systemIdleSeconds: this._idleDetector.idleSeconds(),
+      tasksTotal: taskSummaries.length,
+      tasksDue: taskSummaries.filter(t => t.isDue).length,
+      tasks: taskSummaries,
+      historySize: this._history.length,
+    };
+  }
+
+  /**
+   * Return recent task execution results.
+   * @param {number} [limit=50]
+   */
+  getTaskHistory(limit = 50) {
+    const recent = this._history.slice(-limit);
+    return recent.map(r => ({
+      taskId: r.taskId,
+      taskName: r.taskName,
+      startedAt: new Date(r.startedAt * 1000).toISOString(),
+      durationMs: Math.round(r.durationMs * 100) / 100,
+      success: r.success,
+      error: r.error,
+    }));
+  }
+
+  get idleDetector() {
+    return this._idleDetector;
+  }
+
+  get state() {
+    return this._state;
+  }
+
+  // Expose for testing — force state transition
+  set state(val) {
+    this._state = val;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default Tasks Factory
+// ---------------------------------------------------------------------------
+
+function _noopMemoryConsolidation() {
+  return 'memory_consolidation: complete';
+}
+
+function _noopSkillMetricUpdate() {
+  return 'skill_metric_update: complete';
+}
+
+function _noopMemoryDecay() {
+  return 'memory_decay: complete';
+}
+
+function _noopStaleEngagementCleanup() {
+  return 'stale_engagement_cleanup: complete';
+}
+
+/**
+ * Create the standard set of background self-improvement tasks.
+ * @returns {ScheduledTask[]}
+ */
+export function createDefaultTasks() {
+  const now = Date.now() / 1000;
+  return [
+    new ScheduledTask({
+      name: 'memory_consolidation',
+      taskType: 'memory_consolidation',
+      priority: TaskPriority.MEDIUM,
+      callableFn: _noopMemoryConsolidation,
+      intervalSeconds: 3600,
+      nextRun: now + 3600,
+    }),
+    new ScheduledTask({
+      name: 'skill_metric_update',
+      taskType: 'metric_update',
+      priority: TaskPriority.LOW,
+      callableFn: _noopSkillMetricUpdate,
+      intervalSeconds: 1800,
+      nextRun: now + 1800,
+    }),
+    new ScheduledTask({
+      name: 'memory_decay',
+      taskType: 'memory_consolidation',
+      priority: TaskPriority.BACKGROUND,
+      callableFn: _noopMemoryDecay,
+      intervalSeconds: 21600,
+      nextRun: now + 21600,
+    }),
+    new ScheduledTask({
+      name: 'stale_engagement_cleanup',
+      taskType: 'memory_consolidation',
+      priority: TaskPriority.BACKGROUND,
+      callableFn: _noopStaleEngagementCleanup,
+      intervalSeconds: 86400,
+      nextRun: now + 86400,
+    }),
+  ];
+}