fix(api): declare mount binary responses, regenerate the Fern client (#5518)

The three mount routes that return raw bytes declared no response media type, so
FastAPI advertised application/json for them. The generated clients then parsed a
zip or a file body as JSON and corrupted it, which is why the frontend had to call
these routes through raw axios.

Declare the real media types (application/zip for the archive export,
application/octet-stream for the two file downloads). Setting responses= alone is
not enough: FastAPI keeps its default application/json entry unless the route also
declares a response_class with no media type, so both are set. Runtime behavior is
unchanged, since each handler already returns its own Response.

Regenerate the TypeScript client once from the resulting spec, replacing the
exportMountFiles method that was hand-written into the generated directory after
the /files/export rename. The three methods now return core.BinaryResponse with
responseType binary-response, which exposes both .blob() and .stream(). The
regeneration also corrects two pieces of drift the hand-edits had left behind:
GetMountFilesRequest.order becomes a generated enum, and MountFile moves under the
mounts resource.

Refs #5417

Claude-Session: https://claude.ai/code/session_011npNAXwcM2adqdSX6QGcsz

Author: mmabrouk

api/oss/src/apis/fastapi/mounts/router.py

@@ -2,7 +2,16 @@
 from typing import Literal, Optional
 from uuid import UUID
 
-from fastapi import APIRouter, HTTPException, Query, Request, UploadFile, status
+from fastapi import (
+    APIRouter,
+    HTTPException,
+    Query,
+    Request,
+    Response,
+    UploadFile,
+    status,
+)
+from fastapi.responses import StreamingResponse
 
 from oss.src.utils.exceptions import intercept_exceptions
 
@@ -42,6 +51,8 @@
     MountsResponse,
 )
 from oss.src.apis.fastapi.mounts.utils import (
+    BINARY_RESPONSE,
+    ZIP_RESPONSE,
     download_mount_file,
     merge_mount_query,
     sign_mount_credentials,
@@ -200,6 +211,8 @@ def __init__(
             methods=["POST"],
             operation_id="export_mount_files",
             response_model=None,
+            response_class=StreamingResponse,
+            responses=ZIP_RESPONSE,
             status_code=status.HTTP_200_OK,
         )
         self.router.add_api_route(
@@ -247,6 +260,8 @@ def __init__(
             methods=["GET"],
             operation_id="download_mount_file",
             response_model=None,
+            response_class=Response,
+            responses=BINARY_RESPONSE,
             status_code=status.HTTP_200_OK,
         )
         self.router.add_api_route(

api/oss/src/apis/fastapi/mounts/utils.py

@@ -21,6 +21,27 @@
 # Regular-file mode for archive members (owner rw, group/other r).
 _ARCHIVE_FILE_MODE = S_IFREG | 0o644
 
+# OpenAPI declarations for the routes below that return raw bytes rather than JSON. Without them
+# FastAPI advertises `application/json`, and the generated clients then parse the body as JSON and
+# corrupt the payload. A route must also declare a `response_class` with no media type, or FastAPI
+# keeps its default `application/json` entry alongside these.
+ZIP_RESPONSE = {
+    200: {
+        "content": {
+            "application/zip": {"schema": {"type": "string", "format": "binary"}}
+        }
+    }
+}
+BINARY_RESPONSE = {
+    200: {
+        "content": {
+            "application/octet-stream": {
+                "schema": {"type": "string", "format": "binary"}
+            }
+        }
+    }
+}
+
 
 def _content_disposition_attachment(filename: str) -> str:
     """Build a safe `Content-Disposition: attachment` header value (RFC 6266).

api/oss/src/apis/fastapi/sessions/router.py

@@ -20,7 +20,15 @@
 from functools import wraps
 from uuid import UUID
 
-from fastapi import APIRouter, HTTPException, Query, Request, UploadFile, status
+from fastapi import (
+    APIRouter,
+    HTTPException,
+    Query,
+    Request,
+    Response,
+    UploadFile,
+    status,
+)
 from fastapi.responses import JSONResponse
 from typing import Any, Optional, Union
 
@@ -71,6 +79,7 @@
 from oss.src.core.mounts.service import MountsService
 from oss.src.apis.fastapi.mounts.router import handle_mount_exceptions
 from oss.src.apis.fastapi.mounts.utils import (
+    BINARY_RESPONSE,
     download_mount_file,
     sign_mount_credentials,
     upload_mount_file,
@@ -919,6 +928,8 @@ def __init__(
             methods=["GET"],
             operation_id="download_session_mount_file",
             response_model=None,
+            response_class=Response,
+            responses=BINARY_RESPONSE,
             status_code=status.HTTP_200_OK,
         )
 

web/packages/agenta-api-client/src/generated/api/resources/mounts/client/Client.ts

@@ -527,32 +527,26 @@ export class MountsClient {
     }
 
     /**
-     * @param {AgentaApi.MountArchiveRequest} request
-     * @param {MountsClient.RequestOptions} requestOptions - Request-specific configuration.
-     *
      * @throws {@link AgentaApi.UnprocessableEntityError}
-     *
-     * @example
-     *     await client.mounts.exportMountFiles()
      */
     public exportMountFiles(
         request: AgentaApi.MountArchiveRequest = {},
         requestOptions?: MountsClient.RequestOptions,
-    ): core.HttpResponsePromise<unknown> {
+    ): core.HttpResponsePromise<core.BinaryResponse> {
         return core.HttpResponsePromise.fromPromise(this.__exportMountFiles(request, requestOptions));
     }
 
     private async __exportMountFiles(
         request: AgentaApi.MountArchiveRequest = {},
         requestOptions?: MountsClient.RequestOptions,
-    ): Promise<core.WithRawResponse<unknown>> {
+    ): Promise<core.WithRawResponse<core.BinaryResponse>> {
         const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
         const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
             _authRequest.headers,
             this._options?.headers,
             requestOptions?.headers,
         );
-        const _response = await core.fetcher({
+        const _response = await core.fetcher<core.BinaryResponse>({
             url: core.url.join(
                 (await core.Supplier.get(this._options.baseUrl)) ??
                     (await core.Supplier.get(this._options.environment)) ??
@@ -565,6 +559,7 @@ export class MountsClient {
             queryParameters: requestOptions?.queryParams,
             requestType: "json",
             body: request,
+            responseType: "binary-response",
             timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 30) * 1000,
             maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,
@@ -897,28 +892,19 @@ export class MountsClient {
     }
 
     /**
-     * @param {AgentaApi.DownloadMountFileRequest} request
-     * @param {MountsClient.RequestOptions} requestOptions - Request-specific configuration.
-     *
      * @throws {@link AgentaApi.UnprocessableEntityError}
-     *
-     * @example
-     *     await client.mounts.downloadMountFile({
-     *         mount_id: "mount_id",
-     *         path: "path"
-     *     })
      */
     public downloadMountFile(
         request: AgentaApi.DownloadMountFileRequest,
         requestOptions?: MountsClient.RequestOptions,
-    ): core.HttpResponsePromise<unknown> {
+    ): core.HttpResponsePromise<core.BinaryResponse> {
         return core.HttpResponsePromise.fromPromise(this.__downloadMountFile(request, requestOptions));
     }
 
     private async __downloadMountFile(
         request: AgentaApi.DownloadMountFileRequest,
         requestOptions?: MountsClient.RequestOptions,
-    ): Promise<core.WithRawResponse<unknown>> {
+    ): Promise<core.WithRawResponse<core.BinaryResponse>> {
         const { mount_id: mountId, path } = request;
         const _queryParams: Record<string, unknown> = {
             path,
@@ -929,7 +915,7 @@ export class MountsClient {
             this._options?.headers,
             requestOptions?.headers,
         );
-        const _response = await core.fetcher({
+        const _response = await core.fetcher<core.BinaryResponse>({
             url: core.url.join(
                 (await core.Supplier.get(this._options.baseUrl)) ??
                     (await core.Supplier.get(this._options.environment)) ??
@@ -939,6 +925,7 @@ export class MountsClient {
             method: "GET",
             headers: _headers,
             queryParameters: { ..._queryParams, ...requestOptions?.queryParams },
+            responseType: "binary-response",
             timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 30) * 1000,
             maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,

web/packages/agenta-api-client/src/generated/api/resources/sessions/client/Client.ts

@@ -1289,28 +1289,19 @@ export class SessionsClient {
     }
 
     /**
-     * @param {AgentaApi.DownloadSessionMountFileRequest} request
-     * @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
-     *
      * @throws {@link AgentaApi.UnprocessableEntityError}
-     *
-     * @example
-     *     await client.sessions.downloadSessionMountFile({
-     *         mount_id: "mount_id",
-     *         path: "path"
-     *     })
      */
     public downloadSessionMountFile(
         request: AgentaApi.DownloadSessionMountFileRequest,
         requestOptions?: SessionsClient.RequestOptions,
-    ): core.HttpResponsePromise<unknown> {
+    ): core.HttpResponsePromise<core.BinaryResponse> {
         return core.HttpResponsePromise.fromPromise(this.__downloadSessionMountFile(request, requestOptions));
     }
 
     private async __downloadSessionMountFile(
         request: AgentaApi.DownloadSessionMountFileRequest,
         requestOptions?: SessionsClient.RequestOptions,
-    ): Promise<core.WithRawResponse<unknown>> {
+    ): Promise<core.WithRawResponse<core.BinaryResponse>> {
         const { mount_id: mountId, path } = request;
         const _queryParams: Record<string, unknown> = {
             path,
@@ -1321,7 +1312,7 @@ export class SessionsClient {
             this._options?.headers,
             requestOptions?.headers,
         );
-        const _response = await core.fetcher({
+        const _response = await core.fetcher<core.BinaryResponse>({
             url: core.url.join(
                 (await core.Supplier.get(this._options.baseUrl)) ??
                     (await core.Supplier.get(this._options.environment)) ??
@@ -1331,6 +1322,7 @@ export class SessionsClient {
             method: "GET",
             headers: _headers,
             queryParameters: { ..._queryParams, ...requestOptions?.queryParams },
+            responseType: "binary-response",
             timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 30) * 1000,
             maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,