@cleocode/core 2026.3.68 → 2026.3.70

package/src/agents/retry.ts

@@ -158,32 +158,38 @@ export async function withRetry<T>(
   policy?: Partial<RetryPolicy>,
 ): Promise<RetryResult<T>> {
   const effectivePolicy = createRetryPolicy(policy);
-  const { withRetry: coreRetry } = await import('../lib/retry.js');
   let attemptCount = 0;
-  try {
-    const value = await coreRetry(
-      async () => {
-        attemptCount++;
-        return fn();
-      },
-      {
-        maxAttempts: effectivePolicy.maxRetries + 1,
-        baseDelayMs: effectivePolicy.baseDelayMs,
-        maxDelayMs: effectivePolicy.maxDelayMs,
-        retryableErrors: [(err: unknown) => shouldRetry(err, attemptCount - 1, effectivePolicy)],
-      },
-    );
-    return { success: true, value, attempts: attemptCount, totalDelayMs: 0 };
-  } catch (err) {
-    const error = err instanceof Error ? err : new Error(String(err));
-    const context = err as Partial<{ totalDelayMs: number }>;
-    return {
-      success: false,
-      error,
-      attempts: attemptCount,
-      totalDelayMs: context.totalDelayMs ?? 0,
-    };
+  let totalDelayMs = 0;
+
+  const maxAttempts = effectivePolicy.maxRetries + 1;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      attemptCount++;
+      const value = await fn();
+      return { success: true, value, attempts: attemptCount, totalDelayMs };
+    } catch (err) {
+      lastError = err;
+      const isLastAttempt = attempt === maxAttempts - 1;
+      if (isLastAttempt) break;
+
+      if (!shouldRetry(err, attempt, effectivePolicy)) break;
+
+      const delay = calculateDelay(attempt, effectivePolicy);
+      totalDelayMs += delay;
+      await new Promise<void>((resolve) => setTimeout(resolve, delay));
+    }
   }
+
+  const error = lastError instanceof Error ? lastError : new Error(String(lastError));
+  return {
+    success: false,
+    error,
+    attempts: attemptCount,
+    totalDelayMs,
+  };
 }
 
 // ============================================================================

package/src/config.ts

@@ -79,6 +79,24 @@ const DEFAULTS: CleoConfig = {
     agentPrefix: 'cleo-',
     privacyTier: 'private',
   },
+  brain: {
+    autoCapture: true,
+    captureFiles: false,
+    captureMcp: false,
+    captureWork: false,
+    embedding: {
+      enabled: true,
+      provider: 'local' as const,
+    },
+    memoryBridge: {
+      autoRefresh: true,
+      contextAware: true,
+      maxTokens: 2000,
+    },
+    summarization: {
+      enabled: true,
+    },
+  },
 };
 
 /** Environment variable to config path mapping. */

package/src/hooks/handlers/file-hooks.ts

@@ -5,7 +5,9 @@
  * Includes 5-second dedup and path-based filtering to avoid noisy writes.
  * Auto-registers on module load.
  *
- * Disabled by default. Set CLEO_BRAIN_CAPTURE_FILES=true to enable.
+ * Disabled by default. Enable via:
+ *   - Config: brain.captureFiles = true  (checked first)
+ *   - Env:    CLEO_BRAIN_CAPTURE_FILES=true  (overrides config)
  */
 
 import { isAbsolute, relative } from 'node:path';
@@ -39,10 +41,34 @@ function shouldSkipPath(relativePath: string): boolean {
   return SKIP_PATTERNS.some((pattern) => pattern.test(relativePath));
 }
 
