Child spec for starting under a supervisor.

@spec delete_file(term(), String.t()) :: :ok | {:error, term()}

Delete file or directory from filesystem.

If file was persisted, it's also removed from storage immediately (no debounce).

@spec file_exists?(term(), String.t()) :: boolean()

Check if a file exists in the filesystem.

Examples

iex> file_exists?({:user, 123}, "/notes.txt")
true

iex> file_exists?({:user, 123}, "/nonexistent.txt")
false

@spec flush_all(term()) :: :ok

Flush all pending debounce timers and persist immediately.

Useful for graceful shutdown or checkpoints.

Get the via tuple name for a scope key.

The scope_key can be any term that uniquely identifies the scope. Common patterns include tuples like {:user, 123} or strings like "agent-abc".

@spec get_persistence_configs(term()) :: %{
  required(String.t()) => Sagents.FileSystem.FileSystemConfig.t()
}

Get all registered persistence configurations.

Returns a map of base_directory => FileSystemConfig.

Examples

iex> FileSystemServer.get_persistence_configs({:user, 123})
%{"user_files" => %FileSystemConfig{}, "S3" => %FileSystemConfig{}}

@spec get_scope(pid()) :: {:ok, term()} | {:error, term()}

Get the scope key for a FileSystemServer PID.

Returns the scope_key that was used to start the server.

@spec list_entries(nil | term()) :: [Sagents.FileSystem.FileEntry.t()]

List all file entries in the filesystem (content NOT loaded).

Returns entries with metadata suitable for building sidebar trees, directory listings, or LLM ls tool responses.

Examples

iex> entries = list_entries({:user, 123})
iex> Enum.map(entries, & &1.path)
["/Characters/Hero", "/Notes/Outline"]

@spec list_files(nil | term()) :: [String.t()]

List all file paths in the filesystem.

Returns paths for both memory and persisted files, regardless of load status.

Examples

iex> list_files({:user, 123})
["/file1.txt", "/Memories/file2.txt"]

@spec move_file(term(), String.t(), String.t()) ::
  {:ok, [Sagents.FileSystem.FileEntry.t()]} | {:error, term()}

Moves a file or directory (and its children) from one path to another.

This is an atomic re-key operation — it does not trigger delete_from_storage or create new entries. If the persistence module implements move_in_storage/3, that callback is invoked for each moved entry. Otherwise, entries are marked dirty and persisted via the normal cycle.

Returns {:ok, moved_entries} or {:error, reason}.

Examples

iex> :ok = write_file({:user, 1}, "/old-name", "content")
iex> {:ok, _entries} = move_file({:user, 1}, "/old-name", "/new-name")
iex> {:ok, entry} = read_file({:user, 1}, "/new-name")
iex> entry.content
"content"

Hook fired after a subscriber is registered. Default no-op. Override to send a snapshot of the current state to the new subscriber so it can sync without polling.

@spec read_file(term(), String.t()) ::
  {:ok, Sagents.FileSystem.FileEntry.t()} | {:error, term()}

Read a file entry from filesystem with lazy loading.

Returns the full FileEntry struct with content loaded. Application code can use all fields; the LLM tool layer extracts .content for the model.

Returns

• {:ok, %FileEntry{}} - Full file entry with content loaded
• {:error, :enoent} - File doesn't exist
• {:error, reason} - Other errors (permission, load failure, etc.)

Examples

iex> {:ok, entry} = read_file({:user, 123}, "/Memories/notes.txt")
iex> entry.content
"My notes..."

@spec register_files(
  term(),
  Sagents.FileSystem.FileEntry.t() | [Sagents.FileSystem.FileEntry.t()]
) ::
  :ok

Register file entries in the filesystem.

Useful for pre-populating the filesystem with file metadata. Accepts either a single FileEntry or a list of FileEntry structs.

Parameters

• scope_key - Scope identifier tuple
• file_entry_or_entries - FileEntry struct or list of FileEntry structs

Returns

• :ok on success

Examples

iex> {:ok, entry} = FileEntry.new_memory_file("/scratch/temp.txt", "data")
iex> FileSystemServer.register_files({:user, 123}, entry)
:ok

iex> {:ok, entry1} = FileEntry.new_memory_file("/scratch/file1.txt", "data1")
iex> {:ok, entry2} = FileEntry.new_memory_file("/scratch/file2.txt", "data2")
iex> FileSystemServer.register_files({:user, 123}, [entry1, entry2])
:ok

