principles-disciple 1.8.1 → 1.8.3

package/src/hooks/subagent.ts

@@ -0,0 +1,207 @@
+import type { PluginHookSubagentEndedEvent, PluginHookSubagentContext, PluginLogger, OpenClawPluginApi } from '../openclaw-sdk.js';
+import * as fs from 'fs';
+import { writePainFlag } from '../core/pain.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+// No longer needed — diagnostician runs via HEARTBEAT, not subagent
+import { recordEvolutionSuccess } from '../core/evolution-engine.js';
+import { WorkflowStore } from '../service/subagent-workflow/workflow-store.js';
+import { EmpathyObserverWorkflowManager } from '../service/subagent-workflow/empathy-observer-workflow-manager.js';
+import { DeepReflectWorkflowManager } from '../service/subagent-workflow/deep-reflect-workflow-manager.js';
+import type { WorkflowManager } from '../service/subagent-workflow/types.js';
+
+/**
+ * Factory to create the appropriate WorkflowManager by workflow_type string.
+ * Used by the subagent_ended hook to dispatch lifecycle recovery to the right manager.
+ */
+function createWorkflowManagerForType(
+    workflowType: string,
+    workspaceDir: string,
+    logger: HookLogger,
+    subagent: NonNullable<OpenClawPluginApi['runtime']>['subagent'],
+): WorkflowManager | null {
+    const loggerAdapter: PluginLogger = {
+        info: (m: string) => logger.info(String(m)),
+        warn: (m: string) => logger.warn(String(m)),
+        error: (m: string) => logger.error(String(m)),
+        debug: () => {},
+    } as unknown as PluginLogger;
+
+    switch (workflowType) {
+        case 'empathy-observer':
+            return new EmpathyObserverWorkflowManager({
+                workspaceDir,
+                logger: loggerAdapter,
+                subagent,
+            });
+        case 'deep-reflect':
+            return new DeepReflectWorkflowManager({
+                workspaceDir,
+                logger: loggerAdapter,
+                subagent,
+            });
+        default:
+            return null;
+    }
+}
+
+const HELPER_WORKFLOW_SESSION_PREFIX = 'agent:main:subagent:workflow-';
+
+type HookLogger = Pick<PluginLogger, 'info' | 'warn' | 'error'>;
+
+// Cleanup expired retry entries periodically
+
+function emitSubagentPainEvent(
+    wctx: WorkspaceContext,
+    payload: {
+        source: string;
+        reason: string;
+        score: number;
+        sessionId?: string;
+        agentId?: string;
+    },
+    logger: HookLogger
+): void {
+    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 extractAgentIdFromSessionKey(sessionKey: string | undefined): string | undefined {
+    // sessionKey format: "agent:{agentId}:{type}:{uuid}" or "agent:{agentId}:{uuid}"
+    if (!sessionKey) return undefined;
+    const match = sessionKey.match(/^agent:([^:]+):/);
+    return match ? match[1] : undefined;
+}
+
+
+
+
+
+type SubagentEndedHookContext = PluginHookSubagentContext & {
+    api?: OpenClawPluginApi;
+    workspaceDir?: string;
+    sessionId?: string;
+    agentId?: string;
+};
+
+export async function handleSubagentEnded(
+    event: PluginHookSubagentEndedEvent,
+    ctx: SubagentEndedHookContext
+): Promise<void> {
+    const { outcome, targetSessionKey } = event;
+    const workspaceDir = ctx.workspaceDir;
+
+    if (!workspaceDir) return;
+
+    const wctx = WorkspaceContext.fromHookContext(ctx);
+    const logger: HookLogger = ctx.api?.logger ?? console;
+    // ── Helper Workflow Lifecycle Notification ──
+    // When a helper workflow's subagent ends, notify the workflow manager
+    // so that it can trigger fallback recovery (notifyWaitResult → finalizeOnce)
+    if (targetSessionKey?.startsWith(HELPER_WORKFLOW_SESSION_PREFIX)) {
+        try {
+            const store = new WorkflowStore({ workspaceDir });
+            const workflow = store.getWorkflowByChildSession(targetSessionKey);
+            if (workflow && workflow.state !== 'completed' && workflow.state !== 'terminal_error' && workflow.state !== 'expired') {
+                logger.info(`[PD:Subagent] Helper workflow lifecycle event: workflowId=${workflow.workflow_id}, workflowType=${workflow.workflow_type}, outcome=${outcome}`);
+
+                const mappedOutcome = outcome === 'deleted' ? 'deleted' :
+                                      outcome === 'killed' ? 'killed' :
+                                      outcome === 'reset' ? 'reset' :
+                                      outcome === 'error' ? 'error' :
+                                      outcome === 'timeout' ? 'timeout' : 'ok';
+
+                // Call notifyLifecycleEvent on the appropriate manager so it
+                // triggers notifyWaitResult → finalizeOnce / terminal transition.
+                const subagentRuntime = ctx.api?.runtime?.subagent;
+                if (subagentRuntime) {
+                    const mgr = createWorkflowManagerForType(workflow.workflow_type, workspaceDir, logger, subagentRuntime);
+                    if (mgr) {
+                        await mgr.notifyLifecycleEvent(workflow.workflow_id, 'subagent_ended', { outcome: mappedOutcome });
+                        mgr.dispose();
+                    } else {
+                        logger.warn(`[PD:Subagent] Unknown workflow type ${workflow.workflow_type} — falling back to store-only event`);
+                        store.recordEvent(workflow.workflow_id, 'subagent_ended', workflow.state, workflow.state, `subagent ended with outcome: ${outcome}`, { outcome: mappedOutcome });
+                    }
+                } else {
+                    logger.warn(`[PD:Subagent] Subagent runtime not available — cannot notify manager, falling back to store event`);
+                    store.recordEvent(workflow.workflow_id, 'subagent_ended', workflow.state, workflow.state, `subagent ended with outcome: ${outcome}`, { outcome: mappedOutcome });
+                }
+                store.dispose();
+                return;
+            }
+            store.dispose();
+        } catch (e) {
+            logger.warn(`[PD:Subagent] Failed to notify helper workflow lifecycle: ${String(e)}`);
+        }
+    }
+
+    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',
+        });
+    }
+
+    // ── End of subagent_ended handling ──
+    // Note: Diagnostician runs via HEARTBEAT (main session LLM), not as a subagent.
+    // Principle creation happens in evolution-worker.ts marker detection path.
+}

