little_ghost 0.3.0 → 0.5.0

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

data/lib/little_ghost.rb

@@ -4,6 +4,9 @@ require_relative "little_ghost/version"
 require_relative "little_ghost/errors"
 require_relative "little_ghost/execution_state"
 require_relative "little_ghost/support"
+require_relative "little_ghost/data_map"
+require_relative "little_ghost/artifact"
+require_relative "little_ghost/artifacts"
 require_relative "little_ghost/events"
 require_relative "little_ghost/instrumentation"
 require_relative "little_ghost/tracing/open_telemetry"
@@ -14,6 +17,7 @@ require_relative "little_ghost/usage"
 require_relative "little_ghost/content"
 require_relative "little_ghost/message"
 require_relative "little_ghost/stream_event"
+require_relative "little_ghost/agent_stream_source"
 require_relative "little_ghost/model_request"
 require_relative "little_ghost/model_response"
 require_relative "little_ghost/run_result"
@@ -42,14 +46,22 @@ require_relative "little_ghost/model_resolver"
 require_relative "little_ghost/run_context"
 require_relative "little_ghost/workspace"
 require_relative "little_ghost/sandbox"
-require_relative "little_ghost/unrestricted_sandbox"
+require_relative "little_ghost/sandbox/process_session"
+require_relative "little_ghost/sandboxes/unrestricted"
+require_relative "little_ghost/sandboxes/bubblewrap"
+require_relative "little_ghost/sandboxes/seatbelt"
+require_relative "little_ghost/sandboxes/native"
 require_relative "little_ghost/tool"
 require_relative "little_ghost/tool_execution"
 require_relative "little_ghost/tool_registry"
+require_relative "little_ghost/code_mode"
+require_relative "little_ghost/code_mode/ruby_engine"
+require_relative "little_ghost/code_mode/runtime"
 require_relative "little_ghost/structured_output"
 require_relative "little_ghost/prompt_resolver"
 require_relative "little_ghost/session_store"
 require_relative "little_ghost/session_stores/memory"
+require_relative "little_ghost/session_stores/filesystem"
 require_relative "little_ghost/session"
 require_relative "little_ghost/skills"
 require_relative "little_ghost/tools/write_todos"
@@ -58,7 +70,7 @@ require_relative "little_ghost/execution"
 require_relative "little_ghost/subagents/definition"
 require_relative "little_ghost/subagents/agent_path"
 require_relative "little_ghost/subagents/manager"
-require_relative "little_ghost/agent_interruptions"
+require_relative "little_ghost/agent_interjections"
 require_relative "little_ghost/assembly"
 require_relative "little_ghost/assembly_execution"
 require_relative "little_ghost/agent"
@@ -68,41 +80,33 @@ require_relative "little_ghost/graph"
 require_relative "little_ghost/assembly_builder"
 require_relative "little_ghost/agent_factory"
 require_relative "little_ghost/runtime/hook"
+require_relative "little_ghost/runtime/hooks/artifacts"
 require_relative "little_ghost/runtime"
 
-# Build AI features with reusable agents and composable assemblies. LittleGhost can
-# sit inside an existing Ruby system or support a dedicated AI service, keeping
-# models, prompts, tools, sessions, streaming, and instrumentation behind a
-# cohesive set of Ruby conventions.
+# Build AI features as ordinary Ruby classes. An Agent owns one model
+# conversation. Larger units called Assemblies coordinate several Agents while
+# keeping the same +ask+ and +stream_ask+ entrypoints.
 #
-# A customer support agent can answer directly, use an application tool, or ask a
-# specialist for research while the caller observes one run:
-#
-#   class ResearchAgent < LittleGhost::Agent
-#     description "Researches difficult support questions"
-#     model "openai:gpt-5.6-luna"
-#   end
+# Start with one model-driven behavior:
 #
 #   class CustomerSupportAgent < LittleGhost::Agent
 #     description "Handles support requests"
-#     model "openai:gpt-5.6-luna"
-#     tools AccountTool
-#     subagent ResearchAgent, kind: "research"
+#     model "openrouter:openai/gpt-5.6-luna"
+#     system_prompt "Answer customer questions clearly."
 #   end
 #
 #   run = CustomerSupportAgent.ask("Why is transfer 481 still pending?")
 #   run.completed? # => true
