Personal AI, On Personal Devices
Python
feat: add iMessage connector reading from macOS Messages database
krypticmouse506bcd88bd70
diff --git a/src/openjarvis/connectors/__init__.py b/src/openjarvis/connectors/__init__.pyindex 6d9bfb53..4baaf5d9 100644--- a/src/openjarvis/connectors/__init__.py+++ b/src/openjarvis/connectors/__init__.py@@ -37,3 +37,8 @@ try:import openjarvis.connectors.gcontacts # noqa: F401except ImportError:pass++try:+ import openjarvis.connectors.imessage # noqa: F401+except ImportError:+ passdiff --git a/src/openjarvis/connectors/imessage.py b/src/openjarvis/connectors/imessage.pynew file mode 100644index 00000000..bc73c08a--- /dev/null+++ b/src/openjarvis/connectors/imessage.py@@ -0,0 +1,286 @@+"""iMessage connector — reads directly from the macOS Messages SQLite database.++No API calls, no OAuth. The connector opens ``~/Library/Messages/chat.db``+in read-only mode and yields one :class:`Document` per message that has+non-NULL text.++Requires **Full Disk Access** granted to the terminal / app in+System Settings → Privacy & Security → Full Disk Access.++Timestamp notes+---------------+The iMessage database stores timestamps as nanoseconds since the Apple+epoch of 2001-01-01 00:00:00 UTC. Conversion formula::++ dt = datetime(2001, 1, 1, tzinfo=utc) + timedelta(seconds=apple_ns / 1_000_000_000)+"""++from __future__ import annotations++import sqlite3+from datetime import datetime, timedelta, timezone+from pathlib import Path+from typing import Dict, Iterator, List, Optional, Tuple++from openjarvis.connectors._stubs import BaseConnector, Document, SyncStatus+from openjarvis.core.registry import ConnectorRegistry+from openjarvis.tools._stubs import ToolSpec++# ---------------------------------------------------------------------------+# Constants+# ---------------------------------------------------------------------------++_DEFAULT_DB_PATH = Path.home() / "Library" / "Messages" / "chat.db"++# Apple epoch: 2001-01-01 00:00:00 UTC+_APPLE_EPOCH = datetime(2001, 1, 1, tzinfo=timezone.utc)+++# ---------------------------------------------------------------------------+# Timestamp helper+# ---------------------------------------------------------------------------+++def _apple_ts_to_datetime(apple_ns: int) -> datetime:+ """Convert an Apple nanosecond timestamp to a UTC :class:`datetime`.++ Parameters+ ----------+ apple_ns:+ Nanoseconds since 2001-01-01 00:00:00 UTC.++ Returns+ -------+ datetime+ UTC-aware datetime.+ """+ seconds = apple_ns / 1_000_000_000+ return _APPLE_EPOCH + timedelta(seconds=seconds)+++# ---------------------------------------------------------------------------+# IMessageConnector+# ---------------------------------------------------------------------------++[email protected]("imessage")+class IMessageConnector(BaseConnector):+ """Connector that reads messages from the macOS Messages SQLite database.++ Parameters+ ----------+ db_path:+ Path to ``chat.db``. Defaults to+ ``~/Library/Messages/chat.db``.+ """++ connector_id = "imessage"+ display_name = "iMessage"+ auth_type = "local"++ def __init__(self, db_path: str = "") -> None:+ self._db_path: Path = Path(db_path) if db_path else _DEFAULT_DB_PATH+ self._connected: bool = False+ self._items_synced: int = 0+ self._items_total: int = 0+ self._last_sync: Optional[datetime] = None++ # ------------------------------------------------------------------+ # BaseConnector interface+ # ------------------------------------------------------------------++ def is_connected(self) -> bool:+ """Return ``True`` if the chat.db file exists at the configured path."""+ return self._db_path.exists()++ def disconnect(self) -> None:+ """Mark the connector as disconnected."""+ self._connected = False++ def sync(+ self,+ *,+ since: Optional[datetime] = None,+ cursor: Optional[str] = None, # noqa: ARG002+ ) -> Iterator[Document]:+ """Read messages from chat.db and yield one :class:`Document` each.++ Parameters+ ----------+ since:+ If provided, skip messages whose timestamp is before this+ datetime.+ cursor:+ Not used for this local connector (included for API+ compatibility).++ Yields+ ------+ Document+ One document per message with non-NULL text.+ """+ db_path = str(self._db_path)++ try:+ conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)+ except sqlite3.OperationalError:+ return++ try:+ # ------------------------------------------------------------------+ # 1. Build handle_id → identifier map+ # ------------------------------------------------------------------+ handle_map: Dict[int, str] = {}+ for row in conn.execute("SELECT ROWID, id FROM handle"):+ handle_map[row[0]] = row[1]++ # ------------------------------------------------------------------+ # 2. Build message_id → chat_id map+ # ------------------------------------------------------------------+ msg_to_chat: Dict[int, int] = {}+ for row in conn.execute(+ "SELECT message_id, chat_id FROM chat_message_join"+ ):+ msg_to_chat[row[0]] = row[1]++ # ------------------------------------------------------------------+ # 3. Build chat_id → {identifier, display_name} map+ # ------------------------------------------------------------------+ chat_map: Dict[int, Tuple[str, str]] = {}+ for row in conn.execute(+ "SELECT ROWID, chat_identifier, display_name FROM chat"+ ):+ chat_id: int = row[0]+ chat_identifier: str = row[1] or ""+ display_name: str = row[2] or chat_identifier+ chat_map[chat_id] = (chat_identifier, display_name)++ # ------------------------------------------------------------------+ # 4. Query messages with non-NULL text+ # ------------------------------------------------------------------+ rows = conn.execute(+ "SELECT ROWID, text, handle_id, date, is_from_me "+ "FROM message "+ "WHERE text IS NOT NULL "+ "ORDER BY date ASC"+ ).fetchall()++ self._items_total = len(rows)+ synced = 0++ for row in rows:+ rowid: int = row[0]+ text: str = row[1]+ handle_id: int = row[2] or 0+ apple_ts: int = row[3] or 0+ is_from_me: int = row[4] or 0++ # Convert timestamp+ timestamp = _apple_ts_to_datetime(apple_ts)++ # Apply since filter+ if since is not None:+ since_utc = since+ if since_utc.tzinfo is None:+ since_utc = since_utc.replace(tzinfo=timezone.utc)+ if timestamp < since_utc:+ continue++ # Determine author+ if is_from_me:+ author = "me"+ else:+ author = handle_map.get(handle_id, "unknown")++ # Determine chat name / title+ chat_id = msg_to_chat.get(rowid)+ if chat_id is not None and chat_id in chat_map:+ _chat_identifier, chat_name = chat_map[chat_id]+ else:+ # Fall back to the handle identifier+ chat_name = handle_map.get(handle_id, "")++ doc = Document(+ doc_id=f"imessage:{rowid}",+ source="imessage",+ doc_type="message",+ content=text,+ title=chat_name,+ author=author,+ timestamp=timestamp,+ )+ synced += 1+ yield doc++ self._items_synced = synced+ self._last_sync = datetime.now(tz=timezone.utc)++ finally:+ conn.close()++ def sync_status(self) -> SyncStatus:+ """Return sync progress from the most recent :meth:`sync` call."""+ return SyncStatus(+ state="idle",+ items_synced=self._items_synced,+ items_total=self._items_total,+ last_sync=self._last_sync,+ )++ # ------------------------------------------------------------------+ # MCP tools+ # ------------------------------------------------------------------++ def mcp_tools(self) -> List[ToolSpec]:+ """Expose two MCP tool specs for real-time iMessage queries."""+ return [+ ToolSpec(+ name="imessage_search_messages",+ description=(+ "Search iMessage messages by keyword or contact. "+ "Returns matching messages with sender and timestamp."+ ),+ parameters={+ "type": "object",+ "properties": {+ "query": {+ "type": "string",+ "description": "Search query string",+ },+ "max_results": {+ "type": "integer",+ "description": "Maximum number of messages to return",+ "default": 20,+ },+ },+ "required": ["query"],+ },+ category="knowledge",+ ),+ ToolSpec(+ name="imessage_get_conversation",+ description=(+ "Retrieve the full message history for a specific iMessage "+ "conversation by contact phone number or email address."+ ),+ parameters={+ "type": "object",+ "properties": {+ "contact": {+ "type": "string",+ "description": (+ "Phone number or email address of the contact "+ "(e.g. '+15550100' or '[email protected]')"+ ),+ },+ "max_results": {+ "type": "integer",+ "description": "Maximum number of messages to return",+ "default": 50,+ },+ },+ "required": ["contact"],+ },+ category="knowledge",+ ),+ ]diff --git a/tests/connectors/test_imessage.py b/tests/connectors/test_imessage.pynew file mode 100644index 00000000..4b8fb687--- /dev/null+++ b/tests/connectors/test_imessage.py@@ -0,0 +1,202 @@+"""Tests for IMessageConnector — local macOS Messages database connector.++All tests use a temporary SQLite database that mimics the real chat.db schema.+No actual macOS Messages database is required.+"""++from __future__ import annotations++import sqlite3+from pathlib import Path+from typing import List++import pytest++from openjarvis.connectors._stubs import Document+from openjarvis.core.registry import ConnectorRegistry++# ---------------------------------------------------------------------------+# Helper: create a fake chat.db+# ---------------------------------------------------------------------------+++def _create_fake_chat_db(db_path: Path) -> None:+ """Populate a SQLite file with the iMessage chat.db schema and sample rows."""+ conn = sqlite3.connect(str(db_path))+ conn.executescript(+ "CREATE TABLE handle (ROWID INTEGER PRIMARY KEY, id TEXT NOT NULL);"+ "CREATE TABLE chat ("+ " ROWID INTEGER PRIMARY KEY,"+ " chat_identifier TEXT NOT NULL,"+ " display_name TEXT"+ ");"+ "CREATE TABLE message ("+ " ROWID INTEGER PRIMARY KEY,"+ " text TEXT,"+ " handle_id INTEGER,"+ " date INTEGER,"+ " is_from_me INTEGER DEFAULT 0,"+ " cache_roomnames TEXT"+ ");"+ "CREATE TABLE chat_message_join ("+ " chat_id INTEGER,"+ " message_id INTEGER"+ ");"+ "INSERT INTO handle VALUES (1, '+15550100');"+ "INSERT INTO handle VALUES (2, '[email protected]');"+ "INSERT INTO chat VALUES (1, '+15550100', 'Alice');"+ "INSERT INTO chat VALUES (2, 'chat123', 'Team Group');"+ "INSERT INTO message VALUES ("+ " 1, 'Hey, are we meeting tomorrow?',"+ " 1, 700000000000000000, 0, NULL"+ ");"+ "INSERT INTO message VALUES ("+ " 2, 'Yes at 3pm!', 1, 700000060000000000, 1, NULL"+ ");"+ "INSERT INTO message VALUES ("+ " 3, 'Group message about project',"+ " 2, 700000120000000000, 0, 'chat123'"+ ");"+ "INSERT INTO chat_message_join VALUES (1, 1);"+ "INSERT INTO chat_message_join VALUES (1, 2);"+ "INSERT INTO chat_message_join VALUES (2, 3);"+ )+ conn.commit()+ conn.close()+++# ---------------------------------------------------------------------------+# Fixtures+# ---------------------------------------------------------------------------+++def fake_db(tmp_path: Path) -> Path:+ """Return path to a populated fake chat.db."""+ db_path = tmp_path / "chat.db"+ _create_fake_chat_db(db_path)+ return db_path+++def connector(fake_db: Path):+ """IMessageConnector pointing at the fake DB."""+ from openjarvis.connectors.imessage import IMessageConnector # noqa: PLC0415++ return IMessageConnector(db_path=str(fake_db))+++# ---------------------------------------------------------------------------+# Test 1 — is_connected returns True when db_path exists+# ---------------------------------------------------------------------------+++def test_is_connected(connector) -> None:+ """is_connected() returns True when chat.db exists at the configured path."""+ assert connector.is_connected() is True+++# ---------------------------------------------------------------------------+# Test 2 — is_connected returns False for a missing file+# ---------------------------------------------------------------------------+++def test_not_connected_missing_db() -> None:+ """is_connected() returns False when the database file does not exist."""+ from openjarvis.connectors.imessage import IMessageConnector # noqa: PLC0415++ conn = IMessageConnector(db_path="/nonexistent/path/chat.db")+ assert conn.is_connected() is False+++# ---------------------------------------------------------------------------+# Test 3 — sync yields all 3 messages with correct source and doc_type+# ---------------------------------------------------------------------------+++def test_sync_yields_messages(connector) -> None:+ """sync() yields one Document per non-NULL message (3 total)."""+ docs: List[Document] = list(connector.sync())+ assert len(docs) == 3+ for doc in docs:+ assert doc.source == "imessage"+ assert doc.doc_type == "message"+++# ---------------------------------------------------------------------------+# Test 4 — sync_message_content checks specific text is present+# ---------------------------------------------------------------------------+++def test_sync_message_content(connector) -> None:+ """sync() surfaces the exact message text in each Document's content."""+ docs: List[Document] = list(connector.sync())+ contents = {d.content for d in docs}+ assert "Hey, are we meeting tomorrow?" in contents+ assert "Yes at 3pm!" in contents+ assert "Group message about project" in contents+++# ---------------------------------------------------------------------------+# Test 5 — sync sets author to handle identifier for received messages+# ---------------------------------------------------------------------------+++def test_sync_sets_author(connector) -> None:+ """Received messages use the handle identifier; sent messages use 'me'."""+ docs: List[Document] = list(connector.sync())++ # Message 1 is received from handle +15550100+ msg1 = next(d for d in docs if d.doc_id == "imessage:1")+ assert msg1.author == "+15550100"++ # Message 2 is sent by me+ msg2 = next(d for d in docs if d.doc_id == "imessage:2")+ assert msg2.author == "me"++ # Message 3 is received from handle [email protected]+ msg3 = next(d for d in docs if d.doc_id == "imessage:3")+ assert msg3.author == "[email protected]"+++# ---------------------------------------------------------------------------+# Test 6 — disconnect sets connected flag to False+# ---------------------------------------------------------------------------+++def test_disconnect(connector) -> None:+ """disconnect() marks the connector as disconnected."""+ # Initially the DB file exists, so is_connected is True+ assert connector.is_connected() is True+ connector.disconnect()+ # _connected flag is cleared; is_connected still checks file existence+ assert connector._connected is False+++# ---------------------------------------------------------------------------+# Test 7 — mcp_tools returns exactly 2 tool specs+# ---------------------------------------------------------------------------+++def test_mcp_tools(connector) -> None:+ """mcp_tools() returns exactly 2 tools with the expected names."""+ tools = connector.mcp_tools()+ names = {t.name for t in tools}+ assert len(tools) == 2+ assert "imessage_search_messages" in names+ assert "imessage_get_conversation" in names+++# ---------------------------------------------------------------------------+# Test 8 — ConnectorRegistry contains "imessage" after import+# ---------------------------------------------------------------------------+++def test_registry() -> None:+ """IMessageConnector is registered and retrievable via ConnectorRegistry."""+ from openjarvis.connectors.imessage import IMessageConnector # noqa: PLC0415++ ConnectorRegistry.register_value("imessage", IMessageConnector)+ assert ConnectorRegistry.contains("imessage")+ cls = ConnectorRegistry.get("imessage")+ assert cls.connector_id == "imessage"