security_box 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c7d1c1387ec5b1dffdb9781552e489d4b3d45e7066fdd3c7932e6ba39a8432f
-  data.tar.gz: 7770652a22e98d5067c851b5a1c790896b986b6dc7a68ca03ea4a0c3c4bb2110
+  metadata.gz: 999342421a33fdaba7863952bafad78dc8e87bac98a1ec02269fb2903be9d414
+  data.tar.gz: b119d9d14854ba07b2f99bd1c5d8c8e2e25db4f5f50370d1ecea41491ee8b673
 SHA512:
-  metadata.gz: 2d4f7f357bc27692a392251edfd887c310f94f6b0e5f47dccd01c9ea420c427f307888791205d82ee54a12ad117351464b6deefc06211cdabcf6c2bdeb86779e
-  data.tar.gz: b61989d1e43f6f801b1522643239a96118128825837f680bc57122ea8874be4f6229bde01c8af81f53bcbc8d9985e3100f329e2bcbc56797067d6584ed58cca8
+  metadata.gz: 20c96a86adc927a31e1abbe16a6a6cae1b49b015f7078917a0cd1fccfab61e3f5afbc7e2b0a1f71bf546aa21bd40db7d063fb138f542f3c1d2c14f968cd93e05
+  data.tar.gz: 8eddad9955d7801ce2ce93531ba92d581f1686f07288012501bc933d47034502dc3a7a4089f992340a2173ed2230e3698c1b5fdbb1b1e575465ccda0c53f3004

data/CHANGELOG.md

@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-09-21
+
+### Added
+
+- **Host RPC for code mode (stage 6)**: guest code can call host-registered
+  handlers with a regular, blocking function call:
+  `SB.call("github.search", q: "x")`. The call invokes the wasm import
+  (`sb`/`call`, declared by the new `sb_rpc` C extension statically linked
+  into the image) and blocks while the host executes the handler — no
+  callbacks, no rounds, no replay: the code reads as plain sequential Ruby
+  to the LLM that generated it.
+- `c.rpc "name" => handler` in the register DSL (and `rpcs:` in
+  `Configuration.build` / per-call `eval` overrides, replacing like `env:`).
+  Handlers receive the JSON-parsed request args (string keys) and must
+  return a JSON-serializable value (non-serializable results surface as
+  inspect strings). `SecurityBox::Rpcs` validates the set (non-empty unique
+  String names, `#call`-able handlers, at most 64); handlers are host-only
+  state — excluded from `#fingerprint` and unsupported on `RactorPool`
+  (Procs cannot cross a Ractor boundary; raises `InvalidConfiguration`).
+- `Result#rpcs`: a frozen transcript of the calls
+  (`{"name", "args", "ok", "result"|"error"}`), for agent debugging.
+- Sanitized failure mapping: a raising handler becomes a guest-rescuable
+  `SB::ToolError` (`SB::UnknownTool` for unregistered names, including the
+  "no handlers configured" case) carrying only `class` + `message` — no
+  backtrace, no host details. Unknown names never crash the host.
+- Bridge limits: at most 1000 RPC calls per eval and 1 MiB per response
+  (`SecurityBox::GuestRpc::MAX_CALLS`/`RESULT_LIMIT`), enforced host-side.
+
+### Changed
+
+- **Image build**: the image is now built from the pinned Ruby 4.0 source
+  with the guest gems of `lib/security_box/guest_ext` (Gemfile + `sb_rpc`)
+  statically linked (`rbwasm build` + `rbwasm pack`), replacing the packed
+  prebuilt release tarball. Size: 115MB → ~50MB; memory floor: ~95.5MiB →
+  ~36MiB (576 pages); first build downloads the Ruby source, wasi-sdk and
+  binaryen (cached in `build/`).
+- Epoch timer: the engine's native `start_epoch_interval` (a Ruby timer
+  thread cannot run while `invoke` holds the GVL — stage-4 evidence
+  reconfirmed). With a working timer, `timeout_ms` measurably covers boot +
+  guest compute + RPC handler time (the guest traps at the first epoch
+  check after the deadline passes; the handler itself is not interrupted).
+
+### Notes
+
+- The RPC import must be defined on every linker even when no handlers are
+  configured (the image declares the import); guest calls then receive a
+  clean, rescuable `SB::UnknownTool` instead of a failed instantiation.
+- Guest boot fuel is ~0.9e9 (measured with the new image, consistent with
+  the stage-3 calibration).
+
 ## [0.5.0] - 2026-09-20
 
 ### Added

data/README.md

@@ -15,9 +15,12 @@ tries to escape.
 
 ## How it works
 
-1. A `ruby.wasm` image is packed with the Ruby runtime + stdlib + a small guest
-   entrypoint (`lib/security_box/guest/main.rb`) plus a hardening prelude
-   (`lib/security_box/guest/prelude.rb`).
+1. A `ruby.wasm` image is built from the pinned Ruby 4.0 source with the guest
+   gems of `lib/security_box/guest_ext` statically linked (`rbwasm build`),
+   then packed with the guest entrypoint (`lib/security_box/guest/main.rb`)
+   plus a hardening prelude (`lib/security_box/guest/prelude.rb`). The
+   `sb_rpc` gem declares the `sb`/`call` wasm import used by the host RPC
+   channel (see "Host RPC (code mode)" below).
 2. On every `#eval`, the host creates an exclusive tmpdir, writes the user code to it, and
    mounts it read-write as `/work` inside the sandbox. It also generates a per-eval
    random token and passes it to the guest via `SB_TOKEN`.
