files¶

files ¶

File I/O tools — read, write, edit, append for agent and CLI use.

read_file ¶

read_file(path: str) -> str

Read a file or directory listing from the project.

For files: returns content prefixed with path and line count. Files over 200 lines are truncated with a summary. For directories: returns a listing of contained entries. Binary files trigger a readable error message.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path relative to project root (e.g., "searches/file.md").	required

Returns:

Type	Description
`str`	Formatted string with file contents or directory listing.
`str`	Error messages are prefixed with "Error:" for unrecognised paths.

write_file ¶

write_file(path: str, content: str) -> str

Create or overwrite a file in the sessions/ workspace.

Restricted to paths within SESSIONS_DIR via the _resolve() security check. Creates parent directories as needed.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path relative to project root (must be within sessions/).	required
`content`	`str`	Full text content to write to the file.	required

Returns:

Type	Description
`str`	Success message with relative path, line count, and character count.
`str`	Error messages are prefixed with "Error:".

edit_file ¶

edit_file(path: str, old_text: str, new_text: str) -> str

Find and replace text in a sessions/ workspace file.

Performs exact string matching. Requires a unique match — zero matches returns an error, multiple matches returns a count with guidance to narrow the search text.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path relative to project root (must be within sessions/).	required
`old_text`	`str`	Exact text to find and replace.	required
`new_text`	`str`	Replacement text.	required

Returns:

Type	Description
`str`	Success message with relative path, or an error message
`str`	(prefixed with "Error:") if the file is not found, the text
`str`	is not found, or multiple matches exist.

append_file ¶

append_file(path: str, content: str) -> str

Append text to a file in the sessions/ workspace.

If the file does not exist, creates it (behaves like write_file). If the file exists, appends with a leading newline separator unless the content already starts with one.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path relative to project root (must be within sessions/).	required
`content`	`str`	Text to append to the file.	required

Returns:

Type	Description
`str`	Success message indicating whether the file was created or
`str`	appended to, with relative path and added line count.
`str`	Error messages are prefixed with "Error:".