little_ghost 0.4.0 → 0.6.0

data/lib/little_ghost/tool.rb

@@ -43,13 +43,17 @@ module LittleGhost
   #     end
   #   end
   #
+  #   class OrderSupportAgent < LittleGhost::Agent
+  #     tools OrderStatusTool
+  #   end
+  #
   #   OrderSupportAgent.ask(
   #     "Where is order 481?",
   #     actor_id: authenticated_user.id,
   #     context: {account_id: authenticated_user.account_id}
   #   )
   #
-  # These values cross different trust boundaries:
+  # Each value comes from a different part of the run:
   #
   # [<tt>input</tt>]
   #   Arguments selected by the model. The schema checks their shape, not their
@@ -67,8 +71,8 @@ module LittleGhost
   # The class DSL produces the specification sent to models. During an Agent
   # run, the tool registry creates and binds one Tool instance. Tests and custom
   # integrations may call +execute+ directly; it validates the arguments, calls
-  # +call+, and returns an ExecutionResult. Tool.define offers the same contract
-  # for an embedded implementation.
+  # +call+, and returns a normalized internal result. Tool.define offers the
+  # same contract for an embedded implementation.
   #
   # Mutable Tool instance state belongs to one Agent run. Registries close tool
   # instances that implement +close+; <tt>exclusive true</tt> prevents that tool
@@ -80,7 +84,13 @@ module LittleGhost
   # Cancellation, deadlines, and cleanup errors propagate instead of becoming
   # ordinary tool output. The configured sandbox, not Tool itself, enforces
   # filesystem and process isolation.
+  #
+  # See the {Tools guide}[rdoc-ref:docs/guides/tools.md] for the complete path
+  # from model-selected input to application context, sandbox
+  # delegation, concurrency, and code mode.
   class Tool
+    UNSET_RESULT_VALUE = Object.new.freeze # :nodoc:
+
     # Supply run-scoped collaborators when tools are instantiated outside an agent.
     # A binding can be copied with selected collaborators replaced.
     #
@@ -115,67 +125,84 @@ module LittleGhost
       end
     end
 
-    # Report the caller-safe outcome of one tool execution.
-    # The result retains model-facing content, status, and the original exception
-    # for application-side inspection.
-    ExecutionResult = Data.define(:content, :status, :error, :companion_content) do # :nodoc:
-      def initialize(content:, status:, error: nil, companion_content: [])
-        companions = Array(companion_content)
-        unless companions.all? do |block|
-          block.is_a?(Content::Text) || block.is_a?(Content::Image) || block.is_a?(Content::Document)
-        end
-          raise ArgumentError, "companion content must contain only text, images, or documents"
+    Result = Data.define(:value, :artifacts) do # :nodoc:
+      def initialize(value:, artifacts: [])
+        values = Array(artifacts)
+        unless values.all? { |artifact| artifact.is_a?(Artifact) }
+          raise ArgumentError, "artifacts must contain only LittleGhost::Artifact values"
         end
 
-        super(content:, status:, error:, companion_content: companions.dup.freeze)
-      end
-
-      def success?
-        status == :success
-      end
-
-      def error?
-        status == :error
+        super(value:, artifacts: values.dup.freeze)
       end
     end
 
-    # Reports the caller-safe outcome of one tool execution. It keeps
-    # model-facing content and status beside the original exception retained for
-    # application-side inspection. Companion content lets a tool place trusted
-    # text, images, or documents in the next model request without putting those
-    # blocks inside a provider-specific tool-result shape.
-    class ExecutionResult < Data # :doc:
+    # Returns a Ruby value together with files or media produced by a Tool.
+    # Tools without artifacts should return their Ruby value directly.
+    class Result < Data # :doc:
       ##
       # :singleton-method: new
       # :call-seq:
-      #   new(content:, status:, error: nil, companion_content: []) -> ExecutionResult
+      #   new(value:, artifacts: []) -> Result
       #
-      # Collects the model-facing and application-facing parts of one result.
+      # Creates a result from the Ruby +value+ and an Array of Artifact objects.
 
       ##
-      # :attr_reader: content
-      # The normalized, caller-safe text returned to the model.
+      # :attr_reader: value
+      # The ordinary Ruby value returned to application callers and code mode.
 
       ##
-      # :attr_reader: status
-      # Either +:success+ or +:error+.
+      # :attr_reader: artifacts
+      # The frozen Array of Artifact objects produced by the Tool.
+    end
 
