PhoneWork/ROADMAP.md

# PhoneWork — Roadmap

## Milestone 2: Mailboy as a Versatile Assistant

**Goal:** Elevate the mailboy (GLM-4.7 orchestrator) from a mere Claude Code relay into a
fully capable phone assistant. Users should be able to control their machine, manage files,
search the web, get direct answers, and track long-running tasks — all without necessarily
opening a Claude Code session.

### M2.1 — Direct Q&A (no CC session required)

The mailboy already has an LLM; it just needs permission to answer.
When no active session exists and the user asks a general question, the mailboy should
reply with its own knowledge instead of asking "which project?".

**Changes:**
- Update the system prompt: give the mailboy explicit permission to answer questions directly
- Add a heuristic in `_run_locked`: if there's no active session and the message looks like a
  question (ends with `?`, contains `what/how/why/explain`), skip tool loop and reply directly
- Zero new code; pure prompt + logic tweak in `orchestrator/agent.py`

---

### M2.2 — Shell Tool

Run arbitrary shell commands on the host machine and return stdout/stderr.
Covers: check git status, tail logs, kill a process, `ps aux | grep`, `pip list`, etc.

**New tool:** `orchestrator/tools.py` → `ShellTool`
```
name: "run_shell"
args: command (str), cwd (str, optional, defaults to WORKING_DIR), timeout (int, default 30)
returns: {stdout, stderr, exit_code}
```

**Safety guards:**
- Blocklist of destructive patterns (`rm -rf /`, `format`, `mkfs`, `shutdown`, `reboot`,
  `dd if=`, `:(){:|:&};:`) — refuse with a clear error
- `cwd` must be under `WORKING_DIR` (reuse `_resolve_dir`) or be an explicit absolute path
  approved by the user (raise a confirmation request)
- Timeout hard cap: 120 s; for longer tasks see M2.4

**New slash command:** `/shell <command>` (bypasses LLM; runs directly)

---

### M2.3 — File Operations Tool

Read files, list directories, search content, and send files back to the user in Feishu.
Covers: "show me the error log", "what files are in my project?", "search for TODO comments"

**New tool:** `orchestrator/tools.py` → `FileOpsTool` (single tool, `action` dispatch)
```
name: "file_ops"
args: action ("read" | "list" | "search" | "send"), path (str), query (str, for search),
      max_bytes (int, default 8000)
```

- `read`: read file, truncate to `max_bytes`, return content
- `list`: recursive directory tree (depth-limited to 3), file sizes
- `search`: grep-like ripgrep/Python search for `query` in `path`
- `send`: upload and send file via `bot/feishu.py::send_file()` (already implemented)
  — tool receives `chat_id` via context var (add alongside `current_user_id`)

**Safety:** all paths must be under `WORKING_DIR`

---

### M2.4 — Long-Running Task Manager

This is the key UX upgrade. `claude -p` and shell commands that take minutes need
fire-and-forget with completion notification.

**Design:**
- Add `BackgroundTask` dataclass: `{task_id, description, started_at, status, conv_id_or_none}`
- `TaskRunner` singleton in `agent/task_runner.py`:
  - `submit(coro, description, notify_chat_id) -> task_id`
  - wraps coroutine in `asyncio.create_task`; on completion sends a Feishu notification
    via `send_text(notify_chat_id, ...)`
  - stores tasks in-memory dict `{task_id: BackgroundTask}`
- When `manager.send()` is called for a CC session:
  - if `cc_timeout > 60`: automatically run in background, return immediately with
    `"⏳ Task #<id> started. I'll notify you when it's done."`
  - otherwise run inline as today

**New tool:** `run_background` — explicitly submits any shell command or CC prompt as a
background task and returns `task_id` immediately.

**New slash command:** `/tasks` — list running/completed background tasks with status.

**New tool:** `task_status` — check status of a specific `task_id`, optionally get output so far.

**Notification format:**
```
✅ Task #abc123 done (42s)
/new todo_app: fix the login bug

[CC output truncated to 800 chars]...
```

---

### M2.5 — Web Tool

Let the mailboy fetch URLs and search the web for quick answers.
Covers: "最新的 LangChain 有什么变化?", "fetch this GitHub issue", "帮我搜索这篇论文"

