@dikolab/kbdb 0.1.5 → 0.2.0

package/src/shared/mcp/functions/create-tool-definitions.function.ts

@@ -10,8 +10,10 @@ export function createToolDefinitions(): McpToolDefinition[] {
       {
          name: 'search',
          description:
-            'Search the knowledge base for relevant' +
-            ' sections using natural language queries.',
+            'Search the knowledge base. Returns ranked' +
+            ' results with headings and snippets for' +
+            ' relevance evaluation. Use `recall` to' +
+            ' get full content of specific results.',
          inputSchema: {
             type: 'object',
             properties: {
@@ -28,6 +30,12 @@ export function createToolDefinitions(): McpToolDefinition[] {
                   type: 'number',
                   description: 'Maximum results (default: 20)',
                },
+               offset: {
+                  type: 'number',
+                  description:
+                     'Number of results to skip for' +
+                     ' pagination (default: 0)',
+               },
             },
             required: ['query'],
          },
@@ -36,6 +44,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -75,6 +84,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -97,13 +107,16 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
          name: 'retrieve',
          description:
-            'Retrieve a section or document by ID.' +
-            ' Provide kbid or docid.',
+            '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: {
@@ -122,6 +135,40 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
+         },
+      },
+      {
+         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,
          },
       },
       {
@@ -138,6 +185,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -163,6 +211,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -180,6 +229,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -197,6 +247,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: false,
+            openWorldHint: false,
          },
       },
       {
@@ -214,6 +265,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
+            openWorldHint: false,
          },
       },
       {
@@ -247,6 +299,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -261,6 +314,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -284,6 +338,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -304,6 +359,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -339,6 +395,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -353,6 +410,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -373,6 +431,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
       {
@@ -395,6 +454,7 @@ export function createToolDefinitions(): McpToolDefinition[] {
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: true,
+            openWorldHint: false,
          },
       },
    ];

package/src/shared/mcp/functions/handle-recall.function.ts

@@ -0,0 +1,66 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+
+/** Shape of a content item in an MCP tool call response. */
+interface ToolContent {
+   /** Content type identifier, typically `'text'`. */
+   readonly type: string;
+   /** The text payload. */
+   readonly text: string;
+}
+
+/** Result returned by a tool call handler. */
+interface ToolCallResult {
+   /** One or more content items describing the result. */
+   readonly content: ToolContent[];
+   /** Set to `true` when the tool encountered an error. */
+   readonly isError?: boolean;
+}
+
+/**
+ * Handles the MCP `recall` tool call.
+ *
+ * Retrieves full content and context for one or more knowledge-base
+ * sections by identifier. At least one of `kbid` or `kbids` must be
+ * present in `args`; omitting both returns an error result.
+ *
+ * @param client - the worker client used to execute the operation
+ * @param args - tool arguments from the MCP request
+ * @returns content with JSON-stringified recall result, or an error
+ *   content item when required arguments are missing
+ */
+export async function handleRecall(
+   client: McpWorkerClient,
+   args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   const kbid =
+      typeof args['kbid'] === 'string' ? args['kbid'] : undefined;
+   const kbids =
+      Array.isArray(args['kbids']) &&
+      args['kbids'].every((item: unknown) => typeof item === 'string')
+         ? args['kbids']
+         : undefined;
+
+   if (!kbid && !kbids) {
+      return {
+         content: [
+            {
+               type: 'text',
+               text: 'Provide kbid or kbids',
+            },
+         ],
+         isError: true,
+      };
+   }
+
+   const depth = typeof args['depth'] === 'number' ? args['depth'] : 0;
+
+   const result = await client.recall({ kbid, kbids, depth });
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+         },
+      ],
+   };
+}

package/src/shared/mcp/functions/handle-tool-call.function.ts

@@ -6,6 +6,7 @@ import { handleAgentCreate } from './handle-agent-create.function.ts';
 import { handleAgentList } from './handle-agent-list.function.ts';
 import { handleAgentGet } from './handle-agent-get.function.ts';
 import { handleAgentDelete } from './handle-agent-delete.function.ts';
