@dikolab/kbdb 0.2.2 → 0.3.1

package/src/shared/embedding/typings/embedding-provider.interface.ts

@@ -0,0 +1,25 @@
+/** Pluggable embedding provider interface. */
+export interface EmbeddingProvider {
+   /**
+    * Compute embedding vectors for text inputs.
+    *
+    * @param texts - list of text strings to embed
+    * @returns a Float32Array embedding for each input text,
+    *   in the same order
+    */
+   embed(texts: string[]): Promise<Float32Array[]>;
+
+   /**
+    * Number of dimensions in the embedding vector.
+    *
+    * Returns 0 when embeddings are disabled.
+    */
+   dimensions(): number;
+
+   /**
+    * Name of the underlying model.
+    *
+    * Returns `'none'` when embeddings are disabled.
+    */
+   modelName(): string;
+}

package/src/shared/embedding/typings/near-duplicate-candidate.model.ts

@@ -0,0 +1,25 @@
+/**
+ * A document section candidate for near-duplicate detection.
+ *
+ * Carries the token set for Jaccard comparison and an optional
+ * embedding vector for cosine-similarity comparison.
+ */
+export interface NearDuplicateCandidate {
+   /** Knowledge-base identifier for this section. */
+   readonly kbid: string;
+
+   /**
+    * Set of lowercased word tokens extracted from the section body.
+    *
+    * Used by the Jaccard coefficient pass.
+    */
+   readonly tokens: Set<string>;
+
+   /**
+    * Optional embedding vector for this section.
+    *
+    * When present and a provider is available, used as the
+    * cosine-similarity pass input.
+    */
+   readonly embedding?: Float32Array;
+}

package/src/shared/embedding/typings/near-duplicate-result.model.ts

@@ -0,0 +1,26 @@
+/**
+ * A near-duplicate detected by the two-pass detection algorithm.
+ *
+ * Reports which existing section matched the candidate and which
+ * detection method produced the match.
+ */
+export interface NearDuplicateResult {
+   /** Knowledge-base identifier of the matched existing section. */
+   readonly kbid: string;
+
+   /**
+    * Similarity score of the match (0.0–1.0).
+    *
+    * Jaccard matches use the Jaccard coefficient; cosine matches use
+    * cosine similarity.
+    */
+   readonly score: number;
+
+   /**
+    * Detection method that produced this match.
+    *
+    * - `'jaccard'`: Jaccard coefficient >= 0.85
+    * - `'cosine'`: cosine similarity >= 0.92 with Jaccard 0.40–0.84
+    */
+   readonly method: 'jaccard' | 'cosine';
+}

package/src/shared/embedding/typings/vector-index-entry.model.ts

@@ -0,0 +1,13 @@
+/** A single record written into the vector index file. */
+export interface VectorIndexEntry {
+   /**
+    * Knowledge-base identifier for this section.
+    *
+    * Stored as a fixed 64-byte UTF-8 field in the index file;
+    * truncated or zero-padded as needed.
+    */
+   readonly kbid: string;
+
+   /** Embedding vector for this section. */
+   readonly vector: Float32Array;
+}

package/src/shared/embedding/typings/vector-index-meta.model.ts

@@ -0,0 +1,14 @@
+/** Metadata for a vector index file. */
+export interface VectorIndexMeta {
+   /** Name of the embedding model used. */
+   readonly modelName: string;
+
+   /** Embedding vector dimensions. */
+   readonly dimensions: number;
+
+   /** Number of vectors stored. */
+   readonly count: number;
+
+   /** Schema version. */
+   readonly version: number;
+}

package/src/shared/embedding/typings/vector-search-result.model.ts

@@ -0,0 +1,8 @@
+/** Result from a vector similarity search. */
+export interface VectorSearchResult {
+   /** Knowledge base ID of the matched section. */
+   readonly kbid: string;
+
+   /** Cosine similarity score (0.0 to 1.0). */
+   readonly score: number;
+}

package/src/shared/mcp/classes/mcp-server.class.ts

@@ -59,14 +59,17 @@ export class McpServer {
          terminal: false,
       });
 
+      let pending = Promise.resolve();
       await new Promise<void>((resolve) => {
          rl.on('line', (line) => {
-            void this.dispatchLine(line);
+            pending = pending.then(() => this.dispatchLine(line));
          });
 
          rl.on('close', () => {
-            this.client.disconnect();
-            resolve();
+            void pending.then(() => {
+               this.client.disconnect();
+               resolve();
+            });
          });
       });
    }