@@ -50,23 +53,24 @@ gem "security_box"
 ```
 
 The gem ships a prebuilt sandbox image (`lib/security_box/assets/security_box.wasm`,
-about 110MB), so no network access or build tools are needed at install or at
+about 50MB), so no network access or build tools are needed at install or at
 runtime.
 
 ### Rebuilding the image (development only)
 
-If you change `lib/security_box/guest/*.rb` or bump the pinned ruby.wasm
-release, repack the sandbox image:
+If you change `lib/security_box/guest/*.rb` or anything under
+`lib/security_box/guest_ext/` (guest gems), rebuild the sandbox image:
 
 ```bash
 bundle install
 bundle exec rake security_box:build_image
 ```
 
-This downloads the pinned ruby.wasm release (`2.10.1`, see the `Rakefile`) and
-packs it with the guest script into `lib/security_box/assets/security_box.wasm`.
-The task skips repacking when the image is already fresh. The image is not
-committed to git.
+The first build downloads the Ruby source tarball, wasi-sdk and binaryen into
+`build/` (network required, cached afterwards), builds Ruby 4.0 with the guest
+gems statically linked and packs `lib/security_box/guest` as `/src`. The task
+skips rebuilding when the image is already fresh. The image is not committed to
+git.
 
 You can point the library at a different image with the `SECURITY_BOX_IMAGE`
 environment variable or by passing `image_path:` in the configuration — useful
@@ -156,6 +160,45 @@ result.error["backtrace"]        # => ["sandbox:1:in 'Object#boom'", "sandbox:1:
 The backtrace contains guest frames only (sandbox-internal locations, capped at
 20 frames) — nothing from the host filesystem leaks.
 
+### Host RPC (code mode)
+
+Guest code can call host-registered handlers with a regular, **blocking**
+function call — the shape model-generated "code mode" agents need:
+
+```ruby
+SecurityBox.register(:agent) do |c|
+  c.rpc "github.search" => ->(args) { mcp.call_tool("github", "search", args) }
+  c.rpc "github.get"    => ->(args) { mcp.call_tool("github", "get_file", args) }
+  c.fuel_ms 200
+  c.timeout_ms 5_000   # covers boot + guest compute + handler time
+end
+
+box = SecurityBox.spawn(:agent)
+box.eval(<<~CODE)
+  hits = SB.call("github.search", q: "ruby wasm").items
+  SB.call("github.get", path: hits.first.path)
+CODE
+```
+
+- `SB.call(name, args)` blocks inside the sandbox (a wasm import provided by
+  the statically linked `sb_rpc` gem) while the host executes the handler;
+  from the guest's perspective it is just a function returning a value.
+- Handlers receive the JSON-parsed args (string keys) and must return a
+  JSON-serializable value (non-serializable results surface as inspect
+  strings).
+- A raising handler becomes a guest-rescuable `SB::ToolError`
+  (`SB::UnknownTool` for unregistered names) carrying only `class` +
+  `message` — no backtrace, no host details. Calling an RPC on a sandbox
+  with no handlers configured is also a clean, rescuable error.
+- `Result#rpcs` carries the frozen per-eval transcript
+  (`{"name", "args", "ok", "result"|"error"}`) for agent debugging.
+- Limits: at most 1000 calls per eval and 1MiB per response.
+- Handlers are host-only state: excluded from `#fingerprint`, not supported
+  on `RactorPool` (they cannot cross a Ractor boundary), and must be
+  thread-safe when a `Pool` is used concurrently.
+- Per-call override (replaces, like `env:`):
+  `SecurityBox.eval(code, rpcs: { "calc" => ->(args) { ... } })`.
+
 ### Named profiles
 
 Reusable configurations registered once and spawned as often as needed:
@@ -240,7 +283,8 @@ config = SecurityBox::Configuration.build(
   stderr_limit: 1 << 16,            # stderr capture capacity in bytes
   epoch_interval_ms: 25,            # epoch timer granularity
   env: { "LANG" => "C" },           # guest environment (empty by default)
-  mounts: []                        # host-folder mounts (see "Folder mounts")
+  mounts: [],                       # host-folder mounts (see "Folder mounts")
+  rpcs: {}                          # name => callable host RPC handlers
 )
 
 lean = config.with(timeout_ms: 500, fuel: 5_000_000)
@@ -275,6 +319,10 @@ string.
 | `Thread.new` | `NotImplementedError` (WASI p1 has no threads) |
 | `require "socket"` | `LoadError` (no network) |
 | `ENV` | `{}` (token read and scrubbed by the prelude) |
+| `SB.call("missing")` | `SB::UnknownTool` (guest-rescuable; host never crashes) |
+| `SB.call` with no handlers configured | `SB::UnknownTool` ("no RPC handlers are configured…") |
+| handler raising | guest sees `SB::ToolError` with `class` + `message` only |
+| >1000 RPC calls or >1MiB result | `SB::ToolError` (guest-rescuable, host-side enforced) |
 | forge `out.json` via `at_exit` / fake sentinel | rejected (token mismatch → `:sandbox_error`) |
 | infinite loop | killed by epoch deadline or fuel budget |
 
@@ -291,9 +339,10 @@ Notes:
 - Ractor: wasmtime `Engine`/`Module` are Ractor-shareable and Ractors run wasm in
   parallel — measured ≈1.9x wall-time speedup at 4 workers on 6 cores through
   `RactorPool` (see `docs/plan/stages/stage_3.md` and `stage_4.md`).
-- Memory: the packed image declares a 1528-page (~95.5 MiB) minimum; `memory_size`
-  below that fails instantiation (reported as `:sandbox_error`). Practical minimum is
-  ~128–144MB for small workloads; the 512MB default leaves comfortable headroom.
+- Memory: the image (stage-6 `rbwasm build` flow) declares a ~576-page (~36 MiB)
+  minimum; `memory_size` below that fails instantiation (reported as
+  `:sandbox_error`). Practical minimum is ~48–64MB for small workloads; the
+  512MB default leaves comfortable headroom.
 - Fuel budgeting: compute workloads burn ~4–8e9 fuel/s (tight loops up to ~8.4e9/s)
   and every eval costs ~1e9 fuel for boot — see the calibration table in
   `docs/plan/stages/stage_3.md`. Consequently `fuel` below ~1e9 cannot even boot, and
@@ -378,6 +427,13 @@ prints a timing report:
 bundle exec ruby bin/spike.rb
 ```
 
+## Samples
+
+- [`samples/ruby_llm/reader_agent`](samples/ruby_llm/reader_agent/README.md) — an
+  LLM agent built with [RubyLLM](https://github.com/crmne/ruby_llm) whose code-execution
+  tool runs model-generated Ruby inside the sandbox, demonstrating folder mounts
+  (read-only vs read-write) end to end.
+
 ## Documentation
 
 - `docs/PLAN.md` — architecture, roadmap and threat model
@@ -390,3 +446,6 @@ bundle exec ruby bin/spike.rb
   `fuel_ms`)
 - `docs/plan/stages/stage_5.md` — stage 5 findings (folder mounts: read-only
   enforcement, reserved-path collisions, symlink escapes, mount cost)
+- `docs/plan/stages/stage_6.md` — stage 6 findings (blocking host RPC via a
+  wasm import, `SB.call` code-mode contract, epoch semantics, new image
+  build flow)

data/lib/security_box/assets/security_box.wasm

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/security_box/assets/security_box.wasm
-size: 115877509 bytes
-sha256: d7af08b7b11f5ac8bf9b4b8e9cb2ac6ca3e5c977f0dcdfea3551627247589a70
+size: 52249212 bytes
+sha256: 6a6b265e2c1e79f871ccee925a8ea63310cdf433fcffb061369c72f64fd5301c

data/lib/security_box/configuration.rb

@@ -20,7 +20,8 @@ module SecurityBox
       stderr_limit: 1 << 16,
       epoch_interval_ms: 25,
       env: {}.freeze,
-      mounts: [].freeze
+      mounts: [].freeze,
+      rpcs: {}.freeze
     }.freeze
 
     # Fuel-per-ms conversion for #fuel_ms, from the stage-3 calibration table
@@ -31,14 +32,16 @@ module SecurityBox
     BOOT_FUEL_ALLOWANCE = 1_000_000_000
 
     attr_reader :image_path, :fuel, :fuel_ms, :timeout_ms, :memory_size,
-                :stdout_limit, :stderr_limit, :epoch_interval_ms, :env, :mounts
+                :stdout_limit, :stderr_limit, :epoch_interval_ms, :env, :mounts,
+                :rpcs
 
     def self.build(**options)
       new(**DEFAULTS.merge(options)).freeze
     end
 
     def initialize(image_path: nil, fuel:, fuel_ms:, timeout_ms:, memory_size:,
-                   stdout_limit:, stderr_limit:, epoch_interval_ms:, env:, mounts:)
+                   stdout_limit:, stderr_limit:, epoch_interval_ms:, env:, mounts:,
+                   rpcs:)
       @image_path = image_path || default_image_path
       @fuel = Integer(fuel)
       @fuel_ms = fuel_ms.nil? ? nil : Integer(fuel_ms)
@@ -49,6 +52,7 @@ module SecurityBox
       @epoch_interval_ms = Integer(epoch_interval_ms)
       @env = env.freeze
       @mounts = Mounts.normalize(mounts)
+      @rpcs = Rpcs.normalize(rpcs)
       freeze
     end
 
@@ -91,7 +95,8 @@ module SecurityBox
         stderr_limit: @stderr_limit,
         epoch_interval_ms: @epoch_interval_ms,
         env: @env,
-        mounts: @mounts
+        mounts: @mounts,
+        rpcs: @rpcs
       }
     end
 
@@ -99,12 +104,16 @@ module SecurityBox
     # hash). Two configurations with equal settings — regardless of how they
     # were built — share the same fingerprint; any #with change produces a
     # different one. Used to key profiles and, later, cached artifacts.
+    #
+    # RPC handlers are deliberately excluded: they are host-side callables
+    # (Procs) with no stable serialized identity, and including them would
+    # make the fingerprint depend on object addresses.
     def fingerprint
       Digest::SHA256.hexdigest(JSON.generate(canonical))
     end
 
     def canonical
-      to_h.merge(env: @env.sort.to_h)
+      to_h.except(:rpcs).merge(env: @env.sort.to_h)
     end
 
     # Mutable collector for the register DSL. Setter names match the
@@ -177,6 +186,26 @@ module SecurityBox
         add_mount(mapping, :read_write)
       end
 
+      # Registers a guest-callable RPC handler (stage 6):
+      #   c.rpc "github.search" => ->(args) { ... }
+      #   c.rpc github_search: ->(args) { ... }
+      # Each call appends one handler; the per-call :rpcs override replaces
+      # the whole set. See SecurityBox::Rpcs for the validation rules.
+      def rpc(mapping = nil, **kwargs)
+        unless kwargs.empty?
+          raise InvalidConfiguration, 'rpc expects exactly one pair: c.rpc "name" => handler' unless kwargs.size == 1 && mapping.nil?
+
+          name, handler = kwargs.first
+          mapping = { name.to_s => handler }
+        end
+        unless mapping.is_a?(Hash) && mapping.size == 1
+          raise InvalidConfiguration,
+                'rpc expects exactly one pair: c.rpc "name" => handler'
+        end
+
+        @changes[:rpcs] = Array(@changes[:rpcs]) + [mapping]
+      end
+
       private
 
       def add_mount(mapping, mode)
@@ -322,4 +351,67 @@ module SecurityBox
       end
     end
   end
+
+  # Validated collection of guest-callable RPC handlers (stage 6). A
+  # handler is a name => callable pair; `rpcs` in a Configuration is a
+  # frozen hash, so the value survives #with and #to_h.
+  #
+  # Handlers execute on the host (between guest steps, inside the RPC
+  # import) and are therefore host-only state: they are excluded from
+  # #fingerprint, and a Configuration carrying Procs is not
+  # Ractor-shareable — RactorPool rejects rpcs and strips them before a
+  # config crosses a Ractor boundary.
+  #
+  # Validation (InvalidConfiguration on any violation):
+  #   - raw is a Hash of name => handler, or an Array of one-pair hashes
+  #     (the register DSL appends one pair per c.rpc call)
+  #   - name: non-empty String, unique
+  #   - handler: anything responding to #call; it receives the
+  #     JSON-parsed request args and must return a JSON-serializable
+  #     value (non-serializable results surface as inspect strings)
+  #   - at most MAX_RPCS handlers
+  module Rpcs
+    MAX_RPCS = 64
+
+    class << self
+      # Validates + normalizes `raw` and returns a frozen
+      # name => handler hash.
+      def normalize(raw)
+        return {}.freeze if raw.nil?
+
+        pairs = case raw
+                when Hash then raw.entries
+                when Array
+                  unless raw.all? { |entry| entry.is_a?(Hash) && entry.size == 1 }
+                    raise InvalidConfiguration,
+                          "rpcs must be a Hash or an Array of one-pair hashes, " \
+                          "got #{raw.inspect[0, 80]}"
+                  end
+                  raw.flat_map(&:entries)
+                else
+                  raise InvalidConfiguration,
+                        "rpcs must be a Hash of name => handler, got #{raw.class}"
+                end
+
+        rpcs = {}
+        pairs.each do |name, handler|
+          unless name.is_a?(String) && !name.empty?
+            raise InvalidConfiguration, "rpc name must be a non-empty String, got #{name.inspect}"
+          end
+          unless handler.respond_to?(:call)
+            raise InvalidConfiguration,
+                  "rpc handler for #{name.inspect} must respond to #call, " \
+                  "got #{handler.inspect[0, 80]}"
+          end
+          raise InvalidConfiguration, "duplicate rpc name #{name.inspect}" if rpcs.key?(name)
+
+          rpcs[name] = handler
+        end
+        return rpcs.freeze if rpcs.size <= MAX_RPCS
+
+        raise InvalidConfiguration,
+              "too many rpcs (#{rpcs.size}); the limit is #{MAX_RPCS}"
+      end
+    end
+  end
 end

data/lib/security_box/eval_run.rb

@@ -44,6 +44,13 @@ module SecurityBox
 
         Dir.mktmpdir("security_box") do |workdir|
           File.write(File.join(workdir, CODE_FILE), code)
+          # Per-eval RPC state (stage 6): the /work tmpdir plus the
+          # configuration's handlers (nil when none are configured — the
+          # import is still defined, guest calls get a rescuable error).
+          # The calls array doubles as the Result transcript.
+          rpc_data = GuestRpc.store_data(
+            workdir, config.rpcs.empty? ? nil : config.rpcs
+          )
           envelope = nil
           status = nil
           fuel_used = nil
@@ -52,6 +59,7 @@ module SecurityBox
           begin
             store = Wasmtime::Store.new(
               engine,
+              rpc_data,
               wasi_p1_config: build_wasi(workdir, stdout, stderr, config, token),
               limits: { memory_size: config.memory_size }
             )
@@ -70,7 +78,8 @@ module SecurityBox
             store&.close
           end
 
-          build_result(status, envelope, stdout, stderr, fuel_used, monotonic_ms - t0)
+          build_result(status, envelope, stdout, stderr, fuel_used,
+                       monotonic_ms - t0, rpc_data[:rpc]&.fetch(:calls))
         end
       end
 
@@ -145,12 +154,13 @@ module SecurityBox
         nil
       end
 
-      def build_result(status, envelope, stdout, stderr, fuel_used, duration_ms)
+      def build_result(status, envelope, stdout, stderr, fuel_used, duration_ms, rpc_calls = nil)
+        rpcs = rpc_calls && !rpc_calls.empty? ? rpc_calls.each(&:freeze).freeze : nil
         if envelope.nil?
           status = :sandbox_error if status == :ok
           return Result.new(
             status: status, stdout: stdout, stderr: stderr,
-            fuel_used: fuel_used, duration_ms: duration_ms
+            fuel_used: fuel_used, duration_ms: duration_ms, rpcs: rpcs
           )
         end
 
@@ -159,7 +169,7 @@ module SecurityBox
           Result.new(
             status: status, value: envelope["value"], stdout: stdout, stderr: stderr,
             fuel_used: fuel_used, duration_ms: duration_ms,
-            guest_duration_ms: envelope["duration_ms"]
+            guest_duration_ms: envelope["duration_ms"], rpcs: rpcs
           )
         elsif guest_memory_error?(guest_error)
           # The guest hit the store memory limit through the Ruby interpreter
@@ -168,13 +178,13 @@ module SecurityBox
           Result.new(
             status: :memory_limit, error: guest_error, stdout: stdout, stderr: stderr,
             fuel_used: fuel_used, duration_ms: duration_ms,
-            guest_duration_ms: envelope["duration_ms"]
+            guest_duration_ms: envelope["duration_ms"], rpcs: rpcs
           )
         else
           Result.new(
             status: :error, error: guest_error, stdout: stdout, stderr: stderr,
             fuel_used: fuel_used, duration_ms: duration_ms,
-            guest_duration_ms: envelope["duration_ms"]
+            guest_duration_ms: envelope["duration_ms"], rpcs: rpcs
           )
         end
       end

data/lib/security_box/guest/main.rb

@@ -16,7 +16,6 @@ require_relative "prelude"
 module SB
   SENTINEL = "__SECURITY_BOX_RESULT__"
   WORK_DIR = "/work"
-
   module_function
 
   def run
@@ -97,4 +96,8 @@ module SB
   end
 end
 
+# Guest RPC bridge (SB.call + SB::ToolError) — reopens the SB module
+# above; must load after it.
+require_relative "rpc"
+
 SB.run

data/lib/security_box/guest/rpc.rb

@@ -0,0 +1,77 @@
+# Guest-side host RPC bridge (loaded by main.rb before user code).
+#
+# User code calls SB.call(name, args) and it behaves like a regular,
+# blocking Ruby function: the request is written to /work/rpc_req.json,
+# the wasm import (SBExt.call — the sb_rpc gem statically linked into
+# the image) is invoked, and the guest blocks while the host executes
+# the registered handler. The response is read back from
+# /work/rpc_resp.json.
+#
+# Handler failures never cross the wasm boundary: the host encodes them
+# as {"ok": false, "error": {"class", "message"}} responses, surfaced
+# here as SB::ToolError (SB::UnknownTool for unregistered names) so user
+# code can rescue them.
+module SB
+  # Raised when an RPC handler fails or its result is unusable.
+  class ToolError < StandardError; end
+
+  # Raised when the code calls a name the host did not register —
+  # including when the sandbox has no handlers configured at all.
+  class UnknownTool < ToolError; end
+
+  # Raised when the transport itself fails (image without the guest
+  # gems, broken /work channel).
+  class RpcUnavailable < StandardError; end
+
+  begin
+    # /bundle/setup.rb is generated by the image build; it adds the gem
+    # lib dirs to $LOAD_PATH. The gems are absent when the image was
+    # built without the guest_ext bundle; SB.call then reports it
+    # cleanly instead of crashing on NameError.
+    require "/bundle/setup.rb"
+    require "sb_rpc"
+  rescue LoadError
+    nil
+  end
+
+  module_function
+
+  # Calls a host-registered handler and returns its result. Behaves as a
+  # blocking function call; the LLM-facing contract is plain Ruby.
+  #
+  #   SB.call("github.search", q: "x")          # kwargs form
+  #   SB.call("github.search", { "q" => "x" })  # positional hash form
+  #
+  # `name` and `args` must be JSON-serializable; handlers receive the
+  # JSON-parsed args (string keys) and return a JSON-serializable value.
+  def call(name, args = nil, **kwargs)
+    unless name.is_a?(String) && !name.empty?
+      raise ArgumentError, "rpc name must be a non-empty String, got #{name.inspect}"
+    end
+    unless defined?(SBExt)
+      raise RpcUnavailable, "rpc support is not available in this image (sb_rpc gem missing)"
+    end
+
+    merged = args.nil? ? {} : args
+    merged = merged.merge(kwargs) unless kwargs.empty?
+    request = begin
+      JSON.generate({ name: name, args: merged })
+    rescue StandardError, TypeError => e
+      raise TypeError, "rpc arguments must be JSON-serializable: #{e.message}"
+    end
+
+    File.write(File.join(WORK_DIR, "rpc_req.json"), request)
+    status = SBExt.call
+    unless status.zero?
+      raise RpcUnavailable, "rpc transport failed (status #{status})"
+    end
+
+    response = JSON.parse(File.read(File.join(WORK_DIR, "rpc_resp.json")))
+    unless response["ok"]
+      error = response["error"] || {}
+      klass = error["class"] == "SB::UnknownTool" ? UnknownTool : ToolError
+      raise klass, error["message"].to_s
+    end
+    response["result"]
+  end
+end

data/lib/security_box/guest_ext/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+# Build tooling — excluded from the image by the packager (EXCLUDED_GEMS),
+# present here so `bundle exec rbwasm` works inside this bundle.
+gem "ruby_wasm", "~> 2.10.1"
+
+# Guest image gems (built into the wasm image by `rbwasm build`; see
+# Rakefile). Only guest-safe dependencies belong here — host-only gems
+# (wasmtime) must stay in the project Gemfile.
+gem "sb_rpc", path: "sb_rpc"

data/lib/security_box/guest_ext/Gemfile.lock

@@ -0,0 +1,31 @@
+PATH
+  remote: sb_rpc
+  specs:
+    sb_rpc (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    logger (1.7.0)
+    ruby_wasm (2.10.1)
+      logger
+    ruby_wasm (2.10.1-x86_64-linux)
+      logger
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  ruby_wasm (~> 2.10.1)
+  sb_rpc!
+
+CHECKSUMS
+  bundler (4.0.20) sha256=7978a8ac648767f5e635bc522445b79e80a52b907a39a36c2d8085ed6bc762ae
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  ruby_wasm (2.10.1) sha256=874e0acb783a8326bfb0db892004816c26963a4276a9f719791a8828e53a05f1
+  ruby_wasm (2.10.1-x86_64-linux) sha256=728e29dc688246572b56dcef1c7b131431d07865320c9b8434dd1ccdfd63db2b
+  sb_rpc (0.1.0)
+
+BUNDLED WITH
+  4.0.20

data/lib/security_box/guest_ext/sb_rpc/ext/sb_rpc/extconf.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+create_makefile("sb_rpc")

data/lib/security_box/guest_ext/sb_rpc/ext/sb_rpc/sb_rpc.c

@@ -0,0 +1,29 @@
+#include <ruby.h>
+#include <stdint.h>
+
+/*
+ * Host bridge for security_box RPC.
+ *
+ * sb_rpc_call is resolved as a wasm import by the host
+ * (Wasmtime::Linker#func_new, module "sb", function "call"). The guest
+ * blocks inside this call while the host executes the registered handler;
+ * the host returns 0 on success (any other value signals a transport
+ * failure). The request/response payload travels via /work JSON files
+ * written/read by the guest-side Ruby wrapper (sb_rpc.rb in the image),
+ * keeping this C code free of any protocol knowledge.
+ */
+__attribute__((import_module("sb"), import_name("call")))
+extern int32_t sb_rpc_call(void);
+
+static VALUE
+sb_call(VALUE self)
+{
+    return INT2NUM(sb_rpc_call());
+}
+
+void
+Init_sb_rpc(void)
+{
+    VALUE mSBExt = rb_define_module("SBExt");
+    rb_define_singleton_method(mSBExt, "call", sb_call, 0);
+}

