ask-tools-shell 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c8152ae1dcc82318421fde8c5a890ada7a6d4f11435a6e642e0724a06bab80e
-  data.tar.gz: ce7bb3ea38eb7514ae0f4e44e9cd4adfc1ebed5cf413cc9b424b74e17ce183a8
+  metadata.gz: d9920ae3e941453ed140a053b18b39f59d336f5dbc20334c6b8a262b7554f956
+  data.tar.gz: 3a4ad48154b393b9d69f39d2a6cc4af8fcf4a465a59921017fe7d2c62892d440
 SHA512:
-  metadata.gz: 284a6529ddae8a8099ab8d5af6d53fa2e3f53d97780c6ed9b94a26cb8eb6773500c12b1efb9f4087f3f415dc85b91b8724ecad2483ce511ca5c7e863d0dd00c8
-  data.tar.gz: a1d656f3851f88949869dc9f4aa1591f79c2ae394fa065f4e8767a55af4c004f63f84df06ef88f11bbfec27c5919b7374cc278f8eb97245f93c02799143b8e6e
+  metadata.gz: 8ff7cd4230e7e4be6e2ae9b2a2a0410ed994959fedb0da3628caedff322cb84bd531e8bb62cf5d9b669fb12d759c675ef47d2f4deb32738d292bbbf710a193f7
+  data.tar.gz: a404e7da5f72e0ca458f04bfee0d72ed56d609e39db59e665f4e3a837b1b229a11879317770e6fa901c6cb5ba6e1813834d7464fbba69d34f2dee4fa64a9fba3

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [0.4.0] - 2026-08-05
+
+### Added
+- **`Ask::Tools::Repl`** — evaluate Ruby code in a persistent session (the
+  RLM / recursive-language-model pattern). A long-lived plain-ruby kernel
+  subprocess keeps state across calls: locals, `require`s, and defined
+  methods survive between evaluations, so the model composes capabilities as
+  code against a working environment instead of re-bootstrapping each time.
+  - Framed newline-delimited JSON protocol over stdin/stdout with
+    request/response id matching; concurrent calls to a session serialize.
+  - Per-evaluation timeout kills the session (state is lost, kernel
+    respawns fresh on next call); idle sessions recycle after
+    `Repl.idle_timeout` (default 300s).
+  - Named sessions shared process-wide (`session:` param, default
+    `"default"`); `reset: true` discards state; `Repl.close_session` /
+    `Repl.close_all` manage lifetimes; `at_exit` cleanup.
+  - Sessions are isolated subprocesses — a crash in one session can't take
+    others down, and a dead session is respawned transparently with one
+    retry.
+  - Kernel spawn strips bundler env vars (RUBYOPT, GEM_HOME, etc.) so the
+    session is plain ruby and sees globally installed gems — consistent
+    with the one-shot `Code` tool.
+- Registered `repl` in `Shell::TOOLS` / `Shell.all`.
+
 ## [0.3.4] - 2026-06-25
 
 ### Fixed

data/README.md

@@ -1,171 +1,59 @@
 # ask-tools-shell
 
