principles-disciple 1.8.1 → 1.8.3

package/dist/hooks/subagent.d.ts

@@ -1,10 +0,0 @@
-import type { PluginHookSubagentEndedEvent, PluginHookSubagentContext } from '../openclaw-sdk.js';
-import { type EmpathyObserverApi } from '../service/empathy-observer-manager.js';
-type SubagentEndedHookContext = PluginHookSubagentContext & {
-    api?: EmpathyObserverApi;
-    workspaceDir?: string;
-    sessionId?: string;
-    agentId?: string;
-};
-export declare function handleSubagentEnded(event: PluginHookSubagentEndedEvent, ctx: SubagentEndedHookContext): Promise<void>;
-export {};

package/dist/hooks/subagent.js

@@ -1,387 +0,0 @@
-import * as fs from 'fs';
-import { writePainFlag } from '../core/pain.js';
-import { WorkspaceContext } from '../core/workspace-context.js';
-import { empathyObserverManager, isEmpathyObserverSession } from '../service/empathy-observer-manager.js';
-import { acquireQueueLock } from '../service/evolution-worker.js';
-import { recordEvolutionSuccess } from '../core/evolution-engine.js';
-const COMPLETION_RETRY_DELAY_MS = 250;
-const COMPLETION_MAX_RETRIES = 3;
-const COMPLETION_RETRY_TTL_MS = 60 * 60 * 1000; // 1 hour TTL for retry entries
-const TASK_OUTCOME_RETRY_DELAY_MS = 250;
-const TASK_OUTCOME_MAX_RETRIES = 3;
-const DIAGNOSTICIAN_SESSION_PREFIX = 'agent:diagnostician:';
-const completionRetryCounts = new Map();
-// Cleanup expired retry entries periodically
-function cleanupExpiredRetryEntries() {
-    const now = Date.now();
-    for (const [key, value] of completionRetryCounts.entries()) {
-        if (now > value.expires) {
-            completionRetryCounts.delete(key);
-        }
-    }
-}
-function emitSubagentPainEvent(wctx, payload, logger) {
-    try {
-        wctx.evolutionReducer.emitSync({
-            ts: new Date().toISOString(),
-            type: 'pain_detected',
-            data: {
-                painId: `pain_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
-                painType: 'subagent_error',
-                source: payload.source,
-                reason: payload.reason,
-                score: payload.score,
-                sessionId: payload.sessionId,
-                agentId: payload.agentId,
-            },
-        });
-    }
-    catch (e) {
-        logger.warn(`[PD:Subagent] failed to emit evolution event: ${String(e)}`);
-    }
-}
-function isDiagnosticianSession(targetSessionKey) {
-    return typeof targetSessionKey === 'string' && targetSessionKey.startsWith(DIAGNOSTICIAN_SESSION_PREFIX);
-}
-function extractAgentIdFromSessionKey(sessionKey) {
-    // sessionKey format: "agent:{agentId}:{type}:{uuid}" or "agent:{agentId}:{uuid}"
-    if (!sessionKey)
-        return undefined;
-    const match = sessionKey.match(/^agent:([^:]+):/);
-    return match ? match[1] : undefined;
-}
-function cleanupPainFlagForTask(wctx, completedTaskId, queue, logger) {
-    const painFlagPath = wctx.resolve('PAIN_FLAG');
-    try {
-        const painData = fs.readFileSync(painFlagPath, 'utf8');
-        const taskIdMatch = painData.match(/^task_id:\s*(.+)$/m);
-        const painTaskId = taskIdMatch?.[1]?.trim();
-        const hasQueuedStatus = painData.includes('status: queued');
-        const hasRemainingActiveTasks = queue.some((task) => task?.status === 'pending' || task?.status === 'in_progress');
-        if (!hasQueuedStatus)
-            return;
-        if (painTaskId) {
-            if (painTaskId === completedTaskId) {
-                fs.unlinkSync(painFlagPath);
-            }
-            return;
-        }
-        // Legacy fallback: only clear an untagged queued pain flag when there are
-        // no active queue entries left. This avoids unrelated diagnostician runs
-        // from deleting a queued flag that belongs to another task.
-        if (!hasRemainingActiveTasks) {
-            fs.unlinkSync(painFlagPath);
-        }
-    }
-    catch (e) {
-        if (e.code === 'ENOENT')
-            return; // File doesn't exist, nothing to clean up
-        logger.error(`[PD:Subagent] Failed to cleanup pain flag: ${String(e)}`);
-    }
-}
-function getCompletionRetryKey(workspaceDir, targetSessionKey) {
-    return `${workspaceDir}::${targetSessionKey}`;
-}
-function scheduleCompletionRetry(event, ctx, attempt) {
-    const workspaceDir = ctx.workspaceDir;
-    const targetSessionKey = event.targetSessionKey;
-    if (!workspaceDir || !targetSessionKey || attempt >= COMPLETION_MAX_RETRIES) {
-        return;
-    }
-    cleanupExpiredRetryEntries();
-    const retryKey = getCompletionRetryKey(workspaceDir, targetSessionKey);
-    completionRetryCounts.set(retryKey, {
-        count: attempt + 1,
-        expires: Date.now() + COMPLETION_RETRY_TTL_MS
-    });
-    setTimeout(() => {
-        void handleSubagentEnded(event, ctx).finally(() => {
-            const entry = completionRetryCounts.get(retryKey);
-            if (!entry || entry.count <= attempt + 1) {
-                completionRetryCounts.delete(retryKey);
-            }
-        });
-    }, COMPLETION_RETRY_DELAY_MS);
-}
-function scheduleTaskOutcomeRetry(wctx, payload, attempt, logger) {
-    if (attempt > TASK_OUTCOME_MAX_RETRIES) {
-        logger.error(`[PD:Subagent] Failed to persist task outcome after ${TASK_OUTCOME_MAX_RETRIES} retries: ${payload.taskId}`);
-        return;
-    }
-    setTimeout(() => {
-        try {
-            wctx.trajectory?.recordTaskOutcome?.(payload);
-        }
-        catch (error) {
-            logger.warn(`[PD:Subagent] Retrying task outcome persistence for ${payload.taskId}: ${String(error)}`);
-            scheduleTaskOutcomeRetry(wctx, payload, attempt + 1, logger);
-        }
-    }, TASK_OUTCOME_RETRY_DELAY_MS);
-}
-export async function handleSubagentEnded(event, ctx) {
-    const { outcome, targetSessionKey } = event;
-    const workspaceDir = ctx.workspaceDir;
-    if (!workspaceDir)
-        return;
-    const wctx = WorkspaceContext.fromHookContext(ctx);
-    const logger = ctx.api?.logger ?? console;
-    if (isEmpathyObserverSession(targetSessionKey || '')) {
-        await empathyObserverManager.reap(ctx.api, targetSessionKey, workspaceDir);
-        return;
-    }
-    const config = wctx.config;
-    // ── Outcome-based EP and Pain Signal handling ──
-    // OpenClaw v2026.3.23 fixes: timeout may be false positive (fast-finishing workers)
-    // Only penalize actual errors, not timeout/killed/reset
-    if (outcome === 'error') {
-        // Only actual errors trigger penalty
-        const scoreSettings = config.get('scores');
-        const score = scoreSettings.subagent_error_penalty;
-        const reason = `Subagent session ${targetSessionKey} ended with error`;
-        writePainFlag(workspaceDir, {
-            source: `subagent_error`,
-            score: String(score),
-            time: new Date().toISOString(),
-            reason,
-            is_risky: 'true',
-            session_id: ctx.sessionId || '',
-            agent_id: ctx.agentId || extractAgentIdFromSessionKey(targetSessionKey) || '',
-        });
-        emitSubagentPainEvent(wctx, {
-            source: `subagent_error`,
-            reason,
-            score,
-            sessionId: ctx.sessionId,
-            agentId: ctx.agentId || extractAgentIdFromSessionKey(targetSessionKey),
-        }, logger);
-    }
-    if (outcome === 'timeout') {
-        // OpenClaw v2026.3.23 fix: timeout may be false positive
-        // Fast-finishing workers are no longer incorrectly reported as timed out
-        // Do not penalize - the task may have actually succeeded
-        logger.warn(`[PD:Subagent] Session ${targetSessionKey} timed out - not penalizing (OpenClaw fix applied)`);
-    }
-    if (outcome === 'killed' || outcome === 'reset') {
-        // User-initiated termination or system reset - not an agent failure
-        logger.info(`[PD:Subagent] Session ${targetSessionKey} ended with ${outcome} - no penalty (user/system action)`);
-    }
-    if (outcome === 'ok' || outcome === 'deleted') {
-        recordEvolutionSuccess(workspaceDir, 'subagent', {
-            sessionId: ctx.sessionId,
-            reason: 'subagent_success',
-        });
-    }
-    if ((outcome !== 'ok' && outcome !== 'deleted') || !isDiagnosticianSession(targetSessionKey)) {
-        return;
-    }
-    const queuePath = wctx.resolve('EVOLUTION_QUEUE');
-    if (!fs.existsSync(queuePath))
-        return;
-    const retryKey = getCompletionRetryKey(workspaceDir, targetSessionKey);
-    const retryEntry = completionRetryCounts.get(retryKey);
-    const attempt = retryEntry?.count || 0;
-    let releaseLock = null;
-    try {
-        releaseLock = await acquireQueueLock(queuePath, logger);
-        const queue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
-        let completedTaskId = null;
-        // Improved matching logic: support both direct session key match and HEARTBEAT placeholder match
-        // This fixes task_outcomes being empty for HEARTBEAT-triggered diagnostician runs
-        const matchedTask = queue.find((task) => {
-            // V2: Skip non-pain_diagnosis tasks - they don't use HEARTBEAT completion flow
-            // pain_diagnosis: routed through subagent completion matcher (this block)
-            // sleep_reflection: handled by nocturnal service (separate flow, no HEARTBEAT)
-            // model_eval: handled separately (no HEARTBEAT completion)
-            if (task?.taskKind !== 'pain_diagnosis' && task?.taskKind !== undefined)
-                return false;
-            const taskSessionKey = task?.assigned_session_key;
-            // 1. Exact match: direct session key assignment
-            if (typeof taskSessionKey === 'string' && taskSessionKey === targetSessionKey) {
-                return true;
-            }
-            // 2. HEARTBEAT placeholder match: for diagnostician sessions
-            // Tasks started via HEARTBEAT have placeholder like "heartbeat:diagnostician:{taskId}"
-            if (isDiagnosticianSession(targetSessionKey)) {
-                // Match tasks with HEARTBEAT placeholder
-                if (typeof taskSessionKey === 'string' && taskSessionKey.startsWith('heartbeat:diagnostician')) {
-                    return true;
-                }
-                // Backward compatibility: match tasks with no assigned_session_key (legacy behavior)
-                // Only match tasks started within 2 hours to avoid stale task matching
-                if (taskSessionKey === undefined || taskSessionKey === null) {
-                    const taskStartedAt = task?.started_at ? new Date(task.started_at).getTime() : 0;
-                    const taskAge = taskStartedAt > 0 ? Date.now() - taskStartedAt : Infinity;
-                    const LEGACY_FALLBACK_MAX_AGE_MS = 2 * 60 * 60 * 1000; // 2 hours
-                    if (taskAge < LEGACY_FALLBACK_MAX_AGE_MS) {
-                        return true;
-                    }
-                }
-            }
-            return false;
-        });
-        if (matchedTask) {
-            // Enhanced observability: log match type for debugging
-            const matchType = matchedTask.assigned_session_key === targetSessionKey
-                ? 'exact'
-                : matchedTask.assigned_session_key?.startsWith('heartbeat:diagnostician')
-                    ? 'heartbeat_placeholder'
-                    : 'legacy_fallback';
-            logger.info(`[PD:Subagent] Matched session ${targetSessionKey} to task ${matchedTask.id} (match_type: ${matchType})`);
-            matchedTask.status = 'completed';
-            matchedTask.completed_at = new Date().toISOString();
-            delete matchedTask.assigned_session_key;
-            completedTaskId = matchedTask.id;
-        }
-        else {
-            logger.warn(`[PD:Subagent] No in-progress evolution task matched subagent session ${targetSessionKey}`);
-        }
-        let taskOutcomePayload = null;
-        if (completedTaskId) {
-            fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
-            cleanupPainFlagForTask(wctx, completedTaskId, queue, logger);
-            taskOutcomePayload = {
-                sessionId: targetSessionKey,
-                taskId: completedTaskId,
-                outcome,
-                summary: `Diagnostician session ${targetSessionKey} completed evolution task ${completedTaskId}.`,
-            };
-        }
-        if (taskOutcomePayload) {
-            try {
-                wctx.trajectory?.recordTaskOutcome?.(taskOutcomePayload);
-            }
-            catch (error) {
-                logger.warn(`[PD:Subagent] Failed to persist task outcome for ${taskOutcomePayload.taskId}: ${String(error)}`);
-                scheduleTaskOutcomeRetry(wctx, taskOutcomePayload, 1, logger);
-            }
-        }
-        // Read diagnostician output and create principle with generalized pattern
-        if (completedTaskId && ctx.api?.runtime?.subagent) {
-            try {
-                const messages = await ctx.api?.runtime?.subagent?.getSessionMessages?.({
-                    sessionKey: targetSessionKey,
-                    limit: 50
-                });
-                const assistantText = extractAssistantText(messages);
-                const report = parseDiagnosticianReport(assistantText);
-                if (report?.principle) {
-                    // Principles default to 'manual_only' evaluability unless detector metadata
-                    // is explicitly provided. Only deterministic / weak_heuristic evaluability
-                    // can enter automatic nocturnal targeting.
-                    const evaluability = report.principle.evaluability;
-                    // Only pass detector metadata if ALL required fields are present and valid.
-                    // Incomplete metadata → 'manual_only' — the principle stays prompt-only.
-                    // Defense in depth: also validate in reducer, but subagent should not pass
-                    // malformed data in the first place.
-                    const rawMeta = report.principle.detector_metadata;
-                    // Require confidence (valid enum) + ALL THREE signal arrays non-empty.
-                    // toolSequenceHints is optional (may be empty or absent).
-                    const VALID_CONFIDENCE = ['high', 'medium', 'low'];
-                    const hasValidConfidence = typeof rawMeta?.confidence === 'string' &&
-                        VALID_CONFIDENCE.includes(rawMeta.confidence);
-                    const signalArrays = [
-                        rawMeta?.applicabilityTags,
-                        rawMeta?.positiveSignals,
-                        rawMeta?.negativeSignals,
-                    ];
-                    const allSignalsNonEmpty = signalArrays.every((arr) => Array.isArray(arr) && arr.length > 0 && arr.every((s) => typeof s === 'string' && s.length > 0));
-                    const hasCompleteMetadata = hasValidConfidence && allSignalsNonEmpty;
-                    const detectorMetadata = hasCompleteMetadata && rawMeta.confidence
-                        ? {
-                            applicabilityTags: rawMeta.applicabilityTags ?? [],
-                            positiveSignals: rawMeta.positiveSignals ?? [],
-                            negativeSignals: rawMeta.negativeSignals ?? [],
-                            toolSequenceHints: rawMeta.toolSequenceHints ?? [],
-                            confidence: rawMeta.confidence,
-                        }
-                        : undefined;
-                    const principleId = wctx.evolutionReducer.createPrincipleFromDiagnosis({
-                        painId: matchedTask?.id || completedTaskId,
-                        painType: 'tool_failure', // Default, could be extracted from task
-                        triggerPattern: report.principle.trigger_pattern,
-                        action: report.principle.action,
-                        source: matchedTask?.source || 'diagnostician',
-                        evaluability,
-                        detectorMetadata,
-                    });
-                    if (principleId) {
-                        logger.warn(`[PD:Subagent] Created principle ${principleId} from diagnostician analysis for task ${completedTaskId}`);
-                    }
-                }
-            }
-            catch (e) {
-                logger.warn(`[PD:Subagent] Failed to read diagnostician output: ${String(e)}`);
-            }
-        }
-    }
-    catch (e) {
-        logger.error(`[PD:Subagent] Failed to update evolution queue: ${String(e)}`);
-        scheduleCompletionRetry(event, ctx, attempt);
-    }
-    finally {
-        releaseLock?.();
-    }
-}
-/**
- * Extract text content from assistant messages
- */
-function extractAssistantText(messages) {
-    if (!messages || !Array.isArray(messages))
-        return '';
-    const texts = [];
-    for (const msg of messages) {
-        if (msg?.role !== 'assistant')
-            continue;
-        const content = msg?.content;
-        if (Array.isArray(content)) {
-            for (const block of content) {
-                if (block?.type === 'text' && typeof block.text === 'string') {
-                    texts.push(block.text);
-                }
-            }
-        }
-        else if (typeof content === 'string') {
-            texts.push(content);
-        }
-    }
-    return texts.join('\n');
-}
-/**
- * Parse diagnostician JSON report from text
- */
-function parseDiagnosticianReport(text) {
-    // Try to find JSON in markdown code block
-    const jsonMatch = text.match(/```json\n([\s\S]*?)\n```/);
-    if (jsonMatch) {
-        try {
-            const parsed = JSON.parse(jsonMatch[1]);
-            // Support both direct principle and nested phases.principle_extraction structure
-            if (parsed?.principle) {
-                return { principle: parsed.principle };
-            }
-            if (parsed?.phases?.principle_extraction?.principle) {
-                return { principle: parsed.phases.principle_extraction.principle };
-            }
-        }
-        catch {
-            // Fall through to return null
-        }
-    }
-    // Try to find raw JSON object
-    const objectMatch = text.match(/\{[\s\S]*"principle"[\s\S]*\}/);
-    if (objectMatch) {
-        try {
-            const parsed = JSON.parse(objectMatch[0]);
-            if (parsed?.principle) {
-                return { principle: parsed.principle };
-            }
-            if (parsed?.phases?.principle_extraction?.principle) {
-                return { principle: parsed.phases.principle_extraction.principle };
-            }
-        }
-        catch {
-            // Fall through to return null
-        }
-    }
-    return null;
-}

package/dist/hooks/thinking-checkpoint.d.ts

@@ -1,37 +0,0 @@
-/**
- * Thinking Checkpoint Module
- *
- * Enforces P-10 deep reflection requirement for high-risk tool operations.
- *
- * **Responsibilities:**
- * - Check if high-risk tools have recent deep thinking (T-01 through T-10)
- * - Block high-risk operations without preceding deep reflection
- * - Configurable time window for thinking validity (default 5 minutes)
- * - Provide clear guidance on required action (deep_reflect tool usage)
- *
- * **Configuration:**
- * - Thinking checkpoint settings from profile.thinking_checkpoint
- * - Window duration for thinking validity
- * - High-risk tool list
- */
-import type { PluginHookBeforeToolCallEvent, PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
-export interface ThinkingCheckpointConfig {
-    enabled?: boolean;
-    window_ms?: number;
-    high_risk_tools?: string[];
-}
-/**
- * Checks if a tool call requires a recent deep thinking checkpoint.
- *
- * This enforces P-10 (Thinking OS Checkpoint) - high-risk operations must
- * be preceded by deep reflection within the configured time window.
- *
- * @param event - The before_tool_call event
- * @param config - Thinking checkpoint configuration from profile
- * @param sessionId - Current session ID
- * @param logger - Optional logger for info messages
- * @returns Block result if thinking required, undefined otherwise
- */
-export declare function checkThinkingCheckpoint(event: PluginHookBeforeToolCallEvent, config: ThinkingCheckpointConfig, sessionId: string | undefined, logger?: {
-    info?: (message: string) => void;
-}): PluginHookBeforeToolCallResult | undefined;

package/dist/hooks/thinking-checkpoint.js

@@ -1,51 +0,0 @@
-/**
- * Thinking Checkpoint Module
- *
- * Enforces P-10 deep reflection requirement for high-risk tool operations.
- *
- * **Responsibilities:**
- * - Check if high-risk tools have recent deep thinking (T-01 through T-10)
- * - Block high-risk operations without preceding deep reflection
- * - Configurable time window for thinking validity (default 5 minutes)
- * - Provide clear guidance on required action (deep_reflect tool usage)
- *
- * **Configuration:**
- * - Thinking checkpoint settings from profile.thinking_checkpoint
- * - Window duration for thinking validity
- * - High-risk tool list
- */
-import { hasRecentThinking } from '../core/session-tracker.js';
-import { THINKING_CHECKPOINT_WINDOW_MS, THINKING_CHECKPOINT_DEFAULT_HIGH_RISK_TOOLS } from '../config/index.js';
-/**
- * Checks if a tool call requires a recent deep thinking checkpoint.
- *
- * This enforces P-10 (Thinking OS Checkpoint) - high-risk operations must
- * be preceded by deep reflection within the configured time window.
- *
- * @param event - The before_tool_call event
- * @param config - Thinking checkpoint configuration from profile
- * @param sessionId - Current session ID
- * @param logger - Optional logger for info messages
- * @returns Block result if thinking required, undefined otherwise
- */
-export function checkThinkingCheckpoint(event, config, sessionId, logger) {
-    const enabled = config.enabled ?? false;
-    const windowMs = config.window_ms ?? THINKING_CHECKPOINT_WINDOW_MS;
-    const highRiskTools = config.high_risk_tools ?? [...THINKING_CHECKPOINT_DEFAULT_HIGH_RISK_TOOLS];
-    if (!enabled || !sessionId) {
-        return undefined;
-    }
-    const isHighRisk = highRiskTools.includes(event.toolName);
-    if (!isHighRisk) {
-        return undefined;
-    }
-    const hasThinking = hasRecentThinking(sessionId, windowMs);
-    if (!hasThinking) {
-        logger?.info?.(`[PD:THINKING_GATE] High-risk tool "${event.toolName}" called without recent deep thinking`);
-        return {
-            block: true,
-            blockReason: `[Thinking OS Checkpoint] 高风险操作 "${event.toolName}" 需要先进行深度思考。\n\n请先使用 deep_reflect 工具分析当前情况，然后再尝试此操作。\n\n这是强制性检查点，目的是确保决策质量。\n\n提示：调用 deep_reflect 后，${Math.round(windowMs / 60000)}分钟内的操作将自动放行。\n\n可在PROFILE.json中设置 thinking_checkpoint.enabled: false 来禁用此检查。`,
-        };
-    }
-    return undefined;
-}

package/dist/hooks/trajectory-collector.d.ts

@@ -1,32 +0,0 @@
-/**
- * Trajectory Collector - 行为进化引擎 Phase 0 数据收集
- *
- * 收集工具调用和 LLM 输出到 memory/trajectories/ 目录
- * 用于分析工具使用模式、识别原则应用案例、评估行为质量
- */
-import type { PluginHookAfterToolCallEvent, PluginHookToolContext, PluginHookLlmOutputEvent, PluginHookAgentContext, PluginHookBeforeMessageWriteEvent } from '../openclaw-sdk.js';
-/**
- * 工具调用完成后的处理
- * 记录：工具名、参数、结果、错误、执行时间
- */
-export declare function handleAfterToolCall(event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext & {
-    workspaceDir?: string;
-}): void;
-/**
- * LLM 输出处理
- * 记录：provider、model、输出长度、token 使用量
- */
-export declare function handleLlmOutput(event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext & {
-    workspaceDir?: string;
-}): void;
-/**
- * 消息写入前的处理
- * 记录：用户/助手消息内容
- */
-export declare function handleBeforeMessageWrite(event: PluginHookBeforeMessageWriteEvent, ctx: PluginHookAgentContext & {
-    workspaceDir?: string;
-}): void;
-/**
- * 轨迹汇总统计（供 cron 任务调用）
- */
-export declare function computeTrajectoryStats(workspaceDir: string): object;