cerca 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4105a30061dd7ad4df09964a615a087383ee820e3f6a3538e45df24e1cf39bb9
-  data.tar.gz: 3a0a7c8c07f1d41c2dcb807a235636e8b9ba1c5982b6dcfd669db906a872c01f
+  metadata.gz: ae67561fdcf585399edfd6d08ffa7fe50da0397ace860d689127c2c011dcedde
+  data.tar.gz: 2841db8fd1be916786257f520cf1bc29463612b6e77b3994bab6130203c2caa9
 SHA512:
-  metadata.gz: f9abf94846e11a5073a0567c791524e2b093fad9d66b0b0e2e7aa8da7e40ffcd152dfe1d063c5df10063a6704c2ff7ecb5dd07fbeecd713351c5cb65fb431e94
-  data.tar.gz: 50e520040a0a487d174fc748c0b2bd4da77178f1aee35db844209606245082ad7ee2e4e59134f09efb8f3b33213b12cfd12fd9638befef2b657ce783e1a3c2bd
+  metadata.gz: ad22af0e4917d74a3be488dcbc666b25225b43318bf9ce45233b90ae21f5ba3a09b45114e95742ab305d14175db6d7eecedbd385a4d99ff3d135da47d9b916f9
+  data.tar.gz: 8a82636af422680b0a5c5c422cf7fe57a52c8304b542ddbc6f86195d697d993583e7735ae0fdebbaba69459c6e1af898fa83d547daa29d901c7ee90673601e7f

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0 (2026-05-07)
+
+Full Changelog: [v0.1.0...v0.2.0](https://github.com/matrices/cerca-ruby/compare/v0.1.0...v0.2.0)
+
+### Features
+
+* **api:** api update ([c593d9c](https://github.com/matrices/cerca-ruby/commit/c593d9c928b6ca0e614cd7c241b3b7bc555fcb12))
+
 ## 0.1.0 (2026-05-01)
 
 Full Changelog: [v0.0.1...v0.1.0](https://github.com/matrices/cerca-ruby/compare/v0.0.1...v0.1.0)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "cerca", "~> 0.1.0"
+gem "cerca", "~> 0.2.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/cerca/internal/thread_messages_cursor_page.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Cerca
+  module Internal
+    # @generic Elem
+    #
+    # @example
+    #   if thread_messages_cursor_page.has_next?
+    #     thread_messages_cursor_page = thread_messages_cursor_page.next_page
+    #   end
+    #
+    # @example
+    #   thread_messages_cursor_page.auto_paging_each do |thread|
+    #     puts(thread)
+    #   end
+    class ThreadMessagesCursorPage
+      include Cerca::Internal::Type::BasePage
+
+      # @return [Array<generic<Elem>>, nil]
+      attr_accessor :messages
+
+      # @return [String, nil]
+      attr_accessor :cursor
+
+      # @return [Boolean]
+      attr_accessor :has_more
+
+      # @return [Boolean]
+      def next_page?
+        has_more
+      end
+
+      # @raise [Cerca::HTTP::Error]
+      # @return [self]
+      def next_page
+        unless next_page?
+          message = "No more pages available. Please check #next_page? before calling ##{__method__}"
+          raise RuntimeError.new(message)
+        end
+
+        req = Cerca::Internal::Util.deep_merge(@req, {query: {cursor: cursor}})
+        @client.request(req)
+      end
+
+      # @param blk [Proc]
+      #
+      # @yieldparam [generic<Elem>]
+      def auto_paging_each(&blk)
+        unless block_given?
+          raise ArgumentError.new("A block must be given to ##{__method__}")
+        end
+
+        page = self
+        loop do
+          page.messages&.each(&blk)
+
+          break unless page.next_page?
+          page = page.next_page
+        end
+      end
+
+      # @api private
+      #
+      # @param client [Cerca::Internal::Transport::BaseClient]
+      # @param req [Hash{Symbol=>Object}]
+      # @param headers [Hash{String=>String}]
+      # @param page_data [Hash{Symbol=>Object}]
+      def initialize(client:, req:, headers:, page_data:)
+        super
+
+        case page_data
+        in {messages: Array => messages}
+          @messages = messages.map { Cerca::Internal::Type::Converter.coerce(@model, _1) }
+        else
+        end
+        @cursor = page_data[:cursor]
+        @has_more = page_data[:hasMore]
+      end
+
+      # @api private
+      #
+      # @return [String]
+      def inspect
+        # rubocop:disable Layout/LineLength
+        model = Cerca::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)} cursor=#{cursor.inspect} has_more=#{has_more.inspect}>"
+        # rubocop:enable Layout/LineLength
+      end
+    end
+  end
+end

data/lib/cerca/models/activity_detail.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cerca
+  module Models
+    # @see Cerca::Resources::Threads#activity
+    class ActivityDetail < Cerca::Models::ActivitySummary
+      # @!attribute error
+      #
+      #   @return [String, nil]
+      required :error, String, nil?: true
+
+      # @!attribute recent_turns
+      #
+      #   @return [Array<Cerca::Models::ThreadTurnSummary>]
+      required :recent_turns,
+               -> { Cerca::Internal::Type::ArrayOf[Cerca::ThreadTurnSummary] },
+               api_name: :recentTurns
+
+      # @!method initialize(error:, recent_turns:)
+      #   @param error [String, nil]
+      #   @param recent_turns [Array<Cerca::Models::ThreadTurnSummary>]
+    end
+  end
+end

data/lib/cerca/models/activity_summary.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Cerca
+  module Models
+    class ActivitySummary < Cerca::Internal::Type::BaseModel
+      # @!attribute id
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!attribute completed_at
+      #
+      #   @return [String, nil]
+      required :completed_at, String, api_name: :completedAt, nil?: true
+
+      # @!attribute created_at
+      #
+      #   @return [String]
+      required :created_at, String, api_name: :createdAt
+
+      # @!attribute goal
+      #
+      #   @return [String]
+      required :goal, String
+
+      # @!attribute latest_activity
+      #
+      #   @return [String, nil]
+      required :latest_activity, String, api_name: :latestActivity, nil?: true
+
+      # @!attribute message_count
+      #
+      #   @return [Float]
+      required :message_count, Float, api_name: :messageCount
+
+      # @!attribute model
+      #
+      #   @return [String]
+      required :model, String
+
+      # @!attribute next_step
+      #
+      #   @return [String, nil]
+      required :next_step, String, api_name: :nextStep, nil?: true
+
+      # @!attribute parent_thread_id
+      #
+      #   @return [String, nil]
+      required :parent_thread_id, String, api_name: :parentThreadId, nil?: true
+
+      # @!attribute result
+      #
+      #   @return [String, nil]
+      required :result, String, nil?: true
+
+      # @!attribute schedule_id
+      #
+      #   @return [String, nil]
+      required :schedule_id, String, api_name: :scheduleId, nil?: true
+
+      # @!attribute status
+      #   `idle` threads can accept a new turn or be closed. `running` threads have an
+      #   active turn. `awaiting` threads are paused on external input such as approvals.
+      #   `closed` threads are terminal.
+      #
+      #   @return [Symbol, Cerca::Models::Status]
+      required :status, enum: -> { Cerca::Status }
+
+      # @!attribute step_count
+      #
+      #   @return [Float]
+      required :step_count, Float, api_name: :stepCount
+
+      # @!attribute updated_at
+      #
+      #   @return [String]
+      required :updated_at, String, api_name: :updatedAt
+
+      # @!method initialize(id:, completed_at:, created_at:, goal:, latest_activity:, message_count:, model:, next_step:, parent_thread_id:, result:, schedule_id:, status:, step_count:, updated_at:)
+      #   Some parameter documentations has been truncated, see
+      #   {Cerca::Models::ActivitySummary} for more details.
+      #
+      #   @param id [String]
+      #
+      #   @param completed_at [String, nil]
+      #
+      #   @param created_at [String]
+      #
+      #   @param goal [String]
+      #
+      #   @param latest_activity [String, nil]
+      #
+      #   @param message_count [Float]
+      #
+      #   @param model [String]
+      #
+      #   @param next_step [String, nil]
+      #
+      #   @param parent_thread_id [String, nil]
+      #
+      #   @param result [String, nil]
+      #
+      #   @param schedule_id [String, nil]
+      #
+      #   @param status [Symbol, Cerca::Models::Status] `idle` threads can accept a new turn or be closed. `running` threads have an act
+      #
+      #   @param step_count [Float]
+      #
+      #   @param updated_at [String]
+    end
+  end
+end

data/lib/cerca/models/message.rb

@@ -2,6 +2,7 @@
 
 module Cerca
   module Models
+    # @see Cerca::Resources::Threads#list_messages
     class Message < Cerca::Internal::Type::BaseModel
       # @!attribute content
       #

data/lib/cerca/models/message_page.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Cerca
+  module Models
+    class MessagePage < Cerca::Internal::Type::BaseModel
+      # @!attribute cursor
+      #
+      #   @return [String, nil]
+      required :cursor, String, nil?: true
+
+      # @!attribute has_more
+      #
+      #   @return [Boolean]
+      required :has_more, Cerca::Internal::Type::Boolean, api_name: :hasMore
+
+      # @!attribute messages
+      #
+      #   @return [Array<Cerca::Models::Message>]
+      required :messages, -> { Cerca::Internal::Type::ArrayOf[Cerca::Message] }
+
+      # @!method initialize(cursor:, has_more:, messages:)
+      #   @param cursor [String, nil]
+      #   @param has_more [Boolean]
+      #   @param messages [Array<Cerca::Models::Message>]
+    end
+  end
+end

data/lib/cerca/models/thread.rb

@@ -39,6 +39,11 @@ module Cerca
       #   @return [String, nil]
       required :error, String, nil?: true
 
+      # @!attribute has_more_messages
+      #
+      #   @return [Boolean]
+      required :has_more_messages, Cerca::Internal::Type::Boolean, api_name: :hasMoreMessages
+
       # @!attribute instructions
       #
       #   @return [String, nil]
@@ -57,6 +62,11 @@ module Cerca
       #   @return [String]
       required :message, String
 
+      # @!attribute message_cursor
+      #
+      #   @return [Float, nil]
+      required :message_cursor, Float, api_name: :messageCursor, nil?: true
+
       # @!attribute messages
       #
       #   @return [Array<Cerca::Models::Message>]
@@ -124,7 +134,7 @@ module Cerca
                union: -> { Cerca::Thread::ExternalToolNamespaces },
                api_name: :externalToolNamespaces
 
-      # @!method initialize(id:, agent_id:, compiled_context:, completed_at:, created_at:, depth:, error:, instructions:, last_turn_status:, message:, messages:, model:, parent_thread_id:, result:, schedule_id:, schedule_seq:, status:, sub_threads:, tools:, turns:, updated_at:, external_tool_namespaces: nil)
+      # @!method initialize(id:, agent_id:, compiled_context:, completed_at:, created_at:, depth:, error:, has_more_messages:, instructions:, last_turn_status:, message:, message_cursor:, messages:, model:, parent_thread_id:, result:, schedule_id:, schedule_seq:, status:, sub_threads:, tools:, turns:, updated_at:, external_tool_namespaces: nil)
       #   Some parameter documentations has been truncated, see {Cerca::Models::Thread}
       #   for more details.
       #
@@ -142,12 +152,16 @@ module Cerca
       #
       #   @param error [String, nil]
       #
+      #   @param has_more_messages [Boolean]
+      #
       #   @param instructions [String, nil]
       #
       #   @param last_turn_status [Symbol, Cerca::Models::Thread::LastTurnStatus, nil]
       #
       #   @param message [String]
       #
+      #   @param message_cursor [Float, nil]
+      #
       #   @param messages [Array<Cerca::Models::Message>]
       #
       #   @param model [String]

data/lib/cerca/models/thread_activity_params.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Cerca
+  module Models
+    # @see Cerca::Resources::Threads#activity
+    class ThreadActivityParams < Cerca::Internal::Type::BaseModel
+      extend Cerca::Internal::Type::RequestParameters::Converter
+      include Cerca::Internal::Type::RequestParameters
+
+      # @!attribute agent_id
+      #
+      #   @return [String]
+      required :agent_id, String
+
+      # @!attribute thread_id
+      #
+      #   @return [String]
+      required :thread_id, String
+
+      # @!attribute fleet_id
+      #   Optional fleet id for index-backed authorization.
+      #
+      #   @return [String, nil]
+      optional :fleet_id, String
+
+      # @!method initialize(agent_id:, thread_id:, fleet_id: nil, request_options: {})
+      #   @param agent_id [String]
+      #
+      #   @param thread_id [String]
+      #
+      #   @param fleet_id [String] Optional fleet id for index-backed authorization.
+      #
+      #   @param request_options [Cerca::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/cerca/models/thread_list_messages_params.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Cerca
+  module Models
+    # @see Cerca::Resources::Threads#list_messages
+    class ThreadListMessagesParams < Cerca::Internal::Type::BaseModel
+      extend Cerca::Internal::Type::RequestParameters::Converter
+      include Cerca::Internal::Type::RequestParameters
+
+      # @!attribute agent_id
+      #
+      #   @return [String]
+      required :agent_id, String
+
+      # @!attribute thread_id
+      #
+      #   @return [String]
+      required :thread_id, String
+
+      # @!attribute cursor
+      #   Cursor returned by a previous thread messages response.
+      #
+      #   @return [String, nil]
+      optional :cursor, String
+
+      # @!attribute fleet_id
+      #   Optional fleet id for index-backed authorization.
+      #
+      #   @return [String, nil]
+      optional :fleet_id, String
+
+      # @!attribute limit
+      #   Maximum number of messages to include, capped at 500.
+      #
+      #   @return [String, nil]
+      optional :limit, String
+
+      # @!method initialize(agent_id:, thread_id:, cursor: nil, fleet_id: nil, limit: nil, request_options: {})
+      #   @param agent_id [String]
+      #
+      #   @param thread_id [String]
+      #
+      #   @param cursor [String] Cursor returned by a previous thread messages response.
+      #
+      #   @param fleet_id [String] Optional fleet id for index-backed authorization.
+      #
+      #   @param limit [String] Maximum number of messages to include, capped at 500.
+      #
+      #   @param request_options [Cerca::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/cerca/models/thread_retrieve_params.rb

@@ -24,19 +24,24 @@ module Cerca
       optional :debug, enum: -> { Cerca::ThreadRetrieveParams::Debug }
 
       # @!attribute include_messages
-      #   When true, includes message content in the thread detail.
+      #   Deprecated compatibility flag. Thread detail includes a bounded recent message
+      #   page by default; pass `false` only to opt out when no message pagination params
+      #   are present.
       #
       #   @return [Symbol, Cerca::Models::ThreadRetrieveParams::IncludeMessages, nil]
       optional :include_messages, enum: -> { Cerca::ThreadRetrieveParams::IncludeMessages }
 
       # @!method initialize(agent_id:, thread_id:, debug: nil, include_messages: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {Cerca::Models::ThreadRetrieveParams} for more details.
+      #
       #   @param agent_id [String]
       #
       #   @param thread_id [String]
       #
       #   @param debug [Symbol, Cerca::Models::ThreadRetrieveParams::Debug] When true, includes debug-only compiled context fields.
       #
-      #   @param include_messages [Symbol, Cerca::Models::ThreadRetrieveParams::IncludeMessages] When true, includes message content in the thread detail.
+      #   @param include_messages [Symbol, Cerca::Models::ThreadRetrieveParams::IncludeMessages] Deprecated compatibility flag. Thread detail includes a bounded recent message p
       #
       #   @param request_options [Cerca::RequestOptions, Hash{Symbol=>Object}]
 
@@ -51,7 +56,9 @@ module Cerca
         #   @return [Array<Symbol>]
       end
 
-      # When true, includes message content in the thread detail.
+      # Deprecated compatibility flag. Thread detail includes a bounded recent message
+      # page by default; pass `false` only to opt out when no message pagination params
+      # are present.
       module IncludeMessages
         extend Cerca::Internal::Type::Enum
 

data/lib/cerca/models/thread_turn_summary.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Cerca
+  module Models
+    class ThreadTurnSummary < Cerca::Internal::Type::BaseModel
+      # @!attribute activity
+      #
+      #   @return [String, nil]
+      required :activity, String, nil?: true
+
+      # @!attribute completed_at
+      #
+      #   @return [String]
+      required :completed_at, String, api_name: :completedAt
+
+      # @!attribute message_count
+      #
+      #   @return [Float]
+      required :message_count, Float, api_name: :messageCount
+
+      # @!attribute next_step
+      #
+      #   @return [String, nil]
+      required :next_step, String, api_name: :nextStep, nil?: true
+
+      # @!attribute status
+      #
+      #   @return [Symbol, Cerca::Models::ThreadTurnSummary::Status]
+      required :status, enum: -> { Cerca::ThreadTurnSummary::Status }
+
+      # @!attribute turn_seq
+      #
+      #   @return [Float]
+      required :turn_seq, Float, api_name: :turnSeq
+
+      # @!method initialize(activity:, completed_at:, message_count:, next_step:, status:, turn_seq:)
+      #   @param activity [String, nil]
+      #   @param completed_at [String]
+      #   @param message_count [Float]
+      #   @param next_step [String, nil]
+      #   @param status [Symbol, Cerca::Models::ThreadTurnSummary::Status]
+      #   @param turn_seq [Float]
+
+      # @see Cerca::Models::ThreadTurnSummary#status
+      module Status
+        extend Cerca::Internal::Type::Enum
+
+        COMPLETED = :completed
+        FAILED = :failed
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/cerca/models.rb

@@ -39,6 +39,10 @@ module Cerca
     mod.define_sorbet_constant!(const) { T.type_alias { mod.to_sorbet_type } }
   end
 
+  ActivityDetail = Cerca::Models::ActivityDetail
+
+  ActivitySummary = Cerca::Models::ActivitySummary
+
   Agent = Cerca::Models::Agent
 
   AgentCreateParams = Cerca::Models::AgentCreateParams
@@ -178,6 +182,8 @@ module Cerca
 
   Message = Cerca::Models::Message
 
+  MessagePage = Cerca::Models::MessagePage
+
   # @type [Cerca::Internal::Type::Converter]
   Metadata = Cerca::Models::Metadata
 
@@ -235,6 +241,8 @@ module Cerca
 
   Thread = Cerca::Models::Thread
 
+  ThreadActivityParams = Cerca::Models::ThreadActivityParams
+
   ThreadCancelParams = Cerca::Models::ThreadCancelParams
 
   ThreadCloseParams = Cerca::Models::ThreadCloseParams
@@ -243,6 +251,8 @@ module Cerca
 
   ThreadCreateParams = Cerca::Models::ThreadCreateParams
 
+  ThreadListMessagesParams = Cerca::Models::ThreadListMessagesParams
+
   ThreadListParams = Cerca::Models::ThreadListParams
 
   ThreadRetrieveParams = Cerca::Models::ThreadRetrieveParams
@@ -255,6 +265,8 @@ module Cerca
 
   ThreadSummary = Cerca::Models::ThreadSummary
 
+  ThreadTurnSummary = Cerca::Models::ThreadTurnSummary
+
   TokenUsage = Cerca::Models::TokenUsage
 
   Tool = Cerca::Models::Tool

data/lib/cerca/resources/threads.rb

@@ -38,6 +38,9 @@ module Cerca
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Cerca::Models::ThreadRetrieveParams} for more details.
+      #
       # Retrieve thread
       #
       # @overload retrieve(agent_id, thread_id, debug: nil, include_messages: nil, request_options: {})
@@ -48,7 +51,7 @@ module Cerca
       #
       # @param debug [Symbol, Cerca::Models::ThreadRetrieveParams::Debug] When true, includes debug-only compiled context fields.
       #
-      # @param include_messages [Symbol, Cerca::Models::ThreadRetrieveParams::IncludeMessages] When true, includes message content in the thread detail.
+      # @param include_messages [Symbol, Cerca::Models::ThreadRetrieveParams::IncludeMessages] Deprecated compatibility flag. Thread detail includes a bounded recent message p
       #
       # @param request_options [Cerca::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -102,6 +105,34 @@ module Cerca
         )
       end
 
