principles-disciple 1.126.0 → 1.128.0

package/dist/core/code-implementation-storage.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Code Implementation Asset Storage
+ * ================================
+ *
+ * Manages versioned code implementation assets: manifests, entry files,
+ * and metadata pointers for Implementation(type=code) records.
+ *
+ * DESIGN CONSTRAINTS (per D-09 through D-12):
+ *   - Manifest is loading metadata, NOT the source of truth for lifecycle state (D-11)
+ *   - The Principle Tree ledger remains canonical for lifecycle and relationships (D-11)
+ *   - Asset root follows the PD stateDir convention:
+ *     {stateDir}/principles/implementations/{implId}/
+ *   - All writes use withLock for atomicity (matching ledger pattern)
+ *   - This module does NOT implement replay execution, evaluation report generation,
+ *     or promotion logic (D-12)
+ */
+/**
+ * Manifest shape for a code implementation's filesystem assets.
+ * Subordinate to the ledger per D-11: does NOT store lifecycleState.
+ */
+export interface CodeImplementationManifest {
+    /** Asset version (distinct from Implementation.version in the ledger) */
+    version: string;
+    /** Relative filename of the entry point (e.g., 'entry.js') */
+    entryFile: string;
+    /** ISO timestamp of initial creation */
+    createdAt: string;
+    /** ISO timestamp of last manifest update */
+    updatedAt: string;
+    /** Fingerprints of samples this implementation was tested against */
+    replaySampleRefs: string[];
+    /** Relative path to most recent eval report, or null */
+    lastEvalReportRef: string | null;
+    /** Provenance carried with the generated candidate assets */
+    lineage?: CodeImplementationLineageMetadata;
+}
+export interface CodeImplementationLineageMetadata {
+    principleId: string;
+    ruleId: string;
+    sourceSnapshotRef: string;
+    sourcePainIds: string[];
+    sourceGateBlockIds: string[];
+    sourceSessionId: string;
+    artificerArtifactId: string;
+}
+/**
+ * Get the absolute path for an implementation's asset root.
+ * Convention: {stateDir}/principles/implementations/{implId}/
+ */
+export declare function getImplementationAssetRoot(stateDir: string, implId: string): string;
+/**
+ * Write manifest atomically using withLock.
+ */
+export declare function writeManifest(stateDir: string, implId: string, manifest: CodeImplementationManifest): void;
+export declare function writeEntrySource(stateDir: string, implId: string, sourceCode: string, entryFile?: string): void;
+export declare function deleteImplementationAssetDir(stateDir: string, implId: string): void;
+/**
+ * Create the full asset directory structure for a new implementation.
+ *
+ * Creates:
+ *   {implId}/            - asset root
+ *   {implId}/entry.js    - placeholder entry point (only if not already present)
+ *   {implId}/manifest.json - asset manifest with version and timestamps
+ *   {implId}/replays/    - empty directory for future replay reports
+ *
+ * Idempotent: calling again with the same implId will NOT overwrite an existing entry.js.
+ */
+export declare function createImplementationAssetDir(stateDir: string, implId: string, version: string, options?: {
+    entrySource?: string;
+    lineage?: CodeImplementationLineageMetadata;
+}): CodeImplementationManifest;

package/dist/core/code-implementation-storage.js

