@psiclawops/hypercompositor 0.5.4 → 0.7.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,EAId,MAAM,sBAAsB,CAAC;AAU9B,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC;AAsrElG;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU1F;;;;;;;;AAMD,wBAwBG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAaH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,EAId,MAAM,sBAAsB,CAAC;AAW9B,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC;AAq5ElG;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU1F;;;;;;;;AA8DD,wBA4CG"}

package/dist/index.js

@@ -19,20 +19,24 @@
  *
  * Session key format expected: "agent:<agentId>:<channel>:<name>"
  */
-import { definePluginEntry, emptyPluginConfigSchema } from 'openclaw/plugin-sdk/plugin-entry';
-import { detectTopicShift, stripMessageMetadata, SessionTopicMap, applyToolGradientToWindow, canPersistReshapedHistory } from '@psiclawops/hypermem';
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { buildPluginConfigSchema } from 'openclaw/plugin-sdk/core';
+import { z } from 'zod';
+import { detectTopicShift, stripMessageMetadata, SessionTopicMap, applyToolGradientToWindow, canPersistReshapedHistory, OPENCLAW_BOOTSTRAP_FILES } from '@psiclawops/hypermem';
 import { evictStaleContent } from '@psiclawops/hypermem/image-eviction';
 import { repairToolPairs } from '@psiclawops/hypermem';
 import os from 'os';
 import path from 'path';
 import fs from 'fs/promises';
 import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 // ─── hypermem singleton ────────────────────────────────────────
 // Runtime load is dynamic (hypermem is a sibling package loaded from repo dist,
 // not installed via npm). Types come from the core package devDependency.
 // This pattern keeps the runtime path stable while TypeScript resolves types
 // from the canonical source — no more local shim drift.
-const HYPERMEM_PATH = path.join(os.homedir(), '.openclaw/workspace/repo/hypermem/dist/index.js');
+// Resolved at init time: pluginConfig.hyperMemPath > require.resolve('@psiclawops/hypermem') > dev fallback
+let HYPERMEM_PATH = '';
 const require = createRequire(import.meta.url);
 let _hm = null;
 let _hmInitPromise = null;
@@ -108,25 +112,52 @@ function computeEffectiveBudget(tokenBudget) {
     // Derived from window config: floor to avoid fractional tokens
     return Math.floor(_contextWindowSize * (1 - _contextWindowReserve));
 }
