principles-disciple 1.41.0 → 1.42.0

package/src/service/queue-io.ts

@@ -0,0 +1,375 @@
+/**
+ * Queue I/O + Enqueue — extracted from evolution-worker.ts
+ *
+ * Full persistence layer encapsulating queue file locking, atomic writes,
+ * queue format, and enqueue orchestration. Depends on file-lock.ts, io.ts,
+ * queue-migration.ts, correction-cue-learner.ts, and pain.ts.
+ * Zero imports from evolution-worker.ts.
+ */
+
+import * as fs from 'fs';
+import { createHash } from 'crypto';
+import { acquireLockAsync, releaseLock as releaseImportedLock, type LockContext } from '../utils/file-lock.js';
+import { atomicWriteFileSync } from '../utils/io.js';
+import { LockUnavailableError } from '../config/errors.js';
+import { migrateQueueToV2 } from './queue-migration.js';
+import type { EvolutionQueueItem } from '../core/evolution-types.js';
+import type { RawQueueItem } from './queue-migration.js';
+import type { PluginLogger } from '../openclaw-sdk.js';
+import type { WorkspaceContext } from '../core/workspace-context.js';
+import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
+import { readPainFlagContract } from '../core/pain.js';
+
+/**
+ * Extended EvolutionQueueItem that includes the recentPainContext field.
+ * This field is added inline in evolution-worker.ts but needs to be available
+ * in queue-io.ts for the enqueue functions.
+ */
+interface EvolutionQueueItemWithPain extends EvolutionQueueItem {
+    recentPainContext?: RecentPainContext;
+}
+
+export const EVOLUTION_QUEUE_LOCK_SUFFIX = '.lock';
+export const LOCK_MAX_RETRIES = 50;
+export const LOCK_RETRY_DELAY_MS = 50;
+export const LOCK_STALE_MS = 30_000;
+
+export const PAIN_QUEUE_DEDUP_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours
+
+// ---------------------------------------------------------------------------
+// requireQueueLock — thin wrapper that adds LockUnavailableError
+// ---------------------------------------------------------------------------
+
+/**
+ * Acquire a queue lock, throwing LockUnavailableError on failure.
+ * This is the standard lock used across all queue operations.
+ */
+export async function requireQueueLock(
+    resourcePath: string,
+    logger: PluginLogger | { warn?: (message: string) => void; info?: (message: string) => void } | undefined,
+    scope: string,
+    lockSuffix: string = EVOLUTION_QUEUE_LOCK_SUFFIX,
+): Promise<() => void> {
+    try {
+        return await acquireQueueLock(resourcePath, logger, lockSuffix);
+    } catch (err) {
+        throw new LockUnavailableError(resourcePath, scope, { cause: err });
+    }
+}
+
+// ---------------------------------------------------------------------------
+// RecentPainContext
+// ---------------------------------------------------------------------------
+
+export interface RecentPainContext {
+    mostRecent: {
+        score: number;
+        source: string;
+        reason: string;
+        timestamp: string;
+        sessionId: string;
+    } | null;
+    recentPainCount: number;
+    recentMaxPainScore: number;
+}
+
+// ---------------------------------------------------------------------------
+// Task ID creation
+// ---------------------------------------------------------------------------
+
+export function createEvolutionTaskId(
+    source: string,
+    score: number,
+    preview: string,
+    reason: string,
+    now: number,
+): string {
+    return createHash('md5')
+        .update(`${source}:${score}:${preview}:${reason}:${now}`)
+        .digest('hex')
+        .substring(0, 8);
+}
+
+// ---------------------------------------------------------------------------
+// Queue helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a specific task kind has a pending or in-progress entry.
+ */
+export function hasPendingTask(queue: EvolutionQueueItem[], taskKind: string): boolean {
+    return queue.some(
+        (t) => t.taskKind === taskKind && (t.status === 'pending' || t.status === 'in_progress'),
+    );
+}
+
+/**
+ * Build a dedup key from pain context.
+ * Returns null when no pain context is available (bypasses dedup).
+ */
+function buildPainSourceKey(
+    painCtx: ReturnType<typeof readRecentPainContext>,
+): string | null {
+    if (!painCtx.mostRecent) return null;
+    return `${painCtx.mostRecent.source}::${painCtx.mostRecent.reason?.slice(0, 50) ?? ''}`;
+}
+
+/**
+ * Check whether a similar sleep_reflection task completed recently.
+ */
+function hasRecentSimilarReflection(
+    queue: EvolutionQueueItemWithPain[],
+    painSourceKey: string,
+    now: number,
+): EvolutionQueueItem | null {
+    return queue.find((t) => {
+        if (t.taskKind !== 'sleep_reflection') return false;
+        if (t.status !== 'completed') return false;
+        if (!t.completed_at) return false;
+        const age = now - new Date(t.completed_at).getTime();
+        if (age > PAIN_QUEUE_DEDUP_WINDOW_MS) return false;
+        const taskPainKey = buildPainSourceKey(t.recentPainContext ?? { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 });
+        if (!taskPainKey) return false;
+        return taskPainKey === painSourceKey;
+    }) ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Pain context
+// ---------------------------------------------------------------------------
+
+export function readRecentPainContext(wctx: WorkspaceContext): RecentPainContext {
+    const contract = readPainFlagContract(wctx.workspaceDir);
+    if (contract.status !== 'valid') {
+        return { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 };
+    }
+
+    try {
+        const score = parseInt(contract.data.score ?? '0', 10) || 0;
+        const source = contract.data.source ?? '';
+        const reason = contract.data.reason ?? '';
+        const timestamp = contract.data.time ?? '';
+        const sessionId = contract.data.session_id ?? '';
+
+        if (score > 0) {
+            return {
+                mostRecent: { score, source, reason, timestamp, sessionId },
+                recentPainCount: 1,
+                recentMaxPainScore: score,
+            };
+        }
+    } catch (err) {
+      // Best effort — non-fatal, but surface unexpected errors
+      /* eslint-disable no-console */
+      console.warn(`[queue-io] Failed to read pain context (non-fatal): ${String(err)}`);
+      /* eslint-enable no-console */
+    }
+
+    return { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 };
+}
+
+/**
+ * Decide whether to skip enqueuing due to a recent similar reflection.
+ */
+export function shouldSkipForDedup(
+    queue: EvolutionQueueItemWithPain[],
+    wctx: WorkspaceContext,
+    logger: PluginLogger | undefined,
+): boolean {
+    const recentPainContext = readRecentPainContext(wctx);
+    const painSourceKey = buildPainSourceKey(recentPainContext);
+
+    if (!painSourceKey) return false;
+
+    const now = Date.now();
+    const recentSimilarReflection = hasRecentSimilarReflection(queue, painSourceKey, now);
+
+    if (recentSimilarReflection) {
+        const completedTime = new Date(recentSimilarReflection.completed_at!).getTime(); /* eslint-disable-line @typescript-eslint/no-non-null-assertion */
+        logger?.debug?.(`[PD:EvolutionWorker] Skipping sleep_reflection — similar reflection completed ${Math.round((now - completedTime) / 60000)}min ago (same pain pattern: ${painSourceKey})`);
+        return true;
+    }
+    return false;
+}
+
+// ---------------------------------------------------------------------------
+// Enqueue functions
+// ---------------------------------------------------------------------------
+
+function enqueueNewSleepReflectionTask(
+    queue: EvolutionQueueItemWithPain[],
+    recentPainContext: ReturnType<typeof readRecentPainContext>,
+    queuePath: string,
+    logger: PluginLogger | undefined,
+): void {
+    const taskId = createEvolutionTaskId('nocturnal', 50, 'idle workspace', 'Sleep-mode reflection', Date.now());
+    const nowIso = new Date().toISOString();
+
+    queue.push({
+        id: taskId,
+        taskKind: 'sleep_reflection',
+        priority: 'medium',
+        score: 50,
+        source: 'nocturnal',
+        reason: 'Sleep-mode reflection triggered by idle workspace',
+        trigger_text_preview: 'Idle workspace detected',
+        timestamp: nowIso,
+        enqueued_at: nowIso,
+        status: 'pending',
+        traceId: taskId,
+        retryCount: 0,
+        maxRetries: 1,
+        recentPainContext,
+    });
+
+    // Cast to EvolutionQueueItem[] because saveEvolutionQueue expects the base type
+    // but the queue may contain extended fields (recentPainContext) that are
+    // serialized as part of the JSON - this is safe at runtime.
+    saveEvolutionQueue(queuePath, queue as unknown as EvolutionQueueItem[]);
+    logger?.info?.(`[PD:EvolutionWorker] Enqueued sleep_reflection task ${taskId}`);
+}
+
+/**
+ * Enqueue a sleep_reflection task if one is not already pending.
+ */
+export async function enqueueSleepReflectionTask(
+    wctx: WorkspaceContext,
+    logger: PluginLogger | undefined,
+): Promise<void> {
+    const queuePath = wctx.resolve('EVOLUTION_QUEUE');
+    const releaseLock = await requireQueueLock(queuePath, logger, 'enqueueSleepReflection', EVOLUTION_QUEUE_LOCK_SUFFIX);
+
+    try {
+        const queue = loadEvolutionQueue(queuePath);
+
+        if (hasPendingTask(queue, 'sleep_reflection')) {
+            logger?.debug?.('[PD:EvolutionWorker] sleep_reflection task already pending/in-progress, skipping');
+            return;
+        }
+
+        if (shouldSkipForDedup(queue, wctx, logger)) {
+            return;
+        }
+
+        const recentPainContext = readRecentPainContext(wctx);
+        enqueueNewSleepReflectionTask(queue, recentPainContext, queuePath, logger);
+    } finally {
+        releaseLock();
+    }
+}
+
+/**
+ * Enqueue a keyword_optimization task if one is not already pending/in-progress.
+ */
+export async function enqueueKeywordOptimizationTask(
+    wctx: WorkspaceContext,
+    logger: PluginLogger | undefined,
+): Promise<void> {
+    const queuePath = wctx.resolve('EVOLUTION_QUEUE');
+    const releaseLock = await requireQueueLock(queuePath, logger, 'enqueueKeywordOpt', EVOLUTION_QUEUE_LOCK_SUFFIX);
+
+    try {
+        const queue = loadEvolutionQueue(queuePath);
+
+        if (hasPendingTask(queue, 'keyword_optimization')) {
+            logger?.debug?.('[PD:EvolutionWorker] keyword_optimization task already pending/in-progress, skipping');
+            return;
+        }
+
+        const learner = CorrectionCueLearner.get(wctx.stateDir);
+        if (!learner.canRunKeywordOptimization()) {
+            logger?.debug?.('[PD:EvolutionWorker] keyword_optimization throttle exhausted, skipping');
+            return;
+        }
+
+        const taskId = createEvolutionTaskId('keyword_optimization', 50, 'keyword optimization', 'Keyword optimization via LLM', Date.now());
+        const nowIso = new Date().toISOString();
+
+        queue.push({
+            id: taskId,
+            taskKind: 'keyword_optimization',
+            priority: 'medium',
+            score: 50,
+            source: 'correction',
+            reason: 'Keyword optimization triggered by heartbeat',
+            trigger_text_preview: 'Keyword optimization via LLM',
+            timestamp: nowIso,
+            enqueued_at: nowIso,
+            status: 'pending',
+            traceId: taskId,
+            retryCount: 0,
+            maxRetries: 1,
+        });
+
+        saveEvolutionQueue(queuePath, queue);
+        logger?.info?.(`[PD:EvolutionWorker] Enqueued keyword_optimization task ${taskId}`);
+    } finally {
+        releaseLock();
+    }
+}
+
+export async function acquireQueueLock(
+    resourcePath: string,
+    logger: PluginLogger | { warn?: (message: string) => void; info?: (message: string) => void } | undefined,
+    lockSuffix: string = EVOLUTION_QUEUE_LOCK_SUFFIX,
+): Promise<() => void> {
+    try {
+        const ctx: LockContext = await acquireLockAsync(resourcePath, {
+            lockSuffix,
+            maxRetries: LOCK_MAX_RETRIES,
+            baseRetryDelayMs: LOCK_RETRY_DELAY_MS,
+            lockStaleMs: LOCK_STALE_MS,
+        });
+        return () => releaseImportedLock(ctx);
+    } catch (error: unknown) {
+        const warn = logger?.warn;
+        warn?.(`[PD:EvolutionWorker] Failed to acquire lock for ${resourcePath}: ${String(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * RAII-style lock guard — always releases the lock on exceptions.
+ */
+export async function withQueueLock<T>(
+    resourcePath: string,
+    logger: PluginLogger | { warn?: (message: string) => void; info?: (message: string) => void } | undefined,
+    scope: string,
+    fn: () => Promise<T>,
+): Promise<T> {
+    const releaseLock = await acquireQueueLock(resourcePath, logger, EVOLUTION_QUEUE_LOCK_SUFFIX);
+    try {
+        return await fn();
+    } finally {
+        releaseLock();
+    }
+}
+
+/**
+ * Load and migrate the evolution queue. Returns empty array if file doesn't exist.
+ */
+export function loadEvolutionQueue(queuePath: string): EvolutionQueueItem[] {
+    let rawQueue: RawQueueItem[] = [];
+    try {
+        rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+    } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+            // Queue doesn't exist yet - create empty array
+            rawQueue = [];
+        } else {
+            // Corrupted JSON or other read error — warn and recover with empty queue
+            /* eslint-disable no-console */
+            console.warn(`[queue-io] Failed to load evolution queue (recovering with empty): ${String(err)}`);
+            /* eslint-enable no-console */
+            rawQueue = [];
+        }
+    }
+    return migrateQueueToV2(rawQueue) as unknown as EvolutionQueueItem[];
+}
+
+/**
+ * Atomically write the queue to disk.
+ */
+export function saveEvolutionQueue(queuePath: string, queue: EvolutionQueueItem[]): void {
+    atomicWriteFileSync(queuePath, JSON.stringify(queue, null, 2));
+}

package/src/service/queue-migration.ts

@@ -0,0 +1,122 @@
+/**
+ * Queue Migration — extracted from evolution-worker.ts (lines 297-379)
+ *
+ * Pure data transformation functions for migrating legacy queue items
+ * to the V2 schema. Zero I/O, zero imports from evolution-worker.ts.
+ */
+
+import type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
+
+// V2 types (not exported from evolution-types.ts — defined here for self-containment)
+export type QueueStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
+export type TaskResolution = 'success' | 'failure' | 'skipped';
+export interface EvolutionQueueItem {
+    id: string;
+    taskKind: TaskKind;
+    priority: TaskPriority;
+    source: string;
+    traceId?: string;
+    task?: string;
+    score: number;
+    reason: string;
+    timestamp: string;
+    enqueued_at?: string;
+    started_at?: string;
+    completed_at?: string;
+    assigned_session_key?: string;
+    trigger_text_preview?: string;
+    status: QueueStatus;
+    resolution?: TaskResolution;
+    session_id?: string;
+    agent_id?: string;
+    retryCount: number;
+    maxRetries: number;
+    lastError?: string;
+    resultRef?: string;
+}
+
+/**
+ * Legacy queue item shape (pre-V2) for migration compatibility.
+ * These items lack taskKind, priority, retryCount, maxRetries, lastError fields.
+ */
+export interface LegacyEvolutionQueueItem {
+    id: string;
+    task?: string;
+    score: number;
+    source: string;
+    reason: string;
+    timestamp: string;
+    enqueued_at?: string;
+    started_at?: string;
+    completed_at?: string;
+    assigned_session_key?: string;
+    trigger_text_preview?: string;
+    status?: string;
+    resolution?: string;
+    session_id?: string;
+    agent_id?: string;
+    traceId?: string;
+    taskKind?: string;
+    priority?: string;
+    retryCount?: number;
+    maxRetries?: number;
+    lastError?: string;
+    resultRef?: string;
+}
+
+/**
+ * Default values for new V2 fields when migrating legacy items.
+ */
+const DEFAULT_TASK_KIND: TaskKind = 'pain_diagnosis';
+const DEFAULT_PRIORITY: TaskPriority = 'medium';
+const DEFAULT_MAX_RETRIES = 3;
+
+export { DEFAULT_TASK_KIND, DEFAULT_PRIORITY, DEFAULT_MAX_RETRIES };
+
+export type RawQueueItem = Record<string, unknown>;
+
+/**
+ * Migrate a legacy queue item to V2 schema.
+ * Old items without taskKind are assumed to be pain_diagnosis for backward compatibility.
+ */
+export function migrateToV2(item: LegacyEvolutionQueueItem): EvolutionQueueItem {
+    return {
+        id: item.id,
+        taskKind: (item.taskKind as TaskKind) || DEFAULT_TASK_KIND,
+        priority: (item.priority as TaskPriority) || DEFAULT_PRIORITY,
+        source: item.source,
+        traceId: item.traceId,
+        task: item.task,
+        score: item.score,
+        reason: item.reason,
+        timestamp: item.timestamp,
+        enqueued_at: item.enqueued_at,
+        started_at: item.started_at,
+        completed_at: item.completed_at,
+        assigned_session_key: item.assigned_session_key,
+        trigger_text_preview: item.trigger_text_preview,
+        status: (item.status as QueueStatus) || 'pending',
+        resolution: item.resolution as TaskResolution | undefined,
+        session_id: item.session_id,
+        agent_id: item.agent_id,
+        retryCount: item.retryCount || 0,
+        maxRetries: item.maxRetries || DEFAULT_MAX_RETRIES,
+        lastError: item.lastError,
+        resultRef: item.resultRef,
+    };
+}
+
+/**
+ * Check if an item is a legacy (pre-V2) queue item.
+ */
+export function isLegacyQueueItem(item: RawQueueItem): boolean {
+    return item && typeof item === 'object' && !('taskKind' in item);
+}
+
+/**
+ * Migrate entire queue to V2 schema if needed.
+ * Returns a new array with all items migrated to V2 format.
+ */
+export function migrateQueueToV2(queue: RawQueueItem[]): EvolutionQueueItem[] {
+    return queue.map(item => isLegacyQueueItem(item) ? migrateToV2(item as unknown as LegacyEvolutionQueueItem) : item as unknown as EvolutionQueueItem);
+}

package/src/service/sleep-cycle.ts

@@ -0,0 +1,157 @@
+/**
+ * Sleep Cycle Orchestrator — extracted from evolution-worker.ts
+ *
+ * Responsibilities:
+ * - Idle workspace detection via nocturnal-runtime.js
+ * - Cooldown enforcement via nocturnal-runtime.js
+ * - Sleep reflection task enqueue orchestration (fire-and-forget)
+ * - Keyword optimization task enqueue orchestration (fire-and-forget)
+ * - Cycle heartbeat tracking and periodic trigger reset
+ *
+ * Does NOT include (remain in evolution-worker.ts facade):
+ * - checkPainFlag, processEvolutionQueueWithResult, processDetectionQueue
+ * - Workflow managers (EmpathyObserver, DeepReflect, Nocturnal)
+ * - Workflow watchdog (runWorkflowWatchdog)
+ * - Pain-flag-triggered immediate heartbeat
+ *
+ * Dependencies: nocturnal-runtime.js, nocturnal-config.js, queue-io.js
+ * Zero imports from evolution-worker.ts.
+ */
+
+import type { WorkspaceContext } from '../core/workspace-context.js';
+import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
+import type { EventLog } from '../core/event-log.js';
+import { checkWorkspaceIdle, checkCooldown } from './nocturnal-runtime.js';
+import { loadNocturnalConfigMerged } from './nocturnal-config.js';
+import { enqueueSleepReflectionTask, enqueueKeywordOptimizationTask } from './queue-io.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface WorkerStatusReport {
+    timestamp: string;
+    cycle_start_ms: number;
+    duration_ms: number;
+    pain_flag: { exists: boolean; score: number | null; source: string | null; enqueued: boolean; skipped_reason: string | null };
+    queue: { total: number; pending: number; in_progress: number; completed_this_cycle: number; failed_this_cycle: number };
+    errors: string[];
+}
+
+export interface CycleOptions {
+    wctx: WorkspaceContext;
+    logger: PluginLogger | undefined;
+    eventLog: EventLog;
+    api: OpenClawPluginApi | undefined;
+    /** Mutable ref to the heartbeat counter — incremented by runCycle on each call */
+    heartbeatCounterRef: { value: number };
+}
+
+// ---------------------------------------------------------------------------
+// Cycle Orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute one sleep-cycle heartbeat.
+ *
+ * Orchestrates:
+ * 1. Load merged nocturnal config
+ * 2. Check workspace idle state
+ * 3. Enqueue keyword_optimization task (independent periodic trigger)
+ * 4. Enqueue sleep_reflection task (idle-based OR periodic trigger + cooldown gate)
+ * 5. Cycle result reporting
+ *
+ * Does NOT directly call checkPainFlag, processEvolutionQueueWithResult, or
+ * processDetectionQueue — those remain in the evolution-worker.ts facade.
+ *
+ * @param options.wctx       — workspace context
+ * @param options.logger     — plugin logger
+ * @param options.eventLog   — event log
+ * @param options.api        — OpenClaw plugin API (optional)
+ * @param options.heartbeatCounterRef — mutable counter, incremented by runCycle
+ */
+export async function runCycle(options: CycleOptions): Promise<WorkerStatusReport> {
+    const { wctx, logger, eventLog: _eventLog, api: _api, heartbeatCounterRef } = options;
+    const cycleStart = Date.now();
+    heartbeatCounterRef.value++;
+
+    // ──── DEBUG: Verify subagent availability in heartbeat context ────
+    const hbSubagent = _api?.runtime?.subagent;
+    logger?.info?.(`[PD:DEBUG:SubagentCheck:Heartbeat] api_exists=${!!_api}, subagent_exists=${!!hbSubagent}, subagent.run_exists=${!!hbSubagent?.run}, heartbeatCounter=${heartbeatCounterRef.value}`);
+    if (hbSubagent?.run) {
+        logger?.info?.('[PD:DEBUG:SubagentCheck:Heartbeat] run entrypoint is callable');
+    }
+
+    const cycleResult: WorkerStatusReport = {
+        timestamp: new Date().toISOString(),
+        cycle_start_ms: cycleStart,
+        duration_ms: 0,
+        pain_flag: { exists: false, score: null, source: null, enqueued: false, skipped_reason: null },
+        queue: { total: 0, pending: 0, in_progress: 0, completed_this_cycle: 0, failed_this_cycle: 0 },
+        errors: [],
+    };
+
+    try {
+        // Load config on each cycle (supports runtime updates) — single file read
+        const mergedConfig = loadNocturnalConfigMerged(wctx.stateDir);
+        const { sleepReflection: sleepConfig, keywordOptimization: kwOptConfig } = mergedConfig;
+
+        const idleResult = checkWorkspaceIdle(wctx.workspaceDir, {});
+        logger?.info?.(`[PD:EvolutionWorker] HEARTBEAT cycle=${new Date().toISOString()} idle=${idleResult.isIdle} idleForMs=${idleResult.idleForMs} userActiveSessions=${idleResult.userActiveSessions} abandonedSessions=${idleResult.abandonedSessionIds.length} lastActivityEpoch=${idleResult.mostRecentActivityAt} triggerMode=${sleepConfig.trigger_mode}`);
+
+        let shouldTrySleepReflection = false;
+
+        // Path 1: Idle-based trigger (default mode)
+        if (idleResult.isIdle && sleepConfig.trigger_mode === 'idle') {
+            logger?.info?.(`[PD:EvolutionWorker] Workspace idle (${idleResult.idleForMs}ms since last activity)`);
+            shouldTrySleepReflection = true;
+        }
+
+        // keyword_optimization: Independent periodic trigger (CORR-07).
+        // Fires every kwOptConfig.period_heartbeats regardless of trigger_mode.
+        // Has its own dedicated config (default 24 heartbeats = 6 hours).
+        if (kwOptConfig.enabled && heartbeatCounterRef.value > 0 && heartbeatCounterRef.value % kwOptConfig.period_heartbeats === 0) {
+            logger?.info?.(`[PD:EvolutionWorker] keyword_optimization trigger at heartbeat ${heartbeatCounterRef.value} (trigger_mode=${sleepConfig.trigger_mode})`);
+            enqueueKeywordOptimizationTask(wctx, logger).catch((err) => {
+                logger?.error?.(`[PD:EvolutionWorker] Failed to enqueue keyword_optimization task: ${String(err)}`);
+            });
+        }
+
+        // Path 2: Periodic trigger for sleep_reflection (fires regardless of idle state)
+        if (sleepConfig.trigger_mode === 'periodic') {
+            if (heartbeatCounterRef.value >= sleepConfig.period_heartbeats) {
+                logger?.info?.(`[PD:EvolutionWorker] Periodic trigger: heartbeatCounter=${heartbeatCounterRef.value} >= period_heartbeats=${sleepConfig.period_heartbeats}`);
+                shouldTrySleepReflection = true;
+                heartbeatCounterRef.value = 0; // Reset counter
+            } else {
+                logger?.info?.(`[PD:EvolutionWorker] Periodic: ${heartbeatCounterRef.value}/${sleepConfig.period_heartbeats} heartbeats — waiting`);
+            }
+        }
+
+        if (shouldTrySleepReflection) {
+            const cooldown = checkCooldown(wctx.stateDir, undefined, {
+                globalCooldownMs: sleepConfig.cooldown_ms,
+                maxRunsPerWindow: sleepConfig.max_runs_per_day,
+                quotaWindowMs: 24 * 60 * 60 * 1000,
+            });
+            logger?.info?.(`[PD:EvolutionWorker] Cooldown check: globalCooldownActive=${cooldown.globalCooldownActive} quotaExhausted=${cooldown.quotaExhausted} runsRemaining=${cooldown.runsRemaining}`);
+            if (!cooldown.globalCooldownActive && !cooldown.quotaExhausted) {
+                logger?.info?.('[PD:EvolutionWorker] Attempting to enqueue sleep_reflection task...');
+                enqueueSleepReflectionTask(wctx, logger).catch((err) => {
+                    logger?.error?.(`[PD:EvolutionWorker] Failed to enqueue sleep_reflection task: ${String(err)}`);
+                });
+            } else {
+                logger?.info?.(`[PD:EvolutionWorker] Skipping sleep_reflection: globalCooldown=${cooldown.globalCooldownActive} quotaExhausted=${cooldown.quotaExhausted}`);
+            }
+        }
+
+        cycleResult.duration_ms = Date.now() - cycleStart;
+    } catch (err) {
+        const errMsg = `Error in runCycle: ${String(err)}`;
+        if (logger) logger.error(`[PD:EvolutionWorker] ${errMsg}`);
+        cycleResult.errors.push(errMsg);
+        cycleResult.duration_ms = Date.now() - cycleStart;
+    }
+
+    return cycleResult;
+}

package/src/service/subagent-workflow/runtime-direct-driver.ts

@@ -56,7 +56,7 @@ export interface CleanupParams {
 }
 
  
-type PluginRuntimeSubagent = {
+export type PluginRuntimeSubagent = {
     run: (params: {
         sessionKey: string;
         message: string;