**Backend:** 秘塔AI Search MCP (`https://metaso.cn/api/mcp`) — mainland China accessible,
official API, Bearer token auth. Requires `METASO_API_KEY` in `keyring.yaml`.
Get key at: https://metaso.cn/search-api/api-keys

**New tool:** `WebTool` (three actions dispatched via one tool)
```
name: "web"
args: action ("search" | "fetch" | "ask"), query (str), url (str), scope (str), max_chars (int)
```

- `search`: calls `metaso_web_search` — returns top results (title + snippet + URL)
  - `scope` options: `webpage` (default), `paper`, `document`, `video`, `podcast`
- `fetch`: calls `metaso_web_reader` with `format=markdown` — extracts clean content from URL
- `ask`: calls `metaso_chat` — RAG answer combining search + generation (for quick factual Q&A)

**Implementation:** HTTP POST to `https://metaso.cn/api/mcp` with JSON-RPC body,
`Authorization: Bearer <METASO_API_KEY>` header. Use `httpx.AsyncClient` (already installed).

**New config key:** `METASO_API_KEY` in `keyring.yaml` and `config.py` (optional — WebTool
disabled gracefully if not set)

---

### M2.6 — Scheduling & Reminders

Set a one-shot reminder or run a recurring check.
Covers: "remind me in 30 minutes", "check if the tests pass every 5 minutes"

**Design:** `agent/scheduler.py` — thin wrapper around `asyncio` with:
- `schedule_once(delay_seconds, coro, description)` — fire once
- `schedule_recurring(interval_seconds, coro_factory, description, max_runs)` — repeat N times
- All scheduled jobs send a Feishu notification on completion (same as M2.4)
- Jobs stored in-memory; cleared on server restart (acceptable for now)

**New tool:** `scheduler`
```
args: action ("remind" | "repeat"), delay_seconds (int), interval_seconds (int),
      message (str), conv_id (str, optional — if set, forward to that CC session)
```

**New slash command:** `/remind <N>m|h|s <message>` — set a reminder without LLM

---

## Implementation Order

1. **M2.1** — Direct Q&A (prompt + 10-line logic change; highest ROI, zero risk)
2. **M2.4** — Background task runner (unblocks long CC jobs; foundational for M2.5/M2.6)
3. **M2.2** — Shell tool (most-used phone use case)
4. **M2.3** — File ops tool (`send_file` already done; rest is straightforward)
5. **M2.5** — Web tool (秘塔AI MCP; needs `METASO_API_KEY`)
6. **M2.6** — Scheduling (builds on M2.4 notification infra)

---

## Files to Create / Modify

| File | Change |
|------|--------|
| `orchestrator/agent.py` | M2.1 prompt update + question heuristic |
| `orchestrator/tools.py` | Add `ShellTool`, `FileOpsTool`, `WebTool`, `TaskStatusTool`, `SchedulerTool` |
| `agent/task_runner.py` | New — `TaskRunner` singleton, `BackgroundTask` dataclass |
| `agent/scheduler.py` | New — `schedule_once`, `schedule_recurring` |
| `bot/commands.py` | Add `/shell`, `/tasks`, `/remind` commands |
| `bot/feishu.py` | Add `chat_id` context var for file send from tool |
| `bot/handler.py` | Pass `chat_id` into context var alongside `user_id` |
| `requirements.txt` | Add `httpx` (if not already present as transitive dep) |

---

## Verification Checklist

- [ ] M2.1: Ask "what is a Python generator?" — mailboy replies directly, no tool call
- [ ] M2.2: Send "check git status in todo_app" — `ShellTool` runs, output returned
- [ ] M2.2: Send "rm -rf /" — blocked by safety guard
- [ ] M2.3: Send "show me the last 50 lines of audit/abc123.jsonl" — file content returned
- [ ] M2.3: Send "send me the sessions.json file" — file arrives in Feishu chat
- [ ] M2.4: Start a long CC task (e.g. `--timeout 120`) — bot replies immediately, notifies on finish
- [ ] M2.4: `/tasks` — lists running task with elapsed time
- [ ] M2.5: "Python 3.13 有哪些新特性？" — `web ask` returns RAG answer from metaso
- [ ] M2.5: "帮我读取这个URL: https://example.com" — page content extracted as markdown
- [ ] M2.6: `/remind 10m deploy check` — 10 min later, message arrives in Feishu