refactor(artifact): update admin RPCs and add filter support to ListFilesAdmin

- Reformat long RPC signatures with line wrapping for readability
- Update AddFilesToKnowledgeBaseAdmin to use file resource names
- Update DeleteKnowledgeBaseAdmin docs to describe CASCADE behavior
- Update ListFilesAdmin docs to clarify it bypasses per-file FGA checks
- Add AIP-160 filter field to ListFilesAdminRequest for filtering by
  file ID and tags
- Change UpdateObject body from "object" to "*" for full request body
- Normalize field annotation spacing in file.proto

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: pinglin

artifact/v1alpha/artifact_private_service.proto

@@ -126,25 +126,27 @@ service ArtifactPrivateService {
   // Reset knowledge base embeddings (admin only)
   rpc ResetKnowledgeBaseEmbeddingsAdmin(ResetKnowledgeBaseEmbeddingsAdminRequest) returns (ResetKnowledgeBaseEmbeddingsAdminResponse);
 
-  // Add files to knowledge base (admin only)
+  // List files in a knowledge base without ACL filtering (admin only)
   //
-  // Adds file associations to a target knowledge base by file UIDs.
-  // Files can belong to multiple KBs (many-to-many relationship).
-  // Files that already exist in the target KB are skipped (no duplicates).
-  rpc AddFilesToKnowledgeBaseAdmin(AddFilesToKnowledgeBaseAdminRequest) returns (AddFilesToKnowledgeBaseAdminResponse);
+  // Lists all files in a knowledge base without per-file FGA permission checks.
+  // Unlike the public ListFiles endpoint which filters results based on
+  // can_read_file permission, this admin endpoint returns all files.
+  // Supports AIP-160 filter expressions for filtering by file ID and tags.
+  // Used by internal services (e.g., agent-backend) for service-to-service
+  // file lookups where the calling service handles authorization at its own
+  // level.
+  rpc ListFilesAdmin(ListFilesAdminRequest) returns (ListFilesAdminResponse);
 
-  // Delete knowledge base (admin only)
+  // Delete a knowledge base (admin only)
   //
-  // Force deletes a knowledge base even if it contains files. The files remain
-  // in the file table but lose their KB association (orphaned). Used during
-  // KB consolidation migrations after files have been moved to another KB.
+  // Force-deletes a knowledge base and CASCADE removes file-KB associations.
+  // Used by admin consolidation operations to remove duplicate KBs after moving
+  // files.
   rpc DeleteKnowledgeBaseAdmin(DeleteKnowledgeBaseAdminRequest) returns (DeleteKnowledgeBaseAdminResponse);
 
-  // List files in a knowledge base (admin only)
+  // Add files to a knowledge base (admin only)
   //
-  // Lists all files in a knowledge base without ACL checks. Unlike the public
-  // ListKnowledgeBaseFiles endpoint which requires authentication context, this
-  // admin endpoint allows internal services to list files during migrations and
-  // administrative operations.
-  rpc ListFilesAdmin(ListFilesAdminRequest) returns (ListFilesAdminResponse);
+  // Adds file associations to a target KB by file resource names. Files can
+  // belong to multiple KBs (many-to-many relationship).
+  rpc AddFilesToKnowledgeBaseAdmin(AddFilesToKnowledgeBaseAdminRequest) returns (AddFilesToKnowledgeBaseAdminResponse);
 }

artifact/v1alpha/artifact_public_service.proto

