@dikolab/kbdb 0.6.3 → 0.6.5

package/dist/src/shared/mcp/functions/handle-agent-list.function.d.ts

@@ -1,27 +1,17 @@
 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 the agent-list tool 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;
-}
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
 /**
- * Handles the `agent:list` MCP tool call.
+ * Handles the `agent-list` MCP tool call.
  *
- * Retrieves all documents with `doc_type: 'agent'` and returns a
- * numbered, human-readable list of each agent's name and
- * description.
+ * Retrieves all documents with `doc_type: 'agent'`. When
+ * `args.query` is a non-empty string, results are filtered by a
+ * case-insensitive substring match against each agent's name or
+ * description before being returned.
  *
  * @param client - the worker client used to execute operations
- * @returns content items with the formatted agent list
+ * @param args - tool arguments; a string `query` filters results
+ *   by name or description
+ * @returns content items with a JSON envelope
+ *   (`{ items, total, offset }`) of matching agent names
  */
-export declare function handleAgentList(client: McpWorkerClient): Promise<ToolCallResult>;
-export {};
+export declare function handleAgentList(client: McpWorkerClient, args?: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -1,18 +1,5 @@
 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;
-}
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
 /**
  * Dispatches an MCP tool call to the appropriate knowledge-base
  * operation and returns the result formatted as MCP content.
@@ -23,4 +10,3 @@ interface ToolCallResult {
  * @returns content items with optional isError flag
  */
 export declare function handleToolCall(client: McpWorkerClient, name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
-export {};

package/dist/src/shared/mcp/functions/handle-tool-learn.function.d.ts

@@ -4,7 +4,9 @@ import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
  * Handles the `learn` MCP tool call.
  *
  * Validates that image content includes a title, then imports the
- * content into the knowledge base via the worker client.
+ * content into the knowledge base via the worker client. Text
+ * content without an explicit title is automatically split into
+ * linked sections when it contains multiple headings.
  *
  * @param client - the worker client used to execute operations
  * @param args - tool arguments from the MCP request

package/dist/src/shared/mcp/functions/handle-tool-skill-list.function.d.ts

@@ -3,9 +3,19 @@ import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
 /**
  * Handles the `skill-list` MCP tool call.
  *
- * Lists all skills stored in the knowledge base, including the
- * argument count extracted from each skill's JSON content.
+ * Lists skills stored in the knowledge base as a JSON envelope
+ * of matching skill names. When `args.query` is a non-empty
+ * string, results are filtered by a case-insensitive substring
+ * match against each skill's name or description.
+ *
+ * This handler is not currently wired into `handleToolCall`'s
+ * dispatch (see `handle-tool-call.function.ts`'s inline
+ * `handleSkillList`), but is kept behaviourally in sync with it.
  *
  * @param client - the worker client used to execute operations
+ * @param args - tool arguments; a string `query` filters results
+ *   by name or description
+ * @returns content items with a JSON envelope
+ *   (`{ items, total, offset }`) of matching skill names
  */
-export declare function handleToolSkillList(client: McpWorkerClient): Promise<ToolCallResult>;
+export declare function handleToolSkillList(client: McpWorkerClient, args?: Record<string, unknown>): Promise<ToolCallResult>;

package/dist/src/shared/mcp/functions/learn-with-splitting.function.d.ts

@@ -0,0 +1,22 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { LearnSectionParams } from '../typings/learn-section-params.interface.ts';
+import type { SplitResult } from '../../content-splitter/index.ts';
+/** Result of storing a split document's sections. */
+export interface LearnWithSplittingResult {
+    /** Knowledge-base identifiers, one per stored section. */
+    readonly kbids: string[];
+    /** Resolved title for the document these sections belong to. */
+    readonly docTitle: string;
+}
+/**
+ * Stores each section of a `splitContent` result as a separate
+ * knowledge-base section, in depth-first order. Every section
+ * shares a single `docid`, and each child section is linked to
+ * its parent via the kbid assigned when that parent was stored.
+ *
+ * @param client - the worker client used to store sections
+ * @param splitResult - depth-first ordered sections to persist
+ * @param params - metadata shared across all stored sections
+ * @returns the persisted kbids and the resolved document title
+ */
+export declare function learnWithSplitting(client: McpWorkerClient, splitResult: SplitResult, params: LearnSectionParams): Promise<LearnWithSplittingResult>;

package/dist/src/shared/mcp/functions/parse-learn-args.function.d.ts

@@ -0,0 +1,24 @@
+/** Parsed and type-narrowed arguments for the `learn` tool call. */
+export interface LearnArgs {
+    /** Section type, defaulting to `'text/markdown'`. */
+    readonly sectionType: string;
+    /** Explicit section title, if provided. */
+    readonly title?: string;
+    /** Optional section description. */
+    readonly description?: string;
+    /** Optional shared document ID. */
+    readonly docid?: string;
+    /** Optional tags for scoping and filtering. */
+    readonly tags?: string[];
+    /** Whether to replace an existing section (supersession). */
+    readonly replace?: boolean;
+    /** Optional hierarchical level (1-6). */
+    readonly level?: number;
+}
+/**
+ * Narrows the raw `learn` tool call arguments into typed fields,
+ * applying `'text/markdown'` as the default section type.
+ *
+ * @param args - tool arguments from the MCP request
+ */
+export declare function parseLearnArgs(args: Record<string, unknown>): LearnArgs;

package/dist/src/shared/mcp/functions/store-split-learn-sections.function.d.ts

@@ -0,0 +1,16 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { LearnSectionParams } from '../typings/learn-section-params.interface.ts';
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
+import type { SplitResult } from '../../content-splitter/index.ts';
+/**
+ * Stores a split document's sections and groups them under a
+ * shared document manifest, returning the same result envelope
+ * shape as a single-section `learn` call.
+ *
+ * @param client - the worker client used to store and group
+ *   sections
+ * @param splitResult - depth-first ordered sections to persist
+ * @param params - metadata shared across all stored sections
+ * @returns a learn-result envelope listing every stored kbid
+ */
+export declare function storeSplitLearnSections(client: McpWorkerClient, splitResult: SplitResult, params: LearnSectionParams): Promise<AddSectionResult>;

package/dist/src/shared/mcp/functions/unwrap-json-content.function.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Unwraps content that AI clients accidentally wrap in a JSON
+ * object. If the string starts with `{` and parses as JSON with
+ * a `content` or `text` field, returns that inner field value.
+ * Otherwise returns the original string.
+ *
+ * @param raw - the raw content string from a tool call argument
+ */
+export declare function unwrapJsonContent(raw: string): string;

package/dist/src/shared/mcp/typings/learn-section-params.interface.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Metadata shared across every section stored for a single
+ * `learn` tool call, whether stored as one section or split
+ * into several linked sections.
+ */
+export interface LearnSectionParams {
+    /** Semantic type label applied to every stored section. */
+    readonly sectionType: string;
+    /** Optional description applied to every stored section. */
+    readonly description?: string;
+    /** Optional document ID shared by every stored section. */
+    readonly docid?: string;
+    /** Optional tags applied to every stored section. */
+    readonly tags?: string[];
+    /**
+     * When `true`, replaces an existing section that has the same
+     * source key (supersession).
+     */
+    readonly replace?: boolean;
+}

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

@@ -144,6 +144,10 @@ export interface McpWorkerClient {
          * source key (supersession).
          */
         readonly replace?: boolean;
+        /** Hierarchical level (1-6). */
+        readonly level?: number;
+        /** Kbid of the parent section for nesting. */
+        readonly parent?: string;
     }): Promise<AddSectionResult>;
     /**
      * Removes a section from the knowledge base.

package/dist/src/shared/mcp/typings/mcp-worker-client.interface.d.ts

@@ -84,6 +84,10 @@ export interface McpWorkerClient {
          * source key (supersession).
          */
         readonly replace?: boolean;
