@harborclient/team-hub 0.4.1 → 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
   };
 }
@@ -364,6 +390,7 @@ var REQUESTS_COLLECTION = "requests";
 var AUDIT_LOG_COLLECTION = "auditLog";
 var LLM_USAGE_COLLECTION = "llmUsage";
 var LLM_USAGE_LOG_COLLECTION = "llmUsageLog";
+var RUN_RESULTS_COLLECTION = "runResults";
 var WRITE_BATCH_LIMIT = 500;
 
 // src/db/systemUsers.ts
@@ -400,7 +427,7 @@ var firestoreConfigSchema = z2.object({
 
 // src/db/firestore/utils.ts
 function parseAuditEntityType(value) {
-  if (value === "user" || value === "api_token" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request") {
+  if (value === "user" || value === "api_token" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
     return value;
   }
   throw new Error(`Invalid audit entity type: ${value}`);
@@ -544,6 +571,19 @@ function mapFirestoreRequest(id, data) {
     updatedByUserId: data.updatedByUserId ?? null
   };
 }
+function mapFirestoreRunResult(id, data) {
+  return {
+    id,
+    kind: data.kind,
+    label: data.label,
+    collectionName: data.collectionName,
+    requestName: data.requestName,
+    summary: data.summary,
+    payload: data.payload,
+    createdAt: data.createdAt,
+    createdByUserId: data.createdByUserId ?? null
+  };
+}
 function mapFirestoreAuditLog(id, data) {
   return {
     id,
@@ -557,6 +597,53 @@ function mapFirestoreAuditLog(id, data) {
   };
 }
 
+// src/db/runResultPayload.ts
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function summarizeResultRows(results) {
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+  for (const row of results) {
+    if (!isRecord(row)) {
+      continue;
+    }
+    const status = row.status;
+    if (status === "passed") {
+      passed += 1;
+    } else if (status === "failed") {
+      failed += 1;
+    } else if (status === "skipped") {
+      skipped += 1;
+    }
+  }
+  return { passed, failed, skipped };
+}
+function buildDefaultRunResultLabel(metadata) {
+  const target = metadata.requestName ?? metadata.collectionName ?? "Run";
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 19);
+  return `${target} \u2014 ${timestamp}`;
+}
+function parseRunResultPayload(payload) {
+  const kind = payload.harborclientExport;
+  if (kind !== "collection-run-results" && kind !== "request-run-results") {
+    throw new Error("Invalid run result payload: harborclientExport is required");
+  }
+  const results = payload.results;
+  if (!Array.isArray(results) || results.length === 0) {
+    throw new Error("Invalid run result payload: results are required");
+  }
+  const collection = isRecord(payload.collection) ? payload.collection : void 0;
+  const request = isRecord(payload.request) ? payload.request : void 0;
+  return {
+    kind,
+    collectionName: typeof collection?.name === "string" ? collection.name : null,
+    requestName: typeof request?.name === "string" ? request.name : null,
+    summary: summarizeResultRows(results)
+  };
+}
+
 // src/db/trimRequiredName.ts
 function trimRequiredName(name, label) {
   const trimmed = name.trim();
@@ -1822,6 +1909,78 @@ var FirestoreDatabase = class _FirestoreDatabase {
     }
     return usage;
   }
+  /**
+   * Lists run results saved by the given user, newest first.
+   *
+   * @param userId - Owning user identifier.
+   */
+  async listRunResultsForUser(userId) {
+    const snapshot = await this.requireClient().collection(RUN_RESULTS_COLLECTION).where("createdByUserId", "==", userId).orderBy("createdAt", "desc").get();
+    return snapshot.docs.map(
+      (doc) => mapFirestoreRunResult(doc.id, doc.data())
+    );
+  }
+  /**
+   * Lists all run results for admin inspection, newest first.
+   */
+  async listAllRunResults() {
+    const snapshot = await this.requireClient().collection(RUN_RESULTS_COLLECTION).orderBy("createdAt", "desc").get();
+    return snapshot.docs.map(
+      (doc) => mapFirestoreRunResult(doc.id, doc.data())
+    );
+  }
+  /**
+   * Creates a standalone run result snapshot.
+   *
+   * @param input - HarborClient export payload and optional label.
+   * @param actingUserId - User performing the create action.
+   */
+  async createRunResult(input, actingUserId) {
+    const metadata = parseRunResultPayload(input.payload);
+    const label = input.label?.trim() || buildDefaultRunResultLabel(metadata);
+    const id = randomUUID2();
+    const now = /* @__PURE__ */ new Date();
+    const data = {
+      kind: metadata.kind,
+      label,
+      collectionName: metadata.collectionName,
+      requestName: metadata.requestName,
+      summary: metadata.summary,
+      payload: input.payload,
+      createdAt: now,
+      createdByUserId: actingUserId
+    };
+    await this.requireClient().collection(RUN_RESULTS_COLLECTION).doc(id).set(data);
+    await this.recordAuditEntry(actingUserId, "create", "run_result", id);
+    return mapFirestoreRunResult(id, data);
+  }
+  /**
+   * Finds a run result by stable identifier.
+   *
+   * @param id - Run result ID to look up.
+   */
+  async findRunResultById(id) {
+    const snapshot = await this.requireClient().collection(RUN_RESULTS_COLLECTION).doc(id).get();
+    if (!snapshot.exists) {
+      return null;
+    }
+    return mapFirestoreRunResult(id, snapshot.data());
+  }
+  /**
+   * Deletes a run result.
+   *
+   * @param id - Run result ID to delete.
+   * @param actingUserId - User performing the delete action.
+   */
+  async deleteRunResult(id, actingUserId) {
+    const docRef = this.requireClient().collection(RUN_RESULTS_COLLECTION).doc(id);
+    const snapshot = await docRef.get();
+    if (!snapshot.exists) {
+      throw new Error("Run result not found");
+    }
+    await this.recordAuditEntry(actingUserId, "delete", "run_result", id);
+    await docRef.delete();
+  }
   /**
    * Inserts a per-request LLM usage log entry.
    *
@@ -1976,7 +2135,7 @@ function parseAuditAction(value) {
   throw new Error(`Invalid audit action: ${value}`);
 }
 function parseAuditEntityType2(value) {
-  if (value === "user" || value === "api_token" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request") {
+  if (value === "user" || value === "api_token" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
     return value;
   }
   throw new Error(`Invalid audit entity type: ${value}`);
@@ -2073,6 +2232,23 @@ function mapSnippetSqlRow(row) {
     deletionLocked: Boolean(row.deletion_locked)
   };
 }
+function mapRunResultSqlRow(row) {
+  return {
+    id: row.id,
+    kind: row.kind,
+    label: row.label,
+    collectionName: row.collection_name,
+    requestName: row.request_name,
+    summary: {
+      passed: row.summary_passed,
+      failed: row.summary_failed,
+      skipped: row.summary_skipped
+    },
+    payload: parseJson(row.payload, {}),
+    createdAt: row.created_at,
+    createdByUserId: row.created_by_user_id ?? null
+  };
+}
 function mapFolderSqlRow(row) {
   return {
     id: row.id,
@@ -2349,6 +2525,22 @@ WHERE role = 'user'
   AND snippet_access = '[]'
   AND collection_access LIKE '%"*"%';
 `.trim();
+var RUN_RESULTS_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS run_results (
+  id VARCHAR(36) PRIMARY KEY,
+  kind VARCHAR(64) NOT NULL,
+  label VARCHAR(512) NOT NULL,
+  collection_name VARCHAR(512),
+  request_name VARCHAR(512),
+  summary_passed INT NOT NULL DEFAULT 0,
+  summary_failed INT NOT NULL DEFAULT 0,
+  summary_skipped INT NOT NULL DEFAULT 0,
+  payload LONGTEXT NOT NULL,
+  created_at DATETIME NOT NULL,
+  created_by_user_id VARCHAR(36),
+  INDEX run_results_created_idx (created_at)
+)
+`.trim();
 var MYSQL_MIGRATIONS = [
   USERS_MIGRATION_SQL,
   API_TOKENS_MIGRATION_SQL,
@@ -2374,7 +2566,8 @@ var MYSQL_MIGRATIONS = [
   COLLECTIONS_DELETION_LOCKED_MIGRATION_SQL,
   ENVIRONMENTS_DELETION_LOCKED_MIGRATION_SQL,
   USERS_SNIPPET_ACCESS_MIGRATION_SQL,
-  USERS_SNIPPET_ACCESS_BACKFILL_SQL
+  USERS_SNIPPET_ACCESS_BACKFILL_SQL,
+  RUN_RESULTS_MIGRATION_SQL
 ];
 
 // src/db/mysql/schemas.ts
@@ -2478,6 +2671,8 @@ var LLM_USAGE_SELECT_COLUMNS = `id, user_id, period, prompt_tokens, completion_t
 var COLLECTION_SELECT = `SELECT ${COLLECTION_SELECT_COLUMNS} FROM collections`;
 var ENVIRONMENT_SELECT = `SELECT ${ENVIRONMENT_SELECT_COLUMNS} FROM environments`;
 var SNIPPET_SELECT = `SELECT ${SNIPPET_SELECT_COLUMNS} FROM snippets`;
+var RUN_RESULT_SELECT_COLUMNS = "id, kind, label, collection_name, request_name, summary_passed, summary_failed, summary_skipped, payload, created_at, created_by_user_id";
+var RUN_RESULT_SELECT = `SELECT ${RUN_RESULT_SELECT_COLUMNS} FROM run_results`;
 var USER_SELECT = `SELECT ${USER_SELECT_COLUMNS} FROM users`;
 var API_TOKEN_SELECT = `SELECT ${API_TOKEN_SELECT_COLUMNS} FROM api_tokens`;
 var FOLDER_SELECT = `SELECT ${FOLDER_SELECT_COLUMNS} FROM folders`;
@@ -3883,6 +4078,93 @@ var MysqlDatabase = class _MysqlDatabase {
     );
     return rows.map(mapLlmUsageLogSqlRow);
   }
+  /**
+   * Lists run results saved by the given user, newest first.
+   */
+  async listRunResultsForUser(userId) {
+    const rows = await this.queryRows(
+      `${RUN_RESULT_SELECT} WHERE created_by_user_id = ? ORDER BY created_at DESC`,
+      [userId]
+    );
+    return rows.map(mapRunResultSqlRow);
+  }
+  /**
+   * Lists all run results for admin inspection, newest first.
+   */
+  async listAllRunResults() {
+    const rows = await this.queryRows(
+      `${RUN_RESULT_SELECT} ORDER BY created_at DESC`
+    );
+    return rows.map(mapRunResultSqlRow);
+  }
+  /**
+   * Creates a standalone run result snapshot.
+   */
+  async createRunResult(input, actingUserId) {
+    const metadata = parseRunResultPayload(input.payload);
+    const label = input.label?.trim() || buildDefaultRunResultLabel(metadata);
+    const id = randomUUID3();
+    const now = /* @__PURE__ */ new Date();
+    await this.executeStatement(
+      `INSERT INTO run_results (
+        id,
+        kind,
+        label,
+        collection_name,
+        request_name,
+        summary_passed,
+        summary_failed,
+        summary_skipped,
+        payload,
+        created_at,
+        created_by_user_id
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        metadata.kind,
+        label,
+        metadata.collectionName,
+        metadata.requestName,
+        metadata.summary.passed,
+        metadata.summary.failed,
+        metadata.summary.skipped,
+        JSON.stringify(input.payload),
+        now,
+        actingUserId
+      ]
+    );
+    const rows = await this.queryRows(
+      `${RUN_RESULT_SELECT} WHERE id = ?`,
+      [id]
+    );
+    const row = rows[0];
+    if (!row) {
+      throw new Error("Run result not found after insert");
+    }
+    await this.recordAuditEntry(actingUserId, "create", "run_result", id);
+    return mapRunResultSqlRow(row);
+  }
+  /**
+   * Finds a run result by id.
+   */
+  async findRunResultById(id) {
+    const rows = await this.queryRows(
+      `${RUN_RESULT_SELECT} WHERE id = ?`,
+      [id]
+    );
+    const row = rows[0];
+    return row ? mapRunResultSqlRow(row) : null;
+  }
+  /**
+   * Deletes a run result by id.
+   */
+  async deleteRunResult(id, actingUserId) {
+    const result = await this.executeStatement("DELETE FROM run_results WHERE id = ?", [id]);
+    if (result.affectedRows === 0) {
+      throw new Error("Run result not found");
+    }
+    await this.recordAuditEntry(actingUserId, "delete", "run_result", id);
+  }
   /**
    * Ensures the internal system user exists and caches its identifier.
    */
@@ -4229,6 +4511,22 @@ WHERE role = 'user'
   AND snippet_access = '[]'
   AND collection_access LIKE '%"*"%';
 `.trim();
+var RUN_RESULTS_MIGRATION_SQL2 = `
+CREATE TABLE IF NOT EXISTS run_results (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('collection-run-results', 'request-run-results')),
+  label TEXT NOT NULL,
+  collection_name TEXT,
+  request_name TEXT,
+  summary_passed INT NOT NULL DEFAULT 0,
+  summary_failed INT NOT NULL DEFAULT 0,
+  summary_skipped INT NOT NULL DEFAULT 0,
+  payload TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL,
+  created_by_user_id TEXT REFERENCES users(id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS run_results_created_idx ON run_results (created_at DESC);
+`.trim();
 var POSTGRES_MIGRATIONS = [
   USERS_MIGRATION_SQL2,
   API_TOKENS_MIGRATION_SQL2,
@@ -4254,7 +4552,8 @@ var POSTGRES_MIGRATIONS = [
   COLLECTIONS_DELETION_LOCKED_MIGRATION_SQL2,
   ENVIRONMENTS_DELETION_LOCKED_MIGRATION_SQL2,
   USERS_SNIPPET_ACCESS_MIGRATION_SQL2,
-  USERS_SNIPPET_ACCESS_BACKFILL_SQL2
+  USERS_SNIPPET_ACCESS_BACKFILL_SQL2,
+  RUN_RESULTS_MIGRATION_SQL2
 ];
 
 // src/db/postgres/schemas.ts
@@ -4279,6 +4578,8 @@ var { Pool } = pg;
 var COLLECTION_SELECT2 = `SELECT ${COLLECTION_SELECT_COLUMNS} FROM collections`;
 var ENVIRONMENT_SELECT2 = `SELECT ${ENVIRONMENT_SELECT_COLUMNS} FROM environments`;
 var SNIPPET_SELECT2 = `SELECT ${SNIPPET_SELECT_COLUMNS} FROM snippets`;
+var RUN_RESULT_SELECT_COLUMNS2 = "id, kind, label, collection_name, request_name, summary_passed, summary_failed, summary_skipped, payload, created_at, created_by_user_id";
+var RUN_RESULT_SELECT2 = `SELECT ${RUN_RESULT_SELECT_COLUMNS2} FROM run_results`;
 var USER_SELECT2 = `SELECT ${USER_SELECT_COLUMNS} FROM users`;
 var API_TOKEN_SELECT2 = `SELECT ${API_TOKEN_SELECT_COLUMNS} FROM api_tokens`;
 var FOLDER_SELECT2 = `SELECT ${FOLDER_SELECT_COLUMNS} FROM folders`;
@@ -5629,6 +5930,87 @@ var PostgresDatabase = class _PostgresDatabase {
     );
     return result.rows.map(mapLlmUsageLogSqlRow);
   }
+  /**
+   * Lists run results saved by the given user, newest first.
+   */
+  async listRunResultsForUser(userId) {
+    const result = await this.query(
+      `${RUN_RESULT_SELECT2} WHERE created_by_user_id = $1 ORDER BY created_at DESC`,
+      [userId]
+    );
+    return result.rows.map(mapRunResultSqlRow);
+  }
+  /**
+   * Lists all run results for admin inspection, newest first.
+   */
+  async listAllRunResults() {
+    const result = await this.query(
+      `${RUN_RESULT_SELECT2} ORDER BY created_at DESC`
+    );
+    return result.rows.map(mapRunResultSqlRow);
+  }
+  /**
+   * Creates a standalone run result snapshot.
+   */
+  async createRunResult(input, actingUserId) {
+    const metadata = parseRunResultPayload(input.payload);
+    const label = input.label?.trim() || buildDefaultRunResultLabel(metadata);
+    const id = randomUUID4();
+    const now = /* @__PURE__ */ new Date();
+    const result = await this.query(
+      `INSERT INTO run_results (
+        id,
+        kind,
+        label,
+        collection_name,
+        request_name,
+        summary_passed,
+        summary_failed,
+        summary_skipped,
+        payload,
+        created_at,
+        created_by_user_id
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+      RETURNING ${RUN_RESULT_SELECT_COLUMNS2}`,
+      [
+        id,
+        metadata.kind,
+        label,
+        metadata.collectionName,
+        metadata.requestName,
+        metadata.summary.passed,
+        metadata.summary.failed,
+        metadata.summary.skipped,
+        JSON.stringify(input.payload),
+        now,
+        actingUserId
+      ]
+    );
+    const row = result.rows[0];
+    if (!row) {
+      throw new Error("Run result not found after insert");
+    }
+    await this.recordAuditEntry(actingUserId, "create", "run_result", id);
+    return mapRunResultSqlRow(row);
+  }
+  /**
+   * Finds a run result by id.
+   */
+  async findRunResultById(id) {
+    const result = await this.query(`${RUN_RESULT_SELECT2} WHERE id = $1`, [id]);
+    const row = result.rows[0];
+    return row ? mapRunResultSqlRow(row) : null;
+  }
+  /**
+   * Deletes a run result by id.
+   */
+  async deleteRunResult(id, actingUserId) {
+    const result = await this.query("DELETE FROM run_results WHERE id = $1", [id]);
+    if ((result.rowCount ?? 0) === 0) {
+      throw new Error("Run result not found");
+    }
+    await this.recordAuditEntry(actingUserId, "delete", "run_result", id);
+  }
   /**
    * Returns the active pool or throws when connect has not been called.
    *
@@ -6114,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) => {
@@ -6655,6 +7045,9 @@ function canListEnvironments(user) {
 function canListSnippets(user) {
   return canUseDataApi(user) || canUseManagementApi(user);
 }
+function canListRunResults(user) {
+  return canUseDataApi(user) || canUseManagementApi(user);
+}
 function hasWildcardAccess(access) {
   return access.includes("*");
 }
@@ -6691,6 +7084,9 @@ function canDeleteCollection(user, collection) {
 function canDeleteRequest(user, request) {
   return canUseDataApi(user) && canAccessCollection(user, request.collectionId) && request.createdByUserId === user.id;
 }
+function canDeleteRunResult(user, runResult) {
+  return canUseDataApi(user) && runResult.createdByUserId === user.id;
+}
 function canCreateCollection(user) {
   return user.role === "user" && hasWildcardAccess(user.collectionAccess);
 }
@@ -6923,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(),
@@ -7115,6 +7515,48 @@ function serializeSavedRequest(record) {
     updatedAt: record.updatedAt.toISOString()
   };
 }
+var runResultRecordSchema = z8.object({
+  id: z8.string(),
+  kind: z8.enum(["collection-run-results", "request-run-results"]),
+  label: z8.string(),
+  collectionName: z8.string().nullable(),
+  requestName: z8.string().nullable(),
+  summary: z8.object({
+    passed: z8.number().int().nonnegative(),
+    failed: z8.number().int().nonnegative(),
+    skipped: z8.number().int().nonnegative()
+  }),
+  createdAt: timestampSchema,
+  createdByUserId: z8.string().nullable()
+});
+var runResultDetailSchema = runResultRecordSchema.extend({
+  payload: z8.record(z8.string(), z8.unknown())
+});
+var createRunResultBodySchema = z8.object({
+  label: z8.string().trim().min(1).optional(),
+  payload: z8.record(z8.string(), z8.unknown())
+});
+var listRunResultsResponseSchema = z8.object({
+  runResults: z8.array(runResultRecordSchema)
+});
+function serializeRunResult(record) {
+  return {
+    id: record.id,
+    kind: record.kind,
+    label: record.label,
+    collectionName: record.collectionName,
+    requestName: record.requestName,
+    summary: record.summary,
+    createdAt: record.createdAt.toISOString(),
+    createdByUserId: record.createdByUserId
+  };
+}
+function serializeRunResultDetail(record) {
+  return {
+    ...serializeRunResult(record),
+    payload: record.payload
+  };
+}
 
 // src/server/routes/schemas/admin.ts
 var adminResourceOptionSchema = z9.object({
@@ -7164,6 +7606,9 @@ var listAdminEnvironmentsResponseSchema = z9.object({
 var listAdminSnippetsResponseSchema = z9.object({
   snippets: z9.array(snippetRecordSchema)
 });
+var listAdminRunResultsResponseSchema = z9.object({
+  runResults: z9.array(runResultRecordSchema)
+});
 var adminSnippetRecordSchema = snippetRecordSchema;
 var listAdminLlmModelsResponseSchema = listLlmModelsResponseSchema;
 var hubUserRecordSchema = z9.object({
@@ -7230,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()
 });
@@ -7722,6 +8167,71 @@ async function registerAdminRoutes(app, options) {
       }
     }
   });
+  routes.route({
+    method: "GET",
+    url: "/admin/run-results",
+    schema: {
+      response: {
+        200: listAdminRunResultsResponseSchema,
+        403: errorResponseSchema
+      }
+    },
+    /**
+     * Lists all run results for operator management.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(user))) {
+          return;
+        }
+        const runResults = await db.listAllRunResults();
+        return reply.send({
+          runResults: runResults.map((record) => serializeRunResult(record))
+        });
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "DELETE",
+    url: "/admin/run-results/:id",
+    schema: {
+      params: idParamSchema,
+      response: {
+        204: emptyResponseSchema,
+        403: errorResponseSchema,
+        404: errorResponseSchema
+      }
+    },
+    /**
+     * Deletes a run result regardless of creator ownership.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(user))) {
+          return;
+        }
+        const record = await db.findRunResultById(request.params.id);
+        if (!record) {
+          void reply.code(404).send({ error: "Run result not found" });
+          return;
+        }
+        await db.deleteRunResult(request.params.id, user.id);
+        return reply.code(204).send(null);
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
   routes.route({
     method: "PUT",
     url: "/admin/snippets/:id",
@@ -7905,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({
@@ -9104,6 +9614,140 @@ async function registerRequestRoutes(app, db) {
   });
 }
 
+// src/server/routes/runResults.ts
+async function registerRunResultRoutes(app, db) {
+  const routes = app.withTypeProvider();
+  routes.route({
+    method: "GET",
+    url: "/run-results",
+    schema: {
+      response: {
+        200: listRunResultsResponseSchema
+      }
+    },
+    /**
+     * Lists run results saved by the authenticated user token.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canListRunResults(user))) {
+          return;
+        }
+        const runResults = await db.listRunResultsForUser(user.id);
+        return reply.send({
+          runResults: runResults.map((record) => serializeRunResult(record))
+        });
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "POST",
+    url: "/run-results",
+    schema: {
+      body: createRunResultBodySchema,
+      response: {
+        200: runResultDetailSchema,
+        400: errorResponseSchema
+      }
+    },
+    /**
+     * Saves a standalone run result snapshot.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseDataApi(user))) {
+          return;
+        }
+        const record = await db.createRunResult(request.body, user.id);
+        return reply.send(serializeRunResultDetail(record));
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "GET",
+    url: "/run-results/:id",
+    schema: {
+      params: idParamSchema,
+      response: {
+        200: runResultDetailSchema,
+        404: errorResponseSchema
+      }
+    },
+    /**
+     * Loads a run result snapshot by id for shared deep links.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseDataApi(user))) {
+          return;
+        }
+        const record = await db.findRunResultById(request.params.id);
+        if (!record) {
+          void reply.code(404).send({ error: "Run result not found" });
+          return;
+        }
+        return reply.send(serializeRunResultDetail(record));
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "DELETE",
+    url: "/run-results/:id",
+    schema: {
+      params: idParamSchema,
+      response: {
+        204: emptyResponseSchema,
+        403: errorResponseSchema,
+        404: errorResponseSchema
+      }
+    },
+    /**
+     * Deletes a run result saved by the authenticated user when permitted.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseDataApi(user))) {
+          return;
+        }
+        const record = await db.findRunResultById(request.params.id);
+        if (!record) {
+          void reply.code(404).send({ error: "Run result not found" });
+          return;
+        }
+        if (denyUnlessAllowed(reply, canDeleteRunResult(user, record))) {
+          return;
+        }
+        await db.deleteRunResult(request.params.id, user.id);
+        return reply.code(204).send(null);
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+}
+
 // src/server/llm/client.ts
 var OPENAI_BASE_URL = "https://api.openai.com/v1";
 var CLAUDE_BASE_URL = "https://api.anthropic.com/v1";
@@ -9226,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) {
@@ -9419,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;
@@ -9446,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,
@@ -9455,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({
@@ -9521,7 +10343,8 @@ async function registerLlmRoutes(app, options) {
           id: model.id,
           label: model.label,
           provider: model.provider
-        }))
+        })),
+        capabilities: getHubLlmCapabilities(llm)
       });
     }
   });
@@ -9595,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}`);
@@ -9746,7 +10574,12 @@ async function registerProtectedRoutes(app, options) {
   await registerSnippetRoutes(app, options.db);
   await registerFolderRoutes(app, options.db);
   await registerRequestRoutes(app, options.db);
-  await registerLlmRoutes(app, { db: options.db, getLlm: options.getLlm });
+  await registerRunResultRoutes(app, options.db);
+  await registerLlmRoutes(app, {
+    db: options.db,
+    getLlm: options.getLlm,
+    getDocs: options.getDocs
+  });
   await registerPluginsRoutes(app, { getPlugins: options.getPlugins });
 }
 async function registerRoutes(app, options) {
@@ -9781,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;
@@ -9967,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,
@@ -9981,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);
@@ -10054,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 };
 }