@ontos-ai/knowhere-claw 0.1.0-beta.0 → 0.1.2

package/dist/tools.js

@@ -1,13 +1,16 @@
 import { isRecord } from "./types.js";
-import { assertKnowhereApiKey } from "./config.js";
+import { assertKnowhereApiKey, formatPaymentRequiredMessage, isPaymentRequiredError, persistApiKey } from "./config.js";
+import { normalizeForGrep, normalizeWhitespace, sanitizeStringArray, slugify } from "./text.js";
 import { formatErrorMessage } from "./error-message.js";
 import { KnowhereClient } from "./client.js";
-import { normalizeForGrep, normalizeWhitespace, sanitizeStringArray } from "./text.js";
+import { deliverChannelMessage } from "./channel-delivery.js";
 import { sendTrackerProgress } from "./tracker-progress.js";
-import path from "node:path";
 import fs from "node:fs/promises";
+import path from "node:path";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/core";
 //#region src/tools.ts
 const PREVIEW_SUMMARY_MAX_CHARS = 120;
+const INGEST_TRACKER_LANGUAGES = new Set(["ch", "en"]);
 function textResult(text) {
 	return {
 		content: [{
@@ -17,6 +20,10 @@ function textResult(text) {
 		details: {}
 	};
 }
+function rethrowWithPaymentHint(error) {
+	if (isPaymentRequiredError(error)) throw new Error(formatPaymentRequiredMessage());
+	throw error;
+}
 function deriveStoredDocumentDisplayName(document) {
 	return document.originalFileName || document.title;
 }
@@ -89,6 +96,59 @@ function buildIngestProgressLabel(params) {
 		return params.url;
 	}
 }
+function readIngestTrackerLanguage(value) {
+	const normalized = readString(value)?.toLowerCase();
+	if (!normalized) return "en";
+	if (INGEST_TRACKER_LANGUAGES.has(normalized)) return normalized;
+	return "en";
+}
+function buildIngestTrackerSuccessText(params) {
+	if (params.lang === "ch") return `通知：\`${params.label}\` 已解析完成，可以使用了。任务 ID：\`${params.jobId}\`。`;
+	return `Notice: \`${params.label}\` is parsed and ready. Job ID: \`${params.jobId}\`.`;
+}
+function buildIngestTrackerFailureText(params) {
+	if (params.lang === "ch") return params.jobId ? `通知：解析 \`${params.label}\` 失败（任务 \`${params.jobId}\`）：${params.errorText}` : `通知：解析 \`${params.label}\` 失败：${params.errorText}`;
+	return params.jobId ? `Notice: failed to parse \`${params.label}\` (job \`${params.jobId}\`): ${params.errorText}` : `Notice: failed to parse \`${params.label}\`: ${params.errorText}`;
+}
+function queueBackgroundIngestFollowUp(params) {
+	const sessionKey = readString(params.sessionKey);
+	if (!sessionKey) {
+		params.api.logger.warn(`knowhere: background ingest follow-up skipped because sessionKey is missing contextKey=${params.followUp.contextKey}`);
+		return false;
+	}
+	try {
+		if (!params.api.runtime.system.enqueueSystemEvent(params.followUp.sessionEventText, {
+			sessionKey,
+			contextKey: params.followUp.contextKey
+		})) {
+			params.api.logger.info(`knowhere: background ingest follow-up not queued sessionKey=${sessionKey} contextKey=${params.followUp.contextKey}`);
+			return false;
+		}
+		params.api.runtime.system.requestHeartbeatNow({
+			reason: params.followUp.heartbeatReason,
+			sessionKey
+		});
+		params.api.logger.info(`knowhere: background ingest follow-up queued sessionKey=${sessionKey} contextKey=${params.followUp.contextKey}`);
+		return true;
+	} catch (error) {
+		params.api.logger.warn(`knowhere: background ingest follow-up queue failed sessionKey=${sessionKey} contextKey=${params.followUp.contextKey}. ${formatErrorMessage(error)}`);
+		return false;
+	}
+}
+async function notifyBackgroundIngestOutcome(params) {
+	if (await sendTrackerProgress({
+		api: params.api,
+		context: params.context,
+		sessionKey: params.sessionKey,
+		channelRoute: params.channelRoute,
+		text: params.followUp.trackerText
+	})) return;
+	queueBackgroundIngestFollowUp({
+		api: params.api,
+		sessionKey: params.sessionKey,
+		followUp: params.followUp
+	});
+}
 function normalizeParsingParams(rawParsing) {
 	const parsing = isRecord(rawParsing) ? rawParsing : {};
 	const result = {};
@@ -196,6 +256,146 @@ function findResultFile(browseIndex, 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;
 }
@@ -292,7 +492,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. This uploads the document to the Knowhere API, waits for parsing to complete, downloads the result package, and extracts it locally. After ingestion, use knowhere_preview_document to see the document structure, knowhere_grep to search its content, or knowhere_read_result_file to access raw result files. 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. 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 to check progress at any time. Use lang to control the language of the direct tracker follow-up (`en` by default, `ch` for Chinese). Provide either filePath or url, not both.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -334,6 +534,10 @@ function createIngestTool(params) {
 					type: "boolean",
 					description: "Replace an existing stored document with the same docId."
 				},
+				lang: {
+					type: "string",
+					description: "Language for the direct tracker follow-up message sent after background parsing completes or fails. Supports en and ch; unsupported values fall back to en."
+				},
 				parsing: {
 					type: "object",
 					additionalProperties: false,
@@ -387,31 +591,33 @@ function createIngestTool(params) {
 			});
 			const tags = sanitizeStringArray(paramsRecord.tags);
 			const overwrite = readBoolean(paramsRecord.overwrite, false);
-			let jobId;
-			await sendTrackerProgress({
-				api: params.api,
-				sessionKey: params.ctx.sessionKey,
-				text: `Tracker: creating Knowhere job for \`${progressLabel}\` for this request.`
+			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"}`);
+			let resolveJobCreated;
+			const jobCreatedPromise = new Promise((resolve) => {
+				resolveJobCreated = resolve;
 			});
-			try {
-				const ingestResult = await client.ingestDocument({
-					filePath: resolvedFilePath,
-					fileName: requestedFileName,
-					url: urlParam,
-					dataId,
-					parsingParams: normalizeParsingParams(paramsRecord.parsing),
-					onJobCreated: async (job) => {
-						jobId = job.job_id;
-						await sendTrackerProgress({
-							api: params.api,
-							sessionKey: params.ctx.sessionKey,
-							text: `Tracker: ingesting \`${progressLabel}\` into Knowhere for this request. Job ID: \`${job.job_id}\`.`
-						});
-					}
-				});
-				const fileName = requestedFileName || (resolvedFilePath ? path.basename(resolvedFilePath) : null);
-				const document = await params.store.saveDownloadedDocument(scope, {
-					sourceType: urlParam ? "url" : "file",
+			let createdJobId;
+			const fileName = requestedFileName || (resolvedFilePath ? path.basename(resolvedFilePath) : null);
+			const ingestPromise = client.ingestDocument({
+				filePath: resolvedFilePath,
+				fileName: requestedFileName,
+				url: urlParam,
+				dataId,
+				parsingParams: normalizeParsingParams(paramsRecord.parsing),
+				onJobCreated: (job) => {
+					createdJobId = job.job_id;
+					params.api.logger.info(`knowhere: knowhere_ingest_document job created scope=${scope.label} jobId=${job.job_id} label=${JSON.stringify(progressLabel)}`);
+					resolveJobCreated(job);
+				}
+			});
+			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,
@@ -422,30 +628,59 @@ function createIngestTool(params) {
 					jobResult: ingestResult.jobResult,
 					downloadedResult: ingestResult.downloadedResult
 				}, { overwrite });
-				await sendTrackerProgress({
+				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)}`);
+				await notifyBackgroundIngestOutcome({
 					api: params.api,
-					sessionKey: params.ctx.sessionKey,
-					text: `Tracker: \`${progressLabel}\` is parsed and ready. Job ID: \`${ingestResult.job.job_id}\`. The agent can use it now.`
+					context: params.ctx,
+					sessionKey,
+					channelRoute,
+					followUp: {
+						trackerText: buildIngestTrackerSuccessText({
+							label: progressLabel,
+							jobId: ingestResult.job.job_id,
+							lang: trackerLanguage
+						}),
+						sessionEventText: `Knowhere background ingest completed for "${progressLabel}". The parsed document is stored as "${storedDocument.id}" in the current scope and is ready to use. Send one short follow-up to the user now telling them the parsing for "${progressLabel}" is completed and the file is ready.`,
+						contextKey: `knowhere:ingest-complete:${ingestResult.job.job_id}`,
+						heartbeatReason: "knowhere-ingest-complete"
+					}
 				});
-				return textResult([
-					"Ingest complete.",
-					...buildStoredDocumentSummaryLines({
-						document,
-						scopeLabel: scope.label,
-						includeSource: true,
-						includeJobId: true
-					}),
-					"Next: read manifest.json with knowhere_read_result_file or preview the document with knowhere_preview_document."
-				].join("\n"));
-			} catch (error) {
-				const errorText = formatErrorMessage(error);
-				await sendTrackerProgress({
+			}).catch(async (error) => {
+				const errorText = isPaymentRequiredError(error) ? formatPaymentRequiredMessage() : formatErrorMessage(error);
+				params.api.logger.error(`knowhere: knowhere_ingest_document background ingest failed scope=${scope.label} label=${JSON.stringify(progressLabel)} error=${errorText}`);
+				await notifyBackgroundIngestOutcome({
 					api: params.api,
-					sessionKey: params.ctx.sessionKey,
-					text: `Tracker: failed to ingest \`${progressLabel}\`${jobId ? ` (job \`${jobId}\`)` : ""}: ${errorText}`
+					context: params.ctx,
+					sessionKey,
+					channelRoute,
+					followUp: {
+						trackerText: buildIngestTrackerFailureText({
+							label: progressLabel,
+							jobId: createdJobId,
+							errorText,
+							lang: trackerLanguage
+						}),
+						sessionEventText: `Knowhere background ingest failed for "${progressLabel}". Send one short follow-up to the user now telling them the parsing failed. Error: ${errorText}`,
+						contextKey: `knowhere:ingest-failed:${createdJobId ?? progressLabel}`,
+						heartbeatReason: "knowhere-ingest-failed"
+					}
 				});
-				throw error;
+			});
+			const earlyFailure = Symbol("earlyFailure");
+			const createdJob = await Promise.race([jobCreatedPromise, ingestPromise.then(() => earlyFailure, (err) => {
+				rethrowWithPaymentHint(err);
+			})]);
+			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 job created. Parsing in background.",
+				`Job ID: ${createdJob.job_id}`,
+				`File: ${progressLabel}`,
+				`Scope: ${scope.label}`,
+				"Use knowhere_get_job_status to check progress at any time."
+			].join("\n"));
 		}
 	};
 }
@@ -472,8 +707,11 @@ function createJobStatusTool(params) {
 				config: params.config
 			});
 			const scope = params.store.resolveScope(params.ctx);
-			const job = await client.getJob(jobId);
+			params.api.logger.info(`knowhere: knowhere_get_job_status fetching remote status scope=${scope.label} jobId=${jobId}`);
+			const job = await client.getJob(jobId).catch(rethrowWithPaymentHint);
 			const matchingDocuments = (await params.store.listDocuments(scope)).filter((document) => document.jobId === job.job_id);
+			params.api.logger.info(`knowhere: knowhere_get_job_status fetched status scope=${scope.label} jobId=${job.job_id} status=${job.status} storedDocuments=${matchingDocuments.length}`);
+			if (job.error?.message) params.api.logger.warn(`knowhere: knowhere_get_job_status job returned error scope=${scope.label} jobId=${job.job_id} error=${job.error.message}`);
 			const lines = [
 				`Knowhere job ${job.job_id}`,
 				`Scope: ${scope.label}`,
@@ -568,15 +806,21 @@ function createJobListTool(params) {
 				config: params.config
 			});
 			const scope = params.store.resolveScope(params.ctx);
+			const jobStatus = readString(paramsRecord.jobStatus);
+			const jobType = readString(paramsRecord.jobType);
+			const recentDays = readRecentDays(paramsRecord.recentDays);
+			const startTime = readString(paramsRecord.startTime);
+			const endTime = readString(paramsRecord.endTime);
+			params.api.logger.info(`knowhere: knowhere_list_jobs listing jobs scope=${scope.label} page=${page} pageSize=${pageSize} jobStatus=${jobStatus ?? "any"} jobType=${jobType ?? "any"} recentDays=${recentDays ?? "none"} startTime=${startTime ?? "none"} endTime=${endTime ?? "none"}`);
 			const [jobList, documents] = await Promise.all([client.listJobs({
 				page,
 				pageSize,
-				jobStatus: readString(paramsRecord.jobStatus),
-				jobType: readString(paramsRecord.jobType),
-				recentDays: readRecentDays(paramsRecord.recentDays),
-				startTime: readString(paramsRecord.startTime),
-				endTime: readString(paramsRecord.endTime)
-			}), params.store.listDocuments(scope)]);
+				jobStatus,
+				jobType,
+				recentDays,
+				startTime,
+				endTime
+			}), params.store.listDocuments(scope)]).catch(rethrowWithPaymentHint);
 			const documentsByJobId = /* @__PURE__ */ new Map();
 			for (const document of documents) {
 				if (!document.jobId) continue;
@@ -584,6 +828,7 @@ function createJobListTool(params) {
 				entries.push(document);
 				documentsByJobId.set(document.jobId, entries);
 			}
+			params.api.logger.info(`knowhere: knowhere_list_jobs listed jobs scope=${scope.label} returned=${jobList.jobs.length} total=${jobList.total} storedDocuments=${documents.length}`);
 			return textResult(formatJobList({
 				jobList,
 				documentsByJobId
@@ -634,27 +879,31 @@ function createImportCompletedJobTool(params) {
 				config: params.config
 			});
 			const scope = params.store.resolveScope(params.ctx);
-			const importResult = await client.getCompletedJobResult(jobId);
+			params.api.logger.info(`knowhere: knowhere_import_completed_job importing completed job scope=${scope.label} jobId=${jobId} overwrite=${readBoolean(paramsRecord.overwrite, false)}`);
+			const importResult = await client.getCompletedJobResult(jobId).catch(rethrowWithPaymentHint);
 			const overwrite = readBoolean(paramsRecord.overwrite, false);
 			const tags = mergeTags(sanitizeStringArray(paramsRecord.tags), ["history-imported", `job:${importResult.jobResult.job_id}`]);
 			const fileName = importResult.jobResult.file_name || null;
 			const sourceType = importResult.jobResult.source_type === "url" ? "url" : "file";
+			params.api.logger.info(`knowhere: knowhere_import_completed_job downloaded job result scope=${scope.label} jobId=${importResult.jobResult.job_id} sourceType=${sourceType}`);
+			const document = await params.store.saveDownloadedDocument(scope, {
+				sourceType,
+				source: buildHistoryJobSource(importResult.jobResult.job_id),
+				sourceLabel: buildHistoryJobSourceLabel(importResult.jobResult.job_id, fileName),
+				fileName,
+				docId: readString(paramsRecord.docId),
+				title: readString(paramsRecord.title),
+				dataId: importResult.jobResult.data_id || void 0,
+				tags,
+				job: importResult.job,
+				jobResult: importResult.jobResult,
+				downloadedResult: importResult.downloadedResult
+			}, { overwrite });
+			params.api.logger.info(`knowhere: knowhere_import_completed_job stored imported document scope=${scope.label} jobId=${importResult.jobResult.job_id} docId=${document.id}`);
 			return textResult([
 				"Import complete.",
 				...buildStoredDocumentSummaryLines({
-					document: await params.store.saveDownloadedDocument(scope, {
-						sourceType,
-						source: buildHistoryJobSource(importResult.jobResult.job_id),
-						sourceLabel: buildHistoryJobSourceLabel(importResult.jobResult.job_id, fileName),
-						fileName,
-						docId: readString(paramsRecord.docId),
-						title: readString(paramsRecord.title),
-						dataId: importResult.jobResult.data_id || void 0,
-						tags,
-						job: importResult.job,
-						jobResult: importResult.jobResult,
-						downloadedResult: importResult.downloadedResult
-					}, { overwrite }),
+					document,
 					scopeLabel: scope.label,
 					includeSource: true,
 					includeJobId: true
@@ -735,11 +984,26 @@ function buildNormalizedFields(chunk) {
 	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.",
+		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,
@@ -809,13 +1073,17 @@ function createGrepTool(params) {
 			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) return textResult(formatStoredDocumentNotFound(docId, scope.label));
+			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 = [];
@@ -871,13 +1139,28 @@ function createGrepTool(params) {
 				if (entry.siblingChunkIds) projected.siblingChunkIds = entry.siblingChunkIds;
 				return projected;
 			}), maxStringChars);
-			return formatJsonToolResult({
+			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")}`);
 		}
 	};
 }
@@ -885,7 +1168,7 @@ 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), or table HTML files (e.g., tables/table-1.html). 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.",
+		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,
@@ -924,40 +1207,76 @@ function createReadResultFileTool(params) {
 			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) return textResult(formatStoredDocumentNotFound(docId, scope.label));
+			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) return textResult([
-				"Result file not found.",
-				`File path: ${filePath}`,
-				`Document ID: ${docId}`,
-				`Scope: ${scope.label}`
-			].join("\n"));
-			if (!isTextReadableResultFile(resultFile)) 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"));
+			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) return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			if (storedFile.text === null) return textResult([
-				"Result file not found.",
-				`File path: ${filePath}`,
-				`Document ID: ${docId}`,
-				`Scope: ${scope.label}`
-			].join("\n"));
+			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,
@@ -970,6 +1289,7 @@ function createReadResultFileTool(params) {
 				});
 			}
 			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,