+        /** Hierarchical level (1-6). */
+        readonly level?: number;
+        /** Kbid of the parent section for nesting. */
+        readonly parent?: string;
     }): Promise<AddSectionResult>;
     /**
      * Removes a section from the knowledge base.

package/dist/src/shared/query-filter/functions/matches-query.function.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tests whether any of the given fields contains `query` as a
+ * case-insensitive substring.
+ *
+ * Used to filter list results (skills, agents) against a
+ * free-text query built from CLI positional arguments or an MCP
+ * tool's `query` parameter. An empty `query` always matches,
+ * which lets callers filter unconditionally without a separate
+ * "no filter" branch. `null` and `undefined` fields never match
+ * a non-empty query.
+ *
+ * @param query - the substring to search for; matches
+ *   everything when empty
+ * @param fields - candidate field values to search, in order
+ * @returns `true` when `query` is empty or found in any field
+ */
+export declare function matchesQuery(query: string, ...fields: readonly (string | null | undefined)[]): boolean;

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

@@ -1,2 +1,2 @@
 /** Current package version, kept in sync with package.json. */
-export declare const VERSION = "0.6.3";
+export declare const VERSION = "0.6.5";

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

@@ -3,7 +3,8 @@ import type { RecallResult } from '../../worker-client/typings/recall-result.mod
 /**
  * Decodes a single `RecallResult` record from WASM binary output.
  *
- * Wire format: kbid, heading, section_type, content, docid list,
+ * Wire format: kbid, heading, section_type, content, level
+ * (Option<u8>), parent (Option<String>), docid list,
  * document list, back_references list, siblings list,
  * references list.
  *

package/dist/src/shared/wasm-codec/functions/decode-recall-document.function.d.ts

@@ -5,7 +5,8 @@ import type { RecallDocument } from '../../worker-client/typings/recall-result.m
  *
  * Wire format: docid (String), title (String), section_count (u32),
  * then each section as kbid (String), heading (Option<String>),
- * section_type (String).
+ * section_type (String), level (Option<u8>), parent
+ * (Option<String>).
  *
  * @param bytes - raw binary buffer
  * @param offset - byte position of the record start

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

@@ -14,6 +14,8 @@ import type { RecallResult } from '../../worker-client/typings/recall-result.mod
  * Option<String> heading  (0x00=null, 0x01 + String)
  * String section_type
  * String content
+ * Option<u8> level
+ * Option<String> parent
  * u32 docids_count + String[] docids
  * u32 documents_count + RecallDocument[]
  * u32 back_references_count + RecallReference[]

package/dist/src/shared/wasm-codec/functions/decode-recall-sibling.function.d.ts

@@ -4,7 +4,8 @@ import type { RecallSibling } from '../../worker-client/typings/recall-result.mo
  * Decodes a single `RecallSibling` record from WASM binary output.
  *
  * Wire format: kbid (String), heading (Option<String>),
- * section_type (String), content (String).
+ * section_type (String), content (String), level
+ * (Option<u8>), parent (Option<String>).
  *
  * @param bytes - raw binary buffer
  * @param offset - byte position of the record start

package/dist/src/shared/wasm-codec/functions/decode-scored-results.function.d.ts

@@ -28,6 +28,10 @@ export interface SectionMatch {
     matched_fields: string[];
     /** ISO 8601 creation timestamp of the section. */
     created_at: string;
