Refactor resource handling: rename resource_read to resources, add resource_list tool, and update documentation. Remove obsolete scripts.

Author: pelikhan

docs/src/components/BuiltinTools.mdx

@@ -41,7 +41,8 @@ import { LinkCard } from '@astrojs/starlight/components';
 <LinkCard title="python_code_interpreter_run" description="Executes python 3.12 code for Data Analysis tasks in a docker container. The process output is returned. Do not generate visualizations. The only packages available are numpy===2.1.3, pandas===2.2.3, scipy===1.14.1, matplotlib===3.9.2. There is NO network connectivity. Do not attempt to install other packages or make web requests. You must copy all the necessary files or pass all the data because the python code runs in a separate container." href="/genaiscript/reference/scripts/system#systempython_code_interpreter" />
 <LinkCard title="python_code_interpreter_copy_files_to_container" description="Copy files from the workspace file system to the container file system. NO absolute paths. Returns the path of each file copied in the python container." href="/genaiscript/reference/scripts/system#systempython_code_interpreter" />
 <LinkCard title="python_code_interpreter_read_file" description="Reads a file from the container file system. No absolute paths." href="/genaiscript/reference/scripts/system#systempython_code_interpreter" />
-<LinkCard title="resource_read" description="Read the content of a resource from a URL. Resolves various protocols and returns the content of the files found at the URL." href="/genaiscript/reference/scripts/system#systemresource_read" />
+<LinkCard title="resource_list" description="List available resources from the host. Returns a list of available resource URIs and their descriptions." href="/genaiscript/reference/scripts/system#systemresources" />
+<LinkCard title="resource_read" description="Read the content of a resource from a URL. Resolves various protocols and returns the content of the files found at the URL." href="/genaiscript/reference/scripts/system#systemresources" />
 <LinkCard title="retrieval_fuzz_search" description="Search for keywords using the full text of files and a fuzzy distance." href="/genaiscript/reference/scripts/system#systemretrieval_fuzz_search" />
 <LinkCard title="retrieval_vector_search" description="Search files using embeddings and similarity distance." href="/genaiscript/reference/scripts/system#systemretrieval_vector_search" />
 <LinkCard title="retrieval_web_search" description="Search the web for a user query using Tavily or Bing Search." href="/genaiscript/reference/scripts/system#systemretrieval_web_search" />

docs/src/content/docs/reference/scripts/system.mdx

