principles-disciple 1.103.0 → 1.104.1

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.103.0",
+  "version": "1.104.1",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

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

@@ -23,9 +23,8 @@ 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, isCooldownActiveForEpisode } from '../core/pain-diagnostic-gate.js';
+import { isCooldownActive as isTriggerCooldownActive, markEpisodeAsDiagnosed, clearCooldownState } from './trigger-cooldown-tracker.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';
@@ -40,8 +39,13 @@ import type { ToolCallOutcome, ToolCallObservation, PainAdmissionDecision } from
  * Extracts exitCode logic, determines failure/success, classifies failure source.
  */
 export function classifyToolCallOutcome(event: PluginHookAfterToolCallEvent): ToolCallOutcome {
-  const resultObj = (event.result && typeof event.result === 'object') ? event.result as Record<string, unknown> : null;
-  const details = resultObj?.details && typeof resultObj.details === 'object' ? resultObj.details as Record<string, unknown> : null;
+  // EP-01: Validate event.result at runtime instead of `as` cast
+  const resultObj = (event.result && typeof event.result === 'object' && !Array.isArray(event.result))
+    ? event.result as Record<string, unknown>  // safe: guarded by typeof + Array.isArray checks above
+    : null;
+  const details = (resultObj && resultObj.details && typeof resultObj.details === 'object' && !Array.isArray(resultObj.details))
+    ? resultObj.details as Record<string, unknown>  // safe: guarded by typeof + Array.isArray checks above
+    : null;
   const topExitCode = resultObj?.exitCode;
   const detailExitCode = details?.exitCode;
 
@@ -315,13 +319,26 @@ export function handleProbationFeedback(
 
 const WRITE_TOOLS = ['write', 'edit', 'apply_patch', 'write_file', 'edit_file', 'replace'];
 
+/**
+ * Cooldown map for trigger controller decisions.
+ *
+ * PRI-363: This replaces the hidden map in PainDiagnosticGate.
+ * Core trigger-controller is stateless; plugin layer owns cooldown state.
+ *
+ * EP-05: Loop state freshness — each check reads fresh state from this map.
+ */
+const TRIGGER_COOLDOWN_MAP = new Map<string, number>();
+
 /**
  * Evaluate whether a tool failure should trigger pain diagnosis.
  *
+ * PRI-363: Single-gate architecture — only TriggerController decides.
+ *
  * Combines:
  * 1. Write-tool check — only write tools on failures enter this path
- * 2. PEAT-B1 triage — if feature flag is on, check evidence triage
- * 3. PainDiagnosticGate — cooldown + threshold check
+ * 2. PEAT-B1 triage — evidence triage (always enabled now)
+ * 3. PEAT-B2 trigger controller — single source of truth for task creation
+ * 4. Cooldown tracking — plugin layer owns this state
  *
  * Returns a structured decision with reason and stage.
  */
@@ -333,7 +350,7 @@ export function evaluatePainAdmissionForToolCall(
   sessionState: SessionState | undefined,
   sessionId: string,
   workspaceDir: string,
-  config: { get: (key: string) => unknown },
+  _config: { get: (key: string) => unknown },
 ): PainAdmissionDecision {
   // Only write-tool failures enter the pain path
   if (!WRITE_TOOLS.includes(event.toolName) || !outcome.isFailure) {
@@ -347,98 +364,64 @@ 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);
-
-    // 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: triggerDecision.reason,
-        detail: `outcome=${triggerDecision.outcome}, sourceKind=${triggerDecision.sourceKind}, nextAction=${triggerDecision.nextAction}`,
-      };
-    }
-  }
+  // Check cooldown before calling trigger controller
+  const cooldownActive = isTriggerCooldownActive(
+    failureSource,
+    sessionId,
+    latestFailureState?.lastErrorHash,
+    TRIGGER_COOLDOWN_MAP,
+  );
+
+  // PEAT-B1: Evidence triage (with consecutiveErrors and isRisky for upgrade logic)
+  const sourceKind = resolveSourceKindFromToolFailure(event.toolName, failureSource);
+  const triage = evaluateEvidenceTriage(sourceKind, observation.painScore, {
+    consecutiveErrors: (latestFailureState ?? sessionState)?.consecutiveErrors,
+    isRisky: observation.isRisk,
+  });
 
