# `SuperPi.Env.ClientFS`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/env/client_fs.ex#L1)

Reads a file through the ACP client, so the agent sees the unsaved editor buffer.

This is the one real gain of ACP `fs/read_text_file`. Everything else about delegating file access
costs something: it routes I/O around the workspace boundary check and around `Env.FileLock`, and it
breaks outright when the machine runs on another node than the ACP connection, because the
editor's filesystem does not exist there. So `maybe_read/4` asks the client only when all of these hold:

1. `config :super_pi, :acp, fs_delegation:` is not `:never`. Values: `:unsaved_only` (default),
   `:never`, `:always`.
2. An `SuperPi.ACP.Server` on this node serves the conversation and its client advertised
   `fs.readTextFile`.
3. The workspace is `local`.
4. The path is inside a workspace root (`Permissions.within?/2`), checked before the request leaves.

With `:unsaved_only` a failed request (the client has no such file, a timeout) falls back to the
local disk. With `:always` the client's error is the result. Writes are never delegated.

# `maybe_read`

```elixir
@spec maybe_read(map(), map(), String.t(), keyword()) ::
  {:ok, String.t()} | :skip | {:error, term()}
```

`{:ok, content}` when the client served the read, `:skip` when the caller should read the disk,
`{:error, reason}` when `:always` is set and the client failed.

# `mode`

```elixir
@spec mode() :: :unsaved_only | :never | :always
```

The `:fs_delegation` setting.

---

*Consult [api-reference.md](api-reference.md) for complete listing*