[codex] fix requestDimensions schema sizing and request payload alignment (#572)

* fix: align requestDimensions schema sizing and request payloads

* test: reset singleton plugin state between scenarios

---------

Co-authored-by: Heng Xia <pope@Hengs-Mac-mini.local>

Author: rwmjhb

index.ts

@@ -21,7 +21,10 @@ const isCliMode = () => process.env.OPENCLAW_CLI === "1";
 
 // Import core components
 import { MemoryStore, validateStoragePath } from "./src/store.js";
-import { createEmbedder, getVectorDimensions } from "./src/embedder.js";
+import {
+  createEmbedder,
+  getEffectiveVectorDimensions,
+} from "./src/embedder.js";
 import { createRetriever, DEFAULT_RETRIEVAL_CONFIG } from "./src/retriever.js";
 import { createScopeManager, resolveScopeFilter, isSystemBypassId, parseAgentIdFromSessionKey } from "./src/scopes.js";
 import { createMigrator } from "./src/migrate.js";
@@ -91,6 +94,7 @@ interface PluginConfig {
     model?: string;
     baseURL?: string;
     dimensions?: number;
+    requestDimensions?: number;
     omitDimensions?: boolean;
     taskQuery?: string;
     taskPassage?: string;
@@ -1647,7 +1651,7 @@ const pluginVersion = getPluginVersion();
 // WeakSet keyed by API instance — each distinct API object tracks its own initialized state.
 // Using WeakSet instead of a module-level boolean avoids the "second register() call skips
 // hook/tool registration for the new API instance" regression that rwmjhb identified.
-const _registeredApis = new WeakSet<OpenClawPluginApi>();
+let _registeredApis = new WeakSet<OpenClawPluginApi>();
 
 // ============================================================================
 // Hook Event Deduplication (Phase 1)
@@ -1730,9 +1734,10 @@ function _initPluginState(api: OpenClawPluginApi): PluginSingletonState {
     );
   }
 
-  const vectorDim = getVectorDimensions(
+  const vectorDim = getEffectiveVectorDimensions(
     config.embedding.model || "text-embedding-3-small",
     config.embedding.dimensions,
+    config.embedding.requestDimensions,
   );
   const store = new MemoryStore({ dbPath: resolvedDbPath, vectorDim });
   const embedder = createEmbedder({
@@ -1741,6 +1746,7 @@ function _initPluginState(api: OpenClawPluginApi): PluginSingletonState {
     model: config.embedding.model || "text-embedding-3-small",
     baseURL: config.embedding.baseURL,
     dimensions: config.embedding.dimensions,
+    requestDimensions: config.embedding.requestDimensions,
     omitDimensions: config.embedding.omitDimensions,
     taskQuery: config.embedding.taskQuery,
     taskPassage: config.embedding.taskPassage,
@@ -4033,6 +4039,8 @@ export function parsePluginConfig(value: unknown): PluginConfig {
       // Accept number, numeric string, or env-var string (e.g. "${EMBED_DIM}").
       // Also accept legacy top-level `dimensions` for convenience.
       dimensions: parsePositiveInt(embedding.dimensions ?? cfg.dimensions),
+      // Intentionally no top-level fallback: requestDimensions is request-only.
+      requestDimensions: parsePositiveInt(embedding.requestDimensions),
       omitDimensions:
         typeof embedding.omitDimensions === "boolean"
           ? embedding.omitDimensions
@@ -4255,10 +4263,9 @@ export { getDefaultMdMirrorDir };
  * @public
  */
 export function resetRegistration() {
-  // Note: WeakSets cannot be cleared by design. In test scenarios where the
-  // same process reloads the module, a fresh module state means a new WeakSet.
-  // For hot-reload scenarios, the module is re-imported fresh.
-  // (WeakSet.clear() does not exist, so we do nothing here.)
+  _registeredApis = new WeakSet<OpenClawPluginApi>();
+  _singletonState = null;
+  _hookEventDedup.clear();
 }
 
 export default memoryLanceDBProPlugin;

openclaw.plugin.json

@@ -47,11 +47,17 @@
           },
           "dimensions": {
             "type": "integer",
-            "minimum": 1
+            "minimum": 1,
+            "description": "Internal vector dimensions for LanceDB schema sizing and local embedding validation"
+          },
+          "requestDimensions": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Optional dimensions/output_dimension value to send to embedding providers that support variable output sizes"
           },
           "omitDimensions": {
             "type": "boolean",
-            "description": "When true, omit the dimensions parameter from embedding requests even if dimensions is configured"
+            "description": "When true, omit dimensions/output_dimension from embedding requests even if requestDimensions is configured"
           },
           "taskQuery": {
             "type": "string",
@@ -892,14 +898,20 @@
       "advanced": true
     },
     "embedding.dimensions": {
-      "label": "Vector Dimensions",
+      "label": "Schema Dimensions",
       "placeholder": "auto-detected from model",
-      "help": "Override vector dimensions for custom models not in the built-in lookup table",
+      "help": "Internal vector dimensions used for LanceDB schema sizing and local embedding validation. Override this for custom models not in the built-in lookup table.",
+      "advanced": true
+    },
+    "embedding.requestDimensions": {
+      "label": "Request Dimensions",
+      "placeholder": "omit by default",
+      "help": "Optional dimensions/output_dimension value to send to the embedding API. If unset, no request-side dimensions field is sent.",
       "advanced": true
     },
     "embedding.omitDimensions": {
       "label": "Omit Request Dimensions",
-      "help": "Do not send the dimensions parameter to the embedding API even if embedding.dimensions is configured. Useful for local models like Qwen3-Embedding that reject the field.",
+      "help": "Do not send dimensions/output_dimension to the embedding API even if embedding.requestDimensions is configured. Useful for local models like Qwen3-Embedding that reject the field.",
       "advanced": true
     },
     "embedding.taskQuery": {

src/embedder.ts

@@ -105,7 +105,10 @@ export interface EmbeddingConfig {
   apiKey: string | string[];
   model: string;
   baseURL?: string;
+  /** Internal vector dimension for schema sizing and local validation. */
   dimensions?: number;
+  /** Optional API request output dimension for providers that support it. */
+  requestDimensions?: number;
 
   /** Optional task type for query embeddings (e.g. "retrieval.query") */
   taskQuery?: string;
@@ -434,6 +437,14 @@ export function getVectorDimensions(model: string, overrideDims?: number): numbe
   return dims;
 }
 
+export function getEffectiveVectorDimensions(
+  model: string,
+  dimensions?: number,
+  requestDimensions?: number,
+): number {
+  return getVectorDimensions(model, requestDimensions ?? dimensions);
+}
+
 // ============================================================================
 // Embedder Class
 // ============================================================================
@@ -471,7 +482,7 @@ export class Embedder {
     this._taskQuery = config.taskQuery;
     this._taskPassage = config.taskPassage;
     this._normalized = config.normalized;
-    this._requestDimensions = config.dimensions;
+    this._requestDimensions = config.requestDimensions;
     this._omitDimensions = config.omitDimensions === true;
     // Enable auto-chunking by default for better handling of long documents
     this._autoChunk = config.chunking !== false;
@@ -515,7 +526,11 @@ export class Embedder {
       console.log(`[memory-lancedb-pro] Initialized ${this.clients.length} API keys for round-robin rotation`);
     }
 
-    this.dimensions = getVectorDimensions(config.model, config.dimensions);
+    this.dimensions = getEffectiveVectorDimensions(
+      config.model,
+      config.dimensions,
+      config.requestDimensions,
+    );
     this._cache = new EmbeddingCache(256, 30); // 256 entries, 30 min TTL
   }
 

test/embedder-error-hints.test.mjs

@@ -130,7 +130,7 @@ async function run() {
   installMockEmbeddingClient(jinaEmbedder, async (payload) => {
     assert.equal(payload.task, "retrieval.passage");
     assert.equal(payload.normalized, true);
-    assert.equal(payload.dimensions, 1024);
+    assert.equal(payload.dimensions, undefined, "jina should not send dimensions unless requestDimensions is set");
     return createEmbeddingResponse(1024);
   });
   await jinaEmbedder.embedPassage("hello");
@@ -144,7 +144,7 @@ async function run() {
   });
   installMockEmbeddingClient(genericEmbedder, async (payload) => {
     assert.equal(payload.encoding_format, "float");
-    assert.equal(payload.dimensions, 384);
+    assert.equal(payload.dimensions, undefined, "generic profile should not send dimensions unless requestDimensions is set");
     return createEmbeddingResponse(384);
   });
   await genericEmbedder.embedPassage("hello");
@@ -196,7 +196,7 @@ async function run() {
     apiKey: "test-key",
     model: "voyage-4-lite",
     baseURL: "https://api.voyageai.com/v1",
-    dimensions: 512,
+    requestDimensions: 512,
   });
   installMockEmbeddingClient(voyageDimEmbedder, async (payload) => {
     assert.equal(payload.output_dimension, 512, "voyage should send output_dimension");
@@ -211,7 +211,7 @@ async function run() {
   await withEmbeddingCaptureServer(
     (payload) => {
       assert.equal(payload.encoding_format, "float", "generic profile should send encoding_format");
-      assert.equal(payload.dimensions, 384, "generic profile should send dimensions");
+      assert.equal(payload.dimensions, undefined, "generic profile should not send dimensions by default");
       assert.equal(payload.task, undefined, "generic profile should not send task");
       assert.equal(payload.normalized, undefined, "generic profile should not send normalized");
       return { body: createEmbeddingResponse(384) };
@@ -228,6 +228,24 @@ async function run() {
     },
   );
 
+  await withEmbeddingCaptureServer(
+    (payload) => {
+      assert.equal(payload.encoding_format, "float", "generic profile should send encoding_format");
+      assert.equal(payload.dimensions, 384, "generic profile should send dimensions when requestDimensions is set");
+      return { body: createEmbeddingResponse(384) };
+    },
+    async ({ baseURL }) => {
+      const embedder = new Embedder({
+        provider: "openai-compatible",
+        apiKey: "test-key",
+        model: "text-embedding-3-small",
+        baseURL,
+        requestDimensions: 384,
+      });
+      await embedder.embedPassage("hello world");
+    },
+  );
+
   await withJsonServer(
     403,
     { error: { message: "Invalid API key", code: "invalid_api_key" } },

test/plugin-manifest-regression.mjs

@@ -17,6 +17,7 @@ Module._initPaths();
 
 const jiti = jitiFactory(import.meta.url, { interopDefault: true });
 const plugin = jiti("../index.ts");
+const resetRegistration = plugin.resetRegistration ?? (() => {});
 
 const manifest = JSON.parse(
   readFileSync(new URL("../openclaw.plugin.json", import.meta.url), "utf8"),
@@ -109,6 +110,15 @@ assert.equal(
   "boolean",
   "embedding.omitDimensions should be declared in the plugin schema",
 );
+assert.equal(
+  manifest.configSchema.properties.embedding.properties.requestDimensions?.type,
+  "integer",
+  "embedding.requestDimensions should be declared in the plugin schema",
+);
+assert.ok(
+  Object.prototype.hasOwnProperty.call(manifest.uiHints, "embedding.requestDimensions"),
+  "uiHints should expose embedding.requestDimensions",
+);
 assert.equal(
   manifest.configSchema.properties.sessionMemory.properties.enabled.default,
   false,
@@ -149,6 +159,7 @@ try {
     },
     { services },
   );
+  resetRegistration();
   plugin.register(api);
   assert.equal(services.length, 1, "plugin should register its background service");
   assert.equal(typeof api.hooks.agent_end, "function", "autoCapture should remain enabled by default");
@@ -171,6 +182,7 @@ try {
       dimensions: 1536,
     },
   });
+  resetRegistration();
   plugin.register(sessionDefaultApi);
   // selfImprovement registers command:new by default (#391), independent of sessionMemory config
   assert.equal(
@@ -192,6 +204,7 @@ try {
       dimensions: 1536,
     },
   });
+  resetRegistration();
   plugin.register(sessionEnabledApi);
   assert.equal(
     typeof sessionEnabledApi.hooks.before_reset,
@@ -265,6 +278,7 @@ try {
         chunking: false,
       },
     });
+    resetRegistration();
     plugin.register(chunkingOffApi);
     const chunkingOffTool = chunkingOffApi.toolFactories.memory_store({
       agentId: "main",
@@ -293,6 +307,7 @@ try {
         chunking: true,
       },
     });
+    resetRegistration();
     plugin.register(chunkingOnApi);
     const chunkingOnTool = chunkingOnApi.toolFactories.memory_store({
       agentId: "main",
@@ -320,21 +335,57 @@ try {
         dimensions: 4,
       },
     });
+    resetRegistration();
     plugin.register(withDimensionsApi);
     const withDimensionsTool = withDimensionsApi.toolFactories.memory_store({
       agentId: "main",
       sessionKey: "agent:main:test",
     });
     const requestCountBeforeWithDimensions = embeddingRequests.length;
     await withDimensionsTool.execute("tool-3", {
-      text: "dimensions should be sent by default",
+      text: "dimensions should stay internal by default",
       scope: "global",
     });
     const withDimensionsRequest = embeddingRequests.at(requestCountBeforeWithDimensions);
     assert.equal(
-      withDimensionsRequest?.dimensions,
+      Object.prototype.hasOwnProperty.call(withDimensionsRequest ?? {}, "dimensions"),
+      false,
+      "embedding.dimensions should be used for local schema sizing, not forwarded by default",
+    );
+
+    const withRequestDimensionsApi = createMockApi({
+      dbPath: path.join(workDir, "db-with-request-dimensions"),
+      autoCapture: false,
+      autoRecall: false,
+      embedding: {
+        provider: "openai-compatible",
+        apiKey: "dummy",
+        model: "text-embedding-3-small",
+        baseURL: embeddingBaseURL,
+        requestDimensions: 4,
+      },
+    });
+    resetRegistration();
+    plugin.register(withRequestDimensionsApi);
+    const withRequestDimensionsTool = withRequestDimensionsApi.toolFactories.memory_store({
+      agentId: "main",
+      sessionKey: "agent:main:test",
+    });
+    const requestCountBeforeRequestDimensions = embeddingRequests.length;
+    const withRequestDimensionsResult = await withRequestDimensionsTool.execute("tool-3b", {
+      text: "requestDimensions should drive both request payload and local schema size",
+      scope: "global",
+    });
+    assert.equal(
+      withRequestDimensionsResult.details.action,
+      "created",
+      "requestDimensions-only config should still create memories end-to-end",
+    );
+    const withRequestDimensionsRequest = embeddingRequests.at(requestCountBeforeRequestDimensions);
+    assert.equal(
+      withRequestDimensionsRequest?.dimensions,
       4,
-      "embedding.dimensions should be forwarded by default",
+      "embedding.requestDimensions should be forwarded to embedding requests",
     );
 
     const omitDimensionsApi = createMockApi({
@@ -346,10 +397,11 @@ try {
         apiKey: "dummy",
         model: "text-embedding-3-small",
         baseURL: embeddingBaseURL,
-        dimensions: 4,
+        requestDimensions: 4,
         omitDimensions: true,
       },
     });
+    resetRegistration();
     plugin.register(omitDimensionsApi);
     const omitDimensionsTool = omitDimensionsApi.toolFactories.memory_store({
       agentId: "main",
@@ -364,7 +416,7 @@ try {
     assert.equal(
       Object.prototype.hasOwnProperty.call(omitDimensionsRequest, "dimensions"),
       false,
-      "embedding.omitDimensions=true should omit dimensions from embedding requests",
+      "embedding.omitDimensions=true should omit dimensions from embedding requests even when requestDimensions is set",
     );
   } finally {
     await new Promise((resolve) => embeddingServer.close(resolve));

test/reflection-bypass-hook.test.mjs

@@ -17,6 +17,7 @@ const jiti = jitiFactory(import.meta.url, {
 
 const pluginModule = jiti("../index.ts");
 const memoryLanceDBProPlugin = pluginModule.default || pluginModule;
+const resetRegistration = pluginModule.resetRegistration ?? (() => {});
 const { MemoryStore } = jiti("../src/store.ts");
 const { storeReflectionToLanceDB } = jiti("../src/reflection-store.ts");
 
@@ -134,9 +135,11 @@ describe("reflection hooks tolerate bypass scope filters", () => {
 
   beforeEach(() => {
     workDir = mkdtempSync(path.join(tmpdir(), "reflection-bypass-hook-"));
+    resetRegistration();
   });
 
   afterEach(() => {
+    resetRegistration();
     rmSync(workDir, { recursive: true, force: true });
   });