refactor(semantic-search): introduce backend contract

apps/host-cloudflare/src/plugins.ts

@@ -14,6 +14,7 @@ import { serviceTokensPlugin } from "@executor-js/plugin-service-tokens/server";
 import { semanticSearchHttpPlugin } from "@executor-js/plugin-semantic-search/api";
 import {
   makeVectorizeStore,
+  ToolSearchBackend,
   withCloudflareLimits,
   type VectorizeIndex,
 } from "@executor-js/plugin-semantic-search";
@@ -51,6 +52,14 @@ export const makeCloudflarePlugins = (
   searchNamespace?: string,
 ) => {
   const store = vectorize ? withCloudflareLimits(makeVectorizeStore(vectorize)) : undefined;
+  const semanticSearchBackend =
+    store && geminiApiKey
+      ? ToolSearchBackend.vector({
+          store,
+          geminiApiKey,
+          namespace: searchNamespace,
+        })
+      : undefined;
   return [
     openApiHttpPlugin(),
     googleHttpPlugin(),
@@ -62,7 +71,7 @@ export const makeCloudflarePlugins = (
       observer: () => (analytics ? createWaeMetricsObserver(analytics) : noopExecutionObserver),
     }),
     serviceTokensPlugin(),
-    semanticSearchHttpPlugin({ store, geminiApiKey, namespace: searchNamespace }),
+    semanticSearchHttpPlugin({ backend: semanticSearchBackend }),
   ] as const;
 };
 

packages/plugins/semantic-search/src/sdk/index.ts

@@ -3,6 +3,17 @@ export {
   type SemanticSearchPluginOptions,
   type SemanticSearchExtension,
 } from "./plugin";
+export {
+  ToolSearchBackend,
+  makeVectorToolSearchBackend,
+  type SemanticSearchRefreshResult,
+  type SemanticSearchResultPage,
+  type SemanticSearchStatus,
+  type ToolSearchBackend as ToolSearchBackendType,
+  type ToolSearchBackendFactory,
+  type VectorToolSearchBackendStorage,
+  type VectorToolSearchBackendOptions,
+} from "./tool-search-backend";
 export { makeVectorToolDiscoveryProvider } from "./provider";
 export {
   makeGeminiEmbedder,

packages/plugins/semantic-search/src/sdk/plugin.test.ts

@@ -3,8 +3,9 @@ import { Effect } from "effect";
 
 import type { ToolDiscoveryProvider, ToolDiscoveryResult } from "@executor-js/sdk/core";
 
-import { makeWholeChunker } from "./chunker";
-import { makeSemanticSearchExtension } from "./plugin";
+import { SemanticSearchError } from "./errors";
+import { makeSemanticSearchExtension, semanticSearchPlugin } from "./plugin";
+import type { ToolSearchBackend, ToolSearchBackendFactory } from "./tool-search-backend";
 
 // A result whose integration/path is NOT the tenant id. This is exactly the case
 // the bug broke: the operator search defaulted the integration-prefix filter to
@@ -23,18 +24,33 @@ const githubItem: ToolDiscoveryResult = {
 // by `search` (they drive indexing), so they stay undefined.
 const extensionWith = (provider: ToolDiscoveryProvider) =>
   makeSemanticSearchExtension({
-    namespace: "default", // tenant id — NOT a tool prefix
-    embedder: undefined,
-    store: undefined,
-    chunker: makeWholeChunker(),
-    fingerprints: undefined,
-    indexRuns: undefined,
-    indexJobs: undefined,
-    indexChunks: undefined,
-    blobs: undefined,
-    owner: undefined,
-    lexicalStore: undefined,
-    provider,
+    backend: {
+      namespace: "default", // tenant id — NOT a tool prefix
+      provider,
+      index: () => undefined as never,
+      reindex: () => Effect.die("unused"),
+      sweep: () => Effect.die("unused"),
+      search: (executor, input) =>
+        provider
+          .searchTools({
+            executor,
+            query: input.query,
+            namespace: input.namespace,
+            limit: input.limit ?? 20,
+            offset: 0,
+          })
+          .pipe(
+            Effect.map((page) => ({
+              namespace: "default",
+              query: input.query,
+              items: page.items,
+            })),
+            Effect.mapError(
+              (cause) => new SemanticSearchError({ message: "Test provider failed.", cause }),
+            ),
+          ),
+      status: () => Effect.die("unused"),
+    },
   });
 
 describe("makeSemanticSearchExtension — search namespace handling", () => {
@@ -83,3 +99,37 @@ describe("makeSemanticSearchExtension — search namespace handling", () => {
     }),
   );
 });
+
+describe("semanticSearchPlugin — backend storage", () => {
+  it("registers and builds storage through the selected backend", () => {
+    const pluginStorage = {};
+    const backendStorage = { marker: true };
+    let receivedStorage: unknown;
+
+    const backend: ToolSearchBackend = {
+      namespace: "default",
+      index: () => undefined as never,
+      reindex: () => Effect.die("unused"),
+      sweep: () => Effect.die("unused"),
+      search: () => Effect.die("unused"),
+      status: () => Effect.die("unused"),
+    };
+    const factory: ToolSearchBackendFactory<typeof backendStorage> = {
+      namespace: "default",
+      pluginStorage,
+      storage: () => backendStorage,
+      build: ({ storage }) => {
+        receivedStorage = storage;
+        return backend;
+      },
+    };
+
+    const plugin = semanticSearchPlugin({ backend: factory });
+    const storage = plugin.storage(undefined as never);
+    plugin.extension?.({ storage } as never);
+
+    expect(plugin.pluginStorage).toBe(pluginStorage);
+    expect(storage.backend).toBe(backendStorage);
+    expect(receivedStorage).toBe(backendStorage);
+  });
+});