fix(tool): built-in file tools support relative tools

[fang-tech]

AgentScope-Java Version

[The version of AgentScope-Java you are working on, e.g. 1.0.8, check your pom.xml dependency version or run mvn dependency:tree | grep agentscope-parent:pom(only mac/linux)]

Description

[Please describe the background, purpose, changes made, and how to test this PR]

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[gemini-code-assist]

Summary of Changes

Hello @fang-tech, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines the built-in file tools to better support relative paths, particularly when operating within a restricted base directory. The changes ensure that file operations correctly interpret relative paths and maintain security by preventing unauthorized access outside the designated directory. Additionally, the documentation for skill prompts has been streamlined to provide clearer guidance on skill usage and resource access.

Highlights

• Enhanced File Path Handling: The FileToolUtils.validatePath method has been updated to correctly resolve relative file paths against a provided base directory, improving flexibility and security for file operations.
• Improved Skill Prompt Documentation: The AgentSkillPromptProvider now features clearer and more concise documentation for skill usage, including explicit details on how path information and code examples are provided when a skill is loaded.
• Comprehensive Unit Tests for Path Validation: Extensive new unit tests have been added to FileToolUtilsTest to cover various scenarios for path validation, including relative paths, absolute paths, path traversal attempts, and edge cases like null or empty paths.
• File Tool Integration Tests: Tests for WriteFileTool have been expanded to ensure that file writing and insertion operations correctly handle relative paths when a base directory is specified.

Changelog

• agentscope-core/src/main/java/io/agentscope/core/skill/AgentSkillPromptProvider.java
  • Updated skill usage notes to be more concise and informative.
  • Added a new 'Path Information' section to clarify how skill resources and code examples are provided upon skill loading.
  • Simplified the explanations for template fields like <name>, <description>, and <skill-id>.
• agentscope-core/src/main/java/io/agentscope/core/tool/file/FileToolUtils.java
  • Modified the validatePath method to resolve relative filePath arguments against the baseDir if baseDir is provided, before performing path validation.
  • Added Javadoc comments to validatePath to explain the new behavior for handling relative and absolute paths in conjunction with a baseDir.
• agentscope-core/src/test/java/io/agentscope/core/tool/file/FileToolUtilsTest.java
  • Added new test cases for validatePath to verify correct handling of relative paths when a baseDir is present.
  • Included tests to confirm rejection of path traversal attacks when a baseDir is specified.
  • Added tests for validating absolute paths both within and outside the baseDir.
  • Introduced tests for validatePath behavior with relative and absolute paths when no baseDir is provided.
  • Added tests for edge cases such as null, empty, and whitespace-only file paths.
  • Verified correct path normalization for paths containing . and .. within a baseDir.
• agentscope-core/src/test/java/io/agentscope/core/tool/file/WriteFileToolTest.java
  • Added a test case testWriteTextFile_RelativePathWithBaseDir to ensure writeTextFile correctly handles relative paths when a baseDir is configured.
  • Added a test case testInsertTextFile_RelativePathWithBaseDir to verify insertTextFile correctly processes relative paths with a baseDir.

Activity

• The author has checked all items in the pull request checklist, indicating that the code has been formatted, all tests are passing, Javadoc comments are complete, related documentation has been updated, and the code is ready for review.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a fix to allow built-in file tools to correctly handle relative paths when a baseDir is specified. The core logic change in FileToolUtils.validatePath is sound and correctly resolves relative paths against the base directory, which is a good improvement for security and usability. The accompanying tests are comprehensive and cover various scenarios, ensuring the new logic is robust. The update to the agent skill prompt also improves clarity. Overall, this is a solid contribution. I've left one minor comment regarding a test's display name for better maintainability.

[Copilot]

Pull request overview

This pull request fixes the file tool utilities to properly support relative paths when a base directory is specified. Previously, relative paths were always resolved against the current working directory; now they are correctly resolved relative to the specified baseDir.

Changes:

• Modified FileToolUtils.validatePath() to resolve relative paths relative to the baseDir when specified
• Added comprehensive unit tests for the validatePath method covering relative paths, absolute paths, path traversal attacks, and various edge cases
• Added integration tests for WriteFileTool demonstrating relative path usage with baseDir
• Simplified and improved the AgentSkillPromptProvider documentation to be more concise and remove hardcoded path assumptions

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
agentscope-core/src/main/java/io/agentscope/core/tool/file/FileToolUtils.java	Core logic change: resolve relative paths relative to baseDir instead of current working directory
agentscope-core/src/test/java/io/agentscope/core/tool/file/FileToolUtilsTest.java	Comprehensive unit tests for validatePath method with relative and absolute paths
agentscope-core/src/test/java/io/agentscope/core/tool/file/WriteFileToolTest.java	Integration tests demonstrating relative path usage in writeTextFile and insertTextFile
agentscope-core/src/main/java/io/agentscope/core/skill/AgentSkillPromptProvider.java	Simplified skill usage documentation to remove hardcoded path assumptions

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[chickenlj]

LGTM.