principles-disciple 1.127.0 → 1.129.0

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

@@ -1,33 +1,15 @@
- 
 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';
 import { atomicWriteFileSync } from '../utils/io.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',
-} as const;
-
-export const PD_ENV_DESCRIPTIONS: Record<keyof typeof PD_ENV_VARS, { desc: string; example: string }> = {
+};
+export const PD_ENV_DESCRIPTIONS = {
     WORKSPACE_DIR: {
         desc: 'Override the default workspace directory',
         example: 'PD_WORKSPACE_DIR=/home/user/my-workspace',
@@ -41,47 +23,34 @@ export const PD_ENV_DESCRIPTIONS: Record<keyof typeof PD_ENV_VARS, { desc: strin
         example: 'DEBUG=true',
     },
 };
-
-export function printEnvVarHelp(): void {
+export function printEnvVarHelp() {
     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 as keyof typeof PD_ENV_VARS];
+        const info = PD_ENV_DESCRIPTIONS[key];
         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: string): boolean {
+function isWindowsPath(inputPath) {
     return /^[A-Za-z]:[\\/]/.test(inputPath) || inputPath.startsWith('\\\\');
 }
-
-function isPosixAbsolutePath(inputPath: string): boolean {
+function isPosixAbsolutePath(inputPath) {
     return inputPath.startsWith('/');
 }
-
-function getPathApi(inputPath: string): typeof path.posix | typeof path.win32 | typeof path {
+function getPathApi(inputPath) {
     if (isWindowsPath(inputPath)) {
         return path.win32;
     }
@@ -90,8 +59,7 @@ function getPathApi(inputPath: string): typeof path.posix | typeof path.win32 |
     }
     return path;
 }
-
-function findConfigFile(): string | null {
+function findConfigFile() {
     for (const loc of PD_CONFIG_LOCATIONS) {
         if (fs.existsSync(loc)) {
             return loc;
@@ -99,34 +67,30 @@ function findConfigFile(): string | null {
     }
     return null;
 }
-
-function loadConfigFromFile(): PDConfig | null {
+function loadConfigFromFile() {
     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;
     }
 }
-
 export class PathResolver {
-    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 {
+    static extensionRoot = null;
+    workspaceDir = null;
+    stateDir = null;
+    logger;
+    normalizeWorkspace;
+    initialized = false;
+    static setExtensionRoot(extensionRootPath) {
         if (!extensionRootPath || !extensionRootPath.trim()) {
             return;
         }
@@ -134,15 +98,12 @@ export class PathResolver {
         const pathApi = getPathApi(trimmed);
         PathResolver.extensionRoot = pathApi.normalize(trimmed);
     }
-
-    static getExtensionRoot(): string | null {
+    static getExtensionRoot() {
         return PathResolver.extensionRoot;
     }
-
-    constructor(options: PathResolverOptions = {}) {
+    constructor(options = {}) {
         this.logger = options.logger;
         this.normalizeWorkspace = options.normalizeWorkspace ?? true;
-        
         if (options.workspaceDir) {
             const original = options.workspaceDir;
             const normalized = this.normalizeWorkspace ? this.normalizePath(original) : original;
@@ -153,15 +114,12 @@ export class PathResolver {
             this.initialized = true;
         }
     }
-
-    private log(level: 'debug' | 'info' | 'warn' | 'error', msg: string): void {
+    log(level, msg) {
         const prefix = '[PD:PathResolver]';
         const fullMsg = `${prefix} ${msg}`;
-        
         if (process.env.DEBUG === 'true') {
             this.logger?.debug?.(fullMsg);
         }
-        
         switch (level) {
             case 'debug':
                 this.logger?.debug?.(fullMsg);
@@ -177,40 +135,32 @@ export class PathResolver {
                 break;
         }
     }
-
-    private detectWorkspaceDir(): string {
+    detectWorkspaceDir() {
         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;
     }
-
-    private normalizePath(inputPath: string): string {
+    normalizePath(inputPath) {
         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);
@@ -220,49 +170,38 @@ export class PathResolver {
                 }
             }
         }
-        
         return normalized;
     }
-
-    normalizeWorkspacePath(inputPath: string): string {
+    normalizeWorkspacePath(inputPath) {
         return this.normalizePath(inputPath);
     }
-
-    getWorkspaceDir(): string {
+    getWorkspaceDir() {
         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(): string {
+    getStateDir() {
         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) {
@@ -271,23 +210,19 @@ 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: string): string {
+    resolve(key) {
         const workspace = this.getWorkspaceDir();
         const state = this.getStateDir();
         const workspacePath = getPathApi(workspace);
@@ -299,8 +234,7 @@ export class PathResolver {
         const evolutionWorker = fs.existsSync(extensionSrc)
             ? extensionPath.join(extensionSrc, 'service', 'evolution-worker.ts')
             : extensionPath.join(extensionDist, 'service', 'evolution-worker.js');
-
-        const pathMap: Record<string, string> = {
+        const pathMap = {
             'PROFILE': workspacePath.join(workspace, '.principles', 'PROFILE.json'),
             'PRINCIPLES': workspacePath.join(workspace, '.principles', 'PRINCIPLES.md'),
             'THINKING_OS': workspacePath.join(workspace, '.principles', 'THINKING_OS.md'),
@@ -334,74 +268,55 @@ 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(): void {
+    ensureStateDir() {
         const stateDir = this.getStateDir();
-        
         if (!fs.existsSync(stateDir)) {
             this.log('info', `Creating state directory: ${stateDir}`);
             fs.mkdirSync(stateDir, { recursive: true });
         }
     }
-
-    static createFromHookContext(ctx: Record<string, unknown>): PathResolver {
+    static createFromHookContext(ctx) {
         const resolver = new PathResolver();
-
         if (ctx?.workspaceDir) {
             let workspaceDir = String(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 = String(ctx.stateDir);
         }
-
         return resolver;
     }
 }
-
-export function createDefaultConfig(targetPath?: string): string {
-    const defaultConfig: PDConfig = {
+export function createDefaultConfig(targetPath) {
+    const defaultConfig = {
         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 });
     }
-    
     atomicWriteFileSync(target, JSON.stringify(defaultConfig, null, 2));
-    
     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.
  *
@@ -414,35 +329,30 @@ export function createDefaultConfig(targetPath?: string): string {
  * @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;
-
+export function resolveWorkspaceDirFromApi(api, agentId) {
+    if (!api)
+        return undefined;
     // 1. Official API: api.runtime.agent.resolveAgentWorkspaceDir
-
-    const officialAgent = (api.runtime as { agent?: { resolveAgentWorkspaceDir?: (cfg: unknown, id: string) => string } }).agent;
-
+    const officialAgent = api.runtime.agent;
     if (officialAgent?.resolveAgentWorkspaceDir) {
         try {
             return officialAgent.resolveAgentWorkspaceDir(api.config, agentId ?? 'main');
-        } catch {
+        }
+        catch {
             // Fall through to config check
         }
     }
-
     // 2. Direct config workspaceDir (for tests and programmatic usage)
-    const cfgWorkspaceDir = (api.config as { workspaceDir?: string })?.workspaceDir;
+    const cfgWorkspaceDir = api.config?.workspaceDir;
     if (cfgWorkspaceDir && cfgWorkspaceDir.trim()) {
         return cfgWorkspaceDir.trim();
     }
-
     // 3. Fallback: PathResolver (PD_WORKSPACE_DIR env, config file, default)
     try {
         const pr = new PathResolver();
         return pr.getWorkspaceDir();
-    } catch {
+    }
+    catch {
         return undefined;
     }
 }

package/dist/core/paths.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Principles Disciple Directory Constants
+ * Establishing a logical separation between Identity, State, and Memory.
+ */
+export declare const PD_DIRS: {
+    IDENTITY: string;
+    MODELS: string;
+    STATE: string;
+    MEMORY: string;
+    OKR: string;
+    LOGS: string;
+    SESSIONS: string;
+    PAIN_SAMPLES: string;
+    LOCKS: string;
+    IMPL_CODE_DIR: string;
+};
+/**
+ * Standard File Path Mappings
+ */
+export declare const PD_FILES: {
+    PROFILE: string;
+    PRINCIPLES: string;
+    THINKING_OS: string;
+    DECISION_POLICY: string;
+    MODELS_DIR: string;
+    STATE_DIR: string;
+    EVOLUTION_QUEUE: string;
+    EVOLUTION_DIRECTIVE: string;
+    WORKBOARD: string;
+    AGENT_SCORECARD: string;
+    PAIN_FLAG: string;
+    SYSTEM_CAPABILITIES: string;
+    PAIN_SETTINGS: string;
+    PAIN_CANDIDATES: string;
+    THINKING_OS_USAGE: string;
+    TRAJECTORY_DB: string;
+    TRAJECTORY_BLOBS_DIR: string;
+    EXPORTS_DIR: string;
+    SESSION_DIR: string;
+    DICTIONARY: string;
+    PRINCIPLE_BLACKLIST: string;
+    WORKFLOWS_YAML: string;
+    IMPL_CODE_DIR: string;
+    MEMORY_MD: string;
+    HEARTBEAT: string;
+    SYSTEM_LOG: string;
+    REFLECTION_LOG: string;
+    USER_CONTEXT: string;
+    OKR_DIR: string;
+    CURRENT_FOCUS: string;
+    WEEK_STATE: string;
+    THINKING_OS_CANDIDATES: string;
+    SEMANTIC_PAIN: string;
+    EVOLUTION_STREAM: string;
+    EVOLUTION_LOCK: string;
+};
+/**
+ * Resolves a PD file path within a given workspace.
+ */
+export declare function resolvePdPath(workspaceDir: string, fileKey: keyof typeof PD_FILES): string;

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

@@ -1,12 +1,9 @@
 import * as path from 'path';
-
-const posixJoin = (...parts: string[]): string => path.posix.join(...parts);
-
-function isWindowsPath(input: string): boolean {
+const posixJoin = (...parts) => path.posix.join(...parts);
+function isWindowsPath(input) {
     return /^[A-Za-z]:[\\/]/.test(input) || input.startsWith('\\\\');
 }
-
-function joinWorkspacePath(workspaceDir: string, relativePath: string): string {
+function joinWorkspacePath(workspaceDir, relativePath) {
     if (isWindowsPath(workspaceDir)) {
         return path.win32.join(workspaceDir, relativePath);
     }
@@ -15,7 +12,6 @@ function joinWorkspacePath(workspaceDir: string, relativePath: string): string {
     }
     return path.join(workspaceDir, relativePath);
 }
-
 /**
  * Principles Disciple Directory Constants
  * Establishing a logical separation between Identity, State, and Memory.
@@ -32,7 +28,6 @@ export const PD_DIRS = {
     LOCKS: posixJoin('memory', '.locks'),
     IMPL_CODE_DIR: posixJoin('.state', 'principles', 'implementations'),
 };
-
 /**
  * Standard File Path Mappings
  */
@@ -42,7 +37,6 @@ export const PD_FILES = {
     THINKING_OS: posixJoin(PD_DIRS.IDENTITY, 'THINKING_OS.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'),
@@ -61,10 +55,8 @@ export const PD_FILES = {
     PRINCIPLE_BLACKLIST: posixJoin(PD_DIRS.STATE, 'principle_blacklist.json'),
     WORKFLOWS_YAML: posixJoin(PD_DIRS.STATE, 'workflows.yaml'),
     IMPL_CODE_DIR: PD_DIRS.IMPL_CODE_DIR,
-
     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'),
@@ -76,10 +68,9 @@ 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: string, fileKey: keyof typeof PD_FILES): string {
+export function resolvePdPath(workspaceDir, fileKey) {
     return joinWorkspacePath(workspaceDir, PD_FILES[fileKey]);
 }

package/dist/core/pd-config-loader.d.ts

@@ -0,0 +1,96 @@
+/**
+ * PD Config Loader (Plugin I/O boundary) — PRI-307
+ *
+ * Reads `.pd/config.yaml`, validates via core, computes effective config.
+ * Replaces the old `.pd/feature-flags.yaml` and `.state/workflows.yaml` reading
+ * for plugin production paths.
+ *
+ * ADR-0016: PD owns exactly one user config file.
+ * - Missing config → defaults with nextAction
+ * - Malformed config → fail loud with errors and nextAction
+ * - No secrets in output
+ * - Observer disabled → no start / no noisy log cycling
+ * - Observer enabled + missing setup → structured needs_setup + nextAction
+ */
+import type { EffectivePdConfig } from '@principles/core/runtime-v2';
+export declare const PD_CONFIG_DIR = ".pd";
+export declare const PD_CONFIG_FILENAME = "config.yaml";
+export type ObserverReadiness = 'disabled' | 'needs_setup' | 'ready' | 'not_ready' | 'config_malformed';
+export interface ObserverConfigResult {
+    /** Whether the observer feature is enabled in config */
+    enabled: boolean;
+    /** Observer readiness state */
+    readiness: ObserverReadiness;
+    /** Config source: 'defaults' | 'user_config' | 'malformed' */
+    source: string;
+    /** Reason for current state */
+    reason: string;
+    /** What the user should do next */
+    nextAction: string;
+    /** The runtime profile ID for this observer, if configured */
+    runtimeProfileId: string | null;
+    /** The runtime profile type, if configured */
+    runtimeProfileType: string | null;
+    /** The apiKeyEnv for the runtime profile, if applicable */
+    apiKeyEnv: string | null;
+    /** Whether the apiKeyEnv is present in process.env */
+    apiKeyPresent: boolean;
+    /** Provider name from runtime profile */
+    provider: string | null;
+    /** Model name from runtime profile */
+    model: string | null;
+    /** Timeout from runtime profile */
+    timeoutMs: number | null;
+    /** Base URL from runtime profile */
+    baseUrl: string | null;
+    /** Config validation errors (only present when readiness=config_malformed) */
+    configErrors?: Array<{
+        path: string;
+        reason: string;
+        nextAction: string;
+    }>;
+}
+export interface PluginConfigLoadResult {
+    ok: boolean;
+    effective: EffectivePdConfig;
+    source: 'defaults' | 'user_config' | 'malformed';
+    configPath: string;
+    warnings: string[];
+    errors: Array<{
+        path: string;
+        reason: string;
+        nextAction: string;
+    }>;
+}
+export declare function getPdConfigPath(workspaceDir: string): string;
+/**
+ * Load and validate `.pd/config.yaml` from the workspace.
+ * Never throws on malformed input. Always provides a usable fallback.
+ */
+export declare function loadPdConfigForPlugin(workspaceDir: string): PluginConfigLoadResult;
+/**
+ * Get a single feature flag's enabled state from .pd/config.yaml.
+ * Replaces the old `loadFeatureFlagFromWorkspace` which read .pd/feature-flags.yaml.
+ */
+export declare function loadFeatureFlagFromConfig(workspaceDir: string, flagId: string, logger?: {
+    warn?: (msg: string) => void;
+    info?: (msg: string) => void;
+}): {
+    enabled: boolean;
+    source: string;
+};
+/**
+ * Resolve observer configuration from .pd/config.yaml.
+ *
+ * Returns structured state:
+ * - config_malformed: config file is invalid — no guessing, fail loud
+ * - disabled: observer feature flag is off OR agent.enabled=false → no start, no noisy logs
+ * - needs_setup: observer enabled but runtime profile missing, API key not set, or unsupported profile type
+ * - ready: observer enabled and fully configured (pi-ai with key present)
+ * - not_ready: observer enabled, API key present, but runtime availability unknown
+ */
+export declare function resolveObserverConfig(workspaceDir: string, observerFlagId: string, observerAgentName: string, _logger?: {
+    warn?: (msg: string) => void;
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+}): ObserverConfigResult;