conductor_ruby 0.1.0 → 0.1.1

data/lib/conductor/agents/tools/secret_scanner.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Conductor
+  module Agents
+    module Tools
+      # Finds the secret names a tool body reads, so they can be declared on the wire
+      # (TaskDef#runtime_metadata / tool.config.credentials) without a separate list.
+      #
+      # Only string literals are picked up:
+      #
+      #   secret('GH_TOKEN')            # => GH_TOKEN
+      #   secrets_env('A', 'B')         # => A, B
+      #   secret(name)                  # dynamic: declare with add_tool ..., credentials: [...]
+      module SecretScanner
+        SECRET_METHODS = %i[secret secrets_env].freeze
+
+        module_function
+
+        # @param method [Method, UnboundMethod]
+        # @return [Array<String>] literal secret names, in order of appearance
+        def scan(method)
+          ast = SchemaBuilder.ast_of(method)
+          return [] unless ast
+
+          names = []
+          SchemaBuilder.each_node(ast) do |node|
+            method_id, args = call_parts(node)
+            next unless SECRET_METHODS.include?(method_id)
+
+            SchemaBuilder.each_node(args) { |a| names << a.children[0] if a.type == :STR }
+          end
+          names.uniq
+        end
+
+        def call_parts(node)
+          case node.type
+          when :FCALL then [node.children[0], node.children[1]]
+          when :CALL, :QCALL then [node.children[1], node.children[2]]
+          else [nil, nil]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/conductor/agents/tools.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'runtime/secrets'
+require_relative 'tool'
+require_relative 'tools/schema_builder'
+require_relative 'tools/secret_scanner'
+
+module Conductor
+  module Agents
+    # The tool DSL.
+    #
+    #   include Conductor::Agents          # top level, or
+    #   module Weather; extend Conductor::Agents::Tools; ... end
+    #
+    #   tool def get_weather(city: String, units: 'metric')
+    #     { temp_c: 21.0 }
+    #   end
+    #   describe :get_weather, 'Get the current weather for a city.'
+    #   requires_approval :get_weather
+    #
+    # +tool+ receives the Symbol that +def+ returns, builds a Tool from the method
+    # (schema from keyword defaults, secrets from literal secret() calls) and registers it
+    # both on the receiver (Weather[:get_weather], Weather.tool_defs) and in the global
+    # registry that Agent#add_tool(:get_weather) consults.
+    module Tools
+      TOOL_OPTIONS = %i[name description input_schema output_schema approval_required timeout_seconds credentials
+                        guardrails stateful max_calls retry_count retry_delay_seconds retry_policy external].freeze
+
+      # Weather[:current] on a module that `extend Conductor::Agents::Tools`
+      module Lookup
+        # @return [Tool]
+        def [](name)
+          fetch_tool(name)
+        end
+      end
+
+      class << self
+        # A module that extends Tools also gets [] and the secret helpers
+        def extended(base)
+          base.extend(Lookup)
+          base.extend(Secrets)
+        end
+
+        # Global name => Tool registry shared by every scope that defines tools
+        def registry
+          @registry ||= {}
+        end
+
+        def registry_mutex
+          @registry_mutex ||= Mutex.new
+        end
+
+        def register(tool_def)
+          registry_mutex.synchronize { registry[tool_def.name] = tool_def }
+          tool_def
+        end
+
+        # @return [Tool, nil]
+        def lookup(name)
+          registry_mutex.synchronize { registry[name.to_s] }
+        end
+
+        # Forget every registered tool (tests)
+        def clear!
+          registry_mutex.synchronize { registry.clear }
+        end
+
+        # Build a Tool from a bound Method
+        # @param method [Method]
+        # @param name [String, nil] tool name override
+        def build(method, name: nil, **options)
+          unknown = options.keys - TOOL_OPTIONS
+          raise ConfigurationError, "unknown tool option(s): #{unknown.inspect}" unless unknown.empty?
+
+          tool_name = (name || method.name).to_s
+          input_schema = options.fetch(:input_schema) { SchemaBuilder.input_schema(method) }
+          credentials = SecretScanner.scan(method)
+
+          Tool.new(
+            name: tool_name,
+            description: options.fetch(:description) { humanize(method.name) },
+            input_schema: input_schema,
+            output_schema: options.fetch(:output_schema) { SchemaBuilder.default_output_schema },
+            func: options[:external] ? nil : method,
+            approval_required: options.fetch(:approval_required, false),
+            timeout_seconds: options[:timeout_seconds],
+            credentials: credentials + Array(options[:credentials]),
+            guardrails: Array(options[:guardrails]),
+            stateful: options.fetch(:stateful, false),
+            max_calls: options[:max_calls],
+            retry_count: options.fetch(:retry_count, 2),
+            retry_delay_seconds: options.fetch(:retry_delay_seconds, 2),
+            retry_policy: options.fetch(:retry_policy, 'linear_backoff')
+          )
+        end
+
+        # "get_weather" => "Get weather"
+        def humanize(name)
+          words = name.to_s.tr('_', ' ').strip
+          return '' if words.empty?
+
+          words[0].upcase + words[1..]
+        end
+      end
+
+      # Mark a method as a tool
+      # @param name [Symbol, String, Method] method name (what +def+ returns) or a Method
+      # @param options [Hash] Tool overrides: name: (tool name when it differs from the method name),
+      #   description:, output_schema:, approval_required:, timeout_seconds:, credentials:, guardrails:,
+      #   stateful:, max_calls:, retry_count:, retry_delay_seconds:, retry_policy:, external:
+      # @return [Tool]
+      def tool(name, **options)
+        method = name.is_a?(Method) ? name : resolve_tool_method(name.to_sym)
+        tool_name = options.delete(:name) || (name.is_a?(Method) ? name.name : name)
+        tool_def = Tools.build(method, name: tool_name, **options)
+        tool_registry[tool_def.name] = tool_def
+        Tools.register(tool_def)
+      end
+
+      # Override the description the LLM sees
+      def describe(name, text)
+        fetch_tool(name).description = text.to_s
+      end
+
+      # Require a human approval before the tool runs
+      def requires_approval(name, enabled: true)
+        fetch_tool(name).approval_required = enabled
+      end
+
+      # Declare secret names the scanner could not see (dynamic names)
+      def tool_credentials(name, *secret_names)
+        fetch_tool(name).add_credentials(*secret_names)
+      end
+
+      # Every tool defined in this scope, in definition order
+      # @return [Array<Tool>]
+      def tool_defs
+        tool_registry.values
+      end
+
+      private
+
+      def tool_registry
+        @conductor_tool_registry ||= {} # rubocop:disable Naming/MemoizedInstanceVariableName
+      end
+
+      def fetch_tool(name)
+        tool_registry[name.to_s] || Tools.lookup(name) ||
+          raise(ConfigurationError, "no tool named #{name.inspect}; define it with `tool def #{name}(...)` first")
+      end
+
+      # Find the method behind +tool def name+ for the current receiver:
+      # - top level / objects: the method is on self
+      # - module with `extend Tools`: `def` made an instance method; module_function it
+      # - class bodies (e.g. inside RSpec.describe): bind the instance method to a bare instance
+      def resolve_tool_method(name)
+        return method(name) if respond_to?(name, true)
+
+        if is_a?(Module) && (method_defined?(name) || private_method_defined?(name))
+          if instance_of?(Module)
+            module_function(name)
+            return method(name)
+          end
+
+          return instance_method(name).bind(allocate)
+        end
+
+        raise ConfigurationError, "tool #{name.inspect}: no such method on #{inspect}"
+      end
+    end
+  end
+end

