class LittleGhost::CodeMode::RubyEngine

Runs model-written Ruby in a fresh sandboxed process.

Tool calls cross a bounded protocol to the trusted parent Broker. The engine uses only Ruby’s standard library and adds no runtime dependency.

LittleGhost.configure do |config|
  config.code_mode = {engine: :ruby, sandbox: :native}
end

Constants

DEFAULT_LIMITS: Resource, Tool-call, and program limits applied when the application does not override them.

Public Instance Methods

instructions (catalog:)

Source

# File lib/little_ghost/code_mode/ruby_engine.rb, line 37
      def instructions(catalog:)
        <<~INSTRUCTIONS.strip
          Use Ruby to call the available tools and compose their results.

          Program lifecycle:
          - Every exec call starts a fresh program in a new Ruby process.
          - Exec and wait observe it for up to one minute. They return sooner when it finishes.
          - If exec or wait returns `still_working`, call wait to observe the same running program again.
          - Wait does not pause, resume, or restart the program.
          - Use stop when the result is no longer needed.
          - Do not call wait or stop after `completed`, `error`, or `terminated`.
          - Local variables, constants, and other process state do not persist between exec calls.

          Tool calls:
          - Call a tool with `tools.<method>(keyword: value)` and only its documented keywords.
          - Use `tools.call(name, arguments)` when the name is dynamic.
          - Tool calls are synchronous. Use `tools.parallel` for independent calls; results keep callable order.
          - JSON results become ordinary Ruby values. Other results remain strings.
          - A failed call raises. Rescue it only when the program can recover.
          - `ALL_TOOLS` contains the complete runtime catalog.

          Output and completion:
          - The final Ruby expression becomes the completed program value.
          - Use `text(value)` for user-visible output.
          - Ordinary `puts`, `print`, `printf`, and `p` output is captured and combined into bounded chunks.
          - Use `finish(value)` to complete early with a value.

          The Sandbox controls filesystem, network, subprocess, and optional-library access. Do not assume host
          capabilities are available.

          Available tool methods:

          #{Ruby::Catalog.new(catalog).declarations}
        INSTRUCTIONS
      end

Builds Ruby usage instructions and method declarations for catalog.

language ()

Source

# File lib/little_ghost/code_mode/ruby_engine.rb, line 34
def language = :ruby

Returns the :ruby language identifier.

open_session (broker:, sandbox_factory:, limits: {})

Source

# File lib/little_ghost/code_mode/ruby_engine.rb, line 75
def open_session(broker:, sandbox_factory:, limits: {})
  Ruby::Session.new(
    broker:,
    sandbox_factory:,
    subprocess_policy: method(:allow_subprocesses_for),
    limits: normalize_limits(limits, defaults: DEFAULT_LIMITS)
  )
end

Opens a Ruby Session with engine defaults merged with limits. Unsupported limit keys raise ArgumentError.