@@ -333,7 +333,7 @@ service ArtifactPublicService {
   rpc UpdateObject(UpdateObjectRequest) returns (UpdateObjectResponse) {
     option (google.api.http) = {
       patch: "/v1alpha/{object.name=namespaces/*/objects/*}"
-      body: "object"
+      body: "*"
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "Artifact"

artifact/v1alpha/knowledge_base.proto

@@ -381,7 +381,7 @@ message DeleteKnowledgeBaseAdminResponse {
 }
 
 // ListFilesAdminRequest represents a request to list files in a knowledge base
-// (admin only).
+// (admin only, bypasses ACL checks).
 message ListFilesAdminRequest {
   // The resource name of the knowledge base.
   // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
@@ -393,6 +393,12 @@ message ListFilesAdminRequest {
   int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
   // Page token for pagination.
   string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+  // AIP-160 filter expression. Supports the same syntax as the public ListFiles API.
+  // Examples:
+  //   - `id="file-abc123"` - filter by hash-based file ID
+  //   - `tags:"agent:collection:col-xxx"` - filter by tag
+  //   - `(id="file-a" OR id="file-b") AND tags:"mytag"` - compound filter
+  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // ListFilesAdminResponse represents a response for listing files (admin only).

openapi/v2/service.swagger.yaml

@@ -1184,88 +1184,11 @@ paths:
           required: true
           type: string
           pattern: namespaces/[^/]+/objects/[^/]+
-        - name: object
-          description: |-
-            The object to update. The object's `name` field identifies it.
-            Format: `namespaces/{namespace}/objects/{object}`
+        - name: body
           in: body
           required: true
           schema:
-            type: object
-            properties:
-              id:
-                type: string
-                description: |-
-                  Immutable canonical resource ID (e.g., "obj-3k7m9p2w5t1").
-                  Hash-based, unique within a namespace.
-                readOnly: true
-              displayName:
-                type: string
-                description: Human-readable display name (user-provided filename).
-              ownerName:
-                type: string
-                title: |-
-                  Resource name of the owner namespace.
-                  Format: `namespaces/{namespace}`
-                readOnly: true
-              creatorName:
-                type: string
-                title: |-
-                  Full resource name of the user who created this object.
-                  Format: `users/{user}`
-                readOnly: true
-              createTime:
-                type: string
-                format: date-time
-                description: Object creation time.
-                readOnly: true
-              updateTime:
-                type: string
-                format: date-time
-                description: Object update time.
-                readOnly: true
-              size:
-                type: string
-                format: int64
-                description: Size in bytes.
-                readOnly: true
-              contentType:
-                type: string
-                description: Content type (MIME type from Content-Type header or file extension).
-                readOnly: true
-              isUploaded:
-                type: boolean
-                description: Whether the file has been uploaded to storage.
-                readOnly: true
-              objectExpireDays:
-                type: integer
-                format: int32
-                description: |-
-                  Object expiration time in days.
-                  If set to 0, the object will not be deleted automatically.
-              lastModifiedTime:
-                type: string
-                format: date-time
-                description: Last modified time (client-provided metadata).
-              deleteTime:
-                type: string
-                format: date-time
-                description: Object delete time (for soft delete). Output only.
-                readOnly: true
-              slug:
-                type: string
-                title: |-
-                  URL-friendly slug derived from display_name.
-                  Example: "my-document-pdf"
-              aliases:
-                type: array
-                items:
-                  type: string
-                description: Previous slugs for backward compatibility when display_name changes.
-                readOnly: true
-            title: |-
-              The object to update. The object's `name` field identifies it.
-              Format: `namespaces/{namespace}/objects/{object}`
+            $ref: '#/definitions/UpdateObjectBody'
       tags:
         - Artifact
       x-stage: alpha
@@ -9481,6 +9404,93 @@ definitions:
         allOf:
           - $ref: '#/definitions/Secret'
     description: UpdateNamespaceSecretResponse contains the updated secret.
+  UpdateObjectBody:
+    type: object
+    properties:
+      object:
+        type: object
+        properties:
+          id:
+            type: string
+            description: |-
+              Immutable canonical resource ID (e.g., "obj-3k7m9p2w5t1").
+              Hash-based, unique within a namespace.
+            readOnly: true
+          displayName:
+            type: string
+            description: Human-readable display name (user-provided filename).
+          ownerName:
+            type: string
+            title: |-
+              Resource name of the owner namespace.
+              Format: `namespaces/{namespace}`
+            readOnly: true
+          creatorName:
+            type: string
+            title: |-
+              Full resource name of the user who created this object.
+              Format: `users/{user}`
+            readOnly: true
+          createTime:
+            type: string
+            format: date-time
+            description: Object creation time.
+            readOnly: true
+          updateTime:
+            type: string
+            format: date-time
+            description: Object update time.
+            readOnly: true
+          size:
+            type: string
+            format: int64
+            description: Size in bytes.
+            readOnly: true
+          contentType:
+            type: string
+            description: Content type (MIME type from Content-Type header or file extension).
+            readOnly: true
+          isUploaded:
+            type: boolean
+            description: Whether the file has been uploaded to storage.
+            readOnly: true
+          objectExpireDays:
+            type: integer
+            format: int32
+            description: |-
+              Object expiration time in days.
+              If set to 0, the object will not be deleted automatically.
+          lastModifiedTime:
+            type: string
+            format: date-time
+            description: Last modified time (client-provided metadata).
+          deleteTime:
+            type: string
+            format: date-time
+            description: Object delete time (for soft delete). Output only.
+            readOnly: true
+          slug:
+            type: string
+            title: |-
+              URL-friendly slug derived from display_name.
+              Example: "my-document-pdf"
+          aliases:
+            type: array
+            items:
+              type: string
+            description: Previous slugs for backward compatibility when display_name changes.
+            readOnly: true
+        title: |-
+          The object to update. The object's `name` field identifies it.
+          Format: `namespaces/{namespace}/objects/{object}`
+      updateMask:
+        type: string
+        description: The update mask specifies which fields to update.
+    description: |-
+      UpdateObjectRequest represents a request to update an object.
+      Follows AIP-134: resource's `name` field identifies it.
+    required:
+      - object
   UpdateObjectResponse:
     type: object
     properties: