feat: add v3 integration tests matching cloud exactly

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 7
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-2132f9afd90a3b3c35b772f0de3ac8432cfe46ecfa22ec9c1ed4a3d0eda1ad41.yml
-openapi_spec_hash: 6da568c2948d8ab6000db4291e15a033
-config_hash: 64c9cc393de93af70e11dbf0b1ba9388
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-1c405024b4a17886e921871250a445362463b7ae6070cacc3d1927d59036730c.yml
+openapi_spec_hash: c4ea3735257a48ed105002eb7aaa095a
+config_hash: 85d56c7c196269badbd0b4a9dfb28d45

stagehand-java-core/src/main/kotlin/com/browserbase/api/models/sessions/SessionActParams.kt

@@ -773,26 +773,28 @@ private constructor(
     class Options
     @JsonCreator(mode = JsonCreator.Mode.DISABLED)
     private constructor(
-        private val model: JsonField<ModelConfig>,
+        private val model: JsonField<Model>,
         private val timeout: JsonField<Double>,
         private val variables: JsonField<Variables>,
         private val additionalProperties: MutableMap<String, JsonValue>,
     ) {
 
         @JsonCreator
         private constructor(
-            @JsonProperty("model") @ExcludeMissing model: JsonField<ModelConfig> = JsonMissing.of(),
+            @JsonProperty("model") @ExcludeMissing model: JsonField<Model> = JsonMissing.of(),
             @JsonProperty("timeout") @ExcludeMissing timeout: JsonField<Double> = JsonMissing.of(),
             @JsonProperty("variables")
             @ExcludeMissing
             variables: JsonField<Variables> = JsonMissing.of(),
         ) : this(model, timeout, variables, mutableMapOf())
 
         /**
+         * Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
+         *
          * @throws StagehandInvalidDataException if the JSON field has an unexpected type (e.g. if
          *   the server responded with an unexpected value).
          */
-        fun model(): Optional<ModelConfig> = model.getOptional("model")
+        fun model(): Optional<Model> = model.getOptional("model")
 
         /**
          * Timeout in ms for the action
@@ -815,7 +817,7 @@ private constructor(
          *
          * Unlike [model], this method doesn't throw if the JSON field has an unexpected type.
          */
-        @JsonProperty("model") @ExcludeMissing fun _model(): JsonField<ModelConfig> = model
+        @JsonProperty("model") @ExcludeMissing fun _model(): JsonField<Model> = model
 
         /**
          * Returns the raw JSON value of [timeout].
@@ -854,7 +856,7 @@ private constructor(
         /** A builder for [Options]. */
         class Builder internal constructor() {
 
-            private var model: JsonField<ModelConfig> = JsonMissing.of()
+            private var model: JsonField<Model> = JsonMissing.of()
             private var timeout: JsonField<Double> = JsonMissing.of()
             private var variables: JsonField<Variables> = JsonMissing.of()
             private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
@@ -867,16 +869,23 @@ private constructor(
                 additionalProperties = options.additionalProperties.toMutableMap()
             }
 
-            fun model(model: ModelConfig) = model(JsonField.of(model))
+            /** Model configuration object or model name string (e.g., 'openai/gpt-5-nano') */
+            fun model(model: Model) = model(JsonField.of(model))
 
             /**
              * Sets [Builder.model] to an arbitrary JSON value.
              *
-             * You should usually call [Builder.model] with a well-typed [ModelConfig] value
-             * instead. This method is primarily for setting the field to an undocumented or not yet
-             * supported value.
+             * You should usually call [Builder.model] with a well-typed [Model] value instead. This
+             * method is primarily for setting the field to an undocumented or not yet supported
+             * value.
              */
-            fun model(model: JsonField<ModelConfig>) = apply { this.model = model }
+            fun model(model: JsonField<Model>) = apply { this.model = model }
+
+            /** Alias for calling [model] with `Model.ofConfig(config)`. */
+            fun model(config: ModelConfig) = model(Model.ofConfig(config))
+
+            /** Alias for calling [model] with `Model.ofString(string)`. */
+            fun model(string: String) = model(Model.ofString(string))
 
             /** Timeout in ms for the action */
             fun timeout(timeout: Double) = timeout(JsonField.of(timeout))
@@ -963,6 +972,178 @@ private constructor(
                 (if (timeout.asKnown().isPresent) 1 else 0) +
                 (variables.asKnown().getOrNull()?.validity() ?: 0)
 
+        /** Model configuration object or model name string (e.g., 'openai/gpt-5-nano') */
+        @JsonDeserialize(using = Model.Deserializer::class)
+        @JsonSerialize(using = Model.Serializer::class)
+        class Model
+        private constructor(
+            private val config: ModelConfig? = null,
+            private val string: String? = null,
+            private val _json: JsonValue? = null,
+        ) {
+
+            fun config(): Optional<ModelConfig> = Optional.ofNullable(config)
+
+            fun string(): Optional<String> = Optional.ofNullable(string)
+
+            fun isConfig(): Boolean = config != null
+
+            fun isString(): Boolean = string != null
+
+            fun asConfig(): ModelConfig = config.getOrThrow("config")
+
+            fun asString(): String = string.getOrThrow("string")
+
+            fun _json(): Optional<JsonValue> = Optional.ofNullable(_json)
+
+            fun <T> accept(visitor: Visitor<T>): T =
+                when {
+                    config != null -> visitor.visitConfig(config)
+                    string != null -> visitor.visitString(string)
+                    else -> visitor.unknown(_json)
+                }
+
+            private var validated: Boolean = false
+
+            fun validate(): Model = apply {
+                if (validated) {
+                    return@apply
+                }
+
+                accept(
+                    object : Visitor<Unit> {
+                        override fun visitConfig(config: ModelConfig) {
+                            config.validate()
+                        }
+
+                        override fun visitString(string: String) {}
+                    }
+                )
+                validated = true
+            }
+
+            fun isValid(): Boolean =
+                try {
+                    validate()
+                    true
+                } catch (e: StagehandInvalidDataException) {
+                    false
+                }
+
+            /**
+             * Returns a score indicating how many valid values are contained in this object
+             * recursively.
+             *
+             * Used for best match union deserialization.
+             */
+            @JvmSynthetic
+            internal fun validity(): Int =
+                accept(
+                    object : Visitor<Int> {
+                        override fun visitConfig(config: ModelConfig) = config.validity()
+
+                        override fun visitString(string: String) = 1
+
+                        override fun unknown(json: JsonValue?) = 0
+                    }
+                )
+
+            override fun equals(other: Any?): Boolean {
+                if (this === other) {
+                    return true
+                }
+
+                return other is Model && config == other.config && string == other.string
+            }
+
+            override fun hashCode(): Int = Objects.hash(config, string)
+
+            override fun toString(): String =
+                when {
+                    config != null -> "Model{config=$config}"
+                    string != null -> "Model{string=$string}"
+                    _json != null -> "Model{_unknown=$_json}"
+                    else -> throw IllegalStateException("Invalid Model")
+                }
+
+            companion object {
+
+                @JvmStatic fun ofConfig(config: ModelConfig) = Model(config = config)
+
+                @JvmStatic fun ofString(string: String) = Model(string = string)
+            }
+
+            /**
+             * An interface that defines how to map each variant of [Model] to a value of type [T].
+             */
+            interface Visitor<out T> {
+
+                fun visitConfig(config: ModelConfig): T
+
+                fun visitString(string: String): T
+
+                /**
+                 * Maps an unknown variant of [Model] to a value of type [T].
+                 *
+                 * An instance of [Model] can contain an unknown variant if it was deserialized from
+                 * data that doesn't match any known variant. For example, if the SDK is on an older
+                 * version than the API, then the API may respond with new variants that the SDK is
+                 * unaware of.
+                 *
+                 * @throws StagehandInvalidDataException in the default implementation.
+                 */
+                fun unknown(json: JsonValue?): T {
+                    throw StagehandInvalidDataException("Unknown Model: $json")
+                }
+            }
+
+            internal class Deserializer : BaseDeserializer<Model>(Model::class) {
+
+                override fun ObjectCodec.deserialize(node: JsonNode): Model {
+                    val json = JsonValue.fromJsonNode(node)
+
+                    val bestMatches =
+                        sequenceOf(
+                                tryDeserialize(node, jacksonTypeRef<ModelConfig>())?.let {
+                                    Model(config = it, _json = json)
+                                },
+                                tryDeserialize(node, jacksonTypeRef<String>())?.let {
+                                    Model(string = it, _json = json)
+                                },
+                            )
+                            .filterNotNull()
+                            .allMaxBy { it.validity() }
+                            .toList()
+                    return when (bestMatches.size) {
+                        // This can happen if what we're deserializing is completely incompatible
+                        // with all the possible variants (e.g. deserializing from boolean).
+                        0 -> Model(_json = json)
+                        1 -> bestMatches.single()
+                        // If there's more than one match with the highest validity, then use the
+                        // first completely valid match, or simply the first match if none are
+                        // completely valid.
+                        else -> bestMatches.firstOrNull { it.isValid() } ?: bestMatches.first()
+                    }
+                }
+            }
+
+            internal class Serializer : BaseSerializer<Model>(Model::class) {
+
+                override fun serialize(
+                    value: Model,
+                    generator: JsonGenerator,
+                    provider: SerializerProvider,
+                ) {
+                    when {
+                        value.config != null -> generator.writeObject(value.config)
+                        value.string != null -> generator.writeObject(value.string)
+                        value._json != null -> generator.writeObject(value._json)
+                        else -> throw IllegalStateException("Invalid Model")
+                    }
+                }
+            }
+        }
+
         /** Variables to substitute in the action instruction */
         class Variables
         @JsonCreator