Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

added tree based session handler

Alishahryar15fd7268d3f40
diff --git a/api/app.py b/api/app.py
index 0a48af8a..c0f85077 100644
--- a/api/app.py
+++ b/api/app.py
@@ -41,7 +41,7 @@ async def lifespan(app: FastAPI):
from messaging.telegram import TelegramPlatform
from messaging.handler import ClaudeMessageHandler
from messaging.session import SessionStore
- from messaging.queue import MessageQueueManager
+
from cli.manager import CLISessionManager
# Setup workspace - CLI runs in allowed_dir if set (e.g. project root)
@@ -64,11 +64,10 @@ async def lifespan(app: FastAPI):
max_sessions=settings.max_cli_sessions,
)
- # Initialize session store and queue
+ # Initialize session store
session_store = SessionStore(
storage_path=os.path.join(data_path, "sessions.json")
)
- message_queue = MessageQueueManager()
# Create Telegram platform
messaging_platform = TelegramPlatform(
@@ -80,7 +79,6 @@ async def lifespan(app: FastAPI):
platform=messaging_platform,
cli_manager=cli_manager,
session_store=session_store,
- message_queue=message_queue,
)
# Wire up the handler
diff --git a/messaging/__init__.py b/messaging/__init__.py
index b33182d4..5f6f5c19 100644
--- a/messaging/__init__.py
+++ b/messaging/__init__.py
@@ -4,7 +4,7 @@ from .base import MessagingPlatform
from .models import IncomingMessage, OutgoingMessage
from .handler import ClaudeMessageHandler
from .session import SessionStore
-from .queue import MessageQueueManager
+from .tree_queue import TreeQueueManager, MessageTree, MessageNode, MessageState
__all__ = [
"MessagingPlatform",
@@ -12,5 +12,8 @@ __all__ = [
"OutgoingMessage",
"ClaudeMessageHandler",
"SessionStore",
- "MessageQueueManager",
+ "TreeQueueManager",
+ "MessageTree",
+ "MessageNode",
+ "MessageState",
]
diff --git a/messaging/handler.py b/messaging/handler.py
index 47d2cb17..13dd7786 100644
--- a/messaging/handler.py
+++ b/messaging/handler.py
@@ -3,19 +3,19 @@ Claude Message Handler
Platform-agnostic Claude interaction logic.
Handles the core workflow of processing user messages via Claude CLI.
+Uses tree-based queuing for message ordering.
"""
import time
import asyncio
import logging
-from typing import Optional, List, Tuple, TYPE_CHECKING
+from typing import Optional, TYPE_CHECKING
from .base import MessagingPlatform
-from .models import IncomingMessage, MessageContext
+from .models import IncomingMessage
from .session import SessionStore
-from .queue import MessageQueueManager, QueuedMessage
-from cli import CLISession, CLISessionManager, CLIParser
-from config.settings import get_settings
+from .tree_queue import TreeQueueManager, MessageNode, MessageState
+from cli import CLISessionManager, CLIParser
if TYPE_CHECKING:
pass
@@ -27,13 +27,11 @@ class ClaudeMessageHandler:
"""
Platform-agnostic handler for Claude interactions.
- This class contains the core logic for:
- - Processing user messages
- - Managing Claude CLI sessions
- - Updating status messages
- - Handling tool calls and thinking
-
- It works with any MessagingPlatform implementation.
+ Uses a tree-based message queue where:
+ - New messages create a tree root
+ - Replies become children of the message being replied to
+ - Each node has state: PENDING, IN_PROGRESS, COMPLETED, ERROR
+ - Per-tree queue ensures ordered processing
"""
def __init__(
@@ -41,20 +39,19 @@ class ClaudeMessageHandler:
platform: MessagingPlatform,
cli_manager: CLISessionManager,
session_store: SessionStore,
- message_queue: MessageQueueManager,
):
self.platform = platform
self.cli_manager = cli_manager
self.session_store = session_store
- self.message_queue = message_queue
+ self.tree_queue = TreeQueueManager()
self._flood_wait_until = 0
async def handle_message(self, incoming: IncomingMessage) -> None:
"""
Main entry point for handling an incoming message.
- Determines if this is a new session or continuation,
- sends status message, and queues for processing.
+ Determines if this is a new conversation or reply,
+ creates/extends the message tree, and queues for processing.
"""
# Check for commands
if incoming.text == "/stop":
@@ -72,99 +69,120 @@ class ClaudeMessageHandler:
):
return
- # Check if this is a reply to an existing conversation
- session_id_to_resume = None
+ # Check if this is a reply to an existing node in a tree
+ parent_node_id = None
+ tree = None
+
if incoming.is_reply():
- session_id_to_resume = self.session_store.get_session_by_msg(
- incoming.chat_id,
- incoming.reply_to_message_id,
- incoming.platform,
- )
- if session_id_to_resume:
- logger.info(f"Found session {session_id_to_resume} for reply")
+ # Look up if the replied-to message is in any tree (could be a node or status message)
+ tree = self.tree_queue.get_tree_for_node(incoming.reply_to_message_id)
+ if tree:
+ # Resolve to actual node ID (handles status message replies)
+ parent_node_id = self.tree_queue.resolve_parent_node_id(
+ incoming.reply_to_message_id
+ )
+ if parent_node_id:
+ logger.info(f"Found tree for reply, parent node: {parent_node_id}")
+ else:
+ logger.warning(
+ f"Reply to {incoming.reply_to_message_id} found tree but no valid parent node"
+ )
+ tree = None # Treat as new conversation
+
+ # Generate node ID
+ node_id = incoming.message_id
# Send initial status message
- status_text = self._get_initial_status(session_id_to_resume)
+ status_text = self._get_initial_status(tree, parent_node_id)
status_msg_id = await self.platform.send_message(
incoming.chat_id,
status_text,
reply_to=incoming.message_id,
)
- # Create queued message
- queued = QueuedMessage(
- incoming=incoming,
- status_message_id=status_msg_id,
- )
-
- # Determine session ID for queuing
- if session_id_to_resume:
- queue_session_id = session_id_to_resume
- # Index current messages immediately so they can be replied to even while queued
- self.session_store.update_last_message(
- queue_session_id, incoming.message_id
+ # Create or extend tree
+ if parent_node_id and tree:
+ # Reply to existing node - add as child
+ tree, node = await self.tree_queue.add_to_tree(
+ parent_node_id=parent_node_id,
+ node_id=node_id,
+ incoming=incoming,
+ status_message_id=status_msg_id,
)
- self.session_store.update_last_message(queue_session_id, status_msg_id)
+ # Register status message as a node too for reply chains
+ self.tree_queue.register_node(status_msg_id, tree.root_id)
+ self.session_store.register_node(status_msg_id, tree.root_id)
+ self.session_store.register_node(node_id, tree.root_id)
else:
- # New session - use temp ID
- queue_session_id = f"pending_{incoming.message_id}"
- # Pre-register so replies work immediately
- self.session_store.save_session(
- session_id=queue_session_id,
- chat_id=incoming.chat_id,
- initial_msg_id=incoming.message_id,
- platform=incoming.platform,
+ # New conversation - create new tree
+ tree = await self.tree_queue.create_tree(
+ node_id=node_id,
+ incoming=incoming,
+ status_message_id=status_msg_id,
)
- self.session_store.update_last_message(queue_session_id, status_msg_id)
+ # Register status message
+ self.tree_queue.register_node(status_msg_id, tree.root_id)
+ self.session_store.register_node(node_id, tree.root_id)
+ self.session_store.register_node(status_msg_id, tree.root_id)
+
+ # Persist tree
+ self.session_store.save_tree(tree.root_id, tree.to_dict())
# Enqueue for processing
- await self.message_queue.enqueue(
- session_id=queue_session_id,
- message=queued,
- processor=self._process_task,
+ was_queued = await self.tree_queue.enqueue(
+ node_id=node_id,
+ processor=self._process_node,
)
- async def _process_task(
+ if was_queued:
+ # Update status to show queue position
+ queue_size = self.tree_queue.get_queue_size(node_id)
+ await self.platform.edit_message(
+ incoming.chat_id,
+ status_msg_id,
+ f"📋 **Queued** (position {queue_size}) - waiting...",
+ parse_mode="markdown",
+ )
+
+ async def _process_node(
self,
- session_id_to_resume: Optional[str],
- queued: QueuedMessage,
+ node_id: str,
+ node: MessageNode,
) -> None:
"""Core task processor - handles a single Claude CLI interaction."""
- incoming = queued.incoming
- status_msg_id = queued.status_message_id
+ incoming = node.incoming
+ status_msg_id = node.status_message_id
chat_id = incoming.chat_id
- # specific components for structured display
+ # Update node state to IN_PROGRESS
+ tree = self.tree_queue.get_tree_for_node(node_id)
+ if tree:
+ await tree.update_state(node_id, MessageState.IN_PROGRESS)
+
+ # Components for structured display
components = {
- "thinking": [], # List[str]
- "tools": [], # List[str]
- "subagents": [], # List[str]
- "content": [], # List[str]
- "errors": [], # List[str]
+ "thinking": [],
+ "tools": [],
+ "subagents": [],
+ "content": [],
+ "errors": [],
}
last_ui_update = 0.0
captured_session_id = None
- if session_id_to_resume:
- if session_id_to_resume.startswith("pending_"):
- # Check if it was already resolved earlier
- captured_session_id = await self.cli_manager.get_real_session_id(
- session_id_to_resume
- )
- else:
- captured_session_id = session_id_to_resume
+ temp_session_id = None
- temp_session_id = (
- session_id_to_resume
- if session_id_to_resume and session_id_to_resume.startswith("pending_")
- else None
- )
+ # Get parent session ID for forking (if child node)
+ parent_session_id = None
+ if tree and node.parent_id:
+ parent_session_id = tree.get_parent_session_id(node_id)
+ if parent_session_id:
+ logger.info(f"Will fork from parent session: {parent_session_id}")
async def update_ui(status: Optional[str] = None, force: bool = False) -> None:
nonlocal last_ui_update
now = time.time()
- # Check flood wait
if now < self._flood_wait_until:
return
@@ -189,7 +207,7 @@ class ClaudeMessageHandler:
session_or_temp_id,
is_new,
) = await self.cli_manager.get_or_create_session(
- session_id=captured_session_id
+ session_id=parent_session_id # Fork from parent if available
)
if is_new:
temp_session_id = session_or_temp_id
@@ -198,6 +216,10 @@ class ClaudeMessageHandler:
except RuntimeError as e:
components["errors"].append(str(e))
await update_ui("⏳ **Session limit reached**", force=True)
+ if tree:
+ await tree.update_state(
+ node_id, MessageState.ERROR, error_message=str(e)
+ )
return
# Process CLI events
@@ -211,23 +233,17 @@ class ClaudeMessageHandler:
if event_data.get("type") == "session_info":
real_session_id = event_data.get("session_id")
if real_session_id and temp_session_id:
- # 1. Update CLI Manager mapping
await self.cli_manager.register_real_session_id(
temp_session_id, real_session_id
)
- # 2. Update Session Store (properly migrates all messages)
- self.session_store.rename_session(
- temp_session_id, real_session_id
- )
captured_session_id = real_session_id
- temp_session_id = None # Resolved
+ temp_session_id = None
continue
parsed_list = CLIParser.parse_event(event_data)
for parsed in parsed_list:
if parsed["type"] == "thinking":
- # append to the last thinking block if valid, or just simple list
components["thinking"].append(parsed["text"])
await update_ui("🧠 **Claude is thinking...**")
@@ -251,25 +267,42 @@ class ClaudeMessageHandler:
components["content"].append("Done.")
await update_ui("✅ **Complete**", force=True)
- # Update session's last message
- if captured_session_id:
- self.session_store.update_last_message(
- captured_session_id, status_msg_id
+ # Update node state and session
+ if tree and captured_session_id:
+ await tree.update_state(
+ node_id,
+ MessageState.COMPLETED,
+ session_id=captured_session_id,
)
+ self.session_store.save_tree(tree.root_id, tree.to_dict())
elif parsed["type"] == "error":
components["errors"].append(
parsed.get("message", "Unknown error")
)
await update_ui("❌ **Error**", force=True)
+ if tree:
+ await tree.update_state(
+ node_id,
+ MessageState.ERROR,
+ error_message=parsed.get("message"),
+ )
except asyncio.CancelledError:
components["errors"].append("Task was cancelled")
await update_ui("❌ **Cancelled**", force=True)
+ if tree:
+ await tree.update_state(
+ node_id, MessageState.ERROR, error_message="Cancelled"
+ )
except Exception as e:
logger.error(f"Task failed: {e}")
components["errors"].append(str(e)[:200])
await update_ui("💥 **Task Failed**", force=True)
+ if tree:
+ await tree.update_state(
+ node_id, MessageState.ERROR, error_message=str(e)[:200]
+ )
def _build_message(
self,
@@ -290,7 +323,6 @@ class ClaudeMessageHandler:
# 1. Thinking
if components["thinking"]:
full_thinking = "".join(components["thinking"])
- # limit thinking length visually
display = full_thinking
if len(display) > 800:
display = display[:795] + "..."
@@ -298,7 +330,6 @@ class ClaudeMessageHandler:
# 2. Tools
if components["tools"]:
- # Unique tools to avoid clutter
unique_tools = []
seen = set()
for t in components["tools"]:
@@ -314,7 +345,6 @@ class ClaudeMessageHandler:
# 4. Content
if components["content"]:
- # Join content parts
full_content = "".join(components["content"])
lines.append(full_content)
@@ -325,29 +355,31 @@ class ClaudeMessageHandler:
# 6. Status (Bottom)
if status:
- lines.append("") # spacer
+ lines.append("")
lines.append(status)
result = "\n".join(lines)
# Truncate if too long (Telegram limit ~4096)
- # We leave some buffer
if len(result) > 3800:
result = "..." + result[-3795:]
- # basic attempt to fix unclosed code blocks if we truncated the top
- # but usually we want to preserve the bottom (content/status)
- pass
return result
- def _get_initial_status(self, session_id: Optional[str]) -> str:
+ def _get_initial_status(
+ self,
+ tree: Optional[object],
+ parent_node_id: Optional[str],
+ ) -> str:
"""Get initial status message text."""
- if session_id:
- if self.message_queue.is_session_busy(session_id):
- queue_size = self.message_queue.get_queue_size(session_id) + 1
+ if tree:
+ # Reply to existing tree
+ if self.tree_queue.is_node_tree_busy(parent_node_id):
+ queue_size = self.tree_queue.get_queue_size(parent_node_id) + 1
return f"📋 **Queued** (position {queue_size}) - waiting..."
return "🔄 **Continuing conversation...**"
+ # New conversation
stats = self.cli_manager.get_stats()
if stats["active_sessions"] >= stats["max_sessions"]:
return f"⏳ **Waiting for slot...** ({stats['active_sessions']}/{stats['max_sessions']})"
@@ -356,27 +388,24 @@ class ClaudeMessageHandler:
async def stop_all_tasks(self) -> int:
"""
Stop all pending and in-progress tasks.
- Updates status messages for all affected tasks.
-
- Returns:
- Number of cancelled messages.
+ Updates status messages for all affected nodes.
"""
- cancelled_messages = await self.message_queue.cancel_all()
+ cancelled_nodes = await self.tree_queue.cancel_all()
await self.cli_manager.stop_all()
- # Update UI for all cancelled messages
- for msg in cancelled_messages:
+ # Update UI for all cancelled nodes
+ for node in cancelled_nodes:
try:
await self.platform.edit_message(
- msg.incoming.chat_id,
- msg.status_message_id,
+ node.incoming.chat_id,
+ node.status_message_id,
"⏹ **Stopped.**",
parse_mode="markdown",
)
except Exception as e:
- logger.error(f"Failed to update status for cancelled message: {e}")
+ logger.error(f"Failed to update status for cancelled node: {e}")
- return len(cancelled_messages)
+ return len(cancelled_nodes)
async def _handle_stop_command(self, incoming: IncomingMessage) -> None:
"""Handle /stop command from messaging platform."""
@@ -389,7 +418,8 @@ class ClaudeMessageHandler:
async def _handle_stats_command(self, incoming: IncomingMessage) -> None:
"""Handle /stats command."""
stats = self.cli_manager.get_stats()
+ tree_count = len(self.tree_queue._trees)
await self.platform.send_message(
incoming.chat_id,
- f"📊 **Stats**\n• Active: {stats['active_sessions']}\n• Max: {stats['max_sessions']}",
+ f"📊 **Stats**\n• Active CLI: {stats['active_sessions']}\n• Max CLI: {stats['max_sessions']}\n• Message Trees: {tree_count}",
)
diff --git a/messaging/queue.py b/messaging/queue.py
deleted file mode 100644
index c04a6c50..00000000
--- a/messaging/queue.py
+++ /dev/null
@@ -1,210 +0,0 @@
-"""
-Message Queue Manager for Messaging Platforms
-
-Handles queuing of messages when Claude is busy processing a request.
-Messages are processed one-by-one in order per session.
-Platform-agnostic: works with any messaging platform.
-"""
-
-import asyncio
-import logging
-from typing import Callable, Awaitable, Dict, Optional, List, Any
-from dataclasses import dataclass
-
-from .models import IncomingMessage
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class QueuedMessage:
- """A message waiting to be processed."""
-
- incoming: IncomingMessage
- status_message_id: str # The status message to update
- context: Any = None # Additional context if needed
-
-
-class SessionQueue:
- """Queue for a single session."""
-
- def __init__(self, session_id: str):
- self.session_id = session_id
- self.queue: asyncio.Queue[QueuedMessage] = asyncio.Queue()
- self.is_processing = False
- self.current_task: Optional[asyncio.Task] = None
- self.current_message: Optional[QueuedMessage] = None
-
-
-class MessageQueueManager:
- """
- Manages per-session message queues.
-
- When a session is busy, new messages are queued and processed
- one-by-one after the current request completes.
- """
-
- def __init__(self):
- self._queues: Dict[str, SessionQueue] = {}
- self._lock = asyncio.Lock()
-
- def _get_or_create_queue(self, session_id: str) -> SessionQueue:
- """Get existing queue or create new one for session."""
- if session_id not in self._queues:
- self._queues[session_id] = SessionQueue(session_id)
- return self._queues[session_id]
-
- def is_session_busy(self, session_id: str) -> bool:
- """Check if a session is currently processing a request."""
- if session_id not in self._queues:
- return False
- return self._queues[session_id].is_processing
-
- async def enqueue(
- self,
- session_id: str,
- message: QueuedMessage,
- processor: Callable[[str, QueuedMessage], Awaitable[None]],
- ) -> bool:
- """
- Add a message to the session's queue.
-
- If the session is not busy, processing starts immediately.
- If busy, the message is queued for later processing.
-
- Args:
- session_id: Claude session ID
- message: The queued message data
- processor: Async function to process the message
-
- Returns:
- True if message was queued (session busy), False if processed immediately
- """
- async with self._lock:
- sq = self._get_or_create_queue(session_id)
-
- if sq.is_processing:
- # Session is busy, queue the message
- await sq.queue.put(message)
- queue_size = sq.queue.qsize()
- logger.info(
- f"Queued message for session {session_id}, queue size: {queue_size}"
- )
- return True
- else:
- # Session is free, start processing
- sq.is_processing = True
-
- # Process outside the lock
- sq = self._queues[session_id]
- sq.current_task = asyncio.create_task(
- self._process_message(session_id, message, processor)
- )
- return False
-
- async def _process_message(
- self,
- session_id: str,
- message: QueuedMessage,
- processor: Callable[[str, QueuedMessage], Awaitable[None]],
- ) -> None:
- """Process a single message and then check the queue."""
- sq = self._queues.get(session_id)
- if sq:
- sq.current_message = message
- try:
- await processor(session_id, message)
- except asyncio.CancelledError:
- logger.info(f"Task for session {session_id} was cancelled")
- raise
- except Exception as e:
- logger.error(f"Error processing message for session {session_id}: {e}")
- finally:
- if sq:
- sq.current_message = None
- # Check if there are more messages in the queue
- await self._process_next(session_id, processor)
-
- async def _process_next(
- self,
- session_id: str,
- processor: Callable[[str, QueuedMessage], Awaitable[None]],
- ) -> None:
- """Process the next message in queue, if any."""
- async with self._lock:
- if session_id not in self._queues:
- return
-
- sq = self._queues[session_id]
-
- if sq.queue.empty():
- # No more messages, mark session as free
- sq.is_processing = False
- logger.debug(f"Session {session_id} queue empty, marking as free")
- return
-
- # Get next message
- try:
- next_msg = sq.queue.get_nowait()
- logger.info(f"Processing next queued message for session {session_id}")
- except asyncio.QueueEmpty:
- sq.is_processing = False
- return
-
- # Process next message (outside lock)
- sq.current_task = asyncio.create_task(
- self._process_message(session_id, next_msg, processor)
- )
-
- def get_queue_size(self, session_id: str) -> int:
- """Get the number of messages waiting in a session's queue."""
- if session_id not in self._queues:
- return 0
- return self._queues[session_id].queue.qsize()
-
- def cancel_session(self, session_id: str) -> List[QueuedMessage]:
- """
- Cancel all queued messages for a session and the running task.
-
- Returns:
- List of messages that were cancelled (including the current one if any)
- """
- if session_id not in self._queues:
- return []
-
- sq = self._queues[session_id]
- cancelled_messages = []
-
- # 1. Cancel running task
- if sq.current_task and not sq.current_task.done():
- sq.current_task.cancel()
- if sq.current_message:
- cancelled_messages.append(sq.current_message)
-
- # 2. Clear queue
- while not sq.queue.empty():
- try:
- msg = sq.queue.get_nowait()
- cancelled_messages.append(msg)
- except asyncio.QueueEmpty:
- break
-
- sq.is_processing = False
- logger.info(
- f"Cancelled {len(cancelled_messages)} messages for session {session_id}"
- )
- return cancelled_messages
-
- async def cancel_all(self) -> List[QueuedMessage]:
- """
- Cancel everything in all sessions.
-
- Returns:
- List of all cancelled messages across all sessions.
- """
- async with self._lock:
- all_cancelled = []
- session_ids = list(self._queues.keys())
- for sid in session_ids:
- all_cancelled.extend(self.cancel_session(sid))
- return all_cancelled
diff --git a/messaging/session.py b/messaging/session.py
index 7774a819..1bb7075b 100644
--- a/messaging/session.py
+++ b/messaging/session.py
@@ -1,8 +1,8 @@
"""
Session Store for Messaging Platforms
-Provides persistent storage for mapping platform messages to Claude CLI session IDs.
-This enables conversation continuation when replying to old messages.
+Provides persistent storage for mapping platform messages to Claude CLI session IDs
+and message trees for conversation continuation.
"""
import json
@@ -21,17 +21,17 @@ class SessionRecord:
"""A single session record."""
session_id: str
- chat_id: str # Changed to str for platform-agnostic support
+ chat_id: str
initial_msg_id: str
last_msg_id: str
- platform: str # "telegram", "discord", etc.
+ platform: str
created_at: str
updated_at: str
class SessionStore:
"""
- Persistent storage for message ↔ Claude session mappings.
+ Persistent storage for message ↔ Claude session mappings and message trees.
Uses a JSON file for storage with thread-safe operations.
Platform-agnostic: works with any messaging platform.
@@ -40,10 +40,12 @@ class SessionStore:
def __init__(self, storage_path: str = "sessions.json"):
self.storage_path = storage_path
self._lock = threading.Lock()
- self._sessions: Dict[str, SessionRecord] = {} # session_id -> record
+ self._sessions: Dict[str, SessionRecord] = {}
self._msg_to_session: Dict[
str, str
] = {} # "platform:chat_id:msg_id" -> session_id
+ self._trees: Dict[str, dict] = {} # root_id -> tree data
+ self._node_to_tree: Dict[str, str] = {} # node_id -> root_id
self._load()
def _make_key(self, platform: str, chat_id: str, msg_id: str) -> str:
@@ -51,7 +53,7 @@ class SessionStore:
return f"{platform}:{chat_id}:{msg_id}"
def _load(self) -> None:
- """Load sessions from disk."""
+ """Load sessions and trees from disk."""
if not os.path.exists(self.storage_path):
return
@@ -59,18 +61,16 @@ class SessionStore:
with open(self.storage_path, "r", encoding="utf-8") as f:
data = json.load(f)
+ # Load sessions (legacy support)
for sid, record_data in data.get("sessions", {}).items():
- # Handle legacy records without platform field
if "platform" not in record_data:
record_data["platform"] = "telegram"
- # Convert int to str for backwards compatibility
for field in ["chat_id", "initial_msg_id", "last_msg_id"]:
if isinstance(record_data.get(field), int):
record_data[field] = str(record_data[field])
record = SessionRecord(**record_data)
self._sessions[sid] = record
- # Index by initial and last message
self._msg_to_session[
self._make_key(
record.platform, record.chat_id, record.initial_msg_id
@@ -80,25 +80,33 @@ class SessionStore:
self._make_key(record.platform, record.chat_id, record.last_msg_id)
] = sid
+ # Load trees
+ self._trees = data.get("trees", {})
+ self._node_to_tree = data.get("node_to_tree", {})
+
logger.info(
- f"Loaded {len(self._sessions)} sessions from {self.storage_path}"
+ f"Loaded {len(self._sessions)} sessions and {len(self._trees)} trees from {self.storage_path}"
)
except Exception as e:
logger.error(f"Failed to load sessions: {e}")
def _save(self) -> None:
- """Persist sessions to disk."""
+ """Persist sessions and trees to disk."""
try:
data = {
"sessions": {
sid: asdict(record) for sid, record in self._sessions.items()
- }
+ },
+ "trees": self._trees,
+ "node_to_tree": self._node_to_tree,
}
with open(self.storage_path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2)
except Exception as e:
logger.error(f"Failed to save sessions: {e}")
+ # ==================== Session Methods ====================
+
def save_session(
self,
session_id: str,
@@ -106,15 +114,7 @@ class SessionStore:
initial_msg_id: str,
platform: str = "telegram",
) -> None:
- """
- Save a new session mapping.
-
- Args:
- session_id: Claude CLI session ID
- chat_id: Chat ID (platform-specific)
- initial_msg_id: The message ID that started this session
- platform: Messaging platform name
- """
+ """Save a new session mapping."""
with self._lock:
now = datetime.utcnow().isoformat()
record = SessionRecord(
@@ -138,65 +138,38 @@ class SessionStore:
def get_session_by_msg(
self, chat_id: str, msg_id: str, platform: str = "telegram"
) -> Optional[str]:
- """
- Look up a session ID by a message that's part of that session.
-
- Args:
- chat_id: Chat ID
- msg_id: Message ID to look up
- platform: Messaging platform name
-
- Returns:
- Session ID if found, None otherwise
- """
+ """Look up a session ID by a message that's part of that session."""
with self._lock:
key = self._make_key(platform, str(chat_id), str(msg_id))
return self._msg_to_session.get(key)
def update_last_message(self, session_id: str, msg_id: str) -> None:
- """
- Update the last message ID for a session.
-
- Args:
- session_id: Claude session ID
- msg_id: New last message ID
- """
+ """Update the last message ID for a session."""
with self._lock:
if session_id not in self._sessions:
logger.warning(f"Session {session_id} not found for update")
return
record = self._sessions[session_id]
-
- # Update record
record.last_msg_id = str(msg_id)
record.updated_at = datetime.utcnow().isoformat()
-
- # Update index - add new key, keep old one for chain lookups
new_key = self._make_key(record.platform, record.chat_id, str(msg_id))
self._msg_to_session[new_key] = session_id
-
self._save()
logger.debug(f"Updated session {session_id} last_msg to {msg_id}")
def rename_session(self, old_id: str, new_id: str) -> bool:
- """
- Rename a session ID, migrating all message mappings.
-
- This is crucial for handing over "pending_" sessions to real Claude session IDs.
- """
+ """Rename a session ID, migrating all message mappings."""
with self._lock:
if old_id not in self._sessions:
logger.warning(f"Session {old_id} not found for rename to {new_id}")
return False
- # Transfer record
record = self._sessions.pop(old_id)
record.session_id = new_id
record.updated_at = datetime.utcnow().isoformat()
self._sessions[new_id] = record
- # Update all message mappings pointing to the old ID
items_to_update = [
k for k, v in self._msg_to_session.items() if v == old_id
]
@@ -215,12 +188,7 @@ class SessionStore:
return self._sessions.get(session_id)
def cleanup_old_sessions(self, max_age_days: int = 30) -> int:
- """
- Remove sessions older than max_age_days.
-
- Returns:
- Number of sessions removed
- """
+ """Remove sessions older than max_age_days."""
with self._lock:
cutoff = datetime.utcnow()
removed = 0
@@ -237,7 +205,6 @@ class SessionStore:
for sid in to_remove:
record = self._sessions.pop(sid)
- # Remove index entries
self._msg_to_session.pop(
self._make_key(
record.platform, record.chat_id, record.initial_msg_id
@@ -255,3 +222,94 @@ class SessionStore:
logger.info(f"Cleaned up {removed} old sessions")
return removed
+
+ # ==================== Tree Methods ====================
+
+ def save_tree(self, root_id: str, tree_data: dict) -> None:
+ """
+ Save a message tree.
+
+ Args:
+ root_id: Root node ID of the tree
+ tree_data: Serialized tree data from tree.to_dict()
+ """
+ with self._lock:
+ self._trees[root_id] = tree_data
+
+ # Update node-to-tree mapping
+ for node_id in tree_data.get("nodes", {}).keys():
+ self._node_to_tree[node_id] = root_id
+
+ self._save()
+ logger.debug(f"Saved tree {root_id}")
+
+ def get_tree(self, root_id: str) -> Optional[dict]:
+ """Get a tree by its root ID."""
+ with self._lock:
+ return self._trees.get(root_id)
+
+ def get_tree_by_node(self, node_id: str) -> Optional[dict]:
+ """Get the tree containing a node."""
+ with self._lock:
+ root_id = self._node_to_tree.get(node_id)
+ if not root_id:
+ return None
+ return self._trees.get(root_id)
+
+ def get_tree_root_for_node(self, node_id: str) -> Optional[str]:
+ """Get the root ID of the tree containing a node."""
+ with self._lock:
+ return self._node_to_tree.get(node_id)
+
+ def register_node(self, node_id: str, root_id: str) -> None:
+ """Register a node ID to a tree root."""
+ with self._lock:
+ self._node_to_tree[node_id] = root_id
+ self._save()
+
+ def update_tree_node(self, root_id: str, node_id: str, node_data: dict) -> None:
+ """Update a specific node in a tree."""
+ with self._lock:
+ if root_id not in self._trees:
+ logger.warning(f"Tree {root_id} not found")
+ return
+
+ if "nodes" not in self._trees[root_id]:
+ self._trees[root_id]["nodes"] = {}
+
+ self._trees[root_id]["nodes"][node_id] = node_data
+ self._node_to_tree[node_id] = root_id
+ self._save()
+
+ def cleanup_old_trees(self, max_age_days: int = 30) -> int:
+ """Remove trees older than max_age_days."""
+ with self._lock:
+ cutoff = datetime.utcnow()
+ removed = 0
+ to_remove = []
+
+ for root_id, tree_data in self._trees.items():
+ try:
+ nodes = tree_data.get("nodes", {})
+ root_node = nodes.get(root_id, {})
+ created_str = root_node.get("created_at")
+ if created_str:
+ created = datetime.fromisoformat(created_str)
+ age_days = (cutoff - created).days
+ if age_days > max_age_days:
+ to_remove.append(root_id)
+ except Exception:
+ pass
+
+ for root_id in to_remove:
+ tree_data = self._trees.pop(root_id)
+ # Remove node mappings
+ for node_id in tree_data.get("nodes", {}).keys():
+ self._node_to_tree.pop(node_id, None)
+ removed += 1
+
+ if removed:
+ self._save()
+ logger.info(f"Cleaned up {removed} old trees")
+
+ return removed
diff --git a/messaging/tree_queue.py b/messaging/tree_queue.py
new file mode 100644
index 00000000..a4ecb3b6
--- /dev/null
+++ b/messaging/tree_queue.py
@@ -0,0 +1,608 @@
+"""
+Tree-Based Message Queue Manager
+
+Implements a tree structure for message queuing where:
+- Each new message creates a root node
+- Replies become child nodes of the message being replied to
+- Each node has a state (PENDING, IN_PROGRESS, COMPLETED, ERROR)
+- Per-tree queue processes messages in order
+- Child nodes only access parent context (via session forking)
+"""
+
+import asyncio
+import logging
+from enum import Enum
+from datetime import datetime
+from typing import Dict, Optional, List, Callable, Awaitable, Any
+from dataclasses import dataclass, field, asdict
+
+from .models import IncomingMessage
+
+logger = logging.getLogger(__name__)
+
+
+class MessageState(Enum):
+ """State of a message node in the tree."""
+
+ PENDING = "pending" # Queued, waiting to be processed
+ IN_PROGRESS = "in_progress" # Currently being processed by Claude
+ COMPLETED = "completed" # Processing finished successfully
+ ERROR = "error" # Processing failed
+
+
+@dataclass
+class MessageNode:
+ """
+ A node in the message tree.
+
+ Each node represents a single message and tracks:
+ - Its relationship to parent/children
+ - Its processing state
+ - Claude session information
+ """
+
+ node_id: str # Unique ID (typically message_id)
+ incoming: IncomingMessage # The original message
+ status_message_id: str # Bot's status message ID
+ state: MessageState = MessageState.PENDING
+ parent_id: Optional[str] = None # Parent node ID (None for root)
+ session_id: Optional[str] = None # Claude session ID (forked from parent)
+ children_ids: List[str] = field(default_factory=list)
+ created_at: datetime = field(default_factory=datetime.utcnow)
+ completed_at: Optional[datetime] = None
+ error_message: Optional[str] = None
+ context: Any = None # Additional context if needed
+
+ def to_dict(self) -> dict:
+ """Convert to dictionary for JSON serialization."""
+ return {
+ "node_id": self.node_id,
+ "incoming": {
+ "text": self.incoming.text,
+ "chat_id": self.incoming.chat_id,
+ "user_id": self.incoming.user_id,
+ "message_id": self.incoming.message_id,
+ "platform": self.incoming.platform,
+ "reply_to_message_id": self.incoming.reply_to_message_id,
+ "username": self.incoming.username,
+ },
+ "status_message_id": self.status_message_id,
+ "state": self.state.value,
+ "parent_id": self.parent_id,
+ "session_id": self.session_id,
+ "children_ids": self.children_ids,
+ "created_at": self.created_at.isoformat(),
+ "completed_at": self.completed_at.isoformat()
+ if self.completed_at
+ else None,
+ "error_message": self.error_message,
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict) -> "MessageNode":
+ """Create from dictionary (JSON deserialization)."""
+ incoming_data = data["incoming"]
+ incoming = IncomingMessage(
+ text=incoming_data["text"],
+ chat_id=incoming_data["chat_id"],
+ user_id=incoming_data["user_id"],
+ message_id=incoming_data["message_id"],
+ platform=incoming_data["platform"],
+ reply_to_message_id=incoming_data.get("reply_to_message_id"),
+ username=incoming_data.get("username"),
+ )
+ return cls(
+ node_id=data["node_id"],
+ incoming=incoming,
+ status_message_id=data["status_message_id"],
+ state=MessageState(data["state"]),
+ parent_id=data.get("parent_id"),
+ session_id=data.get("session_id"),
+ children_ids=data.get("children_ids", []),
+ created_at=datetime.fromisoformat(data["created_at"]),
+ completed_at=datetime.fromisoformat(data["completed_at"])
+ if data.get("completed_at")
+ else None,
+ error_message=data.get("error_message"),
+ )
+
+
+class MessageTree:
+ """
+ A tree of message nodes with queue functionality.
+
+ Provides:
+ - O(1) node lookup via hashmap
+ - Per-tree message queue
+ - Thread-safe operations via asyncio.Lock
+ """
+
+ def __init__(self, root_node: MessageNode):
+ """
+ Initialize tree with a root node.
+
+ Args:
+ root_node: The root message node
+ """
+ self.root_id = root_node.node_id
+ self._nodes: Dict[str, MessageNode] = {root_node.node_id: root_node}
+ self._queue: asyncio.Queue[str] = asyncio.Queue()
+ self._lock = asyncio.Lock()
+ self._is_processing = False
+ self._current_node_id: Optional[str] = None
+ self._current_task: Optional[asyncio.Task] = None
+
+ logger.debug(f"Created MessageTree with root {self.root_id}")
+
+ @property
+ def is_processing(self) -> bool:
+ """Check if tree is currently processing a message."""
+ return self._is_processing
+
+ async def add_node(
+ self,
+ node_id: str,
+ incoming: IncomingMessage,
+ status_message_id: str,
+ parent_id: str,
+ ) -> MessageNode:
+ """
+ Add a child node to the tree.
+
+ Args:
+ node_id: Unique ID for the new node
+ incoming: The incoming message
+ status_message_id: Bot's status message ID
+ parent_id: Parent node ID
+
+ Returns:
+ The created MessageNode
+ """
+ async with self._lock:
+ if parent_id not in self._nodes:
+ raise ValueError(f"Parent node {parent_id} not found in tree")
+
+ node = MessageNode(
+ node_id=node_id,
+ incoming=incoming,
+ status_message_id=status_message_id,
+ parent_id=parent_id,
+ state=MessageState.PENDING,
+ )
+
+ self._nodes[node_id] = node
+ self._nodes[parent_id].children_ids.append(node_id)
+
+ logger.debug(f"Added node {node_id} as child of {parent_id}")
+ return node
+
+ def get_node(self, node_id: str) -> Optional[MessageNode]:
+ """Get a node by ID (O(1) lookup)."""
+ return self._nodes.get(node_id)
+
+ def get_root(self) -> MessageNode:
+ """Get the root node."""
+ return self._nodes[self.root_id]
+
+ def get_children(self, node_id: str) -> List[MessageNode]:
+ """Get all child nodes of a given node."""
+ node = self._nodes.get(node_id)
+ if not node:
+ return []
+ return [self._nodes[cid] for cid in node.children_ids if cid in self._nodes]
+
+ def get_parent(self, node_id: str) -> Optional[MessageNode]:
+ """Get the parent node."""
+ node = self._nodes.get(node_id)
+ if not node or not node.parent_id:
+ return None
+ return self._nodes.get(node.parent_id)
+
+ def get_parent_session_id(self, node_id: str) -> Optional[str]:
+ """
+ Get the parent's session ID for forking.
+
+ Returns None for root nodes.
+ """
+ parent = self.get_parent(node_id)
+ return parent.session_id if parent else None
+
+ async def update_state(
+ self,
+ node_id: str,
+ state: MessageState,
+ session_id: Optional[str] = None,
+ error_message: Optional[str] = None,
+ ) -> None:
+ """Update a node's state."""
+ async with self._lock:
+ node = self._nodes.get(node_id)
+ if not node:
+ logger.warning(f"Node {node_id} not found for state update")
+ return
+
+ node.state = state
+ if session_id:
+ node.session_id = session_id
+ if error_message:
+ node.error_message = error_message
+ if state in (MessageState.COMPLETED, MessageState.ERROR):
+ node.completed_at = datetime.utcnow()
+
+ logger.debug(f"Node {node_id} state -> {state.value}")
+
+ async def enqueue(self, node_id: str) -> int:
+ """
+ Add a node to the processing queue.
+
+ Returns:
+ Queue position (1-indexed)
+ """
+ async with self._lock:
+ await self._queue.put(node_id)
+ position = self._queue.qsize()
+ logger.debug(f"Enqueued node {node_id}, position {position}")
+ return position
+
+ async def dequeue(self) -> Optional[str]:
+ """
+ Get the next node ID from the queue.
+
+ Returns None if queue is empty.
+ """
+ try:
+ return self._queue.get_nowait()
+ except asyncio.QueueEmpty:
+ return None
+
+ def get_queue_size(self) -> int:
+ """Get number of messages waiting in queue."""
+ return self._queue.qsize()
+
+ def get_queue_position(self, node_id: str) -> int:
+ """
+ Get position of a node in the queue.
+
+ Returns 0 if not in queue, 1+ for queue position.
+ """
+ # Note: asyncio.Queue doesn't support direct iteration
+ # This is an approximation based on order
+ return 0 # TODO: Track positions separately if needed
+
+ def to_dict(self) -> dict:
+ """Serialize tree to dictionary."""
+ return {
+ "root_id": self.root_id,
+ "nodes": {nid: node.to_dict() for nid, node in self._nodes.items()},
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict) -> "MessageTree":
+ """Deserialize tree from dictionary."""
+ root_id = data["root_id"]
+ nodes_data = data["nodes"]
+
+ # Create root node first
+ root_node = MessageNode.from_dict(nodes_data[root_id])
+ tree = cls(root_node)
+
+ # Add remaining nodes
+ for node_id, node_data in nodes_data.items():
+ if node_id != root_id:
+ tree._nodes[node_id] = MessageNode.from_dict(node_data)
+
+ return tree
+
+ def all_nodes(self) -> List[MessageNode]:
+ """Get all nodes in the tree."""
+ return list(self._nodes.values())
+
+ def has_node(self, node_id: str) -> bool:
+ """Check if a node exists in this tree."""
+ return node_id in self._nodes
+
+ def find_node_by_status_message(self, status_msg_id: str) -> Optional[MessageNode]:
+ """Find the node that has this status message ID."""
+ for node in self._nodes.values():
+ if node.status_message_id == status_msg_id:
+ return node
+ return None
+
+
+class TreeQueueManager:
+ """
+ Manages multiple message trees.
+
+ Each new conversation creates a new tree.
+ Replies to existing messages add nodes to existing trees.
+ """
+
+ def __init__(self):
+ self._trees: Dict[str, MessageTree] = {} # root_id -> tree
+ self._node_to_tree: Dict[str, str] = {} # node_id -> root_id
+ self._lock = asyncio.Lock()
+
+ logger.info("TreeQueueManager initialized")
+
+ async def create_tree(
+ self,
+ node_id: str,
+ incoming: IncomingMessage,
+ status_message_id: str,
+ ) -> MessageTree:
+ """
+ Create a new tree with a root node.
+
+ Args:
+ node_id: ID for the root node
+ incoming: The incoming message
+ status_message_id: Bot's status message ID
+
+ Returns:
+ The created MessageTree
+ """
+ async with self._lock:
+ root_node = MessageNode(
+ node_id=node_id,
+ incoming=incoming,
+ status_message_id=status_message_id,
+ state=MessageState.PENDING,
+ )
+
+ tree = MessageTree(root_node)
+ self._trees[node_id] = tree
+ self._node_to_tree[node_id] = node_id
+
+ logger.info(f"Created new tree with root {node_id}")
+ return tree
+
+ async def add_to_tree(
+ self,
+ parent_node_id: str,
+ node_id: str,
+ incoming: IncomingMessage,
+ status_message_id: str,
+ ) -> tuple[MessageTree, MessageNode]:
+ """
+ Add a reply as a child node to an existing tree.
+
+ Args:
+ parent_node_id: ID of the parent message
+ node_id: ID for the new node
+ incoming: The incoming reply message
+ status_message_id: Bot's status message ID
+
+ Returns:
+ Tuple of (tree, new_node)
+ """
+ async with self._lock:
+ if parent_node_id not in self._node_to_tree:
+ raise ValueError(f"Parent node {parent_node_id} not found in any tree")
+
+ root_id = self._node_to_tree[parent_node_id]
+ tree = self._trees[root_id]
+
+ # Add node (tree has its own lock)
+ node = await tree.add_node(
+ node_id=node_id,
+ incoming=incoming,
+ status_message_id=status_message_id,
+ parent_id=parent_node_id,
+ )
+
+ async with self._lock:
+ self._node_to_tree[node_id] = root_id
+
+ logger.info(f"Added node {node_id} to tree {root_id}")
+ return tree, node
+
+ def get_tree(self, root_id: str) -> Optional[MessageTree]:
+ """Get a tree by its root ID."""
+ return self._trees.get(root_id)
+
+ def get_tree_for_node(self, node_id: str) -> Optional[MessageTree]:
+ """Get the tree containing a given node."""
+ root_id = self._node_to_tree.get(node_id)
+ if not root_id:
+ return None
+ return self._trees.get(root_id)
+
+ def get_node(self, node_id: str) -> Optional[MessageNode]:
+ """Get a node from any tree."""
+ tree = self.get_tree_for_node(node_id)
+ return tree.get_node(node_id) if tree else None
+
+ def resolve_parent_node_id(self, msg_id: str) -> Optional[str]:
+ """
+ Resolve a message ID to the actual parent node ID.
+
+ Handles the case where msg_id is a status message ID
+ (which maps to the tree but isn't an actual node).
+
+ Returns:
+ The node_id to use as parent, or None if not found
+ """
+ tree = self.get_tree_for_node(msg_id)
+ if not tree:
+ return None
+
+ # Check if msg_id is an actual node
+ if tree.has_node(msg_id):
+ return msg_id
+
+ # Otherwise, it might be a status message - find the owning node
+ node = tree.find_node_by_status_message(msg_id)
+ if node:
+ return node.node_id
+
+ return None
+
+ def is_tree_busy(self, root_id: str) -> bool:
+ """Check if a tree is currently processing."""
+ tree = self._trees.get(root_id)
+ return tree.is_processing if tree else False
+
+ def is_node_tree_busy(self, node_id: str) -> bool:
+ """Check if the tree containing a node is busy."""
+ tree = self.get_tree_for_node(node_id)
+ return tree.is_processing if tree else False
+
+ async def enqueue(
+ self,
+ node_id: str,
+ processor: Callable[[str, MessageNode], Awaitable[None]],
+ ) -> bool:
+ """
+ Enqueue a node for processing.
+
+ If the tree is not busy, processing starts immediately.
+ If busy, the message is queued.
+
+ Args:
+ node_id: Node to process
+ processor: Async function to process the node
+
+ Returns:
+ True if queued, False if processing immediately
+ """
+ tree = self.get_tree_for_node(node_id)
+ if not tree:
+ logger.error(f"No tree found for node {node_id}")
+ return False
+
+ async with tree._lock:
+ if tree._is_processing:
+ # Tree is busy, queue the message
+ await tree._queue.put(node_id)
+ queue_size = tree._queue.qsize()
+ logger.info(f"Queued node {node_id}, position {queue_size}")
+ return True
+ else:
+ # Tree is free, start processing
+ tree._is_processing = True
+ tree._current_node_id = node_id
+
+ # Process outside the lock
+ node = tree.get_node(node_id)
+ if node:
+ tree._current_task = asyncio.create_task(
+ self._process_node(tree, node, processor)
+ )
+ return False
+
+ async def _process_node(
+ self,
+ tree: MessageTree,
+ node: MessageNode,
+ processor: Callable[[str, MessageNode], Awaitable[None]],
+ ) -> None:
+ """Process a single node and then check the queue."""
+ try:
+ await processor(node.node_id, node)
+ except asyncio.CancelledError:
+ logger.info(f"Task for node {node.node_id} was cancelled")
+ raise
+ except Exception as e:
+ logger.error(f"Error processing node {node.node_id}: {e}")
+ await tree.update_state(
+ node.node_id, MessageState.ERROR, error_message=str(e)
+ )
+ finally:
+ tree._current_node_id = None
+ # Check if there are more messages in the queue
+ await self._process_next(tree, processor)
+
+ async def _process_next(
+ self,
+ tree: MessageTree,
+ processor: Callable[[str, MessageNode], Awaitable[None]],
+ ) -> None:
+ """Process the next message in queue, if any."""
+ async with tree._lock:
+ next_node_id = await tree.dequeue()
+
+ if not next_node_id:
+ # No more messages, mark tree as free
+ tree._is_processing = False
+ logger.debug(f"Tree {tree.root_id} queue empty, marking as free")
+ return
+
+ tree._current_node_id = next_node_id
+ logger.info(f"Processing next queued node {next_node_id}")
+
+ # Process next node (outside lock)
+ node = tree.get_node(next_node_id)
+ if node:
+ tree._current_task = asyncio.create_task(
+ self._process_node(tree, node, processor)
+ )
+
+ def get_queue_size(self, node_id: str) -> int:
+ """Get queue size for the tree containing a node."""
+ tree = self.get_tree_for_node(node_id)
+ return tree.get_queue_size() if tree else 0
+
+ def cancel_tree(self, root_id: str) -> List[MessageNode]:
+ """
+ Cancel all queued messages in a tree.
+
+ Returns:
+ List of cancelled nodes
+ """
+ tree = self._trees.get(root_id)
+ if not tree:
+ return []
+
+ cancelled_nodes = []
+
+ # Cancel running task
+ if tree._current_task and not tree._current_task.done():
+ tree._current_task.cancel()
+ if tree._current_node_id:
+ node = tree.get_node(tree._current_node_id)
+ if node:
+ cancelled_nodes.append(node)
+
+ # Clear queue
+ while not tree._queue.empty():
+ try:
+ node_id = tree._queue.get_nowait()
+ node = tree.get_node(node_id)
+ if node:
+ cancelled_nodes.append(node)
+ except asyncio.QueueEmpty:
+ break
+
+ tree._is_processing = False
+ tree._current_node_id = None
+
+ logger.info(f"Cancelled {len(cancelled_nodes)} nodes in tree {root_id}")
+ return cancelled_nodes
+
+ async def cancel_all(self) -> List[MessageNode]:
+ """Cancel all messages in all trees."""
+ async with self._lock:
+ all_cancelled = []
+ for root_id in list(self._trees.keys()):
+ all_cancelled.extend(self.cancel_tree(root_id))
+ return all_cancelled
+
+ def register_node(self, node_id: str, root_id: str) -> None:
+ """Register a node ID to a tree (for external mapping)."""
+ self._node_to_tree[node_id] = root_id
+
+ def to_dict(self) -> dict:
+ """Serialize all trees."""
+ return {
+ "trees": {rid: tree.to_dict() for rid, tree in self._trees.items()},
+ "node_to_tree": self._node_to_tree.copy(),
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict) -> "TreeQueueManager":
+ """Deserialize from dictionary."""
+ manager = cls()
+ for root_id, tree_data in data.get("trees", {}).items():
+ manager._trees[root_id] = MessageTree.from_dict(tree_data)
+ manager._node_to_tree = data.get("node_to_tree", {})
+ return manager
diff --git a/tests/test_handler_format.py b/tests/test_handler_format.py
index 34c76fb8..d3953219 100644
--- a/tests/test_handler_format.py
+++ b/tests/test_handler_format.py
@@ -8,8 +8,7 @@ def handler():
platform = MagicMock()
cli = MagicMock()
store = MagicMock()
- queue = MagicMock()
- return ClaudeMessageHandler(platform, cli, store, queue)
+ return ClaudeMessageHandler(platform, cli, store)
def test_build_message_structure(handler):
diff --git a/tests/test_messaging.py b/tests/test_messaging.py
index 4c41976e..a4547e4a 100644
--- a/tests/test_messaging.py
+++ b/tests/test_messaging.py
@@ -134,56 +134,56 @@ class TestSessionStore:
assert found is None
-class TestMessageQueueManager:
- """Test MessageQueueManager."""
+class TestTreeQueueManager:
+ """Test TreeQueueManager."""
- def test_queue_manager_init(self):
- """Test MessageQueueManager initialization."""
- from messaging.queue import MessageQueueManager
+ def test_tree_queue_manager_init(self):
+ """Test TreeQueueManager initialization."""
+ from messaging.tree_queue import TreeQueueManager
- mgr = MessageQueueManager()
- assert mgr._queues == {}
+ mgr = TreeQueueManager()
+ assert mgr._trees == {}
- def test_session_not_busy_initially(self):
- """Test session is not busy when no messages."""
- from messaging.queue import MessageQueueManager
+ def test_tree_not_busy_initially(self):
+ """Test tree is not busy when no messages."""
+ from messaging.tree_queue import TreeQueueManager
- mgr = MessageQueueManager()
- assert mgr.is_session_busy("nonexistent") is False
+ mgr = TreeQueueManager()
+ assert mgr.is_tree_busy("nonexistent") is False
def test_get_queue_size_empty(self):
- """Test queue size is 0 for non-existent session."""
- from messaging.queue import MessageQueueManager
+ """Test queue size is 0 for non-existent node."""
+ from messaging.tree_queue import TreeQueueManager
- mgr = MessageQueueManager()
+ mgr = TreeQueueManager()
assert mgr.get_queue_size("nonexistent") == 0
@pytest.mark.asyncio
- async def test_enqueue_and_process(self):
- """Test enqueueing a message starts processing."""
- from messaging.queue import MessageQueueManager, QueuedMessage
+ async def test_create_tree_and_enqueue(self):
+ """Test creating a tree and enqueueing."""
+ from messaging.tree_queue import TreeQueueManager
from messaging.models import IncomingMessage
- mgr = MessageQueueManager()
+ mgr = TreeQueueManager()
processed = []
- async def processor(sid, msg):
- processed.append(msg)
+ async def processor(node_id, node):
+ processed.append(node_id)
incoming = IncomingMessage(
text="test", chat_id="1", user_id="1", message_id="1", platform="test"
)
- queued = QueuedMessage(incoming=incoming, status_message_id="status_1")
- was_queued = await mgr.enqueue("session_1", queued, processor)
+ tree = await mgr.create_tree("1", incoming, "status_1")
+ was_queued = await mgr.enqueue("1", processor)
# First message should process immediately, not queue
assert was_queued is False
- def test_cancel_session_empty(self):
- """Test cancelling non-existent session."""
- from messaging.queue import MessageQueueManager
+ def test_cancel_tree_empty(self):
+ """Test cancelling non-existent tree."""
+ from messaging.tree_queue import TreeQueueManager
- mgr = MessageQueueManager()
- cancelled = mgr.cancel_session("nonexistent")
+ mgr = TreeQueueManager()
+ cancelled = mgr.cancel_tree("nonexistent")
assert cancelled == []
diff --git a/tests/test_tree_queue.py b/tests/test_tree_queue.py
new file mode 100644
index 00000000..bdbcf3e6
--- /dev/null
+++ b/tests/test_tree_queue.py
@@ -0,0 +1,446 @@
+"""Tests for tree-based message queue system."""
+
+import pytest
+import asyncio
+from datetime import datetime
+
+from messaging.tree_queue import (
+ MessageState,
+ MessageNode,
+ MessageTree,
+ TreeQueueManager,
+)
+from messaging.models import IncomingMessage
+
+
+class TestMessageState:
+ """Test MessageState enum."""
+
+ def test_state_values(self):
+ """Test state enum values."""
+ assert MessageState.PENDING.value == "pending"
+ assert MessageState.IN_PROGRESS.value == "in_progress"
+ assert MessageState.COMPLETED.value == "completed"
+ assert MessageState.ERROR.value == "error"
+
+
+class TestMessageNode:
+ """Test MessageNode dataclass."""
+
+ def test_node_creation(self):
+ """Test creating a message node."""
+ incoming = IncomingMessage(
+ text="Hello",
+ chat_id="123",
+ user_id="456",
+ message_id="789",
+ platform="telegram",
+ )
+ node = MessageNode(
+ node_id="789",
+ incoming=incoming,
+ status_message_id="status_1",
+ )
+
+ assert node.node_id == "789"
+ assert node.state == MessageState.PENDING
+ assert node.parent_id is None
+ assert node.children_ids == []
+ assert node.session_id is None
+
+ def test_node_to_dict(self):
+ """Test serializing a node."""
+ incoming = IncomingMessage(
+ text="Test",
+ chat_id="1",
+ user_id="2",
+ message_id="3",
+ platform="test",
+ )
+ node = MessageNode(
+ node_id="3",
+ incoming=incoming,
+ status_message_id="s1",
+ state=MessageState.COMPLETED,
+ session_id="sess_123",
+ )
+
+ data = node.to_dict()
+ assert data["node_id"] == "3"
+ assert data["state"] == "completed"
+ assert data["session_id"] == "sess_123"
+
+ def test_node_from_dict(self):
+ """Test deserializing a node."""
+ data = {
+ "node_id": "n1",
+ "incoming": {
+ "text": "Hello",
+ "chat_id": "c1",
+ "user_id": "u1",
+ "message_id": "m1",
+ "platform": "test",
+ },
+ "status_message_id": "s1",
+ "state": "in_progress",
+ "parent_id": "parent_1",
+ "session_id": None,
+ "children_ids": ["child_1"],
+ "created_at": "2025-01-01T00:00:00",
+ }
+
+ node = MessageNode.from_dict(data)
+ assert node.node_id == "n1"
+ assert node.state == MessageState.IN_PROGRESS
+ assert node.parent_id == "parent_1"
+ assert "child_1" in node.children_ids
+
+
+class TestMessageTree:
+ """Test MessageTree class."""
+
+ def test_tree_creation(self):
+ """Test creating a tree with root node."""
+ incoming = IncomingMessage(
+ text="Root",
+ chat_id="1",
+ user_id="1",
+ message_id="root_msg",
+ platform="test",
+ )
+ root = MessageNode(
+ node_id="root_msg",
+ incoming=incoming,
+ status_message_id="status_1",
+ )
+
+ tree = MessageTree(root)
+ assert tree.root_id == "root_msg"
+ assert tree.get_node("root_msg") is not None
+ assert tree.is_processing is False
+
+ @pytest.mark.asyncio
+ async def test_add_child_node(self):
+ """Test adding a child node to the tree."""
+ # Create root
+ root_incoming = IncomingMessage(
+ text="Root",
+ chat_id="1",
+ user_id="1",
+ message_id="root",
+ platform="test",
+ )
+ root = MessageNode(
+ node_id="root",
+ incoming=root_incoming,
+ status_message_id="s1",
+ )
+ tree = MessageTree(root)
+
+ # Add child
+ child_incoming = IncomingMessage(
+ text="Child",
+ chat_id="1",
+ user_id="1",
+ message_id="child",
+ platform="test",
+ reply_to_message_id="root",
+ )
+ child = await tree.add_node(
+ node_id="child",
+ incoming=child_incoming,
+ status_message_id="s2",
+ parent_id="root",
+ )
+
+ assert child.node_id == "child"
+ assert child.parent_id == "root"
+ assert "child" in tree.get_root().children_ids
+ assert tree.get_parent("child").node_id == "root"
+
+ @pytest.mark.asyncio
+ async def test_update_state(self):
+ """Test updating node state."""
+ incoming = IncomingMessage(
+ text="Test",
+ chat_id="1",
+ user_id="1",
+ message_id="m1",
+ platform="test",
+ )
+ root = MessageNode(node_id="m1", incoming=incoming, status_message_id="s1")
+ tree = MessageTree(root)
+
+ await tree.update_state("m1", MessageState.IN_PROGRESS)
+ assert tree.get_node("m1").state == MessageState.IN_PROGRESS
+
+ await tree.update_state("m1", MessageState.COMPLETED, session_id="sess_abc")
+ node = tree.get_node("m1")
+ assert node.state == MessageState.COMPLETED
+ assert node.session_id == "sess_abc"
+ assert node.completed_at is not None
+
+ @pytest.mark.asyncio
+ async def test_enqueue_dequeue(self):
+ """Test queue operations."""
+ incoming = IncomingMessage(
+ text="Test",
+ chat_id="1",
+ user_id="1",
+ message_id="m1",
+ platform="test",
+ )
+ root = MessageNode(node_id="m1", incoming=incoming, status_message_id="s1")
+ tree = MessageTree(root)
+
+ # Enqueue
+ pos = await tree.enqueue("m1")
+ assert pos == 1
+ assert tree.get_queue_size() == 1
+
+ # Dequeue
+ node_id = await tree.dequeue()
+ assert node_id == "m1"
+ assert tree.get_queue_size() == 0
+
+ def test_tree_serialization(self):
+ """Test tree to_dict and from_dict."""
+ incoming = IncomingMessage(
+ text="Test",
+ chat_id="1",
+ user_id="1",
+ message_id="m1",
+ platform="test",
+ )
+ root = MessageNode(
+ node_id="m1",
+ incoming=incoming,
+ status_message_id="s1",
+ state=MessageState.COMPLETED,
+ session_id="sess_1",
+ )
+ tree = MessageTree(root)
+
+ data = tree.to_dict()
+ restored = MessageTree.from_dict(data)
+
+ assert restored.root_id == "m1"
+ assert restored.get_node("m1").session_id == "sess_1"
+
+
+class TestTreeQueueManager:
+ """Test TreeQueueManager class."""
+
+ @pytest.mark.asyncio
+ async def test_create_tree(self):
+ """Test creating a new tree."""
+ manager = TreeQueueManager()
+
+ incoming = IncomingMessage(
+ text="New message",
+ chat_id="1",
+ user_id="1",
+ message_id="msg_1",
+ platform="test",
+ )
+
+ tree = await manager.create_tree(
+ node_id="msg_1",
+ incoming=incoming,
+ status_message_id="status_1",
+ )
+
+ assert tree is not None
+ assert tree.root_id == "msg_1"
+ assert manager.get_tree("msg_1") is tree
+
+ @pytest.mark.asyncio
+ async def test_add_reply_to_tree(self):
+ """Test adding a reply to existing tree."""
+ manager = TreeQueueManager()
+
+ # Create root
+ root_incoming = IncomingMessage(
+ text="Root",
+ chat_id="1",
+ user_id="1",
+ message_id="root",
+ platform="test",
+ )
+ await manager.create_tree("root", root_incoming, "s1")
+
+ # Add reply
+ reply_incoming = IncomingMessage(
+ text="Reply",
+ chat_id="1",
+ user_id="1",
+ message_id="reply",
+ platform="test",
+ reply_to_message_id="root",
+ )
+ tree, node = await manager.add_to_tree(
+ parent_node_id="root",
+ node_id="reply",
+ incoming=reply_incoming,
+ status_message_id="s2",
+ )
+
+ assert node.parent_id == "root"
+ assert manager.get_tree_for_node("reply") is tree
+
+ @pytest.mark.asyncio
+ async def test_enqueue_and_process(self):
+ """Test enqueueing and processing."""
+ manager = TreeQueueManager()
+ processed = []
+
+ async def processor(node_id, node):
+ processed.append(node_id)
+ await asyncio.sleep(0.01) # Simulate work
+
+ incoming = IncomingMessage(
+ text="Test",
+ chat_id="1",
+ user_id="1",
+ message_id="m1",
+ platform="test",
+ )
+ await manager.create_tree("m1", incoming, "s1")
+
+ was_queued = await manager.enqueue("m1", processor)
+ assert was_queued is False # First message processes immediately
+
+ # Wait for processing
+ await asyncio.sleep(0.1)
+ assert "m1" in processed
+
+ @pytest.mark.asyncio
+ async def test_queue_when_busy(self):
+ """Test that messages queue when tree is busy."""
+ manager = TreeQueueManager()
+ processing_started = asyncio.Event()
+ processing_complete = asyncio.Event()
+
+ async def slow_processor(node_id, node):
+ processing_started.set()
+ await processing_complete.wait()
+
+ # Create tree with root
+ root_incoming = IncomingMessage(
+ text="Root",
+ chat_id="1",
+ user_id="1",
+ message_id="root",
+ platform="test",
+ )
+ await manager.create_tree("root", root_incoming, "s1")
+
+ # Start processing root
+ was_queued = await manager.enqueue("root", slow_processor)
+ assert was_queued is False
+
+ # Wait for processing to start
+ await processing_started.wait()
+
+ # Add a child
+ child_incoming = IncomingMessage(
+ text="Child",
+ chat_id="1",
+ user_id="1",
+ message_id="child",
+ platform="test",
+ reply_to_message_id="root",
+ )
+ await manager.add_to_tree("root", "child", child_incoming, "s2")
+
+ # Try to enqueue child - should be queued since tree is busy
+ was_queued = await manager.enqueue("child", slow_processor)
+ assert was_queued is True
+ assert manager.get_queue_size("child") == 1
+
+ # Cleanup
+ processing_complete.set()
+
+ @pytest.mark.asyncio
+ async def test_cancel_tree(self):
+ """Test cancelling a tree."""
+ manager = TreeQueueManager()
+ processing_complete = asyncio.Event()
+
+ async def slow_processor(node_id, node):
+ await processing_complete.wait()
+
+ incoming = IncomingMessage(
+ text="Test",
+ chat_id="1",
+ user_id="1",
+ message_id="m1",
+ platform="test",
+ )
+ await manager.create_tree("m1", incoming, "s1")
+ await manager.enqueue("m1", slow_processor)
+
+ # Cancel
+ cancelled = manager.cancel_tree("m1")
+ assert len(cancelled) == 1
+
+ processing_complete.set()
+
+
+class TestSessionStoreTrees:
+ """Test SessionStore tree methods."""
+
+ def test_save_and_get_tree(self, tmp_path):
+ """Test saving and retrieving a tree."""
+ from messaging.session import SessionStore
+
+ store = SessionStore(storage_path=str(tmp_path / "sessions.json"))
+
+ tree_data = {
+ "root_id": "root_1",
+ "nodes": {
+ "root_1": {
+ "node_id": "root_1",
+ "state": "completed",
+ "session_id": "sess_abc",
+ }
+ },
+ }
+
+ store.save_tree("root_1", tree_data)
+
+ retrieved = store.get_tree("root_1")
+ assert retrieved is not None
+ assert retrieved["root_id"] == "root_1"
+
+ def test_get_tree_by_node(self, tmp_path):
+ """Test getting tree by node ID."""
+ from messaging.session import SessionStore
+
+ store = SessionStore(storage_path=str(tmp_path / "sessions.json"))
+
+ tree_data = {
+ "root_id": "root",
+ "nodes": {
+ "root": {"node_id": "root"},
+ "child": {"node_id": "child"},
+ },
+ }
+
+ store.save_tree("root", tree_data)
+
+ # Should find tree by child node
+ retrieved = store.get_tree_by_node("child")
+ assert retrieved is not None
+ assert retrieved["root_id"] == "root"
+
+ def test_register_node(self, tmp_path):
+ """Test registering a node to a tree."""
+ from messaging.session import SessionStore
+
+ store = SessionStore(storage_path=str(tmp_path / "sessions.json"))
+
+ store.register_node("new_node", "root_tree")
+
+ root_id = store.get_tree_root_for_node("new_node")
+ assert root_id == "root_tree"