exa-ai 0.11.2 → 0.12.0

data/lib/exa/services/agent_run_delete.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../resources/agent_run"
+
+module Exa
+  module Services
+    class AgentRunDelete
+      def initialize(connection, run_id:)
+        @connection = connection
+        @run_id = run_id
+      end
+
+      def call
+        response = @connection.delete("/agent/runs/#{@run_id}")
+        body = response.body
+
+        # ponytail: 204-vs-200 unconfirmed; nil-guarded. Confirm against live API.
+        if body.nil? || body.empty?
+          return Resources::AgentRun.new(id: @run_id, object: "agent_run", status: "deleted")
+        end
+
+        Resources::AgentRun.new(
+          id: body["id"],
+          object: body["object"],
+          status: body["status"],
+          stop_reason: body["stopReason"],
+          created_at: body["createdAt"],
+          completed_at: body["completedAt"],
+          request: body["request"],
+          output: body["output"],
+          usage: body["usage"],
+          cost_dollars: body["costDollars"]
+        )
+      end
+    end
+  end
+end

data/lib/exa/services/agent_run_events.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../resources/agent_run_event_list"
+
+module Exa
+  module Services
+    class AgentRunEvents
+      def initialize(connection, run_id:, **params)
+        @connection = connection
+        @run_id = run_id
+        @params = params
+      end
+
+      def call
+        response = @connection.get("/agent/runs/#{@run_id}/events", @params)
+        body = response.body
+
+        # Confirmed live: GET /agent/runs/{id}/events returns a paginated list
+        # {object: "list", data: [...], hasMore, nextCursor}.
+        Resources::AgentRunEventList.new(
+          data: body["data"] || [],
+          has_more: body["hasMore"],
+          next_cursor: body["nextCursor"]
+        )
+      end
+    end
+  end
+end

data/lib/exa/services/agent_run_get.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../resources/agent_run"
+
+module Exa
+  module Services
+    class AgentRunGet
+      def initialize(connection, run_id:, **params)
+        @connection = connection
+        @run_id = run_id
+        @params = params
+      end
+
+      def call
+        response = @connection.get("/agent/runs/#{@run_id}", @params)
+        body = response.body
+
+        Resources::AgentRun.new(
+          id: body["id"],
+          object: body["object"],
+          status: body["status"],
+          stop_reason: body["stopReason"],
+          created_at: body["createdAt"],
+          completed_at: body["completedAt"],
+          request: body["request"],
+          output: body["output"],
+          usage: body["usage"],
+          cost_dollars: body["costDollars"]
+        )
+      end
+    end
+  end
+end

data/lib/exa/services/agent_run_list.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "../resources/agent_run"
+require_relative "../resources/agent_run_list"
+
+module Exa
+  module Services
+    class AgentRunList
+      def initialize(connection, **params)
+        @connection = connection
+        @params = params
+      end
+
+      def call
+        response = @connection.get("/agent/runs", @params)
+        body = response.body
+
+        data = body["data"].map do |run_data|
+          Resources::AgentRun.new(
+            id: run_data["id"],
+            object: run_data["object"],
+            status: run_data["status"],
+            stop_reason: run_data["stopReason"],
+            created_at: run_data["createdAt"],
+            completed_at: run_data["completedAt"],
+            request: run_data["request"],
+            output: run_data["output"],
+            usage: run_data["usage"],
+            cost_dollars: run_data["costDollars"]
+          )
+        end
+
+        Resources::AgentRunList.new(
+          data: data,
+          has_more: body["hasMore"],
+          next_cursor: body["nextCursor"]
+        )
+      end
+    end
+  end
+end

data/lib/exa/services/agent_run_stream.rb

@@ -0,0 +1,110 @@
+require "json"
+require_relative "parameter_converter"
+require_relative "../resources/agent_run"
+
+# ponytail: copied AnswerStream's SSE parser rather than extracting a shared module — agent frames add event:/id: lines and the two may diverge. Extract only if a third SSE consumer appears.
+
+module Exa
+  module Services
+    class AgentRunStream
+      TERMINAL_EVENTS = %w[agent_run.completed agent_run.failed agent_run.cancelled].freeze
+
+      def initialize(connection, **params)
+        @connection = connection
+        @params = params
+      end
+
+      # Streams SSE frames to the block as (event_type, data). Returns the final
+      # AgentRun built from the terminal event's payload (completed/failed/
+      # cancelled), or nil if the stream ended before a terminal event arrived.
+      def call(&block)
+        raise ArgumentError, "block required for streaming" unless block_given?
+
+        @buffer = ""
+        @final_payload = nil
+
+        # Capture the terminal payload as it streams, then forward to the caller.
+        interceptor = proc do |event_type, data|
+          @final_payload = data if TERMINAL_EVENTS.include?(event_type)
+          block.call(event_type, data)
+        end
+
+        body = ParameterConverter.convert(@params)
+
+        @connection.post("/agent/runs", body) do |req|
+          req.headers["Accept"] = "text/event-stream"
+          req.options.on_data = proc do |chunk|
+            @buffer += chunk
+            process_sse_buffer(&interceptor)
+          end
+        end
+
+        process_remaining_buffer(&interceptor) if @buffer.length.positive?
+
+        @final_payload && Resources::AgentRun.from_response(@final_payload)
+      end
+
+      private
+
+      def process_sse_buffer
+        return if @buffer.empty?
+
+        parts = @buffer.split("\n\n")
+
+        if @buffer.end_with?("\n\n")
+          complete_parts = parts
+          @buffer = ""
+        else
+          complete_parts = parts[0...-1]
+          @buffer = parts.last || ""
+        end
+
+        complete_parts.each do |frame|
+          next if frame.empty?
+
+          event_type = nil
+          data_json = nil
+
+          frame.split("\n").each do |line|
+            if line.start_with?("event: ")
+              event_type = line.sub(/^event: /, "").strip
+            elsif line.start_with?("data: ")
+              data_json = line.sub(/^data: /, "").strip
+            end
+          end
+
+          next if data_json.nil?
+
+          begin
+            data = JSON.parse(data_json)
+            yield(event_type, data)
+          rescue JSON::ParserError
+            # Skip lines that aren't valid JSON
+          end
+        end
+      end
+
+      def process_remaining_buffer
+        event_type = nil
+        data_json = nil
+
+        @buffer.split("\n").each do |line|
+          if line.start_with?("event: ")
+            event_type = line.sub(/^event: /, "").strip
+          elsif line.start_with?("data: ")
+            data_json = line.sub(/^data: /, "").strip
+          end
+        end
+
+        return if data_json.nil?
+
+        begin
+          data = JSON.parse(data_json)
+          yield(event_type, data)
+        rescue JSON::ParserError
+          # Skip lines that aren't valid JSON
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/parameter_converter.rb