data/lib/conductor/agents.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Conductor::Agents - define agents in Ruby, run them on a Conductor server.
+#
+#   require 'conductor/agents'
+#   include Conductor::Agents
+#
+#   tool def get_weather(city: String, units: 'metric')
+#     { temp_c: 21.0, summary: "Sunny in #{city}" }
+#   end
+#
+#   agent = Agent.new(name: 'weather', model: 'openai/gpt-4o', instructions: 'Answer weather questions.')
+#   agent.add_tool :get_weather
+#   puts agent.call_sync('Weather in Lisbon?')
+require_relative '../conductor'
+require_relative 'agents/errors'
+require_relative 'agents/runtime/secrets'
+require_relative 'agents/tool'
+require_relative 'agents/tools'
+require_relative 'agents/guardrail'
+require_relative 'agents/termination'
+require_relative 'agents/handoff'
+require_relative 'agents/callback_handler'
+require_relative 'agents/memory'
+require_relative 'agents/prompt_template'
+require_relative 'agents/agent'
+require_relative 'agents/plans'
+require_relative 'agents/config_serializer'
+require_relative 'agents/runtime/agent_config'
+require_relative 'agents/runtime/dispatch'
+require_relative 'agents/runtime/system_workers'
+require_relative 'agents/runtime/tool_registry'
+require_relative 'agents/runtime/execution'
+require_relative 'agents/runtime/approval_request'
+require_relative 'agents/runtime/sse_client'
+require_relative 'agents/runtime/status_poller'
+require_relative 'agents/runtime/agent_runtime'
+
+module Conductor
+  # Ruby port of the Python SDK's conductor.ai.agents package
+  module Agents
+    include Tools
+    include Secrets
+    include Plans
+
+    class << self
+      # Tools and secrets are usable at the module level too (Conductor::Agents.tool ...)
+      include Tools
+      include Secrets
+      include Plans
+
+      # The default runtime used by Agent#call_sync / #call_async (built from the environment)
+      # @return [AgentRuntime]
+      def runtime
+        @runtime ||= AgentRuntime.new
+      end
+
+      attr_writer :runtime
+
+      # Replace the default runtime
+      #   Conductor::Agents.configure(configuration: Conductor::Configuration.new(server_api_url: '...'))
+      # @return [AgentRuntime]
+      def configure(configuration: nil, agent_config: nil, logger: nil)
+        @runtime&.shutdown
+        @runtime = AgentRuntime.new(configuration: configuration, agent_config: agent_config, logger: logger)
+      end
+
+      # Stop the default runtime's workers and streams
+      def shutdown
+        @runtime&.shutdown
+        @runtime = nil
+      end
+    end
+  end
+end

