conductor_ruby 0.1.0 → 0.1.1

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative 'tool_call'
+
+module Conductor
+  module Agents
+    # A tool call (or batch of them) waiting for a human decision.
+    #
+    #   agent.on_approval do |request|
+    #     request.amount < 100 ? request.approve : request.reject('Needs a manager')
+    #   end
+    #
+    # The server pauses on one HUMAN task per turn, so a request may carry several tool
+    # calls; +tool_name+ and the argument accessors (request.amount) read the first one.
+    class ApprovalRequest
+      attr_reader :execution_id, :task_ref_name, :tool_calls, :response_schema, :raw
+
+      # @param pending_tool [Hash] the SSE "waiting" event's pendingTool payload
+      def initialize(execution_id, pending_tool, client:, execution: nil)
+        @execution_id = execution_id
+        @client = client
+        @execution = execution
+        @raw = pending_tool || {}
+        @task_ref_name = @raw['taskRefName']
+        @response_schema = @raw['response_schema']
+        @tool_calls = extract_tool_calls(@raw)
+        @responded = false
+      end
+
+      # First tool call's name
+      def tool_name
+        @tool_calls.first&.name
+      end
+
+      # First tool call's arguments (String keys)
+      def arguments
+        @tool_calls.first&.arguments || {}
+      end
+
+      def responded?
+        @responded
+      end
+
+      # Let the tool run
+      def approve
+        complete_response { @client.approve(@execution_id) }
+      end
+
+      # Skip the tool; the run ends COMPLETED with finish_reason :rejected
+      def reject(reason = '')
+        complete_response { @client.reject(@execution_id, reason) }
+      end
+
+      # Free-text answer (human tools / feedback)
+      def send_message(message)
+        complete_response { @client.send_message(@execution_id, message) }
+      end
+
+      # Submit fields requested by response_schema (approval plus reviewer feedback,
+      # or structured input for a human tool).
+      def respond(body)
+        complete_response { @client.respond(@execution_id, body) }
+      end
+
+      # request.amount, request.order_id ... read the first tool call's arguments
+      def method_missing(name, *args, &block)
+        key = name.to_s
+        return arguments[key] if args.empty? && arguments.key?(key)
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        arguments.key?(name.to_s) || super
+      end
+
+      def to_s
+        calls = @tool_calls.map(&:to_s).join(', ')
+        "#<Conductor::Agents::ApprovalRequest #{@execution_id} #{calls}>"
+      end
+      alias inspect to_s
+
+      private
+
+      def complete_response
+        raise Error, 'approval request already answered' if @responded
+
+        yield
+        @responded = true
+        @execution&.clear_waiting
+        self
+      end
+
+      def extract_tool_calls(raw)
+        calls = raw['toolCalls'] || raw['tool_calls']
+        if calls.is_a?(Array) && !calls.empty?
+          return calls.map do |c|
+            c = c.transform_keys(&:to_s)
+            ToolCall.new(name: c['name'], arguments: (c['args'] || c['arguments'] || c['parameters'] || {}).transform_keys(&:to_s))
+          end
+        end
+
+        name = raw['tool_name'] || raw['toolName']
+        return [] if name.nil?
+
+        [ToolCall.new(name: name, arguments: (raw['parameters'] || raw['args'] || {}).transform_keys(&:to_s))]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../errors'
+require_relative 'secrets'
+require_relative '../../http/models/task_result'
+
+module Conductor
+  module Agents
+    # Executes one tool task: maps the task's inputData onto the tool method's keyword
+    # arguments, runs it, and shapes the result for the server.
+    #
+    # The server sends the LLM's arguments as top-level keys plus a few injected keys
+    # (method, _agent_state, _agent_tool_name, _allowed_commands) that are stripped here.
+    # Missing required arguments, missing credentials and unserializable results are
+    # terminal failures; anything raised by the tool itself is a retryable failure.
+    module Dispatch
+      INJECTED_KEYS = %w[method _agent_state _agent_tool_name _allowed_commands __conductor_agent_ctx__].freeze
+      WORKER_ID = 'agent-sdk'
+      TRUE_STRINGS = %w[true 1 yes].freeze
+      FALSE_STRINGS = %w[false 0 no].freeze
+
+      # Raised when the LLM omitted a required argument
+      class MissingArgumentError < Error; end
+
+      module_function
+
+      # @param task [Http::Models::Task]
+      # @param tool_def [Tool]
+      # @return [Http::Models::TaskResult]
+      def run_tool_task(task, tool_def, logger: nil)
+        result = base_result(task)
+        input = (task.input_data || {}).transform_keys(&:to_s)
+        args = input.except(*INJECTED_KEYS)
+
+        check_credentials!(tool_def)
+        kwargs = coerce_args(args, tool_def)
+        output = tool_def.func.call(**kwargs)
+        return output if output.is_a?(Http::Models::TaskResult)
+
+        result.status = Http::Models::TaskResultStatus::COMPLETED
+        result.output_data = normalize_output(tool_def, output)
+        result
+      rescue MissingArgumentError, CredentialNotFoundError, ToolSerializationError => e
+        logger&.error("tool #{tool_def.name}: #{e.message}")
+        terminal_failure(result, e)
+      rescue StandardError => e
+        logger&.error("tool #{tool_def.name} raised #{e.class}: #{e.message}")
+        result.status = Http::Models::TaskResultStatus::FAILED
+        result.reason_for_incompletion = "#{e.class}: #{e.message}"
+        result
+      end
+
+      # Map input keys to the tool's keyword arguments, coercing by the JSON schema
+      # @return [Hash<Symbol, Object>]
+      def coerce_args(args, tool_def)
+        schema = tool_def.input_schema || {}
+        properties = schema['properties'] || {}
+        required = Array(schema['required'])
+        accepts_rest = tool_def.func.respond_to?(:parameters) && tool_def.func.parameters.any? { |kind, _| kind == :keyrest }
+
+        missing = required.reject { |name| args.key?(name) }
+        raise MissingArgumentError, "tool #{tool_def.name}: missing required argument(s) #{missing.join(', ')}" unless missing.empty?
+
+        args.each_with_object({}) do |(name, value), kwargs|
+          if properties.key?(name)
+            kwargs[name.to_sym] = coerce_value(value, properties[name])
+          elsif accepts_rest || properties.empty?
+            kwargs[name.to_sym] = value
+          end
+        end
+      end
+
+      # Coerce one value to its JSON schema type (LLMs often send numbers and JSON as strings)
+      def coerce_value(value, property)
+        return value unless property.is_a?(Hash)
+
+        type = property['type']
+        case type
+        when 'integer'
+          value.is_a?(String) ? (Integer(value, 10) rescue value) : value # rubocop:disable Style/RescueModifier
+        when 'number'
+          value.is_a?(String) ? (Float(value) rescue value) : value # rubocop:disable Style/RescueModifier
+        when 'boolean'
+          return value unless value.is_a?(String)
+
+          lower = value.strip.downcase
+          return true if TRUE_STRINGS.include?(lower)
+          return false if FALSE_STRINGS.include?(lower)
+
+          value
+        when 'array', 'object'
+          return value unless value.is_a?(String)
+
+          parsed = JSON.parse(value)
+          expected = type == 'array' ? Array : Hash
+          parsed.is_a?(expected) ? parsed : value
+        when 'string'
+          value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value
+        else
+          value
+        end
+      rescue JSON::ParserError
+        value
+      end
+
+      # Hash results go out as-is; anything else is wrapped as { "result" => value }
+      def normalize_output(tool_def, output)
+        data = output.is_a?(Hash) ? output.transform_keys(&:to_s) : { 'result' => output }
+        begin
+          JSON.generate(data)
+        rescue StandardError => e
+          raise ToolSerializationError, "tool #{tool_def.name} returned a non-JSON-serializable result: #{e.message}"
+        end
+        data
+      end
+
+      def check_credentials!(tool_def)
+        tool_def.credentials.each { |name| Secrets.secret(name) }
+      end
+
+      def base_result(task)
+        result = Http::Models::TaskResult.new
+        result.task_id = task.task_id
+        result.workflow_instance_id = task.workflow_instance_id
+        result.worker_id = WORKER_ID
+        result
+      end
+
+      def terminal_failure(result, error)
+        result.status = Http::Models::TaskResultStatus::FAILED_WITH_TERMINAL_ERROR
+        result.reason_for_incompletion = error.message
+        result
+      end
+    end
+  end
+end

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

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require_relative '../errors'
+require_relative 'approval_request'
+
+module Conductor
+  module Agents
+    # Token usage for an execution (summed over sub-agent executions)
+    TokenUsage = Struct.new(:prompt_tokens, :completion_tokens, :total_tokens, keyword_init: true) do
+      def initialize(prompt_tokens: 0, completion_tokens: 0, total_tokens: 0)
+        super
+      end
+
+      def +(other)
+        TokenUsage.new(prompt_tokens: prompt_tokens + other.prompt_tokens,
+                       completion_tokens: completion_tokens + other.completion_tokens,
+                       total_tokens: total_tokens + other.total_tokens)
+      end
+    end
+
+    # Maps the server's status + output.finishReason to a Symbol
+    module FinishReason
+      def self.derive(status, output)
+        case status.to_s
+        when 'COMPLETED'
+          fr = output.is_a?(Hash) ? output['finishReason'].to_s : ''
+          case fr
+          when 'rejected' then :rejected
+          when 'LENGTH', 'MAX_TOKENS' then :length
+          when 'tool_calls', 'TOOL_CALLS' then :tool_calls
+          when 'CONTENT_FILTER' then :content_filter
+          else :stop
+          end
+        when 'FAILED' then :error
+        when 'TERMINATED' then :cancelled
+        when 'TIMED_OUT' then :timeout
+        else :stop
+        end
+      end
+    end
+
+    # Handle on a running (or finished) agent execution.
+    #
+    #   execution = agent.call_async('Refund order A-1029')
+    #   execution.done?          # false until finished
+    #   execution.partial_text   # streamed text so far
+    #   execution.result         # blocks for the answer
+    #   execution.finish_reason  # :stop | :rejected | ...
+    class Execution
+      TERMINAL_STATUSES = %w[COMPLETED FAILED TERMINATED TIMED_OUT].freeze
+
+      attr_reader :execution_id, :agent_name, :tool_calls, :token_usage, :pending, :error, :status, :output, :events
+
+      # @param execution_id [String] also the Conductor workflow id
+      # @param client [Client::AgentClient]
+      def initialize(execution_id, client:, agent_name: nil, runtime: nil)
+        @execution_id = execution_id
+        @client = client
+        @agent_name = agent_name
+        @runtime = runtime
+        @mutex = Mutex.new
+        @done_cv = ConditionVariable.new
+        @partial_text = +''
+        @tool_calls = []
+        @events = []
+        @token_usage = TokenUsage.new
+        @pending = nil
+        @status = 'RUNNING'
+        @output = nil
+        @result = nil
+        @error = nil
+        @waiting = false
+        @finished = false
+      end
+
+      # Look up an execution by id (a snapshot; +result+ attaches a stream if still running)
+      # @return [Execution]
+      def self.find(execution_id, runtime: Conductor::Agents.runtime)
+        execution = new(execution_id, client: runtime.client, runtime: runtime)
+        execution.refresh!
+        execution
+      end
+
+      # Re-read status from the server
+      def refresh!
+        status = @client.get_status(@execution_id)
+        @agent_name ||= status['agentName']
+        if status['isComplete']
+          finish(status: status['status'], output: status['output'], reason: status['reasonForIncompletion'])
+        elsif status['isWaiting']
+          mark_waiting(ApprovalRequest.new(@execution_id, status['pendingTool'], client: @client, execution: self))
+        else
+          clear_waiting
+        end
+        self
+      end
+
+      def done?
+        @mutex.synchronize { @finished }
+      end
+
+      def waiting?
+        @mutex.synchronize { @waiting && !@finished }
+      end
+
+      # Text streamed so far (never behind +result+ once done)
+      def partial_text
+        @mutex.synchronize { @partial_text.dup }
+      end
+
+      # Block until finished and return the answer
+      # @param timeout [Numeric, nil] seconds; nil waits forever
+      # @raise [Error] when the execution failed, was cancelled or timed out on the server
+      # @raise [Timeout::Error] when +timeout+ elapses first
+      def result(timeout: nil)
+        @runtime&.attach(self) unless done? || @attached
+        @mutex.synchronize do
+          deadline = timeout && (Time.now + timeout)
+          until @finished
+            remaining = deadline && (deadline - Time.now)
+            raise Timeout::Error, "execution #{@execution_id} still running after #{timeout}s" if remaining && remaining <= 0
+
+            @done_cv.wait(@mutex, remaining)
+          end
+          raise Error, "execution #{@execution_id} #{@status.downcase}: #{@error}" if @error && @status != 'COMPLETED'
+
+          @result
+        end
+      end
+
+      # The answer without blocking or raising (nil while running or when failed)
+      def answer
+        @mutex.synchronize { @finished ? @result : nil }
+      end
+
+      # @return [Symbol] :stop | :tool_calls | :length | :content_filter | :rejected | :error | :cancelled | :timeout | nil
+      def finish_reason
+        @mutex.synchronize { @finished ? FinishReason.derive(@status, @output) : nil }
+      end
+
+      def rejected?
+        finish_reason == :rejected
+      end
+
+      # ── control ─────────────────────────────────────────────────────
+
+      def pause
+        @client.pause(@execution_id)
+        self
+      end
+
+      def resume
+        @client.resume(@execution_id)
+        self
+      end
+
+      def cancel(reason: 'cancelled by client')
+        @client.cancel(@execution_id, reason: reason)
+        self
+      end
+
+      def stop
+        @client.stop(@execution_id)
+        self
+      end
+
+      def signal(message)
+        @client.signal(@execution_id, message)
+        self
+      end
+
+      # Approve / reject the pending tool call, if any
+      def approve
+        (pending || raise(Error, 'nothing is waiting for approval')).approve
+      end
+
+      def reject(reason = '')
+        (pending || raise(Error, 'nothing is waiting for approval')).reject(reason)
+      end
+
+      # ── mutators used by the runtime's stream thread ────────────────
+
+      def attached!
+        @attached = true
+      end
+
+      def record_event(event)
+        @mutex.synchronize { @events << event }
+      end
+
+      def append_text(text)
+        return if text.nil? || text.to_s.empty?
+
+        @mutex.synchronize { @partial_text << text.to_s }
+      end
+
+      def add_tool_call(name, arguments)
+        @mutex.synchronize { @tool_calls << ToolCall.new(name: name, arguments: arguments || {}) }
+      end
+
+      def add_tool_result(name, result)
+        @mutex.synchronize do
+          call = @tool_calls.reverse.find { |c| c.name == name && c.result.nil? }
+          call ? call.result = result : @tool_calls << ToolCall.new(name: name, arguments: {}, result: result)
+        end
+      end
+
+      def mark_waiting(pending)
+        @mutex.synchronize do
+          @waiting = true
+          @pending = pending
+        end
+      end
+
+      def clear_waiting
+        @mutex.synchronize do
+          @waiting = false
+          @pending = nil
+        end
+      end
+
+      def token_usage=(usage)
+        @mutex.synchronize { @token_usage = usage }
+      end
+
+      # Mark the execution finished. +output+ is the workflow output ({result, finishReason, ...}).
+      def finish(status:, output:, reason: nil)
+        @mutex.synchronize do
+          return if @finished
+
+          @status = status.to_s
+          @output = output.is_a?(Hash) ? output : {}
+          @result = extract_result(output)
+          @error = reason if reason && !reason.to_s.empty?
+          @error ||= (@output['error'] || @output['reason']) unless @status == 'COMPLETED'
+          @error ||= "execution #{@status.downcase}" unless @status == 'COMPLETED'
+          @partial_text = @result.to_s.dup if @result.is_a?(String) && @partial_text.empty?
+          @waiting = false
+          @pending = nil
+          @finished = true
+          @done_cv.broadcast
+        end
+      end
+
+      def fail(reason)
+        finish(status: 'FAILED', output: { 'error' => reason }, reason: reason)
+      end
+
+      def to_s
+        "#<Conductor::Agents::Execution #{@execution_id} #{@status}#{@finished ? '' : ' (running)'}>"
+      end
+      alias inspect to_s
+
+      private
+
+      def extract_result(output)
+        return output unless output.is_a?(Hash)
+        return output['result'] if output.key?('result')
+
+        output
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../../worker/task_context'
+
+module Conductor
+  module Agents
+    # Read secrets inside a tool body.
+    #
+    #   tool def create_issue(title: String)
+    #     Github.create_issue(title, token: secret('GH_TOKEN'))
+    #   end
+    #
+    # The literal name is also the declaration: the Tools DSL scans the body and puts
+    # GH_TOKEN on the tool's TaskDef#runtime_metadata. The server resolves it from its
+    # secret store at poll time and delivers the value on Task#runtime_metadata, which
+    # TaskContext (thread/fiber-local) exposes to the running tool. Nothing is ever written
+    # to ENV; for subprocesses use secrets_env.
+    module Secrets
+      module_function
+
+      # @param name [String, Symbol]
+      # @return [String]
+      # @raise [CredentialNotFoundError] when neither the task nor ENV has it
+      def secret(name)
+        key = name.to_s
+        value = task_secrets[key]
+        value = ENV.fetch(key, nil) if value.nil?
+        return value unless value.nil?
+
+        raise CredentialNotFoundError,
+              "secret #{key.inspect} not found: it was not delivered on the task's runtimeMetadata " \
+              "and ENV[#{key.inspect}] is unset. Store it on the server (conductor secrets put #{key} ...) " \
+              'or declare it with add_tool ..., credentials: [...]'
+      end
+
+      # Environment hash for system / spawn / Open3: { 'GH_TOKEN' => '...' }
+      # @return [Hash<String, String>]
+      def secrets_env(*names)
+        names.flatten.each_with_object({}) { |n, env| env[n.to_s] = secret(n) }
+      end
+
+      # Secrets bound for the current task (wire-only Task#runtime_metadata)
+      # @return [Hash<String, String>]
+      def task_secrets
+        ctx = Conductor::Worker::TaskContext.current
+        task = ctx&.task
+        return {} unless task.respond_to?(:runtime_metadata)
+
+        task.runtime_metadata || {}
+      end
+    end
+  end
+end