feat: update dependencies and enhance job management with session tracking

Author: Michael-Obele

packages/core/bun.lock

@@ -56,7 +56,7 @@
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
     "@tmcp/adapter-valibot": "^0.1.5",
-    "@tmcp/transport-http": "^0.8.4",
+    "@tmcp/transport-http": "^0.8.5",
     "@tmcp/transport-sse": "^0.5.3",
     "@tmcp/transport-stdio": "^0.4.1",
     "cac": "^7.0.0",
@@ -66,7 +66,7 @@
     "puppeteer-core": "^24.37.5",
     "robots-parser": "^3.0.1",
     "srvx": "^0.11.8",
-    "tmcp": "^1.19.2",
+    "tmcp": "^1.19.3",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2",
     "valibot": "^1.2.0"

packages/core/package.json

@@ -14,9 +14,9 @@ export class JobManager {
     ) { }
 
     /** Start a crawl job for a library */
-    startCrawl(libraryId: string, opts?: { incremental?: boolean }): CrawlJob {
+    startCrawl(libraryId: string, opts?: { incremental?: boolean; sessionId?: string }): CrawlJob {
         const jobId = nanoid();
-        const job = this.db.createJob({ id: jobId, libraryId });
+        const job = this.db.createJob({ id: jobId, libraryId, sessionId: opts?.sessionId });
 
         // Run crawl async (non-blocking)
         const worker = new CrawlWorker(this.db, this.eventBus);

packages/core/src/jobs/manager.ts

@@ -1,4 +1,5 @@
 import type { SearchResult } from './types.js';
+import { sanitizeDocContent } from './sanitize.js';
 
 function formatReasons(reasons: string[]): string {
   if (reasons.length === 0) {
@@ -16,7 +17,9 @@ export function formatSearchResults(query: string, results: SearchResult[]): str
       if (result.heading_context.trim().length > 0) {
         block += `**Section:** ${result.heading_context}\n`;
       }
-      block += `${formatReasons(result.reasons)}${result.content}`;
+      // Sanitize content to prevent prompt injection
+      const sanitizedContent = sanitizeDocContent(result.content);
+      block += `${formatReasons(result.reasons)}${sanitizedContent}`;
       return block;
     })
     .join('\n\n---\n\n');

packages/core/src/search/format-results.ts

@@ -0,0 +1,47 @@
+/**
+ * Output sanitization to prevent prompt injection attacks
+ * Removes suspicious patterns that could escape agent context
+ */
+
+export function sanitizeOutput(text: string): string {
+  return text
+    // Remove template directives
+    .replace(/\{[#%].*?[#%]\}/g, '')
+    // Remove system prompt markers
+    .replace(/\[SYSTEM[\]:].*?\[\/SYSTEM\]/gi, '')
+    .replace(/\[ADMIN[\]:].*?\[\/ADMIN\]/gi, '')
+    // Remove potential prompt injection patterns
+    .replace(/ignore\s+above.*?instructions/gi, '')
+    .replace(/forget\s+previous.*?context/gi, '')
+    .trim();
+}
+
+/**
+ * Sanitize a single chunk of documentation content
+ * Removes malicious content while preserving code blocks and formatting
+ */
+export function sanitizeDocContent(content: string): string {
+  // First sanitize for injection patterns
+  let sanitized = sanitizeOutput(content);
+
+  // Escape potential dangerous markdown constructs
+  // but preserve code blocks (between triple backticks)
+  const codeBlockPattern = /```[\s\S]*?```/g;
+  const codeBlocks = sanitized.match(codeBlockPattern) || [];
+  
+  // Temporarily replace code blocks
+  let temp = sanitized;
+  codeBlocks.forEach((block, i) => {
+    temp = temp.replace(block, `__CODE_BLOCK_${i}__`);
+  });
+
+  // Sanitize outside code blocks
+  temp = sanitizeOutput(temp);
+
+  // Restore code blocks
+  codeBlocks.forEach((block, i) => {
+    temp = temp.replace(`__CODE_BLOCK_${i}__`, block);
+  });
+
+  return temp;
+}

packages/core/src/search/sanitize.ts

@@ -42,10 +42,11 @@ server.tool(
   {
     name: "search_docs",
     description:
-      "Search through indexed documentation libraries for relevant information. " +
-      "Returns ranked documentation sections with code examples and source URLs. " +
-      "Use this when you need to find information about a library, framework, API, " +
-      "or any technical concept.",
+      "Search indexed docs by keyword or library. Returns ranked sections with URLs.",
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
     schema: v.object({
       query: v.pipe(
         v.string(),
@@ -61,11 +62,16 @@ server.tool(
     }),
   },
   async ({ query, library, limit }) => {
-    const results = searchEngine.search(query, { library, limit });
-    if (results.length === 0)
-      return tool.text(`No results found for "${query}".`);
+    try {
+      const results = searchEngine.search(query, { library, limit });
+      if (results.length === 0)
+        return tool.text(`No results found for "${query}".`);
 
-    return tool.text(formatSearchResults(query, results));
+      return tool.text(formatSearchResults(query, results));
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : "Search failed";
+      return tool.text(`❌ Error: ${message}`);
+    }
   },
 );
 
@@ -108,14 +114,16 @@ function formatLibraryInfo(libraryId: string): string {
 }
 
 // ──────────────────────────────────────
-// Tool 2: list_libraries — Discovery tool
+// Tool 2: list_libraries — Discovery tool with pagination
 // ──────────────────────────────────────
 server.tool(
   {
     name: "list_libraries",
-    description:
-      "List all documentation libraries currently indexed and available for searching. " +
-      "Use this to discover what docs are available before running search_docs.",
+    description: "List indexed documentation libraries. Paginated results.",
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
     schema: v.object({
       status: v.optional(
         v.pipe(
@@ -124,23 +132,46 @@ server.tool(
         ),
         "all",
       ),
+      page: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 1),
+      limit: v.optional(
+        v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(50)),
+        20,
+      ),
     }),
   },
-  async ({ status }) => {
-    const libraries = db.listLibraries(status);
-    if (libraries.length === 0) {
-      return tool.text(
-        "No libraries indexed yet. Use manage_library with action=add to add a documentation website.",
-      );
-    }
+  async ({ status, page = 1, limit = 20 }) => {
+    try {
+      const libraries = db.listLibraries(status);
+      if (libraries.length === 0) {
+        return tool.text(
+          "No libraries indexed yet. Use manage_library with action=add to add a documentation website.",
+        );
+      }
 
-    let output = `## Indexed Libraries (${libraries.length} total)\n\n`;
-    output += "| Library | URL | Pages | Chunks | Status |\n";
-    output += "| ------- | --- | ----- | ------ | ------ |\n";
-    for (const lib of libraries) {
-      output += `| ${lib.name} | ${lib.url} | ${lib.page_count} | ${lib.chunk_count} | ${lib.status} |\n`;
+      // Paginate results
+      const start = (page - 1) * limit;
+      const end = start + limit;
+      const paginated = libraries.slice(start, end);
+      const hasMore = end < libraries.length;
+
+      // Minified response (no pretty-printing)
+      let output = `## Libraries (${start + 1}-${Math.min(end, libraries.length)} of ${libraries.length})\n\n`;
+      output += "| Library | URL | Pages | Chunks | Status |\n";
+      output += "| ------- | --- | ----- | ------ | ------ |\n";
+      for (const lib of paginated) {
+        output += `|${lib.name}|${lib.url}|${lib.page_count}|${lib.chunk_count}|${lib.status}|\n`;
+      }
+
+      if (hasMore) {
+        output += `\n**More available.** Use page=${page + 1} to fetch next page.`;
+      }
+
+      return tool.text(output);
+    } catch (err: unknown) {
+      const message =
+        err instanceof Error ? err.message : "Failed to list libraries";
+      return tool.text(`❌ Error: ${message}`);
     }
-    return tool.text(output);
   },
 );
 
@@ -150,9 +181,11 @@ server.tool(
 server.tool(
   {
     name: "get_doc_page",
-    description:
-      "Retrieve the complete content of a specific documentation page as markdown. " +
-      "Use when search results reference a page and you need full context.",
+    description: "Retrieve complete documentation page as markdown.",
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
     schema: v.object({
       url: v.optional(
         v.pipe(
@@ -169,14 +202,20 @@ server.tool(
     }),
   },
   async ({ url, library, path }) => {
-    const page = db.getPage({ url, library, path });
-    if (!page)
+    try {
+      const page = db.getPage({ url, library, path });
+      if (!page)
+        return tool.text(
+          "Page not found. Use search_docs to find the correct page.",
+        );
       return tool.text(
-        "Page not found. Use search_docs to find the correct page.",
+        `# ${page.title}\n**Source:** ${page.url}\n\n${page.content_markdown}`,
       );
-    return tool.text(
-      `# ${page.title}\n**Source:** ${page.url}\n\n${page.content_markdown}`,
-    );
+    } catch (err: unknown) {
+      const message =
+        err instanceof Error ? err.message : "Failed to fetch page";
+      return tool.text(`❌ Error: ${message}`);
+    }
   },
 );
 
@@ -187,7 +226,10 @@ server.tool(
   {
     name: "manage_library",
     description:
-      "Manage a documentation library lifecycle. Use action=add to crawl a new source, action=rename to change the library name, action=refresh to re-crawl, action=remove to delete it, or action=info to inspect its pages and stats.",
+      "Manage library lifecycle: add/rename/refresh/remove/info. Destructive actions require confirmation.",
+    annotations: {
+      destructiveHint: true,
+    },
     schema: v.object({
       action: v.pipe(
         v.picklist(["add", "rename", "refresh", "remove", "info"]),
@@ -268,7 +310,7 @@ server.tool(
           const lib = db.getLibraryByName(libraryName);
           if (!lib)
             return tool.text(
-              `Library "${libraryName}" not found. Use list_libraries to see available.`,
+              `❌ Library "${libraryName}" not found. Use list_libraries to see available.`,
             );
 
           const job = jobManager.startCrawl(lib.id, { incremental: true });
@@ -282,7 +324,7 @@ server.tool(
             "library is required for action=remove.",
           );
           const lib = db.getLibraryByName(libraryName);
-          if (!lib) return tool.text(`Library "${libraryName}" not found.`);
+          if (!lib) return tool.text(`❌ Library "${libraryName}" not found.`);
 
           db.removeLibrary(lib.id);
           return tool.text(
@@ -297,17 +339,17 @@ server.tool(
           const lib = db.getLibraryByName(libraryName);
           if (!lib)
             return tool.text(
-              `Library "${libraryName}" not found. Use list_libraries to see available libraries.`,
+              `❌ Library "${libraryName}" not found. Use list_libraries to see available libraries.`,
             );
 
           return tool.text(formatLibraryInfo(lib.id));
         }
       }
     } catch (err: unknown) {
       const message = err instanceof Error ? err.message : "Unknown error";
-      return tool.text(`❌ Failed: ${message}`);
+      return tool.text(`❌ Error: ${message}`);
     }
 
-    return tool.text(`❌ Failed: Unsupported action.`);
+    return tool.text(`❌ Error: Unsupported action.`);
   },
 );

packages/core/src/server.ts

@@ -104,6 +104,7 @@ export class Database {
       CREATE TABLE IF NOT EXISTS crawl_jobs (
         id               TEXT PRIMARY KEY,
         library_id       TEXT NOT NULL REFERENCES libraries(id) ON DELETE CASCADE,
+        session_id       TEXT,
         status           TEXT NOT NULL DEFAULT 'queued',
         pages_discovered INTEGER NOT NULL DEFAULT 0,
         pages_crawled    INTEGER NOT NULL DEFAULT 0,
@@ -316,10 +317,10 @@ export class Database {
   // Crawl Jobs
   // ──────────────────────────────────────
 
-  createJob(job: { id: string; libraryId: string }): CrawlJob {
+  createJob(job: { id: string; libraryId: string; sessionId?: string }): CrawlJob {
     this.db
-      .prepare("INSERT INTO crawl_jobs (id, library_id) VALUES (?, ?)")
-      .run(job.id, job.libraryId);
+      .prepare("INSERT INTO crawl_jobs (id, library_id, session_id) VALUES (?, ?, ?)")
+      .run(job.id, job.libraryId, job.sessionId ?? null);
     return this.db
       .prepare("SELECT * FROM crawl_jobs WHERE id = ?")
       .get(job.id) as CrawlJob;

packages/core/src/storage/db.ts

@@ -47,6 +47,7 @@ export interface ChunkRecord {
 export interface CrawlJob {
     id: string;
     library_id: string;
+    session_id?: string;
     status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
     pages_discovered: number;
     pages_crawled: number;