@@ -0,0 +1,139 @@
+/**
+ * Code Implementation Asset Storage
+ * ================================
+ *
+ * Manages versioned code implementation assets: manifests, entry files,
+ * and metadata pointers for Implementation(type=code) records.
+ *
+ * DESIGN CONSTRAINTS (per D-09 through D-12):
+ *   - Manifest is loading metadata, NOT the source of truth for lifecycle state (D-11)
+ *   - The Principle Tree ledger remains canonical for lifecycle and relationships (D-11)
+ *   - Asset root follows the PD stateDir convention:
+ *     {stateDir}/principles/implementations/{implId}/
+ *   - All writes use withLock for atomicity (matching ledger pattern)
+ *   - This module does NOT implement replay execution, evaluation report generation,
+ *     or promotion logic (D-12)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { withLock } from '../utils/file-lock.js';
+import { atomicWriteFileSync } from '../utils/io.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MANIFEST_FILENAME = 'manifest.json';
+const ENTRY_FILENAME = 'entry.js';
+const REPLAYS_DIRNAME = 'replays';
+// ---------------------------------------------------------------------------
+// Path validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate that an implId contains no path separators.
+ * implId comes from ledger record IDs (controlled namespace), but we
+ * validate to prevent path traversal (T-12-08).
+ */
+function validateImplId(implId) {
+    if (implId.includes('/') || implId.includes('\\') || implId.includes('..')) {
+        throw new Error(`Invalid implementation ID: "${implId}" contains path separators`);
+    }
+    if (!implId) {
+        throw new Error('Implementation ID must not be empty');
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function ensureDir(dir) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Get the absolute path for an implementation's asset root.
+ * Convention: {stateDir}/principles/implementations/{implId}/
+ */
+export function getImplementationAssetRoot(stateDir, implId) {
+    validateImplId(implId);
+    return path.join(stateDir, 'principles', 'implementations', implId);
+}
+/**
+ * Write manifest atomically using withLock.
+ */
+export function writeManifest(stateDir, implId, manifest) {
+    validateImplId(implId);
+    const assetRoot = getImplementationAssetRoot(stateDir, implId);
+    const manifestPath = path.join(assetRoot, MANIFEST_FILENAME);
+    ensureDir(assetRoot);
+    withLock(manifestPath, () => {
+        atomicWriteFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    });
+}
+export function writeEntrySource(stateDir, implId, sourceCode, entryFile = ENTRY_FILENAME) {
+    validateImplId(implId);
+    const assetRoot = getImplementationAssetRoot(stateDir, implId);
+    const entryPath = path.join(assetRoot, entryFile);
+    ensureDir(assetRoot);
+    withLock(entryPath, () => {
+        atomicWriteFileSync(entryPath, sourceCode);
+    });
+}
+export function deleteImplementationAssetDir(stateDir, implId) {
+    validateImplId(implId);
+    const assetRoot = getImplementationAssetRoot(stateDir, implId);
+    if (!fs.existsSync(assetRoot)) {
+        return;
+    }
+    withLock(assetRoot, () => {
+        fs.rmSync(assetRoot, { recursive: true, force: true });
+    });
+}
+/**
+ * Create the full asset directory structure for a new implementation.
+ *
+ * Creates:
+ *   {implId}/            - asset root
+ *   {implId}/entry.js    - placeholder entry point (only if not already present)
+ *   {implId}/manifest.json - asset manifest with version and timestamps
+ *   {implId}/replays/    - empty directory for future replay reports
+ *
+ * Idempotent: calling again with the same implId will NOT overwrite an existing entry.js.
+ */
+export function createImplementationAssetDir(stateDir, implId, version, options = {}) {
+    validateImplId(implId);
+    const assetRoot = getImplementationAssetRoot(stateDir, implId);
+    const replaysDir = path.join(assetRoot, REPLAYS_DIRNAME);
+    const entryPath = path.join(assetRoot, ENTRY_FILENAME);
+    const entrySource = options.entrySource ??
+        [
+            '// Code implementation entry point',
+            '// Exports: meta (RuleHostMeta), evaluate (input: RuleHostInput) => RuleHostResult',
+            '// This file will be replaced by nocturnal candidate generation (Phase 14)',
+            'export const meta = { name: "placeholder", version: "0.0.1", ruleId: "", coversCondition: "" };',
+            'export function evaluate(input) { return { decision: "allow", matched: false, reason: "placeholder" }; }',
+        ].join('\n');
+    withLock(assetRoot, () => {
+        ensureDir(assetRoot);
+        ensureDir(replaysDir);
+        if (!fs.existsSync(entryPath)) {
+            atomicWriteFileSync(entryPath, entrySource);
+        }
+    });
+    if (fs.existsSync(entryPath) && options.entrySource) {
+        writeEntrySource(stateDir, implId, options.entrySource);
+    }
+    const now = new Date().toISOString();
+    const manifest = {
+        version,
+        entryFile: ENTRY_FILENAME,
+        createdAt: now,
+        updatedAt: now,
+        replaySampleRefs: [],
+        lastEvalReportRef: null,
+        ...(options.lineage ? { lineage: options.lineage } : {}),
+    };
+    writeManifest(stateDir, implId, manifest);
+    return manifest;
+}

package/dist/core/config-health.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Conversation Access Health Check (PRI-343 / PRI-346)
+ *
+ * Pure function for checking whether OpenClaw plugin config has
+ * allowConversationAccess set to true. When missing, llm_output and
+ * trajectory hooks are silently blocked by OpenClaw, causing evidence
+ * to always be empty (PRI-338 root cause).
+ *
+ * Extracted from index.ts to avoid circular imports when trajectory-collector.ts
+ * needs to check conversation access state (PRI-346).
+ */
+/**
+ * PRI-348: Extract the full plugin entry (including hooks) from the global OpenClaw config.
+ * Unlike api.pluginConfig (which is only the entry.config sub-object), this returns
+ * the entire entry including hooks, config, enabled, etc.
+ */
+export declare function getPluginEntry(config: unknown, pluginId: string): unknown;
+export interface ConversationAccessCheckResult {
+    authorized: boolean;
+    reason?: string;
+    nextAction?: string;
+}
+/**
+ * PRI-343: Pure function — checks if pluginConfig has hooks.allowConversationAccess === true.
+ * Returns a structured result with reason and nextAction when not authorized (ERR-002).
+ */
+export declare function checkConversationAccessConfig(pluginConfig: unknown): ConversationAccessCheckResult;

package/dist/core/config-health.js

@@ -0,0 +1,60 @@
+/**
+ * Conversation Access Health Check (PRI-343 / PRI-346)
+ *
+ * Pure function for checking whether OpenClaw plugin config has
+ * allowConversationAccess set to true. When missing, llm_output and
+ * trajectory hooks are silently blocked by OpenClaw, causing evidence
+ * to always be empty (PRI-338 root cause).
+ *
+ * Extracted from index.ts to avoid circular imports when trajectory-collector.ts
+ * needs to check conversation access state (PRI-346).
+ */
+/**
+ * PRI-348: Extract the full plugin entry (including hooks) from the global OpenClaw config.
+ * Unlike api.pluginConfig (which is only the entry.config sub-object), this returns
+ * the entire entry including hooks, config, enabled, etc.
+ */
+export function getPluginEntry(config, pluginId) {
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        return undefined;
+    const plugins = config.plugins;
+    if (!plugins || typeof plugins !== 'object' || Array.isArray(plugins))
+        return undefined;
+    const entries = plugins.entries;
+    if (!entries || typeof entries !== 'object' || Array.isArray(entries))
+        return undefined;
+    return entries[pluginId];
+}
+/** Keep in sync with @principles/core CONVERSATION_ACCESS_CONFIG_KEY */
+const CONVERSATION_ACCESS_CONFIG_KEY = 'allowConversationAccess';
+const CONVERSATION_ACCESS_FIX_COMMAND = 'openclaw config set plugins.entries.principles-disciple.hooks.allowConversationAccess true --strict-json';
+/**
+ * PRI-343: Pure function — checks if pluginConfig has hooks.allowConversationAccess === true.
+ * Returns a structured result with reason and nextAction when not authorized (ERR-002).
+ */
+export function checkConversationAccessConfig(pluginConfig) {
+    if (pluginConfig === null || pluginConfig === undefined || typeof pluginConfig !== 'object' || Array.isArray(pluginConfig)) {
+        return {
+            authorized: false,
+            reason: 'pluginConfig is missing or invalid — conversation hooks cannot be registered',
+            nextAction: CONVERSATION_ACCESS_FIX_COMMAND,
+        };
+    }
+    const config = pluginConfig;
+    if (typeof config.hooks !== 'object' || config.hooks === null || Array.isArray(config.hooks)) {
+        return {
+            authorized: false,
+            reason: 'allowConversationAccess is not set to true',
+            nextAction: CONVERSATION_ACCESS_FIX_COMMAND,
+        };
+    }
+    const hooks = config.hooks;
+    if (hooks[CONVERSATION_ACCESS_CONFIG_KEY] !== true) {
+        return {
+            authorized: false,
+            reason: 'allowConversationAccess is not set to true',
+            nextAction: CONVERSATION_ACCESS_FIX_COMMAND,
+        };
+    }
+    return { authorized: true };
+}

package/dist/core/config-service.d.ts

@@ -0,0 +1,15 @@
+import { PainConfig } from './config.js';
+/**
+ * Singleton service to manage the Pain Configuration.
+ */
+export declare const ConfigService: {
+    /**
+     * Gets or initializes the Pain Configuration instance.
+     * @param stateDir The directory where the settings JSON is stored.
+     */
+    get(stateDir: string): PainConfig;
+    /**
+     * Resets the singleton instance (primarily for testing).
+     */
+    reset(): void;
+};

package/{src/core/config-service.ts → dist/core/config-service.js}

@@ -1,8 +1,6 @@
 import { PainConfig } from './config.js';
-
-let config: PainConfig | null = null;
-let lastStateDir: string | null = null;
-
+let config = null;
+let lastStateDir = null;
 /**
  * Singleton service to manage the Pain Configuration.
  */
@@ -11,7 +9,7 @@ export const ConfigService = {
      * Gets or initializes the Pain Configuration instance.
      * @param stateDir The directory where the settings JSON is stored.
      */
-    get(stateDir: string): PainConfig {
+    get(stateDir) {
         if (!config || lastStateDir !== stateDir) {
             config = new PainConfig(stateDir);
             config.load();
@@ -19,11 +17,10 @@ export const ConfigService = {
         }
         return config;
     },
-
     /**
      * Resets the singleton instance (primarily for testing).
      */
-    reset(): void {
+    reset() {
         config = null;
     }
 };

package/dist/core/config.d.ts

@@ -0,0 +1,111 @@
+export interface GfiGateSettings {
+    enabled: boolean;
+    thresholds: {
+        low_risk_block: number;
+        high_risk_block: number;
+        large_change_block: number;
+    };
+    large_change_lines: number;
+    ep_tier_multipliers: {
+        '1': number;
+        '2': number;
+        '3': number;
+        '4': number;
+        '5': number;
+    };
+    bash_safe_patterns: string[];
+    bash_dangerous_patterns: string[];
+}
+export interface DiagnosticianSettings {
+    context: {
+        time_window_minutes: number;
+        max_message_length: number;
+        max_summary_length: number;
+    };
+}
+export interface PainSettings {
+    language: 'en' | 'zh';
+    trajectory?: {
+        blob_inline_threshold_bytes?: number;
+        busy_timeout_ms?: number;
+        orphan_blob_grace_days?: number;
+    };
+    diagnostician?: DiagnosticianSettings;
+    thresholds: {
+        pain_trigger: number;
+        cognitive_paralysis_input: number;
+        stuck_loops_trigger: number;
+        semantic_min_score: number;
+        promotion_count_threshold: number;
+        promotion_similarity_threshold: number;
+    };
+    scores: {
+        paralysis: number;
+        default_confusion: number;
+        default_loop: number;
+        tool_failure_friction: number;
+        exit_code_penalty: number;
+        spiral_penalty: number;
+        missing_test_command_penalty: number;
+        subagent_error_penalty: number;
+        subagent_timeout_penalty: number;
+    };
+    severity_thresholds: {
+        high: number;
+        medium: number;
+        low: number;
+    };
+    intervals: {
+        worker_poll_ms: number;
+        initial_delay_ms: number;
+        task_timeout_ms: number;
+    };
+    empathy_engine?: {
+        enabled?: boolean;
+        dedupe_window_ms?: number;
+        penalties?: {
+            mild?: number;
+            moderate?: number;
+            severe?: number;
+        };
+        rate_limit?: {
+            max_per_turn?: number;
+            max_per_hour?: number;
+        };
+        model_calibration?: Record<string, number>;
+    };
+    gfi_gate?: GfiGateSettings;
+    compression?: {
+        /** 触发自动压缩的行数阈值 */
+        line_threshold?: number;
+        /** 触发自动压缩的字节阈值 */
+        size_threshold_kb?: number;
+        /** 自动压缩间隔（小时） */
+        interval_hours?: number;
+        /** 保留的已完成任务数 */
+        keep_completed_tasks?: number;
+        /** Working Memory 最大条数 */
+        max_working_memory_artifacts?: number;
+    };
+}
+export declare const DEFAULT_SETTINGS: PainSettings;
+export declare class PainConfig {
+    private settings;
+    private readonly filePath;
+    constructor(stateDir: string);
+    load(): void;
+    save(): void;
+    private deepMerge;
+    /**
+     * Basic validation for critical settings
+     */
+    private validate;
+    /**
+     * Gets a value using dot notation (e.g. 'thresholds.pain_trigger')
+     */
+    get(keyPath: string): any;
+    /**
+     * Returns all settings as a plain object.
+     */
+    getAll(): PainSettings;
+}