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

package/dist/tracker-progress.d.ts

@@ -0,0 +1,8 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+export declare function sendTrackerProgress(params: {
+    api: OpenClawPluginApi;
+    context?: unknown;
+    sessionKey?: string;
+    messages?: unknown[];
+    text: string;
+}): Promise<void>;

package/dist/tracker-progress.js

@@ -0,0 +1,197 @@
+import { isRecord } from "./types.js";
+import { normalizeWhitespace } from "./text.js";
+import { findConversationSegmentValue, parseConversationSessionKey } from "./session.js";
+//#region src/tracker-progress.ts
+const TRACKER_PROGRESS_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 normalizeTrackerProgressSurface(value) {
+	const normalized = readString(value)?.toLowerCase();
+	if (!normalized || !TRACKER_PROGRESS_SURFACES.has(normalized)) return;
+	return normalized;
+}
+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 resolveTrackerProgressTarget(params) {
+	const context = isRecord(params.context) ? params.context : void 0;
+	const session = parseConversationSessionKey(params.sessionKey);
+	const surface = normalizeTrackerProgressSurface(context?.channelId) || normalizeTrackerProgressSurface(context?.provider) || normalizeTrackerProgressSurface(context?.surface) || normalizeTrackerProgressSurface(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");
+			const channelId = findConversationSegmentValue(session, "channel", "guild");
+			const directId = findConversationSegmentValue(session, "direct", "user", "member");
+			const to = threadId && `channel:${threadId}` || readString(context?.conversationId) || channelId && `channel:${channelId}` || directId && `user:${directId}`;
+			if (!to) return;
+			return {
+				surface,
+				to,
+				accountId: "tracker",
+				replyTo: replyReference
+			};
+		}
+		case "slack": {
+			const directId = findConversationSegmentValue(session, "direct", "user", "member");
+			const channelId = findConversationSegmentValue(session, "channel", "group");
+			const to = readString(context?.conversationId) || channelId || (directId ? `user:${directId}` : void 0);
+			if (!to) return;
+			return {
+				surface,
+				to,
+				accountId: readString(context?.accountId),
+				threadTs: readString(context?.threadTs) || replyReference
+			};
+		}
+		case "telegram": {
+			const chatId = findConversationSegmentValue(session, "direct", "group", "channel", "chat", "room");
+			const to = readString(context?.conversationId) || chatId;
+			if (!to) return;
+			return {
+				surface,
+				to,
+				accountId: readString(context?.accountId),
+				replyToMessageId: readInteger(replyReference),
+				messageThreadId: readInteger(context?.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) || (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),
+				replyToken: readString(context?.replyToken)
+			};
+		}
+		case "imessage":
+		case "signal":
+		case "whatsapp": {
+			const conversationId = findConversationSegmentValue(session, "direct", "group", "channel", "chat", "room");
+			const to = readString(context?.conversationId) || conversationId;
+			if (!to) return;
+			return {
+				surface,
+				to,
+				accountId: readString(context?.accountId)
+			};
+		}
+	}
+}
+async function sendTrackerProgress(params) {
+	const target = resolveTrackerProgressTarget({
+		context: params.context,
+		sessionKey: params.sessionKey,
+		messages: params.messages
+	});
+	if (!target) return;
+	try {
+		switch (target.surface) {
+			case "discord":
+				await params.api.runtime.channel.discord.sendMessageDiscord(target.to, params.text, {
+					accountId: target.accountId,
+					replyTo: target.replyTo
+				});
+				break;
+			case "slack":
+				await params.api.runtime.channel.slack.sendMessageSlack(target.to, params.text, {
+					accountId: target.accountId,
+					threadTs: target.threadTs
+				});
+				break;
+			case "telegram":
+				await params.api.runtime.channel.telegram.sendMessageTelegram(target.to, params.text, {
+					accountId: target.accountId,
+					messageThreadId: target.messageThreadId,
+					replyToMessageId: target.replyToMessageId
+				});
+				break;
+			case "line":
+				await params.api.runtime.channel.line.sendMessageLine(target.to, params.text, {
+					accountId: target.accountId,
+					replyToken: target.replyToken
+				});
+				break;
+			case "whatsapp":
+				await params.api.runtime.channel.whatsapp.sendMessageWhatsApp(target.to, params.text, {
+					accountId: target.accountId,
+					verbose: false
+				});
+				break;
+			case "signal":
+				await params.api.runtime.channel.signal.sendMessageSignal(target.to, params.text, { accountId: target.accountId });
+				break;
+			case "imessage":
+				await params.api.runtime.channel.imessage.sendMessageIMessage(target.to, params.text, { accountId: target.accountId });
+				break;
+		}
+	} catch (error) {
+		params.api.logger.warn(`knowhere: tracker progress send failed. ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+//#endregion
+export { sendTrackerProgress };

package/dist/types.d.ts

@@ -0,0 +1,247 @@
+export type ScopeMode = "session" | "agent" | "global";
+export type StringRecord = Record<string, unknown>;
+export interface PluginLogger {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+export interface ToolRuntimeContext {
+    workspaceDir?: string;
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+}
+export interface ResolvedKnowhereConfig {
+    apiKey: string;
+    baseUrl: string;
+    storageDir: string;
+    scopeMode: ScopeMode;
+    autoGrounding: boolean;
+    maxContextChars: number;
+    pollIntervalMs: number;
+    pollTimeoutMs: number;
+    requestTimeoutMs: number;
+    uploadTimeoutMs: number;
+}
+export interface KnowhereStatistics {
+    total_chunks?: number;
+    text_chunks?: number;
+    image_chunks?: number;
+    table_chunks?: number;
+    total_pages?: number;
+}
+export interface KnowhereChecksum {
+    algorithm?: string;
+    value?: string;
+}
+export interface KnowhereManifest {
+    version?: string;
+    job_id?: string;
+    data_id?: string;
+    source_file_name?: string;
+    processing_date?: string;
+    checksum?: KnowhereChecksum;
+    statistics?: KnowhereStatistics;
+    files?: StringRecord;
+}
+export interface StoredChunk {
+    chunkId: string;
+    type: "text" | "image" | "table";
+    path: string | null;
+    summary: string;
+    content: string;
+    tokens: number | null;
+    keywords: string[];
+    relationships: unknown[];
+    metadata: StringRecord;
+    assetFilePath: string | null;
+    originalName: string | null;
+    tableType: string | null;
+}
+export interface StoredPathRecord {
+    path: string;
+    parentPath: string | null;
+    depth: number;
+    childPaths: string[];
+    chunkIds: string[];
+    directChunkCount: number;
+    chunkCount: number;
+    textChunkCount: number;
+    imageChunkCount: number;
+    tableChunkCount: number;
+}
+export type StoredResultFileKind = "manifest" | "chunks" | "fullMarkdown" | "kbCsv" | "hierarchy" | "hierarchyView" | "image" | "table" | "other";
+export interface StoredResultFileRecord {
+    relativePath: string;
+    kind: StoredResultFileKind;
+    chunkId: string | null;
+    format: string | null;
+    sizeBytes: number | null;
+}
+export interface StoredBrowseIndex {
+    version: number;
+    paths: StoredPathRecord[];
+    chunkOrder: string[];
+    resultFiles: StoredResultFileRecord[];
+}
+export interface KnowhereParseResult {
+    manifest: KnowhereManifest;
+    chunks: StoredChunk[];
+    fullMarkdown: string;
+    hierarchy: unknown;
+    browseIndex: StoredBrowseIndex;
+}
+export interface KnowhereDownloadedResult {
+    zipBytes: Buffer;
+    rawZipSha1: string;
+}
+export interface KnowhereJob {
+    job_id: string;
+    status: string;
+    source_type: string;
+    data_id?: string | null;
+    created_at?: string | null;
+    upload_url?: string | null;
+    upload_headers?: Record<string, string> | null;
+    expires_in?: number | null;
+}
+export interface KnowhereJobError {
+    code?: string;
+    message?: string;
+    request_id?: string;
+    details?: unknown;
+}
+export interface KnowhereJobResult {
+    job_id: string;
+    status: string;
+    source_type: string;
+    data_id?: string | null;
+    created_at?: string | null;
+    progress?: unknown;
+    error?: KnowhereJobError | null;
+    result?: StringRecord | null;
+    result_url?: string | null;
+    result_url_expires_at?: string | null;
+    file_name?: string | null;
+    file_extension?: string | null;
+    model?: string | null;
+    ocr_enabled?: boolean | null;
+    duration_seconds?: number | null;
+    credits_spent?: number | null;
+}
+export interface KnowhereJobList {
+    jobs: KnowhereJobResult[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+export interface KnowhereJobListRequest {
+    page?: number;
+    pageSize?: number;
+    jobStatus?: string;
+    jobType?: string;
+    recentDays?: 1 | 7 | 30;
+    startTime?: string;
+    endTime?: string;
+}
+export interface KnowhereParsingParams {
+    model?: "base" | "advanced";
+    ocr_enabled?: boolean;
+    kb_dir?: string;
+    doc_type?: string;
+    smart_title_parse?: boolean;
+    summary_image?: boolean;
+    summary_table?: boolean;
+    summary_txt?: boolean;
+    add_frag_desc?: string;
+}
+export interface KnowhereIngestRequest {
+    filePath?: string;
+    fileName?: string;
+    url?: string;
+    dataId?: string;
+    parsingParams?: KnowhereParsingParams;
+    onJobCreated?: (job: KnowhereJob) => void | Promise<void>;
+    onJobUpdated?: (jobResult: KnowhereJobResult) => void | Promise<void>;
+}
+export interface KnowhereIngestResult {
+    job: KnowhereJob;
+    jobResult: KnowhereJobResult;
+    downloadedResult: KnowhereDownloadedResult;
+}
+export interface KnowhereScope {
+    mode: ScopeMode | "global";
+    key: string;
+    label: string;
+    rootDir: string;
+    documentsDir: string;
+    indexPath: string;
+}
+export interface KnowhereAutoGroundingController {
+    forgetDocument(scope: KnowhereScope, docId: string): void;
+    forgetScope(scope: KnowhereScope): void;
+}
+export interface StoredDocumentRecord {
+    id: string;
+    title: string;
+    sourceType: "file" | "url";
+    source: string;
+    sourceLabel: string;
+    fileName: string | null;
+    originalFileName: string | null;
+    dataId: string | null;
+    jobId: string | null;
+    checksum: string | null;
+    resultUrl: string | null;
+    resultUrlExpiresAt: string | null;
+    scopeLabel: string;
+    tags: string[];
+    ingestedAt: string;
+    updatedAt: string;
+    chunkCount: number;
+    statistics: KnowhereStatistics;
+}
+export interface StoredDocumentPayload {
+    version: number;
+    document: StoredDocumentRecord;
+    manifest: KnowhereManifest;
+    jobResult: KnowhereJobResult;
+    fullMarkdown: string;
+    hierarchy: unknown;
+    browseIndex: StoredBrowseIndex;
+    rawZipSha1: string;
+    chunks: StoredChunk[];
+}
+export interface StoredDocumentMetadata {
+    version: number;
+    document: StoredDocumentRecord;
+    jobResult: KnowhereJobResult;
+    rawZipSha1: string;
+}
+export interface KnowhereIndex {
+    version: number;
+    scopeMode: string;
+    scopeKey: string;
+    updatedAt: string | null;
+    documents: StoredDocumentRecord[];
+}
+export interface SaveStoredDocumentPayload {
+    sourceType: "file" | "url";
+    source: string;
+    sourceLabel?: string;
+    fileName: string | null;
+    docId?: string;
+    title?: string;
+    dataId?: string;
+    tags: string[];
+    job: KnowhereJob;
+    jobResult: KnowhereJobResult;
+    downloadedResult: KnowhereDownloadedResult;
+}
+export interface JsonSchemaObject {
+    [key: string]: unknown;
+}
+export declare function isRecord(value: unknown): value is StringRecord;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;

package/dist/types.js

@@ -0,0 +1,9 @@
+//#region src/types.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeError(error) {
+	return error instanceof Error;
+}
+//#endregion
+export { isNodeError, isRecord };

package/openclaw.plugin.json

@@ -0,0 +1,107 @@
+{
+  "id": "knowhere",
+  "name": "Knowhere",
+  "description": "Parse documents with Knowhere and expose the stored result as tool-queryable document state for OpenClaw agents.",
+  "skills": ["./skills"],
+  "version": "0.1.0-beta.0",
+  "uiHints": {
+    "apiKey": {
+      "label": "Knowhere API Key",
+      "help": "Optional when KNOWHERE_API_KEY is already present in the environment.",
+      "sensitive": true
+    },
+    "baseUrl": {
+      "label": "Knowhere Base URL",
+      "help": "Override the Knowhere API base URL when using a non-default deployment."
+    },
+    "storageDir": {
+      "label": "Storage Directory",
+      "help": "Directory for persisted parsed documents and scope indexes."
+    },
+    "scopeMode": {
+      "label": "Document Scope",
+      "help": "Choose whether ingested documents are isolated per session, shared per agent, or global."
+    },
+    "autoGrounding": {
+      "label": "Auto Grounding",
+      "help": "Automatically ingest attachments and inject compact Knowhere document availability/status guidance before prompt construction."
+    },
+    "maxContextChars": {
+      "label": "Grounding Context Limit",
+      "help": "Maximum characters injected into the prompt for Knowhere document handle/status context."
+    },
+    "pollIntervalMs": {
+      "label": "Poll Interval",
+      "help": "Polling interval in milliseconds while waiting for Knowhere jobs to finish."
+    },
+    "pollTimeoutMs": {
+      "label": "Poll Timeout",
+      "help": "Maximum time to wait for a Knowhere job to finish."
+    },
+    "requestTimeoutMs": {
+      "label": "Request Timeout",
+      "help": "Timeout for regular Knowhere API requests."
+    },
+    "uploadTimeoutMs": {
+      "label": "Upload Timeout",
+      "help": "Timeout for result downloads and file uploads."
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "minLength": 1
+      },
+      "baseUrl": {
+        "type": "string",
+        "format": "uri",
+        "default": "https://api.knowhereto.ai"
+      },
+      "storageDir": {
+        "type": "string"
+      },
+      "scopeMode": {
+        "type": "string",
+        "enum": ["session", "agent", "global"],
+        "default": "session"
+      },
+      "autoGrounding": {
+        "type": "boolean",
+        "default": true
+      },
+      "maxContextChars": {
+        "type": "integer",
+        "minimum": 500,
+        "maximum": 12000,
+        "default": 4000
+      },
+      "pollIntervalMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 60000,
+        "default": 10000
+      },
+      "pollTimeoutMs": {
+        "type": "integer",
+        "minimum": 10000,
+        "maximum": 7200000,
+        "default": 1800000
+      },
+      "requestTimeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 300000,
+        "default": 60000
+      },
+      "uploadTimeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 7200000,
+        "default": 600000
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ontos-ai/knowhere-claw",
+  "version": "0.1.0-beta.0",
+  "description": "OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.",
+  "files": [
+    "dist/",
+    "skills/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rolldown -c && tsc -p tsconfig.build.json",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint --type-aware",
+    "lint:fix": "oxlint --type-aware --fix",
+    "smoke:tools": "vite-node --mode smoke ./smoketest/run-tool.ts",
+    "tsgo": "tsgo --noEmit -p tsconfig.json",
+    "typecheck": "pnpm tsgo",
+    "clean": "rm -rf dist",
+    "check:plugin-version": "node ./scripts/release-guard.mjs plugin-version",
+    "check:beta-version": "node ./scripts/release-guard.mjs beta-version",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "@knowhere-ai/sdk": "^0.1.1",
+    "fflate": "^0.8.2"
+  },
+  "devDependencies": {
+    "@tsconfig/node22": "^22.0.5",
+    "@types/node": "^25.3.5",
+    "@typescript/native-preview": "7.0.0-dev.20260307.1",
+    "oxfmt": "0.38.0",
+    "oxlint": "^1.51.0",
+    "oxlint-tsgolint": "^0.16.0",
+    "rolldown": "^1.0.0-rc.8",
+    "typescript": "^5.9.3",
+    "vite-node": "5.2.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.8"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "pnpm@10.23.0",
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  }
+}