e2b 0.2.0

data/lib/e2b/services/pty.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require "base64"
+require_relative "base_service"
+require_relative "command_handle"
+
+module E2B
+  module Services
+    # Pseudo-terminal size specification.
+    #
+    # @example Default 80x24 terminal
+    #   size = PtySize.new
+    #
+    # @example Custom size
+    #   size = PtySize.new(cols: 120, rows: 40)
+    class PtySize
+      # @return [Integer] Number of columns
+      attr_reader :cols
+
+      # @return [Integer] Number of rows
+      attr_reader :rows
+
+      # @param cols [Integer] Number of columns (default: 80)
+      # @param rows [Integer] Number of rows (default: 24)
+      def initialize(cols: 80, rows: 24)
+        @cols = cols
+        @rows = rows
+      end
+
+      # Convert to a Hash suitable for the Connect RPC request body.
+      #
+      # @return [Hash]
+      def to_h
+        { cols: @cols, rows: @rows }
+      end
+    end
+
+    # PTY (pseudo-terminal) service for E2B sandbox.
+    #
+    # Provides methods to create, connect to, and manage interactive
+    # pseudo-terminals inside the sandbox. Uses Connect RPC protocol
+    # with the +process.Process+ service.
+    #
+    # @example Create a PTY and send commands
+    #   pty = sandbox.pty
+    #   handle = pty.create
+    #   handle.send_stdin("ls -la\n")
+    #   result = handle.wait(on_pty: ->(data) { print data })
+    #
+    # @example Resize a PTY
+    #   pty.resize(handle.pid, PtySize.new(cols: 120, rows: 40))
+    #
+    # @example Connect to an existing PTY
+    #   handle = pty.connect(pid)
+    class Pty < BaseService
+      # Default shell to use for PTY sessions
+      DEFAULT_SHELL = "/bin/bash"
+
+      # Default shell arguments for interactive login shell
+      DEFAULT_SHELL_ARGS = ["-i", "-l"].freeze
+
+      # Create a new PTY (pseudo-terminal) session in the sandbox.
+      #
+      # Starts an interactive shell process with a PTY attached. The
+      # returned {CommandHandle} can be used to send input, receive
+      # output, and manage the PTY lifecycle.
+      #
+      # @param size [PtySize] Terminal size (default: 80 columns x 24 rows)
+      # @param user [String, nil] User to run the PTY as
+      # @param cwd [String, nil] Working directory for the PTY shell
+      # @param envs [Hash{String => String}, nil] Environment variables
+      # @param cmd [String] Shell executable (default: /bin/bash)
+      # @param args [Array<String>] Shell arguments (default: ["-i", "-l"])
+      # @param timeout [Integer] Timeout for the PTY session in seconds
+      # @return [CommandHandle] Handle to interact with the PTY
+      # @raise [E2B::E2BError] if the PTY could not be started
+      #
+      # @example
+      #   handle = sandbox.pty.create(
+      #     size: PtySize.new(cols: 120, rows: 40),
+      #     cwd: "/home/user/project",
+      #     envs: { "EDITOR" => "vim" }
+      #   )
+      def create(size: PtySize.new, user: nil, cwd: nil, envs: nil,
+                 cmd: DEFAULT_SHELL, args: DEFAULT_SHELL_ARGS, timeout: 60)
+        envs = build_pty_envs(envs)
+
+        process_spec = {
+          cmd: cmd,
+          args: args,
+          envs: envs
+        }
+        process_spec[:cwd] = cwd if cwd
+
+        body = {
+          process: process_spec,
+          pty: {
+            size: size.to_h
+          }
+        }
+
+        pid = nil
+
+        # Use streaming RPC to capture the StartEvent and extract the PID
+        on_event = ->(event_data) {
+          event = event_data[:event]
+          if event.is_a?(Hash) && event["event"]
+            start_event = event["event"]["Start"] || event["event"]["start"]
+            if start_event && start_event["pid"]
+              pid = start_event["pid"]
+            end
+          end
+        }
+
+        response = envd_rpc(
+          "process.Process", "Start",
+          body: body,
+          timeout: timeout + 30,
+          on_event: on_event
+        )
+
+        # If PID was not captured from streaming, try the accumulated result
+        pid ||= extract_pid_from_result(response)
+
+        CommandHandle.new(
+          pid: pid,
+          handle_kill: -> { kill(pid) },
+          handle_send_stdin: ->(data) { send_stdin(pid, data) },
+          result: response
+        )
+      end
+
+      # Connect to an existing PTY process.
+      #
+      # Attaches to a running PTY process by PID and returns a handle
+      # for sending input and receiving output.
+      #
+      # @param pid [Integer] Process ID of the PTY to connect to
+      # @param timeout [Integer] Timeout for the connection in seconds
+      # @return [CommandHandle] Handle to interact with the PTY
+      # @raise [E2B::E2BError] if the process is not found or connection fails
+      #
+      # @example
+      #   handle = sandbox.pty.connect(12345)
+      #   handle.send_stdin("whoami\n")
+      def connect(pid, timeout: 60)
+        body = {
+          process: { pid: pid }
+        }
+
+        response = envd_rpc(
+          "process.Process", "Connect",
+          body: body,
+          timeout: timeout + 30
+        )
+
+        CommandHandle.new(
+          pid: pid,
+          handle_kill: -> { kill(pid) },
+          handle_send_stdin: ->(data) { send_stdin(pid, data) },
+          result: response
+        )
+      end
+
+      # Send input data to a PTY.
+      #
+      # The data is base64-encoded and sent as PTY input (not stdin),
+      # which means it goes through the terminal emulator and supports
+      # control characters, escape sequences, etc.
+      #
+      # @param pid [Integer] Process ID of the PTY
+      # @param data [String] Input data to send (e.g., "ls -la\n")
+      # @return [void]
+      # @raise [E2B::E2BError] if the process is not found
+      #
+      # @example Send a command
+      #   sandbox.pty.send_stdin(pid, "echo hello\n")
+      #
+      # @example Send Ctrl+C
+      #   sandbox.pty.send_stdin(pid, "\x03")
+      def send_stdin(pid, data)
+        encoded = Base64.strict_encode64(data.is_a?(String) ? data : data.to_s)
+        envd_rpc("process.Process", "SendInput", body: {
+          process: { pid: pid },
+          input: { pty: encoded }
+        })
+      end
+
+      # Kill a PTY process with SIGKILL.
+      #
+      # @param pid [Integer] Process ID of the PTY to kill
+      # @return [Boolean] true if the signal was sent, false if the process was not found
+      #
+      # @example
+      #   sandbox.pty.kill(12345)
+      def kill(pid)
+        envd_rpc("process.Process", "SendSignal", body: {
+          process: { pid: pid },
+          signal: 9 # SIGKILL
+        })
+        true
+      rescue E2B::E2BError
+        false
+      end
+
+      # Resize a PTY terminal.
+      #
+      # Should be called when the terminal window size changes to keep
+      # the remote PTY in sync.
+      #
+      # @param pid [Integer] Process ID of the PTY
+      # @param size [PtySize] New terminal size
+      # @return [void]
+      # @raise [E2B::E2BError] if the process is not found
+      #
+      # @example
+      #   sandbox.pty.resize(pid, PtySize.new(cols: 120, rows: 40))
+      def resize(pid, size)
+        envd_rpc("process.Process", "Update", body: {
+          process: { pid: pid },
+          pty: {
+            size: size.to_h
+          }
+        })
+      end
+
+      # Close the stdin of a PTY process.
+      #
+      # After calling this, no more input can be sent to the PTY via
+      # {#send_stdin}.
+      #
+      # @param pid [Integer] Process ID of the PTY
+      # @return [void]
+      # @raise [E2B::E2BError] if the process is not found
+      def close_stdin(pid)
+        envd_rpc("process.Process", "CloseStdin", body: {
+          process: { pid: pid }
+        })
+      end
+
+      # List running processes in the sandbox.
+      #
+      # @return [Array<Hash>] List of running process descriptors
+      def list
+        response = envd_rpc("process.Process", "List", body: {})
+        response["processes"] || response[:processes] || []
+      end
+
+      private
+
+      # Build environment variables hash with PTY defaults.
+      #
+      # Ensures TERM, LANG, and LC_ALL are set to sensible defaults
+      # for terminal operation unless the caller has overridden them.
+      #
+      # @param envs [Hash{String => String}, nil] Caller-provided env vars
+      # @return [Hash{String => String}]
+      def build_pty_envs(envs)
+        result = {}
+        result["TERM"] = "xterm-256color"
+        result["LANG"] = "C.UTF-8"
+        result["LC_ALL"] = "C.UTF-8"
+
+        if envs.is_a?(Hash)
+          envs.each { |k, v| result[k.to_s] = v.to_s }
+        end
+
+        result
+      end
+
+      # Extract PID from the StartEvent in a pre-materialized RPC result.
+      #
+      # The result hash from {EnvdHttpClient#handle_streaming_rpc} or
+      # {EnvdHttpClient#handle_rpc_response} contains an :events array.
+      # The first event with a Start sub-event carries the PID.
+      #
+      # @param response [Hash] RPC response hash with :events key
+      # @return [Integer, nil] Process ID, or nil if not found
+      def extract_pid_from_result(response)
+        return nil unless response.is_a?(Hash)
+
+        events = response[:events] || []
+        events.each do |event_hash|
+          next unless event_hash.is_a?(Hash) && event_hash["event"]
+
+          event = event_hash["event"]
+          start_event = event["Start"] || event["start"]
+          if start_event && start_event["pid"]
+            return start_event["pid"]
+          end
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/e2b/services/watch_handle.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module E2B
+  module Services
+    # Handle for watching directory changes in the sandbox
+    #
+    # Returned by {Filesystem#watch_dir}. Uses the polling-based watcher RPCs
+    # (CreateWatcher/GetWatcherEvents/RemoveWatcher) from the filesystem proto service.
+    #
+    # The watcher is created externally and its ID is passed into this handle.
+    # Call {#get_new_events} to poll for new filesystem changes, and {#stop}
+    # to clean up the watcher when done.
+    #
+    # @example Basic usage
+    #   handle = sandbox.files.watch_dir("/home/user/project")
+    #   loop do
+    #     events = handle.get_new_events
+    #     events.each { |e| puts "#{e.name}: #{e.type}" }
+    #     sleep 1
+    #   end
+    #   handle.stop
+    #
+    # @example With ensure block for cleanup
+    #   handle = sandbox.files.watch_dir("/home/user/project")
+    #   begin
+    #     events = handle.get_new_events
+    #     events.each { |e| process_event(e) }
+    #   ensure
+    #     handle.stop
+    #   end
+    class WatchHandle
+      # @return [String] The watcher ID assigned by the CreateWatcher RPC
+      attr_reader :watcher_id
+
+      # Create a new WatchHandle
+      #
+      # @param watcher_id [String] The watcher ID returned by the CreateWatcher RPC
+      # @param envd_rpc_proc [Proc] A callable that performs RPC calls. It must accept
+      #   three positional arguments (service, method) and keyword arguments (body:, timeout:).
+      #   Typically a lambda wrapping {BaseService#envd_rpc}.
+      def initialize(watcher_id:, envd_rpc_proc:)
+        @watcher_id = watcher_id
+        @envd_rpc_proc = envd_rpc_proc
+        @stopped = false
+      end
+
+      # Poll for new filesystem events since the last check
+      #
+      # Calls the GetWatcherEvents RPC to retrieve any filesystem events
+      # that have occurred since the last poll (or since the watcher was created).
+      #
+      # @return [Array<Models::FilesystemEvent>] New events since last poll
+      # @raise [E2B::E2BError] If the watcher has been stopped
+      def get_new_events
+        raise E2B::E2BError, "Watcher has been stopped" if @stopped
+
+        response = @envd_rpc_proc.call(
+          "filesystem.Filesystem", "GetWatcherEvents",
+          body: { watcherId: @watcher_id }
+        )
+
+        events = extract_events(response)
+        events.map { |e| Models::FilesystemEvent.from_hash(e) }
+      end
+
+      # Stop watching and clean up the watcher
+      #
+      # Calls the RemoveWatcher RPC to release server-side resources.
+      # After calling this method, {#get_new_events} will raise an error.
+      # Calling stop on an already-stopped handle is a no-op.
+      #
+      # @return [void]
+      def stop
+        return if @stopped
+
+        @envd_rpc_proc.call(
+          "filesystem.Filesystem", "RemoveWatcher",
+          body: { watcherId: @watcher_id }
+        )
+        @stopped = true
+      rescue StandardError
+        @stopped = true
+        # Ignore errors on cleanup - the watcher may have already been
+        # removed server-side (e.g., sandbox shutdown)
+      end
+
+      # Check if the watcher has been stopped
+      #
+      # @return [Boolean] true if {#stop} has been called
+      def stopped?
+        @stopped
+      end
+
+      private
+
+      # Extract events array from the RPC response
+      #
+      # The response may contain events under different keys depending on
+      # the serialization format (camelCase JSON vs. symbol keys from parsed response).
+      #
+      # @param response [Hash] The parsed RPC response
+      # @return [Array<Hash>] Array of raw event hashes
+      def extract_events(response)
+        return [] unless response.is_a?(Hash)
+
+        response["events"] || response[:events] || []
+      end
+    end
+  end
+end