+import { handleRecall } from './handle-recall.function.ts';
 
 /** Shape of a content item in an MCP tool call response. */
 interface ToolContent {
@@ -69,6 +70,8 @@ export async function handleToolCall(
             return await handleUnlearn(client, args);
          case 'retrieve':
             return await handleRetrieve(client, args);
+         case 'recall':
+            return await handleRecall(client, args);
          case 'status':
             return await handleStatus(client);
          case 'content':
@@ -127,12 +130,19 @@ async function handleSearch(
       query: asString(args['query'], ''),
       mode: args['mode'] as string | undefined,
       limit: args['limit'] as number | undefined,
+      offset: args['offset'] as number | undefined,
    });
+
+   const stripped = {
+      ...results,
+      items: results.items.map(({ score: _score, ...rest }) => rest),
+   };
+
    return {
       content: [
          {
             type: 'text',
-            text: JSON.stringify(results, null, 2),
+            text: JSON.stringify(stripped, null, 2),
          },
       ],
    };

package/src/shared/mcp/typings/mcp-client.interface.ts

@@ -85,21 +85,23 @@ export interface McpWorkerClient {
       readonly mode?: string;
       /** Maximum number of results to return. */
       readonly limit?: number;
-   }): Promise<
-      {
-         /** Knowledge-base identifier of the matched section. */
-         kbid: string;
-         /** Relevance score assigned by the ranking engine. */
-         score: number;
-         /** Terms that matched within this section. */
-         readonly matches: readonly {
-            /** The matched term. */
-            readonly term: string;
-            /** Number of times the term appears in the section. */
-            readonly frequency: number;
-         }[];
-      }[]
-   >;
+      /** Number of results to skip for pagination. */
+      readonly offset?: number;
+   }): Promise<{
+      readonly items: readonly {
+         readonly kbid: string;
+         readonly heading: string | null;
+         readonly type: string;
+         readonly docids: readonly string[];
+         readonly score: number;
+         readonly snippet: string;
+         readonly matched_terms: readonly string[];
+      }[];
+      readonly total: number;
+      readonly offset: number;
+      readonly limit: number;
+      readonly has_more: boolean;
+   }>;
 
    /**
     * Adds a new section to the knowledge base.
@@ -245,6 +247,22 @@ export interface McpWorkerClient {
     */
    removeGrouping(docid: string): Promise<void>;
 
+   /**
+    * Retrieves full content and context for one or more sections by
+    * their knowledge-base identifiers.
+    *
+    * @param params - section identifier(s) and optional expansion depth
+    * @returns a single result or array of results depending on input
+    */
+   recall(params: {
+      /** Single section identifier. */
+      readonly kbid?: string;
+      /** Batch section identifiers. */
+      readonly kbids?: readonly string[];
+      /** Expansion depth (0-3, default: 0). */
+      readonly depth?: number;
+   }): Promise<unknown>;
+
    /** Destroys the IPC socket and clears the connection state. */
    disconnect(): void;
 }

package/src/shared/version/constants/version.constant.ts

@@ -1,2 +1,2 @@
 /** Current package version, kept in sync with package.json. */
-export const VERSION = '0.1.5';
+export const VERSION = '0.2.0';

package/src/shared/wasm-codec/functions/decode-recall-result.function.ts