+    /** Heading level (1-6), or `null` when unset. */
+    level: number | null;
+    /** Kbid of the parent section, or `null`. */
+    parent: string | null;
 }
 /**
  * Paginated search response envelope returned by the WASM engine.
@@ -71,5 +75,7 @@ export interface PagedSearchResult {
  *   - `matched_terms`: `u32` count + `String[]`
  *   - `matched_fields`: `u32` count + `String[]`
  *   - `created_at`: `String`
+ *   - `level`: `Option<u8>`
+ *   - `parent`: `Option<String>`
  */
 export declare function decodePagedSearchResult(bytes: Uint8Array): PagedSearchResult;

package/dist/src/shared/wasm-codec/functions/decode-section-match.function.d.ts

@@ -6,7 +6,8 @@ import type { SectionMatch } from '../typings/section-match.model.ts';
  * Wire format per item: kbid, heading (Option<String>),
  * section_type, docids (u32 count + String[]), score (f32),
  * confidence (f32), snippet, matched_terms (u32 + String[]),
- * matched_fields (u32 + String[]), created_at.
+ * matched_fields (u32 + String[]), created_at, level
+ * (Option<u8>), parent (Option<String>).
  *
  * @param bytes - raw binary buffer
  * @param startOffset - byte position of the item start

package/dist/src/shared/wasm-codec/functions/decode-section-records.function.d.ts

@@ -67,6 +67,10 @@ export interface SectionRecord {
      * Hierarchical level (1-6). `null` when not set.
      */
     level?: number | null;
+    /**
+     * KBDB ID of the parent section for nesting. `null` for root.
+     */
+    parent?: string | null;
 }
 /**
  * Decodes a list of `SectionRecord` values from WASM binary output.

package/dist/src/shared/wasm-codec/functions/encode-add-section-params.function.d.ts

@@ -15,5 +15,6 @@ import type { AddSectionInput } from '../typings/add-section-input.model.ts';
  * - `tags`: `u32` count + each `String`
  * - `replace`: `u8` (0 or 1)
  * - `level`: `u8` flag + optional `u8` (`Option<u8>`)
+ * - `parent`: `u8` flag + optional `String`
  */
 export declare function encodeAddSectionParams(params: AddSectionInput): Uint8Array;

