principles-disciple 1.8.1 → 1.8.2

package/{dist/service/nocturnal-runtime.js → src/service/nocturnal-runtime.ts}

@@ -17,115 +17,176 @@
  * - cooldown/quota state is persisted in nocturnal-runtime.json
  * - abandoned sessions (>2h inactive) must not block nocturnal flow
  */
+
 import * as fs from 'fs';
 import * as path from 'path';
-import { listSessions } from '../core/session-tracker.js';
+import { listSessions, SessionState } from '../core/session-tracker.js';
 import { withLockAsync } from '../utils/file-lock.js';
+
 // ---------------------------------------------------------------------------
-// Session Key Parsing (replicated from openclaw/src/sessions/session-key-utils.ts)
+// System Session Detection
 // ---------------------------------------------------------------------------
-/** Parse an agent-scoped session key. Returns null for non-agent keys. */
-function parseAgentSessionKey(sessionKey) {
-    const raw = (sessionKey ?? '').trim().toLowerCase();
-    if (!raw)
-        return null;
-    const parts = raw.split(':').filter(Boolean);
-    if (parts.length < 3 || parts[0] !== 'agent')
-        return null;
-    const agentId = parts[1]?.trim();
-    const rest = parts.slice(2).join(':');
-    if (!agentId || !rest)
-        return null;
-    return { agentId, rest };
-}
-/**
- * Returns true if the session was created by a system process (cron, boot, probe, subagent, acp).
- * Uses OpenClaw's native session key patterns to avoid false positives.
- *
- * System patterns:
- * - boot- prefix: boot sessions (e.g. boot-2026-04-02_10-43-45)
- * - probe- prefix: probe sessions (e.g. probe-glm-4.9-xxx)
- * - cron:<...> rest: cron run sessions (agent:<id>:cron:...)
- * - subagent: prefix: subagent sessions
- * - acp: prefix: acp sessions
- *
- * Excluded (NOT system sessions):
- * - User sessions like agent:main:feishu:user:xxx — third component is channel type, NOT cron/subagent/acp
- */
+
 /**
  * Returns true if the session was created by a system process (cron, boot, probe, subagent, acp).
  * Uses OpenClaw's native session key patterns to avoid false positives.
  *
  * Detection priority (most reliable first):
- * 1. trigger field: Most reliable - explicitly set by OpenClaw ("cron", "heartbeat", "subagent")
+ * 1. trigger field: Most reliable — explicitly set by OpenClaw ("cron", "heartbeat", "subagent")
  * 2. sessionKey patterns: Secondary confirmation via structured key (agent:main:cron:...)
  * 3. sessionId prefix: Fallback for boot-, probe- prefixed IDs
  *
- * System patterns:
- * - trigger === 'cron' | 'heartbeat' | 'subagent'
- * - sessionKey contains: cron:, subagent:, acp:
- * - sessionId starts with: boot-, probe-
+ * Excluded (NOT system sessions):
+ * - User sessions like agent:main:feishu:user:xxx — third component is channel type
  */
