feat(sessions): support session expiry in VertexAiSessionService

`VertexAiSessionService` now takes a `sessionTtl` applied to every session it
creates, including the ones a runner creates through the `SessionService`
interface, where a per-call argument cannot reach. A Vertex-only `createSession`
overload additionally takes `ttl` or `expireTime` for one session, overriding
that default.

At most one expiry may be set, since the wire field is a single choice. Without
one the backend applies its own default, which is long; with one, the minimum it
accepts is 24 hours. The `SessionService` interface is unchanged.

PiperOrigin-RevId: 970575360

Author: kvmilos

core/src/jvmMain/kotlin/com/google/adk/kt/sessions/VertexAiSessionService.kt

@@ -24,7 +24,11 @@ import com.google.adk.kt.sessions.dto.toDto
 import com.google.auth.oauth2.GoogleCredentials
 import io.ktor.client.HttpClient
 import io.ktor.client.engine.java.Java
+import java.time.Duration as JavaDuration
 import kotlin.jvm.JvmStatic
+import kotlin.time.Duration
+import kotlin.time.Instant
+import kotlin.time.toKotlinDuration
 
 /**
  * A [SessionService] backed by the managed Vertex AI Session Service.
@@ -51,6 +55,7 @@ internal constructor(
   private val project: String,
   private val location: String,
   private val reasoningEngineId: String,
+  private val sessionTtl: Duration? = null,
 ) : SessionService {
 
   init {
@@ -59,6 +64,9 @@ internal constructor(
       "reasoningEngineId must be the numeric reasoning engine id (e.g. \"1234567890\"), not a" +
         " resource name; pass project and location as separate arguments. Got: $reasoningEngineId"
     }
+    require(sessionTtl == null || sessionTtl.inWholeSeconds > 0) {
+      "sessionTtl must be at least one second, but was $sessionTtl."
+    }
   }
 
   private val engine = ReasoningEngineRef(project, location, reasoningEngineId)
@@ -72,22 +80,59 @@ internal constructor(
    * @param credentials Credentials for the Vertex AI API; defaults to application-default
    *   credentials scoped for Google Cloud Platform.
    * @param httpClient The underlying ktor [HttpClient].
+   * @param sessionTtl Lifetime applied to every session this service creates, including those the
+   *   runner creates through the [SessionService] interface. A per-call `ttl` or `expireTime`
+   *   overrides it; `null` leaves the backend default in place.
    */
   constructor(
     project: String,
     location: String,
     reasoningEngineId: String,
     credentials: GoogleCredentials = GoogleApiClient.defaultCredentials(),
     httpClient: HttpClient = HttpClient(Java),
+    sessionTtl: Duration? = null,
   ) : this(
     VertexAiSessionsClient(GoogleApiClient(httpClient, credentials)),
     project,
     location,
     reasoningEngineId,
+    sessionTtl,
   )
 
