Builtin read tool panics on UTF-8 character boundary at 2000-byte truncation

[zoubo9034]

Summary

The builtin read tool panics when the 2000th byte of the target file falls inside a multibyte UTF-8 character.

This is reproducible through the Python API with a completely generic local setup. It does not require MCP servers, project files, or private data.

Minimal repro

from pathlib import Path
from tempfile import TemporaryDirectory

from a3s_code import Agent

with TemporaryDirectory(prefix="a3s-read-repro-") as tmp_dir:
    workspace = Path(tmp_dir)
    boundary_file = workspace / "boundary.txt"

    # 1999 ASCII bytes + one 3-byte UTF-8 char + trailing ASCII.
    # This places byte index 2000 inside a multibyte code point.
    boundary_file.write_text("a" * 1999 + "频" + "z" * 20, encoding="utf-8")

    agent = Agent.create("/path/to/your/working/config.hcl")
    session = agent.session(str(workspace), permissive=True)

    session.tool("read", {"file_path": str(boundary_file)})

Steps to reproduce

1. Create any valid local a3s-code config.
2. Run the script above.
3. Observe the builtin read tool panic.

Expected behavior

The read tool should either:

• return a valid truncated UTF-8 string, or
• return a normal tool error

but it should not panic the runtime.

Actual behavior

The runtime panics with:

thread '<unnamed>' panicked at .../core/src/tools/builtin/read.rs:99:22:
byte index 2000 is not a char boundary; it is inside '频' (bytes 1999..2002)
...
pyo3_runtime.PanicException: byte index 2000 is not a char boundary; it is inside '频' ...

Notes

• This appears to be a byte-slicing vs UTF-8 character-boundary bug in builtin read.
• The issue is independent of my application code.
• A temporary workaround on my side is to avoid feeding non-ASCII intermediate files to the builtin read tool.

[ZhiXiao-Lin]

Status: Fixed ✅

This bug has been fixed. The issue was in the truncate_utf8 function which was slicing bytes directly without checking UTF-8 character boundaries.

Root Cause

In core/src/tools/builtin/read.rs:99, the call to truncate_utf8(line, MAX_LINE_LENGTH) was passing the raw byte limit, but truncate_utf8 was doing a simple &s[..max_bytes] slice which panics when max_bytes falls inside a multibyte UTF-8 character.

Fix

The truncate_utf8 function in core/src/text.rs now walks back from max_bytes to find a valid character boundary:

pub(crate) fn truncate_utf8(s: &str, max_bytes: usize) -> &str {
    if s.len() <= max_bytes {
        return s;
    }

    let mut end = max_bytes;
    while end > 0 && !s.is_char_boundary(end) {
        end -= 1;
    }

    &s[..end]
}

Regression Test

A test case test_read_truncation_at_utf8_boundary was added to core/src/tools/builtin/read.rs that reproduces the exact scenario from this issue (1999 ASCII bytes + "频" + 20 ASCII bytes).

cargo test -p a3s-code-core test_read_truncation_at_utf8_boundary
# → ok

The fix ensures that when byte index 2000 falls inside a multibyte character (like "频" which is 3 bytes), the truncation finds the nearest valid character boundary instead of panicking.