data/lib/e2b/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module E2B
+  VERSION = "0.2.0"
+end

data/lib/e2b.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# E2B Ruby SDK
+# Ruby client for E2B sandbox API
+
+# Core requires
+require_relative "e2b/version"
+require_relative "e2b/errors"
+require_relative "e2b/configuration"
+
+# API layer
+require_relative "e2b/api/http_client"
+
+# Models
+require_relative "e2b/models/sandbox_info"
+require_relative "e2b/models/process_result"
+require_relative "e2b/models/entry_info"
+
+# Services
+require_relative "e2b/services/base_service"
+require_relative "e2b/services/command_handle"
+require_relative "e2b/services/commands"
+require_relative "e2b/services/filesystem"
+require_relative "e2b/services/watch_handle"
+require_relative "e2b/services/pty"
+require_relative "e2b/services/git"
+
+# Core classes
+require_relative "e2b/sandbox"
+require_relative "e2b/client"
+
+# E2B SDK for Ruby
+#
+# Provides access to E2B sandboxes - secure cloud environments
+# for AI-generated code execution.
+#
+# @example Quick start with Sandbox class (recommended)
+#   sandbox = E2B::Sandbox.create(template: "base", api_key: "your-key")
+#
+#   result = sandbox.commands.run("echo 'Hello, World!'")
+#   puts result.stdout
+#
+#   sandbox.files.write("/home/user/hello.txt", "Hello!")
+#   content = sandbox.files.read("/home/user/hello.txt")
+#
+#   sandbox.kill
+#
+# @example Using Client class
+#   client = E2B::Client.new(api_key: "your-api-key")
+#   sandbox = client.create(template: "base")
+#
+# @example Using global configuration
+#   E2B.configure do |config|
+#     config.api_key = "your-api-key"
+#   end
+#
+#   sandbox = E2B::Sandbox.create(template: "base")
+#
+# @see https://e2b.dev/docs E2B Documentation
+module E2B
+  class << self
+    # @return [Configuration, nil] Global configuration
+    attr_accessor :configuration
+
+    # Configure the E2B SDK globally
+    #
+    # @yield [config] Configuration block
+    # @yieldparam config [Configuration] Configuration instance
+    # @return [Configuration]
+    #
+    # @example
+    #   E2B.configure do |config|
+    #     config.api_key = "your-api-key"
+    #     config.domain = "e2b.app"
+    #   end
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Reset global configuration
+    def reset_configuration!
+      self.configuration = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: e2b
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Tao Luo
+bindir: bin
+cert_chain: []
+date: 2026-03-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  Ruby client for creating and managing E2B sandboxes - secure cloud environments
+  for AI-generated code execution. Supports sandbox lifecycle management, command
+  execution, file operations, PTY terminals, git operations, and directory watching.
+email:
+- luotao@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/e2b.rb
+- lib/e2b/api/http_client.rb
+- lib/e2b/client.rb
+- lib/e2b/configuration.rb
+- lib/e2b/errors.rb
+- lib/e2b/models/entry_info.rb
+- lib/e2b/models/process_result.rb
+- lib/e2b/models/sandbox_info.rb
+- lib/e2b/sandbox.rb
+- lib/e2b/services/base_service.rb
+- lib/e2b/services/command_handle.rb
+- lib/e2b/services/commands.rb
+- lib/e2b/services/filesystem.rb
+- lib/e2b/services/git.rb
+- lib/e2b/services/pty.rb
+- lib/e2b/services/watch_handle.rb
+- lib/e2b/version.rb
+homepage: https://github.com/ya-luotao/e2b-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ya-luotao/e2b-ruby
+  source_code_uri: https://github.com/ya-luotao/e2b-ruby
+  documentation_uri: https://e2b.dev/docs
+  changelog_uri: https://github.com/ya-luotao/e2b-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Ruby SDK for E2B sandbox API
+test_files: []