Sagents.FileSystem.FileSystemSupervisor (Sagents v0.7.0)

Copy Markdown

Dynamic supervisor for managing FileSystemServer instances.

Manages filesystem lifecycles independent of agent/conversation lifecycles. Filesystems are identified by scope keys like {:user, user_id} or {:project, project_id}.

Scope Keys

Scope keys are tuples that identify the context of a filesystem:

  • {:user, user_id} - User-scoped filesystem
  • {:project, project_id} - Project-scoped filesystem
  • {:organization, org_id} - Organization-scoped filesystem
  • {:agent, agent_id} - Agent-scoped filesystem (backward compatible)

Usage

# Start the supervisor
{:ok, pid} = FileSystemSupervisor.start_link(name: MyApp.FileSystemSupervisor)

# Start a filesystem for a user
{:ok, fs_pid} = FileSystemSupervisor.start_filesystem(
  {:user, 123},
  [config1, config2]
)

# Get a filesystem PID
{:ok, fs_pid} = FileSystemSupervisor.get_filesystem({:user, 123})

# Stop a filesystem
:ok = FileSystemSupervisor.stop_filesystem({:user, 123})

# List all running filesystems
filesystems = FileSystemSupervisor.list_filesystems()

Summary

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

get_filesystem(scope_key)

Get the PID of a running filesystem by scope key.

list_filesystems()

List all running filesystem scopes and their PIDs.

start_filesystem(scope_key, configs, opts \\ [])

Start a new filesystem for the given scope.

start_link(opts \\ [])

Start the FileSystemSupervisor.

stop_filesystem(scope_key, opts \\ [])

Stop an existing filesystem.

wait_for_supervisor_ready(supervisor \\ __MODULE__, timeout_ms \\ 5000)

Wait for the FileSystemSupervisor to be ready.

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_filesystem(scope_key)

@spec get_filesystem(tuple()) :: {:ok, pid()} | {:error, :not_found}

Get the PID of a running filesystem by scope key.

Parameters

  • scope_key - Tuple identifying the filesystem scope

Returns

  • {:ok, pid} - Filesystem found
  • {:error, :not_found} - Filesystem not running for this scope

Examples

{:ok, pid} = get_filesystem({:user, 123})

list_filesystems()

@spec list_filesystems() :: [{tuple(), pid()}]

List all running filesystem scopes and their PIDs.

Returns

List of {scope_key, pid} tuples.

Examples

filesystems = list_filesystems()
# => [{:user, 123, #PID<0.123.0>}, {:project, 456, #PID<0.124.0>}]

start_filesystem(scope_key, configs, opts \\ [])

@spec start_filesystem(tuple(), list(), keyword()) :: {:ok, pid()} | {:error, term()}

Start a new filesystem for the given scope.

Parameters

  • scope_key - Tuple identifying the filesystem scope (e.g., {:user, 123})
  • configs - List of FileSystemConfig structs for this filesystem
  • opts - Additional options:
    • :supervisor - Supervisor reference (PID or registered name). Defaults to __MODULE__.
    • :pubsub - PubSub configuration as {module(), atom()} tuple (optional)

Returns

  • {:ok, pid} - Successfully started filesystem
  • {:error, {:already_started, pid}} - Filesystem already running for this scope
  • {:error, reason} - Other error

Examples

{:ok, config} = FileSystemConfig.new(%{
  scope_key: {:user, 123},
  base_directory: "Documents",
  persistence_module: Disk,
  storage_opts: [path: "/data/users/123"]
})

{:ok, pid} = start_filesystem({:user, 123}, [config])

# With PubSub
{:ok, pid} = start_filesystem({:user, 123}, [config], pubsub: {Phoenix.PubSub, :my_pubsub})

start_link(opts \\ [])

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

Start the FileSystemSupervisor.

Options

  • :name - Registered name for the supervisor (optional)

Examples

{:ok, pid} = start_link(name: MyApp.FileSystemSupervisor)

stop_filesystem(scope_key, opts \\ [])

@spec stop_filesystem(
  tuple(),
  keyword()
) :: :ok | {:error, :not_found}

Stop an existing filesystem.

The filesystem will be gracefully terminated, allowing it to flush any pending writes.

Parameters

  • scope_key - Tuple identifying the filesystem scope
  • opts - Additional options:
    • :supervisor - Supervisor reference (PID or registered name). Defaults to __MODULE__.

Returns

  • :ok - Successfully stopped
  • {:error, :not_found} - Filesystem not running for this scope

Examples

:ok = stop_filesystem({:user, 123})

wait_for_supervisor_ready(supervisor \\ __MODULE__, timeout_ms \\ 5000)

@spec wait_for_supervisor_ready(atom() | pid(), non_neg_integer()) ::
  :ok | {:error, :supervisor_not_ready}

Wait for the FileSystemSupervisor to be ready.

This function polls for the supervisor to be available, useful in scenarios where the supervisor might be starting up asynchronously (e.g., in async tests).

Parameters

  • supervisor - Supervisor reference (PID or registered name). Defaults to __MODULE__.
  • timeout_ms - Maximum time to wait in milliseconds (default: 5000)

Returns

  • :ok - Supervisor is ready
  • {:error, :supervisor_not_ready} - Timeout waiting for supervisor

Examples

:ok = wait_for_supervisor_ready()
:ok = wait_for_supervisor_ready(__MODULE__, 10_000)