principles-disciple 1.136.0 → 1.138.0

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

@@ -1,9 +1,23 @@
 /**
  * Trajectory Collector - message write trajectory recording
  *
- * Records message data to memory/trajectories/ JSONL files.
- * PRI-347 removed tool_call and llm_output JSONL writers (no consumers).
- * PRI-346 will repurpose handleBeforeMessageWrite for SQLite collection.
+ * Fallback trajectory collection when llm_output is blocked by missing
+ * allowConversationAccess. before_message_write is NOT in
+ * CONVERSATION_HOOK_NAMES so OpenClaw always delivers it.
+ *
+ * SQLite writes are enqueued to an async queue because before_message_write is
+ * a SYNCHRONOUS OpenClaw hook — the handler must return immediately. better-sqlite3
+ * is synchronous, so calling it directly would block the message-write main path.
+ * Trade-off: in degradation mode the last few queued writes may be lost on
+ * process exit; this is acceptable because degradation mode is already caused
+ * by a config problem (missing allowConversationAccess), and the primary
+ * llm_output path is authoritative when authorized.
+ *
+ * JSONL writing was removed (no consumers — verified zero readers across the
+ * codebase; PRI-347 already removed tool_call/llm_output JSONL writers).
+ *
+ * ERR-002: fallback errors are logged, never silent.
+ * ERR-001/005: content is sanitized before persisting.
  */
 import type { PluginHookAgentContext, PluginHookBeforeMessageWriteEvent } from '../openclaw-sdk.js';
 /**
@@ -14,7 +28,9 @@ import type { PluginHookAgentContext, PluginHookBeforeMessageWriteEvent } from '
  * CONVERSATION_HOOK_NAMES, so it always fires — making it the natural fallback.
  *
  * De-duplication: only writes to SQLite when llm_output is blocked (unauthorized).
- * When llm_output is working (authorized), this hook degrades to JSONL-only.
+ * When llm_output is working (authorized), this hook is a no-op.
+ *
+ * SQLite writes are async-queued (see file header) to avoid blocking the sync hook.
  *
  * ERR-002: structured observability when fallback fires.
  * ERR-001/005: content is sanitized before persisting.

package/dist/hooks/trajectory-collector.js

@@ -1,127 +1,79 @@
 /**
  * Trajectory Collector - message write trajectory recording
  *
- * Records message data to memory/trajectories/ JSONL files.
- * PRI-347 removed tool_call and llm_output JSONL writers (no consumers).
- * PRI-346 will repurpose handleBeforeMessageWrite for SQLite collection.
+ * Fallback trajectory collection when llm_output is blocked by missing
+ * allowConversationAccess. before_message_write is NOT in
+ * CONVERSATION_HOOK_NAMES so OpenClaw always delivers it.
+ *
+ * SQLite writes are enqueued to an async queue because before_message_write is
+ * a SYNCHRONOUS OpenClaw hook — the handler must return immediately. better-sqlite3
+ * is synchronous, so calling it directly would block the message-write main path.
+ * Trade-off: in degradation mode the last few queued writes may be lost on
+ * process exit; this is acceptable because degradation mode is already caused
+ * by a config problem (missing allowConversationAccess), and the primary
+ * llm_output path is authoritative when authorized.
+ *
+ * JSONL writing was removed (no consumers — verified zero readers across the
+ * codebase; PRI-347 already removed tool_call/llm_output JSONL writers).
+ *
+ * ERR-002: fallback errors are logged, never silent.
+ * ERR-001/005: content is sanitized before persisting.
  */
-import * as fs from 'fs';
-import * as path from 'path';
 import { MAX_STRING_LENGTH } from '../config/defaults/runtime.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { SystemLogger } from '../core/system-logger.js';
 import { sanitizeForEvidence } from './message-sanitize.js';
 import { checkConversationAccessConfig } from '../core/config-health.js';
