metainsight-context-engine 0.0.8 → 0.0.9

package/engine.ts

@@ -0,0 +1,259 @@
+/**
+ * Cloud Context Engine
+ *
+ * A lightweight ContextEngine implementation whose primary responsibilities are:
+ *   1. **Bootstrap** — Eagerly initialize COS and trigger initial local memory sync.
+ *   2. **Local Memory Sync** — Periodically sync local memory files (MEMORY.md,
+ *      daily logs, config) to cloud storage via `afterTurn`.
+ *
+ * All other ContextEngine lifecycle methods are no-ops / pass-throughs:
+ *   - `assemble` — pass-through (runtime handles history via `limitHistoryTurns`,
+ *     memory recall is handled by `before_prompt_build` hook in index.ts).
+ *   - `compact` — no-op (owns compaction flag to prevent legacy compactor).
+ *   - `ingest` / `ingestBatch` — no-ops.
+ *
+ * By setting `ownsCompaction: true`, the runtime will bypass the legacy
+ * `compactEmbeddedPiSessionDirect()` and delegate entirely to our `compact()`.
+ *
+ * The engine receives a `clientFactory` function that returns a `CosOperations`
+ * instance asynchronously — this allows lazy COS bootstrap (bucket/dataset/binding
+ * initialization happens on first use, not at plugin registration time).
+ */
+
+import type { AgentMessage } from '@mariozechner/pi-agent-core';
+import type {
+  AssembleResult,
+  BootstrapResult,
+  CompactResult,
+  ContextEngine,
+  ContextEngineInfo,
+  ContextEngineRuntimeContext,
+  IngestBatchResult,
+  IngestResult,
+} from 'openclaw/plugin-sdk/core';
+
+import type { CosOperations } from './cos-operations.js';
+import { syncLocalMemoryToCloud, type LocalMemorySyncConfig } from './local-memory-sync.js';
+
+// ============================================================================
+// Config
+// ============================================================================
+
+export interface CloudEngineConfig {
+  localMemorySync: LocalMemorySyncConfig;
+  /** When false, local memory files (MEMORY.md / daily logs) are NOT synced to cloud. Default: true */
+  localMemorySyncEnabled: boolean;
+}
+
+// ============================================================================
+// Logger (subset used by the engine)
+// ============================================================================
+
+interface Logger {
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Run local memory sync every N turns (to pick up file changes). */
+const LOCAL_MEMORY_SYNC_INTERVAL = 5;
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+export class CloudContextEngine implements ContextEngine {
+  readonly info: ContextEngineInfo = {
+    id: 'metainsight-context-engine',
+    name: 'MetaInsight Context Engine',
+    version: '1.0.0',
+    ownsCompaction: true,
+  };
+
+  private readonly clientFactory: () => Promise<CosOperations>;
+  private cachedClient: CosOperations | null = null;
+  private readonly config: CloudEngineConfig;
+  private readonly logger: Logger;
+  /** Counter for incremental local memory sync (every N turns). */
+  private turnsSinceLastSync = 0;
+
+  constructor(clientFactory: () => Promise<CosOperations>, config: CloudEngineConfig, logger: Logger) {
+    this.clientFactory = clientFactory;
+    this.config = config;
+    this.logger = logger;
+  }
+
+  /**
+   * Lazily initialize and cache the CosOperations instance (triggers COS bootstrap on first call).
+   */
+  private async getClient(): Promise<CosOperations> {
+    if (!this.cachedClient) {
+      this.cachedClient = await this.clientFactory();
+    }
+    return this.cachedClient;
+  }
+
+  // ==========================================================================
+  // bootstrap — session initialization
+  // ==========================================================================
+
+  async bootstrap(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+  }): Promise<BootstrapResult> {
+    // Eagerly trigger COS bootstrap so errors surface early
+    try {
+      await this.getClient();
+    } catch (err) {
+      this.logger.warn(`cloud-engine: COS bootstrap failed during session init: ${String(err)}`);
+    }
+
+    // Sync local memory files to cloud (non-blocking background task)
+    if (this.config.localMemorySyncEnabled && this.config.localMemorySync.enabled) {
+      void this.runLocalMemorySync(params.sessionFile);
+    }
+
+    return { bootstrapped: true };
+  }
+
+  // ==========================================================================
+  // ingest — no-op (conversation memory upload disabled)
+  // ==========================================================================
+
+  async ingest(_params: {
+    sessionId: string;
+    sessionKey?: string;
+    message: AgentMessage;
+    isHeartbeat?: boolean;
+  }): Promise<IngestResult> {
+    return { ingested: false };
+  }
+
+  // ==========================================================================
+  // ingestBatch — no-op (conversation memory upload disabled)
+  // ==========================================================================
+
+  async ingestBatch(_params: {
+    sessionId: string;
+    sessionKey?: string;
+    messages: AgentMessage[];
+    isHeartbeat?: boolean;
+  }): Promise<IngestBatchResult> {
+    return { ingestedCount: 0 };
+  }
+
+  // ==========================================================================
+  // assemble — pass-through (memory recall handled by before_prompt_build hook)
+  // ==========================================================================
+
+  async assemble(params: {
+    sessionId: string;
+    sessionKey?: string;
+    messages: AgentMessage[];
+    tokenBudget?: number;
+  }): Promise<AssembleResult> {
+    // Pass-through: runtime handles history limiting via limitHistoryTurns(),
+    // and memory recall is handled by the before_prompt_build hook in index.ts
+    // which has full control over the system prompt.
+    return {
+      messages: params.messages,
+      estimatedTokens: 0,
+    };
+  }
+
+  // ==========================================================================
+  // compact — no-op (owns compaction to prevent legacy compactor from running)
+  // ==========================================================================
+
+  async compact(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    tokenBudget?: number;
+    force?: boolean;
+    currentTokenCount?: number;
+    compactionTarget?: 'budget' | 'threshold';
+    customInstructions?: string;
+    runtimeContext?: ContextEngineRuntimeContext;
+  }): Promise<CompactResult> {
+    return {
+      ok: true,
+      compacted: true,
+      reason: 'cloud-engine: compaction handled by runtime limitHistoryTurns()',
+      result: {
+        tokensBefore: params.currentTokenCount ?? 0,
+        tokensAfter: 0,
+      },
+    };
+  }
+
+  // ==========================================================================
+  // afterTurn — periodic local memory sync only
+  // ==========================================================================
+
+  async afterTurn(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    messages: AgentMessage[];
+    prePromptMessageCount: number;
+    autoCompactionSummary?: string;
+    isHeartbeat?: boolean;
+    tokenBudget?: number;
+    runtimeContext?: ContextEngineRuntimeContext;
+  }): Promise<void> {
+    if (params.isHeartbeat) {
+      return;
+    }
+
+    // Run local memory sync periodically (every N turns) to pick up file changes
+    if (this.config.localMemorySyncEnabled && this.config.localMemorySync.enabled) {
+      this.turnsSinceLastSync += 1;
+      if (this.turnsSinceLastSync >= LOCAL_MEMORY_SYNC_INTERVAL) {
+        this.turnsSinceLastSync = 0;
+        void this.runLocalMemorySync(params.sessionFile);
+      }
+    }
+  }
+
+  // ==========================================================================
+  // dispose
+  // ==========================================================================
+
+  async dispose(): Promise<void> {
+    this.cachedClient = null;
+  }
+
+  // ==========================================================================
+  // Private helpers
+  // ==========================================================================
+
+  /**
+   * Run local memory sync in the background (non-blocking).
+   * Uploads MEMORY.md, daily logs, and config to cloud storage.
+   */
+  private async runLocalMemorySync(sessionFile: string): Promise<void> {
+    try {
+      const client = await this.getClient();
+      const result = await syncLocalMemoryToCloud(
+        client,
+        sessionFile,
+        this.config.localMemorySync,
+        this.logger,
+      );
+
+      if (result.uploaded > 0) {
+        this.logger.info(
+          `cloud-engine: local memory sync — uploaded=${result.uploaded}, skipped=${result.skipped}`,
+        );
+      }
+    } catch (err) {
+      this.logger.warn(`cloud-engine: local memory sync failed: ${String(err)}`);
+    }
+  }
+
+}