@@ -207,8 +210,12 @@ export class McpServer {
             request.method === 'notifications/initialized' ||
             request.method === 'notifications/cancelled'
          ) {
-            if (request.method === 'notifications/initialized') {
+            if (
+               request.method === 'notifications/initialized' &&
+               !this.initialized
+            ) {
                this.initialized = true;
+               void this.runStartupHealthCheck();
             }
          }
          return null;
@@ -445,4 +452,29 @@ export class McpServer {
       const json = JSON.stringify(response);
       process.stdout.write(json + '\n');
    }
+
+   /**
+    * Runs an integrity check immediately after the MCP handshake
+    * completes. Emits a `notifications/message` warning when the
+    * check detects issues so the connected agent is aware before
+    * making requests. The server continues operating regardless of
+    * the result.
+    */
+   private async runStartupHealthCheck(): Promise<void> {
+      try {
+         const report = await this.client.integrityCheck();
+         if (!report.ok) {
+            const summary = report.errors
+               .map((e) => `${e.type}: ${e.entity} -- ${e.detail}`)
+               .join('; ');
+            this.notify('notifications/message', {
+               level: 'warning',
+               logger: 'kbdb',
+               data: `Database integrity issues detected: ${summary}`,
+            });
+         }
+      } catch {
+         // Health check failure is non-fatal -- server continues
+      }
+   }
 }

package/src/shared/mcp/constants/tool-agent-create.constant.ts