package/src/hooks/thinking-checkpoint.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 type { PluginHookBeforeToolCallEvent, PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
+import { 
+  THINKING_CHECKPOINT_WINDOW_MS,
+  THINKING_CHECKPOINT_DEFAULT_HIGH_RISK_TOOLS 
+} from '../config/index.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 function checkThinkingCheckpoint(
+  event: PluginHookBeforeToolCallEvent,
+  config: ThinkingCheckpointConfig,
+  sessionId: string | undefined,
+  logger?: { info?: (message: string) => void }
+): PluginHookBeforeToolCallResult | undefined {
+  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/src/hooks/trajectory-collector.ts

@@ -0,0 +1,290 @@
+/**
+ * Trajectory Collector - 行为进化引擎 Phase 0 数据收集
+ * 
+ * 收集工具调用和 LLM 输出到 memory/trajectories/ 目录
+ * 用于分析工具使用模式、识别原则应用案例、评估行为质量
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { 
+  PluginHookAfterToolCallEvent, 
+  PluginHookToolContext, 
+  PluginHookLlmOutputEvent, 
+  PluginHookAgentContext,
+  PluginHookBeforeMessageWriteEvent
+} from '../openclaw-sdk.js';
+
+const TRAJECTORY_DIR = 'memory/trajectories/';
+
+// 敏感字段匹配正则
+const SENSITIVE_KEY_PATTERN = /password|token|authorization|secret|api[_-]?key|credential|cookie|session/i;
+
+// 最大字符串长度
+const MAX_STRING_LENGTH = 1000;
+const MAX_RESULT_LENGTH = 500;
+
+/**
+ * 递归脱敏处理：遍历对象/数组，移除敏感字段值
+ */
+function scrubSensitive(obj: unknown, depth = 0): unknown {
+  // 防止无限递归
+  if (depth > 10) return '[MAX_DEPTH]';
+  
+  // 处理 null/undefined
+  if (obj == null) return obj;
+  
+  // 处理基本类型
+  if (typeof obj !== 'object') {
+    if (typeof obj === 'string' && obj.length > MAX_STRING_LENGTH) {
+      return obj.slice(0, MAX_STRING_LENGTH) + '...[truncated]';
+    }
+    return obj;
+  }
+  
+  // 处理数组
+  if (Array.isArray(obj)) {
+    return obj.map(item => scrubSensitive(item, depth + 1));
+  }
+  
+  // 处理对象
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    if (SENSITIVE_KEY_PATTERN.test(key)) {
+      result[key] = '[REDACTED]';
+    } else {
+      result[key] = scrubSensitive(value, depth + 1);
+    }
+  }
+  return result;
+}
+
+/**
+ * 异步写入队列 - 确保有序、非阻塞写入
+ */
+class AsyncWriteQueue {
+  private queue: Array<() => Promise<void>> = [];
+  private processing = false;
+  
+  async enqueue(task: () => Promise<void>): Promise<void> {
+    this.queue.push(task);
+    if (!this.processing) {
+      this.processNext();
+    }
+  }
+  
+  private async processNext(): Promise<void> {
+    if (this.queue.length === 0) {
+      this.processing = false;
+      return;
+    }
+    
+    this.processing = true;
+    const task = this.queue.shift();
+    
+    try {
+      await task!();
+    } catch {
+      // Silently fail - trajectory collection should not block main functionality
+    }
+    
+    // 处理下一个任务
+    this.processNext();
+  }
+}
+
+// 全局写入队列实例
+const writeQueue = new AsyncWriteQueue();
+
+// 目录缓存（避免重复检查）
+const dirCache = new Map<string, boolean>();
+
+/**
+ * 确保轨迹目录存在（异步）
+ */
+async function ensureTrajectoryDirAsync(workspaceDir: string): Promise<string> {
+  const dir = path.join(workspaceDir, TRAJECTORY_DIR);
+  
+  if (dirCache.get(dir)) {
+    return dir;
+  }
+  
+  try {
+    await fs.promises.mkdir(dir, { recursive: true });
+    dirCache.set(dir, true);
+  } catch {
+    // 目录可能已存在，忽略错误
+    dirCache.set(dir, true);
+  }
+  
+  return dir;
+}
+
+/**
+ * 获取今日轨迹文件名
+ */
+function getTodayFilename(): string {
+  const now = new Date();
+  const year = now.getUTCFullYear();
+  const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+  return `${year}-${month}-${String(now.getUTCDate()).padStart(2, '0')}.jsonl`;
+}
+
+/**
+ * 写入轨迹记录（JSON Lines 格式）- 异步版本
+ */
+function writeTrajectoryRecord(workspaceDir: string, record: object): void {
+  const line = JSON.stringify(record) + '\n';
+  
+  writeQueue.enqueue(async () => {
+    const dir = await ensureTrajectoryDirAsync(workspaceDir);
+    const filepath = path.join(dir, getTodayFilename());
+    await fs.promises.appendFile(filepath, line, 'utf8');
+  });
+}
+
+/**
+ * 工具调用完成后的处理
+ * 记录：工具名、参数、结果、错误、执行时间
+ */
+export function handleAfterToolCall(
+  event: PluginHookAfterToolCallEvent,
+  ctx: PluginHookToolContext & { workspaceDir?: string }
+): void {
+  const workspaceDir = ctx.workspaceDir;
+  if (!workspaceDir) return;
+
+  // 递归脱敏处理所有字段
+  const sanitizedParams = scrubSensitive(event.params);
+  const sanitizedResult = event.result == null 
+    ? null 
+    : String(scrubSensitive(event.result)).slice(0, MAX_RESULT_LENGTH);
+  const sanitizedError = event.error == null 
+    ? null 
+    : String(scrubSensitive(event.error));
+
+  writeTrajectoryRecord(workspaceDir, {
+    type: 'tool_call',
+    timestamp: new Date().toISOString(),
+    sessionId: ctx.sessionId || 'unknown',
+    toolName: event.toolName,
+    params: sanitizedParams,
+    result: sanitizedResult,
+    error: sanitizedError,
+    durationMs: event.durationMs,
+    success: !event.error,
+    runId: event.runId || null,
+    toolCallId: event.toolCallId || null
+  });
+}
+
+/**
+ * LLM 输出处理
+ * 记录：provider、model、输出长度、token 使用量
+ */
+export function handleLlmOutput(
+  event: PluginHookLlmOutputEvent,
+  ctx: PluginHookAgentContext & { workspaceDir?: string }
+): void {
+  const workspaceDir = ctx.workspaceDir;
+  if (!workspaceDir) return;
+
+  const totalTextLength = event.assistantTexts?.reduce((sum, text) => sum + (text?.length || 0), 0) || 0;
+
+  writeTrajectoryRecord(workspaceDir, {
+    type: 'llm_output',
+    timestamp: new Date().toISOString(),
+    sessionId: ctx.sessionId || 'unknown',
+    provider: event.provider,
+    model: event.model,
+    textLength: totalTextLength,
+    outputCount: event.assistantTexts?.length || 0,
+    usage: event.usage ? scrubSensitive(event.usage) : null
+  });
+}
+
+/**
+ * 消息写入前的处理
+ * 记录：用户/助手消息内容
+ */
+export function handleBeforeMessageWrite(
+  event: PluginHookBeforeMessageWriteEvent,
+  ctx: PluginHookAgentContext & { workspaceDir?: string }
+): void {
+  const workspaceDir = ctx.workspaceDir;
+  if (!workspaceDir) return;
+
+  const msg = event.message;
+  if (!msg || !msg.role) return;
+
+  // 只记录 user 和 assistant 消息
+  if (msg.role !== 'user' && msg.role !== 'assistant') return;
+
+  // 提取文本内容
+  let content = '';
+  if (typeof msg.content === 'string') {
+    content = msg.content;
+  } else if (Array.isArray(msg.content)) {
+    content = msg.content
+      .filter((part: any) => part?.type === 'text')
+      .map((part: any) => part.text)
+      .join('\n');
+  }
+
+  // 脱敏处理内容预览
+  const sanitizedPreview = scrubSensitive(content.slice(0, 200));
+
+  writeTrajectoryRecord(workspaceDir, {
+    type: 'message',
+    timestamp: new Date().toISOString(),
+    sessionId: event.sessionKey || 'unknown',
+    role: msg.role,
+    contentLength: content.length,
+    contentPreview: typeof sanitizedPreview === 'string' ? sanitizedPreview : '[sanitized]',
+    agentId: event.agentId || null
+  });
+}
+
+/**
+ * 脱敏处理：移除敏感参数（保留旧函数签名以兼容）
+ * @deprecated 使用 scrubSensitive 替代
+ */
+function sanitizeParams(params: Record<string, any>): Record<string, any> {
+  return scrubSensitive(params) as Record<string, any>;
+}
+
+/**
+ * 轨迹汇总统计（供 cron 任务调用）
+ */
+export function computeTrajectoryStats(workspaceDir: string): object {
+  const dir = path.join(workspaceDir, TRAJECTORY_DIR);
+  const todayFile = path.join(dir, getTodayFilename());
+  
+  if (!fs.existsSync(todayFile)) {
+    return { date: getTodayFilename(), totalRecords: 0, toolCalls: 0, llmOutputs: 0, messages: 0 };
+  }
+
+  const content = fs.readFileSync(todayFile, 'utf8');
+  const lines = content.split('\n').filter(line => line.trim());
+  
+  const toolCalls = lines.filter(line => {
+    try { return JSON.parse(line).type === 'tool_call'; } catch { return false; }
+  }).length;
+  
+  const llmOutputs = lines.filter(line => {
+    try { return JSON.parse(line).type === 'llm_output'; } catch { return false; }
+  }).length;
+  
+  const messages = lines.filter(line => {
+    try { return JSON.parse(line).type === 'message'; } catch { return false; }
+  }).length;
+
+  return {
+    date: getTodayFilename(),
+    totalRecords: lines.length,
+    toolCalls,
+    llmOutputs,
+    messages,
+    generatedAt: new Date().toISOString()
+  };
+}