little_ghost 0.1.0

data/lib/little_ghost/agent_builder.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  class AgentBuilder # :nodoc: all
+    class ActivityRelay
+      def initialize
+        @mutex = Mutex.new
+        @observers = []
+      end
+
+      def subscribe(&observer)
+        @mutex.synchronize { @observers << observer }
+      end
+
+      def publish
+        @mutex.synchronize { @observers.dup }.each(&:call)
+      end
+    end
+
+    def initialize(runtime:, prompt_paths:, resolve_agent:)
+      @runtime = runtime
+      @prompt_paths = prompt_paths
+      @resolve_agent = resolve_agent
+    end
+
+    def build(
+      agent_class_or_name,
+      run:,
+      model: nil,
+      tools: [],
+      conversation_id: nil,
+      agent_path: Subagents::AgentPath::ROOT
+    )
+      agent_class = @resolve_agent.call(agent_class_or_name)
+      build_agent(agent_class, run:, model:, tools:, conversation_id:, agent_path:)
+    end
+
+    private
+
+    attr_reader :runtime, :prompt_paths
+
+    def instantiate(agent_class, run:, tools:, model:, delegation_activity:, agent_path:)
+      agent_class.new(
+        model:,
+        runtime:,
+        tools:,
+        template_paths: prompt_paths,
+        run:,
+        workspace: run.workspace,
+        sandbox: run.sandbox,
+        delegation_activity:,
+        agent_path:,
+        **agent_class.limits
+      )
+    end
+
+    def build_agent(
+      agent_class,
+      run:,
+      model:,
+      tools:,
+      conversation_id: nil,
+      agent_path: Subagents::AgentPath::ROOT
+    )
+      delegation_activity = ActivityRelay.new
+      configured_tools = Array(tools).dup
+      configured_tools.concat(
+        delegation_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:)
+      )
+      resolved_model = model || runtime.model_for(agent_class, run)
+      transferred = true
+      instantiate(
+        agent_class,
+        run:,
+        model: resolved_model,
+        tools: configured_tools,
+        delegation_activity:,
+        agent_path:
+      )
+    rescue
+      close_tools(configured_tools) unless transferred
+      raise
+    end
+
+    def delegation_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:)
+      tools = agent_tools(agent_class, run)
+      tools.concat(subagent_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:))
+    rescue
+      close_tools(tools)
+      raise
+    end
+
+    def agent_tools(agent_class, run)
+      tools = []
+      agent_class.agent_tool_declarations.each do |declaration|
+        child = declared_agent(declaration, run)
+        begin
+          tools << child.as_tool(
+            name: declaration.fetch(:name),
+            description: declaration.fetch(:description),
+            preserve_context: declaration.fetch(:preserve_context)
+          )
+        rescue
+          child.close
+          raise
+        end
+      end
+      tools
+    rescue
+      close_tools(tools)
+      raise
+    end
+
+    def subagent_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:)
+      definitions = agent_class.subagent_declarations.map do |declaration|
+        Subagents::Definition.new(
+          kind: declaration.fetch(:kind),
+          description: declaration.fetch(:description),
+          persist: declaration.fetch(:persist, true),
+          accepts_conversation_id: true,
+          factory: lambda do |subagent_id, child_conversation_id = nil|
+            factory = declaration[:factory]
+            if factory
+              invoke_factory(factory, subagent_id, run)
+            else
+              declared_agent(
+                declaration,
+                run,
+                conversation_id: child_conversation_id,
+                agent_path: subagent_id
+              )
+            end
+          end
+        )
+      end
+      declared_kinds = definitions.map(&:kind)
+      agent_class.subagent_resolvers.each do |resolver|
+        resolved = Array(resolver.call(run))
+        unless resolved.all? { |definition| definition.is_a?(Subagents::Definition) }
+          raise ConfigurationError, "Subagent resolvers must return LittleGhost::Subagents::Definition objects"
+        end
+        definitions.concat(resolved.reject { |definition| declared_kinds.include?(definition.kind) })
+      end
+      return [] if definitions.empty?
+
+      Subagents::Manager.new(
+        definitions,
+        runtime:,
+        wait_timeout: agent_class.subagent_long_poll_duration,
+        parent_session: conversation_id ? runtime.open_subagent_session(run, conversation_id) : run.session,
+        cancellation_token: run.cancellation_token,
+        deadline: run.invocation.deadline_at,
+        parent_agent_path: agent_path,
+        observer: lambda do |event|
+          delegation_activity.publish
+          run.publish(:subagent, event:)
+        end
+      ).tools
+    end
+
+    def declared_agent(declaration, run, conversation_id: nil, agent_path: Subagents::AgentPath::ROOT)
+      agent_class = @resolve_agent.call(declaration.fetch(:agent))
+      build_agent(
+        agent_class, run:,
+        model: resolve(declaration[:model], run),
+        tools: Array(resolve(declaration[:tools], run)),
+        conversation_id:,
+        agent_path:
+      )
+    end
+
+    def close_tools(tools)
+      Array(tools).reverse_each do |tool|
+        tool.close if tool.is_a?(Tool) && tool.respond_to?(:close)
+      rescue
+        nil
+      end
+    end
+
+    def resolve(value, run)
+      value.is_a?(Proc) ? value.call(run) : value
+    end
+
+    def invoke_factory(factory, *arguments)
+      accepts_runtime = factory.parameters.any? do |kind, name|
+        %i[key keyreq keyrest].include?(kind) && (name == :runtime || kind == :keyrest)
+      end
+      accepts_runtime ? factory.call(*arguments, runtime: @runtime) : factory.call(*arguments)
+    end
+  end
+end

