fix(tool): reject out-of-range Read offset and limit - #3303

AgentScope Version

2.0.10

Description

Fixes #3291.

What Problem This Solves

This PR fixes a pagination validation gap in the builtin Read tool.

The Read schema already declares offset as a 1-based line number with ge=1, and limit with ge=1, le=2000 (src/agentscope/tool/_builtin/_read.py:60-72), but — unlike Grep and Glob — nothing validated them at runtime, so tool calls whose arguments bypass schema validation reached the slicing step unvalidated.

_read_text_file slices with lines[start_idx:end_idx] where start_idx = offset - 1 (src/agentscope/tool/_builtin/_read.py:533-535). A non-positive offset makes start_idx negative, so Python addresses the list from its end and the tool returns the tail of the file labeled with line numbers 0 or negative, with a success state. limit <= 0 returns empty text, also with a success state. Reading a 10-line file on main:

read = Read()
await read.call(file_path=p, offset=0)   # -> "     0\tline 10", state=running
await read.call(file_path=p, offset=-3)  # -> lines 7..10 labeled -3..0, state=running
await read.call(file_path=p, limit=0)    # -> "", state=running

Because the tool reports success, the model receives content from the wrong part of the file with impossible line numbers and no signal to self-correct.

Change

Add runtime validation in _read_text_file, before any slicing, mirroring the Grep/Glob pagination guards:

• offset < 1 -> Error: offset must be at least 1, got: {offset}.
• limit < 1 or limit > 2000 -> Error: limit must be between 1 and 2000, got: {limit}.

Both return a ToolResultState.ERROR chunk so the model can retry with valid arguments. Valid reads are unchanged, and since offset/limit only apply to plain text files, the guards live in _read_text_file so the PDF and image paths are untouched.

Testing

• New regression tests on unpatched main (before the fix):

FAILED tests/builtin_read_test.py::ReadToolTest::test_invalid_limit_returns_error
FAILED tests/builtin_read_test.py::ReadToolTest::test_non_positive_offset_returns_error
AssertionError: <ToolResultState.RUNNING: 'running'> != 'error' : 0

• After the fix:
  • pytest tests/builtin_read_test.py -> 20 passed in 0.86s
  • pytest tests/builtin_read_test.py tests/builtin_write_test.py tests/builtin_edit_test.py tests/builtin_grep_test.py tests/builtin_glob_test.py tests/builtin_bash_test.py tests/builtin_file_cache_test.py -> 122 passed, 61 subtests passed in 2.13s
  • pytest tests -> 2746 passed, 147 skipped, 600 subtests passed in 167.54s
  • pre-commit run --files src/agentscope/tool/_builtin/_read.py tests/builtin_read_test.py -> all hooks passed (mypy, black, flake8, pylint, pyroma)

Checklist

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

• An issue has been created for this PR
• I have read the CONTRIBUTING.md
• Docstrings are in Google style
• Related documentation has been updated (e.g. links, examples, etc.) in documentation repository
• Code is ready for review