little_ghost 0.2.1 → 0.4.0

data/lib/little_ghost/session_stores/filesystem.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "securerandom"
+require_relative "../data_map"
+require_relative "../session_store"
+
+module LittleGhost
+  module SessionStores
+    # Filesystem preserves LittleGhost sessions across process restarts in an
+    # application-controlled directory. Use it for durable local development,
+    # a single-host service, or processes that share a suitable filesystem.
+    #
+    #   store = LittleGhost::SessionStores::Filesystem.new(
+    #     root: "/var/lib/customer_support/sessions"
+    #   )
+    #
+    # Configure the resulting store through Configuration#session_store, or
+    # pass it directly when opening a Session. Calls for the same session wait
+    # for one writer, including when separate Ruby processes share the root.
+    #
+    # **Warning:** The root contains readable session data and is not encrypted.
+    # Its complete path must be application-controlled: anyone able to read it
+    # can read session data, and anyone able to replace it can alter sessions.
+    #
+    # Session data is stored as ordinary JSON with canonical String keys. A
+    # value outside that boundary raises ProtocolError without replacing the
+    # previous snapshot. Shared roots require filesystem support for file
+    # locking and atomic rename.
+    class Filesystem < SessionStore
+      FORMAT_VERSION = 1 # :nodoc:
+
+      # Creates a store rooted at +root+ and creates the directory when needed.
+      #
+      # +root+ must be a private, non-symlinked directory. The application owns
+      # the complete path and must not let an untrusted request choose it.
+      # Raises ArgumentError when the root does not meet those requirements.
+      def initialize(root:)
+        super()
+        @root = File.expand_path(String(root))
+        raise ArgumentError, "root must not be empty" if root.to_s.empty?
+
+        FileUtils.mkdir_p(@root, mode: 0o700)
+        validate_root!
+      end
+
+      # Returns the stored snapshot for +id+, or +nil+ before the first write.
+      #
+      # +actor_id+ must match the actor that created an existing session.
+      # Raises Error for an actor mismatch and ProtocolError for an invalid or
+      # unsafe persisted snapshot.
+      def load(id, actor_id: nil)
+        with_lock(id) do
+          snapshot = read_snapshot(id)
+          validate_actor!(snapshot, actor_id) if snapshot
+          snapshot
+        end
+      end
+
+      # Atomically appends sanitized +messages+ and returns the updated snapshot.
+      #
+      # +expected_count+ must match the stored history length. +state+ and
+      # +metadata+ must meet this store's JSON boundary. Raises ProtocolError
+      # when another writer changed the session or the snapshot cannot be read
+      # or written. Raises Error when +actor_id+ does not match the session.
+      def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
+        messages = persistable_messages(messages)
+        state = canonical_map(state)
+        metadata = canonical_map(metadata)
+        with_lock(id) do
+          current = read_snapshot(id)
+          validate_actor!(current, actor_id) if current
+          current ||= empty_snapshot(actor_id)
+          unless current.fetch(:messages).length == expected_count
+            raise ProtocolError, "Session changed while it was being updated"
+          end
+
+          snapshot = {
+            actor_digest: current.fetch(:actor_digest),
+            messages: [*current.fetch(:messages), *messages].freeze,
+            state:,
+            metadata:
+          }.freeze
+          write_snapshot(id, snapshot)
+          public_snapshot(snapshot)
+        end
+      end
+
+      # Atomically replaces the complete persisted snapshot and returns it.
+      #
+      # +state+, +metadata+, and +actor_id+ follow the same requirements as
+      # #append.
+      def replace(id, messages:, state:, metadata:, actor_id: nil)
+        messages = persistable_messages(messages)
+        state = canonical_map(state)
+        metadata = canonical_map(metadata)
+        with_lock(id) do
+          current = read_snapshot(id)
+          validate_actor!(current, actor_id) if current
+          snapshot = {
+            actor_digest: current ? current.fetch(:actor_digest) : actor_digest(actor_id),
+            messages: messages.freeze,
+            state:,
+            metadata:
+          }.freeze
+          write_snapshot(id, snapshot)
+          public_snapshot(snapshot)
+        end
+      end
+
+      private
+
+      def empty_snapshot(actor_id)
+        {
+          actor_digest: actor_digest(actor_id),
+          messages: [].freeze,
+          state: {}.freeze,
+          metadata: {}.freeze
+        }.freeze
+      end
+
+      def public_snapshot(snapshot)
+        snapshot.slice(:messages, :state, :metadata)
+      end
+
+      def validate_actor!(snapshot, actor_id)
+        return if snapshot.fetch(:actor_digest) == actor_digest(actor_id)
+
+        raise Error, "Session actor does not match"
+      end
+
+      def with_lock(id)
+        path = lock_path(id)
+        validate_entry!(path) if File.exist?(path) || File.symlink?(path)
+        File.open(path, File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+          yield
+        ensure
+          lock.flock(File::LOCK_UN)
+        end
+      end
+
+      def read_snapshot(id)
+        path = snapshot_path(id)
+        return unless File.exist?(path) || File.symlink?(path)
+
+        validate_entry!(path)
+
+        document = JSON.parse(File.binread(path))
+        validate_document!(document)
+        snapshot = document.fetch("snapshot")
+        validate_snapshot!(snapshot)
+        {
+          actor_digest: document.fetch("actor_digest"),
+          messages: Array(snapshot.fetch("messages")).map { |message| Message.coerce(message) }.freeze,
+          state: snapshot.fetch("state"),
+          metadata: snapshot.fetch("metadata")
+        }.freeze
+      rescue JSON::ParserError, KeyError, TypeError, ArgumentError, NoMethodError => error
+        raise ProtocolError, "Filesystem session snapshot is invalid: #{error.class}"
+      end
+
+      def write_snapshot(id, snapshot)
+        serialized_snapshot = public_snapshot(snapshot).merge(
+          messages: snapshot.fetch(:messages).map(&:to_h)
+        )
+        document = {
+          "version" => FORMAT_VERSION,
+          "actor_digest" => snapshot.fetch(:actor_digest),
+          "snapshot" => serialized_snapshot
+        }
+        document["digest"] = Digest::SHA256.hexdigest(JSON.generate(document))
+        write_atomically(snapshot_path(id), JSON.generate(document))
+      rescue JSON::GeneratorError, TypeError => error
+        raise ProtocolError, "Filesystem session snapshot could not be serialized: #{error.class}"
+      end
+
+      def validate_document!(document)
+        raise ArgumentError unless document.is_a?(Hash)
+        raise ArgumentError unless document.fetch("version") == FORMAT_VERSION
+        raise ArgumentError unless document.fetch("actor_digest").match?(/\A[0-9a-f]{64}\z/)
+        digest = document.fetch("digest")
+        raise ArgumentError unless digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/)
+
+        expected = document.except("digest")
+        raise ArgumentError unless Digest::SHA256.hexdigest(JSON.generate(expected)) == digest
+      end
+
+      def validate_snapshot!(snapshot)
+        raise ArgumentError unless snapshot.is_a?(Hash)
+        raise ArgumentError unless snapshot.fetch("messages").is_a?(Array)
+        DataMap.new(snapshot.fetch("state"))
+        DataMap.new(snapshot.fetch("metadata"))
+      end
+
+      def canonical_map(value)
+        DataMap.new(value).to_h
+      rescue ArgumentError => error
+        raise ProtocolError, "Filesystem session data is invalid: #{error.message}"
+      end
+
+      def write_atomically(path, content)
+        validate_entry!(path) if File.exist?(path) || File.symlink?(path)
+        temporary = "#{path}.#{Process.pid}.#{SecureRandom.hex(8)}.tmp"
+        File.open(temporary, "wb", 0o600) do |file|
+          file.write(content)
+          file.flush
+          file.fsync
+        end
+        File.rename(temporary, path)
+        sync_root
+      ensure
+        File.delete(temporary) if temporary && File.exist?(temporary)
+      end
+
+      def sync_root
+        File.open(@root, File::RDONLY) { |directory| directory.fsync }
+      rescue SystemCallError
+        nil
+      end
+
+      def validate_root!
+        stat = File.lstat(@root)
+        unless stat.directory? && !stat.symlink? && private_mode?(stat)
+          raise ArgumentError, "root must be a private, non-symlinked directory"
+        end
+      end
+
+      def validate_entry!(path)
+        stat = File.lstat(path)
+        unless stat.file? && !stat.symlink? && private_mode?(stat)
+          raise ProtocolError, "Filesystem session entry is unsafe"
+        end
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def private_mode?(stat)
+        (stat.mode & 0o077).zero?
+      end
+
+      def snapshot_path(id)
+        File.join(@root, "#{session_digest(id)}.json")
+      end
+
+      def lock_path(id)
+        File.join(@root, "#{session_digest(id)}.lock")
+      end
+
+      def session_digest(id)
+        Digest::SHA256.hexdigest("little_ghost/filesystem_session/v1\0#{String(id)}")
+      end
+
+      def actor_digest(actor_id)
+        Digest::SHA256.hexdigest(JSON.generate([actor_id.nil?, actor_id&.to_s]))
+      end
+    end
+  end
+end

