jishushell 0.6.18 → 0.7.3

package/dist/services/integrations/openclaw/jishukb-shim.js

@@ -9,9 +9,11 @@
  *
  * Scope intentionally stays typed and bounded:
  *   - Read/search: list KBs, search, list documents, read handbook, read
- *     sanitized config
- *   - Write: create KBs, upload documents into a chosen KB
- *   - Dangerous delete operations require explicit confirmation arguments
+ *     document metadata/source/chunks/FAQ, inspect ingest jobs, and read
+ *     sanitized config/capabilities
+ *   - Write: create KBs, upload documents, import URLs, retry jobs, and
+ *     reindex documents in a chosen KB
+ *   - Dangerous delete/cancel/reindex operations require explicit confirmation arguments
  *   - No raw admin/provider passthrough: secrets and arbitrary provider edits
  *     remain outside the agent surface
  *
@@ -26,7 +28,7 @@
  * Stdio framing: NDJSON JSON-RPC 2.0 (MCP standard). Pure Node builtins, no
  * npm install needed inside the runtime image.
  */
-export const JISHUKB_MCP_SHIM_VERSION = "0.2.0";
+export const JISHUKB_MCP_SHIM_VERSION = "0.3.0";
 /** Default topK when the caller doesn't specify one. Mirrors the manifest
  * `JISHU_KB_TOPK` default so the agent and the backend agree on page size. */
 export const JISHUKB_DEFAULT_TOPK = 6;
@@ -34,6 +36,8 @@ export const JISHUKB_DEFAULT_TOPK = 6;
 export const JISHUKB_FETCH_TIMEOUT_MS = 60_000;
 /** Soft guard for upload memory use. */
 export const JISHUKB_MAX_UPLOAD_BYTES = 30 * 1024 * 1024;
