principles-disciple 1.94.0 → 1.96.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.94.0",
+  "version": "1.96.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/src/commands/pain.ts

@@ -349,10 +349,31 @@ export async function handlePainReportCommand(ctx: PluginCommandContext): Promis
       };
     }
 
+    if (result.status === 'retried') {
+      const errorInfo = result.failureCategory
+        ? (isZh ? `\n⚠️ **错误类别**: ${result.failureCategory}` : `\n⚠️ **Error category**: ${result.failureCategory}`)
+        : '';
+      const messageInfo = result.message
+        ? (isZh ? `\n📝 **详情**: ${result.message}` : `\n📝 **Detail**: ${result.message}`)
+        : '';
+      return {
+        text: isZh
+          ? `✅ Pain 已记录，诊断任务已进入重试\n\n📋 **Pain ID**: ${result.painId}\n🔧 **Task ID**: ${result.taskId}${errorInfo}${messageInfo}\n\n诊断任务将在后台自动重试。使用 \`/pd-status\` 查看任务状态。`
+          : `✅ Pain recorded, diagnosis task entered retry\n\n📋 **Pain ID**: ${result.painId}\n🔧 **Task ID**: ${result.taskId}${errorInfo}${messageInfo}\n\nThe diagnosis task will retry automatically in the background. Use \`/pd-status\` to check task status.`,
+      };
+    }
+
+    // status === 'failed' | 'skipped' | 'degraded' — pain was NOT accepted
+    const reasonInfo = result.failureCategory
+      ? (isZh ? `\n⚠️ **原因**: ${result.failureCategory}` : `\n⚠️ **Reason**: ${result.failureCategory}`)
+      : '';
+    const messageInfo = result.message
+      ? (isZh ? `\n📝 **详情**: ${result.message}` : `\n📝 **Detail**: ${result.message}`)
+      : '';
     return {
       text: isZh
-        ? `⚠️ Pain 记录未成功 (status: ${result.status})。请检查系统日志或使用 \`/pd-status\` 查看状态。`
-        : `⚠️ Pain recording not accepted (status: ${result.status}). Check system logs or use \`/pd-status\` for status.`,
+        ? `❌ Pain 记录未成功 (status: ${result.status})${reasonInfo}${messageInfo}\n\n请检查系统日志或使用 \`/pd-status\` 查看状态。`
+        : `❌ Pain recording not accepted (status: ${result.status})${reasonInfo}${messageInfo}\n\nCheck system logs or use \`/pd-status\` for status.`,
     };
   } catch (err) {
     return {

package/src/core/pain-diagnostic-gate.ts

@@ -88,6 +88,21 @@ export function resetPainDiagnosticGateForTest(): void {
   lastDiagnosedAtByEpisode.clear();
 }
 
+/**
+ * Check whether cooldown is currently active for a given episode.
+ * Used by the trigger controller (PEAT-B2) to align its cooldown decision
+ * with the PainDiagnosticGate's cooldown state.
+ */
+export function isCooldownActiveForEpisode(
+  source: string,
+  sessionId: string | undefined,
+  errorHash: string | undefined,
+  cooldownMs?: number,
+): boolean {
+  const episodeKey = buildEpisodeKey({ source, sessionId, errorHash } as PainDiagnosticGateInput);
+  return withinCooldown({ source, sessionId, errorHash, cooldownMs } as PainDiagnosticGateInput, episodeKey);
+}
+
 export function evaluatePainDiagnosticGate(input: PainDiagnosticGateInput): PainDiagnosticGateDecision {
   const source = normalizedSource(input.source);
   const episodeKey = buildEpisodeKey(input);

package/src/hooks/after-tool-call-helpers.ts

@@ -23,10 +23,11 @@ import { WorkspaceContext } from '../core/workspace-context.js';
 import { getEvolutionLogger, createTraceId } from '../core/evolution-logger.js';
 import { recordEvolutionSuccess, recordEvolutionFailure } from '../core/evolution-engine.js';
 import type { PluginHookAfterToolCallEvent } from '../openclaw-sdk.js';
-import { evaluatePainDiagnosticGate } from '../core/pain-diagnostic-gate.js';
+import { evaluatePainDiagnosticGate, isCooldownActiveForEpisode } from '../core/pain-diagnostic-gate.js';
 import { sanitizeForEvidence, sanitizeToolParamsForEvidence } from './message-sanitize.js';
 import { loadFeatureFlagFromConfig } from '../core/pd-config-loader.js';
 import { resolveSourceKindFromToolFailure, evaluateEvidenceTriage } from './triage-adapter.js';
+import { evaluateTriggerController } from '@principles/core/runtime-v2';
 import { buildTrajectoryEvidence } from './trajectory-evidence.js';
 import type { ToolCallOutcome, ToolCallObservation, PainAdmissionDecision } from './after-tool-call-types.js';
 
@@ -347,24 +348,44 @@ export function evaluatePainAdmissionForToolCall(
   const failureSource = outcome.failureSource ?? 'tool_failure';
 
   // PEAT-B1: Evidence triage (feature-flagged)
+  // PEAT-B2: Trigger controller adds structured outcome + cooldown awareness
   const painTriageFlag = loadFeatureFlagFromConfig(workspaceDir, 'painEvidenceAdmission');
   if (painTriageFlag.enabled) {
     const sourceKind = resolveSourceKindFromToolFailure(event.toolName, failureSource);
     const triage = evaluateEvidenceTriage(sourceKind, observation.painScore);
-    if (triage.decision !== 'admit') {
-      SystemLogger.log(workspaceDir, 'TRIAGE_EVIDENCE_ONLY', JSON.stringify({
-        sourceKind: triage.sourceKind,
-        decision: triage.decision,
-        reason: triage.reason,
-        nextAction: triage.nextAction,
+
+    // PEAT-B2: Evaluate trigger controller for structured decision
+    // Compute real cooldown state from PainDiagnosticGate's episode map
+    // so trigger decision aligns with the gate's cooldown logic (EP-07).
+    const cooldownActive = isCooldownActiveForEpisode(
+      failureSource,
+      sessionId,
+      latestFailureState?.lastErrorHash,
+    );
+    const triggerDecision = evaluateTriggerController({
+      triageResult: triage,
+      isOwnerManual: false, // tool failures are never owner manual
+      isCooldownActive: cooldownActive,
+      isValid: true,
+      score: observation.painScore,
+      sessionId,
+    });
+
+    if (!triggerDecision.shouldCreateDiagnosticTask) {
+      SystemLogger.log(workspaceDir, 'TRIGGER_DECISION', JSON.stringify({
+        outcome: triggerDecision.outcome,
+        sourceKind: triggerDecision.sourceKind,
+        reason: triggerDecision.reason,
+        nextAction: triggerDecision.nextAction,
+        triageDecision: triggerDecision.triageDecision,
         tool: event.toolName,
         path: observation.relPath,
       }));
       return {
         admitted: false,
         stage: 'triage_evidence_only',
-        reason: triage.reason,
-        detail: `sourceKind=${triage.sourceKind}, decision=${triage.decision}, nextAction=${triage.nextAction}`,
+        reason: triggerDecision.reason,
+        detail: `outcome=${triggerDecision.outcome}, sourceKind=${triggerDecision.sourceKind}, nextAction=${triggerDecision.nextAction}`,
       };
     }
   }

package/src/hooks/pain.ts

@@ -74,6 +74,20 @@ export async function emitPainDetectedEvent(wctx: WorkspaceContext, event: Evolu
     const painData = event.data as PainDetectedData;
     try {
       const service = createPainToPrincipleService(wctx);
+      const isManual = painData.source === 'manual' || painData.source === 'pain' || painData.source === 'skill:pain';
+
+      // PEAT-B2: Record trigger decision for observability
+      if (isManual) {
+        SystemLogger.log(wctx.workspaceDir, 'TRIGGER_DECISION', JSON.stringify({
+          outcome: 'manual_owner_admitted',
+          sourceKind: 'owner_reported',
+          reason: 'Owner explicit manual pain. Bypasses triage and cooldown.',
+          nextAction: 'create_diagnostic_task',
+          painId: painData.painId,
+          score: painData.score,
+        }));
+      }
+
       const result = await service.recordPain({
         painId: painData.painId,
         painType: painData.painType,
@@ -307,6 +321,20 @@ function handleManualPain(
       payload = JSON.stringify({ reason: gate.reason, detail: '(log serialization failed)' });
     }
     SystemLogger.log(workspaceDir, 'PAIN_GATE_REJECTED', payload);
+
+    // PEAT-B2: Record trigger decision even when cooldown blocks manual pain
+    const painTriageFlag = loadPdConfigForPlugin(workspaceDir);
+    if (painTriageFlag.effective) {
+      SystemLogger.log(workspaceDir, 'TRIGGER_DECISION', JSON.stringify({
+        outcome: 'cooldown_skipped',
+        sourceKind: 'owner_reported',
+        reason: `Manual pain within cooldown: ${gate.detail}`,
+        nextAction: 'wait_for_cooldown_or_manual_retrigger',
+        isOwnerManual: true,
+        sessionId,
+        score: 100,
+      }));
+    }
     return;
   }
 

package/tests/commands/pain.test.ts

@@ -1,10 +1,19 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { handlePainCommand } from '../../src/commands/pain.js';
+import { handlePainCommand, handlePainReportCommand } from '../../src/commands/pain.js';
 import * as sessionTracker from '../../src/core/session-tracker.js';
 import { WorkspaceContext } from '../../src/core/workspace-context.js';
 
 vi.mock('../../src/core/session-tracker.js');
 vi.mock('../../src/core/workspace-context.js');
+vi.mock('../../src/core/pd-config-loader.js', () => ({
+  loadPdConfigForPlugin: vi.fn().mockReturnValue({ ok: true, effective: {}, source: 'defaults', warnings: [], errors: [] }),
+}));
+vi.mock('@principles/core/runtime-v2', () => ({
+  PainToPrincipleService: vi.fn(),
+  PrincipleTreeLedgerAdapter: vi.fn(function(this: any) { this.stateDir = ''; }),
+}));
+
+import { PainToPrincipleService } from '@principles/core/runtime-v2';
 
 describe('Pain Command', () => {
     const workspaceDir = '/mock/workspace';
@@ -106,3 +115,173 @@ describe('Pain Command', () => {
         expect(result.text).toContain('approved samples');
     });
 });
+
+describe('Pain Report Command (/pd-pain)', () => {
+    const workspaceDir = '/mock/workspace';
+    const sessionId = 's1';
+
+    const mockEvolutionReducer = { emitSync: vi.fn() };
+    const mockWctx = {
+        workspaceDir,
+        stateDir: '/mock/workspace/.state',
+        evolutionReducer: mockEvolutionReducer,
+    };
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.mocked(WorkspaceContext.fromHookContext).mockReturnValue(mockWctx as any);
+    });
+
+    async function runPainReport(args: string, lang = 'en') {
+        return handlePainReportCommand({
+            args,
+            config: { workspaceDir, language: lang },
+            sessionId,
+        } as any);
+    }
+
+    it('rejects empty args', async () => {
+        const result = await runPainReport('');
+        expect(result.text).toContain('Please provide a pain reason');
+    });
+
+    it('rejects missing session ID', async () => {
+        const result = await handlePainReportCommand({
+            args: 'something broke',
+            config: { workspaceDir, language: 'en' },
+        } as any);
+        expect(result.text).toContain('Session ID not available');
+    });
+
+    it('reports success when recordPain returns succeeded', async () => {
+        const mockRecordPain = vi.fn().mockResolvedValue({
+            status: 'succeeded',
+            painId: 'manual_123_abc',
+            taskId: 'diagnosis_manual_123_abc',
+            candidateIds: [],
+            ledgerEntryIds: [],
+            observabilityWarnings: [],
+            latencyMs: 100,
+        });
+        vi.mocked(PainToPrincipleService).mockImplementation(function(this: any) { this.recordPain = mockRecordPain; } as any);
+
+        const result = await runPainReport('something broke');
+        expect(result.text).toContain('Pain recorded');
+        expect(result.text).toContain('manual_');
+        expect(result.text).not.toContain('not accepted');
+    });
+
+    it('reports retried as pain recorded with retry info, NOT as "not accepted"', async () => {
+        const mockRecordPain = vi.fn().mockResolvedValue({
+            status: 'retried',
+            painId: 'manual_456_def',
+            taskId: 'diagnosis_manual_456_def',
+            failureCategory: 'output_invalid',
+            message: 'Diagnostician output failed validation',
+            candidateIds: [],
+            ledgerEntryIds: [],
+            observabilityWarnings: [],
+            latencyMs: 200,
+        });
+        vi.mocked(PainToPrincipleService).mockImplementation(function(this: any) { this.recordPain = mockRecordPain; } as any);
+
+        const result = await runPainReport('something broke');
+        expect(result.text).toContain('Pain recorded');
+        expect(result.text).toContain('retry');
+        expect(result.text).toContain('diagnosis_manual_456_def');
+        expect(result.text).toContain('output_invalid');
+        expect(result.text).toContain('/pd-status');
+        // Must NOT say "not accepted" or "failed"
+        expect(result.text).not.toContain('not accepted');
+        expect(result.text).not.toContain('未成功');
+    });
+
+    it('reports retried in Chinese correctly', async () => {
+        const mockRecordPain = vi.fn().mockResolvedValue({
+            status: 'retried',
+            painId: 'manual_789_xyz',
+            taskId: 'diagnosis_manual_789_xyz',
+            failureCategory: 'output_invalid',
+            candidateIds: [],
+            ledgerEntryIds: [],
+            observabilityWarnings: [],
+            latencyMs: 200,
+        });
+        vi.mocked(PainToPrincipleService).mockImplementation(function(this: any) { this.recordPain = mockRecordPain; } as any);
+
+        const result = await runPainReport('something broke', 'zh');
+        expect(result.text).toContain('Pain 已记录');
+        expect(result.text).toContain('重试');
+        expect(result.text).not.toContain('未成功');
+        expect(result.text).not.toContain('not accepted');
+    });
+
+    it('reports retried without failureCategory or message', async () => {
+        const mockRecordPain = vi.fn().mockResolvedValue({
+            status: 'retried',
+            painId: 'manual_000_nocat',
+            taskId: 'diagnosis_manual_000_nocat',
+            candidateIds: [],
+            ledgerEntryIds: [],
+            observabilityWarnings: [],
+            latencyMs: 150,
+        });
+        vi.mocked(PainToPrincipleService).mockImplementation(function(this: any) { this.recordPain = mockRecordPain; } as any);
+
+        const result = await runPainReport('something broke');
+        expect(result.text).toContain('Pain recorded');
+        expect(result.text).toContain('retry');
+        expect(result.text).toContain('diagnosis_manual_000_nocat');
+        // No error category or detail lines when absent
+        expect(result.text).not.toContain('Error category');
+        expect(result.text).not.toContain('Detail');
+    });
+
+    it('reports failed as "not accepted" with reason', async () => {
+        const mockRecordPain = vi.fn().mockResolvedValue({
+            status: 'failed',
+            painId: 'manual_fail_1',
+            taskId: 'diagnosis_manual_fail_1',
+            failureCategory: 'runtime_unavailable',
+            message: 'No runner available',
+            candidateIds: [],
+            ledgerEntryIds: [],
+            observabilityWarnings: [],
+            latencyMs: 50,
+        });
+        vi.mocked(PainToPrincipleService).mockImplementation(function(this: any) { this.recordPain = mockRecordPain; } as any);
+
+        const result = await runPainReport('something broke');
+        expect(result.text).toContain('not accepted');
+        expect(result.text).toContain('failed');
+        expect(result.text).toContain('runtime_unavailable');
+        expect(result.text).toContain('No runner available');
+    });
+
+    it('reports degraded as "not accepted"', async () => {
+        const mockRecordPain = vi.fn().mockResolvedValue({
+            status: 'degraded',
+            painId: 'manual_deg_1',
+            taskId: 'diagnosis_manual_deg_1',
+            candidateIds: [],
+            ledgerEntryIds: [],
+            observabilityWarnings: [],
+            latencyMs: 30,
+        });
+        vi.mocked(PainToPrincipleService).mockImplementation(function(this: any) { this.recordPain = mockRecordPain; } as any);
+
+        const result = await runPainReport('something broke');
+        expect(result.text).toContain('not accepted');
+        expect(result.text).toContain('degraded');
+    });
+
+    it('reports error on exception', async () => {
+        vi.mocked(PainToPrincipleService).mockImplementation(function(this: any) {
+            throw new Error('DB connection failed');
+        });
+
+        const result = await runPainReport('something broke');
+        expect(result.text).toContain('Failed to record pain');
+        expect(result.text).toContain('DB connection failed');
+    });
+});