data/lib/security_box/guest_ext/sb_rpc/lib/sb_rpc.rb

@@ -0,0 +1,6 @@
+# Loaded by `require "sb_rpc"` inside the security_box guest image.
+#
+# The extension is statically linked into the ruby.wasm binary; requiring
+# the .so feature name triggers its Init_sb_rpc hook through the static
+# extension registry.
+require "sb_rpc.so"

data/lib/security_box/guest_ext/sb_rpc/sb_rpc.gemspec

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = "sb_rpc"
+  spec.version = "0.1.0"
+  spec.summary = "Host RPC bridge for security_box guest images"
+  spec.description =
+    "Exposes SBExt.call, a wasm import bridge the guest uses to invoke " \
+    "host-registered RPC handlers. The call blocks inside the sandbox while " \
+    "the host executes the handler; the request/response travel via JSON " \
+    "files in /work."
+  spec.authors = ["security_box"]
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+  spec.files = Dir["lib/**/*.rb", "ext/**/*.{c,h,rb}"] + ["sb_rpc.gemspec"]
+  spec.extensions = ["ext/sb_rpc/extconf.rb"]
+end

data/lib/security_box/guest_rpc.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SecurityBox
+  # Host side of the guest RPC channel (stage 6).
+  #
+  # The image statically links the sb_rpc gem, whose C extension declares
+  # the wasm import ("sb", "call"). The linker must define it for every
+  # instantiation — even when no handlers are configured, or instantiation
+  # fails on an unresolved import. Per-eval state (the /work tmpdir, the
+  # handler map and the call transcript) travels through Store data and
+  # reaches the closure via caller.store_data, so a single definition is
+  # safe to share across evaluations, threads and Ractor workers.
+  #
+  # Protocol (guest side: lib/security_box/guest/rpc.rb):
+  #   guest writes /work/rpc_req.json  {"name", "args"}
+  #   guest calls SBExt.call           (blocks inside the import)
+  #   host executes handlers[name], writes /work/rpc_resp.json
+  #   host returns 0 (any non-zero value is a transport failure)
+  #
+  # Nothing escapes the closure: a raising handler (or any failure in the
+  # bridge) becomes an {"ok": false, "error": {"class", "message"}}
+  # response the guest can rescue. Messages never include host details
+  # (no backtraces, no paths). Handler results are JSON round-tripped,
+  # like guest return values — never Marshal.
+  module GuestRpc
+    IMPORT_MODULE = "sb"
+    IMPORT_NAME = "call"
+    REQUEST_FILE = "rpc_req.json"
+    RESPONSE_FILE = "rpc_resp.json"
+    MAX_CALLS = 1_000
+    RESULT_LIMIT = 1 << 20
+
+    class << self
+      # Defines the import on `linker` (once per linker; state is
+      # per-Store). The closure captures nothing — Ractor-safe.
+      def define_import(linker)
+        linker.func_new(IMPORT_MODULE, IMPORT_NAME, [], [:i32]) do |caller|
+          serve(caller)
+        end
+        nil
+      end
+
+      # Per-eval Store data. `handlers` is the configuration's
+      # name => callable map, or nil when no rpcs are configured (guest
+      # calls still get a clean, rescuable error).
+      def store_data(workdir, handlers)
+        {
+          workdir: workdir,
+          rpc: handlers.nil? ? nil : { handlers: handlers, calls: [] }
+        }
+      end
+
+      private
+
+      def serve(caller)
+        data = caller.store_data
+        rpc = data[:rpc]
+        unless rpc
+          return fail_call(data, nil, "SB::UnknownTool",
+                           "no RPC handlers are configured for this sandbox")
+        end
+
+        request = JSON.parse(File.read(request_path(data)))
+        entry = { "name" => request["name"], "args" => request["args"] }
+        rpc[:calls] << entry
+        dispatch(data, rpc, request, entry)
+        0
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # Transport/boundary failure (unparsable request, broken /work):
+        # encoded as a tool error so the guest gets a rescuable exception
+        # instead of the host crashing through the wasm boundary.
+        fail_call(data, nil, e.class.name, e.message.to_s)
+      end
+
+      def dispatch(data, rpc, request, entry)
+        if rpc[:calls].size > MAX_CALLS
+          return fail_call(data, entry, "SB::ToolError",
+                           "too many RPC calls (limit #{MAX_CALLS})")
+        end
+
+        handler = rpc[:handlers][request["name"]]
+        if handler.nil?
+          return fail_call(data, entry, "SB::UnknownTool",
+                           "unknown rpc: #{request["name"]}")
+        end
+
+        result = jsonable(handler.call(request["args"]))
+        payload = { "ok" => true, "result" => result }
+        if JSON.generate(payload).bytesize > RESULT_LIMIT
+          return fail_call(data, entry, "SB::ToolError",
+                           "rpc result too large (limit #{RESULT_LIMIT} bytes)")
+        end
+
+        entry["ok"] = true
+        entry["result"] = result
+        write_response(data, payload)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        fail_call(data, entry, e.class.name, e.message.to_s)
+      end
+
+      def fail_call(data, entry, klass, message)
+        error = { "class" => klass, "message" => message }
+        # The entry (when present) is already in the transcript — mutate
+        # it in place instead of pushing a duplicate.
+        if entry
+          entry["ok"] = false
+          entry["error"] = error
+        end
+        write_response(data, { "ok" => false, "error" => error })
+        0
+      end
+
+      def request_path(data)
+        File.join(data[:workdir], REQUEST_FILE)
+      end
+
+      def write_response(data, payload)
+        File.write(File.join(data[:workdir], RESPONSE_FILE), JSON.generate(payload))
+      end
+
+      # Non-serializable handler results surface as inspect strings, like
+      # guest return values (PLAN.md: never Marshal guest/host payloads).
+      def jsonable(value)
+        JSON.parse(JSON.generate(value))
+      rescue StandardError, TypeError
+        value.inspect
+      end
+    end
+  end
+end