-      ##
-      # :attr_reader: error
-      # The original exception for application-side inspection, when present.
+    # Internal normalized outcome used between Tool, Agent, and code mode.
+    ExecutionResult = Data.define(:value, :content, :status, :error, :artifacts, :presentation_content) do # :nodoc:
+      def initialize(
+        status:,
+        content: UNSET_RESULT_VALUE,
+        value: UNSET_RESULT_VALUE,
+        error: nil,
+        artifacts: [],
+        presentation_content: []
+      )
+        if content.equal?(UNSET_RESULT_VALUE) && value.equal?(UNSET_RESULT_VALUE)
+          raise ArgumentError, "tool result requires content or value"
+        end
+        content = value if content.equal?(UNSET_RESULT_VALUE)
+        value = content if value.equal?(UNSET_RESULT_VALUE)
 
-      ##
-      # :attr_reader: companion_content
-      # Frozen Text, Image, and Document blocks appended as a transient user
-      # message after the ordinary tool result.
+        presentations = Array(presentation_content)
+        unless presentations.all? do |block|
+          block.is_a?(Content::Text) || block.is_a?(Content::Image) || block.is_a?(Content::Document)
+        end
+          raise ArgumentError, "artifact presentation must contain only text, images, or documents"
+        end
 
-      ##
-      # :method: success?
-      # Indicates that +status+ is +:success+.
+        artifact_values = Array(artifacts)
+        unless artifact_values.all? { |artifact| artifact.is_a?(Artifact) }
+          raise ArgumentError, "artifacts must contain only LittleGhost::Artifact values"
+        end
 
-      ##
-      # :method: error?
-      # Indicates that +status+ is +:error+.
+        status = status.to_sym
+        raise ArgumentError, "tool result status must be success or error" unless %i[success error].include?(status)
+
+        super(
+          value:,
+          content:,
+          status:,
+          error:,
+          artifacts: artifact_values.dup.freeze,
+          presentation_content: presentations.dup.freeze
+        )
+      end
+
+      def success?
+        status == :success
+      end
+
+      def error?
+        status == :error
+      end
     end
 
     extend Support::ClassAttributes
@@ -184,6 +211,7 @@ module LittleGhost
     class_attribute :description_value
     class_attribute :input_schema_value
     class_attribute :exclusive_value, default: false
+    class_attribute :availability_value
 
     class << self
       # :call-seq:
@@ -238,6 +266,20 @@ module LittleGhost
         self.exclusive_value = !!values.fetch(0)
       end
 
+      # Declares whether this Tool is available for a run-scoped +binding+.
+      # With no block, returns the configured predicate or nil. ToolRegistry
+      # omits a Tool whose predicate returns false before constructing it.
+      def available_if(&predicate)
+        return availability_value unless predicate
+
+        self.availability_value = predicate
+      end
+
+      # Returns whether this Tool should be registered for +binding+.
+      def available?(binding)
+        !availability_value || !!availability_value.call(binding)
+      end
+
       # Creates an anonymous Tool subclass backed by +implementation+.
       # The block receives +input+ and may also accept the +context:+ keyword.
       #
@@ -335,7 +377,7 @@ module LittleGhost
     # Bound sandbox, when available.
     def sandbox = binding.sandbox
 
-    # Validates +input+ and invokes the tool, returning an ExecutionResult.
+    # Validates +input+ and invokes the Tool, returning its normalized outcome.
     #
     # Cancellation, deadline, and cleanup exceptions remain control-flow
     # exceptions. ToolError and unexpected failures become sanitized error
@@ -350,8 +392,9 @@ module LittleGhost
 
       value = bound_for(context).call(input)
       return normalize_execution_result(value) if value.is_a?(ExecutionResult)
+      return success(value.value, artifacts: value.artifacts) if value.is_a?(Result)
 
-      success(sanitize(value))
+      success(value)
     rescue CancelledError, DeadlineExceededError, CleanupError
       raise
     rescue ToolError => error
@@ -396,8 +439,8 @@ module LittleGhost
       raise ToolError, "Tool returned content that cannot be serialized"
     end
 
-    def success(content)
-      ExecutionResult.new(content: content.freeze, status: :success)
+    def success(value, artifacts: [])
+      ExecutionResult.new(value:, content: sanitize(value).freeze, status: :success, artifacts:)
     end
 
     def failure(content, error:)
