Sagents.FileSystem.FileEntry (Sagents v0.8.0-rc.2)

Copy Markdown

Represents a file in the virtual filesystem.

Field Semantics

  • :loaded - Content availability

    • true - Content is in ETS, ready to use
    • false - Content exists in storage but not loaded (lazy load on read)

  • :dirty_content - Content sync status

    • false - In-memory content matches storage (or no storage attached)
    • true - In-memory content needs to be flushed to storage

Whether a given entry is actually backed by storage is determined by the Sagents.FileSystem.FileSystemConfig registered for its path — not by the entry itself. Entries that don't match any config live only in memory; their dirty_content flag is irrelevant.

Summary

Types

t()

Functions

internal_changeset(entry \\ %FileEntry{}, attrs)

Creates a changeset for a file entry from internal attrs.

mark_clean(entry)

Marks a persisted file as clean (synced with storage).

mark_loaded(entry, content)

Marks a file as loaded with the given content.

new_file(path, content, opts \\ [])

Creates a new file entry.

new_indexed_file(path, opts \\ [])

Creates a file entry for an indexed persisted file (not yet loaded).

to_llm_map(entry)

Returns the canonical LLM-facing JSON map for a file entry.

update_content(entry, new_content, opts \\ [])

Updates file content and marks as dirty.

valid_name?(name)

Validates that a path segment is safe for use in paths.

Types

t()

@type t() :: %Sagents.FileSystem.FileEntry{
  content: String.t() | nil,
  dirty_content: boolean(),
  loaded: boolean(),
  metadata: Sagents.FileSystem.FileMetadata.t() | nil,
  path: String.t()
}

Functions

internal_changeset(entry \\ %FileEntry{}, attrs)

Creates a changeset for a file entry from internal attrs.

This is the full internal changeset used by new_file/3 and friends. It casts all schema fields including :path, :content, and :dirty_content.

mark_clean(entry)

Marks a persisted file as clean (synced with storage).

mark_loaded(entry, content)

Marks a file as loaded with the given content.

Preserves existing metadata if present, updating only content-related fields.

new_file(path, content, opts \\ [])

Creates a new file entry.

The returned entry is marked dirty_content: true so any registered persistence backend picks it up on the next persist cycle. If no backend is registered for the path, the state machine simply ignores the dirty flag — memory-only files never have anywhere to be flushed to.

Options

  • :mime_type - Override the metadata mime type (default "text/markdown").

new_indexed_file(path, opts \\ [])

Creates a file entry for an indexed persisted file (not yet loaded).

Accepts an optional :metadata keyword to attach pre-built metadata.

to_llm_map(entry)

Returns the canonical LLM-facing JSON map for a file entry.

This is the single source of truth for what a FileEntry looks like to the LLM. Tools that render entries to the model (e.g. list_files, create_file) call this directly.

update_content(entry, new_content, opts \\ [])

Updates file content and marks as dirty.

Preserves existing metadata (created_at, mime_type, etc.) and only updates content-related fields (size, modified_at, checksum).

valid_name?(name)

@spec valid_name?(String.t()) :: boolean()

Validates that a path segment is safe for use in paths.

The library enforces minimal restrictions — only characters that would break path resolution are disallowed:

  • / (path separator)
  • null bytes
  • leading/trailing whitespace
  • empty strings