package/dist/src/shared/wasm-codec/typings/add-section-input.model.d.ts

@@ -48,4 +48,6 @@ export interface AddSectionInput {
      * no explicit level (defaults to 1 in the engine).
      */
     level?: number;
+    /** Kbid of the parent section for nesting. */
+    parent?: string | null;
 }

package/dist/src/shared/wasm-codec/typings/section-match.model.d.ts

@@ -28,4 +28,8 @@ export interface SectionMatch {
     matched_fields: string[];
     /** ISO 8601 creation timestamp of the section. */
     created_at: string;
+    /** Heading level (1-6), or `null` when unset. */
+    level: number | null;
+    /** Kbid of the parent section, or `null`. */
+    parent: string | null;
 }

package/dist/src/shared/wasm-codec/typings/section-record-trailing.model.d.ts

@@ -38,6 +38,8 @@ export interface SectionRecordTrailing {
      * to 1 in the engine).
      */
     level: number | null;
+    /** Kbid of the parent section, or `null`. */
+    parent: string | null;
     /** Number of bytes consumed from the buffer. */
     bytesRead: number;
 }

package/dist/src/shared/wasm-codec/typings/section-record.model.d.ts

@@ -68,4 +68,6 @@ export interface SectionRecord {
      * to 1 in the engine).
      */
     level?: number | null;
+    /** Kbid of the parent section, or `null`. */
+    parent?: string | null;
 }

package/dist/src/shared/worker-client/typings/recall-result.model.d.ts

@@ -27,6 +27,10 @@ export interface RecallDocument {
         readonly heading: string | null;
         /** Semantic type label for the section. */
         readonly type: string;
+        /** Heading level (1-6), or `null`. */
+        readonly level?: number | null;
+        /** Kbid of the parent section, or `null`. */
+        readonly parent?: string | null;
     }[];
 }
 /** A sibling section adjacent to the recalled section. */
