thorbit-kb-mcp 0.2.8 → 0.2.9

package/dist/bin/thorbit-kb-mcp.cjs

@@ -64,46 +64,12 @@ function resolveThorbitKbMcpEnv() {
 
 // src/thorbit-kb-mcp-server.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
-
-// src/thorbit-kb-mcp-response-formatters.ts
-function summarizeResult(toolName, result) {
-  if (toolName === "thorbit_kb_create" && result && typeof result === "object" && "knowledgeBase" in result) {
-    const kb = result.knowledgeBase;
-    return `Created Thorbit knowledge base ${String(kb.name ?? kb.publicId ?? "")}.`;
-  }
-  if (toolName === "thorbit_kb_list" && result && typeof result === "object" && "knowledgeBases" in result) {
-    const count = Array.isArray(result.knowledgeBases) ? result.knowledgeBases.length : 0;
-    return `Found ${count} Thorbit knowledge base${count === 1 ? "" : "s"}.`;
-  }
-  if (toolName.startsWith("thorbit_kb_ingest")) return "Knowledge-base ingestion completed. Check structuredContent for source receipts.";
-  if (toolName === "thorbit_kb_source_status") return "Source status returned. Check structuredContent for details.";
-  if (toolName === "thorbit_kb_search") return "Knowledge-base search completed. Check structuredContent for results and citations.";
-  if (toolName === "thorbit_kb_ask") return "Knowledge-base answer generated. Check structuredContent for citations and strategy.";
-  return "Thorbit knowledge-base tool completed.";
-}
-function formatThorbitKbMcpToolResult(toolName, envelope) {
-  if (!envelope.ok) {
-    return {
-      isError: true,
-      content: [{
-        type: "text",
-        text: `${envelope.error.code}: ${envelope.error.message}`
-      }],
-      structuredContent: envelope
-    };
-  }
-  return {
-    content: [{
-      type: "text",
-      text: summarizeResult(toolName, envelope.result)
-    }],
-    structuredContent: envelope.result
-  };
-}
+var import_thorbit_mcp_core2 = require("thorbit-mcp-core");
 
 // src/thorbit-kb-mcp-tool-schemas.ts
+var import_thorbit_mcp_core = require("thorbit-mcp-core");
 var import_zod = require("zod");
-var MetadataSchema = import_zod.z.record(import_zod.z.string(), import_zod.z.unknown());
+var MetadataSchema = import_zod.z.record(import_thorbit_mcp_core.JsonValueSchema);
 var ThorbitKbCreateInputSchema = {
   name: import_zod.z.string().min(1).max(255).describe("Name for the new Thorbit knowledge base."),
   description: import_zod.z.string().max(2e3).optional().describe("Optional description for the new knowledge base."),
@@ -167,16 +133,542 @@ var ThorbitKbAskInputSchema = {
   limit: import_zod.z.number().int().min(1).max(20).default(8).describe("Maximum retrieved chunks used for the answer."),
   requireCitations: import_zod.z.boolean().default(true).describe("Keep true for grounded answers with citation arrays.")
 };
+var ThorbitKnowledgeBasePublicIdSchema = import_zod.z.string().min(1).max(128);
+var ThorbitKnowledgeBaseStatusSchema = import_zod.z.string().min(1).max(64);
+var ThorbitKnowledgeBaseSourceTypeSchema = import_zod.z.string().min(1).max(64);
+var ThorbitKnowledgeBaseSourceStatusSchema = import_zod.z.enum([
+  "pending",
+  "processing",
+  "ready",
+  "failed"
+]);
+var ThorbitKnowledgeBaseResultSchema = import_zod.z.object({
+  knowledgeBasePublicId: ThorbitKnowledgeBasePublicIdSchema,
+  name: import_zod.z.string().min(1).max(255),
+  status: ThorbitKnowledgeBaseStatusSchema,
+  createdAt: import_zod.z.string().datetime(),
+  updatedAt: import_zod.z.string().datetime()
+}).strict();
+var ThorbitKnowledgeBaseListResultSchema = import_zod.z.object({
+  knowledgeBases: import_zod.z.array(ThorbitKnowledgeBaseResultSchema).max(100),
+  nextCursor: import_zod.z.string().min(1).max(512).nullable()
+}).strict();
+var ThorbitKnowledgeBaseSourceStatusResultSchema = import_zod.z.object({
+  knowledgeBasePublicId: ThorbitKnowledgeBasePublicIdSchema,
+  sourcePublicId: ThorbitKnowledgeBasePublicIdSchema,
+  sourceType: ThorbitKnowledgeBaseSourceTypeSchema,
+  status: ThorbitKnowledgeBaseSourceStatusSchema,
+  progressPercent: import_zod.z.number().finite().min(0).max(100),
+  error: import_zod.z.string().min(1).max(4e3).nullable(),
+  updatedAt: import_zod.z.string().datetime()
+}).strict();
+var ThorbitKnowledgeBaseSourceStatusPollInputSchema = import_zod.z.object({
+  sourcePublicIds: import_zod.z.array(ThorbitKnowledgeBasePublicIdSchema).min(1).max(100)
+}).strict();
+var ThorbitKnowledgeBaseIngestResultSchema = import_zod.z.object({
+  knowledgeBasePublicId: ThorbitKnowledgeBasePublicIdSchema,
+  sourcePublicId: ThorbitKnowledgeBasePublicIdSchema,
+  sourceType: ThorbitKnowledgeBaseSourceTypeSchema,
+  status: ThorbitKnowledgeBaseSourceStatusSchema,
+  pollToolName: import_zod.z.literal("thorbit_kb_source_status"),
+  pollInput: ThorbitKnowledgeBaseSourceStatusPollInputSchema
+}).strict();
+var ThorbitKnowledgeBaseCitationSchema = import_zod.z.object({
+  index: import_zod.z.number().int().positive().max(1e4),
+  chunkPublicId: ThorbitKnowledgeBasePublicIdSchema,
+  sourcePublicId: ThorbitKnowledgeBasePublicIdSchema.nullable(),
+  sourceTitle: import_zod.z.string().min(1).max(1e3),
+  sourceType: ThorbitKnowledgeBaseSourceTypeSchema,
+  sourceUrl: import_zod.z.string().url().max(2048).nullable(),
+  chunkIndex: import_zod.z.number().int().nonnegative().max(1e7).nullable(),
+  timestampStart: import_zod.z.number().finite().nonnegative().max(1e7).nullable(),
+  excerpt: import_zod.z.string().max(1e4)
+}).strict();
+var ThorbitKnowledgeBaseSearchMatchSchema = import_zod.z.object({
+  chunkPublicId: ThorbitKnowledgeBasePublicIdSchema,
+  text: import_zod.z.string().max(5e4),
+  score: import_zod.z.number().finite().min(0).max(1)
+}).strict();
+var ThorbitKnowledgeBaseSearchResultSchema = import_zod.z.object({
+  query: import_zod.z.string().min(1).max(4e3),
+  results: import_zod.z.array(ThorbitKnowledgeBaseSearchMatchSchema).max(50),
+  citations: import_zod.z.array(ThorbitKnowledgeBaseCitationSchema).max(50)
+}).strict();
+var ThorbitKnowledgeBaseAnswerResultSchema = import_zod.z.object({
+  answer: import_zod.z.string().max(5e5),
+  citations: import_zod.z.array(ThorbitKnowledgeBaseCitationSchema).max(50),
+  followUps: import_zod.z.array(import_zod.z.string().min(1).max(8e3)).max(20),
+  modelId: import_zod.z.string().min(1).max(255).nullable()
+}).strict();
+function createThorbitKnowledgeBaseMcpOutputContract(resultSchema) {
+  const strictSchema = (0, import_thorbit_mcp_core.createThorbitMcpStructuredResultSchema)(resultSchema);
+  const successShape = strictSchema.options[0].shape;
+  const errorShape = strictSchema.options[1].shape;
+  const advertisedSchema = import_zod.z.object({
+    ok: import_zod.z.boolean(),
+    toolName: successShape.toolName,
+    requestId: successShape.requestId,
+    summary: successShape.summary.optional(),
+    result: resultSchema.optional(),
+    artifacts: successShape.artifacts.optional(),
+    next: successShape.next,
+    warnings: successShape.warnings.optional(),
+    usage: successShape.usage.optional(),
+    error: errorShape.error.optional()
+  }).strict();
+  return { strictSchema, advertisedSchema };
+}
+var thorbitKnowledgeBaseOutputContracts = {
+  thorbit_kb_create: createThorbitKnowledgeBaseMcpOutputContract(ThorbitKnowledgeBaseResultSchema),
+  thorbit_kb_list: createThorbitKnowledgeBaseMcpOutputContract(ThorbitKnowledgeBaseListResultSchema),
+  thorbit_kb_source_status: createThorbitKnowledgeBaseMcpOutputContract(ThorbitKnowledgeBaseSourceStatusResultSchema),
+  thorbit_kb_ingest_url: createThorbitKnowledgeBaseMcpOutputContract(ThorbitKnowledgeBaseIngestResultSchema),
+  thorbit_kb_ingest_site: createThorbitKnowledgeBaseMcpOutputContract(ThorbitKnowledgeBaseIngestResultSchema),
+  thorbit_kb_ingest_youtube: createThorbitKnowledgeBaseMcpOutputContract(ThorbitKnowledgeBaseIngestResultSchema),
+  thorbit_kb_ingest_text: createThorbitKnowledgeBaseMcpOutputContract(ThorbitKnowledgeBaseIngestResultSchema),
+  thorbit_kb_search: createThorbitKnowledgeBaseMcpOutputContract(ThorbitKnowledgeBaseSearchResultSchema),
+  thorbit_kb_ask: createThorbitKnowledgeBaseMcpOutputContract(ThorbitKnowledgeBaseAnswerResultSchema)
+};
+var ThorbitKnowledgeBaseMcpToolStrictOutputSchemas = {
+  thorbit_kb_create: thorbitKnowledgeBaseOutputContracts.thorbit_kb_create.strictSchema,
+  thorbit_kb_list: thorbitKnowledgeBaseOutputContracts.thorbit_kb_list.strictSchema,
+  thorbit_kb_source_status: thorbitKnowledgeBaseOutputContracts.thorbit_kb_source_status.strictSchema,
+  thorbit_kb_ingest_url: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ingest_url.strictSchema,
+  thorbit_kb_ingest_site: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ingest_site.strictSchema,
+  thorbit_kb_ingest_youtube: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ingest_youtube.strictSchema,
+  thorbit_kb_ingest_text: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ingest_text.strictSchema,
+  thorbit_kb_search: thorbitKnowledgeBaseOutputContracts.thorbit_kb_search.strictSchema,
+  thorbit_kb_ask: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ask.strictSchema
+};
+var ThorbitKnowledgeBaseMcpToolOutputSchemas = {
+  thorbit_kb_create: thorbitKnowledgeBaseOutputContracts.thorbit_kb_create.advertisedSchema,
+  thorbit_kb_list: thorbitKnowledgeBaseOutputContracts.thorbit_kb_list.advertisedSchema,
+  thorbit_kb_source_status: thorbitKnowledgeBaseOutputContracts.thorbit_kb_source_status.advertisedSchema,
+  thorbit_kb_ingest_url: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ingest_url.advertisedSchema,
+  thorbit_kb_ingest_site: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ingest_site.advertisedSchema,
+  thorbit_kb_ingest_youtube: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ingest_youtube.advertisedSchema,
+  thorbit_kb_ingest_text: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ingest_text.advertisedSchema,
+  thorbit_kb_search: thorbitKnowledgeBaseOutputContracts.thorbit_kb_search.advertisedSchema,
+  thorbit_kb_ask: thorbitKnowledgeBaseOutputContracts.thorbit_kb_ask.advertisedSchema
+};
+
+// src/thorbit-kb-mcp-response-formatters.ts
+var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "unauthorized",
+  "forbidden",
+  "payment_required",
+  "not_found",
+  "validation_error",
+  "provider_error",
+  "rate_limited",
+  "conflict",
+  "internal_error"
+]);
+var SENSITIVE_DETAIL_KEY = /(?:authorization|cookie|credential|password|secret|token|api.?key|private.?key)/i;
+var CREDENTIAL_TEXT = /(?:Bearer\s+[^\s,;]+|\b(?:sk|pk|key|token|thbt)[_-][A-Za-z0-9._-]{6,}\b|\bAIza[A-Za-z0-9_-]{20,}\b)/gi;
+var SAFE_METADATA_IDENTIFIER = /^[A-Za-z0-9._/:-]+$/;
+var CREDENTIAL_METADATA = /(?:\b(?:Bearer|Basic|Digest)\s+\S+|\b(?:authorization|api[\s_-]?key|token|secret)\s*[:=]|\b[a-z][a-z0-9+.-]*:\/\/[^/@\s]+@|\b(?:sk|pk|rk|key|token|thbt)[_-][A-Za-z0-9._-]{6,}\b|\bAIza[A-Za-z0-9_-]{20,}\b|\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bxox[baprs]-[A-Za-z0-9-]{10,}\b|\b(?:AKIA|ASIA)[A-Z0-9]{16}\b)/i;
+var IDEMPOTENT_READ_TOOLS = /* @__PURE__ */ new Set([
+  "thorbit_kb_list",
+  "thorbit_kb_source_status",
+  "thorbit_kb_search"
+]);
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function safeText(value, fallback, maxLength = 4e3) {
+  if (typeof value !== "string" || value.trim().length === 0) return fallback;
+  return value.trim().slice(0, maxLength).replace(CREDENTIAL_TEXT, "[redacted]");
+}
+function safeDetails(value, depth = 0, active = /* @__PURE__ */ new WeakSet()) {
+  if (depth > 4) return "[detail depth omitted]";
+  if (typeof value === "string") return safeText(value, "[empty detail]");
+  if (typeof value === "number" || typeof value === "boolean" || value === null) return value;
+  if (Array.isArray(value)) return value.slice(0, 25).map((item) => safeDetails(item, depth + 1, active));
+  if (!value || typeof value !== "object") return void 0;
+  if (active.has(value)) return "[cyclic detail omitted]";
+  active.add(value);
+  try {
+    const output = {};
+    for (const [key, detail] of Object.entries(value).slice(0, 40)) {
+      output[key] = SENSITIVE_DETAIL_KEY.test(key) ? "[redacted]" : safeDetails(detail, depth + 1, active);
+    }
+    return output;
+  } catch {
+    return "[unavailable detail]";
+  } finally {
+    active.delete(value);
+  }
+}
+function requiredString(record, key) {
+  const value = record[key];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`Knowledge Base result is missing ${key}`);
+  }
+  return value.trim();
+}
+function optionalString(record, key) {
+  const value = record[key];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function safeMetadataIdentifier(value, maxLength = 255) {
+  if (typeof value !== "string") return null;
+  const candidate = value.trim();
+  if (candidate.length === 0 || candidate.length > maxLength || !SAFE_METADATA_IDENTIFIER.test(candidate) || CREDENTIAL_METADATA.test(candidate)) return null;
+  return candidate;
+}
+function requiredDateTime(record, key) {
+  const value = requiredString(record, key);
+  if (Number.isNaN(Date.parse(value))) {
+    throw new TypeError(`Knowledge Base result has an invalid ${key}`);
+  }
+  return value;
+}
+function requiredNumber(record, key) {
+  const value = record[key];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new TypeError(`Knowledge Base result is missing ${key}`);
+  }
+  return value;
+}
+function normalizeSourceStatus(value) {
+  switch (value) {
+    case "pending":
+    case "processing":
+    case "ready":
+    case "failed":
+      return value;
+    default:
+      throw new TypeError(`Unsupported Knowledge Base source status: ${String(value)}`);
+  }
+}
+function normalizeKnowledgeBase(value) {
+  const record = asRecord(value);
+  if (!record) throw new TypeError("Knowledge Base record must be an object");
+  return {
+    knowledgeBasePublicId: optionalString(record, "knowledgeBasePublicId") ?? requiredString(record, "publicId"),
+    name: requiredString(record, "name"),
+    status: requiredString(record, "status"),
+    createdAt: requiredDateTime(record, "createdAt"),
+    updatedAt: requiredDateTime(record, "updatedAt")
+  };
+}
+function normalizeCitation(value) {
+  const citation = asRecord(value);
+  if (!citation) throw new TypeError("Knowledge Base citation must be an object");
+  const sourceUrl = optionalString(citation, "sourceUrl");
+  const rawChunkIndex = citation.chunkIndex;
+  const rawTimestampStart = citation.timestampStart;
+  return {
+    index: requiredNumber(citation, "index"),
+    chunkPublicId: requiredString(citation, "chunkPublicId"),
+    sourcePublicId: optionalString(citation, "sourcePublicId"),
+    sourceTitle: requiredString(citation, "sourceTitle"),
+    sourceType: requiredString(citation, "sourceType"),
+    sourceUrl,
+    chunkIndex: typeof rawChunkIndex === "number" && Number.isFinite(rawChunkIndex) ? rawChunkIndex : null,
+    timestampStart: typeof rawTimestampStart === "number" && Number.isFinite(rawTimestampStart) ? rawTimestampStart : null,
+    excerpt: typeof citation.excerpt === "string" ? citation.excerpt.slice(0, 1e4) : ""
+  };
+}
+function normalizeCitationList(value) {
+  if (!Array.isArray(value)) {
+    throw new TypeError("Knowledge Base result is missing citations");
+  }
+  return value.slice(0, 50).map(normalizeCitation);
+}
+function normalizeIngestReceipt(result) {
+  let receipt = result;
+  const wrappedReceipt = asRecord(result.receipt);
+  if (wrappedReceipt) {
+    receipt = wrappedReceipt;
+  } else if (Array.isArray(result.receipts)) {
+    if (result.receipts.length !== 1) {
+      throw new TypeError("The exact Knowledge Base ingest contract requires one provider source receipt");
+    }
+    const onlyReceipt = asRecord(result.receipts[0]);
+    if (!onlyReceipt) throw new TypeError("Knowledge Base ingest receipt must be an object");
+    receipt = onlyReceipt;
+  }
+  const sourcePublicId = requiredString(receipt, "sourcePublicId");
+  return {
+    knowledgeBasePublicId: requiredString(receipt, "knowledgeBasePublicId"),
+    sourcePublicId,
+    sourceType: requiredString(receipt, "sourceType"),
+    status: normalizeSourceStatus(receipt.status),
+    pollToolName: "thorbit_kb_source_status",
+    pollInput: { sourcePublicIds: [sourcePublicId] }
+  };
+}
+function normalizeSuccessResult(toolName, value, envelopeUsage) {
+  const result = asRecord(value);
+  if (!result) throw new TypeError("Knowledge Base result must be an object");
+  switch (toolName) {
+    case "thorbit_kb_create":
+      return normalizeKnowledgeBase(asRecord(result.knowledgeBase) ?? result);
+    case "thorbit_kb_list": {
+      if (!Array.isArray(result.knowledgeBases)) {
+        throw new TypeError("Knowledge Base list is missing knowledgeBases");
+      }
+      return {
+        knowledgeBases: result.knowledgeBases.slice(0, 100).map(normalizeKnowledgeBase),
+        nextCursor: optionalString(result, "nextCursor")
+      };
+    }
+    case "thorbit_kb_source_status": {
+      let source = result;
+      if (Array.isArray(result.sources)) {
+        if (result.sources.length !== 1) {
+          throw new TypeError("The exact Knowledge Base source-status contract requires one provider source");
+        }
+        const onlySource = asRecord(result.sources[0]);
+        if (!onlySource) throw new TypeError("Knowledge Base source status must be an object");
+        source = onlySource;
+      }
+      const rawError = optionalString(source, "error") ?? optionalString(source, "errorMessage");
+      return {
+        knowledgeBasePublicId: requiredString(source, "knowledgeBasePublicId"),
+        sourcePublicId: requiredString(source, "sourcePublicId"),
+        sourceType: requiredString(source, "sourceType"),
+        status: normalizeSourceStatus(source.status),
+        progressPercent: requiredNumber(source, "progressPercent"),
+        error: rawError ? rawError.slice(0, 4e3) : null,
+        updatedAt: requiredDateTime(source, "updatedAt")
+      };
+    }
+    case "thorbit_kb_ingest_url":
+    case "thorbit_kb_ingest_site":
+    case "thorbit_kb_ingest_youtube":
+    case "thorbit_kb_ingest_text":
+      return normalizeIngestReceipt(result);
+    case "thorbit_kb_search": {
+      if (!Array.isArray(result.results)) {
+        throw new TypeError("Knowledge Base search is missing results");
+      }
+      return {
+        query: requiredString(result, "query"),
+        results: result.results.slice(0, 50).map((value2) => {
+          const match = asRecord(value2);
+          if (!match) throw new TypeError("Knowledge Base search match must be an object");
+          const text = typeof match.text === "string" ? match.text : requiredString(match, "content");
+          return {
+            chunkPublicId: requiredString(match, "chunkPublicId"),
+            text: text.slice(0, 5e4),
+            score: requiredNumber(match, "score")
+          };
+        }),
+        citations: normalizeCitationList(result.citations)
+      };
+    }
+    case "thorbit_kb_ask": {
+      const sufficiency = asRecord(result.sufficiency);
+      const followUpValue = Array.isArray(result.followUps) ? result.followUps : sufficiency?.followUpSuggestions;
+      const followUps = Array.isArray(followUpValue) ? followUpValue.filter((item) => typeof item === "string" && item.trim().length > 0).map((item) => item.trim().slice(0, 8e3)).slice(0, 20) : [];
+      const usage = asRecord(envelopeUsage);
+      const explicitModelId = optionalString(result, "modelId");
+      return {
+        answer: requiredString(result, "answer").slice(0, 5e5),
+        citations: normalizeCitationList(result.citations),
+        followUps,
+        modelId: explicitModelId !== null ? safeMetadataIdentifier(explicitModelId) : safeMetadataIdentifier(usage?.modelId)
+      };
+    }
+  }
+}
+function normalizeUsage(value) {
+  const usage = asRecord(value);
+  if (!usage) return void 0;
+  const output = {};
+  for (const key of ["creditsConsumed", "estimatedUsd"]) {
+    const candidate = usage[key];
+    if (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0) {
+      output[key] = candidate;
+    }
+  }
+  for (const key of ["inputTokens", "outputTokens"]) {
+    const candidate = usage[key];
+    if (typeof candidate === "number" && Number.isInteger(candidate) && candidate >= 0) {
+      output[key] = candidate;
+    }
+  }
+  for (const key of ["provider", "modelId"]) {
+    const candidate = safeMetadataIdentifier(usage[key]);
+    if (candidate !== null) output[key] = candidate;
+  }
+  return Object.keys(output).length > 0 ? output : void 0;
+}
+function successNextActions(toolName, result) {
+  const record = asRecord(result);
+  if (!record) return [];
+  if (toolName.startsWith("thorbit_kb_ingest_")) {
+    return [{
+      toolName: "thorbit_kb_source_status",
+      reason: "Check the real provider-backed source status after ingestion.",
+      input: record.pollInput
+    }];
+  }
+  if (toolName === "thorbit_kb_source_status") {
+    if (record.status === "pending" || record.status === "processing") {
+      return [{
+        toolName: "thorbit_kb_source_status",
+        reason: "Poll this source until it is ready or failed.",
+        input: { sourcePublicIds: [record.sourcePublicId] }
+      }];
+    }
+    if (record.status === "ready") {
+      return [
+        {
+          toolName: "thorbit_kb_search",
+          reason: "Retrieve bounded citation-ready chunks from the ready knowledge base.",
+          input: { knowledgeBasePublicId: record.knowledgeBasePublicId }
+        },
+        {
+          toolName: "thorbit_kb_ask",
+          reason: "Ask a grounded question against the ready knowledge base.",
+          input: { knowledgeBasePublicId: record.knowledgeBasePublicId }
+        }
+      ];
+    }
+  }
+  if (toolName === "thorbit_kb_search") {
+    return [{
+      toolName: "thorbit_kb_ask",
+      reason: "Synthesize a grounded answer when the retrieved chunks are sufficient.",
+      input: { question: record.query }
+    }];
+  }
+  return [];
+}
+function normalizedErrorCode(code) {
+  if (PUBLIC_ERROR_CODES.has(code)) return code;
+  if (code === "ingestion_error" || code === "invalid_response" || code.startsWith("http_")) {
+    return "provider_error";
+  }
+  return "internal_error";
+}
+function errorRecovery(toolName, code) {
+  const transient = code === "provider_error" || code === "rate_limited" || code === "internal_error";
+  if (!transient || !IDEMPOTENT_READ_TOOLS.has(toolName)) {
+    return { retryable: false, next: [] };
+  }
+  return {
+    retryable: true,
+    next: [{
+      toolName,
+      reason: code === "rate_limited" ? "Retry this idempotent read after the rate limit resets." : "Retry this idempotent read after the transient service issue is resolved."
+    }]
+  };
+}
+function projectionErrorDetails(error) {
+  const issueRecord = asRecord(error);
+  const issues = Array.isArray(issueRecord?.issues) ? issueRecord.issues.slice(0, 25).map((issue) => {
+    const issueValue = asRecord(issue);
+    return {
+      path: Array.isArray(issueValue?.path) ? issueValue.path.map(String).join(".") : "",
+      code: typeof issueValue?.code === "string" ? issueValue.code : "invalid_result"
+    };
+  }) : [];
+  return {
+    reason: "Hosted result did not satisfy the exact public Knowledge Base result contract.",
+    ...issues.length > 0 ? { schemaIssues: issues } : {}
+  };
+}
+function successSummary(toolName, result) {
+  const record = asRecord(result);
+  switch (toolName) {
+    case "thorbit_kb_create":
+      return `Created Thorbit knowledge base ${String(record?.name ?? "")}.`;
+    case "thorbit_kb_list":
+      return `Found ${Array.isArray(record?.knowledgeBases) ? record.knowledgeBases.length : 0} Thorbit knowledge bases.`;
+    case "thorbit_kb_source_status":
+      return `Knowledge Base source ${String(record?.sourcePublicId ?? "")} is ${String(record?.status ?? "unknown")}.`;
+    case "thorbit_kb_ingest_url":
+    case "thorbit_kb_ingest_site":
+    case "thorbit_kb_ingest_youtube":
+    case "thorbit_kb_ingest_text":
+      return `Knowledge Base source ${String(record?.sourcePublicId ?? "")} was accepted with status ${String(record?.status ?? "unknown")}.`;
+    case "thorbit_kb_search":
+      return `Retrieved ${Array.isArray(record?.results) ? record.results.length : 0} bounded Knowledge Base chunks with citations.`;
+    case "thorbit_kb_ask":
+      return `Generated a grounded Knowledge Base answer with ${Array.isArray(record?.citations) ? record.citations.length : 0} citations.`;
+  }
+}
+function formatThorbitKbMcpToolResult(toolName, envelope, _requestInput) {
+  const requestId = safeText(envelope.requestId, "unavailable", 256);
+  const outputSchema = ThorbitKnowledgeBaseMcpToolStrictOutputSchemas[toolName];
+  if (!envelope.ok) {
+    const code = normalizedErrorCode(envelope.error.code);
+    const message = safeText(envelope.error.message, "Knowledge Base operation failed.");
+    const recovery = errorRecovery(toolName, code);
+    const structuredContent = outputSchema.parse({
+      ok: false,
+      toolName,
+      requestId,
+      error: {
+        code,
+        message,
+        retryable: recovery.retryable,
+        ...envelope.error.details !== void 0 ? { details: safeDetails(envelope.error.details) } : {}
+      },
+      next: recovery.next
+    });
+    return {
+      content: [{ type: "text", text: `${message} Request ID: ${requestId}.` }],
+      structuredContent,
+      isError: true
+    };
+  }
+  try {
+    const result = normalizeSuccessResult(toolName, envelope.result, envelope.usage);
+    const summary = successSummary(toolName, result);
+    const usage = normalizeUsage(envelope.usage);
+    const structuredContent = outputSchema.parse({
+      ok: true,
+      toolName,
+      requestId,
+      summary,
+      result,
+      artifacts: [],
+      next: successNextActions(toolName, result),
+      warnings: (envelope.warnings ?? []).map((warning) => safeText(warning, "Hosted warning")),
+      ...usage ? { usage } : {}
+    });
+    return {
+      content: [{ type: "text", text: summary }],
+      structuredContent,
+      isError: false
+    };
+  } catch (error) {
+    const message = "Thorbit completed the Knowledge Base operation, but its hosted result could not be projected to the exact public contract.";
+    const structuredContent = outputSchema.parse({
+      ok: false,
+      toolName,
+      requestId,
+      error: {
+        code: "provider_error",
+        message,
+        retryable: false,
+        details: projectionErrorDetails(error)
+      },
+      next: []
+    });
+    return {
+      content: [{ type: "text", text: `${message} Request ID: ${requestId}.` }],
+      structuredContent,
+      isError: true
+    };
+  }
+}
 
 // src/thorbit-kb-mcp-server.ts