data/lib/security_box/ractor_pool.rb

@@ -45,6 +45,8 @@ module SecurityBox
       raise ArgumentError, "size must be >= 1" if @size < 1
 
       @config = resolve_config(profile, options)
+      raise InvalidConfiguration, "rpcs are not supported on RactorPool (handlers cannot cross a Ractor boundary)" unless @config.rpcs.empty?
+
       @mutex = Mutex.new
       @pending = {} # request id => Queue
       @in_flight = Array.new(@size, 0)
@@ -64,10 +66,16 @@ module SecurityBox
 
     # Runs `code` on one of the workers and blocks until its Result arrives.
     # Per-call overrides follow Sandbox#eval (same Configuration#with rules).
+    #
+    # RPC handlers are not supported here (v1): they are host Procs that
+    # cannot cross a Ractor boundary. A configuration with rpcs raises
+    # InvalidConfiguration at construction.
     def eval(code, **overrides)
       raise PoolClosed, "pool is closed" if closed?
 
       config = overrides.empty? ? @config : @config.with(**overrides)
+      raise InvalidConfiguration, "rpcs are not supported on RactorPool (handlers cannot cross a Ractor boundary)" unless config.rpcs.empty?
+
       request = {
         id: next_id,
         code: code,
@@ -136,7 +144,14 @@ module SecurityBox
 
     def build_worker(engine, module_, worker_index)
       Ractor.new(engine, module_, worker_index, name: "security_box-worker-#{worker_index}") do |eng, mod, index|
-        linker = Wasmtime::Linker.new(eng).tap { |l| Wasmtime::WASI::P1.add_to_linker_sync(l) }
+        linker = Wasmtime::Linker.new(eng).tap do |l|
+          Wasmtime::WASI::P1.add_to_linker_sync(l)
+          # The image statically links the sb_rpc extension, so the
+          # "sb"/"call" import must be defined even though configs are
+          # stripped of rpcs before crossing the Ractor boundary
+          # (guest calls get a rescuable error via caller.store_data).
+          SecurityBox::GuestRpc.define_import(l)
+        end
         loop do
           request = Ractor.receive
           break if request == :security_box_stop

data/lib/security_box/result.rb

@@ -8,12 +8,17 @@ module SecurityBox
   #   :fuel_exhausted — CPU budget exhausted
   #   :memory_limit   — exceeded the store memory_size
   #   :sandbox_error  — sandbox failure (unexpected trap, missing/invalid envelope)
+  #
+  # `rpcs` (stage 6): the host-side transcript of guest RPC calls, one
+  # frozen {"name", "args", "ok", "result"|"error"} entry per call, or nil
+  # when no rpcs were configured (or none were called).
   class Result
     attr_reader :status, :value, :error, :stdout, :stderr,
-                :fuel_used, :duration_ms, :guest_duration_ms
+                :fuel_used, :duration_ms, :guest_duration_ms, :rpcs
 
     def initialize(status:, value: nil, error: nil, stdout: "", stderr: "",
-                   fuel_used: nil, duration_ms: nil, guest_duration_ms: nil)
+                   fuel_used: nil, duration_ms: nil, guest_duration_ms: nil,
+                   rpcs: nil)
       @status = status
       @value = value
       @error = error