+      # Fetch compact current and recent activity for a thread without returning
+      # transcript content or runtime debug state.
+      #
+      # @overload activity(agent_id, thread_id, fleet_id: nil, request_options: {})
+      #
+      # @param agent_id [String]
+      #
+      # @param thread_id [String]
+      #
+      # @param fleet_id [String] Optional fleet id for index-backed authorization.
+      #
+      # @param request_options [Cerca::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Cerca::Models::ActivityDetail]
+      #
+      # @see Cerca::Models::ThreadActivityParams
+      def activity(agent_id, thread_id, params = {})
+        parsed, options = Cerca::ThreadActivityParams.dump_request(params)
+        query = Cerca::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["agents/%1$s/threads/%2$s/activity", agent_id, thread_id],
+          query: query.transform_keys(fleet_id: "fleetId"),
+          model: Cerca::ActivityDetail,
+          options: options
+        )
+      end
+
       # Cancel a running or awaiting thread. The underlying runtime treats repeat
       # cancellation as an idempotent lifecycle operation when possible.
       #
@@ -165,6 +196,39 @@ module Cerca
         )
       end
 
+      # List a bounded page of transcript messages for a thread, newest first. Use the
+      # returned `cursor` to page older messages.
+      #
+      # @overload list_messages(agent_id, thread_id, cursor: nil, fleet_id: nil, limit: nil, request_options: {})
+      #
+      # @param agent_id [String]
+      #
+      # @param thread_id [String]
+      #
+      # @param cursor [String] Cursor returned by a previous thread messages response.
+      #
+      # @param fleet_id [String] Optional fleet id for index-backed authorization.
+      #
+      # @param limit [String] Maximum number of messages to include, capped at 500.
+      #
+      # @param request_options [Cerca::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Cerca::Internal::ThreadMessagesCursorPage<Cerca::Models::Message>]
+      #
+      # @see Cerca::Models::ThreadListMessagesParams
+      def list_messages(agent_id, thread_id, params = {})
+        parsed, options = Cerca::ThreadListMessagesParams.dump_request(params)
+        query = Cerca::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["agents/%1$s/threads/%2$s/messages", agent_id, thread_id],
+          query: query.transform_keys(fleet_id: "fleetId"),
+          page: Cerca::Internal::ThreadMessagesCursorPage,
+          model: Cerca::Message,
+          options: options
+        )
+      end
+
       # Some parameter documentations has been truncated, see
       # {Cerca::Models::ThreadStartTurnParams} for more details.
       #

data/lib/cerca/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cerca
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end