@ontos-ai/knowhere-claw 0.2.2 → 0.2.4

package/dist/tools.js

@@ -1,29 +1,28 @@
 import { isRecord } from "./types.js";
 import { assertKnowhereApiKey, formatPaymentRequiredMessage, isPaymentRequiredError, persistApiKey } from "./config.js";
-import { normalizeForGrep, normalizeWhitespace, sanitizeStringArray, slugify } from "./text.js";
+import { resolveStoredKnowhereArtifactPath } from "./parser.js";
+import { sanitizeStringArray } from "./text.js";
 import { formatErrorMessage } from "./error-message.js";
 import { KnowhereClient } from "./client.js";
-import { deliverChannelMessage } from "./channel-delivery.js";
 import { sendTrackerProgress } from "./tracker-progress.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/core";
 //#region src/tools.ts
+const TERMINAL_JOB_STATUSES = new Set([
+	"cancelled",
+	"canceled",
+	"done",
+	"error",
+	"failed"
+]);
 async function buildKnowledgeGraphAsync(params) {
 	const docDir = path.join(params.scope.documentsDir, params.docId);
-	const metadataPath = path.join(docDir, "metadata.json");
-	let payload = null;
-	try {
-		payload = await fs.readFile(metadataPath, "utf-8");
-	} catch {
-		payload = null;
-	}
-	if (!payload) {
+	const payloadData = await params.store.readDocumentMetadata(params.scope, params.docId);
+	if (!payloadData) {
 		params.api.logger.warn(`knowhere: cannot build KG, metadata not found for docId=${params.docId}`);
 		return;
 	}
-	const payloadData = JSON.parse(payload);
-	const fullMarkdownPath = path.join(docDir, "full_markdown.txt");
+	const fullMarkdownPath = await resolveStoredKnowhereArtifactPath(docDir, "full_markdown.txt");
 	let fullMarkdown = "";
 	try {
 		fullMarkdown = await fs.readFile(fullMarkdownPath, "utf-8");
@@ -37,8 +36,8 @@ async function buildKnowledgeGraphAsync(params) {
 		sourcePath: docDir,
 		keywords,
 		metadata: {
-			title: payloadData.document?.title || "Untitled",
-			sourceLabel: payloadData.document?.sourceLabel || "Unknown",
+			title: payloadData.document.title || "Untitled",
+			sourceLabel: payloadData.document.sourceLabel || "Unknown",
 			checksum: params.documentPayload.downloadedResult.rawZipSha1,
 			ingestedAt: (/* @__PURE__ */ new Date()).toISOString()
 		}
@@ -48,7 +47,6 @@ async function buildKnowledgeGraphAsync(params) {
 	});
 	params.api.logger.info(`knowhere: knowledge graph build completed kbId=${params.kbId} docId=${params.docId}`);
 }
-const PREVIEW_SUMMARY_MAX_CHARS = 120;
 const INGEST_TRACKER_LANGUAGES = new Set(["ch", "en"]);
 function textResult(text) {
 	return {
@@ -69,13 +67,6 @@ function deriveStoredDocumentDisplayName(document) {
 function deriveStoredDocumentFileLabel(document, manifestSourceFileName) {
 	return document.originalFileName || document.fileName || manifestSourceFileName || "unknown";
 }
-function formatStoredDocumentNotFound(docId, scopeLabel) {
-	return [
-		"Stored document not found.",
-		`Document ID: ${docId}`,
-		`Scope: ${scopeLabel}`
-	].join("\n");
-}
 function buildStoredDocumentSummaryLines(params) {
 	const lines = [`Stored document: "${params.document.title}" [${params.document.id}]`, `Scope: ${params.scopeLabel}`];
 	if (params.includeSource) lines.push(`Source: ${params.document.sourceLabel}`);
@@ -95,6 +86,69 @@ function buildStoredDocumentSummaryLines(params) {
 	if (params.includeUpdatedAt) lines.push(`Updated: ${params.document.updatedAt}`);
 	return lines;
 }
+function isTerminalJobStatus(status, hasError) {
+	return TERMINAL_JOB_STATUSES.has(status.trim().toLowerCase()) || hasError;
+}
+function startKnowledgeGraphBuild(params) {
+	if (!params.kgService.isEnabled()) return;
+	const kbId = params.kgService.resolveKbId(params.ctx);
+	if (!kbId) return;
+	params.api.logger.info(`knowhere: initiating knowledge graph build kbId=${kbId} docId=${params.document.id}`);
+	buildKnowledgeGraphAsync({
+		kgService: params.kgService,
+		kbId,
+		docId: params.document.id,
+		documentPayload: params.ingestResult,
+		scope: params.scope,
+		store: params.store,
+		ctx: params.ctx,
+		api: params.api,
+		channelRoute: params.channelRoute,
+		sessionKey: params.sessionKey
+	}).catch((kgError) => {
+		params.api.logger.error(`knowhere: knowledge graph build failed kbId=${kbId} docId=${params.document.id}: ${formatErrorMessage(kgError)}`);
+	});
+}
+async function persistIngestedDocument(params) {
+	const storedDocument = await params.store.saveDownloadedDocument(params.scope, {
+		sourceType: params.sourceType,
+		source: params.source,
+		fileName: params.fileName,
+		docId: params.docId,
+		title: params.title,
+		dataId: params.dataId,
+		tags: params.tags,
+		job: params.ingestResult.job,
+		jobResult: params.ingestResult.jobResult,
+		downloadedResult: params.ingestResult.downloadedResult
+	}, { overwrite: params.overwrite });
+	params.api.logger.info(`knowhere: knowhere_ingest_document stored document scope=${params.scope.label} jobId=${params.ingestResult.job.job_id} docId=${storedDocument.id}`);
+	startKnowledgeGraphBuild({
+		api: params.api,
+		channelRoute: params.channelRoute,
+		ctx: params.ctx,
+		document: storedDocument,
+		ingestResult: params.ingestResult,
+		kgService: params.kgService,
+		scope: params.scope,
+		store: params.store,
+		sessionKey: params.sessionKey
+	});
+	return storedDocument;
+}
+function formatCompletedIngestResult(params) {
+	return [
+		"Ingest complete.",
+		...buildStoredDocumentSummaryLines({
+			document: params.document,
+			scopeLabel: params.scopeLabel,
+			includeJobId: true,
+			includeSource: true
+		}),
+		`Source type: ${params.sourceType}`,
+		"Next: use knowhere_kg_query to search the knowledge graph for related content."
+	].join("\n");
+}
 function readString(value) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
@@ -216,22 +270,6 @@ function normalizeParsingParams(rawParsing) {
 	}
 	return Object.keys(result).length > 0 ? result : void 0;
 }
-function formatDocumentList(documents, scopeLabel) {
-	if (documents.length === 0) return `No stored documents in scope ${scopeLabel}.`;
-	return documents.map((document, index) => {
-		const displayTitle = deriveStoredDocumentDisplayName(document);
-		const lines = [
-			`${index + 1}. ${displayTitle} [${document.id}]`,
-			`Source: ${document.sourceLabel}`,
-			`Chunks: ${document.chunkCount}`,
-			`Updated: ${document.updatedAt || document.ingestedAt}`
-		];
-		if (document.title && document.title !== displayTitle) lines.push(`Title: ${document.title}`);
-		if (document.tags.length > 0) lines.push(`Tags: ${document.tags.join(", ")}`);
-		if (document.resultUrl) lines.push(`Result URL: ${document.resultUrl}`);
-		return lines.join("\n");
-	}).join("\n\n");
-}
 function formatJobList(params) {
 	if (params.jobList.jobs.length === 0) return `No Knowhere jobs on page ${params.jobList.page}.`;
 	const lines = [`Knowhere jobs ${params.jobList.page}/${params.jobList.totalPages || 1} (${params.jobList.total} total).`, ""];
@@ -266,239 +304,6 @@ function buildHistoryJobSourceLabel(jobId, fileName) {
 function mergeTags(tags, extras) {
 	return Array.from(new Set([...tags, ...extras]));
 }
-function formatScopeClearResult(documents, scopeLabel) {
-	if (documents.length === 0) return `Scope ${scopeLabel} is already empty.`;
-	const lines = [`Removed ${documents.length} stored document${documents.length === 1 ? "" : "s"} from scope ${scopeLabel}.`];
-	for (const [index, document] of documents.entries()) lines.push(`${index + 1}. ${deriveStoredDocumentDisplayName(document)} [${document.id}]`);
-	return lines.join("\n");
-}
-function readResultFileReadMode(value) {
-	return value === "json" || value === "csv" || value === "text" ? value : "text";
-}
-function normalizeResultFilePath(filePath) {
-	const value = normalizeWhitespace(filePath);
-	if (!value) return;
-	return path.posix.normalize(value.replace(/\\/g, "/")).replace(/^\/+/, "");
-}
-function buildChunkOrderIndex(browseIndex) {
-	return new Map(browseIndex.chunkOrder.map((chunkId, index) => [chunkId, index]));
-}
-function sortChunksByBrowseOrder(chunks, browseIndex) {
-	const orderIndex = buildChunkOrderIndex(browseIndex);
-	return [...chunks].sort((left, right) => {
-		return (orderIndex.get(left.chunkId) ?? Number.MAX_SAFE_INTEGER) - (orderIndex.get(right.chunkId) ?? Number.MAX_SAFE_INTEGER) || left.chunkId.localeCompare(right.chunkId);
-	});
-}
-function findResultFile(browseIndex, relativePath) {
-	return browseIndex.resultFiles.find((entry) => entry.relativePath === relativePath);
-}
-function isTextReadableResultFile(fileRecord) {
-	return fileRecord.kind !== "image";
-}
-const IMAGE_EXTENSION_MIME_TYPES = {
-	".png": "image/png",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".gif": "image/gif",
-	".webp": "image/webp",
-	".svg": "image/svg+xml",
-	".bmp": "image/bmp",
-	".tiff": "image/tiff",
-	".tif": "image/tiff"
-};
-function inferImageMimeType(filePath) {
-	return IMAGE_EXTENSION_MIME_TYPES[path.extname(filePath).toLowerCase()] || "image/png";
-}
-async function buildImageToolResult(params) {
-	const mimeType = inferImageMimeType(params.absolutePath);
-	const stagedImage = await stageImageResultFileForDelivery({
-		absolutePath: params.absolutePath,
-		documentTitle: params.documentTitle,
-		relativePath: params.filePath,
-		workspaceDir: params.workspaceDir
-	});
-	const stagedImagePath = stagedImage.stagedPath;
-	const fileName = path.basename(stagedImagePath);
-	const caption = `${params.documentTitle} - ${params.filePath}`;
-	const directDelivery = await deliverChannelMessage({
-		api: params.api,
-		operationLabel: "read result image",
-		context: params.context,
-		sessionKey: params.sessionKey,
-		channelRoute: params.channelRoute,
-		text: caption,
-		mediaUrl: stagedImagePath,
-		mediaLocalRoots: [path.dirname(stagedImagePath)]
-	});
-	if (directDelivery.delivered) {
-		const payload = {
-			scope: params.scopeLabel,
-			docId: params.docId,
-			documentTitle: params.documentTitle,
-			file: params.file,
-			mode: "image_sent",
-			data: {
-				mimeType,
-				sourceRelativePath: params.filePath,
-				stagedPath: stagedImagePath,
-				fileName,
-				caption,
-				note: "Image already sent to the current channel by the plugin. Do not call read on stagedPath. Do not call the message tool or attach this file again. If you reply, send only a brief confirmation.",
-				delivery: {
-					method: "direct_runtime",
-					surface: directDelivery.surface,
-					target: directDelivery.to,
-					accountId: directDelivery.accountId
-				}
-			}
-		};
-		return {
-			content: [{
-				type: "text",
-				text: `${JSON.stringify(payload, null, 2)}\n`
-			}],
-			details: payload
-		};
-	}
-	const sendWithMessageTool = {
-		action: "send",
-		path: stagedImagePath,
-		filePath: stagedImagePath,
-		filename: fileName,
-		caption
-	};
-	const replyFallback = stagedImage.workspaceRelativePath ? {
-		instructions: "If the message tool is unavailable, send your normal user-visible reply and include this exact line on its own line to attach the image.",
-		workspaceRelativePath: stagedImage.workspaceRelativePath,
-		replyWithMediaDirective: `MEDIA:${stagedImage.workspaceRelativePath}`
-	} : void 0;
-	const note = replyFallback ? "Image bytes are not inlined. Do not call read on stagedPath. If the user wants to see this image, use the message tool with sendWithMessageTool. If the message tool is unavailable, send your user-visible reply normally and include replyFallback.replyWithMediaDirective on its own line." : "Image bytes are not inlined. Do not call read on stagedPath. If the user wants to see this image, call the message tool with sendWithMessageTool.";
-	const nextActionInstructions = replyFallback ? "Do not call read on stagedPath. Call the message tool with sendWithMessageTool to attach this image. If the message tool is unavailable, use replyFallback.replyWithMediaDirective in your normal reply instead." : "Do not call read on stagedPath. Call the message tool with sendWithMessageTool to attach this image.";
-	const payload = {
-		scope: params.scopeLabel,
-		docId: params.docId,
-		documentTitle: params.documentTitle,
-		file: params.file,
-		mode: "image_attachment",
-		data: {
-			mimeType,
-			sourceRelativePath: params.filePath,
-			stagedPath: stagedImagePath,
-			fileName,
-			caption,
-			note,
-			nextAction: {
-				tool: "message",
-				instructions: nextActionInstructions,
-				args: sendWithMessageTool
-			},
-			sendWithMessageTool,
-			...replyFallback ? { replyFallback } : {}
-		}
-	};
-	return {
-		content: [{
-			type: "text",
-			text: `${JSON.stringify(payload, null, 2)}\n`
-		}],
-		details: payload
-	};
-}
-function normalizeWorkspaceDir(workspaceDir) {
-	const trimmed = readString(workspaceDir);
-	return trimmed ? path.resolve(trimmed) : void 0;
-}
-function toWorkspaceRelativeMediaPath(params) {
-	const relativePath = path.relative(params.workspaceDir, params.stagedPath);
-	if (!relativePath || relativePath.startsWith("..") || path.isAbsolute(relativePath)) return;
-	const normalizedRelativePath = relativePath.split(path.sep).join("/");
-	return normalizedRelativePath.startsWith("./") || normalizedRelativePath.startsWith("../") ? normalizedRelativePath : `./${normalizedRelativePath}`;
-}
-async function stageImageResultFileForDelivery(params) {
-	const extension = path.extname(params.relativePath) || path.extname(params.absolutePath) || ".png";
-	const imageBaseName = path.basename(params.relativePath, extension) || "image";
-	const workspaceDir = normalizeWorkspaceDir(params.workspaceDir);
-	let stagedDir;
-	if (workspaceDir) {
-		const workspaceStageRoot = path.join(workspaceDir, ".openclaw");
-		await fs.mkdir(workspaceStageRoot, { recursive: true });
-		stagedDir = await fs.mkdtemp(path.join(workspaceStageRoot, "knowhere-read-result-file-"));
-	} else stagedDir = await fs.mkdtemp(path.join(resolvePreferredOpenClawTmpDir(), "knowhere-read-result-file-"));
-	const stagedFileName = `${slugify(`${params.documentTitle}-${imageBaseName}`, "knowhere-image")}${extension.toLowerCase()}`;
-	const stagedPath = path.join(stagedDir, stagedFileName);
-	await fs.copyFile(params.absolutePath, stagedPath);
-	return {
-		stagedPath,
-		...workspaceDir ? { workspaceRelativePath: toWorkspaceRelativeMediaPath({
-			workspaceDir,
-			stagedPath
-		}) } : {}
-	};
-}
-function stripUtf8Bom(text) {
-	return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
-}
-function buildTextFilePayload(text, maxChars) {
-	return {
-		content: truncatePreview(text, maxChars),
-		lineCount: text === "" ? 0 : text.split(/\r\n|\n|\r/).length
-	};
-}
-function buildCsvFilePayload(text, maxChars) {
-	const normalized = stripUtf8Bom(text);
-	const [headerLine = ""] = normalized.split(/\r\n|\n|\r/, 1);
-	return {
-		content: truncatePreview(normalized, maxChars),
-		header: headerLine.trim() || null,
-		lineCount: normalized === "" ? 0 : normalized.split(/\r\n|\n|\r/).length
-	};
-}
-function truncatePreview(value, maxChars) {
-	if (typeof value !== "string") return "";
-	const normalized = value.replace(/\r\n/g, "\n").trim();
-	if (!normalized) return "";
-	if (normalized.length <= maxChars) return normalized;
-	return `${normalized.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
-}
-function truncateJsonValue(value, maxStringChars) {
-	if (typeof value === "string") {
-		if (value.length <= maxStringChars) return {
-			value,
-			truncated: false
-		};
-		return {
-			value: `${value.slice(0, Math.max(0, maxStringChars - 1))}…`,
-			truncated: true
-		};
-	}
-	if (Array.isArray(value)) {
-		let truncated = false;
-		return {
-			value: value.map((entry) => {
-				const result = truncateJsonValue(entry, maxStringChars);
-				truncated = truncated || result.truncated;
-				return result.value;
-			}),
-			truncated
-		};
-	}
-	if (isRecord(value)) {
-		let truncated = false;
-		const entries = Object.entries(value).map(([key, entry]) => {
-			const result = truncateJsonValue(entry, maxStringChars);
-			truncated = truncated || result.truncated;
-			return [key, result.value];
-		});
-		return {
-			value: Object.fromEntries(entries),
-			truncated
-		};
-	}
-	return {
-		value,
-		truncated: false
-	};
-}
 function formatJsonToolResult(value) {
 	return textResult(`${JSON.stringify(value, null, 2)}\n`);
 }
@@ -531,7 +336,7 @@ function createIngestTool(params) {
 	return {
 		name: "knowhere_ingest_document",
 		label: "Knowhere Ingest",
-		description: "Parse a local file or remote URL with Knowhere and store the result in the current scope. Before calling this for a document that might already be stored in the current scope, use knowhere_list_documents and reuse the existing stored document when Source, File, or Title clearly match unless the user explicitly asks for a fresh parse or overwrite. When the user provides a URL to a document (PDF link, web page, etc.), pass it as the url parameter — Knowhere fetches it directly, no local download needed. Returns immediately with a job ID while parsing continues in the background. Use knowhere_get_job_status only when the current turn needs the parsed result. Use lang to control the language of any user-facing background status update (`en` by default, `ch` for Chinese). Provide either filePath or url, not both.",
+		description: "Parse a local file or remote URL with Knowhere and store the result in the current scope. When the user provides a URL to a document (PDF link, web page, etc.), pass it as the url parameter — Knowhere fetches it directly, no local download needed. Knowhere must be the only parser for supported files. If Knowhere returns an error, surface that exact error to the user and do not fall back to other parsing methods or fabricate a preview. By default blockUntilComplete is false, so this tool is fire-and-forget and returns a job ID while parsing continues in the background. Set blockUntilComplete to true only when the current turn explicitly needs the parsed result before continuing. Use lang to control the language of any user-facing background status update (`en` by default, `ch` for Chinese). Provide either filePath or url, not both.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -573,6 +378,10 @@ function createIngestTool(params) {
 					type: "boolean",
 					description: "Replace an existing stored document with the same docId."
 				},
+				blockUntilComplete: {
+					type: "boolean",
+					description: "When true, wait for Knowhere to finish parsing, store the result, and return a ready-to-use stored-document summary. Defaults to false, which returns immediately with a job ID and continues parsing in the background."
+				},
 				lang: {
 					type: "string",
 					description: "Language for any user-facing background status update sent after parsing completes or fails. Supports en and ch; unsupported values fall back to en."
@@ -628,13 +437,14 @@ function createIngestTool(params) {
 				filePath: resolvedFilePath,
 				url: urlParam
 			});
+			const blockUntilComplete = readBoolean(paramsRecord.blockUntilComplete, false);
 			const tags = sanitizeStringArray(paramsRecord.tags);
 			const overwrite = readBoolean(paramsRecord.overwrite, false);
 			const trackerLanguage = readIngestTrackerLanguage(paramsRecord.lang);
 			const sessionKey = params.ctx.sessionKey;
 			const sourceType = urlParam ? "url" : "file";
 			const channelRoute = await params.store.resolveChannelRoute({ sessionKey });
-			params.api.logger.info(`knowhere: knowhere_ingest_document starting background ingest scope=${scope.label} sourceType=${sourceType} label=${JSON.stringify(progressLabel)} overwrite=${overwrite} docId=${docId ?? "auto"} dataId=${dataId ?? "none"} lang=${trackerLanguage} routeState=${channelRoute ? "resolved" : "missing"} routeAccountId=${channelRoute?.accountId ?? "none"}`);
+			params.api.logger.info(`knowhere: knowhere_ingest_document starting ingest scope=${scope.label} sourceType=${sourceType} label=${JSON.stringify(progressLabel)} mode=${blockUntilComplete ? "blocking" : "background"} overwrite=${overwrite} docId=${docId ?? "auto"} dataId=${dataId ?? "none"} lang=${trackerLanguage} routeState=${channelRoute ? "resolved" : "missing"} routeAccountId=${channelRoute?.accountId ?? "none"}`);
 			let resolveJobCreated;
 			const jobCreatedPromise = new Promise((resolve) => {
 				resolveJobCreated = resolve;
@@ -653,40 +463,52 @@ function createIngestTool(params) {
 					resolveJobCreated(job);
 				}
 			});
+			if (blockUntilComplete) {
+				const ingestResult = await ingestPromise.catch(rethrowWithPaymentHint);
+				params.api.logger.info(`knowhere: knowhere_ingest_document download completed scope=${scope.label} jobId=${ingestResult.job.job_id}; storing extracted result`);
+				return textResult(formatCompletedIngestResult({
+					document: await persistIngestedDocument({
+						api: params.api,
+						channelRoute,
+						ctx: params.ctx,
+						dataId,
+						docId,
+						fileName,
+						ingestResult,
+						kgService: params.kgService,
+						overwrite,
+						scope,
+						sessionKey,
+						source: urlParam || resolvedFilePath || "",
+						sourceType,
+						store: params.store,
+						tags,
+						title
+					}),
+					scopeLabel: scope.label,
+					sourceType
+				}));
+			}
 			ingestPromise.then(async (ingestResult) => {
 				params.api.logger.info(`knowhere: knowhere_ingest_document download completed scope=${scope.label} jobId=${ingestResult.job.job_id}; storing extracted result`);
-				const storedDocument = await params.store.saveDownloadedDocument(scope, {
-					sourceType,
-					source: urlParam || resolvedFilePath || "",
-					fileName,
-					docId,
-					title,
+				const storedDocument = await persistIngestedDocument({
+					api: params.api,
+					channelRoute,
+					ctx: params.ctx,
 					dataId,
+					docId,
+					fileName,
+					ingestResult,
+					kgService: params.kgService,
+					overwrite,
+					scope,
+					sessionKey,
+					source: urlParam || resolvedFilePath || "",
+					sourceType,
+					store: params.store,
 					tags,
-					job: ingestResult.job,
-					jobResult: ingestResult.jobResult,
-					downloadedResult: ingestResult.downloadedResult
-				}, { overwrite });
-				params.api.logger.info(`knowhere: knowhere_ingest_document stored document scope=${scope.label} jobId=${ingestResult.job.job_id} docId=${storedDocument.id} label=${JSON.stringify(progressLabel)}`);
-				if (params.kgService.isEnabled()) {
-					const kbId = params.kgService.resolveKbId(params.ctx);
-					if (kbId) {
-						params.api.logger.info(`knowhere: initiating knowledge graph build kbId=${kbId} docId=${storedDocument.id}`);
-						buildKnowledgeGraphAsync({
-							kgService: params.kgService,
-							kbId,
-							docId: storedDocument.id,
-							documentPayload: ingestResult,
-							scope,
-							ctx: params.ctx,
-							api: params.api,
-							channelRoute,
-							sessionKey
-						}).catch((kgError) => {
-							params.api.logger.error(`knowhere: knowledge graph build failed kbId=${kbId} docId=${storedDocument.id}: ${formatErrorMessage(kgError)}`);
-						});
-					}
-				}
+					title
+				});
 				await notifyBackgroundIngestOutcome({
 					api: params.api,
 					context: params.ctx,
@@ -730,14 +552,14 @@ function createIngestTool(params) {
 			})]);
 			if (typeof createdJob === "symbol") {
 				params.api.logger.warn(`knowhere: knowhere_ingest_document ingest completed before job-created callback scope=${scope.label} label=${JSON.stringify(progressLabel)}`);
-				return textResult("Ingest completed synchronously. Use knowhere_list_documents to find the stored document.");
+				return textResult("Ingest completed synchronously. The document is now stored and indexed.");
 			}
 			return textResult([
 				"Ingest job created. Parsing in background.",
 				`Job ID: ${createdJob.job_id}`,
 				`File: ${progressLabel}`,
 				`Scope: ${scope.label}`,
-				"Use knowhere_get_job_status only if this turn needs the parsed result."
+				"This call does not include parsed content yet."
 			].join("\n"));
 		}
 	};
@@ -746,7 +568,7 @@ function createJobStatusTool(params) {
 	return {
 		name: "knowhere_get_job_status",
 		label: "Knowhere Job Status",
-		description: "Check the status of a Knowhere parsing job by job ID. Returns job status, progress, duration, credits spent, and whether the result is already stored locally. Use this to monitor a running job or inspect a past job before importing it with knowhere_import_completed_job.",
+		description: "Check the status of a Knowhere parsing job by job ID. Returns job status, progress, duration, credits spent, and whether the result is already stored locally. Use this to monitor a running job or inspect a past job before importing it with knowhere_import_completed_job. Do not assume a running job is stuck just because progress is unchanged or slow. Only treat the job as failed or stuck when Knowhere returns an explicit failure status or error code.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -798,6 +620,10 @@ function createJobStatusTool(params) {
 				lines.push(`Result URL: ${job.result_url}`);
 				if (job.result_url_expires_at) lines.push(`Result URL expires: ${job.result_url_expires_at}`);
 			}
+			const hasExplicitError = Boolean(job.error?.code || job.error?.message);
+			if (job.status.trim().toLowerCase() === "done") lines.push("Interpretation: completed.");
+			else if (isTerminalJobStatus(job.status, hasExplicitError)) lines.push("Interpretation: Knowhere reported an explicit failure. Surface this error to the user and do not fall back to other parsing methods.");
+			else lines.push("Interpretation: still running. Do not describe this job as stuck or failed unless a later Knowhere API response returns an explicit failure status or error code.");
 			if (matchingDocuments.length === 0) lines.push("Stored docs in scope: none");
 			else {
 				lines.push("Stored docs in scope:");
@@ -898,7 +724,7 @@ function createImportCompletedJobTool(params) {
 	return {
 		name: "knowhere_import_completed_job",
 		label: "Knowhere Import Completed Job",
-		description: "Import a previously completed Knowhere job into the current scope. Downloads the result package and extracts it locally, making it available for knowhere_preview_document, knowhere_grep, and knowhere_read_result_file. Use knowhere_list_jobs to find available completed jobs.",
+		description: "Import a previously completed Knowhere job into the current scope. Downloads the result package and extracts it locally. Use knowhere_list_jobs to find available completed jobs.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -968,551 +794,11 @@ function createImportCompletedJobTool(params) {
 				}),
 				`Imported from job: ${importResult.jobResult.job_id}`,
 				`Source type: ${importResult.jobResult.source_type}`,
-				"Next: read manifest.json with knowhere_read_result_file or preview the document with knowhere_preview_document."
+				"Document imported successfully. Use knowhere_kg_query to search its content."
 			].join("\n"));
 		}
 	};
 }
-const GREP_VALID_TARGETS = new Set([
-	"chunk.content",
-	"chunk.summary",
-	"chunk.keywords",
-	"chunk.path",
-	"chunk.type",
-	"chunk.chunkId"
-]);
-const GREP_TEXT_TARGETS = [
-	"chunk.content",
-	"chunk.summary",
-	"chunk.keywords",
-	"chunk.path"
-];
-function parseGrepConditions(raw) {
-	if (!Array.isArray(raw)) return [];
-	return raw.filter(isRecord).map((entry) => {
-		const target = readString(entry.target);
-		if (target && !GREP_VALID_TARGETS.has(target)) throw new Error(`Invalid grep target: "${target}". Valid targets: ${[...GREP_VALID_TARGETS].join(", ")}`);
-		const pattern = typeof entry.pattern === "string" ? entry.pattern : "";
-		return {
-			...target ? { target } : {},
-			pattern,
-			...typeof entry.regex === "boolean" ? { regex: entry.regex } : {},
-			...typeof entry.caseSensitive === "boolean" ? { caseSensitive: entry.caseSensitive } : {}
-		};
-	});
-}
-function resolveGrepFieldValue(chunk, target) {
-	switch (target) {
-		case "chunk.content": return chunk.content || "";
-		case "chunk.summary": return chunk.summary || "";
-		case "chunk.keywords": return chunk.keywords || [];
-		case "chunk.path": return chunk.path || "";
-		case "chunk.type": return chunk.type;
-		case "chunk.chunkId": return chunk.chunkId;
-		default: return "";
-	}
-}
-function testGrepMatch(text, pattern, useRegex, caseSensitive) {
-	if (pattern === "") return true;
-	if (useRegex) {
-		const flags = caseSensitive ? "" : "i";
-		return new RegExp(pattern, flags).test(text);
-	}
-	if (caseSensitive) return text.includes(pattern);
-	return text.toLowerCase().includes(pattern.toLowerCase());
-}
-function testGrepCondition(chunk, normalizedFields, condition, outerRegex, outerCaseSensitive) {
-	const useRegex = condition.regex ?? outerRegex;
-	const caseSensitive = condition.caseSensitive ?? outerCaseSensitive;
-	const matchedTargets = [];
-	const targets = condition.target ? [condition.target] : GREP_TEXT_TARGETS;
-	for (const target of targets) {
-		const fieldValue = target === "chunk.type" || target === "chunk.chunkId" ? resolveGrepFieldValue(chunk, target) : normalizedFields.get(target) ?? resolveGrepFieldValue(chunk, target);
-		if (Array.isArray(fieldValue)) {
-			if (fieldValue.some((entry) => testGrepMatch(entry, condition.pattern, useRegex, caseSensitive))) matchedTargets.push(target);
-		} else if (testGrepMatch(fieldValue, condition.pattern, useRegex, caseSensitive)) matchedTargets.push(target);
-	}
-	return matchedTargets;
-}
-function buildNormalizedFields(chunk) {
-	const fields = /* @__PURE__ */ new Map();
-	fields.set("chunk.content", normalizeForGrep(chunk.content || ""));
-	fields.set("chunk.summary", normalizeForGrep(chunk.summary || ""));
-	fields.set("chunk.keywords", (chunk.keywords || []).map((k) => normalizeForGrep(k)));
-	fields.set("chunk.path", normalizeForGrep(chunk.path || ""));
-	return fields;
-}
-function buildGrepHints(params) {
-	const hints = [];
-	const maxHints = 3;
-	if (params.totalMatches === 0 && params.conditionCount > 0) hints.push("No matches. Try broadening: remove a condition, use a shorter pattern, or check for typos. Call knowhere_preview_document to see the document structure first.");
-	if (hints.length < maxHints && params.totalMatches > params.returned) {
-		let hint = `Showing ${params.returned} of ${params.totalMatches} matches. Add another condition (e.g., target chunk.path to a specific section) to narrow results.`;
-		if (!params.hasPathCondition) hint += " Use knowhere_preview_document to find section paths.";
-		hints.push(hint);
-	}
-	if (hints.length < maxHints && params.truncatedStrings) if (params.returned > 3) hints.push(`Fields truncated at ${params.maxStringChars} chars. Reduce maxResults to 1-3 and increase maxStringChars to 12000-20000 for full content.`);
-	else hints.push(`Fields truncated at ${params.maxStringChars} chars. Increase maxStringChars (up to 20000) for full content.`);
-	if (hints.length < maxHints && params.totalMatches >= 1 && params.totalMatches <= 5 && !params.includeContext) hints.push("Tip: set includeContext=true to discover sibling chunks in the same section.");
-	if (hints.length < maxHints && params.totalChunks > 0 && params.totalMatches > params.totalChunks * .5 && params.conditionCount <= 1) hints.push("Pattern matches over half the document. Add a second condition to narrow.");
-	return hints;
-}
-function createGrepTool(params) {
-	return {
-		name: "knowhere_grep",
-		label: "Knowhere Grep",
-		description: "Search a stored document's chunks with composable AND conditions. Returns matching chunks with content, summary, keywords, path, and chunkId. Supports substring and regex matching with text normalization (HTML stripping, LaTeX cleanup, unicode normalization). Omit conditions to list all chunks. Omit the target field in a condition to search across all text fields (content, summary, keywords, path) — this is the recommended default. When answering questions from results, cite the chunkId and path. Tip: set maxStringChars up to 20000 when you need full untruncated content from a small number of results (e.g., maxResults=1). The default 4000 may truncate long chunks. Search strategy: (1) Start with knowhere_preview_document to see document structure. (2) Search broadly with a single short pattern, then narrow by adding conditions. (3) If zero results, broaden or try synonyms. If too many, add a path condition. (4) Once you find the right chunks, re-query with maxResults=1-3 and maxStringChars=12000-20000 to read full content.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: {
-				docId: {
-					type: "string",
-					description: "Identifier of the stored document to search."
-				},
-				conditions: {
-					type: "array",
-					items: {
-						type: "object",
-						additionalProperties: false,
-						properties: {
-							target: {
-								type: "string",
-								enum: [...GREP_VALID_TARGETS],
-								description: "Chunk field to search. Omit to search all text fields (content, summary, keywords, path) — this is the recommended default."
-							},
-							pattern: {
-								type: "string",
-								description: "Search pattern. Empty string matches all."
-							},
-							regex: {
-								type: "boolean",
-								description: "Use regex matching for this condition. Overrides outer regex default."
-							},
-							caseSensitive: {
-								type: "boolean",
-								description: "Case-sensitive matching for this condition. Overrides outer default."
-							}
-						},
-						required: ["pattern"]
-					},
-					description: "ANDed search conditions. Each condition must match for a chunk to be returned. Default [] matches all chunks (useful for browsing). Omit target in a condition to search all text fields. Use multiple conditions to narrow results (e.g., path contains 'chapter 3' AND content contains 'algorithm')."
-				},
-				regex: {
-					type: "boolean",
-					description: "Default regex mode for all conditions. Defaults to false."
-				},
-				caseSensitive: {
-					type: "boolean",
-					description: "Default case-sensitivity for all conditions. Defaults to false."
-				},
-				includeContext: {
-					type: "boolean",
-					description: "Include sibling chunk IDs sharing the same document path for each matched chunk. Useful for navigating to adjacent chunks in the same section — re-query with a condition on chunk.chunkId to fetch a specific sibling."
-				},
-				maxResults: {
-					type: "integer",
-					minimum: 1,
-					maximum: 50,
-					description: "Maximum number of matching chunks to return. Defaults to 10. Use a low value (1–3) with high maxStringChars to read specific chunks in full. Use a higher value (10–50) with lower maxStringChars to scan broadly."
-				},
-				maxStringChars: {
-					type: "integer",
-					minimum: 100,
-					maximum: 2e4,
-					description: "Maximum characters per string field before truncation. Defaults to 4000. Increase up to 20000 when retrieving full content from a small number of results (e.g., reading a single chunk in full). Reduce below 4000 when scanning many results to save tokens."
-				}
-			},
-			required: ["docId"]
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const paramsRecord = isRecord(rawParams) ? rawParams : {};
-			const docId = readString(paramsRecord.docId);
-			if (!docId) throw new Error("docId is required.");
-			const scope = params.store.resolveScope(params.ctx);
-			const payload = await params.store.loadDocumentPayload(scope, docId);
-			if (!payload) {
-				params.api.logger.warn(`knowhere: knowhere_grep document not found scope=${scope.label} docId=${docId}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			const conditions = parseGrepConditions(paramsRecord.conditions);
-			const outerRegex = readBoolean(paramsRecord.regex, false);
-			const outerCaseSensitive = readBoolean(paramsRecord.caseSensitive, false);
-			const includeContext = readBoolean(paramsRecord.includeContext, false);
-			const maxResults = Math.min(50, Math.max(1, Math.trunc(readNumber(paramsRecord.maxResults, 10))));
-			const maxStringChars = Math.min(2e4, Math.max(100, Math.trunc(readNumber(paramsRecord.maxStringChars, 4e3))));
-			params.api.logger.info(`knowhere: knowhere_grep searching document scope=${scope.label} docId=${docId} conditions=${conditions.length} regex=${outerRegex} caseSensitive=${outerCaseSensitive} includeContext=${includeContext} maxResults=${maxResults} maxStringChars=${maxStringChars}`);
-			const pathChunkIndex = includeContext ? new Map(payload.browseIndex.paths.map((p) => [p.path, p.chunkIds])) : void 0;
-			const sortedChunks = sortChunksByBrowseOrder(payload.chunks, payload.browseIndex);
-			const results = [];
-			for (const chunk of sortedChunks) {
-				if (results.length >= maxResults) break;
-				const normalizedFields = buildNormalizedFields(chunk);
-				const allMatchedTargets = /* @__PURE__ */ new Set();
-				let allConditionsPassed = true;
-				for (const condition of conditions) {
-					const matched = testGrepCondition(chunk, normalizedFields, condition, outerRegex, outerCaseSensitive);
-					if (matched.length === 0) {
-						allConditionsPassed = false;
-						break;
-					}
-					for (const target of matched) allMatchedTargets.add(target);
-				}
-				if (!allConditionsPassed) continue;
-				const entry = {
-					chunk,
-					matchedOn: [...allMatchedTargets]
-				};
-				if (includeContext && pathChunkIndex && chunk.path) {
-					const siblings = pathChunkIndex.get(chunk.path);
-					if (siblings) entry.siblingChunkIds = siblings.filter((id) => id !== chunk.chunkId);
-				}
-				results.push(entry);
-			}
-			let totalMatches = results.length;
-			if (results.length >= maxResults) {
-				const remainingChunks = sortedChunks.slice(sortedChunks.indexOf(results[results.length - 1].chunk) + 1);
-				for (const chunk of remainingChunks) {
-					const normalizedFields = buildNormalizedFields(chunk);
-					let passed = true;
-					for (const condition of conditions) if (testGrepCondition(chunk, normalizedFields, condition, outerRegex, outerCaseSensitive).length === 0) {
-						passed = false;
-						break;
-					}
-					if (passed) totalMatches++;
-				}
-			}
-			const truncated = truncateJsonValue(results.map((entry) => {
-				const projected = {
-					chunkId: entry.chunk.chunkId,
-					type: entry.chunk.type,
-					path: entry.chunk.path,
-					content: entry.chunk.content,
-					summary: entry.chunk.summary,
-					keywords: entry.chunk.keywords,
-					tokens: entry.chunk.tokens,
-					assetFilePath: entry.chunk.assetFilePath,
-					matchedOn: entry.matchedOn
-				};
-				if (entry.siblingChunkIds) projected.siblingChunkIds = entry.siblingChunkIds;
-				return projected;
-			}), maxStringChars);
-			params.api.logger.info(`knowhere: knowhere_grep completed search scope=${scope.label} docId=${docId} returned=${results.length} totalMatches=${totalMatches} truncated=${truncated.truncated}`);
-			const hasPathCondition = conditions.some((c) => c.target === "chunk.path");
-			const hints = buildGrepHints({
-				totalMatches,
-				returned: results.length,
-				maxResults,
-				maxStringChars,
-				truncatedStrings: truncated.truncated,
-				conditionCount: conditions.length,
-				includeContext,
-				totalChunks: sortedChunks.length,
-				hasPathCondition
-			});
-			const jsonResult = formatJsonToolResult({
-				totalMatches,
-				returned: results.length,
-				results: truncated.value,
-				maxStringChars,
-				truncatedStrings: truncated.truncated
-			});
-			if (hints.length === 0) return jsonResult;
-			return textResult(`${jsonResult.content[0].text}\n---\n${hints.join("\n")}`);
-		}
-	};
-}
-function createReadResultFileTool(params) {
-	return {
-		name: "knowhere_read_result_file",
-		label: "Knowhere Read Result File",
-		description: "Read a raw result file from the stored document's extracted ZIP package. Common files: manifest.json (parsing metadata), hierarchy.json (document structure), kb.csv (knowledge base export), table HTML files (e.g., tables/table-1.html), or image assets (e.g., images/img-0.png). Image files are staged into a local attachment path and sent directly to the current channel when routing can be resolved. If direct delivery is unavailable, the tool returns a message-tool handoff and, when the run has a workspace, a workspace-relative MEDIA fallback for a normal assistant reply. When the result mode is image_attachment, do not call generic file-read tools on data.stagedPath; use data.sendWithMessageTool or data.replyFallback as returned. When the result mode is image_sent, the plugin already delivered the image. Use mode='json' for JSON files, mode='csv' for CSV files, or mode='text' (default) for everything else. Increase maxStringChars (up to 20000) for large files.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: {
-				docId: {
-					type: "string",
-					description: "Identifier of the stored document to read from."
-				},
-				filePath: {
-					type: "string",
-					description: "Relative path under the stored result directory, for example manifest.json or tables/table-1.html."
-				},
-				mode: {
-					type: "string",
-					enum: [
-						"text",
-						"json",
-						"csv"
-					],
-					description: "text returns trimmed text, json parses JSON, and csv returns a raw CSV preview. Defaults to text."
-				},
-				maxStringChars: {
-					type: "integer",
-					minimum: 100,
-					maximum: 2e4,
-					description: "Maximum characters per string field before truncation. Defaults to 4000. Increase up to 20000 for large files like hierarchy.json or kb.csv."
-				}
-			},
-			required: ["docId", "filePath"]
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const paramsRecord = isRecord(rawParams) ? rawParams : {};
-			const docId = readString(paramsRecord.docId);
-			const filePath = normalizeResultFilePath(paramsRecord.filePath);
-			if (!docId) throw new Error("docId is required.");
-			if (!filePath) throw new Error("filePath is required.");
-			const scope = params.store.resolveScope(params.ctx);
-			const payload = await params.store.loadDocumentPayload(scope, docId);
-			if (!payload) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file document not found scope=${scope.label} docId=${docId}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			const resultFile = findResultFile(payload.browseIndex, filePath);
-			if (!resultFile) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file result file not found scope=${scope.label} docId=${docId} filePath=${filePath}`);
-				return textResult([
-					"Result file not found.",
-					`File path: ${filePath}`,
-					`Document ID: ${docId}`,
-					`Scope: ${scope.label}`
-				].join("\n"));
-			}
-			if (resultFile.kind === "image") {
-				const absolutePath = params.store.getResultFileAbsolutePath(scope, docId, filePath);
-				const channelRoute = await params.store.resolveChannelRoute({ sessionKey: params.ctx.sessionKey });
-				params.api.logger.info(`knowhere: knowhere_read_result_file staging image asset scope=${scope.label} docId=${docId} filePath=${filePath}`);
-				return await buildImageToolResult({
-					api: params.api,
-					absolutePath,
-					channelRoute,
-					context: params.ctx,
-					docId: payload.document.id,
-					documentTitle: payload.document.title,
-					filePath,
-					file: resultFile,
-					sessionKey: params.ctx.sessionKey,
-					scopeLabel: scope.label,
-					workspaceDir: params.ctx.workspaceDir
-				});
-			}
-			if (!isTextReadableResultFile(resultFile)) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file unreadable result kind scope=${scope.label} docId=${docId} filePath=${filePath} kind=${resultFile.kind}`);
-				return textResult([
-					"Result file is not readable as text through this tool.",
-					`File path: ${filePath}`,
-					`Kind: ${resultFile.kind}`,
-					`Document ID: ${docId}`,
-					`Scope: ${scope.label}`
-				].join("\n"));
-			}
-			const storedFile = await params.store.readResultFile(scope, docId, filePath);
-			if (!storedFile) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file payload disappeared scope=${scope.label} docId=${docId} filePath=${filePath}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			if (storedFile.text === null) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file text content missing scope=${scope.label} docId=${docId} filePath=${filePath}`);
-				return textResult([
-					"Result file not found.",
-					`File path: ${filePath}`,
-					`Document ID: ${docId}`,
-					`Scope: ${scope.label}`
-				].join("\n"));
-			}
-			const mode = readResultFileReadMode(paramsRecord.mode);
-			const maxStringChars = Math.min(2e4, Math.max(100, Math.trunc(readNumber(paramsRecord.maxStringChars, 4e3))));
-			const normalizedText = stripUtf8Bom(storedFile.text);
-			params.api.logger.info(`knowhere: knowhere_read_result_file reading file scope=${scope.label} docId=${docId} filePath=${filePath} kind=${resultFile.kind} mode=${mode} maxStringChars=${maxStringChars}`);
-			if (mode === "json") {
-				let parsedJson;
-				try {
-					parsedJson = JSON.parse(normalizedText);
-				} catch (error) {
-					params.api.logger.warn(`knowhere: knowhere_read_result_file invalid json scope=${scope.label} docId=${docId} filePath=${filePath} error=${formatErrorMessage(error)}`);
-					throw new Error(`Result file ${filePath} is not valid JSON. ${formatErrorMessage(error)}`, { cause: error });
-				}
-				const truncatedJson = truncateJsonValue(parsedJson, maxStringChars);
-				params.api.logger.info(`knowhere: knowhere_read_result_file parsed json scope=${scope.label} docId=${docId} filePath=${filePath} truncated=${truncatedJson.truncated}`);
-				return formatJsonToolResult({
-					scope: scope.label,
-					docId: payload.document.id,
-					documentTitle: payload.document.title,
-					file: resultFile,
-					mode,
-					maxStringChars,
-					truncatedStrings: truncatedJson.truncated,
-					data: truncatedJson.value
-				});
-			}
-			const data = mode === "csv" ? buildCsvFilePayload(normalizedText, maxStringChars) : buildTextFilePayload(normalizedText, maxStringChars);
-			params.api.logger.info(`knowhere: knowhere_read_result_file prepared text payload scope=${scope.label} docId=${docId} filePath=${filePath} lineCount=${data.lineCount}`);
-			return formatJsonToolResult({
-				scope: scope.label,
-				docId: payload.document.id,
-				documentTitle: payload.document.title,
-				file: resultFile,
-				mode,
-				maxStringChars,
-				data
-			});
-		}
-	};
-}
-function createPreviewDocumentTool(params) {
-	return {
-		name: "knowhere_preview_document",
-		label: "Knowhere Preview Document",
-		description: "Get a structural overview of a stored Knowhere document. Returns the document metadata and a hierarchical table of contents showing sections, subsections, and chunk counts per path (text, image, table). Use this as the first step after identifying a docId to understand the document's structure before searching with knowhere_grep.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: { docId: {
-				type: "string",
-				description: "Identifier of the stored document to preview."
-			} },
-			required: ["docId"]
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const docId = readString((isRecord(rawParams) ? rawParams : {}).docId);
-			if (!docId) throw new Error("docId is required.");
-			const scope = params.store.resolveScope(params.ctx);
-			const payload = await params.store.loadDocumentPayload(scope, docId);
-			if (!payload) {
-				params.api.logger.warn(`knowhere: knowhere_preview_document document not found scope=${scope.label} docId=${docId}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			const { document } = payload;
-			const pathSummaryMap = /* @__PURE__ */ new Map();
-			for (const chunk of payload.chunks) {
-				if (!chunk.path || pathSummaryMap.has(chunk.path)) continue;
-				const raw = (chunk.summary || chunk.content || "").trim();
-				if (raw) {
-					const oneLine = raw.replace(/\n+/g, " ").slice(0, PREVIEW_SUMMARY_MAX_CHARS);
-					pathSummaryMap.set(chunk.path, oneLine + (raw.length > PREVIEW_SUMMARY_MAX_CHARS ? "..." : ""));
-				}
-			}
-			const lines = [
-				`"${document.title}" [${document.id}]`,
-				`Scope: ${scope.label}`,
-				`Source: ${document.sourceLabel}`,
-				`Chunks: ${document.chunkCount}`
-			];
-			const pathByName = /* @__PURE__ */ new Map();
-			for (const p of payload.browseIndex.paths) pathByName.set(p.path, p);
-			const roots = payload.browseIndex.paths.filter((p) => p.depth === 1);
-			params.api.logger.info(`knowhere: knowhere_preview_document building preview scope=${scope.label} docId=${docId} paths=${payload.browseIndex.paths.length} roots=${roots.length} chunks=${payload.chunks.length}`);
-			if (roots.length > 0) {
-				lines.push("");
-				lines.push("## Table of Contents");
-				lines.push("");
-				const renderTree = (pathRecord, indent) => {
-					const prefix = "  ".repeat(indent);
-					const segments = pathRecord.path.split(/\/|-->/);
-					const label = segments[segments.length - 1] || pathRecord.path;
-					const counts = [];
-					if (pathRecord.textChunkCount > 0) counts.push(`${pathRecord.textChunkCount} text`);
-					if (pathRecord.imageChunkCount > 0) counts.push(`${pathRecord.imageChunkCount} img`);
-					if (pathRecord.tableChunkCount > 0) counts.push(`${pathRecord.tableChunkCount} tbl`);
-					const countStr = counts.length > 0 ? ` (${counts.join(", ")})` : "";
-					const summary = pathSummaryMap.get(pathRecord.path);
-					const summaryStr = summary ? ` — ${summary}` : "";
-					lines.push(`${prefix}- ${label}${countStr}${summaryStr}`);
-					for (const childPath of pathRecord.childPaths) {
-						const child = pathByName.get(childPath);
-						if (child) renderTree(child, indent + 1);
-					}
-				};
-				for (const root of roots) renderTree(root, 0);
-			} else {
-				lines.push("");
-				lines.push("No structural paths available for this document.");
-				params.api.logger.warn(`knowhere: knowhere_preview_document no structural paths scope=${scope.label} docId=${docId}`);
-			}
-			return textResult(lines.join("\n"));
-		}
-	};
-}
-function createListTool(params) {
-	return {
-		name: "knowhere_list_documents",
-		label: "Knowhere List",
-		description: "List all Knowhere documents stored in the current scope. Returns each document's ID, title, source, chunk count, tags, and last-updated timestamp. Use this first to discover available documents, check whether a file or URL is already stored, and find the right docId before calling other tools.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: {}
-		},
-		execute: async () => {
-			const scope = params.store.resolveScope(params.ctx);
-			const documents = await params.store.listDocuments(scope);
-			params.api.logger.info(`knowhere: knowhere_list_documents listed documents scope=${scope.label} count=${documents.length}`);
-			return textResult(formatDocumentList(documents, scope.label));
-		}
-	};
-}
-function createRemoveTool(params) {
-	return {
-		name: "knowhere_remove_document",
-		label: "Knowhere Remove",
-		description: "Remove a stored Knowhere document and all its extracted data from the current scope. This is irreversible — the document must be re-ingested or re-imported to restore it.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: { docId: {
-				type: "string",
-				description: "Identifier of the stored document to remove."
-			} },
-			required: ["docId"]
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const docId = readString((isRecord(rawParams) ? rawParams : {}).docId);
-			if (!docId) throw new Error("docId is required.");
-			const scope = params.store.resolveScope(params.ctx);
-			params.api.logger.info(`knowhere: knowhere_remove_document removing document scope=${scope.label} docId=${docId}`);
-			const removed = await params.store.removeDocument(scope, docId);
-			if (!removed) {
-				params.api.logger.warn(`knowhere: knowhere_remove_document document not found scope=${scope.label} docId=${docId}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			params.api.logger.info(`knowhere: knowhere_remove_document removed document scope=${scope.label} docId=${removed.id}`);
-			return textResult([
-				"Removed stored document.",
-				`Document ID: ${removed.id}`,
-				`Title: ${removed.title}`,
-				`Scope: ${scope.label}`
-			].join("\n"));
-		}
-	};
-}
-function createClearScopeTool(params) {
-	return {
-		name: "knowhere_clear_scope",
-		label: "Knowhere Clear Scope",
-		description: "Remove all stored Knowhere documents from the current scope. This is irreversible and affects every document in the scope. Set confirm=true to execute.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: { confirm: {
-				type: "boolean",
-				description: "Must be true to clear the current scope."
-			} }
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const paramsRecord = isRecord(rawParams) ? rawParams : {};
-			const scope = params.store.resolveScope(params.ctx);
-			if (!readBoolean(paramsRecord.confirm, false)) {
-				params.api.logger.warn(`knowhere: knowhere_clear_scope skipped without confirm scope=${scope.label}`);
-				return textResult(`Set confirm=true to clear scope ${scope.label}.`);
-			}
-			params.api.logger.info(`knowhere: knowhere_clear_scope clearing scope scope=${scope.label}`);
-			const removedDocuments = await params.store.clearScope(scope);
-			params.api.logger.info(`knowhere: knowhere_clear_scope cleared scope scope=${scope.label} removed=${removedDocuments.length}`);
-			return textResult(formatScopeClearResult(removedDocuments, scope.label));
-		}
-	};
-}
 function createSetApiKeyTool(params) {
 	return {
 		name: "knowhere_set_api_key",
@@ -1655,36 +941,6 @@ function createKnowhereToolFactory(params) {
 			store: params.store,
 			ctx
 		}),
-		createGrepTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createReadResultFileTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createPreviewDocumentTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createListTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createRemoveTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createClearScopeTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
 		createSetApiKeyTool({
 			api: params.api,
 			config: params.config