+// ─── Plugin config cache ───────────────────────────────────────
+// Populated from openclaw.json plugins.entries.hypercompositor.config
+// during register(). loadUserConfig() merges this over config.json.
+let _pluginConfig = {};
 /**
- * Load optional user config from ~/.openclaw/hypermem/config.json.
- * Supports overriding compositor tuning knobs without editing plugin source.
- * Unknown keys are ignored. Missing file is silently skipped.
+ * Load user config with priority: pluginConfig (openclaw.json) > config.json (legacy).
+ * pluginConfig values win; config.json provides fallback for keys not set in openclaw.json.
+ * This allows gradual migration from the shadow config.json to central config.
  */
 async function loadUserConfig() {
-    const configPath = path.join(os.homedir(), '.openclaw/hypermem/config.json');
+    // Resolve data dir: pluginConfig > default
+    const dataDir = _pluginConfig.dataDir ?? path.join(os.homedir(), '.openclaw/hypermem');
+    const configPath = path.join(dataDir, 'config.json');
+    let fileConfig = {};
     try {
         const raw = await fs.readFile(configPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        console.log(`[hypermem-plugin] Loaded user config from ${configPath}`);
-        return parsed;
+        fileConfig = JSON.parse(raw);
+        console.log(`[hypermem-plugin] Loaded legacy config from ${configPath}`);
     }
     catch (err) {
         if (err.code !== 'ENOENT') {
             console.warn(`[hypermem-plugin] Failed to parse config.json (using defaults):`, err.message);
         }
-        return {};
     }
+    // Merge: pluginConfig (openclaw.json) wins over fileConfig (legacy config.json).
+    // Top-level scalar keys from pluginConfig override fileConfig.
+    // Nested objects (compositor, eviction, embedding) are shallow-merged.
+    const merged = { ...fileConfig };
+    if (_pluginConfig.contextWindowSize != null)
+        merged.contextWindowSize = _pluginConfig.contextWindowSize;
+    if (_pluginConfig.contextWindowReserve != null)
+        merged.contextWindowReserve = _pluginConfig.contextWindowReserve;
+    if (_pluginConfig.deferToolPruning != null)
+        merged.deferToolPruning = _pluginConfig.deferToolPruning;
+    if (_pluginConfig.subagentWarming != null)
+        merged.subagentWarming = _pluginConfig.subagentWarming;
+    if (_pluginConfig.compositor)
+        merged.compositor = { ...merged.compositor, ..._pluginConfig.compositor };
+    if (_pluginConfig.eviction)
+        merged.eviction = { ...merged.eviction, ..._pluginConfig.eviction };
+    if (_pluginConfig.embedding)
+        merged.embedding = { ...merged.embedding, ..._pluginConfig.embedding };
+    if (Object.keys(fileConfig).length > 0 && Object.keys(_pluginConfig).filter(k => k !== 'hyperMemPath' && k !== 'dataDir').length > 0) {
+        console.log('[hypermem-plugin] Note: migrating config.json keys to plugins.entries.hypercompositor.config in openclaw.json is recommended');
+    }
+    return merged;
 }
 async function getHyperMem() {
     if (_hm)
@@ -150,16 +181,24 @@ async function getHyperMem() {
         // (VectorStore init) and the _generateEmbeddings closure above.
         if (userConfig.embedding) {
             const ue = userConfig.embedding;
+            // Provider-specific model/dimension/batch defaults
+            const providerDefaults = ue.provider === 'gemini'
+                ? { model: 'gemini-embedding-001', dimensions: 3072, batchSize: 100, timeout: 15000 }
+                : ue.provider === 'openai'
+                    ? { model: 'text-embedding-3-small', dimensions: 1536, batchSize: 128, timeout: 10000 }
+                    : { model: 'nomic-embed-text', dimensions: 768, batchSize: 32, timeout: 10000 };
             _embeddingConfig = {
                 provider: ue.provider ?? 'ollama',
                 ollamaUrl: ue.ollamaUrl ?? 'http://localhost:11434',
                 openaiBaseUrl: ue.openaiBaseUrl ?? 'https://api.openai.com/v1',
                 openaiApiKey: ue.openaiApiKey,
-                // Apply provider-specific model + dimension defaults when not explicitly set
-                model: ue.model ?? (ue.provider === 'openai' ? 'text-embedding-3-small' : 'nomic-embed-text'),
-                dimensions: ue.dimensions ?? (ue.provider === 'openai' ? 1536 : 768),
-                timeout: ue.timeout ?? 10000,
-                batchSize: ue.batchSize ?? (ue.provider === 'openai' ? 128 : 32),
+                geminiBaseUrl: ue.geminiBaseUrl,
+                geminiIndexTaskType: ue.geminiIndexTaskType,
+                geminiQueryTaskType: ue.geminiQueryTaskType,
+                model: ue.model ?? providerDefaults.model,
+                dimensions: ue.dimensions ?? providerDefaults.dimensions,
+                timeout: ue.timeout ?? providerDefaults.timeout,
+                batchSize: ue.batchSize ?? providerDefaults.batchSize,
             };
             console.log(`[hypermem-plugin] Embedding provider: ${_embeddingConfig.provider} ` +
                 `(model: ${_embeddingConfig.model}, ${_embeddingConfig.dimensions}d, batch: ${_embeddingConfig.batchSize})`);
@@ -192,7 +231,7 @@ async function getHyperMem() {
             `${Math.round(_contextWindowReserve * 100)}% reserved (${reservedTokens} tokens), ` +
             `effective history budget: ${_contextWindowSize - reservedTokens} tokens`);
         const instance = await HyperMem.create({
-            dataDir: path.join(os.homedir(), '.openclaw/hypermem'),
+            dataDir: _pluginConfig.dataDir ?? path.join(os.homedir(), '.openclaw/hypermem'),
             cache: {
                 keyPrefix: 'hm:',
                 sessionTTL: 14400, // 4h for system/identity/meta slots
@@ -679,7 +718,7 @@ function createHyperMemEngine() {
         info: {
             id: 'hypermem',
             name: 'hypermem context engine',
-            version: '0.5.3',
+            version: '0.6.3',
             // We own compaction — assemble() trims to budget via the compositor safety
             // valve, so runtime compaction is never needed. compact() handles any
             // explicit calls by trimming the Redis history window directly.
@@ -703,34 +742,7 @@ function createHyperMemEngine() {
                 const hm = await getHyperMem();
                 const sk = resolveSessionKey(sessionId, sessionKey);
                 const agentId = extractAgentId(sk);
-                // EC1 pre-flight: proactively truncate the JSONL on disk if it is over
-                // the safe replay threshold. Fires BEFORE warm() so the next restart
-                // (not this one) loads a clean file. Combined with the preflight script
-                // run before each gateway restart, this closes the EC1 loop entirely.
-                //
-                // Why this doesn't help the CURRENT session:
-                //   OpenClaw has already replayed the JSONL into memory by the time
-                //   bootstrap() is called. Disk truncation here is forward-looking only.
-                //
-                // Why it still matters:
-                //   Without this, a session that saturates in operation (no preflight ran)
-                //   would restart saturated on the next boot. This ensures at least one
-                //   restart cycle later the session comes up clean.
-                try {
-                    const sessionDir = path.join(os.homedir(), '.openclaw', 'agents', agentId, 'sessions');
-                    const jsonlPath = path.join(sessionDir, `${sessionId}.jsonl`);
-                    // EC1 threshold: 60 conversation messages (token-capped at 40% of 128k)
-                    const EC1_MAX_MESSAGES = 60;
-                    const EC1_TOKEN_BUDGET = Math.floor(128_000 * 0.40);
-                    const truncated = await truncateJsonlIfNeeded(jsonlPath, EC1_MAX_MESSAGES, false, EC1_TOKEN_BUDGET);
-                    if (truncated) {
-                        console.log(`[hypermem-plugin] bootstrap: proactive JSONL trim for ${agentId} ` +
-                            `(EC1 guard — next restart will load clean)`);
-                    }
-                }
-                catch {
-                    // Non-fatal — JSONL truncation is best-effort
-                }
+                // EC1 JSONL truncation moved to maintain() — bootstrap stays fast.
                 // Fast path: if session already has history in Redis, skip warm entirely.
                 // sessionExists() is a single EXISTS call — sub-millisecond cost.
                 const alreadyWarm = await hm.cache.sessionExists(agentId, sk);
@@ -746,10 +758,12 @@ function createHyperMemEngine() {
                     return { bootstrapped: true };
                 }
                 // Cold start: warm Redis with the session — pre-loads history + slots
-                // CRIT-002: Load identity block (SOUL.md + IDENTITY.md + MOTIVATIONS.md)
-                // and pass into warm() so the compositor identity slot is populated.
-                // Previously opts.identity was always undefined — the slot was allocated
-                // but always empty. Non-fatal: missing files are silently skipped.
+                // CRIT-002: Load supplemental identity files (MOTIVATIONS.md, STYLE.md) that are
+                // NOT already injected by OpenClaw's contextInjection into the system prompt.
+                // SOUL.md and IDENTITY.md are filtered out here because OpenClaw injects them
+                // via workspace bootstrap — re-injecting them via the identity slot would cause
+                // duplication. Only agent-specific extras (MOTIVATIONS.md, STYLE.md) are included.
+                // Non-fatal: missing files are silently skipped.
                 let identityBlock;
                 try {
                     // Council agents live at workspace-council/<agentId>/
@@ -764,7 +778,8 @@ function createHyperMemEngine() {
                     catch {
                         wsPath = workspacePath;
                     }
-                    const identityFiles = ['SOUL.md', 'IDENTITY.md', 'MOTIVATIONS.md', 'STYLE.md'];
+                    const identityFiles = ['SOUL.md', 'IDENTITY.md', 'MOTIVATIONS.md', 'STYLE.md']
+                        .filter(f => !OPENCLAW_BOOTSTRAP_FILES.has(f));
                     const parts = [];
                     for (const fname of identityFiles) {
                         try {
@@ -853,6 +868,67 @@ function createHyperMemEngine() {
                 return { bootstrapped: false, reason: err.message };
             }
         },
+        /**
+         * Transcript maintenance — runs after bootstrap, successful turns, or compaction.
+         *
+         * Moved from bootstrap: proactive JSONL truncation is forward-looking (helps
+         * next restart, not current session), so it belongs in maintenance, not init.
+         * Also runs tool pair repair on Redis history to fix orphaned pairs from
+         * trim/compaction passes.
+         */
+        async maintain({ sessionId, sessionKey, sessionFile }) {
+            let changed = false;
+            let bytesFreed = 0;
+            let rewrittenEntries = 0;
+            try {
+                const hm = await getHyperMem();
+                const sk = resolveSessionKey(sessionId, sessionKey);
+                const agentId = extractAgentId(sk);
+                // 1. Proactive JSONL truncation (EC1 guard — next restart loads clean)
+                try {
+                    const EC1_MAX_MESSAGES = 60;
+                    const EC1_TOKEN_BUDGET = Math.floor(128_000 * 0.40);
+                    const truncated = await truncateJsonlIfNeeded(sessionFile, EC1_MAX_MESSAGES, false, EC1_TOKEN_BUDGET);
+                    if (truncated) {
+                        console.log(`[hypermem-plugin] maintain: proactive JSONL trim for ${agentId} ` +
+                            `(EC1 guard — next restart will load clean)`);
+                        changed = true;
+                    }
+                }
+                catch {
+                    // Non-fatal — JSONL truncation is best-effort
+                }
+                // 2. Redis history tool pair repair
+                // Compaction and trim passes can orphan tool_call/tool_result pairs.
+                // Anthropic and Gemini reject orphaned pairs with 400 errors.
+                try {
+                    const history = await hm.cache.getHistory(agentId, sk);
+                    if (history && history.length > 0) {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const repairedHistory = repairToolPairs(history);
+                        const removedCount = history.length - repairedHistory.length;
+                        if (removedCount > 0) {
+                            await hm.cache.replaceHistory(agentId, sk, repairedHistory);
+                            await hm.cache.invalidateWindow(agentId, sk);
+                            console.log(`[hypermem-plugin] maintain: repaired tool pairs in Redis history ` +
+                                `for ${agentId} (removed ${removedCount} orphaned messages)`);
+                            changed = true;
+                            rewrittenEntries += removedCount;
+                            // Rough estimate: ~500 bytes per removed message
+                            bytesFreed += removedCount * 500;
+                        }
+                    }
+                }
+                catch {
+                    // Non-fatal
+                }
+                return { changed, bytesFreed, rewrittenEntries };
+            }
+            catch (err) {
+                console.warn('[hypermem-plugin] maintain failed:', err.message);
+                return { changed, bytesFreed, rewrittenEntries, reason: err.message };
+            }
+        },
         /**
          * Ingest a single message into hypermem's message store.
          * Skip heartbeats — they're noise in the memory store.
@@ -891,17 +967,24 @@ function createHyperMemEngine() {
                     const redisTokens = await estimateWindowTokens(hm, agentId, sk);
                     const effectiveBudget = computeEffectiveBudget(undefined);
                     const redisPressure = redisTokens / effectiveBudget;
+                    // Error tool results are always preserved intact — they're small and
+                    // the model needs the error signal to understand what went wrong.
+                    const hasErrorResult = neutral.toolResults.some(tr => tr.isError);
                     if (redisPressure > 0.85) {
                         // FIX (Bug 4): Never skip a tool result entirely — that leaves an orphaned
                         // tool_call in Redis history (the assistant message was already recorded).
                         // Anthropic rejects assistant messages with tool_calls that have no matching result.
                         // Instead, record a compact stub that preserves pair integrity in history.
-                        const stubbedResults = neutral.toolResults.map(tr => ({
-                            ...tr,
-                            content: `[tool result omitted by wave-guard at ${(redisPressure * 100).toFixed(0)}% Redis pressure]`,
-                        }));
+                        const stubbedResults = neutral.toolResults.map(tr => {
+                            if (tr.isError)
+                                return tr; // preserve error results intact
+                            return {
+                                ...tr,
+                                content: `[tool result omitted by wave-guard at ${(redisPressure * 100).toFixed(0)}% Redis pressure]`,
+                            };
+                        });
                         const stubNeutral = { ...neutral, toolResults: stubbedResults };
-                        console.log(`[hypermem] ingest wave-guard: stubbing toolResult (Redis pressure ${(redisPressure * 100).toFixed(0)}% > 85%) — preserving pair integrity`);
+                        console.log(`[hypermem] ingest wave-guard: stubbing toolResult (Redis pressure ${(redisPressure * 100).toFixed(0)}% > 85%)${hasErrorResult ? ' — error results preserved' : ''} — preserving pair integrity`);
                         await hm.recordAssistantMessage(agentId, sk, stubNeutral);
                         return { ingested: true };
                     }
@@ -911,6 +994,8 @@ function createHyperMemEngine() {
                         neutral = {
                             ...neutral,
                             toolResults: neutral.toolResults.map(tr => {
+                                if (tr.isError)
+                                    return tr; // preserve error results intact
                                 const content = typeof tr.content === 'string' ? tr.content : JSON.stringify(tr.content);
                                 if (content.length <= MAX_TOOL_RESULT_CHARS)
                                     return tr;
@@ -920,7 +1005,7 @@ function createHyperMemEngine() {
                                 };
                             }),
                         };
-                        console.log(`[hypermem] ingest wave-guard: truncated toolResult (Redis pressure ${(redisPressure * 100).toFixed(0)}% > 70%)`);
+                        console.log(`[hypermem] ingest wave-guard: truncated toolResult (Redis pressure ${(redisPressure * 100).toFixed(0)}% > 70%)${hasErrorResult ? ' — error results preserved' : ''}`);
                     }
                 }
                 await hm.recordAssistantMessage(agentId, sk, neutral);
@@ -932,6 +1017,41 @@ function createHyperMemEngine() {
                 return { ingested: false };
             }
         },
+        /**
+         * Batch ingest: process multiple messages in a single call.
+         *
+         * Note: when afterTurn() is defined (which it is), the runtime calls
+         * afterTurn instead of ingest/ingestBatch. This is here for interface
+         * completeness and forward compatibility.
+         */
+        async ingestBatch({ sessionId, sessionKey, messages, isHeartbeat }) {
+            if (isHeartbeat) {
+                return { ingestedCount: 0 };
+            }
+            let ingestedCount = 0;
+            try {
+                const hm = await getHyperMem();
+                const sk = resolveSessionKey(sessionId, sessionKey);
+                const agentId = extractAgentId(sk);
+                for (const message of messages) {
+                    const msg = message;
+                    if (msg.role === 'system')
+                        continue;
+                    const neutral = toNeutralMessage(msg);
+                    if (neutral.role === 'user' && !neutral.toolResults?.length) {
+                        await hm.recordUserMessage(agentId, sk, stripMessageMetadata(neutral.textContent ?? ''));
+                    }
+                    else {
+                        await hm.recordAssistantMessage(agentId, sk, neutral);
+                    }
+                    ingestedCount++;
+                }
+            }
+            catch (err) {
+                console.warn('[hypermem-plugin] ingestBatch failed:', err.message);
+            }
+            return { ingestedCount };
+        },
         /**
          * Assemble model context from all four hypermem layers.
          *
@@ -1903,6 +2023,81 @@ function createHyperMemEngine() {
                 console.warn('[hypermem-plugin] afterTurn failed:', err.message);
             }
         },
+        /**
+         * Prepare context for a subagent session before it starts.
+         *
+         * Seeds the child session's Redis with parent context based on the
+         * subagentWarming config ('full' | 'light' | 'off').
+         * Returns a rollback handle to clean up if spawn fails.
+         */
+        async prepareSubagentSpawn({ parentSessionKey, childSessionKey }) {
+            if (_subagentWarming === 'off') {
+                return undefined;
+            }
+            try {
+                const hm = await getHyperMem();
+                const parentAgentId = extractAgentId(parentSessionKey);
+                const childAgentId = extractAgentId(childSessionKey);
+                // Seed child with parent's active facts
+                const facts = hm.getActiveFacts(parentAgentId, { limit: 50 });
+                if (facts && facts.length > 0) {
+                    const factBlock = facts
+                        .map(f => f.content)
+                        .join('\n');
+                    await hm.cache.setSlot(childAgentId, childSessionKey, 'parentFacts', factBlock);
+                }
+                // For 'full' warming, also seed recent history context
+                if (_subagentWarming === 'full') {
+                    const history = await hm.cache.getHistory(parentAgentId, parentSessionKey);
+                    if (history && history.length > 0) {
+                        const recentHistory = history.slice(-10);
+                        await hm.cache.setSlot(childAgentId, childSessionKey, 'parentHistory', JSON.stringify(recentHistory));
+                    }
+                }
+                console.log(`[hypermem-plugin] prepareSubagentSpawn: seeded ${childSessionKey} ` +
+                    `from ${parentSessionKey} (warming=${_subagentWarming})`);
+                return {
+                    async rollback() {
+                        try {
+                            const hm = await getHyperMem();
+                            await hm.cache.setSlot(childAgentId, childSessionKey, 'parentFacts', '');
+                            await hm.cache.setSlot(childAgentId, childSessionKey, 'parentHistory', '');
+                        }
+                        catch {
+                            // Rollback is best-effort
+                        }
+                    },
+                };
+            }
+            catch (err) {
+                console.warn('[hypermem-plugin] prepareSubagentSpawn failed (non-fatal):', err.message);
+                return undefined;
+            }
+        },
+        /**
+         * Clean up after a subagent session ends.
+         *
+         * Removes Redis slots and invalidates caches for the dead session
+         * to prevent stale data accumulation.
+         */
+        async onSubagentEnded({ childSessionKey, reason }) {
+            try {
+                const hm = await getHyperMem();
+                const childAgentId = extractAgentId(childSessionKey);
+                await Promise.all([
+                    hm.cache.setSlot(childAgentId, childSessionKey, 'parentFacts', ''),
+                    hm.cache.setSlot(childAgentId, childSessionKey, 'parentHistory', ''),
+                    hm.cache.setSlot(childAgentId, childSessionKey, 'assemblyContextBlock', ''),
+                    hm.cache.setSlot(childAgentId, childSessionKey, 'assemblyContextAt', '0'),
+                    hm.cache.invalidateWindow(childAgentId, childSessionKey).catch(() => { }),
+                ]);
+                _overheadCache.delete(childSessionKey);
+                console.log(`[hypermem-plugin] onSubagentEnded: cleaned up ${childSessionKey} (reason=${reason})`);
+            }
+            catch (err) {
+                console.warn('[hypermem-plugin] onSubagentEnded failed (non-fatal):', err.message);
+            }
+        },
         /**
          * Dispose: intentionally a no-op.
          *
@@ -2028,6 +2223,58 @@ export async function bustAssemblyCache(agentId, sessionKey) {
         // Non-fatal
     }
 }
+// ─── Plugin Config Schema ────────────────────────────────────────
+// Exposed via openclaw.json → plugins.entries.hypercompositor.config
+// Validated by OpenClaw on gateway start. Visible via `openclaw config get`.
+const hypercompositorConfigSchema = z.object({
+    /** Path to HyperMem core dist/index.js. Auto-resolved if omitted. */
+    hyperMemPath: z.string().optional(),
+    /** HyperMem data directory. Default: ~/.openclaw/hypermem */
+    dataDir: z.string().optional(),
+    /** Full model context window size in tokens. Default: 128000 */
+    contextWindowSize: z.number().int().positive().optional(),
+    /** Fraction [0.0–0.5] reserved for system prompts + headroom. Default: 0.25 */
+    contextWindowReserve: z.number().min(0).max(0.5).optional(),
+    /** Defer tool pruning to OpenClaw's contextPruning. Default: false */
+    deferToolPruning: z.boolean().optional(),
+    /** Subagent context injection: 'full' | 'light' | 'off'. Default: 'light' */
+    subagentWarming: z.enum(['full', 'light', 'off']).optional(),
+    /** Compositor tuning overrides */
+    compositor: z.object({
+        defaultTokenBudget: z.number().int().positive().optional(),
+        maxHistoryMessages: z.number().int().positive().optional(),
+        maxFacts: z.number().int().positive().optional(),
+        maxCrossSessionContext: z.number().int().nonnegative().optional(),
+        maxRecentToolPairs: z.number().int().nonnegative().optional(),
+        maxProseToolPairs: z.number().int().nonnegative().optional(),
+        warmHistoryBudgetFraction: z.number().min(0).max(1).optional(),
+        keystoneHistoryFraction: z.number().min(0).max(1).optional(),
+        keystoneMaxMessages: z.number().int().nonnegative().optional(),
+        keystoneMinSignificance: z.number().min(0).max(1).optional(),
+    }).optional(),
+    /** Image/tool eviction settings */
+    eviction: z.object({
+        enabled: z.boolean().optional(),
+        imageAgeTurns: z.number().int().nonnegative().optional(),
+        toolResultAgeTurns: z.number().int().nonnegative().optional(),
+        minTokensToEvict: z.number().int().nonnegative().optional(),
+        keepPreviewChars: z.number().int().nonnegative().optional(),
+    }).optional(),
+    /** Embedding provider config */
+    embedding: z.object({
+        provider: z.enum(['ollama', 'openai', 'gemini']).optional(),
+        ollamaUrl: z.string().optional(),
+        openaiApiKey: z.string().optional(),
+        openaiBaseUrl: z.string().optional(),
+        geminiBaseUrl: z.string().optional(),
+        geminiIndexTaskType: z.string().optional(),
+        geminiQueryTaskType: z.string().optional(),
+        model: z.string().optional(),
+        dimensions: z.number().int().positive().optional(),
+        timeout: z.number().int().positive().optional(),
+        batchSize: z.number().int().positive().optional(),
+    }).optional(),
+});
 // ─── Plugin Entry ───────────────────────────────────────────────
 const engine = createHyperMemEngine();
 export default definePluginEntry({
@@ -2035,8 +2282,28 @@ export default definePluginEntry({
     name: 'HyperCompositor — context engine',
     description: 'Four-layer memory architecture for OpenClaw agents: Redis hot cache, message history, vector search, and structured library.',
     kind: 'context-engine',
-    configSchema: emptyPluginConfigSchema(),
+    configSchema: buildPluginConfigSchema(hypercompositorConfigSchema),
     register(api) {
+        // ── Resolve plugin config from openclaw.json ──
+        const pluginCfg = (api.pluginConfig ?? {});
+        _pluginConfig = pluginCfg;
+        // ── Resolve HYPERMEM_PATH: pluginConfig > npm resolve > dev fallback ──
+        if (pluginCfg.hyperMemPath) {
+            HYPERMEM_PATH = pluginCfg.hyperMemPath;
+            console.log(`[hypermem-plugin] Using configured hyperMemPath: ${HYPERMEM_PATH}`);
+        }
+        else {
+            try {
+                HYPERMEM_PATH = require.resolve('@psiclawops/hypermem');
+                console.log(`[hypermem-plugin] Resolved @psiclawops/hypermem from node_modules: ${HYPERMEM_PATH}`);
+            }
+            catch {
+                // Dev fallback: resolve relative to plugin directory
+                const __pluginDir = path.dirname(fileURLToPath(import.meta.url));
+                HYPERMEM_PATH = path.resolve(__pluginDir, '../../dist/index.js');
+                console.log(`[hypermem-plugin] Falling back to dev path: ${HYPERMEM_PATH}`);
+            }
+        }
         api.registerContextEngine('hypercompositor', () => engine);
         // P1.7: Bind TaskFlow runtime for task visibility — best-effort.
         // Guard: api.runtime.taskFlow may not exist on older OpenClaw versions.

package/openclaw.plugin.json

@@ -2,6 +2,9 @@
   "id": "hypercompositor",
   "enabledByDefault": false,
   "kind": "context-engine",
+  "activation": {
+    "onCapabilities": ["context-engine"]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@psiclawops/hypercompositor",
-  "version": "0.5.4",
+  "version": "0.7.0",
   "description": "HyperCompositor — context engine plugin for OpenClaw",
   "type": "module",
   "main": "dist/index.js",
@@ -23,14 +23,22 @@
     },
     "extensions": [
       "./dist/index.js"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.12",
+      "minGatewayVersion": "2026.4.12"
+    },
+    "build": {
+      "openclawVersion": "2026.4.9",
+      "pluginSdkVersion": "2026.4.12"
+    }
   },
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@psiclawops/hypermem": "^0.5.2"
+    "@psiclawops/hypermem": "^0.6.3"
   },
   "devDependencies": {
     "openclaw": "*",