@@ -39,6 +43,10 @@ export interface RecallSibling {
     readonly type: string;
     /** Full text content of the sibling section. */
     readonly content: string;
+    /** Heading level (1-6), or `null`. */
+    readonly level?: number | null;
+    /** Kbid of the parent section, or `null`. */
+    readonly parent?: string | null;
 }
 /** A section that references or is referenced by the recalled section. */
 export interface RecallReference {
@@ -65,6 +73,10 @@ export interface RecallResult {
     readonly type: string;
     /** Full text content of the section. */
     readonly content: string;
+    /** Heading level (1-6), or `null`. */
+    readonly level?: number | null;
+    /** Kbid of the parent section, or `null`. */
+    readonly parent?: string | null;
     /** Identifiers of documents that contain this section. */
     readonly docids: readonly string[];
     /**

package/dist/src/shared/worker-client/typings/search-result.model.d.ts

@@ -26,6 +26,10 @@ export interface SearchResult {
     readonly confidence?: number;
     /** ISO 8601 creation timestamp of the section. */
     readonly created_at?: string;
+    /** Heading level (1-6), or `null` when unset. */
+    readonly level?: number | null;
+    /** Kbid of the parent section, or `null`. */
+    readonly parent?: string | null;
 }
 /** Paginated search result envelope. */
 export interface PagedSearchResult {

package/dist/src/shared/worker-client/typings/section.model.d.ts

@@ -44,4 +44,6 @@ export interface AddSectionParams {
      * (lower number) represent broader scope.
      */
     readonly level?: number;
+    /** Kbid of the parent section for nesting. */
+    readonly parent?: string;
 }

package/dist/worker.mjs

@@ -1006,6 +1006,7 @@ function encodeAddSectionParams(params) {
     params.replace === true ? 1 : 0
   ]);
   const levelBytes = params.level != null ? new Uint8Array([1, params.level]) : new Uint8Array([0]);
+  const parentBytes = encodeOptionString(params.parent);
   const parts = [
     encodeSectionType(params.sectionType, params.mimeType),
     encodeString(params.content),
@@ -1018,7 +1019,8 @@ function encodeAddSectionParams(params) {
     tagsCountBytes,
     ...tagParts,
     replaceByte,
-    levelBytes
+    levelBytes,
+    parentBytes
   ];
   const totalLen = parts.reduce((sum, p) => sum + p.length, 0);
   const result = new Uint8Array(totalLen);
@@ -1156,6 +1158,15 @@ function decodeU64(bytes, offset) {
   };
 }
 
+// src/shared/wasm-codec/functions/decode-option-u8.function.ts
+function decodeOptionU8(bytes, offset) {
+  const tag = bytes[offset];
+  if (tag === 1) {
+    return { value: bytes[offset + 1], bytesRead: 2 };
+  }
+  return { value: null, bytesRead: 1 };
+}
+
 // src/shared/wasm-codec/functions/decode-scored-results.function.ts
 function decodeOptionString(bytes, offset) {
   const tag = bytes[offset];
@@ -1221,6 +1232,10 @@ function decodePagedSearchResult(bytes) {
     }
     const createdAt = decodeString(bytes, offset);
     offset += createdAt.bytesRead;
+    const optLevel = decodeOptionU8(bytes, offset);
+    offset += optLevel.bytesRead;
+    const optParent = decodeOptionString(bytes, offset);
+    offset += optParent.bytesRead;
     items.push({
       kbid: kbid.value,
       heading: heading.value,
@@ -1231,7 +1246,9 @@ function decodePagedSearchResult(bytes) {
       snippet: snippet.value,
       matched_terms,
       matched_fields,
-      created_at: createdAt.value
+      created_at: createdAt.value,
+      level: optLevel.value,
+      parent: optParent.value
     });
   }
   return {
@@ -1245,7 +1262,7 @@ function decodePagedSearchResult(bytes) {
 }
 
 // src/shared/wasm-codec/functions/decode-section-records.function.ts
-function decodeOptionU8(bytes, offset) {
+function decodeOptionU82(bytes, offset) {
   const tag = bytes[offset];
   if (tag === 1) {
     return { value: bytes[offset + 1], bytesRead: 2 };
@@ -1350,10 +1367,16 @@ function decodeSectionRecords(bytes) {
     }
     let level = null;
     if (offset < bytes.length) {
-      const v = decodeOptionU8(bytes, offset);
+      const v = decodeOptionU82(bytes, offset);
       offset += v.bytesRead;
       level = v.value;
     }
+    let parent = null;
+    if (offset < bytes.length) {
+      const v = decodeOptionString2(bytes, offset);
+      offset += v.bytesRead;
+      parent = v.value;
+    }
     const record = {
       kbid: kbid.value,
       docid: docid.value,
@@ -1375,7 +1398,8 @@ function decodeSectionRecords(bytes) {
       updatedAt,
       tags,
       supersedes,
-      level
+      level,
+      parent
     };
     if (st.mimeType !== void 0) {
       record.mimeType = st.mimeType;
@@ -1588,12 +1612,18 @@ function decodeSibling(bytes, offset) {
   pos += sectionType.bytesRead;
   const content = decodeString(bytes, pos);
   pos += content.bytesRead;
+  const optLevel = decodeOptionU8(bytes, pos);
+  pos += optLevel.bytesRead;
+  const optParent = decodeOptionString3(bytes, pos);
+  pos += optParent.bytesRead;
   return {
     value: {
       kbid: kbid.value,
       heading: heading.value,
       type: sectionType.value,
-      content: content.value
+      content: content.value,
+      level: optLevel.value,
+      parent: optParent.value
     },
     bytesRead: pos - offset
   };
@@ -1614,10 +1644,16 @@ function decodeDocument(bytes, offset) {
     pos += secHeading.bytesRead;
     const secType = decodeString(bytes, pos);
     pos += secType.bytesRead;
+    const secLevel = decodeOptionU8(bytes, pos);
+    pos += secLevel.bytesRead;
+    const secParent = decodeOptionString3(bytes, pos);
+    pos += secParent.bytesRead;
     sections.push({
       kbid: secKbid.value,
       heading: secHeading.value,
-      type: secType.value
+      type: secType.value,
+      level: secLevel.value,
+      parent: secParent.value
     });
   }
   return {
@@ -1639,6 +1675,10 @@ function decodeOneResult(bytes, startOffset) {
   pos += sectionType.bytesRead;
   const content = decodeString(bytes, pos);
   pos += content.bytesRead;
+  const optLevel = decodeOptionU8(bytes, pos);
+  pos += optLevel.bytesRead;
+  const optParent = decodeOptionString3(bytes, pos);
+  pos += optParent.bytesRead;
   const docidCount = decodeU32(bytes, pos);
   pos += docidCount.bytesRead;
   const docids = [];
@@ -1685,6 +1725,8 @@ function decodeOneResult(bytes, startOffset) {
       heading: heading.value,
       type: sectionType.value,
       content: content.value,
+      level: optLevel.value,
+      parent: optParent.value,
       docids,
       documents,
       back_references,