little_ghost 0.7.0 → 0.9.0

data/lib/little_ghost/code_mode/javascript/host.rb

@@ -16,6 +16,18 @@ module LittleGhost
       JAVASCRIPT_TIMEOUT_MS = 10_000
       MAX_PENDING_TOOL_CALLS = 1_024
       Terminated = Class.new(StandardError)
+      DEFAULT_MESSAGES = {
+        "execution_limit" => "JavaScript execution exceeded its limit.",
+        "memory_limit" => "JavaScript execution exceeded its memory limit.",
+        "cleanup_failed" => "JavaScript context cleanup failed.",
+        "pending_calls_limit" => "The code-mode program exceeded the pending Tool-call limit.",
+        "active_programs_limit" => "The code-mode host has too many active programs.",
+        "invalid_request" => "Invalid code-mode request: __DETAIL__",
+        "unavailable_tool" => "Unavailable code-mode Tool: __TOOL_NAME__",
+        "execution_failed" => "__ERROR_CLASS__: __ERROR_MESSAGE__",
+        "source_size_limit" => "Code-mode source exceeds the size limit.",
+        "tools_array" => "Code-mode tools must be an array."
+      }.freeze
 
       BOOTSTRAP = <<~'JAVASCRIPT'
         const __LITTLE_GHOST_CONTROL_IDENTIFIER__ = (() => {
@@ -26,6 +38,7 @@ module LittleGhost
           const outputs = [];
           const pending = new Map();
           const exitSignal = Object.freeze({exit: true});
+          const unavailableToolMessage = __LITTLE_GHOST_UNAVAILABLE_TOOL_MESSAGE__;
           let nextCallId = 0;
           let done = false;
           let failure = null;
@@ -40,7 +53,7 @@ module LittleGhost
 
           const enqueue = (name, args) => new Promise((resolve, reject) => {
             if (!Object.prototype.hasOwnProperty.call(definitionIndex, name)) {
-              reject(new Error(`Unknown tool: ${name}`));
+              reject(new Error(unavailableToolMessage.split("__TOOL_NAME__").join(name)));
               return;
             }
             const id = String(++nextCallId);
@@ -129,10 +142,11 @@ module LittleGhost
       JAVASCRIPT
 
       class Program
-        def initialize(id:, source:, tools:, writer:, finished:)
+        def initialize(id:, source:, tools:, writer:, finished:, messages: nil)
           @id = id
           @source = source
           @tools = tools
+          @messages = DEFAULT_MESSAGES.merge(messages || {}).freeze
           @writer = writer
           @finished = finished
           @incoming = Queue.new
@@ -175,7 +189,11 @@ module LittleGhost
           context.eval(
             BOOTSTRAP
               .gsub("__LITTLE_GHOST_CONTROL_IDENTIFIER__", @control_identifier)
-              .sub("__LITTLE_GHOST_TOOL_DEFINITIONS__", definitions),
+              .sub("__LITTLE_GHOST_TOOL_DEFINITIONS__", definitions)
+              .sub(
+                "__LITTLE_GHOST_UNAVAILABLE_TOOL_MESSAGE__",
+                JSON.generate(@messages.fetch("unavailable_tool"))
+              ),
             filename: "little-ghost-code-mode-bootstrap.js"
           )
           call_control(context, :run, @source)
@@ -186,15 +204,18 @@ module LittleGhost
           terminal = if @context_mutex.synchronize { @terminating }
             {type: "terminated"}
           else
-            {type: "failed", error: "JavaScript execution exceeded its limit", fatal: true}
+            {type: "failed", error: @messages.fetch("execution_limit"), fatal: true}
           end
         rescue MiniRacer::V8OutOfMemoryError
-          terminal = {type: "failed", error: "JavaScript execution exceeded its memory limit", fatal: true}
+          terminal = {type: "failed", error: @messages.fetch("memory_limit"), fatal: true}
         rescue => error
-          terminal = {type: "failed", error: "#{error.class}: #{error.message}", fatal: true}
+          failure = @messages.fetch("execution_failed")
+            .gsub("__ERROR_CLASS__") { error.class.to_s }
+            .gsub("__ERROR_MESSAGE__") { error.message }
+          terminal = {type: "failed", error: failure, fatal: true}
         ensure
           cleanup_error = dispose_context
-          terminal = {type: "failed", error: "JavaScript context cleanup failed", fatal: true} if cleanup_error
+          terminal = {type: "failed", error: @messages.fetch("cleanup_failed"), fatal: true} if cleanup_error
           begin
             emit(**terminal) if terminal
           ensure
@@ -210,7 +231,7 @@ module LittleGhost
             if calls.length > MAX_PENDING_TOOL_CALLS
               return {
                 type: "failed",
-                error: "Code-mode program exceeded the pending tool-call limit",
+                error: @messages.fetch("pending_calls_limit"),
                 fatal: true
               }
             end
@@ -308,23 +329,26 @@ module LittleGhost
           id = message.fetch("program_id").to_s
           source = message.fetch("source").to_s
           tools = message.fetch("tools")
-          raise Protocol::Error, "Code-mode source exceeds the size limit" if source.bytesize > MAX_SOURCE_BYTES
-          raise Protocol::Error, "Code-mode tools must be an array" unless tools.is_a?(Array)
+          messages = DEFAULT_MESSAGES.merge(message["messages"] || {})
+          raise Protocol::Error, messages.fetch("source_size_limit") if source.bytesize > MAX_SOURCE_BYTES
+          raise Protocol::Error, messages.fetch("tools_array") unless tools.is_a?(Array)
 
           created = @programs_mutex.synchronize do
             next false if @programs.key?(id) || @programs.length >= MAX_ACTIVE_PROGRAMS
 
             @programs[id] = Program.new(
-              id:, source:, tools:, writer: method(:write),
+              id:, source:, tools:, messages:, writer: method(:write),
               finished: ->(program_id) { @programs_mutex.synchronize { @programs.delete(program_id) } }
             )
             true
           end
           unless created
-            write(type: "failed", program_id: id, error: "Code-mode host has too many active programs", fatal: true)
+            write(type: "failed", program_id: id, error: messages.fetch("active_programs_limit"), fatal: true)
           end
         rescue KeyError, TypeError, Protocol::Error => error
-          write(type: "failed", program_id: id.to_s, error: "Invalid code-mode request: #{error.message}", fatal: true)
+          template = messages.fetch("invalid_request")
+          detail = error.message
+          write(type: "failed", program_id: id.to_s, error: template.gsub("__DETAIL__") { detail }, fatal: true)
         end
 
         def program(id)

data/lib/little_ghost/code_mode/javascript/session.rb

@@ -17,12 +17,14 @@ module LittleGhost
       Deadline = Struct.new(:task, :cancelled, :expiring, :finished, :error)
 
       def initialize(broker:, client:, sandbox: nil, workspace: nil, max_concurrency: 8,
-        wall_seconds: 3_600, observation_seconds: OBSERVATION_SECONDS, cleanup_timeout: CLEANUP_TIMEOUT)
+        wall_seconds: 3_600, observation_seconds: OBSERVATION_SECONDS, cleanup_timeout: CLEANUP_TIMEOUT,
+        framework_prompt_scope: {})
         @broker = broker
         @task_runner = broker.task_runner
         @client = client
         @sandbox = sandbox
         @workspace = workspace
+        @framework_prompt_scope = framework_prompt_scope.freeze
         @max_concurrency = Integer(max_concurrency)
         raise ArgumentError, "max_concurrency must be positive" unless @max_concurrency.positive?
         @wall_seconds = Float(wall_seconds)
@@ -119,6 +121,16 @@ module LittleGhost
 
       private
 
+      def prompt(key, **locals)
+        framework_prompts = @framework_prompt_scope[:framework_prompts] || FrameworkPrompts.new
+        framework_prompts.render(
+          key,
+          locals:,
+          invocation_paths: @framework_prompt_scope.fetch(:invocation_paths, []),
+          agent_path: @framework_prompt_scope[:agent_path]
+        )
+      end
+
       def execute_program(source:, catalog:, frame:, max_output_tokens:, context:)
         ensure_open
         raise_pending_deadline_error!
@@ -126,7 +138,7 @@ module LittleGhost
         program_id = SecureRandom.uuid
         @frames_mutex.synchronize do
           if @current_program_id
-            raise LittleGhost::ToolError, "Wait for or stop the active JavaScript program before starting another"
+            raise LittleGhost::ToolError, prompt("code_mode/feedback/program_active")
           end
           @frames[program_id] = javascript_catalog
           @current_program_id = program_id
@@ -152,7 +164,7 @@ module LittleGhost
         ensure_open
         program_id = @frames_mutex.synchronize { @current_program_id }
         raise_pending_deadline_error! unless program_id
-        raise LittleGhost::ToolError, "There is no active JavaScript program" unless program_id
+        raise LittleGhost::ToolError, prompt("code_mode/feedback/not_active") unless program_id
         result = @client.observe(
           owner: self, program_id:, timeout: @observation_seconds,
           max_tokens: output_tokens(max_output_tokens), context:
@@ -175,7 +187,7 @@ module LittleGhost
         context&.check!
         program_id = @frames_mutex.synchronize { @current_program_id }
         raise_pending_deadline_error! unless program_id
-        raise LittleGhost::ToolError, "There is no active JavaScript program" unless program_id
+        raise LittleGhost::ToolError, prompt("code_mode/feedback/not_active") unless program_id
 
         finish(program_id, terminate_program(program_id, max_output_tokens:))
       rescue LittleGhost::CleanupError
@@ -196,7 +208,7 @@ module LittleGhost
           )
         end
         @mutex.synchronize do
-          raise LittleGhost::ToolError, "Code-mode session is closed" if @closed
+          raise LittleGhost::ToolError, prompt("code_mode/feedback/closed", resource: "session") if @closed
 
           ensure_worker
           register_dispatch(batch)
@@ -213,7 +225,7 @@ module LittleGhost
       def with_control
         acquired = @control_mutex.try_lock
         unless acquired
-          raise LittleGhost::ToolError, "another code-mode control operation is already active"
+          raise LittleGhost::ToolError, prompt("code_mode/feedback/control_active")
         end
 
         yield
@@ -441,8 +453,8 @@ module LittleGhost
 
       def ensure_open
         @mutex.synchronize do
-          raise LittleGhost::ToolError, "Code-mode session is closed" if @closed
-          raise LittleGhost::ToolError, "Code-mode session cannot be reused after cleanup failed" if @poisoned
+          raise LittleGhost::ToolError, prompt("code_mode/feedback/closed", resource: "session") if @closed
+          raise LittleGhost::ToolError, prompt("code_mode/errors/cleanup_failed") if @poisoned
         end
       end
 
@@ -482,7 +494,7 @@ module LittleGhost
         end
         return unless current
 
-        error = LittleGhost::ToolError.new("code-mode program timed out")
+        error = LittleGhost::ToolError.new(FrameworkPrompts.reference("code_mode/feedback/program_timed_out"))
         begin
           terminate_program(program_id)
         rescue => cleanup_error

data/lib/little_ghost/code_mode/javascript_engine.rb

@@ -50,40 +50,15 @@ module LittleGhost
 
       # Builds JavaScript usage instructions and TypeScript declarations for
       # +catalog+.
-      def instructions(catalog:)
+      def instructions(catalog:, prompts: nil)
         javascript_catalog = Javascript::Catalog.new(catalog)
-        <<~INSTRUCTIONS.strip
-          Use JavaScript to call the available tools and compose their results.
-
-          Program lifecycle:
-          - Every exec call starts a fresh program in a new V8 context.
-          - 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`.
-
-          Tool calls:
-          - Tool functions return Promises. Use await or Promise.all.
-          - JSON results become objects or arrays. Other results remain strings.
-          - Unawaited tool calls finish before the program exits.
-          - `ALL_TOOLS` contains the complete runtime catalog.
-
-          Output and completion:
-          - Use `text(value)` for user-visible output.
-          - Use `exit()` to complete early.
-
-          The V8 context has no Node.js APIs, filesystem, network, console, WebAssembly, or process API.
-
-          Available tool methods:
-
-          #{javascript_catalog.declarations}
-        INSTRUCTIONS
+        renderer = prompts || ->(key, **locals) { FrameworkPrompts.new.render(key, locals:) }
+        renderer.call("code_mode/javascript/instructions", declarations: javascript_catalog.declarations)
       end
 
       # Opens a JavaScript Session with engine defaults merged with +limits+.
       # Unsupported limit keys raise ArgumentError.
-      def open_session(broker:, sandbox_factory:, limits: {})
+      def open_session(broker:, sandbox_factory:, limits: {}, framework_prompt_scope: {})
         configured_limits = normalize_limits(limits, defaults: DEFAULT_LIMITS)
         root = Dir.mktmpdir("little-ghost-javascript-")
         runtime_paths = javascript_runtime_paths
@@ -99,22 +74,26 @@ module LittleGhost
           required_runtime_paths: runtime_paths.keys.to_h { |name| [name, :read_only] }
         )
         sandbox.open
-        client = Javascript::Client.new(session_factory: lambda {
-          sandbox.start_program(
-            host_command,
-            cwd: ".",
-            environment: child_environment,
-            output_bytes: configured_limits.fetch(:output_bytes),
-            memory_bytes: configured_limits[:memory_bytes],
-            cpu_seconds: configured_limits[:cpu_seconds],
-            file_bytes: configured_limits[:file_bytes],
-            allow_subprocesses: allow_subprocesses_for(sandbox)
-          )
-        })
+        client = Javascript::Client.new(
+          session_factory: lambda {
+            sandbox.start_program(
+              host_command,
+              cwd: ".",
+              environment: child_environment,
+              output_bytes: configured_limits.fetch(:output_bytes),
+              memory_bytes: configured_limits[:memory_bytes],
+              cpu_seconds: configured_limits[:cpu_seconds],
+              file_bytes: configured_limits[:file_bytes],
+              allow_subprocesses: allow_subprocesses_for(sandbox)
+            )
+          },
+          framework_prompt_scope:
+        )
         Javascript::Session.new(
           broker:, client:, sandbox:, workspace:,
           max_concurrency: configured_limits.fetch(:max_concurrency),
-          wall_seconds: configured_limits.fetch(:wall_seconds)
+          wall_seconds: configured_limits.fetch(:wall_seconds),
+          framework_prompt_scope:
         )
       rescue
         sandbox&.close

data/lib/little_ghost/code_mode/ruby/host.rb

@@ -35,6 +35,7 @@ module LittleGhost
             response_queues = {}
             calls = 0
             max_calls = request.fetch("tool_calls")
+            messages = request.fetch("messages")
             output_buffer = +""
             flush_output = lambda do
               unless output_buffer.empty?
@@ -81,7 +82,7 @@ module LittleGhost
             invoke = lambda do |name, arguments|
               id, queue = queues_lock.synchronize do
                 calls += 1
-                raise "tool call limit exceeded" if calls > max_calls
+                raise messages.fetch("tool_calls_limit") if calls > max_calls
                 id = "call-#{calls}"
                 queue = Queue.new
                 response_queues[id] = queue
@@ -102,7 +103,7 @@ module LittleGhost
             end
             concurrency = request.fetch("concurrency")
             tools.define_singleton_method(:parallel) do |*operations|
-              raise ArgumentError, "parallel accepts callables" unless operations.all? { |operation| operation.respond_to?(:call) }
+              raise ArgumentError, messages.fetch("parallel_callables") unless operations.all? { |operation| operation.respond_to?(:call) }
               operations.each_slice(concurrency).flat_map do |batch|
                 batch.map { |operation| Thread.new { operation.call } }.map(&:value)
               end
@@ -130,8 +131,11 @@ module LittleGhost
           rescue SignalException
             exit 0
           rescue Exception => error
-            STDERR.puts("#{error.class}: #{error.message}")
-            error_frame = {type: "error", error: "#{error.class}: #{error.message}"}
+            failure = messages.fetch("execution_failed")
+              .gsub("__ERROR_CLASS__") { error.class.to_s }
+              .gsub("__ERROR_MESSAGE__") { error.message }
+            STDERR.puts(failure)
+            error_frame = {type: "error", error: failure}
             emit ? emit.call(error_frame) : write_frame&.call(error_frame)
             exit 1
             end

data/lib/little_ghost/code_mode/ruby/session.rb

@@ -12,13 +12,17 @@ module LittleGhost
       class Session < CodeMode::Session # :nodoc:
         OBSERVATION_SECONDS = 60
 
-        def initialize(broker:, sandbox_factory:, subprocess_policy:, limits:, observation_seconds: OBSERVATION_SECONDS)
+        def initialize(
+          broker:, sandbox_factory:, subprocess_policy:, limits:, observation_seconds: OBSERVATION_SECONDS,
+          framework_prompt_scope: {}
+        )
           @broker = broker
           @task_runner = broker.task_runner
           @sandbox_factory = sandbox_factory
           @subprocess_policy = subprocess_policy
           @limits = limits
           @observation_seconds = Float(observation_seconds)
+          @framework_prompt_scope = framework_prompt_scope.freeze
           raise ArgumentError, "observation_seconds must be positive" unless @observation_seconds.positive?
           @session = nil
           @workspace = nil
@@ -65,7 +69,7 @@ module LittleGhost
           @closed = true
           acquired = @control_mutex.try_lock
           unless acquired
-            raise ToolError, "cannot close while another code-mode control operation is active"
+            raise ToolError, prompt("code_mode/feedback/control_active")
           end
           cleanup_error = begin
             close_process
@@ -87,13 +91,23 @@ module LittleGhost
 
         private
 
+        def prompt(key, **locals)
+          framework_prompts = @framework_prompt_scope[:framework_prompts] || FrameworkPrompts.new
+          framework_prompts.render(
+            key,
+            locals:,
+            invocation_paths: @framework_prompt_scope.fetch(:invocation_paths, []),
+            agent_path: @framework_prompt_scope[:agent_path]
+          )
+        end
+
         def execute_program(source:, catalog:, frame:, max_output_tokens:, context:)
-          raise ToolError, "code-mode session is closed" if @closed
+          raise ToolError, prompt("code_mode/feedback/closed", resource: "session") if @closed
           ensure_program_can_start!
           @programs += 1
-          raise ToolError, "code-mode program limit exceeded" if @programs > @limits.fetch(:programs)
+          raise ToolError, prompt("code_mode/feedback/limit_exceeded", limit: "program") if @programs > @limits.fetch(:programs)
           source = String(source)
-          raise ToolError, "code-mode source exceeds the limit" if source.bytesize > @limits.fetch(:source_bytes)
+          raise ToolError, prompt("code_mode/feedback/limit_exceeded", limit: "source size") if source.bytesize > @limits.fetch(:source_bytes)
           normalized_catalog = Catalog.new(catalog).host_definitions
 
           generation, process = open_process
@@ -103,7 +117,16 @@ module LittleGhost
             catalog: normalized_catalog,
             frame:,
             tool_calls: @limits.fetch(:tool_calls),
-            concurrency: @limits.fetch(:concurrency)
+            concurrency: @limits.fetch(:concurrency),
+            messages: {
+              parallel_callables: prompt("code_mode/ruby/feedback/parallel_callables"),
+              tool_calls_limit: prompt("code_mode/feedback/limit_exceeded", limit: "Tool call"),
+              execution_failed: prompt(
+                "code_mode/errors/execution_failed",
+                error_class: "__ERROR_CLASS__",
+                message: "__ERROR_MESSAGE__"
+              )
+            }
           ))
           drive(generation:, process:, max_output_tokens:, context:)
         rescue
@@ -144,7 +167,7 @@ module LittleGhost
         def with_control
           acquired = @control_mutex.try_lock
           unless acquired
-            raise ToolError, "another code-mode control operation is already active"
+            raise ToolError, prompt("code_mode/feedback/control_active")
           end
 
           yield
@@ -156,7 +179,7 @@ module LittleGhost
           error = @lifecycle_mutex.synchronize do
             @lifecycle_condition.wait(@lifecycle_mutex) while @expiring_generation
             pending = take_pending_program_error
-            raise ToolError, "a code-mode program is already active" if !pending && (@generation || @session)
+            raise ToolError, prompt("code_mode/feedback/program_active") if !pending && (@generation || @session)
 
             pending
           end
@@ -178,7 +201,7 @@ module LittleGhost
             factory.new(workspace: @workspace)
           end
           @sandbox.open
-          raise ToolError, "code-mode session is closed" if @closed
+          raise ToolError, prompt("code_mode/feedback/closed", resource: "session") if @closed
           @session = @sandbox.start_program(
             [RbConfig.ruby, "-e", Host::SOURCE],
             output_bytes: @limits.fetch(:output_bytes),
@@ -275,7 +298,7 @@ module LittleGhost
             active = @call_tasks.count(&:alive?)
             raise ProtocolError, "code-mode concurrent tool call limit exceeded" if active >= @limits.fetch(:concurrency)
             @tool_calls += 1
-            raise ToolError, "tool call limit exceeded" if @tool_calls > @limits.fetch(:tool_calls)
+            raise ToolError, prompt("code_mode/feedback/limit_exceeded", limit: "Tool call") if @tool_calls > @limits.fetch(:tool_calls)
 
             call_errors = @call_errors
             closing_marker = @closing_marker
@@ -290,7 +313,7 @@ module LittleGhost
         def append_output(value)
           value = String(value).dup.force_encoding(Encoding::UTF_8).scrub
           @output_bytes += value.bytesize
-          raise ToolError, "code-mode output exceeded the limit" if @output_bytes > @limits.fetch(:output_bytes)
+          raise ToolError, prompt("code_mode/feedback/limit_exceeded", limit: "output") if @output_bytes > @limits.fetch(:output_bytes)
 
           @output << value
         end
@@ -314,7 +337,11 @@ module LittleGhost
           @output = +""
           return output unless max_output_tokens
 
-          Support::OutputTruncation.truncate_middle_with_token_budget(output, max_output_tokens).first
+          Support::OutputTruncation.truncate_middle_with_token_budget(
+            output,
+            max_output_tokens,
+            **@framework_prompt_scope
+          ).first
         end
 
         def active_process
@@ -323,7 +350,7 @@ module LittleGhost
             @lifecycle_condition.wait(@lifecycle_mutex) while @expiring_generation
             error = take_pending_program_error
             raise error if error
-            raise ToolError, "there is no active code-mode program" unless @generation && @session
+            raise ToolError, prompt("code_mode/feedback/not_active") unless @generation && @session
 
             [@generation, @session]
           end
@@ -442,7 +469,7 @@ module LittleGhost
           end
           return unless process
 
-          error = ToolError.new("code-mode program timed out")
+          error = ToolError.new(FrameworkPrompts.reference("code_mode/feedback/program_timed_out"))
           begin
             mark_process_closing
             process.terminate

data/lib/little_ghost/code_mode/ruby_engine.rb

@@ -34,50 +34,20 @@ module LittleGhost
       def language = :ruby
 
       # Builds Ruby usage instructions and method declarations for +catalog+.
-      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
+      def instructions(catalog:, prompts: nil)
+        renderer = prompts || ->(key, **locals) { FrameworkPrompts.new.render(key, locals:) }
+        renderer.call("code_mode/ruby/instructions", declarations: Ruby::Catalog.new(catalog).declarations)
       end
 
       # Opens a Ruby Session with engine defaults merged with +limits+.
       # Unsupported limit keys raise ArgumentError.
-      def open_session(broker:, sandbox_factory:, limits: {})
+      def open_session(broker:, sandbox_factory:, limits: {}, framework_prompt_scope: {})
         Ruby::Session.new(
           broker:,
           sandbox_factory:,
           subprocess_policy: method(:allow_subprocesses_for),
-          limits: normalize_limits(limits, defaults: DEFAULT_LIMITS)
+          limits: normalize_limits(limits, defaults: DEFAULT_LIMITS),
+          framework_prompt_scope:
         )
       end
     end