little_ghost 0.1.0

data/lib/little_ghost/sandbox.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # A Sandbox decides what an agent may do with files and processes. Applications
+  # can place that work on the host, in a container or VM, or behind a remote
+  # execution service without changing their tools.
+  #
+  #   class ContainerSandbox < LittleGhost::Sandbox
+  #     def initialize(workspace:, container:)
+  #       super(workspace:)
+  #       @container = container
+  #     end
+  #
+  #     def read(path, context: nil)
+  #       context&.check!
+  #       @container.read(path)
+  #     end
+  #
+  #     def execute_program(command, timeout:, context: nil, **)
+  #       result = @container.run(
+  #         command, timeout:, cancellation: context&.cancellation_token
+  #       )
+  #       Execution.new(**result)
+  #     end
+  #   end
+  #
+  # Implementations confine paths to #workspace, honor RunContext cancellation,
+  # enforce time and output limits, and return
+  # {Execution}[rdoc-ref:LittleGhost::Sandbox::Execution] from process
+  # operations.
+  class Sandbox
+    # Contains captured process output, exit status, and an optional execution
+    # error.
+    Execution = Data.define(:stdout, :stderr, :exit_code, :error) do # :nodoc:
+      def initialize(stdout:, stderr:, exit_code:, error: nil)
+        super
+      end
+
+      def success?
+        error.nil? && exit_code&.zero?
+      end
+    end
+
+    # Carries captured process output, exit status, and an optional execution
+    # error from Sandbox#execute or Sandbox#execute_program.
+    class Execution < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(stdout:, stderr:, exit_code:, error: nil) -> Execution
+      #
+      # Collects the observable result of one sandbox process.
+
+      ##
+      # :attr_reader: stdout
+      # Captured standard output, subject to the sandbox's output limit.
+
+      ##
+      # :attr_reader: stderr
+      # Captured standard error, subject to the sandbox's output limit.
+
+      ##
+      # :attr_reader: exit_code
+      # The child process exit status, when one is available.
+
+      ##
+      # :attr_reader: error
+      # The execution error, or +nil+ when the process completed normally.
+
+      ##
+      # :method: success?
+      # Indicates that no execution error occurred and the exit code is zero.
+    end
+
+    # Binds the sandbox to +workspace+.
+    def initialize(workspace:)
+      @workspace = workspace
+    end
+
+    # Workspace whose files and processes this sandbox governs.
+    attr_reader :workspace
+
+    # Opens any run-scoped resources and makes the sandbox ready for tools.
+    def open(run: nil)
+      self
+    end
+
+    # Indicates whether filesystem mutation is allowed.
+    def writable? = false
+
+    # Reads UTF-8 text at a workspace-relative +path+.
+    def read(path, context: nil)
+      raise NotImplementedError, "#{self.class} does not support filesystem reads"
+    end
+
+    # Lists entries at a workspace-relative directory +path+.
+    def list(path = ".", context: nil)
+      raise NotImplementedError, "#{self.class} does not support filesystem listings"
+    end
+
+    # Writes +content+ to a workspace-relative +path+.
+    def write(path, content, context: nil)
+      raise NotImplementedError, "#{self.class} does not support filesystem writes"
+    end
+
+    # Replaces one exact +old_text+ occurrence with +new_text+.
+    def replace(path, old_text, new_text, context: nil)
+      raise NotImplementedError, "#{self.class} does not support filesystem edits"
+    end
+
+    # Executes +command+ through +/bin/sh+.
+    #
+    # Prefer #execute_program for model-controlled arguments so shell syntax is
+    # not interpreted.
+    def execute(command, timeout:, context: nil, max_output_bytes: 1_000_000, **options)
+      execute_program(
+        ["/bin/sh", "-c", String(command)],
+        timeout:,
+        context:,
+        max_output_bytes:,
+        **options
+      )
+    end
+
+    # Executes an argument vector without shell interpretation.
+    #
+    # Implementations must enforce +timeout+ and +max_output_bytes+. Environment
+    # inheritance is disabled by default to avoid leaking process credentials.
+    def execute_program(command, timeout:, context: nil, max_output_bytes: 1_000_000, environment: {}, inherit_environment: false)
+      raise NotImplementedError, "#{self.class} does not support program execution"
+    end
+
+    # Releases sandbox resources. Runs close the sandbox before its workspace.
+    def close
+      nil
+    end
+  end
+end

