research-powerpack-mcp 3.4.7 → 3.5.0

package/dist/tools/search.js

@@ -6,6 +6,7 @@ import { SearchClient } from '../clients/search.js';
 import { aggregateAndRank, buildUrlLookup, lookupUrl, generateEnhancedOutput, markConsensus, } from '../utils/url-aggregator.js';
 import { CTR_WEIGHTS } from '../config/index.js';
 import { classifyError } from '../utils/errors.js';
+import { safeLog, formatSuccess, formatError, formatDuration, } from './utils.js';
 function getPositionScore(position) {
     if (position >= 1 && position <= 10) {
         return CTR_WEIGHTS[position] ?? 0;
@@ -16,9 +17,7 @@ export async function handleWebSearch(params, options = {}) {
     const { sessionId, logger } = options;
     const startTime = Date.now();
     try {
-        if (sessionId && logger) {
-            await logger('info', `Searching for ${params.keywords.length} keyword(s)`, sessionId);
-        }
+        await safeLog(logger, sessionId, 'info', `Searching for ${params.keywords.length} keyword(s)`, 'WebSearch');
         const client = new SearchClient();
         const response = await client.searchMultiple(params.keywords);
         const aggregation = aggregateAndRank(response.searches, 5);
@@ -87,9 +86,19 @@ export async function handleWebSearch(params, options = {}) {
             markdown += `\n---\n\n> *${queriesOmitted} additional queries not shown. Consensus URLs above include all ${response.searches.length} queries.*\n`;
         }
         const executionTime = Date.now() - startTime;
-        if (sessionId && logger) {
-            await logger('info', `Search completed: ${totalResults} results, ${aggregation.totalUniqueUrls} unique URLs, ${consensusUrls.length} consensus URLs in ${executionTime}ms`, sessionId);
-        }
+        await safeLog(logger, sessionId, 'info', `Search completed: ${totalResults} results, ${aggregation.totalUniqueUrls} unique URLs, ${consensusUrls.length} consensus URLs in ${executionTime}ms`, 'WebSearch');
+        // Add next steps section
+        const nextSteps = [
+            `Scrape top URLs: \`scrape_links({urls: [${consensusUrls.slice(0, 3).map(u => `"${u.url}"`).join(', ')}], use_llm: true})\``,
+            'Use `deep_research()` for in-depth analysis of specific topics',
+            'Refine search with more specific keywords based on results',
+        ];
+        const formattedContent = formatSuccess({
+            title: `Web Search Results (${params.keywords.length} keywords)`,
+            summary: `**Found ${totalResults} results** across ${response.totalKeywords} queries\n• ${aggregation.totalUniqueUrls} unique URLs\n• ${consensusUrls.length} consensus URLs (appeared in ${aggregation.frequencyThreshold}+ searches)\n• Execution time: ${formatDuration(executionTime)}`,
+            data: markdown,
+            nextSteps,
+        });
         const metadata = {
             total_keywords: response.totalKeywords,
             total_results: totalResults,
@@ -98,20 +107,21 @@ export async function handleWebSearch(params, options = {}) {
             consensus_url_count: consensusUrls.length,
             frequency_threshold: aggregation.frequencyThreshold,
         };
-        return { content: markdown, structuredContent: { content: markdown, metadata } };
+        return { content: formattedContent, structuredContent: { content: formattedContent, metadata } };
     }
     catch (error) {
         // Classify error for better reporting
         const structuredError = classifyError(error);
-        const errorCode = structuredError.code;
-        if (sessionId && logger) {
-            await logger('error', `web_search: ${structuredError.message}`, sessionId);
-        }
+        await safeLog(logger, sessionId, 'error', `web_search: ${structuredError.message}`, 'WebSearch');
         const executionTime = Date.now() - startTime;
-        const retryHint = structuredError.retryable
-            ? '\n\n💡 This error may be temporary. Try again in a moment.'
-            : '';
-        const errorContent = `# ❌ web_search: Search Failed\n\n**${errorCode}:** ${structuredError.message}${retryHint}\n\n**Tip:** Make sure SERPER_API_KEY is set in your environment variables.`;
+        const errorContent = formatError({
+            code: structuredError.code,
+            message: structuredError.message,
+            retryable: structuredError.retryable,
+            toolName: 'web_search',
+            howToFix: ['Make sure SERPER_API_KEY is set in your environment variables'],
+            alternatives: ['Try search_reddit() for community discussions', 'Use deep_research() for AI-powered research'],
+        });
         return {
             content: errorContent,
             structuredContent: {
@@ -120,7 +130,7 @@ export async function handleWebSearch(params, options = {}) {
                     total_keywords: params.keywords.length,
                     total_results: 0,
                     execution_time_ms: executionTime,
-                    errorCode, // Include error code for programmatic handling
+                    errorCode: structuredError.code,
                 },
             },
         };

package/dist/tools/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"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"}

package/dist/tools/utils.d.ts

@@ -1,92 +1,53 @@
 /**
  * Shared Tool Utilities
- * Extracted from individual handlers to eliminate duplication
+ * Central module for common tool functionality
+ * Re-exports from specialized utility modules for backwards compatibility
  */
+export { safeLog, createToolLogger, type ToolLogger, type ToolOptions } from '../utils/logger.js';
+export { formatSuccess, formatError, formatBatchHeader, formatList, formatKeyValues, formatDuration, truncateText, type SuccessResponseOptions, type ErrorResponseOptions, type BatchResultOptions, } from '../utils/response.js';
 /**
- * Logger function type used by tools
+ * Token budgets for different tools
+ * Centralized here to ensure consistency
  */
-export type ToolLogger = (level: 'info' | 'error' | 'debug', message: string, sessionId: string) => Promise<void>;
-/**
- * Standard tool options passed to handlers
- */
-export interface ToolOptions {
-    sessionId?: string;
-    logger?: ToolLogger;
-}
-/**
- * Safe logger wrapper - NEVER throws
- * Logs to provided logger or falls back to console.error
- *
- * @param logger - Optional logger function
- * @param sessionId - Session ID for logging context
- * @param level - Log level
- * @param message - Message to log
- * @param toolName - Name of the tool for prefixing
- */
-export declare function safeLog(logger: ToolLogger | undefined, sessionId: string | undefined, level: 'info' | 'error' | 'debug', message: string, toolName: string): Promise<void>;
+export declare const TOKEN_BUDGETS: {
+    /** Total token budget for deep research */
+    readonly RESEARCH: 32000;
+    /** Total token budget for web scraping */
+    readonly SCRAPER: 32000;
+    /** Total token budget for Reddit post fetching */
+    readonly REDDIT: 1000;
+};
 /**
  * Calculate token allocation for batch operations
  * Distributes a fixed budget across multiple items
  *
  * @param count - Number of items to distribute budget across
- * @param budget - Total token budget
+ * @param budget - Total token budget (defaults to RESEARCH budget)
  * @returns Tokens per item
  */
-export declare function calculateTokenAllocation(count: number, budget: number): number;
+export declare function calculateTokenAllocation(count: number, budget?: number): number;
 /**
- * Format retry hint based on error retryability
- *
- * @param retryable - Whether the error is retryable
- * @returns Hint string or empty string
+ * @deprecated Use formatError from response.ts instead
  */
 export declare function formatRetryHint(retryable: boolean): string;
 /**
- * Create a standard error markdown response
- *
- * @param toolName - Name of the tool that errored
- * @param errorCode - Error code
- * @param message - Error message
- * @param retryable - Whether error is retryable
- * @param tip - Optional tip for resolution
- * @returns Formatted markdown error string
+ * @deprecated Use formatError from response.ts instead
  */
 export declare function formatToolError(toolName: string, errorCode: string, message: string, retryable: boolean, tip?: string): string;
 /**
  * Validate that a value is a non-empty array
- *
- * @param value - Value to check
- * @param fieldName - Field name for error message
- * @returns Error message or undefined if valid
  */
 export declare function validateNonEmptyArray(value: unknown, fieldName: string): string | undefined;
 /**
  * Validate array length is within bounds
- *
- * @param arr - Array to check
- * @param min - Minimum length
- * @param max - Maximum length
- * @param fieldName - Field name for error message
- * @returns Error message or undefined if valid
  */
 export declare function validateArrayBounds(arr: unknown[], min: number, max: number, fieldName: string): string | undefined;
 /**
- * Build standard header for batch operation results
- *
- * @param title - Title of the results section
- * @param count - Number of items processed
- * @param tokensPerItem - Tokens allocated per item
- * @param totalBudget - Total token budget
- * @returns Formatted header string
+ * @deprecated Use formatBatchHeader from response.ts instead
  */
 export declare function buildBatchHeader(title: string, count: number, tokensPerItem: number, totalBudget: number): string;
 /**
- * Build status line for batch results
- *
- * @param successful - Number of successful items
- * @param failed - Number of failed items
- * @param batches - Number of batches processed
- * @param extras - Optional extra status items
- * @returns Formatted status line
+ * @deprecated Use formatBatchHeader from response.ts instead
  */
 export declare function buildStatusLine(successful: number, failed: number, batches: number, extras?: string[]): string;
 //# sourceMappingURL=utils.d.ts.map

package/dist/tools/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAQf;AAMD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG9E;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAI1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,OAAO,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAIR;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EAAE,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAQpB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,MAAM,CAMR"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGlG,OAAO,EACL,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,cAAc,EACd,YAAY,EACZ,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAM9B;;;GAGG;AACH,eAAO,MAAM,aAAa;IACxB,2CAA2C;;IAE3C,0CAA0C;;IAE1C,kDAAkD;;CAE1C,CAAC;AAMX;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAA+B,GAAG,MAAM,CAGvG;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAI1D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,OAAO,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAIR;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAQpB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EAAE,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAQpB;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,MAAM,CAMR"}

package/dist/tools/utils.js

@@ -1,31 +1,27 @@
 /**
  * Shared Tool Utilities
- * Extracted from individual handlers to eliminate duplication
+ * Central module for common tool functionality
+ * Re-exports from specialized utility modules for backwards compatibility
  */
+// Re-export logging utilities from centralized module
+export { safeLog, createToolLogger } from '../utils/logger.js';
+// Re-export response formatting utilities
+export { formatSuccess, formatError, formatBatchHeader, formatList, formatKeyValues, formatDuration, truncateText, } from '../utils/response.js';
 // ============================================================================
-// Logging Utilities
+// Token Budget Constants
 // ============================================================================
 /**
- * Safe logger wrapper - NEVER throws
- * Logs to provided logger or falls back to console.error
- *
- * @param logger - Optional logger function
- * @param sessionId - Session ID for logging context
- * @param level - Log level
- * @param message - Message to log
- * @param toolName - Name of the tool for prefixing
+ * Token budgets for different tools
+ * Centralized here to ensure consistency
  */
-export async function safeLog(logger, sessionId, level, message, toolName) {
-    if (!logger || !sessionId)
-        return;
-    try {
-        await logger(level, `[${toolName}] ${message}`, sessionId);
-    }
-    catch {
-        // Silently ignore logger errors - they should never crash the tool
-        console.error(`[${toolName}] Logger failed: ${message}`);
-    }
-}
+export const TOKEN_BUDGETS = {
+    /** Total token budget for deep research */
+    RESEARCH: 32000,
+    /** Total token budget for web scraping */
+    SCRAPER: 32000,
+    /** Total token budget for Reddit post fetching */
+    REDDIT: 1000, // Comments budget
+};
 // ============================================================================
 // Token Allocation
 // ============================================================================
@@ -34,22 +30,19 @@ export async function safeLog(logger, sessionId, level, message, toolName) {
  * Distributes a fixed budget across multiple items
  *
  * @param count - Number of items to distribute budget across
- * @param budget - Total token budget
+ * @param budget - Total token budget (defaults to RESEARCH budget)
  * @returns Tokens per item
  */
-export function calculateTokenAllocation(count, budget) {
+export function calculateTokenAllocation(count, budget = TOKEN_BUDGETS.RESEARCH) {
     if (count <= 0)
         return budget;
     return Math.floor(budget / count);
 }
 // ============================================================================
-// Error Formatting
+// Legacy Error Formatting (deprecated - use response.ts instead)
 // ============================================================================
 /**
- * Format retry hint based on error retryability
- *
- * @param retryable - Whether the error is retryable
- * @returns Hint string or empty string
+ * @deprecated Use formatError from response.ts instead
  */
 export function formatRetryHint(retryable) {
     return retryable
@@ -57,14 +50,7 @@ export function formatRetryHint(retryable) {
         : '';
 }
 /**
- * Create a standard error markdown response
- *
- * @param toolName - Name of the tool that errored
- * @param errorCode - Error code
- * @param message - Error message
- * @param retryable - Whether error is retryable
- * @param tip - Optional tip for resolution
- * @returns Formatted markdown error string
+ * @deprecated Use formatError from response.ts instead
  */
 export function formatToolError(toolName, errorCode, message, retryable, tip) {
     const retryHint = formatRetryHint(retryable);
@@ -76,10 +62,6 @@ export function formatToolError(toolName, errorCode, message, retryable, tip) {
 // ============================================================================
 /**
  * Validate that a value is a non-empty array
- *
- * @param value - Value to check
- * @param fieldName - Field name for error message
- * @returns Error message or undefined if valid
  */
 export function validateNonEmptyArray(value, fieldName) {
     if (!Array.isArray(value)) {
@@ -92,12 +74,6 @@ export function validateNonEmptyArray(value, fieldName) {
 }
 /**
  * Validate array length is within bounds
- *
- * @param arr - Array to check
- * @param min - Minimum length
- * @param max - Maximum length
- * @param fieldName - Field name for error message
- * @returns Error message or undefined if valid
  */
 export function validateArrayBounds(arr, min, max, fieldName) {
     if (arr.length < min) {
@@ -109,28 +85,16 @@ export function validateArrayBounds(arr, min, max, fieldName) {
     return undefined;
 }
 // ============================================================================
-// Response Builders
+// Legacy Response Builders (deprecated - use response.ts instead)
 // ============================================================================
 /**
- * Build standard header for batch operation results
- *
- * @param title - Title of the results section
- * @param count - Number of items processed
- * @param tokensPerItem - Tokens allocated per item
- * @param totalBudget - Total token budget
- * @returns Formatted header string
+ * @deprecated Use formatBatchHeader from response.ts instead
  */
 export function buildBatchHeader(title, count, tokensPerItem, totalBudget) {
     return `# ${title} (${count} items)\n\n**Token Allocation:** ${tokensPerItem.toLocaleString()} tokens/item (${count} items, ${totalBudget.toLocaleString()} total budget)`;
 }
 /**
- * Build status line for batch results
- *
- * @param successful - Number of successful items
- * @param failed - Number of failed items
- * @param batches - Number of batches processed
- * @param extras - Optional extra status items
- * @returns Formatted status line
+ * @deprecated Use formatBatchHeader from response.ts instead
  */
 export function buildStatusLine(successful, failed, batches, extras) {
     let status = `**Status:** ✅ ${successful} successful | ❌ ${failed} failed | 📦 ${batches} batch(es)`;

package/dist/tools/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Centralized Logger Utilities
+ * Provides safe logging that NEVER throws - extracted from tool handlers
+ */
+/**
+ * Logger function type used across all tools
+ */
+export type ToolLogger = (level: 'info' | 'error' | 'debug', message: string, sessionId: string) => Promise<void>;
+/**
+ * Standard options passed to tool handlers
+ */
+export interface ToolOptions {
+    sessionId?: string;
+    logger?: ToolLogger;
+}
+/**
+ * Safe logger wrapper - NEVER throws
+ * Logs to provided logger or falls back to console.error
+ *
+ * @param logger - Optional logger function
+ * @param sessionId - Session ID for logging context
+ * @param level - Log level ('info' | 'error' | 'debug')
+ * @param message - Message to log
+ * @param toolName - Name of the tool for prefixing (optional)
+ */
+export declare function safeLog(logger: ToolLogger | undefined, sessionId: string | undefined, level: 'info' | 'error' | 'debug', message: string, toolName?: string): Promise<void>;
+/**
+ * Create a bound logger for a specific tool
+ * Returns a simpler function that only needs level and message
+ *
+ * @param options - Tool options containing logger and sessionId
+ * @param toolName - Name of the tool for log prefixing
+ * @returns Bound log function
+ */
+export declare function createToolLogger(options: ToolOptions, toolName: string): (level: 'info' | 'error' | 'debug', message: string) => Promise<void>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EACjC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,GACf,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAIvE"}

package/dist/utils/logger.js

@@ -0,0 +1,40 @@
+/**
+ * Centralized Logger Utilities
+ * Provides safe logging that NEVER throws - extracted from tool handlers
+ */
+/**
+ * Safe logger wrapper - NEVER throws
+ * Logs to provided logger or falls back to console.error
+ *
+ * @param logger - Optional logger function
+ * @param sessionId - Session ID for logging context
+ * @param level - Log level ('info' | 'error' | 'debug')
+ * @param message - Message to log
+ * @param toolName - Name of the tool for prefixing (optional)
+ */
+export async function safeLog(logger, sessionId, level, message, toolName) {
+    if (!logger || !sessionId)
+        return;
+    const prefix = toolName ? `[${toolName}] ` : '';
+    try {
+        await logger(level, `${prefix}${message}`, sessionId);
+    }
+    catch {
+        // Silently ignore logger errors - they should never crash the tool
+        console.error(`${prefix}Logger failed: ${message}`);
+    }
+}
+/**
+ * Create a bound logger for a specific tool
+ * Returns a simpler function that only needs level and message
+ *
+ * @param options - Tool options containing logger and sessionId
+ * @param toolName - Name of the tool for log prefixing
+ * @returns Bound log function
+ */
+export function createToolLogger(options, toolName) {
+    return async (level, message) => {
+        await safeLog(options.logger, options.sessionId, level, message, toolName);
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmBH;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,MAA8B,EAC9B,SAA6B,EAC7B,KAAiC,EACjC,OAAe,EACf,QAAiB;IAEjB,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS;QAAE,OAAO;IAElC,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAEhD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,EAAE,GAAG,MAAM,GAAG,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,kBAAkB,OAAO,EAAE,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAoB,EACpB,QAAgB;IAEhB,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC9B,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC7E,CAAC,CAAC;AACJ,CAAC"}

package/dist/utils/response.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Standardized Response Formatting for MCP Tools
+ * Implements the 70/20/10 pattern for agent-optimized responses
+ *
+ * 70% Summary - Key insights, status, metrics
+ * 20% Data - Structured results
+ * 10% Next Steps - Actionable follow-ups
+ */
+export interface SuccessResponseOptions {
+    /** Main title for the response */
+    title: string;
+    /** Summary section (70% of response) */
+    summary: string;
+    /** Optional data section (20% of response) */
+    data?: string;
+    /** Optional next steps (10% of response) */
+    nextSteps?: string[];
+    /** Optional metadata to append */
+    metadata?: Record<string, string | number>;
+}
+export interface ErrorResponseOptions {
+    /** Error code (e.g., RATE_LIMITED, TIMEOUT) */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Whether the error is retryable */
+    retryable?: boolean;
+    /** Steps to fix the error */
+    howToFix?: string[];
+    /** Alternative actions to try */
+    alternatives?: string[];
+    /** Tool name for context */
+    toolName?: string;
+}
+export interface BatchResultOptions {
+    /** Title for the batch results */
+    title: string;
+    /** Number of items processed */
+    totalItems: number;
+    /** Number of successful items */
+    successful: number;
+    /** Number of failed items */
+    failed: number;
+    /** Tokens allocated per item */
+    tokensPerItem?: number;
+    /** Total token budget */
+    totalBudget?: number;
+    /** Number of batches processed */
+    batches?: number;
+    /** Additional status items */
+    extras?: string[];
+}
+/**
+ * Format a successful tool response using the 70/20/10 pattern
+ *
+ * @example
+ * formatSuccess({
+ *   title: 'Web Search Results',
+ *   summary: '**Found 45 unique URLs** across 5 queries\n• 12 consensus results (appeared 3+ times)\n• Top domains: github.com, stackoverflow.com',
+ *   data: '## Top Results\n1. [Title](url) - snippet\n2. ...',
+ *   nextSteps: ['Scrape top URLs: scrape_links({urls: [...]})', 'Deep dive: deep_research({...})']
+ * })
+ */
+export declare function formatSuccess(options: SuccessResponseOptions): string;
+/**
+ * Format an error response with recovery guidance
+ *
+ * @example
+ * formatError({
+ *   code: 'RATE_LIMITED',
+ *   message: 'API rate limit exceeded',
+ *   retryable: true,
+ *   howToFix: ['Wait 60 seconds', 'Reduce batch size'],
+ *   alternatives: ['Use cached results', 'Try different API']
+ * })
+ */
+export declare function formatError(options: ErrorResponseOptions): string;
+/**
+ * Format batch operation header with status
+ */
+export declare function formatBatchHeader(options: BatchResultOptions): string;
+/**
+ * Format a list of items with optional truncation
+ */
+export declare function formatList(items: string[], options?: {
+    maxItems?: number;
+    ordered?: boolean;
+}): string;
+/**
+ * Format key-value pairs as a compact list
+ */
+export declare function formatKeyValues(data: Record<string, unknown>): string;
+/**
+ * Format execution time
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Truncate text with ellipsis
+ */
+export declare function truncateText(text: string, maxLength: number): string;
+//# sourceMappingURL=response.d.ts.map

package/dist/utils/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,iCAAiC;IACjC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAyCrE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAwCjE;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAwBrE;AAMD;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACjD,MAAM,CAeR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAKrE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGpE"}