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

package/README.md

@@ -1,137 +1,53 @@
-# 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.
+# Knowhere for OpenClaw
 
-## Runtime model
+Knowhere is an OpenClaw plugin that parses documents and URLs with Knowhere,
+stores the extracted result package in OpenClaw state, and gives agents a
+browse-first toolset for grounded document work.
 
-The plugin has three main runtime surfaces:
+Quick mental model:
 
-- 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
+- Install the plugin
+- Restart the Gateway
+- Configure `plugins.entries."knowhere-claw".config`
+- Ask an agent to read, search, or compare a document
+- Let the bundled `knowhere` skill steer the agent toward the right tools
 
-The primary browse workflow is:
+## Where It Runs
 
-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
+This plugin runs inside the OpenClaw Gateway process.
 
-`autoGrounding: true` enables hooks. `autoGrounding: false` leaves the plugin in
-manual tool mode while still loading the bundled skill.
+If your agents talk to a remote Gateway, install and configure the plugin on
+the machine running that Gateway, then restart that Gateway.
 
-## Development
+## What You Get
 
-Install dependencies:
-
-```bash
-pnpm install
-```
+- Ingest local files or document URLs with Knowhere
+- Store parsed result packages inside OpenClaw-managed state
+- Preview document structure, search chunks, and inspect raw result files
+- Reuse stored documents across `session`, `agent`, or `global` scope
+- Ship a bundled `knowhere` skill so agents prefer this toolchain for
+  document-heavy tasks
 
-Required validation after every code change:
+## Install
 
 ```bash
-pnpm fmt
-pnpm typecheck
-pnpm lint
-pnpm build
+openclaw plugins install @ontos-ai/knowhere-claw
 ```
 
-Useful scripts:
+Restart the Gateway afterwards.
 
-- `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/`
+## Config
 
-## OpenClaw integration
-
-Minimal plugin config:
+Set config under `plugins.entries."knowhere-claw".config`:
 
 ```json5
 {
   plugins: {
-    load: {
-      paths: ["/absolute/path/to/knowhere-openclaw-plugin"],
-    },
     entries: {
-      knowhere: {
+      "knowhere-claw": {
         enabled: true,
         config: {
-          apiKey: "sk_...",
-          scopeMode: "session",
-          autoGrounding: true,
+          // apiKey is optional
         },
       },
     },
@@ -141,23 +57,80 @@ Minimal plugin config:
 
 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.
+- `apiKey`: optional Knowhere API key. If omitted, the plugin falls back to
+  `KNOWHERE_API_KEY` and any API key previously stored with
+  `knowhere_set_api_key`.
+- If no API key is available when the agent first needs Knowhere, the plugin
+  guides the user to the Knowhere API key page at
+  `https://knowhereto.ai/api-keys`.
+- `baseUrl`: optional Knowhere API base URL. Falls back to
+  `KNOWHERE_BASE_URL` and defaults to `https://api.knowhereto.ai`.
+- `storageDir`: optional directory for persisted parsed documents. By default,
+  the plugin stores data under the OpenClaw state directory for
+  `knowhere-claw`.
+- `scopeMode`: document sharing boundary. Supported values are `session`,
+  `agent`, and `global`. If omitted, the plugin defaults to `session`.
+- `pollIntervalMs`, `pollTimeoutMs`, `requestTimeoutMs`, `uploadTimeoutMs`:
+  optional tuning for job polling, API calls, and large uploads.
+- An explicit `storageDir` such as
+  `/home/<user>/.openclaw/plugin-state/knowhere` makes stored result packages
+  easier to inspect, back up, or clean up.
+
+## How OpenClaw Uses It
+
+Once the plugin is enabled, you can ask an OpenClaw agent to:
+
+- summarize a local document
+- read a document URL
+- find a table or section in a previously ingested document
+- compare a new document with documents already stored in scope
+
+The bundled `knowhere` skill teaches agents to use the `knowhere_*` tools
+instead of raw file reads when document parsing matters.
+
+If you use skill filters or allowlists in OpenClaw, keep the bundled
+`knowhere` skill enabled or the tools will load without their intended usage
+guidance.
+
+If your agent runtime uses a tool allowlist, include `knowhere_*` so agents can
+actually call the plugin tools.
+
+## Scope And Storage
+
+`scopeMode` controls who can reuse parsed documents:
+
+- `session`: only the current session can reuse the stored documents
+- `agent`: all conversations for the same agent can reuse them
+- `global`: all agents on the same Gateway can reuse them
+
+Within each scope, the plugin keeps:
+
+- an `index.json` cache of stored document summaries
+- per-document metadata and browse indexes
+- the extracted Knowhere result package under `result/`
+
+## Common Workflow
+
+1. Provide a file path or URL to the agent.
+2. The agent ingests it into Knowhere and waits for the parse to finish.
+3. Follow-up questions reuse stored results from the current scope.
+4. When needed, the agent can preview structure, search chunks, read raw result
+   files, or clear stored documents.
+
+## Troubleshooting
+
+- Missing API key: `apiKey` config is optional. You can set
+  `plugins.entries."knowhere-claw".config.apiKey`, export
+  `KNOWHERE_API_KEY`, or let the plugin guide the user to
+  `https://knowhereto.ai/api-keys` and store the key with
+  `knowhere_set_api_key`.
+- Documents are not shared between conversations: change `scopeMode` from
+  `session` to `agent` or `global`.
+- The plugin is enabled but agents do not reach for Knowhere: check that the
+  bundled `knowhere` skill is not filtered out.
+- Large documents time out: increase `pollTimeoutMs` or `uploadTimeoutMs`.
+
+## Developer Docs
+
+Contributor-oriented architecture, workflow, and packaging notes live in
+`DEVELOPMENT.md` at the repository root.

