principles-disciple 1.100.0 → 1.101.0

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.100.0",
+  "version": "1.101.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/src/core/config-health.ts

@@ -0,0 +1,58 @@
+/**
+ * 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).
+ */
+
+/** Keep in sync with @principles/core CONVERSATION_ACCESS_CONFIG_KEY */
+const CONVERSATION_ACCESS_CONFIG_KEY = 'allowConversationAccess' as const;
+
+export interface ConversationAccessCheckResult {
+  authorized: boolean;
+  reason?: string;
+  nextAction?: string;
+}
+
+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: unknown): ConversationAccessCheckResult {
+  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 as Record<string, unknown>;
+
+  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 as Record<string, unknown>;
+  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/src/hooks/trajectory-collector.ts

@@ -13,6 +13,10 @@ import type {
   PluginHookBeforeMessageWriteEvent
 } from '../openclaw-sdk.js';
 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/';
 
@@ -144,25 +148,32 @@ function writeTrajectoryRecord(workspaceDir: string, record: object): void {
 }
 
 /**
- * 消息写入前的处理
- * 记录：用户/助手消息内容
+ * PRI-346: Message write hook with SQLite fallback trajectory recording.
  *
- * PRI-346 will repurpose this to write to SQLite instead of JSONL.
+ * When allowConversationAccess is NOT set (unauthorized), llm_output is silently
+ * blocked by OpenClaw and trajectory.db has no data. This hook is NOT in
+ * 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.
+ *
+ * ERR-002: structured observability when fallback fires.
+ * ERR-001/005: content is sanitized before persisting.
  */
 export function handleBeforeMessageWrite(
   event: PluginHookBeforeMessageWriteEvent,
-  ctx: PluginHookAgentContext & { workspaceDir?: string }
+  ctx: PluginHookAgentContext & { workspaceDir?: string; pluginConfig?: unknown }
 ): void {
-  const {workspaceDir} = ctx;
+  const { workspaceDir } = ctx;
   if (!workspaceDir) return;
 
   const msg = event.message;
   if (!msg || !msg.role) return;
 
-  // 只记录 user 和 assistant 消息
+  // 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;
@@ -173,16 +184,70 @@ export function handleBeforeMessageWrite(
       .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 || 'unknown',
+    sessionId: event.sessionKey || event.sessionId || 'unknown',
     role: msg.role,
     contentLength: content.length,
     contentPreview: typeof sanitizedPreview === 'string' ? sanitizedPreview : '[sanitized]',
-    agentId: event.agentId || null
+    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
+  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 as string | undefined) ?? 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)}`);
+    }
+  } else if (msg.role === 'user') {
+    try {
+      const wctx = WorkspaceContext.fromHookContext({ workspaceDir, logger: ctx.logger });
+      const sessionId = (event.sessionKey as string | undefined) ?? 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)}`);
+    }
+  }
+
+  // ERR-002: Structured observability — no silent fallback
+  SystemLogger.log(workspaceDir, 'CONVERSATION_HOOK_BLOCKED', JSON.stringify({
+    reason: accessCheck.reason,
+    nextAction: accessCheck.nextAction,
+    hook: 'llm_output',
+    fallback: 'before_message_write',
+    role: msg.role,
+  }));
 }

package/src/index.ts

@@ -16,9 +16,13 @@ import type {
   PluginHookSubagentSpawningEvent,
   PluginHookSubagentSpawningResult,
   PluginHookSubagentContext,
+  PluginHookBeforeMessageWriteEvent,
 } from './openclaw-sdk.js';
 import * as path from 'path';
 import { loadFeatureFlagFromConfig } from './core/pd-config-loader.js';
+import { checkConversationAccessConfig } from './core/config-health.js';
+export { checkConversationAccessConfig } from './core/config-health.js';
+export type { ConversationAccessCheckResult } from './core/config-health.js';
 import { classifyTask } from './core/local-worker-routing.js';
 import { completeShadowObservation, recordShadowRouting } from './core/shadow-observation-registry.js';
 import { getCommandDescription } from './i18n/commands.js';
@@ -28,6 +32,7 @@ import { handleBeforeToolCall } from './hooks/gate.js';
 import { handleAfterToolCall } from './hooks/pain.js';
 import { handleBeforeReset, handleBeforeCompaction, handleAfterCompaction } from './hooks/lifecycle.js';
 import { handleLlmOutput } from './hooks/llm.js';
+import * as TrajectoryCollector from './hooks/trajectory-collector.js';
 import { handleSubagentEnded } from './hooks/subagent.js';
 import { handleInitStrategy } from './commands/strategy.js';
 import { handleBootstrapTools, handleResearchTools } from './commands/capabilities.js';
