@dikolab/kbdb 0.1.6 → 0.2.0

package/dist/cli.mjs

@@ -71,6 +71,13 @@ function parseArgs(argv) {
       case "-l":
         options.limit = parseInt(argv[++i] ?? "", 10) || DEFAULT_LIMIT;
         break;
+      case "--offset":
+      case "-o":
+        options.offset = Math.max(
+          0,
+          parseInt(argv[++i] ?? "", 10) || 0
+        );
+        break;
       case "--title":
         options.title = argv[++i];
         break;
@@ -111,29 +118,39 @@ function parseArgs(argv) {
 }
 
 // src/shared/cli/functions/format-output.function.ts
-function formatOutput(results, format) {
+function formatOutput(paged, format) {
   switch (format) {
     case "json":
-      return JSON.stringify(results, null, 2);
+      return JSON.stringify(paged, null, 2);
     case "text":
-      return formatText(results);
+      return formatText(paged);
     case "mcp":
-      return formatMcp(results);
-  }
-}
-function formatText(results) {
-  if (results.length === 0) return "No results found.";
-  return results.map(
-    (r, i) => `${String(i + 1)}. [${r.kbid}] (score: ${r.score.toFixed(4)})
-   ${r.preview}
-   matches: ${r.matches.map((m) => m.term).join(", ")}`
-  ).join("\n\n");
-}
-function formatMcp(results) {
+      return formatMcp(paged);
+  }
+}
+function formatText(paged) {
+  if (paged.items.length === 0) return "No results found.";
+  const start = paged.offset + 1;
+  const end = paged.offset + paged.items.length;
+  const lines = paged.items.map((r, i) => {
+    const num = paged.offset + i + 1;
+    const heading = r.heading ?? "(untitled)";
+    const terms = r.matched_terms.join(", ");
+    return `${String(num)}. [${r.kbid}] ${heading} (score: ${r.score.toFixed(4)})
+   ${r.snippet || r.preview || "(no snippet)"}
+   type: ${r.type}  terms: ${terms}`;
+  }).join("\n\n");
+  const footer = `
+Showing ${String(start)}-${String(end)} of ${String(paged.total)} results`;
+  const hint = paged.has_more ? `
+Use --offset ${String(end)} to see more` : "";
+  return lines + footer + hint;
+}
+function formatMcp(paged) {
   return JSON.stringify({
     type: "text",
-    text: results.map(
-      (r) => `[${r.kbid}] score=${r.score.toFixed(4)} \u2014 ${r.preview}`
+    text: paged.items.map(
+      (r) => `[${r.kbid}] ${r.heading ?? "(untitled)"} \u2014 ${r.snippet || r.preview}`
     ).join("\n")
   });
 }
@@ -141,18 +158,37 @@ function formatMcp(results) {
 // src/shared/cli/functions/run-search.function.ts
 async function runSearch(client, options) {
   const query = options.args.join(" ").trim();
-  if (!query) return [];
+  if (!query) {
+    return {
+      items: [],
+      total: 0,
+      offset: 0,
+      limit: options.limit,
+      has_more: false
+    };
+  }
   const results = await client.search({
     query,
     mode: options.mode,
-    limit: options.limit
+    limit: options.limit,
+    offset: options.offset
   });
-  return results.map((r) => ({
-    kbid: r.kbid,
-    score: r.score,
-    preview: "",
-    matches: r.matches
-  }));
+  return {
+    items: results.items.map((r) => ({
+      kbid: r.kbid,
+      heading: r.heading,
+      type: r.type,
+      docids: r.docids,
+      score: r.score,
+      snippet: r.snippet,
+      matched_terms: r.matched_terms,
+      preview: ""
+    })),
+    total: results.total,
+    offset: results.offset,
+    limit: results.limit,
+    has_more: results.has_more
+  };
 }
 
 // src/shared/cli/functions/run-learn.function.ts
@@ -872,9 +908,9 @@ async function handleDbMigrate(client, options) {
     };
   }
 }
-async function hydrateSearchPreviews(client, results) {
+async function hydrateSearchPreviews(client, paged) {
   await Promise.all(
-    results.map(async (result) => {
+    paged.items.map(async (result) => {
       try {
         const contentResult = await client.content([result.kbid]);
         result.preview = contentResult.data;
@@ -885,7 +921,7 @@ async function hydrateSearchPreviews(client, results) {
 }
 
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.1.6";
+var VERSION = "0.2.0";
 
 // src/shared/cli/functions/generate-help.function.ts
 var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
@@ -1594,11 +1630,22 @@ var WorkerClient = class {
    * Searches the knowledge base.
    *
    * @param params - query parameters including the search string
-   * @returns ranked list of matching sections
+   * @returns paginated search results with metadata
    */
   async search(params) {
     return this.call("search", params);
   }
+  /**
+   * 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 `RecallResult` when `kbid` is provided without
+   *   `kbids`, or a `RecallResult[]` when `kbids` is provided
+   */
+  async recall(params) {
+    return this.call("recall", params);
+  }
   /**
    * Adds a new section to the knowledge base.
    *
@@ -2016,7 +2063,7 @@ function createToolDefinitions() {
   return [
     {
       name: "search",
-      description: "Search the knowledge base for relevant sections using natural language queries.",
+      description: "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: {
@@ -2032,6 +2079,10 @@ function createToolDefinitions() {
           limit: {
             type: "number",
             description: "Maximum results (default: 20)"
+          },
+          offset: {
+            type: "number",
+            description: "Number of results to skip for pagination (default: 0)"
           }
         },
         required: ["query"]
@@ -2040,7 +2091,8 @@ function createToolDefinitions() {
         title: "Search KB",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2076,7 +2128,8 @@ function createToolDefinitions() {
         title: "Import Content",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2096,12 +2149,13 @@ function createToolDefinitions() {
         title: "Remove Section",
         readOnlyHint: false,
         destructiveHint: true,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
       name: "retrieve",
-      description: "Retrieve a section or document by ID. Provide kbid or docid.",
+      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: {
@@ -2119,7 +2173,37 @@ function createToolDefinitions() {
         title: "Fetch Content",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        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
       }
     },
     {
@@ -2133,7 +2217,8 @@ function createToolDefinitions() {
         title: "DB Status",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2154,7 +2239,8 @@ function createToolDefinitions() {
         title: "Compose Content",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2168,7 +2254,8 @@ function createToolDefinitions() {
         title: "Integrity Check",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2182,7 +2269,8 @@ function createToolDefinitions() {
         title: "Garbage Collect",
         readOnlyHint: false,
         destructiveHint: true,
-        idempotentHint: false
+        idempotentHint: false,
+        openWorldHint: false
       }
     },
     {
@@ -2196,7 +2284,8 @@ function createToolDefinitions() {
         title: "Rebuild Indexes",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: false
+        idempotentHint: false,
+        openWorldHint: false
       }
     },
     {
@@ -2224,7 +2313,8 @@ function createToolDefinitions() {
         title: "Create Skill",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2238,7 +2328,8 @@ function createToolDefinitions() {
         title: "List Skills",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2261,7 +2352,8 @@ function createToolDefinitions() {
         title: "Get Skill",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2281,7 +2373,8 @@ function createToolDefinitions() {
         title: "Delete Skill",
         readOnlyHint: false,
         destructiveHint: true,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2314,7 +2407,8 @@ function createToolDefinitions() {
         title: "Create Agent",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2328,7 +2422,8 @@ function createToolDefinitions() {
         title: "List Agents",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2348,7 +2443,8 @@ function createToolDefinitions() {
         title: "Get Agent",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2368,7 +2464,8 @@ function createToolDefinitions() {
         title: "Delete Agent",
         readOnlyHint: false,
         destructiveHint: true,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     }
   ];
@@ -2569,6 +2666,33 @@ async function handleAgentDelete(client, args) {
   };
 }
 
+// src/shared/mcp/functions/handle-recall.function.ts
+async function handleRecall(client, args) {
+  const kbid = typeof args["kbid"] === "string" ? args["kbid"] : void 0;
+  const kbids = Array.isArray(args["kbids"]) && args["kbids"].every((item) => typeof item === "string") ? args["kbids"] : void 0;
+  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)
+      }
+    ]
+  };
+}
+
 // src/shared/mcp/functions/handle-tool-call.function.ts
 function asString2(value, fallback) {
   return typeof value === "string" ? value : fallback;
@@ -2590,6 +2714,8 @@ async function handleToolCall(client, name, args) {
         return await handleUnlearn2(client, args);
       case "retrieve":
         return await handleRetrieve(client, args);
+      case "recall":
+        return await handleRecall(client, args);
       case "status":
         return await handleStatus2(client);
       case "content":
@@ -2643,13 +2769,18 @@ async function handleSearch2(client, args) {
   const results = await client.search({
     query: asString2(args["query"], ""),
     mode: args["mode"],
-    limit: args["limit"]
+    limit: args["limit"],
+    offset: args["offset"]
   });
+  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)
       }
     ]
   };