feat(agents): expose turn-scoped artifact content responses

Author: apcha-oai

docs/helpers/agent-files.md

@@ -35,3 +35,14 @@ var docs = AgentEnvironmentFiles.prepareDirectory(client, Paths.get("docs"),
 var staged = AgentEnvironmentFiles.upload(client, environmentId,
     Paths.get("update.csv"), "/workspace/update.csv");
 ```
+
+Artifact content can be read in memory, or streamed to an application-owned, safe destination path. Both modes select the exact result turn and path; async service overloads return `CompletableFuture`.
+
+```java
+var artifacts = AgentArtifactDownloads.forResult(
+    client.beta().agents().sessions().artifacts(), result);
+try (var response = artifacts.content("/workspace/outputs/report.md")) {
+    byte[] report = response.body().readAllBytes();
+}
+artifacts.download("/workspace/outputs/report.md", Paths.get("downloaded-report.md"));
+```

openai-java-core/src/main/kotlin/com/openai/helpers/beta/agents/AgentArtifactDownloads.kt

@@ -50,13 +50,30 @@ private constructor(
         }
     }
 
-    /** Streams the exact turn/path artifact to the caller-selected file, replacing that file. */
+    /** Returns the exact turn/path response. The caller owns and must close it. */
+    @JvmOverloads
+    fun content(path: String, options: RequestOptions = RequestOptions.none()): HttpResponse =
+        openContent(findArtifact(path, options), options)
+
+    /** Streams to an application-owned destination, replacing that file. */
     @JvmOverloads
     fun download(
         path: String,
         destination: Path,
         options: RequestOptions = RequestOptions.none(),
     ): SessionArtifact {
+        val artifact = findArtifact(path, options)
+        openContent(artifact, options).use { Files.copy(it.body(), destination, REPLACE_EXISTING) }
+        return artifact
+    }
+
+    private fun openContent(artifact: SessionArtifact, options: RequestOptions) =
+        service.content(
+            ArtifactContentParams.builder().sessionId(sessionId).artifactId(artifact.id()).build(),
+            options,
+        )
+
+    private fun findArtifact(path: String, options: RequestOptions): SessionArtifact {
         var selected: SessionArtifact? = null
         var params = ArtifactListParams.builder().sessionId(sessionId).build()
         while (true) {
@@ -65,17 +82,7 @@ private constructor(
             if (!page.hasNextPage()) break
             params = page.nextPageParams()
         }
-        val artifact = checkNotNull(selected) { "No artifact matches this turn and path" }
-        service
-            .content(
-                ArtifactContentParams.builder()
-                    .sessionId(sessionId)
-                    .artifactId(artifact.id())
-                    .build(),
-                options,
-            )
-            .use { Files.copy(it.body(), destination, REPLACE_EXISTING) }
-        return artifact
+        return checkNotNull(selected) { "No artifact matches this turn and path" }
     }
 
     class Async
@@ -84,14 +91,34 @@ private constructor(
         private val sessionId: String,
         private val turnId: String,
     ) {
+        /** Returns the exact turn/path response. The caller owns and must close it. */
+        @JvmOverloads
+        fun content(
+            path: String,
+            options: RequestOptions = RequestOptions.none(),
+        ): CompletableFuture<HttpResponse> = withContent(path, options) { _, response -> response }
+
+        /** Streams to an application-owned destination, replacing that file. */
         @JvmOverloads
         fun download(
             path: String,
             destination: Path,
             options: RequestOptions = RequestOptions.none(),
-        ): CompletableFuture<SessionArtifact> {
-            val result = CompletableFuture<SessionArtifact>()
+        ): CompletableFuture<SessionArtifact> =
+            withContent(path, options) { artifact, response ->
+                response.use { Files.copy(it.body(), destination, REPLACE_EXISTING) }
+                artifact
+            }
+
+        private fun <T> withContent(
+            path: String,
+            options: RequestOptions,
+            consume: (SessionArtifact, HttpResponse) -> T,
+        ): CompletableFuture<T> {
+            val result = CompletableFuture<T>()
             val response = AtomicReference<HttpResponse?>()
+            // Native service futures are dependent stages: canceling them does not abort their
+            // transport and can suppress delivery of a response that still needs closing.
             result.whenComplete { _, _ -> if (result.isCancelled) response.get()?.close() }
             var selected: SessionArtifact? = null
             fun downloadSelected() {
@@ -110,12 +137,11 @@ private constructor(
                         else {
                             response.set(content)
                             try {
-                                content.use {
-                                    if (!result.isDone)
-                                        Files.copy(it.body(), destination, REPLACE_EXISTING)
-                                }
-                                result.complete(artifact)
+                                if (result.isDone) content.close()
+                                else if (!result.complete(consume(artifact, content)))
+                                    content.close()
                             } catch (error: Throwable) {
+                                runCatching { content.close() }
                                 result.completeExceptionally(error)
                             } finally {
                                 response.set(null)

openai-java-core/src/test/kotlin/com/openai/helpers/beta/agents/AgentFileHelpersTest.kt

@@ -440,6 +440,51 @@ internal class AgentFileHelpersTest {
         }
     }
 
+    @ParameterizedTest
+    @ValueSource(booleans = [false, true])
+    fun `content preserves exact scope options and caller ownership`(async: Boolean) {
+        val t =
+            Transport().apply {
+                pages =
+                    mutableListOf(
+                        page(artifact("old", "old"), more = true),
+                        page(artifact("selected")),
+                    )
+            }
+        val client = t.client()
+        try {
+            val response =
+                if (async)
+                    AgentArtifactDownloads.forResult(
+                            client.async().beta().agents().sessions().artifacts(),
+                            result(),
+                        )
+                        .content("/workspace/outputs/report.txt", options)
+                        .join()
+                else
+                    AgentArtifactDownloads.forResult(
+                            client.beta().agents().sessions().artifacts(),
+                            result(),
+                        )
+                        .content("/workspace/outputs/report.txt", options)
+            assertThat(t.contentClosed).isFalse()
+            assertThat(t.contentReads).isZero()
+            response.use {
+                val bytes = ByteArrayOutputStream()
+                it.body().copyTo(bytes)
+                assertThat(bytes.size()).isEqualTo(t.contentSize)
+            }
+            assertThat(t.contentClosed).isTrue()
+            assertThat(t.requests).hasSize(3)
+            assertThat(t.requests.last().pathSegments).contains("s", "selected")
+            assertThat(t.requestOptions).allSatisfy {
+                assertThat(it.timeout).isEqualTo(options.timeout)
+            }
+        } finally {
+            client.close()
+        }
+    }
+
     @ParameterizedTest
     @ValueSource(booleans = [false, true])
     fun `artifact lookup reports missing and ambiguous matches without touching destination`(
@@ -597,8 +642,11 @@ internal class AgentFileHelpersTest {
         }
     }
 
-    @Test
-    fun `cancelling an async download closes a late content response without writing`() {
+    @ParameterizedTest
+    @ValueSource(booleans = [false, true])
+    fun `cancelling native async content closes a late response without writing`(
+        inMemory: Boolean
+    ) {
         val t = Transport()
         val client = t.client()
         val pending = CompletableFuture<HttpResponse>()
@@ -613,12 +661,14 @@ internal class AgentFileHelpersTest {
         }
         try {
             val destination = directory.resolve("cancelled.txt")
-            val download =
+            val scoped =
                 AgentArtifactDownloads.forResult(
-                        client.async().beta().agents().sessions().artifacts(),
-                        result(),
-                    )
-                    .download("/workspace/outputs/report.txt", destination)
+                    client.async().beta().agents().sessions().artifacts(),
+                    result(),
+                )
+            val download =
+                if (inMemory) scoped.content("/workspace/outputs/report.txt")
+                else scoped.download("/workspace/outputs/report.txt", destination)
             assertThat(requested.await(5, TimeUnit.SECONDS)).isTrue()
             assertThat(download.cancel(true)).isTrue()
             pending.complete(t.execute(requireNotNull(request), options))