feat(research): deep_research tool — autonomous multi-step web research (#293)

[mattmezza]

Closes #293.

What

A new deep_research native tool: plan → search → read → iterate → synthesize, as a deterministic pipeline (core/deep_research.py) rather than a free-form agent loop.

1. Plan — the question is decomposed into up to 5 focused search queries (fast model)
2. Search — each query runs through the existing web_search tool (SearXNG or Tavily), URLs deduped across cycles
3. Read — plain HTTP fetch (httpx, already a dep) + stdlib HTML→text; no Playwright spin-up. A failed fetch falls back to the search snippet
4. Extract — per-source notes on the fast model, concurrently; irrelevant sources dropped
5. Iterate — up to depth cycles: a gap-analysis call produces follow-up queries, or stops early
6. Synthesize — a structured Markdown report with inline [n] citations

Decisions (per the issue discussion)

• Models — sub-calls (plan/extract/gap) run on a configurable fast/cheap model (default deepseek / deepseek-v4-flash); synthesis defaults to the main agent model (honouring per-agent LLM overrides via _agent_llm), with an optional dedicated synthesis provider/model. All in the Tools tab.
• Source reading — lightweight HTTP fetch, not the browser tool.
• Result format — the report is published as a themed web artifact (artifacts/research-<slug>-<hex>/index.html, one shared look and feel across runs) and the tool instructs the model to reply briefly with takeaways + link. Without a servable workspace, the full Markdown report rides back in the tool result for the model to relay.
• Cancellation — the pipeline runs inside the turn's tool call and polls the turn's abort Event between phases, so /stop (and the Stop button) cancels it. Inside a background subagent, task.cancel() propagates through the awaits as usual.
• Cost guardrails — hard per-run token_budget (default 300k, counted from real usage), plus depth and max_sources ceilings the model may dial down but never exceed (resolve_cap, same semantics as subagents).
• Search backend — provider-agnostic: goes through _tool_web_search, so SearXNG and Tavily both work.
• Streaming progress — phase updates (🔍 Researching…, 📖 Reading N sources…, 🕳️ Following up on gaps…, ✍️ Synthesizing…) are sent to the originating chat.
• State persistence — skipped: the run lives inside one tool call; a restart kills it like any in-flight turn. Making it resumable would need a persistent job store — out of scope, per the issue answers.
• Background runs — not a separate mechanism: the tool is offered inside subagent loops too, so spawn_subagent(background=true) with a research task gives a non-blocking run for free.

Wiring

• DeepResearchToolConfig under tools.deep_research (hot-applied via the existing config PATCH path)
• Feature-gated like every native tool: hidden unless enabled and web search is ready; per-agent allowlisting via GATEABLE_TOOLS; default permission ALWAYS (read-only; budgets cap the cost)
• Tools tab card: enable, sub-call provider/model, synthesis provider/model (blank = main agent), depth, max sources, token budget
• Docs: README feature block + structure tree, admin-ui.mdx, configuration.mdx, permissions.mdx

Tests

12 new tests in tests/test_deep_research.py (pipeline happy path, gap iteration + URL dedup, irrelevant-source drop, token-budget early stop, cancellation, max-sources cap, snippet fallback, HTML/text/slug/report-rendering helpers, feature gating). Full suite: 1079 passed.

[mattmezza]

Self-review done (two passes). Fixed: artifact path expanduser, seen-URL starvation across cycles, per-agent web_search scope bypass, missing-provider-key upfront error (base_url-only sidecars still allowed), silent extraction failures, report heading hierarchy, fetch/extract pipelining, Tools-tab single get_many + defaults sourced from the pydantic model, shared provider dropdown catalog. 1080 tests green, ruff clean.

[mattmezza]

Follow-up from a live run: the model's reply omitted the artifact links. The handler now posts the report link straight to the chat (same path as the progress updates) instead of relying on the model to echo it.