stagehand 0.0.3 → 3.5.2

data/lib/stagehand/models/session_act_response.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Stagehand
+  module Models
+    # @see Stagehand::Resources::Sessions#act
+    #
+    # @see Stagehand::Resources::Sessions#act_streaming
+    class SessionActResponse < Stagehand::Internal::Type::BaseModel
+      # @!attribute data
+      #
+      #   @return [Stagehand::Models::SessionActResponse::Data]
+      required :data, -> { Stagehand::Models::SessionActResponse::Data }
+
+      # @!attribute success
+      #   Indicates whether the request was successful
+      #
+      #   @return [Boolean]
+      required :success, Stagehand::Internal::Type::Boolean
+
+      # @!method initialize(data:, success:)
+      #   @param data [Stagehand::Models::SessionActResponse::Data]
+      #
+      #   @param success [Boolean] Indicates whether the request was successful
+
+      # @see Stagehand::Models::SessionActResponse#data
+      class Data < Stagehand::Internal::Type::BaseModel
+        # @!attribute result
+        #
+        #   @return [Stagehand::Models::SessionActResponse::Data::Result]
+        required :result, -> { Stagehand::Models::SessionActResponse::Data::Result }
+
+        # @!attribute action_id
+        #   Action ID for tracking
+        #
+        #   @return [String, nil]
+        optional :action_id, String, api_name: :actionId
+
+        # @!method initialize(result:, action_id: nil)
+        #   @param result [Stagehand::Models::SessionActResponse::Data::Result]
+        #
+        #   @param action_id [String] Action ID for tracking
+
+        # @see Stagehand::Models::SessionActResponse::Data#result
+        class Result < Stagehand::Internal::Type::BaseModel
+          # @!attribute action_description
+          #   Description of the action that was performed
+          #
+          #   @return [String]
+          required :action_description, String, api_name: :actionDescription
+
+          # @!attribute actions
+          #   List of actions that were executed
+          #
+          #   @return [Array<Stagehand::Models::SessionActResponse::Data::Result::Action>]
+          required :actions,
+                   -> { Stagehand::Internal::Type::ArrayOf[Stagehand::Models::SessionActResponse::Data::Result::Action] }
+
+          # @!attribute message
+          #   Human-readable result message
+          #
+          #   @return [String]
+          required :message, String
+
+          # @!attribute success
+          #   Whether the action completed successfully
+          #
+          #   @return [Boolean]
+          required :success, Stagehand::Internal::Type::Boolean
+
+          # @!method initialize(action_description:, actions:, message:, success:)
+          #   @param action_description [String] Description of the action that was performed
+          #
+          #   @param actions [Array<Stagehand::Models::SessionActResponse::Data::Result::Action>] List of actions that were executed
+          #
+          #   @param message [String] Human-readable result message
+          #
+          #   @param success [Boolean] Whether the action completed successfully
+
+          class Action < Stagehand::Internal::Type::BaseModel
+            # @!attribute description
+            #   Human-readable description of the action
+            #
+            #   @return [String]
+            required :description, String
+
+            # @!attribute selector
+            #   CSS selector or XPath for the element
+            #
+            #   @return [String]
+            required :selector, String
+
+            # @!attribute arguments
+            #   Arguments to pass to the method
+            #
+            #   @return [Array<String>, nil]
+            optional :arguments, Stagehand::Internal::Type::ArrayOf[String]
+
+            # @!attribute backend_node_id
+            #   Backend node ID for the element
+            #
+            #   @return [Float, nil]
+            optional :backend_node_id, Float, api_name: :backendNodeId
+
+            # @!attribute method_
+            #   The method to execute (click, fill, etc.)
+            #
+            #   @return [String, nil]
+            optional :method_, String, api_name: :method
+
+            # @!method initialize(description:, selector:, arguments: nil, backend_node_id: nil, method_: nil)
+            #   Action object returned by observe and used by act
+            #
+            #   @param description [String] Human-readable description of the action
+            #
+            #   @param selector [String] CSS selector or XPath for the element
+            #
+            #   @param arguments [Array<String>] Arguments to pass to the method
+            #
+            #   @param backend_node_id [Float] Backend node ID for the element
+            #
+            #   @param method_ [String] The method to execute (click, fill, etc.)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stagehand/models/session_end_params.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Stagehand
+  module Models
+    # @see Stagehand::Resources::Sessions#end_
+    class SessionEndParams < Stagehand::Internal::Type::BaseModel
+      extend Stagehand::Internal::Type::RequestParameters::Converter
+      include Stagehand::Internal::Type::RequestParameters
+
+      # @!attribute x_stream_response
+      #   Whether to stream the response via SSE
+      #
+      #   @return [Symbol, Stagehand::Models::SessionEndParams::XStreamResponse, nil]
+      optional :x_stream_response, enum: -> { Stagehand::SessionEndParams::XStreamResponse }
+
+      # @!method initialize(x_stream_response: nil, request_options: {})
+      #   @param x_stream_response [Symbol, Stagehand::Models::SessionEndParams::XStreamResponse] Whether to stream the response via SSE
+      #
+      #   @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}]
+
+      # Whether to stream the response via SSE
+      module XStreamResponse
+        extend Stagehand::Internal::Type::Enum
+
+        TRUE = :true
+        FALSE = :false
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/stagehand/models/session_end_response.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Stagehand
+  module Models
+    # @see Stagehand::Resources::Sessions#end_
+    class SessionEndResponse < Stagehand::Internal::Type::BaseModel
+      # @!attribute success
+      #   Indicates whether the request was successful
+      #
+      #   @return [Boolean]
+      required :success, Stagehand::Internal::Type::Boolean
+
+      # @!method initialize(success:)
+      #   @param success [Boolean] Indicates whether the request was successful
+    end
+  end
+end

