principles-disciple 1.19.0 → 1.20.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.19.0",
+  "version": "1.20.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/src/core/nocturnal-snapshot-contract.ts

@@ -14,8 +14,9 @@ function isNonEmptyString(value: unknown): value is string {
   return typeof value === 'string' && value.trim().length > 0;
 }
 
-function isNumberOrNull(value: unknown): value is number | null {
-  return value === null || (typeof value === 'number' && Number.isFinite(value));
+/** #246: Stats fields must now be finite numbers — null is no longer accepted. */
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
 }
 
 export function validateNocturnalSnapshotIngress(
@@ -56,20 +57,20 @@ export function validateNocturnalSnapshotIngress(
   if (!isObjectRecord(stats)) {
     reasons.push('snapshot.stats must be an object');
   } else {
-    if (!isNumberOrNull(stats.totalAssistantTurns)) {
-      reasons.push('snapshot.stats.totalAssistantTurns must be a number or null');
+    if (!isFiniteNumber(stats.totalAssistantTurns)) {
+      reasons.push('snapshot.stats.totalAssistantTurns must be a finite number');
     }
-    if (!isNumberOrNull(stats.totalToolCalls)) {
-      reasons.push('snapshot.stats.totalToolCalls must be a number or null');
+    if (!isFiniteNumber(stats.totalToolCalls)) {
+      reasons.push('snapshot.stats.totalToolCalls must be a finite number');
     }
-    if (typeof stats.totalPainEvents !== 'number' || !Number.isFinite(stats.totalPainEvents)) {
+    if (!isFiniteNumber(stats.totalPainEvents)) {
       reasons.push('snapshot.stats.totalPainEvents must be a finite number');
     }
-    if (!isNumberOrNull(stats.totalGateBlocks)) {
-      reasons.push('snapshot.stats.totalGateBlocks must be a number or null');
+    if (!isFiniteNumber(stats.totalGateBlocks)) {
+      reasons.push('snapshot.stats.totalGateBlocks must be a finite number');
     }
-    if (!isNumberOrNull(stats.failureCount)) {
-      reasons.push('snapshot.stats.failureCount must be a number or null');
+    if (!isFiniteNumber(stats.failureCount)) {
+      reasons.push('snapshot.stats.failureCount must be a finite number');
     }
   }
 
@@ -85,21 +86,6 @@ export function validateNocturnalSnapshotIngress(
     }
   }
 
-  if (!isFallback && isObjectRecord(stats)) {
-    if (stats.totalAssistantTurns === null) {
-      reasons.push('non-fallback snapshot.stats.totalAssistantTurns must be a number');
-    }
-    if (stats.totalToolCalls === null) {
-      reasons.push('non-fallback snapshot.stats.totalToolCalls must be a number');
-    }
-    if (stats.totalGateBlocks === null) {
-      reasons.push('non-fallback snapshot.stats.totalGateBlocks must be a number');
-    }
-    if (stats.failureCount === null) {
-      reasons.push('non-fallback snapshot.stats.failureCount must be a number');
-    }
-  }
-
   if (reasons.length > 0) {
     return { status: 'invalid', reasons };
   }

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

@@ -116,15 +116,18 @@ export interface NocturnalSessionSnapshot {
   gateBlocks: NocturnalGateBlock[];
   /**
    * Summary statistics for quick triage.
-   * When _dataSource is 'pain_context_fallback', these fields are null
-   * to distinguish "no data" from "data is zero".
+   * #246: All fields are now number (never null).
+   * Previously null was used to mean "no trajectory data", but this caused
+   * downstream consumers to crash on arithmetic. The fallback path now
+   * queries the trajectory extractor for real data and falls back to 0.
+   * Use _dataSource === 'pain_context_fallback' to detect partial data.
    */
   stats: {
-    totalAssistantTurns: number | null;
-    totalToolCalls: number | null;
+    totalAssistantTurns: number;
+    totalToolCalls: number;
     totalPainEvents: number;
-    totalGateBlocks: number | null;
-    failureCount: number | null;
+    totalGateBlocks: number;
+    failureCount: number;
   };
   /**
    * #219: Marker for data source to identify fallback/partial stats.

package/src/service/evolution-worker.ts

@@ -132,9 +132,17 @@ async function runWorkflowWatchdog(
             if (dataSource === 'pain_context_fallback') {
               details.push(`fallback_snapshot: nocturnal workflow ${wf.workflow_id} uses pain-context fallback (stats may be incomplete)`);
             }
-            const stats = snapshot.stats as Record<string, number | null> | undefined;
-            if (stats && stats.totalAssistantTurns === null && stats.totalToolCalls === null && stats.totalPainEvents === 0 && stats.totalGateBlocks === null) {
-              details.push(`fallback_snapshot_stats: nocturnal workflow ${wf.workflow_id} has null stats (data unavailable)`);
+            const stats = snapshot.stats as Record<string, number> | undefined;
+            // #246: Stats are now always number (never null). Detect "empty" fallback:
+            // fallback + all counts zero means no real data was available.
+            // NOTE: totalAssistantTurns may be 0 even for valid sessions because
+            // listRecentNocturnalCandidateSessions (used in fallback path) does not
+            // populate assistantTurnCount (only getNocturnalSessionSnapshot does).
+            // We use totalToolCalls=0 as the primary indicator instead.
+            if (stats && dataSource === 'pain_context_fallback' &&
+                stats.totalToolCalls === 0 && stats.totalGateBlocks === 0 &&
+                stats.failureCount === 0) {
+              details.push(`fallback_snapshot_stats: nocturnal workflow ${wf.workflow_id} has empty fallback stats (no trajectory data found)`);
             }
           }
         } catch { /* ignore malformed metadata */ }
@@ -335,7 +343,10 @@ function isSessionAtOrBeforeTriggerTime(
     return true;
 }
 
-function buildFallbackNocturnalSnapshot(sleepTask: EvolutionQueueItem): NocturnalSessionSnapshot | null {
+function buildFallbackNocturnalSnapshot(
+    sleepTask: EvolutionQueueItem,
+    extractor?: ReturnType<typeof createNocturnalTrajectoryExtractor> | null
+): NocturnalSessionSnapshot | null {
     const painContext = sleepTask.recentPainContext;
     if (!painContext) {
         return null;
@@ -349,6 +360,30 @@ function buildFallbackNocturnalSnapshot(sleepTask: EvolutionQueueItem): Nocturna
         createdAt: painContext.mostRecent.timestamp,
     }] : [];
 
+    // #246: Try to extract real session stats from trajectory DB for the pain session.
+    // The main path tries getNocturnalSessionSnapshot which returns null when no session
+    // exists. Here we attempt a lighter query via listRecentNocturnalCandidateSessions
+    // to at least get summary counts for the pain-triggering session.
+    let realStats: { totalAssistantTurns: number; totalToolCalls: number; failureCount: number; totalGateBlocks: number } | null = null;
+    if (extractor && painContext.mostRecent?.sessionId) {
+        try {
+            // #246-fix: Use minToolCalls=0 to avoid filtering out sessions with 0 tool calls.
+            // The pain-triggering session may have no tool calls but still be worth tracking.
+            const summaries = extractor.listRecentNocturnalCandidateSessions({ limit: 300, minToolCalls: 0 });
+            const match = summaries.find(s => s.sessionId === painContext.mostRecent!.sessionId);
+            if (match) {
+                realStats = {
+                    totalAssistantTurns: match.assistantTurnCount,
+                    totalToolCalls: match.toolCallCount,
+                    failureCount: match.failureCount,
+                    totalGateBlocks: match.gateBlockCount,
+                };
+            }
+        } catch {
+            // Best effort — non-fatal
+        }
+    }
+
     return {
         sessionId: painContext.mostRecent?.sessionId || sleepTask.id,
         startedAt: sleepTask.timestamp,
@@ -359,11 +394,11 @@ function buildFallbackNocturnalSnapshot(sleepTask: EvolutionQueueItem): Nocturna
         painEvents: fallbackPainEvents,
         gateBlocks: [],
         stats: {
-            totalAssistantTurns: null,
-            totalToolCalls: null,
-            failureCount: null,
+            totalAssistantTurns: realStats?.totalAssistantTurns ?? 0,
+            totalToolCalls: realStats?.totalToolCalls ?? 0,
+            failureCount: realStats?.failureCount ?? 0,
             totalPainEvents: painContext.recentPainCount,
-            totalGateBlocks: null,
+            totalGateBlocks: realStats?.totalGateBlocks ?? 0,
         },
         _dataSource: 'pain_context_fallback',
     };
@@ -1466,8 +1501,9 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                     } else {
                         // Phase 1: Build trajectory snapshot for Nocturnal pipeline
                         // Priority: Pain signal sessionId → Task ID → Recent session with violations
+                        let extractor: ReturnType<typeof createNocturnalTrajectoryExtractor> | null = null;
                         try {
-                            const extractor = createNocturnalTrajectoryExtractor(wctx.workspaceDir);
+                            extractor = createNocturnalTrajectoryExtractor(wctx.workspaceDir);
 
                             // 1. Try exact session ID from pain signal (most accurate)
                             const painSessionId = sleepTask.recentPainContext?.mostRecent?.sessionId;
@@ -1516,8 +1552,8 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
 
                         // Phase 2: If no trajectory data, try pain-context fallback
                         if (!snapshotData && sleepTask.recentPainContext) {
-                            logger?.warn?.(`[PD:EvolutionWorker] Using pain-context fallback for ${sleepTask.id}: trajectory stats unavailable (stats will be null)`);
-                            snapshotData = buildFallbackNocturnalSnapshot(sleepTask) ?? undefined;
+                            logger?.warn?.(`[PD:EvolutionWorker] Using pain-context fallback for ${sleepTask.id}: trajectory snapshot unavailable, will try session summary from extractor`);
+                            snapshotData = buildFallbackNocturnalSnapshot(sleepTask, extractor) ?? undefined;
                         }
 
                         const snapshotValidation = validateNocturnalSnapshotIngress(snapshotData);

package/tests/core/nocturnal-snapshot-contract.test.ts

@@ -54,10 +54,35 @@ describe('validateNocturnalSnapshotIngress', () => {
       toolCalls: [],
       painEvents: [],
       gateBlocks: [],
+      stats: {
+        totalAssistantTurns: 0,
+        totalToolCalls: 0,
+        totalPainEvents: 0,
+        totalGateBlocks: 0,
+        failureCount: 0,
+      },
+      _dataSource: 'pain_context_fallback',
+    });
+
+    expect(result.status).toBe('invalid');
+    expect(result.reasons).toContain('fallback snapshot must contain at least one pain signal');
+  });
+
+  // #246: null stats fields should now be rejected (they used to be accepted for fallback)
+  it('rejects null values in stats fields', () => {
+    const result = validateNocturnalSnapshotIngress({
+      sessionId: 'session-1',
+      startedAt: '2026-04-10T00:00:00.000Z',
+      updatedAt: '2026-04-10T00:00:00.000Z',
+      assistantTurns: [],
+      userTurns: [],
+      toolCalls: [],
+      painEvents: [{ source: 'test', score: 5, severity: 'high', reason: 'test', createdAt: '2026-04-10T00:00:00.000Z' }],
+      gateBlocks: [],
       stats: {
         totalAssistantTurns: null,
         totalToolCalls: null,
-        totalPainEvents: 0,
+        totalPainEvents: 1,
         totalGateBlocks: null,
         failureCount: null,
       },
@@ -65,6 +90,32 @@ describe('validateNocturnalSnapshotIngress', () => {
     });
 
     expect(result.status).toBe('invalid');
-    expect(result.reasons).toContain('fallback snapshot must contain at least one pain signal');
+    expect(result.reasons).toContain('snapshot.stats.totalAssistantTurns must be a finite number');
+    expect(result.reasons).toContain('snapshot.stats.totalToolCalls must be a finite number');
+    expect(result.reasons).toContain('snapshot.stats.totalGateBlocks must be a finite number');
+    expect(result.reasons).toContain('snapshot.stats.failureCount must be a finite number');
+  });
+
+  it('accepts fallback snapshot with valid stats and pain signal', () => {
+    const result = validateNocturnalSnapshotIngress({
+      sessionId: 'session-1',
+      startedAt: '2026-04-10T00:00:00.000Z',
+      updatedAt: '2026-04-10T00:00:00.000Z',
+      assistantTurns: [],
+      userTurns: [],
+      toolCalls: [],
+      painEvents: [{ source: 'test', score: 5, severity: 'high', reason: 'test', createdAt: '2026-04-10T00:00:00.000Z' }],
+      gateBlocks: [],
+      stats: {
+        totalAssistantTurns: 0,
+        totalToolCalls: 0,
+        totalPainEvents: 1,
+        totalGateBlocks: 0,
+        failureCount: 0,
+      },
+      _dataSource: 'pain_context_fallback',
+    });
+
+    expect(result.status).toBe('valid');
   });
 });