@@ -1001,7 +1321,10 @@ function createPreviewDocumentTool(params) {
 			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) return textResult(formatStoredDocumentNotFound(docId, scope.label));
+			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) {
@@ -1021,6 +1344,7 @@ function createPreviewDocumentTool(params) {
 			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");
@@ -1046,6 +1370,7 @@ function createPreviewDocumentTool(params) {
 			} 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"));
 		}
@@ -1055,7 +1380,7 @@ 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 and their docId values before calling other tools.",
+		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,
@@ -1063,7 +1388,9 @@ function createListTool(params) {
 		},
 		execute: async () => {
 			const scope = params.store.resolveScope(params.ctx);
-			return textResult(formatDocumentList(await params.store.listDocuments(scope), scope.label));
+			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));
 		}
 	};
 }
@@ -1085,9 +1412,13 @@ function createRemoveTool(params) {
 			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) return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			params.autoGroundingController?.forgetDocument(scope, removed.id);
+			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}`,
@@ -1113,9 +1444,38 @@ function createClearScopeTool(params) {
 		execute: async (_toolCallId, rawParams) => {
 			const paramsRecord = isRecord(rawParams) ? rawParams : {};
 			const scope = params.store.resolveScope(params.ctx);
-			if (!readBoolean(paramsRecord.confirm, false)) return textResult(`Set confirm=true to clear scope ${scope.label}.`);
-			params.autoGroundingController?.forgetScope(scope);
-			return textResult(formatScopeClearResult(await params.store.clearScope(scope), scope.label));
+			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",
+		label: "Set Knowhere API Key",
+		description: "Save a Knowhere API key so the plugin can authenticate with the Knowhere service. The key is persisted in the plugin state directory and loaded automatically on next startup.",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: { apiKey: {
+				type: "string",
+				description: "The Knowhere API key to store."
+			} },
+			required: ["apiKey"]
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const apiKey = readString((isRecord(rawParams) ? rawParams : {}).apiKey);
+			if (!apiKey) throw new Error("apiKey is required.");
+			await persistApiKey(params.config.storageDir, apiKey);
+			params.config.apiKey = apiKey;
+			params.api.logger.info("knowhere: API key saved to plugin state");
+			return textResult("Knowhere API key saved successfully. All Knowhere tools are now ready to use.");
 		}
 	};
 }
@@ -1146,30 +1506,38 @@ function createKnowhereToolFactory(params) {
 			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,
-			autoGroundingController: params.autoGroundingController
+			ctx
 		}),
 		createClearScopeTool({
+			api: params.api,
 			store: params.store,
-			ctx,
-			autoGroundingController: params.autoGroundingController
+			ctx
+		}),
+		createSetApiKeyTool({
+			api: params.api,
+			config: params.config
 		})
 	];
 }