data/lib/conductor/client/agent_client.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative '../exceptions'
+require_relative '../http/api/agent_resource_api'
+
+module Conductor
+  module Client
+    # AgentClient - High-level client for the server-side agent runtime.
+    #
+    # Mirrors the Python SDK's OrkesAgentClient: hashes in, hashes out, and every
+    # transport error is re-raised as AgentApiError (AgentNotFoundError on 404).
+    class AgentClient
+      attr_reader :agent_api
+
+      # @param api_client [Http::ApiClient]
+      def initialize(api_client)
+        @api_client = api_client
+        @agent_api = Http::Api::AgentResourceApi.new(api_client)
+      end
+
+      # @param payload [Hash] AgentStartRequest
+      # @return [Hash] { "executionId", "agentName", "requiredWorkers" }
+      def start_agent(payload)
+        wrap { @agent_api.start(payload) }
+      end
+
+      # @return [Hash] { "agentName", "requiredWorkers" }
+      def deploy_agent(payload)
+        wrap { @agent_api.deploy(payload) }
+      end
+
+      # @return [Hash] { "workflowDef", "requiredWorkers" }
+      def compile_agent(payload)
+        wrap { @agent_api.compile(payload) }
+      end
+
+      def get_status(execution_id)
+        wrap { @agent_api.status(execution_id) }
+      end
+
+      # Stream raw agent events; runtime consumers can instead use call_async(on_event:).
+      def stream_sse(execution_id, last_event_id: nil, &block)
+        require_relative '../agents/runtime/sse_client'
+        Agents::SseClient.new(@api_client).each_event(execution_id, last_event_id: last_event_id, &block)
+      end
+
+      def get_execution(execution_id)
+        wrap { @agent_api.execution(execution_id) }
+      end
+
+      def list_executions(params = {})
+        wrap { @agent_api.executions(params) }
+      end
+
+      # Respond to a waiting execution. Hashes pass through; anything else is wrapped as
+      # { "output" => value } like the Python client does.
+      def respond(execution_id, body)
+        payload = body.is_a?(Hash) ? body : { 'output' => body }
+        wrap { @agent_api.respond(execution_id, payload) }
+      end
+
+      def approve(execution_id)
+        respond(execution_id, { 'approved' => true })
+      end
+
+      def reject(execution_id, reason = '')
+        respond(execution_id, { 'approved' => false, 'reason' => reason.to_s })
+      end
+
+      def send_message(execution_id, message)
+        respond(execution_id, { 'message' => message.to_s })
+      end
+
+      def stop(execution_id)
+        wrap { @agent_api.stop(execution_id) }
+      end
+
+      def signal(execution_id, message)
+        wrap { @agent_api.signal(execution_id, message) }
+      end
+
+      def pause(execution_id)
+        wrap { @agent_api.pause(execution_id) }
+      end
+
+      def resume(execution_id)
+        wrap { @agent_api.resume(execution_id) }
+      end
+
+      def cancel(execution_id, reason: nil)
+        wrap { @agent_api.cancel(execution_id, reason: reason) }
+      end
+
+      def list_agents
+        wrap { @agent_api.list }
+      end
+
+      def get_agent(name, version: nil)
+        wrap { @agent_api.get_agent(name, version: version) }
+      end
+
+      def delete_agent(name, version: nil)
+        wrap { @agent_api.delete(name, version: version) }
+      end
+
+      private
+
+      def wrap
+        yield
+      rescue AgentApiError
+        raise
+      rescue ApiError => e
+        raise AgentApiError.from_api_error(e)
+      end
+    end
+  end
+end