-var VERSION = "0.2.8";
-function readOnlyAnnotations(title, idempotent = true) {
+var VERSION = "0.2.9";
+function readOnlyAnnotations(title, idempotent = true, openWorldHint = false) {
   return {
     title,
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: idempotent,
-    openWorldHint: false
+    openWorldHint
   };
 }
 function ingestAnnotations(title, openWorldHint) {
@@ -188,6 +680,101 @@ function ingestAnnotations(title, openWorldHint) {
     openWorldHint
   };
 }
+function defineKnowledgeBaseQuality(quality) {
+  return import_thorbit_mcp_core2.ThorbitMcpToolQualityMetadataSchema.parse({ productId: "kb", ...quality });
+}
+var KNOWLEDGE_BASE_TOOL_QUALITY = {
+  thorbit_kb_create: defineKnowledgeBaseQuality({
+    requiredScopes: ["knowledge_base:ingest"],
+    whenToUse: ["Use to create a new caller-organization or project Knowledge Base."],
+    avoidWhen: ["Avoid when a suitable Knowledge Base already exists; list first."],
+    userPhrases: ["create a knowledge base", "make a RAG library", "start a KB"],
+    costSummary: "Low-cost durable Knowledge Base record creation.",
+    resultMode: "inline",
+    nextTools: ["thorbit_kb_ingest_url", "thorbit_kb_ingest_text"],
+    sideEffects: ["Creates a durable caller-organization Knowledge Base."]
+  }),
+  thorbit_kb_list: defineKnowledgeBaseQuality({
+    requiredScopes: ["knowledge_base:read"],
+    whenToUse: ["Use to find a visible Knowledge Base public ID before ingestion or retrieval."],
+    avoidWhen: ["Avoid when the exact Knowledge Base public ID is already known."],
+    userPhrases: ["list knowledge bases", "find my KB", "show RAG libraries"],
+    costSummary: "Low-cost caller-organization database read.",
+    resultMode: "paginated",
+    nextTools: ["thorbit_kb_search", "thorbit_kb_ask"],
+    sideEffects: []
+  }),
+  thorbit_kb_source_status: defineKnowledgeBaseQuality({
+    requiredScopes: ["knowledge_base:read"],
+    whenToUse: ["Use to poll one provider-backed source receipt returned by ingestion."],
+    avoidWhen: ["Avoid for retrieving chunks or synthesizing an answer."],
+    userPhrases: ["check ingest status", "is this source ready", "poll KB source"],
+    costSummary: "Low-cost caller-organization source status read.",
+    resultMode: "async",
+    nextTools: ["thorbit_kb_search", "thorbit_kb_ask"],
+    sideEffects: []
+  }),
+  thorbit_kb_ingest_url: defineKnowledgeBaseQuality({
+    requiredScopes: ["knowledge_base:ingest"],
+    whenToUse: ["Use to extract and ingest one public URL into a known Knowledge Base."],
+    avoidWhen: ["Avoid for whole websites, YouTube videos, or content already in hand."],
+    userPhrases: ["ingest this URL", "add this page to the KB", "vectorize this web page"],
+    costSummary: "External MCP Scraper extraction plus durable chunking and vectorization.",
+    resultMode: "async",
+    nextTools: ["thorbit_kb_source_status"],
+    sideEffects: ["Creates an append-only durable Knowledge Base source and chunks."]
+  }),
+  thorbit_kb_ingest_site: defineKnowledgeBaseQuality({
+    requiredScopes: ["knowledge_base:ingest"],
+    whenToUse: ["Use to map and ingest a bounded set of pages from one website."],
+    avoidWhen: ["Avoid for one known URL, which is cheaper through URL ingestion."],
+    userPhrases: ["ingest this website", "crawl pages into the KB", "build a KB from this site"],
+    costSummary: "Bounded MCP Scraper mapping and extraction plus durable vectorization per page.",
+    resultMode: "async",
+    nextTools: ["thorbit_kb_source_status"],
+    sideEffects: ["Creates append-only Knowledge Base sources and chunks for accepted pages."]
+  }),
+  thorbit_kb_ingest_youtube: defineKnowledgeBaseQuality({
+    requiredScopes: ["knowledge_base:ingest"],
+    whenToUse: ["Use to transcribe and ingest one YouTube video into a known Knowledge Base."],
+    avoidWhen: ["Avoid for web pages or caller-supplied text."],
+    userPhrases: ["ingest this YouTube video", "add this transcript to the KB", "vectorize this video"],
+    costSummary: "External transcription plus durable chunking and vectorization.",
+    resultMode: "async",
+    nextTools: ["thorbit_kb_source_status"],
+    sideEffects: ["Creates an append-only durable transcript source and chunks."]
+  }),
+  thorbit_kb_ingest_text: defineKnowledgeBaseQuality({
+    requiredScopes: ["knowledge_base:ingest"],
+    whenToUse: ["Use to ingest text or Markdown already supplied by the caller."],
+    avoidWhen: ["Avoid when Thorbit must fetch a URL, website, or YouTube transcript."],
+    userPhrases: ["ingest this text", "add these notes to the KB", "vectorize this Markdown"],
+    costSummary: "Durable chunking and vectorization without external scraping.",
+    resultMode: "async",
+    nextTools: ["thorbit_kb_source_status"],
+    sideEffects: ["Creates an append-only durable Knowledge Base source and chunks."]
+  }),
+  thorbit_kb_search: defineKnowledgeBaseQuality({
+    requiredScopes: ["knowledge_base:read"],
+    whenToUse: ["Use to retrieve bounded citation-ready chunks without answer synthesis."],
+    avoidWhen: ["Avoid when the caller wants a direct grounded answer."],
+    userPhrases: ["search the KB", "retrieve source chunks", "find citation evidence"],
+    costSummary: "Bounded vector or hybrid retrieval and optional reranking.",
+    resultMode: "inline",
+    nextTools: ["thorbit_kb_ask"],
+    sideEffects: []
+  }),
+  thorbit_kb_ask: defineKnowledgeBaseQuality({
+    requiredScopes: ["knowledge_base:read", "knowledge_base:ask"],
+    whenToUse: ["Use to synthesize a direct answer grounded in bounded Knowledge Base citations."],
+    avoidWhen: ["Avoid when raw retrieved passages are required for caller-side reasoning."],
+    userPhrases: ["ask the knowledge base", "answer from my KB", "give me a cited answer"],
+    costSummary: "Bounded retrieval plus potentially metered model answer generation.",
+    resultMode: "inline",
+    nextTools: ["thorbit_kb_search"],
+    sideEffects: []
+  })
+};
 var SERVER_INSTRUCTIONS = [
   "Thorbit Knowledge Base MCP. Vector-backed knowledge bases for ingestion, smart RAG search, and grounded Q&A with citations. This server is a thin client, authenticated and metered against your Thorbit MCP API key.",
   "",
@@ -207,9 +794,7 @@ var SERVER_INSTRUCTIONS = [
   "- Need citation-ready chunks yourself, not a synthesized answer -> **thorbit_kb_search**.",
   '- Need a direct answer grounded in retrieved context -> **thorbit_kb_ask** (set answerStyle:"extractive" for source excerpts without an LLM-written answer). Use thorbit_kb_search instead when you want the raw chunks to reason over yourself.'
 ].join("\n");
-function buildThorbitKnowledgeBaseMcpServer(options) {
-  const callTool = (toolName, input) => options.callTool(toolName, input);
-  const server = new import_mcp.McpServer({ name: "thorbit-kb-mcp", version: VERSION }, { instructions: SERVER_INSTRUCTIONS });
+function registerThorbitKnowledgeBaseResources(server, callTool) {
   server.registerResource(
     "knowledge-bases",
     "thorbit-kb://knowledge-bases",
@@ -233,70 +818,109 @@ function buildThorbitKnowledgeBaseMcpServer(options) {
     },
     async (uri, variables) => {
       const sourcePublicId = Array.isArray(variables.sourcePublicId) ? variables.sourcePublicId[0] : variables.sourcePublicId;
-      const envelope = await callTool("thorbit_kb_source_status", { sourcePublicIds: [String(sourcePublicId)] });
+      const envelope = await callTool("thorbit_kb_source_status", {
+        sourcePublicIds: [String(sourcePublicId)]
+      });
       return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(envelope, null, 2) }] };
     }
   );
+}
+function registerThorbitKnowledgeBaseMcpTools(server, callTool) {
   function registerTool(toolName, config) {
-    server.registerTool(toolName, config, async (input) => {
-      const envelope = await callTool(toolName, input);
-      return formatThorbitKbMcpToolResult(toolName, envelope);
-    });
+    server.registerTool(toolName, {
+      title: config.title,
+      description: config.description,
+      inputSchema: config.inputSchema,
+      outputSchema: config.outputSchema,
+      annotations: config.annotations,
+      _meta: { thorbit: config.quality }
+    }, async (input) => formatThorbitKbMcpToolResult(
+      toolName,
+      await callTool(toolName, input),
+      input
+    ));
   }
   registerTool("thorbit_kb_create", {
     title: "Create Thorbit Knowledge Base",
     description: "Create a new vector-backed knowledge base for ingestion, RAG search, and grounded Q&A. Org-level by default; pass projectPublicId to scope it to one project. Use thorbit_kb_list first if you're not sure whether a suitable knowledge base already exists.",
     inputSchema: ThorbitKbCreateInputSchema,
-    annotations: ingestAnnotations("Create Thorbit Knowledge Base", false)
+    outputSchema: ThorbitKnowledgeBaseMcpToolOutputSchemas.thorbit_kb_create,
+    annotations: ingestAnnotations("Create Thorbit Knowledge Base", false),
+    quality: KNOWLEDGE_BASE_TOOL_QUALITY.thorbit_kb_create
   });
   registerTool("thorbit_kb_list", {
     title: "List Thorbit Knowledge Bases",
     description: "List knowledge bases visible to this API key, org-level and project-scoped. Use before ingestion/search when you don't already have the target knowledgeBasePublicId \u2014 every ingest tool needs one (search/ask can omit it to query all visible KBs instead).",
     inputSchema: ThorbitKbListInputSchema,
-    annotations: readOnlyAnnotations("List Thorbit Knowledge Bases")
+    outputSchema: ThorbitKnowledgeBaseMcpToolOutputSchemas.thorbit_kb_list,
+    annotations: readOnlyAnnotations("List Thorbit Knowledge Bases"),
+    quality: KNOWLEDGE_BASE_TOOL_QUALITY.thorbit_kb_list
   });
   registerTool("thorbit_kb_source_status", {
     title: "Read Thorbit KB Source Status",
-    description: "Poll ingestion status for source public IDs returned by any thorbit_kb_ingest_* tool \u2014 the only way to check whether an ingest finished, since the ingest tools may return before vectorization completes.",
+    description: "Poll ingestion status for a source public ID returned by a thorbit_kb_ingest_* tool. Returns the real source state, progress, safe error, and updated time; continue polling until ready or failed, then use thorbit_kb_search or thorbit_kb_ask.",
     inputSchema: ThorbitKbSourceStatusInputSchema,
-    annotations: readOnlyAnnotations("Read Thorbit KB Source Status")
+    outputSchema: ThorbitKnowledgeBaseMcpToolOutputSchemas.thorbit_kb_source_status,
+    annotations: readOnlyAnnotations("Read Thorbit KB Source Status"),
+    quality: KNOWLEDGE_BASE_TOOL_QUALITY.thorbit_kb_source_status
   });
   registerTool("thorbit_kb_ingest_url", {
     title: "Ingest URL Into Thorbit KB",
-    description: "Extract ONE public URL through MCP Scraper, clean it, and vectorize it into a knowledge base (up to 500,000 chars before chunking). For a whole site instead of one page, use thorbit_kb_ingest_site. Append-only: re-ingesting the same URL adds a new source version rather than replacing the prior one \u2014 there is no refresh mode in this version.",
+    description: "Extract ONE public URL through MCP Scraper, clean it, and vectorize it into a knowledge base (up to 500,000 chars before chunking). For a whole site instead of one page, use thorbit_kb_ingest_site. Append-only: re-ingesting adds a new source version. Returns a real source receipt and thorbit_kb_source_status follow-up.",
     inputSchema: ThorbitKbIngestUrlInputSchema,
-    annotations: ingestAnnotations("Ingest URL Into Thorbit KB", true)
+    outputSchema: ThorbitKnowledgeBaseMcpToolOutputSchemas.thorbit_kb_ingest_url,
+    annotations: ingestAnnotations("Ingest URL Into Thorbit KB", true),
+    quality: KNOWLEDGE_BASE_TOOL_QUALITY.thorbit_kb_ingest_url
   });
   registerTool("thorbit_kb_ingest_site", {
     title: "Ingest Website Into Thorbit KB",
-    description: "Map a website through MCP Scraper, extract selected pages (up to 100, default 25, filterable via includePatterns/excludePatterns), and vectorize each into a knowledge base. For a single known page instead of crawling a site, use thorbit_kb_ingest_url \u2014 cheaper and faster. Append-only, same as thorbit_kb_ingest_url.",
+    description: "Map a website through MCP Scraper, extract selected pages (up to 100, default 25), and vectorize them. For one known page, use thorbit_kb_ingest_url because it is cheaper and faster. The exact public receipt succeeds only when Phoenix supplies one unambiguous source; multi-source provider batches fail closed rather than hiding source IDs.",
     inputSchema: ThorbitKbIngestSiteInputSchema,
-    annotations: ingestAnnotations("Ingest Website Into Thorbit KB", true)
+    outputSchema: ThorbitKnowledgeBaseMcpToolOutputSchemas.thorbit_kb_ingest_site,
+    annotations: ingestAnnotations("Ingest Website Into Thorbit KB", true),
+    quality: KNOWLEDGE_BASE_TOOL_QUALITY.thorbit_kb_ingest_site
   });
   registerTool("thorbit_kb_ingest_youtube", {
     title: "Ingest YouTube Into Thorbit KB",
-    description: "Transcribe a YouTube video through MCP Scraper and vectorize the transcript (timestamp chunks preserved by default) into a knowledge base. For web pages or raw text instead of video, use thorbit_kb_ingest_url or thorbit_kb_ingest_text.",
+    description: "Transcribe one YouTube video through MCP Scraper and vectorize the transcript, preserving timestamp chunks by default. For web pages or raw text, use thorbit_kb_ingest_url or thorbit_kb_ingest_text. Returns the real source receipt and a thorbit_kb_source_status follow-up.",
     inputSchema: ThorbitKbIngestYoutubeInputSchema,
-    annotations: ingestAnnotations("Ingest YouTube Into Thorbit KB", true)
+    outputSchema: ThorbitKnowledgeBaseMcpToolOutputSchemas.thorbit_kb_ingest_youtube,
+    annotations: ingestAnnotations("Ingest YouTube Into Thorbit KB", true),
+    quality: KNOWLEDGE_BASE_TOOL_QUALITY.thorbit_kb_ingest_youtube
   });
   registerTool("thorbit_kb_ingest_text", {
     title: "Ingest Text Into Thorbit KB",
-    description: "Submit text or Markdown you already have directly into a knowledge base \u2014 no scraping involved. Use this instead of thorbit_kb_ingest_url when you already have the content in hand rather than a URL to fetch.",
+    description: "Submit bounded text or Markdown already in hand directly into a knowledge base with no scraping. Use thorbit_kb_ingest_url when content must be fetched. Returns the real source receipt and a thorbit_kb_source_status follow-up after durable chunking and vectorization.",
     inputSchema: ThorbitKbIngestTextInputSchema,
-    annotations: ingestAnnotations("Ingest Text Into Thorbit KB", false)
+    outputSchema: ThorbitKnowledgeBaseMcpToolOutputSchemas.thorbit_kb_ingest_text,
+    annotations: ingestAnnotations("Ingest Text Into Thorbit KB", false),
+    quality: KNOWLEDGE_BASE_TOOL_QUALITY.thorbit_kb_ingest_text
   });
   registerTool("thorbit_kb_search", {
     title: "Search Thorbit Knowledge Base",
-    description: "Search knowledge-base content and get citation-ready chunks back directly, without a synthesized answer. Use this instead of thorbit_kb_ask when you want to reason over the raw retrieved passages yourself. Omit knowledgeBasePublicId to search all KBs visible to this key.",
+    description: "Search visible knowledge-base content and return at most 50 bounded, scored chunks plus bounded provider citations, without synthesizing an answer. Use thorbit_kb_ask for a direct grounded response. Omit knowledgeBasePublicId to search visible KBs.",
     inputSchema: ThorbitKbSearchInputSchema,
-    annotations: readOnlyAnnotations("Search Thorbit Knowledge Base")
+    outputSchema: ThorbitKnowledgeBaseMcpToolOutputSchemas.thorbit_kb_search,
+    annotations: readOnlyAnnotations("Search Thorbit Knowledge Base", true, true),
+    quality: KNOWLEDGE_BASE_TOOL_QUALITY.thorbit_kb_search
   });
   registerTool("thorbit_kb_ask", {
     title: "Ask Thorbit Knowledge Base",
-    description: 'Answer a question using ONLY retrieved knowledge-base context \u2014 returns the answer, citations, sufficiency, and retrieval metadata. Set answerStyle:"extractive" for source excerpts without an LLM-written answer. Use thorbit_kb_search instead when you want the raw chunks rather than a synthesized answer.',
+    description: "Answer a question using only retrieved Knowledge Base context and return a bounded answer, citations, follow-ups, and nullable real model ID. Use extractive style for excerpts; use thorbit_kb_search for raw scored chunks. This may invoke a metered answer model.",
     inputSchema: ThorbitKbAskInputSchema,
-    annotations: readOnlyAnnotations("Ask Thorbit Knowledge Base", false)
+    outputSchema: ThorbitKnowledgeBaseMcpToolOutputSchemas.thorbit_kb_ask,
+    annotations: readOnlyAnnotations("Ask Thorbit Knowledge Base", false, true),
+    quality: KNOWLEDGE_BASE_TOOL_QUALITY.thorbit_kb_ask
   });
+}
+function buildThorbitKnowledgeBaseMcpServer(options) {
+  const callTool = (toolName, input) => options.callTool(toolName, input);
+  const server = new import_mcp.McpServer(
+    { name: "thorbit-kb-mcp", version: VERSION },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
+  registerThorbitKnowledgeBaseResources(server, callTool);
+  registerThorbitKnowledgeBaseMcpTools(server, callTool);
   return server;
 }