agent-filesystem

agent-filesystem is the host filesystem provider for the agent system.

It exposes admitted, scoped filesystem capabilities. It is not an ambient disk-access backdoor.

Purpose

agent-filesystem owns host filesystem operations for provider/plugin use:

• scoped file reads
• scoped file writes
• directory listing
• metadata/stat inspection
• safe create/update flows
• atomic write/replace helpers
• bounded content reads
• explicit delete/move/copy operations when admitted
• filesystem audit events

Authority boundaries

agent-filesystem is not the action authority.

• agent-core-system owns action admission, approval, policy, audit, execution envelopes, and host-admitted filesystem scopes.
• rpc-plugin-system owns substrate runtime, transport, lifecycle, plugin identity/generation, and supervision.
• agent-keyring owns credentials and secrets; filesystem access must not become secret exfiltration.
• agent-filesystem owns filesystem operation mechanics, scope enforcement, and local path safety.

Filesystem access is not automatically authorized because a process can reach the host disk. All filesystem operations must be scoped and admitted.

Provider diagnostics

Filesystem provider diagnostics are structured, redacted observability facts emitted through the inherited rpc-plugin-system SDK/helper path. They may report provider/plugin generation, capability, operation, correlation IDs, bounded status, coarse error/degraded classes, counts, sizes, and non-authoritative digest facts.

They must not contain raw request paths, normalized backend paths, admitted roots, provider-private paths, file descriptors, path handles, COW/trash/snapshot storage paths, reusable rollback/artifact refs, raw authority_use_ref values, sockets, sessions, credentials, read/write/patch payload bytes, upstream bodies, or reusable handles. Diagnostics do not grant filesystem authority and do not replace agent-core-system admission.

Non-goals

• Do not provide ambient root filesystem access.
• Do not bypass agent-core-system admission.
• Do not silently follow symlinks across scope boundaries.
• Do not treat path strings from models/providers as trusted.
• Do not store credentials here.
• Do not hide destructive operations behind convenience helpers.

First useful implementation slice

1. Define filesystem capability contracts.
2. Define host-admitted filesystem scope model.
3. Define path normalization and symlink policy.
4. Add fake filesystem backend tests.
5. Add local backend only after scope checks are tested.
6. Add rpc-plugin-system plugin wiring after contract stability.

Release status

This source tree defines agent-filesystem v1.0.0. The repository workflow records the V1 implementation as complete. Tagging, publication, deployment, and hosted Release status are separate distribution facts and are not asserted here.

License

Licensed under the MIT License. See LICENSE.