data/lib/conductor/client/task_client.rb

@@ -45,6 +45,13 @@ module Conductor
         @task_api.update_task(task_result)
       end
 
+      # Update task status using the v2 endpoint (supports lease extension)
+      # @param [TaskResult] task_result Task result
+      # @return [Task, nil] Next task for this worker, if any
+      def update_task_v2(task_result)
+        @task_api.update_task_v2(task_result)
+      end
+
       # Get task details
       # @param [String] task_id Task ID
       # @return [Task] Task object

data/lib/conductor/configuration.rb

@@ -5,12 +5,43 @@ require_relative 'configuration/authentication_settings'
 module Conductor
   # Configuration for Conductor client
   class Configuration
-    # Class-level auth token cache (shared across instances, like Python SDK)
+    # Legacy process-wide token cache. Tokens are now cached per Configuration
+    # instance so that two configurations (different servers or credentials) in
+    # one process never share a token. The class-level accessors remain for one
+    # release as a compatibility shim and warn once when used.
     @auth_token = nil
     @token_update_time = 0
 
     class << self
-      attr_accessor :auth_token, :token_update_time
+      def auth_token
+        legacy_token_cache_warning
+        @auth_token
+      end
+
+      def auth_token=(token)
+        legacy_token_cache_warning
+        @auth_token = token
+      end
+
+      def token_update_time
+        legacy_token_cache_warning
+        @token_update_time
+      end
+
+      def token_update_time=(time)
+        legacy_token_cache_warning
+        @token_update_time = time
+      end
+
+      private
+
+      def legacy_token_cache_warning
+        return if @legacy_token_cache_warned
+
+        @legacy_token_cache_warned = true
+        warn '[Conductor] Configuration.auth_token / token_update_time are deprecated: ' \
+             'the auth token is cached per Configuration instance.'
+      end
     end
 
     attr_accessor :base_url, :server_api_url, :debug, :authentication_settings,