@@ -0,0 +1,267 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeU32 } from './decode-u32.function.ts';
+import type {
+   RecallResult,
+   RecallDocument,
+   RecallSibling,
+   RecallReference,
+} from '../../worker-client/typings/recall-result.model.ts';
+
+/**
+ * Decodes recall result binary output from the `worker_recall` WASM
+ * export.
+ *
+ * Binary layout:
+ * - `u8 tag`: `0` = single result, `1` = batch
+ * - If tag=0: one RecallResult record
+ * - If tag=1: `u32 count` + `count` RecallResult records
+ *
+ * Each RecallResult:
+ * ```
+ * String kbid
+ * Option<String> heading  (0x00=null, 0x01 + String)
+ * String section_type
+ * String content
+ * u32 docids_count + String[] docids
+ * u32 documents_count + RecallDocument[]
+ * u32 back_references_count + RecallReference[]
+ * u32 siblings_count + RecallSibling[]
+ * u32 references_count + RecallReference[]
+ * ```
+ *
+ * @param bytes - raw binary output from the WASM export
+ * @returns a single `RecallResult` for tag=0, or `RecallResult[]`
+ *   for tag=1
+ */
+export function decodeRecallResult(
+   bytes: Uint8Array,
+): RecallResult | RecallResult[] {
+   const tag = bytes[0];
+   let offset = 1;
+
+   if (tag === 0x01) {
+      // Batch
+      const countResult = decodeU32(bytes, offset);
+      offset += countResult.bytesRead;
+      const items: RecallResult[] = [];
+      for (let i = 0; i < countResult.value; i++) {
+         const { item, bytesRead } = decodeOneResult(bytes, offset);
+         offset += bytesRead;
+         items.push(item);
+      }
+      return items;
+   }
+
+   // Single (tag=0 or any other value)
+   const { item } = decodeOneResult(bytes, offset);
+   return item;
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+interface DecodeResultPair {
+   item: RecallResult;
+   bytesRead: number;
+}
+
+function decodeOptionString(
+   bytes: Uint8Array,
+   offset: number,
+): { value: string | null; bytesRead: number } {
+   const tag = bytes[offset];
+   if (tag === 0x00) {
+      return { value: null, bytesRead: 1 };
+   }
+   const str = decodeString(bytes, offset + 1);
+   return { value: str.value, bytesRead: 1 + str.bytesRead };
+}
+
+function decodeReference(
+   bytes: Uint8Array,
+   offset: number,
+): { value: RecallReference; bytesRead: number } {
+   let pos = offset;
+
+   const kbid = decodeString(bytes, pos);
+   pos += kbid.bytesRead;
+
+   const heading = decodeOptionString(bytes, pos);
+   pos += heading.bytesRead;
+
+   const sectionType = decodeString(bytes, pos);
+   pos += sectionType.bytesRead;
+
+   const markerType = decodeString(bytes, pos);
+   pos += markerType.bytesRead;
+
+   const contextSnippet = decodeString(bytes, pos);
+   pos += contextSnippet.bytesRead;
+
+   const direction = decodeString(bytes, pos);
+   pos += direction.bytesRead;
+
+   return {
+      value: {
+         kbid: kbid.value,
+         heading: heading.value,
+         type: sectionType.value,
+         marker_type: markerType.value,
+         context_snippet: contextSnippet.value,
+         direction: direction.value as 'forward' | 'back',
+      },
+      bytesRead: pos - offset,
+   };
+}
+
+function decodeSibling(
+   bytes: Uint8Array,
+   offset: number,
+): { value: RecallSibling; bytesRead: number } {
+   let pos = offset;
+
+   const kbid = decodeString(bytes, pos);
+   pos += kbid.bytesRead;
+
+   const heading = decodeOptionString(bytes, pos);
+   pos += heading.bytesRead;
+
+   const sectionType = decodeString(bytes, pos);
+   pos += sectionType.bytesRead;
+
+   const content = decodeString(bytes, pos);
+   pos += content.bytesRead;
+
+   return {
+      value: {
+         kbid: kbid.value,
+         heading: heading.value,
+         type: sectionType.value,
+         content: content.value,
+      },
+      bytesRead: pos - offset,
+   };
+}
+
+function decodeDocument(
+   bytes: Uint8Array,
+   offset: number,
+): { value: RecallDocument; bytesRead: number } {
+   let pos = offset;
+
+   const docid = decodeString(bytes, pos);
+   pos += docid.bytesRead;
+
+   const title = decodeString(bytes, pos);
+   pos += title.bytesRead;
+
+   const sectionCount = decodeU32(bytes, pos);
+   pos += sectionCount.bytesRead;
+
+   const sections: RecallDocument['sections'][number][] = [];
+   for (let i = 0; i < sectionCount.value; i++) {
+      const secKbid = decodeString(bytes, pos);
+      pos += secKbid.bytesRead;
+
+      const secHeading = decodeOptionString(bytes, pos);
+      pos += secHeading.bytesRead;
+
+      const secType = decodeString(bytes, pos);
+      pos += secType.bytesRead;
+
+      sections.push({
+         kbid: secKbid.value,
+         heading: secHeading.value,
+         type: secType.value,
+      });
+   }
+
+   return {
+      value: {
+         docid: docid.value,
+         title: title.value,
+         sections,
+      },
+      bytesRead: pos - offset,
+   };
+}
+
+function decodeOneResult(
+   bytes: Uint8Array,
+   startOffset: number,
+): DecodeResultPair {
+   let pos = startOffset;
+
+   const kbid = decodeString(bytes, pos);
+   pos += kbid.bytesRead;
+
+   const heading = decodeOptionString(bytes, pos);
+   pos += heading.bytesRead;
+
+   const sectionType = decodeString(bytes, pos);
+   pos += sectionType.bytesRead;
+
+   const content = decodeString(bytes, pos);
+   pos += content.bytesRead;
+
+   const docidCount = decodeU32(bytes, pos);
+   pos += docidCount.bytesRead;
+   const docids: string[] = [];
+   for (let i = 0; i < docidCount.value; i++) {
+      const docid = decodeString(bytes, pos);
+      pos += docid.bytesRead;
+      docids.push(docid.value);
+   }
+
+   const docCount = decodeU32(bytes, pos);
+   pos += docCount.bytesRead;
+   const documents: RecallDocument[] = [];
+   for (let i = 0; i < docCount.value; i++) {
+      const doc = decodeDocument(bytes, pos);
+      pos += doc.bytesRead;
+      documents.push(doc.value);
+   }
+
+   const backRefCount = decodeU32(bytes, pos);
+   pos += backRefCount.bytesRead;
+   const back_references: RecallReference[] = [];
+   for (let i = 0; i < backRefCount.value; i++) {
+      const ref = decodeReference(bytes, pos);
+      pos += ref.bytesRead;
+      back_references.push(ref.value);
+   }
+
+   const sibCount = decodeU32(bytes, pos);
+   pos += sibCount.bytesRead;
+   const siblings: RecallSibling[] = [];
+   for (let i = 0; i < sibCount.value; i++) {
+      const sib = decodeSibling(bytes, pos);
+      pos += sib.bytesRead;
+      siblings.push(sib.value);
+   }
+
+   const refCount = decodeU32(bytes, pos);
+   pos += refCount.bytesRead;
+   const references: RecallReference[] = [];
+   for (let i = 0; i < refCount.value; i++) {
+      const ref = decodeReference(bytes, pos);
+      pos += ref.bytesRead;
+      references.push(ref.value);
+   }
+
+   return {
+      item: {
+         kbid: kbid.value,
+         heading: heading.value,
+         type: sectionType.value,
+         content: content.value,
+         docids,
+         documents,
+         back_references,
+         siblings,
+         references,
+      },
+      bytesRead: pos - startOffset,
+   };
+}