@@ -70,57 +75,8 @@ const startedWorkspaces = new Set<string>();
 const pendingShadowObservations = new Map<string, string>();
 
 // ── Conversation Access Health Check (PRI-343) ────────────────────────────
-// 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).
-
-/** Keep in sync with @principles/core CONVERSATION_ACCESS_CONFIG_KEY */
-const CONVERSATION_ACCESS_CONFIG_KEY = 'allowConversationAccess' as const;
-
-export interface ConversationAccessCheckResult {
-  authorized: boolean;
-  reason?: string;
-  nextAction?: string;
-}
-
-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: unknown): ConversationAccessCheckResult {
-  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 as Record<string, unknown>;
-
-  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 as Record<string, unknown>;
-  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 };
-}
+// Re-exported from core/config-health.ts for backward compatibility.
+// Implementation moved to avoid circular imports with trajectory-collector.ts.
 
 // ── Feature Flag Loader (plugin I/O boundary) ─────────────────────────────
 // Reads workspace feature-flags.yaml and checks a specific flag.
@@ -567,6 +523,31 @@ const plugin = {
       return handleAfterCompaction(event, { ...ctx, workspaceDir: wsResult.workspaceDir });
     }));
 
+    // ── Hook: Before Message Write (PRI-346) ──
+    // Fallback trajectory collection when llm_output is blocked by
+    // missing allowConversationAccess. Not in CONVERSATION_HOOK_NAMES
+    // so OpenClaw always delivers it.
+    api.on(
+      'before_message_write',
+      guardHook('hook:before_message_write', api.logger, (event: PluginHookBeforeMessageWriteEvent, ctx: PluginHookAgentContext): void => {
+        const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_message_write');
+        if (!wsResult.ok) {
+          api.logger.warn(`[PD:before_message_write] workspaceDir resolution failed: ${wsResult.reason}`);
+          return;
+        }
+        try {
+          TrajectoryCollector.handleBeforeMessageWrite(event, {
+            ...ctx,
+            workspaceDir: wsResult.workspaceDir,
+            pluginConfig: api.pluginConfig,
+          });
+        } catch (err) {
+          // Non-critical: don't surface to user
+          api.logger.warn(`[PD:before_message_write] error: ${String(err)}`);
+        }
+      })
+    );
+
     // ── Service Registration (surface-guarded) ──
     // PRI-294: EvolutionWorker service registration removed — it starts via
     // before_prompt_build hook gate, not via api.registerService. The surface

package/tests/core-anti-growth.test.ts

