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

package/README.md

@@ -0,0 +1,163 @@
+# Knowhere OpenClaw Plugin
+
+Developer guide for the Knowhere plugin that integrates with OpenClaw.
+
+This repository is intentionally focused on runtime behavior, storage, and
+integration details. Agent-facing usage guidance lives in
+[`skills/knowhere/SKILL.md`](./skills/knowhere/SKILL.md).
+
+## What this plugin does
+
+The plugin uses Knowhere for parsing and job orchestration, then stores the
+returned result package inside OpenClaw-managed local storage.
+
+Its responsibilities are:
+
+- register the `knowhere_*` tools
+- optionally auto-ingest supported attachments
+- persist extracted Knowhere result packages by scope
+- expose browse-first path, chunk, context, and raw-file access back to agents
+- inject compact document availability or status context when `autoGrounding` is enabled
+
+The package targets Node `>=22.12.0` and builds to `dist/` with Rolldown plus
+TypeScript declarations.
+
+## Repository layout
+
+- [`src/index.ts`](./src/index.ts): plugin entrypoint and registration
+- [`src/config.ts`](./src/config.ts): config schema and resolution
+- [`src/client.ts`](./src/client.ts): Knowhere API client
+- [`src/store.ts`](./src/store.ts): scoped local storage and index maintenance
+- [`src/parser.ts`](./src/parser.ts): ZIP extraction and stored result readers
+- [`src/tools.ts`](./src/tools.ts): `knowhere_*` tool definitions and response formatting
+- [`src/hooks.ts`](./src/hooks.ts): auto-grounding and background attachment ingest
+- [`skills/knowhere/SKILL.md`](./skills/knowhere/SKILL.md): agent usage instructions
+- [`smoketest/run-tool.ts`](./smoketest/run-tool.ts): tool smoke-test entrypoint
+- [`openclaw.plugin.json`](./openclaw.plugin.json): plugin manifest, config schema, and bundled skill declaration
+
+## Storage model
+
+The store is scope-aware. Supported `scopeMode` values are `session`, `agent`,
+and `global`.
+
+Each scope is stored under the resolved plugin storage directory with this
+shape:
+
+```text
+<scope>/
+  index.json
+  documents/
+    <docId>/
+      metadata.json
+      browse-index.json
+      result/
+        manifest.json
+        chunks.json
+        hierarchy.json
+        full.md
+        ...
+```
+
+Storage roles:
+
+- `index.json`: internal per-scope cache of document summaries; rebuildable
+- `metadata.json`: plugin-local mapping layer for one stored document
+- `browse-index.json`: plugin-local browse index for path navigation and result-file inventory
+- `result/`: untouched extracted Knowhere result package files
+
+`index.json` is an optimization, not the primary source of truth. If its schema
+version no longer matches the current store code, the plugin rebuilds it from
+the per-document directories.
+
+## Runtime model
+
+The plugin has three main runtime surfaces:
+
+- tools: explicit ingest, browse, raw-file read, job, preview, and cleanup operations
+- hooks: background attachment ingest plus prompt-time document/status injection
+- skill: agent guidance for when and how to use the tools
+
+The primary browse workflow is:
+
+1. `knowhere_read_result_file` on `manifest.json`
+2. `knowhere_preview_document`
+3. `knowhere_grep` for text search
+4. `knowhere_read_result_file` again for `hierarchy.json`, `kb.csv`, or table HTML when needed
+
+`autoGrounding: true` enables hooks. `autoGrounding: false` leaves the plugin in
+manual tool mode while still loading the bundled skill.
+
+## Development
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Required validation after every code change:
+
+```bash
+pnpm fmt
+pnpm typecheck
+pnpm lint
+pnpm build
+```
+
+Useful scripts:
+
+- `pnpm build`: bundle runtime code and emit declarations
+- `pnpm fmt`: format the repository with Oxc Formatter
+- `pnpm fmt:check`: check formatting without writing changes
+- `pnpm lint`: run Oxlint in type-aware mode
+- `pnpm lint:fix`: run Oxlint with fixes
+- `pnpm typecheck`: run `tsgo --noEmit`
+- `pnpm smoke:tools -- ...`: execute one plugin tool through the real registration path
+- `pnpm clean`: remove `dist/`
+
+## OpenClaw integration
+
+Minimal plugin config:
+
+```json5
+{
+  plugins: {
+    load: {
+      paths: ["/absolute/path/to/knowhere-openclaw-plugin"],
+    },
+    entries: {
+      knowhere: {
+        enabled: true,
+        config: {
+          apiKey: "sk_...",
+          scopeMode: "session",
+          autoGrounding: true,
+        },
+      },
+    },
+  },
+}
+```
+
+Config notes:
+
+- `apiKey` falls back to `KNOWHERE_API_KEY`
+- `baseUrl` falls back to `KNOWHERE_BASE_URL`
+- `storageDir` defaults to the OpenClaw state directory under `plugins/<plugin-id>`
+- `scopeMode` controls document sharing boundaries
+- `maxContextChars`, polling, and timeout settings are declared in [`openclaw.plugin.json`](./openclaw.plugin.json)
+
+If you use skill filters in OpenClaw, allow the bundled `knowhere` skill or the
+agents will have the tools without the intended usage guidance.
+
+## Packaging
+
+The published package includes:
+
+- `dist/`
+- `skills/`
+- [`openclaw.plugin.json`](./openclaw.plugin.json)
+- `README.md`
+
+That is enough for OpenClaw to load the plugin runtime and bundled skill from
+the installed package root.

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,37 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
+	if (typeof require !== "undefined") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
+});
+//#endregion
+export { __commonJSMin, __exportAll, __require, __toESM };

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { KnowhereIngestRequest, KnowhereIngestResult, KnowhereJobList, KnowhereJobListRequest, KnowhereJobResult } from "./types";
+export declare class KnowhereClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    private readonly uploadTimeoutMs;
+    private readonly pollIntervalMs;
+    private readonly pollTimeoutMs;
+    private readonly logger;
+    private readonly sdk;
+    constructor(params: {
+        apiKey: string;
+        baseUrl: string;
+        requestTimeoutMs: number;
+        uploadTimeoutMs: number;
+        pollIntervalMs: number;
+        pollTimeoutMs: number;
+        logger: {
+            debug?: (message: string) => void;
+            info: (message: string) => void;
+        };
+    });
+    ingestDocument(params: KnowhereIngestRequest): Promise<KnowhereIngestResult>;
+    private logPollProgress;
+    getJob(jobId: string): Promise<KnowhereJobResult>;
+    listJobs(options?: KnowhereJobListRequest): Promise<KnowhereJobList>;
+    getCompletedJobResult(jobId: string): Promise<KnowhereIngestResult>;
+    private downloadResultArchive;
+    private uploadFile;
+    private requestJson;
+    private requestBuffer;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,395 @@
+import { isRecord } from "./types.js";
+import { Knowhere } from "./node_modules/.pnpm/@knowhere-ai_sdk@0.1.1/node_modules/@knowhere-ai/sdk/dist/index.js";
+import { formatErrorMessage } from "./error-message.js";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { openAsBlob } from "node:fs";
+//#region src/client.ts
+const RETRYABLE_STATUS_CODES = new Set([
+	409,
+	500,
+	502,
+	503,
+	504
+]);
+const RETRYABLE_UPLOAD_STATUS_CODES = new Set([
+	500,
+	502,
+	503,
+	504
+]);
+const USER_AGENT = "knowhere-openclaw-plugin/0.1.0";
+function createRetryableError(message, retryable) {
+	const error = new Error(message);
+	error.retryable = retryable;
+	return error;
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function normalizeInlineText(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+function stringifyPayload(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return null;
+	}
+}
+function buildApiErrorMessage(status, payload) {
+	if (typeof payload === "string") {
+		const normalized = normalizeInlineText(payload);
+		if (normalized) return `HTTP ${status}: ${normalized}`;
+	}
+	if (isRecord(payload)) {
+		const nested = isRecord(payload.error) ? payload.error : payload;
+		const code = typeof nested.code === "string" ? nested.code : null;
+		const message = typeof nested.message === "string" ? nested.message : null;
+		const requestId = typeof nested.request_id === "string" ? nested.request_id : null;
+		const detailsPayload = Object.hasOwn(nested, "details") ? nested.details : void 0;
+		const detailsText = detailsPayload === void 0 ? null : stringifyPayload(detailsPayload);
+		const parts = [
+			code,
+			message ? normalizeInlineText(message) : null,
+			requestId ? `request_id=${requestId}` : null,
+			detailsText ? `details=${detailsText}` : null
+		].filter((value) => Boolean(value));
+		if (parts.length > 0) return parts.join(" ");
+		const payloadText = stringifyPayload(payload);
+		if (payloadText) return `HTTP ${status}: ${payloadText}`;
+	}
+	return `HTTP ${status}`;
+}
+function buildChainedErrorMessage(prefix, error) {
+	const detail = formatErrorMessage(error);
+	return detail ? `${prefix} ${detail}` : prefix;
+}
+async function readApiErrorPayload(response) {
+	const normalized = (await response.clone().text()).trim();
+	if (!normalized) return null;
+	try {
+		return JSON.parse(normalized);
+	} catch {
+		return normalized;
+	}
+}
+function readRetryAfterSeconds(value) {
+	if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+	if (typeof value === "string" && value.trim()) {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed) && parsed > 0) return parsed;
+	}
+	return null;
+}
+function extractRetryAfterSeconds(payload, response) {
+	if (isRecord(payload)) {
+		const nested = isRecord(payload.error) ? payload.error : payload;
+		const retryAfter = readRetryAfterSeconds((isRecord(nested.details) ? nested.details : null)?.retry_after);
+		if (retryAfter !== null) return retryAfter;
+	}
+	return readRetryAfterSeconds(response.headers.get("retry-after"));
+}
+function readFiniteNumber(value, fieldName) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`Knowhere API returned an invalid ${fieldName} value.`);
+	return value;
+}
+function toIsoString(value) {
+	if (value instanceof Date && !Number.isNaN(value.valueOf())) return value.toISOString();
+	if (typeof value === "string" && value.trim()) return value.trim();
+	return null;
+}
+function normalizeSdkJob(job) {
+	return {
+		job_id: job.jobId,
+		status: job.status,
+		source_type: job.sourceType,
+		data_id: job.dataId ?? null,
+		created_at: toIsoString(job.createdAt),
+		upload_url: job.uploadUrl ?? null,
+		upload_headers: job.uploadHeaders ?? null,
+		expires_in: job.expiresIn ?? null
+	};
+}
+function normalizeSdkJobError(error) {
+	if (!error) return null;
+	return {
+		code: error.code,
+		message: error.message,
+		request_id: error.requestId,
+		details: error.details
+	};
+}
+function normalizeSdkJobResult(jobResult) {
+	return {
+		job_id: jobResult.jobId,
+		status: jobResult.status,
+		source_type: jobResult.sourceType,
+		data_id: jobResult.dataId ?? null,
+		created_at: toIsoString(jobResult.createdAt),
+		progress: jobResult.progress ?? void 0,
+		error: normalizeSdkJobError(jobResult.error),
+		result: isRecord(jobResult.result) ? jobResult.result : null,
+		result_url: jobResult.resultUrl ?? null,
+		result_url_expires_at: toIsoString(jobResult.resultUrlExpiresAt),
+		file_name: jobResult.fileName ?? null,
+		file_extension: jobResult.fileExtension ?? null,
+		model: jobResult.model ?? null,
+		ocr_enabled: typeof jobResult.ocrEnabled === "boolean" ? jobResult.ocrEnabled : null,
+		duration_seconds: typeof jobResult.durationSeconds === "number" ? jobResult.durationSeconds : null,
+		credits_spent: typeof jobResult.creditsSpent === "number" ? jobResult.creditsSpent : null
+	};
+}
+function normalizeApiJobResult(raw) {
+	if (!isRecord(raw) || typeof raw.job_id !== "string") throw new Error("Knowhere API returned an invalid job result payload.");
+	return raw;
+}
+function normalizeApiJobList(raw) {
+	if (!isRecord(raw) || !Array.isArray(raw.jobs)) throw new Error("Knowhere API returned an invalid job list payload.");
+	return {
+		jobs: raw.jobs.map((job) => normalizeApiJobResult(job)),
+		total: readFiniteNumber(raw.total, "total"),
+		page: readFiniteNumber(raw.page, "page"),
+		pageSize: readFiniteNumber(raw.page_size, "page_size"),
+		totalPages: readFiniteNumber(raw.total_pages, "total_pages")
+	};
+}
+function buildSyntheticJob(jobResult) {
+	return {
+		job_id: jobResult.job_id,
+		status: jobResult.status,
+		source_type: jobResult.source_type,
+		data_id: jobResult.data_id ?? null,
+		created_at: jobResult.created_at ?? null,
+		upload_url: null,
+		upload_headers: null,
+		expires_in: null
+	};
+}
+function toSdkParsingParams(parsingParams) {
+	if (!parsingParams) return;
+	const mapped = {
+		...parsingParams.model ? { model: parsingParams.model } : {},
+		...typeof parsingParams.ocr_enabled === "boolean" ? { ocrEnabled: parsingParams.ocr_enabled } : {},
+		...parsingParams.kb_dir ? { kbDir: parsingParams.kb_dir } : {},
+		...parsingParams.doc_type ? { docType: parsingParams.doc_type } : {},
+		...typeof parsingParams.smart_title_parse === "boolean" ? { smartTitleParse: parsingParams.smart_title_parse } : {},
+		...typeof parsingParams.summary_image === "boolean" ? { summaryImage: parsingParams.summary_image } : {},
+		...typeof parsingParams.summary_table === "boolean" ? { summaryTable: parsingParams.summary_table } : {},
+		...typeof parsingParams.summary_txt === "boolean" ? { summaryTxt: parsingParams.summary_txt } : {},
+		...parsingParams.add_frag_desc ? { addFragDesc: parsingParams.add_frag_desc } : {}
+	};
+	return Object.keys(mapped).length > 0 ? mapped : void 0;
+}
+var KnowhereClient = class {
+	apiKey;
+	baseUrl;
+	requestTimeoutMs;
+	uploadTimeoutMs;
+	pollIntervalMs;
+	pollTimeoutMs;
+	logger;
+	sdk;
+	constructor(params) {
+		this.apiKey = params.apiKey;
+		this.baseUrl = params.baseUrl.replace(/\/+$/, "");
+		this.requestTimeoutMs = params.requestTimeoutMs;
+		this.uploadTimeoutMs = params.uploadTimeoutMs;
+		this.pollIntervalMs = params.pollIntervalMs;
+		this.pollTimeoutMs = params.pollTimeoutMs;
+		this.logger = params.logger;
+		this.sdk = new Knowhere({
+			apiKey: this.apiKey,
+			baseURL: this.baseUrl,
+			timeout: this.requestTimeoutMs,
+			uploadTimeout: this.uploadTimeoutMs,
+			maxRetries: 5,
+			defaultHeaders: { "User-Agent": USER_AGENT }
+		});
+	}
+	async ingestDocument(params) {
+		const sourceType = params.url ? "url" : "file";
+		const parsingParams = toSdkParsingParams(params.parsingParams);
+		const resolvedFileName = typeof params.fileName === "string" && params.fileName.trim() ? params.fileName.trim() : params.filePath ? path.basename(params.filePath) : void 0;
+		const job = await this.sdk.jobs.create({
+			sourceType,
+			...sourceType === "url" ? { sourceUrl: params.url } : { fileName: resolvedFileName },
+			...params.dataId ? { dataId: params.dataId } : {},
+			...parsingParams ? { parsingParams } : {}
+		});
+		this.logger.info(`knowhere: created ingest job ${job.jobId} sourceType=${sourceType} requestTimeoutMs=${this.requestTimeoutMs} pollIntervalMs=${this.pollIntervalMs} pollTimeoutMs=${this.pollTimeoutMs}`);
+		await params.onJobCreated?.(normalizeSdkJob(job));
+		if (sourceType === "file") {
+			if (!params.filePath) throw new Error("filePath is required when sourceType=file.");
+			if (!job.uploadUrl) throw new Error(`Knowhere job ${job.jobId} did not return an uploadUrl.`);
+			const fileBlob = await openAsBlob(params.filePath);
+			this.logger.info(`knowhere: uploading local file for job ${job.jobId} path=${params.filePath} bytes=${fileBlob.size}`);
+			await this.uploadFile(job.uploadUrl, job.uploadHeaders, fileBlob);
+			this.logger.info(`knowhere: upload completed for job ${job.jobId}`);
+		}
+		let updateChain = Promise.resolve();
+		const enqueueJobUpdate = (jobResult) => {
+			if (!params.onJobUpdated) return;
+			const normalizedJobResult = normalizeSdkJobResult(jobResult);
+			updateChain = updateChain.then(() => Promise.resolve(params.onJobUpdated?.(normalizedJobResult)));
+		};
+		const sdkJobResult = await this.sdk.jobs.wait(job.jobId, {
+			pollInterval: this.pollIntervalMs,
+			pollTimeout: this.pollTimeoutMs,
+			onProgress: (progress) => {
+				this.logPollProgress(job.jobId, progress);
+				enqueueJobUpdate(progress.jobResult);
+			}
+		});
+		this.logger.info(`knowhere: polling completed for job ${job.jobId} status=${sdkJobResult.status}`);
+		enqueueJobUpdate(sdkJobResult);
+		await updateChain;
+		const jobResult = normalizeSdkJobResult(sdkJobResult);
+		if (!jobResult.result_url) throw new Error(`Knowhere job ${jobResult.job_id} completed without a result_url.`);
+		return {
+			job: normalizeSdkJob(job),
+			jobResult,
+			downloadedResult: await this.downloadResultArchive(jobResult.result_url)
+		};
+	}
+	logPollProgress(jobId, progress) {
+		const parts = [
+			`knowhere: polling job ${jobId}`,
+			`status=${progress.status}`,
+			`elapsedSeconds=${progress.elapsedSeconds}`
+		];
+		const progressText = stringifyPayload(progress.jobResult.progress);
+		if (progressText && progressText !== "null") parts.push(`progress=${normalizeInlineText(progressText)}`);
+		const errorMessage = progress.jobResult.error?.message;
+		if (errorMessage) parts.push(`error=${normalizeInlineText(errorMessage)}`);
+		(this.logger.debug ?? this.logger.info)(parts.join(" "));
+	}
+	async getJob(jobId) {
+		const normalizedJobId = jobId.trim();
+		if (!normalizedJobId) throw new Error("jobId is required.");
+		return normalizeSdkJobResult(await this.sdk.jobs.get(normalizedJobId));
+	}
+	async listJobs(options = {}) {
+		const params = new URLSearchParams();
+		if (typeof options.page === "number") params.set("page", String(options.page));
+		if (typeof options.pageSize === "number") params.set("page_size", String(options.pageSize));
+		if (typeof options.jobStatus === "string" && options.jobStatus.trim()) params.set("job_status", options.jobStatus.trim());
+		if (typeof options.jobType === "string" && options.jobType.trim()) params.set("job_type", options.jobType.trim());
+		if (typeof options.recentDays === "number") params.set("recent_days", String(options.recentDays));
+		if (typeof options.startTime === "string" && options.startTime.trim()) params.set("start_time", options.startTime.trim());
+		if (typeof options.endTime === "string" && options.endTime.trim()) params.set("end_time", options.endTime.trim());
+		const target = params.size > 0 ? `/v1/jobs/page?${params.toString()}` : "/v1/jobs/page";
+		return normalizeApiJobList(await this.requestJson("GET", target, void 0, { timeoutMs: this.requestTimeoutMs }));
+	}
+	async getCompletedJobResult(jobId) {
+		const normalizedJobId = jobId.trim();
+		if (!normalizedJobId) throw new Error("jobId is required.");
+		const jobResult = await this.getJob(normalizedJobId);
+		if (jobResult.status !== "done") throw new Error(`Knowhere job ${jobResult.job_id} is not completed. Current status: ${jobResult.status}.`);
+		if (!jobResult.result_url) throw new Error(`Knowhere job ${jobResult.job_id} completed without a result_url.`);
+		return {
+			job: buildSyntheticJob(jobResult),
+			jobResult,
+			downloadedResult: await this.downloadResultArchive(jobResult.result_url)
+		};
+	}
+	async downloadResultArchive(resultUrl) {
+		const resultZip = await this.requestBuffer(resultUrl, {
+			auth: false,
+			timeoutMs: this.uploadTimeoutMs
+		});
+		return {
+			zipBytes: resultZip,
+			rawZipSha1: createHash("sha1").update(resultZip).digest("hex")
+		};
+	}
+	async uploadFile(uploadUrl, uploadHeaders, fileBlob) {
+		const headers = { ...uploadHeaders ?? {} };
+		if (!Object.keys(headers).some((key) => key.toLowerCase() === "content-length")) headers["Content-Length"] = String(fileBlob.size);
+		let lastError;
+		for (let attempt = 0; attempt <= 2; attempt += 1) try {
+			const response = await fetch(uploadUrl, {
+				method: "PUT",
+				headers,
+				body: fileBlob,
+				signal: AbortSignal.timeout(this.uploadTimeoutMs)
+			});
+			if (response.ok) return;
+			const payload = await readApiErrorPayload(response);
+			if (attempt < 2 && RETRYABLE_UPLOAD_STATUS_CODES.has(response.status)) {
+				await sleep(Math.min(16e3, 1e3 * 2 ** attempt));
+				continue;
+			}
+			throw createRetryableError(buildApiErrorMessage(response.status, payload), false);
+		} catch (error) {
+			lastError = error;
+			const retryable = error instanceof Error && "retryable" in error ? error.retryable !== false : true;
+			if (attempt >= 2 || !retryable) break;
+			await sleep(Math.min(16e3, 1e3 * 2 ** attempt));
+		}
+		throw new Error(buildChainedErrorMessage("Knowhere upload failed.", lastError), { cause: lastError });
+	}
+	async requestJson(method, target, body, options = {}) {
+		const text = await (await this.request(method, target, body, {
+			...options,
+			headers: {
+				Accept: "application/json",
+				...body === void 0 ? {} : { "Content-Type": "application/json" },
+				...options.headers ?? {}
+			}
+		})).text();
+		if (!text) return {};
+		try {
+			return JSON.parse(text);
+		} catch (error) {
+			throw new Error(`Knowhere API returned invalid JSON for ${method} ${target}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
+	}
+	async requestBuffer(target, options = {}) {
+		const arrayBuffer = await (await this.request("GET", target, void 0, {
+			...options,
+			headers: {
+				Accept: "application/octet-stream",
+				...options.headers ?? {}
+			}
+		})).arrayBuffer();
+		return Buffer.from(arrayBuffer);
+	}
+	async request(method, target, body, options = {}) {
+		const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+		const retries = Number.isFinite(options.retries) ? options.retries : 2;
+		const url = /^https?:\/\//i.test(target) ? target : new URL(target.replace(/^\/+/, ""), `${this.baseUrl}/`).toString();
+		let lastError;
+		for (let attempt = 0; attempt <= retries; attempt += 1) try {
+			const response = await fetch(url, {
+				method,
+				headers: {
+					"User-Agent": USER_AGENT,
+					...options.auth === false ? {} : { Authorization: `Bearer ${this.apiKey}` },
+					...options.headers ?? {}
+				},
+				body: body === void 0 ? void 0 : JSON.stringify(body),
+				signal: AbortSignal.timeout(timeoutMs)
+			});
+			if (!response.ok) {
+				const payload = await readApiErrorPayload(response);
+				const retryAfter = extractRetryAfterSeconds(payload, response);
+				const canRetry = RETRYABLE_STATUS_CODES.has(response.status) || response.status === 429 && retryAfter !== null;
+				if (attempt < retries && canRetry) {
+					await sleep(retryAfter !== null ? retryAfter * 1e3 : Math.min(3e4, 500 * 2 ** attempt));
+					continue;
+				}
+				throw createRetryableError(buildApiErrorMessage(response.status, payload), false);
+			}
+			return response;
+		} catch (error) {
+			lastError = error;
+			const retryable = error instanceof Error && "retryable" in error ? error.retryable !== false : true;
+			if (attempt >= retries || !retryable) break;
+			await sleep(Math.min(3e4, 500 * 2 ** attempt));
+		}
+		throw new Error(buildChainedErrorMessage(`Knowhere request failed for ${method} ${target}.`, lastError), { cause: lastError });
+	}
+};
+//#endregion
+export { KnowhereClient };

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { JsonSchemaObject, ResolvedKnowhereConfig } from "./types";
+export declare const DEFAULT_BASE_URL = "https://api.knowhereto.ai";
+export declare const knowherePluginConfigSchema: JsonSchemaObject;
+export declare function resolveKnowhereConfig(api: OpenClawPluginApi): ResolvedKnowhereConfig;
+export declare function assertKnowhereApiKey(config: ResolvedKnowhereConfig): void;