-  // PainDiagnosticGate evaluation
-  const diagnosticGate = evaluatePainDiagnosticGate({
-    source: failureSource,
+  // PEAT-B2: Trigger controller — single source of truth for task creation
+  const triggerDecision = evaluateTriggerController({
+    triageResult: triage,
+    isOwnerManual: false, // tool failures are never owner manual
+    isCooldownActive: cooldownActive,
+    isValid: true,
     score: observation.painScore,
-    currentGfi: (latestFailureState ?? sessionState)?.currentGfi ?? 0,
-    consecutiveErrors: (latestFailureState ?? sessionState)?.consecutiveErrors ?? 0,
-    isRisky: observation.isRisk,
-    errorHash: latestFailureState?.lastErrorHash,
     sessionId,
-    thresholds: {
-      painTrigger: (config.get('thresholds.pain_trigger') as number) || 40,
-      highSeverity: (config.get('severity_thresholds.high') as number) || 70,
-      repeatedFailure: (config.get('thresholds.stuck_loops_trigger') as number) || 4,
-    },
   });
 
-  if (!diagnosticGate.shouldDiagnose) {
-    SystemLogger.log(workspaceDir, 'PAIN_DIAGNOSE_SKIPPED', `Tool failure recorded as friction only: ${diagnosticGate.detail}; tool=${event.toolName}; path=${observation.relPath}`);
-    let rejectPayload: string;
-    try {
-      rejectPayload = JSON.stringify({
-        reason: diagnosticGate.reason,
-        detail: diagnosticGate.detail,
-        source: failureSource,
-        sessionId,
-        gfi: (latestFailureState ?? sessionState)?.currentGfi ?? 0,
-        score: observation.painScore,
-      });
-    } catch (e) {
-      SystemLogger.log(workspaceDir, 'PAYLOAD_SERIALIZE_FAILED', String(e));
-      rejectPayload = JSON.stringify({ reason: diagnosticGate.reason, detail: '(log serialization failed)' });
-    }
-    SystemLogger.log(workspaceDir, 'PAIN_GATE_REJECTED', rejectPayload);
-
+  // Log the decision
+  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,
+  }));
+
+  // If trigger controller says yes, mark cooldown and admit
+  if (triggerDecision.shouldCreateDiagnosticTask) {
+    markEpisodeAsDiagnosed(
+      failureSource,
+      sessionId,
+      latestFailureState?.lastErrorHash,
+      TRIGGER_COOLDOWN_MAP,
+    );
     return {
-      admitted: false,
-      stage: 'gate_rejected',
-      reason: diagnosticGate.reason,
-      detail: diagnosticGate.detail,
-      gateResult: { shouldDiagnose: false, reason: diagnosticGate.reason, detail: diagnosticGate.detail },
+      admitted: true,
+      stage: 'trigger_admitted',
+      reason: triggerDecision.reason,
+      detail: `outcome=${triggerDecision.outcome}, sourceKind=${triggerDecision.sourceKind}, nextAction=${triggerDecision.nextAction}`,
     };
   }
 
+  // Otherwise, reject with trigger controller's reason
   return {
-    admitted: true,
-    stage: 'gate_admitted',
-    reason: diagnosticGate.reason,
-    detail: diagnosticGate.detail,
-    gateResult: { shouldDiagnose: true, reason: diagnosticGate.reason, detail: diagnosticGate.detail },
+    admitted: false,
+    stage: 'trigger_rejected',
+    reason: triggerDecision.reason,
+    detail: `outcome=${triggerDecision.outcome}, sourceKind=${triggerDecision.sourceKind}, nextAction=${triggerDecision.nextAction}`,
   };
 }
 