@@ -3971,91 +3971,139 @@ export default function (ctx: ChatGenerationContext) {
 `````
 
 
-### `system.resource_read`
+### `system.resources`
 
 Read resource content from a URL using MCP resource resolution
 
 Provides a tool that can read and return the content of resources from URLs using the host's resolveResource function. Supports various protocols including https, file, git, gist, and vscode.
 
+-  tool `resource_list`: List available resources from the host. Returns a list of available resource URIs and their descriptions.
 -  tool `resource_read`: Read the content of a resource from a URL. Resolves various protocols and returns the content of the files found at the URL.
 
-`````js wrap title="system.resource_read"
+`````js wrap title="system.resources"
 system({
-    title: "Read resource content from a URL using MCP resource resolution",
-    description: "Provides a tool that can read and return the content of resources from URLs using the host's resolveResource function. Supports various protocols including https, file, git, gist, and vscode.",
-})
+  title: "Read resource content from a URL using MCP resource resolution",
+  description:
+    "Provides a tool that can read and return the content of resources from URLs using the host's resolveResource function. Supports various protocols including https, file, git, gist, and vscode.",
+});
 
 export default function (ctx: ChatGenerationContext) {
-    const { defTool } = ctx
+  const { defTool } = ctx;
 
-    const dbg = host.logger("genaiscript:res:read")
+  const dbg = host.logger("genaiscript:resources");
 
-    defTool(
-        "resource_read",
-        "Read the content of a resource from a URL. Resolves various protocols and returns the content of the files found at the URL.",
-        {
-            type: "object",
-            properties: {
-                url: {
-                    type: "string",
-                    description: "The URL to read the resource content from. Supports various protocols including https, file, git, gist, and vscode.",
-                },
-            },
-            required: ["url"],
+  defTool(
+    "resource_list",
+    "List available resources from the host. Returns a list of available resource URIs and their descriptions.",
+    {
+      type: "object",
+      properties: {},
+    },
+    async (args) => {
+      const { context } = args;
+
+      dbg(`listing available resources`);
+
+      try {
+        const resources = await host.resources();
+
+        if (!resources || resources.length === 0) {
+          return "No resources available from host. You can still use builtin protocols like https://, file://, git://, gist:// with the resource_read tool.";
+        }
+
+        dbg(`found ${resources.length} resources`);
+
+        const results = resources
+          .map((resource) => {
+            const { uri, name, description, mimeType } = resource;
+            let result = `uri: ${uri}`;
+            if (name) result += `\nname: ${name}`;
+            if (description) result += `\ndescription: ${description}`;
+            if (mimeType) result += `\nmime: ${mimeType}`;
+            return result;
+          })
+          .join("\n\n");
+
+        context.log(`Found ${resources.length} resource(s)`);
+        return results;
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        dbg(`error listing resources: ${errorMsg}`);
+        context.log(`Error listing resources: ${errorMsg}`);
+        return `Error listing resources: ${errorMsg}`;
+      }
+    },
+  );
+
+  defTool(
+    "resource_read",
+    "Read the content of a resource from a URL. Resolves various protocols and returns the content of the files found at the URL.",
+    {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description:
+            "The URL to read the resource content from. Supports MCP resource resolution and various protocols including https, file, git, gist, and vscode.",
         },
-        async (args) => {
-            const { context, url } = args
-            
-            if (!url) {
-                return "Error: URL is required"
-            }
+      },
+      required: ["url"],
+    },
+    async (args) => {
+      const { context, url } = args;
 
-            dbg(`reading resource from URL: ${url}`)
-            context.log(`Reading resource content from: ${url}`)
+      if (!url) {
+        return "Error: URL is required";
+      }
 
-            try {
-                const resource = await host.resolveResource(url)
-                
-                if (!resource) {
-                    dbg(`failed to resolve resource: ${url}`)
-                    return `Error: Unable to resolve resource from URL: ${url}`
-                }
+      dbg(`reading resource from URL: ${url}`);
+      context.log(`Reading resource content from: ${url}`);
 
-                const { uri, files } = resource
-                dbg(`resolved ${files.length} files from ${uri.href}`)
+      try {
+        const resource = await host.resolveResource(url);
 
-                if (!files || files.length === 0) {
-                    return `Error: No files found at URL: ${url}`
-                }
+        if (!resource) {
+          dbg(`failed to resolve resource: ${url}`);
+          return `Error: Unable to resolve resource from URL: ${url}`;
+        }
 
-                // Return content of all files found
-                const results = files.map((file) => {
-                    if (!file.content) {
-                        return `File: ${file.filename} (no content available)`
-                    }
-                    
-                    const header = `File: ${file.filename}${file.type ? ` (${file.type})` : ""}`
-                    const separator = "```"
-                    
-                    if (file.encoding === "base64") {
-                        return `${header}\n${separator}\n[Base64 encoded content - ${file.content.length} characters]\n${separator}`
-                    }
-                    
-                    return `${header}\n${separator}\n${file.content}\n${separator}`
-                }).join("\n\n")
-
-                context.log(`Successfully read ${files.length} file(s) from resource`)
-                return results
-
-            } catch (error) {
-                const errorMsg = error instanceof Error ? error.message : String(error)
-                dbg(`error reading resource: ${errorMsg}`)
-                context.log(`Error reading resource: ${errorMsg}`)
-                return `Error reading resource from ${url}: ${errorMsg}`
-            }
+        const { uri, files } = resource;
+        dbg(`resolved ${files.length} files from ${uri.href}`);
+
+        if (!files || files.length === 0) {
+          return `Error: No files found at URL: ${url}`;
         }
-    )
+
+        // Return content of all files found
+        const results = files
+          .map((file) => {
+            if (!file.content) {
+              return `File: ${file.filename} (no content available)`;
+            }
+
+            const header = `File: ${file.filename}${file.type ? ` (${file.type})` : ""}`;
+            const separator = "```";
+
+            if (file.encoding === "base64") {
+              return `${header}\n${separator}\n[Base64 encoded content - ${file.content.length} characters]\n${separator}`;
+            }
+
+            return `${header}\n${separator}\n${file.content}\n${separator}`;
+          })
+          .join("\n\n");
+
+        context.log(`Successfully read ${files.length} file(s) from resource`);
+        return results;
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        dbg(`error reading resource: ${errorMsg}`);
+        context.log(`Error reading resource: ${errorMsg}`);
+        return `Error reading resource from ${url}: ${errorMsg}`;
+      }
+    },
+  );
 }
+
 `````