ruby_llm-code_mode 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d933b7782ef9b21eb6c9c704630a456b1aa96ffecc52e4a258aa50fd99e09ebf
-  data.tar.gz: d006d9fbac9d85b569a0978f5bf74cca9430ffe8bf7ba47c526a83ecdb52b7ac
+  metadata.gz: b92ccf0470dc8d3563eafa55662e7aa0db058095d8ac12a0d60a062547474f81
+  data.tar.gz: c2955740ee6b04b1a38279b25f63703194df752fa51f3d4f49166bab3f318ac3
 SHA512:
-  metadata.gz: 0ce747225815a3dd6a9aeccc8ccbb74ac64d9a24e7716797941d75afb009e55c7a56a899abafaeac5a490ad7a921ce0c771955ced03d72861f9472c42f3a2c13
-  data.tar.gz: e62fdd4dbe81c6dd7034ea4e27d1ff18c0aa2bf22d83ab58a94d35e1b51fc045db31e73fd4a560c13ffc5615d8e800cdb83be2f0c38c704c1a8e9c767fec97cd
+  metadata.gz: 7fb1029e393ec6c0041d91d5a45fbef2acdc253fe28427986d0832a73eb33b43becfa42d97983212ac7a3312a771e9506765c271bd4bd2ebcf68968b7adf467e
+  data.tar.gz: 52e9aa1bf43f9dcedf0a6e50deb9578c86716bdd5ae353da6717a6553b7f5170f3773f5c40a4229779589be9686e0a3274788d3dc658cdb084fcc5ff862c206a

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Juneira
+Copyright (c) 2026 Marcelo Junior
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

data/README.md

@@ -48,7 +48,9 @@ a fixed description built from the declared mounts:
   from the host, with a private `/work` scratch directory wiped between
   executions and no state carried over between runs;
 - a **Read-only folders** section listing each `mount` as `` `/guest/path` — description``;
-- a **Read-write folders** section listing each `mount_rw`.
+- a **Read-write folders** section listing each `mount_rw`;
+- a **Host tools** section listing every bound `RubyLLM::Tool` with its
+  parameters, when any are bound with `tool` or `mcp`.
 
 The single parameter is `code` — a complete, self-contained Ruby script.
 
@@ -68,6 +70,9 @@ A JSON object sent back to the model:
 ```ruby
 mount    source: host_path, dest: guest_path, description: "..."  # read-only
 mount_rw source: host_path, dest: guest_path, description: "..." # read-write
+tool     SomeRubyLLMTool                                          # host tool
+tool     "name" => SomeRubyLLMTool                                # explicit name
+mcp      SomeMcpServer                                            # MCP server (instance or class)
 ```
 
 - `source:` — folder on the host machine, relative to the process working
@@ -75,9 +80,100 @@ mount_rw source: host_path, dest: guest_path, description: "..." # read-write
 - `dest:` — absolute, normalized path inside the sandbox (may not overlap
   the reserved `/work`, `/usr` or `/src` trees, and must be unique).
 - `description:` — shown to the model in the tool description.
