mcp-researchpowerpack-http 3.10.0

package/dist/src/tools/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/tools/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAiBlC,OAAO,EAML,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAgK1B,wBAAsB,eAAe,CACnC,MAAM,EAAE,eAAe,EACvB,QAAQ,GAAE,YAA4B,GACrC,OAAO,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC,CAmC/C;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4B7D"}

package/dist/src/tools/search.js

@@ -0,0 +1,197 @@
+import { getCapabilities, getMissingEnvMessage } from "../config/index.js";
+import {
+  webSearchOutputSchema,
+  webSearchParamsSchema
+} from "../schemas/web-search.js";
+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 {
+  mcpLog,
+  formatError,
+  formatDuration
+} from "./utils.js";
+import {
+  createToolReporter,
+  NOOP_REPORTER,
+  toolFailure,
+  toolSuccess,
+  toToolResponse
+} from "./mcp-helpers.js";
+function getPositionScore(position) {
+  if (position >= 1 && position <= 10) {
+    return CTR_WEIGHTS[position] ?? 0;
+  }
+  return Math.max(0, 10 - (position - 10) * 0.5);
+}
+async function executeSearches(keywords) {
+  const client = new SearchClient();
+  return client.searchMultiple(keywords);
+}
+function processAndRankResults(response) {
+  const aggregation = aggregateAndRank(response.searches, 5);
+  const urlLookup = buildUrlLookup(aggregation.rankedUrls);
+  const consensusUrls = aggregation.rankedUrls.filter((u) => u.isConsensus);
+  return { aggregation, urlLookup, consensusUrls };
+}
+function buildConsensusSection(keywords, aggregation) {
+  return generateEnhancedOutput(
+    aggregation.rankedUrls,
+    keywords,
+    aggregation.totalUniqueUrls,
+    aggregation.frequencyThreshold,
+    aggregation.thresholdNote
+  ) + "\n---\n\n";
+}
+function formatSearchResultEntry(result, position, urlLookup) {
+  const positionScore = getPositionScore(position);
+  const rankedUrl = lookupUrl(result.link, urlLookup);
+  const frequency = rankedUrl?.frequency ?? 1;
+  const consensusMark = markConsensus(frequency);
+  const consensusInfo = rankedUrl ? `${consensusMark} (${frequency} searches)` : `${consensusMark} (1 search)`;
+  let entry = `${position}. **[${result.title}](${result.link})** \u2014 Position ${position} | Score: ${positionScore.toFixed(1)} | Consensus: ${consensusInfo}
+`;
+  if (result.snippet) {
+    entry += result.date ? `   - *${result.date}* \u2014 ${result.snippet}
+` : `   - ${result.snippet}
+`;
+  }
+  entry += "\n";
+  return entry;
+}
+function buildPerQuerySection(response, urlLookup) {
+  let markdown = `## \u{1F4CA} Full Search Results by Query
+
+`;
+  let totalResults = 0;
+  response.searches.forEach((search, index) => {
+    markdown += `### Query ${index + 1}: "${search.keyword}"
+
+`;
+    search.results.forEach((result, resultIndex) => {
+      markdown += formatSearchResultEntry(result, resultIndex + 1, urlLookup);
+      totalResults++;
+    });
+    if (search.related && search.related.length > 0) {
+      const relatedSuggestions = search.related.map((r) => `\`${r}\``).join(", ");
+      markdown += `*Related:* ${relatedSuggestions}
+
+`;
+    }
+    if (index < response.searches.length - 1) markdown += `---
+
+`;
+  });
+  return { markdown, totalResults };
+}
+function formatSearchOutput(consensusSection, perQuerySection, totalResults, aggregation, consensusUrlCount, executionTime, totalKeywords) {
+  let markdown = consensusSection + perQuerySection;
+  markdown += `
+---
+*${formatDuration(executionTime)} | ${aggregation.totalUniqueUrls} unique URLs | ${consensusUrlCount} consensus*`;
+  const metadata = {
+    total_keywords: totalKeywords,
+    total_results: totalResults,
+    execution_time_ms: executionTime,
+    total_unique_urls: aggregation.totalUniqueUrls,
+    consensus_url_count: consensusUrlCount,
+    frequency_threshold: aggregation.frequencyThreshold
+  };
+  return toolSuccess(markdown, { content: markdown, metadata });
+}
+function buildWebSearchError(error, params, startTime) {
+  const structuredError = classifyError(error);
+  const executionTime = Date.now() - startTime;
+  mcpLog("error", `web-search: ${structuredError.message}`, "search");
+  const errorContent = formatError({
+    code: structuredError.code,
+    message: structuredError.message,
+    retryable: structuredError.retryable,
+    toolName: "web-search",
+    howToFix: ["Verify SERPER_API_KEY is set correctly"],
+    alternatives: [
+      'search-reddit(queries=["topic recommendations", "topic best practices", "topic vs alternatives"]) \u2014 Reddit search uses the same API but may work; also provides community perspective',
+      'deep-research(questions=[{question: "What are the key findings, best practices, and recommendations for [topic]?"}]) \u2014 uses OpenRouter API (different key), not affected by this error',
+      "scrape-links(urls=[...any URLs you already have...], use_llm=true) \u2014 if you have URLs from prior steps, scrape them now instead of searching"
+    ]
+  });
+  return toolFailure(
+    `${errorContent}
+
+Execution time: ${formatDuration(executionTime)}
+Keywords: ${params.keywords.length}`
+  );
+}
+async function handleWebSearch(params, reporter = NOOP_REPORTER) {
+  const startTime = Date.now();
+  try {
+    mcpLog("info", `Searching for ${params.keywords.length} keyword(s)`, "search");
+    await reporter.log("info", `Searching for ${params.keywords.length} keyword(s)`);
+    await reporter.progress(15, 100, "Submitting search queries");
+    const response = await executeSearches(params.keywords);
+    await reporter.progress(50, 100, "Collected search results");
+    const { aggregation, urlLookup, consensusUrls } = processAndRankResults(response);
+    await reporter.log(
+      "info",
+      `Collected ${aggregation.totalUniqueUrls} unique URLs across ${response.totalKeywords} queries`
+    );
+    const consensusSection = buildConsensusSection(params.keywords, aggregation);
+    const { markdown: perQuerySection, totalResults } = buildPerQuerySection(response, urlLookup);
+    await reporter.progress(80, 100, "Ranking and formatting search results");
+    const executionTime = Date.now() - startTime;
+    mcpLog("info", `Search completed: ${totalResults} results, ${aggregation.totalUniqueUrls} unique URLs, ${consensusUrls.length} consensus`, "search");
+    await reporter.log(
+      "info",
+      `Search completed with ${totalResults} ranked results and ${consensusUrls.length} consensus URL(s)`
+    );
+    return formatSearchOutput(
+      consensusSection,
+      perQuerySection,
+      totalResults,
+      aggregation,
+      consensusUrls.length,
+      executionTime,
+      response.totalKeywords
+    );
+  } catch (error) {
+    return buildWebSearchError(error, params, startTime);
+  }
+}
+function registerWebSearchTool(server) {
+  server.tool(
+    {
+      name: "web-search",
+      title: "Web Search",
+      description: "Run parallel Google searches across 1\u2013100 keywords and return CTR-weighted, consensus-ranked URLs for follow-up scraping. This is a bulk discovery tool \u2014 supply 3\u20137 keywords for solid consensus detection, or up to 100 for exhaustive coverage. Each keyword runs as a separate Google search; results are aggregated, scored by search position, and URLs appearing across multiple queries are flagged as high-confidence. Output is a ranked URL list ready to pipe into scrape-links or get-reddit-post.",
+      schema: webSearchParamsSchema,
+      outputSchema: webSearchOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: true
+      }
+    },
+    async (args, ctx) => {
+      if (!getCapabilities().search) {
+        return toToolResponse(toolFailure(getMissingEnvMessage("search")));
+      }
+      const reporter = createToolReporter(ctx, "web-search");
+      const result = await handleWebSearch(args, reporter);
+      await reporter.progress(100, 100, result.isError ? "Search failed" : "Search complete");
+      return toToolResponse(result);
+    }
+  );
+}
+export {
+  handleWebSearch,
+  registerWebSearchTool
+};
+//# sourceMappingURL=search.js.map

