autourgos-cap-fs

Filesystem tools for an Autourgos agent — read, write, list, glob, search, move, and delete — implementing autourgos_core.Capability so they plug straight into Engine(capabilities=[...]) and get root-jailed, risk-tiered, and journaled by autourgos-policy for free.

from autourgos_cap_fs import FsCapability

fs = FsCapability(trash_dir="C:/work/.trash")
fs.write_file("C:/work/report.md", "Hello")
print(fs.read_file("C:/work/report.md"))
# Hello

Features

• Seven tools: read_file, list_dir, glob_files, search_text, write_file, move_file, delete_file
• No root-jail of its own — every tool declares Resource(kind="path", ...) so autourgos_policy.FilesystemPolicy enforces containment, symlink/.. resolution, and case-insensitive Windows path handling
• Nothing is ever silently discarded: delete_file moves the file into a managed trash directory instead of removing it, and write_file backs up whatever it's about to overwrite first
• Undoable: FsCapability.register_undo(registry) wires the trash store into autourgos_policy.UndoRegistry — journal.undo_last(registry) restores the exact prior state
• Atomic writes: write_file writes to a temp file and os.replace()s it into place, never leaving a half-written file behind
• Fully typed (py.typed), zero required dependency beyond autourgos-core/autourgos-policy

Table of Contents

• Install
• Tools
• Usage
  • Direct calls
  • Through a PolicyGate
  • With autourgos-kernel
• Soft Delete and Undo
• API Reference
• License

Install

pip install autourgos-cap-fs

Requires autourgos-core>=0.2.0 and autourgos-policy>=0.3.1.

Tools

Usage

Direct calls

from autourgos_cap_fs import FsCapability

fs = FsCapability(trash_dir="C:/work/.trash")

fs.write_file("C:/work/notes.txt", "First draft")
print(fs.read_file("C:/work/notes.txt"))
# First draft

print(fs.list_dir("C:/work"))
# notes.txt

print(fs.glob_files("C:/work", "*.txt"))
# C:/work/notes.txt

print(fs.search_text("C:/work", "draft"))
# C:/work/notes.txt:1: First draft

Through a PolicyGate

from autourgos_cap_fs import FsCapability
from autourgos_core import Action, Resource, Risk
from autourgos_policy import PolicyConfig, PolicyExecutor, PolicyGate

fs = FsCapability(trash_dir="C:/work/.trash")
gate = PolicyGate(
    PolicyConfig(profile="assisted", writable_roots=("C:/work/output",), readable_roots=("C:/work",))
)
executor = PolicyExecutor(gate, confirmation_callback=lambda action, decision: True)

action = Action(
    tool="write_file",
    arguments={"path": "C:/work/output/report.md", "content": "Done"},
    targets=[Resource("path", "C:/work/output/report.md")],
    risk=Risk.WRITE,
)
outcome = await executor.execute(action, fs.write_file)
assert outcome.executed

A path outside writable_roots/readable_roots is denied by FilesystemPolicy before fs.write_file ever runs — cap-fs itself never checks containment.

With autourgos-kernel

from autourgos_kernel import Engine, Run
from autourgos_policy import PolicyConfig, PolicyExecutor, PolicyGate

engine = Engine(llm=my_llm, capabilities=[fs])
gate = PolicyGate(PolicyConfig(profile="assisted", writable_roots=("C:/work/output",)))
result = await engine.run(Run(goal="Write a report to output/report.md"), policy_executor=PolicyExecutor(gate))

Soft Delete and Undo

write_file (on overwrite) and delete_file never discard prior content — both stash it in a TrashStore first and return an autourgos_policy.ExecutionValue with reversible=True and an fscap:<id> undo token. move_file records enough to move the file back too.

from autourgos_cap_fs import FsCapability
from autourgos_policy import EffectJournal, UndoRegistry

fs = FsCapability(trash_dir="C:/work/.trash")
registry = UndoRegistry()
fs.register_undo(registry)

journal = EffectJournal("run-effects.jsonl")
# ... run tools through a PolicyExecutor(gate, journal=journal) ...

outcome = await journal.undo_last(registry)
assert outcome.ok

API Reference

FsCapability(trash_dir: str)

TrashStore(root: str)

The backing store FsCapability owns internally (fs.trash) — stash_delete/stash_overwrite/ stash_create/stash_move record what happened, restore(entry_id) reverses it. Not root-jailed itself; pair FsCapability with FilesystemPolicy for containment.

License

Apache License 2.0, Copyright (c) 2026 Jitin Kumar Sengar