stack/scratchpads/cli-tui-tools-enhancement.md

CLI/TUI Tools Enhancement Scratchpad

Objective

Add 5 capability areas to the Mosaic CLI/TUI + gateway agent:

1. Web search tools (multi-provider: Brave, DuckDuckGo, Tavily, SearXNG)
2. File edit tool (fs_edit_file with targeted text replacement)
3. MCP management TUI commands (/mcp status, /mcp reconnect, /mcp servers)
4. File reference in chat (@file syntax + /attach command)
5. Implement /stop to cancel streaming

Plan

1. Web Search Tools (gateway agent tools)

• Create apps/gateway/src/agent/tools/search-tools.ts
• Providers: Brave Search API, DuckDuckGo (HTML scraping), Tavily API, SearXNG (self-hosted)
• Each provider activated by env var (BRAVE_API_KEY, TAVILY_API_KEY, SEARXNG_URL)
• Tools: web_search (unified), web_search_news (news-specific)
• Export from apps/gateway/src/agent/tools/index.ts
• Wire into agent.service.ts buildToolsForSandbox

2. File Edit Tool (gateway agent tool)

• Add fs_edit_file to apps/gateway/src/agent/tools/file-tools.ts
• Parameters: path, edits[{oldText, newText}] — same semantics as pi's Edit tool
• Validates uniqueness of each oldText, applies all edits atomically

3. MCP Management Commands (TUI + gateway)

• Add gateway endpoints: GET /api/mcp/status, POST /api/mcp/:name/reconnect
• Add TUI gateway-api.ts functions for MCP
• Add gateway slash commands: /mcp (with subcommands status, reconnect, servers)
• Register in command manifest from gateway
• Handle in TUI via gateway command forwarding (already works)

4. File Reference in Chat (@file syntax)

• TUI-side: detect @path/to/file in input, read file contents, inline into message
• Add /attach <path> local command as alternative
• gateway-api.ts helper not needed — this is purely client-side pre-processing
• Modify InputBar or sendMessage to expand @file references before sending

5. Implement /stop

• Add abort event to ClientToServerEvents in @mosaic/types
• TUI sends abort event on /stop command
• Gateway chat handler aborts the Pi session prompt
• Update use-socket to support abort
• Wire /stop in app.tsx

Progress

• 1. Web search tools
• 2. File edit tool
• 3. MCP management commands
• 4. File reference in chat
• 5. Implement /stop

Risks

• DuckDuckGo has no official API — need HTML scraping or use lite endpoint
• SearXNG needs self-hosted instance
• @file expansion could be large — need size limits
• /stop requires Pi SDK abort support — need to check API