@@ -75,6 +75,8 @@ module Exa
         when :include_domains then :includeDomains
         when :exclude_domains then :excludeDomains
         when :system_prompt then :systemPrompt
+        when :previous_run_id then :previousRunId
+        when :data_sources then :dataSources
         else
           key
         end

data/lib/exa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exa
-  VERSION = "0.11.2"
+  VERSION = "0.12.0"
 end

data/lib/exa.rb

@@ -12,6 +12,9 @@ require_relative "exa/resources/find_similar_result"
 require_relative "exa/resources/contents_result"
 require_relative "exa/resources/research_task"
 require_relative "exa/resources/research_list"
+require_relative "exa/resources/agent_run"
+require_relative "exa/resources/agent_run_list"
+require_relative "exa/resources/agent_run_event_list"
 require_relative "exa/resources/answer"
 require_relative "exa/resources/context_result"
 require_relative "exa/resources/webset_collection"
@@ -32,6 +35,13 @@ require_relative "exa/services/get_contents"
 require_relative "exa/services/research_get"
 require_relative "exa/services/research_start"
 require_relative "exa/services/research_list"
+require_relative "exa/services/agent_run_create"
+require_relative "exa/services/agent_run_stream"
+require_relative "exa/services/agent_run_get"
+require_relative "exa/services/agent_run_list"
+require_relative "exa/services/agent_run_cancel"
+require_relative "exa/services/agent_run_delete"
+require_relative "exa/services/agent_run_events"
 require_relative "exa/services/answer"
 require_relative "exa/services/answer_stream"
 require_relative "exa/services/context"
@@ -74,6 +84,7 @@ require_relative "exa/cli/formatters/webset_search_formatter"
 require_relative "exa/cli/formatters/context_formatter"
 require_relative "exa/cli/formatters/contents_formatter"
 require_relative "exa/cli/formatters/research_formatter"
+require_relative "exa/cli/formatters/agent_run_formatter"
 require_relative "exa/cli/formatters/answer_formatter"
 require_relative "exa/cli/formatters/webset_formatter"
 require_relative "exa/cli/formatters/webset_item_formatter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.12.0
 platform: ruby
 authors:
 - Benjamin Jackson
@@ -146,6 +146,12 @@ files:
 - LICENSE
 - README.md
 - exe/exa-ai
+- exe/exa-ai-agent-run-cancel
+- exe/exa-ai-agent-run-create
+- exe/exa-ai-agent-run-delete
+- exe/exa-ai-agent-run-events
+- exe/exa-ai-agent-run-get
+- exe/exa-ai-agent-run-list
 - exe/exa-ai-answer
 - exe/exa-ai-context
 - exe/exa-ai-enrichment-cancel
@@ -188,6 +194,7 @@ files:
 - lib/exa.rb
 - lib/exa/cli/base.rb
 - lib/exa/cli/error_handler.rb
+- lib/exa/cli/formatters/agent_run_formatter.rb
 - lib/exa/cli/formatters/answer_formatter.rb
 - lib/exa/cli/formatters/contents_formatter.rb
 - lib/exa/cli/formatters/context_formatter.rb
@@ -207,6 +214,9 @@ files:
 - lib/exa/constants/websets.rb
 - lib/exa/error.rb
 - lib/exa/middleware/raise_error.rb
+- lib/exa/resources/agent_run.rb
+- lib/exa/resources/agent_run_event_list.rb
+- lib/exa/resources/agent_run_list.rb
 - lib/exa/resources/answer.rb
 - lib/exa/resources/contents_result.rb
 - lib/exa/resources/context_result.rb
@@ -226,6 +236,13 @@ files:
 - lib/exa/resources/webset_enrichment_collection.rb
 - lib/exa/resources/webset_item_collection.rb
 - lib/exa/resources/webset_search.rb
+- lib/exa/services/agent_run_cancel.rb
+- lib/exa/services/agent_run_create.rb
+- lib/exa/services/agent_run_delete.rb
+- lib/exa/services/agent_run_events.rb
+- lib/exa/services/agent_run_get.rb
+- lib/exa/services/agent_run_list.rb
+- lib/exa/services/agent_run_stream.rb
 - lib/exa/services/answer.rb
 - lib/exa/services/answer_stream.rb
 - lib/exa/services/context.rb