principles-disciple 1.8.1 → 1.8.3

package/src/core/pain.ts

@@ -0,0 +1,122 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { serializeKvLines, parseKvLines } from '../utils/io.js';
+import { resolvePdPath } from './paths.js';
+import { ConfigService } from './config-service.js';
+
+export function computePainScore(rc: number, isSpiral: boolean, missingTestCommand: boolean, softScore: number, projectDir?: string): number {
+  let score = Math.max(0, softScore || 0);
+  
+  const stateDir = projectDir ? resolvePdPath(projectDir, 'STATE_DIR') : undefined;
+  const config = stateDir ? ConfigService.get(stateDir) : null;
+  const scoreSettings = config ? config.get('scores') : {
+    exit_code_penalty: 70,
+    spiral_penalty: 40,
+    missing_test_command_penalty: 30
+  };
+
+  if (rc !== 0) {
+    score += scoreSettings.exit_code_penalty;
+  }
+
+  if (isSpiral) {
+    score += scoreSettings.spiral_penalty;
+  }
+
+  if (missingTestCommand) {
+    score += scoreSettings.missing_test_command_penalty;
+  }
+
+  return Math.min(100, score);
+}
+
+export function painSeverityLabel(painScore: number, isSpiral: boolean = false, projectDir?: string): string {
+  if (isSpiral) {
+    return "critical";
+  }
+
+  const stateDir = projectDir ? resolvePdPath(projectDir, 'STATE_DIR') : undefined;
+  const config = stateDir ? ConfigService.get(stateDir) : null;
+  const thresholds = config ? config.get('severity_thresholds') : {
+    high: 70,
+    medium: 40,
+    low: 20
+  };
+
+  if (painScore >= thresholds.high) {
+    return "high";
+  } else if (painScore >= thresholds.medium) {
+    return "medium";
+  } else if (painScore >= thresholds.low) {
+    return "low";
+  } else {
+    return "info";
+  }
+}
+
+export function writePainFlag(projectDir: string, painData: Record<string, string>): void {
+  const painFlagPath = resolvePdPath(projectDir, 'PAIN_FLAG');
+  const dir = path.dirname(painFlagPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(painFlagPath, serializeKvLines(painData), "utf-8");
+}
+
+export function readPainFlagData(projectDir: string): Record<string, string> {
+  const painFlagPath = resolvePdPath(projectDir, 'PAIN_FLAG');
+  try {
+    if (!fs.existsSync(painFlagPath)) {
+      return {};
+    }
+    const content = fs.readFileSync(painFlagPath, "utf-8");
+    return parseKvLines(content);
+  } catch (e) {
+    return {};
+  }
+}
+
+/**
+ * Track principle value metrics when a pain signal is written.
+ * This is observation-only — it does NOT affect the pain flag write flow.
+ * If any principle matches the pain signal, its painPreventedCount is incremented.
+ * Errors are silently ignored to avoid disrupting the pain pipeline.
+ */
+export function trackPrincipleValue(
+  workspaceDir: string,
+  painData: { reason?: string; source?: string; score?: string },
+  getActivePrinciples: () => Array<{
+    id: string;
+    trigger: string;
+    valueMetrics?: { painPreventedCount: number; lastPainPreventedAt?: string; calculatedAt: string };
+  }>,
+  updatePrincipleMetrics: (id: string, metrics: { painPreventedCount: number; lastPainPreventedAt: string; calculatedAt: string }) => void,
+): void {
+  try {
+    const activePrinciples = getActivePrinciples();
+    if (!activePrinciples.length) return;
+
+    const painText = `${painData.reason || ''} ${painData.source || ''}`.toLowerCase();
+    const now = new Date().toISOString();
+
+    for (const principle of activePrinciples) {
+      const triggerPattern = principle.trigger?.toLowerCase();
+      if (!triggerPattern) continue;
+
+      // Simple keyword match — if any word from the trigger appears in the pain text
+      const triggerWords = triggerPattern.split(/[\s|\\.+*?()[\]{}^$-]+/).filter((w) => w.length > 2);
+      const matchCount = triggerWords.filter((word) => painText.includes(word)).length;
+
+      if (matchCount >= 2 || (triggerWords.length <= 3 && matchCount >= 1)) {
+        const currentMetrics = principle.valueMetrics ?? { painPreventedCount: 0, calculatedAt: now };
+        updatePrincipleMetrics(principle.id, {
+          painPreventedCount: currentMetrics.painPreventedCount + 1,
+          lastPainPreventedAt: now,
+          calculatedAt: now,
+        });
+      }
+    }
+  } catch {
+    // Observation only — never disrupt the pain pipeline
+  }
+}

package/{dist/core/path-resolver.js → src/core/path-resolver.ts}

@@ -1,14 +1,29 @@
 import * as path from 'path';
 import * as os from 'os';
 import * as fs from 'fs';
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
 import { PathResolutionError } from '../config/index.js';
+
+export interface PathResolverOptions {
+    workspaceDir?: string;
+    normalizeWorkspace?: boolean;
+    logger?: {
+        debug?: (msg: string) => void;
+        info?: (msg: string) => void;
+        warn?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+}
+
 const DEFAULT_WORKSPACE_SUBPATH = '.openclaw/workspace';
+
 export const PD_ENV_VARS = {
     WORKSPACE_DIR: 'PD_WORKSPACE_DIR',
     STATE_DIR: 'PD_STATE_DIR',
     DEBUG: 'DEBUG',
-};
-export const PD_ENV_DESCRIPTIONS = {
+} as const;
+
+export const PD_ENV_DESCRIPTIONS: Record<keyof typeof PD_ENV_VARS, { desc: string; example: string }> = {
     WORKSPACE_DIR: {
         desc: 'Override the default workspace directory',
         example: 'PD_WORKSPACE_DIR=/home/user/my-workspace',
@@ -22,34 +37,47 @@ export const PD_ENV_DESCRIPTIONS = {
         example: 'DEBUG=true',
     },
 };
-export function printEnvVarHelp() {
+
+export function printEnvVarHelp(): void {
     console.log('\n📁 Principles Disciple - Environment Variables\n');
     console.log('You can customize directory paths using environment variables:\n');
+    
     for (const [key, varName] of Object.entries(PD_ENV_VARS)) {
-        const info = PD_ENV_DESCRIPTIONS[key];
+        const info = PD_ENV_DESCRIPTIONS[key as keyof typeof PD_ENV_VARS];
         console.log(`  ${varName}`);
         console.log(`    Description: ${info.desc}`);
         console.log(`    Example: ${info.example}`);
         console.log();
     }
+    
     console.log('💡 Tips:');
     console.log('  - These can be set in your shell profile (~/.bashrc, ~/.zshrc)');
     console.log('  - Or passed when starting OpenClaw gateway');
     console.log('  - Example: PD_WORKSPACE_DIR=/custom/path openclaw-gateway start\n');
 }
+
+export interface PDConfig {
+    workspace?: string;
+    state?: string;
+    debug?: boolean;
+}
+
 const PD_CONFIG_FILE = 'principles-disciple.json';
 const PD_CONFIG_LOCATIONS = [
     path.join(process.cwd(), PD_CONFIG_FILE),
     path.join(os.homedir(), '.openclaw', PD_CONFIG_FILE),
     path.join(os.homedir(), '.principles', PD_CONFIG_FILE),
 ];
-function isWindowsPath(inputPath) {
+
+function isWindowsPath(inputPath: string): boolean {
     return /^[A-Za-z]:[\\/]/.test(inputPath) || inputPath.startsWith('\\\\');
 }
-function isPosixAbsolutePath(inputPath) {
+
+function isPosixAbsolutePath(inputPath: string): boolean {
     return inputPath.startsWith('/');
 }
-function getPathApi(inputPath) {
+
+function getPathApi(inputPath: string): typeof path.posix | typeof path.win32 | typeof path {
     if (isWindowsPath(inputPath)) {
         return path.win32;
     }
@@ -58,7 +86,8 @@ function getPathApi(inputPath) {
     }
     return path;
 }
-function findConfigFile() {
+
+function findConfigFile(): string | null {
     for (const loc of PD_CONFIG_LOCATIONS) {
         if (fs.existsSync(loc)) {
             return loc;
@@ -66,30 +95,36 @@ function findConfigFile() {
     }
     return null;
 }
-function loadConfigFromFile() {
+
+/* eslint-disable no-console */
+function loadConfigFromFile(): PDConfig | null {
     const configPath = findConfigFile();
     if (!configPath) {
         return null;
     }
+    
     try {
         const content = fs.readFileSync(configPath, 'utf8');
         const config = JSON.parse(content);
         console.log(`[PD:PathResolver] Loaded config from: ${configPath}`);
         return config;
-    }
-    catch (e) {
+    } catch (e) {
         console.warn(`[PD:PathResolver] Failed to load config from ${configPath}: ${String(e)}`);
         return null;
     }
 }
+/* eslint-enable no-console */
+
 export class PathResolver {
-    static extensionRoot = null;
-    workspaceDir = null;
-    stateDir = null;
-    logger;
-    normalizeWorkspace;
-    initialized = false;
-    static setExtensionRoot(extensionRootPath) {
+    private static extensionRoot: string | null = null;
+    private workspaceDir: string | null = null;
+    private stateDir: string | null = null;
+    private readonly logger?: PathResolverOptions['logger'];
+    private readonly normalizeWorkspace: boolean;
+    private initialized = false;
+
+
+    static setExtensionRoot(extensionRootPath: string): void {
         if (!extensionRootPath || !extensionRootPath.trim()) {
             return;
         }
@@ -97,12 +132,15 @@ export class PathResolver {
         const pathApi = getPathApi(trimmed);
         PathResolver.extensionRoot = pathApi.normalize(trimmed);
     }
-    static getExtensionRoot() {
+
+    static getExtensionRoot(): string | null {
         return PathResolver.extensionRoot;
     }
-    constructor(options = {}) {
+
+    constructor(options: PathResolverOptions = {}) {
         this.logger = options.logger;
         this.normalizeWorkspace = options.normalizeWorkspace ?? true;
+        
         if (options.workspaceDir) {
             const original = options.workspaceDir;
             const normalized = this.normalizeWorkspace ? this.normalizePath(original) : original;
@@ -113,53 +151,64 @@ export class PathResolver {
             this.initialized = true;
         }
     }
-    log(level, msg) {
+
+    private log(level: 'debug' | 'info' | 'warn' | 'error', msg: string): void {
         const prefix = '[PD:PathResolver]';
         const fullMsg = `${prefix} ${msg}`;
+        
         if (process.env.DEBUG === 'true') {
-            console.debug(fullMsg);
+            this.logger?.debug?.(fullMsg);
         }
+        
         switch (level) {
             case 'debug':
                 this.logger?.debug?.(fullMsg);
                 break;
             case 'info':
-                this.logger?.info?.(fullMsg) || console.log(fullMsg);
+                this.logger?.info?.(fullMsg);
                 break;
             case 'warn':
-                this.logger?.warn?.(fullMsg) || console.warn(fullMsg);
+                this.logger?.warn?.(fullMsg);
                 break;
             case 'error':
-                this.logger?.error?.(fullMsg) || console.error(fullMsg);
+                this.logger?.error?.(fullMsg);
                 break;
         }
     }
-    detectWorkspaceDir() {
+
+    private detectWorkspaceDir(): string {
         const envWorkspace = process.env.PD_WORKSPACE_DIR;
         if (envWorkspace && envWorkspace.trim()) {
             this.log('info', `Using workspace from PD_WORKSPACE_DIR: ${envWorkspace}`);
             return envWorkspace.trim();
         }
+
         const envOpenclaw = process.env.OPENCLAW_WORKSPACE;
         if (envOpenclaw && envOpenclaw.trim()) {
             this.log('info', `Using workspace from OPENCLAW_WORKSPACE: ${envOpenclaw}`);
             return envOpenclaw.trim();
         }
+
         const fileConfig = loadConfigFromFile();
         if (fileConfig?.workspace) {
             this.log('info', `Using workspace from config file: ${fileConfig.workspace}`);
             return fileConfig.workspace;
         }
+
         const homeDir = os.homedir();
         const defaultWorkspace = path.join(homeDir, DEFAULT_WORKSPACE_SUBPATH);
         this.log('info', `Using default workspace: ${defaultWorkspace}`);
+        
         return defaultWorkspace;
     }
-    normalizePath(inputPath) {
+
+    private normalizePath(inputPath: string): string {
         const pathApi = getPathApi(inputPath);
         let normalized = pathApi === path ? path.resolve(inputPath) : pathApi.normalize(inputPath);
+        
         if (this.normalizeWorkspace) {
             const problematicSuffixes = ['/memory', '/docs', '\\memory', '\\docs'];
+            
             for (const suffix of problematicSuffixes) {
                 if (normalized.endsWith(suffix)) {
                     const parent = pathApi.dirname(normalized);
@@ -169,38 +218,49 @@ export class PathResolver {
                 }
             }
         }
+        
         return normalized;
     }
-    normalizeWorkspacePath(inputPath) {
+
+    normalizeWorkspacePath(inputPath: string): string {
         return this.normalizePath(inputPath);
     }
-    getWorkspaceDir() {
+
+    getWorkspaceDir(): string {
         if (this.initialized && this.workspaceDir) {
             return this.workspaceDir;
         }
+
         let dir = this.detectWorkspaceDir();
+        
         if (this.normalizeWorkspace) {
             const originalDir = dir;
             dir = this.normalizePath(dir);
+            
             if (originalDir !== dir) {
                 this.log('info', `Workspace path normalized: ${originalDir} -> ${dir}`);
             }
         }
+
         this.workspaceDir = dir;
         this.initialized = true;
         this.log('debug', `Final workspace directory: ${this.workspaceDir}`);
+        
         return this.workspaceDir;
     }
-    getStateDir() {
+
+    getStateDir(): string {
         if (this.stateDir) {
             return this.stateDir;
         }
+
         const envStateDir = process.env.PD_STATE_DIR;
         if (envStateDir && envStateDir.trim()) {
             this.stateDir = envStateDir.trim();
             this.log('info', `Using state directory from PD_STATE_DIR: ${this.stateDir}`);
             return this.stateDir;
         }
+
         // If workspaceDir was explicitly provided via constructor, use workspace-based state dir
         // This ensures tests and programmatic usage don't get polluted by global config
         if (this.initialized && this.workspaceDir) {
@@ -209,19 +269,23 @@ export class PathResolver {
             this.log('debug', `Using workspace-based state directory: ${this.stateDir}`);
             return this.stateDir;
         }
+
         const fileConfig = loadConfigFromFile();
         if (fileConfig?.state) {
             this.stateDir = fileConfig.state;
             this.log('info', `Using state directory from config file: ${this.stateDir}`);
             return this.stateDir;
         }
+
         const workspaceDir = this.getWorkspaceDir();
         const pathApi = getPathApi(workspaceDir);
         this.stateDir = pathApi.join(workspaceDir, '.state');
         this.log('debug', `Computed state directory: ${this.stateDir}`);
+
         return this.stateDir;
     }
-    resolve(key) {
+
+    resolve(key: string): string {
         const workspace = this.getWorkspaceDir();
         const state = this.getStateDir();
         const workspacePath = getPathApi(workspace);
@@ -233,7 +297,8 @@ export class PathResolver {
         const evolutionWorker = fs.existsSync(extensionSrc)
             ? extensionPath.join(extensionSrc, 'service', 'evolution-worker.ts')
             : extensionPath.join(extensionDist, 'service', 'evolution-worker.js');
-        const pathMap = {
+
+        const pathMap: Record<string, string> = {
             'PROFILE': workspacePath.join(workspace, '.principles', 'PROFILE.json'),
             'PRINCIPLES': workspacePath.join(workspace, '.principles', 'PRINCIPLES.md'),
             'THINKING_OS': workspacePath.join(workspace, '.principles', 'THINKING_OS.md'),
@@ -269,51 +334,107 @@ export class PathResolver {
             'PRINCIPLE_BLACKLIST': workspacePath.join(state, 'principle_blacklist.json'),
             'MEMORY': memory,
         };
+
         const resolved = pathMap[key];
         if (!resolved) {
             this.log('warn', `Unknown path key: ${key}`);
             throw new PathResolutionError(key);
         }
+
         this.log('debug', `Resolved path for '${key}': ${resolved}`);
+        
         return resolved;
     }
-    ensureStateDir() {
+
+    ensureStateDir(): void {
         const stateDir = this.getStateDir();
+        
         if (!fs.existsSync(stateDir)) {
             this.log('info', `Creating state directory: ${stateDir}`);
             fs.mkdirSync(stateDir, { recursive: true });
         }
     }
-    static createFromHookContext(ctx) {
+
+    static createFromHookContext(ctx: any): PathResolver {
         const resolver = new PathResolver();
+        
         if (ctx?.workspaceDir) {
             let workspaceDir = ctx.workspaceDir;
+            
             if (resolver.normalizeWorkspace) {
                 workspaceDir = resolver.normalizePath(workspaceDir);
             }
+            
             resolver.workspaceDir = workspaceDir;
             resolver.initialized = true;
             resolver.log('info', `Created from hook context with workspace: ${workspaceDir}`);
         }
+        
         if (ctx?.stateDir) {
             resolver.stateDir = ctx.stateDir;
         }
+        
         return resolver;
     }
 }
-export function createDefaultConfig(targetPath) {
-    const defaultConfig = {
+
+export function createDefaultConfig(targetPath?: string): string {
+    const defaultConfig: PDConfig = {
         workspace: path.join(os.homedir(), '.openclaw', 'workspace'),
         state: path.join(os.homedir(), '.openclaw', 'workspace', '.state'),
         debug: false,
     };
+    
     const target = targetPath || path.join(os.homedir(), '.openclaw', PD_CONFIG_FILE);
     const dir = path.dirname(target);
+    
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
+    
     fs.writeFileSync(target, JSON.stringify(defaultConfig, null, 2), 'utf8');
+    
     console.log(`✅ Created default config at: ${target}`);
     console.log(`   You can edit this file to customize paths.`);
+
     return target;
 }
+
+// ── OpenClaw API Workspace Resolution ────────────────────────────
+
+/**
+ * Resolve workspace directory via OpenClaw's official API.
+ *
+ * Replaces the removed `api.workspaceDir` field.
+ *
+ * Priority: api.runtime.agent.resolveAgentWorkspaceDir(agentId)
+ *           → PathResolver.getWorkspaceDir() (PD env vars, config file, default)
+ *
+ * @param api - Plugin API instance
+ * @param agentId - Agent ID (defaults to 'main' if not provided)
+ * @returns Resolved workspace directory, or `undefined` if all resolution paths fail
+ */
+export function resolveWorkspaceDirFromApi(
+    api: OpenClawPluginApi | undefined,
+    agentId?: string,
+): string | undefined {
+    if (!api) return undefined;
+
+    // 1. Official API: api.runtime.agent.resolveAgentWorkspaceDir
+    const officialAgent = (api.runtime as { agent?: { resolveAgentWorkspaceDir?: (cfg: unknown, id: string) => string } }).agent;
+    if (officialAgent?.resolveAgentWorkspaceDir) {
+        try {
+            return officialAgent.resolveAgentWorkspaceDir(api.config, agentId ?? 'main');
+        } catch {
+            // Fall through to PathResolver
+        }
+    }
+
+    // 2. Fallback: PathResolver (PD_WORKSPACE_DIR env, config file, default)
+    try {
+        const pr = new PathResolver();
+        return pr.getWorkspaceDir();
+    } catch {
+        return undefined;
+    }
+}

package/{dist/core/paths.js → src/core/paths.ts}

@@ -1,9 +1,12 @@
 import * as path from 'path';
-const posixJoin = (...parts) => path.posix.join(...parts);
-function isWindowsPath(input) {
+
+const posixJoin = (...parts: string[]): string => path.posix.join(...parts);
+
+function isWindowsPath(input: string): boolean {
     return /^[A-Za-z]:[\\/]/.test(input) || input.startsWith('\\\\');
 }
-function joinWorkspacePath(workspaceDir, relativePath) {
+
+function joinWorkspacePath(workspaceDir: string, relativePath: string): string {
     if (isWindowsPath(workspaceDir)) {
         return path.win32.join(workspaceDir, relativePath);
     }
@@ -12,6 +15,7 @@ function joinWorkspacePath(workspaceDir, relativePath) {
     }
     return path.join(workspaceDir, relativePath);
 }
+
 /**
  * Principles Disciple Directory Constants
  * Establishing a logical separation between Identity, State, and Memory.
@@ -30,6 +34,7 @@ export const PD_DIRS = {
     NOCTURNAL_MEMORY: posixJoin('.state', 'nocturnal', 'memory'),
     NOCTURNAL_EXPORTS: posixJoin('.state', 'exports', 'orpo'),
 };
+
 /**
  * Standard File Path Mappings
  */
@@ -40,6 +45,7 @@ export const PD_FILES = {
     KERNEL: posixJoin(PD_DIRS.IDENTITY, '00-kernel.md'),
     DECISION_POLICY: posixJoin(PD_DIRS.IDENTITY, 'DECISION_POLICY.json'),
     MODELS_DIR: PD_DIRS.MODELS,
+
     STATE_DIR: PD_DIRS.STATE,
     EVOLUTION_QUEUE: posixJoin(PD_DIRS.STATE, 'evolution_queue.json'),
     EVOLUTION_DIRECTIVE: posixJoin(PD_DIRS.STATE, 'evolution_directive.json'),
@@ -59,9 +65,11 @@ export const PD_FILES = {
     NOCTURNAL_SAMPLES_DIR: PD_DIRS.NOCTURNAL_SAMPLES,
     NOCTURNAL_MEMORY_DIR: PD_DIRS.NOCTURNAL_MEMORY,
     NOCTURNAL_EXPORTS_DIR: PD_DIRS.NOCTURNAL_EXPORTS,
+
     PLAN: 'PLAN.md',
     MEMORY_MD: 'MEMORY.md',
     HEARTBEAT: 'HEARTBEAT.md',
+
     SYSTEM_LOG: posixJoin(PD_DIRS.LOGS, 'SYSTEM.log'),
     REFLECTION_LOG: posixJoin(PD_DIRS.MEMORY, 'reflection-log.md'),
     USER_CONTEXT: posixJoin(PD_DIRS.MEMORY, 'USER_CONTEXT.md'),
@@ -73,9 +81,10 @@ export const PD_FILES = {
     EVOLUTION_STREAM: posixJoin(PD_DIRS.MEMORY, 'evolution.jsonl'),
     EVOLUTION_LOCK: posixJoin(PD_DIRS.LOCKS, 'evolution'),
 };
+
 /**
  * Resolves a PD file path within a given workspace.
  */
-export function resolvePdPath(workspaceDir, fileKey) {
+export function resolvePdPath(workspaceDir: string, fileKey: keyof typeof PD_FILES): string {
     return joinWorkspacePath(workspaceDir, PD_FILES[fileKey]);
 }