Skip to content

Personal AI, On Personal Devices

Python

docs: add implementation plan for channel gateway → DeepResearch wiring

Jon Saad-Falconf2d84840ce35
diff --git a/docs/superpowers/plans/2026-03-27-channel-gateway-deep-research.md b/docs/superpowers/plans/2026-03-27-channel-gateway-deep-research.md
new file mode 100644
index 00000000..2aaee5ad
--- /dev/null
+++ b/docs/superpowers/plans/2026-03-27-channel-gateway-deep-research.md
@@ -0,0 +1,722 @@
+# Channel Gateway → DeepResearch Wiring 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:** Wire the ChannelBridge (from PR #78, now merged) to route incoming messages from Slack, iMessage/BlueBubbles, WhatsApp, and SMS to the DeepResearchAgent, and add an AppleScript-based iMessage daemon for direct iPhone-to-agent messaging without external services.
+
+**Architecture:** Modify `ChannelBridge.handle_incoming()` to use DeepResearchAgent instead of generic `JarvisSystem.ask()`. Add an `IMessageDaemon` that polls `chat.db` for new messages and routes them through the bridge. Add `jarvis channels` CLI commands for setup and lifecycle.
+
+**Tech Stack:** Python 3.10+, sqlite3, subprocess (AppleScript), Click, asyncio, pytest
+
+---
+
+### Task 1: Wire ChannelBridge to DeepResearchAgent
+
+**Files:**
+- Modify: `src/openjarvis/server/channel_bridge.py`
+- Create: `tests/server/test_channel_bridge_deep_research.py`
+
+- [ ] **Step 1: Read `channel_bridge.py` to find `_handle_chat` method**
+
+The `_handle_chat` method currently calls `self._system.ask()`. We need it to use DeepResearchAgent when available.
+
+- [ ] **Step 2: Write the test**
+
+Create `tests/server/test_channel_bridge_deep_research.py`:
+
+```python
+"""Test ChannelBridge routes to DeepResearchAgent."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def test_handle_chat_uses_deep_research_agent() -> None:
+ """When a DeepResearch agent is configured, route through it."""
+ from openjarvis.server.channel_bridge import ChannelBridge
+ from openjarvis.server.session_store import SessionStore
+
+ mock_agent = MagicMock()
+ mock_agent.run.return_value = MagicMock(
+ content="Found 3 results about Spain.",
+ )
+
+ bridge = ChannelBridge(
+ channels={},
+ session_store=SessionStore(db_path=":memory:"),
+ bus=MagicMock(),
+ deep_research_agent=mock_agent,
+ )
+
+ result = bridge.handle_incoming(
+ sender_id="+15551234567",
+ content="When was my last trip to Spain?",
+ channel_type="twilio",
+ )
+
+ assert "Spain" in result
+ mock_agent.run.assert_called_once()
+
+
+def test_handle_chat_falls_back_to_system() -> None:
+ """When no DeepResearch agent, fall back to system.ask()."""
+ from openjarvis.server.channel_bridge import ChannelBridge
+ from openjarvis.server.session_store import SessionStore
+
+ mock_system = MagicMock()
+ mock_system.ask.return_value = "Generic response"
+
+ bridge = ChannelBridge(
+ channels={},
+ session_store=SessionStore(db_path=":memory:"),
+ bus=MagicMock(),
+ system=mock_system,
+ )
+
+ result = bridge.handle_incoming(
+ sender_id="+15551234567",
+ content="Hello",
+ channel_type="twilio",
+ )
+
+ assert result == "Generic response"
+ mock_system.ask.assert_called_once()
+```
+
+- [ ] **Step 3: Modify `ChannelBridge.__init__` to accept `deep_research_agent`**
+
+In `channel_bridge.py`, add `deep_research_agent` parameter to `__init__`:
+
+```python
+def __init__(
+ self,
+ channels: Dict[str, BaseChannel],
+ session_store: SessionStore,
+ bus: EventBus,
+ system: Any = None,
+ agent_manager: Any = None,
+ deep_research_agent: Any = None,
+) -> None:
+ self._channels = channels
+ self._session_store = session_store
+ self._bus = bus
+ self._system = system
+ self._agent_manager = agent_manager
+ self._deep_research_agent = deep_research_agent
+ self._notification_timestamps: Dict[str, float] = {}
+ self._subscribe_notifications()
+```
+
+- [ ] **Step 4: Modify `_handle_chat` to use DeepResearchAgent first**
+
+Find the `_handle_chat` method. Replace the body to try DeepResearchAgent first, fall back to system:
+
+```python
+def _handle_chat(
+ self,
+ sender_id: str,
+ content: str,
+ channel_type: str,
+ max_length: int = _DEFAULT_MAX_LENGTH,
+) -> str:
+ """Route chat to DeepResearchAgent or JarvisSystem."""
+ # Try DeepResearchAgent first
+ if self._deep_research_agent is not None:
+ try:
+ result = self._deep_research_agent.run(content)
+ response = result.content or "No results found."
+ except Exception as exc:
+ logger.error("DeepResearch agent failed: %s", exc)
+ response = f"Research error: {exc}"
+ elif self._system is not None:
+ response = self._system.ask(content)
+ else:
+ response = "No agent or system configured."
+
+ # Truncate if needed
+ if len(response) > max_length:
+ self._session_store.set_overflow(sender_id, response)
+ response = response[:max_length] + "\n\n(truncated — send /more for the rest)"
+
+ return response
+```
+
+- [ ] **Step 5: Run tests**
+
+```bash
+uv run pytest tests/server/test_channel_bridge_deep_research.py tests/server/test_channel_bridge.py -v --tb=short
+```
+
+Expected: All PASS (new tests + existing tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/openjarvis/server/channel_bridge.py tests/server/test_channel_bridge_deep_research.py
+git commit -m "feat: wire ChannelBridge to route messages to DeepResearchAgent"
+```
+
+---
+
+### Task 2: Create iMessage AppleScript daemon
+
+**Files:**
+- Create: `src/openjarvis/channels/imessage_daemon.py`
+- Create: `tests/channels/test_imessage_daemon.py`
+
+- [ ] **Step 1: Write the test**
+
+Create `tests/channels/test_imessage_daemon.py`:
+
+```python
+"""Tests for iMessage AppleScript daemon."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def _create_fake_chat_db(db_path: Path) -> None:
+ """Create a minimal chat.db with one message."""
+ conn = sqlite3.connect(str(db_path))
+ conn.executescript("""
+ CREATE TABLE handle (ROWID INTEGER PRIMARY KEY, id TEXT);
+ CREATE TABLE chat (
+ ROWID INTEGER PRIMARY KEY,
+ chat_identifier TEXT, display_name TEXT
+ );
+ CREATE TABLE chat_message_join (chat_id INTEGER, message_id INTEGER);
+ CREATE TABLE message (
+ ROWID INTEGER PRIMARY KEY, text TEXT, handle_id INTEGER,
+ date INTEGER, is_from_me INTEGER
+ );
+ """)
+ conn.execute("INSERT INTO handle VALUES (1, '+15551234567')")
+ conn.execute("INSERT INTO chat VALUES (1, '+15551234567', 'Test Chat')")
+ conn.execute("INSERT INTO chat_message_join VALUES (1, 1)")
+ conn.execute(
+ "INSERT INTO message VALUES (1, 'Hello agent', 1, 700000000000000000, 0)"
+ )
+ conn.commit()
+ conn.close()
+
+
+def test_poll_new_messages(tmp_path: Path) -> None:
+ """Daemon detects new messages after last_rowid."""
+ from openjarvis.channels.imessage_daemon import poll_new_messages
+
+ db_path = tmp_path / "chat.db"
+ _create_fake_chat_db(db_path)
+
+ messages = poll_new_messages(
+ db_path=str(db_path),
+ last_rowid=0,
+ chat_identifier="+15551234567",
+ )
+ assert len(messages) == 1
+ assert messages[0]["text"] == "Hello agent"
+ assert messages[0]["rowid"] == 1
+
+
+def test_poll_skips_old_messages(tmp_path: Path) -> None:
+ """Daemon skips messages with ROWID <= last_rowid."""
+ from openjarvis.channels.imessage_daemon import poll_new_messages
+
+ db_path = tmp_path / "chat.db"
+ _create_fake_chat_db(db_path)
+
+ messages = poll_new_messages(
+ db_path=str(db_path),
+ last_rowid=1,
+ chat_identifier="+15551234567",
+ )
+ assert len(messages) == 0
+
+
+def test_poll_filters_by_chat(tmp_path: Path) -> None:
+ """Daemon only returns messages from the designated chat."""
+ from openjarvis.channels.imessage_daemon import poll_new_messages
+
+ db_path = tmp_path / "chat.db"
+ _create_fake_chat_db(db_path)
+
+ messages = poll_new_messages(
+ db_path=str(db_path),
+ last_rowid=0,
+ chat_identifier="+15559999999",
+ )
+ assert len(messages) == 0
+
+
+def test_poll_skips_own_messages(tmp_path: Path) -> None:
+ """Daemon ignores messages sent by the user (is_from_me=1)."""
+ from openjarvis.channels.imessage_daemon import poll_new_messages
+
+ db_path = tmp_path / "chat.db"
+ conn = sqlite3.connect(str(db_path))
+ conn.executescript("""
+ CREATE TABLE handle (ROWID INTEGER PRIMARY KEY, id TEXT);
+ CREATE TABLE chat (
+ ROWID INTEGER PRIMARY KEY,
+ chat_identifier TEXT, display_name TEXT
+ );
+ CREATE TABLE chat_message_join (chat_id INTEGER, message_id INTEGER);
+ CREATE TABLE message (
+ ROWID INTEGER PRIMARY KEY, text TEXT, handle_id INTEGER,
+ date INTEGER, is_from_me INTEGER
+ );
+ """)
+ conn.execute("INSERT INTO handle VALUES (1, '+15551234567')")
+ conn.execute("INSERT INTO chat VALUES (1, '+15551234567', 'Test')")
+ conn.execute("INSERT INTO chat_message_join VALUES (1, 1)")
+ conn.execute(
+ "INSERT INTO message VALUES (1, 'My own msg', 1, 700000000000000000, 1)"
+ )
+ conn.commit()
+ conn.close()
+
+ messages = poll_new_messages(
+ db_path=str(db_path),
+ last_rowid=0,
+ chat_identifier="+15551234567",
+ )
+ assert len(messages) == 0
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+uv run pytest tests/channels/test_imessage_daemon.py -v --tb=short
+```
+
+Expected: FAIL — `ModuleNotFoundError`
+
+- [ ] **Step 3: Create the daemon module**
+
+Create `src/openjarvis/channels/imessage_daemon.py`:
+
+```python
+"""iMessage daemon — polls chat.db and routes to DeepResearchAgent.
+
+Monitors a designated iMessage conversation for new messages, routes
+them to the agent, and sends responses back via AppleScript.
+
+Requires macOS with Full Disk Access for chat.db reading and
+Accessibility permission for AppleScript Messages control.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import signal
+import sqlite3
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_DB_PATH = str(
+ Path.home() / "Library" / "Messages" / "chat.db"
+)
+_POLL_INTERVAL = 5 # seconds
+_PID_FILE = str(Path.home() / ".openjarvis" / "imessage-agent.pid")
+
+
+# -------------------------------------------------------------------
+# Polling
+# -------------------------------------------------------------------
+
+
+def poll_new_messages(
+ *,
+ db_path: str = _DEFAULT_DB_PATH,
+ last_rowid: int = 0,
+ chat_identifier: str = "",
+) -> List[Dict[str, Any]]:
+ """Return new incoming messages since last_rowid.
+
+ Only returns messages where ``is_from_me = 0`` (incoming) and
+ that belong to the designated chat.
+ """
+ try:
+ conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+ conn.row_factory = sqlite3.Row
+ except sqlite3.OperationalError:
+ return []
+
+ try:
+ rows = conn.execute(
+ "SELECT m.ROWID as rowid, m.text, m.date, c.chat_identifier "
+ "FROM message m "
+ "JOIN chat_message_join cmj ON cmj.message_id = m.ROWID "
+ "JOIN chat c ON c.ROWID = cmj.chat_id "
+ "WHERE m.ROWID > ? AND m.is_from_me = 0 AND m.text IS NOT NULL "
+ "AND c.chat_identifier = ? "
+ "ORDER BY m.ROWID ASC",
+ (last_rowid, chat_identifier),
+ ).fetchall()
+
+ return [dict(row) for row in rows]
+ finally:
+ conn.close()
+
+
+# -------------------------------------------------------------------
+# AppleScript sending
+# -------------------------------------------------------------------
+
+
+def send_imessage(chat_identifier: str, message: str) -> bool:
+ """Send an iMessage via AppleScript.
+
+ Returns True on success, False on failure.
+ """
+ # Escape double quotes and backslashes for AppleScript
+ escaped = message.replace("\\", "\\\\").replace('"', '\\"')
+ script = (
+ f'tell application "Messages"\n'
+ f' set targetChat to a reference to chat id "{chat_identifier}"\n'
+ f' send "{escaped}" to targetChat\n'
+ f"end tell"
+ )
+
+ try:
+ subprocess.run(
+ ["osascript", "-e", script],
+ capture_output=True,
+ text=True,
+ timeout=30,
+ )
+ return True
+ except (subprocess.TimeoutExpired, FileNotFoundError):
+ logger.error("Failed to send iMessage via AppleScript")
+ return False
+
+
+# -------------------------------------------------------------------
+# Daemon loop
+# -------------------------------------------------------------------
+
+
+def run_daemon(
+ *,
+ chat_identifier: str,
+ db_path: str = _DEFAULT_DB_PATH,
+ handler: Any = None,
+ poll_interval: float = _POLL_INTERVAL,
+ max_iterations: int = 0,
+) -> None:
+ """Run the iMessage polling daemon.
+
+ Parameters
+ ----------
+ chat_identifier:
+ The chat to monitor (phone number or email).
+ handler:
+ Callable that takes a message string and returns a response string.
+ If None, messages are logged but not responded to.
+ poll_interval:
+ Seconds between polls.
+ max_iterations:
+ Stop after this many iterations (0 = run forever).
+ """
+ # Write PID file
+ pid_path = Path(_PID_FILE)
+ pid_path.parent.mkdir(parents=True, exist_ok=True)
+ pid_path.write_text(str(os.getpid()))
+
+ # Find starting ROWID
+ last_rowid = _get_max_rowid(db_path)
+ logger.info(
+ "iMessage daemon started — monitoring %s from ROWID %d",
+ chat_identifier,
+ last_rowid,
+ )
+
+ running = True
+
+ def _stop(signum: int, frame: Any) -> None:
+ nonlocal running
+ running = False
+
+ signal.signal(signal.SIGTERM, _stop)
+ signal.signal(signal.SIGINT, _stop)
+
+ iterations = 0
+ while running:
+ messages = poll_new_messages(
+ db_path=db_path,
+ last_rowid=last_rowid,
+ chat_identifier=chat_identifier,
+ )
+
+ for msg in messages:
+ last_rowid = msg["rowid"]
+ text = msg["text"]
+ logger.info("Received: %s", text[:100])
+
+ if handler is not None:
+ try:
+ response = handler(text)
+ if response:
+ send_imessage(chat_identifier, response)
+ except Exception:
+ logger.exception("Handler failed for message %d", msg["rowid"])
+
+ iterations += 1
+ if max_iterations and iterations >= max_iterations:
+ break
+
+ time.sleep(poll_interval)
+
+ # Cleanup PID file
+ if pid_path.exists():
+ pid_path.unlink()
+ logger.info("iMessage daemon stopped")
+
+
+def _get_max_rowid(db_path: str) -> int:
+ """Get the current max ROWID from chat.db."""
+ try:
+ conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+ row = conn.execute("SELECT MAX(ROWID) FROM message").fetchone()
+ conn.close()
+ return row[0] or 0
+ except sqlite3.OperationalError:
+ return 0
+
+
+def is_running() -> bool:
+ """Check if the daemon is currently running."""
+ pid_path = Path(_PID_FILE)
+ if not pid_path.exists():
+ return False
+ try:
+ pid = int(pid_path.read_text().strip())
+ os.kill(pid, 0)
+ return True
+ except (ValueError, ProcessLookupError, PermissionError):
+ pid_path.unlink(missing_ok=True)
+ return False
+
+
+def stop_daemon() -> bool:
+ """Stop the running daemon. Returns True if stopped."""
+ pid_path = Path(_PID_FILE)
+ if not pid_path.exists():
+ return False
+ try:
+ pid = int(pid_path.read_text().strip())
+ os.kill(pid, signal.SIGTERM)
+ pid_path.unlink(missing_ok=True)
+ return True
+ except (ValueError, ProcessLookupError, PermissionError):
+ pid_path.unlink(missing_ok=True)
+ return False
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+uv run pytest tests/channels/test_imessage_daemon.py -v --tb=short
+```
+
+Expected: 4/4 PASS.
+
+- [ ] **Step 5: Lint + commit**
+
+```bash
+uv run ruff check src/openjarvis/channels/imessage_daemon.py
+git add src/openjarvis/channels/imessage_daemon.py tests/channels/test_imessage_daemon.py
+git commit -m "feat: add iMessage AppleScript daemon for iPhone-to-agent messaging"
+```
+
+---
+
+### Task 3: Add `jarvis channels` CLI commands
+
+**Files:**
+- Create: `src/openjarvis/cli/channels_cmd.py`
+- Modify: `src/openjarvis/cli/__init__.py`
+
+- [ ] **Step 1: Create the CLI command module**
+
+Create `src/openjarvis/cli/channels_cmd.py`:
+
+```python
+"""``jarvis channels`` — manage channel connections for the DeepResearch agent."""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+
[email protected]("channels")
+def channels() -> None:
+ """Manage messaging channels (iMessage, Slack, WhatsApp, SMS)."""
+
+
+def channels_status() -> None:
+ """Show status of all configured channels."""
+ from openjarvis.channels.imessage_daemon import is_running
+
+ console = Console()
+ table = Table(title="Channel Status")
+ table.add_column("Channel", style="bold")
+ table.add_column("Status")
+ table.add_column("Details", style="dim")
+
+ # iMessage daemon
+ if is_running():
+ table.add_row("iMessage", "[green]running[/green]", "Polling chat.db")
+ else:
+ table.add_row("iMessage", "[dim]stopped[/dim]", "jarvis channels imessage-start")
+
+ console.print(table)
+
+
[email protected]("imessage-start")
[email protected]("chat_identifier")
[email protected]("--background/--foreground", default=True, help="Run in background.")
+def imessage_start(chat_identifier: str, background: bool) -> None:
+ """Start the iMessage daemon for a chat.
+
+ CHAT_IDENTIFIER is the phone number or email to monitor
+ (e.g. +15551234567 or group chat name).
+ """
+ from openjarvis.channels.imessage_daemon import is_running, run_daemon
+
+ console = Console()
+
+ if is_running():
+ console.print("[yellow]iMessage daemon is already running.[/yellow]")
+ return
+
+ if background:
+ import subprocess
+ proc = subprocess.Popen(
+ [
+ sys.executable, "-m", "openjarvis.channels.imessage_daemon",
+ "--chat", chat_identifier,
+ ],
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ start_new_session=True,
+ )
+ console.print(
+ f"[green]iMessage daemon started[/green] (PID {proc.pid})\n"
+ f"Monitoring: {chat_identifier}\n"
+ f"Text this contact from your iPhone to chat with the agent."
+ )
+ else:
+ console.print(f"[green]Starting iMessage daemon[/green] — monitoring {chat_identifier}")
+ console.print("Press Ctrl+C to stop.\n")
+
+ from openjarvis.agents.deep_research import DeepResearchAgent
+ from openjarvis.connectors.retriever import TwoStageRetriever
+ from openjarvis.connectors.store import KnowledgeStore
+ from openjarvis.engine.ollama import OllamaEngine
+ from openjarvis.tools.knowledge_search import KnowledgeSearchTool
+ from openjarvis.tools.knowledge_sql import KnowledgeSQLTool
+ from openjarvis.tools.scan_chunks import ScanChunksTool
+ from openjarvis.tools.think import ThinkTool
+
+ engine = OllamaEngine()
+ store = KnowledgeStore()
+ retriever = TwoStageRetriever(store)
+ tools = [
+ KnowledgeSearchTool(retriever=retriever),
+ KnowledgeSQLTool(store=store),
+ ScanChunksTool(store=store, engine=engine, model="qwen3.5:4b"),
+ ThinkTool(),
+ ]
+ agent = DeepResearchAgent(engine=engine, model="qwen3.5:4b", tools=tools)
+
+ def handler(text: str) -> str:
+ result = agent.run(text)
+ return result.content or "No results found."
+
+ run_daemon(
+ chat_identifier=chat_identifier,
+ handler=handler,
+ )
+
+
[email protected]("imessage-stop")
+def imessage_stop() -> None:
+ """Stop the iMessage daemon."""
+ from openjarvis.channels.imessage_daemon import stop_daemon
+
+ console = Console()
+ if stop_daemon():
+ console.print("[green]iMessage daemon stopped.[/green]")
+ else:
+ console.print("[dim]iMessage daemon is not running.[/dim]")
+```
+
+- [ ] **Step 2: Register in CLI __init__.py**
+
+In `src/openjarvis/cli/__init__.py`, add:
+
+```python
+from openjarvis.cli.channels_cmd import channels
+cli.add_command(channels, "channels")
+```
+
+- [ ] **Step 3: Verify**
+
+```bash
+uv run jarvis channels --help
+uv run jarvis channels status
+```
+
+- [ ] **Step 4: Lint + commit**
+
+```bash
+uv run ruff check src/openjarvis/cli/channels_cmd.py
+git add src/openjarvis/cli/channels_cmd.py src/openjarvis/cli/__init__.py
+git commit -m "feat: add jarvis channels CLI commands for iMessage daemon lifecycle"
+```
+
+---
+
+### Task 4: Run full test suite + push
+
+**Files:** None
+
+- [ ] **Step 1: Run all tests**
+
+```bash
+uv run pytest tests/connectors/ tests/agents/test_deep_research.py tests/agents/test_deep_research_integration.py tests/agents/test_channel_agent.py tests/agents/test_channel_agent_integration.py tests/cli/test_deep_research_setup.py tests/tools/test_knowledge_sql.py tests/tools/test_scan_chunks.py tests/server/test_channel_bridge.py tests/server/test_channel_bridge_deep_research.py tests/server/test_session_store.py tests/server/test_webhook_routes.py tests/server/test_auth_middleware.py tests/server/test_deep_research_tools_wiring.py tests/channels/test_twilio_sms.py tests/channels/test_imessage_daemon.py --ignore=tests/connectors/test_embedding_store.py -k "not cached_embeddings and not caches_new_embeddings" -q --tb=short
+```
+
+Expected: All PASS.
+
+- [ ] **Step 2: Lint**
+
+```bash
+uv run ruff check src/openjarvis/channels/imessage_daemon.py src/openjarvis/server/channel_bridge.py src/openjarvis/cli/channels_cmd.py
+```
+
+- [ ] **Step 3: Push to both branches**
+
+```bash
+git push origin feat/deep-research-setup
+git push origin feat/deep-research-setup:feat/mobile-channel-gateway --force-with-lease
+```