@@ -406,14 +449,18 @@ module LittleGhost
 
     def normalize_execution_result(result)
       ExecutionResult.new(
+        value: result.value,
         content: sanitize(result.content).freeze,
         status: result.status,
         error: result.error,
-        companion_content: result.companion_content
+        artifacts: result.artifacts,
+        presentation_content: result.presentation_content
       )
     end
 
     class SchemaValidator # :nodoc:
+      REGEXP_TIMEOUT = 0.05
+
       def initialize(schema)
         @schema = schema
       end
@@ -482,7 +529,11 @@ module LittleGhost
         pattern = schema["pattern"]
         errors << "#{path} must have at least #{minimum} characters" if minimum && value.length < minimum
         errors << "#{path} must have at most #{maximum} characters" if maximum && value.length > maximum
-        errors << "#{path} has an invalid format" if pattern && !Regexp.new(pattern).match?(value)
+        if pattern && !Regexp.new(pattern, timeout: REGEXP_TIMEOUT).match?(value)
+          errors << "#{path} has an invalid format"
+        end
+      rescue Regexp::TimeoutError
+        errors << "#{path} has an invalid format"
       rescue RegexpError
         errors << "#{path} has an invalid schema pattern"
       end

data/lib/little_ghost/tool_registry.rb

@@ -127,7 +127,7 @@ module LittleGhost
       if value.is_a?(Array)
         value.flatten.compact.each { |child| resolve(child, instances, binding:) }
       elsif value.is_a?(Class) && value <= Tool
-        instances << value.new(binding:)
+        instances << value.new(binding:) if value.available?(binding)
       elsif value.is_a?(Class)
         resolve(value.tools(binding), instances, binding:)
       else

data/lib/little_ghost/tools/filesystem.rb

@@ -14,7 +14,7 @@ module LittleGhost
     #   )
     #   registry.names # => ["read_file", "list_files"]
     #
-    # === Security and trust
+    # === Files follow the Sandbox
     #
     # These tools do not add isolation. The configured sandbox must enforce path
     # containment, permissions, size limits, and cancellation.

data/lib/little_ghost/tools/shell.rb

@@ -9,9 +9,10 @@ module LittleGhost
     # shell syntax.
     #
     # The child environment is cleared, runtime is limited to 30 seconds, and
-    # each output stream is limited to 1 MB. These defaults reduce accidental
-    # exposure but do not create an isolation boundary; the configured sandbox
-    # remains responsible for security.
+    # each output stream is limited to 1 MB. Commands may spawn children when
+    # the backend supports them. These defaults reduce accidental exposure but
+    # do not create an isolation boundary; the configured sandbox remains
+    # responsible for security.
     class Shell < Tool
       DEFAULT_TIMEOUT = 30 # :nodoc:
       MAX_OUTPUT_BYTES = 1_000_000 # :nodoc:

data/lib/little_ghost/version.rb

@@ -2,5 +2,5 @@
 
 module LittleGhost
   # Current LittleGhost gem version.
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/little_ghost/workflow.rb

@@ -318,8 +318,8 @@ module LittleGhost
 
       token = @cancellation_token.child
       queue = SizedQueue.new(1_000)