data/lib/little_ghost/session_stores/memory.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "../data_map"
+require_relative "../session_store"
+
 module LittleGhost
   # Ready-to-use persistence implementations for LittleGhost conversations.
   module SessionStores
@@ -32,6 +35,8 @@ module LittleGhost
       # stored conversation, then returns the updated snapshot.
       def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
         messages = persistable_messages(messages)
+        state = DataMap.new(state).to_h
+        metadata = DataMap.new(metadata).to_h
         @records_mutex.synchronize do
           key = id.to_s
           record = @records[key]
@@ -56,6 +61,8 @@ module LittleGhost
       # Replaces the complete in-memory snapshot with sanitized +messages+.
       def replace(id, messages:, state:, metadata:, actor_id: nil)
         messages = persistable_messages(messages)
+        state = DataMap.new(state).to_h
+        metadata = DataMap.new(metadata).to_h
         @records_mutex.synchronize do
           key = id.to_s
           validate_actor!(@records[key], actor_id)

data/lib/little_ghost/subagents/manager.rb

@@ -21,11 +21,11 @@ module LittleGhost
     #   end
     #
     # LittleGhost then gives +CustomerSupportAgent+ tools to spawn, message, wait for,
-    # interrupt, and list research agents. The manager keeps each child identity
+    # interject, and list research agents. The manager keeps each child identity
     # stable across follow-up turns.
     #
