Swarmauri Tool Scroll File
swarmauri_tool_scrollfile gives agents and workflows a bounded way to inspect
large UTF-8 text files. It returns numbered lines together with stable previous
and next page positions, avoiding full-file output.
Features
- Restricts reads to service-configured filesystem roots by default.
- Rejects symlinks unless the service owner explicitly opts in.
- Caps page size, scanned lines and bytes, individual-line size, elapsed time, and returned bytes.
- Navigates up or down using one-based line anchors.
- Returns line numbers and explicit previous/next page positions.
- Clamps an anchor beyond EOF to the final available page.
- Validates paths and navigation arguments before reading.
- Registers as a
swarmauri.toolsentry point. - Supports Python 3.10, 3.11, 3.12, 3.13, and 3.14.
Installation
uv add swarmauri_tool_scrollfile
pip install swarmauri_tool_scrollfile
Usage
from pathlib import Path
from swarmauri_tool_scrollfile import ScrollFileTool
tool = ScrollFileTool(allowed_roots=[str(Path("logs").resolve())])
first_page = tool("logs/application.log")
if first_page["has_next"]:
second_page = tool(
"logs/application.log",
start_line=first_page["next_start_line"],
page_size=first_page["page_size"],
direction="down",
)
An upward request treats start_line as the current page anchor and returns
the preceding page:
previous_page = tool(
"logs/application.log",
start_line=second_page["start_line"],
page_size=second_page["page_size"],
direction="up",
)
Each result contains lines, start_line, end_line, page_size,
has_previous, has_next, previous_start_line, and next_start_line.
Security and Resource Limits
file_path is agent-controlled, but filesystem policy is not. The service
owner configures allowed_roots when creating the tool; requested paths are
canonically resolved and must remain inside one of those roots. Paths
containing symlinks are rejected by default, and the resolved target must be a
regular file.
tool = ScrollFileTool(
allowed_roots=["/srv/application-logs", "/srv/reports"],
)
The default root is the process working directory. Set allow_symlinks=True
only when following symlinks is part of the trusted service configuration.
allow_unrestricted_paths=True is a privileged opt-in that disables root
containment; use it only when the process already runs in a least-privilege
filesystem sandbox.
Each call enforces service-owned limits: at most 100 returned lines, 100,000
scanned lines, 8 MiB scanned data, 64 KiB per line, 256 KiB returned content,
and two seconds of file-reading time. Exceeding a limit raises ValueError
rather than returning a partial or ambiguous page.
Workflow Integration
from swarmauri_standard.tools.ToolCollection import ToolCollection
from swarmauri_tool_scrollfile import ScrollFileTool
tools = ToolCollection(
tools=[ScrollFileTool(allowed_roots=["/srv/application-logs"])]
)
Performance
The tool streams from the start of the file to the requested page and holds at
most one page plus one lookahead line in memory, subject to the limits above.
Memory use is O(page_size); runtime is O(start_line + page_size) for a
stateless request.
License
This package is licensed under Apache-2.0.
Descriptor-based opening and page boundaries
Where Linux openat2 is available, lookups use beneath-root resolution.
If the syscall is unavailable, the POSIX fallback opens a single child of
the trusted root with a no-follow lookup. Nested file lookups fail
with ENOTSUP. Policy denials such as EPERM or EACCES are returned as
errors, including when opening the configured root.
The service must control the configured root, its ancestors, and mount configuration. A root handle identifies the directory opened by the tool. Filesystem permissions still govern concurrent changes to opened objects.
allow_symlinks=True requires Linux openat2 and permits only relative links
whose complete resolution stays beneath the selected root. Absolute links,
root escapes, and magic links are rejected. This intentionally narrows the old
opt-in. allow_unrestricted_paths=True anchors at the filesystem root; it does
not independently enable symlink following. Configured root paths cannot
contain symlinks or parent traversal.
Opened handles retain inode identity if directories are renamed. This prevents symlink substitution from redirecting a read, but does not freeze file contents or prevent another actor from moving an opened directory. Services must control permissions on their trees.
The returned-content budget applies to the page actually returned, including EOF fallback. The preceding rolling buffer is bounded separately by page size and individual-line limits; large earlier lines no longer reject a small later page merely because they exceed the return budget. A one-byte lookahead detects the next page without decoding or line-validating its contents. That probe is still charged against scanned-line and scanned-byte limits. Time checks remain cooperative and cannot interrupt a filesystem syscall already blocked in the kernel.
Windows filesystem support
On Windows the backend opens the local drive by its volume identity and opens each component relative to a held directory handle. It rejects junctions and other reparse points and does not accept UNC or device paths, alternate data streams, or ambiguous trailing dots or spaces, or reserved DOS basenames. Ancestors are opened for traversal without requiring listing access. Volume and directory handles deny delete sharing during traversal. Returned paths are descriptive snapshots. Confined reads check the opened file and reject files with multiple hard links. Filesystem permissions govern concurrent changes to file contents.
Metadata
Release files for swarmauri_tool_scrollfile 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| swarmauri_tool_scrollfile-0.1.0.tar.gz | 17.4 kB | Without provenance | Details for swarmauri_tool_scrollfile-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swarmauri_tool_scrollfile-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for swarmauri_tool_scrollfile-0.1.0-py3-none-any.whl |
Total release size: 35.1 kB
Release files / swarmauri_tool_scrollfile-0.1.0.tar.gz
| Download URL | swarmauri_tool_scrollfile-0.1.0.tar.gz |
|---|---|
| Size | 17.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4839659b5d8b145ef2090ffe2637f100dff083dde9ee4a29a0a9ad709969c553
|
|
BLAKE2b-256 checksum How to use checksums |
09655133bb5219f6d26f3d98dc839713e253d524dd3ab6e66ba52d83241abd23
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / swarmauri_tool_scrollfile-0.1.0-py3-none-any.whl
| Download URL | swarmauri_tool_scrollfile-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0f1bd54aedfb5571f18c476c9bbe47105892c6200c6defa5ae084f05982a1300
|
|
BLAKE2b-256 checksum How to use checksums |
da5691aca58d1d3e67f21f7a362cbb997c8328d92f68f063d78a0a5559288fcc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for swarmauri_tool_scrollfile 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.