@@ -562,6 +545,13 @@ export function emitPainIfAdmitted(
 
 export { buildTrajectoryEvidence } from './trajectory-evidence.js';
 
+/**
+ * Reset trigger cooldown state (for tests).
+ */
+export function resetTriggerCooldownForTest(): void {
+  clearCooldownState(TRIGGER_COOLDOWN_MAP);
+}
+
 // ── Source Classification ────────────────────────────────────────────────────
 
 /**

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

@@ -69,23 +69,17 @@ export interface ToolCallObservation {
 /**
  * Result of evaluating whether a tool failure should trigger pain diagnosis.
  *
- * Encapsulates the combined triage + PainDiagnosticGate decision.
+ * Encapsulates the single-gate trigger controller decision.
  */
 export interface PainAdmissionDecision {
   /** Whether the tool failure should proceed to pain emission */
   readonly admitted: boolean;
   /** The admission stage that made the decision */
-  readonly stage: 'triage_evidence_only' | 'gate_rejected' | 'gate_admitted' | 'not_applicable';
+  readonly stage: 'not_applicable' | 'trigger_admitted' | 'trigger_rejected';
   /** Human-readable reason for the decision */
   readonly reason: string;
   /** Detail about the decision */
   readonly detail: string;
-  /** The diagnostic gate result (if gate was evaluated) */
-  readonly gateResult?: {
-    readonly shouldDiagnose: boolean;
-    readonly reason: string;
-    readonly detail: string;
-  };
 }
 
 // ── Friction Update Result ──────────────────────────────────────────────────

package/src/hooks/raw-observation-adapter.ts

@@ -0,0 +1,231 @@
+/**
+ * Raw Observation Adapter — PRI-362
+ *
+ * Unified source-kind resolution from RawObservation.
+ *
+ * Replaces scattered resolveSourceKindFrom* functions with a single
+ * field-driven adapter that maps observation fields to SourceKind.
+ *
+ * Field precedence (highest to lowest):
+ * 1. isManualEntry → owner_reported
+ * 2. isGateBlock → rulehost_block
+ * 3. isSubagentError → subagent_error
+ * 4. isRateLimit → rate_limit (if true)
+ * 5. toolName === 'pain' / 'skill:pain' → agent_on_owner_request (with openclaw_context_bound) / owner_reported
+ * 6. failureSource → tool_failure / dispatch_error
+ * 7. isGfiTriggered → gfi_threshold
+ * 8. detectionSource → llm_paralysis / semantic / empathy_inferred / unknown
+ * 9. Fallback → unknown
+ *
+ * ERR checklist:
+ * - ERR-001: Source kind resolved from runtime values, no `as` casts.
+ * - ERR-002: Every path returns a valid SourceKind (fallback to 'unknown').
+ * - EP-01: Runtime values validated before use.
+ */
+
+import type { SourceKind } from '@principles/core/runtime-v2';
+import type { RawObservation } from './raw-observation-types.js';
+
+/**
+ * Resolve SourceKind from a unified RawObservation.
+ *
+ * This function replaces the scattered resolveSourceKindFrom* functions
+ * and provides a single entry point for source-kind classification.
+ *
+ * Field precedence is explicitly defined in the function body to ensure
+ * deterministic behavior and make the logic easy to understand and test.
+ */
+export function resolveSourceKind(observation: RawObservation): SourceKind {
+  const {
+    isManualEntry,
+    isGateBlock,
+    isSubagentError,
+    isRateLimit,
+    toolName,
+    failureSource,
+    isGfiTriggered,
+    detectionSource,
+    nonZeroExit,
+    timedOut,
+    toolNotFound,
+  } = observation;
+
+  // Priority 1: Manual entry (CLI, owner-reported)
+  if (isManualEntry) {
+    return 'owner_reported';
+  }
+
+  // Priority 2: Gate block
+  if (isGateBlock) {
+    return 'rulehost_block';
+  }
+
+  // Priority 3: Subagent error
+  if (isSubagentError) {
+    return 'subagent_error';
+  }
+
+  // Priority 4: Provider rate limit (explicit true/false)
+  if (isRateLimit === true) {
+    return 'rate_limit';
+  }
+  if (isRateLimit === false) {
+    return 'provider_failure';
+  }
+
+  // Priority 5: Manual pain tool
+  if (toolName === 'pain' || toolName === 'skill:pain') {
+    // Match resolveSourceKindFromToolFailure behavior:
+    // openclaw_context_bound → agent_on_owner_request
+    // other provenance or undefined → owner_reported
+    if (observation.provenance === 'openclaw_context_bound') {
+      return 'agent_on_owner_request';
+    }
+    return 'owner_reported';
+  }
+
+  // Priority 6: GFI threshold (must check before failure source for LLM detection path)
+  if (isGfiTriggered) {
+    return 'gfi_threshold';
+  }
+
+  // Priority 7: Tool failure / dispatch error
+  if (failureSource) {
+    // Match resolveSourceKindFromToolFailure behavior:
+    // dispatch_error → dispatch_error, anything else → tool_failure
+    if (failureSource === 'dispatch_error') {
+      return 'dispatch_error';
+    }
+    return 'tool_failure';
+  }
+
+  // Infer failureSource from tool failure indicators if not explicitly set
+  if (toolNotFound) {
+    return 'dispatch_error';
+  }
+
+  // Match classifyToolFailureSource behavior: unknown tool name → dispatch_error
+  // BUT only if this looks like a tool failure context (has other tool fields)
+  // Otherwise, this is likely a non-tool observation (e.g., LLM detection)
+  const hasToolContext = toolName !== undefined || nonZeroExit || timedOut || toolNotFound;
+  if (hasToolContext && (!toolName || toolName.trim() === '')) {
+    return 'dispatch_error';
+  }
+
+  // Exit code-based detection: non-zero exit or timeout → tool_failure
+  if (nonZeroExit || timedOut) {
+    return 'tool_failure';
+  }
+
+  // Priority 8: LLM detection source
+  if (detectionSource) {
+    // Match resolveSourceKindFromLlmDetection behavior:
+    if (detectionSource === 'llm_paralysis') {
+      return 'llm_paralysis';
+    }
+    if (detectionSource.startsWith('llm_')) {
+      return 'semantic';
+    }
+    if (detectionSource === 'user_empathy') {
+      return 'empathy_inferred';
+    }
+  }
+
+  // Fallback: unknown
+  return 'unknown';
+}
+
+/**
+ * Resolve SourceKind from tool failure context (legacy wrapper).
+ *
+ * This is a thin wrapper around resolveSourceKind for compatibility.
+ * It constructs a RawObservation from the old function signature.
+ *
+ * @deprecated Use resolveSourceKind directly with RawObservation.
+ */
+export function resolveSourceKindFromToolFailure(
+  toolName: string | undefined,
+  failureSource: 'tool_failure' | 'dispatch_error',
+  provenance?: 'openclaw_context_bound' | 'owner_reported_no_host_trace' | 'automatic_hook',
+): SourceKind {
+  const observation: RawObservation = {
+    observedAt: new Date().toISOString(),
+    toolName,
+    failureSource,
+    provenance,
+  };
+  return resolveSourceKind(observation);
+}
+
+/**
+ * Resolve SourceKind from LLM detection context (legacy wrapper).
+ *
+ * This is a thin wrapper around resolveSourceKind for compatibility.
+ *
+ * @deprecated Use resolveSourceKind directly with RawObservation.
+ */
+export function resolveSourceKindFromLlmDetection(
+  detectionSource: string,
+  isGfiTriggered: boolean,
+): SourceKind {
+  const observation: RawObservation = {
+    observedAt: new Date().toISOString(),
+    detectionSource,
+    isGfiTriggered,
+  };
+  return resolveSourceKind(observation);
+}
+
+/**
+ * Resolve SourceKind from gate block context (legacy wrapper).
+ *
+ * @deprecated Use resolveSourceKind directly with RawObservation.
+ */
+export function resolveSourceKindFromGateBlock(): SourceKind {
+  const observation: RawObservation = {
+    observedAt: new Date().toISOString(),
+    isGateBlock: true,
+  };
+  return resolveSourceKind(observation);
+}
+
+/**
+ * Resolve SourceKind from manual command context (legacy wrapper).
+ *
+ * @deprecated Use resolveSourceKind directly with RawObservation.
+ */
+export function resolveSourceKindFromCommand(): SourceKind {
+  const observation: RawObservation = {
+    observedAt: new Date().toISOString(),
+    isManualEntry: true,
+  };
+  return resolveSourceKind(observation);
+}
+
+/**
+ * Resolve SourceKind from provider context (legacy wrapper).
+ *
+ * @deprecated Use resolveSourceKind directly with RawObservation.
+ */
+export function resolveSourceKindFromProvider(
+  isRateLimit: boolean,
+): SourceKind {
+  const observation: RawObservation = {
+    observedAt: new Date().toISOString(),
+    isRateLimit,
+  };
+  return resolveSourceKind(observation);
+}
+
+/**
+ * Resolve SourceKind from subagent context (legacy wrapper).
+ *
+ * @deprecated Use resolveSourceKind directly with RawObservation.
+ */
+export function resolveSourceKindFromSubagent(): SourceKind {
+  const observation: RawObservation = {
+    observedAt: new Date().toISOString(),
+    isSubagentError: true,
+  };
+  return resolveSourceKind(observation);
+}

package/src/hooks/raw-observation-types.ts

@@ -0,0 +1,77 @@
+/**
+ * Raw Observation Types — PRI-362
+ *
+ * Source adapter layer that normalizes diverse hook contexts into a unified
+ * observation model before mapping to SourceKind.
+ *
+ * This replaces scattered resolveSourceKindFrom* functions with a single
+ * field-driven adapter.
+ *
+ * ERR checklist:
+ * - ERR-001: No `as` casts; validate unknown payload field-by-field.
+ * - ERR-002: Every decision carries reason + nextAction.
+ * - EP-01: Source adapter validates before use.
+ */
+
+/**
+ * Raw observation from a source adapter.
+ *
+ * This is the input to resolveSourceKind. It contains all possible
+ * context fields that different sources may provide. The adapter
+ * reads only the fields it needs based on the observation source.
+ */
+export interface RawObservation {
+  /** When the observation was made (ISO timestamp) */
+  readonly observedAt: string;
+  /** Workspace identifier */
+  readonly workspaceId?: string;
+  /** Session identifier */
+  readonly sessionId?: string;
+  /** Trace identifier for correlation */
+  readonly traceId?: string;
+
+  // ── Tool Failure Fields ────────────────────────────────────────────────
+  /** Tool name (for after_tool_call hook) */
+  readonly toolName?: string;
+  /** Failure source classification */
+  readonly failureSource?: 'tool_failure' | 'dispatch_error';
+  /** Whether the tool call exited with non-zero code */
+  readonly nonZeroExit?: boolean;
+  /** Whether the tool call timed out */
+  readonly timedOut?: boolean;
+  /** Whether the tool does not exist */
+  readonly toolNotFound?: boolean;
+
+  // ── LLM Detection Fields ───────────────────────────────────────────────
+  /** Detection source identifier */
+  readonly detectionSource?: string;
+  /** Whether GFI threshold was crossed */
+  readonly isGfiTriggered?: boolean;
+
+  // ── Provider Fields ───────────────────────────────────────────────────
+  /** Whether the failure was a rate limit (429) */
+  readonly isRateLimit?: boolean;
+
+  // ── Gate Block Fields ────────────────────────────────────────────────
+  /** Whether this observation came from a gate block */
+  readonly isGateBlock?: boolean;
+
+  // ── Manual Entry Fields ───────────────────────────────────────────────
+  /** Whether this was a manual CLI entry */
+  readonly isManualEntry?: boolean;
+  /** Provenance: how trustworthy and context-bound is the observation */
+  readonly provenance?: 'openclaw_context_bound' | 'owner_reported_no_host_trace' | 'automatic_hook';
+
+  // ── Subagent Fields ───────────────────────────────────────────────────
+  /** Whether this observation came from a subagent error */
+  readonly isSubagentError?: boolean;
+
+  // ── Raw Payload ──────────────────────────────────────────────────────
+  /**
+   * Raw payload from the source.
+   *
+   * This is always `unknown` (ERR-005). Source adapters validate only
+   * enough to identify the source and capture bounded context.
+   */
+  readonly payload?: unknown;
+}