@@ -22,6 +27,7 @@ module SecurityBox
       @fuel_used = fuel_used
       @duration_ms = duration_ms
       @guest_duration_ms = guest_duration_ms
+      @rpcs = rpcs
       freeze
     end
 
@@ -45,7 +51,8 @@ module SecurityBox
         stderr: @stderr,
         fuel_used: @fuel_used,
         duration_ms: @duration_ms,
-        guest_duration_ms: @guest_duration_ms
+        guest_duration_ms: @guest_duration_ms,
+        rpcs: @rpcs
       }
     end
   end

data/lib/security_box/sandbox.rb

@@ -43,6 +43,10 @@ module SecurityBox
       @linker_mutex.synchronize do
         @linker ||= Wasmtime::Linker.new(@engine).tap do |linker|
           Wasmtime::WASI::P1.add_to_linker_sync(linker)
+          # The image statically links the sb_rpc extension, so the
+          # "sb"/"call" import must be defined even when no rpcs are
+          # configured (state is per-Store; see GuestRpc).
+          GuestRpc.define_import(linker)
         end
       end
     end

data/lib/security_box/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SecurityBox
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/security_box.rb

@@ -8,6 +8,7 @@ require_relative "security_box/result"
 require_relative "security_box/module_cache"
 require_relative "security_box/runtime"
 require_relative "security_box/envelope"
+require_relative "security_box/guest_rpc"
 require_relative "security_box/sandbox"
 require_relative "security_box/eval_run"
 require_relative "security_box/pool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: security_box
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Marcelo Junior
@@ -44,6 +44,14 @@ files:
 - lib/security_box/eval_run.rb
 - lib/security_box/guest/main.rb
 - lib/security_box/guest/prelude.rb
+- lib/security_box/guest/rpc.rb
+- lib/security_box/guest_ext/Gemfile
+- lib/security_box/guest_ext/Gemfile.lock
+- lib/security_box/guest_ext/sb_rpc/ext/sb_rpc/extconf.rb
+- lib/security_box/guest_ext/sb_rpc/ext/sb_rpc/sb_rpc.c
+- lib/security_box/guest_ext/sb_rpc/lib/sb_rpc.rb
+- lib/security_box/guest_ext/sb_rpc/sb_rpc.gemspec
+- lib/security_box/guest_rpc.rb
 - lib/security_box/module_cache.rb
 - lib/security_box/pool.rb
 - lib/security_box/ractor_pool.rb