+/**
+ * Check whether file-change capture is enabled.
+ *
+ * Resolution order (first truthy wins):
+ *   1. CLEO_BRAIN_CAPTURE_FILES env var (explicit override)
+ *   2. brain.captureFiles project config value
+ *
+ * Defaults to false when neither is set.
+ */
+async function isFileCaptureEnabled(projectRoot: string): Promise<boolean> {
+  const envOverride = process.env['CLEO_BRAIN_CAPTURE_FILES'];
+  if (envOverride !== undefined) {
+    return envOverride === 'true';
+  }
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    return config.brain?.captureFiles ?? false;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Handle onFileChange - capture file changes to BRAIN
  *
- * Gated behind CLEO_BRAIN_CAPTURE_FILES=true env var.
+ * Gated behind brain.captureFiles config or CLEO_BRAIN_CAPTURE_FILES env var.
+ * Env var takes precedence over config for backward compatibility.
  * Deduplicates rapid writes to the same file within a 5-second window.
  * Filters out .cleo/ internal files and test temp directories.
  * Converts absolute paths to project-relative paths.
@@ -52,7 +78,7 @@ export async function handleFileChange(
   payload: OnFileChangePayload,
 ): Promise<void> {
   // Opt-in gate: disabled by default to prevent observation noise
-  if (process.env['CLEO_BRAIN_CAPTURE_FILES'] !== 'true') return;
+  if (!(await isFileCaptureEnabled(projectRoot))) return;
 
   // 5-second dedup
   const now = Date.now();

package/src/hooks/handlers/index.ts

@@ -11,6 +11,7 @@ import './task-hooks.js';
 import './error-hooks.js';
 import './file-hooks.js';
 import './mcp-hooks.js';
+import './work-capture-hooks.js';
 
 export { handleError } from './error-hooks.js';
 export { handleFileChange } from './file-hooks.js';
@@ -18,3 +19,4 @@ export { handlePromptSubmit, handleResponseComplete } from './mcp-hooks.js';
 // Re-export handler functions for explicit use
 export { handleSessionEnd, handleSessionStart } from './session-hooks.js';
 export { handleToolComplete, handleToolStart } from './task-hooks.js';
+export { handleWorkPromptSubmit, handleWorkResponseComplete } from './work-capture-hooks.js';

package/src/hooks/handlers/mcp-hooks.ts

@@ -1,9 +1,11 @@
 /**
  * MCP Prompt/Response Hook Handlers - Wave 2 of T5237
  *
- * Handlers for onPromptSubmit and onResponseComplete events.
- * By default, NO brain capture (too noisy). Brain observation is
- * opt-in via CLEO_BRAIN_CAPTURE_MCP=true environment variable.
+ * Handlers for onPromptSubmit and onResponseComplete events that capture
+ * ALL gateway operations (read and write) to BRAIN.
+ * By default, NO brain capture (too noisy). Enable via:
+ *   - Config: brain.captureMcp = true  (checked first)
+ *   - Env:    CLEO_BRAIN_CAPTURE_MCP=true  (overrides config)
  * Auto-registers on module load.
  */
 
@@ -17,23 +19,39 @@ function isMissingBrainSchemaError(err: unknown): boolean {
 }
 
 /**
- * Check if brain capture is enabled for MCP events.
- * Defaults to false (too noisy for normal operation).
+ * Check whether MCP-level brain capture is enabled.
+ *
+ * Resolution order (first truthy wins):
+ *   1. CLEO_BRAIN_CAPTURE_MCP env var (explicit override)
+ *   2. brain.captureMcp project config value
+ *
+ * Defaults to false when neither is set (too noisy for normal operation).
  */
-function isBrainCaptureEnabled(): boolean {
-  return process.env['CLEO_BRAIN_CAPTURE_MCP'] === 'true';
+async function isBrainCaptureEnabled(projectRoot: string): Promise<boolean> {
+  const envOverride = process.env['CLEO_BRAIN_CAPTURE_MCP'];
+  if (envOverride !== undefined) {
+    return envOverride === 'true';
+  }
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    return config.brain?.captureMcp ?? false;
+  } catch {
+    return false;
+  }
 }
 
 /**
- * Handle onPromptSubmit - optionally capture prompt events to BRAIN
+ * Handle onPromptSubmit - optionally capture ALL gateway prompt events to BRAIN.
  *
- * No-op by default. Set CLEO_BRAIN_CAPTURE_MCP=true to enable.
+ * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
+ * For selective mutation-only capture, use work-capture-hooks.ts instead.
  */
 export async function handlePromptSubmit(
   projectRoot: string,
   payload: OnPromptSubmitPayload,
 ): Promise<void> {
-  if (!isBrainCaptureEnabled()) return;
+  if (!(await isBrainCaptureEnabled(projectRoot))) return;
 
   const { observeBrain } = await import('../../memory/brain-retrieval.js');
 
@@ -50,15 +68,16 @@ export async function handlePromptSubmit(
 }
 
 /**
- * Handle onResponseComplete - optionally capture response events to BRAIN
+ * Handle onResponseComplete - optionally capture ALL gateway response events to BRAIN.
  *
- * No-op by default. Set CLEO_BRAIN_CAPTURE_MCP=true to enable.
+ * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
+ * For selective mutation-only capture, use work-capture-hooks.ts instead.
  */
 export async function handleResponseComplete(
   projectRoot: string,
   payload: OnResponseCompletePayload,
 ): Promise<void> {
-  if (!isBrainCaptureEnabled()) return;
+  if (!(await isBrainCaptureEnabled(projectRoot))) return;
 
   const { observeBrain } = await import('../../memory/brain-retrieval.js');
 

package/src/hooks/handlers/memory-bridge-refresh.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared memory bridge refresh helper for hook handlers.
+ *
+ * Provides a config-gated, debounced wrapper around refreshMemoryBridge().
+ * Prevents rapid regeneration of .cleo/memory-bridge.md when multiple
+ * lifecycle events fire in quick succession (e.g. session end + task complete).
+ *
+ * Debounce: max one refresh per 30 seconds across all callers in the process.
+ *
+ * @task T138
+ * @epic T134
+ */
+
+/** Debounce window in milliseconds. */
+const DEBOUNCE_MS = 30_000;
+
+/** Timestamp of the last successful refresh call (module-level singleton). */
+let lastRefreshTime = 0;
+
+/**
+ * Refresh the memory bridge if autoRefresh is enabled and the debounce window
+ * has elapsed. Reads config via loadConfig() (cascaded). Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+export async function maybeRefreshMemoryBridge(projectRoot: string): Promise<void> {
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+
+    if (!config.brain?.memoryBridge?.autoRefresh) {
+      return;
+    }
+
+    const now = Date.now();
+    if (now - lastRefreshTime < DEBOUNCE_MS) {
+      return;
+    }
+
+    lastRefreshTime = now;
+
+    const { refreshMemoryBridge } = await import('../../memory/memory-bridge.js');
+    await refreshMemoryBridge(projectRoot);
+  } catch {
+    // Best-effort: never block lifecycle events
+  }
+}

package/src/hooks/handlers/session-hooks.ts

@@ -3,10 +3,15 @@
  *
  * Handlers that capture session lifecycle events to BRAIN via memory.observe.
  * Auto-registers on module load.
+ *
+ * T138: Triggers memory bridge refresh on session start and end.
+ * T139: Regenerates bridge with session scope on start.
+ * T144: Extracts transcript observations on session end.
  */
 
 import { hooks } from '../registry.js';
 import type { OnSessionEndPayload, OnSessionStartPayload } from '../types.js';
+import { maybeRefreshMemoryBridge } from './memory-bridge-refresh.js';
 
 function isMissingBrainSchemaError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
@@ -16,6 +21,9 @@ function isMissingBrainSchemaError(err: unknown): boolean {
 
 /**
  * Handle onSessionStart - capture initial session context
+ *
+ * T138: Refresh memory bridge on session start.
+ * T139: Regenerate bridge with session scope context.
  */
 export async function handleSessionStart(
   projectRoot: string,
@@ -34,10 +42,16 @@ export async function handleSessionStart(
   } catch (err) {
     if (!isMissingBrainSchemaError(err)) throw err;
   }
+
+  // T138/T139: Refresh memory bridge after session starts (best-effort)
+  await maybeRefreshMemoryBridge(projectRoot);
 }
 
 /**
  * Handle onSessionEnd - capture session summary
+ *
+ * T138: Refresh memory bridge after session ends.
+ * T144: Extract transcript observations via cross-provider adapter.
  */
 export async function handleSessionEnd(
   projectRoot: string,
@@ -64,6 +78,30 @@ export async function handleSessionEnd(
   } catch {
     // Grading must never block session end
   }
+
+  // T144: Cross-provider transcript extraction (best-effort)
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    if (config.brain?.autoCapture) {
+      const { AdapterManager } = await import('../../adapters/index.js');
+      const manager = AdapterManager.getInstance(projectRoot);
+      const activeAdapter = manager.getActive();
+      const hookProvider = activeAdapter?.hooks;
+      if (hookProvider && typeof hookProvider.getTranscript === 'function') {
+        const transcript = await hookProvider.getTranscript(payload.sessionId, projectRoot);
+        if (transcript) {
+          const { extractFromTranscript } = await import('../../memory/auto-extract.js');
+          await extractFromTranscript(projectRoot, payload.sessionId, transcript);
+        }
+      }
+    }
+  } catch {
+    // Graceful no-op: transcript extraction must never block session end
+  }
+
+  // T138: Refresh memory bridge after session ends (best-effort)
+  await maybeRefreshMemoryBridge(projectRoot);
 }
 
 // Register handlers on module load

package/src/hooks/handlers/task-hooks.ts

@@ -3,10 +3,13 @@
  *
  * Handlers that capture task lifecycle events to BRAIN via memory.observe.
  * Auto-registers on module load.
+ *
+ * T138: Triggers memory bridge refresh after task completion.
  */
 
 import { hooks } from '../registry.js';
 import type { OnToolCompletePayload, OnToolStartPayload } from '../types.js';
+import { maybeRefreshMemoryBridge } from './memory-bridge-refresh.js';
 
 function isMissingBrainSchemaError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
@@ -37,6 +40,8 @@ export async function handleToolStart(
 
 /**
  * Handle onToolComplete (maps to task.complete in CLEO)
+ *
+ * T138: Refresh memory bridge after task completion.
  */
 export async function handleToolComplete(
   projectRoot: string,
@@ -54,6 +59,9 @@ export async function handleToolComplete(
   } catch (err) {
     if (!isMissingBrainSchemaError(err)) throw err;
   }
+
+  // T138: Refresh memory bridge after task completes (best-effort)
+  await maybeRefreshMemoryBridge(projectRoot);
 }
 
 // Register handlers