+- `tool` — a `RubyLLM::Tool` class or instance; the name inside the sandbox
+  is derived from the class-name leaf (`MyApp::Tools::Weather` → `weather`),
+  or the explicit one from the one-pair form.
+- `mcp` — a `RubyLLM::MCP` instance or class (auto-instantiated, with the
+  server's declared inputs as keywords); all of the server's tools are bound
+  under their own names.
 
 Invalid declarations raise at class-definition time, so a misconfigured tool
-never reaches a live chat. Subclasses inherit their parent's mounts.
+never reaches a live chat. Subclasses inherit their parent's mounts and tools.
+
+### Host tools
+
+Bind existing `RubyLLM::Tool`s so the sandboxed code can call them through
+SecurityBox's host RPC channel:
+
+```ruby
+class Weather < RubyLLM::Tool
+  description "Current weather for a city"
+  parameter :city, type: "string", description: "City name"
+
+  def execute(city:)
+    # host-side HTTP call, database query, ...
+  end
+end
+
+class Assistant < RubyLLM::CodeMode
+  mount source: "data", dest: "/data", description: "Project data"
+  tool  Weather                 # binds as `weather`
+  tool  "forecast" => Weather   # or bind it under an explicit name
+end
+```
+
+The description tells the model what is available, and inside the sandbox it
+writes Ruby like:
+
+```ruby
+report = SB.call("weather", city: "Porto Alegre")
+```
+
+- Bound classes are instantiated once at definition time; every call shares
+  that instance, so state persists across calls (like the sandbox itself).
+- Arguments must be JSON-serializable; they arrive as the tool's keyword
+  arguments (top-level string keys become symbols, nested data keeps string
+  keys). Bad arguments come back as an `error` hash — RubyLLM's
+  recoverable-failure convention.
+- The return value is JSON round-tripped: hashes, arrays and scalars pass
+  through; non-serializable objects surface as their `inspect` string.
+- A tool that raises surfaces as `SB::ToolError` (class name and message
+  only — no backtrace), which the sandboxed code can rescue. Unbound names
+  raise `SB::UnknownTool`.
+- Limits per execution: 1000 tool calls and 1 MiB per result. At most 64
+  tools can be bound to one class.
+- A `RubyLLM::CodeMode` cannot be bound inside another `CodeMode`.
+
+### MCP servers
+
+The `mcp` DSL connects [RubyLLM::MCP](https://rubyllm.com/next/mcp/) servers
+and binds all their tools in one call, letting the sandboxed code reach the
+server through the host RPC channel:
+
+```ruby
+docs = RubyLLM.mcp(url: "https://learn.microsoft.com/api/mcp")
+
+class DocsResearch < RubyLLM::CodeMode
+  mcp docs                       # instance
+  # mcp MicrosoftDocs            # or the class (instantiated with .new)
+  # mcp Linear, user: current_user  # class + the server's declared inputs
+end
+```
+
+Each server tool keeps its server name and its JSON schema is rendered into
+the tool description, so inside the sandbox the model writes:
+
+```ruby
+result = SB.call("microsoft_docs_search", query: "Azure Blob Storage")
+result[:text]       # => the tool's text output
+result[:structured] # => parsed structured content, or nil
+result[:error]      # => true when the tool reported a failure
+```
+
+- A tool whose name is already bound is re-bound as `<server>_tool`
+  (`search` on server `github` → `github_search`); a name that still collides
+  after prefixing raises at definition time.
+- Servers that send `instructions` have them listed in the description under
+  a "## Server notes" section.
+- Everything fails fast: an argument that is not a `RubyLLM::MCP`, a server
+  that cannot be reached, or a stuck name collision roll the whole call back
+  and raise at definition time.
+- The class form binds the tools of one instance built at definition time —
+  for servers that act per-user, pass a ready instance instead
+  (`mcp Linear.new(user: current_user)`) where the user is available.
+
+The sandbox itself never sees the network — every `SB.call` performs the MCP
+request on the host. A runnable example lives in `sample/ruby_llm_mcp/`.
 
 ### Sandbox limits
 
@@ -96,11 +192,9 @@ every subsequent evaluation then takes a few hundred milliseconds.
 - Guest code is sandboxed by [SecurityBox](https://rubygems.org/gems/security_box):
   no network, no threads, no processes, no host filesystem beyond the mounts,
   deterministic CPU/memory/time limits, and forged results are rejected.
-
-## Roadmap
-
-- v2: a **Tools** section in the description backed by SecurityBox host RPC
-  handlers, so guest code can call registered host functions via `SB.call`.
+- Bound host tools execute on the host, behind the sandbox's call boundary:
+  their arguments come from model-generated code, so treat them as untrusted
+  input, and only bind tools whose effects you are willing to grant the model.
 
 ## Development
 

data/lib/ruby_llm/code_mode.rb

@@ -5,10 +5,14 @@ require "security_box"
 
 module RubyLLM
   class CodeMode < Tool
-    VERSION = "0.1.1"
+    VERSION = "0.2.0"
 
     DEFAULT_TIMEOUT_MS = 30_000
     DEFAULT_FUEL_MS = 10_000
+    MAX_TOOLS = SecurityBox::Rpcs::MAX_RPCS
+
+    TOOL_USAGE = "tool expects a RubyLLM::Tool class or instance, " \
+                 'or exactly one "name" => tool pair'
 
     FIXED_DESCRIPTION = <<~DESC.freeze
       Executes Ruby code inside a secure sandbox and returns what it produced.
@@ -29,12 +33,26 @@ module RubyLLM
       class, message and backtrace are returned so you can fix and retry.
     DESC
 
+    HOST_TOOLS_INTRO = <<~DESC.freeze
+      Registered host tools are callable from inside the sandbox. Call one with
+      `SB.call('name', key: value)`: arguments must be JSON-serializable and become
+      the tool's keyword arguments, and the return value is the tool's result
+      (non-serializable values come back as their inspect string). Bad arguments
+      come back as an `error` hash; handler failures raise `SB::ToolError`
+      (rescuable); unknown names raise `SB::UnknownTool`. Limits: at most 1000
+      tool calls per execution and 1 MiB per result.
+    DESC
+
     Mount = Struct.new(:host, :guest, :mode, :description, keyword_init: true) do
       def payload
         { host: host, guest: guest, mode: mode }
       end
     end
 
+    ToolEntry = Struct.new(:name, :tool, keyword_init: true)
+
+    McpEntry = Struct.new(:name, :mcp, :instructions, keyword_init: true)
+
     class << self
       def tool_name
         leaf = name.to_s.split('::').last
@@ -51,15 +69,78 @@ module RubyLLM
         add_mount(source, dest, :read_write, description)
       end
 
+      def tool(mapping = nil, **kwargs)
+        if !kwargs.empty?
+          raise ArgumentError, TOOL_USAGE unless kwargs.size == 1 && mapping.nil?
+
+          name, bound = kwargs.first
+          mapping = { name.to_s => bound }
+        end
+
+        if mapping.is_a?(Hash)
+          raise ArgumentError, TOOL_USAGE unless mapping.size == 1
+
+          name, bound = mapping.first
+          add_tool(bound, name.to_s)
+        else
+          add_tool(mapping, nil)
+        end
+      end
+
+      # Connects MCP server(s) and binds all their tools into the sandbox:
+      #
+      #   docs = RubyLLM.mcp(url: "https://learn.microsoft.com/api/mcp")
+      #
+      #   class DocsResearch < RubyLLM::CodeMode
+      #     mcp docs                    # instance
+      #     mcp MicrosoftDocs           # or the class (instantiated with .new)
+      #     mcp Linear, user: current_user  # class + declared inputs
+      #     mcp Docs, Github            # several servers / arrays at once
+      #   end
+      #
+      # Server tools keep their names (`microsoft_docs_search`, ...); a tool
+      # whose name is already bound is re-bound as "<server>_tool". The
+      # servers' instructions (when the server sends them) are snapshotted
+      # at definition and listed in the description under "## Server notes".
+      # Fails fast: every argument must be a RubyLLM::MCP (class or
+      # instance), and if anything goes wrong — a server that cannot be
+      # reached, a name that stays colliding after prefixing — nothing is
+      # bound.
+      def mcp(*servers, **inputs)
+        flat = servers.flatten(1)
+        raise ArgumentError, "expected at least one RubyLLM::MCP server" if flat.empty?
+        unless inputs.empty? || flat.all?(Class)
+          raise ArgumentError, "inputs only apply when passing RubyLLM::MCP classes"
+        end
+
+        snapshot_tools = tools.dup
+        snapshot_mcps = mcps.dup
+        normalize_mcp_servers(flat, inputs).each { |server| bind_mcp_server(server) }
+        mcps
+      rescue StandardError
+        instance_variable_set(:@tools, snapshot_tools)
+        instance_variable_set(:@mcps, snapshot_mcps)
+        raise
+      end
+
       def mounts
         @mounts ||= []
       end
 
+      def tools
+        @tools ||= {}
+      end
+
+      def mcps
+        @mcps ||= []
+      end
+
       def configuration
         @configuration ||= SecurityBox::Configuration.build(
           timeout_ms: DEFAULT_TIMEOUT_MS,
           fuel_ms: DEFAULT_FUEL_MS,
-          mounts: mounts.map(&:payload)
+          mounts: mounts.map(&:payload),
+          rpcs: build_rpcs
         )
       end
 
@@ -68,7 +149,9 @@ module RubyLLM
         [
           FIXED_DESCRIPTION.rstrip,
           folder_section("## Read-only folders (readable, never writable)", read_only),
-          folder_section("## Read-write folders (readable and writable)", read_write)
+          folder_section("## Read-write folders (readable and writable)", read_write),
+          tools_section,
+          server_notes_section
         ].compact.join("\n\n")
       end
 
@@ -87,6 +170,8 @@ module RubyLLM
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@mounts, mounts.dup)
+        subclass.instance_variable_set(:@tools, tools.dup)
+        subclass.instance_variable_set(:@mcps, mcps.dup)
         subclass.instance_variable_set(:@configuration, nil)
       end
 
@@ -106,6 +191,113 @@ module RubyLLM
               "Invalid mount #{source.inspect} => #{dest.inspect}: #{e.message}"
       end
 
+      def add_tool(bound, name)
+        instance = normalize_bound_tool(bound)
+        if instance.is_a?(RubyLLM::CodeMode)
+          raise ArgumentError, "cannot bind a RubyLLM::CodeMode inside another CodeMode"
+        end
+
+        name = (name || tool_binding_name(instance)).to_s
+        raise ArgumentError, "tool name must be a non-empty String" if name.empty?
+        raise ArgumentError, "tool name #{name.inspect} is already bound" if tools.key?(name)
+        if tools.size >= MAX_TOOLS
+          raise ArgumentError, "too many tools (#{tools.size + 1}); the limit is #{MAX_TOOLS}"
+        end
+
+        tools[name] = ToolEntry.new(name: name, tool: instance)
+      end
+
+      def normalize_bound_tool(bound)
+        if bound.is_a?(Class)
+          unless bound <= RubyLLM::Tool
+            raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
+          end
+
+          bound.new
+        elsif bound.is_a?(RubyLLM::Tool)
+          bound
+        else
+          raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
+        end
+      end
+
+      # Leaf-only name derivation, like .tool_name — the guest has no use
+      # for the RubyLLM namespace ("MyApp::Tools::Search" binds as "search").
+      def leaf_tool_name(klass)
+        leaf = klass.name.to_s.split('::').last
+        return "" unless leaf
+
+        RubyLLM::Support::Utils.underscore(leaf).delete_suffix('_tool')
+      end
+
+      # Regular tools keep the leaf-only derivation; MCP tools carry their
+      # own (server) name, which is what they bind under inside the sandbox.
+      def tool_binding_name(instance)
+        return instance.name.to_s if instance.respond_to?(:server_name)
+
+        leaf_tool_name(instance.class)
+      end
+
+      def build_rpcs
+        tools.transform_values { |entry| ->(args) { call_bound_tool(entry, args) } }
+      end
+
+      def call_bound_tool(entry, args)
+        unless args.is_a?(Hash)
+          raise ArgumentError,
+                "tool #{entry.name.inspect} expects a hash of arguments, got #{args.class}"
+        end
+
+        normalize_result(entry.tool.call(**args))
+      end
+
+      # MCP tools return RubyLLM::MCP::Result objects; SecurityBox JSON
+      # round-trips handler returns, so give the guest plain data instead
+      # of an inspect string.
+      def normalize_result(value)
+        return value unless defined?(RubyLLM::MCP::Result) && value.is_a?(RubyLLM::MCP::Result)
+
+        { text: value.text, structured: value.structured, error: value.error? }
+      end
+
+      def normalize_mcp_servers(servers, inputs)
+        unless defined?(RubyLLM::MCP)
+          raise ArgumentError,
+                "RubyLLM::MCP is not available; mcp needs a ruby_llm version with MCP support"
+        end
+
+        servers.map do |server|
+          case server
+          when Class
+            unless server <= RubyLLM::MCP
+              raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
+            end
+
+            server.new(**inputs)
+          when RubyLLM::MCP
+            server
+          else
+            raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
+          end
+        end
+      end
+
+      def bind_mcp_server(server)
+        # Fetching .tools connects to the server; snapshot the instructions
+        # right after, so description builds never touch the network.
+        tools_list = server.tools
+        mcps << McpEntry.new(
+          name: server.name.to_s, mcp: server, instructions: server.instructions.to_s
+        )
+        tools_list.each { |tool| bind_mcp_tool(server, tool) }
+      end
+
+      def bind_mcp_tool(server, tool)
+        name = tool_binding_name(tool)
+        name = "#{server.name}_#{name}" if tools.key?(name) && !server.name.to_s.empty?
+        add_tool(tool, name)
+      end
+
       def folder_section(header, entries)
         return nil if entries.empty?
 
@@ -116,6 +308,51 @@ module RubyLLM
         end
         [header, *lines].join("\n")
       end
+
+      def tools_section
+        return nil if tools.empty?
+
+        [
+          "## Host tools (call with SB.call)",
+          HOST_TOOLS_INTRO.rstrip,
+          *tools.values.flat_map { |entry| tool_lines(entry) }
+        ].join("\n")
+      end
+
+      def server_notes_section
+        notes = mcps.filter_map do |entry|
+          instructions = entry.instructions.to_s
+          next if instructions.empty?
+
+          "- **#{entry.name}** — #{instructions}"
+        end
+        return nil if notes.empty?
+
+        ["## Server notes", *notes].join("\n")
+      end
+
+      def tool_lines(entry)
+        line = "- `#{entry.name}`"
+        description = entry.tool.description.to_s
+        line += " — #{description}" unless description.empty?
+
+        [line, *param_lines(entry.tool).map { |param| "  #{param}" }]
+      end
+
+      def param_lines(tool)
+        schema = tool.parameters_schema || {}
+        properties = schema["properties"] || {}
+        required = schema["required"] || []
+
+        properties.filter_map do |param, spec|
+          spec ||= {}
+          status = required.include?(param) ? "required" : "optional"
+          line = "- `#{param}` (#{spec["type"] || "string"}, #{status})"
+          description = spec["description"].to_s
+          line += " — #{description}" unless description.empty?
+          line
+        end
+      end
     end
 
     parameter :code, description: "Complete Ruby script to execute in the sandbox"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-code_mode
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Juneira