-  override suspend fun createSession(key: SessionKey, state: Map<String, Any>?): Session {
-    val sessionDto = client.createSession(engine, key.userId, state).getOrThrow()
+  override suspend fun createSession(key: SessionKey, state: Map<String, Any>?): Session =
+    createSession(key, state, ttl = null, expireTime = null)
+
+  /**
+   * Creates a session that expires, addressing the reasoning engine fixed at construction.
+   *
+   * At most one of [ttl] and [expireTime] may be set, because the backend models them as a single
+   * choice; setting both is rejected. The backend also requires the expiry to be at least 24 hours
+   * out. When neither is given, the service-wide `sessionTtl` applies if one was configured.
+   *
+   * @param key The composite identifier of the session; [SessionKey.appName] is only a label.
+   * @param state An optional map representing the initial state of the session.
+   * @param ttl How long the session lives, measured from creation. Sub-second precision is dropped.
+   * @param expireTime The absolute instant at which the session expires.
+   * @return The newly created [Session].
+   */
+  suspend fun createSession(
+    key: SessionKey,
+    state: Map<String, Any>? = null,
+    ttl: Duration? = null,
+    expireTime: Instant? = null,
+  ): Session {
+    require(ttl == null || expireTime == null) {
+      "Cannot specify both ttl and expireTime simultaneously."
+    }
+    // The wire format is whole seconds, so a sub-second ttl would silently travel as "0s".
+    require(ttl == null || ttl.inWholeSeconds > 0) {
+      "ttl must be at least one second, but was $ttl."
+    }
+    // A per-call arm wins; otherwise the service-wide default applies, so a session created
+    // through the SessionService interface still expires.
+    val effectiveTtl = if (ttl == null && expireTime == null) sessionTtl else ttl
+    val sessionDto =
+      client.createSession(engine, key.userId, state, effectiveTtl, expireTime).getOrThrow()
     return sessionDto.toAdk(key.appName, key.userId, key.id)
   }
 
@@ -168,6 +213,7 @@ internal constructor(
     private var reasoningEngineId: String? = null
     private var credentials: GoogleCredentials? = null
     private var httpClient: HttpClient? = null
+    private var sessionTtl: Duration? = null
 
     fun project(project: String): Builder = apply { this.project = project }
 
@@ -183,6 +229,16 @@ internal constructor(
 
     fun httpClient(httpClient: HttpClient): Builder = apply { this.httpClient = httpClient }
 
+    /**
+     * Sets the lifetime applied to every session this service creates.
+     *
+     * Takes a [JavaDuration] because Java cannot name a method whose signature contains [Duration],
+     * a value class.
+     */
+    fun sessionTtl(sessionTtl: JavaDuration): Builder = apply {
+      this.sessionTtl = sessionTtl.toKotlinDuration()
+    }
+
     fun build(): VertexAiSessionService =
       VertexAiSessionService(
         project =
@@ -195,6 +251,7 @@ internal constructor(
           },
         credentials = credentials ?: GoogleApiClient.defaultCredentials(),
         httpClient = httpClient ?: HttpClient(Java),
+        sessionTtl = sessionTtl,
       )
   }
 

core/src/jvmMain/kotlin/com/google/adk/kt/sessions/VertexAiSessionsClient.kt

@@ -38,6 +38,8 @@ import java.io.IOException
 import java.net.URLEncoder
 import java.nio.charset.StandardCharsets
 import java.util.concurrent.TimeoutException
+import kotlin.time.Duration
+import kotlin.time.Instant
 import kotlinx.coroutines.delay
 import kotlinx.serialization.DeserializationStrategy
 
@@ -101,17 +103,28 @@ internal open class VertexAiSessionsClient(
    * @param engine The reasoning engine that owns the session.
    * @param userId The ID of the user owning the session.
    * @param state Optional initial state map to inject into the session.
+   * @param ttl Optional lifetime of the session, measured from creation.
+   * @param expireTime Optional absolute expiry of the session. The wire field is a oneof, so the
+   *   caller must not set both this and [ttl].
    * @return The created [SessionDto], or a [Result.failure] describing why creation failed.
    */
   open suspend fun createSession(
     engine: ReasoningEngineRef,
     userId: String,
     state: Map<String, Any>?,
+    ttl: Duration? = null,
+    expireTime: Instant? = null,
   ): Result<SessionDto> {
     val requestBody =
       adkJson.encodeToString(
         CreateSessionRequestDto.serializer(),
-        CreateSessionRequestDto(userId = userId, sessionState = state?.let { anyToJsonElement(it) }),
+        CreateSessionRequestDto(
+          userId = userId,
+          sessionState = state?.let { anyToJsonElement(it) },
+          // proto3 JSON writes a Duration as seconds with an "s" suffix.
+          ttl = ttl?.let { "${it.inWholeSeconds}s" },
+          expireTime = expireTime?.toString(),
+        ),
       )
     val createResponse =
       postAndDecode(

core/src/jvmMain/kotlin/com/google/adk/kt/sessions/dto/ResponsesDto.kt

@@ -38,4 +38,7 @@ internal data class ListEventsResponseDto(
 internal data class CreateSessionRequestDto(
   val userId: String,
   val sessionState: JsonElement? = null,
+  // `ttl`/`expire_time` are a proto oneof; at most one is set, in its JSON string form.
+  val ttl: String? = null,
+  val expireTime: String? = null,
 )

core/src/jvmTest/kotlin/com/google/adk/kt/sessions/VertexAiSessionServiceTest.kt

@@ -28,7 +28,12 @@ import com.google.adk.kt.types.Part
 import com.google.common.truth.Truth.assertThat
 import java.io.IOException
 import kotlin.test.assertFailsWith
+import kotlin.time.Duration
+import kotlin.time.Duration.Companion.hours
+import kotlin.time.Duration.Companion.milliseconds
+import kotlin.time.Duration.Companion.seconds
 import kotlin.time.Instant
+import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.test.runTest
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.JsonPrimitive
@@ -54,27 +59,33 @@ import org.mockito.kotlin.verifyBlocking
 @RunWith(JUnit4::class)
 class VertexAiSessionServiceTest {
 
-  private fun service(client: VertexAiSessionsClient) =
+  private fun service(client: VertexAiSessionsClient, sessionTtl: Duration? = null) =
     VertexAiSessionService(
       client,
       project = PROJECT,
       location = LOCATION,
       reasoningEngineId = ENGINE_ID,
+      sessionTtl = sessionTtl,
     )
 
+  /** A client that accepts any create call, for asserting which expiration was forwarded. */
+  private fun expiringSessionClient() =
+    mock<VertexAiSessionsClient> {
+      onBlocking { createSession(any(), any(), anyOrNull(), anyOrNull(), anyOrNull()) } doReturn
+        Result.success(SessionDto(name = "reasoningEngines/123/sessions/s"))
+    }
+
   @Test
   fun addressesConfiguredEngineRegardlessOfAppName() = runTest {
-    val client =
-      mock<VertexAiSessionsClient> {
-        onBlocking { createSession(any(), any(), anyOrNull()) } doReturn
-          Result.success(SessionDto(name = "reasoningEngines/123/sessions/s"))
-      }
+    val client = expiringSessionClient()
 
     // The app name is only a label; the service always addresses the engine set at construction.
     val unused =
       service(client).createSession(SessionKey("any-label", "user", id = null), state = null)
 
-    verifyBlocking(client) { createSession(eq(ENGINE), eq("user"), anyOrNull()) }
+    verifyBlocking(client) {
+      createSession(eq(ENGINE), eq("user"), anyOrNull(), anyOrNull(), anyOrNull())
+    }
   }
 
   @Test
@@ -137,7 +148,9 @@ class VertexAiSessionServiceTest {
   fun createSession_mapsClientResponse() = runTest {
     val client =
       mock<VertexAiSessionsClient> {
-        onBlocking { createSession(eq(ENGINE), eq("user"), anyOrNull()) } doReturn
+        onBlocking {
+          createSession(eq(ENGINE), eq("user"), anyOrNull(), anyOrNull(), anyOrNull())
+        } doReturn
           Result.success(
             SessionDto(
               name = "reasoningEngines/123/sessions/session-1",
@@ -160,7 +173,7 @@ class VertexAiSessionServiceTest {
   fun createSession_clientFails_propagates() = runTest {
     val client =
       mock<VertexAiSessionsClient> {
-        onBlocking { createSession(any(), any(), anyOrNull()) } doReturn
+        onBlocking { createSession(any(), any(), anyOrNull(), anyOrNull(), anyOrNull()) } doReturn
           Result.failure(IOException("boom"))
       }
 
@@ -169,6 +182,142 @@ class VertexAiSessionServiceTest {
     }
   }
 
+  @Test
+  fun createSession_ttl_forwardsTtlOnly() {
+    val client = expiringSessionClient()
+
+    runBlocking {
+      val unused =
+        service(client).createSession(SessionKey("123", "user", id = null), ttl = 24.hours)
+    }
+
+    verifyBlocking(client) {
+      createSession(eq(ENGINE), eq("user"), anyOrNull(), eq(24.hours), eq(null))
+    }
+  }
+
+  @Test
+  fun createSession_expireTime_forwardsExpireTimeOnly() {
+    val client = expiringSessionClient()
+    val expiry = Instant.parse("2026-10-01T00:00:00Z")
+
+    runBlocking {
+      val unused =
+        service(client).createSession(SessionKey("123", "user", id = null), expireTime = expiry)
+    }
+
+    verifyBlocking(client) {
+      createSession(eq(ENGINE), eq("user"), anyOrNull(), eq(null), eq(expiry))
+    }
+  }
+
+  @Test
+  fun createSession_noExpiration_forwardsNeither() {
+    val client = expiringSessionClient()
+
+    // The SessionService overload must not invent an expiration of its own.
+    runBlocking {
+      val unused = service(client).createSession(SessionKey("123", "user", id = null))
+    }
+
+    verifyBlocking(client) {
+      createSession(eq(ENGINE), eq("user"), anyOrNull(), eq(null), eq(null))
+    }
+  }
+
+  @Test
+  fun createSession_ttlAndExpireTime_throwsWithoutCallingBackend() {
+    val client = expiringSessionClient()
+
+    assertFailsWith<IllegalArgumentException> {
+      runBlocking {
+        service(client)
+          .createSession(
+            SessionKey("123", "user", id = null),
+            ttl = 24.hours,
+            expireTime = Instant.parse("2026-10-01T00:00:00Z"),
+          )
+      }
+    }
+    verifyBlocking(client, never()) {
+      createSession(any(), any(), anyOrNull(), anyOrNull(), anyOrNull())
+    }
+  }
+
+  @Test
+  fun createSession_serviceTtl_appliedThroughSessionServiceInterface() {
+    val client = expiringSessionClient()
+    // The runner and the web server create sessions through the interface, where the per-call
+    // overload is unreachable, so the configured default has to reach them.
+    val sessionService: SessionService = service(client, sessionTtl = 24.hours)
+
+    runBlocking {
+      val unused = sessionService.createSession(SessionKey("123", "user", id = null))
+    }
+
+    verifyBlocking(client) {
+      createSession(eq(ENGINE), eq("user"), anyOrNull(), eq(24.hours), eq(null))
+    }
+  }
+
+  @Test
+  fun createSession_perCallTtl_overridesServiceTtl() {
+    val client = expiringSessionClient()
+
+    runBlocking {
+      val unused =
+        service(client, sessionTtl = 24.hours)
+          .createSession(SessionKey("123", "user", id = null), ttl = 48.hours)
+    }
+
+    verifyBlocking(client) {
+      createSession(eq(ENGINE), eq("user"), anyOrNull(), eq(48.hours), eq(null))
+    }
+  }
+
+  @Test
+  fun createSession_perCallExpireTime_suppressesServiceTtl() {
+    val client = expiringSessionClient()
+    val expiry = Instant.parse("2026-10-01T00:00:00Z")
+
+    // Both arms are a single wire choice, so the default must not ride along with expireTime.
+    runBlocking {
+      val unused =
+        service(client, sessionTtl = 24.hours)
+          .createSession(SessionKey("123", "user", id = null), expireTime = expiry)
+    }
+
+    verifyBlocking(client) {
+      createSession(eq(ENGINE), eq("user"), anyOrNull(), eq(null), eq(expiry))
+    }
+  }
+
+  @Test
+  fun constructor_sessionTtlBelowOneSecond_throws() {
+    for (bad in listOf(Duration.ZERO, (-1).seconds, 500.milliseconds)) {
+      assertFailsWith<IllegalArgumentException> {
+        service(mock<VertexAiSessionsClient>(), sessionTtl = bad)
+      }
+    }
+  }
+
+  @Test
+  fun createSession_ttlBelowOneSecond_throwsWithoutCallingBackend() {
+    val client = expiringSessionClient()
+
+    // 500ms is positive but truncates to "0s" on the wire, so it must be rejected too.
+    for (bad in listOf(Duration.ZERO, (-1).seconds, 500.milliseconds)) {
+      assertFailsWith<IllegalArgumentException> {
+        runBlocking {
+          service(client).createSession(SessionKey("123", "user", id = null), ttl = bad)
+        }
+      }
+    }
+    verifyBlocking(client, never()) {
+      createSession(any(), any(), anyOrNull(), anyOrNull(), anyOrNull())
+    }
+  }
+
   @Test
   fun getSession_notFound_returnsNull() = runTest {
     val client =