package/dist/__tests__/channel-route.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/ingest-tool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/read-result-file-tool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/tracker-progress.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/channel-delivery.d.ts

@@ -0,0 +1,21 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { ChannelRouteRecord } from "./types";
+type DeliverySurface = "discord" | "imessage" | "line" | "signal" | "slack" | "telegram" | "whatsapp";
+type DeliveryResult = {
+    delivered: boolean;
+    surface?: DeliverySurface;
+    to?: string;
+    accountId?: string;
+};
+export declare function deliverChannelMessage(params: {
+    api: OpenClawPluginApi;
+    operationLabel: string;
+    context?: unknown;
+    sessionKey?: string;
+    messages?: unknown[];
+    channelRoute?: ChannelRouteRecord;
+    text: string;
+    mediaUrl?: string;
+    mediaLocalRoots?: readonly string[];
+}): Promise<DeliveryResult>;
+export {};

package/dist/channel-delivery.js

@@ -0,0 +1,337 @@
+import { isRecord } from "./types.js";
+import { normalizeWhitespace } from "./text.js";
+import { findConversationSegmentValue, parseConversationSessionKey } from "./session.js";
+import fs from "node:fs/promises";
+//#region src/channel-delivery.ts
+const DELIVERY_SURFACES = new Set([
+	"discord",
+	"imessage",
+	"line",
+	"signal",
+	"slack",
+	"telegram",
+	"whatsapp"
+]);
+function readString(value) {
+	return normalizeWhitespace(value) || void 0;
+}
+function readInteger(value) {
+	const normalized = readString(value);
+	if (!normalized || !/^-?\d+$/.test(normalized)) return;
+	const parsed = Number(normalized);
+	return Number.isSafeInteger(parsed) ? parsed : void 0;
+}
+function normalizeDeliverySurface(value) {
+	const normalized = readString(value)?.toLowerCase();
+	if (!normalized || !DELIVERY_SURFACES.has(normalized)) return;
+	return normalized;
+}
+function readThreadValue(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return Math.trunc(value);
+	return readString(value);
+}
+function parseSessionThreadInfo(sessionKey) {
+	const normalized = readString(sessionKey);
+	if (!normalized) return {};
+	const topicIndex = normalized.lastIndexOf(":topic:");
+	const threadIndex = normalized.lastIndexOf(":thread:");
+	const markerIndex = Math.max(topicIndex, threadIndex);
+	if (markerIndex < 0) return { baseSessionKey: normalized };
+	const marker = topicIndex > threadIndex ? ":topic:" : ":thread:";
+	return {
+		baseSessionKey: normalized.slice(0, markerIndex),
+		threadId: normalized.slice(markerIndex + marker.length).trim() || void 0
+	};
+}
+function buildSessionStoreLookupKeys(sessionKey) {
+	const normalized = readString(sessionKey);
+	if (!normalized) return [];
+	const { baseSessionKey } = parseSessionThreadInfo(normalized);
+	const candidates = [
+		normalized,
+		normalized.toLowerCase(),
+		baseSessionKey,
+		baseSessionKey?.toLowerCase()
+	];
+	return [...new Set(candidates.filter((value) => Boolean(value)))];
+}
+function readSessionDelivery(value) {
+	const entry = isRecord(value) ? value : void 0;
+	const deliveryContext = isRecord(entry?.deliveryContext) ? entry.deliveryContext : void 0;
+	const surface = normalizeDeliverySurface(deliveryContext?.channel) || normalizeDeliverySurface(entry?.lastChannel) || normalizeDeliverySurface(entry?.channel);
+	const to = readString(deliveryContext?.to) || readString(entry?.lastTo);
+	const accountId = readString(deliveryContext?.accountId) || readString(entry?.lastAccountId);
+	const threadId = readThreadValue(deliveryContext?.threadId ?? entry?.lastThreadId);
+	if (!surface && !to && !accountId && threadId == null) return;
+	return {
+		surface,
+		to,
+		accountId,
+		threadId
+	};
+}
+async function resolveSessionDelivery(params) {
+	const sessionKey = readString(params.sessionKey);
+	if (!sessionKey) return;
+	try {
+		const parsedSession = parseConversationSessionKey(sessionKey);
+		const storePath = params.api.runtime.channel.session.resolveStorePath(params.api.config.session?.store, { agentId: parsedSession?.agentId });
+		const lookupKeys = buildSessionStoreLookupKeys(sessionKey);
+		params.api.logger.debug?.(`knowhere: ${params.operationLabel} session delivery lookup sessionKey=${sessionKey} storePath=${storePath} lookupKeys=${JSON.stringify(lookupKeys)}`);
+		const rawStore = await fs.readFile(storePath, "utf-8");
+		const store = JSON.parse(rawStore);
+		if (!isRecord(store)) {
+			params.api.logger.debug?.(`knowhere: ${params.operationLabel} session delivery store invalid sessionKey=${sessionKey} storePath=${storePath}`);
+			return;
+		}
+		for (const lookupKey of lookupKeys) {
+			const delivery = readSessionDelivery(store[lookupKey]);
+			if (delivery) {
+				params.api.logger.debug?.(`knowhere: ${params.operationLabel} session delivery resolved sessionKey=${sessionKey} matchedKey=${lookupKey} surface=${delivery.surface ?? "(none)"} to=${delivery.to ?? "(none)"} accountId=${delivery.accountId ?? "(none)"} threadId=${delivery.threadId ?? "(none)"}`);
+				return delivery;
+			}
+		}
+		params.api.logger.debug?.(`knowhere: ${params.operationLabel} session delivery not found sessionKey=${sessionKey} storePath=${storePath}`);
+	} catch (error) {
+		params.api.logger.debug?.(`knowhere: ${params.operationLabel} session delivery lookup failed${sessionKey ? ` sessionKey=${sessionKey}` : ""}. ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function extractReplyReferenceFromValue(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (typeof value === "string") return readString(value.match(/"(?:messageId|message_id|replyTo|reply_to|threadTs|thread_ts|ts)"\s*:\s*"([^"]+)"/)?.[1]);
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return;
+		seen.add(value);
+		for (let index = value.length - 1; index >= 0; index -= 1) {
+			const replyReference = extractReplyReferenceFromValue(value[index], seen);
+			if (replyReference) return replyReference;
+		}
+		return;
+	}
+	if (!isRecord(value)) return;
+	if (seen.has(value)) return;
+	seen.add(value);
+	for (const key of [
+		"messageId",
+		"message_id",
+		"replyTo",
+		"reply_to",
+		"threadTs",
+		"thread_ts",
+		"ts"
+	]) {
+		const replyReference = readString(value[key]);
+		if (replyReference) return replyReference;
+	}
+	const preferredKeys = [
+		"content",
+		"text",
+		"body",
+		"message",
+		"messages",
+		"items"
+	];
+	const preferredKeySet = new Set(preferredKeys);
+	for (const key of preferredKeys) {
+		const replyReference = extractReplyReferenceFromValue(value[key], seen);
+		if (replyReference) return replyReference;
+	}
+	for (const [key, nestedValue] of Object.entries(value).reverse()) {
+		if (preferredKeySet.has(key)) continue;
+		const replyReference = extractReplyReferenceFromValue(nestedValue, seen);
+		if (replyReference) return replyReference;
+	}
+}
+function resolveDeliveryTarget(params) {
+	const context = isRecord(params.context) ? params.context : void 0;
+	const session = parseConversationSessionKey(params.sessionKey);
+	const surface = normalizeDeliverySurface(context?.channelId) || normalizeDeliverySurface(context?.provider) || normalizeDeliverySurface(context?.surface) || normalizeDeliverySurface(params.channelRoute?.channelId) || params.sessionDelivery?.surface || normalizeDeliverySurface(session?.surface);
+	if (!surface) return;
+	const replyReference = readString(context?.messageId) || readString(context?.replyTo) || readString(context?.threadTs) || (params.messages ? extractReplyReferenceFromValue(params.messages) : void 0);
+	switch (surface) {
+		case "discord": {
+			const threadId = readString(context?.threadId) || findConversationSegmentValue(session, "thread") || readString(params.sessionDelivery?.threadId);
+			const channelId = findConversationSegmentValue(session, "channel", "guild");
+			const directId = findConversationSegmentValue(session, "direct", "user", "member");
+			const to = threadId && `channel:${threadId}` || readString(context?.conversationId) || params.channelRoute?.conversationId || params.sessionDelivery?.to || channelId && `channel:${channelId}` || directId && `user:${directId}`;
+			if (!to) return;
+			return {
+				surface,
+				to,
+				accountId: readString(context?.accountId) || findConversationSegmentValue(session, "account") || params.channelRoute?.accountId || params.sessionDelivery?.accountId,
+				replyTo: replyReference
+			};
+		}
+		case "slack": {
+			const directId = findConversationSegmentValue(session, "direct", "user", "member");
+			const channelId = findConversationSegmentValue(session, "channel", "group");
+			const to = readString(context?.conversationId) || params.channelRoute?.conversationId || params.sessionDelivery?.to || channelId || (directId ? `user:${directId}` : void 0);
+			if (!to) return;
+			return {
+				surface,
+				to,
+				accountId: readString(context?.accountId) || findConversationSegmentValue(session, "account") || params.channelRoute?.accountId || params.sessionDelivery?.accountId,
+				threadTs: readString(context?.threadTs) || replyReference || readString(params.sessionDelivery?.threadId)
+			};
+		}
+		case "telegram": {
+			const chatId = findConversationSegmentValue(session, "direct", "group", "channel", "chat", "room");
+			const to = readString(context?.conversationId) || params.channelRoute?.conversationId || params.sessionDelivery?.to || chatId;
+			if (!to) return;
+			return {
+				surface,
+				to,
+				accountId: readString(context?.accountId) || findConversationSegmentValue(session, "account") || params.channelRoute?.accountId || params.sessionDelivery?.accountId,
+				replyToMessageId: readInteger(replyReference),
+				messageThreadId: readInteger(context?.threadId) ?? (typeof params.sessionDelivery?.threadId === "number" ? params.sessionDelivery.threadId : readInteger(params.sessionDelivery?.threadId))
+			};
+		}
+		case "line": {
+			const directId = findConversationSegmentValue(session, "direct", "user", "member");
+			const groupId = findConversationSegmentValue(session, "group");
+			const roomId = findConversationSegmentValue(session, "room");
+			const chatId = findConversationSegmentValue(session, "channel", "chat", "space");
+			const to = readString(context?.conversationId) || params.channelRoute?.conversationId || params.sessionDelivery?.to || (groupId ? `line:group:${groupId}` : void 0) || (roomId ? `line:room:${roomId}` : void 0) || (directId ? `line:${directId}` : void 0) || (chatId ? `line:${chatId}` : void 0);
+			if (!to) return;
+			return {
+				surface,
+				to,
+				accountId: readString(context?.accountId) || findConversationSegmentValue(session, "account") || params.channelRoute?.accountId || params.sessionDelivery?.accountId,
+				replyToken: readString(context?.replyToken)
+			};
+		}
+		case "imessage":
+		case "signal":
+		case "whatsapp": {
+			const conversationId = findConversationSegmentValue(session, "direct", "group", "channel", "chat", "room");
+			const to = readString(context?.conversationId) || params.channelRoute?.conversationId || params.sessionDelivery?.to || conversationId;
+			if (!to) return;
+			return {
+				surface,
+				to,
+				accountId: readString(context?.accountId) || findConversationSegmentValue(session, "account") || params.channelRoute?.accountId || params.sessionDelivery?.accountId
+			};
+		}
+	}
+}
+function hasDeliveryResolutionHints(params) {
+	const context = isRecord(params.context) ? params.context : void 0;
+	if (normalizeDeliverySurface(context?.channelId) || normalizeDeliverySurface(context?.provider) || normalizeDeliverySurface(context?.surface) || normalizeDeliverySurface(params.channelRoute?.channelId) || parseConversationSessionKey(params.sessionKey)) return true;
+	return Boolean(readString(context?.conversationId) || readString(context?.threadId) || readString(context?.groupId) || readString(context?.messageId) || readString(context?.replyTo) || readString(context?.threadTs) || params.channelRoute?.conversationId);
+}
+function canSendMediaDirectly(target, mediaUrl) {
+	if (target.surface !== "line") return true;
+	return /^https?:\/\//i.test(mediaUrl.trim());
+}
+async function deliverChannelMessage(params) {
+	const sessionDelivery = await resolveSessionDelivery({
+		api: params.api,
+		sessionKey: params.sessionKey,
+		operationLabel: params.operationLabel
+	});
+	const target = resolveDeliveryTarget({
+		context: params.context,
+		sessionKey: params.sessionKey,
+		messages: params.messages,
+		channelRoute: params.channelRoute,
+		sessionDelivery
+	});
+	params.api.logger.debug?.(`knowhere: ${params.operationLabel} resolution sessionKey=${readString(params.sessionKey) ?? "(none)"} routeAccountId=${params.channelRoute?.accountId ?? "(none)"} routeConversationId=${params.channelRoute?.conversationId ?? "(none)"} sessionStoreAccountId=${sessionDelivery?.accountId ?? "(none)"} sessionStoreTo=${sessionDelivery?.to ?? "(none)"} resolvedSurface=${target?.surface ?? "(none)"} resolvedTo=${target?.to ?? "(none)"} resolvedAccountId=${target?.accountId ?? "(none)"}`);
+	if (!target) {
+		if (hasDeliveryResolutionHints({
+			context: params.context,
+			sessionKey: params.sessionKey,
+			channelRoute: params.channelRoute
+		})) {
+			const sessionKey = readString(params.sessionKey);
+			params.api.logger.warn(`knowhere: ${params.operationLabel} skipped because no target could be resolved${sessionKey ? ` sessionKey=${sessionKey}` : ""}`);
+		}
+		return { delivered: false };
+	}
+	const mediaUrl = readString(params.mediaUrl);
+	if (mediaUrl && !canSendMediaDirectly(target, mediaUrl)) {
+		params.api.logger.info(`knowhere: ${params.operationLabel} direct media delivery not supported for ${target.surface}; falling back`);
+		return {
+			delivered: false,
+			surface: target.surface,
+			to: target.to,
+			accountId: target.accountId
+		};
+	}
+	try {
+		params.api.logger.info(`knowhere: ${params.operationLabel} sending via ${target.surface} to ${target.to}${target.accountId ? ` accountId=${target.accountId}` : ""}${mediaUrl ? " media=yes" : " media=no"}`);
+		switch (target.surface) {
+			case "discord":
+				await params.api.runtime.channel.discord.sendMessageDiscord(target.to, params.text, {
+					accountId: target.accountId,
+					replyTo: target.replyTo,
+					...mediaUrl ? { mediaUrl } : {},
+					...params.mediaLocalRoots?.length ? { mediaLocalRoots: params.mediaLocalRoots } : {}
+				});
+				break;
+			case "slack":
+				await params.api.runtime.channel.slack.sendMessageSlack(target.to, params.text, {
+					accountId: target.accountId,
+					threadTs: target.threadTs,
+					...mediaUrl ? { mediaUrl } : {},
+					...params.mediaLocalRoots?.length ? { mediaLocalRoots: params.mediaLocalRoots } : {}
+				});
+				break;
+			case "telegram":
+				await params.api.runtime.channel.telegram.sendMessageTelegram(target.to, params.text, {
+					accountId: target.accountId,
+					messageThreadId: target.messageThreadId,
+					replyToMessageId: target.replyToMessageId,
+					...mediaUrl ? { mediaUrl } : {},
+					...params.mediaLocalRoots?.length ? { mediaLocalRoots: params.mediaLocalRoots } : {}
+				});
+				break;
+			case "line":
+				await params.api.runtime.channel.line.sendMessageLine(target.to, params.text, {
+					accountId: target.accountId,
+					replyToken: target.replyToken,
+					verbose: false,
+					...mediaUrl ? { mediaUrl } : {}
+				});
+				break;
+			case "whatsapp":
+				await params.api.runtime.channel.whatsapp.sendMessageWhatsApp(target.to, params.text, {
+					accountId: target.accountId,
+					verbose: false,
+					...mediaUrl ? { mediaUrl } : {},
+					...params.mediaLocalRoots?.length ? { mediaLocalRoots: params.mediaLocalRoots } : {}
+				});
+				break;
+			case "signal":
+				await params.api.runtime.channel.signal.sendMessageSignal(target.to, params.text, {
+					accountId: target.accountId,
+					...mediaUrl ? { mediaUrl } : {},
+					...params.mediaLocalRoots?.length ? { mediaLocalRoots: params.mediaLocalRoots } : {}
+				});
+				break;
+			case "imessage":
+				await params.api.runtime.channel.imessage.sendMessageIMessage(target.to, params.text, {
+					accountId: target.accountId,
+					...mediaUrl ? { mediaUrl } : {},
+					...params.mediaLocalRoots?.length ? { mediaLocalRoots: params.mediaLocalRoots } : {}
+				});
+				break;
+		}
+		params.api.logger.info(`knowhere: ${params.operationLabel} sent via ${target.surface} to ${target.to}${target.accountId ? ` accountId=${target.accountId}` : ""}`);
+		return {
+			delivered: true,
+			surface: target.surface,
+			to: target.to,
+			accountId: target.accountId
+		};
+	} catch (error) {
+		params.api.logger.warn(`knowhere: ${params.operationLabel} send failed via ${target.surface} to ${target.to}${target.accountId ? ` accountId=${target.accountId}` : ""}. ${error instanceof Error ? error.message : String(error)}`);
+		return {
+			delivered: false,
+			surface: target.surface,
+			to: target.to,
+			accountId: target.accountId
+		};
+	}
+}
+//#endregion
+export { deliverChannelMessage };

package/dist/config.d.ts

@@ -3,4 +3,10 @@ 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 const API_KEY_URL = "https://knowhereto.ai/api-keys";
+export declare const PURCHASE_CREDITS_URL = "https://knowhereto.ai/usage?buy=true";
 export declare function assertKnowhereApiKey(config: ResolvedKnowhereConfig): void;
+export declare function isPaymentRequiredError(error: unknown): boolean;
+export declare function formatPaymentRequiredMessage(): string;
+export declare function readPersistedApiKey(storageDir: string): Promise<string | null>;
+export declare function persistApiKey(storageDir: string, apiKey: string): Promise<void>;