cerca 0.1.0 → 0.2.0

data/lib/cerca.rb

@@ -64,8 +64,11 @@ require_relative "cerca/internal/grants_cursor_page"
 require_relative "cerca/internal/results_cursor_page"
 require_relative "cerca/internal/sources_cursor_page"
 require_relative "cerca/internal/subscriptions_cursor_page"
+require_relative "cerca/internal/thread_messages_cursor_page"
 require_relative "cerca/internal/threads_cursor_page"
+require_relative "cerca/models/activity_summary"
 require_relative "cerca/models/connection"
+require_relative "cerca/models/activity_detail"
 require_relative "cerca/models/agent"
 require_relative "cerca/models/agent_create_params"
 require_relative "cerca/models/agent_delete_params"
@@ -143,6 +146,7 @@ require_relative "cerca/models/json_object"
 require_relative "cerca/models/mcp_tool_execution_policy"
 require_relative "cerca/models/mcp_tool_source"
 require_relative "cerca/models/message"
+require_relative "cerca/models/message_page"
 require_relative "cerca/models/metadata"
 require_relative "cerca/models/model_descriptor"
 require_relative "cerca/models/model_list_params"
@@ -176,16 +180,19 @@ require_relative "cerca/models/steer_result"
 require_relative "cerca/models/subscription_event"
 require_relative "cerca/models/sub_thread_summary"
 require_relative "cerca/models/thread"
+require_relative "cerca/models/thread_activity_params"
 require_relative "cerca/models/thread_cancel_params"
 require_relative "cerca/models/thread_close_params"
 require_relative "cerca/models/thread_compact_params"
 require_relative "cerca/models/thread_create_params"
+require_relative "cerca/models/thread_list_messages_params"
 require_relative "cerca/models/thread_list_params"
 require_relative "cerca/models/thread_retrieve_params"
 require_relative "cerca/models/thread_start_turn_params"
 require_relative "cerca/models/thread_steer_params"
 require_relative "cerca/models/thread_stream_event"
 require_relative "cerca/models/thread_summary"
+require_relative "cerca/models/thread_turn_summary"
 require_relative "cerca/models/token_usage"
 require_relative "cerca/models/tool"
 require_relative "cerca/models/tool_approval_mode"

data/rbi/cerca/internal/thread_messages_cursor_page.rbi

@@ -0,0 +1,25 @@
+# typed: strong
+
+module Cerca
+  module Internal
+    class ThreadMessagesCursorPage
+      include Cerca::Internal::Type::BasePage
+
+      Elem = type_member
+
+      sig { returns(T.nilable(T::Array[Elem])) }
+      attr_accessor :messages
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :cursor
+
+      sig { returns(T::Boolean) }
+      attr_accessor :has_more
+
+      # @api private
+      sig { returns(String) }
+      def inspect
+      end
+    end
+  end
+end

data/rbi/cerca/models/activity_detail.rbi

