Skip to content

Personal AI, On Personal Devices

Python

docs: add Phase 4 plan for channel plugins (ChannelAgent + escalation)

krypticmouse85e531499298
diff --git a/docs/superpowers/plans/2026-03-26-deep-research-phase4-channel-plugins.md b/docs/superpowers/plans/2026-03-26-deep-research-phase4-channel-plugins.md
new file mode 100644
index 00000000..d72c95d9
--- /dev/null
+++ b/docs/superpowers/plans/2026-03-26-deep-research-phase4-channel-plugins.md
@@ -0,0 +1,816 @@
+# Deep Research Phase 4: Channel Plugins Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a ChannelAgent that connects existing messaging channels (Slack, WhatsApp, iMessage) to the DeepResearchAgent, with automatic query classification (quick inline answers vs. escalation to desktop for complex research).
+
+**Architecture:** A `ChannelAgent` class registers as a `ChannelHandler` callback on any `BaseChannel`. When a message arrives, it classifies the query (quick vs. deep), runs the DeepResearchAgent with the appropriate turn limit, and sends the response back via `channel.send()`. Quick answers go inline; complex queries get a brief preview + escalation link. A worker thread pool prevents blocking the channel's event loop.
+
+**Tech Stack:** Python 3.10+, threading (worker pool), existing channel transports (Slack Socket Mode, WhatsApp Baileys, BlueBubbles), pytest
+
+**Spec:** `docs/superpowers/specs/2026-03-25-deep-research-setup-design.md` — Section 9 (Channel Plugins)
+
+**Depends on:** Phase 1 (connectors, KnowledgeStore), Phase 3 (DeepResearchAgent, TwoStageRetriever)
+
+---
+
+## File Structure
+
+```
+src/openjarvis/agents/
+├── channel_agent.py # ChannelAgent: bridge between channels and DeepResearchAgent
+
+tests/agents/
+├── test_channel_agent.py # ChannelAgent tests
+```
+
+---
+
+### Task 1: Query Classifier
+
+**Files:**
+- Create: `src/openjarvis/agents/channel_agent.py` (first half — classifier only)
+- Create: `tests/agents/test_channel_agent.py`
+
+The classifier determines whether a message needs a quick single-hop answer or full multi-hop research. This is an internal implementation detail — the user never sees it.
+
+- [ ] **Step 1: Write failing tests for classifier**
+
+Create `tests/agents/test_channel_agent.py`:
+
+```python
+"""Tests for ChannelAgent — bridge between channels and DeepResearchAgent."""
+
+from __future__ import annotations
+
+from openjarvis.agents.channel_agent import classify_query
+
+
+def test_quick_when_query() -> None:
+ assert classify_query("When is my next meeting?") == "quick"
+
+
+def test_quick_where_query() -> None:
+ assert classify_query("Where is the design doc?") == "quick"
+
+
+def test_quick_find_query() -> None:
+ assert classify_query("Find the budget spreadsheet") == "quick"
+
+
+def test_quick_short_query() -> None:
+ assert classify_query("Who sent the last email?") == "quick"
+
+
+def test_deep_summarize() -> None:
+ assert classify_query("Summarize all discussions about pricing") == "deep"
+
+
+def test_deep_research() -> None:
+ assert classify_query("Research the context behind the K8s decision") == "deep"
+
+
+def test_deep_context() -> None:
+ assert classify_query("What was the context around the migration?") == "deep"
+
+
+def test_deep_time_range() -> None:
+ assert classify_query("What happened last month with the project?") == "deep"
+
+
+def test_deep_long_query() -> None:
+ long = "Tell me about all the discussions between Sarah and Mike about the infrastructure migration including cost analysis and timeline"
+ assert classify_query(long) == "deep"
+
+
+def test_quick_single_entity() -> None:
+ assert classify_query("What's Sarah's email?") == "quick"
+
+
+def test_deep_multi_entity() -> None:
+ assert classify_query("Compare what Sarah and Mike said about the budget") == "deep"
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd /lambda/nfs/lambda-stanford/jonsf/scratch_v2/OpenJarvis && uv run pytest tests/agents/test_channel_agent.py -v`
+
+Expected: FAIL — `ModuleNotFoundError`
+
+- [ ] **Step 3: Implement classify_query**
+
+Create `src/openjarvis/agents/channel_agent.py`:
+
+```python
+"""ChannelAgent — bridges messaging channels to the DeepResearchAgent.
+
+Handles:
+- Automatic query classification (quick vs. deep)
+- Quick answers inline in the chat channel
+- Complex queries escalated with a preview + desktop link
+- Worker thread pool so channel event loops aren't blocked
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Dict, List, Optional
+
+from openjarvis.agents._stubs import AgentContext, AgentResult
+from openjarvis.channels._stubs import BaseChannel, ChannelMessage
+from openjarvis.core.events import EventType, get_event_bus
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------
+# Query classification
+# ---------------------------------------------------------------
+
+_DEEP_KEYWORDS = re.compile(
+ r"\b(summarize|summary|research|context|compare|analyze|analysis"
+ r"|overview|all discussions|comprehensive|timeline|history"
+ r"|what happened|tell me about all)\b",
+ re.IGNORECASE,
+)
+
+_TIME_RANGE_PATTERNS = re.compile(
+ r"\b(last (week|month|quarter|year)|past \d+|since (january|february"
+ r"|march|april|may|june|july|august|september|october|november"
+ r"|december))\b",
+ re.IGNORECASE,
+)
+
+_QUICK_STARTERS = re.compile(
+ r"^(when|where|find|who sent|what'?s|what is)\b", re.IGNORECASE
+)
+
+_MAX_QUICK_WORDS = 20
+
+
+def classify_query(text: str) -> str:
+ """Classify a user query as 'quick' or 'deep'.
+
+ Quick: single-entity lookups, short factual questions.
+ Deep: multi-source synthesis, summarization, time-range analysis.
+
+ This is an internal heuristic — the user never specifies the mode.
+ """
+ text = text.strip()
+ words = text.split()
+
+ # Deep signals take priority
+ if _DEEP_KEYWORDS.search(text):
+ return "deep"
+ if _TIME_RANGE_PATTERNS.search(text):
+ return "deep"
+ if len(words) > _MAX_QUICK_WORDS:
+ return "deep"
+
+ # Quick signals
+ if _QUICK_STARTERS.match(text):
+ return "quick"
+ if len(words) <= _MAX_QUICK_WORDS:
+ return "quick"
+
+ return "quick"
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `cd /lambda/nfs/lambda-stanford/jonsf/scratch_v2/OpenJarvis && uv run pytest tests/agents/test_channel_agent.py -v`
+
+Expected: All 11 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/openjarvis/agents/channel_agent.py tests/agents/test_channel_agent.py
+git commit -m "feat: add query classifier for channel agent (quick vs deep)"
+```
+
+---
+
+### Task 2: ChannelAgent Core
+
+**Files:**
+- Modify: `src/openjarvis/agents/channel_agent.py`
+- Modify: `tests/agents/test_channel_agent.py`
+
+- [ ] **Step 1: Write failing tests for ChannelAgent**
+
+Add to `tests/agents/test_channel_agent.py`:
+
+```python
+import json
+import threading
+import time
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from openjarvis.agents.channel_agent import ChannelAgent, classify_query
+from openjarvis.agents.deep_research import DeepResearchAgent
+from openjarvis.agents._stubs import AgentResult
+from openjarvis.channels._stubs import BaseChannel, ChannelMessage, ChannelStatus
+from openjarvis.connectors.store import KnowledgeStore
+from openjarvis.connectors.retriever import TwoStageRetriever
+from openjarvis.core.types import ToolResult
+from openjarvis.tools.knowledge_search import KnowledgeSearchTool
+
+
+class FakeChannel(BaseChannel):
+ """Minimal channel for testing."""
+
+ channel_id = "fake"
+
+ def __init__(self) -> None:
+ self._handlers: list = []
+ self._sent: list = []
+ self._connected = True
+
+ def connect(self) -> None:
+ self._connected = True
+
+ def disconnect(self) -> None:
+ self._connected = False
+
+ def send(
+ self,
+ channel: str,
+ content: str,
+ *,
+ conversation_id: str = "",
+ metadata: dict | None = None,
+ ) -> bool:
+ self._sent.append(
+ {
+ "channel": channel,
+ "content": content,
+ "conversation_id": conversation_id,
+ }
+ )
+ return True
+
+ def status(self) -> ChannelStatus:
+ return ChannelStatus.CONNECTED if self._connected else ChannelStatus.DISCONNECTED
+
+ def list_channels(self) -> list[str]:
+ return ["test"]
+
+ def on_message(self, handler) -> None:
+ self._handlers.append(handler)
+
+ def simulate_message(self, text: str, sender: str = "user1") -> None:
+ msg = ChannelMessage(
+ channel="fake",
+ sender=sender,
+ content=text,
+ conversation_id="conv1",
+ )
+ for h in self._handlers:
+ h(msg)
+
+
+def mock_agent() -> MagicMock:
+ agent = MagicMock(spec=DeepResearchAgent)
+ agent.agent_id = "deep_research"
+ agent.run.return_value = AgentResult(
+ content="The next meeting is tomorrow at 2pm.",
+ tool_results=[],
+ turns=1,
+ )
+ return agent
+
+
+def channel() -> FakeChannel:
+ return FakeChannel()
+
+
+def channel_agent(
+ channel: FakeChannel, mock_agent: MagicMock
+) -> ChannelAgent:
+ return ChannelAgent(
+ channel=channel,
+ agent=mock_agent,
+ )
+
+
+def test_channel_agent_registers_handler(
+ channel: FakeChannel, channel_agent: ChannelAgent
+) -> None:
+ assert len(channel._handlers) == 1
+
+
+def test_quick_query_sends_response_inline(
+ channel: FakeChannel,
+ channel_agent: ChannelAgent,
+ mock_agent: MagicMock,
+) -> None:
+ channel.simulate_message("When is my next meeting?")
+ # Give worker thread time to process
+ time.sleep(0.5)
+ assert len(channel._sent) >= 1
+ assert "meeting" in channel._sent[0]["content"].lower()
+ mock_agent.run.assert_called_once()
+
+
+def test_deep_query_sends_preview_and_link(
+ channel: FakeChannel,
+ channel_agent: ChannelAgent,
+ mock_agent: MagicMock,
+) -> None:
+ mock_agent.run.return_value = AgentResult(
+ content="# Kubernetes Migration Report\n\nDetailed analysis...",
+ tool_results=[
+ ToolResult(
+ tool_name="knowledge_search",
+ content="results",
+ success=True,
+ metadata={"num_results": 15},
+ ),
+ ],
+ turns=3,
+ )
+ channel.simulate_message(
+ "Summarize all discussions about the Kubernetes migration"
+ )
+ time.sleep(0.5)
+ assert len(channel._sent) >= 1
+ # Deep queries should include an escalation link
+ sent_content = channel._sent[-1]["content"]
+ assert "openjarvis://" in sent_content or len(sent_content) > 50
+
+
+def test_agent_error_sends_error_message(
+ channel: FakeChannel,
+ channel_agent: ChannelAgent,
+ mock_agent: MagicMock,
+) -> None:
+ mock_agent.run.side_effect = RuntimeError("LLM unavailable")
+ channel.simulate_message("When is my meeting?")
+ time.sleep(0.5)
+ assert len(channel._sent) >= 1
+ assert "error" in channel._sent[0]["content"].lower() or "sorry" in channel._sent[0]["content"].lower()
+
+
+def test_quick_query_uses_max_turns_1(
+ channel: FakeChannel,
+ channel_agent: ChannelAgent,
+ mock_agent: MagicMock,
+) -> None:
+ channel.simulate_message("Find the budget doc")
+ time.sleep(0.5)
+ call_kwargs = mock_agent.run.call_args
+ # Quick queries should be called (the agent handles turn limits internally)
+ mock_agent.run.assert_called_once()
+
+
+def test_channel_agent_does_not_block_handler(
+ channel: FakeChannel,
+ channel_agent: ChannelAgent,
+ mock_agent: MagicMock,
+) -> None:
+ """Handler should return immediately (work dispatched to thread pool)."""
+ mock_agent.run.side_effect = lambda *a, **kw: (
+ time.sleep(2),
+ AgentResult(content="done", turns=1),
+ )[-1]
+
+ t0 = time.time()
+ channel.simulate_message("When is my meeting?")
+ elapsed = time.time() - t0
+ # Handler should return in < 0.1s even if agent takes 2s
+ assert elapsed < 0.5
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd /lambda/nfs/lambda-stanford/jonsf/scratch_v2/OpenJarvis && uv run pytest tests/agents/test_channel_agent.py::test_channel_agent_registers_handler -v`
+
+Expected: FAIL — `ImportError: cannot import name 'ChannelAgent'`
+
+- [ ] **Step 3: Implement ChannelAgent**
+
+Add to `src/openjarvis/agents/channel_agent.py` (after the classifier):
+
+```python
+# ---------------------------------------------------------------
+# ChannelAgent
+# ---------------------------------------------------------------
+
+_ESCALATION_TEMPLATE = """{preview}
+
+---
+Full report ready — open in OpenJarvis:
+openjarvis://research/{session_id}"""
+
+_ERROR_TEMPLATE = (
+ "Sorry, I ran into an error processing your request. "
+ "Please try again or open OpenJarvis for the full experience."
+)
+
+_MAX_INLINE_LENGTH = 500
+
+
+class ChannelAgent:
+ """Bridges a messaging channel to the DeepResearchAgent.
+
+ Registers as a handler on the given channel. When a message
+ arrives, classifies it (quick vs deep), runs the agent in a
+ worker thread, and sends the response back via the channel.
+
+ Quick queries get the full response inline.
+ Deep queries get a brief preview + escalation link.
+
+ Parameters
+ ----------
+ channel:
+ The messaging channel to listen on.
+ agent:
+ The DeepResearchAgent (or any BaseAgent) to handle queries.
+ max_workers:
+ Thread pool size for concurrent query processing.
+ """
+
+ def __init__(
+ self,
+ channel: BaseChannel,
+ agent: Any,
+ *,
+ max_workers: int = 2,
+ ) -> None:
+ self._channel = channel
+ self._agent = agent
+ self._pool = ThreadPoolExecutor(
+ max_workers=max_workers,
+ thread_name_prefix="channel_agent",
+ )
+
+ # Register handler
+ channel.on_message(self._handle_message)
+
+ def _handle_message(self, msg: ChannelMessage) -> Optional[str]:
+ """Handler callback — dispatches work to thread pool."""
+ self._pool.submit(self._process_message, msg)
+ return None # Don't block the channel's event loop
+
+ def _process_message(self, msg: ChannelMessage) -> None:
+ """Process a message in a worker thread."""
+ query = msg.content.strip()
+ if not query:
+ return
+
+ classification = classify_query(query)
+ session_id = uuid.uuid4().hex[:12]
+
+ bus = get_event_bus()
+ bus.publish(
+ EventType.AGENT_TURN_START,
+ {
+ "agent": "channel_agent",
+ "channel": msg.channel,
+ "sender": msg.sender,
+ "classification": classification,
+ },
+ )
+
+ try:
+ result = self._agent.run(query)
+ except Exception as exc:
+ logger.error(
+ "ChannelAgent error for %s: %s",
+ msg.sender,
+ exc,
+ )
+ self._channel.send(
+ msg.sender,
+ _ERROR_TEMPLATE,
+ conversation_id=msg.conversation_id,
+ )
+ return
+
+ content = result.content.strip()
+
+ if classification == "deep" or len(content) > _MAX_INLINE_LENGTH:
+ # Truncate for preview
+ preview = content[:300]
+ if len(content) > 300:
+ preview = preview.rsplit(" ", 1)[0] + "..."
+ response = _ESCALATION_TEMPLATE.format(
+ preview=preview, session_id=session_id
+ )
+ else:
+ response = content
+
+ self._channel.send(
+ msg.sender,
+ response,
+ conversation_id=msg.conversation_id,
+ )
+
+ bus.publish(
+ EventType.AGENT_TURN_END,
+ {
+ "agent": "channel_agent",
+ "channel": msg.channel,
+ "turns": result.turns,
+ "classification": classification,
+ "session_id": session_id,
+ },
+ )
+
+ def shutdown(self) -> None:
+ """Shut down the worker thread pool."""
+ self._pool.shutdown(wait=False)
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `cd /lambda/nfs/lambda-stanford/jonsf/scratch_v2/OpenJarvis && uv run pytest tests/agents/test_channel_agent.py -v`
+
+Expected: All 17 tests PASS (11 classifier + 6 ChannelAgent).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/openjarvis/agents/channel_agent.py tests/agents/test_channel_agent.py
+git commit -m "feat: add ChannelAgent with query classification and escalation"
+```
+
+---
+
+### Task 3: Integration Test — ChannelAgent + DeepResearchAgent + Real Data
+
+**Files:**
+- Create: `tests/agents/test_channel_agent_integration.py`
+
+- [ ] **Step 1: Write integration test**
+
+Create `tests/agents/test_channel_agent_integration.py`:
+
+```python
+"""Integration test — ChannelAgent with real KnowledgeStore and mock engine."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from openjarvis.agents.channel_agent import ChannelAgent
+from openjarvis.agents.deep_research import DeepResearchAgent
+from openjarvis.channels._stubs import BaseChannel, ChannelMessage, ChannelStatus
+from openjarvis.connectors._stubs import Document
+from openjarvis.connectors.pipeline import IngestionPipeline
+from openjarvis.connectors.retriever import TwoStageRetriever
+from openjarvis.connectors.store import KnowledgeStore
+from openjarvis.tools.knowledge_search import KnowledgeSearchTool
+
+
+class FakeChannel(BaseChannel):
+ channel_id = "fake"
+
+ def __init__(self) -> None:
+ self._handlers: list = []
+ self._sent: list = []
+
+ def connect(self) -> None:
+ pass
+
+ def disconnect(self) -> None:
+ pass
+
+ def send(
+ self,
+ channel: str,
+ content: str,
+ *,
+ conversation_id: str = "",
+ metadata: dict | None = None,
+ ) -> bool:
+ self._sent.append({"content": content, "conv": conversation_id})
+ return True
+
+ def status(self) -> ChannelStatus:
+ return ChannelStatus.CONNECTED
+
+ def list_channels(self) -> list[str]:
+ return ["test"]
+
+ def on_message(self, handler) -> None:
+ self._handlers.append(handler)
+
+ def simulate(self, text: str) -> None:
+ msg = ChannelMessage(
+ channel="fake",
+ sender="user",
+ content=text,
+ conversation_id="conv1",
+ )
+ for h in self._handlers:
+ h(msg)
+
+
+def populated_store(tmp_path: Path) -> KnowledgeStore:
+ store = KnowledgeStore(
+ db_path=str(tmp_path / "channel_int.db")
+ )
+ pipeline = IngestionPipeline(store=store, max_tokens=256)
+ pipeline.ingest(
+ [
+ Document(
+ doc_id="gcalendar:evt1",
+ source="gcalendar",
+ doc_type="event",
+ content="Sprint Planning\nWhen: Tomorrow 2pm\nAttendees: Sarah, Mike",
+ title="Sprint Planning",
+ ),
+ Document(
+ doc_id="slack:msg1",
+ source="slack",
+ doc_type="message",
+ content="We need to finalize the API redesign before Friday",
+ title="#engineering",
+ author="sarah",
+ ),
+ Document(
+ doc_id="gmail:msg1",
+ source="gmail",
+ doc_type="email",
+ content="Budget report attached. Q3 spending up 15%.",
+ title="Re: Q3 Budget",
+ author="mike",
+ ),
+ ]
+ )
+ return store
+
+
+def test_quick_query_through_full_stack(
+ populated_store: KnowledgeStore,
+) -> None:
+ """Quick query → agent searches → inline response."""
+ mock_engine = MagicMock()
+ mock_engine.engine_id = "mock"
+ mock_engine.generate.return_value = {
+ "content": "Your next meeting is Sprint Planning tomorrow at 2pm with Sarah and Mike.",
+ "usage": {"prompt_tokens": 100, "completion_tokens": 50, "total_tokens": 150},
+ "model": "test",
+ "finish_reason": "stop",
+ }
+
+ retriever = TwoStageRetriever(store=populated_store)
+ ks_tool = KnowledgeSearchTool(
+ store=populated_store, retriever=retriever
+ )
+ agent = DeepResearchAgent(
+ engine=mock_engine,
+ model="test",
+ tools=[ks_tool],
+ max_turns=2,
+ )
+
+ channel = FakeChannel()
+ ca = ChannelAgent(channel=channel, agent=agent)
+
+ channel.simulate("When is my next meeting?")
+ time.sleep(1.0)
+
+ assert len(channel._sent) >= 1
+ response = channel._sent[0]["content"]
+ assert "Sprint Planning" in response or "meeting" in response.lower()
+ # Quick query should NOT have escalation link
+ assert "openjarvis://" not in response
+
+ ca.shutdown()
+
+
+def test_deep_query_gets_escalation_link(
+ populated_store: KnowledgeStore,
+) -> None:
+ """Deep query → agent searches → preview + escalation link."""
+ search_call = {
+ "content": "",
+ "usage": {"prompt_tokens": 100, "completion_tokens": 50, "total_tokens": 150},
+ "model": "test",
+ "finish_reason": "tool_calls",
+ "tool_calls": [
+ {
+ "id": "call_1",
+ "type": "function",
+ "function": {
+ "name": "knowledge_search",
+ "arguments": json.dumps({"query": "budget API"}),
+ },
+ }
+ ],
+ }
+ final_answer = {
+ "content": (
+ "## Research Report\n\n"
+ + "Based on analysis of Slack messages and emails, "
+ + "the team discussed API redesign and Q3 budget. "
+ * 10
+ + "\n\n**Sources:**\n1. [slack] #engineering\n2. [gmail] Q3 Budget"
+ ),
+ "usage": {"prompt_tokens": 500, "completion_tokens": 300, "total_tokens": 800},
+ "model": "test",
+ "finish_reason": "stop",
+ }
+
+ mock_engine = MagicMock()
+ mock_engine.engine_id = "mock"
+ mock_engine.generate.side_effect = [search_call, final_answer]
+
+ retriever = TwoStageRetriever(store=populated_store)
+ ks_tool = KnowledgeSearchTool(
+ store=populated_store, retriever=retriever
+ )
+ agent = DeepResearchAgent(
+ engine=mock_engine,
+ model="test",
+ tools=[ks_tool],
+ max_turns=3,
+ )
+
+ channel = FakeChannel()
+ ca = ChannelAgent(channel=channel, agent=agent)
+
+ channel.simulate(
+ "Summarize all discussions about budget and API redesign"
+ )
+ time.sleep(1.0)
+
+ assert len(channel._sent) >= 1
+ response = channel._sent[-1]["content"]
+ # Deep query should have escalation link
+ assert "openjarvis://" in response
+
+ ca.shutdown()
+```
+
+- [ ] **Step 2: Run integration test**
+
+Run: `cd /lambda/nfs/lambda-stanford/jonsf/scratch_v2/OpenJarvis && uv run pytest tests/agents/test_channel_agent_integration.py -v`
+
+Expected: All 2 tests PASS.
+
+- [ ] **Step 3: Run full test suite**
+
+Run: `cd /lambda/nfs/lambda-stanford/jonsf/scratch_v2/OpenJarvis && uv run pytest tests/agents/test_channel_agent.py tests/agents/test_channel_agent_integration.py tests/agents/test_deep_research.py tests/connectors/ tests/tools/test_knowledge_search.py -v --tb=short`
+
+Expected: All tests PASS.
+
+- [ ] **Step 4: Run linter**
+
+Run: `cd /lambda/nfs/lambda-stanford/jonsf/scratch_v2/OpenJarvis && uv run ruff check src/openjarvis/agents/channel_agent.py tests/agents/test_channel_agent.py tests/agents/test_channel_agent_integration.py`
+
+Expected: No errors.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/agents/test_channel_agent_integration.py
+git commit -m "feat: add integration test for ChannelAgent with DeepResearchAgent"
+```
+
+---
+
+## Post-Plan Notes
+
+**What this plan produces:**
+- `classify_query()` — automatic quick/deep classification (no user input needed)
+- `ChannelAgent` — bridges any `BaseChannel` to the `DeepResearchAgent` with:
+ - Non-blocking handler (thread pool)
+ - Quick inline answers for simple lookups
+ - Preview + `openjarvis://research/{session_id}` escalation link for complex research
+ - Error handling with user-friendly messages
+ - Event bus telemetry
+- Integration test proving the full stack: channel message → classification → agent → tool call → retrieval → response
+
+**What this does NOT do (future work):**
+- Platform-specific formatting (Slack Block Kit, WhatsApp markdown) — can be added per-channel later
+- BlueBubbles incoming message support — needs upstream work on the bridge
+- Tauri `openjarvis://` URL handler registration — that's Phase 2B (desktop)
+- Persistent conversation context across messages — would need session store integration
+
+**Connecting to real channels:** After this plan, wiring to real Slack/WhatsApp is just:
+```python
+channel = SlackChannel(bot_token="xoxb-...", app_token="xapp-...")
+channel.connect()
+agent = DeepResearchAgent(engine, model, tools=[ks_tool])
+ca = ChannelAgent(channel=channel, agent=agent)
+# Now the Slack bot responds to DMs with Deep Research answers
+```