-const TRAJECTORY_DIR = 'memory/trajectories/';
-// 敏感字段匹配正则
-const SENSITIVE_KEY_PATTERN = /password|token|authorization|secret|api[_-]?key|credential|cookie|session/i;
-/**
- * 递归脱敏处理：遍历对象/数组，移除敏感字段值
- */
-function scrubSensitive(obj, depth = 0) {
-    // 防止无限递归
-    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 = {};
-    for (const [key, value] of Object.entries(obj)) {
-        if (SENSITIVE_KEY_PATTERN.test(key)) {
-            result[key] = '[REDACTED]';
-        }
-        else {
-            result[key] = scrubSensitive(value, depth + 1);
-        }
-    }
-    return result;
-}
 /**
- * 异步写入队列 - 确保有序、非阻塞写入
+ * Async write queue — ensures ordered, non-blocking execution of SQLite writes.
+ * before_message_write is a sync hook; SQLite I/O must not block it.
+ *
+ * Tasks are deferred to the microtask queue via `queueMicrotask` so the sync
+ * hook handler returns before any synchronous better-sqlite3 work runs.
  */
 class AsyncWriteQueue {
     queue = [];
     processing = false;
-    async enqueue(task) {
+    enqueue(task) {
         this.queue.push(task);
         if (!this.processing) {
-            this.processNext();
+            this.processing = true;
+            queueMicrotask(() => { void this.processNext(); });
         }
     }
     async processNext() {
-        if (this.queue.length === 0) {
-            this.processing = false;
-            return;
-        }
-        this.processing = true;
-        const task = this.queue.shift();
-        if (!task) {
-            this.processing = false;
-            return;
+        while (this.queue.length > 0) {
+            const task = this.queue.shift();
+            if (!task)
+                break;
+            try {
+                await task();
+            }
+            catch (err) {
+                // EP-03/ERR-002: safety net — tasks should catch their own errors with
+                // structured logging. This catches bugs where a task's try/catch is
+                // missing or re-throws. Never silently swallow (ERR-002).
+                console.warn('[PD:trajectory-queue] uncaught task error:', err);
+            }
         }
-        try {
-            await task();
-        }
-        catch {
-            // Silently fail - trajectory collection should not block main functionality
-        }
-        // 处理下一个任务
-        this.processNext();
+        this.processing = false;
     }
 }
-// 全局写入队列实例
 const writeQueue = new AsyncWriteQueue();
-// 目录缓存（避免重复检查）
-const dirCache = new Map();
 /**
- * 确保轨迹目录存在（异步）
+ * Extract text content from a message (string or content-part array).
  */
-async function ensureTrajectoryDirAsync(workspaceDir) {
-    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);
+function extractContent(content) {
+    if (typeof content === 'string') {
+        return content;
     }
-    catch {
-        // 目录可能已存在，忽略错误
-        dirCache.set(dir, true);
+    if (Array.isArray(content)) {
+        return content
+            .filter((part) => part && typeof part === 'object' && part.type === 'text')
+            .map((part) => part.text)
+            .join('\n');
     }
-    return dir;
-}
-/**
- * 获取今日轨迹文件名
- */
-function getTodayFilename() {
-    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, record) {
-    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');
-    });
+    return '';
 }
 /**
  * PRI-346: Message write hook with SQLite fallback trajectory recording.
@@ -131,7 +83,9 @@ function writeTrajectoryRecord(workspaceDir, record) {
  * CONVERSATION_HOOK_NAMES, so it always fires — making it the natural fallback.
  *
  * De-duplication: only writes to SQLite when llm_output is blocked (unauthorized).
- * When llm_output is working (authorized), this hook degrades to JSONL-only.
+ * When llm_output is working (authorized), this hook is a no-op.
+ *
+ * SQLite writes are async-queued (see file header) to avoid blocking the sync hook.
  *
  * ERR-002: structured observability when fallback fires.
  * ERR-001/005: content is sanitized before persisting.
@@ -146,73 +100,58 @@ export function handleBeforeMessageWrite(event, ctx) {
     // Only record user and assistant messages
     if (msg.role !== 'user' && msg.role !== 'assistant')
         return;
-    // Extract text content (consistent with existing implementation)
-    let content = '';
-    if (typeof msg.content === 'string') {
-        content = msg.content;
-    }
-    else if (Array.isArray(msg.content)) {
-        content = msg.content
-            .filter((part) => part && typeof part === 'object' && part.type === 'text')
-            .map((part) => part.text)
-            .join('\n');
-    }
-    // Sanitize content preview for JSONL
-    const sanitizedPreview = scrubSensitive(content.slice(0, 200));
-    // Existing JSONL write (always, for backward compatibility)
-    writeTrajectoryRecord(workspaceDir, {
-        type: 'message',
-        timestamp: new Date().toISOString(),
-        sessionId: event.sessionKey || event.sessionId || 'unknown',
-        role: msg.role,
-        contentLength: content.length,
-        contentPreview: typeof sanitizedPreview === 'string' ? sanitizedPreview : '[sanitized]',
-        agentId: event.agentId || null,
-        fallback: 'before_message_write',
-    });
     // ── SQLite fallback (PRI-346): only when conversation hooks are blocked ──
     const accessCheck = checkConversationAccessConfig(ctx.pluginConfig);
     if (accessCheck.authorized) {
         // llm_output is working — do NOT duplicate write to SQLite (de-dup, case D)
         return;
     }
-    // Conversation hooks blocked — this hook is the fallback trajectory writer
+    // Conversation hooks blocked — this hook is the fallback trajectory writer.
+    // Enqueue SQLite writes to avoid blocking the sync before_message_write hook.
+    const logger = ctx.logger;
+    const content = extractContent(msg.content);
+    const sessionId = event.sessionKey ?? ctx.sessionId ?? 'unknown';
+    const createdAt = new Date().toISOString();
     if (msg.role === 'assistant') {
-        try {
-            const wctx = WorkspaceContext.fromHookContext({ workspaceDir, logger: ctx.logger });
-            const sanitized = sanitizeForEvidence(content.slice(0, MAX_STRING_LENGTH), workspaceDir);
-            const sessionId = event.sessionKey ?? ctx.sessionId ?? 'unknown';
-            wctx.trajectory?.recordAssistantTurn?.({
-                sessionId,
-                runId: 'before_message_write_fallback',
-                provider: 'unknown',
-                model: 'unknown',
-                rawText: content,
-                sanitizedText: sanitized,
-                usageJson: {},
-                empathySignalJson: { detected: false, severity: 'mild', confidence: 1 },
-                createdAt: new Date().toISOString(),
-            });
-        }
-        catch (err) {
-            ctx.logger?.warn?.(`[PD:before_message_write] SQLite fallback write failed: ${String(err)}`);
-        }
+        writeQueue.enqueue(async () => {
+            try {
+                const wctx = WorkspaceContext.fromHookContext({ workspaceDir, logger });
+                const sanitized = sanitizeForEvidence(content.slice(0, MAX_STRING_LENGTH), workspaceDir);
+                wctx.trajectory?.recordAssistantTurn?.({
+                    sessionId,
+                    runId: 'before_message_write_fallback',
+                    provider: 'unknown',
+                    model: 'unknown',
+                    rawText: content,
+                    sanitizedText: sanitized,
+                    usageJson: {},
+                    empathySignalJson: { detected: false, severity: 'mild', confidence: 1 },
+                    createdAt,
+                });
+            }
+            catch (err) {
+                // EP-03/ERR-002: observable degradation, never silent
+                logger?.warn?.(`[PD:before_message_write] SQLite fallback write failed: ${String(err)}`);
+            }
+        });
     }
     else if (msg.role === 'user') {
-        try {
-            const wctx = WorkspaceContext.fromHookContext({ workspaceDir, logger: ctx.logger });
-            const sessionId = event.sessionKey ?? ctx.sessionId ?? 'unknown';
-            wctx.trajectory?.recordUserTurn?.({
-                sessionId,
-                turnIndex: 0,
-                rawText: content.slice(0, MAX_STRING_LENGTH),
-                correctionDetected: false,
-                createdAt: new Date().toISOString(),
-            });
-        }
-        catch (err) {
-            ctx.logger?.warn?.(`[PD:before_message_write] SQLite user turn fallback failed: ${String(err)}`);
-        }
+        writeQueue.enqueue(async () => {
+            try {
+                const wctx = WorkspaceContext.fromHookContext({ workspaceDir, logger });
+                wctx.trajectory?.recordUserTurn?.({
+                    sessionId,
+                    turnIndex: 0,
+                    rawText: content.slice(0, MAX_STRING_LENGTH),
+                    correctionDetected: false,
+                    createdAt,
+                });
+            }
+            catch (err) {
+                // EP-03/ERR-002: observable degradation, never silent
+                logger?.warn?.(`[PD:before_message_write] SQLite user turn fallback failed: ${String(err)}`);
+            }
+        });
     }
     // ERR-002: Structured observability — no silent fallback
     SystemLogger.log(workspaceDir, 'CONVERSATION_HOOK_BLOCKED', JSON.stringify({

package/dist/index.js

@@ -266,6 +266,9 @@ const plugin = {
             }
         }));
         // ── Hook: Pain & Trust ──
+        // timeoutMs=10s: OpenClaw has no default timeout for after_tool_call; without
+        // this a stuck SQLite write (busy_timeout=5000ms) leaks the handler promise.
+        // 10s gives 2x headroom over busy_timeout. fail-open means agent is unaffected.
         api.on('after_tool_call', guardHook('hook:after_tool_call', api.logger, (event, ctx) => {
             const wsResult = resolveHookWorkspaceDir(ctx, api, 'after_tool_call');
             if (!wsResult.ok) {
@@ -294,8 +297,10 @@ const plugin = {
                 }, { flushImmediately: true });
                 api.logger.error(`[PD:EmpathyObserver] Error in after_tool_call: ${String(err)}`);
             }
-        }));
+        }), { timeoutMs: 10_000 });
         // ── Hook: LLM Analysis ──
+        // timeoutMs=10s: OpenClaw has no default timeout for llm_output; without
+        // this a stuck SQLite write leaks the handler promise. See after_tool_call.
         api.on('llm_output', guardHook('hook:llm_output', api.logger, (event, ctx) => {
             const wsResult = resolveHookWorkspaceDir(ctx, api, 'llm_output');
             if (!wsResult.ok) {
@@ -325,7 +330,7 @@ const plugin = {
                 });
                 api.logger.error(`[PD] Error in llm_output: ${String(err)}`);
             }
-        }));
+        }), { timeoutMs: 10_000 });
         // ── Hook: Lifecycle ──
         api.on('before_reset', guardHook('hook:before_reset', api.logger, (event, ctx) => {
             const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_reset');

package/dist/openclaw-sdk.d.ts

@@ -151,7 +151,10 @@ export interface OpenClawPluginApi {
             text: (content: string, code?: number) => void;
         }) => boolean | Promise<boolean>;
     }) => void;
-    on: (event: string, handler: (...args: any[]) => unknown) => void;
+    on: (event: string, handler: (...args: any[]) => unknown, opts?: {
+        priority?: number;
+        timeoutMs?: number;
+    }) => void;
 }
 export interface PluginHookBeforePromptBuildEvent {
     agentId?: string;

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.136.0",
+  "version": "1.138.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.136.0",
+  "version": "1.138.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",