data/lib/little_ghost/agent_interruptions.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module LittleGhost
+  class AgentInterruptions # :nodoc: all
+    MAX_BATCH_SIZE = 100
+    MAX_INTERRUPTION_COUNT = 1_000
+
+    Response = Data.define(:text, :tool_calls, :interruption_ids, :batch_key) do
+      def initialize(text:, tool_calls:, interruption_ids: [], batch_key: nil)
+        super(
+          text: String(text),
+          tool_calls: !!tool_calls,
+          interruption_ids: Array(interruption_ids).map { |id| String(id).dup.freeze }.freeze,
+          batch_key: batch_key.nil? ? nil : String(batch_key).dup.freeze
+        )
+      end
+
+      def tool_calls? = tool_calls
+    end
+
+    Batch = Data.define(:tickets) do
+      def interruption_ids = tickets.map(&:id)
+      def batch_key = tickets.first&.batch_key
+      def metadata = tickets.last&.metadata
+    end
+
+    class Ticket
+      attr_reader :id, :message, :batch_key, :metadata
+
+      def initialize(message, id:, batch_key:, metadata:)
+        @id = id
+        @message = message
+        @batch_key = batch_key
+        @metadata = metadata
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @resolved = false
+      end
+
+      def resolve(value)
+        @mutex.synchronize do
+          return if @resolved
+
+          @value = value
+          @resolved = true
+          @condition.broadcast
+        end
+      end
+
+      def reject(error)
+        @mutex.synchronize do
+          return if @resolved
+
+          @error = error
+          @resolved = true
+          @condition.broadcast
+        end
+      end
+
+      def value(cancellation_token:, deadline:)
+        @mutex.synchronize do
+          until @resolved
+            cancellation_token.raise_if_cancelled!
+            raise DeadlineExceededError, "The run deadline was reached" if deadline && Time.now >= deadline
+
+            timeout = deadline ? [deadline - Time.now, 0.05].min : 0.05
+            @condition.wait(@mutex, [timeout, 0].max)
+          end
+          cancellation_token.raise_if_cancelled!
+          raise DeadlineExceededError, "The run deadline was reached" if deadline && Time.now >= deadline
+          raise @error if @error
+
+          @value
+        end
+      end
+    end
+
+    attr_reader :operation_id, :target_operation_id
+
+    def initialize
+      @mutex = Mutex.new
+      @queue = []
+      @tickets_by_id = {}
+      @waiters = Hash.new(0)
+      @delivered = nil
+      @closed_error = nil
+      @operation_id = nil
+      @target_operation_id = nil
+    end
+
+    def bind(operation_id, target_operation_id:)
+      @mutex.synchronize do
+        @operation_id = operation_id
+        @target_operation_id = target_operation_id || operation_id
+      end
+    end
+
+    def enqueue(message, id: SecureRandom.uuid, batch_key: nil, metadata: {})
+      id = String(id)
+      raise ArgumentError, "interruption_id cannot be empty" if id.empty?
+
+      batch_key = String(batch_key) unless batch_key.nil?
+      metadata = metadata.to_h
+      @mutex.synchronize do
+        raise @closed_error if @closed_error
+
+        existing = @tickets_by_id[id]
+        if existing
+          unless existing.message.to_h == message.to_h &&
+              existing.batch_key == batch_key &&
+              existing.metadata == metadata
+            raise ArgumentError, "interruption_id has already been used with different input"
+          end
+
+          @waiters[existing] += 1
+          return existing
+        end
+        if @tickets_by_id.length >= MAX_INTERRUPTION_COUNT
+          raise AgentInterruptError, "Agent interruption capacity reached"
+        end
+
+        ticket = Ticket.new(message, id: id.freeze, batch_key: batch_key&.freeze, metadata:)
+        @tickets_by_id[id] = ticket
+        @waiters[ticket] = 1
+        @queue << ticket
+        ticket
+      end
+    rescue TypeError, NoMethodError
+      raise ArgumentError, "interruption_id, batch_key, and metadata are invalid"
+    end
+
+    def deliver
+      @mutex.synchronize do
+        return if @delivered || @queue.empty?
+
+        batch_key = @queue.first.batch_key
+        tickets = []
+        tickets << @queue.shift
+        if batch_key
+          while tickets.length < MAX_BATCH_SIZE && @queue.first&.batch_key == batch_key
+            tickets << @queue.shift
+          end
+        end
+        @delivered = Batch.new(tickets: tickets.freeze)
+      end
+    end
+
+    def resolve(batch, response)
+      tickets = @mutex.synchronize do
+        return unless batch && @delivered.equal?(batch)
+
+        @delivered = nil
+        batch.tickets
+      end
+      tickets.each { |ticket| ticket.resolve(response) }
+    end
+
+    def pending?
+      @mutex.synchronize { !@queue.empty? }
+    end
+
+    def finish
+      @mutex.synchronize do
+        return true if @closed_error
+        return false if @delivered || !@queue.empty?
+
+        @closed_error = AgentInterruptError.new("Agent is not currently running")
+        true
+      end
+    end
+
+    def release(ticket, withdraw: false)
+      @mutex.synchronize do
+        @waiters[ticket] -= 1
+        return unless withdraw && @waiters[ticket] <= 0 && @queue.delete(ticket)
+
+        @tickets_by_id.delete(ticket.id)
+        @waiters.delete(ticket)
+      end
+    end
+
+    def close(error)
+      tickets = @mutex.synchronize do
+        return if @closed_error
+
+        @closed_error = error
+        values = [*@delivered&.tickets, *@queue].compact
+        @delivered = nil
+        @queue.clear
+        values
+      end
+      tickets.each { |ticket| ticket.reject(error) }
+    end
+  end
+end