package/dist/src/tools/search.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/tools/search.ts"],
+  "sourcesContent": ["/**\n * Web Search Tool Handler\n * NEVER throws - always returns structured response for graceful degradation\n */\n\nimport type { MCPServer } from 'mcp-use/server';\n\nimport { getCapabilities, getMissingEnvMessage } from '../config/index.js';\nimport {\n  webSearchOutputSchema,\n  webSearchParamsSchema,\n  type WebSearchParams,\n  type WebSearchOutput,\n} from '../schemas/web-search.js';\nimport { SearchClient } from '../clients/search.js';\nimport {\n  aggregateAndRank,\n  buildUrlLookup,\n  lookupUrl,\n  generateEnhancedOutput,\n  markConsensus,\n} from '../utils/url-aggregator.js';\nimport { CTR_WEIGHTS } from '../config/index.js';\nimport { classifyError } from '../utils/errors.js';\nimport {\n  mcpLog,\n  formatSuccess,\n  formatError,\n  formatDuration,\n} from './utils.js';\nimport {\n  createToolReporter,\n  NOOP_REPORTER,\n  toolFailure,\n  toolSuccess,\n  toToolResponse,\n  type ToolExecutionResult,\n  type ToolReporter,\n} from './mcp-helpers.js';\n\nfunction getPositionScore(position: number): number {\n  if (position >= 1 && position <= 10) {\n    return CTR_WEIGHTS[position] ?? 0;\n  }\n  return Math.max(0, 10 - (position - 10) * 0.5);\n}\n\n// --- Internal types ---\n\ninterface SearchAggregation {\n  readonly rankedUrls: ReturnType<typeof aggregateAndRank>['rankedUrls'];\n  readonly totalUniqueUrls: number;\n  readonly frequencyThreshold: number;\n  readonly thresholdNote?: string;\n}\n\ninterface SearchResponse {\n  searches: Parameters<typeof aggregateAndRank>[0];\n  totalKeywords: number;\n}\n\n// --- Helpers ---\n\nasync function executeSearches(keywords: string[]): Promise<SearchResponse> {\n  const client = new SearchClient();\n  return client.searchMultiple(keywords);\n}\n\nfunction processAndRankResults(response: SearchResponse): {\n  aggregation: SearchAggregation;\n  urlLookup: ReturnType<typeof buildUrlLookup>;\n  consensusUrls: SearchAggregation['rankedUrls'];\n} {\n  const aggregation = aggregateAndRank(response.searches, 5);\n  // Build lookup from ALL ranked URLs so per-query entries can show consensus info\n  const urlLookup = buildUrlLookup(aggregation.rankedUrls);\n  const consensusUrls = aggregation.rankedUrls.filter(u => u.isConsensus);\n  return { aggregation, urlLookup, consensusUrls };\n}\n\nfunction buildConsensusSection(\n  keywords: string[],\n  aggregation: SearchAggregation,\n): string {\n  // Always show all ranked URLs (consensus-marked within)\n  return generateEnhancedOutput(\n    aggregation.rankedUrls, keywords, aggregation.totalUniqueUrls,\n    aggregation.frequencyThreshold, aggregation.thresholdNote,\n  ) + '\\n---\\n\\n';\n}\n\nfunction formatSearchResultEntry(\n  result: { title: string; link: string; snippet?: string; date?: string },\n  position: number,\n  urlLookup: ReturnType<typeof buildUrlLookup>,\n): string {\n  const positionScore = getPositionScore(position);\n  const rankedUrl = lookupUrl(result.link, urlLookup);\n  const frequency = rankedUrl?.frequency ?? 1;\n  const consensusMark = markConsensus(frequency);\n  const consensusInfo = rankedUrl\n    ? `${consensusMark} (${frequency} searches)`\n    : `${consensusMark} (1 search)`;\n\n  let entry = `${position}. **[${result.title}](${result.link})** \u2014 Position ${position} | Score: ${positionScore.toFixed(1)} | Consensus: ${consensusInfo}\\n`;\n\n  if (result.snippet) {\n    entry += result.date\n      ? `   - *${result.date}* \u2014 ${result.snippet}\\n`\n      : `   - ${result.snippet}\\n`;\n  }\n\n  entry += '\\n';\n  return entry;\n}\n\nfunction buildPerQuerySection(\n  response: SearchResponse,\n  urlLookup: ReturnType<typeof buildUrlLookup>,\n): { markdown: string; totalResults: number } {\n  let markdown = `## \uD83D\uDCCA Full Search Results by Query\\n\\n`;\n\n  let totalResults = 0;\n\n  response.searches.forEach((search, index) => {\n    markdown += `### Query ${index + 1}: \"${search.keyword}\"\\n\\n`;\n\n    search.results.forEach((result, resultIndex) => {\n      markdown += formatSearchResultEntry(result, resultIndex + 1, urlLookup);\n      totalResults++;\n    });\n\n    if (search.related && search.related.length > 0) {\n      const relatedSuggestions = search.related\n        .map((r: string) => `\\`${r}\\``)\n        .join(', ');\n      markdown += `*Related:* ${relatedSuggestions}\\n\\n`;\n    }\n\n    if (index < response.searches.length - 1) markdown += `---\\n\\n`;\n  });\n\n  return { markdown, totalResults };\n}\n\nfunction formatSearchOutput(\n  consensusSection: string,\n  perQuerySection: string,\n  totalResults: number,\n  aggregation: SearchAggregation,\n  consensusUrlCount: number,\n  executionTime: number,\n  totalKeywords: number,\n): ToolExecutionResult<WebSearchOutput> {\n  let markdown = consensusSection + perQuerySection;\n\n  markdown += `\\n---\\n*${formatDuration(executionTime)} | ${aggregation.totalUniqueUrls} unique URLs | ${consensusUrlCount} consensus*`;\n\n  const metadata = {\n    total_keywords: totalKeywords,\n    total_results: totalResults,\n    execution_time_ms: executionTime,\n    total_unique_urls: aggregation.totalUniqueUrls,\n    consensus_url_count: consensusUrlCount,\n    frequency_threshold: aggregation.frequencyThreshold,\n  };\n\n  return toolSuccess(markdown, { content: markdown, metadata });\n}\n\nfunction buildWebSearchError(\n  error: unknown,\n  params: WebSearchParams,\n  startTime: number,\n): ToolExecutionResult<WebSearchOutput> {\n  const structuredError = classifyError(error);\n  const executionTime = Date.now() - startTime;\n\n  mcpLog('error', `web-search: ${structuredError.message}`, 'search');\n\n  const errorContent = formatError({\n    code: structuredError.code,\n    message: structuredError.message,\n    retryable: structuredError.retryable,\n    toolName: 'web-search',\n    howToFix: ['Verify SERPER_API_KEY is set correctly'],\n    alternatives: [\n      'search-reddit(queries=[\"topic recommendations\", \"topic best practices\", \"topic vs alternatives\"]) \u2014 Reddit search uses the same API but may work; also provides community perspective',\n      'deep-research(questions=[{question: \"What are the key findings, best practices, and recommendations for [topic]?\"}]) \u2014 uses OpenRouter API (different key), not affected by this error',\n      'scrape-links(urls=[...any URLs you already have...], use_llm=true) \u2014 if you have URLs from prior steps, scrape them now instead of searching',\n    ],\n  });\n\n  return toolFailure(\n    `${errorContent}\\n\\nExecution time: ${formatDuration(executionTime)}\\nKeywords: ${params.keywords.length}`,\n  );\n}\n\nexport async function handleWebSearch(\n  params: WebSearchParams,\n  reporter: ToolReporter = NOOP_REPORTER,\n): Promise<ToolExecutionResult<WebSearchOutput>> {\n  const startTime = Date.now();\n\n  try {\n    mcpLog('info', `Searching for ${params.keywords.length} keyword(s)`, 'search');\n    await reporter.log('info', `Searching for ${params.keywords.length} keyword(s)`);\n    await reporter.progress(15, 100, 'Submitting search queries');\n\n    const response = await executeSearches(params.keywords);\n    await reporter.progress(50, 100, 'Collected search results');\n\n    const { aggregation, urlLookup, consensusUrls } = processAndRankResults(response);\n    await reporter.log(\n      'info',\n      `Collected ${aggregation.totalUniqueUrls} unique URLs across ${response.totalKeywords} queries`,\n    );\n\n    const consensusSection = buildConsensusSection(params.keywords, aggregation);\n    const { markdown: perQuerySection, totalResults } = buildPerQuerySection(response, urlLookup);\n    await reporter.progress(80, 100, 'Ranking and formatting search results');\n\n    const executionTime = Date.now() - startTime;\n    mcpLog('info', `Search completed: ${totalResults} results, ${aggregation.totalUniqueUrls} unique URLs, ${consensusUrls.length} consensus`, 'search');\n    await reporter.log(\n      'info',\n      `Search completed with ${totalResults} ranked results and ${consensusUrls.length} consensus URL(s)`,\n    );\n\n    return formatSearchOutput(\n      consensusSection, perQuerySection, totalResults,\n      aggregation, consensusUrls.length, executionTime, response.totalKeywords,\n    );\n  } catch (error) {\n    return buildWebSearchError(error, params, startTime);\n  }\n}\n\nexport function registerWebSearchTool(server: MCPServer): void {\n  server.tool(\n    {\n      name: 'web-search',\n      title: 'Web Search',\n      description:\n        'Run parallel Google searches across 1\u2013100 keywords and return CTR-weighted, consensus-ranked URLs for follow-up scraping. This is a bulk discovery tool \u2014 supply 3\u20137 keywords for solid consensus detection, or up to 100 for exhaustive coverage. Each keyword runs as a separate Google search; results are aggregated, scored by search position, and URLs appearing across multiple queries are flagged as high-confidence. Output is a ranked URL list ready to pipe into scrape-links or get-reddit-post.',\n      schema: webSearchParamsSchema,\n      outputSchema: webSearchOutputSchema,\n      annotations: {\n        readOnlyHint: true,\n        idempotentHint: true,\n        destructiveHint: false,\n        openWorldHint: true,\n      },\n    },\n    async (args, ctx) => {\n      if (!getCapabilities().search) {\n        return toToolResponse(toolFailure(getMissingEnvMessage('search')));\n      }\n\n      const reporter = createToolReporter(ctx, 'web-search');\n      const result = await handleWebSearch(args, reporter);\n\n      await reporter.progress(100, 100, result.isError ? 'Search failed' : 'Search complete');\n      return toToolResponse(result);\n    },\n  );\n}\n"],
+  "mappings": "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",
+  "names": []
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Shared Tool Utilities
+ * Extracted from individual handlers to eliminate duplication
+ */
+export { mcpLog, safeLog as safeLogSimple, createToolLogger, type LogLevel, type ToolLogger as SimpleToolLogger, } from '../utils/logger.js';
+export { formatSuccess, formatError, formatBatchHeader, formatList, formatDuration, truncateText, type SuccessOptions, type ErrorOptions, type BatchHeaderOptions, type ListItem, } from '../utils/response.js';
+/**
+ * Centralized token budgets for all tools
+ */
+export declare const TOKEN_BUDGETS: {
+    /** Deep research total budget */
+    readonly RESEARCH: 32000;
+    /** Web scraper total budget */
+    readonly SCRAPER: 32000;
+    /** Reddit comment budget per batch */
+    readonly REDDIT_COMMENTS: 1000;
+};
+/**
+ * Logger function type used by tools
+ */
+export type ToolLogger = (level: 'info' | 'error' | 'debug', message: string, sessionId: string) => Promise<void>;
+/**
+ * Standard tool options passed to handlers
+ */
+export interface ToolOptions {
+    readonly sessionId?: string;
+    readonly 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>;
+/**
+ * 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
+ * @returns Tokens per item
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+export declare function buildStatusLine(successful: number, failed: number, batches: number, extras?: string[]): string;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/tools/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,MAAM,EACN,OAAO,IAAI,aAAa,EACxB,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,UAAU,IAAI,gBAAgB,GACpC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,GACd,MAAM,sBAAsB,CAAC;AAM9B;;GAEG;AACH,eAAO,MAAM,aAAa;IACxB,iCAAiC;;IAEjC,+BAA+B;;IAE/B,sCAAsC;;CAE9B,CAAC;AAMX;;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,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;CAC9B;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"}

package/dist/src/tools/utils.js

@@ -0,0 +1,96 @@
+import {
+  mcpLog,
+  safeLog,
+  createToolLogger
+} from "../utils/logger.js";
+import {
+  formatSuccess,
+  formatError,
+  formatBatchHeader,
+  formatList,
+  formatDuration,
+  truncateText
+} from "../utils/response.js";
+const TOKEN_BUDGETS = {
+  /** Deep research total budget */
+  RESEARCH: 32e3,
+  /** Web scraper total budget */
+  SCRAPER: 32e3,
+  /** Reddit comment budget per batch */
+  REDDIT_COMMENTS: 1e3
+};
+async function safeLog2(logger, sessionId, level, message, toolName) {
+  if (!logger || !sessionId) return;
+  try {
+    await logger(level, `[${toolName}] ${message}`, sessionId);
+  } catch {
+    console.error(`[${toolName}] Logger failed: ${message}`);
+  }
+}
+function calculateTokenAllocation(count, budget) {
+  if (count <= 0) return budget;
+  return Math.floor(budget / count);
+}
+function formatRetryHint(retryable) {
+  return retryable ? "\n\n\u{1F4A1} This error may be temporary. Try again in a moment." : "";
+}
+function formatToolError(toolName, errorCode, message, retryable, tip) {
+  const retryHint = formatRetryHint(retryable);
+  const tipSection = tip ? `
+
+**Tip:** ${tip}` : "";
+  return `# \u274C ${toolName}: Operation Failed
+
+**${errorCode}:** ${message}${retryHint}${tipSection}`;
+}
+function validateNonEmptyArray(value, fieldName) {
+  if (!Array.isArray(value)) {
+    return `${fieldName} must be an array`;
+  }
+  if (value.length === 0) {
+    return `${fieldName} must not be empty`;
+  }
+  return void 0;
+}
+function validateArrayBounds(arr, min, max, fieldName) {
+  if (arr.length < min) {
+    return `${fieldName} requires at least ${min} items. Received: ${arr.length}`;
+  }
+  if (arr.length > max) {
+    return `${fieldName} allows at most ${max} items. Received: ${arr.length}. Please remove ${arr.length - max} item(s).`;
+  }
+  return void 0;
+}
+function buildBatchHeader(title, count, tokensPerItem, totalBudget) {
+  return `# ${title} (${count} items)
+
+**Token Allocation:** ${tokensPerItem.toLocaleString()} tokens/item (${count} items, ${totalBudget.toLocaleString()} total budget)`;
+}
+function buildStatusLine(successful, failed, batches, extras) {
+  let status = `**Status:** \u2705 ${successful} successful | \u274C ${failed} failed | \u{1F4E6} ${batches} batch(es)`;
+  if (extras && extras.length > 0) {
+    status += ` | ${extras.join(" | ")}`;
+  }
+  return status;
+}
+export {
+  TOKEN_BUDGETS,
+  buildBatchHeader,
+  buildStatusLine,
+  calculateTokenAllocation,
+  createToolLogger,
+  formatBatchHeader,
+  formatDuration,
+  formatError,
+  formatList,
+  formatRetryHint,
+  formatSuccess,
+  formatToolError,
+  mcpLog,
+  safeLog2 as safeLog,
+  safeLog as safeLogSimple,
+  truncateText,
+  validateArrayBounds,
+  validateNonEmptyArray
+};
+//# sourceMappingURL=utils.js.map

