# 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 @mosaicstack/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