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

package/dist/tools.js

@@ -0,0 +1,1177 @@
+import { isRecord } from "./types.js";
+import { assertKnowhereApiKey } from "./config.js";
+import { formatErrorMessage } from "./error-message.js";
+import { KnowhereClient } from "./client.js";
+import { normalizeForGrep, normalizeWhitespace, sanitizeStringArray } from "./text.js";
+import { sendTrackerProgress } from "./tracker-progress.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+//#region src/tools.ts
+const PREVIEW_SUMMARY_MAX_CHARS = 120;
+function textResult(text) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		details: {}
+	};
+}
+function deriveStoredDocumentDisplayName(document) {
+	return document.originalFileName || document.title;
+}
+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}`);
+	lines.push(`File: ${deriveStoredDocumentFileLabel(params.document, params.manifestSourceFileName)}`);
+	lines.push(`Chunks: ${params.document.chunkCount}`);
+	const stats = params.document.statistics;
+	if (stats) {
+		const parts = [];
+		if (stats.text_chunks) parts.push(`${stats.text_chunks} text`);
+		if (stats.image_chunks) parts.push(`${stats.image_chunks} image`);
+		if (stats.table_chunks) parts.push(`${stats.table_chunks} table`);
+		if (parts.length > 0) lines.push(`Breakdown: ${parts.join(", ")}`);
+		if (stats.total_pages) lines.push(`Pages: ${stats.total_pages}`);
+	}
+	if (params.includeJobId && params.document.jobId) lines.push(`Job ID: ${params.document.jobId}`);
+	if (params.document.resultUrl) lines.push(`Result URL: ${params.document.resultUrl}`);
+	if (params.includeUpdatedAt) lines.push(`Updated: ${params.document.updatedAt}`);
+	return lines;
+}
+function readString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function readBoolean(value, fallback = false) {
+	return typeof value === "boolean" ? value : fallback;
+}
+function readNumber(value, fallback) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim()) {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return fallback;
+}
+function resolveWorkspacePath(filePath, ctx) {
+	if (path.isAbsolute(filePath)) return filePath;
+	return path.resolve(ctx.workspaceDir || process.cwd(), filePath);
+}
+function parseAllowedIngestUrl(urlText) {
+	const parsedUrl = new URL(urlText);
+	if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") throw new Error(`Only http and https URLs are supported for Knowhere ingest. URL: ${urlText}`);
+	const hostName = parsedUrl.hostname.trim().toLowerCase();
+	if (!hostName) throw new Error(`URL host is required for Knowhere ingest. URL: ${urlText}`);
+	if (hostName === "localhost" || hostName === "::1" || hostName.startsWith("127.")) throw new Error(`Loopback URLs are not allowed for Knowhere ingest. URL: ${urlText}`);
+	return parsedUrl;
+}
+function buildIngestProgressLabel(params) {
+	if (typeof params.fileName === "string" && params.fileName.trim()) return params.fileName.trim();
+	if (params.filePath) return path.basename(params.filePath);
+	if (!params.url) return "document";
+	try {
+		const parsedUrl = new URL(params.url);
+		const decodedPath = decodeURIComponent(parsedUrl.pathname);
+		const baseName = path.posix.basename(decodedPath);
+		if (baseName && baseName !== "/" && baseName !== ".") return baseName;
+		return parsedUrl.host || params.url;
+	} catch {
+		return params.url;
+	}
+}
+function normalizeParsingParams(rawParsing) {
+	const parsing = isRecord(rawParsing) ? rawParsing : {};
+	const result = {};
+	const model = readString(parsing.model);
+	if (model === "base" || model === "advanced") result.model = model;
+	const kbDir = readString(parsing.kbDir ?? parsing.kb_dir);
+	if (kbDir) result.kb_dir = kbDir;
+	const docType = readString(parsing.docType ?? parsing.doc_type);
+	if (docType) result.doc_type = docType;
+	const addFragDesc = readString(parsing.addFragDesc ?? parsing.add_frag_desc);
+	if (addFragDesc) result.add_frag_desc = addFragDesc;
+	for (const [sourceKey, targetKey] of [
+		["ocrEnabled", "ocr_enabled"],
+		["ocr_enabled", "ocr_enabled"],
+		["smartTitleParse", "smart_title_parse"],
+		["smart_title_parse", "smart_title_parse"],
+		["summaryImage", "summary_image"],
+		["summary_image", "summary_image"],
+		["summaryTable", "summary_table"],
+		["summary_table", "summary_table"],
+		["summaryText", "summary_txt"],
+		["summary_txt", "summary_txt"]
+	]) {
+		const value = parsing[sourceKey];
+		if (typeof value === "boolean") result[targetKey] = value;
+	}
+	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).`, ""];
+	for (const [index, job] of params.jobList.jobs.entries()) {
+		const storedDocuments = params.documentsByJobId.get(job.job_id) ?? [];
+		const entry = [
+			`${index + 1}. ${job.job_id}`,
+			`Status: ${job.status}`,
+			`Source type: ${job.source_type}`,
+			job.file_name ? `File: ${job.file_name}` : null,
+			job.created_at ? `Created: ${job.created_at}` : null,
+			job.result_url ? `Result URL: ${job.result_url}` : "Result package: not ready",
+			storedDocuments.length > 0 ? `Stored docs in scope: ${storedDocuments.map((document) => document.id).join(", ")}` : "Stored docs in scope: none",
+			job.error?.message ? `Error: ${job.error.message}` : null
+		].filter((value) => Boolean(value));
+		lines.push(entry.join("\n"));
+		if (index < params.jobList.jobs.length - 1) lines.push("");
+	}
+	return lines.join("\n");
+}
+function readRecentDays(value) {
+	const parsed = readNumber(value, NaN);
+	if (parsed === 1 || parsed === 7 || parsed === 30) return parsed;
+}
+function buildHistoryJobSource(jobId) {
+	return `knowhere-job:${jobId}`;
+}
+function buildHistoryJobSourceLabel(jobId, fileName) {
+	if (typeof fileName === "string" && fileName.trim()) return fileName.trim();
+	return `Imported Knowhere job ${jobId}`;
+}
+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";
+}
+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`);
+}
+function formatJsonInline(value) {
+	if (value === void 0) return null;
+	if (value === null) return "null";
+	if (typeof value === "string") return value.trim() || null;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "symbol") return value.description ? `Symbol(${value.description})` : "Symbol()";
+	if (typeof value === "function") return value.name ? `[function ${value.name}]` : "[function]";
+	try {
+		return JSON.stringify(value) ?? Object.prototype.toString.call(value);
+	} catch {
+		return Object.prototype.toString.call(value);
+	}
+}
+function createClient(params) {
+	return new KnowhereClient({
+		apiKey: params.config.apiKey,
+		baseUrl: params.config.baseUrl,
+		requestTimeoutMs: params.config.requestTimeoutMs,
+		uploadTimeoutMs: params.config.uploadTimeoutMs,
+		pollIntervalMs: params.config.pollIntervalMs,
+		pollTimeoutMs: params.config.pollTimeoutMs,
+		logger: params.api.logger
+	});
+}
+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.",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				filePath: {
+					type: "string",
+					description: "Local file path to parse. Use either filePath or url."
+				},
+				fileName: {
+					type: "string",
+					description: "Original filename to send to Knowhere and store locally when filePath points to a temporary attachment path."
+				},
+				originalFileName: {
+					type: "string",
+					description: "Alias of fileName. Useful when an attachment was saved locally under a UUID path but the prompt still shows the visible filename."
+				},
+				url: {
+					type: "string",
+					description: "Remote document URL to parse. Use either url or filePath."
+				},
+				docId: {
+					type: "string",
+					description: "Optional stable identifier to use in the local store."
+				},
+				title: {
+					type: "string",
+					description: "Optional display title stored with the document."
+				},
+				tags: {
+					type: "array",
+					items: { type: "string" },
+					description: "Optional tags stored alongside the document."
+				},
+				dataId: {
+					type: "string",
+					description: "Optional Knowhere data_id for correlation/idempotency."
+				},
+				overwrite: {
+					type: "boolean",
+					description: "Replace an existing stored document with the same docId."
+				},
+				parsing: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						model: {
+							type: "string",
+							enum: ["base", "advanced"]
+						},
+						ocrEnabled: { type: "boolean" },
+						kbDir: { type: "string" },
+						docType: {
+							type: "string",
+							description: "Optional Knowhere parsing_params.doc_type value passed through as-is."
+						},
+						smartTitleParse: { type: "boolean" },
+						summaryImage: { type: "boolean" },
+						summaryTable: { type: "boolean" },
+						summaryText: { type: "boolean" },
+						addFragDesc: { type: "string" }
+					}
+				}
+			}
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const paramsRecord = isRecord(rawParams) ? rawParams : {};
+			const filePathParam = readString(paramsRecord.filePath);
+			const urlParam = readString(paramsRecord.url);
+			if (!filePathParam && !urlParam) throw new Error("filePath or url is required.");
+			if (filePathParam && urlParam) throw new Error("Provide either filePath or url, not both.");
+			assertKnowhereApiKey(params.config);
+			const scope = params.store.resolveScope(params.ctx);
+			const client = createClient({
+				api: params.api,
+				config: params.config
+			});
+			let resolvedFilePath;
+			if (filePathParam) {
+				resolvedFilePath = resolveWorkspacePath(filePathParam, params.ctx);
+				const stats = await fs.stat(resolvedFilePath).catch(() => null);
+				if (!stats || !stats.isFile()) throw new Error(`File not found: ${resolvedFilePath}`);
+			}
+			if (urlParam) parseAllowedIngestUrl(urlParam);
+			const dataId = readString(paramsRecord.dataId);
+			const docId = readString(paramsRecord.docId);
+			const title = readString(paramsRecord.title);
+			const requestedFileName = readString(paramsRecord.fileName) ?? readString(paramsRecord.originalFileName);
+			const progressLabel = buildIngestProgressLabel({
+				fileName: requestedFileName,
+				filePath: resolvedFilePath,
+				url: urlParam
+			});
+			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.`
+			});
+			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",
+					source: urlParam || resolvedFilePath || "",
+					fileName,
+					docId,
+					title,
+					dataId,
+					tags,
+					job: ingestResult.job,
+					jobResult: ingestResult.jobResult,
+					downloadedResult: ingestResult.downloadedResult
+				}, { overwrite });
+				await sendTrackerProgress({
+					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.`
+				});
+				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({
+					api: params.api,
+					sessionKey: params.ctx.sessionKey,
+					text: `Tracker: failed to ingest \`${progressLabel}\`${jobId ? ` (job \`${jobId}\`)` : ""}: ${errorText}`
+				});
+				throw error;
+			}
+		}
+	};
+}
+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.",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: { jobId: {
+				type: "string",
+				description: "Knowhere job ID, for example job_f6f12930906a."
+			} },
+			required: ["jobId"]
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const jobId = readString((isRecord(rawParams) ? rawParams : {}).jobId);
+			if (!jobId) throw new Error("jobId is required.");
+			assertKnowhereApiKey(params.config);
+			const client = createClient({
+				api: params.api,
+				config: params.config
+			});
+			const scope = params.store.resolveScope(params.ctx);
+			const job = await client.getJob(jobId);
+			const matchingDocuments = (await params.store.listDocuments(scope)).filter((document) => document.jobId === job.job_id);
+			const lines = [
+				`Knowhere job ${job.job_id}`,
+				`Scope: ${scope.label}`,
+				`Status: ${job.status}`,
+				`Source type: ${job.source_type}`
+			];
+			if (job.file_name) lines.push(`File: ${job.file_name}`);
+			if (job.data_id) lines.push(`Data ID: ${job.data_id}`);
+			if (job.created_at) lines.push(`Created: ${job.created_at}`);
+			if (job.model) lines.push(`Model: ${job.model}`);
+			if (typeof job.ocr_enabled === "boolean") lines.push(`OCR enabled: ${job.ocr_enabled}`);
+			if (typeof job.duration_seconds === "number") lines.push(`Duration seconds: ${job.duration_seconds}`);
+			if (typeof job.credits_spent === "number") lines.push(`Credits spent: ${job.credits_spent}`);
+			const progressText = formatJsonInline(job.progress);
+			if (progressText) lines.push(`Progress: ${progressText}`);
+			if (job.error) {
+				const errorParts = [
+					job.error.code,
+					job.error.message,
+					job.error.request_id ? `request_id=${job.error.request_id}` : null,
+					job.error.details !== void 0 ? `details=${formatJsonInline(job.error.details) || "unavailable"}` : null
+				].filter((value) => Boolean(value));
+				if (errorParts.length > 0) lines.push(`Error: ${errorParts.join(" | ")}`);
+			}
+			if (job.result_url) {
+				lines.push(`Result URL: ${job.result_url}`);
+				if (job.result_url_expires_at) lines.push(`Result URL expires: ${job.result_url_expires_at}`);
+			}
+			if (matchingDocuments.length === 0) lines.push("Stored docs in scope: none");
+			else {
+				lines.push("Stored docs in scope:");
+				for (const [index, document] of matchingDocuments.entries()) lines.push(`${index + 1}. ${deriveStoredDocumentDisplayName(document)} [${document.id}]`);
+			}
+			return textResult(lines.join("\n"));
+		}
+	};
+}
+function createJobListTool(params) {
+	return {
+		name: "knowhere_list_jobs",
+		label: "Knowhere Job List",
+		description: "List Knowhere parsing jobs for the current API key with optional filters. Returns job IDs, statuses, file names, and whether each job is already stored locally. Use this to find completed jobs that can be imported with knowhere_import_completed_job.",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				page: {
+					type: "integer",
+					minimum: 1,
+					description: "Page number. Defaults to 1."
+				},
+				pageSize: {
+					type: "integer",
+					minimum: 1,
+					maximum: 100,
+					description: "Page size. Defaults to 20."
+				},
+				jobStatus: {
+					type: "string",
+					description: "Optional Knowhere job status filter."
+				},
+				jobType: {
+					type: "string",
+					description: "Optional Knowhere job type filter."
+				},
+				recentDays: {
+					type: "integer",
+					enum: [
+						1,
+						7,
+						30
+					],
+					description: "Optional recent-days filter supported by Knowhere."
+				},
+				startTime: {
+					type: "string",
+					description: "Optional ISO start timestamp. Overrides recentDays lower bound."
+				},
+				endTime: {
+					type: "string",
+					description: "Optional ISO end timestamp."
+				}
+			}
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const paramsRecord = isRecord(rawParams) ? rawParams : {};
+			assertKnowhereApiKey(params.config);
+			const page = Math.max(1, Math.trunc(readNumber(paramsRecord.page, 1)));
+			const pageSize = Math.min(100, Math.max(1, Math.trunc(readNumber(paramsRecord.pageSize, 20))));
+			const client = createClient({
+				api: params.api,
+				config: params.config
+			});
+			const scope = params.store.resolveScope(params.ctx);
+			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)]);
+			const documentsByJobId = /* @__PURE__ */ new Map();
+			for (const document of documents) {
+				if (!document.jobId) continue;
+				const entries = documentsByJobId.get(document.jobId) ?? [];
+				entries.push(document);
+				documentsByJobId.set(document.jobId, entries);
+			}
+			return textResult(formatJobList({
+				jobList,
+				documentsByJobId
+			}));
+		}
+	};
+}
+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.",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				jobId: {
+					type: "string",
+					description: "Completed Knowhere job ID to import."
+				},
+				docId: {
+					type: "string",
+					description: "Optional stable local document ID to use in the store."
+				},
+				title: {
+					type: "string",
+					description: "Optional display title for the stored document."
+				},
+				tags: {
+					type: "array",
+					items: { type: "string" },
+					description: "Optional tags stored alongside the imported document."
+				},
+				overwrite: {
+					type: "boolean",
+					description: "Replace an existing stored document with the same derived or explicit docId."
+				}
+			},
+			required: ["jobId"]
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const paramsRecord = isRecord(rawParams) ? rawParams : {};
+			const jobId = readString(paramsRecord.jobId);
+			if (!jobId) throw new Error("jobId is required.");
+			assertKnowhereApiKey(params.config);
+			const client = createClient({
+				api: params.api,
+				config: params.config
+			});
+			const scope = params.store.resolveScope(params.ctx);
+			const importResult = await client.getCompletedJobResult(jobId);
+			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";
+			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 }),
+					scopeLabel: scope.label,
+					includeSource: true,
+					includeJobId: true
+				}),
+				`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."
+			].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 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.",
+		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) 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))));
+			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);
+			return formatJsonToolResult({
+				totalMatches,
+				returned: results.length,
+				results: truncated.value,
+				maxStringChars,
+				truncatedStrings: truncated.truncated
+			});
+		}
+	};
+}
+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.",
+		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) 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"));
+			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"));
+			const mode = readResultFileReadMode(paramsRecord.mode);
+			const maxStringChars = Math.min(2e4, Math.max(100, Math.trunc(readNumber(paramsRecord.maxStringChars, 4e3))));
+			const normalizedText = stripUtf8Bom(storedFile.text);
+			if (mode === "json") {
+				let parsedJson;
+				try {
+					parsedJson = JSON.parse(normalizedText);
+				} catch (error) {
+					throw new Error(`Result file ${filePath} is not valid JSON. ${formatErrorMessage(error)}`, { cause: error });
+				}
+				const truncatedJson = truncateJsonValue(parsedJson, maxStringChars);
+				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);
+			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) 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);
+			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.");
+			}
+			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 and their docId values before calling other tools.",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {}
+		},
+		execute: async () => {
+			const scope = params.store.resolveScope(params.ctx);
+			return textResult(formatDocumentList(await params.store.listDocuments(scope), 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);
+			const removed = await params.store.removeDocument(scope, docId);
+			if (!removed) return textResult(formatStoredDocumentNotFound(docId, scope.label));
+			params.autoGroundingController?.forgetDocument(scope, 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)) return textResult(`Set confirm=true to clear scope ${scope.label}.`);
+			params.autoGroundingController?.forgetScope(scope);
+			return textResult(formatScopeClearResult(await params.store.clearScope(scope), scope.label));
+		}
+	};
+}
+function createKnowhereToolFactory(params) {
+	return (ctx) => [
+		createIngestTool({
+			api: params.api,
+			config: params.config,
+			store: params.store,
+			ctx
+		}),
+		createJobListTool({
+			api: params.api,
+			config: params.config,
+			store: params.store,
+			ctx
+		}),
+		createJobStatusTool({
+			api: params.api,
+			config: params.config,
+			store: params.store,
+			ctx
+		}),
+		createImportCompletedJobTool({
+			api: params.api,
+			config: params.config,
+			store: params.store,
+			ctx
+		}),
+		createGrepTool({
+			store: params.store,
+			ctx
+		}),
+		createReadResultFileTool({
+			store: params.store,
+			ctx
+		}),
+		createPreviewDocumentTool({
+			store: params.store,
+			ctx
+		}),
+		createListTool({
+			store: params.store,
+			ctx
+		}),
+		createRemoveTool({
+			store: params.store,
+			ctx,
+			autoGroundingController: params.autoGroundingController
+		}),
+		createClearScopeTool({
+			store: params.store,
+			ctx,
+			autoGroundingController: params.autoGroundingController
+		})
+	];
+}
+//#endregion
+export { createKnowhereToolFactory };