data/lib/little_ghost/session.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Sessions let an agent continue a conversation without tying it to one Ruby
+  # process. Each session keeps messages, application state, and metadata
+  # together behind a SessionStore.
+  #
+  #   session = LittleGhost::Session.new(
+  #     id: "conversation-42",
+  #     actor_id: "user-7",
+  #     store: LittleGhost::SessionStores::Memory.new
+  #   )
+  #   session.append(
+  #     messages: [LittleGhost::Message.new(role: :user, content: "Hello")],
+  #     state: {language: "en"}
+  #   )
+  #
+  #   reopened = LittleGhost::Session.new(
+  #     id: "conversation-42",
+  #     actor_id: "user-7",
+  #     store: session.store
+  #   )
+  #   reopened.history.last.text # => "Hello"
+  #   reopened.state              # => {language: "en"}
+  #
+  # === Persistence and trust
+  #
+  # System messages, transient messages, and private model reasoning are removed
+  # before persistence. Store failures reach the caller; a successful write is
+  # the checkpoint boundary.
+  #
+  # Multi-tenant applications must derive +actor_id+ from stable, authenticated
+  # identity. A nil actor provides no tenant isolation and is appropriate only
+  # for a store that serves one actor.
+  class Session
+    # The store key, explicit actor identity, backing store, and telemetry
+    # operation used by this session.
+    attr_reader :id, :actor_id, :store, :operation_id
+
+    # No store access occurs until the session is read or written.
+    def initialize(id:, store:, actor_id: nil, metadata: {}, operation_id: nil)
+      @id = String(id)
+      @actor_id = actor_id&.to_s
+      @store = store
+      @operation_id = operation_id
+      @metadata = metadata.to_h.freeze
+      @loaded = false
+    end
+
+    # Loads and normalizes the snapshot once. A new session has no snapshot.
+    def load
+      return @snapshot if @loaded
+
+      value = with_store_operation_context { store.load(id, actor_id:) }
+      @snapshot = normalize(value)
+      @loaded = true
+      @snapshot
+    end
+
+    # Uses persisted conversation messages when present and +fallback+ for a new
+    # session.
+    def history(fallback: [])
+      load&.fetch(:messages) || fallback
+    end
+
+    # Exposes a mutable copy of the persisted application state.
+    def state
+      snapshot = load
+      snapshot ? mutable_copy(snapshot.fetch(:state)) : {}
+    end
+
+    # Uses persisted metadata when present and otherwise keeps the metadata from
+    # construction.
+    def metadata
+      load&.fetch(:metadata) || @metadata
+    end
+
+    # Atomically appends +messages+ when the store still has the expected
+    # history length. Prefer #checkpoint when replacing earlier messages is
+    # also valid.
+    def append(messages:, state: self.state, metadata: self.metadata)
+      current = current_snapshot
+      added = persistable_messages(messages)
+      snapshot = build_snapshot(
+        messages: [*current.fetch(:messages), *added],
+        state:,
+        metadata:
+      )
+      with_store_operation_context do
+        store.append(
+          id,
+          messages: added,
+          state: snapshot.fetch(:state),
+          metadata: snapshot.fetch(:metadata),
+          expected_count: current.fetch(:messages).length,
+          actor_id:
+        )
+      end
+      remember(snapshot)
+    end
+
+    # Replaces the complete persisted snapshot.
+    def replace(messages:, state: self.state, metadata: self.metadata)
+      snapshot = build_snapshot(messages:, state:, metadata:)
+      with_store_operation_context { store.replace(id, actor_id:, **snapshot) }
+      remember(snapshot)
+    end
+
+    # Persists one conversation checkpoint. History is appended when the stored
+    # messages are an unchanged prefix and replaced otherwise.
+    def checkpoint(messages:, state: self.state, metadata: self.metadata, parent_operation_id: @operation_id)
+      with_store_operation_context(parent_operation_id) do
+        snapshot = build_snapshot(messages:, state:, metadata:)
+        current = current_snapshot
+        if message_prefix?(current.fetch(:messages), snapshot.fetch(:messages))
+          added = snapshot.fetch(:messages).drop(current.fetch(:messages).length)
+          unless added.empty? && same_session_data?(current, snapshot)
+            store.append(
+              id,
+              messages: added,
+              state: snapshot.fetch(:state),
+              metadata: snapshot.fetch(:metadata),
+              expected_count: current.fetch(:messages).length,
+              actor_id:
+            )
+          end
+        else
+          store.replace(id, actor_id:, **snapshot)
+        end
+        remember(snapshot)
+      end
+    end
+
+    # Checkpoints the messages and state from a completed run result.
+    def checkpoint_result(result)
+      checkpoint(messages: result.messages, state: result.state)
+    end
+
+    # Serializes work for this session and actor through the backing store.
+    def synchronize(&block)
+      store.synchronize(id, actor_id:, &block)
+    end
+
+    # Publishes a conversational view without changing the session's stored
+    # transcript. Unlike session persistence, projection does not automatically
+    # remove system or transient messages; callers must omit any message whose
+    # visible text should stay local. Stores that do not support projections
+    # return nil.
+    def project_conversation(messages:, metadata: self.metadata)
+      with_store_operation_context do
+        store.project_conversation(id, messages:, metadata:, actor_id:)
+      end
+    end
+
+    private
+
+    def current_snapshot
+      load || build_snapshot(messages: [], state: {}, metadata: @metadata)
+    end
+
+    def with_store_operation_context(operation_id = @operation_id)
+      store.with_operation_context(operation_id) { yield }
+    end
+
+    def build_snapshot(messages:, state:, metadata:)
+      {
+        messages: persistable_messages(messages),
+        state: Support.deep_dup(state.to_h),
+        metadata: Support.deep_dup(metadata.to_h)
+      }.freeze
+    end
+
+    def remember(snapshot)
+      @snapshot = snapshot
+      @loaded = true
+      snapshot
+    end
+
+    def message_prefix?(current, candidate)
+      return false if current.length > candidate.length
+
+      current.each_with_index.all? do |message, index|
+        message.to_h == candidate.fetch(index).to_h
+      end
+    end
+
+    def same_session_data?(left, right)
+      left.fetch(:state) == right.fetch(:state) && left.fetch(:metadata) == right.fetch(:metadata)
+    end
+
+    def normalize(value)
+      return unless value
+
+      {
+        messages: persistable_messages(Array(value.fetch(:messages))),
+        state: Support.deep_dup(value.fetch(:state, {}).to_h),
+        metadata: Support.deep_dup(value.fetch(:metadata, {}).to_h)
+      }.freeze
+    rescue KeyError, NoMethodError, TypeError => error
+      raise ProtocolError, "Session store returned an invalid value: #{error.class}"
+    end
+
+    def persistable_messages(messages)
+      messages.filter_map do |value|
+        message = Message.coerce(value)
+        next if message.role == :system
+        next if message.metadata[:transient] || message.metadata["transient"]
+
+        sanitized = message.without_reasoning
+        next if sanitized.content.empty? && !message.content.empty?
+
+        sanitized
+      end.freeze
+    end
+
+    def mutable_copy(value)
+      case value
+      when Hash
+        value.to_h { |key, child| [mutable_copy(key), mutable_copy(child)] }
+      when Array
+        value.map { |child| mutable_copy(child) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+  end
+end

data/lib/little_ghost/session_store.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # SessionStore connects LittleGhost conversations to application
+  # persistence. Subclass it to keep sessions in a database, remote service, or
+  # other durable store.
+  #
+  #   class DatabaseSessionStore < LittleGhost::SessionStore
+  #     def load(id, actor_id: nil)
+  #       Conversation.find_by(external_id: id, actor_id:)&.snapshot
+  #     end
+  #
+  #     def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
+  #       Conversation.append!(
+  #         id, messages:, state:, metadata:, expected_count:, actor_id:
+  #       )
+  #     end
+  #
+  #     def replace(id, messages:, state:, metadata:, actor_id: nil)
+  #       Conversation.replace!(id, messages:, state:, metadata:, actor_id:)
+  #     end
+  #   end
+  #
+  # A snapshot contains +:messages+, +:state+, and +:metadata+. Implementations
+  # provide #load, #append, and #replace; #append must check +expected_count+
+  # atomically so two writers cannot silently lose a turn.
+  #
+  # Actor identity always comes from the caller. A store must not infer it from
+  # ambient process state.
+  class SessionStore
+    # Prepares the per-session synchronization used by #synchronize.
+    def initialize
+      @session_locks = {}
+      @session_locks_mutex = Mutex.new
+    end
+
+    # Finds the snapshot for +id+, or returns nil when it does not exist.
+    def load(_id, actor_id: nil)
+      raise NotImplementedError
+    end
+
+    # Atomically appends sanitized messages and stores state and metadata.
+    # Implementations raise ProtocolError if the persisted message count differs
+    # from +expected_count+.
+    def append(_id, messages:, state:, metadata:, expected_count:, actor_id: nil)
+      raise NotImplementedError
+    end
+
+    # Replaces the complete snapshot for +id+ atomically.
+    def replace(_id, messages:, state:, metadata:, actor_id: nil)
+      raise NotImplementedError
+    end
+
+    # Stores may expose a clean conversational view without changing the stored
+    # session transcript. The default implementation is a no-op.
+    def project_conversation(_id, messages:, metadata:, actor_id: nil)
+      nil
+    end
+
+    # Wraps a store operation with an optional telemetry parent operation.
+    # Custom stores may override this while preserving the block's return value.
+    def with_operation_context(_operation_id)
+      yield
+    end
+
+    # Serializes work for one actor/session key within this store instance.
+    def synchronize(id, actor_id: nil)
+      key = [actor_id&.to_s, id.to_s].freeze
+      entry = @session_locks_mutex.synchronize do
+        current = (@session_locks[key] ||= [Mutex.new, 0])
+        current[1] += 1
+        current
+      end
+      entry.first.synchronize { yield }
+    ensure
+      if entry
+        @session_locks_mutex.synchronize do
+          entry[1] -= 1
+          @session_locks.delete(key) if entry[1].zero?
+        end
+      end
+    end
+
+    protected
+
+    def persistable_messages(messages)
+      messages.filter_map do |value|
+        message = Message.coerce(value)
+        sanitized = message.without_reasoning
+        next if sanitized.content.empty? && !message.content.empty?
+
+        sanitized
+      end.freeze
+    end
+  end
+end