-    # Follow-up messages are FIFO turns and never interrupt active work.
-    # #interrupt is the separate synchronous path for delivery at the next model
+    # Follow-up messages are FIFO turns and never interject active work.
+    # #interject is the separate synchronous path for delivery at the next model
     # boundary; delivery does not stop the child, and tool calls from that model
     # response continue in the child run.
     #
@@ -58,16 +58,16 @@ module LittleGhost
       CURSOR_MAX_BYTES = 512 # :nodoc:
       UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/ # :nodoc:
 
-      InterruptExchange = Struct.new(:message, :response, :complete) # :nodoc:
+      InterjectionExchange = Struct.new(:message, :response, :complete) # :nodoc:
       Turn = Struct.new( # :nodoc:
         :number,
         :message,
         :completion,
         :operation_id,
         :parent_operation_id,
-        :interrupts,
-        :interruption_metadata,
-        :interruption_ids
+        :interjections,
+        :interjection_metadata,
+        :interjection_ids
       )
       Identity = Struct.new( # :nodoc:
         :subagent_id,
@@ -368,7 +368,7 @@ module LittleGhost
       # model response. The returned +response_disposition+ says whether that
       # response also initiated tool calls; it does not imply the subagent has
       # stopped.
-      def interrupt(subagent_id:, message:, cancellation_token: @cancellation_token, deadline: @deadline)
+      def interject(subagent_id:, message:, cancellation_token: @cancellation_token, deadline: @deadline)
         unless message.is_a?(String)
           raise ToolError, "Subagent messages must be strings."
         end
@@ -376,30 +376,30 @@ module LittleGhost
           raise ToolError, "Subagent messages cannot exceed #{@max_message_chars} characters."
         end
 
-        exchange = InterruptExchange.new(message:, complete: false)
+        exchange = InterjectionExchange.new(message:, complete: false)
         identity, turn = @mutex.synchronize do
           ensure_open!
           value = fetch_identity!(subagent_id)
-          unless value.agent.respond_to?(:interrupt_response)
-            raise ToolError, "Subagent #{subagent_id.inspect} does not support interruptions."
+          unless value.agent.respond_to?(:interject)
+            raise ToolError, "Subagent #{subagent_id.inspect} does not support interjections."
           end
           unless value.status == "running"
             raise ToolError, "Subagent #{subagent_id.inspect} is not currently running."
           end
-          if value.current.interrupts.length >= @max_queued_turns_per_identity
-            raise ToolError, "Subagent #{subagent_id.inspect} has reached its interrupt limit."
+          if value.current.interjections.length >= @max_queued_turns_per_identity
+            raise ToolError, "Subagent #{subagent_id.inspect} has reached its interject limit."
           end
-          interrupt_chars = value.current.interrupts.sum { |pending| pending.message.length }
-          if interrupt_chars + message.length > @max_message_chars
-            raise ToolError, "Subagent interrupt messages cannot exceed #{@max_message_chars} total characters."
+          interjection_chars = value.current.interjections.sum { |pending| pending.message.length }
+          if interjection_chars + message.length > @max_message_chars
+            raise ToolError, "Subagent interjection messages cannot exceed #{@max_message_chars} total characters."
           end
 
-          value.current.interrupts << exchange
+          value.current.interjections << exchange
           [value, value.current]
         end
 
-        interrupt_response = begin
-          identity.agent.interrupt_response(
+        result = begin
+          identity.agent.interject(
             message,
             cancellation_token:,
             deadline:,
@@ -407,16 +407,16 @@ module LittleGhost
           )
         rescue
           @mutex.synchronize do
-            turn.interrupts.delete(exchange)
+            turn.interjections.delete(exchange)
             @condition.broadcast
           end
           raise
         end
-        response = interrupt_response.text
+        response = result.text
         truncated = response.length > @max_response_chars
         returned_response = truncated ? response[0, @max_response_chars] : response
         @mutex.synchronize do
-          used_response_chars = turn.interrupts.sum do |pending|
+          used_response_chars = turn.interjections.sum do |pending|
             pending.equal?(exchange) ? 0 : pending.response.to_s.length
           end
           remaining_response_chars = [@max_response_chars - used_response_chars, 0].max
@@ -428,17 +428,17 @@ module LittleGhost
           snapshot(identity, include_response: true, include_progress: true)
         end
         value = {
-          status: "interruption_delivered",
+          status: "interjection_delivered",
           subagent_id: identity.subagent_id,
           kind: identity.definition.kind,
           subagent:,
           turn: turn.number,
           response: returned_response,
-          response_disposition: interrupt_response.tool_calls? ? "text_with_tool_calls" : "text_only"
+          response_disposition: result.tool_calls? ? "text_with_tool_calls" : "text_only"
         }
         value[:response_truncated] = true if truncated
         value
-      rescue AgentInterruptError => error
+      rescue AgentInterjectionError => error
         raise ToolError, error.message
       end
 
@@ -504,7 +504,7 @@ module LittleGhost
         end
       end
 
-      # Builds spawn, follow-up, interrupt, wait, and list tools bound to this
+      # Builds spawn, follow-up, interject, wait, and list tools bound to this
       # manager. Closing the first tool closes the shared manager.
       def tools
         manager = self
@@ -559,8 +559,8 @@ module LittleGhost
             description: <<~DESCRIPTION.strip,
               Send a follow-up turn to an existing active or persisted subagent identity. Persisted conversations
               are restored transparently before the follow-up. Messages are processed in order after the
-              current turn and never interrupt active work. Do not use this for status, steering, stopping, or
-              finalization; use interrupt_subagent for an active subagent. Mode controls delivery: sync waits for the
+              current turn and never interject active work. Do not use this for status, steering, stopping, or
+              finalization; use interject_subagent for an active subagent. Mode controls delivery: sync waits for the
               later turn's response, while async enqueues the turn and returns immediately.
             DESCRIPTION
             input_schema: {
@@ -586,7 +586,7 @@ module LittleGhost
             )
           end,
           Tool.define(
-            name: "interrupt_subagent",
+            name: "interject_subagent",
             description: <<~DESCRIPTION.strip,
               Interrupt an actively running subagent in its current turn. The message is added at the next model
               boundary. This call waits for that model response and reports its ordinary text, whether the same
@@ -606,7 +606,7 @@ module LittleGhost
             options = {}
             options[:cancellation_token] = context.cancellation_token if context
             options[:deadline] = context.deadline if context&.deadline
-            manager.interrupt(
+            manager.interject(
               subagent_id: input.fetch("subagent_id"),
               message: input.fetch("message"),
               **options
@@ -1089,9 +1089,9 @@ module LittleGhost
             completion: Completion.new,
             operation_id: SecureRandom.uuid,
             parent_operation_id:,
-            interrupts: [],
-            interruption_metadata: context&.interruption_metadata,
-            interruption_ids: context&.interruption_ids || []
+            interjections: [],
+            interjection_metadata: context&.interjection_metadata,
+            interjection_ids: context&.interjection_ids || []
           )
           identity.next_turn += 1
           @turn_count += 1 if count_turn
@@ -1157,8 +1157,8 @@ module LittleGhost
                   options[:history] = identity.history
                   options[:context] = identity.state
                   options[:conversation_id] = identity.conversation_id
-                  options[:interruption_metadata] = turn.interruption_metadata
-                  options[:interruption_ids] = turn.interruption_ids
+                  options[:interjection_metadata] = turn.interjection_metadata
+                  options[:interjection_ids] = turn.interjection_ids
                 end
                 result = if identity.agent.is_a?(Agent)
                   run_agent_turn(identity, turn, options)
@@ -1284,8 +1284,8 @@ module LittleGhost
         response = serialized_response[0, @max_response_chars] if truncated
         persisted_response = response.is_a?(String) ? response : serialized_response
 
-        interrupt_exchanges = @mutex.synchronize do
-          while identity.durable && turn.interrupts.any? { |exchange| !exchange.complete } && !@closed
+        interject_exchanges = @mutex.synchronize do
+          while identity.durable && turn.interjections.any? { |exchange| !exchange.complete } && !@closed
             @condition.wait(@mutex, CANCELLATION_POLL_INTERVAL)
           end
           if @closed
@@ -1294,11 +1294,11 @@ module LittleGhost
           end
 
           identity.status = "persisting" if identity.durable
-          turn.interrupts.select(&:complete).map { |exchange| [exchange.message, exchange.response] }
+          turn.interjections.select(&:complete).map { |exchange| [exchange.message, exchange.response] }
         end
-        return unless interrupt_exchanges
+        return unless interject_exchanges
 
-        retain_agent_conversation(identity, turn, result, persisted_response, interrupt_exchanges)
+        retain_agent_conversation(identity, turn, result, persisted_response, interject_exchanges)
 
         @mutex.synchronize do
           identity.latest_turn = turn.number
@@ -1323,11 +1323,11 @@ module LittleGhost
         end
       end
 
-      def retain_agent_conversation(identity, turn, result, persisted_response, interrupt_exchanges)
+      def retain_agent_conversation(identity, turn, result, persisted_response, interject_exchanges)
         if identity.durable
           state = result.is_a?(RunResult) ? result.state : identity.state
           messages = [Message.new(role: :user, content: turn.message)]
-          interrupt_exchanges.each do |message, response|
+          interject_exchanges.each do |message, response|
             messages << Message.new(role: :user, content: message)
             messages << Message.new(role: :assistant, content: response)
           end

data/lib/little_ghost/support/executor.rb

@@ -31,6 +31,8 @@ module LittleGhost
         items.each_index { |index| queue << index }
         results = Array.new(items.length)
         errors = Array.new(items.length)
+        error_mutex = Mutex.new
+        first_worker_error = nil
         worker_count = [@max_concurrency, items.length].min
         execution_state = ExecutionState.capture
 
@@ -49,6 +51,8 @@ module LittleGhost
                   results[index] = block.call(items[index])
                 rescue => error
                   errors[index] = error
+                  error_mutex.synchronize { first_worker_error ||= error }
+                  cancellation_token.cancel
                 ensure
                   completions << index
                 end
@@ -56,16 +60,24 @@ module LittleGhost
             end
           end
         end
+        callback_error = nil
         begin
           items.length.times do
             index = completions.pop
-            on_result.call(index, results[index]) if on_result && !errors[index]
+            begin
+              on_result.call(index, results[index]) if on_result && !errors[index]
+            rescue => error
+              callback_error = error
+              cancellation_token.cancel
+              break
+            end
           end
         ensure
           workers.each(&:join)
         end
 
-        first_error = errors.compact.find { |error| error.is_a?(CleanupError) } || errors.compact.first
+        raise callback_error if callback_error
+        first_error = errors.compact.find { |error| error.is_a?(CleanupError) } || first_worker_error
         raise first_error if first_error
 
         results

data/lib/little_ghost/support/loader.rb

@@ -5,7 +5,7 @@ require "monitor"
 
 module LittleGhost
   module Support
-    # Loader finds agents and tools from a conventional application layout. Ruby
+    # Loader finds agents, assemblies, and tools from a conventional application layout. Ruby
     # files map to constants by path, so applications can add extension classes
     # without maintaining a manual require list.
     #
@@ -16,7 +16,7 @@ module LittleGhost
     # checked for symbolic-link escapes. Application load roots are trusted code,
     # not a sandbox for untrusted files.
     class Loader
-      DEFAULT_DIRECTORIES = %w[app/agents app/tools].freeze # :nodoc:
+      DEFAULT_DIRECTORIES = %w[app/agents app/assemblies app/tools].freeze # :nodoc:
       PROCESS_LOCK = Monitor.new # :nodoc:
 
       # Application root and configured relative load directories.

data/lib/little_ghost/support.rb

@@ -9,17 +9,29 @@ module LittleGhost
 
     # Recursively duplicates hashes, arrays, and strings while preserving other
     # values. Cyclic containers are not supported.
-    def deep_dup(value)
+    def deep_dup(value, ancestors = {})
+      if value.is_a?(Hash) || value.is_a?(Array) || value.is_a?(Data)
+        identity = value.object_id
+        raise ArgumentError, "cyclic values cannot be duplicated" if ancestors.key?(identity)
+
+        ancestors[identity] = true
+      end
       case value
       when Hash
-        value.each_with_object({}) { |(key, child), copy| copy[deep_dup(key)] = deep_dup(child) }
+        value.each_with_object({}) do |(key, child), copy|
+          copy[deep_dup(key, ancestors)] = deep_dup(child, ancestors)
+        end
       when Array
-        value.map { |child| deep_dup(child) }
+        value.map { |child| deep_dup(child, ancestors) }
       when String
         value.dup
+      when Data
+        value.class.new(**value.to_h.transform_values { |child| deep_dup(child, ancestors) })
       else
         value
       end
+    ensure
+      ancestors.delete(identity) if identity
     end
   end
 end