-Shell, filesystem, and code execution tools for AI agents. Part of the ask-rb ecosystem.
+[![Gem Version](https://badge.fury.io/rb/ask-tools-shell.svg)](https://badge.fury.io/rb/ask-tools-shell)
 
-Provides **Bash**, **Read**, **Write**, **Edit**, **Glob**, **Grep**, and **Code** — the execution tools every agent needs.
+Shell, filesystem, and code execution tools for AI agents. Ships 8 tools: Bash, Read, Write, Edit, Glob, Grep, Code, and ApplyPatch. Bash and Code execute through ask-sandbox-providers; the rest operate directly on the local filesystem.
+
+## Installation
 
 ```ruby
 gem "ask-tools-shell"
 ```
 
-## Dependencies
-
-- **ask-tools** ~> 0.1 (provides `Ask::Tool` base class and `Ask::Result`)
-
----
-
 ## Quick Start
 
 ```ruby
 require "ask-tools-shell"
 
-# List all available tools
 Ask::Tools::Shell.all.map(&:name)
-# => ["bash", "read", "write", "edit", "glob", "grep", "code"]
+# => ["bash", "read", "write", "edit", "glob", "grep", "code", "apply_patch"]
 
-# Use a tool standalone
 result = Ask::Tools::Bash.new.call(command: "echo hello")
-result.ok?              # => true
-result.output[:stdout]  # => "hello\n"
-result.output[:exit_code] # => 0
+result.ok?                 # => true
+result.output[:stdout]     # => "hello\n"
+result.output[:exit_code]  # => 0
 ```
 
----
-
-## Tools
-
-### `Ask::Tools::Bash`
-
-Execute shell commands in a sandboxed temp directory.
+## The tools
 
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `command` | `string` | Yes | — | The bash command to execute |
-| `timeout` | `integer` | No | 30 | Timeout in seconds |
-| `workdir` | `string` | No | temp dir | Working directory |
+| Tool | Parameters | Notes |
+|---|---|---|
+| `Ask::Tools::Bash` | `command`, `timeout` (30), `workdir` | Runs via `Ask::Sandbox.provider`; returns `{ stdout, stderr, exit_code, timed_out }`, output truncated to 100KB |
+| `Ask::Tools::Read` | `path`, `offset` (0-indexed), `limit` (2000) | Reads files with line numbers, or lists a directory |
+| `Ask::Tools::Write` | `path`, `content` | Creates parent directories automatically |
+| `Ask::Tools::Edit` | `path`, `old_string`, `new_string`, `replace_all` | Exact string replacement |
+| `Ask::Tools::Glob` | `pattern`, `path` | Up to 1000 files, newest first |
+| `Ask::Tools::Grep` | `pattern`, `path`, `include` | Regex search; 100 matches max, skips `.git`, `node_modules`, `vendor`, `.bundle`, `tmp`, `log` |
+| `Ask::Tools::Code` | `code` | Runs Ruby via `Ask::Sandbox.provider`; returns `{ stdout, stderr, exit_code }` |
+| `Ask::Tools::ApplyPatch` | `patchText` | Applies unified diffs inside a `*** Begin Patch` / `*** End Patch` envelope (Add File, Update File, Delete File sections) |
 
-Returns `{ stdout, stderr, exit_code, timed_out }`. Output truncated to 100KB. Process killed on timeout.
+## Sandboxed execution
 
-```ruby
-Ask::Tools::Bash.new.call(command: "ls -la", timeout: 10)
-```
-
-### `Ask::Tools::Read`
-
-Read file contents with line numbers, or list directory entries.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `path` | `string` | Yes | — | Absolute path to file or directory |
-| `offset` | `integer` | No | 0 | Starting line number (0-indexed) |
-| `limit` | `integer` | No | 2000 | Maximum lines to read |
+`Bash` and `Code` run through `Ask::Sandbox.provider` (ask-sandbox-providers), which defaults to the Local provider. Switch to stronger isolation:
 
 ```ruby
-Ask::Tools::Read.new.call(path: "/etc/hosts")
-Ask::Tools::Read.new.call(path: "large.log", offset: 100, limit: 50)
+Ask::Sandbox.provider = :docker
 ```
 
-### `Ask::Tools::Write`
-
-Write content to a file. Creates parent directories automatically.
+## Full documentation
 
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `path` | `string` | Yes | — | Absolute path to write to |
-| `content` | `string` | Yes | — | File content (max 500KB) |
-
-```ruby
-Ask::Tools::Write.new.call(path: "/tmp/hello.txt", content: "Hello, World!")
-```
-
-### `Ask::Tools::Edit`
-
-Replace exact text in a file. Uses exact string matching.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `path` | `string` | Yes | — | Absolute path to the file |
-| `old_string` | `string` | Yes | — | Exact text to replace |
-| `new_string` | `string` | Yes | — | Replacement text |
-| `replace_all` | `boolean` | No | false | Replace all occurrences |
-
-```ruby
-Ask::Tools::Edit.new.call(path: "file.rb", old_string: "foo", new_string: "bar")
-Ask::Tools::Edit.new.call(path: "file.rb", old_string: "x", new_string: "y", replace_all: true)
-```
-
-### `Ask::Tools::Glob`
-
-Find files matching a glob pattern, sorted by modification time (newest first).
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `pattern` | `string` | Yes | — | Glob pattern (e.g. `**/*.rb`) |
-| `path` | `string` | No | current dir | Base directory |
-
-Max 1000 results.
-
-```ruby
-Ask::Tools::Glob.new.call(pattern: "**/*.rb", path: "/path/to/project")
-```
-
-### `Ask::Tools::Grep`
-
-Search file contents using a regex pattern.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `pattern` | `string` | Yes | — | Regex pattern to search for |
-| `path` | `string` | No | current dir | Directory to search |
-| `include` | `string` | No | `**/*` | File pattern filter (e.g. `*.rb`) |
-
-Max 100 matches. Line content capped at 500 chars. Skips `.git`, `node_modules`, `vendor`, `.bundle`, `tmp`, `log`.
-
-```ruby
-Ask::Tools::Grep.new.call(pattern: "TODO", path: ".", include: "*.rb")
-```
-
-### `Ask::Tools::Code`
-
-Write and execute Ruby code in a subprocess. Uses gems already available in the environment.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `code` | `string` | Yes | — | Ruby source code to execute |
-
-Returns `{ stdout, stderr, exit_code }`. Output truncated to 100KB.
-
-```ruby
-Ask::Tools::Code.new.call(code: <<~RUBY)
-  puts "Hello from Ruby!"
-  result = 2 + 2
-  puts "2 + 2 = #{result}"
-RUBY
-```
-
----
-
-## Using Tools with an Agent
-
-```ruby
-require "ask-tools-shell"
-
-# All tools
-tools = Ask::Tools::Shell.all
-
-# Find by name
-bash = Ask::Tools["bash"]
-bash.call(command: "date")
-```
-
----
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. [ask-tools in depth](https://ask-rb.github.io/ask-docs/core/tools) covers the shell tools, the ApplyPatch format, and sandbox configuration. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
+```
 bundle install
 bundle exec rake test
-gem build ask-tools-shell.gemspec
 ```
 
 ## License

data/lib/ask/tools/shell/grep.rb

@@ -34,7 +34,13 @@ module Ask
 
         Dir.glob(File.join(base, glob)).each do |file|
           next unless File.file?(file)
-          next if EXCLUDE_DIRS.any? { |d| file.include?("/#{d}/") }
+
+          # Exclude by path segment relative to the search root, not by
+          # absolute-path substring: the old check matched any path
+          # containing "/tmp/" (e.g. a search rooted under the system tmp
+          # dir on Linux), excluding every file.
+          relative = file.delete_prefix("#{base}/")
+          next if relative.split("/").any? { |seg| EXCLUDE_DIRS.include?(seg) }
 
           begin
             File.readlines(file).each_with_index do |line, i|

data/lib/ask/tools/shell/repl/kernel_script.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Persistent Ruby kernel for Ask::Tools::Shell::Repl.
+#
+# A standalone plain-Ruby script run as a long-lived subprocess. Reads framed
+# JSON requests from stdin, evaluates each snippet into a persistent binding,
+# and writes a framed JSON response to stdout.
+#
+# Protocol (newline-delimited JSON):
+#   request:  {"id": 1, "code": "1 + 1"}
+#   response: {"id": 1, "result": "2", "stdout": "", "stderr": "", "error": null}
+#
+# The binding persists across requests, so locals, requires, and defined
+# methods survive between calls. stdout/stderr are captured per evaluation.
+
+require "json"
+require "stringio"
+
+# Die immediately on TERM (sent by the parent to shut the session down).
+# exit! bypasses the rescue Exception below, which would otherwise swallow
+# the SignalException raised mid-eval and keep the kernel alive.
+trap("TERM") { exit!(0) }
+
+def read_frame
+  line = $stdin.gets
+  return nil if line.nil?
+
+  JSON.parse(line)
+rescue JSON::ParserError
+  { "error" => "invalid request frame" }
+end
+
+def write_frame(frame)
+  $stdout.puts(JSON.generate(frame))
+  $stdout.flush
+end
+
+def capture_output
+  old_out = $stdout
+  old_err = $stderr
+  out = StringIO.new
+  err = StringIO.new
+  $stdout = out
+  $stderr = err
+  yield
+  [out.string, err.string]
+ensure
+  $stdout = old_out
+  $stderr = old_err
+end
+
+def safe_inspect(value)
+  value.inspect
+rescue StandardError
+  "#<#{value.class}>"
+end
+
+binding = TOPLEVEL_BINDING
+
+loop do
+  request = read_frame
+  break if request.nil?
+
+  id = request["id"]
+  code = request["code"].to_s
+
+  result = nil
+  stdout = ""
+  stderr = ""
+  error = nil
+
+  begin
+    stdout, stderr = capture_output do
+      result = binding.eval(code)
+    end
+  rescue Exception => e # rubocop:disable Lint/RescueException
+    error = "#{e.class}: #{e.message}"
+    trace = (e.backtrace || []).first(10).join("\n")
+    stderr += trace
+  end
+
+  write_frame(
+    "id" => id,
+    "result" => safe_inspect(result),
+    "stdout" => stdout,
+    "stderr" => stderr,
+    "error" => error
+  )
+end

data/lib/ask/tools/shell/repl.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+require "io/wait"
+
+module Ask
+  module Tools
+    # Evaluate Ruby code in a persistent, long-lived subprocess.
+    #
+    # Unlike {Code} (which spawns a fresh `ruby -e` per call), Repl keeps a
+    # kernel process alive across calls and evaluates every snippet into the
+    # same binding — so state (locals, requires, defined methods) survives
+    # between calls. This is the RLM (recursive language model) pattern: the
+    # model composes capabilities as code against a persistent environment.
+    #
+    # @example
+    #   repl = Ask::Tools::Repl.new
+    #   repl.call(code: 'require "json"; data = JSON.parse(%q({"a": 1}))')
+    #   repl.call(code: "data['a'] + 1")       # => 2 — `data` still exists
+    #   repl.call(code: "def double(x); x * 2; end")
+    #   repl.call(code: "double(21)")          # => 42
+    #
+    # Sessions are named and shared process-wide: calling with the same
+    # +session+ name from any tool instance reaches the same kernel. A
+    # session is closed by +reset: true+, {Repl.close_session}, or after
+    # {Repl.idle_timeout} seconds without use.
+    #
+    # @note The kernel runs with the caller's permissions (like {Code}).
+    #   It is a durable control environment, not a security sandbox.
+    class Repl < Ask::Tool
+      description "Evaluate Ruby code in a persistent session. " \
+                   "State (variables, requires, defined methods) survives " \
+                   "across calls in the same session. " \
+                   "Use sessions to keep working context alive."
+
+      param :code, type: :string, desc: "Ruby source code to evaluate", required: true
+      param :session, type: :string, desc: "Session name; state persists per name", required: false
+      param :reset, type: :boolean, desc: "Discard session state before evaluating", required: false
+
+      # Timeout for a single evaluation, in seconds.
+      DEFAULT_EVAL_TIMEOUT = 30
+
+      # Sessions idle longer than this are closed on next access.
+      DEFAULT_IDLE_TIMEOUT = 300
+
+      # Env vars that would drag the parent's bundler context into the
+      # kernel subprocess (RUBYOPT=-rbundler/setup restricts $LOAD_PATH to
+      # the parent's Gemfile). Nil overrides remove them at spawn so the
+      # session is plain ruby, like the one-shot Code tool's sandbox.
+      BUNDLER_ENV = %w[
+        RUBYOPT RUBYLIB BASH_ENV GEM_PATH GEM_HOME
+        BUNDLE_GEMFILE BUNDLE_PATH BUNDLE_BIN_PATH BUNDLER_SETUP
+        BUNDLER_VERSION BUNDLE_WITHOUT BUNDLE_FROZEN BUNDLE_DEPLOYMENT
+        BUNDLE_LOCKFILE BUNDLE_APP_CONFIG
+      ].freeze
+
+      class << self
+        # @return [Integer] seconds a session may sit unused before it is
+        #   closed on next access
+        attr_accessor :idle_timeout
+
+        # @return [Integer] seconds a single evaluation may take
+        attr_accessor :eval_timeout
+      end
+
+      self.idle_timeout = DEFAULT_IDLE_TIMEOUT
+      self.eval_timeout = DEFAULT_EVAL_TIMEOUT
+
+      @registry = {}
+      @registry_mutex = Monitor.new
+
+      class << self
+        # The kernel for +session+, spawning one if needed (or after reset).
+        #
+        # @param session [String]
+        # @param reset [Boolean] discard existing session state
+        # @return [Kernel]
+        def kernel_for(session, reset: false)
+          @registry_mutex.synchronize do
+            close_session(session) if reset
+            kernel = @registry[session]
+            if kernel.nil? || kernel.dead?
+              kernel = Kernel.new(session: session)
+              @registry[session] = kernel
+            elsif kernel.idle_seconds > idle_timeout
+              kernel.close
+              kernel = Kernel.new(session: session)
+              @registry[session] = kernel
+            end
+            kernel
+          end
+        end
+
+        # Close and forget a session's kernel.
+        #
+        # @param session [String]
+        # @return [void]
+        def close_session(session)
+          @registry_mutex.synchronize do
+            kernel = @registry.delete(session)
+            kernel&.close
+          end
+          nil
+        end
+
+        # Close every session kernel. Called at exit; call it explicitly to
+        # free subprocesses early.
+        #
+        # @return [void]
+        def close_all
+          @registry_mutex.synchronize do
+            @registry.each_value(&:close)
+            @registry.clear
+          end
+          nil
+        end
+
+        # @return [Array<String>] active session names
+        def sessions
+          @registry_mutex.synchronize { @registry.keys }
+        end
+      end
+
+      at_exit { Repl.close_all }
+
+      def execute(code:, session: "default", reset: false)
+        build_result(eval_code(session, code, reset: reset), session)
+      rescue Kernel::TimeoutError => e
+        Ask::Result.error(message: "REPL session '#{session}' timed out (#{e.timeout}s); session state was lost")
+      rescue Kernel::DeadError => e
+        # The session died (crash, external kill, closed stdin). Respawn a
+        # fresh kernel and retry once; only give up if it dies again.
+        begin
+          build_result(eval_code(session, code), session)
+        rescue Kernel::DeadError
+          Ask::Result.error(message: "REPL session '#{session}' died repeatedly: #{e.message}")
+        end
+      end
+
+      private
+
+      def eval_code(session, code, reset: false)
+        Repl.kernel_for(session, reset: reset).eval(code, timeout: Repl.eval_timeout)
+      end
+
+      def build_result(result, session)
+        if result["error"]
+          Ask::Result.error(
+            message: result["error"],
+            metadata: { session: session, stdout: result["stdout"], stderr: result["stderr"] }
+          )
+        else
+          Ask::Result.ok(data: {
+            result: result["result"],
+            stdout: result["stdout"],
+            stderr: result["stderr"],
+            session: session
+          })
+        end
+      end
+
+      # A single long-lived Ruby subprocess executing the kernel script.
+      #
+      # Communicates over newline-delimited JSON on stdin/stdout. One eval
+      # at a time per kernel; concurrent calls serialize on an internal
+      # monitor.
+      class Kernel
+        class Error < StandardError; end
+        class TimeoutError < Error
+          attr_reader :timeout
+
+          def initialize(timeout)
+            @timeout = timeout
+            super("evaluation exceeded #{timeout}s")
+          end
+        end
+        class DeadError < Error; end
+
+        # @return [String] session name this kernel belongs to
+        attr_reader :session
+
+        # @return [Time] last time an evaluation completed
+        attr_reader :last_used
+
+        def initialize(session:, ruby: "ruby")
+          @session = session
+          @script = File.expand_path("repl/kernel_script.rb", __dir__)
+          @monitor = Monitor.new
+          @last_used = Time.now
+          @next_id = 0
+          spawn_process(ruby)
+        end
+
+        # @return [Float] seconds since the last evaluation
+        def idle_seconds
+          Time.now - @last_used
+        end
+
+        # @return [Boolean] whether the kernel process is gone. Reaps the
+        #   child if it already exited (zombies count as dead).
+        def dead?
+          return true if @closed
+          return true unless @pid
+
+          _, status = Process.waitpid(@pid, Process::WNOHANG)
+          if status.nil?
+            false
+          else
+            @pid = nil
+            true
+          end
+        rescue Errno::ECHILD, Errno::ESRCH, Errno::EINTR
+          @pid = nil
+          true
+        end
+
+        # Evaluate +code+ in the persistent binding.
+        #
+        # @param code [String]
+        # @param timeout [Integer] max seconds for this evaluation
+        # @return [Hash] {"result" => String, "stdout" => String,
+        #   "stderr" => String, "error" => String or nil}
+        # @raise [TimeoutError] evaluation exceeded +timeout+; the kernel
+        #   was killed and session state lost
+        # @raise [DeadError] the kernel process died
+        def eval(code, timeout: Repl.eval_timeout)
+          @monitor.synchronize do
+            raise DeadError, "process not running" if dead?
+
+            id = (@next_id += 1)
+            write_frame("id" => id, "code" => code)
+            response = read_frame(id, timeout)
+            @last_used = Time.now
+            response
+          end
+        end
+
+        # Terminate the kernel process and close pipes. TERM is normally
+        # enough (the kernel script exits on it); KILL is the fallback for
+        # user code that overrode the trap or wedged the VM.
+        #
+        # @return [void]
+        def close
+          @monitor.synchronize do
+            return if @closed
+
+            @closed = true
+            if @pid
+              begin
+                Process.kill("TERM", @pid)
+              rescue Errno::ESRCH, Errno::ECHILD
+                @pid = nil
+              end
+              wait_for_exit(2)
+              if @pid
+                begin
+                  Process.kill("KILL", @pid)
+                rescue Errno::ESRCH, Errno::ECHILD
+                  @pid = nil
+                end
+                wait_for_exit(1)
+              end
+            end
+            @in_w.close unless @in_w.closed?
+            @out_r.close unless @out_r.closed?
+            @err_r.close unless @err_r.closed?
+          end
+          nil
+        end
+
+        private
+
+        # Poll until the child exits or +seconds+ elapse. Reaps the child
+        # when it does. Avoids blocking +Process.wait+ which Timeout cannot
+        # always interrupt.
+        #
+        # @param seconds [Numeric]
+        # @return [void]
+        def wait_for_exit(seconds)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+          loop do
+            _, status = Process.waitpid(@pid, Process::WNOHANG)
+            return if status
+
+            break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+            sleep 0.01
+          end
+        rescue Errno::ECHILD, Errno::ESRCH, Errno::EINTR
+          @pid = nil
+        end
+
+        def spawn_process(ruby)
+          @in_r, @in_w = IO.pipe
+          @out_r, @out_w = IO.pipe
+          @err_r, @err_w = IO.pipe
+
+          # The kernel is a plain ruby environment: remove bundler plumbing
+          # inherited from the parent (RUBYOPT=-rbundler/setup etc.) so the
+          # session sees globally installed gems, not the parent's Gemfile
+          # subset. Note: Process.spawn *merges* its env hash with the
+          # parent environment — only explicit nil values delete keys.
+          env = BUNDLER_ENV.to_h { |key| [key, nil] }
+
+          @pid = Process.spawn(
+            env, ruby, @script,
+            in: @in_r, out: @out_w, err: @err_w
+          )
+          @in_r.close
+          @out_w.close
+          @err_w.close
+        rescue StandardError
+          close
+          raise
+        end
+
+        def write_frame(frame)
+          @in_w.write(JSON.generate(frame) + "\n")
+          @in_w.flush
+        rescue Errno::EPIPE, IOError => e
+          raise DeadError, e.message
+        end
+
+        def read_frame(expected_id, timeout)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+          loop do
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if remaining <= 0
+              close
+              raise TimeoutError, timeout
+            end
+
+            ready = @out_r.wait_readable(remaining)
+            unless ready
+              close
+              raise TimeoutError, timeout
+            end
+
+            line = @out_r.gets
+            if line.nil?
+              err = @err_r.read
+              close
+              raise DeadError, "kernel exited unexpectedly#{err.empty? ? "" : ": #{err.strip}"}"
+            end
+
+            frame = JSON.parse(line)
+            return frame if frame["id"] == expected_id
+          rescue JSON::ParserError
+            next
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/tools/shell/version.rb

@@ -3,7 +3,7 @@
 module Ask
   module Tools
     module Shell
-      VERSION = "0.3.4"
+      VERSION = "0.4.0"
     end
   end
 end

data/lib/ask/tools/shell.rb

@@ -10,11 +10,12 @@ require_relative "shell/glob"
 require_relative "shell/grep"
 require_relative "shell/code"
 require_relative "shell/apply_patch"
+require_relative "shell/repl"
 
 module Ask
   module Tools
     module Shell
-      TOOLS = [Bash, Read, Write, Edit, Glob, Grep, Code, ApplyPatch].freeze
+      TOOLS = [Bash, Read, Write, Edit, Glob, Grep, Code, ApplyPatch, Repl].freeze
 
       def self.all
         TOOLS.map(&:new)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-tools-shell
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -100,6 +100,8 @@ files:
 - lib/ask/tools/shell/glob.rb
 - lib/ask/tools/shell/grep.rb
 - lib/ask/tools/shell/read.rb
+- lib/ask/tools/shell/repl.rb
+- lib/ask/tools/shell/repl/kernel_script.rb
 - lib/ask/tools/shell/version.rb
 - lib/ask/tools/shell/write.rb
 homepage: https://github.com/ask-rb/ask-tools-shell