conductor_ruby 0.1.0 → 0.1.1

data/lib/conductor/agents/runtime/sse_client.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'logger'
+require_relative '../errors'
+
+module Conductor
+  module Agents
+    # Server-sent events from GET /api/agent/stream/{executionId}.
+    #
+    # Uses a plain Net::HTTP streaming request (the shared Faraday RestClient buffers
+    # bodies, retries, and has a 120 s total timeout, none of which suit a long-lived
+    # stream). Auth headers come from the ApiClient so token refresh stays in one place.
+    #
+    # Wire format (see AgentStreamRegistry on the server): ":connected" first, then
+    # "id:<n>\nevent:<type>\ndata:<json>\n\n" frames, a ":heartbeat" comment every 15 s, the
+    # stream closes after "done" or "error". Last-Event-ID (a bare integer) resumes; without
+    # it the server replays from the start, so connecting after start loses nothing.
+    class SseClient
+      HEARTBEAT_ONLY_TIMEOUT = 15
+      RECONNECT_DELAY = 1
+      TERMINAL_EVENTS = %w[done error].freeze
+      READ_TIMEOUT = 60
+      OPEN_TIMEOUT = 5
+
+      # Incremental parser for the SSE wire format
+      class Parser
+        def initialize
+          @buffer = +''
+          @event = nil
+          @id = nil
+          @data = []
+        end
+
+        # Feed a chunk; yields each complete event as { 'event', 'id', 'data' } or { 'heartbeat' => true }
+        def feed(chunk, &block)
+          @buffer << chunk
+          while (idx = @buffer.index("\n"))
+            line = @buffer.slice!(0..idx).chomp
+            process_line(line, &block)
+          end
+        end
+
+        private
+
+        def process_line(line, &block)
+          if line.start_with?(':')
+            yield({ 'heartbeat' => true })
+          elsif line.empty?
+            flush(&block)
+          elsif (m = line.match(/\A(\w+):\s?(.*)\z/m))
+            field = m[1]
+            value = m[2]
+            case field
+            when 'event' then @event = value
+            when 'id' then @id = value
+            when 'data' then @data << value
+            end
+          end
+        end
+
+        def flush
+          return if @data.empty? && @event.nil?
+
+          raw = @data.join("\n")
+          data = begin
+            raw.empty? ? {} : JSON.parse(raw)
+          rescue JSON::ParserError
+            { 'content' => raw }
+          end
+          data = { 'content' => data } unless data.is_a?(Hash)
+          id = @id.to_s =~ /\A\d+\z/ ? @id.to_i : @id
+          yield({ 'event' => @event || data['type'], 'id' => id, 'data' => data })
+        ensure
+          @event = nil
+          @id = nil
+          @data = []
+        end
+      end
+
+      # @param api_client [Http::ApiClient] supplies base URL, TLS settings and auth headers
+      def initialize(api_client, logger: nil)
+        @api_client = api_client
+        @configuration = api_client.configuration
+        @logger = logger || Logger.new($stdout, level: Logger::INFO)
+      end
+
+      # Yield every real event for +execution_id+ until done/error, reconnecting on drops.
+      # @param last_event_id [Integer, nil] resume point
+      # @raise [SseUnavailableError] when the first connection fails or only heartbeats arrive
+      def each_event(execution_id, last_event_id: nil)
+        return enum_for(:each_event, execution_id, last_event_id: last_event_id) unless block_given?
+
+        first_connect = true
+        got_real_event = false
+
+        loop do
+          begin
+            finished = connect(execution_id, last_event_id) do |event|
+              if event['heartbeat']
+                next unless !got_real_event && Time.now - @connected_at > HEARTBEAT_ONLY_TIMEOUT
+
+                raise SseUnavailableError, "SSE connected but only heartbeats arrived for #{HEARTBEAT_ONLY_TIMEOUT}s"
+              end
+              first_connect = false
+              got_real_event = true
+              last_event_id = event['id'] if event['id'].is_a?(Integer)
+              yield event
+              return if TERMINAL_EVENTS.include?(event['event'].to_s)
+            end
+            first_connect = false
+            return if finished
+          rescue SseUnavailableError
+            raise
+          rescue StandardError => e
+            raise SseUnavailableError, "SSE unavailable: #{e.class}: #{e.message}" if first_connect
+
+            @logger.warn("SSE connection lost (#{e.class}: #{e.message}), reconnecting in #{RECONNECT_DELAY}s")
+          end
+          sleep RECONNECT_DELAY
+        end
+      end
+
+      private
+
+      # Open one streaming request. Returns true when a terminal event was seen, false on EOF.
+      def connect(execution_id, last_event_id)
+        uri = URI.parse("#{@configuration.server_url}/agent/stream/#{execution_id}")
+        request = Net::HTTP::Get.new(uri)
+        request['Accept'] = 'text/event-stream'
+        request['Cache-Control'] = 'no-cache'
+        request['Last-Event-ID'] = last_event_id.to_s if last_event_id
+        auth_headers.each { |k, v| request[k] = v }
+
+        parser = Parser.new
+        terminal = false
+        Net::HTTP.start(uri.host, uri.port, **http_options(uri)) do |http|
+          http.request(request) do |response|
+            raise SseUnavailableError, "SSE endpoint returned HTTP #{response.code}" unless response.code.to_i == 200
+
+            @connected_at = Time.now
+            response.read_body do |chunk|
+              parser.feed(chunk) do |event|
+                yield event
+                terminal = true if TERMINAL_EVENTS.include?(event['event'].to_s)
+              end
+              break if terminal
+            end
+          end
+        end
+        terminal
+      end
+
+      def auth_headers
+        return {} unless @configuration.auth_configured?
+
+        @api_client.get_authentication_headers || {}
+      rescue StandardError => e
+        @logger.warn("Could not attach auth headers to SSE request: #{e.message}")
+        {}
+      end
+
+      def http_options(uri)
+        opts = { use_ssl: uri.scheme == 'https', read_timeout: READ_TIMEOUT, open_timeout: OPEN_TIMEOUT }
+        if opts[:use_ssl]
+          opts[:verify_mode] = @configuration.verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+          opts[:ca_file] = @configuration.ssl_ca_cert if @configuration.ssl_ca_cert
+        end
+        opts
+      end
+    end
+  end
+end