@@ -29,6 +60,8 @@ module Conductor
       @key_file = nil
       @proxy = nil
       @auth_token_ttl_min = auth_token_ttl_min
+      @auth_token = nil
+      @token_update_time = 0
 
       # Resolve server URL
       @host = resolve_host(server_api_url, base_url)
@@ -50,18 +83,18 @@ module Conductor
       @authentication_settings = nil
     end
 
+    # Cache an auth token on this configuration instance
+    # @param token [String] JWT returned by the /token endpoint
     def update_token(token)
-      self.class.auth_token = token
-      self.class.token_update_time = (Time.now.to_f * 1000).to_i
+      @auth_token = token
+      @token_update_time = (Time.now.to_f * 1000).to_i
     end
 
-    def auth_token
-      self.class.auth_token
-    end
+    # @return [String, nil] The cached auth token for this configuration
+    attr_reader :auth_token
 
-    def token_update_time
-      self.class.token_update_time
-    end
+    # @return [Integer] Epoch milliseconds of the last token update (0 when never set)
+    attr_reader :token_update_time
 
     # Alias for server URL (used in some places)
     def server_url

data/lib/conductor/exceptions.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Conductor
   # Base exception for all Conductor errors
   class ConductorError < StandardError; end
@@ -71,6 +73,40 @@ module Conductor
     end
   end
 
+  # Error returned by the agent REST API (/api/agent/*). The server answers 4xx with
+  # {"error": "<message>", "status": <code>}; +error+ carries that message when present.
+  class AgentApiError < ApiError
+    attr_reader :error
+
+    def initialize(message = nil, status: nil, code: nil, reason: nil, body: nil, headers: nil)
+      @error = parse_error(body)
+      super(message || @error, status: status, code: code, reason: reason, body: body, headers: headers)
+    end
+
+    # Build from a generic ApiError raised by the transport layer
+    # @param error [ApiError]
+    # @return [AgentApiError]
+    def self.from_api_error(error)
+      klass = error.not_found? ? AgentNotFoundError : AgentApiError
+      klass.new(error.message, status: error.status, code: error.code, reason: error.reason,
+                               body: error.body, headers: error.headers)
+    end
+
+    private
+
+    def parse_error(body)
+      return nil unless body.is_a?(String) && !body.empty?
+
+      data = JSON.parse(body)
+      data['error'] if data.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  # Agent, execution, or deployment not found (404 from /api/agent/*)
+  class AgentNotFoundError < AgentApiError; end
+
   # Non-retryable worker error (terminal failure)
   class NonRetryableError < ConductorError; end
 