@@ -125,6 +125,7 @@ describe('PRI-212 plugin core anti-growth guard', () => {
     'workspace-guidance-migrator.ts',
     'surface-guard.ts',
     'pd-config-loader.ts',
+    'config-health.ts',  // PRI-346: conversation access check extracted to avoid circular imports
   ] as const;
 
   // Category 6: Test files

package/tests/evolution-worker-slimming.test.ts

@@ -144,6 +144,7 @@ describe('PRI-294: Surface registry coverage audit', () => {
     'hook:before_reset',
     'hook:before_compaction',
     'hook:after_compaction',
+    'hook:before_message_write',  // PRI-346: SQLite fallback trajectory collection
     // Services registered via guardService
     'service:correction-observer',
     'service:trajectory',

package/tests/hooks/trajectory-collector.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Trajectory Collector — before_message_write hook tests (PRI-346)
+ *
+ * Cases A–F verify:
+ *  A: hook registration via api.on('before_message_write', ...)
+ *  B: assistant message → SQLite fallback when unauthorized
+ *  C: user message → user_turns; non-user/assistant → skip
+ *  D: authorized → no SQLite write (de-duplication)
+ *  E: CONVERSATION_HOOK_BLOCKED observability log
+ *  F: privacy / path redaction in sanitized text
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { OpenClawPluginApi, PluginHookBeforeMessageWriteEvent, PluginHookAgentContext } from '../../src/openclaw-sdk.js';
+
+// Mock heavy dependencies before importing the module under test
+const mockRecordAssistantTurn = vi.fn(() => 42);
+const mockRecordUserTurn = vi.fn(() => 1);
+
+vi.mock('../../src/core/workspace-context.js', () => {
+  return {
+    WorkspaceContext: {
+      fromHookContext: vi.fn(() => ({
+        trajectory: {
+          recordAssistantTurn: mockRecordAssistantTurn,
+          recordUserTurn: mockRecordUserTurn,
+        },
+        workspaceDir: '/mock/workspace',
+        stateDir: '/mock/workspace/.state',
+      })),
+    },
+  };
+});
+
+vi.mock('../../src/core/system-logger.js', () => ({
+  SystemLogger: {
+    log: vi.fn(),
+  },
+}));
+
+vi.mock('../../src/hooks/message-sanitize.js', () => ({
+  sanitizeForEvidence: vi.fn((text: string, _wsDir?: string) => {
+    // Simulate path redaction: replace C:\Users\... patterns
+    return text.replace(/C:\\Users\\[^\s]+/gi, '[PATH_REDACTED]');
+  }),
+}));
+
+// fs mock: prevent real file I/O from writeTrajectoryRecord
+vi.mock('fs', () => {
+  const memfs: Record<string, string> = {};
+  return {
+    existsSync: vi.fn(() => true),
+    mkdirSync: vi.fn(),
+    promises: {
+      mkdir: vi.fn(),
+      appendFile: vi.fn(async (filepath: string, data: string) => {
+        memfs[filepath] = (memfs[filepath] ?? '') + data;
+      }),
+    },
+    appendFile: vi.fn(),
+    __memfs: memfs,
+  };
+});
+
+import { handleBeforeMessageWrite } from '../../src/hooks/trajectory-collector.js';
+import { WorkspaceContext } from '../../src/core/workspace-context.js';
+import { SystemLogger } from '../../src/core/system-logger.js';
+import plugin from '../../src/index.js';
+
+function makeEvent(role: string, content: string | unknown[]): PluginHookBeforeMessageWriteEvent {
+  return {
+    message: { role, content },
+    sessionKey: 'sess-001',
+    sessionId: 'sess-001',
+    agentId: 'main',
+  };
+}
+
+const unauthorizedConfig = { hooks: { allowConversationAccess: false } };
+const authorizedConfig = { hooks: { allowConversationAccess: true } };
+
+function makeCtx(pluginConfig: unknown, workspaceDir: string | null = '/mock/workspace') {
+  return {
+    workspaceDir: workspaceDir === null ? undefined : workspaceDir,
+    pluginConfig,
+    sessionId: 'sess-001',
+    agentId: 'main',
+    logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+  } as PluginHookAgentContext & { workspaceDir?: string; pluginConfig?: unknown };
+}
+
+describe('PRI-346: before_message_write hook', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // ── Case A: hook registration ──────────────────────────────────────────────
+  describe('Case A — hook is registered', () => {
+    it('calls api.on with "before_message_write"', () => {
+      const onSpy = vi.fn();
+      const mockApi = {
+        rootDir: '/mock',
+        pluginConfig: { language: 'en' },
+        logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+        config: {},
+        registerCommand: vi.fn(),
+        registerService: vi.fn(),
+        registerTool: vi.fn(),
+        registerHttpRoute: vi.fn(),
+        on: onSpy,
+      } as unknown as OpenClawPluginApi;
+
+      plugin.register(mockApi);
+
+      const registeredEvents = onSpy.mock.calls.map((c: unknown[]) => c[0]);
+      expect(registeredEvents).toContain('before_message_write');
+    });
+  });
+
+  // ── Case B: assistant message → SQLite when unauthorized ───────────────────
+  describe('Case B — assistant message writes to SQLite when unauthorized', () => {
+    it('calls recordAssistantTurn once', () => {
+      const event = makeEvent('assistant', 'Hello, how can I help?');
+      const ctx = makeCtx(unauthorizedConfig);
+
+      handleBeforeMessageWrite(event, ctx);
+
+      expect(mockRecordAssistantTurn).toHaveBeenCalledTimes(1);
+      const call = mockRecordAssistantTurn.mock.calls[0][0];
+      expect(call.sessionId).toBe('sess-001');
+      expect(call.runId).toBe('before_message_write_fallback');
+      expect(call.provider).toBe('unknown');
+      expect(call.model).toBe('unknown');
+    });
+  });
+
+  // ── Case C: user → user_turns; tool → skip ─────────────────────────────────
+  describe('Case C — user message and non-user/assistant', () => {
+    it('calls recordUserTurn for role=user', () => {
+      const event = makeEvent('user', 'Fix this bug please');
+      const ctx = makeCtx(unauthorizedConfig);
+
+      handleBeforeMessageWrite(event, ctx);
+
+      expect(mockRecordUserTurn).toHaveBeenCalledTimes(1);
+      expect(mockRecordAssistantTurn).not.toHaveBeenCalled();
+    });
+
+    it('skips writing for role=tool', () => {
+      const event = makeEvent('tool', 'tool output here');
+      const ctx = makeCtx(unauthorizedConfig);
+
+      handleBeforeMessageWrite(event, ctx);
+
+      expect(mockRecordAssistantTurn).not.toHaveBeenCalled();
+      expect(mockRecordUserTurn).not.toHaveBeenCalled();
+    });
+
+    it('handles array content (multipart messages)', () => {
+      const content = [
+        { type: 'text', text: 'Part one' },
+        { type: 'image_url', url: 'http://example.com/img.png' },
+        { type: 'text', text: 'Part two' },
+      ];
+      const event = makeEvent('assistant', content);
+      const ctx = makeCtx(unauthorizedConfig);
+
+      handleBeforeMessageWrite(event, ctx);
+
+      expect(mockRecordAssistantTurn).toHaveBeenCalledTimes(1);
+      const call = mockRecordAssistantTurn.mock.calls[0][0];
+      expect(call.rawText).toContain('Part one');
+      expect(call.rawText).toContain('Part two');
+    });
+  });
+
+  // ── Case D: de-duplication (authorized → no SQLite) ────────────────────────
+  describe('Case D — authorized config skips SQLite (de-dup)', () => {
+    it('does NOT call recordAssistantTurn when authorized', () => {
+      const event = makeEvent('assistant', 'Normal response');
+      const ctx = makeCtx(authorizedConfig);
+
+      handleBeforeMessageWrite(event, ctx);
+
+      expect(mockRecordAssistantTurn).not.toHaveBeenCalled();
+      expect(mockRecordUserTurn).not.toHaveBeenCalled();
+    });
+
+    it('does NOT call SystemLogger.log when authorized', () => {
+      const event = makeEvent('assistant', 'Normal response');
+      const ctx = makeCtx(authorizedConfig);
+
+      handleBeforeMessageWrite(event, ctx);
+
+      expect(SystemLogger.log).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── Case E: CONVERSATION_HOOK_BLOCKED observability ─────────────────────────
+  describe('Case E — CONVERSATION_HOOK_BLOCKED logged when unauthorized', () => {
+    it('logs with reason + nextAction', () => {
+      const event = makeEvent('assistant', 'Some response');
+      const ctx = makeCtx(unauthorizedConfig);
+
+      handleBeforeMessageWrite(event, ctx);
+
+      expect(SystemLogger.log).toHaveBeenCalledWith(
+        '/mock/workspace',
+        'CONVERSATION_HOOK_BLOCKED',
+        expect.any(String),
+      );
+      const payload = JSON.parse(
+        (SystemLogger.log as ReturnType<typeof vi.fn>).mock.calls[0][2] as string
+      );
+      expect(payload.reason).toBeDefined();
+      expect(payload.nextAction).toBeDefined();
+      expect(payload.hook).toBe('llm_output');
+      expect(payload.fallback).toBe('before_message_write');
+      expect(payload.role).toBe('assistant');
+    });
+  });
+
+  // ── Case F: privacy / path redaction ────────────────────────────────────────
+  describe('Case F — sensitive path is redacted in sanitizedText', () => {
+    it('sanitizedText does not contain the raw path', () => {
+      const sensitiveContent = 'The file is at C:\\Users\\sensitive\\path\\secret.txt please check it';
+      const event = makeEvent('assistant', sensitiveContent);
+      const ctx = makeCtx(unauthorizedConfig);
+
+      handleBeforeMessageWrite(event, ctx);
+
+      expect(mockRecordAssistantTurn).toHaveBeenCalledTimes(1);
+      const call = mockRecordAssistantTurn.mock.calls[0][0];
+      expect(call.sanitizedText).not.toContain('C:\\Users\\sensitive\\path');
+    });
+  });
+
+  // ── Edge cases ─────────────────────────────────────────────────────────────
+  describe('Edge cases', () => {
+    it('returns early when workspaceDir is missing', () => {
+      mockRecordAssistantTurn.mockReset();
+      mockRecordUserTurn.mockReset();
+      const event = makeEvent('assistant', 'Hello');
+      const ctx = makeCtx(unauthorizedConfig, null);
+
+      // Should not throw
+      handleBeforeMessageWrite(event, ctx);
+      expect(mockRecordAssistantTurn).not.toHaveBeenCalled();
+    });
+
+    it('returns early when message is null/undefined', () => {
+      const event = { message: null as unknown as { role?: string }, sessionKey: 's' } as PluginHookBeforeMessageWriteEvent;
+      const ctx = makeCtx(unauthorizedConfig);
+
+      handleBeforeMessageWrite(event, ctx);
+      expect(mockRecordAssistantTurn).not.toHaveBeenCalled();
+    });
+
+    it('handles missing pluginConfig gracefully', () => {
+      const event = makeEvent('assistant', 'Hello');
+      const ctx = makeCtx(undefined);
+
+      handleBeforeMessageWrite(event, ctx);
+
+      // pluginConfig undefined → unauthorized → fallback fires
+      expect(mockRecordAssistantTurn).toHaveBeenCalledTimes(1);
+    });
+  });
+});