principles-disciple 1.127.0 → 1.129.0

package/dist/core/pain-diagnostic-gate.d.ts

@@ -0,0 +1,36 @@
+declare const PAIN_DIAGNOSTIC_SOURCES: readonly ["manual", "tool_failure", "dispatch_error", "gate_blocked", "user_empathy", "llm_paralysis", "semantic", "subagent_error"];
+export type PainDiagnosticSource = typeof PAIN_DIAGNOSTIC_SOURCES[number];
+export type PainDiagnosticGateReason = 'manual' | 'high_gfi' | 'repeated_failure' | 'semantic_pain' | 'llm_paralysis' | 'risky_high_score' | 'subagent_error' | 'gate_blocked' | 'cooldown' | 'below_gate';
+export interface PainDiagnosticGateInput {
+    source: PainDiagnosticSource | string;
+    score: number;
+    currentGfi: number;
+    consecutiveErrors?: number;
+    isRisky?: boolean;
+    errorHash?: string;
+    sessionId?: string;
+    nowMs?: number;
+    cooldownMs?: number;
+    thresholds?: {
+        painTrigger?: number;
+        highSeverity?: number;
+        highGfi?: number;
+        repeatedFailure?: number;
+        semanticPain?: number;
+    };
+}
+export interface PainDiagnosticGateDecision {
+    shouldDiagnose: boolean;
+    reason: PainDiagnosticGateReason;
+    episodeKey: string;
+    detail: string;
+}
+export declare function resetPainDiagnosticGateForTest(): void;
+/**
+ * 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 declare function isCooldownActiveForEpisode(source: string, sessionId: string | undefined, errorHash: string | undefined, cooldownMs?: number): boolean;
+export declare function evaluatePainDiagnosticGate(input: PainDiagnosticGateInput): PainDiagnosticGateDecision;
+export {};

package/dist/core/pain-diagnostic-gate.js

@@ -0,0 +1,105 @@
+import { SystemLogger } from './system-logger.js';
+const PAIN_DIAGNOSTIC_SOURCES = [
+    'manual',
+    'tool_failure',
+    'dispatch_error',
+    'gate_blocked',
+    'user_empathy',
+    'llm_paralysis',
+    'semantic',
+    'subagent_error',
+];
+const DEFAULT_COOLDOWN_MS = 15 * 60 * 1000;
+const lastDiagnosedAtByEpisode = new Map();
+function normalizedSource(source) {
+    if (source.startsWith('llm_') && source !== 'llm_paralysis') {
+        return 'semantic';
+    }
+    if (!PAIN_DIAGNOSTIC_SOURCES.includes(source)) {
+        SystemLogger.log('', 'GATE_UNKNOWN_SOURCE', `Unknown pain source: "${source}"`);
+    }
+    return source;
+}
+function buildEpisodeKey(input) {
+    const source = normalizedSource(input.source);
+    const sessionId = input.sessionId || 'unknown';
+    const hash = input.errorHash || 'no-hash';
+    return `${sessionId}:${source}:${hash}`;
+}
+function withinCooldown(input, episodeKey) {
+    const cooldownMs = input.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+    if (cooldownMs <= 0)
+        return false;
+    const nowMs = input.nowMs ?? Date.now();
+    const last = lastDiagnosedAtByEpisode.get(episodeKey);
+    return last !== undefined && nowMs - last < cooldownMs;
+}
+function markDiagnosed(input, episodeKey) {
+    lastDiagnosedAtByEpisode.set(episodeKey, input.nowMs ?? Date.now());
+}
+export function resetPainDiagnosticGateForTest() {
+    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, sessionId, errorHash, cooldownMs) {
+    const episodeKey = buildEpisodeKey({ source, sessionId, errorHash });
+    return withinCooldown({ source, sessionId, errorHash, cooldownMs }, episodeKey);
+}
+export function evaluatePainDiagnosticGate(input) {
+    const source = normalizedSource(input.source);
+    const episodeKey = buildEpisodeKey(input);
+    const painTrigger = input.thresholds?.painTrigger ?? 40;
+    const highSeverity = input.thresholds?.highSeverity ?? 70;
+    const highGfi = input.thresholds?.highGfi ?? Math.max(highSeverity, painTrigger + 30);
+    const repeatedFailure = input.thresholds?.repeatedFailure ?? 4;
+    const semanticPain = input.thresholds?.semanticPain ?? Math.max(painTrigger, 60);
+    const score = Number.isFinite(input.score) ? input.score : 0;
+    const currentGfi = Number.isFinite(input.currentGfi) ? input.currentGfi : 0;
+    const consecutiveErrors = Number.isFinite(input.consecutiveErrors) ? input.consecutiveErrors : 0;
+    const approve = (reason, detail) => {
+        if (withinCooldown(input, episodeKey)) {
+            return {
+                shouldDiagnose: false,
+                reason: 'cooldown',
+                episodeKey,
+                detail: `recently diagnosed; ${detail}`,
+            };
+        }
+        markDiagnosed(input, episodeKey);
+        return { shouldDiagnose: true, reason, episodeKey, detail };
+    };
+    if (source === 'manual') {
+        return approve('manual', 'manual pain signal bypasses automatic gate');
+    }
+    if (source === 'subagent_error' && score >= painTrigger) {
+        return approve('subagent_error', `subagent error score ${score} >= ${painTrigger}`);
+    }
+    if (source === 'llm_paralysis' && score >= painTrigger) {
+        return approve('llm_paralysis', `llm paralysis score ${score} >= ${painTrigger}`);
+    }
+    if (source === 'gate_blocked' && score >= painTrigger) {
+        return approve('gate_blocked', `gate blocked score ${score} >= ${painTrigger}`);
+    }
+    if ((source === 'user_empathy' || source === 'semantic') && score >= semanticPain) {
+        return approve('semantic_pain', `semantic pain score ${score} >= ${semanticPain}`);
+    }
+    if (input.isRisky === true && score >= highSeverity) {
+        return approve('risky_high_score', `risky operation score ${score} >= ${highSeverity}`);
+    }
+    if (consecutiveErrors >= repeatedFailure) {
+        return approve('repeated_failure', `consecutive errors ${consecutiveErrors} >= ${repeatedFailure}`);
+    }
+    if (currentGfi >= highGfi) {
+        return approve('high_gfi', `GFI ${currentGfi.toFixed(1)} >= ${highGfi}`);
+    }
+    return {
+        shouldDiagnose: false,
+        reason: 'below_gate',
+        episodeKey,
+        detail: `score=${score}; gfi=${currentGfi.toFixed(1)}; consecutive=${consecutiveErrors}`,
+    };
+}

package/dist/core/pain.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Required fields — every pain flag MUST have these.
+ */
+export interface PainFlagData {
+    /** What triggered this pain signal (e.g., tool_failure, human_intervention, intercept_extraction) */
+    source: string;
+    /** Pain score 0-100 */
+    score: string;
+    /** ISO 8601 timestamp */
+    time: string;
+    /** Human-readable reason / error description */
+    reason: string;
+    /** Session ID — identifies which conversation this happened in */
+    session_id: string;
+    /** Agent ID — identifies which agent (main, builder, diagnostician, etc.) */
+    agent_id: string;
+    /** Whether this involves risky operation ('true' / 'false') */
+    is_risky: string;
+    /** Correlation trace ID (for linking events across the pipeline) */
+    trace_id: string;
+    /** Preview of the text that triggered this pain */
+    trigger_text_preview: string;
+    /** Trajectory pain_events row ID (set by recordPainEvent) */
+    pain_event_id?: string;
+}
+export interface PainFlagContractResult {
+    status: 'missing' | 'valid' | 'invalid';
+    format: 'missing' | 'empty' | 'kv' | 'json' | 'invalid_json';
+    data: Record<string, string>;
+    missingFields: string[];
+}
+/**
+ * Builds legacy pain flag data for compatibility tests and historical readers.
+ * Do not use this to create new Runtime V2 diagnosis requests.
+ */
+export declare function buildPainFlag(input: {
+    source: string;
+    score: string;
+    time?: string;
+    reason: string;
+    session_id?: string;
+    agent_id?: string;
+    is_risky?: boolean;
+    trace_id?: string;
+    trigger_text_preview?: string;
+    pain_event_id?: string;
+}): PainFlagData;
+/**
+ * Validates a pain flag read from disk.
+ * Returns list of missing required fields — empty string means all present.
+ */
+export declare function validatePainFlag(data: Record<string, string>): string[];
+export declare function computePainScore(rc: number, isSpiral: boolean, missingTestCommand: boolean, softScore: number, projectDir?: string): number;
+export declare function painSeverityLabel(painScore: number, isSpiral?: boolean, projectDir?: string): string;
+/**
+ * Reads and validates the legacy pain flag file.
+ *
+ * - If file doesn't exist → returns {}
+ * - If file is JSON format → converts to KV in memory only
+ * - If file is KV format → validates required fields, logs warning if missing
+ * - If file has unknown fields → silently ignores them (forward-compatible)
+ */
+export declare function readPainFlagData(projectDir: string): Record<string, string>;
+export declare function readPainFlagContract(projectDir: string): PainFlagContractResult;
+/**
+ * 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 declare function trackPrincipleValue(workspaceDir: string, painData: {
+    reason?: string;
+    source?: string;
+    score?: string;
+}, getActivePrinciples: () => {
+    id: string;
+    trigger: string;
+    valueMetrics?: {
+        painPreventedCount: number;
+        lastPainPreventedAt?: string;
+        calculatedAt: string;
+    };
+}[], updatePrincipleMetrics: (_id: string, _metrics: {
+    painPreventedCount: number;
+    lastPainPreventedAt: string;
+    calculatedAt: string;
+}) => void): void;

package/dist/core/pain.js

@@ -0,0 +1,223 @@
+import * as fs from 'fs';
+import { parseKvLines } from '../utils/io.js';
+import { resolvePdPath } from './paths.js';
+import { ConfigService } from './config-service.js';
+import { SystemLogger } from './system-logger.js';
+/**
+ * Builds legacy pain flag data for compatibility tests and historical readers.
+ * Do not use this to create new Runtime V2 diagnosis requests.
+ */
+export function buildPainFlag(input) {
+    // Omit optional fields when not provided — prevents writing empty lines to disk
+    // which causes agent confusion (SKILL.md vs reality drift)
+    return {
+        source: input.source,
+        score: input.score,
+        time: input.time || new Date().toISOString(),
+        reason: input.reason,
+        session_id: input.session_id ?? '',
+        agent_id: input.agent_id ?? '',
+        is_risky: input.is_risky ? 'true' : 'false',
+        trace_id: input.trace_id ?? '',
+        trigger_text_preview: input.trigger_text_preview ?? '',
+        pain_event_id: input.pain_event_id,
+    };
+}
+/**
+ * Validates a pain flag read from disk.
+ * Returns list of missing required fields — empty string means all present.
+ */
+export function validatePainFlag(data) {
+    const missing = [];
+    // Only source/score/time/reason are truly required — session_id/agent_id
+    // may be empty in automated contexts (heartbeat, background workers)
+    const required = ['source', 'score', 'time', 'reason'];
+    for (const field of required) {
+        if (!data[field] || data[field].trim() === '') {
+            missing.push(field);
+        }
+    }
+    return missing;
+}
+export function computePainScore(rc, isSpiral, missingTestCommand, softScore, projectDir) {
+    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, isSpiral = false, projectDir) {
+    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";
+    }
+}
+/**
+ * Converts a JSON pain flag object to KV format.
+ */
+function convertJsonToKv(json) {
+    const kvData = {};
+    const fieldMap = {
+        source: 'source',
+        score: 'score',
+        time: 'time',
+        timestamp: 'time',
+        reason: 'reason',
+        session_id: 'session_id',
+        sessionId: 'session_id',
+        agent_id: 'agent_id',
+        agentId: 'agent_id',
+        is_risky: 'is_risky',
+        isRisky: 'is_risky',
+        severity: 'severity',
+        painId: 'pain_id',
+    };
+    for (const [jsonKey, kvKey] of Object.entries(fieldMap)) {
+        if (json[jsonKey] !== undefined) {
+            kvData[kvKey] = String(json[jsonKey]);
+        }
+    }
+    for (const [key, value] of Object.entries(json)) {
+        if (fieldMap[key] === undefined && value !== undefined && value !== null) {
+            kvData[key] = String(value);
+        }
+    }
+    return kvData;
+}
+/**
+ * Reads and validates the legacy pain flag file.
+ *
+ * - If file doesn't exist → returns {}
+ * - If file is JSON format → converts to KV in memory only
+ * - If file is KV format → validates required fields, logs warning if missing
+ * - If file has unknown fields → silently ignores them (forward-compatible)
+ */
+export function readPainFlagData(projectDir) {
+    const painFlagPath = resolvePdPath(projectDir, 'PAIN_FLAG');
+    try {
+        if (!fs.existsSync(painFlagPath)) {
+            return {};
+        }
+        const content = fs.readFileSync(painFlagPath, "utf-8").trim();
+        if (!content) {
+            return {};
+        }
+        // Detect JSON format. Legacy compatibility only: parse in memory and do not
+        // rewrite .pain_flag, because Runtime V2 must not create or repair this file.
+        if (content.startsWith('{')) {
+            let json;
+            try {
+                json = JSON.parse(content);
+            }
+            catch {
+                SystemLogger.log(projectDir, 'PAIN_FLAG_CORRUPT', 'Pain flag file contains invalid JSON');
+                return {};
+            }
+            const kvData = convertJsonToKv(json);
+            SystemLogger.log(projectDir, 'PAIN_FLAG_LEGACY_JSON_READ', `Read legacy JSON pain flag in memory (${Object.keys(json).length} fields)`);
+            return kvData;
+        }
+        // KV format — parse and validate
+        const data = parseKvLines(content);
+        const missing = validatePainFlag(data);
+        if (missing.length > 0) {
+            SystemLogger.log(projectDir, 'PAIN_FLAG_INCOMPLETE', `Pain flag missing required fields: ${missing.join(', ')}`);
+        }
+        return data;
+    }
+    catch (e) {
+        SystemLogger.log(projectDir, 'PAIN_FLAG_READ_ERROR', `Failed to read pain flag: ${String(e)}`);
+        return {};
+    }
+}
+export function readPainFlagContract(projectDir) {
+    const data = readPainFlagData(projectDir);
+    if (Object.keys(data).length === 0) {
+        const painFlagPath = resolvePdPath(projectDir, 'PAIN_FLAG');
+        if (!fs.existsSync(painFlagPath)) {
+            return { status: 'missing', format: 'missing', data: {}, missingFields: [] };
+        }
+        const raw = fs.readFileSync(painFlagPath, 'utf-8').trim();
+        if (!raw) {
+            return { status: 'missing', format: 'empty', data: {}, missingFields: [] };
+        }
+        return {
+            status: 'invalid',
+            format: raw.startsWith('{') ? 'invalid_json' : 'kv',
+            data: {},
+            missingFields: ['unparseable'],
+        };
+    }
+    const missing = validatePainFlag(data);
+    return {
+        status: missing.length > 0 ? 'invalid' : 'valid',
+        format: 'kv',
+        data,
+        missingFields: missing,
+    };
+}
+/**
+ * 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, painData, getActivePrinciples, updatePrincipleMetrics) {
+    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.d.ts

@@ -0,0 +1,60 @@
+import type { OpenClawPluginApi } from '../openclaw-sdk.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;
+    };
+}
+export declare const PD_ENV_VARS: {
+    readonly WORKSPACE_DIR: "PD_WORKSPACE_DIR";
+    readonly STATE_DIR: "PD_STATE_DIR";
+    readonly DEBUG: "DEBUG";
+};
+export declare const PD_ENV_DESCRIPTIONS: Record<keyof typeof PD_ENV_VARS, {
+    desc: string;
+    example: string;
+}>;
+export declare function printEnvVarHelp(): void;
+export interface PDConfig {
+    workspace?: string;
+    state?: string;
+    debug?: boolean;
+}
+export declare class PathResolver {
+    private static extensionRoot;
+    private workspaceDir;
+    private stateDir;
+    private readonly logger?;
+    private readonly normalizeWorkspace;
+    private initialized;
+    static setExtensionRoot(extensionRootPath: string): void;
+    static getExtensionRoot(): string | null;
+    constructor(options?: PathResolverOptions);
+    private log;
+    private detectWorkspaceDir;
+    private normalizePath;
+    normalizeWorkspacePath(inputPath: string): string;
+    getWorkspaceDir(): string;
+    getStateDir(): string;
+    resolve(key: string): string;
+    ensureStateDir(): void;
+    static createFromHookContext(ctx: Record<string, unknown>): PathResolver;
+}
+export declare function createDefaultConfig(targetPath?: string): string;
+/**
+ * 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 declare function resolveWorkspaceDirFromApi(api: OpenClawPluginApi | undefined, agentId?: string): string | undefined;