File System Explorer

Relevant source files

The following files were used as context for generating this wiki page:

• src/components/ExplorerFS.tsx
• src/utils/ai.ts
• src/data.ts
• src/components/ChatArea.tsx
• src/components/Sidebar.tsx
• src/components/SyncCluster.tsx

The File System Explorer manages a virtual and real-mapped filesystem mount within the Agent Studio workspace. It provides the primary interface for users to interact with local files, allowing for file creation, deletion, editing, and synchronization with Large Language Model (LLM) contexts. This component operates alongside the Plugin Registry and Dialogue Streams to facilitate data-driven AI interactions.

Sources: src/components/ExplorerFS.tsx:136-140, src/data.ts:223-230

Architecture and Core Logic

The system utilizes a VirtualFile data structure to represent both directories and files. The UI separates these into root-level files and nested structures through path parsing. The explorer uses React state to manage active folder visibility and inline code editing transitions.

Data Structures

Field	Type	Description
id	string	Unique identifier for the file or directory.
name	string	Display name of the item.
path	string	Full path within the virtual mount (e.g., /config/settings.json).
content	string	Raw textual payload of the file.
size	number	Size in bytes.
type	string	MIME type (e.g., text/markdown, application/json).
isDir	boolean	Flag indicating if the item is a directory.

Sources: src/components/ExplorerFS.tsx:16-25, src/data.ts:252-263

Logical Flow: File Operations

The following diagram illustrates the flow for creating and editing files within the virtual workspace.

Workspace Integration

The File System Explorer integrates with the chat interface via two primary mechanisms: context attachment and Model Context Protocol (MCP) tool calls.

Context Attachment

Users can attach files to a chat session by clicking the @ symbol next to a file in the explorer. This adds the file's content to the LLM's context window. The ChatArea component provides an autocomplete feature triggered by the @ symbol, allowing users to select files from the virtualFiles array.

Sources: src/components/ChatArea.tsx:106-114, src/components/ExplorerFS.tsx:265-275

MCP Tool Execution

The mcp_filesystem plugin provides deep read/write and cataloging capabilities. The system intercepts natural language prompts to trigger specific filesystem tools.

Tool Name	Action	Parameters
read_filesystem_file	Reads file content	path (string)
write_filesystem_file	Overwrites file payload	path (string), content (string)
list_filesystem_dir	Enumerates directories	path (string)

Sources: src/data.ts:101-137, src/utils/ai.ts:74-106

Execution Sequence

The sequence diagram below shows how a file read request is handled between the chat, the AI utility, and the filesystem.

File Handling and Types

The explorer supports multiple file types and automatically assigns MIME types based on file extensions. This metadata assists the Skill Plugins in determining how to render code blocks (e.g., Python, SVG, or LaTeX).

const getFileTypeByName = (name: string) => {
  if (name.endsWith('.json')) return 'application/json';
  if (name.endsWith('.js') || name.endsWith('.ts') || name.endsWith('.tsx')) return 'text/typescript';
  if (name.endsWith('.py')) return 'text/x-python';
  if (name.endsWith('.md')) return 'text/markdown';
  return 'text/plain';
};

Sources: src/components/ExplorerFS.tsx:75-82

Import and Drag-and-Drop

The system allows importing external files into the local virtual filesystem.

1. Selection: Users click the upload zone or drag files into the interface.
2. Processing: processUploadedFile uses the FileReader API.
3. Encoding: Files identified as text are read as text; others are converted to Data URLs.
4. Registration: A new VirtualFile object is created with a unique upload_ ID and added to the workspace.

Sources: src/components/ExplorerFS.tsx:94-124

Synchronization and Persistence

Files stored in the virtual explorer are included in the Cloud Sync Cluster. When a sync is triggered, the entire filesystem state—including path mappings and content—is hashed using PBKDF2 and encrypted via AES-256-GCM before being bridged to other nodes in the cluster.

Sources: src/components/SyncCluster.tsx:43-50, src/components/Sidebar.tsx:77-80, src/data.ts:315-320