@remnic/core 9.3.651 → 9.3.652

package/src/namespaces/search.test.ts

@@ -6,17 +6,22 @@ import type {
   SearchExecutionOptions,
   SearchQueryOptions,
 } from "../search/port.js";
+import type { QmdCapabilities, QmdVersionStatus } from "../qmd.js";
 import type { PluginConfig, QmdSearchResult } from "../types.js";
 
 type CollectionState = "present" | "missing" | "unknown" | "skipped";
 
 class FakeBackend implements SearchBackend {
   updates = 0;
+  disposed = 0;
+  available = true;
   calls: Array<{
     method: string;
     collection: string | undefined;
     maxResults: number | undefined;
   }> = [];
+  availabilitySignals: Array<AbortSignal | undefined> = [];
+  probeCalls = 0;
   ensureSignals: Array<AbortSignal | undefined> = [];
   ensureCollections: Array<string | undefined> = [];
   checkSignals: Array<AbortSignal | undefined> = [];
@@ -29,6 +34,11 @@ class FakeBackend implements SearchBackend {
       check?: CollectionState;
       ensure?: CollectionState;
     } = {},
+    private readonly daemonMode = false,
+    private readonly diagnostics: {
+      debugStatus?: string;
+      versionStatus?: QmdVersionStatus;
+    } = {},
   ) {}
 
   private limitedResults(maxResults: number | undefined): QmdSearchResult[] {
@@ -38,15 +48,33 @@ class FakeBackend implements SearchBackend {
   }
 
   async probe(): Promise<boolean> {
-    return true;
+    this.probeCalls += 1;
+    return this.available;
+  }
+
+  async checkAvailability(execution?: SearchExecutionOptions): Promise<boolean> {
+    this.availabilitySignals.push(execution?.signal);
+    return this.available;
   }
 
   isAvailable(): boolean {
-    return true;
+    return this.available;
   }
 
   debugStatus(): string {
-    return "fake";
+    return this.diagnostics.debugStatus ?? "fake";
+  }
+
+  isDaemonMode(): boolean {
+    return this.daemonMode;
+  }
+
+  getVersionStatus(): QmdVersionStatus | null {
+    return this.diagnostics.versionStatus ?? null;
+  }
+
+  async dispose(): Promise<void> {
+    this.disposed += 1;
   }
 
   async search(
@@ -154,6 +182,41 @@ function config(): PluginConfig {
   } as PluginConfig;
 }
 
+function qmdCapabilities(enabled: boolean): QmdCapabilities {
+  return {
+    version: enabled ? "2.5.3" : null,
+    parsedVersion: enabled ? [2, 5, 3] : null,
+    stableSdk: enabled,
+    unifiedSearch: enabled,
+    getDocumentBody: enabled,
+    maintenanceApi: enabled,
+    legacySkillInstall: enabled,
+    intentHints: enabled,
+    explainTraces: enabled,
+    candidateLimit: enabled,
+    v2McpQueryTool: enabled,
+    structuredSearches: enabled,
+    queryRerankToggle: enabled,
+    chunkStrategy: enabled,
+    qmdBench: enabled,
+    perCollectionModels: enabled,
+    jsonLineNumbers: enabled,
+    editorLinks: enabled,
+    doctor: enabled,
+    versionedSkills: enabled,
+    absoluteSnippetLines: enabled,
+    fullQueryOutput: enabled,
+    forceCpu: enabled,
+    gpuBackendOverride: enabled,
+    embedParallelism: enabled,
+    modelEnvConsistency: enabled,
+    scopedEmbed: enabled,
+    safeStatusDeviceProbe: enabled,
+    mcpIndexSelection: enabled,
+    outputFormatFlag: enabled,
+  };
+}
+
 test("updateNamespaces runs a global-update backend only once", async () => {
   const created: FakeBackend[] = [];
   const router = new NamespaceSearchRouter(
@@ -304,6 +367,198 @@ test("legacy default namespace root fail-opens missing guarded collections", asy
   assert.deepEqual(backend.ensureCollections, []);
 });
 
+test("healthForNamespace checks namespace collection without auto-creating or caching state", async () => {
+  const created: FakeBackend[] = [];
+  const router = new NamespaceSearchRouter(
+    config(),
+    { storageFor: async (namespace: string) => ({ dir: `/tmp/remnic/${namespace}` }) },
+    () => {
+      const backend = new FakeBackend(false, [], created.length === 0
+        ? { check: "missing" }
+        : { ensure: "present" });
+      created.push(backend);
+      return backend;
+    },
+  );
+
+  const health = await router.healthForNamespace("shared");
+
+  assert.equal(health.collectionState, "missing");
+  assert.equal(health.collection, "openclaw-engram--ns-736861726564");
+  assert.deepEqual(created[0]?.checkCollections, ["openclaw-engram--ns-736861726564"]);
+  assert.deepEqual(created[0]?.ensureCollections, []);
+  assert.equal(created[0]?.probeCalls, 0);
+  assert.equal(created[0]?.availabilitySignals.length, 1);
+  assert.equal(created[0]?.disposed, 1);
+
+  const ensured = await router.ensureNamespaceCollection("shared");
+
+  assert.equal(ensured, "present");
+  assert.equal(created.length, 2);
+  assert.deepEqual(created[1]?.ensureCollections, ["openclaw-engram--ns-736861726564"]);
+});
+
+test("healthForNamespace reports daemon mode from live cached namespace backend", async () => {
+  const created: FakeBackend[] = [];
+  const router = new NamespaceSearchRouter(
+    config(),
+    { storageFor: async (namespace: string) => ({ dir: `/tmp/remnic/${namespace}` }) },
+    () => {
+      const backend = created.length === 0
+        ? new FakeBackend(false, [
+          {
+            path: "facts/a.md",
+            docid: "a",
+            score: 1,
+            snippet: "a",
+          },
+        ], { ensure: "present" }, true, {
+          debugStatus: "live-daemon",
+          versionStatus: {
+            installedVersion: "qmd 2.5.3",
+            supportedVersion: "2.5.3",
+            supported: true,
+            newerThanSupported: false,
+            upgradeAvailable: false,
+            capabilities: qmdCapabilities(true),
+          },
+        })
+        : new FakeBackend(false, [], { check: "present" }, false, {
+          debugStatus: "probe-unavailable",
+          versionStatus: {
+            installedVersion: null,
+            supportedVersion: "2.5.3",
+            supported: false,
+            newerThanSupported: false,
+            upgradeAvailable: false,
+            capabilities: qmdCapabilities(false),
+          },
+        });
+      if (created.length === 1) {
+        backend.available = false;
+      }
+      created.push(backend);
+      return backend;
+    },
+  );
+
+  await router.searchAcrossNamespaces({
+    query: "a",
+    namespaces: ["shared"],
+    maxResults: 1,
+  });
+  const health = await router.healthForNamespace("shared");
+
+  assert.equal(health.available, true);
+  assert.equal(health.daemonMode, true);
+  assert.equal(health.debugStatus, "live-daemon");
+  assert.equal(health.installedVersion, "qmd 2.5.3");
+  assert.equal(health.supportedVersion, "2.5.3");
+  assert.equal(health.supported, true);
+  assert.equal(health.upgradeAvailable, false);
+  assert.equal(health.doctorAvailable, true);
+  assert.equal(health.collectionState, "unknown");
+  assert.equal(created.length, 2);
+  assert.equal(created[0]?.disposed, 0);
+  assert.equal(created[1]?.disposed, 1);
+  assert.deepEqual(created[1]?.checkCollections, []);
+});
+
+test("healthForNamespace preserves cached missing collection state", async () => {
+  const created: FakeBackend[] = [];
+  const router = new NamespaceSearchRouter(
+    config(),
+    { storageFor: async (namespace: string) => ({ dir: `/tmp/remnic/${namespace}` }) },
+    () => {
+      const backend = created.length === 0
+        ? new FakeBackend(false, [], { ensure: "missing" }, true)
+        : new FakeBackend(false, [], { check: "present" }, false);
+      created.push(backend);
+      return backend;
+    },
+  );
+
+  assert.deepEqual(
+    await router.searchAcrossNamespaces({
+      query: "a",
+      namespaces: ["shared"],
+      maxResults: 1,
+    }),
+    [],
+  );
+  const health = await router.healthForNamespace("shared");
+
+  assert.equal(health.available, true);
+  assert.equal(health.daemonMode, true);
+  assert.equal(health.collectionState, "missing");
+  assert.equal(created.length, 2);
+  assert.deepEqual(created[1]?.checkCollections, ["openclaw-engram--ns-736861726564"]);
+});
+
+test("healthForNamespace stops waiting when namespace availability probe aborts", async () => {
+  const backend = new class extends FakeBackend {
+    override async checkAvailability(execution?: SearchExecutionOptions): Promise<boolean> {
+      this.availabilitySignals.push(execution?.signal);
+      return await new Promise<boolean>(() => {});
+    }
+  }(false);
+  const router = new NamespaceSearchRouter(
+    config(),
+    { storageFor: async (namespace: string) => ({ dir: `/tmp/remnic/${namespace}` }) },
+    () => backend,
+  );
+  const controller = new AbortController();
+  controller.abort();
+
+  const health = await router.healthForNamespace("shared", {
+    signal: controller.signal,
+  });
+
+  assert.equal(health.available, false);
+  assert.equal(health.collectionState, "unknown");
+  assert.equal(backend.probeCalls, 0);
+  assert.equal(backend.availabilitySignals[0], controller.signal);
+  assert.deepEqual(backend.checkCollections, []);
+  assert.deepEqual(backend.ensureCollections, []);
+  assert.equal(backend.disposed, 1);
+});
+
+test("ensureNamespaceCollection does not cache aborted namespace backend probes", async () => {
+  const created: FakeBackend[] = [];
+  const router = new NamespaceSearchRouter(
+    config(),
+    { storageFor: async (namespace: string) => ({ dir: `/tmp/remnic/${namespace}` }) },
+    () => {
+      const backend = created.length === 0
+        ? new class extends FakeBackend {
+          override async probe(): Promise<boolean> {
+            return await new Promise<boolean>(() => {});
+          }
+        }(false)
+        : new FakeBackend(false, [], { ensure: "present" });
+      created.push(backend);
+      return backend;
+    },
+  );
+  const controller = new AbortController();
+  controller.abort();
+
+  await assert.rejects(
+    () => router.ensureNamespaceCollection("shared", { signal: controller.signal }),
+    /operation aborted/,
+  );
+
+  assert.equal(created[0]?.disposed, 1);
+  assert.deepEqual(created[0]?.checkCollections, []);
+  assert.deepEqual(created[0]?.ensureCollections, []);
+
+  const ensured = await router.ensureNamespaceCollection("shared");
+
+  assert.equal(ensured, "present");
+  assert.equal(created.length, 2);
+  assert.deepEqual(created[1]?.ensureCollections, ["openclaw-engram--ns-736861726564"]);
+});
+
 test("legacy default namespace root filters nested namespace search results", async () => {
   const router = new NamespaceSearchRouter(
     config(),

package/src/namespaces/search.ts

@@ -44,12 +44,32 @@ type NamespaceBackendRecord = {
   filtersNestedNamespaces: boolean;
 };
 
-type CollectionState = "present" | "missing" | "unknown" | "skipped";
+export type CollectionState = "present" | "missing" | "unknown" | "skipped";
+
+export interface NamespaceSearchHealth {
+  collection: string;
+  memoryDir: string;
+  available: boolean;
+  collectionState: CollectionState;
+  debugStatus: string;
+  installedVersion: string | null;
+  supportedVersion: string | null;
+  supported: boolean | null;
+  upgradeAvailable: boolean | null;
+  doctorAvailable: boolean | null;
+  daemonMode: boolean | null;
+}
 
 type NamespaceScopedSearchConfig = PluginConfig & {
   hostEmbeddingProviderScope?: string;
 };
 
+type BackendRecordOptions = {
+  autoCreateCollection: boolean;
+  abortAsUnavailable: boolean;
+  failOpenMissingGuardedCollection: boolean;
+};
+
 export class NamespaceSearchRouter {
   private readonly cache = new Map<string, Promise<NamespaceBackendRecord>>();
 
@@ -184,6 +204,67 @@ export class NamespaceSearchRouter {
     return record.collectionState;
   }
 
+  async healthForNamespace(
+    namespace: string,
+    execution?: SearchExecutionOptions,
+  ): Promise<NamespaceSearchHealth> {
+    const key = namespace.trim() || this.config.defaultNamespace;
+    const record = await this.createBackendRecordFor(
+      key,
+      execution,
+      {
+        autoCreateCollection: false,
+        abortAsUnavailable: true,
+        failOpenMissingGuardedCollection: false,
+      },
+    );
+    try {
+      const liveRecord = await this.liveCachedRecordForHealth(key, record, execution);
+      const diagnosticBackend = liveRecord?.backend ?? record.backend;
+      const versionStatus =
+        "getVersionStatus" in diagnosticBackend &&
+        typeof diagnosticBackend.getVersionStatus === "function"
+          ? diagnosticBackend.getVersionStatus()
+          : null;
+      const daemonMode = daemonModeForBackend(diagnosticBackend);
+      const collectionState =
+        liveRecord?.collectionState === "missing"
+          ? "missing"
+          : record.collectionState;
+
+      return {
+        collection: record.collection,
+        memoryDir: record.memoryDir,
+        available: liveRecord?.available ?? record.available,
+        collectionState,
+        debugStatus: diagnosticBackend.debugStatus(),
+        installedVersion: versionStatus?.installedVersion ?? null,
+        supportedVersion: versionStatus?.supportedVersion ?? null,
+        supported: versionStatus?.supported ?? null,
+        upgradeAvailable: versionStatus?.upgradeAvailable ?? null,
+        doctorAvailable: versionStatus?.capabilities?.doctor ?? null,
+        daemonMode,
+      };
+    } finally {
+      const dispose = (record.backend as { dispose?: () => void | Promise<void> }).dispose;
+      await dispose?.call(record.backend);
+    }
+  }
+
+  private async liveCachedRecordForHealth(
+    key: string,
+    disposableRecord: NamespaceBackendRecord,
+    execution?: SearchExecutionOptions,
+  ): Promise<NamespaceBackendRecord | null> {
+    const pending = this.cache.get(key);
+    if (!pending) return null;
+    const cachedRecord = await awaitWithAbort(pending, execution?.signal).catch(() => null);
+    if (!cachedRecord) return null;
+    if (cachedRecord.collection !== disposableRecord.collection) return null;
+    if (cachedRecord.memoryDir !== disposableRecord.memoryDir) return null;
+    return cachedRecord;
+  }
+
   /** Clear cached backend records so the next access re-probes availability. */
   clearCache(): void {
     this.cache.clear();
@@ -211,31 +292,69 @@ export class NamespaceSearchRouter {
     const existing = this.cache.get(key);
     if (existing) return await existing;
 
-    const pending = (async (): Promise<NamespaceBackendRecord> => {
-      const storage = await this.storageRouter.storageFor(key);
-      const useLegacyDefaultCollection =
-        key === this.config.defaultNamespace && storage.dir === this.config.memoryDir;
-      const filtersNestedNamespaces =
-        this.config.namespacesEnabled === true && useLegacyDefaultCollection;
-      const rootHostEmbeddingScope =
-        (this.config as NamespaceScopedSearchConfig).hostEmbeddingProviderScope ??
-        this.config.memoryDir;
-      const scopedConfig: NamespaceScopedSearchConfig = {
-        ...this.config,
-        memoryDir: storage.dir,
-        hostEmbeddingProviderScope: rootHostEmbeddingScope,
-        qmdCollection: namespaceCollectionName(this.config.qmdCollection, key, {
-          defaultNamespace: this.config.defaultNamespace,
-          useLegacyDefaultCollection,
-        }),
-      };
+    const pending = this.createBackendRecordFor(key, execution, {
+      autoCreateCollection: true,
+      abortAsUnavailable: false,
+      failOpenMissingGuardedCollection: true,
+    }).catch((error) => {
+      this.cache.delete(key);
+      throw error;
+    });
+
+    this.cache.set(key, pending);
+    return await pending;
+  }
+
+  private async createBackendRecordFor(
+    namespace: string,
+    execution: SearchExecutionOptions | undefined,
+    options: BackendRecordOptions,
+  ): Promise<NamespaceBackendRecord> {
+    const key = namespace.trim() || this.config.defaultNamespace;
+    const storage = await this.storageRouter.storageFor(key);
+    const useLegacyDefaultCollection =
+      key === this.config.defaultNamespace && storage.dir === this.config.memoryDir;
+    const filtersNestedNamespaces =
+      this.config.namespacesEnabled === true && useLegacyDefaultCollection;
+    const rootHostEmbeddingScope =
+      (this.config as NamespaceScopedSearchConfig).hostEmbeddingProviderScope ??
+      this.config.memoryDir;
+    const scopedConfig: NamespaceScopedSearchConfig = {
+      ...this.config,
+      memoryDir: storage.dir,
+      hostEmbeddingProviderScope: rootHostEmbeddingScope,
+      qmdCollection: namespaceCollectionName(this.config.qmdCollection, key, {
+        defaultNamespace: this.config.defaultNamespace,
+        useLegacyDefaultCollection,
+      }),
+    };
 
-      const backend = this.createBackend(scopedConfig);
-      const available = await backend.probe().catch(() => false);
+    const backend = this.createBackend(scopedConfig);
+    try {
+      const availabilityProbe =
+        options.autoCreateCollection || typeof backend.checkAvailability !== "function"
+          ? backend.probe()
+          : backend.checkAvailability({ signal: execution?.signal });
+      const available = await awaitWithAbort(availabilityProbe, execution?.signal).catch((error) => {
+        if (error instanceof NamespaceSearchAbortError && !options.abortAsUnavailable) {
+          throw error;
+        }
+        return false;
+      });
       const collectionState = available
-        ? await this.collectionStateForBackend(backend, storage.dir, scopedConfig.qmdCollection, {
-          skipAutoCreate: filtersNestedNamespaces,
-          execution,
+        ? await awaitWithAbort(
+          this.collectionStateForBackend(backend, storage.dir, scopedConfig.qmdCollection, {
+            autoCreate: options.autoCreateCollection,
+            failOpenMissingGuardedCollection: options.failOpenMissingGuardedCollection,
+            skipAutoCreate: filtersNestedNamespaces,
+            execution,
+          }),
+          execution?.signal,
+        ).catch((error) => {
+          if (error instanceof NamespaceSearchAbortError && !options.abortAsUnavailable) {
+            throw error;
+          }
+          return "unknown" as const;
         })
         : "unknown";
       return {
@@ -246,10 +365,13 @@ export class NamespaceSearchRouter {
         collectionState,
         filtersNestedNamespaces,
       };
-    })();
-
-    this.cache.set(key, pending);
-    return await pending;
+    } catch (error) {
+      const dispose = (backend as { dispose?: () => void | Promise<void> }).dispose;
+      if (dispose) {
+        await Promise.resolve(dispose.call(backend)).catch(() => {});
+      }
+      throw error;
+    }
   }
 
   private async collectionStateForBackend(
@@ -257,21 +379,47 @@ export class NamespaceSearchRouter {
     memoryDir: string,
     collection: string,
     options: {
+      autoCreate: boolean;
+      failOpenMissingGuardedCollection: boolean;
       skipAutoCreate: boolean;
       execution?: SearchExecutionOptions;
     },
   ): Promise<CollectionState> {
-    if (options.skipAutoCreate) {
+    if (!options.autoCreate || options.skipAutoCreate) {
       if (!backend.checkCollection) return "unknown";
       const collectionState = await backend
         .checkCollection(collection, options.execution)
         .catch(() => "unknown" as const);
-      return collectionState === "missing" ? "unknown" : collectionState;
+      return options.failOpenMissingGuardedCollection && collectionState === "missing"
+        ? "unknown"
+        : collectionState;
     }
     return await backend.ensureCollection(memoryDir, collection, options.execution).catch(() => "unknown" as const);
   }
 }
 
+class NamespaceSearchAbortError extends Error {
+  constructor() {
+    super("operation aborted");
+  }
+}
+
+function awaitWithAbort<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return operation;
+  if (signal.aborted) return Promise.reject(new NamespaceSearchAbortError());
+
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      signal.removeEventListener("abort", onAbort);
+      reject(new NamespaceSearchAbortError());
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(resolve, reject).finally(() => {
+      signal.removeEventListener("abort", onAbort);
+    });
+  });
+}
+
 function filterNamespaceSubtreeResults(
   record: NamespaceBackendRecord,
   results: QmdSearchResult[],
@@ -294,6 +442,12 @@ function backendSearchLimit(
   );
 }
 
+function daemonModeForBackend(backend: SearchBackend): boolean | null {
+  return "isDaemonMode" in backend && typeof backend.isDaemonMode === "function"
+    ? backend.isDaemonMode() === true
+    : null;
+}
+
 function pathIsInsideNamespaceSubtree(
   memoryDir: string,
   collection: string,

package/src/orchestrator.ts

@@ -311,7 +311,10 @@ import {
   resolveCodingNamespaceOverlay,
 } from "./coding/coding-namespace.js";
 import type { CodingContext } from "./types.js";
-import { NamespaceSearchRouter } from "./namespaces/search.js";
+import {
+  NamespaceSearchRouter,
+  type NamespaceSearchHealth,
+} from "./namespaces/search.js";
 import { SharedContextManager } from "./shared-context/manager.js";
 import {
   CompoundingEngine,
@@ -2324,6 +2327,13 @@ export class Orchestrator {
     });
   }
 
+  async searchHealthForNamespace(
+    namespace: string,
+    execution?: SearchExecutionOptions,
+  ): Promise<NamespaceSearchHealth> {
+    return await this.namespaceSearchRouter.healthForNamespace(namespace, execution);
+  }
+
   private isSearchAvailableForNamespaceRouting(): boolean {
     if (this.config.namespacesEnabled) return true;
     return this.qmd.isAvailable();