-#   run.response   # => "Transfer 481 is waiting for the receiving bank."
+#   run.response
+#   # One possible response: Transfer 481 is waiting for the receiving bank.
 #
-# Agent subclasses hold reusable behavior; Invocation objects carry one request,
-# and Run objects own execution and cleanup. Assembly gives Agent, Workflow,
-# Swarm, and Graph the same caller interface while each type owns a different
-# coordination policy.
+# The class holds reusable behavior. Each call creates a Run, which records the
+# result and closes the resources opened for that request. Workflow, Swarm, and
+# Graph are Assembly types for coordinating more than one participant.
 #
-# LittleGhost.configuration is process-wide unless LittleGhost.with_configuration
-# supplies an execution-scoped replacement. Configuration is loaded lazily and
-# snapshotted into a Runtime, so make application changes before the first agent
-# runtime is built.
+# Configure LittleGhost before the first call. The first standalone call builds
+# a shared Runtime from that configuration. +with_configuration+ can select an
+# independent configuration for one execution context.
 module LittleGhost
   class << self
     # The configuration active in the current execution context, falling back to
@@ -114,15 +118,24 @@ module LittleGhost
     # Opens the active Configuration for application setup and returns it.
     #
     # Configuration files are loaded lazily when a runtime is first built, so
-    # make application-level changes before invoking an agent.
+    # make application-level changes before invoking an agent. Once the shared
+    # Runtime is ready, later mutations raise ConfigurationError.
     def configure(&block)
       configuration.configure(&block)
     end
 
+    # Returns the shared Runtime for the active Configuration.
+    #
+    # Most applications do not need to call this method. Standalone Agent and
+    # Assembly entrypoints use it automatically. Runtime construction is lazy,
+    # thread-safe, and locks the active Configuration after it succeeds.
+    def runtime = configuration.runtime
+
     # Returns the model resolver owned by the active process configuration.
     def model_resolver = configuration.model_resolver
 
-    # Makes +configuration+ current only while the block runs.
+    # Makes +configuration+ and its independent shared Runtime current only
+    # while the block runs.
     #
     # Execution state restores the previous configuration even when the block
     # raises. Other execution contexts continue to see their own configuration.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: little_ghost
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Matt Robinson
@@ -23,6 +23,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mini_racer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -117,8 +159,18 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- docs/guides/assemblies.md
+- docs/guides/code_mode.md
 - docs/guides/core_concepts.md
 - docs/guides/getting_started.md
+- docs/guides/integrations.md
+- docs/guides/models_and_providers.md
+- docs/guides/production.md
+- docs/guides/prompt_views.md
+- docs/guides/sandboxing.md
+- docs/guides/skills.md
+- docs/guides/structured_outputs_and_content.md
+- docs/guides/tools.md
 - lib/little_ghost.rb
 - lib/little_ghost/ag_ui.rb
 - lib/little_ghost/ag_ui/adapter.rb
@@ -129,13 +181,36 @@ files:
 - lib/little_ghost/agent/tool_loop.rb
 - lib/little_ghost/agent_builder.rb
 - lib/little_ghost/agent_factory.rb
-- lib/little_ghost/agent_interruptions.rb
+- lib/little_ghost/agent_interjections.rb
+- lib/little_ghost/agent_stream_source.rb
+- lib/little_ghost/artifact.rb
+- lib/little_ghost/artifacts.rb
+- lib/little_ghost/artifacts/presentation_budget.rb
+- lib/little_ghost/artifacts/workspace_store.rb
 - lib/little_ghost/assembly.rb
 - lib/little_ghost/assembly_builder.rb
 - lib/little_ghost/assembly_execution.rb
+- lib/little_ghost/code_mode.rb
+- lib/little_ghost/code_mode/broker.rb
+- lib/little_ghost/code_mode/catalog.rb
+- lib/little_ghost/code_mode/engine.rb
+- lib/little_ghost/code_mode/javascript/catalog.rb
+- lib/little_ghost/code_mode/javascript/client.rb
+- lib/little_ghost/code_mode/javascript/host.rb
+- lib/little_ghost/code_mode/javascript/session.rb
+- lib/little_ghost/code_mode/javascript_engine.rb
+- lib/little_ghost/code_mode/protocol.rb
+- lib/little_ghost/code_mode/ruby/catalog.rb
+- lib/little_ghost/code_mode/ruby/host.rb
+- lib/little_ghost/code_mode/ruby/session.rb
+- lib/little_ghost/code_mode/ruby_engine.rb
+- lib/little_ghost/code_mode/runtime.rb
+- lib/little_ghost/code_mode/session.rb
+- lib/little_ghost/code_mode/types.rb
 - lib/little_ghost/configuration.rb
 - lib/little_ghost/content.rb
 - lib/little_ghost/data/model_catalog.json