@@ -0,0 +1,36 @@
+# typed: strong
+
+module Cerca
+  module Models
+    class ActivityDetail < Cerca::Models::ActivitySummary
+      OrHash =
+        T.type_alias { T.any(Cerca::ActivityDetail, Cerca::Internal::AnyHash) }
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :error
+
+      sig { returns(T::Array[Cerca::ThreadTurnSummary]) }
+      attr_accessor :recent_turns
+
+      sig do
+        params(
+          error: T.nilable(String),
+          recent_turns: T::Array[Cerca::ThreadTurnSummary::OrHash]
+        ).returns(T.attached_class)
+      end
+      def self.new(error:, recent_turns:)
+      end
+
+      sig do
+        override.returns(
+          {
+            error: T.nilable(String),
+            recent_turns: T::Array[Cerca::ThreadTurnSummary]
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/cerca/models/activity_summary.rbi

@@ -0,0 +1,117 @@
+# typed: strong
+
+module Cerca
+  module Models
+    class ActivitySummary < Cerca::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias { T.any(Cerca::ActivitySummary, Cerca::Internal::AnyHash) }
+
+      sig { returns(String) }
+      attr_accessor :id
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :completed_at
+
+      sig { returns(String) }
+      attr_accessor :created_at
+
+      sig { returns(String) }
+      attr_accessor :goal
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :latest_activity
+
+      sig { returns(Float) }
+      attr_accessor :message_count
+
+      sig { returns(String) }
+      attr_accessor :model
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :next_step
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :parent_thread_id
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :result
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :schedule_id
+
+      # `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.
+      sig { returns(Cerca::Status::TaggedSymbol) }
+      attr_accessor :status
+
+      sig { returns(Float) }
+      attr_accessor :step_count
+
+      sig { returns(String) }
+      attr_accessor :updated_at
+
+      sig do
+        params(
+          id: String,
+          completed_at: T.nilable(String),
+          created_at: String,
+          goal: String,
+          latest_activity: T.nilable(String),
+          message_count: Float,
+          model: String,
+          next_step: T.nilable(String),
+          parent_thread_id: T.nilable(String),
+          result: T.nilable(String),
+          schedule_id: T.nilable(String),
+          status: Cerca::Status::OrSymbol,
+          step_count: Float,
+          updated_at: String
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        id:,
+        completed_at:,
+        created_at:,
+        goal:,
+        latest_activity:,
+        message_count:,
+        model:,
+        next_step:,
+        parent_thread_id:,
+        result:,
+        schedule_id:,
+        # `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.
+        status:,
+        step_count:,
+        updated_at:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            id: String,
+            completed_at: T.nilable(String),
+            created_at: String,
+            goal: String,
+            latest_activity: T.nilable(String),
+            message_count: Float,
+            model: String,
+            next_step: T.nilable(String),
+            parent_thread_id: T.nilable(String),
+            result: T.nilable(String),
+            schedule_id: T.nilable(String),
+            status: Cerca::Status::TaggedSymbol,
+            step_count: Float,
+            updated_at: String
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/cerca/models/message_page.rbi

@@ -0,0 +1,41 @@
+# typed: strong
+
+module Cerca
+  module Models
+    class MessagePage < Cerca::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias { T.any(Cerca::MessagePage, Cerca::Internal::AnyHash) }
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :cursor
+
+      sig { returns(T::Boolean) }
+      attr_accessor :has_more
+
+      sig { returns(T::Array[Cerca::Message]) }
+      attr_accessor :messages
+
+      sig do
+        params(
+          cursor: T.nilable(String),
+          has_more: T::Boolean,
+          messages: T::Array[Cerca::Message::OrHash]
+        ).returns(T.attached_class)
+      end
+      def self.new(cursor:, has_more:, messages:)
+      end
+
+      sig do
+        override.returns(
+          {
+            cursor: T.nilable(String),
+            has_more: T::Boolean,
+            messages: T::Array[Cerca::Message]
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/cerca/models/thread.rbi

@@ -31,6 +31,9 @@ module Cerca
       sig { returns(T.nilable(String)) }
       attr_accessor :error
 
+      sig { returns(T::Boolean) }
+      attr_accessor :has_more_messages
+
       sig { returns(T.nilable(String)) }
       attr_accessor :instructions
 
@@ -40,6 +43,9 @@ module Cerca
       sig { returns(String) }
       attr_accessor :message
 
+      sig { returns(T.nilable(Float)) }
+      attr_accessor :message_cursor
+
       sig { returns(T::Array[Cerca::Message]) }
       attr_accessor :messages
 
@@ -95,9 +101,11 @@ module Cerca
           created_at: String,
           depth: Float,
           error: T.nilable(String),
+          has_more_messages: T::Boolean,
           instructions: T.nilable(String),
           last_turn_status: T.nilable(Cerca::Thread::LastTurnStatus::OrSymbol),
           message: String,
+          message_cursor: T.nilable(Float),
           messages: T::Array[Cerca::Message::OrHash],
           model: String,
           parent_thread_id: T.nilable(String),
@@ -120,9 +128,11 @@ module Cerca
         created_at:,
         depth:,
         error:,
+        has_more_messages:,
         instructions:,
         last_turn_status:,
         message:,
+        message_cursor:,
         messages:,
         model:,
         parent_thread_id:,
@@ -151,10 +161,12 @@ module Cerca
             created_at: String,
             depth: Float,
             error: T.nilable(String),
+            has_more_messages: T::Boolean,
             instructions: T.nilable(String),
             last_turn_status:
               T.nilable(Cerca::Thread::LastTurnStatus::TaggedSymbol),
             message: String,
+            message_cursor: T.nilable(Float),
             messages: T::Array[Cerca::Message],
             model: String,
             parent_thread_id: T.nilable(String),

data/rbi/cerca/models/thread_activity_params.rbi

@@ -0,0 +1,58 @@
+# typed: strong
+
+module Cerca
+  module Models
+    class ThreadActivityParams < Cerca::Internal::Type::BaseModel
+      extend Cerca::Internal::Type::RequestParameters::Converter
+      include Cerca::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(Cerca::ThreadActivityParams, Cerca::Internal::AnyHash)
+        end
+
+      sig { returns(String) }
+      attr_accessor :agent_id
+
+      sig { returns(String) }
+      attr_accessor :thread_id
+
+      # Optional fleet id for index-backed authorization.
+      sig { returns(T.nilable(String)) }
+      attr_reader :fleet_id
+
+      sig { params(fleet_id: String).void }
+      attr_writer :fleet_id
+
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          fleet_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        agent_id:,
+        thread_id:,
+        # Optional fleet id for index-backed authorization.
+        fleet_id: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            agent_id: String,
+            thread_id: String,
+            fleet_id: String,
+            request_options: Cerca::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/cerca/models/thread_list_messages_params.rbi

@@ -0,0 +1,80 @@
+# typed: strong
+
+module Cerca
+  module Models
+    class ThreadListMessagesParams < Cerca::Internal::Type::BaseModel
+      extend Cerca::Internal::Type::RequestParameters::Converter
+      include Cerca::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(Cerca::ThreadListMessagesParams, Cerca::Internal::AnyHash)
+        end
+
+      sig { returns(String) }
+      attr_accessor :agent_id
+
+      sig { returns(String) }
+      attr_accessor :thread_id
+
+      # Cursor returned by a previous thread messages response.
+      sig { returns(T.nilable(String)) }
+      attr_reader :cursor
+
+      sig { params(cursor: String).void }
+      attr_writer :cursor
+
+      # Optional fleet id for index-backed authorization.
+      sig { returns(T.nilable(String)) }
+      attr_reader :fleet_id
+
+      sig { params(fleet_id: String).void }
+      attr_writer :fleet_id
+
+      # Maximum number of messages to include, capped at 500.
+      sig { returns(T.nilable(String)) }
+      attr_reader :limit
+
+      sig { params(limit: String).void }
+      attr_writer :limit
+
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          cursor: String,
+          fleet_id: String,
+          limit: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        agent_id:,
+        thread_id:,
+        # Cursor returned by a previous thread messages response.
+        cursor: nil,
+        # Optional fleet id for index-backed authorization.
+        fleet_id: nil,
+        # Maximum number of messages to include, capped at 500.
+        limit: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            agent_id: String,
+            thread_id: String,
+            cursor: String,
+            fleet_id: String,
+            limit: String,
+            request_options: Cerca::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/cerca/models/thread_retrieve_params.rbi

@@ -24,7 +24,9 @@ module Cerca
       sig { params(debug: Cerca::ThreadRetrieveParams::Debug::OrSymbol).void }
       attr_writer :debug
 
-      # 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.
       sig do
         returns(
           T.nilable(Cerca::ThreadRetrieveParams::IncludeMessages::OrSymbol)
@@ -55,7 +57,9 @@ module Cerca
         thread_id:,
         # When true, includes debug-only compiled context fields.
         debug: nil,
-        # 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.
         include_messages: nil,
         request_options: {}
       )
@@ -96,7 +100,9 @@ module Cerca
         end
       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/rbi/cerca/models/thread_turn_summary.rbi

@@ -0,0 +1,85 @@
+# typed: strong
+
+module Cerca
+  module Models
+    class ThreadTurnSummary < Cerca::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Cerca::ThreadTurnSummary, Cerca::Internal::AnyHash)
+        end
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :activity
+
+      sig { returns(String) }
+      attr_accessor :completed_at
+
+      sig { returns(Float) }
+      attr_accessor :message_count
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :next_step
+
+      sig { returns(Cerca::ThreadTurnSummary::Status::TaggedSymbol) }
+      attr_accessor :status
+
+      sig { returns(Float) }
+      attr_accessor :turn_seq
+
+      sig do
+        params(
+          activity: T.nilable(String),
+          completed_at: String,
+          message_count: Float,
+          next_step: T.nilable(String),
+          status: Cerca::ThreadTurnSummary::Status::OrSymbol,
+          turn_seq: Float
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        activity:,
+        completed_at:,
+        message_count:,
+        next_step:,
+        status:,
+        turn_seq:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            activity: T.nilable(String),
+            completed_at: String,
+            message_count: Float,
+            next_step: T.nilable(String),
+            status: Cerca::ThreadTurnSummary::Status::TaggedSymbol,
+            turn_seq: Float
+          }
+        )
+      end
+      def to_hash
+      end
+
+      module Status
+        extend Cerca::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, Cerca::ThreadTurnSummary::Status) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        COMPLETED =
+          T.let(:completed, Cerca::ThreadTurnSummary::Status::TaggedSymbol)
+        FAILED = T.let(:failed, Cerca::ThreadTurnSummary::Status::TaggedSymbol)
+
+        sig do
+          override.returns(
+            T::Array[Cerca::ThreadTurnSummary::Status::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/cerca/models.rbi

@@ -1,6 +1,10 @@
 # typed: strong
 
 module Cerca
+  ActivityDetail = Cerca::Models::ActivityDetail
+
+  ActivitySummary = Cerca::Models::ActivitySummary
+
   Agent = Cerca::Models::Agent
 
   AgentCreateParams = Cerca::Models::AgentCreateParams
@@ -143,6 +147,8 @@ module Cerca
 
   Message = Cerca::Models::Message
 
+  MessagePage = Cerca::Models::MessagePage
+
   Metadata = T.let(Cerca::Models::Metadata, Cerca::Internal::Type::Converter)
 
   ModelDescriptor = Cerca::Models::ModelDescriptor
@@ -199,6 +205,8 @@ module Cerca
 
   Thread = Cerca::Models::Thread
 
+  ThreadActivityParams = Cerca::Models::ThreadActivityParams
+
   ThreadCancelParams = Cerca::Models::ThreadCancelParams
 
   ThreadCloseParams = Cerca::Models::ThreadCloseParams
@@ -207,6 +215,8 @@ module Cerca
 
   ThreadCreateParams = Cerca::Models::ThreadCreateParams
 
+  ThreadListMessagesParams = Cerca::Models::ThreadListMessagesParams
+
   ThreadListParams = Cerca::Models::ThreadListParams
 
   ThreadRetrieveParams = Cerca::Models::ThreadRetrieveParams
@@ -219,6 +229,8 @@ module Cerca
 
   ThreadSummary = Cerca::Models::ThreadSummary
 
+  ThreadTurnSummary = Cerca::Models::ThreadTurnSummary
+
   TokenUsage = Cerca::Models::TokenUsage
 
   Tool = Cerca::Models::Tool

data/rbi/cerca/resources/threads.rbi

@@ -46,7 +46,9 @@ module Cerca
         thread_id,
         # When true, includes debug-only compiled context fields.
         debug: nil,
-        # 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.
         include_messages: nil,
         request_options: {}
       )
@@ -78,6 +80,25 @@ module Cerca
       )
       end
 
+      # Fetch compact current and recent activity for a thread without returning
+      # transcript content or runtime debug state.
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          fleet_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::ActivityDetail)
+      end
+      def activity(
+        agent_id,
+        thread_id,
+        # Optional fleet id for index-backed authorization.
+        fleet_id: nil,
+        request_options: {}
+      )
+      end
+
       # Cancel a running or awaiting thread. The underlying runtime treats repeat
       # cancellation as an idempotent lifecycle operation when possible.
       sig do
@@ -114,6 +135,31 @@ module Cerca
       def compact(agent_id, thread_id, request_options: {})
       end
 
+      # List a bounded page of transcript messages for a thread, newest first. Use the
+      # returned `cursor` to page older messages.
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          cursor: String,
+          fleet_id: String,
+          limit: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::Internal::ThreadMessagesCursorPage[Cerca::Message])
+      end
+      def list_messages(
+        agent_id,
+        thread_id,
+        # Cursor returned by a previous thread messages response.
+        cursor: nil,
+        # Optional fleet id for index-backed authorization.
+        fleet_id: nil,
+        # Maximum number of messages to include, capped at 500.
+        limit: nil,
+        request_options: {}
+      )
+      end
+
       # Create turn
       sig do
         params(