@harborclient/team-hub 0.4.2 → 0.4.3

package/dist/cli.js

@@ -21,9 +21,22 @@ import { Command as Command2 } from "commander";
 
 // src/config/serverConfig.ts
 import { existsSync, readFileSync } from "fs";
-import path from "path";
+import path2 from "path";
 import { parse as parseYaml } from "yaml";
 
+// src/config/docsConfig.ts
+import path from "path";
+var DEFAULT_DOCS_SEARCH_INDEX_PATH = "/app/data/docsSearchIndex.json";
+function resolveDocsSearchIndexPath(searchIndexPath) {
+  return path.isAbsolute(searchIndexPath) ? searchIndexPath : path.resolve(process.cwd(), searchIndexPath);
+}
+function normalizeDocsConfig(section) {
+  const trimmed = section.searchIndexPath?.trim();
+  return {
+    searchIndexPath: trimmed && trimmed.length > 0 ? trimmed : DEFAULT_DOCS_SEARCH_INDEX_PATH
+  };
+}
+
 // src/config/llmConfig.ts
 function headerRowsFromSingleKeyObject(record) {
   const rows = [];
@@ -176,6 +189,9 @@ var pluginsSectionSchema = z.object({
   catalogs: z.array(z.string().trim().url()).optional(),
   trusted: z.array(z.string().trim().url()).optional()
 });
+var docsSectionSchema = z.object({
+  searchIndexPath: z.string().trim().min(1).optional()
+});
 var logLevelSchema = z.enum(["debug", "info", "warn", "error"]);
 var loggingSectionSchema = z.object({
   level: logLevelSchema.optional(),
@@ -188,6 +204,7 @@ var serverConfigDocumentSchema = z.object({
   redis: redisSectionSchema,
   llm: llmSectionSchema.optional(),
   plugins: pluginsSectionSchema.optional(),
+  docs: docsSectionSchema.optional(),
   logging: loggingSectionSchema.optional()
 });
 
@@ -205,7 +222,7 @@ var ConfigError = class extends Error {
   }
 };
 function resolveConfigPath(configPath) {
-  return path.isAbsolute(configPath) ? configPath : path.resolve(process.cwd(), configPath);
+  return path2.isAbsolute(configPath) ? configPath : path2.resolve(process.cwd(), configPath);
 }
 function assertDocumentShape(document) {
   if (document === null || typeof document !== "object" || Array.isArray(document)) {
@@ -288,6 +305,14 @@ function parseServerConfig(document) {
     }
     plugins = normalizePluginsConfig(parsedPluginsSection.data);
   }
+  let docs = null;
+  if (root.docs !== void 0) {
+    const parsedDocsSection = docsSectionSchema.safeParse(root.docs);
+    if (!parsedDocsSection.success) {
+      throw new ConfigError(formatZodError(parsedDocsSection.error));
+    }
+    docs = normalizeDocsConfig(parsedDocsSection.data);
+  }
   let logging = DEFAULT_LOGGING_CONFIG;
   if (root.logging !== void 0) {
     const parsedLoggingSection = loggingSectionSchema.safeParse(root.logging);
@@ -303,6 +328,7 @@ function parseServerConfig(document) {
     redis: parsedRedisSection.data,
     llm,
     plugins,
+    docs,
     logging
   };
 }
@@ -6470,6 +6496,14 @@ var LLM_MODEL_CATALOG = [
 function hasProviderKey(config, provider) {
   return Boolean(config.providers[provider]?.apiKey.trim());
 }
+function hasHubOpenAiProvider(config) {
+  return hasProviderKey(config, "openai");
+}
+function getHubLlmCapabilities(config) {
+  return {
+    openai: hasProviderKey(config, "openai")
+  };
+}
 function listHubOfferedModels(config) {
   const allowList = config.models ? new Set(config.models) : null;
   return LLM_MODEL_CATALOG.filter((model) => {
@@ -7285,8 +7319,12 @@ var llmModelSchema = z7.object({
   label: z7.string(),
   provider: z7.enum(["openai", "claude", "gemini"])
 });
+var llmCapabilitiesSchema = z7.object({
+  openai: z7.boolean()
+});
 var listLlmModelsResponseSchema = z7.object({
-  models: z7.array(llmModelSchema)
+  models: z7.array(llmModelSchema),
+  capabilities: llmCapabilitiesSchema
 });
 var llmUsageSummaryResponseSchema = z7.object({
   period: z7.string(),
@@ -7637,7 +7675,7 @@ var listAdminTokensResponseSchema = z9.object({
   tokens: z9.array(hubApiTokenRecordSchema)
 });
 var reloadConfigSectionResultSchema = z9.object({
-  section: z9.enum(["db", "redis", "llm", "plugins", "server"]),
+  section: z9.enum(["db", "redis", "llm", "plugins", "docs", "server"]),
   status: z9.enum(["reloaded", "unchanged", "failed", "restart-required"]),
   error: z9.string().optional()
 });
@@ -8377,7 +8415,7 @@ async function registerAdminRoutes(app, options) {
         label: model.label,
         provider: model.provider
       }));
-      return reply.send({ models });
+      return reply.send({ models, capabilities: getHubLlmCapabilities(llm) });
     }
   });
   routes.route({
@@ -9832,6 +9870,165 @@ async function runLlmCompletion(config, input) {
   return parseCompletionResponse(json);
 }
 
+// src/server/docs/docsSearch.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import path3 from "path";
+import { create, load, search } from "@orama/orama";
+import OpenAI from "openai";
+var DOCS_EMBEDDING_MODEL = "text-embedding-3-small";
+var DOCS_EMBEDDING_DIMENSIONS = 1536;
+var DEFAULT_RESULT_LIMIT = 5;
+var MAX_RESULT_LIMIT = 10;
+var DEFAULT_SIMILARITY = 0.5;
+var SNIPPET_MAX_CHARS = 600;
+var DOCS_SEARCH_SCHEMA = {
+  id: "string",
+  source: "string",
+  path: "string",
+  url: "string",
+  title: "string",
+  heading: "string",
+  content: "string",
+  embedding: `vector[${DOCS_EMBEDDING_DIMENSIONS}]`
+};
+var cachedDb = null;
+var indexUnavailable = false;
+function getDocsSearchIndexPaths(docsConfig) {
+  const paths = /* @__PURE__ */ new Set();
+  if (docsConfig?.searchIndexPath) {
+    paths.add(resolveDocsSearchIndexPath(docsConfig.searchIndexPath));
+  }
+  paths.add(DEFAULT_DOCS_SEARCH_INDEX_PATH);
+  paths.add(path3.resolve(process.cwd(), "data/docsSearchIndex.json"));
+  return [...paths];
+}
+function isDocsSearchIndexAvailable(docsConfig) {
+  return getDocsSearchIndexPaths(docsConfig).some((candidate) => existsSync2(candidate));
+}
+function truncateSnippet(content, maxChars = SNIPPET_MAX_CHARS) {
+  if (content.length <= maxChars) {
+    return content;
+  }
+  return `${content.slice(0, maxChars)}...`;
+}
+function clampResultLimit(limit) {
+  if (limit == null || !Number.isFinite(limit)) {
+    return DEFAULT_RESULT_LIMIT;
+  }
+  return Math.min(Math.max(1, Math.floor(limit)), MAX_RESULT_LIMIT);
+}
+function loadDocsSearchIndex(docsConfig, paths) {
+  if (cachedDb != null) {
+    return cachedDb;
+  }
+  if (indexUnavailable) {
+    throw new Error(
+      "Documentation search index is not available. Deploy docsSearchIndex.json to the Team Hub server."
+    );
+  }
+  const candidates = paths ?? getDocsSearchIndexPaths(docsConfig);
+  const catalogPath = candidates.find((candidate) => existsSync2(candidate));
+  if (catalogPath == null) {
+    indexUnavailable = true;
+    throw new Error(
+      "Documentation search index is not available. Deploy docsSearchIndex.json to the Team Hub server."
+    );
+  }
+  const raw = JSON.parse(readFileSync3(catalogPath, "utf8"));
+  const db = create({ schema: DOCS_SEARCH_SCHEMA });
+  load(db, raw);
+  cachedDb = db;
+  return db;
+}
+async function embedDocsQuery(query, apiKey) {
+  const client = new OpenAI({ apiKey });
+  const response = await client.embeddings.create({
+    model: DOCS_EMBEDDING_MODEL,
+    input: query
+  });
+  const embedding = response.data[0]?.embedding;
+  if (!Array.isArray(embedding) || embedding.length !== DOCS_EMBEDDING_DIMENSIONS) {
+    throw new Error("Unexpected embedding size from OpenAI.");
+  }
+  return embedding;
+}
+async function searchDocs(llmConfig, docsConfig, args) {
+  const query = args.query?.trim();
+  if (!query) {
+    throw new Error("query is required.");
+  }
+  const apiKey = llmConfig.providers.openai?.apiKey.trim();
+  if (!apiKey) {
+    throw new Error(
+      "OpenAI provider is not configured on this Team Hub. Documentation search requires an OpenAI API key."
+    );
+  }
+  const db = loadDocsSearchIndex(docsConfig);
+  const embedding = await embedDocsQuery(query, apiKey);
+  const limit = clampResultLimit(args.limit);
+  const results = search(db, {
+    mode: "vector",
+    vector: {
+      value: embedding,
+      property: "embedding"
+    },
+    similarity: DEFAULT_SIMILARITY,
+    limit,
+    ...args.source != null ? { where: { source: args.source } } : {}
+  });
+  const resolved = results instanceof Promise ? await results : results;
+  return resolved.hits.map((hit) => {
+    const document = hit.document;
+    return {
+      title: document.title,
+      heading: document.heading,
+      url: document.url,
+      source: document.source,
+      path: document.path,
+      score: hit.score,
+      snippet: truncateSnippet(document.content)
+    };
+  });
+}
+
+// src/server/llm/hubNativeTools.ts
+var HUB_NATIVE_TOOL_NAMES = ["search_docs"];
+function isHubNativeToolName(name) {
+  return HUB_NATIVE_TOOL_NAMES.includes(name);
+}
+function canExecuteHubDocsSearch(llmConfig, docsConfig) {
+  if (!llmConfig || !hasHubOpenAiProvider(llmConfig)) {
+    return false;
+  }
+  return isDocsSearchIndexAvailable(docsConfig);
+}
+function filterClientToolsForHub(tools, llmConfig, docsConfig) {
+  if (!tools || tools.length === 0) {
+    return tools;
+  }
+  if (canExecuteHubDocsSearch(llmConfig, docsConfig)) {
+    return tools;
+  }
+  const filtered = tools.filter((tool) => {
+    const name = tool.function?.name;
+    return name !== "search_docs";
+  });
+  return filtered.length > 0 ? filtered : void 0;
+}
+async function callHubNativeTool(name, args, llmConfig, docsConfig) {
+  if (name !== "search_docs") {
+    return JSON.stringify({ error: `Unknown hub-native tool: ${name}` });
+  }
+  try {
+    const parsed = args;
+    const hits = await searchDocs(llmConfig, docsConfig, parsed);
+    return JSON.stringify(hits);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Documentation search failed.";
+    return JSON.stringify({ error: message });
+  }
+}
+
 // src/server/llm/hubMcpToolNames.ts
 var HUB_MCP_TOOL_PREFIX = "hubmcp__";
 function encodeHubMcpToolName(serverIndex, toolName) {
@@ -10025,14 +10222,16 @@ function parseToolArguments(raw) {
     return {};
   }
 }
-async function runHubChatStep(config, input, deps = {}) {
+async function runHubChatStep(config, input, deps = {}, docsConfig = null) {
   const runCompletion = deps.runCompletion ?? runLlmCompletion;
   const ensureConnections = deps.ensureConnections ?? ensureHubMcpConnections;
   const listTools = deps.listTools ?? listHubMcpTools;
   const callTool = deps.callTool ?? callHubMcpTool;
+  const callNativeTool = deps.callNativeTool ?? callHubNativeTool;
   await ensureConnections(config);
   const hubTools = listTools();
-  const mergedTools = hubTools.length > 0 || (input.tools?.length ?? 0) > 0 ? [...hubTools, ...input.tools ?? []] : void 0;
+  const clientTools = filterClientToolsForHub(input.tools, config, docsConfig);
+  const mergedTools = hubTools.length > 0 || (clientTools?.length ?? 0) > 0 ? [...hubTools, ...clientTools ?? []] : void 0;
   let messages = [...input.messages];
   let usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
   let lastContent = null;
@@ -10052,8 +10251,11 @@ async function runHubChatStep(config, input, deps = {}) {
         usage
       };
     }
+    const nativeCalls = toolCalls.filter((call) => isHubNativeToolName(call.name));
     const hubCalls = toolCalls.filter((call) => isHubMcpToolName(call.name));
-    const passthroughCalls = toolCalls.filter((call) => !isHubMcpToolName(call.name));
+    const passthroughCalls = toolCalls.filter(
+      (call) => !isHubNativeToolName(call.name) && !isHubMcpToolName(call.name)
+    );
     if (passthroughCalls.length > 0) {
       return {
         content: result.content,
@@ -10061,14 +10263,28 @@ async function runHubChatStep(config, input, deps = {}) {
         usage
       };
     }
+    const serverCalls = [...nativeCalls, ...hubCalls];
     messages = [
       ...messages,
       {
         role: "assistant",
         content: result.content,
-        tool_calls: hubCalls
+        tool_calls: serverCalls
       }
     ];
+    for (const call of nativeCalls) {
+      const toolResult = await callNativeTool(
+        call.name,
+        parseToolArguments(call.arguments),
+        config,
+        docsConfig
+      );
+      messages.push({
+        role: "tool",
+        tool_call_id: call.id,
+        content: toolResult
+      });
+    }
     for (const call of hubCalls) {
       const toolResult = await callTool(call.name, parseToolArguments(call.arguments));
       messages.push({
@@ -10127,7 +10343,8 @@ async function registerLlmRoutes(app, options) {
           id: model.id,
           label: model.label,
           provider: model.provider
-        }))
+        })),
+        capabilities: getHubLlmCapabilities(llm)
       });
     }
   });
@@ -10201,12 +10418,17 @@ async function registerLlmRoutes(app, options) {
       if (isNewTurn && isOverMonthlyLimit(totalTokens, user.llmMonthlyTokenLimit)) {
         return sendMonthlyLimitExceeded(reply);
       }
-      const result = await runHubChatStep(llm, {
-        model,
-        messages,
-        tools,
-        systemPrompt
-      });
+      const result = await runHubChatStep(
+        llm,
+        {
+          model,
+          messages,
+          tools,
+          systemPrompt
+        },
+        {},
+        options.getDocs()
+      );
       const catalogModel = getHubModelById(model);
       if (!catalogModel) {
         throw new Error(`Unknown hub model: ${model}`);
@@ -10353,7 +10575,11 @@ async function registerProtectedRoutes(app, options) {
   await registerFolderRoutes(app, options.db);
   await registerRequestRoutes(app, options.db);
   await registerRunResultRoutes(app, options.db);
-  await registerLlmRoutes(app, { db: options.db, getLlm: options.getLlm });
+  await registerLlmRoutes(app, {
+    db: options.db,
+    getLlm: options.getLlm,
+    getDocs: options.getDocs
+  });
   await registerPluginsRoutes(app, { getPlugins: options.getPlugins });
 }
 async function registerRoutes(app, options) {
@@ -10388,6 +10614,7 @@ async function createServer(ctxOrConfig, options = {}) {
     throttleStore,
     getLlm: ctx ? () => ctx.getLlm() : () => legacyConfig?.llm ?? null,
     getPlugins: ctx ? () => ctx.getPlugins() : () => legacyConfig?.plugins ?? null,
+    getDocs: ctx ? () => ctx.getDocs() : () => legacyConfig?.docs ?? null,
     reloadConfig: options.reloadConfig ?? (async () => ({ sections: [] }))
   });
   return app;
@@ -10574,7 +10801,8 @@ function createRuntimeContext(config, configPath) {
     dbHolder: { underlying: createDatabase(config.db) },
     throttleHolder: { underlying: createThrottleStore(config.redis) },
     llm: config.llm,
-    plugins: config.plugins
+    plugins: config.plugins,
+    docs: config.docs
   };
   const ctx = {
     configPath: state.configPath,
@@ -10588,6 +10816,7 @@ function createRuntimeContext(config, configPath) {
     throttleStore: createSwappableProxy(state.throttleHolder),
     getLlm: () => state.llm,
     getPlugins: () => state.plugins,
+    getDocs: () => state.docs,
     logger: createLogger(config.logging)
   };
   runtimeContextStates.set(ctx, state);
@@ -10661,6 +10890,8 @@ async function reloadRuntimeConfig(ctx) {
   sections.push({ section: "llm", status: "reloaded" });
   state.plugins = nextConfig.plugins;
   sections.push({ section: "plugins", status: "reloaded" });
+  state.docs = nextConfig.docs;
+  sections.push({ section: "docs", status: "reloaded" });
   sections.push(reloadServerSection(state, nextConfig));
   return { sections };
 }