Add system.resources system script for URL content resolution and update documentation (#1886)

* Initial plan

* Add system.mcp_read_resource system script with basic functionality and documentation

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* Add integration tests and finalize system.mcp_read_resource implementation

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* Refactor MCP resource reading tools: rename `mcp_read_resource` to `resource_read`, update documentation, and remove obsolete test scripts.

* Update URL description in resource_read tool and remove required flag

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

* Update resource documentation to include system.resources tools

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: Peli de Halleux <pelikhan@users.noreply.github.com>

Author: Copilot

docs/src/components/BuiltinTools.mdx

@@ -41,6 +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_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/blog/mcp-resources.mdx

@@ -151,6 +151,36 @@ await host.resolveResource("https://github.com/user/repo.git/path/to/file");
 await host.resolveResource("vscode://vsls-contrib.gistfs/open?gist=123&file=script.js");
 ```
 
+## System Resource Tools
+
+GenAIScript provides built-in tools for working with resources through the `system.resources` system script. These tools make it easy to list and read resources in your scripts:
+
+### `resource_list`
+
+Lists all available resources from the host, returning their URIs and descriptions.
+
+```js
+script({
+    system: ["system.resources"]
+})
+
+$`Use the resource_list tool to see what resources are available, then read one of them.`
+```
+
+### `resource_read`
+
+Reads content from a URL using the same resolution logic as `host.resolveResource`. Supports all the URL patterns mentioned above.
+
+```js
+script({
+    system: ["system.resources"]
+})
+
+$`Use the resource_read tool to read the content from https://raw.githubusercontent.com/microsoft/genaiscript/main/README.md`
+```
+
+The tool automatically handles content formatting, binary detection, and multiple files.
+
 ## Next steps
 
 Are you ready to build your own MCP tools and resources?

docs/src/content/docs/reference/cli/commands.md

@@ -93,6 +93,7 @@ Options:
   -n, --pull-request-comment [string]      create comment on a pull request with a unique id (defaults to script id)
   -d, --pull-request-description [string]  create comment on a pull request description with a unique id (defaults to script id)
   -r, --pull-request-reviews               create pull request reviews from annotations
+  --issue                                  create a GitHub issue with the generation output
   --teams-message                          Posts a message to the teams channel
   -j, --json                               emit full JSON response to output
   --fail-on-errors                         fails on detected annotation error

docs/src/content/docs/reference/scripts/mcp-server.mdx

@@ -264,6 +264,8 @@ script({
 are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data
 and content that can be read by clients and used as context for LLM interactions.
 
+### Publishing Resources
+
 In GenAIScript, you can create a resource using `host.publishResource` and
 it will automatically be exposed as a MCP resource.
 
@@ -276,6 +278,30 @@ The return value is the resource uri which can be used in the prompt output.
 
 The resource will be available for the lifetime of the MCP server.
 
+### Reading Resources with Tools
+
+GenAIScript provides built-in tools for working with resources through the `system.resources` system script:
+
+- **`resource_list`**: List available resources from the host. Returns a list of available resource URIs and their descriptions.
+- **`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.
+
+These tools support various protocols including HTTPS, file, git, gist, and VSCode URLs using the host's `resolveResource` function.
+
+```js title="script-using-resources.genai.mjs"
+script({
+    title: "Script that uses resource tools",
+    system: ["system.resources"]
+})
+
+$`Use the resource_read tool to read content from https://raw.githubusercontent.com/microsoft/genaiscript/main/README.md`
+```
+
+The `resource_read` tool automatically handles:
+- **Protocol Support**: HTTPS URLs, GitHub blob URLs, Git repositories, Gists, VSCode URLs
+- **Content Formatting**: Returns well-formatted output with file headers and code blocks
+- **Binary Content**: Detects base64 encoding and provides appropriate metadata
+- **Multiple Files**: Supports URLs that resolve to multiple files (e.g., repository directories)
+
 ### Images
 
 Using `env.output.image`, script can output images that will be part of the tool response.

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

@@ -3971,6 +3971,142 @@ export default function (ctx: ChatGenerationContext) {
 `````
 
 
+### `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.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.",
+});
+
+export default function (ctx: ChatGenerationContext) {
+  const { defTool } = ctx;
+
+  const dbg = host.logger("genaiscript:resources");
+
+  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.",
+        },
+      },
+      required: ["url"],
+    },
+    async (args) => {
+      const { context, url } = args;
+
+      if (!url) {
+        return "Error: URL is required";
+      }
+
+      dbg(`reading resource from URL: ${url}`);
+      context.log(`Reading resource content from: ${url}`);
+
+      try {
+        const resource = await host.resolveResource(url);
+
+        if (!resource) {
+          dbg(`failed to resolve resource: ${url}`);
+          return `Error: Unable to resolve resource from URL: ${url}`;
+        }
+
+        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}`;
+      }
+    },
+  );
+}
+
+`````
+
+
 ### `system.retrieval_fuzz_search`
 
 Full Text Fuzzy Search

packages/core/genaisrc/system.resources.genai.mts

@@ -0,0 +1,122 @@
+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.",
+});
+
+export default function (ctx: ChatGenerationContext) {
+  const { defTool } = ctx;
+
+  const dbg = host.logger("genaiscript:resources");
+
+  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.",
+        },
+      },
+      required: ["url"],
+    },
+    async (args) => {
+      const { context, url } = args;
+
+      if (!url) {
+        return "Error: URL is required";
+      }
+
+      dbg(`reading resource from URL: ${url}`);
+      context.log(`Reading resource content from: ${url}`);
+
+      try {
+        const resource = await host.resolveResource(url);
+
+        if (!resource) {
+          dbg(`failed to resolve resource: ${url}`);
+          return `Error: Unable to resolve resource from URL: ${url}`;
+        }
+
+        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}`;
+      }
+    },
+  );
+}

packages/core/src/openai-chatcompletion.ts

@@ -487,7 +487,7 @@ export const OpenAIv1ChatCompletion: ChatCompletionHandler = async (req, cfg, op
       }
       if (cancellationToken?.isCancellationRequested) finishReason = "cancel";
       else if (toolCalls?.length) finishReason = "tool_calls";
-      finishReason = finishReason || "stop"; // some provider do not implement this final mesage
+      finishReason = finishReason || "stop"; // some provider do not implement this final message
     } catch (e) {
       finishReason = "fail";
       error = serializeError(e);