feat(BA-6054): expose subpath on v2 REST/GraphQL session MountItemInput (#11628)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jopemachine

changes/11628.feature.md

@@ -0,0 +1 @@
+Expose `subpath` on the v2 REST/GraphQL session `MountItemInput` so `EnqueueSession` callers can mount a vfolder subpath. Follow-up to #11608, which only exposed `subpath` on the legacy `CreationConfigV*.mount_options` wire schema.

docs/manager/graphql-reference/supergraph.graphql

@@ -17112,6 +17112,11 @@ input SessionMountItemInput
 
   """Mount permission ('rw' or 'ro')."""
   permission: String = null
+
+  """
+  Added in UNRELEASED. Subpath within the vfolder to mount. Null mounts the vfolder root.
+  """
+  subpath: String = null
 }
 
 """Added in 25.13.0."""

docs/manager/graphql-reference/v2-schema.graphql

@@ -11636,6 +11636,11 @@ input SessionMountItemInput {
 
   """Mount permission ('rw' or 'ro')."""
   permission: String = null
+
+  """
+  Added in UNRELEASED. Subpath within the vfolder to mount. Null mounts the vfolder root.
+  """
+  subpath: String = null
 }
 
 """Added in 26.4.2. Additional resource options for session creation."""

src/ai/backend/common/dto/manager/v2/model_serving/request.py

@@ -4,12 +4,12 @@
 
 from __future__ import annotations
 
-from typing import Any
 from uuid import UUID
 
 from pydantic import ConfigDict, Field, NonNegativeFloat, field_validator
 
 from ai.backend.common.api_handlers import BaseRequestModel
+from ai.backend.common.dto.manager.session.types import MountOption
 from ai.backend.common.types import RuntimeVariant
 
 __all__ = (
@@ -36,9 +36,12 @@ class ServiceConfigInput(BaseRequestModel):
         default="/models",
         description="Mount destination for the model VFolder inside the inference session",
     )
-    extra_mounts: dict[UUID, Any] = Field(
+    extra_mounts: dict[UUID, MountOption] = Field(
         default_factory=dict,
-        description="Extra VFolders mounted to model service session",
+        description=(
+            "Extra VFolders mounted to the model service session, keyed by vfolder UUID."
+            " Each value carries per-mount options (mount destination, permission, subpath)."
+        ),
     )
     environ: dict[str, str] | None = Field(
         default=None,

src/ai/backend/common/dto/manager/v2/session/request.py

@@ -261,6 +261,14 @@ class MountItemInput(BaseRequestModel):
     permission: str | None = Field(
         default=None, description="Mount permission override ('rw' or 'ro')."
     )
+    subpath: str | None = Field(
+        default=None,
+        min_length=1,
+        description=(
+            "Subpath within the vfolder to mount. Omit (null) to mount the vfolder root."
+            " Empty string is rejected."
+        ),
+    )
 
 
 class BatchConfigInput(BaseRequestModel):

src/ai/backend/manager/api/adapter_options/session/options.py

@@ -200,6 +200,7 @@ def _mount_items_to_entries(items: Sequence[MountItemInput]) -> list[MountInfoEn
                 vfolder_id=VFolderUUID(item.vfolder_id),
                 mount_destination=item.mount_path,
                 mount_perm=perm or MountPermission.READ_WRITE,
+                subpath=item.subpath,
             )
         )
     return result

src/ai/backend/manager/api/adapters/session/adapter.py

@@ -251,6 +251,7 @@ async def enqueue(
                     vfolder_id=VFolderUUID(m.vfolder_id),
                     mount_destination=m.mount_path,
                     mount_perm=(MountPermission(m.permission) if m.permission else None),
+                    subpath=m.subpath,
                 )
                 for m in input.mounts
             ]

src/ai/backend/manager/api/gql/session/types.py

@@ -51,6 +51,7 @@
     ProjectSessionScope,
     SessionStatusFilter,
 )
+from ai.backend.common.meta.meta import NEXT_RELEASE_VERSION
 from ai.backend.common.types import ImageID, SessionId
 from ai.backend.manager.api.gql.base import OrderDirection, StringFilter, UUIDFilter, encode_cursor
 from ai.backend.manager.api.gql.common.types import (
@@ -533,6 +534,13 @@ class SessionMountItemInputGQL(PydanticInputMixin[MountItemInputDTO]):
     vfolder_id: ID = gql_field(description="Virtual folder UUID.")
     mount_path: str | None = gql_field(default=None, description="Custom mount path.")
     permission: str | None = gql_field(default=None, description="Mount permission ('rw' or 'ro').")
+    subpath: str | None = gql_added_field(
+        BackendAIGQLMeta(
+            added_version=NEXT_RELEASE_VERSION,
+            description="Subpath within the vfolder to mount. Null mounts the vfolder root.",
+        ),
+        default=None,
+    )
 
 
 @gql_pydantic_input(