File System Agent: Navigation, Browsing & Scratchpad Tools

[kovtcharov]

Summary

Enhance the ChatAgent with file system navigation, web browsing, and structured data analysis capabilities — transforming it from a document Q&A bot into a capable file system and research agent.

Primary PR: #495 (feature/chat-agent-file-navigation)

Current State (PR #495)

+15,913 lines across 31 files with three new tool mixins and a security module:

New Modules

Module	Path	Capabilities
FileSystemToolsMixin	src/gaia/agents/tools/filesystem_tools.py	6 tools: browse_directory, tree, find_files, file_info, read_file, bookmark
BrowserToolsMixin	src/gaia/agents/tools/browser_tools.py	3 tools: fetch_page, search_web, download_file
ScratchpadToolsMixin	src/gaia/agents/tools/scratchpad_tools.py	5 tools: create_table, insert_data, query_data, list_tables, drop_table
File Index	src/gaia/filesystem/index.py, categorizer.py	Persistent SQLite-backed file index with FTS5 full-text search, auto-categorization
Web Client	src/gaia/web/client.py	HTTP client with SSRF prevention, rate limiting, content extraction
Scratchpad	src/gaia/scratchpad/service.py	SQLite working memory for structured data analysis

Security Hardening (src/gaia/security.py)

• Blocked system directories (Windows + Unix)
• Sensitive file protection (.env, SSH keys, certificates)
• 10 MB write size limits, overwrite confirmation prompts, timestamped backups
• Audit logging to ~/.gaia/cache/file_audit.log
• Symlink resolution for TOCTOU prevention

ChatAgent Integration

• Now inherits all three new mixins
• Config toggles: enable_filesystem, enable_scratchpad, enable_browser (all default True)

Test Coverage

• 11 new test files with ~8,000 lines of test code

Remaining Work

• Complete code review and merge of PR Enhance ChatAgent with file navigation, web browsing, scratchpad tools, and write security guardrails #495
• Integration testing with Agent UI (PR Add GAIA Chat UI: privacy-first desktop chat with document Q&A #428)
• Security audit of file write operations and web client
• Performance testing with large directory trees
• Documentation: user guide and SDK reference for new tools

Acceptance Criteria

• User can browse, search, and read files through chat interface
• Web page fetching works with content extraction and SSRF prevention
• Scratchpad enables structured data analysis within chat sessions
• Security guardrails prevent access to sensitive files and system directories
• All 14 new tools registered and functional
• Audit log captures all file system operations

Related Issues

• Implement BrowserToolsMixin with Playwright for web browsing agent #458 — BrowserToolsMixin with Playwright (future enhancement beyond requests+BS4)
• Add browser use security policy and URL allowlisting #459 — Browser security policy and URL allowlisting