package/dist/src/tools/utils.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/tools/utils.ts"],
+  "sourcesContent": ["/**\n * Shared Tool Utilities\n * Extracted from individual handlers to eliminate duplication\n */\n\n// Re-export from centralized modules\nexport {\n  mcpLog,\n  safeLog as safeLogSimple,\n  createToolLogger,\n  type LogLevel,\n  type ToolLogger as SimpleToolLogger,\n} from '../utils/logger.js';\n\nexport {\n  formatSuccess,\n  formatError,\n  formatBatchHeader,\n  formatList,\n  formatDuration,\n  truncateText,\n  type SuccessOptions,\n  type ErrorOptions,\n  type BatchHeaderOptions,\n  type ListItem,\n} from '../utils/response.js';\n\n// ============================================================================\n// Token Budget Constants\n// ============================================================================\n\n/**\n * Centralized token budgets for all tools\n */\nexport const TOKEN_BUDGETS = {\n  /** Deep research total budget */\n  RESEARCH: 32_000,\n  /** Web scraper total budget */\n  SCRAPER: 32_000,\n  /** Reddit comment budget per batch */\n  REDDIT_COMMENTS: 1_000,\n} as const;\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Logger function type used by tools\n */\nexport type ToolLogger = (\n  level: 'info' | 'error' | 'debug',\n  message: string,\n  sessionId: string\n) => Promise<void>;\n\n/**\n * Standard tool options passed to handlers\n */\nexport interface ToolOptions {\n  readonly sessionId?: string;\n  readonly logger?: ToolLogger;\n}\n\n// ============================================================================\n// Logging Utilities\n// ============================================================================\n\n/**\n * Safe logger wrapper - NEVER throws\n * Logs to provided logger or falls back to console.error\n *\n * @param logger - Optional logger function\n * @param sessionId - Session ID for logging context\n * @param level - Log level\n * @param message - Message to log\n * @param toolName - Name of the tool for prefixing\n */\nexport async function safeLog(\n  logger: ToolLogger | undefined,\n  sessionId: string | undefined,\n  level: 'info' | 'error' | 'debug',\n  message: string,\n  toolName: string\n): Promise<void> {\n  if (!logger || !sessionId) return;\n  try {\n    await logger(level, `[${toolName}] ${message}`, sessionId);\n  } catch {\n    // Silently ignore logger errors - they should never crash the tool\n    console.error(`[${toolName}] Logger failed: ${message}`);\n  }\n}\n\n// ============================================================================\n// Token Allocation\n// ============================================================================\n\n/**\n * Calculate token allocation for batch operations\n * Distributes a fixed budget across multiple items\n *\n * @param count - Number of items to distribute budget across\n * @param budget - Total token budget\n * @returns Tokens per item\n */\nexport function calculateTokenAllocation(count: number, budget: number): number {\n  if (count <= 0) return budget;\n  return Math.floor(budget / count);\n}\n\n// ============================================================================\n// Error Formatting\n// ============================================================================\n\n/**\n * Format retry hint based on error retryability\n *\n * @param retryable - Whether the error is retryable\n * @returns Hint string or empty string\n */\nexport function formatRetryHint(retryable: boolean): string {\n  return retryable\n    ? '\\n\\n\uD83D\uDCA1 This error may be temporary. Try again in a moment.'\n    : '';\n}\n\n/**\n * Create a standard error markdown response\n *\n * @param toolName - Name of the tool that errored\n * @param errorCode - Error code\n * @param message - Error message\n * @param retryable - Whether error is retryable\n * @param tip - Optional tip for resolution\n * @returns Formatted markdown error string\n */\nexport function formatToolError(\n  toolName: string,\n  errorCode: string,\n  message: string,\n  retryable: boolean,\n  tip?: string\n): string {\n  const retryHint = formatRetryHint(retryable);\n  const tipSection = tip ? `\\n\\n**Tip:** ${tip}` : '';\n  return `# \u274C ${toolName}: Operation Failed\\n\\n**${errorCode}:** ${message}${retryHint}${tipSection}`;\n}\n\n// ============================================================================\n// Validation Helpers\n// ============================================================================\n\n/**\n * Validate that a value is a non-empty array\n *\n * @param value - Value to check\n * @param fieldName - Field name for error message\n * @returns Error message or undefined if valid\n */\nexport function validateNonEmptyArray(\n  value: unknown,\n  fieldName: string\n): string | undefined {\n  if (!Array.isArray(value)) {\n    return `${fieldName} must be an array`;\n  }\n  if (value.length === 0) {\n    return `${fieldName} must not be empty`;\n  }\n  return undefined;\n}\n\n/**\n * Validate array length is within bounds\n *\n * @param arr - Array to check\n * @param min - Minimum length\n * @param max - Maximum length\n * @param fieldName - Field name for error message\n * @returns Error message or undefined if valid\n */\nexport function validateArrayBounds(\n  arr: unknown[],\n  min: number,\n  max: number,\n  fieldName: string\n): string | undefined {\n  if (arr.length < min) {\n    return `${fieldName} requires at least ${min} items. Received: ${arr.length}`;\n  }\n  if (arr.length > max) {\n    return `${fieldName} allows at most ${max} items. Received: ${arr.length}. Please remove ${arr.length - max} item(s).`;\n  }\n  return undefined;\n}\n\n// ============================================================================\n// Response Builders\n// ============================================================================\n\n/**\n * Build standard header for batch operation results\n *\n * @param title - Title of the results section\n * @param count - Number of items processed\n * @param tokensPerItem - Tokens allocated per item\n * @param totalBudget - Total token budget\n * @returns Formatted header string\n */\nexport function buildBatchHeader(\n  title: string,\n  count: number,\n  tokensPerItem: number,\n  totalBudget: number\n): string {\n  return `# ${title} (${count} items)\\n\\n**Token Allocation:** ${tokensPerItem.toLocaleString()} tokens/item (${count} items, ${totalBudget.toLocaleString()} total budget)`;\n}\n\n/**\n * Build status line for batch results\n *\n * @param successful - Number of successful items\n * @param failed - Number of failed items\n * @param batches - Number of batches processed\n * @param extras - Optional extra status items\n * @returns Formatted status line\n */\nexport function buildStatusLine(\n  successful: number,\n  failed: number,\n  batches: number,\n  extras?: string[]\n): string {\n  let status = `**Status:** \u2705 ${successful} successful | \u274C ${failed} failed | \uD83D\uDCE6 ${batches} batch(es)`;\n  if (extras && extras.length > 0) {\n    status += ` | ${extras.join(' | ')}`;\n  }\n  return status;\n}\n"],
+  "mappings": "AAMA;AAAA,EACE;AAAA,EACW;AAAA,EACX;AAAA,OAGK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAKK;AASA,MAAM,gBAAgB;AAAA;AAAA,EAE3B,UAAU;AAAA;AAAA,EAEV,SAAS;AAAA;AAAA,EAET,iBAAiB;AACnB;AAqCA,eAAsBA,SACpB,QACA,WACA,OACA,SACA,UACe;AACf,MAAI,CAAC,UAAU,CAAC,UAAW;AAC3B,MAAI;AACF,UAAM,OAAO,OAAO,IAAI,QAAQ,KAAK,OAAO,IAAI,SAAS;AAAA,EAC3D,QAAQ;AAEN,YAAQ,MAAM,IAAI,QAAQ,oBAAoB,OAAO,EAAE;AAAA,EACzD;AACF;AAcO,SAAS,yBAAyB,OAAe,QAAwB;AAC9E,MAAI,SAAS,EAAG,QAAO;AACvB,SAAO,KAAK,MAAM,SAAS,KAAK;AAClC;AAYO,SAAS,gBAAgB,WAA4B;AAC1D,SAAO,YACH,sEACA;AACN;AAYO,SAAS,gBACd,UACA,WACA,SACA,WACA,KACQ;AACR,QAAM,YAAY,gBAAgB,SAAS;AAC3C,QAAM,aAAa,MAAM;AAAA;AAAA,WAAgB,GAAG,KAAK;AACjD,SAAO,YAAO,QAAQ;AAAA;AAAA,IAA2B,SAAS,OAAO,OAAO,GAAG,SAAS,GAAG,UAAU;AACnG;AAaO,SAAS,sBACd,OACA,WACoB;AACpB,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,WAAO,GAAG,SAAS;AAAA,EACrB;AACA,MAAI,MAAM,WAAW,GAAG;AACtB,WAAO,GAAG,SAAS;AAAA,EACrB;AACA,SAAO;AACT;AAWO,SAAS,oBACd,KACA,KACA,KACA,WACoB;AACpB,MAAI,IAAI,SAAS,KAAK;AACpB,WAAO,GAAG,SAAS,sBAAsB,GAAG,qBAAqB,IAAI,MAAM;AAAA,EAC7E;AACA,MAAI,IAAI,SAAS,KAAK;AACpB,WAAO,GAAG,SAAS,mBAAmB,GAAG,qBAAqB,IAAI,MAAM,mBAAmB,IAAI,SAAS,GAAG;AAAA,EAC7G;AACA,SAAO;AACT;AAeO,SAAS,iBACd,OACA,OACA,eACA,aACQ;AACR,SAAO,KAAK,KAAK,KAAK,KAAK;AAAA;AAAA,wBAAoC,cAAc,eAAe,CAAC,iBAAiB,KAAK,WAAW,YAAY,eAAe,CAAC;AAC5J;AAWO,SAAS,gBACd,YACA,QACA,SACA,QACQ;AACR,MAAI,SAAS,sBAAiB,UAAU,wBAAmB,MAAM,uBAAgB,OAAO;AACxF,MAAI,UAAU,OAAO,SAAS,GAAG;AAC/B,cAAU,MAAM,OAAO,KAAK,KAAK,CAAC;AAAA,EACpC;AACA,SAAO;AACT;",
+  "names": ["safeLog"]
+}