data/lib/stagehand/models/session_execute_params.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Stagehand
+  module Models
+    # @see Stagehand::Resources::Sessions#execute
+    #
+    # @see Stagehand::Resources::Sessions#execute_streaming
+    class SessionExecuteParams < Stagehand::Internal::Type::BaseModel
+      extend Stagehand::Internal::Type::RequestParameters::Converter
+      include Stagehand::Internal::Type::RequestParameters
+
+      # @!attribute agent_config
+      #
+      #   @return [Stagehand::Models::SessionExecuteParams::AgentConfig]
+      required :agent_config, -> { Stagehand::SessionExecuteParams::AgentConfig }, api_name: :agentConfig
+
+      # @!attribute execute_options
+      #
+      #   @return [Stagehand::Models::SessionExecuteParams::ExecuteOptions]
+      required :execute_options,
+               -> { Stagehand::SessionExecuteParams::ExecuteOptions },
+               api_name: :executeOptions
+
+      # @!attribute frame_id
+      #   Target frame ID for the agent
+      #
+      #   @return [String, nil]
+      optional :frame_id, String, api_name: :frameId, nil?: true
+
+      # @!attribute should_cache
+      #   If true, the server captures a cache entry and returns it to the client
+      #
+      #   @return [Boolean, nil]
+      optional :should_cache, Stagehand::Internal::Type::Boolean, api_name: :shouldCache
+
+      # @!attribute x_stream_response
+      #   Whether to stream the response via SSE
+      #
+      #   @return [Symbol, Stagehand::Models::SessionExecuteParams::XStreamResponse, nil]
+      optional :x_stream_response, enum: -> { Stagehand::SessionExecuteParams::XStreamResponse }
+
+      # @!method initialize(agent_config:, execute_options:, frame_id: nil, should_cache: nil, x_stream_response: nil, request_options: {})
+      #   @param agent_config [Stagehand::Models::SessionExecuteParams::AgentConfig]
+      #
+      #   @param execute_options [Stagehand::Models::SessionExecuteParams::ExecuteOptions]
+      #
+      #   @param frame_id [String, nil] Target frame ID for the agent
+      #
+      #   @param should_cache [Boolean] If true, the server captures a cache entry and returns it to the client
+      #
+      #   @param x_stream_response [Symbol, Stagehand::Models::SessionExecuteParams::XStreamResponse] Whether to stream the response via SSE
+      #
+      #   @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}]
+
+      class AgentConfig < Stagehand::Internal::Type::BaseModel
+        # @!attribute cua
+        #   Deprecated. Use mode: 'cua' instead. If both are provided, mode takes
+        #   precedence.
+        #
+        #   @return [Boolean, nil]
+        optional :cua, Stagehand::Internal::Type::Boolean
+
+        # @!attribute execution_model
+        #   Model configuration object or model name string (e.g., 'openai/gpt-5-nano') for
+        #   tool execution (observe/act calls within agent tools). If not specified,
+        #   inherits from the main model configuration.
+        #
+        #   @return [Stagehand::Models::ModelConfig, String, nil]
+        optional :execution_model,
+                 union: -> { Stagehand::SessionExecuteParams::AgentConfig::ExecutionModel },
+                 api_name: :executionModel
+
+        # @!attribute mode
+        #   Tool mode for the agent (dom, hybrid, cua). If set, overrides cua.
+        #
+        #   @return [Symbol, Stagehand::Models::SessionExecuteParams::AgentConfig::Mode, nil]
+        optional :mode, enum: -> { Stagehand::SessionExecuteParams::AgentConfig::Mode }
+
+        # @!attribute model
+        #   Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
+        #
+        #   @return [Stagehand::Models::ModelConfig, String, nil]
+        optional :model, union: -> { Stagehand::SessionExecuteParams::AgentConfig::Model }
+
+        # @!attribute provider
+        #   AI provider for the agent (legacy, use model: openai/gpt-5-nano instead)
+        #
+        #   @return [Symbol, Stagehand::Models::SessionExecuteParams::AgentConfig::Provider, nil]
+        optional :provider, enum: -> { Stagehand::SessionExecuteParams::AgentConfig::Provider }
+
+        # @!attribute system_prompt
+        #   Custom system prompt for the agent
+        #
+        #   @return [String, nil]
+        optional :system_prompt, String, api_name: :systemPrompt
+
+        # @!method initialize(cua: nil, execution_model: nil, mode: nil, model: nil, provider: nil, system_prompt: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Stagehand::Models::SessionExecuteParams::AgentConfig} for more details.
+        #
+        #   @param cua [Boolean] Deprecated. Use mode: 'cua' instead. If both are provided, mode takes precedence
+        #
+        #   @param execution_model [Stagehand::Models::ModelConfig, String] Model configuration object or model name string (e.g., 'openai/gpt-5-nano') for
+        #
+        #   @param mode [Symbol, Stagehand::Models::SessionExecuteParams::AgentConfig::Mode] Tool mode for the agent (dom, hybrid, cua). If set, overrides cua.
+        #
+        #   @param model [Stagehand::Models::ModelConfig, String] Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
+        #
+        #   @param provider [Symbol, Stagehand::Models::SessionExecuteParams::AgentConfig::Provider] AI provider for the agent (legacy, use model: openai/gpt-5-nano instead)
+        #
+        #   @param system_prompt [String] Custom system prompt for the agent
+
+        # Model configuration object or model name string (e.g., 'openai/gpt-5-nano') for
+        # tool execution (observe/act calls within agent tools). If not specified,
+        # inherits from the main model configuration.
+        #
+        # @see Stagehand::Models::SessionExecuteParams::AgentConfig#execution_model
+        module ExecutionModel
+          extend Stagehand::Internal::Type::Union
+
+          variant -> { Stagehand::ModelConfig }
+
+          variant String
+
+          # @!method self.variants
+          #   @return [Array(Stagehand::Models::ModelConfig, String)]
+        end
+
+        # Tool mode for the agent (dom, hybrid, cua). If set, overrides cua.
+        #
+        # @see Stagehand::Models::SessionExecuteParams::AgentConfig#mode
+        module Mode
+          extend Stagehand::Internal::Type::Enum
+
+          DOM = :dom
+          HYBRID = :hybrid
+          CUA = :cua
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
+        # Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
+        #
+        # @see Stagehand::Models::SessionExecuteParams::AgentConfig#model
+        module Model
+          extend Stagehand::Internal::Type::Union
+
+          variant -> { Stagehand::ModelConfig }
+
+          variant String
+
+          # @!method self.variants
+          #   @return [Array(Stagehand::Models::ModelConfig, String)]
+        end
+
+        # AI provider for the agent (legacy, use model: openai/gpt-5-nano instead)
+        #
+        # @see Stagehand::Models::SessionExecuteParams::AgentConfig#provider
+        module Provider
+          extend Stagehand::Internal::Type::Enum
+
+          OPENAI = :openai
+          ANTHROPIC = :anthropic
+          GOOGLE = :google
+          MICROSOFT = :microsoft
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
+      class ExecuteOptions < Stagehand::Internal::Type::BaseModel
+        # @!attribute instruction
+        #   Natural language instruction for the agent
+        #
+        #   @return [String]
+        required :instruction, String
+
+        # @!attribute highlight_cursor
+        #   Whether to visually highlight the cursor during execution
+        #
+        #   @return [Boolean, nil]
+        optional :highlight_cursor, Stagehand::Internal::Type::Boolean, api_name: :highlightCursor
+
+        # @!attribute max_steps
+        #   Maximum number of steps the agent can take
+        #
+        #   @return [Float, nil]
+        optional :max_steps, Float, api_name: :maxSteps
+
+        # @!method initialize(instruction:, highlight_cursor: nil, max_steps: nil)
+        #   @param instruction [String] Natural language instruction for the agent
+        #
+        #   @param highlight_cursor [Boolean] Whether to visually highlight the cursor during execution
+        #
+        #   @param max_steps [Float] Maximum number of steps the agent can take
+      end
+
+      # Whether to stream the response via SSE
+      module XStreamResponse
+        extend Stagehand::Internal::Type::Enum
+
+        TRUE = :true
+        FALSE = :false
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/stagehand/models/session_execute_response.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Stagehand
+  module Models
+    # @see Stagehand::Resources::Sessions#execute
+    #
+    # @see Stagehand::Resources::Sessions#execute_streaming
+    class SessionExecuteResponse < Stagehand::Internal::Type::BaseModel
+      # @!attribute data
+      #
+      #   @return [Stagehand::Models::SessionExecuteResponse::Data]
+      required :data, -> { Stagehand::Models::SessionExecuteResponse::Data }
+
+      # @!attribute success
+      #   Indicates whether the request was successful
+      #
+      #   @return [Boolean]
+      required :success, Stagehand::Internal::Type::Boolean
+
+      # @!method initialize(data:, success:)
+      #   @param data [Stagehand::Models::SessionExecuteResponse::Data]
+      #
+      #   @param success [Boolean] Indicates whether the request was successful
+
+      # @see Stagehand::Models::SessionExecuteResponse#data
+      class Data < Stagehand::Internal::Type::BaseModel
+        # @!attribute result
+        #
+        #   @return [Stagehand::Models::SessionExecuteResponse::Data::Result]
+        required :result, -> { Stagehand::Models::SessionExecuteResponse::Data::Result }
+
+        # @!attribute cache_entry
+        #
+        #   @return [Stagehand::Models::SessionExecuteResponse::Data::CacheEntry, nil]
+        optional :cache_entry,
+                 -> { Stagehand::Models::SessionExecuteResponse::Data::CacheEntry },
+                 api_name: :cacheEntry
+
+        # @!method initialize(result:, cache_entry: nil)
+        #   @param result [Stagehand::Models::SessionExecuteResponse::Data::Result]
+        #   @param cache_entry [Stagehand::Models::SessionExecuteResponse::Data::CacheEntry]
+
+        # @see Stagehand::Models::SessionExecuteResponse::Data#result
+        class Result < Stagehand::Internal::Type::BaseModel
+          # @!attribute actions
+          #
+          #   @return [Array<Stagehand::Models::SessionExecuteResponse::Data::Result::Action>]
+          required :actions,
+                   -> { Stagehand::Internal::Type::ArrayOf[Stagehand::Models::SessionExecuteResponse::Data::Result::Action] }
+
+          # @!attribute completed
+          #   Whether the agent finished its task
+          #
+          #   @return [Boolean]
+          required :completed, Stagehand::Internal::Type::Boolean
+
+          # @!attribute message
+          #   Summary of what the agent accomplished
+          #
+          #   @return [String]
+          required :message, String
+
+          # @!attribute success
+          #   Whether the agent completed successfully
+          #
+          #   @return [Boolean]
+          required :success, Stagehand::Internal::Type::Boolean
+
+          # @!attribute metadata
+          #
+          #   @return [Hash{Symbol=>Object}, nil]
+          optional :metadata, Stagehand::Internal::Type::HashOf[Stagehand::Internal::Type::Unknown]
+
+          # @!attribute usage
+          #
+          #   @return [Stagehand::Models::SessionExecuteResponse::Data::Result::Usage, nil]
+          optional :usage, -> { Stagehand::Models::SessionExecuteResponse::Data::Result::Usage }
+
+          # @!method initialize(actions:, completed:, message:, success:, metadata: nil, usage: nil)
+          #   @param actions [Array<Stagehand::Models::SessionExecuteResponse::Data::Result::Action>]
+          #
+          #   @param completed [Boolean] Whether the agent finished its task
+          #
+          #   @param message [String] Summary of what the agent accomplished
+          #
+          #   @param success [Boolean] Whether the agent completed successfully
+          #
+          #   @param metadata [Hash{Symbol=>Object}]
+          #
+          #   @param usage [Stagehand::Models::SessionExecuteResponse::Data::Result::Usage]
+
+          class Action < Stagehand::Internal::Type::BaseModel
+            # @!attribute type
+            #   Type of action taken
+            #
+            #   @return [String]
+            required :type, String
+
+            # @!attribute action
+            #
+            #   @return [String, nil]
+            optional :action, String
+
+            # @!attribute instruction
+            #
+            #   @return [String, nil]
+            optional :instruction, String
+
+            # @!attribute page_text
+            #
+            #   @return [String, nil]
+            optional :page_text, String, api_name: :pageText
+
+            # @!attribute page_url
+            #
+            #   @return [String, nil]
+            optional :page_url, String, api_name: :pageUrl
+
+            # @!attribute reasoning
+            #   Agent's reasoning for taking this action
+            #
+            #   @return [String, nil]
+            optional :reasoning, String
+
+            # @!attribute task_completed
+            #
+            #   @return [Boolean, nil]
+            optional :task_completed, Stagehand::Internal::Type::Boolean, api_name: :taskCompleted
+
+            # @!attribute time_ms
+            #   Time taken for this action in ms
+            #
+            #   @return [Float, nil]
+            optional :time_ms, Float, api_name: :timeMs
+
+            # @!method initialize(type:, action: nil, instruction: nil, page_text: nil, page_url: nil, reasoning: nil, task_completed: nil, time_ms: nil)
+            #   @param type [String] Type of action taken
+            #
+            #   @param action [String]
+            #
+            #   @param instruction [String]
+            #
+            #   @param page_text [String]
+            #
+            #   @param page_url [String]
+            #
+            #   @param reasoning [String] Agent's reasoning for taking this action
+            #
+            #   @param task_completed [Boolean]
+            #
+            #   @param time_ms [Float] Time taken for this action in ms
+          end
+
+          # @see Stagehand::Models::SessionExecuteResponse::Data::Result#usage
+          class Usage < Stagehand::Internal::Type::BaseModel
+            # @!attribute inference_time_ms
+            #
+            #   @return [Float]
+            required :inference_time_ms, Float
+
+            # @!attribute input_tokens
+            #
+            #   @return [Float]
+            required :input_tokens, Float
+
+            # @!attribute output_tokens
+            #
+            #   @return [Float]
+            required :output_tokens, Float
+
+            # @!attribute cached_input_tokens
+            #
+            #   @return [Float, nil]
+            optional :cached_input_tokens, Float
+
+            # @!attribute reasoning_tokens
+            #
+            #   @return [Float, nil]
+            optional :reasoning_tokens, Float
+
+            # @!method initialize(inference_time_ms:, input_tokens:, output_tokens:, cached_input_tokens: nil, reasoning_tokens: nil)
+            #   @param inference_time_ms [Float]
+            #   @param input_tokens [Float]
+            #   @param output_tokens [Float]
+            #   @param cached_input_tokens [Float]
+            #   @param reasoning_tokens [Float]
+          end
+        end
+
+        # @see Stagehand::Models::SessionExecuteResponse::Data#cache_entry
+        class CacheEntry < Stagehand::Internal::Type::BaseModel
+          # @!attribute cache_key
+          #   Opaque cache identifier computed from instruction, URL, options, and config
+          #
+          #   @return [String]
+          required :cache_key, String, api_name: :cacheKey
+
+          # @!attribute entry
+          #   Serialized cache entry that can be written to disk
+          #
+          #   @return [Object]
+          required :entry, Stagehand::Internal::Type::Unknown
+
+          # @!method initialize(cache_key:, entry:)
+          #   @param cache_key [String] Opaque cache identifier computed from instruction, URL, options, and config
+          #
+          #   @param entry [Object] Serialized cache entry that can be written to disk
+        end
+      end
+    end
+  end
+end