+- lib/little_ghost/data_map.rb
 - lib/little_ghost/errors.rb
 - lib/little_ghost/events.rb
 - lib/little_ghost/execution.rb
@@ -146,6 +221,8 @@ files:
 - lib/little_ghost/lookup.rb
 - lib/little_ghost/mcp.rb
 - lib/little_ghost/mcp/client.rb
+- lib/little_ghost/mcp/toolset.rb
+- lib/little_ghost/mcp/types.rb
 - lib/little_ghost/message.rb
 - lib/little_ghost/model.rb
 - lib/little_ghost/model_capabilities.rb
@@ -159,6 +236,12 @@ files:
 - lib/little_ghost/models/configuration.rb
 - lib/little_ghost/models/details.rb
 - lib/little_ghost/models/target.rb
+- lib/little_ghost/network.rb
+- lib/little_ghost/network/authorizer_server.rb
+- lib/little_ghost/network/certificate_authority.rb
+- lib/little_ghost/network/envoy_config.rb
+- lib/little_ghost/network/envoy_gateway.rb
+- lib/little_ghost/network/external_gateway.rb
 - lib/little_ghost/path_set.rb
 - lib/little_ghost/prompt_resolver.rb
 - lib/little_ghost/provider_registry.rb
@@ -184,17 +267,36 @@ files:
 - lib/little_ghost/run_result.rb
 - lib/little_ghost/runtime.rb
 - lib/little_ghost/runtime/hook.rb
+- lib/little_ghost/runtime/hooks/artifacts.rb
 - lib/little_ghost/sandbox.rb
+- lib/little_ghost/sandbox/capabilities.rb
+- lib/little_ghost/sandbox/environment_policy.rb
+- lib/little_ghost/sandbox/filesystem.rb
+- lib/little_ghost/sandbox/isolated_backend.rb
+- lib/little_ghost/sandbox/limits.rb
+- lib/little_ghost/sandbox/mount.rb
+- lib/little_ghost/sandbox/network_policy.rb
+- lib/little_ghost/sandbox/policy.rb
+- lib/little_ghost/sandbox/process_runner.rb
+- lib/little_ghost/sandbox/process_session.rb
+- lib/little_ghost/sandbox/scope.rb
+- lib/little_ghost/sandboxes/bubblewrap.rb
+- lib/little_ghost/sandboxes/native.rb
+- lib/little_ghost/sandboxes/seatbelt.rb
+- lib/little_ghost/sandboxes/unrestricted.rb
 - lib/little_ghost/session.rb
 - lib/little_ghost/session_store.rb
 - lib/little_ghost/session_stores/agent_core_memory.rb
+- lib/little_ghost/session_stores/filesystem.rb
 - lib/little_ghost/session_stores/memory.rb
 - lib/little_ghost/skills.rb
 - lib/little_ghost/skills/catalog.rb
+- lib/little_ghost/skills/resource_root.rb
 - lib/little_ghost/skills/skill.rb
 - lib/little_ghost/stream_event.rb
 - lib/little_ghost/structured_output.rb
 - lib/little_ghost/subagents/agent_path.rb
+- lib/little_ghost/subagents/control_tool.rb
 - lib/little_ghost/subagents/definition.rb
 - lib/little_ghost/subagents/manager.rb
 - lib/little_ghost/support.rb
@@ -218,7 +320,6 @@ files:
 - lib/little_ghost/tools/shell.rb
 - lib/little_ghost/tools/write_todos.rb
 - lib/little_ghost/tracing/open_telemetry.rb
-- lib/little_ghost/unrestricted_sandbox.rb
 - lib/little_ghost/usage.rb
 - lib/little_ghost/version.rb
 - lib/little_ghost/workflow.rb