principles-disciple 1.29.0 → 1.30.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

package/src/core/nocturnal-trajectory-extractor.ts

@@ -95,6 +95,14 @@ export interface NocturnalGateBlock {
   createdAt: string;
 }
 
+/**
+ * User correction sample for nocturnal snapshot.
+ * #268: Wire correction_samples into nocturnal pipeline.
+ */
+export interface NocturnalUserCorrection {
+  correctionCue: string | null;
+}
+
 /**
  * A structured nocturnal session snapshot.
  * Contains all information needed for a reflector to generate decision-point samples.
@@ -114,6 +122,8 @@ export interface NocturnalSessionSnapshot {
   toolCalls: NocturnalToolCall[];
   painEvents: NocturnalPainEvent[];
   gateBlocks: NocturnalGateBlock[];
+  /** #268: User corrections from correction_samples table */
+  userCorrections: NocturnalUserCorrection[];
   /**
    * Summary statistics for quick triage.
    * #246: All fields are now number (never null).
@@ -281,6 +291,8 @@ export class NocturnalTrajectoryExtractor {
     const toolCalls = this.trajectory.listToolCallsForSession(sessionId);
     const painEvents = this.trajectory.listPainEventsForSession(sessionId);
     const gateBlocks = this.trajectory.listGateBlocksForSession(sessionId);
+    // #268: Fetch correction samples for this session
+    const correctionSamples = this.trajectory.listCorrectionSamplesForSession(sessionId);
 
     // Map to sanitized structures
     // SECURITY: Only sanitizedText from assistant turns
@@ -346,6 +358,10 @@ export class NocturnalTrajectoryExtractor {
       toolCalls: nocturnalToolCalls,
       painEvents: nocturnalPainEvents,
       gateBlocks: nocturnalGateBlocks,
+      // #268: Map correction samples to nocturnal format
+      userCorrections: correctionSamples.map((cs: { correctionCue: string | null }) => ({
+        correctionCue: cs.correctionCue,
+      })),
       stats: {
         totalAssistantTurns: sanitizedAssistantTurns.length,
         totalToolCalls: nocturnalToolCalls.length,

package/src/core/trajectory.ts

@@ -935,6 +935,25 @@ export class TrajectoryDatabase {
     }));
   }
 
+  /**
+   * List correction samples for a specific session.
+   * Returns minimal fields for nocturnal use — correction cue only.
+   * #268: Wire correction_samples into nocturnal pipeline.
+   */
+  listCorrectionSamplesForSession(sessionId: string): { correctionCue: string | null }[] {
+    const rows = this.db.prepare(`
+      SELECT cs.sample_id, ut.correction_cue
+      FROM correction_samples cs
+      LEFT JOIN user_turns ut ON ut.id = cs.user_correction_turn_id
+      WHERE cs.session_id = ?
+      ORDER BY cs.created_at DESC
+    `).all(sessionId) as Record<string, unknown>[];
+
+    return rows.map((row) => ({
+      correctionCue: row.correction_cue ? String(row.correction_cue) : null,
+    }));
+  }
+
   reviewCorrectionSample(sampleId: string, status: Exclude<CorrectionSampleReviewStatus, 'pending'>, note?: string): CorrectionSampleRecord {
     const updatedAt = nowIso();
     const updated = this.withWrite(() => {

package/src/index.ts

@@ -17,6 +17,7 @@ import type {
   PluginHookSubagentContext,
 } from './openclaw-sdk.js';
 import * as crypto from 'crypto';
+import * as path from 'path';
 import type { WorkerProfile } from './core/model-deployment-registry.js';
 import { classifyTask } from './core/local-worker-routing.js';
 import { completeShadowObservation, recordShadowRouting } from './core/shadow-observation-registry.js';
@@ -66,6 +67,8 @@ import { extractAgentIdFromSessionKey } from './utils/session-key.js';
 
 // Track initialization to avoid repeated calls
 let workspaceInitialized = false;
+// Track started evolution workers — one per workspace
+const startedWorkspaces = new Set<string>();
 
 /**
  * Resolve workspaceDir for slash commands.
@@ -171,6 +174,23 @@ const plugin = {
             SystemLogger.log(workspaceDir, 'SYSTEM_BOOT', `Principles Disciple online. Language: ${language}`);
             workspaceInitialized = true;
           }
+
+          // ── Start EvolutionWorker for THIS workspace ──
+          // Each agent has its own heartbeat task. When before_prompt_build fires,
+          // it fires for the current agent's workspaceDir. Start one EvolutionWorker
+          // per workspace so each agent's pain signals are processed independently.
+          if (!startedWorkspaces.has(workspaceDir)) {
+            startedWorkspaces.add(workspaceDir);
+            EvolutionWorkerService.api = api;
+            EvolutionWorkerService.start({
+              config: api.config,
+              workspaceDir,
+              stateDir: path.join(workspaceDir, '.state'),
+              logger: api.logger,
+            });
+            api.logger.info(`[PD] EvolutionWorker started for workspace: ${workspaceDir}`);
+          }
+
           const result = await handleBeforePromptBuild(event, { ...ctx, api, workspaceDir });
           
           // Record success

package/src/service/evolution-worker.ts

@@ -17,6 +17,7 @@ import type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
 export type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
 import { LockUnavailableError } from '../config/index.js';
 import { checkWorkspaceIdle, checkCooldown } from './nocturnal-runtime.js';
+import { loadNocturnalConfig } from './nocturnal-config.js';
 import { WorkflowStore } from './subagent-workflow/workflow-store.js';
 import type { WorkflowRow } from './subagent-workflow/types.js';
 import { EmpathyObserverWorkflowManager } from './subagent-workflow/empathy-observer-workflow-manager.js';
@@ -407,6 +408,8 @@ function buildFallbackNocturnalSnapshot(
         toolCalls: [],
         painEvents: fallbackPainEvents,
         gateBlocks: [],
+        // #268: Empty corrections in fallback path (no trajectory data available)
+        userCorrections: [],
         stats: {
             totalAssistantTurns: realStats?.totalAssistantTurns ?? 0,
             totalToolCalls: realStats?.totalToolCalls ?? 0,
@@ -485,14 +488,13 @@ function findRecentDuplicateTask(
     now: number,
     reason?: string
 ): EvolutionQueueItem | undefined {
-     
     // eslint-disable-next-line @typescript-eslint/no-use-before-define
     const key = normalizePainDedupKey(source, preview, reason);
     return queue.find((task) => {
         if (task.status === 'completed') return false;
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
         const taskTime = new Date(task.enqueued_at || task.timestamp).getTime();
         if (!Number.isFinite(taskTime) || (now - taskTime) > PAIN_QUEUE_DEDUP_WINDOW_MS) return false;
-         
         // eslint-disable-next-line @typescript-eslint/no-use-before-define
         return normalizePainDedupKey(task.source, task.trigger_text_preview || '', task.reason) === key;
     });
@@ -547,6 +549,7 @@ function normalizePainDedupKey(source: string, preview: string, reason?: string)
 }
 
  
+ 
 // eslint-disable-next-line @typescript-eslint/max-params
 export function hasRecentDuplicateTask(queue: EvolutionQueueItem[], source: string, preview: string, now: number, reason?: string): boolean {
     return !!findRecentDuplicateTask(queue, source, preview, now, reason);
@@ -675,7 +678,7 @@ function shouldSkipForDedup(
  * Load and migrate the evolution queue. Returns empty array if file doesn't exist.
  */
 function loadEvolutionQueue(queuePath: string): EvolutionQueueItem[] {
-    // eslint-disable-next-line no-useless-assignment
+    // eslint-disable-next-line @typescript-eslint/init-declarations, no-useless-assignment
     let rawQueue: RawQueueItem[] = [];
     try {
         rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
@@ -689,6 +692,7 @@ function loadEvolutionQueue(queuePath: string): EvolutionQueueItem[] {
 /**
  * Build and persist a new sleep_reflection task.
  */
+ 
 // eslint-disable-next-line @typescript-eslint/max-params
 function enqueueNewSleepReflectionTask(
     queue: EvolutionQueueItem[],
@@ -1608,10 +1612,8 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
 
                     // eslint-disable-next-line @typescript-eslint/init-declarations
                     let workflowId: string | undefined;
-                     
                     // eslint-disable-next-line @typescript-eslint/init-declarations
                     let nocturnalManager: NocturnalWorkflowManager;
-                     
                     // eslint-disable-next-line @typescript-eslint/init-declarations
                     let snapshotData: NocturnalSessionSnapshot | undefined;
 
@@ -2014,6 +2016,7 @@ export async function registerEvolutionTaskSession(
 export interface ExtendedEvolutionWorkerService {
     id: string;
     api: OpenClawPluginApi | null;
+    _startedWorkspaces: Set<string>;
     start: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
     stop?: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
 }
@@ -2085,17 +2088,27 @@ async function processEvolutionQueueWithResult(
 export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
     id: 'principles-evolution-worker',
     api: null,
+    _startedWorkspaces: new Set<string>(),
 
     start(ctx: OpenClawPluginServiceContext): void {
+        const workspaceDir = ctx?.workspaceDir;
         const logger = ctx?.logger || console;
         const {api} = this;
-        const workspaceDir = ctx?.workspaceDir;
 
         if (!workspaceDir) {
             if (logger) logger.warn('[PD:EvolutionWorker] workspaceDir not found in service config. Evolution cycle disabled.');
             return;
         }
 
+        // Guard: prevent duplicate starts for the SAME workspace
+        const started = EvolutionWorkerService._startedWorkspaces;
+        if (started.has(workspaceDir)) {
+            ctx?.logger?.info?.(`[PD:EvolutionWorker] Already started for ${workspaceDir}, skipping`);
+            return;
+        }
+
+        started.add(workspaceDir);
+
         const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
         if (logger) logger.info(`[PD:EvolutionWorker] Starting with workspaceDir=${wctx.workspaceDir}, stateDir=${wctx.stateDir}`);
 
@@ -2109,12 +2122,16 @@ export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
         const initialDelay = 5000;
         const interval = config.get('intervals.worker_poll_ms') || (15 * 60 * 1000);
 
+        // Periodic trigger tracking
+        let heartbeatCounter = 0;
+
         async function runCycle(): Promise<void> {
             const cycleStart = Date.now();
+            heartbeatCounter++;
 
             // ──── 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}`);
+            logger?.info?.(`[PD:DEBUG:SubagentCheck:Heartbeat] api_exists=${!!api}, subagent_exists=${!!hbSubagent}, subagent.run_exists=${!!hbSubagent?.run}, heartbeatCounter=${heartbeatCounter}`);
             if (hbSubagent?.run) {
                 logger?.info?.('[PD:DEBUG:SubagentCheck:Heartbeat] run entrypoint is callable');
             }
@@ -2135,18 +2152,45 @@ export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
             };
 
             try {
+                // Load config on each cycle (supports runtime updates)
+                const sleepConfig = loadNocturnalConfig(wctx.stateDir);
+
                 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}`);
-                if (idleResult.isIdle) {
-                    logger?.debug?.(`[PD:EvolutionWorker] Workspace idle (${idleResult.idleForMs}ms since last activity)`);
-                    const cooldown = checkCooldown(wctx.stateDir);
+                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;
+                }
+
+                // Path 2: Periodic trigger (bypasses idle requirement — for debugging)
+                if (!idleResult.isIdle && sleepConfig.trigger_mode === 'periodic') {
+                    if (heartbeatCounter >= sleepConfig.period_heartbeats) {
+                        logger?.info?.(`[PD:EvolutionWorker] Periodic trigger: heartbeatCounter=${heartbeatCounter} >= period_heartbeats=${sleepConfig.period_heartbeats}`);
+                        shouldTrySleepReflection = true;
+                        heartbeatCounter = 0; // Reset counter
+                    } else {
+                        logger?.info?.(`[PD:EvolutionWorker] Periodic: ${heartbeatCounter}/${sleepConfig.period_heartbeats} heartbeats — waiting`);
+                    }
+                }
+
+                if (shouldTrySleepReflection) {
+                    const cooldown = checkCooldown(wctx.stateDir, undefined, {
+                        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}`);
                     }
-                } else {
-                    logger?.debug?.(`[PD:EvolutionWorker] Workspace active (last activity ${idleResult.idleForMs}ms ago)`);
                 }
 
                 const painCheckResult = await checkPainFlag(wctx, logger);

package/src/service/nocturnal-config.ts

@@ -0,0 +1,72 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface SleepReflectionConfig {
+    /** Trigger mode: "idle" (default) or "periodic" */
+    trigger_mode: 'idle' | 'periodic';
+    /** In periodic mode, trigger every N heartbeat cycles */
+    period_heartbeats: number;
+    /** Minimum time between runs (ms) */
+    cooldown_ms: number;
+    /** Maximum runs per 24-hour window */
+    max_runs_per_day: number;
+    /** Whether sleep_reflection is enabled */
+    enabled: boolean;
+}
+
+export interface NocturnalConfig {
+    sleep_reflection?: Partial<SleepReflectionConfig>;
+}
+
+const DEFAULT_SLEEP_REFLECTION: SleepReflectionConfig = {
+    trigger_mode: 'idle',
+    period_heartbeats: 4,       // ~1 hour at 15-min heartbeat interval
+    cooldown_ms: 30 * 60 * 1000, // 30 minutes
+    max_runs_per_day: 3,
+    enabled: true,
+};
+
+const CONFIG_FILENAME = 'nocturnal-config.json';
+
+/**
+ * Resolve the nocturnal config file path.
+ */
+function resolveConfigPath(stateDir: string): string {
+    return path.join(stateDir, CONFIG_FILENAME);
+}
+
+/**
+ * Load nocturnal config from .state/nocturnal-config.json.
+ * Returns default config if file doesn't exist or is malformed.
+ */
+export function loadNocturnalConfig(stateDir: string): SleepReflectionConfig {
+    const configPath = resolveConfigPath(stateDir);
+    let fileConfig: NocturnalConfig = {};
+
+    if (fs.existsSync(configPath)) {
+        try {
+            const raw = fs.readFileSync(configPath, 'utf8');
+            fileConfig = JSON.parse(raw);
+        } catch {
+            // Malformed config — continue with defaults
+        }
+    }
+
+    const fileSleep = fileConfig.sleep_reflection || {};
+
+    return {
+        trigger_mode: fileSleep.trigger_mode === 'periodic' ? 'periodic' : DEFAULT_SLEEP_REFLECTION.trigger_mode,
+        period_heartbeats: typeof fileSleep.period_heartbeats === 'number' && fileSleep.period_heartbeats > 0
+            ? fileSleep.period_heartbeats
+            : DEFAULT_SLEEP_REFLECTION.period_heartbeats,
+        cooldown_ms: typeof fileSleep.cooldown_ms === 'number' && fileSleep.cooldown_ms >= 0
+            ? fileSleep.cooldown_ms
+            : DEFAULT_SLEEP_REFLECTION.cooldown_ms,
+        max_runs_per_day: typeof fileSleep.max_runs_per_day === 'number' && fileSleep.max_runs_per_day > 0
+            ? fileSleep.max_runs_per_day
+            : DEFAULT_SLEEP_REFLECTION.max_runs_per_day,
+        enabled: typeof fileSleep.enabled === 'boolean'
+            ? fileSleep.enabled
+            : DEFAULT_SLEEP_REFLECTION.enabled,
+    };
+}

package/src/service/nocturnal-target-selector.ts

@@ -474,7 +474,10 @@ export class NocturnalTargetSelector {
             toolName: gb.toolName,
             reason: gb.reason,
           })),
-          userCorrections: [],
+          // #268: Use actual correction samples from snapshot instead of empty array
+          userCorrections: snapshot.userCorrections.map((uc) => ({
+            correctionCue: uc.correctionCue ?? undefined,
+          })),
           planApprovals: [],
         });
         hasViolation = violationResult.violated;