data/lib/conductor/agents/runtime/status_poller.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Conductor
+  module Agents
+    # Polling fallback for servers without SSE: turns GET /agent/{id}/status into the
+    # same event hashes the SseClient yields (waiting, done, error). No partial text.
+    class StatusPoller
+      def initialize(client, interval: 0.5, logger: nil)
+        @client = client
+        @interval = interval
+        @logger = logger
+      end
+
+      def each_event(execution_id)
+        return enum_for(:each_event, execution_id) unless block_given?
+
+        was_waiting = false
+        loop do
+          status = @client.get_status(execution_id)
+          if status['isComplete']
+            yield terminal_event(status)
+            return
+          end
+
+          if status['isWaiting'] && !was_waiting
+            yield({ 'event' => 'waiting', 'id' => nil, 'data' => { 'type' => 'waiting', 'executionId' => execution_id,
+                                                                   'pendingTool' => status['pendingTool'] || {} } })
+          end
+          was_waiting = status['isWaiting'] ? true : false
+          sleep(was_waiting ? [@interval * 4, 2.0].min : @interval)
+        end
+      end
+
+      private
+
+      def terminal_event(status)
+        if status['status'].to_s == 'COMPLETED'
+          { 'event' => 'done', 'id' => nil,
+            'data' => { 'type' => 'done', 'executionId' => status['executionId'], 'output' => status['output'] || {} } }
+        else
+          { 'event' => 'error', 'id' => nil,
+            'data' => { 'type' => 'error', 'executionId' => status['executionId'], 'status' => status['status'],
+                        'content' => status['reasonForIncompletion'] || "execution #{status['status']}",
+                        'output' => status['output'] } }
+        end
+      end
+    end
+  end
+end