data/lib/conductor/http/api/agent_resource_api.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative '../api_client'
+
+module Conductor
+  module Http
+    module Api
+      # AgentResourceApi - REST bindings for the server-side agent runtime (/api/agent/*)
+      #
+      # Every method returns the parsed JSON body as a Hash (or Array) so that callers
+      # see exactly the keys the server sent (executionId, requiredWorkers, isComplete, ...).
+      # The SSE stream endpoint is not here: it needs a long-lived streaming connection and
+      # lives in Conductor::Agents::Runtime::SseClient.
+      class AgentResourceApi
+        HASH = 'Hash<String, Object>'
+
+        attr_accessor :api_client
+
+        def initialize(api_client = nil)
+          @api_client = api_client || ApiClient.new
+        end
+
+        # Start an agent execution
+        # @param body [Hash] AgentStartRequest: agentConfig | name, prompt, sessionId, media, context, runId, ...
+        # @return [Hash] { "executionId", "agentName", "requiredWorkers" }
+        def start(body)
+          post('/agent/start', body)
+        end
+
+        # Register (deploy) an agent definition without starting it
+        # @param body [Hash] AgentStartRequest with agentConfig
+        # @return [Hash] { "agentName", "requiredWorkers" }
+        def deploy(body)
+          post('/agent/deploy', body)
+        end
+
+        # Compile an agent config into a workflow definition without registering it
+        # @param body [Hash] AgentStartRequest with agentConfig
+        # @return [Hash] { "workflowDef", "requiredWorkers" }
+        def compile(body)
+          post('/agent/compile', body)
+        end
+
+        # Get the status of an execution
+        # @return [Hash] { "executionId", "status", "isComplete", "isRunning", "isWaiting", "output", "pendingTool", ... }
+        def status(execution_id)
+          get('/agent/{executionId}/status', execution_id)
+        end
+
+        # Get an execution with its tasks and token usage
+        # @return [Hash] { "executionId", "status", "output", "tokenUsage", "tasks" }
+        def execution(execution_id)
+          get('/agent/execution/{executionId}', execution_id)
+        end
+
+        # List executions
+        # @param params [Hash] start, size, sort, freeText, status, agentName, sessionId
+        # @return [Hash] { "totalHits", "results" }
+        def executions(params = {})
+          @api_client.call_api('/agent/executions', 'GET', query_params: params, return_type: HASH,
+                                                           return_http_data_only: true)
+        end
+
+        # Respond to a waiting execution (approval, human input, free text)
+        # @param body [Hash] e.g. { "approved" => true } or { "approved" => false, "reason" => "..." }
+        def respond(execution_id, body)
+          post_action(execution_id, 'respond', body)
+        end
+
+        # Ask the agent loop to stop after the current iteration
+        def stop(execution_id)
+          post_action(execution_id, 'stop')
+        end
+
+        # Inject a signal message into the next LLM turn
+        def signal(execution_id, message)
+          post_action(execution_id, 'signal', { 'message' => message })
+        end
+
+        # Pause the execution
+        def pause(execution_id)
+          @api_client.call_api('/agent/{executionId}/pause', 'PUT', path_params: { executionId: execution_id },
+                                                                    return_http_data_only: true)
+        end
+
+        # Resume a paused execution
+        def resume(execution_id)
+          @api_client.call_api('/agent/{executionId}/resume', 'PUT', path_params: { executionId: execution_id },
+                                                                     return_http_data_only: true)
+        end
+
+        # Cancel (terminate) the execution
+        def cancel(execution_id, reason: nil)
+          query = reason ? { reason: reason } : {}
+          @api_client.call_api('/agent/{executionId}/cancel', 'DELETE', path_params: { executionId: execution_id },
+                                                                        query_params: query, return_http_data_only: true)
+        end
+
+        # List deployed agents
+        # @return [Array<Hash>]
+        def list
+          @api_client.call_api('/agent/list', 'GET', return_type: 'Array<Object>', return_http_data_only: true)
+        end
+
+        # Get a deployed agent definition by name
+        # @return [Hash] the agentConfig as deployed
+        def get_agent(name, version: nil)
+          query = version ? { version: version } : {}
+          @api_client.call_api('/agent/{name}', 'GET', path_params: { name: name }, query_params: query,
+                                                       return_type: HASH, return_http_data_only: true)
+        end
+
+        # Delete a deployed agent definition
+        def delete(name, version: nil)
+          query = version ? { version: version } : {}
+          @api_client.call_api('/agent/{name}', 'DELETE', path_params: { name: name }, query_params: query,
+                                                          return_http_data_only: true)
+        end
+
+        private
+
+        def get(path, execution_id)
+          @api_client.call_api(path, 'GET', path_params: { executionId: execution_id }, return_type: HASH,
+                                            return_http_data_only: true)
+        end
+
+        def post(path, body)
+          @api_client.call_api(path, 'POST', body: body, return_type: HASH, return_http_data_only: true)
+        end
+
+        def post_action(execution_id, action, body = nil)
+          @api_client.call_api("/agent/{executionId}/#{action}", 'POST', path_params: { executionId: execution_id },
+                                                                         body: body, return_http_data_only: true)
+        end
+      end
+    end
+  end
+end