ruby_llm-code_mode 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d933b7782ef9b21eb6c9c704630a456b1aa96ffecc52e4a258aa50fd99e09ebf
+  data.tar.gz: d006d9fbac9d85b569a0978f5bf74cca9430ffe8bf7ba47c526a83ecdb52b7ac
+SHA512:
+  metadata.gz: 0ce747225815a3dd6a9aeccc8ccbb74ac64d9a24e7716797941d75afb009e55c7a56a899abafaeac5a490ad7a921ce0c771955ced03d72861f9472c42f3a2c13
+  data.tar.gz: e62fdd4dbe81c6dd7034ea4e27d1ff18c0aa2bf22d83ab58a94d35e1b51fc045db31e73fd4a560c13ffc5615d8e800cdb83be2f0c38c704c1a8e9c767fec97cd

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juneira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

data/README.md

@@ -0,0 +1,124 @@
+# ruby_llm-code_mode
+
+A [RubyLLM](https://rubyllm.com) tool that runs model-generated Ruby code inside a
+secure sandbox, powered by [SecurityBox](https://rubygems.org/gems/security_box).
+
+The model writes Ruby; the code runs as a fresh Ruby 4.0 process inside a
+WebAssembly sandbox (ruby.wasm + wasmtime) with no network, no threads, no
+subprocesses and no access to the host filesystem — except the folders you
+explicitly mount, which are read-only by default.
+
+## Installation
+
+```bash
+gem install ruby_llm-code_mode
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "ruby_llm-code_mode"
+```
+
+## Usage
+
+Define a tool class, declare the host folders the sandbox may see, and give it to
+your chat:
+
+```ruby
+require "ruby_llm"
+require "ruby_llm/code_mode"
+
+class Analytics < RubyLLM::CodeMode
+  mount    source: "data/input", dest: "/data",      description: "CSV files with the raw data (read only)"
+  mount_rw source: "workspace",  dest: "/workspace", description: "Write generated reports and artifacts here"
+end
+
+chat = RubyLLM.chat
+chat.with_tools(Analytics)
+chat.ask "Compute the total sales per month from the CSVs in /data and save the report to /workspace/report.md"
+```
+
+### What the model sees
+
+The tool is presented to the model as `analytics` (derived from the class name) with
+a fixed description built from the declared mounts:
+
+- a **How to use** section: the code runs as a fresh Ruby 4.0 process, isolated
+  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`.
+
+The single parameter is `code` — a complete, self-contained Ruby script.
+
+### What the tool returns
+
+A JSON object sent back to the model:
+
+| status | payload |
+|---|---|
+| `ok` | `{status:, value:, stdout?}` — value of the last expression, captured `puts` output |
+| `error` | `{status:, error: {class, message, backtrace}, stdout?}` — guest exception details |
+| `timeout` / `fuel_exhausted` / `memory_limit` | `{status:, error:}` — resource limit hit |
+| `sandbox_error` | `{status:, error:, stderr?}` — the sandbox itself failed |
+
+### DSL
+
+```ruby
+mount    source: host_path, dest: guest_path, description: "..."  # read-only
+mount_rw source: host_path, dest: guest_path, description: "..." # read-write
+```
+
+- `source:` — folder on the host machine, relative to the process working
+  directory (expanded at class-definition time) or absolute.
+- `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.
+
+Invalid declarations raise at class-definition time, so a misconfigured tool
+never reaches a live chat. Subclasses inherit their parent's mounts.
+
+### Sandbox limits
+
+Defaults: `timeout_ms: 30_000` (wall clock), `fuel_ms: 10_000` (CPU budget).
+Call `MyTool.warmup` at boot to pay the WebAssembly compilation cost up front —
+every subsequent evaluation then takes a few hundred milliseconds.
+
+## Security notes
+
+- Mounted folders are fully readable by the executed code — only mount folders
+  whose content you are willing to expose.
+- Read-only mounts are enforced by wasmtime: writes fail inside the sandbox and
+  never touch the host folder.
+- Read-write mounts are part of the guest's blast radius: the model can create,
+  modify and delete files in them.
+- 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`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+### Releasing
+
+The version lives in the `VERSION` constant of `lib/ruby_llm/code_mode.rb`
+(the gemspec parses it from the source).
+
+```bash
+rake version:bump[minor]          # bump: major, minor or patch (default: patch)
+git commit -am "Bump version to X.Y.Z"
+rake release                      # specs + git tag vX.Y.Z + push to GitHub + push gem to RubyGems
+```
+
+`rake release` refuses a dirty working tree or an existing tag and uses the
+RubyGems credentials from `~/.gem/credentials`.

data/lib/ruby_llm/code_mode.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "security_box"
+
+module RubyLLM
+  class CodeMode < Tool
+    VERSION = "0.1.1"
+
+    DEFAULT_TIMEOUT_MS = 30_000
+    DEFAULT_FUEL_MS = 10_000
+
+    FIXED_DESCRIPTION = <<~DESC.freeze
+      Executes Ruby code inside a secure sandbox and returns what it produced.
+
+      ## How to use
+
+      Pass a complete, self-contained Ruby script as the `code` argument. It runs
+      as a fresh Ruby 4.0 process with:
+      - no network, no threads, no subprocesses, and no access to the host
+        filesystem outside the mounted folders listed below;
+      - a private writable scratch directory at `/work`, wiped between executions;
+      - no state carried over between executions, except the contents of
+        read-write folders.
+
+      Capture progress with `puts` (returned as `stdout`) and end with a value or
+      a JSON-serializable data structure (returned as `value`; non-serializable
+      objects come back as their inspect string). If the code raises, the error
+      class, message and backtrace are returned so you can fix and retry.
+    DESC
+
+    Mount = Struct.new(:host, :guest, :mode, :description, keyword_init: true) do
+      def payload
+        { host: host, guest: guest, mode: mode }
+      end
+    end
+
+    class << self
+      def tool_name
+        leaf = name.to_s.split('::').last
+        return '' unless leaf
+
+        RubyLLM::Support::Utils.underscore(leaf).delete_suffix('_tool')
+      end
+
+      def mount(source:, dest:, description: nil)
+        add_mount(source, dest, :read_only, description)
+      end
+
+      def mount_rw(source:, dest:, description: nil)
+        add_mount(source, dest, :read_write, description)
+      end
+
+      def mounts
+        @mounts ||= []
+      end
+
+      def configuration
+        @configuration ||= SecurityBox::Configuration.build(
+          timeout_ms: DEFAULT_TIMEOUT_MS,
+          fuel_ms: DEFAULT_FUEL_MS,
+          mounts: mounts.map(&:payload)
+        )
+      end
+
+      def build_description
+        read_only, read_write = mounts.partition { |m| m.mode == :read_only }
+        [
+          FIXED_DESCRIPTION.rstrip,
+          folder_section("## Read-only folders (readable, never writable)", read_only),
+          folder_section("## Read-write folders (readable and writable)", read_write)
+        ].compact.join("\n\n")
+      end
+
+      def description(text = nil)
+        raise ArgumentError,
+              "RubyLLM::CodeMode builds the tool description from the declared mounts; " \
+              "the description is fixed and cannot be set by hand" if text
+
+        build_description
+      end
+
+      def warmup
+        SecurityBox.warmup(timeout_ms: DEFAULT_TIMEOUT_MS, fuel_ms: DEFAULT_FUEL_MS)
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@mounts, mounts.dup)
+        subclass.instance_variable_set(:@configuration, nil)
+      end
+
+      private
+
+      def add_mount(source, dest, mode, description)
+        mounts << Mount.new(
+          host: File.expand_path(source.to_s),
+          guest: dest.to_s,
+          mode: mode,
+          description: description.to_s
+        )
+        SecurityBox::Mounts.normalize(mounts.map(&:payload))
+      rescue SecurityBox::InvalidConfiguration => e
+        mounts.pop
+        raise ArgumentError,
+              "Invalid mount #{source.inspect} => #{dest.inspect}: #{e.message}"
+      end
+
+      def folder_section(header, entries)
+        return nil if entries.empty?
+
+        lines = entries.map do |entry|
+          line = "- `#{entry.guest}`"
+          line += " — #{entry.description}" unless entry.description.empty?
+          line
+        end
+        [header, *lines].join("\n")
+      end
+    end
+
+    parameter :code, description: "Complete Ruby script to execute in the sandbox"
+
+    def execute(code:)
+      format_result(sandbox.eval(code))
+    rescue SecurityBox::Error => e
+      { status: "sandbox_error", error: { class: e.class.name, message: e.message } }
+    end
+
+    private
+
+    def sandbox
+      @sandbox ||= SecurityBox::Sandbox.new(self.class.configuration)
+    end
+
+    def format_result(result)
+      payload = { status: result.status.to_s }
+      case result.status
+      when :ok
+        payload[:value] = result.value
+      when :error
+        payload[:error] = result.error || { "class" => "Unknown", "message" => "guest code failed" }
+      when :timeout
+        payload[:error] = "execution timed out before finishing"
+      when :fuel_exhausted
+        payload[:error] = "execution exceeded its CPU budget before finishing"
+      when :memory_limit
+        payload[:error] = "execution exceeded the sandbox memory limit"
+      when :sandbox_error
+        payload[:error] = "the sandbox failed to run the code"
+      end
+      payload[:stdout] = result.stdout if result.stdout && !result.stdout.empty?
+      payload[:stderr] = result.stderr if result.stderr && !result.stderr.empty?
+      payload
+    end
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-code_mode
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Juneira
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: security_box
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+description: |
+  A RubyLLM tool that runs model-generated Ruby code inside a secure
+  WebAssembly sandbox (SecurityBox), with explicit read-only and read-write
+  folder mounts so agents can work on host project folders safely.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ruby_llm/code_mode.rb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Secure sandboxed Ruby code execution tool for RubyLLM, powered by SecurityBox.
+test_files: []