feat: add web search, file edit, MCP management, file refs, and /stop to CLI/TUI (#348)

scratchpads/cli-tui-tools-enhancement.md

@@ -0,0 +1,66 @@
+# 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
+
+- [x] 1. Web search tools
+- [x] 2. File edit tool
+- [x] 3. MCP management commands
+- [x] 4. File reference in chat
+- [x] 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