@@ -0,0 +1,39 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `agent-create` operation. */
+export const TOOL_AGENT_CREATE: McpToolDefinition = {
+   name: 'agent-create',
+   description:
+      'Create an AI agent with a persona and' +
+      ' optional skill references.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         name: {
+            type: 'string',
+            description: 'Agent name',
+         },
+         description: {
+            type: 'string',
+            description: 'Agent description',
+         },
+         persona: {
+            type: 'string',
+            description: 'Agent persona prompt',
+         },
+         skills: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Skill kbid references to attach',
+         },
+      },
+      required: ['name', 'persona'],
+   },
+   annotations: {
+      title: 'Create Agent',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-agent-delete.constant.ts

@@ -0,0 +1,26 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `agent-delete` operation. */
+export const TOOL_AGENT_DELETE: McpToolDefinition = {
+   name: 'agent-delete',
+   description:
+      'Delete an agent by its document ID.' +
+      ' Skill sections are not removed.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         docid: {
+            type: 'string',
+            description: 'Document ID of the agent',
+         },
+      },
+      required: ['docid'],
+   },
+   annotations: {
+      title: 'Delete Agent',
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-agent-get.constant.ts

@@ -0,0 +1,24 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `agent-get` operation. */
+export const TOOL_AGENT_GET: McpToolDefinition = {
+   name: 'agent-get',
+   description: 'Get an agent definition by document ID.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         docid: {
+            type: 'string',
+            description: 'Document ID of the agent',
+         },
+      },
+      required: ['docid'],
+   },
+   annotations: {
+      title: 'Get Agent',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-agent-list.constant.ts

@@ -0,0 +1,18 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `agent-list` operation. */
+export const TOOL_AGENT_LIST: McpToolDefinition = {
+   name: 'agent-list',
+   description: 'List all agents in the knowledge base.',
+   inputSchema: {
+      type: 'object',
+      properties: {},
+   },
+   annotations: {
+      title: 'List Agents',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-auto-capture-review.constant.ts

@@ -0,0 +1,32 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/**
+ * MCP tool definition for the `auto-capture-review` operation.
+ *
+ * Allows agents to list, approve, or reject pending
+ * auto-captured knowledge entries before they are persisted.
+ */
+export const TOOL_AUTO_CAPTURE_REVIEW: McpToolDefinition = {
+   name: 'auto-capture-review',
+   description:
+      'Review and approve pending auto-captured knowledge' +
+      ' before storage. Use list to see pending captures,' +
+      ' approve or reject to act on them.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         action: {
+            type: 'string',
+            enum: ['list', 'approve', 'reject'],
+            description: 'Action to perform on pending captures.',
+         },
+      },
+   },
+   annotations: {
+      title: 'Auto-Capture Review',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-check.constant.ts

@@ -0,0 +1,21 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `check` operation. */
+export const TOOL_CHECK: McpToolDefinition = {
+   name: 'check',
+   description:
+      'Verify the integrity of the knowledge base.' +
+      ' Reports checksum mismatches, orphan sections,' +
+      ' broken references, and circular reference chains.',
+   inputSchema: {
+      type: 'object',
+      properties: {},
+   },
+   annotations: {
+      title: 'Integrity Check',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-content.constant.ts

@@ -0,0 +1,29 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `content` operation. */
+export const TOOL_CONTENT: McpToolDefinition = {
+   name: 'content',
+   description:
+      'Compose a rendered Markdown document from one or' +
+      ' more kbid or docid identifiers.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         ids: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+               'One or more kbid or docid identifiers' +
+               ' (may be mixed)',
+         },
+      },
+      required: ['ids'],
+   },
+   annotations: {
+      title: 'Compose Content',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-export.constant.ts

@@ -0,0 +1,27 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `export` operation. */
+export const TOOL_EXPORT: McpToolDefinition = {
+   name: 'export',
+   description:
+      'Export the database as a self-contained' +
+      ' directory snapshot (sections, documents,' +
+      ' catalog -- no indexes).',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         path: {
+            type: 'string',
+            description:
+               'Export destination path' + ' (default: ./kbdb-export/)',
+         },
+      },
+   },
+   annotations: {
+      title: 'Export Snapshot',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-gc.constant.ts

@@ -0,0 +1,21 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `gc` operation. */
+export const TOOL_GC: McpToolDefinition = {
+   name: 'gc',
+   description:
+      'Remove unreferenced sections from the knowledge' +
+      ' base. A section is eligible when no document' +
+      ' manifest references it.',
+   inputSchema: {
+      type: 'object',
+      properties: {},
+   },
+   annotations: {
+      title: 'Garbage Collect',
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-learn.constant.ts

@@ -0,0 +1,58 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `learn` operation. */
+export const TOOL_LEARN: McpToolDefinition = {
+   name: 'learn',
+   description:
+      'Import content into the knowledge base.' +
+      ' Use for durable facts, decisions, and' +
+      ' corrections. Use replace when updating' +
+      ' existing knowledge. Attach tags for scoping.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         content: {
+            type: 'string',
+            description: 'Text content to add',
+         },
+         type: {
+            type: 'string',
+            description:
+               'MIME type (default: text/markdown).' +
+               ' Use image/* for images.',
+         },
+         title: {
+            type: 'string',
+            description:
+               'Section title.' + ' Required for image/* types.',
+         },
+         description: {
+            type: 'string',
+            description: 'Optional section description',
+         },
+         docid: {
+            type: 'string',
+            description: 'Document ID to group under',
+         },
+         tags: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Tags for scoping and filtering',
+         },
+         replace: {
+            type: 'boolean',
+            description:
+               'Replace existing section with same' +
+               ' source key (supersession)',
+         },
+      },
+      required: ['content'],
+   },
+   annotations: {
+      title: 'Import Content',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-rebuild.constant.ts

@@ -0,0 +1,21 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `rebuild` operation. */
+export const TOOL_REBUILD: McpToolDefinition = {
+   name: 'rebuild',
+   description:
+      'Reconstruct all index files from section files' +
+      ' and document manifests on disk. Use this to' +
+      ' recover from index corruption.',
+   inputSchema: {
+      type: 'object',
+      properties: {},
+   },
+   annotations: {
+      title: 'Rebuild Indexes',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-recall.constant.ts

@@ -0,0 +1,36 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `recall` operation. */
+export const TOOL_RECALL: McpToolDefinition = {
+   name: 'recall',
+   description:
+      'Retrieve full content and context for sections' +
+      ' by identifier. Use after search to read relevant' +
+      ' results. Returns section text, metadata,' +
+      ' references, and back-references.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         kbid: {
+            type: 'string',
+            description: 'Single section identifier',
+         },
+         kbids: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Batch section identifiers',
+         },
+         depth: {
+            type: 'number',
+            description: 'Expansion depth (0-3, default: 0)',
+         },
+      },
+   },
+   annotations: {
+      title: 'Recall Context',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-retrieve.constant.ts

@@ -0,0 +1,31 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `retrieve` operation. */
+export const TOOL_RETRIEVE: McpToolDefinition = {
+   name: 'retrieve',
+   description:
+      'Low-level fetch of a section or document' +
+      ' by identifier. For AI agent workflows,' +
+      ' prefer `recall` which includes metadata,' +
+      ' context, and back-references.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         kbid: {
+            type: 'string',
+            description: 'Section kb-id',
+         },
+         docid: {
+            type: 'string',
+            description: 'Document ID',
+         },
+      },
+   },
+   annotations: {
+      title: 'Fetch Content',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-search.constant.ts

@@ -0,0 +1,51 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `search` operation. */
+export const TOOL_SEARCH: McpToolDefinition = {
+   name: 'search',
+   description:
+      'Query the knowledge base by keywords.' +
+      ' Returns ranked results with heading,' +
+      ' snippet, and matched terms. Use multiple' +
+      ' short keyword queries for best coverage.' +
+      ' Use recall to get full content.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         query: {
+            type: 'string',
+            description: 'Search query text',
+         },
+         mode: {
+            type: 'string',
+            enum: ['sections', 'documents', 'stats'],
+            description: 'Search mode (default: sections)',
+         },
+         algo: {
+            type: 'string',
+            enum: ['lexical', 'vector', 'hybrid'],
+            description:
+               'Search algorithm (default: lexical).' +
+               ' Use hybrid for embedding+keyword fusion.',
+         },
+         limit: {
+            type: 'number',
+            description: 'Maximum results (default: 20)',
+         },
+         offset: {
+            type: 'number',
+            description:
+               'Number of results to skip for' +
+               ' pagination (default: 0)',
+         },
+      },
+      required: ['query'],
+   },
+   annotations: {
+      title: 'Search KB',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-skill-delete.constant.ts

@@ -0,0 +1,24 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `skill-delete` operation. */
+export const TOOL_SKILL_DELETE: McpToolDefinition = {
+   name: 'skill-delete',
+   description: 'Delete a skill by its kbid.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         kbid: {
+            type: 'string',
+            description: 'Knowledge base ID',
+         },
+      },
+      required: ['kbid'],
+   },
+   annotations: {
+      title: 'Delete Skill',
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};