package/dist/src/utils/concurrency.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Concurrency utilities for bounded parallel execution
+ * Prevents CPU spikes and API rate limiting from unbounded Promise.all
+ */
+/**
+ * Execute async tasks with a concurrency limit (like p-map).
+ * Processes items from the input array through the mapper function,
+ * running at most `concurrency` tasks simultaneously.
+ *
+ * @param items - Array of items to process
+ * @param mapper - Async function to apply to each item
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
+ * @param signal - Optional AbortSignal to cancel remaining work
+ * @returns Array of results in the same order as input items
+ */
+export declare function pMap<T, R>(items: readonly T[], mapper: (item: T, index: number) => Promise<R>, concurrency?: number, signal?: AbortSignal): Promise<R[]>;
+/**
+ * Like pMap but uses Promise.allSettled semantics — never rejects,
+ * returns PromiseSettledResult for each item.
+ *
+ * @param items - Array of items to process
+ * @param mapper - Async function to apply to each item
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
+ * @param signal - Optional AbortSignal to cancel remaining work
+ * @returns Array of PromiseSettledResult in the same order as input items
+ */
+export declare function pMapSettled<T, R>(items: readonly T[], mapper: (item: T, index: number) => Promise<R>, concurrency?: number, signal?: AbortSignal): Promise<PromiseSettledResult<R>[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/src/utils/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../../src/utils/concurrency.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,wBAAsB,IAAI,CAAC,CAAC,EAAE,CAAC,EAC7B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,WAAW,GAAE,MAAU,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,EAAE,CAAC,CAkCd;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EACpC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,WAAW,GAAE,MAAU,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC,CAoCpC"}

package/dist/src/utils/concurrency.js

@@ -0,0 +1,62 @@
+async function pMap(items, mapper, concurrency = 6, signal) {
+  if (items.length === 0) return [];
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  const internalAbort = new AbortController();
+  async function worker() {
+    while (true) {
+      if (signal?.aborted || internalAbort.signal.aborted) {
+        throw new DOMException("Aborted", "AbortError");
+      }
+      const index = nextIndex++;
+      if (index >= items.length) break;
+      try {
+        results[index] = await mapper(items[index], index);
+      } catch (err) {
+        internalAbort.abort();
+        throw err;
+      }
+    }
+  }
+  const workers = [];
+  for (let i = 0; i < limit; i++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+async function pMapSettled(items, mapper, concurrency = 6, signal) {
+  if (items.length === 0) return [];
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < items.length) {
+      if (signal?.aborted) break;
+      const index = nextIndex++;
+      try {
+        const value = await mapper(items[index], index);
+        results[index] = { status: "fulfilled", value };
+      } catch (reason) {
+        results[index] = { status: "rejected", reason };
+      }
+    }
+  }
+  const workers = [];
+  for (let i = 0; i < limit; i++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  for (let i = 0; i < items.length; i++) {
+    if (results[i] === void 0) {
+      results[i] = { status: "rejected", reason: new DOMException("Aborted", "AbortError") };
+    }
+  }
+  return results;
+}
+export {
+  pMap,
+  pMapSettled
+};
+//# sourceMappingURL=concurrency.js.map

package/dist/src/utils/concurrency.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/concurrency.ts"],
+  "sourcesContent": ["/**\n * Concurrency utilities for bounded parallel execution\n * Prevents CPU spikes and API rate limiting from unbounded Promise.all\n */\n\n/**\n * Execute async tasks with a concurrency limit (like p-map).\n * Processes items from the input array through the mapper function,\n * running at most `concurrency` tasks simultaneously.\n *\n * @param items - Array of items to process\n * @param mapper - Async function to apply to each item\n * @param concurrency - Maximum number of concurrent tasks (default: 6)\n * @param signal - Optional AbortSignal to cancel remaining work\n * @returns Array of results in the same order as input items\n */\nexport async function pMap<T, R>(\n  items: readonly T[],\n  mapper: (item: T, index: number) => Promise<R>,\n  concurrency: number = 6,\n  signal?: AbortSignal,\n): Promise<R[]> {\n  if (items.length === 0) return [];\n\n  // Clamp concurrency to reasonable bounds\n  const limit = Math.max(1, Math.min(concurrency, items.length));\n\n  const results: R[] = new Array(items.length);\n  let nextIndex = 0;\n  const internalAbort = new AbortController();\n\n  async function worker(): Promise<void> {\n    while (true) {\n      if (signal?.aborted || internalAbort.signal.aborted) {\n        throw new DOMException('Aborted', 'AbortError');\n      }\n      const index = nextIndex++;\n      if (index >= items.length) break;\n      try {\n        results[index] = await mapper(items[index]!, index);\n      } catch (err) {\n        internalAbort.abort(); // Signal other workers to stop picking up new work\n        throw err;\n      }\n    }\n  }\n\n  // Spawn `limit` workers that pull from the shared index\n  const workers: Promise<void>[] = [];\n  for (let i = 0; i < limit; i++) {\n    workers.push(worker());\n  }\n\n  await Promise.all(workers);\n  return results;\n}\n\n/**\n * Like pMap but uses Promise.allSettled semantics \u2014 never rejects,\n * returns PromiseSettledResult for each item.\n *\n * @param items - Array of items to process\n * @param mapper - Async function to apply to each item\n * @param concurrency - Maximum number of concurrent tasks (default: 6)\n * @param signal - Optional AbortSignal to cancel remaining work\n * @returns Array of PromiseSettledResult in the same order as input items\n */\nexport async function pMapSettled<T, R>(\n  items: readonly T[],\n  mapper: (item: T, index: number) => Promise<R>,\n  concurrency: number = 6,\n  signal?: AbortSignal,\n): Promise<PromiseSettledResult<R>[]> {\n  if (items.length === 0) return [];\n\n  const limit = Math.max(1, Math.min(concurrency, items.length));\n\n  const results: PromiseSettledResult<R>[] = new Array(items.length);\n  let nextIndex = 0;\n\n  async function worker(): Promise<void> {\n    while (nextIndex < items.length) {\n      if (signal?.aborted) break;\n      const index = nextIndex++;\n      try {\n        const value = await mapper(items[index]!, index);\n        results[index] = { status: 'fulfilled', value };\n      } catch (reason) {\n        results[index] = { status: 'rejected', reason };\n      }\n    }\n  }\n\n  const workers: Promise<void>[] = [];\n  for (let i = 0; i < limit; i++) {\n    workers.push(worker());\n  }\n\n  await Promise.all(workers);\n\n  // Fill any unprocessed items after abort\n  for (let i = 0; i < items.length; i++) {\n    if (results[i] === undefined) {\n      results[i] = { status: 'rejected', reason: new DOMException('Aborted', 'AbortError') };\n    }\n  }\n\n  return results;\n}\n"],
+  "mappings": "AAgBA,eAAsB,KACpB,OACA,QACA,cAAsB,GACtB,QACc;AACd,MAAI,MAAM,WAAW,EAAG,QAAO,CAAC;AAGhC,QAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,IAAI,aAAa,MAAM,MAAM,CAAC;AAE7D,QAAM,UAAe,IAAI,MAAM,MAAM,MAAM;AAC3C,MAAI,YAAY;AAChB,QAAM,gBAAgB,IAAI,gBAAgB;AAE1C,iBAAe,SAAwB;AACrC,WAAO,MAAM;AACX,UAAI,QAAQ,WAAW,cAAc,OAAO,SAAS;AACnD,cAAM,IAAI,aAAa,WAAW,YAAY;AAAA,MAChD;AACA,YAAM,QAAQ;AACd,UAAI,SAAS,MAAM,OAAQ;AAC3B,UAAI;AACF,gBAAQ,KAAK,IAAI,MAAM,OAAO,MAAM,KAAK,GAAI,KAAK;AAAA,MACpD,SAAS,KAAK;AACZ,sBAAc,MAAM;AACpB,cAAM;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAGA,QAAM,UAA2B,CAAC;AAClC,WAAS,IAAI,GAAG,IAAI,OAAO,KAAK;AAC9B,YAAQ,KAAK,OAAO,CAAC;AAAA,EACvB;AAEA,QAAM,QAAQ,IAAI,OAAO;AACzB,SAAO;AACT;AAYA,eAAsB,YACpB,OACA,QACA,cAAsB,GACtB,QACoC;AACpC,MAAI,MAAM,WAAW,EAAG,QAAO,CAAC;AAEhC,QAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,IAAI,aAAa,MAAM,MAAM,CAAC;AAE7D,QAAM,UAAqC,IAAI,MAAM,MAAM,MAAM;AACjE,MAAI,YAAY;AAEhB,iBAAe,SAAwB;AACrC,WAAO,YAAY,MAAM,QAAQ;AAC/B,UAAI,QAAQ,QAAS;AACrB,YAAM,QAAQ;AACd,UAAI;AACF,cAAM,QAAQ,MAAM,OAAO,MAAM,KAAK,GAAI,KAAK;AAC/C,gBAAQ,KAAK,IAAI,EAAE,QAAQ,aAAa,MAAM;AAAA,MAChD,SAAS,QAAQ;AACf,gBAAQ,KAAK,IAAI,EAAE,QAAQ,YAAY,OAAO;AAAA,MAChD;AAAA,IACF;AAAA,EACF;AAEA,QAAM,UAA2B,CAAC;AAClC,WAAS,IAAI,GAAG,IAAI,OAAO,KAAK;AAC9B,YAAQ,KAAK,OAAO,CAAC;AAAA,EACvB;AAEA,QAAM,QAAQ,IAAI,OAAO;AAGzB,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,QAAI,QAAQ,CAAC,MAAM,QAAW;AAC5B,cAAQ,CAAC,IAAI,EAAE,QAAQ,YAAY,QAAQ,IAAI,aAAa,WAAW,YAAY,EAAE;AAAA,IACvF;AAAA,EACF;AAEA,SAAO;AACT;",
+  "names": []
+}