axio-tools-local

Async handlers for filesystem operations, shell commands, and Python execution on the harness host.

async axio_tools_local.list_files.list_files(directory: Annotated[str, ~axio.field.FieldInfo(description, default=MISSING, ge=None, le=None, strict=True)] = '.') → str

List files and directories. Shows permissions, size, modification time, and name for each entry. Directories are listed first and marked with a trailing slash. Use this to explore the project structure before reading or editing files.

async axio_tools_local.read_file.read_file(filename: ~typing.Annotated[str, ~axio.field.FieldInfo(description=, default=MISSING, ge=None, le=None, strict=True)], max_chars: int = 32768, binary_as_hex: bool = True, start_line: int | None = None, end_line: int | None = None, line_numbers: bool = False) → ReadFileResult

Read file contents. Returns text for text files, hex for binaries. Audio files (mp3/wav/ogg/flac/etc.), image files (jpg/png/gif/webp) and video files (mp4/webm/etc.) are returned as multimodal content blocks for capable models. Lines are 1-indexed: start_line=1 is the first line, end_line=3 includes line 3. Pass line_numbers=True to prefix each line with its 1-based line number (tab-separated) — required before calling patch_file. Large files are truncated to max_chars. Always read the file before editing it with write_file or patch_file.

async axio_tools_local.write_file.write_file(file_path: ~typing.Annotated[str, ~axio.field.FieldInfo(description=, default=MISSING, ge=None, le=None, strict=True)], content: str, mode: int = 420) → str

Create or overwrite a file with the given content. Parent directories are created automatically. Use this for new files or full rewrites. For partial edits prefer patch_file instead.

async axio_tools_local.patch_file.patch_file(file_path: ~typing.Annotated[str, ~axio.field.FieldInfo(description=, default=MISSING, ge=None, le=None, strict=True)], from_line: int, to_line: int, content: str, mode: int = 420) → str

Replace a range of lines in an existing file. Lines are 1-indexed: from_line and to_line are both inclusive (from_line=2, to_line=4 replaces lines 2, 3, 4). To insert without deleting, set to_line = from_line - 1. Always read the file first with line_numbers=True to get correct line numbers. Patch each file at most once per read — re-read with line_numbers=True after patching before issuing another patch to the same file. Use this for surgical edits instead of rewriting the whole file with write_file.

async axio_tools_local.shell.shell(command: ~typing.Annotated[str, ~axio.field.FieldInfo(description=, default=MISSING, ge=None, le=None, strict=True)], timeout: int = 5, cwd: ~typing.Annotated[str, ~axio.field.FieldInfo(description=, default=MISSING, ge=None, le=None, strict=True)] = '.', stdin: str | None = None) → str

Run a shell command and return combined stdout/stderr. Use for git, build tools, grep, tests, or any CLI operation. Non-zero exit codes are reported. Optionally pass stdin data for commands that read from standard input. The default timeout is 5s — raise it for long-running commands (installs, builds, and test suites often need 60-300s). Avoid interactive commands.

async axio_tools_local.run_python.run_python(code: str, cwd: str = '.', timeout: int = 5, stdin: str | None = None) → str

Run a Python code snippet in a subprocess and return stdout/stderr. The code is written to a temp file and executed with the current interpreter. Use for calculations, data processing, or testing small scripts. Optionally pass stdin data. Non-zero exit codes and tracebacks are returned as-is.