little_ghost 0.1.0

data/lib/little_ghost/unrestricted_sandbox.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module LittleGhost
+  # UnrestrictedSandbox is a convenient host-backed sandbox for trusted local
+  # work. It offers bounded text-file operations and command execution using only
+  # Ruby's standard library.
+  #
+  #   workspace = LittleGhost::Workspace.new(root: Dir.pwd)
+  #   sandbox = LittleGhost::UnrestrictedSandbox.new(workspace:)
+  #   sandbox.read("README.md").lines.first # => "# LittleGhost\n"
+  #
+  # Reads return valid UTF-8 text. Writes preserve the supplied String bytes.
+  # Paths must be relative, may not contain +..+, and are checked against the
+  # configured workspace root.
+  #
+  # === Security and trust
+  #
+  # This sandbox is not a security boundary. Commands run directly on the host
+  # with the Ruby process's permissions, and filesystem containment cannot defend
+  # against concurrent adversarial mutation. Use an isolated Sandbox
+  # implementation for untrusted work.
+  class UnrestrictedSandbox < Sandbox
+    # Configures a host sandbox with explicit read, write, and listing limits.
+    # Filesystem writes remain disabled unless +writable+ is true.
+    def initialize(workspace:, writable: false, max_read_bytes: 1_000_000, max_write_bytes: 1_000_000, max_list_entries: 10_000)
+      super(workspace:)
+      @writable = writable
+      @max_read_bytes = Integer(max_read_bytes)
+      @max_write_bytes = Integer(max_write_bytes)
+      @max_list_entries = Integer(max_list_entries)
+      unless [@max_read_bytes, @max_write_bytes, @max_list_entries].all?(&:positive?)
+        raise ArgumentError, "sandbox limits must be positive"
+      end
+
+      @root = File.expand_path(workspace.root)
+      capture_root_identity if File.exist?(@root)
+    end
+
+    # Opens the sandbox and verifies that the workspace root has not changed.
+    def open(run: nil)
+      if @root_identity
+        validate_root!
+      else
+        @root = File.realpath(workspace.root)
+        capture_root_identity
+      end
+      self
+    end
+
+    # Indicates whether this sandbox accepts filesystem mutations.
+    def writable? = @writable
+
+    # Reads a bounded UTF-8 file within the workspace.
+    def read(path, context: nil)
+      context&.check!
+      File.open(existing_path(path), read_flags) do |file|
+        raise ToolError, "Path is not a file" unless file.stat.file?
+
+        content = file.read(@max_read_bytes + 1)
+        raise ToolError, "File exceeds the read limit" if content.bytesize > @max_read_bytes
+
+        content.force_encoding(Encoding::UTF_8)
+        raise ToolError, "File is not valid UTF-8 text" unless content.valid_encoding?
+        content
+      end
+    rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+      raise ToolError, "File is not valid UTF-8 text"
+    end
+
+    # Produces a newline-delimited, sorted directory listing. Directories end in
+    # +/+.
+    def list(path = ".", context: nil)
+      context&.check!
+      directory = existing_path(path, allow_root: true)
+      raise ToolError, "Path is not a directory" unless File.directory?(directory)
+
+      entries = Dir.children(directory)
+      raise ToolError, "Directory exceeds the listing limit" if entries.length > @max_list_entries
+
+      entries.sort.map do |entry|
+        File.lstat(File.join(directory, entry)).directory? ? "#{entry}/" : entry
+      end.join("\n")
+    end
+
+    # Writes a bounded String without following a symbolic-link target.
+    def write(path, content, context: nil)
+      context&.check!
+      raise ToolError, "Sandbox is read-only" unless writable?
+      raise ToolError, "Content exceeds the write limit" if content.bytesize > @max_write_bytes
+
+      flags = File::WRONLY | File::CREAT | File::TRUNC
+      flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+      flags |= File::NONBLOCK if defined?(File::NONBLOCK)
+      File.open(writable_path(path), flags, 0o644) do |file|
+        raise ToolError, "Path is not a file" unless file.stat.file?
+
+        file.write(content)
+      end
+      "Wrote #{content.bytesize} bytes to #{display_path(path)}"
+    rescue Errno::ELOOP
+      raise ToolError, "Write target cannot be a symbolic link"
+    end
+
+    # Replaces exactly one occurrence of +old_text+ in a writable file.
+    def replace(path, old_text, new_text, context: nil)
+      context&.check!
+      raise ToolError, "Text to replace cannot be empty" if old_text.empty?
+
+      content = read(path, context:)
+      occurrences = content.scan(old_text).length
+      raise ToolError, "Text was not found in #{display_path(path)}" if occurrences.zero?
+      raise ToolError, "Text occurs more than once in #{display_path(path)}" if occurrences > 1
+
+      write(path, content.sub(old_text, new_text), context:)
+    end
+
+    # Executes an argument vector on the host from the workspace root.
+    #
+    # Shell syntax is not interpreted. The child starts with an empty environment
+    # unless +inherit_environment+ is true, is terminated when the context is
+    # cancelled or the timeout expires, and has each output stream truncated to
+    # +max_output_bytes+.
+    def execute_program(
+      command,
+      timeout:,
+      context: nil,
+      max_output_bytes: 1_000_000,
+      environment: {},
+      inherit_environment: false
+    )
+      argv = Array(command).map(&:to_s)
+      raise ToolError, "Command must contain an executable" if argv.empty? || argv.first.empty?
+
+      timeout = Float(timeout)
+      max_output_bytes = Integer(max_output_bytes)
+      raise ArgumentError, "timeout must be positive" unless timeout.positive?
+      raise ArgumentError, "max_output_bytes must be positive" unless max_output_bytes.positive?
+
+      stdout, stderr, status = capture(
+        argv,
+        timeout:,
+        context:,
+        max_output_bytes:,
+        environment:,
+        inherit_environment:
+      )
+      Execution.new(stdout:, stderr:, exit_code: status.exitstatus)
+    end
+
+    private
+
+    def capture(argv, timeout:, context:, max_output_bytes:, environment:, inherit_environment:)
+      result = nil
+      deadline = monotonic_time + timeout
+      Open3.popen3(
+        environment.transform_keys(&:to_s).transform_values(&:to_s),
+        *argv,
+        chdir: workspace.root,
+        pgroup: true,
+        unsetenv_others: !inherit_environment
+      ) do |stdin, stdout, stderr, wait_thread|
+        stdin.close
+        stdout_reader = Thread.new { drain(stdout, max_output_bytes) }
+        stderr_reader = Thread.new { drain(stderr, max_output_bytes) }
+        wait_for(wait_thread, [stdout_reader, stderr_reader], deadline, context)
+        result = [stdout_reader.value, stderr_reader.value, wait_thread.value]
+      ensure
+        stdout_reader&.kill
+        stderr_reader&.kill
+      end
+      result
+    end
+
+    def wait_for(wait_thread, readers, deadline, context)
+      until !wait_thread.alive? && readers.none?(&:alive?)
+        context&.check!
+        raise ToolError, "Command timed out" if monotonic_time >= deadline
+
+        wait_thread.join(0.01)
+        Thread.pass
+      end
+    rescue
+      terminate(wait_thread.pid)
+      raise
+    end
+
+    def terminate(pid)
+      Process.kill("TERM", -pid)
+      deadline = monotonic_time + 0.5
+      while monotonic_time < deadline
+        return unless process_group_alive?(pid)
+
+        Thread.pass
+      end
+
+      Process.kill("KILL", -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def process_group_alive?(pid)
+      Process.kill(0, -pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def drain(io, max_output_bytes)
+      captured = +""
+      while (chunk = io.read(16_384))
+        remaining = max_output_bytes + 1 - captured.bytesize
+        captured << chunk.byteslice(0, remaining) if remaining.positive?
+      end
+      truncate(captured, max_output_bytes)
+    end
+
+    def truncate(output, max_output_bytes)
+      return output if output.bytesize <= max_output_bytes
+
+      "#{output.byteslice(0, max_output_bytes)}\n[output truncated]"
+    end
+
+    def existing_path(path, allow_root: false)
+      candidate = expanded_path(path, allow_root:)
+      validate_root!
+      resolved = File.realpath(candidate)
+      ensure_within_root!(resolved)
+      resolved
+    rescue Errno::ENOENT
+      raise ToolError, "Path does not exist"
+    end
+
+    def writable_path(path)
+      candidate = expanded_path(path)
+      validate_root!
+      raise ToolError, "Write target cannot be a symbolic link" if File.symlink?(candidate)
+
+      if File.exist?(candidate)
+        resolved = File.realpath(candidate)
+        ensure_within_root!(resolved)
+        resolved
+      else
+        parent = File.realpath(File.dirname(candidate))
+        ensure_within_root!(parent)
+        File.join(parent, File.basename(candidate))
+      end
+    rescue Errno::ENOENT
+      raise ToolError, "Path does not exist"
+    end
+
+    def expanded_path(path, allow_root: false)
+      components = path_components(path)
+      raise ToolError, "Path must identify a workspace entry" if components.empty? && !allow_root
+
+      File.join(@root, *components)
+    end
+
+    def ensure_within_root!(path)
+      root_prefix = @root.end_with?(File::SEPARATOR) ? @root : "#{@root}#{File::SEPARATOR}"
+      return path if path == @root || path.start_with?(root_prefix)
+
+      raise ToolError, "Path escapes the configured workspace"
+    end
+
+    def validate_root!
+      identity = File.stat(File.realpath(@root)).then { |stat| [stat.dev, stat.ino] }
+      raise ToolError, "Workspace root changed after initialization" unless identity == @root_identity
+    rescue Errno::ENOENT
+      raise ToolError, "Workspace root changed after initialization"
+    end
+
+    def capture_root_identity
+      @root = File.realpath(@root)
+      @root_identity = File.stat(@root).then { |stat| [stat.dev, stat.ino] }.freeze
+    end
+
+    def read_flags
+      flags = File::RDONLY
+      flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+      flags |= File::NONBLOCK if defined?(File::NONBLOCK)
+      flags
+    end
+
+    def path_components(path)
+      value = String(path)
+      raise ToolError, "Path contains a null byte" if value.include?("\0")
+      raise ToolError, "Path must be relative to the workspace" if value.start_with?(File::SEPARATOR)
+
+      value.split(File::SEPARATOR).reject { |component| component.empty? || component == "." }.tap do |components|
+        raise ToolError, "Path escapes the configured workspace" if components.include?("..")
+      end
+    end
+
+    def display_path(path)
+      path_components(path).join(File::SEPARATOR)
+    end
+  end
+end

data/lib/little_ghost/usage.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Usage makes token accounting consistent across model providers. It keeps
+  # input, output, cache, and reasoning counts separate so applications can
+  # aggregate them without double-counting.
+  #
+  # Providers report uncached input, visible output, cache reads, cache writes,
+  # and reasoning separately. Invalid or negative values normalize to zero.
+  class Usage
+    FIELDS = %i[input_tokens output_tokens cache_read_tokens cache_write_tokens reasoning_tokens].freeze # :nodoc:
+
+    attr_reader(*FIELDS)
+
+    # Normalizes provider token counts; invalid or negative values become zero.
+    def initialize(input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, reasoning_tokens: 0)
+      @input_tokens = integer(input_tokens)
+      @output_tokens = integer(output_tokens)
+      @cache_read_tokens = integer(cache_read_tokens)
+      @cache_write_tokens = integer(cache_write_tokens)
+      @reasoning_tokens = integer(reasoning_tokens)
+    end
+
+    # Sums every normalized token field.
+    def total_tokens
+      FIELDS.sum { |field| public_send(field) }
+    end
+
+    # Adds two usage values field by field.
+    def +(other)
+      self.class.new(**FIELDS.to_h { |field| [field, public_send(field) + other.public_send(field)] })
+    end
+
+    # Exposes every field and +total_tokens+ as a hash.
+    def to_h
+      FIELDS.to_h { |field| [field, public_send(field)] }.merge(total_tokens: total_tokens)
+    end
+
+    private
+
+    def integer(value)
+      [Integer(value || 0), 0].max
+    rescue ArgumentError, TypeError
+      0
+    end
+  end
+end

data/lib/little_ghost/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Current LittleGhost gem version.
+  VERSION = "0.1.0"
+end

data/lib/little_ghost/workflow.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Build agentic workflows with ordinary Ruby branching and local variables.
+  # A workflow composes several agents, consumes intermediate answers, and
+  # streams one final agent response.
+  #
+  # A support workflow can route a difficult request through research before the
+  # responder writes the caller-visible answer:
+  #
+  #   class ResponseWorkflow < LittleGhost::Workflow
+  #     private
+  #
+  #     def perform
+  #       route = invoke(RouterAgent).output
+  #       return invoke(CustomerSupportAgent) unless route["research"]
+  #
+  #       evidence = invoke(ResearchAgent).output
+  #       invoke CustomerSupportAgent, input: <<~PROMPT
+  #         #{input.text}
+  #
+  #         Research:
+  #         #{evidence}
+  #       PROMPT
+  #     end
+  #   end
+  #
+  #   run = runtime.build_run(
+  #     {message: "Why is transfer 481 pending?"},
+  #     agent_class: CustomerSupportAgent,
+  #     entrypoint_class: ResponseWorkflow
+  #   ).call
+  #   run.response # => "Transfer 481 is waiting for the receiving bank."
+  #
+  # +invoke+ returns a lazy Workflow::Invocation. Reading +output+ consumes an
+  # intermediate invocation and returns RunResult#output; +perform+ must return
+  # its final invocation without consuming it so those events reach the caller.
+  # Intermediate usage is added to the final result.
+  #
+  # Every child inherits input, history, settings, cancellation, deadline,
+  # template paths, and trace parentage unless +invoke+ overrides its input.
+  # JSON-like context is copied for each child, preventing one intermediate agent
+  # from mutating a sibling's state. Non-JSON-like workflow context raises
+  # ArgumentError.
+  #
+  # A workflow instance streams once. Returning the wrong value, returning an
+  # already consumed invocation, or consuming an invocation twice raises
+  # ProtocolError. Built agents close in reverse order, and the first cleanup
+  # failure is re-raised after every invocation has been given a chance to close.
+  # Composition errors emit an +invocation_error+ event and then re-raise.
+  class Workflow
+    # Hold one lazy agent call inside a workflow composition.
+    # Workflow implementations normally use only its output method or return the
+    # object as the final invocation.
+    class Invocation
+      attr_reader :result # :nodoc:
+
+      def initialize(input:, history:, context:, build:, on_usage:) # :nodoc:
+        @input = input
+        @history = history
+        @context = context
+        @build = build
+        @on_usage = on_usage
+        @mutex = Mutex.new
+        @consumed = false
+        @closed = false
+      end
+
+      def each(checkpoint: nil) # :nodoc:
+        return enum_for(__method__, checkpoint:) unless block_given?
+
+        agent, options = @mutex.synchronize do
+          raise Error, "workflow invocation is already closed" if @closed
+          raise ProtocolError, "workflow invocation was already consumed" if @consumed
+
+          @consumed = true
+          @agent, options = @build.call
+          [@agent, options]
+        end
+        begin
+          agent.stream(
+            @input,
+            history: @history,
+            context: @context,
+            **options,
+            checkpoint:
+          ).each do |event|
+            @result = event.data[:result] if event.type == :invocation_stop
+            @usage = event.data[:usage] if event.type == :invocation_error
+            yield event
+          end
+        ensure
+          report_usage if @intermediate
+          close
+        end
+      end
+
+      # Consumes this invocation when necessary and returns RunResult#output.
+      #
+      # A structured agent returns its validated value; an ordinary agent returns
+      # response text. Intermediate usage is recorded for the workflow total.
+      def output
+        @intermediate = true
+        each {} unless consumed?
+        result&.output
+      end
+
+      def consumed? # :nodoc:
+        @mutex.synchronize { @consumed }
+      end
+
+      def close # :nodoc:
+        agent = @mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          @agent
+        end
+        agent&.close
+      end
+
+      private
+
+      def report_usage
+        usage = result&.usage || @usage
+        @on_usage.call(usage) if usage
+      end
+    end
+
+    # Owning run and the runtime used to resolve workflow agents.
+    attr_reader :run, :runtime
+
+    def initialize(run:, runtime: run.runtime) # :nodoc:
+      @run = run
+      @runtime = runtime
+      @mutex = Mutex.new
+      @closed = false
+      @started = false
+      @invocations = []
+    end
+
+    # Additional prompt locals shared by agents invoked from the workflow.
+    # Subclasses may override this hook.
+    def prompt_locals = {}
+
+    # Streams the workflow once as StreamEvent objects.
+    #
+    # +perform+ must return a final, unconsumed Workflow::Invocation. The returned
+    # Enumerator is lazy, but calling +stream+ reserves the single-use workflow
+    # instance even when enumeration has not started yet.
+    def stream(
+      input = nil,
+      history: nil,
+      context: nil,
+      cancellation_token: Support::CancellationToken.new,
+      deadline: nil,
+      settings: nil,
+      template_locals: nil,
+      template_paths: nil,
+      parent_operation_id: nil,
+      checkpoint: nil
+    )
+      raise ArgumentError, "input is required" if input.nil?
+
+      @mutex.synchronize do
+        raise Error, "workflow is already closed" if @closed
+        raise Error, "workflow instances can only be streamed once" if @started
+
+        @started = true
+        @input = input.is_a?(Message) ? input : Message.new(role: :user, content: input)
+        @history = normalize_history(history)
+        @context = context || {}
+        @cancellation_token = cancellation_token
+        @deadline = deadline
+        @settings = settings || {}
+        @template_locals = template_locals || {}
+        @template_paths = template_paths || []
+        @parent_operation_id = parent_operation_id
+        @checkpoint = checkpoint
+        @intermediate_usage = Usage.new
+      end
+
+      Enumerator.new do |events|
+        error_emitted = false
+        observed_usage = nil
+        ensure_open!
+        final_invocation = perform
+        unless final_invocation.is_a?(Invocation) && !final_invocation.consumed?
+          raise ProtocolError, "#{self.class} must return its final invoke from perform"
+        end
+
+        final_invocation.each(checkpoint: @checkpoint) do |event|
+          error_emitted = true if event.type == :invocation_error
+          event = aggregate_usage(event)
+          observed_usage = case event.type
+          when :invocation_stop
+            event.data.fetch(:result).usage
+          when :invocation_error
+            event.data[:usage] || observed_usage
+          else
+            observed_usage
+          end
+          events << event
+        end
+      rescue => error
+        unless error_emitted
+          events << StreamEvent.build(
+            :invocation_error,
+            error:,
+            usage: observed_usage || workflow_usage,
+            metadata: {}
+          )
+        end
+        raise
+      end
+    end
+
+    # Closes all built agent invocations in reverse order.
+    #
+    # The operation is idempotent, attempts every close, and raises the first
+    # cleanup failure.
+    def close
+      invocations = @mutex.synchronize do
+        return if @closed
+
+        @closed = true
+        @invocations.reverse
+      end
+      errors = []
+      invocations.each do |invocation|
+        invocation.close
+      rescue => error
+        errors << error
+      end
+      raise errors.first if errors.any?
+    end
+
+    private
+
+    # The current normalized input, frozen history, and JSON-like context exposed
+    # to workflow implementations.
+    # :doc:
+    attr_reader :input, :history, :context
+
+    # :doc:
+    # Implements the composition and returns its final unconsumed invocation.
+    # Subclasses must override this hook.
+    def perform
+      raise NotImplementedError, "#{self.class} must implement #perform"
+    end
+
+    # :doc:
+    # Creates a lazy invocation for +agent_class_or_name+.
+    #
+    # Intermediate calls may use +output+; the final call must be returned from
+    # +perform+ without being consumed.
+    def invoke(agent_class_or_name, input: self.input, history: self.history, context: self.context)
+      invocation = Invocation.new(
+        input:,
+        history:,
+        context: isolated_state(context),
+        build: lambda {
+          agent = runtime.build_agent(agent_class_or_name, run:)
+          begin
+            [
+              agent,
+              {
+                cancellation_token: @cancellation_token,
+                deadline: @deadline,
+                settings: @settings,
+                template_locals: template_locals_for(agent),
+                template_paths: @template_paths,
+                parent_operation_id: @parent_operation_id
+              }
+            ]
+          rescue
+            agent.close
+            raise
+          end
+        },
+        on_usage: ->(usage) { record_intermediate_usage(usage) }
+      )
+      @mutex.synchronize do
+        raise Error, "workflow is already closed" if @closed
+
+        @invocations << invocation
+      end
+      invocation
+    end
+
+    def record_intermediate_usage(usage)
+      @mutex.synchronize { @intermediate_usage += usage }
+    end
+
+    def aggregate_usage(event)
+      case event.type
+      when :invocation_stop
+        result = event.data.fetch(:result)
+        combined = RunResult.new(
+          message: result.message,
+          stop_reason: result.stop_reason,
+          usage: workflow_usage + result.usage,
+          messages: result.messages,
+          state: result.state,
+          structured_result: result.structured_result
+        )
+        StreamEvent.build(event.type, **event.data.merge(result: combined))
+      when :invocation_error
+        usage = event.data[:usage]
+        return event unless usage
+
+        StreamEvent.build(event.type, **event.data.merge(usage: workflow_usage + usage))
+      else
+        event
+      end
+    end
+
+    def template_locals_for(agent)
+      @template_locals.merge(runtime.template_locals(run:, agent:))
+    end
+
+    def isolated_state(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [isolated_state(key), isolated_state(item)] }
+      when Array
+        value.map { |item| isolated_state(item) }
+      when String
+        value.dup
+      when NilClass, TrueClass, FalseClass, Numeric, Symbol
+        value
+      else
+        raise ArgumentError, "workflow context must contain only JSON-like state"
+      end
+    end
+
+    def workflow_usage
+      @mutex.synchronize { @intermediate_usage }
+    end
+
+    def ensure_open!
+      @mutex.synchronize { raise Error, "workflow is already closed" if @closed }
+    end
+
+    def normalize_history(value)
+      return [].freeze if value.nil?
+
+      Array(value).map { |message| Message.coerce(message) }.freeze
+    end
+  end
+end