Files

Preview

Reading, writing, searching and publishing files inside a run.

Each run gets an isolated working filesystem. Files are ephemeral until explicitly published as artifacts.

Operations#

Tool	Effect class	Notes
`files.read`	`none`	Range reads supported for large files
`files.write`	`workspace_write`	Checkpointed; reversible via rollback
`files.search`	`none`	Content and path search across the working tree
`files.list`	`none`	Directory listing with size and type
`files.delete`	`workspace_write`	Soft delete until the run ends
`artifacts.publish`	`workspace_write`	Promotes a file to durable storage

Large files#

Files above the context threshold are never read wholesale into reasoning context. They are registered as datasets and queried through code execution, which keeps precision high and cost bounded.

Querying a dataset instead of reading it

import polars as pl

df = pl.read_parquet(class="tok-str">"/work/data/transactions.parquet")

suspicious = (
    df.filter(pl.col(class="tok-str">"amount") > 10_000)
      .group_by(class="tok-str">"counterparty")
      .agg(pl.len().alias(class="tok-str">"n"), pl.col(class="tok-str">"amount").sum().alias(class="tok-str">"total"))
      .sort(class="tok-str">"total", descending=True)
      .head(class="tok-num">25)
)

print(suspicious)

Last updated 2026-09-01