data/lib/conductor/agents/runtime/system_workers.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../errors'
+
+module Conductor
+  module Agents
+    # Bodies for the compiler-generated SIMPLE tasks the server asks the SDK to serve
+    # (they appear in requiredWorkers next to the user's tools). Ports of the Python
+    # SDK's TerminationEntry, GuardrailEntry, CallbackEntry and OnCondition handoff workers.
+    module SystemWorkers
+      module_function
+
+      # <agent>_termination: { should_continue, reason }
+      def termination(condition, logger: nil)
+        lambda do |task|
+          input = stringify(task.input_data)
+          context = { 'result' => input['result'].to_s, 'messages' => input['messages'] || [],
+                      'iteration' => input['iteration'].to_i, 'token_usage' => input['token_usage'] }
+          begin
+            outcome = condition.should_terminate(context)
+            { 'should_continue' => !outcome.should_terminate, 'reason' => outcome.reason.to_s }
+          rescue StandardError => e
+            logger&.error("termination condition failed: #{e.class}: #{e.message}")
+            { 'should_continue' => true, 'reason' => '' }
+          end
+        end
+      end
+
+      # <guardrail name>: { passed, message, on_fail, fixed_output, guardrail_name, should_continue }
+      def guardrail(guardrail, logger: nil)
+        lambda do |task|
+          input = stringify(task.input_data)
+          content = stringify_content(input['content'])
+          iteration = input['iteration'].to_i
+          begin
+            result = guardrail.check(content)
+            return pass_result if result.passed?
+
+            on_fail = guardrail.on_fail
+            fixed = result.fixed_output
+            on_fail = 'raise' if on_fail == 'retry' && iteration >= guardrail.max_retries
+            on_fail = 'raise' if on_fail == 'fix' && fixed.nil?
+            { 'passed' => false, 'message' => result.message.to_s, 'on_fail' => on_fail, 'fixed_output' => fixed,
+              'guardrail_name' => guardrail.name, 'should_continue' => on_fail == 'retry' }
+          rescue StandardError => e
+            logger&.error("guardrail #{guardrail.name} raised: #{e.class}: #{e.message}")
+            on_fail = guardrail.on_fail
+            on_fail = 'raise' if on_fail == 'retry' && iteration >= guardrail.max_retries
+            { 'passed' => false, 'message' => "Guardrail error: #{e.message}", 'on_fail' => on_fail, 'fixed_output' => nil,
+              'guardrail_name' => guardrail.name, 'should_continue' => on_fail == 'retry' }
+          end
+        end
+      end
+
+      # <agent>_<position>: the callback chain's Hash (or {})
+      def callback(chain, logger: nil)
+        lambda do |task|
+          input = stringify(task.input_data)
+          kwargs = {}
+          kwargs[:messages] = input['messages'] if input.key?('messages')
+          kwargs[:llm_result] = input['llm_result'] if input.key?('llm_result')
+          begin
+            result = chain.call(**kwargs)
+            result.is_a?(Hash) ? result : {}
+          rescue StandardError => e
+            logger&.error("callback failed: #{e.class}: #{e.message}")
+            {}
+          end
+        end
+      end
+
+      # <agent>_handoff_<target>: { handoff, target }
+      def handoff(condition, logger: nil)
+        lambda do |task|
+          input = stringify(task.input_data)
+          begin
+            { 'handoff' => condition.should_handoff(input) ? true : false, 'target' => condition.target }
+          rescue StandardError => e
+            logger&.error("handoff condition failed: #{e.class}: #{e.message}")
+            { 'handoff' => false, 'target' => condition.target }
+          end
+        end
+      end
+
+      def pass_result
+        { 'passed' => true, 'message' => '', 'on_fail' => 'pass', 'fixed_output' => nil, 'guardrail_name' => '',
+          'should_continue' => false }
+      end
+
+      # Function-based routers return the selected sub-agent's name.
+      def router(callable, agent_names, logger: nil)
+        lambda do |task|
+          { 'selected_agent' => callable.call(stringify(task.input_data).fetch('prompt', '')).to_s }
+        rescue StandardError => e
+          logger&.error("router failed: #{e.class}: #{e.message}")
+          { 'selected_agent' => agent_names.first || '' }
+        end
+      end
+
+      def stringify(input)
+        (input || {}).transform_keys(&:to_s)
+      end
+
+      def stringify_content(content)
+        return '' if content.nil?
+        return content if content.is_a?(String)
+
+        JSON.generate(content)
+      rescue StandardError
+        content.to_s
+      end
+    end
+  end
+end