+/** Soft guard for text returned through MCP. */
+export const JISHUKB_MAX_TEXT_RESPONSE_CHARS = 12_000;
 export const JISHUKB_MCP_SHIM_SOURCE = `#!/usr/bin/env node
 // jishushell-jishukb-shim — generated, do not edit by hand.
 // Source: src/services/integrations/openclaw/jishukb-shim.ts
@@ -44,6 +48,7 @@ const ALLOWED_UPLOAD_ROOTS_LIT = "__JS_ALLOWED_UPLOAD_ROOTS__";
 
 const fs = require("node:fs");
 const path = require("node:path");
+const { TextDecoder } = require("node:util");
 
 const BASE_URL = (BASE_URL_LIT.startsWith("__JS_") ? (process.env.JISHUKB_BASE_URL || "") : BASE_URL_LIT).replace(/\\/+$/, "");
 const KB_ID = KB_ID_LIT.startsWith("__JS_") ? trimString(process.env.JISHUKB_KB_ID || "") : trimString(KB_ID_LIT);
@@ -55,6 +60,7 @@ const ALLOWED_UPLOAD_ROOTS = (
 const DEFAULT_TOPK = ${JISHUKB_DEFAULT_TOPK};
 const FETCH_TIMEOUT = ${JISHUKB_FETCH_TIMEOUT_MS};
 const MAX_UPLOAD_BYTES = ${JISHUKB_MAX_UPLOAD_BYTES};
+const MAX_TEXT_RESPONSE_CHARS = ${JISHUKB_MAX_TEXT_RESPONSE_CHARS};
 const OPEN_UPLOAD_FLAGS = fs.constants.O_RDONLY
   | (typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0)
   | (typeof fs.constants.O_NONBLOCK === "number" ? fs.constants.O_NONBLOCK : 0);
@@ -66,7 +72,9 @@ function envCheck() {
 }
 
 function trimString(raw) {
-  return typeof raw === "string" ? raw.trim() : "";
+  if (typeof raw === "string") return raw.trim();
+  if (typeof raw === "number" || typeof raw === "boolean") return String(raw).trim();
+  return "";
 }
 
 function jsonText(value) {
@@ -247,6 +255,205 @@ async function readText(toolName, relativePath, options) {
   return await res.text();
 }
 
+function cappedText(raw, maxChars) {
+  const text = String(raw ?? "");
+  if (text.length <= maxChars) {
+    return { text, truncated: false, characters: text.length };
+  }
+  return {
+    text: text.slice(0, Math.max(0, maxChars - 1)) + "…",
+    truncated: true,
+    characters: text.length,
+  };
+}
+
+function optionalString(raw) {
+  const value = trimString(raw);
+  return value || null;
+}
+
+function positiveInt(raw, fallback, max) {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return fallback;
+  const i = Math.floor(n);
+  if (i < 1) return fallback;
+  return Math.min(i, max);
+}
+
+function boolWithDefault(raw, fallback) {
+  if (raw === undefined || raw === null || raw === "") return fallback;
+  if (typeof raw === "boolean") return raw;
+  const text = trimString(raw).toLowerCase();
+  if (["1", "true", "yes", "y"].includes(text)) return true;
+  if (["0", "false", "no", "n"].includes(text)) return false;
+  return fallback;
+}
+
+function appendOptionalQuery(qs, key, value) {
+  const text = trimString(value);
+  if (text) qs.set(key, text);
+}
+
+function encodePathPart(value) {
+  return encodeURIComponent(value);
+}
+
+function normalizeBacklinks(raw) {
+  return Array.isArray(raw) ? raw : [];
+}
+
+function normalizeDocument(item, kbId) {
+  const doc = item && typeof item === "object" ? item : {};
+  return {
+    id: doc.id || null,
+    kbId: doc.kb_id || doc.kbId || kbId || null,
+    title: doc.title || null,
+    relPath: doc.rel_path || doc.relPath || null,
+    mime: doc.mime || null,
+    sha256: doc.sha256 || null,
+    bytes: doc.bytes ?? null,
+    status: doc.status || null,
+    createdAt: doc.created_at ?? doc.createdAt ?? null,
+    origin: doc.origin || null,
+    sourcePath: doc.source_path || doc.sourcePath || null,
+    sourceUrl: doc.source_url || doc.sourceUrl || null,
+    batchId: doc.batch_id || doc.batchId || null,
+    clientItemId: doc.client_item_id || doc.clientItemId || null,
+    externalAssetId: doc.external_asset_id || doc.externalAssetId || null,
+    backlinks: normalizeBacklinks(doc.backlinks),
+    chunkCount: doc.chunkCount ?? null,
+    faqCount: doc.faqCount ?? null,
+    jobCount: doc.jobCount ?? null,
+  };
+}
+
+function normalizeJob(item, kbId) {
+  const job = item && typeof item === "object" ? item : {};
+  return {
+    id: job.id || null,
+    docId: job.docId || job.doc_id || null,
+    kbId: job.kbId || job.kb_id || kbId || null,
+    filename: job.filename || null,
+    relPath: job.relPath || job.rel_path || null,
+    mime: job.mime || null,
+    sha256: job.sha256 || null,
+    bytes: job.bytes ?? null,
+    status: job.status || null,
+    stage: job.stage || null,
+    progressCurrent: job.progressCurrent ?? job.progress_current ?? null,
+    progressTotal: job.progressTotal ?? job.progress_total ?? null,
+    attempts: job.attempts ?? null,
+    error: job.error || null,
+    createdAt: job.createdAt ?? job.created_at ?? null,
+    updatedAt: job.updatedAt ?? job.updated_at ?? null,
+    origin: job.origin || null,
+    sourcePath: job.sourcePath || job.source_path || null,
+    sourceUrl: job.sourceUrl || job.source_url || null,
+    batchId: job.batchId || job.batch_id || null,
+    clientItemId: job.clientItemId || job.client_item_id || null,
+    externalAssetId: job.externalAssetId || job.external_asset_id || null,
+  };
+}
+
+function documentArrayFromPayload(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (payload && Array.isArray(payload.documents)) return payload.documents;
+  if (payload && Array.isArray(payload.items)) return payload.items;
+  return null;
+}
+
+function jobArrayFromPayload(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (payload && Array.isArray(payload.jobs)) return payload.jobs;
+  if (payload && Array.isArray(payload.items)) return payload.items;
+  return null;
+}
+
+function mediaType(raw) {
+  return trimString(raw).toLowerCase().split(";")[0].trim();
+}
+
+function isTextLikeContentType(raw) {
+  const type = mediaType(raw);
+  if (!type) return false;
+  if (type.startsWith("text/")) return true;
+  return [
+    "application/ecmascript",
+    "application/javascript",
+    "application/json",
+    "application/sql",
+    "application/toml",
+    "application/x-ndjson",
+    "application/x-yaml",
+    "application/xhtml+xml",
+    "application/xml",
+    "application/yaml",
+  ].includes(type) || type.endsWith("+json") || type.endsWith("+xml");
+}
+
+function contentLengthOf(headers) {
+  const raw = trimString(headers?.get?.("content-length"));
+  if (!raw) return null;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+async function readBoundedTextResponse(toolName, res, maxChars) {
+  const contentType = res.headers.get("content-type") || "";
+  const contentDisposition = res.headers.get("content-disposition") || null;
+  const contentLength = contentLengthOf(res.headers);
+  if (!isTextLikeContentType(contentType)) {
+    try { await res.body?.cancel?.(); } catch { /* ignore cleanup errors */ }
+    throw new Error(
+      toolName + ": raw document is not text-like" +
+      " (contentType=" + (contentType || "unknown") +
+      (contentLength != null ? ", contentLength=" + contentLength : "") +
+      (contentDisposition ? ", contentDisposition=" + contentDisposition : "") +
+      "). Use kb_get_document for metadata; binary originals should be opened through the file surface.",
+    );
+  }
+  if (!res.body || typeof res.body.getReader !== "function") {
+    throw new Error(toolName + ": upstream response does not support bounded streaming");
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  let text = "";
+  let bytesRead = 0;
+  let truncated = false;
+  try {
+    while (text.length <= maxChars) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      const value = chunk.value || new Uint8Array();
+      bytesRead += value.byteLength || 0;
+      text += decoder.decode(value, { stream: true });
+      if (text.length > maxChars) {
+        truncated = true;
+        try { await reader.cancel(); } catch { /* ignore cleanup errors */ }
+        break;
+      }
+    }
+    if (!truncated) {
+      text += decoder.decode();
+      if (text.length > maxChars) {
+        truncated = true;
+      }
+    }
+  } finally {
+    try { reader.releaseLock?.(); } catch { /* ignore cleanup errors */ }
+  }
+  if (truncated) {
+    text = text.slice(0, Math.max(0, maxChars - 1)) + "…";
+  }
+  return {
+    text,
+    truncated,
+    characters: text.length,
+    bytesRead,
+    contentLength,
+  };
+}
+
 function normalizeChunksResponse(payload) {
   const j = payload && typeof payload === "object" ? payload : {};
   const rawChunks = Array.isArray(j.chunks) ? j.chunks
@@ -384,6 +591,7 @@ async function kbList() {
       name: item?.name || null,
       description: item?.description ?? null,
       chunks: item?.chunks ?? null,
+      documents: item?.documents ?? item?.docCount ?? item?.documentCount ?? null,
       createdAt: item?.created_at ?? null,
       usable: false,
       unavailableReason: null,
@@ -399,6 +607,11 @@ async function kbList() {
         { headers: { Accept: "application/json" } },
       );
       if (res.ok) {
+        const docs = await res.json();
+        const docRows = documentArrayFromPayload(docs);
+        if (docRows) {
+          row.documents = docRows.length;
+        }
         row.usable = true;
         return row;
       }
@@ -434,6 +647,41 @@ async function kbCreate(name, kbId, description) {
   };
 }
 
+async function kbGetCapabilities() {
+  const payload = await readJson("kb_get_capabilities", "/api/service/capabilities");
+  return {
+    contractVersion: payload?.contractVersion || null,
+    serviceVersion: payload?.serviceVersion || null,
+    auth: payload?.auth || null,
+    features: payload?.features || {},
+    limits: payload?.limits || {},
+    upload: payload?.upload ? {
+      shortFormats: payload.upload.shortFormats || [],
+      formatsDetail: payload.upload.formatsDetail || null,
+      extensions: payload.upload.extensions || [],
+    } : null,
+    routes: payload?.routes || null,
+  };
+}
+
+async function kbGet(kbIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_get");
+  const payload = await readJson(
+    "kb_get",
+    "/api/kb/" + encodePathPart(kbId),
+  );
+  return {
+    id: payload?.id || kbId,
+    name: payload?.name || null,
+    description: payload?.description ?? null,
+    documents: payload?.documents ?? payload?.docCount ?? payload?.documentCount ?? null,
+    chunks: payload?.chunks ?? null,
+    jobs: payload?.jobs ?? payload?.jobCount ?? null,
+    createdAt: payload?.created_at ?? payload?.createdAt ?? null,
+    config: payload?.config || payload?.retrieval || null,
+  };
+}
+
 async function kbSearch(query, kbIdRaw, topK) {
   const trimmedQuery = trimString(query);
   if (!trimmedQuery) throw new Error("kb_search: missing 'query' argument");
@@ -488,17 +736,205 @@ async function kbListDocuments(kbIdRaw) {
     "kb_list_documents",
     "/api/kb/" + encodeURIComponent(kbId) + "/documents",
   );
-  if (!Array.isArray(payload)) {
-    throw new Error("kb_list_documents: upstream returned a non-array payload");
-  }
-  return payload.map((item) => ({
-    id: item?.id || null,
-    kbId: item?.kb_id || kbId,
-    title: item?.title || null,
-    bytes: item?.bytes ?? null,
-    status: item?.status || null,
-    createdAt: item?.created_at ?? null,
-  }));
+  const docs = documentArrayFromPayload(payload);
+  if (!docs) {
+    throw new Error("kb_list_documents: upstream returned a non-array document payload");
+  }
+  return docs.map((item) => normalizeDocument(item, kbId));
+}
+
+async function kbGetDocument(kbIdRaw, documentIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_get_document");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_get_document: missing 'documentId' argument");
+  const payload = await readJson(
+    "kb_get_document",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId),
+  );
+  return normalizeDocument(payload, kbId);
+}
+
+async function kbListDocumentChunks(kbIdRaw, documentIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_list_document_chunks");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_list_document_chunks: missing 'documentId' argument");
+  const payload = await readJson(
+    "kb_list_document_chunks",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId) + "/chunks",
+  );
+  const rawChunks = Array.isArray(payload) ? payload : Array.isArray(payload?.chunks) ? payload.chunks : null;
+  if (!rawChunks) {
+    throw new Error("kb_list_document_chunks: upstream returned a non-array chunks payload");
+  }
+  return rawChunks.map((item, idx) => {
+    const chunk = item && typeof item === "object" ? item : { text: String(item ?? "") };
+    const capped = cappedText(chunk.text || chunk.content || "", 1600);
+    return {
+      id: chunk.id ?? null,
+      chunkIndex: chunk.chunk_index ?? chunk.chunkIndex ?? idx,
+      page: chunk.page ?? null,
+      text: capped.text,
+      truncated: capped.truncated,
+      characters: capped.characters,
+    };
+  });
+}
+
+async function kbReadDocumentRaw(kbIdRaw, documentIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_read_document_raw");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_read_document_raw: missing 'documentId' argument");
+  const res = await fetchWithTimeout(
+    "kb_read_document_raw",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId) + "/raw",
+    { headers: { Accept: "text/plain, application/octet-stream;q=0.5, */*;q=0.1" } },
+  );
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error("kb_read_document_raw: upstream " + res.status + ": " + txt.slice(0, 400));
+  }
+  const capped = await readBoundedTextResponse("kb_read_document_raw", res, MAX_TEXT_RESPONSE_CHARS);
+  return {
+    kbId,
+    documentId,
+    contentType: res.headers.get("content-type") || null,
+    contentDisposition: res.headers.get("content-disposition") || null,
+    text: capped.text,
+    truncated: capped.truncated,
+    characters: capped.characters,
+    bytesRead: capped.bytesRead,
+    contentLength: capped.contentLength,
+  };
+}
+
+async function kbListDocumentFaq(kbIdRaw, documentIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_list_document_faq");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_list_document_faq: missing 'documentId' argument");
+  const payload = await readJson(
+    "kb_list_document_faq",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId) + "/faq",
+  );
+  const faqs = Array.isArray(payload) ? payload : Array.isArray(payload?.faqs) ? payload.faqs : null;
+  if (!faqs) {
+    throw new Error("kb_list_document_faq: upstream returned a non-array FAQ payload");
+  }
+  return faqs;
+}
+
+async function kbReindexDocument(kbIdRaw, documentIdRaw, confirmDocumentIdRaw) {
+  const kbId = requireKbId(kbIdRaw, "kb_reindex_document");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_reindex_document: missing 'documentId' argument");
+  requireConfirm(confirmDocumentIdRaw, documentId, "kb_reindex_document", "confirmDocumentId");
+  const payload = await readJson(
+    "kb_reindex_document",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId) + "/reindex",
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" },
+  );
+  return {
+    kbId,
+    documentId,
+    doc: payload?.doc ? normalizeDocument(payload.doc, kbId) : null,
+    parents: payload?.parents ?? null,
+    chunks: payload?.chunks ?? null,
+    removedChunks: payload?.removedChunks ?? null,
+    faqRegeneration: payload?.faqRegeneration || null,
+    sourceGeneration: payload?.sourceGeneration || null,
+  };
+}
+
+async function kbImportUrl(args) {
+  const kbId = requireKbId(args?.kbId, "kb_import_url");
+  const url = trimString(args?.url);
+  if (!url) throw new Error("kb_import_url: missing 'url' argument");
+  const asyncMode = boolWithDefault(args?.async, true);
+  const payload = { url };
+  for (const key of ["origin", "sourcePath", "batchId", "clientItemId", "externalAssetId"]) {
+    const value = optionalString(args?.[key]);
+    if (value) payload[key] = value;
+  }
+  const headers = { "Content-Type": "application/json" };
+  const idempotencyKey = optionalString(args?.idempotencyKey);
+  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+  const result = await readJson(
+    "kb_import_url",
+    "/api/kb/" + encodePathPart(kbId) + "/import" + (asyncMode ? "?async=true" : ""),
+    { method: "POST", headers, body: JSON.stringify(payload) },
+  );
+  return {
+    kbId,
+    async: asyncMode,
+    sourceUrl: result?.sourceUrl || null,
+    job: result?.job ? normalizeJob(result.job, kbId) : null,
+    doc: result?.doc ? normalizeDocument(result.doc, kbId) : null,
+    chunks: result?.chunks ?? null,
+    parents: result?.parents ?? null,
+    idempotencyKey: result?.idempotencyKey || idempotencyKey || null,
+    replayed: !!result?.replayed,
+  };
+}
+
+async function kbListJobs(args) {
+  const kbId = defaultKbId(args?.kbId, "kb_list_jobs");
+  const qs = new URLSearchParams();
+  const limit = positiveInt(args?.limit, null, 100);
+  if (limit) qs.set("limit", String(limit));
+  appendOptionalQuery(qs, "cursor", args?.cursor);
+  appendOptionalQuery(qs, "status", args?.status);
+  appendOptionalQuery(qs, "clientItemId", args?.clientItemId);
+  appendOptionalQuery(qs, "batchId", args?.batchId);
+  const query = qs.toString();
+  const payload = await readJson(
+    "kb_list_jobs",
+    "/api/kb/" + encodePathPart(kbId) + "/jobs" + (query ? "?" + query : ""),
+  );
+  const jobs = jobArrayFromPayload(payload);
+  if (!jobs) {
+    throw new Error("kb_list_jobs: upstream returned a non-array jobs payload");
+  }
+  return {
+    jobs: jobs.map((item) => normalizeJob(item, kbId)),
+    nextCursor: payload?.nextCursor ?? null,
+    totalEstimate: payload?.totalEstimate ?? null,
+    limit: payload?.limit ?? limit ?? null,
+  };
+}
+
+async function kbGetJob(kbIdRaw, jobIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_get_job");
+  const jobId = trimString(jobIdRaw);
+  if (!jobId) throw new Error("kb_get_job: missing 'jobId' argument");
+  const payload = await readJson(
+    "kb_get_job",
+    "/api/kb/" + encodePathPart(kbId) + "/jobs/" + encodePathPart(jobId),
+  );
+  return normalizeJob(payload, kbId);
+}
+
+async function kbRetryJob(kbIdRaw, jobIdRaw) {
+  const kbId = requireKbId(kbIdRaw, "kb_retry_job");
+  const jobId = trimString(jobIdRaw);
+  if (!jobId) throw new Error("kb_retry_job: missing 'jobId' argument");
+  const payload = await readJson(
+    "kb_retry_job",
+    "/api/kb/" + encodePathPart(kbId) + "/jobs/" + encodePathPart(jobId) + "/retry",
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" },
+  );
+  return normalizeJob(payload, kbId);
+}
+
+async function kbCancelJob(kbIdRaw, jobIdRaw, confirmJobIdRaw) {
+  const kbId = requireKbId(kbIdRaw, "kb_cancel_job");
+  const jobId = trimString(jobIdRaw);
+  if (!jobId) throw new Error("kb_cancel_job: missing 'jobId' argument");
+  requireConfirm(confirmJobIdRaw, jobId, "kb_cancel_job", "confirmJobId");
+  const payload = await readJson(
+    "kb_cancel_job",
+    "/api/kb/" + encodePathPart(kbId) + "/jobs/" + encodePathPart(jobId) + "/cancel",
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" },
+  );
+  return normalizeJob(payload, kbId);
 }
 
 async function kbReadHandbook(section) {
@@ -554,7 +990,12 @@ async function kbDeleteKb(kbIdRaw, confirmKbIdRaw) {
 const TOOLS = [
   {
     name: "kb_list",
-    description: "List knowledge bases and validate whether each id can be used by document/search APIs. Only use entries with usable=true for follow-up calls.",
+    description: "List knowledge bases and validate whether each id can be used by document/search APIs. Returns documents=file count and chunks=index chunk count; use documents when the user asks how many files are in a KB. Only use entries with usable=true for follow-up calls.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "kb_get_capabilities",
+    description: "Read the JishuShell-KB external-control capability summary, including enabled features, upload formats, limits, and route inventory pointer. Does not expose secrets.",
     inputSchema: { type: "object", properties: {} },
   },
   {
@@ -570,6 +1011,16 @@ const TOOLS = [
       required: ["name"],
     },
   },
+  {
+    name: "kb_get",
+    description: "Read one knowledge base's metadata, counts, and safe retrieval/config summary. If kbId is omitted the wired default KB is used.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+      },
+    },
+  },
   {
     name: "kb_search",
     description: "Search a knowledge base for chunks relevant to a question. Use whenever the user asks something likely answered by indexed documents. If kbId is omitted the default KB is used.",
@@ -605,6 +1056,138 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: "kb_get_document",
+    description: "Read one indexed document's metadata and derived counts. Use after kb_list_documents when the user asks about a specific document.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        documentId: { type: "string", description: "Document id to inspect" },
+      },
+      required: ["documentId"],
+    },
+  },
+  {
+    name: "kb_list_document_chunks",
+    description: "List indexed chunks for a document. Use to inspect why search matched a document or to debug chunking. Chunk text is capped in the MCP response.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        documentId: { type: "string", description: "Document id to inspect" },
+      },
+      required: ["documentId"],
+    },
+  },
+  {
+    name: "kb_read_document_raw",
+    description: "Read the original stored document text for a document id. Use only when the user asks to inspect the source document or search snippets are insufficient. Output is capped.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        documentId: { type: "string", description: "Document id to read" },
+      },
+      required: ["documentId"],
+    },
+  },
+  {
+    name: "kb_list_document_faq",
+    description: "List generated FAQ suggestions for a document, if the KB has generated any.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        documentId: { type: "string", description: "Document id to inspect" },
+      },
+      required: ["documentId"],
+    },
+  },
+  {
+    name: "kb_reindex_document",
+    description: "Rebuild one document's chunks, vectors, and FAQ suggestions from the stored raw file. This is a write/repair action; only use after explicit user confirmation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Target KB id" },
+        documentId: { type: "string", description: "Document id to reindex" },
+        confirmDocumentId: { type: "string", description: "Must exactly equal documentId" },
+      },
+      required: ["kbId", "documentId", "confirmDocumentId"],
+    },
+  },
+  {
+    name: "kb_import_url",
+    description: "Fetch a readable remote URL and index its extracted text into a specific KB. Defaults to async=true and returns an ingest job; use kb_get_job to check progress.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Target KB id (required for writes)" },
+        url: { type: "string", description: "User-provided URL to import" },
+        async: { type: "boolean", description: "Whether to enqueue async ingest; defaults to true" },
+        idempotencyKey: { type: "string", description: "Optional idempotency key for safe retries" },
+        origin: { type: "string", description: "Optional provenance origin" },
+        sourcePath: { type: "string", description: "Optional caller-visible source path" },
+        batchId: { type: "string", description: "Optional batch id" },
+        clientItemId: { type: "string", description: "Optional caller item id" },
+        externalAssetId: { type: "string", description: "Optional external asset id" },
+      },
+      required: ["kbId", "url"],
+    },
+  },
+  {
+    name: "kb_list_jobs",
+    description: "List recent ingest jobs for a KB, with optional status/clientItemId/batchId filters and pagination.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        limit: { type: "number", description: "Optional page size, max 100" },
+        cursor: { type: "string", description: "Optional pagination cursor" },
+        status: { type: "string", description: "Optional job status filter" },
+        clientItemId: { type: "string", description: "Optional client item id filter" },
+        batchId: { type: "string", description: "Optional batch id filter" },
+      },
+    },
+  },
+  {
+    name: "kb_get_job",
+    description: "Read one ingest job's current status and provenance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        jobId: { type: "string", description: "Ingest job id" },
+      },
+      required: ["jobId"],
+    },
+  },
+  {
+    name: "kb_retry_job",
+    description: "Retry one failed or cancelled ingest job. This is a write/repair action; use only when the user asks to retry.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Target KB id" },
+        jobId: { type: "string", description: "Ingest job id to retry" },
+      },
+      required: ["kbId", "jobId"],
+    },
+  },
+  {
+    name: "kb_cancel_job",
+    description: "Cancel one queued or running ingest job. Only use after explicit user confirmation. The confirmation field must exactly equal the target job id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Target KB id" },
+        jobId: { type: "string", description: "Ingest job id to cancel" },
+        confirmJobId: { type: "string", description: "Must exactly equal jobId" },
+      },
+      required: ["kbId", "jobId", "confirmJobId"],
+    },
+  },
   {
     name: "kb_read_handbook",
     description: "Read the JishuShell-KB handbook. Use this to answer how the KB settings work or what a handbook section says. Section matching uses exact heading text after whitespace normalization.",
@@ -674,8 +1257,12 @@ async function handle(req) {
       const a = params?.arguments || {};
       if (tool === "kb_list") {
         reply(id, { content: [{ type: "text", text: jsonText(await kbList()) }] });
+      } else if (tool === "kb_get_capabilities") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbGetCapabilities()) }] });
       } else if (tool === "kb_create") {
         reply(id, { content: [{ type: "text", text: jsonText(await kbCreate(a.name, a.id, a.description)) }] });
+      } else if (tool === "kb_get") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbGet(a.kbId)) }] });
       } else if (tool === "kb_search") {
         reply(id, { content: [{ type: "text", text: fmtSearchResult(await kbSearch(a.query, a.kbId, a.topK)) }] });
       } else if (tool === "kb_upload") {
@@ -691,6 +1278,26 @@ async function handle(req) {
         });
       } else if (tool === "kb_list_documents") {
         reply(id, { content: [{ type: "text", text: jsonText(await kbListDocuments(a.kbId)) }] });
+      } else if (tool === "kb_get_document") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbGetDocument(a.kbId, a.documentId)) }] });
+      } else if (tool === "kb_list_document_chunks") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbListDocumentChunks(a.kbId, a.documentId)) }] });
+      } else if (tool === "kb_read_document_raw") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbReadDocumentRaw(a.kbId, a.documentId)) }] });
+      } else if (tool === "kb_list_document_faq") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbListDocumentFaq(a.kbId, a.documentId)) }] });
+      } else if (tool === "kb_reindex_document") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbReindexDocument(a.kbId, a.documentId, a.confirmDocumentId)) }] });
+      } else if (tool === "kb_import_url") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbImportUrl(a)) }] });
+      } else if (tool === "kb_list_jobs") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbListJobs(a)) }] });
+      } else if (tool === "kb_get_job") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbGetJob(a.kbId, a.jobId)) }] });
+      } else if (tool === "kb_retry_job") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbRetryJob(a.kbId, a.jobId)) }] });
+      } else if (tool === "kb_cancel_job") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbCancelJob(a.kbId, a.jobId, a.confirmJobId)) }] });
       } else if (tool === "kb_read_handbook") {
         reply(id, { content: [{ type: "text", text: await kbReadHandbook(a.section) }] });
       } else if (tool === "kb_get_config") {