@psiclawops/hypercompositor 0.5.4 → 0.6.2

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;AAMH,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;AA6uElG;;;;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.5.4',
             // 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.
@@ -746,10 +785,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 +805,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 {
@@ -891,17 +933,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 +960,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 +971,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);
@@ -2028,6 +2079,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 +2138,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@psiclawops/hypercompositor",
-  "version": "0.5.4",
+  "version": "0.6.2",
   "description": "HyperCompositor — context engine plugin for OpenClaw",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,15 @@
     },
     "extensions": [
       "./dist/index.js"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.5",
+      "minGatewayVersion": "2026.4.5"
+    },
+    "build": {
+      "openclawVersion": "2026.4.9",
+      "pluginSdkVersion": "2026.4.5"
+    }
   },
   "scripts": {
     "build": "tsc",