data/lib/conductor/agents/runtime/tool_call.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Conductor
+  module Agents
+    # A tool call observed on the stream or awaiting approval
+    ToolCall = Struct.new(:name, :arguments, :result, keyword_init: true) do
+      def to_s
+        "#<ToolCall #{name} #{(arguments || {}).map { |k, v| "#{k}: #{v.inspect}" }.join(' ')}>"
+      end
+      alias_method :inspect, :to_s
+    end
+  end
+end

data/lib/conductor/agents/runtime/tool_registry.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative '../errors'
+require_relative 'dispatch'
+require_relative 'system_workers'
+require_relative '../../worker/worker'
+require_relative '../../http/models/task_def'
+
+module Conductor
+  module Agents
+    # Turns an agent tree into the Conductor workers this process must run: one per
+    # local tool (worker/cli tools with a func) and one per compiler-generated system task
+    # the server listed in requiredWorkers.
+    class ToolRegistry
+      SYSTEM_SUFFIX_TERMINATION = '_termination'
+
+      attr_reader :logger
+
+      def initialize(agent_config, logger: nil)
+        @agent_config = agent_config
+        @logger = logger
+      end
+
+      # @param agent [Agent] root agent
+      # @param required_workers [Array<String>, nil] from the start/deploy response (nil = register everything)
+      # @param domain [String, nil] task domain for stateful runs (the runId)
+      # @return [Array<Worker::Worker>]
+      def workers_for(agent, required_workers: nil, domain: nil)
+        required = required_workers.nil? ? nil : Set.new(required_workers.map(&:to_s))
+        workers = tool_workers(agent, domain: domain)
+        workers += system_workers(agent, required, domain: domain)
+        warn_unhandled(required, workers)
+        workers
+      end
+
+      # Workers for every local tool in the tree (deduplicated by name)
+      def tool_workers(agent, domain: nil)
+        seen = {}
+        each_agent_with_credentials(agent) do |a, credentials|
+          a.tools.each do |tool_def|
+            next unless tool_def.local?
+
+            if seen.key?(tool_def.name)
+              template = seen[tool_def.name].task_def_template
+              template.runtime_metadata = (template.runtime_metadata + credentials + tool_def.credentials).uniq
+              next
+            end
+
+            seen[tool_def.name] = build_tool_worker(tool_def, credentials: credentials, domain: domain)
+          end
+        end
+        seen.values
+      end
+
+      # Workers for compiler-generated tasks: termination, custom guardrails, callbacks, on_condition handoffs
+      def system_workers(agent, required, domain: nil)
+        workers = []
+        agent.all_agents.each do |a|
+          if a.termination
+            name = "#{a.name}#{SYSTEM_SUFFIX_TERMINATION}"
+            workers << build_system_worker(name, SystemWorkers.termination(a.termination, logger: @logger), domain, a) if wanted?(required, name)
+          end
+          (a.guardrails + a.tools.flat_map(&:guardrails)).each do |g|
+            next if g.external? || g.is_a?(RegexGuardrail) || g.is_a?(LlmGuardrail)
+
+            workers << build_system_worker(g.name, SystemWorkers.guardrail(g, logger: @logger), domain, a) if wanted?(required, g.name)
+          end
+          if a.router.respond_to?(:call)
+            name = "#{a.name}_router_fn"
+            workers << build_system_worker(name, SystemWorkers.router(a.router, a.agents.map(&:name), logger: @logger), domain, a) if wanted?(required, name)
+          end
+          a.callback_positions.each do |position|
+            name = "#{a.name}_#{position}"
+            next unless wanted?(required, name)
+
+            workers << build_system_worker(name, SystemWorkers.callback(a.callback_chain(position, logger: @logger), logger: @logger), domain, a)
+          end
+          handoffs = a.handoffs
+          handoffs += a.agents.flat_map(&:handoffs) if !a.strategy_set? || a.strategy == Strategy::SWARM
+          handoffs.each do |h|
+            next unless h.is_a?(Handoff::OnCondition)
+
+            name = "#{a.name}_handoff_#{h.target}"
+            workers << build_system_worker(name, SystemWorkers.handoff(h, logger: @logger), domain, a) if wanted?(required, name)
+          end
+        end
+        workers.uniq(&:task_definition_name)
+      end
+
+      # Task definition for a tool worker (same defaults as the Python SDK)
+      def task_def_for(name, retry_count: 2, retry_delay_seconds: 2, retry_logic: 'LINEAR_BACKOFF', credentials: [])
+        Http::Models::TaskDef.new(
+          name: name,
+          retry_count: retry_count,
+          retry_delay_seconds: retry_delay_seconds,
+          retry_logic: retry_logic,
+          timeout_seconds: 0,
+          response_timeout_seconds: 10,
+          timeout_policy: 'RETRY',
+          runtime_metadata: credentials.uniq
+        )
+      end
+
+      private
+
+      def wanted?(required, name)
+        required.nil? || required.include?(name)
+      end
+
+      def build_tool_worker(tool_def, credentials:, domain:)
+        credentials = tool_def.credentials + credentials
+        Worker::Worker.new(
+          tool_def.name,
+          ->(task) { Dispatch.run_tool_task(task, tool_def, logger: @logger) },
+          **worker_options(domain, @agent_config.worker_thread_count),
+          task_def_template: task_def_for(tool_def.name, retry_count: tool_def.retry_count,
+                                                         retry_delay_seconds: tool_def.retry_delay_seconds,
+                                                         retry_logic: tool_def.retry_logic, credentials: credentials)
+        )
+      end
+
+      def each_agent_with_credentials(agent, inherited = [], &block)
+        credentials = (inherited + agent.credentials).uniq
+        yield agent, credentials
+        children = agent.agents + [agent.router, agent.planner, agent.fallback].grep(Agent)
+        children += agent.tools.filter_map { |tool| tool.config['agent'] if tool.tool_type == ToolType::AGENT_TOOL }.grep(Agent)
+        children.each { |child| each_agent_with_credentials(child, credentials, &block) }
+      end
+
+      def build_system_worker(name, body, domain, agent)
+        Worker::Worker.new(
+          name, body,
+          **worker_options(domain, @agent_config.system_worker_thread_count),
+          task_def_template: task_def_for(name, credentials: agent.credentials)
+        )
+      end
+
+      # When a run has a runId the server maps every required worker to that domain, so all
+      # workers of the run poll on it.
+      def worker_options(domain, thread_count)
+        {
+          register_task_def: true,
+          overwrite_task_def: true,
+          lease_extend_enabled: true,
+          poll_interval: @agent_config.worker_poll_interval_ms,
+          thread_count: thread_count,
+          domain: domain
+        }
+      end
+
+      def warn_unhandled(required, workers)
+        return if required.nil?
+
+        handled = workers.map(&:task_definition_name)
+        missing = required.to_a - handled
+        return if missing.empty?
+
+        @logger&.warn("server requires workers this process does not provide: #{missing.join(', ')} " \
+                      '(tasks of these types will stay SCHEDULED until some worker serves them)')
+      end
+    end
+  end
+end