@ontos-ai/knowhere-claw 0.2.0 → 0.2.1

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__/kg-service-test-helper.d.ts

@@ -0,0 +1,2 @@
+import type { KnowledgeGraphService } from "../kg-service";
+export declare function createKgServiceStub(): KnowledgeGraphService;

package/dist/__tests__/kg-service.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/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/config.d.ts

@@ -0,0 +1,13 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { JsonSchemaObject, ResolvedKnowhereConfig, StringRecord, KnowledgeGraphConfig } 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>;
+export declare function resolveKnowledgeGraphConfig(raw: StringRecord): KnowledgeGraphConfig;

package/dist/connect-builder.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Connection Builder Module
+ *
+ * TypeScript implementation of knowhere-api/apps/worker/app/services/connect_builder/builder.py
+ * Builds connections between chunks based on keyword overlap and content similarity.
+ */
+import type { PluginLogger } from "./types";
+/**
+ * Chunk data structure for building connections
+ */
+export interface ChunkData {
+    chunk_id: string;
+    path: string;
+    content: string;
+    metadata: {
+        keywords?: string[];
+        tokens?: string[];
+        summary?: string;
+        length?: number;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Connection result between two chunks
+ */
+export interface Connection {
+    source: string;
+    target: string;
+    relation: string;
+    score: number;
+    sharedKeywords: string[];
+}
+/**
+ * Configuration for connection building
+ */
+export interface ConnectBuilderConfig {
+    minKeywordOverlap: number;
+    keywordScoreWeight: number;
+    maxConnectionsPerChunk: number;
+    minScoreThreshold: number;
+    crossFileOnly: boolean;
+    maxContentOverlap: number;
+}
+/**
+ * Main function to build connections between chunks
+ * Equivalent to Python: build_connections
+ */
+export declare function buildConnections(chunks: ChunkData[], config: ConnectBuilderConfig, logger?: PluginLogger): Connection[];

package/dist/connect-builder.js

@@ -120,7 +120,6 @@ function buildConnections(chunks, config, logger) {
 		const sourceChunk = chunkById.get(sourceId);
 		if (!sourceChunk) continue;
 		const sourceKeywords = getKeywords(sourceChunk);
-		sourceKeywords.map(normalizeKeyword);
 		const sourceFileKey = extractFileKey(sourceChunk.path);
 		for (const targetId of targetIds) {
 			const targetChunk = chunkById.get(targetId);
@@ -165,7 +164,7 @@ function buildConnections(chunks, config, logger) {
 			connectionsByChunk.get(conn.target).push(conn);
 		}
 		const kept = /* @__PURE__ */ new Set();
-		for (const [chunkId, conns] of connectionsByChunk) {
+		for (const [, conns] of connectionsByChunk) {
 			const topN = conns.sort((a, b) => b.score - a.score).slice(0, config.maxConnectionsPerChunk);
 			for (const conn of topN) kept.add(conn);
 		}

package/dist/error-message.d.ts

@@ -0,0 +1 @@
+export declare function formatErrorMessage(error: unknown): string;

package/dist/graph-builder.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Graph Builder Module
+ *
+ * TypeScript implementation of knowhere-api/apps/worker/app/services/connect_builder/graph_builder.py
+ * Builds file-level knowledge graphs from chunk connections with TF-IDF and importance scoring.
+ */
+import type { ChunkData, Connection } from "./connect-builder";
+import type { PluginLogger } from "./types";
+/**
+ * File-level edge in the knowledge graph
+ */
+interface FileEdge {
+    source: string;
+    target: string;
+    connection_count: number;
+    avg_score: number;
+    top_connections: Array<{
+        source_chunk: string;
+        source_id: string;
+        target_chunk: string;
+        target_id: string;
+        relation: string;
+        score: number;
+    }>;
+}
+/**
+ * File metadata in the knowledge graph
+ */
+interface FileMetadata {
+    chunks_count: number;
+    types: Record<string, number>;
+    top_keywords: string[];
+    top_summary: string;
+    importance: number;
+}
+/**
+ * Complete knowledge graph structure
+ */
+export interface KnowledgeGraph {
+    version: string;
+    stats: {
+        total_files: number;
+        total_chunks: number;
+        total_cross_file_edges: number;
+    };
+    files: Record<string, FileMetadata>;
+    edges: FileEdge[];
+}
+/**
+ * Chunk statistics for usage tracking
+ */
+export interface ChunkStats {
+    [chunkId: string]: {
+        hit_count: number;
+        last_accessed?: string;
+    };
+}
+/**
+ * Main function to build knowledge graph
+ * Equivalent to Python: build_knowledge_graph
+ */
+export declare function buildKnowledgeGraph(chunks: ChunkData[], connections: Connection[], chunkStats: ChunkStats, jiebaInitialized: boolean, logger?: PluginLogger): KnowledgeGraph;
+/**
+ * Incremental update: match new chunks against existing chunks
+ * Equivalent to Python: _incremental_connections
+ */
+export declare function incrementalConnections(newChunks: ChunkData[], existingChunks: ChunkData[], config: {
+    minKeywordOverlap: number;
+    keywordScoreWeight: number;
+    maxConnectionsPerChunk: number;
+    minScoreThreshold: number;
+    crossFileOnly: boolean;
+    maxContentOverlap: number;
+}, logger?: PluginLogger): Connection[];
+export {};

package/dist/graph-builder.js

@@ -31,7 +31,7 @@ function extractTokensFromContent(content, jiebaInitialized) {
 			if (/^[^\w\u4e00-\u9fa5]+$/.test(token)) return false;
 			return true;
 		});
-	} catch (error) {
+	} catch {
 		return cleanContent.split(/\s+/).filter((w) => w.length > 1);
 	}
 }

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("./types").JsonSchemaObject;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;

package/dist/kg-service.d.ts

@@ -0,0 +1,38 @@
+import type { KnowledgeGraphConfig, PluginLogger, ToolRuntimeContext, KbMetadata, KnowledgeGraph, FileEdge } from "./types";
+export interface KnowledgeGraphServiceParams {
+    config: KnowledgeGraphConfig;
+    logger: PluginLogger;
+}
+type DegradationMode = "full" | "basic" | "disabled";
+export declare class KnowledgeGraphService {
+    private readonly config;
+    private readonly logger;
+    private degradationMode;
+    private buildQueues;
+    private jiebaInitialized;
+    constructor(params: KnowledgeGraphServiceParams);
+    initialize(): Promise<void>;
+    private checkPythonEnvironment;
+    private initializeJieba;
+    extractKeywords(text: string, topK?: number): Promise<string[]>;
+    resolveKbId(context: ToolRuntimeContext): string | null;
+    getKbPath(kbId: string): string;
+    ensureKbDirectory(kbId: string): Promise<string>;
+    saveDocumentToKb(params: {
+        kbId: string;
+        docId: string;
+        sourcePath: string;
+        keywords: string[];
+        metadata: Record<string, unknown>;
+    }): Promise<void>;
+    scheduleBuild(kbId: string, task: () => Promise<void>): Promise<void>;
+    buildKnowledgeGraph(kbId: string): Promise<void>;
+    private updateKbMetadata;
+    queryGraph(kbId: string, fileKey?: string): Promise<FileEdge[]>;
+    getKnowledgeGraph(kbId: string): Promise<KnowledgeGraph | null>;
+    listKnowledgeBases(): Promise<string[]>;
+    getKbMetadata(kbId: string): Promise<KbMetadata | null>;
+    isEnabled(): boolean;
+    getDegradationMode(): DegradationMode;
+}
+export {};

package/dist/kg-service.js

@@ -25,6 +25,15 @@ const DEFAULT_KG_CONFIG = {
 	buildTimeout: 3e5,
 	notifyOnGraphFailure: false
 };
+function formatUnknownError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function extractKeywordText(item) {
+	if (typeof item === "string") return item;
+	if (typeof item === "number" || typeof item === "boolean" || typeof item === "bigint") return String(item);
+	if (typeof item === "object" && item !== null && "word" in item && typeof item.word === "string") return item.word;
+	return null;
+}
 var KnowledgeGraphService = class {
 	config;
 	logger;
@@ -68,7 +77,7 @@ var KnowledgeGraphService = class {
 	async checkPythonEnvironment() {
 		return new Promise((resolve, reject) => {
 			const python = spawn("python3", ["--version"]);
-			python.on("error", (err) => {
+			python.on("error", () => {
 				const error = /* @__PURE__ */ new Error("Python3 not found in PATH");
 				error.code = "PYTHON_MISSING";
 				reject(error);
@@ -90,7 +99,7 @@ var KnowledgeGraphService = class {
 			import_nodejieba.load();
 			this.jiebaInitialized = true;
 			this.logger.info("Nodejieba initialized successfully");
-		} catch (error) {
+		} catch {
 			const err = /* @__PURE__ */ new Error("Failed to initialize nodejieba");
 			err.code = "NODEJIEBA_MISSING";
 			throw err;
@@ -100,13 +109,13 @@ var KnowledgeGraphService = class {
 		if (this.degradationMode === "disabled") return [];
 		if (this.degradationMode === "full" && this.jiebaInitialized) try {
 			const rawKeywords = import_nodejieba.extract(text, topK);
-			return (Array.isArray(rawKeywords) ? rawKeywords : []).map((item) => typeof item === "string" ? item : String(item.word || item)).filter((kw) => {
+			return (Array.isArray(rawKeywords) ? rawKeywords : []).map((item) => extractKeywordText(item)).filter((keyword) => keyword !== null).filter((kw) => {
 				if (kw.length <= 1) return false;
 				if (/^\d+$/.test(kw)) return false;
 				return true;
 			}).slice(0, topK);
 		} catch (error) {
-			this.logger.warn(`Jieba extraction failed, falling back to basic: ${error}`);
+			this.logger.warn(`Jieba extraction failed, falling back to basic: ${formatUnknownError(error)}`);
 			this.degradationMode = "basic";
 		}
 		return text.split(/\s+/).filter((w) => w.length > 1).slice(0, topK);
@@ -202,7 +211,7 @@ var KnowledgeGraphService = class {
 			});
 			this.logger.info(`Knowledge graph built successfully for kb=${kbId}`);
 		} catch (error) {
-			this.logger.error(`Failed to build knowledge graph: ${error}`);
+			this.logger.error(`Failed to build knowledge graph: ${formatUnknownError(error)}`);
 			throw error;
 		}
 	}

package/dist/parser.d.ts

@@ -0,0 +1,16 @@
+import type { KnowhereDownloadedResult, KnowhereManifest, KnowhereParseResult, KnowhereStatistics, StoredBrowseIndex, StoredChunk } from "./types";
+type KnowhereStoredResultSummary = {
+    manifest: KnowhereManifest;
+    chunkCount: number;
+    statistics: KnowhereStatistics;
+};
+export declare const STORED_BROWSE_INDEX_VERSION = 2;
+export declare function resolveResultEntryPath(rootDir: string, entryPath: string): string;
+export declare function buildStoredPathPrefixes(storedPath: string): string[];
+export declare function isStoredBrowseIndex(value: unknown): value is StoredBrowseIndex;
+export declare function buildStoredBrowseIndex(resultDir: string, manifest: KnowhereManifest, chunks: StoredChunk[]): Promise<StoredBrowseIndex>;
+export declare function extractKnowhereResultArchive(downloadedResult: KnowhereDownloadedResult, targetDir: string): Promise<void>;
+export declare function readStoredKnowhereResultSummary(resultDir: string): Promise<KnowhereStoredResultSummary>;
+export declare function readStoredKnowhereResultContent(resultDir: string): Promise<Omit<KnowhereParseResult, "browseIndex">>;
+export declare function readStoredKnowhereParseResult(resultDir: string): Promise<KnowhereParseResult>;
+export {};

package/dist/session.d.ts

@@ -0,0 +1,11 @@
+export type ParsedConversationSessionKey = {
+    agentId: string;
+    surface: string;
+    remainder: string;
+    segments: string[];
+};
+export declare function parseConversationSessionKey(sessionKey: string | undefined): ParsedConversationSessionKey | undefined;
+export declare function normalizeConversationScopeKey(sessionKey: string | undefined): string | undefined;
+export declare function resolveSharedConversationScopeKey(sessionKey: string | undefined): string | undefined;
+export declare function findConversationSegmentValue(session: ParsedConversationSessionKey | undefined, ...keys: string[]): string | undefined;
+export declare function deriveMessageContextScopeKey(context: unknown): string | undefined;

package/dist/store.d.ts

@@ -0,0 +1,79 @@
+import type { ChannelRouteRecord, KnowhereScope, PluginLogger, SaveStoredDocumentPayload, ScopeMode, StoredDocumentPayload, StoredDocumentRecord } from "./types";
+export declare class KnowhereStore {
+    private readonly rootDir;
+    private readonly scopeMode;
+    private readonly logger;
+    private readonly indexCache;
+    private readonly documentPayloadCache;
+    private readonly scopeAccessChains;
+    private readonly scopeKeyAliases;
+    private readonly sessionScopeKeysBySessionId;
+    private readonly sessionScopeKeysBySessionKey;
+    private readonly channelRoutes;
+    private routesLoaded;
+    constructor(params: {
+        rootDir: string;
+        scopeMode: ScopeMode;
+        logger: PluginLogger;
+    });
+    registerScopeAlias(context: {
+        scopeKey: string;
+        sessionKey?: string;
+        sessionId?: string;
+    }): string;
+    registerMessageScope(context: {
+        sessionKey?: string;
+        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;
+        requesterSessionKey?: string;
+        requesterSessionId?: string;
+    }): string | undefined;
+    resolveScope(context?: {
+        agentId?: string;
+        sessionKey?: string;
+        sessionId?: string;
+    }): 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;
+        text: string | null;
+    } | null>;
+    saveDownloadedDocument(scope: KnowhereScope, payload: SaveStoredDocumentPayload, options?: {
+        overwrite?: boolean;
+    }): Promise<StoredDocumentRecord>;
+    removeDocument(scope: KnowhereScope, docId: string): Promise<StoredDocumentRecord | null>;
+    clearScope(scope: KnowhereScope): Promise<StoredDocumentRecord[]>;
+    private getIndex;
+    private persistIndex;
+    private runWithScopeAccessLock;
+    private removeDocumentArtifacts;
+    private buildDocumentPayloadCacheKey;
+    private touchDocumentPayloadCache;
+    private deleteDocumentPayloadCache;
+    private deleteScopeDocumentPayloadCaches;
+    private loadOrBuildBrowseIndex;
+    private buildRouteKey;
+    private ensureRoutesLoaded;
+    private persistRoutes;
+    private resolveCanonicalScopeKey;
+    private resolveKnownScopeKey;
+    private rebuildIndex;
+}

package/dist/text.d.ts

@@ -0,0 +1,10 @@
+export declare function normalizeWhitespace(value: unknown): string;
+export declare function truncateText(value: unknown, maxChars: number): string;
+export declare function slugify(value: unknown, fallback?: string): string;
+export declare function hashString(value: string): string;
+export declare function sanitizeStringArray(value: unknown): string[];
+export declare function toComparableText(value: unknown): string;
+export declare function stripHtmlTags(text: string): string;
+export declare function stripLatex(text: string): string;
+export declare function normalizeUnicode(text: string): string;
+export declare function normalizeForGrep(text: string): string;

package/dist/tools.d.ts

@@ -0,0 +1,10 @@
+import { type AnyAgentTool, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { KnowhereStore } from "./store";
+import type { KnowledgeGraphService } from "./kg-service";
+import type { ResolvedKnowhereConfig, ToolRuntimeContext } from "./types";
+export declare function createKnowhereToolFactory(params: {
+    api: OpenClawPluginApi;
+    config: ResolvedKnowhereConfig;
+    store: KnowhereStore;
+    kgService: KnowledgeGraphService;
+}): (ctx: ToolRuntimeContext) => AnyAgentTool[];

package/dist/tracker-progress.d.ts

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

package/dist/types.d.ts

@@ -0,0 +1,320 @@
+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;
+    accountId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+}
+export interface ResolvedKnowhereConfig {
+    apiKey: string;
+    baseUrl: string;
+    storageDir: string;
+    scopeMode: ScopeMode;
+    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 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 interface ChannelRouteRecord {
+    readonly channelId: string;
+    readonly accountId: string;
+    readonly conversationId?: string;
+    readonly updatedAt: string;
+}
+export declare function isRecord(value: unknown): value is StringRecord;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;
+export type KbIdSource = "disabled" | "agent" | "agent-session" | "global";
+export interface KnowledgeGraphConnectConfig {
+    minKeywordOverlap: number;
+    keywordScoreWeight: number;
+    maxConnectionsPerChunk: number;
+    minScoreThreshold: number;
+    crossFileOnly: boolean;
+    maxContentOverlap: number;
+}
+export interface KnowledgeGraphConfig {
+    enableKnowledgeGraph: boolean;
+    kbId?: string;
+    kbIdSource?: KbIdSource;
+    concurrentBuildStrategy?: "queue" | "skip";
+    buildTimeout?: number;
+    notifyOnGraphFailure?: boolean;
+    connectConfig?: Partial<KnowledgeGraphConnectConfig>;
+}
+export interface GraphConnection {
+    source: string;
+    target: string;
+    score: number;
+    sharedKeywords: string[];
+    connectionType: string;
+}
+/**
+ * File-level edge in knowledge graph (matches SKILL.md schema)
+ */
+export interface FileEdge {
+    source: string;
+    target: string;
+    connection_count: number;
+    avg_score: number;
+    top_connections: Array<{
+        source_chunk: string;
+        source_id: string;
+        target_chunk: string;
+        target_id: string;
+        relation: string;
+        score: number;
+    }>;
+}
+/**
+ * File metadata in knowledge graph (matches SKILL.md schema)
+ */
+export interface FileMetadata {
+    chunks_count: number;
+    types: Record<string, number>;
+    top_keywords: string[];
+    top_summary: string;
+    importance: number;
+}
+/**
+ * Knowledge graph structure (matches SKILL.md schema)
+ */
+export interface KnowledgeGraph {
+    version: string;
+    stats: {
+        total_files: number;
+        total_chunks: number;
+        total_cross_file_edges: number;
+    };
+    files: Record<string, FileMetadata>;
+    edges: FileEdge[];
+}
+export interface KbMetadata {
+    kbId: string;
+    createdAt: string;
+    lastUpdated: string;
+    documentCount: number;
+    config: Partial<KnowledgeGraphConnectConfig>;
+}

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "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.5",
+  "version": "0.2.1",
   "uiHints": {
     "apiKey": {
       "label": "Knowhere API Key",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-claw",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.",
   "files": [
     "dist/",
@@ -18,7 +18,7 @@
     }
   },
   "scripts": {
-    "build": "rolldown -c",
+    "build": "rolldown -c && tsc -p tsconfig.build.json",
     "changeset": "changeset",
     "changeset:publish": "changeset publish",
     "fmt": "oxfmt",
@@ -69,4 +69,4 @@
       "./dist/index.js"
     ]
   }
-}
+}