@spec register_persistence(term(), Sagents.FileSystem.FileSystemConfig.t()) ::
  :ok | {:error, term()}

Register a new persistence configuration.

Allows dynamically adding persistence backends for different base directories.

Parameters

• scope_key - Scope identifier tuple
• config - FileSystemConfig struct

Returns

• :ok on success
• {:error, reason} if base_directory already registered

Examples

iex> config = FileSystemConfig.new!(%{
...>   base_directory: "user_files",
...>   persistence_module: MyApp.Persistence.Disk,
...>   storage_opts: [path: "/data/users"]
...> })
iex> FileSystemServer.register_persistence({:user, 123}, config)
:ok

@spec reset(term()) :: :ok

Reset the filesystem to pristine persisted state.

This operation:

• Removes all memory-only files (not persisted)
• Unloads all persisted files (discards in-memory modifications)
• Cancels all pending debounce timers (discards unsaved changes)

Result: Next read will reload persisted files from storage in their original state.

This is useful when resetting to start fresh without carrying over transient in-memory file modifications.

Examples

iex> FileSystemServer.reset({:user, 123})
:ok

@spec start_link(keyword()) :: GenServer.on_start()

Start FileSystemServer for a scope.

Options

• :scope_key - Scope identifier (required) - Can be any term that uniquely identifies the scope
  • Tuple: {:user, 123}, {:agent, uuid}, {:project, id}
  • UUID: "550e8400-e29b-41d4-a716-446655440000"
  • Database ID: 12345 or "12345"
• :configs - List of FileSystemConfig structs (optional, default: [])
• :initial_subscribers - List of {channel, pid} tuples seeded as subscribers before init/1 returns. The only valid channel today is :main. Use this when the caller wants subscribe + start to be atomic. Default: [].

Examples

# Memory-only filesystem with tuple scope
{:ok, pid} = start_link(scope_key: {:user, 123})

# Memory-only filesystem with UUID
{:ok, pid} = start_link(scope_key: "550e8400-e29b-41d4-a716-446655440000")

# Memory-only filesystem with database ID
{:ok, pid} = start_link(scope_key: 789)

# With disk persistence
{:ok, config} = FileSystemConfig.new(%{
  base_directory: "Memories",
  persistence_module: Sagents.FileSystem.Persistence.Disk,
  debounce_ms: 5000,
  storage_opts: [path: "/data/users/123"]
})
{:ok, pid} = start_link(
  scope_key: {:user, 123},
  configs: [config]
)

@spec stats(term()) :: {:ok, map()}

Get filesystem statistics.

Returns map with various statistics about the filesystem state.

@spec subscribe(term()) :: {:ok, pid(), reference()} | {:error, :process_not_found}

Subscribe the calling process to file change events for a filesystem scope.

Events delivered (wrapped in {:file_system, event} tuple):

• {:file_system, {:file_updated, path}} - File was created or updated at path
• {:file_system, {:file_deleted, path}} - File was deleted at path
• {:file_system, {:file_moved, old_path, new_path}} - File was moved

Returns {:ok, server_pid, monitor_ref} on success — the subscriber may Process.monitor/1 the returned server_pid to detect server death.

Returns {:error, :process_not_found} if no FileSystemServer is running for the given scope.

Examples

# Subscribe to user's filesystem
{:ok, _pid, _ref} = FileSystemServer.subscribe({:user, 123})

# Receive events
receive do
  {:file_system, {:file_updated, path}} -> IO.puts("File updated: #{path}")
  {:file_system, {:file_deleted, path}} -> IO.puts("File deleted: #{path}")
end

@spec unsubscribe(term()) :: :ok

Unsubscribe the calling process from file change events.

Always returns :ok.

@spec whereis(term()) :: pid() | nil

Get the FileSystemServer PID by scope key.

The scope_key can be any term that uniquely identifies the filesystem scope. Common patterns include tuples like {:user, 123}, UUIDs like "550e8400-e29b-41d4-a716-446655440000", or database IDs like 12345.

@spec write_file(term(), String.t(), String.t(), keyword()) ::
  {:ok, Sagents.FileSystem.FileEntry.t()} | {:error, term()}

Write content to a file path.

For existing files, preserves existing metadata (created_at, etc.) and only updates content-related fields. For new files, creates a fresh entry.

Returns the updated FileEntry on success.

Options

• :mime_type - MIME type string

Examples

iex> {:ok, entry} = write_file({:user, 123}, "/tmp/notes.txt", "Hello")
iex> entry.content
"Hello"