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

package/dist/config.js

@@ -1,4 +1,5 @@
 import { isRecord } from "./types.js";
+import fs from "node:fs/promises";
 import path from "node:path";
 //#region src/config.ts
 const DEFAULT_BASE_URL = "https://api.knowhereto.ai";
@@ -24,16 +25,6 @@ const knowherePluginConfigSchema = {
 			],
 			default: "session"
 		},
-		autoGrounding: {
-			type: "boolean",
-			default: true
-		},
-		maxContextChars: {
-			type: "integer",
-			minimum: 500,
-			maximum: 12e3,
-			default: 4e3
-		},
 		pollIntervalMs: {
 			type: "integer",
 			minimum: 1e3,
@@ -63,8 +54,6 @@ const knowherePluginConfigSchema = {
 const KNOWHERE_PLUGIN_DEFAULTS = Object.freeze({
 	baseUrl: DEFAULT_BASE_URL,
 	scopeMode: "session",
-	autoGrounding: true,
-	maxContextChars: 4e3,
 	pollIntervalMs: 1e4,
 	pollTimeoutMs: 18e5,
 	requestTimeoutMs: 6e4,
@@ -74,9 +63,6 @@ function readString(raw, key) {
 	const value = raw[key];
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
-function readBoolean(raw, key, fallback) {
-	return typeof raw[key] === "boolean" ? raw[key] : fallback;
-}
 function readNumber(raw, key, fallback, options = {}) {
 	const value = raw[key];
 	const parsed = typeof value === "number" && Number.isFinite(value) ? value : fallback;
@@ -97,12 +83,6 @@ function resolveKnowhereConfig(api) {
 		baseUrl: readString(raw, "baseUrl") || process.env.KNOWHERE_BASE_URL || "https://api.knowhereto.ai",
 		storageDir: storageDirRaw ? api.resolvePath(storageDirRaw) : path.join(stateDir, "plugins", api.id),
 		scopeMode: readScopeMode(raw),
-		autoGrounding: readBoolean(raw, "autoGrounding", KNOWHERE_PLUGIN_DEFAULTS.autoGrounding),
-		maxContextChars: readNumber(raw, "maxContextChars", KNOWHERE_PLUGIN_DEFAULTS.maxContextChars, {
-			min: 500,
-			max: 12e3,
-			integer: true
-		}),
 		pollIntervalMs: readNumber(raw, "pollIntervalMs", KNOWHERE_PLUGIN_DEFAULTS.pollIntervalMs, {
 			min: 1e3,
 			max: 6e4,
@@ -125,8 +105,42 @@ function resolveKnowhereConfig(api) {
 		})
 	};
 }
+const API_KEY_URL = "https://knowhereto.ai/api-keys";
+const PURCHASE_CREDITS_URL = "https://knowhereto.ai/usage?buy=true";
+const API_KEY_STATE_FILE = "api-key.json";
 function assertKnowhereApiKey(config) {
-	if (!config.apiKey) throw new Error("Knowhere API key missing. Set plugins.entries.knowhere.config.apiKey or KNOWHERE_API_KEY.");
+	if (!config.apiKey) throw new Error([
+		"Knowhere API key is not configured.",
+		`Please create one at: ${API_KEY_URL}`,
+		"Then paste the key into this conversation so I can set it up with the knowhere_set_api_key tool."
+	].join("\n"));
+}
+function isPaymentRequiredError(error) {
+	if (!(error instanceof Error)) return false;
+	if (!("code" in error)) return false;
+	if (typeof error.code !== "string") return false;
+	return error.code.includes("PAYMENT_REQUIRED");
+}
+function formatPaymentRequiredMessage() {
+	return ["Your Knowhere account has insufficient credits.", `Please purchase more at: ${PURCHASE_CREDITS_URL}`].join("\n");
+}
+function resolveApiKeyStatePath(storageDir) {
+	return path.join(storageDir, API_KEY_STATE_FILE);
+}
+async function readPersistedApiKey(storageDir) {
+	try {
+		const raw = await fs.readFile(resolveApiKeyStatePath(storageDir), "utf-8");
+		const parsed = JSON.parse(raw);
+		if (isRecord(parsed) && typeof parsed.apiKey === "string" && parsed.apiKey.trim()) return parsed.apiKey.trim();
+		return null;
+	} catch {
+		return null;
+	}
+}
+async function persistApiKey(storageDir, apiKey) {
+	await fs.mkdir(storageDir, { recursive: true });
+	const filePath = resolveApiKeyStatePath(storageDir);
+	await fs.writeFile(filePath, JSON.stringify({ apiKey: apiKey.trim() }), "utf-8");
 }
 //#endregion
-export { assertKnowhereApiKey, knowherePluginConfigSchema, resolveKnowhereConfig };
+export { assertKnowhereApiKey, formatPaymentRequiredMessage, isPaymentRequiredError, knowherePluginConfigSchema, persistApiKey, readPersistedApiKey, resolveKnowhereConfig };

package/dist/index.js

@@ -1,10 +1,9 @@
-import { knowherePluginConfigSchema, resolveKnowhereConfig } from "./config.js";
-import { registerKnowhereAutoGrounding } from "./hooks.js";
+import { knowherePluginConfigSchema, readPersistedApiKey, resolveKnowhereConfig } from "./config.js";
 import { KnowhereStore } from "./store.js";
 import { createKnowhereToolFactory } from "./tools.js";
 //#region src/index.ts
 const plugin = {
-	id: "knowhere",
+	id: "knowhere-claw",
 	name: "Knowhere",
 	description: "Knowhere document ingestion and direct stored-result access for OpenClaw.",
 	configSchema: knowherePluginConfigSchema,
@@ -15,16 +14,18 @@ const plugin = {
 			scopeMode: config.scopeMode,
 			logger: api.logger
 		});
-		const autoGroundingController = config.autoGrounding ? registerKnowhereAutoGrounding({
-			api,
-			config,
-			store
-		}) : void 0;
+		if (!config.apiKey) readPersistedApiKey(config.storageDir).then((persistedKey) => {
+			if (persistedKey) {
+				config.apiKey = persistedKey;
+				api.logger.info("knowhere: loaded API key from persisted state");
+			}
+		}).catch((error) => {
+			api.logger.warn(`knowhere: failed to read persisted API key: ${error instanceof Error ? error.message : String(error)}`);
+		});
 		api.registerTool(createKnowhereToolFactory({
 			api,
 			config,
-			store,
-			autoGroundingController
+			store
 		}), { names: [
 			"knowhere_ingest_document",
 			"knowhere_list_jobs",
@@ -35,7 +36,8 @@ const plugin = {
 			"knowhere_preview_document",
 			"knowhere_list_documents",
 			"knowhere_remove_document",
-			"knowhere_clear_scope"
+			"knowhere_clear_scope",
+			"knowhere_set_api_key"
 		] });
 	}
 };

package/dist/parser.js

@@ -1,7 +1,7 @@
 import { isNodeError, isRecord } from "./types.js";
 import { strFromU8, unzipSync } from "./node_modules/.pnpm/fflate@0.8.2/node_modules/fflate/esm/browser.js";
-import path from "node:path";
 import fs from "node:fs/promises";
+import path from "node:path";
 import { createHash } from "node:crypto";
 const CHUNKS_FILE_NAME = "chunks.json";
 const FULL_MARKDOWN_FILE_NAME = "full.md";

package/dist/session.js

@@ -7,6 +7,7 @@ const RESERVED_AGENT_SESSION_ROOTS = new Set([
 	"global"
 ]);
 const CONVERSATION_KIND_SEGMENTS = new Set([
+	"account",
 	"channel",
 	"chat",
 	"conversation",

package/dist/store.d.ts

@@ -1,4 +1,4 @@
-import type { KnowhereScope, PluginLogger, SaveStoredDocumentPayload, ScopeMode, StoredDocumentPayload, StoredDocumentRecord } from "./types";
+import type { ChannelRouteRecord, KnowhereScope, PluginLogger, SaveStoredDocumentPayload, ScopeMode, StoredDocumentPayload, StoredDocumentRecord } from "./types";
 export declare class KnowhereStore {
     private readonly rootDir;
     private readonly scopeMode;
@@ -9,6 +9,8 @@ export declare class KnowhereStore {
     private readonly scopeKeyAliases;
     private readonly sessionScopeKeysBySessionId;
     private readonly sessionScopeKeysBySessionKey;
+    private readonly channelRoutes;
+    private routesLoaded;
     constructor(params: {
         rootDir: string;
         scopeMode: ScopeMode;
@@ -24,6 +26,17 @@ export declare class KnowhereStore {
         sessionId?: string;
         messageContext: unknown;
     }): string | undefined;
+    registerChannelRoute(params: {
+        channelId: string;
+        accountId?: string;
+        conversationId?: string;
+    }): Promise<void>;
+    resolveChannelRoute(params: {
+        channelId?: string;
+        conversationId?: string;
+        sessionKey?: string;
+    }): Promise<ChannelRouteRecord | undefined>;
+    private lookupChannelRoute;
     inheritScopeAlias(context: {
         childSessionKey?: string;
         childSessionId?: string;
@@ -37,6 +50,7 @@ export declare class KnowhereStore {
     }): KnowhereScope;
     listDocuments(scope: KnowhereScope): Promise<StoredDocumentRecord[]>;
     loadDocumentPayload(scope: KnowhereScope, docId: string): Promise<StoredDocumentPayload | null>;
+    getResultFileAbsolutePath(scope: KnowhereScope, docId: string, relativePath: string): string;
     readResultFile(scope: KnowhereScope, docId: string, relativePath: string): Promise<{
         document: StoredDocumentRecord;
         relativePath: string;
@@ -56,6 +70,9 @@ export declare class KnowhereStore {
     private deleteDocumentPayloadCache;
     private deleteScopeDocumentPayloadCaches;
     private loadOrBuildBrowseIndex;
+    private buildRouteKey;
+    private ensureRoutesLoaded;
+    private persistRoutes;
     private resolveCanonicalScopeKey;
     private resolveKnownScopeKey;
     private rebuildIndex;

package/dist/store.js

@@ -1,9 +1,9 @@
 import { isNodeError } from "./types.js";
-import { hashString, normalizeWhitespace, sanitizeStringArray, slugify } from "./text.js";
-import { deriveMessageContextScopeKey } from "./session.js";
 import { buildStoredBrowseIndex, extractKnowhereResultArchive, isStoredBrowseIndex, readStoredKnowhereResultContent, readStoredKnowhereResultSummary, resolveResultEntryPath } from "./parser.js";
-import path from "node:path";
+import { hashString, normalizeWhitespace, sanitizeStringArray, slugify } from "./text.js";
+import { deriveMessageContextScopeKey, findConversationSegmentValue, parseConversationSessionKey } from "./session.js";
 import fs from "node:fs/promises";
+import path from "node:path";
 import { randomUUID } from "node:crypto";
 //#region src/store.ts
 const INDEX_VERSION = 1;
@@ -11,6 +11,7 @@ const BROWSE_INDEX_FILE_NAME = "browse-index.json";
 const DOCUMENT_PAYLOAD_CACHE_LIMIT = 16;
 const METADATA_FILE_NAME = "metadata.json";
 const RESULT_DIRECTORY_NAME = "result";
+const ROUTES_FILE_NAME = "routes.json";
 async function pathExists(targetPath) {
 	try {
 		await fs.access(targetPath);
@@ -146,6 +147,8 @@ var KnowhereStore = class {
 	scopeKeyAliases;
 	sessionScopeKeysBySessionId;
 	sessionScopeKeysBySessionKey;
+	channelRoutes;
+	routesLoaded;
 	constructor(params) {
 		this.rootDir = params.rootDir;
 		this.scopeMode = params.scopeMode;
@@ -156,6 +159,8 @@ var KnowhereStore = class {
 		this.scopeKeyAliases = /* @__PURE__ */ new Map();
 		this.sessionScopeKeysBySessionId = /* @__PURE__ */ new Map();
 		this.sessionScopeKeysBySessionKey = /* @__PURE__ */ new Map();
+		this.channelRoutes = /* @__PURE__ */ new Map();
+		this.routesLoaded = false;
 	}
 	registerScopeAlias(context) {
 		const canonicalScopeKey = this.resolveCanonicalScopeKey(context.scopeKey);
@@ -181,6 +186,68 @@ var KnowhereStore = class {
 			sessionId
 		});
 	}
+	async registerChannelRoute(params) {
+		if (!params.accountId) {
+			this.logger.debug?.(`knowhere: registerChannelRoute skipped — no accountId channelId=${params.channelId} conversationId=${params.conversationId ?? "(none)"}`);
+			return;
+		}
+		const key = this.buildRouteKey(params.channelId, params.conversationId);
+		if (!key) return;
+		const record = {
+			channelId: params.channelId,
+			accountId: params.accountId,
+			conversationId: params.conversationId,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		this.channelRoutes.set(key, record);
+		this.logger.info?.(`knowhere: registerChannelRoute key=${key} accountId=${params.accountId} (immediate)`);
+		await this.ensureRoutesLoaded();
+		this.channelRoutes.set(key, record);
+		this.logger.info?.(`knowhere: registerChannelRoute key=${key} accountId=${params.accountId} (persisted)`);
+		await this.persistRoutes();
+	}
+	async resolveChannelRoute(params) {
+		const immediate = this.lookupChannelRoute(params);
+		if (immediate) {
+			this.logger.debug?.(`knowhere: resolveChannelRoute hit (immediate) accountId=${immediate.accountId} channelId=${params.channelId ?? "(none)"} sessionKey=${params.sessionKey ?? "(none)"}`);
+			return immediate;
+		}
+		await this.ensureRoutesLoaded();
+		const resolved = this.lookupChannelRoute(params);
+		this.logger.debug?.(resolved ? `knowhere: resolveChannelRoute hit (disk) accountId=${resolved.accountId} channelId=${params.channelId ?? "(none)"} sessionKey=${params.sessionKey ?? "(none)"}` : `knowhere: resolveChannelRoute miss channelId=${params.channelId ?? "(none)"} sessionKey=${params.sessionKey ?? "(none)"} mapSize=${this.channelRoutes.size}`);
+		return resolved;
+	}
+	lookupChannelRoute(params) {
+		if (params.channelId) {
+			const directKey = this.buildRouteKey(params.channelId, params.conversationId);
+			if (directKey) {
+				const route = this.channelRoutes.get(directKey);
+				if (route) return route;
+			}
+		}
+		if (params.sessionKey) {
+			const parsed = parseConversationSessionKey(params.sessionKey);
+			if (parsed) {
+				const surface = parsed.surface;
+				const remainderAfterSurface = parsed.segments.slice(1).join(":");
+				if (surface && remainderAfterSurface) {
+					const fullKey = this.buildRouteKey(surface, remainderAfterSurface);
+					if (fullKey) {
+						const route = this.channelRoutes.get(fullKey);
+						if (route) return route;
+					}
+				}
+				const conversation = findConversationSegmentValue(parsed, "channel", "direct", "group", "chat", "room", "conversation", "user", "member");
+				if (surface && conversation) {
+					const derivedKey = this.buildRouteKey(surface, conversation);
+					if (derivedKey) {
+						const route = this.channelRoutes.get(derivedKey);
+						if (route) return route;
+					}
+				}
+			}
+		}
+	}
 	inheritScopeAlias(context) {
 		const requesterScopeKey = this.resolveKnownScopeKey({
 			sessionId: context.requesterSessionId,
@@ -247,6 +314,9 @@ var KnowhereStore = class {
 			return payload;
 		});
 	}
+	getResultFileAbsolutePath(scope, docId, relativePath) {
+		return resolveResultEntryPath(buildStoredDocumentPaths(scope, docId).resultDir, relativePath);
+	}
 	async readResultFile(scope, docId, relativePath) {
 		return this.runWithScopeAccessLock(scope, async () => {
 			const paths = buildStoredDocumentPaths(scope, docId);
@@ -437,6 +507,24 @@ var KnowhereStore = class {
 		await writeJsonAtomic(paths.browseIndexPath, browseIndex);
 		return browseIndex;
 	}
+	buildRouteKey(channelId, conversationId) {
+		const normalizedChannel = normalizeWhitespace(channelId)?.toLowerCase();
+		if (!normalizedChannel) return;
+		const normalizedConversation = normalizeWhitespace(conversationId);
+		return normalizedConversation ? `${normalizedChannel}:${normalizedConversation}` : normalizedChannel;
+	}
+	async ensureRoutesLoaded() {
+		if (this.routesLoaded) return;
+		const stored = await readJson(path.join(this.rootDir, ROUTES_FILE_NAME), {});
+		for (const [key, record] of Object.entries(stored)) this.channelRoutes.set(key, record);
+		this.routesLoaded = true;
+	}
+	async persistRoutes() {
+		const routesPath = path.join(this.rootDir, ROUTES_FILE_NAME);
+		const data = {};
+		for (const [key, record] of this.channelRoutes) data[key] = record;
+		await writeJsonAtomic(routesPath, data);
+	}
 	resolveCanonicalScopeKey(scopeKey) {
 		let currentKey = normalizeWhitespace(scopeKey) || scopeKey;
 		const seen = /* @__PURE__ */ new Set();

package/dist/tools.d.ts

@@ -1,9 +1,8 @@
-import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { type AnyAgentTool, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import { KnowhereStore } from "./store";
-import type { KnowhereAutoGroundingController, ResolvedKnowhereConfig, ToolRuntimeContext } from "./types";
+import type { ResolvedKnowhereConfig, ToolRuntimeContext } from "./types";
 export declare function createKnowhereToolFactory(params: {
     api: OpenClawPluginApi;
     config: ResolvedKnowhereConfig;
     store: KnowhereStore;
-    autoGroundingController?: KnowhereAutoGroundingController;
 }): (ctx: ToolRuntimeContext) => AnyAgentTool[];