-function isSystemSession(state) {
+function isSystemSession(state: SessionState): boolean {
     const { sessionId, sessionKey, trigger } = state;
+
     // Primary: trigger field is explicitly set by OpenClaw - most reliable
     if (trigger === 'cron' || trigger === 'heartbeat' || trigger === 'subagent') {
         return true;
     }
+
     // Secondary: sessionKey pattern matching
     if (sessionKey) {
         const raw = sessionKey.toLowerCase();
-        if (raw.includes('cron:'))
-            return true;
-        if (raw.includes('subagent:'))
-            return true;
-        if (raw.includes('acp:'))
-            return true;
+        if (raw.includes('cron:')) return true;
+        if (raw.includes('subagent:')) return true;
+        if (raw.includes('acp:')) return true;
     }
+
     // Fallback: sessionId prefix patterns (boot-, probe-)
-    if (sessionId?.startsWith('boot-'))
-        return true;
-    if (sessionId?.startsWith('probe-'))
-        return true;
+    if (sessionId?.startsWith('boot-')) return true;
+    if (sessionId?.startsWith('probe-')) return true;
+
     return false;
 }
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
+
 /** File name for nocturnal runtime bookkeeping */
 export const NOCTURNAL_RUNTIME_FILE = 'nocturnal-runtime.json';
+
 /** Default idle threshold: workspace is considered idle if no activity for this duration (ms) */
 export const DEFAULT_IDLE_THRESHOLD_MS = 30 * 60 * 1000; // 30 minutes
+
 /** Default cooldown between nocturnal runs (ms) */
 export const DEFAULT_GLOBAL_COOLDOWN_MS = 60 * 60 * 1000; // 1 hour
+
 /** Default per-principle cooldown (ms) */
 export const DEFAULT_PRINCIPLE_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6 hours
+
 /** Default maximum nocturnal runs per quota window */
 export const DEFAULT_MAX_RUNS_PER_WINDOW = 3;
+
 /** Default quota window size (ms) */
 export const DEFAULT_QUOTA_WINDOW_MS = 24 * 60 * 60 * 1000; // 24 hours
+
 /** Abandoned session threshold: sessions inactive for longer than this are ignored (ms) */
 export const DEFAULT_ABANDONED_THRESHOLD_MS = 2 * 60 * 60 * 1000; // 2 hours
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Persisted state for nocturnal runtime bookkeeping.
+ * Stored in {stateDir}/nocturnal-runtime.json
+ */
+export interface NocturnalRuntimeState {
+    /** Last time a nocturnal run was started (ISO string) */
+    lastRunAt?: string;
+
+    /** Last time a nocturnal run completed successfully */
+    lastSuccessfulRunAt?: string;
+
+    /** Cooldown end time for global cooldown (ISO string) */
+    globalCooldownUntil?: string;
+
+    /**
+     * Per-principle cooldown map.
+     * Key: principleId, Value: ISO string of cooldown end time
+     */
+    principleCooldowns: Record<string, string>;
+
+    /**
+     * Sliding window of recent run timestamps.
+     * Used for quota enforcement.
+     */
+    recentRunTimestamps: string[];
+
+    /** Metadata about last run (for debugging) */
+    lastRunMeta?: {
+        targetPrincipleId?: string;
+        sampleCount?: number;
+        status: 'success' | 'failed' | 'skipped';
+        reason?: string;
+    };
+}
+
+/** Result of an idle check */
+export interface IdleCheckResult {
+    /** Whether the workspace is currently idle */
+    isIdle: boolean;
+    /** Most recent activity timestamp across all sessions (epoch ms) */
+    mostRecentActivityAt: number;
+    /** How long since the last activity (ms) */
+    idleForMs: number;
+    /** Number of active (non-abandoned) user sessions found */
+    userActiveSessions: number;
+    /** List of abandoned session IDs (inactive > abandoned threshold) */
+    abandonedSessionIds: string[];
+    /** Whether trajectory guardrail also confirms idle */
+    trajectoryGuardrailConfirmsIdle: boolean;
+    /** Reason for the idle determination */
+    reason: string;
+}
+
+/** Result of a cooldown check */
+export interface CooldownCheckResult {
+    /** Whether the global cooldown is currently active */
+    globalCooldownActive: boolean;
+    /** When the global cooldown ends (ISO string), null if not in cooldown */
+    globalCooldownUntil: string | null;
+    /** Remaining ms until global cooldown expires */
+    globalCooldownRemainingMs: number;
+    /** Whether the principle-specific cooldown is active */
+    principleCooldownActive: boolean;
+    /** When the principle cooldown ends (ISO string), null if not in cooldown */
+    principleCooldownUntil: string | null;
+    /** Remaining ms until principle cooldown expires */
+    principleCooldownRemainingMs: number;
+    /** Whether the quota has been exhausted */
+    quotaExhausted: boolean;
+    /** Number of runs remaining in current window */
+    runsRemaining: number;
+}
+
 // ---------------------------------------------------------------------------
 // Default State
 // ---------------------------------------------------------------------------
-function createDefaultState() {
+
+function createDefaultState(): NocturnalRuntimeState {
     return {
         principleCooldowns: {},
         recentRunTimestamps: [],
     };
 }
+
 // ---------------------------------------------------------------------------
 // File Operations (with locking)
 // ---------------------------------------------------------------------------
-async function readState(stateDir) {
+
+async function readState(stateDir: string): Promise<NocturnalRuntimeState> {
     const filePath = path.join(stateDir, NOCTURNAL_RUNTIME_FILE);
     if (!fs.existsSync(filePath)) {
         return createDefaultState();
     }
     try {
         const raw = fs.readFileSync(filePath, 'utf-8');
-        const parsed = JSON.parse(raw);
+        const parsed = JSON.parse(raw) as NocturnalRuntimeState;
         // Ensure required fields exist (migration-safe)
         return {
             principleCooldowns: parsed.principleCooldowns ?? {},
@@ -135,20 +196,20 @@ async function readState(stateDir) {
             globalCooldownUntil: parsed.globalCooldownUntil,
             lastRunMeta: parsed.lastRunMeta,
         };
-    }
-    catch {
+    } catch {
         // Corrupted file — start fresh
         return createDefaultState();
     }
 }
-function readStateSync(stateDir) {
+
+function readStateSync(stateDir: string): NocturnalRuntimeState {
     const filePath = path.join(stateDir, NOCTURNAL_RUNTIME_FILE);
     if (!fs.existsSync(filePath)) {
         return createDefaultState();
     }
     try {
         const raw = fs.readFileSync(filePath, 'utf-8');
-        const parsed = JSON.parse(raw);
+        const parsed = JSON.parse(raw) as NocturnalRuntimeState;
         return {
             principleCooldowns: parsed.principleCooldowns ?? {},
             recentRunTimestamps: parsed.recentRunTimestamps ?? [],
@@ -157,13 +218,13 @@ function readStateSync(stateDir) {
             globalCooldownUntil: parsed.globalCooldownUntil,
             lastRunMeta: parsed.lastRunMeta,
         };
-    }
-    catch (err) {
+    } catch (err) {
         console.warn(`[nocturnal-runtime] State file corrupted, resetting: ${err instanceof Error ? err.message : String(err)}`);
         return createDefaultState();
     }
 }
-async function writeState(stateDir, state) {
+
+async function writeState(stateDir: string, state: NocturnalRuntimeState): Promise<void> {
     const filePath = path.join(stateDir, NOCTURNAL_RUNTIME_FILE);
     const stateDirPath = path.dirname(filePath);
     if (!fs.existsSync(stateDirPath)) {
@@ -173,9 +234,11 @@ async function writeState(stateDir, state) {
         fs.writeFileSync(filePath, JSON.stringify(state, null, 2), 'utf-8');
     });
 }
+
 // ---------------------------------------------------------------------------
 // Idle Detection
 // ---------------------------------------------------------------------------
+
 /**
  * Check if the workspace is currently idle based on session activity.
  *
@@ -191,31 +254,45 @@ async function writeState(stateDir, state) {
  * @param trajectoryLastActivityAt - Optional trajectory timestamp as secondary guardrail
  * @returns IdleCheckResult with full diagnostic information
  */
-export function checkWorkspaceIdle(workspaceDir, options = {}, trajectoryLastActivityAt) {
-    const { idleThresholdMs = DEFAULT_IDLE_THRESHOLD_MS, abandonedThresholdMs = DEFAULT_ABANDONED_THRESHOLD_MS, } = options;
+export function checkWorkspaceIdle(
+    workspaceDir: string,
+    options: {
+        idleThresholdMs?: number;
+        abandonedThresholdMs?: number;
+    } = {},
+    trajectoryLastActivityAt?: number
+): IdleCheckResult {
+    const {
+        idleThresholdMs = DEFAULT_IDLE_THRESHOLD_MS,
+        abandonedThresholdMs = DEFAULT_ABANDONED_THRESHOLD_MS,
+    } = options;
+
     const now = Date.now();
     const sessions = listSessions(workspaceDir);
+
     // Separate active vs abandoned sessions
-    const abandonedSessions = [];
+    const abandonedSessions: string[] = [];
     let mostRecentActivityAt = 0;
     let userActiveSessions = 0;
+
     for (const session of sessions) {
         // Skip system sessions (cron, boot, probe, subagent, acp) from idle determination
-        if (isSystemSession(session))
-            continue;
+        if (isSystemSession(session)) continue;
+
         const inactiveFor = now - session.lastActivityAt;
         if (inactiveFor > abandonedThresholdMs) {
             abandonedSessions.push(session.sessionId);
-        }
-        else {
+        } else {
             userActiveSessions++;
             if (session.lastActivityAt > mostRecentActivityAt) {
                 mostRecentActivityAt = session.lastActivityAt;
             }
         }
     }
+
     const idleForMs = mostRecentActivityAt > 0 ? now - mostRecentActivityAt : now;
     const isIdle = mostRecentActivityAt === 0 || idleForMs > idleThresholdMs;
+
     // Trajectory guardrail: only used as a secondary check
     // If trajectory says there's recent activity but session state says idle,
     // that's a discrepancy we should note but still trust session state as primary
@@ -225,19 +302,20 @@ export function checkWorkspaceIdle(workspaceDir, options = {}, trajectoryLastAct
         // Guardrail confirms if trajectory also shows idle or near-idle (>80% of threshold)
         trajectoryGuardrailConfirmsIdle = trajectoryIdleFor > idleThresholdMs * 0.8;
     }
-    let reason;
+
+    let reason: string;
     if (mostRecentActivityAt === 0) {
         reason = 'No active sessions found — workspace is idle';
-    }
-    else if (isIdle) {
+    } else if (isIdle) {
         reason = `Most recent activity ${idleForMs}ms ago (>${idleThresholdMs}ms threshold)`;
-    }
-    else {
+    } else {
         reason = `Recent activity ${idleForMs}ms ago (<${idleThresholdMs}ms threshold)`;
     }
+
     if (abandonedSessions.length > 0) {
         reason += `; ${abandonedSessions.length} abandoned session(s) ignored`;
     }
+
     return {
         isIdle,
         mostRecentActivityAt,
@@ -248,9 +326,11 @@ export function checkWorkspaceIdle(workspaceDir, options = {}, trajectoryLastAct
         reason,
     };
 }
+
 // ---------------------------------------------------------------------------
 // Cooldown Management
 // ---------------------------------------------------------------------------
+
 /**
  * Check if the workspace is currently in a cooldown period.
  *
@@ -259,14 +339,31 @@ export function checkWorkspaceIdle(workspaceDir, options = {}, trajectoryLastAct
  * @param options - Cooldown configuration options
  * @returns CooldownCheckResult
  */
-export function checkCooldown(stateDir, principleId, options = {}) {
-    const { globalCooldownMs = DEFAULT_GLOBAL_COOLDOWN_MS, principleCooldownMs = DEFAULT_PRINCIPLE_COOLDOWN_MS, maxRunsPerWindow = DEFAULT_MAX_RUNS_PER_WINDOW, quotaWindowMs = DEFAULT_QUOTA_WINDOW_MS, } = options;
+export function checkCooldown(
+    stateDir: string,
+    principleId?: string,
+    options: {
+        globalCooldownMs?: number;
+        principleCooldownMs?: number;
+        maxRunsPerWindow?: number;
+        quotaWindowMs?: number;
+    } = {}
+): CooldownCheckResult {
+    const {
+        globalCooldownMs = DEFAULT_GLOBAL_COOLDOWN_MS,
+        principleCooldownMs = DEFAULT_PRINCIPLE_COOLDOWN_MS,
+        maxRunsPerWindow = DEFAULT_MAX_RUNS_PER_WINDOW,
+        quotaWindowMs = DEFAULT_QUOTA_WINDOW_MS,
+    } = options;
+
     const now = Date.now();
     const state = readStateSync(stateDir);
+
     // Global cooldown check
     let globalCooldownActive = false;
     let globalCooldownRemainingMs = 0;
-    let globalCooldownUntil = null;
+    let globalCooldownUntil: string | null = null;
+
     if (state.globalCooldownUntil) {
         const cooldownEnd = new Date(state.globalCooldownUntil).getTime();
         if (cooldownEnd > now) {
@@ -275,10 +372,12 @@ export function checkCooldown(stateDir, principleId, options = {}) {
             globalCooldownUntil = state.globalCooldownUntil;
         }
     }
+
     // Principle-specific cooldown check
     let principleCooldownActive = false;
     let principleCooldownRemainingMs = 0;
-    let principleCooldownUntil = null;
+    let principleCooldownUntil: string | null = null;
+
     if (principleId && state.principleCooldowns[principleId]) {
         const cooldownEnd = new Date(state.principleCooldowns[principleId]).getTime();
         if (cooldownEnd > now) {
@@ -287,13 +386,16 @@ export function checkCooldown(stateDir, principleId, options = {}) {
             principleCooldownUntil = state.principleCooldowns[principleId];
         }
     }
+
     // Quota check: count runs in sliding window
     const windowStart = now - quotaWindowMs;
     const recentRuns = state.recentRunTimestamps
         .map(ts => new Date(ts).getTime())
         .filter(ts => ts > windowStart);
+
     const quotaExhausted = recentRuns.length >= maxRunsPerWindow;
     const runsRemaining = Math.max(0, maxRunsPerWindow - recentRuns.length);
+
     return {
         globalCooldownActive,
         globalCooldownUntil,
@@ -305,6 +407,7 @@ export function checkCooldown(stateDir, principleId, options = {}) {
         runsRemaining,
     };
 }
+
 /**
  * Record that a nocturnal run has started.
  * Updates global cooldown and quota tracking.
@@ -312,27 +415,36 @@ export function checkCooldown(stateDir, principleId, options = {}) {
  * @param stateDir - State directory
  * @param principleId - Target principle ID for this run
  */
-export async function recordRunStart(stateDir, principleId) {
+export async function recordRunStart(
+    stateDir: string,
+    principleId: string
+): Promise<void> {
     const state = await readState(stateDir);
     const now = new Date().toISOString();
+
     state.lastRunAt = now;
     state.lastRunMeta = {
         targetPrincipleId: principleId,
         status: 'skipped', // Will be updated on completion
     };
+
     // Set global cooldown
     const cooldownUntil = new Date(Date.now() + DEFAULT_GLOBAL_COOLDOWN_MS).toISOString();
     state.globalCooldownUntil = cooldownUntil;
+
     // Add to recent runs for quota tracking
     state.recentRunTimestamps.push(now);
+
     // Prune old timestamps outside the quota window
     const windowStart = Date.now() - DEFAULT_QUOTA_WINDOW_MS;
     state.recentRunTimestamps = state.recentRunTimestamps
         .map(ts => new Date(ts).getTime())
         .filter(ts => ts > windowStart)
         .map(ts => new Date(ts).toISOString());
+
     await writeState(stateDir, state);
 }
+
 /**
  * Record the outcome of a nocturnal run.
  *
@@ -340,17 +452,29 @@ export async function recordRunStart(stateDir, principleId) {
  * @param outcome - 'success', 'failed', or 'skipped'
  * @param details - Optional details about the run
  */
-export async function recordRunEnd(stateDir, outcome, details) {
+export async function recordRunEnd(
+    stateDir: string,
+    outcome: 'success' | 'failed' | 'skipped',
+    details?: {
+        sampleCount?: number;
+        reason?: string;
+    }
+): Promise<void> {
     const state = await readState(stateDir);
     const now = new Date().toISOString();
+
     if (outcome === 'success') {
         state.lastSuccessfulRunAt = now;
+
         // Also set per-principle cooldown if we know which principle was targeted
         if (state.lastRunMeta?.targetPrincipleId) {
             const pid = state.lastRunMeta.targetPrincipleId;
-            state.principleCooldowns[pid] = new Date(Date.now() + DEFAULT_PRINCIPLE_COOLDOWN_MS).toISOString();
+            state.principleCooldowns[pid] = new Date(
+                Date.now() + DEFAULT_PRINCIPLE_COOLDOWN_MS
+            ).toISOString();
         }
     }
+
     // Update run metadata
     state.lastRunMeta = {
         ...state.lastRunMeta,
@@ -358,16 +482,19 @@ export async function recordRunEnd(stateDir, outcome, details) {
         sampleCount: details?.sampleCount ?? state.lastRunMeta?.sampleCount,
         reason: details?.reason ?? state.lastRunMeta?.reason,
     };
+
     // Note: global cooldown remains active (set at run start) - we don't clear it on failure
     // This prevents rapid retry loops
+
     await writeState(stateDir, state);
 }
+
 /**
  * Clear all cooldowns (for testing or admin reset).
  *
  * @param stateDir - State directory
  */
-export async function clearAllCooldowns(stateDir) {
+export async function clearAllCooldowns(stateDir: string): Promise<void> {
     const state = await readState(stateDir);
     state.globalCooldownUntil = undefined;
     state.principleCooldowns = {};
@@ -375,15 +502,31 @@ export async function clearAllCooldowns(stateDir) {
     state.lastRunMeta = undefined;
     await writeState(stateDir, state);
 }
+
 /**
  * Get the current runtime state (for debugging/inspection).
  *
  * @param stateDir - State directory
  * @returns The current NocturnalRuntimeState
  */
-export async function getRuntimeState(stateDir) {
+export async function getRuntimeState(stateDir: string): Promise<NocturnalRuntimeState> {
     return readState(stateDir);
 }
+
+// ---------------------------------------------------------------------------
+// Convenience: Full Pre-Flight Check
+// ---------------------------------------------------------------------------
+
+export interface PreflightCheckResult {
+    canRun: boolean;
+    idle: IdleCheckResult;
+    cooldown: CooldownCheckResult;
+    /**
+     * Human-readable reasons why run is blocked (if canRun is false)
+     */
+    blockers: string[];
+}
+
 /**
  * Combined pre-flight check for whether a nocturnal run should proceed.
  * Integrates idle + cooldown + quota checks.
@@ -394,26 +537,39 @@ export async function getRuntimeState(stateDir) {
  * @param trajectoryLastActivityAt - Optional trajectory timestamp as secondary guardrail
  * @param idleCheckOverride - Optional override for idle check result (for testing)
  */
-export function checkPreflight(workspaceDir, stateDir, principleId, trajectoryLastActivityAt, idleCheckOverride) {
+export function checkPreflight(
+    workspaceDir: string,
+    stateDir: string,
+    principleId?: string,
+    trajectoryLastActivityAt?: number,
+    idleCheckOverride?: IdleCheckResult
+): PreflightCheckResult {
     const idle = idleCheckOverride ?? checkWorkspaceIdle(workspaceDir, {}, trajectoryLastActivityAt);
     const cooldown = checkCooldown(stateDir, principleId);
-    const blockers = [];
+
+    const blockers: string[] = [];
+
     if (!idle.isIdle) {
         blockers.push(`Workspace not idle (active for ${idle.idleForMs}ms, threshold=${DEFAULT_IDLE_THRESHOLD_MS}ms)`);
     }
+
     if (cooldown.globalCooldownActive) {
         blockers.push(`Global cooldown active until ${cooldown.globalCooldownUntil}`);
     }
+
     if (cooldown.principleCooldownActive) {
         blockers.push(`Principle cooldown active until ${cooldown.principleCooldownUntil}`);
     }
+
     if (cooldown.quotaExhausted) {
         blockers.push(`Quota exhausted (${DEFAULT_MAX_RUNS_PER_WINDOW} runs per ${DEFAULT_QUOTA_WINDOW_MS / 3600000}h window)`);
     }
+
     if (idle.abandonedSessionIds.length > 0 && idle.userActiveSessions === 0) {
         // Only block if ALL sessions are abandoned (meaning workspace truly has no activity)
         // If some sessions are active, we trust the session-based idle check
     }
+
     return {
         canRun: blockers.length === 0,
         idle,