-      worker = Thread.new do
-        results = Support::Executor.new(max_concurrency:).map(
+      worker = task_runner.spawn do
+        results = Support::Executor.new(max_concurrency:, runner: task_runner).map(
           invocations,
           cancellation_token: token,
           on_result: ->(_index, execution) { record_workflow_steps(execution.fetch(:steps)) }
@@ -345,7 +345,7 @@ module LittleGhost
       executions.map { |execution| execution.fetch(:output) }
     ensure
       token&.cancel
-      worker&.join
+      worker&.wait
     end
 
     def execute_workflow_invocation(reference:, participant:, input:, history:, context:, policies:, checkpoint:)

data/lib/little_ghost/workspace.rb

@@ -1,31 +1,245 @@
 # frozen_string_literal: true
 
+require "pathname"
+require "fileutils"
+
 module LittleGhost
-  # A Workspace gives an agent a concrete home for files. Pair it with a Sandbox
-  # to decide how those files may be read, changed, or used by commands.
+  # A Workspace names the host paths associated with a Run. Pair it with a
+  # Sandbox to decide how those paths may be read, changed, or used by commands.
   #
   #   workspace = LittleGhost::Workspace.new(root: "./tmp/support-run")
   #   workspace.root # => an absolute path ending in "/tmp/support-run"
   #
-  # Workspaces participate in the run resource lifecycle. A custom workspace can
-  # provision storage in #open and release it in #close.
+  # Workspaces participate in the Run resource lifecycle, but object lifetime
+  # and file lifetime are separate. Opening creates +root+ and relative named
+  # paths, but does not delete them by default. Absolute named paths are trusted
+  # references that must already exist. Setup and teardown callbacks let trusted
+  # application configuration provision run-scoped resources without a
+  # Workspace subclass. Applications that share a writable root between Runs
+  # must provide their own concurrency and tenant isolation.
+  #
+  # See the {Workspaces and Sandboxes guide}[rdoc-ref:docs/guides/sandboxing.md]
+  # for logical paths, Sandbox policy, process ownership, and networking.
   class Workspace
-    # Expands +root+ to an absolute path.
-    def initialize(root:)
+    @providers = {}
+
+    class << self
+      # Registers a trusted workspace provider under a configuration symbol.
+      def register_provider(name, implementation)
+        unless implementation.is_a?(Class) && implementation <= Workspace
+          raise ArgumentError, "workspace provider must be a Workspace class"
+        end
+
+        Workspace.providers[name.to_sym] = implementation
+      end
+
+      # Resolves an explicitly selected provider without changing its meaning.
+      def resolve_provider(name)
+        Workspace.providers.fetch(name.to_sym) do
+          raise DependencyError, "workspace provider :#{name} is not available"
+        end
+      end
+
+      def providers # :nodoc:
+        @providers ||= {}
+      end
+    end
+
+    # Expands +root+ and every named path to absolute paths. Relative named paths
+    # must remain beneath +root+; absolute named paths deliberately refer outside
+    # it. +setup+ receives +workspace:+ and +run:+ when the Run opens. +teardown+
+    # receives the same values when it closes, including after partial setup.
+    def initialize(root:, paths: {}, setup: nil, teardown: nil)
       @root = File.expand_path(root)
+      @paths = normalize_paths(paths)
+      @setup = validate_callback(setup, :setup)
+      @teardown = validate_callback(teardown, :teardown)
+      @opened = false
+      @active = false
+      @run = nil
+      @identities = nil
     end
 
     # Absolute filesystem root assigned to this workspace.
     attr_reader :root
 
-    # Opens any run-scoped resources and yields this workspace to the run.
+    # Immutable named absolute paths owned by this workspace declaration.
+    attr_reader :paths
+
+    # Returns a configured named path, raising KeyError when it is absent.
+    def path(name)
+      paths.fetch(name.to_sym)
+    end
+
+    # Converts a logical path to its physical workspace path. This method checks
+    # lexical containment but does not make direct filesystem access safe for
+    # untrusted input. Pass model-selected paths through Sandbox file operations,
+    # which reject symlinks while opening each path component.
+    #
+    # Relative paths belong to +root+; named paths use
+    # <tt>workspace://name/path</tt>. Physical absolute paths are deliberately
+    # rejected so brokered tools do not teach callers host filesystem layout.
+    def resolve(reference)
+      validate! if @identities
+      value = String(reference)
+      raise ArgumentError, "workspace paths must be relative or use workspace://" if Pathname.new(value).absolute?
+
+      base, relative = if value.start_with?("workspace://")
+        logical = value.delete_prefix("workspace://")
+        name, separator, child = logical.partition("/")
+        raise ArgumentError, "workspace path must name a configured path" if name.empty?
+
+        [path(name), separator.empty? ? "." : child]
+      else
+        [root, value]
+      end
+      resolve_beneath(base, relative)
+    end
+
+    # Returns the stable logical reference for a physical workspace path.
+    def reference(physical_path)
+      candidate = File.expand_path(physical_path)
+      named = paths.sort_by { |_, path| -path.length }.find { |_, path| beneath?(candidate, path) }
+      if named
+        name, base = named
+        relative = candidate.delete_prefix(base).delete_prefix(File::SEPARATOR)
+        return relative.empty? ? "workspace://#{name}" : "workspace://#{name}/#{relative}"
+      end
+      raise ArgumentError, "path is outside the workspace" unless beneath?(candidate, root)
+
+      candidate.delete_prefix(root).delete_prefix(File::SEPARATOR).then { |value| value.empty? ? "." : value }
+    end
+
+    # Environment variables supplied to sandboxed programs. These values are
+    # trusted process configuration and are never returned by filesystem tools.
+    def environment
+      {"LITTLE_GHOST_WORKSPACE_ROOT" => root}.merge(paths.to_h do |name, path|
+        ["LITTLE_GHOST_WORKSPACE_#{name.to_s.upcase.gsub(/[^A-Z0-9]/, "_")}", path]
+      end).freeze
+    end
+
+    # Verifies that no configured directory was replaced after #open.
+    def validate!
+      return self unless @identities
+
+      {root: root}.merge(paths).each do |name, path|
+        realpath = File.realpath(path)
+        stat = File.stat(realpath)
+        expected = @identities.fetch(name)
+        unless [realpath, stat.dev, stat.ino] == expected
+          raise ToolError, "workspace path changed after opening: #{name}"
+        end
+      end
+      self
+    rescue Errno::ENOENT
+      raise ToolError, "workspace path changed after opening: #{name}"
+    end
+
+    # Calls the application setup callback once and returns this workspace.
     def open(run: nil)
+      return self if @opened
+
+      @run = run
+      @active = true
+      @setup&.call(workspace: self, run:)
+      materialize!
+      capture_identities!
+      @opened = true
       self
+    rescue
+      close
+      raise
     end
 
-    # Releases workspace resources. The default workspace has nothing to close.
+    # Calls the application teardown callback once. The default does not remove
+    # files or directories.
     def close
+      return nil unless @active
+
+      @teardown&.call(workspace: self, run: @run)
       nil
+    ensure
+      @opened = false
+      @active = false
+      @run = nil
+      @identities = nil
+    end
+
+    private
+
+    def materialize!
+      FileUtils.mkdir_p(root)
+      paths.each do |name, directory|
+        if @relative_path_names.include?(name)
+          FileUtils.mkdir_p(directory)
+        elsif !File.directory?(directory)
+          raise ArgumentError, "absolute workspace path :#{name} must already exist"
+        end
+      end
+    end
+
+    def capture_identities!
+      entries = {root: root}.merge(paths)
+      identities = entries.to_h do |name, path|
+        realpath = File.realpath(path)
+        stat = File.stat(realpath)
+        [name, [realpath, stat.dev, stat.ino].freeze]
+      end
+      duplicates = identities.group_by { |_, identity| identity.drop(1) }.select { |_, values| values.length > 1 }
+      unless duplicates.empty?
+        names = duplicates.values.flat_map { |values| values.map(&:first) }
+        raise ArgumentError, "workspace paths must not alias the same directory: #{names.join(", ")}"
+      end
+      @identities = identities.freeze
+    end
+
+    def resolve_beneath(base, relative)
+      raise ArgumentError, "workspace path must not be empty" if relative.empty?
+      components = Pathname.new(relative).each_filename.to_a
+      raise ArgumentError, "workspace path traversal is not allowed" if components.include?("..")
+
+      expanded = File.expand_path(relative, base)
+      raise ArgumentError, "workspace path escapes its root" unless beneath?(expanded, base)
+
+      expanded
+    end
+
+    def beneath?(candidate, base)
+      candidate == base || candidate.start_with?(base.end_with?(File::SEPARATOR) ? base : "#{base}#{File::SEPARATOR}")
+    end
+
+    def normalize_paths(values)
+      unless values.respond_to?(:each_pair)
+        raise ArgumentError, "workspace paths must be a Hash"
+      end
+
+      relative_names = []
+      normalized = values.each_pair.to_h do |name, value|
+        key = name.to_sym
+        path = value.to_s
+        raise ArgumentError, "workspace path :#{key} must not be empty" if path.empty?
+
+        expanded = File.expand_path(path, root)
+        root_prefix = root.end_with?(File::SEPARATOR) ? root : "#{root}#{File::SEPARATOR}"
+        relative = !Pathname.new(path).absolute?
+        if relative && expanded != root && !expanded.start_with?(root_prefix)
+          raise ArgumentError, "relative workspace path :#{key} must remain beneath the workspace root"
+        end
+        relative_names << key if relative
+
+        [key, expanded.freeze]
+      end.freeze
+      @relative_path_names = relative_names.freeze
+      normalized
+    end
+
+    def validate_callback(callback, name)
+      return unless callback
+      raise ArgumentError, "workspace #{name} must be callable" unless callback.respond_to?(:call)
+
+      callback
     end
   end
+
+  Workspace.register_provider(:directory, Workspace)
 end