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

Refactor messaging workflow architecture (#852)

Ali Khokhara97bf7f8b324
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index d377b158..d019004f 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -114,10 +114,10 @@ new places to add unrelated behavior:
transport bases from per-request stream runners, recovery event construction,
and transport-specific parsing. Shared protocol rules should continue moving
toward [core/](core/) when they are not provider-specific.
-- [messaging/handler.py](messaging/handler.py) owns command dispatch, tree
- queueing, CLI session execution, transcript updates, and persistence
- coordination. New platform-specific behavior should stay in platform or
- rendering modules.
+- [messaging/workflow.py](messaging/workflow.py) coordinates messaging runtime
+ dependencies. Inbound turn intake, queued node execution, slash command
+ dependencies, and tree queue internals live in separate modules so new
+ behavior has one owner instead of growing the workflow object.
- [api/admin_config.py](api/admin_config.py) owns the admin config manifest,
validation, env rendering, and status metadata. Keep it data-driven, and split
only around cohesive admin responsibilities.
@@ -488,16 +488,31 @@ Messaging is optional. [api/runtime.py](api/runtime.py) calls
If `MESSAGING_PLATFORM` is `none`, or if the selected platform token is missing,
the messaging bridge is skipped.
-[messaging/handler.py](messaging/handler.py) contains `ClaudeMessageHandler`, the
-platform-agnostic orchestration layer. It receives `IncomingMessage` objects,
-dispatches commands, filters its own status messages, creates or extends a
-message tree, queues work, runs a managed client CLI session, parses CLI events,
-updates transcripts, and persists conversation state.
+[messaging/workflow.py](messaging/workflow.py) contains `MessagingWorkflow`, the
+platform-agnostic coordinator. It owns dependencies, callback wiring, stop/clear
+side effects, render settings, and shutdown-visible state.
-[messaging/trees/queue_manager.py](messaging/trees/queue_manager.py) preserves
+[messaging/turn_intake.py](messaging/turn_intake.py) owns inbound message
+recording, slash command dispatch, status-echo filtering, reply resolution, tree
+creation/extension, initial status messages, persistence, and enqueueing.
+
+[messaging/node_runner.py](messaging/node_runner.py) owns managed CLI session
+lifecycle for queued nodes: parent-session fork/resume, session registration,
+CLI event parsing, transcript/status updates, cancellation, error propagation,
+and session cleanup.
+
+[messaging/command_context.py](messaging/command_context.py) defines the typed
+dependency surface for `/stop`, `/clear`, and `/stats`; commands should not
+depend on the concrete workflow object.
+
+[messaging/trees/manager.py](messaging/trees/manager.py) preserves
per-conversation ordering with tree-aware queues. Replies become child nodes, and
each tree processes one node at a time while separate trees can progress
-independently.
+independently. [messaging/trees/repository.py](messaging/trees/repository.py)
+owns the in-memory tree/node index, and
+[messaging/trees/processor.py](messaging/trees/processor.py) owns async queue
+processing. [messaging/trees/data.py](messaging/trees/data.py) owns the persisted
+`MessageNode` and `MessageTree` JSON shape.
[messaging/session.py](messaging/session.py) persists trees, node-to-tree
mappings, and message IDs to a JSON file under the managed agent workspace. It
@@ -506,20 +521,23 @@ uses debounced atomic writes and flushes pending saves on shutdown.
```mermaid
sequenceDiagram
participant Platform as DiscordOrTelegram
- participant Handler as ClaudeMessageHandler
+ participant Workflow as MessagingWorkflow
+ participant Intake as MessagingTurnIntake
participant Queue as TreeQueueManager
+ participant Runner as MessagingNodeRunner
participant Manager as CLISessionManager
participant CLI as ClientCLI
participant Proxy as LocalProxy
- Platform->>Handler: IncomingMessage
- Handler->>Queue: create or extend message tree
- Queue->>Handler: process node in order
- Handler->>Manager: get_or_create_session
+ Platform->>Workflow: IncomingMessage
+ Workflow->>Intake: handle inbound turn
+ Intake->>Queue: create or extend message tree
+ Queue->>Runner: process node in order
+ Runner->>Manager: get_or_create_session
Manager->>CLI: launch JSON stream task
CLI->>Proxy: provider-backed API calls
- CLI-->>Handler: parsed stdout events
- Handler-->>Platform: status and transcript updates
+ CLI-->>Runner: parsed stdout events
+ Runner-->>Platform: status and transcript updates
```
## Observability, Diagnostics, And Safety
@@ -645,3 +663,4 @@ Update this file when a change adds or meaningfully changes:
Docs-only changes to this file do not require a semver bump. Production code
changes still follow the versioning rules in [AGENTS.md](AGENTS.md) and
[CLAUDE.md](CLAUDE.md).
+
diff --git a/api/routes.py b/api/routes.py
index 73581b0a..08b7fef6 100644
--- a/api/routes.py
+++ b/api/routes.py
@@ -135,8 +135,8 @@ async def list_models(
@router.post("/stop")
async def stop_cli(request: Request, _auth=Depends(require_api_key)):
"""Stop all CLI sessions and pending tasks."""
- handler = getattr(request.app.state, "message_handler", None)
- if not handler:
+ workflow = getattr(request.app.state, "messaging_workflow", None)
+ if not workflow:
# Fallback if messaging not initialized
cli_manager = getattr(request.app.state, "cli_manager", None)
if cli_manager:
@@ -145,12 +145,12 @@ async def stop_cli(request: Request, _auth=Depends(require_api_key)):
return {"status": "stopped", "source": "cli_manager"}
raise HTTPException(status_code=503, detail="Messaging system not initialized")
- count = await handler.stop_all_tasks()
+ count = await workflow.stop_all_tasks()
trace_event(
stage="ingress",
- event="api.cli.stop_via_handler",
+ event="api.cli.stop_via_messaging_workflow",
source="api",
cancelled_nodes=count,
)
- logger.info("STOP_CLI: source=handler cancelled_count={}", count)
+ logger.info("STOP_CLI: source=messaging_workflow cancelled_count={}", count)
return {"status": "stopped", "cancelled_count": count}
diff --git a/api/runtime.py b/api/runtime.py
index 2090c28f..3bb197a1 100644
--- a/api/runtime.py
+++ b/api/runtime.py
@@ -18,9 +18,9 @@ from providers.registry import ProviderRegistry
if TYPE_CHECKING:
from cli.manager import CLISessionManager
- from messaging.handler import ClaudeMessageHandler
from messaging.platforms.base import MessagingPlatform
from messaging.session import SessionStore
+ from messaging.workflow import MessagingWorkflow
_SHUTDOWN_TIMEOUT_S = 5.0
@@ -89,7 +89,7 @@ class AppRuntime:
settings: Settings
_provider_registry: ProviderRegistry | None = field(default=None, init=False)
messaging_platform: MessagingPlatform | None = None
- message_handler: ClaudeMessageHandler | None = None
+ messaging_workflow: MessagingWorkflow | None = None
cli_manager: CLISessionManager | None = None
@classmethod
@@ -140,9 +140,9 @@ class AppRuntime:
async def shutdown(self) -> None:
verbose = self.settings.log_api_error_tracebacks
- if self.message_handler is not None:
+ if self.messaging_workflow is not None:
try:
- self.message_handler.session_store.flush_pending_save()
+ self.messaging_workflow.session_store.flush_pending_save()
except Exception as e:
if verbose:
logger.warning("Session store flush on shutdown: {}", e)
@@ -201,7 +201,7 @@ class AppRuntime:
)
if self.messaging_platform:
- await self._start_message_handler()
+ await self._start_messaging_workflow()
except ImportError as e:
if self.settings.log_api_error_tracebacks:
@@ -223,10 +223,10 @@ class AppRuntime:
type(e).__name__,
)
- async def _start_message_handler(self) -> None:
+ async def _start_messaging_workflow(self) -> None:
from cli.manager import CLISessionManager
- from messaging.handler import ClaudeMessageHandler
from messaging.session import SessionStore
+ from messaging.workflow import MessagingWorkflow
workspace = (
os.path.abspath(self.settings.allowed_dir)
@@ -261,7 +261,7 @@ class AppRuntime:
)
platform = self.messaging_platform
assert platform is not None
- self.message_handler = ClaudeMessageHandler(
+ self.messaging_workflow = MessagingWorkflow(
platform=platform,
cli_manager=self.cli_manager,
session_store=session_store,
@@ -273,39 +273,39 @@ class AppRuntime:
)
self._restore_tree_state(session_store)
- platform.on_message(self.message_handler.handle_message)
+ platform.on_message(self.messaging_workflow.handle_message)
await platform.start()
- logger.info(f"{platform.name} platform started with message handler")
+ logger.info(f"{platform.name} platform started with messaging workflow")
def _restore_tree_state(self, session_store: SessionStore) -> None:
saved_trees = session_store.get_all_trees()
if not saved_trees:
return
- if self.message_handler is None:
+ if self.messaging_workflow is None:
return
logger.info(f"Restoring {len(saved_trees)} conversation trees...")
- from messaging.trees.queue_manager import TreeQueueManager
+ from messaging.trees import TreeQueueManager
- self.message_handler.replace_tree_queue(
+ self.messaging_workflow.replace_tree_queue(
TreeQueueManager.from_dict(
{
"trees": saved_trees,
"node_to_tree": session_store.get_node_mapping(),
},
- queue_update_callback=self.message_handler.update_queue_positions,
- node_started_callback=self.message_handler.mark_node_processing,
+ queue_update_callback=self.messaging_workflow.update_queue_positions,
+ node_started_callback=self.messaging_workflow.mark_node_processing,
)
)
- if self.message_handler.tree_queue.cleanup_stale_nodes() > 0:
- tree_data = self.message_handler.tree_queue.to_dict()
+ if self.messaging_workflow.tree_queue.cleanup_stale_nodes() > 0:
+ tree_data = self.messaging_workflow.tree_queue.to_dict()
session_store.sync_from_tree_data(
tree_data["trees"], tree_data["node_to_tree"]
)
def _publish_state(self) -> None:
self.app.state.messaging_platform = self.messaging_platform
- self.app.state.message_handler = self.message_handler
+ self.app.state.messaging_workflow = self.messaging_workflow
self.app.state.cli_manager = self.cli_manager
async def _shutdown_limiter(self) -> None:
diff --git a/messaging/__init__.py b/messaging/__init__.py
index 4aaa736e..919a4996 100644
--- a/messaging/__init__.py
+++ b/messaging/__init__.py
@@ -1,21 +1,20 @@
"""Platform-agnostic messaging layer."""
from .event_parser import parse_cli_event
-from .handler import ClaudeMessageHandler
from .models import IncomingMessage
from .platforms.base import CLISession, MessagingPlatform, SessionManagerInterface
from .session import SessionStore
-from .trees.data import MessageNode, MessageState, MessageTree
-from .trees.queue_manager import TreeQueueManager
+from .trees import MessageNode, MessageState, MessageTree, TreeQueueManager
+from .workflow import MessagingWorkflow
__all__ = [
"CLISession",
- "ClaudeMessageHandler",
"IncomingMessage",
"MessageNode",
"MessageState",
"MessageTree",
"MessagingPlatform",
+ "MessagingWorkflow",
"SessionManagerInterface",
"SessionStore",
"TreeQueueManager",
diff --git a/messaging/command_context.py b/messaging/command_context.py
new file mode 100644
index 00000000..65d37bcd
--- /dev/null
+++ b/messaging/command_context.py
@@ -0,0 +1,66 @@
+"""Typed dependency surface for messaging slash commands."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from .platforms.base import MessagingPlatform, SessionManagerInterface
+from .session import SessionStore
+from .transcript import RenderCtx
+from .trees import MessageNode, MessageTree, TreeQueueManager
+
+
+class MessagingCommandContext(Protocol):
+ """Operations commands need from the messaging workflow."""
+
+ platform: MessagingPlatform
+ cli_manager: SessionManagerInterface
+ session_store: SessionStore
+
+ @property
+ def tree_queue(self) -> TreeQueueManager: ...
+
+ def format_status(self, emoji: str, label: str, suffix: str | None = None) -> str:
+ """Format a platform-specific status line."""
+ ...
+
+ def get_render_ctx(self) -> RenderCtx:
+ """Return the render context for command output."""
+ ...
+
+ def replace_tree_queue(self, tree_queue: TreeQueueManager) -> None:
+ """Replace the active tree queue after global clear/restore."""
+ ...
+
+ async def update_queue_positions(self, tree: MessageTree) -> None:
+ """Refresh queued status messages."""
+ ...
+
+ async def mark_node_processing(self, tree: MessageTree, node_id: str) -> None:
+ """Mark a dequeued node as processing."""
+ ...
+
+ async def stop_all_tasks(self) -> int:
+ """Stop every pending or active messaging task."""
+ ...
+
+ async def stop_task(self, node_id: str) -> int:
+ """Stop one pending or active node."""
+ ...
+
+ def record_outgoing_message(
+ self,
+ platform: str,
+ chat_id: str,
+ msg_id: str | None,
+ kind: str,
+ ) -> None:
+ """Persist an outgoing platform message ID."""
+ ...
+
+ def update_cancelled_nodes_ui(self, nodes: list[MessageNode]) -> None:
+ """Render cancellation status and persist affected trees."""
+ ...
+
+
+__all__ = ["MessagingCommandContext"]
diff --git a/messaging/command_dispatcher.py b/messaging/command_dispatcher.py
index ee6435ef..0944c87f 100644
--- a/messaging/command_dispatcher.py
+++ b/messaging/command_dispatcher.py
@@ -2,8 +2,7 @@
from __future__ import annotations
-from typing import Any
-
+from .command_context import MessagingCommandContext
from .commands import handle_clear_command, handle_stats_command, handle_stop_command
from .models import IncomingMessage
@@ -21,7 +20,7 @@ def message_kind_for_command(command_base: str) -> str:
async def dispatch_command(
- handler: Any,
+ context: MessagingCommandContext,
incoming: IncomingMessage,
command_base: str,
) -> bool:
@@ -34,5 +33,5 @@ async def dispatch_command(
command = commands.get(command_base)
if command is None:
return False
- await command(handler, incoming)
+ await command(context, incoming)
return True
diff --git a/messaging/commands.py b/messaging/commands.py
index e3f71d6d..8d8e140e 100644
--- a/messaging/commands.py
+++ b/messaging/commands.py
@@ -1,7 +1,6 @@
"""Command handlers for messaging platform commands (/stop, /stats, /clear).
-Extracted from ClaudeMessageHandler to keep handler.py focused on
-core message processing logic.
+Commands depend on MessagingCommandContext instead of the concrete workflow.
"""
from __future__ import annotations
@@ -10,13 +9,14 @@ from typing import TYPE_CHECKING
from loguru import logger
+from .command_context import MessagingCommandContext
+
if TYPE_CHECKING:
- from messaging.handler import ClaudeMessageHandler
from messaging.models import IncomingMessage
async def handle_stop_command(
- handler: ClaudeMessageHandler, incoming: IncomingMessage
+ handler: MessagingCommandContext, incoming: IncomingMessage
) -> None:
"""Handle /stop command from messaging platform."""
# Reply-scoped stop: reply "/stop" to stop only that task.
@@ -68,7 +68,7 @@ async def handle_stop_command(
async def handle_stats_command(
- handler: ClaudeMessageHandler, incoming: IncomingMessage
+ handler: MessagingCommandContext, incoming: IncomingMessage
) -> None:
"""Handle /stats command."""
stats = handler.cli_manager.get_stats()
@@ -91,7 +91,7 @@ async def handle_stats_command(
async def _delete_message_ids(
- handler: ClaudeMessageHandler, chat_id: str, msg_ids: set[str]
+ handler: MessagingCommandContext, chat_id: str, msg_ids: set[str]
) -> None:
"""Best-effort delete messages by ID. Sorts numeric IDs descending."""
if not msg_ids:
@@ -126,7 +126,7 @@ async def _delete_message_ids(
async def _handle_clear_branch(
- handler: ClaudeMessageHandler,
+ handler: MessagingCommandContext,
incoming: IncomingMessage,
branch_root_id: str,
) -> None:
@@ -178,7 +178,7 @@ async def _handle_clear_branch(
async def handle_clear_command(
- handler: ClaudeMessageHandler, incoming: IncomingMessage
+ handler: MessagingCommandContext, incoming: IncomingMessage
) -> None:
"""
Handle /clear command.
diff --git a/messaging/handler.py b/messaging/handler.py
deleted file mode 100644
index 21e8997a..00000000
--- a/messaging/handler.py
+++ /dev/null
@@ -1,676 +0,0 @@
-"""
-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 asyncio
-
-from loguru import logger
-
-from core.anthropic import format_user_error_preview, get_user_facing_error_message
-from core.trace import trace_event
-
-from .cli_event_constants import STATUS_MESSAGE_PREFIXES
-from .command_dispatcher import (
- dispatch_command,
- message_kind_for_command,
- parse_command_base,
-)
-from .event_parser import parse_cli_event
-from .models import IncomingMessage
-from .node_event_pipeline import handle_session_info_event, process_parsed_cli_event
-from .platforms.base import MessagingPlatform, SessionManagerInterface
-from .rendering.profiles import build_rendering_profile
-from .safe_diagnostics import format_exception_for_log
-from .session import SessionStore
-from .transcript import RenderCtx, TranscriptBuffer
-from .trees.queue_manager import (
- MessageNode,
- MessageState,
- MessageTree,
- TreeQueueManager,
-)
-from .ui_updates import ThrottledTranscriptEditor
-
-
-class ClaudeMessageHandler:
- """
- Platform-agnostic handler for Claude interactions.
-
- 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__(
- self,
- platform: MessagingPlatform,
- cli_manager: SessionManagerInterface,
- session_store: SessionStore,
- *,
- debug_platform_edits: bool = False,
- debug_subagent_stack: bool = False,
- log_raw_messaging_content: bool = False,
- log_raw_cli_diagnostics: bool = False,
- log_messaging_error_details: bool = False,
- ):
- self.platform = platform
- self.cli_manager = cli_manager
- self.session_store = session_store
- self._debug_platform_edits = debug_platform_edits
- self._debug_subagent_stack = debug_subagent_stack
- self._log_raw_messaging_content = log_raw_messaging_content
- self._log_raw_cli_diagnostics = log_raw_cli_diagnostics
- self._log_messaging_error_details = log_messaging_error_details
- self._tree_queue = TreeQueueManager(
- queue_update_callback=self.update_queue_positions,
- node_started_callback=self.mark_node_processing,
- )
- self._rendering_profile = build_rendering_profile(platform.name)
-
- def format_status(self, emoji: str, label: str, suffix: str | None = None) -> str:
- return self._rendering_profile.format_status(emoji, label, suffix)
-
- def _parse_mode(self) -> str | None:
- return self._rendering_profile.parse_mode
-
- def get_render_ctx(self) -> RenderCtx:
- return self._rendering_profile.render_ctx
-
- def _get_limit_chars(self) -> int:
- return self._rendering_profile.limit_chars
-
- @property
- def tree_queue(self) -> TreeQueueManager:
- """Accessor for the current tree queue manager."""
- return self._tree_queue
-
- def replace_tree_queue(self, tree_queue: TreeQueueManager) -> None:
- """Replace tree queue manager via explicit API."""
- self._tree_queue = tree_queue
- self._tree_queue.set_queue_update_callback(self.update_queue_positions)
- self._tree_queue.set_node_started_callback(self.mark_node_processing)
-
- async def handle_message(self, incoming: IncomingMessage) -> None:
- """
- Main entry point for handling an incoming message.
-
- Determines if this is a new conversation or reply,
- creates/extends the message tree, and queues for processing.
- """
- platform_name = getattr(self.platform, "name", "messaging")
- trace_event(
- stage="ingress",
- event="turn.received",
- source=platform_name,
- chat_id=incoming.chat_id,
- platform_message_id=incoming.message_id,
- reply_to_message_id=incoming.reply_to_message_id,
- thread_id=getattr(incoming, "message_thread_id", None),
- message_text=incoming.text or "",
- )
-
- with logger.contextualize(
- chat_id=incoming.chat_id, node_id=incoming.message_id
- ):
- await self._handle_message_impl(incoming)
-
- async def _handle_message_impl(self, incoming: IncomingMessage) -> None:
- """Implementation of handle_message with context bound."""
- cmd_base = parse_command_base(incoming.text)
-
- # Record incoming message ID for best-effort UI clearing (/clear), even if
- # we later ignore this message (status/command/etc).
- try:
- if incoming.message_id is not None:
- self.session_store.record_message_id(
- incoming.platform,
- incoming.chat_id,
- str(incoming.message_id),
- direction="in",
- kind=message_kind_for_command(cmd_base),
- )
- except Exception as e:
- logger.debug(
- "Failed to record incoming message_id: {}",
- format_exception_for_log(
- e, log_full_message=self._log_messaging_error_details
- ),
- )
-
- if await dispatch_command(self, incoming, cmd_base):
- return
-
- # Filter out status messages (our own messages)
- text = incoming.text or ""
- if any(text.startswith(p) for p in STATUS_MESSAGE_PREFIXES):
- return
-
- # Check if this is a reply to an existing node in a tree
- parent_node_id = None
- tree = None
-
- if incoming.is_reply() and incoming.reply_to_message_id:
- # Look up if the replied-to message is in any tree (could be a node or status message)
- reply_id = incoming.reply_to_message_id
- tree = self.tree_queue.get_tree_for_node(reply_id)
- if tree:
- # Resolve to actual node ID (handles status message replies)
- parent_node_id = self.tree_queue.resolve_parent_node_id(reply_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
-
- # Use pre-sent status (e.g. voice note) or send new
- status_text = self._get_initial_status(tree, parent_node_id)
- if incoming.status_message_id:
- status_msg_id = incoming.status_message_id
- await self.platform.queue_edit_message(
- incoming.chat_id,
- status_msg_id,
- status_text,
- parse_mode=self._parse_mode(),
- fire_and_forget=False,
- )
- else:
- status_msg_id = await self.platform.queue_send_message(
- incoming.chat_id,
- status_text,
- reply_to=incoming.message_id,
- fire_and_forget=False,
- message_thread_id=incoming.message_thread_id,
- )
- self.record_outgoing_message(
- incoming.platform, incoming.chat_id, status_msg_id, "status"
- )
-
- # Create or extend tree
- if parent_node_id and tree and status_msg_id:
- # 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,
- )
- # 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)
- elif status_msg_id:
- # New conversation - create new tree
- tree = await self.tree_queue.create_tree(
- node_id=node_id,
- incoming=incoming,
- status_message_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
- if tree:
- self.session_store.save_tree(tree.root_id, tree.to_dict())
-
- # Enqueue for processing
- was_queued = await self.tree_queue.enqueue(
- node_id=node_id,
- processor=self._process_node,
- )
-
- if was_queued and status_msg_id:
- queue_size = self.tree_queue.get_queue_size(node_id)
- trace_event(
- stage="routing",
- event="turn.queued",
- source=getattr(self.platform, "name", "messaging"),
- chat_id=incoming.chat_id,
- platform_message_id=node_id,
- status_message_id=status_msg_id,
- queue_size=queue_size,
- )
- await self.platform.queue_edit_message(
- incoming.chat_id,
- status_msg_id,
- self.format_status(
- "📋", "Queued", f"(position {queue_size}) - waiting..."
- ),
- parse_mode=self._parse_mode(),
- )
-
- async def update_queue_positions(self, tree: MessageTree) -> None:
- """Refresh queued status messages after a dequeue."""
- try:
- queued_ids = await tree.get_queue_snapshot()
- except Exception as e:
- logger.warning(
- "Failed to read queue snapshot: {}",
- format_exception_for_log(
- e, log_full_message=self._log_messaging_error_details
- ),
- )
- return
-
- if not queued_ids:
- return
-
- position = 0
- for node_id in queued_ids:
- node = tree.get_node(node_id)
- if not node or node.state != MessageState.PENDING:
- continue
- position += 1
- self.platform.fire_and_forget(
- self.platform.queue_edit_message(
- node.incoming.chat_id,
- node.status_message_id,
- self.format_status(
- "📋", "Queued", f"(position {position}) - waiting..."
- ),
- parse_mode=self._parse_mode(),
- )
- )
-
- async def mark_node_processing(self, tree: MessageTree, node_id: str) -> None:
- """Update the dequeued node's status to processing immediately."""
- node = tree.get_node(node_id)
- if not node or node.state == MessageState.ERROR:
- return
- self.platform.fire_and_forget(
- self.platform.queue_edit_message(
- node.incoming.chat_id,
- node.status_message_id,
- self.format_status("🔄", "Processing..."),
- parse_mode=self._parse_mode(),
- )
- )
-
- def _create_transcript_and_render_ctx(
- self,
- ) -> tuple[TranscriptBuffer, RenderCtx]:
- """Create transcript buffer and render context for node processing."""
- transcript = TranscriptBuffer(
- show_tool_results=False,
- debug_subagent_stack=self._debug_subagent_stack,
- )
- return transcript, self.get_render_ctx()
-
- async def _process_node(
- self,
- node_id: str,
- node: MessageNode,
- ) -> None:
- """Core task processor - handles a single Claude CLI interaction."""
- incoming = node.incoming
- status_msg_id = node.status_message_id
- chat_id = incoming.chat_id
-
- with logger.contextualize(node_id=node_id, chat_id=chat_id):
- await self._process_node_impl(node_id, node, chat_id, status_msg_id)
-
- async def _process_node_impl(
- self,
- node_id: str,
- node: MessageNode,
- chat_id: str,
- status_msg_id: str,
- ) -> None:
- """Internal implementation of _process_node with context bound."""
- incoming = node.incoming
-
- tree = self.tree_queue.get_tree_for_node(node_id)
- if tree:
- await tree.update_state(node_id, MessageState.IN_PROGRESS)
-
- transcript, render_ctx = self._create_transcript_and_render_ctx()
-
- had_transcript_events = False
- captured_session_id = None
- temp_session_id = None
- last_status: str | None = None
-
- parent_session_id = None
- platform_nm = getattr(self.platform, "name", "messaging")
- if tree and node.parent_id:
- parent_session_id = tree.get_parent_session_id(node_id)
- if parent_session_id:
- trace_event(
- stage="claude_cli",
- event="claude_cli.fork.from_parent_session",
- source=platform_nm,
- chat_id=chat_id,
- node_id=node_id,
- parent_session_id=parent_session_id,
- )
-
- editor = ThrottledTranscriptEditor(
- platform=self.platform,
- parse_mode=self._parse_mode(),
- get_limit_chars=self._get_limit_chars,
- transcript=transcript,
- render_ctx=render_ctx,
- node_id=node_id,
- chat_id=chat_id,
- status_msg_id=status_msg_id,
- debug_platform_edits=self._debug_platform_edits,
- log_messaging_error_details=self._log_messaging_error_details,
- )
-
- async def update_ui(status: str | None = None, force: bool = False) -> None:
- await editor.update(status, force=force)
-
- try:
- try:
- (
- cli_session,
- session_or_temp_id,
- is_new,
- ) = await self.cli_manager.get_or_create_session(
- session_id=parent_session_id
- )
- if is_new:
- temp_session_id = session_or_temp_id
- else:
- captured_session_id = session_or_temp_id
-
- sess_evt = (
- "claude_cli.session.pending_created"
- if is_new
- else "claude_cli.session.reused"
- )
- trace_event(
- stage="claude_cli",
- event=sess_evt,
- source=platform_nm,
- chat_id=chat_id,
- node_id=node_id,
- status_message_id=status_msg_id,
- session_handle=str(session_or_temp_id),
- parent_resume_session_id=parent_session_id,
- fork_requested=bool(parent_session_id),
- )
- trace_event(
- stage="claude_cli",
- event="claude_cli.request.sent",
- source=platform_nm,
- chat_id=chat_id,
- node_id=node_id,
- prompt=incoming.text,
- fork_session_arg=bool(parent_session_id),
- resume_session_arg=parent_session_id,
- )
- except RuntimeError as e:
- error_message = get_user_facing_error_message(e)
- transcript.apply({"type": "error", "message": error_message})
- await update_ui(
- self.format_status("⏳", "Session limit reached"),
- force=True,
- )
- if tree:
- await tree.update_state(
- node_id,
- MessageState.ERROR,
- error_message=error_message,
- )
- trace_event(
- stage="claude_cli",
- event="claude_cli.session.limit_reached",
- source=platform_nm,
- chat_id=chat_id,
- node_id=node_id,
- )
- return
-
- async for event_data in cli_session.start_task(
- incoming.text,
- session_id=parent_session_id,
- fork_session=bool(parent_session_id),
- ):
- if not isinstance(event_data, dict):
- logger.warning(
- f"HANDLER: Non-dict event received: {type(event_data)}"
- )
- continue
-
- (
- captured_session_id,
- temp_session_id,
- ) = await handle_session_info_event(
- event_data,
- tree,
- node_id,
- captured_session_id,
- temp_session_id,
- cli_manager=self.cli_manager,
- session_store=self.session_store,
- )
- if event_data.get("type") == "session_info":
- continue
-
- parsed_list = parse_cli_event(
- event_data, log_raw_cli=self._log_raw_cli_diagnostics
- )
-
- for parsed in parsed_list:
- (
- last_status,
- had_transcript_events,
- ) = await process_parsed_cli_event(
- parsed,
- transcript,
- update_ui,
- last_status,
- had_transcript_events,
- tree,
- node_id,
- captured_session_id,
- session_store=self.session_store,
- format_status=self.format_status,
- propagate_error_to_children=self._propagate_error_to_children,
- log_messaging_error_details=self._log_messaging_error_details,
- )
-
- except asyncio.CancelledError:
- trace_event(
- stage="claude_cli",
- event="turn.processor.cancelled",
- source=platform_nm,
- chat_id=chat_id,
- node_id=node_id,
- )
- logger.warning(f"HANDLER: Task cancelled for node {node_id}")
- cancel_reason = None
- if isinstance(node.context, dict):
- cancel_reason = node.context.get("cancel_reason")
-
- if cancel_reason == "stop":
- await update_ui(self.format_status("⏹", "Stopped."), force=True)
- else:
- transcript.apply({"type": "error", "message": "Task was cancelled"})
- await update_ui(self.format_status("❌", "Cancelled"), force=True)
-
- # Do not propagate cancellation to children; a reply-scoped "/stop"
- # should only stop the targeted task.
- if tree:
- await tree.update_state(
- node_id, MessageState.ERROR, error_message="Cancelled by user"
- )
- except Exception as e:
- trace_event(
- stage="claude_cli",
- event="turn.processor.exception",
- source=platform_nm,
- chat_id=chat_id,
- node_id=node_id,
- exc_type=type(e).__name__,
- )
- logger.error(
- "HANDLER: Task failed with exception: {}",
- format_exception_for_log(
- e, log_full_message=self._log_messaging_error_details
- ),
- )
- error_msg = format_user_error_preview(e)
- transcript.apply({"type": "error", "message": error_msg})
- await update_ui(self.format_status("💥", "Task Failed"), force=True)
- if tree:
- await self._propagate_error_to_children(
- node_id, error_msg, "Parent task failed"
- )
- finally:
- trace_event(
- stage="routing",
- event="turn.processor.finished",
- source=platform_nm,
- chat_id=chat_id,
- node_id=node_id,
- claude_session_id=captured_session_id or temp_session_id,
- )
- # Free the session-manager slot. Session IDs are persisted in the tree and
- # can be resumed later by ID; we don't need to keep a CLISession instance
- # around after this node completes.
- try:
- if captured_session_id:
- await self.cli_manager.remove_session(captured_session_id)
- elif temp_session_id:
- await self.cli_manager.remove_session(temp_session_id)
- except Exception as e:
- logger.debug(
- "Failed to remove session for node {}: {}",
- node_id,
- format_exception_for_log(
- e, log_full_message=self._log_messaging_error_details
- ),
- )
-
- async def _propagate_error_to_children(
- self,
- node_id: str,
- error_msg: str,
- child_status_text: str,
- ) -> None:
- """Mark node as error and propagate to pending children with UI updates."""
- affected = await self.tree_queue.mark_node_error(
- node_id, error_msg, propagate_to_children=True
- )
- # Update status messages for all affected children (skip first = current node)
- for child in affected[1:]:
- self.platform.fire_and_forget(
- self.platform.queue_edit_message(
- child.incoming.chat_id,
- child.status_message_id,
- self.format_status("❌", "Cancelled:", child_status_text),
- parse_mode=self._parse_mode(),
- )
- )
-
- def _get_initial_status(
- self,
- tree: object | None,
- parent_node_id: str | None,
- ) -> str:
- """Get initial status message text."""
- if tree and parent_node_id:
- # 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 self.format_status(
- "📋", "Queued", f"(position {queue_size}) - waiting..."
- )
- return self.format_status("🔄", "Continuing conversation...")
-
- # New conversation
- return self.format_status("⏳", "Launching new Claude CLI instance...")
-
- async def stop_all_tasks(self) -> int:
- """
- Stop all pending and in-progress tasks.
-
- Order of operations:
- 1. Cancel tree queue tasks (uses internal locking)
- 2. Stop CLI sessions
- 3. Update UI for all affected nodes
- """
- # 1. Cancel tree queue tasks using the public async method
- logger.info("Cancelling tree queue tasks...")
- cancelled_nodes = await self.tree_queue.cancel_all()
- logger.info(f"Cancelled {len(cancelled_nodes)} nodes")
-
- # 2. Stop CLI sessions - this kills subprocesses and ensures everything is dead
- logger.info("Stopping all CLI sessions...")
- await self.cli_manager.stop_all()
-
- # 3. Update UI and persist state for all cancelled nodes
- self.update_cancelled_nodes_ui(cancelled_nodes)
-
- return len(cancelled_nodes)
-
- async def stop_task(self, node_id: str) -> int:
- """
- Stop a single queued or in-progress task node.
-
- Used when the user replies "/stop" to a specific status/user message.
- """
- tree = self.tree_queue.get_tree_for_node(node_id)
- if tree:
- node = tree.get_node(node_id)
- if node and node.state not in (MessageState.COMPLETED, MessageState.ERROR):
- # Used by _process_node cancellation path to render "Stopped."
- node.set_context({"cancel_reason": "stop"})
-
- cancelled_nodes = await self.tree_queue.cancel_node(node_id)
- self.update_cancelled_nodes_ui(cancelled_nodes)
- return len(cancelled_nodes)
-
- def record_outgoing_message(
- self,
- platform: str,
- chat_id: str,
- msg_id: str | None,
- kind: str,
- ) -> None:
- """Record outgoing message ID for /clear. Best-effort, never raises."""
- if not msg_id:
- return
- try:
- self.session_store.record_message_id(
- platform, chat_id, str(msg_id), direction="out", kind=kind
- )
- except Exception as e:
- logger.debug(
- "Failed to record message_id: {}",
- format_exception_for_log(
- e, log_full_message=self._log_messaging_error_details
- ),
- )
-
- def update_cancelled_nodes_ui(self, nodes: list[MessageNode]) -> None:
- """Update status messages and persist tree state for cancelled nodes."""
- trees_to_save: dict[str, MessageTree] = {}
- for node in nodes:
- self.platform.fire_and_forget(
- self.platform.queue_edit_message(
- node.incoming.chat_id,
- node.status_message_id,
- self.format_status("⏹", "Stopped."),
- parse_mode=self._parse_mode(),
- )
- )
- tree = self.tree_queue.get_tree_for_node(node.node_id)
- if tree:
- trees_to_save[tree.root_id] = tree
- for root_id, tree in trees_to_save.items():
- self.session_store.save_tree(root_id, tree.to_dict())
diff --git a/messaging/node_event_pipeline.py b/messaging/node_event_pipeline.py
index 8481643a..0e6680c6 100644
--- a/messaging/node_event_pipeline.py
+++ b/messaging/node_event_pipeline.py
@@ -14,7 +14,7 @@ from .platforms.base import SessionManagerInterface
from .safe_diagnostics import text_len_hint
from .session import SessionStore
from .transcript import TranscriptBuffer
-from .trees.queue_manager import MessageState, MessageTree
+from .trees import MessageState, MessageTree
async def handle_session_info_event(
diff --git a/messaging/node_runner.py b/messaging/node_runner.py
new file mode 100644
index 00000000..d0b06d6c
--- /dev/null
+++ b/messaging/node_runner.py
@@ -0,0 +1,342 @@
+"""Run queued messaging nodes through a managed CLI session."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+
+from loguru import logger
+
+from core.anthropic import format_user_error_preview, get_user_facing_error_message
+from core.trace import trace_event
+
+from .event_parser import parse_cli_event
+from .node_event_pipeline import handle_session_info_event, process_parsed_cli_event
+from .platforms.base import MessagingPlatform, SessionManagerInterface
+from .safe_diagnostics import format_exception_for_log
+from .session import SessionStore
+from .transcript import RenderCtx, TranscriptBuffer
+from .trees import MessageNode, MessageState, MessageTree, TreeQueueManager
+from .ui_updates import ThrottledTranscriptEditor
+
+
+class MessagingNodeRunner:
+ """Owns the lifecycle of one queued messaging node."""
+
+ def __init__(
+ self,
+ *,
+ platform: MessagingPlatform,
+ cli_manager: SessionManagerInterface,
+ session_store: SessionStore,
+ get_tree_queue: Callable[[], TreeQueueManager],
+ format_status: Callable[[str, str, str | None], str],
+ get_parse_mode: Callable[[], str | None],
+ get_render_ctx: Callable[[], RenderCtx],
+ get_limit_chars: Callable[[], int],
+ debug_platform_edits: bool = False,
+ debug_subagent_stack: bool = False,
+ log_raw_cli_diagnostics: bool = False,
+ log_messaging_error_details: bool = False,
+ ) -> None:
+ self.platform = platform
+ self.cli_manager = cli_manager
+ self.session_store = session_store
+ self._get_tree_queue = get_tree_queue
+ self._format_status = format_status
+ self._get_parse_mode = get_parse_mode
+ self._get_render_ctx = get_render_ctx
+ self._get_limit_chars = get_limit_chars
+ self._debug_platform_edits = debug_platform_edits
+ self._debug_subagent_stack = debug_subagent_stack
+ self._log_raw_cli_diagnostics = log_raw_cli_diagnostics
+ self._log_messaging_error_details = log_messaging_error_details
+
+ def _create_transcript_and_render_ctx(
+ self,
+ ) -> tuple[TranscriptBuffer, RenderCtx]:
+ """Create transcript buffer and render context for node processing."""
+ transcript = TranscriptBuffer(
+ show_tool_results=False,
+ debug_subagent_stack=self._debug_subagent_stack,
+ )
+ return transcript, self._get_render_ctx()
+
+ def _save_tree(self, tree: MessageTree | None) -> None:
+ """Persist tree state after runner-owned mutations."""
+ if tree:
+ self.session_store.save_tree(tree.root_id, tree.to_dict())
+
+ async def process_node(
+ self,
+ node_id: str,
+ node: MessageNode,
+ ) -> None:
+ """Core task processor for a single CLI interaction."""
+ incoming = node.incoming
+ status_msg_id = node.status_message_id
+ chat_id = incoming.chat_id
+
+ with logger.contextualize(node_id=node_id, chat_id=chat_id):
+ await self._process_node_impl(node_id, node, chat_id, status_msg_id)
+
+ async def _process_node_impl(
+ self,
+ node_id: str,
+ node: MessageNode,
+ chat_id: str,
+ status_msg_id: str,
+ ) -> None:
+ """Internal implementation of process_node with context bound."""
+ incoming = node.incoming
+
+ tree_queue = self._get_tree_queue()
+ tree = tree_queue.get_tree_for_node(node_id)
+ if tree:
+ await tree.update_state(node_id, MessageState.IN_PROGRESS)
+
+ transcript, render_ctx = self._create_transcript_and_render_ctx()
+
+ had_transcript_events = False
+ captured_session_id = None
+ temp_session_id = None
+ last_status: str | None = None
+
+ parent_session_id = None
+ platform_nm = getattr(self.platform, "name", "messaging")
+ if tree and node.parent_id:
+ parent_session_id = tree.get_parent_session_id(node_id)
+ if parent_session_id:
+ trace_event(
+ stage="claude_cli",
+ event="claude_cli.fork.from_parent_session",
+ source=platform_nm,
+ chat_id=chat_id,
+ node_id=node_id,
+ parent_session_id=parent_session_id,
+ )
+
+ editor = ThrottledTranscriptEditor(
+ platform=self.platform,
+ parse_mode=self._get_parse_mode(),
+ get_limit_chars=self._get_limit_chars,
+ transcript=transcript,
+ render_ctx=render_ctx,
+ node_id=node_id,
+ chat_id=chat_id,
+ status_msg_id=status_msg_id,
+ debug_platform_edits=self._debug_platform_edits,
+ log_messaging_error_details=self._log_messaging_error_details,
+ )
+
+ async def update_ui(status: str | None = None, force: bool = False) -> None:
+ await editor.update(status, force=force)
+
+ try:
+ try:
+ (
+ cli_session,
+ session_or_temp_id,
+ is_new,
+ ) = await self.cli_manager.get_or_create_session(
+ session_id=parent_session_id
+ )
+ if is_new:
+ temp_session_id = session_or_temp_id
+ else:
+ captured_session_id = session_or_temp_id
+
+ sess_evt = (
+ "claude_cli.session.pending_created"
+ if is_new
+ else "claude_cli.session.reused"
+ )
+ trace_event(
+ stage="claude_cli",
+ event=sess_evt,
+ source=platform_nm,
+ chat_id=chat_id,
+ node_id=node_id,
+ status_message_id=status_msg_id,
+ session_handle=str(session_or_temp_id),
+ parent_resume_session_id=parent_session_id,
+ fork_requested=bool(parent_session_id),
+ )
+ trace_event(
+ stage="claude_cli",
+ event="claude_cli.request.sent",
+ source=platform_nm,
+ chat_id=chat_id,
+ node_id=node_id,
+ prompt=incoming.text,
+ fork_session_arg=bool(parent_session_id),
+ resume_session_arg=parent_session_id,
+ )
+ except RuntimeError as e:
+ error_message = get_user_facing_error_message(e)
+ transcript.apply({"type": "error", "message": error_message})
+ await update_ui(
+ self._format_status("⏳", "Session limit reached", None),
+ force=True,
+ )
+ if tree:
+ await tree.update_state(
+ node_id,
+ MessageState.ERROR,
+ error_message=error_message,
+ )
+ self._save_tree(tree)
+ trace_event(
+ stage="claude_cli",
+ event="claude_cli.session.limit_reached",
+ source=platform_nm,
+ chat_id=chat_id,
+ node_id=node_id,
+ )
+ return
+
+ async for event_data in cli_session.start_task(
+ incoming.text,
+ session_id=parent_session_id,
+ fork_session=bool(parent_session_id),
+ ):
+ if not isinstance(event_data, dict):
+ logger.warning(
+ f"HANDLER: Non-dict event received: {type(event_data)}"
+ )
+ continue
+
+ (
+ captured_session_id,
+ temp_session_id,
+ ) = await handle_session_info_event(
+ event_data,
+ tree,
+ node_id,
+ captured_session_id,
+ temp_session_id,
+ cli_manager=self.cli_manager,
+ session_store=self.session_store,
+ )
+ if event_data.get("type") == "session_info":
+ continue
+
+ parsed_list = parse_cli_event(
+ event_data, log_raw_cli=self._log_raw_cli_diagnostics
+ )
+
+ for parsed in parsed_list:
+ (
+ last_status,
+ had_transcript_events,
+ ) = await process_parsed_cli_event(
+ parsed,
+ transcript,
+ update_ui,
+ last_status,
+ had_transcript_events,
+ tree,
+ node_id,
+ captured_session_id,
+ session_store=self.session_store,
+ format_status=self._format_status,
+ propagate_error_to_children=self.propagate_error_to_children,
+ log_messaging_error_details=self._log_messaging_error_details,
+ )
+
+ except asyncio.CancelledError:
+ trace_event(
+ stage="claude_cli",
+ event="turn.processor.cancelled",
+ source=platform_nm,
+ chat_id=chat_id,
+ node_id=node_id,
+ )
+ logger.warning(f"HANDLER: Task cancelled for node {node_id}")
+ cancel_reason = None
+ if isinstance(node.context, dict):
+ cancel_reason = node.context.get("cancel_reason")
+
+ if cancel_reason == "stop":
+ await update_ui(self._format_status("⏹", "Stopped.", None), force=True)
+ else:
+ transcript.apply({"type": "error", "message": "Task was cancelled"})
+ await update_ui(
+ self._format_status("❌", "Cancelled", None), force=True
+ )
+
+ if tree:
+ await tree.update_state(
+ node_id, MessageState.ERROR, error_message="Cancelled by user"
+ )
+ self._save_tree(tree)
+ except Exception as e:
+ trace_event(
+ stage="claude_cli",
+ event="turn.processor.exception",
+ source=platform_nm,
+ chat_id=chat_id,
+ node_id=node_id,
+ exc_type=type(e).__name__,
+ )
+ logger.error(
+ "HANDLER: Task failed with exception: {}",
+ format_exception_for_log(
+ e, log_full_message=self._log_messaging_error_details
+ ),
+ )
+ error_msg = format_user_error_preview(e)
+ transcript.apply({"type": "error", "message": error_msg})
+ await update_ui(self._format_status("💥", "Task Failed", None), force=True)
+ if tree:
+ await self.propagate_error_to_children(
+ node_id, error_msg, "Parent task failed"
+ )
+ finally:
+ trace_event(
+ stage="routing",
+ event="turn.processor.finished",
+ source=platform_nm,
+ chat_id=chat_id,
+ node_id=node_id,
+ claude_session_id=captured_session_id or temp_session_id,
+ )
+ try:
+ if captured_session_id:
+ await self.cli_manager.remove_session(captured_session_id)
+ elif temp_session_id:
+ await self.cli_manager.remove_session(temp_session_id)
+ except Exception as e:
+ logger.debug(
+ "Failed to remove session for node {}: {}",
+ node_id,
+ format_exception_for_log(
+ e, log_full_message=self._log_messaging_error_details
+ ),
+ )
+
+ async def propagate_error_to_children(
+ self,
+ node_id: str,
+ error_msg: str,
+ child_status_text: str,
+ ) -> None:
+ """Mark node as error and propagate to pending children with UI updates."""
+ tree_queue = self._get_tree_queue()
+ affected = await tree_queue.mark_node_error(
+ node_id, error_msg, propagate_to_children=True
+ )
+ if affected:
+ self._save_tree(tree_queue.get_tree_for_node(node_id))
+ for child in affected[1:]:
+ self.platform.fire_and_forget(
+ self.platform.queue_edit_message(
+ child.incoming.chat_id,
+ child.status_message_id,
+ self._format_status("❌", "Cancelled:", child_status_text),
+ parse_mode=self._get_parse_mode(),
+ )
+ )
+
+
+__all__ = ["MessagingNodeRunner"]
diff --git a/messaging/session.py b/messaging/session.py
index bbb0cdc1..89297726 100644
--- a/messaging/session.py
+++ b/messaging/session.py
@@ -240,6 +240,36 @@ class SessionStore:
# ==================== Tree Methods ====================
+ @staticmethod
+ def _tree_lookup_ids(tree_data: dict) -> set[str]:
+ """Return lookup IDs represented by serialized tree nodes."""
+ lookup_ids: set[str] = set()
+ nodes = tree_data.get("nodes", {})
+ if not isinstance(nodes, dict):
+ return lookup_ids
+
+ for node_key, node_data in nodes.items():
+ lookup_ids.add(str(node_key))
+ if not isinstance(node_data, dict):
+ continue
+ node_id = node_data.get("node_id")
+ if node_id is not None:
+ lookup_ids.add(str(node_id))
+ status_message_id = node_data.get("status_message_id")
+ if status_message_id is not None:
+ lookup_ids.add(str(status_message_id))
+ return lookup_ids
+
+ def _remove_tree_lookup_ids_unlocked(self, root_id: str) -> None:
+ """Remove all lookup IDs currently pointing at a root. Caller holds lock."""
+ stale_lookup_ids = [
+ lookup_id
+ for lookup_id, mapped_root_id in self._node_to_tree.items()
+ if mapped_root_id == root_id
+ ]
+ for lookup_id in stale_lookup_ids:
+ self._node_to_tree.pop(lookup_id, None)
+
def save_tree(self, root_id: str, tree_data: dict) -> None:
"""
Save a message tree.
@@ -251,9 +281,9 @@ class SessionStore:
with self._lock:
self._trees[root_id] = tree_data
- # Update node-to-tree mapping
- for node_id in tree_data.get("nodes", {}):
- self._node_to_tree[node_id] = root_id
+ self._remove_tree_lookup_ids_unlocked(root_id)
+ for lookup_id in self._tree_lookup_ids(tree_data):
+ self._node_to_tree[lookup_id] = root_id
self._schedule_save()
logger.debug(f"Saved tree {root_id}")
@@ -281,8 +311,7 @@ class SessionStore:
with self._lock:
tree_data = self._trees.pop(root_id, None)
if tree_data:
- for node_id in tree_data.get("nodes", {}):
- self._node_to_tree.pop(node_id, None)
+ self._remove_tree_lookup_ids_unlocked(root_id)
self._schedule_save()
def get_all_trees(self) -> dict[str, dict]:
diff --git a/messaging/trees/__init__.py b/messaging/trees/__init__.py
index b3b556eb..cc96cb2e 100644
--- a/messaging/trees/__init__.py
+++ b/messaging/trees/__init__.py
@@ -1,11 +1,15 @@
"""Message tree data structures and queue management."""
from .data import MessageNode, MessageState, MessageTree
-from .queue_manager import TreeQueueManager
+from .manager import TreeQueueManager
+from .processor import TreeQueueProcessor
+from .repository import TreeRepository
__all__ = [
"MessageNode",
"MessageState",
"MessageTree",
"TreeQueueManager",
+ "TreeQueueProcessor",
+ "TreeRepository",
]
diff --git a/messaging/trees/queue_manager.py b/messaging/trees/manager.py
similarity index 54%
rename from messaging/trees/queue_manager.py
rename to messaging/trees/manager.py
index 2c0cecda..dda4dcec 100644
--- a/messaging/trees/queue_manager.py
+++ b/messaging/trees/manager.py
@@ -1,337 +1,14 @@
-"""Tree-based message queue: index, async node processor, and public manager API."""
+"""Public manager API for tree-based messaging queues."""
import asyncio
from collections.abc import Awaitable, Callable
from loguru import logger
-from config.settings import get_settings
-from core.anthropic import get_user_facing_error_message
-
from ..models import IncomingMessage
-from ..safe_diagnostics import format_exception_for_log
from .data import MessageNode, MessageState, MessageTree
-
-
-class TreeRepository:
- """
- In-memory index of trees and node-to-root mappings.
-
- Used only by :class:`TreeQueueManager`; kept as a named type for tests.
- """
-
- def __init__(self) -> None:
- self._trees: dict[str, MessageTree] = {} # root_id -> tree
- self._node_to_tree: dict[str, str] = {} # node_id -> root_id
-
- def get_tree(self, root_id: str) -> MessageTree | None:
- """Get a tree by its root ID."""
- return self._trees.get(root_id)
-
- def get_tree_for_node(self, node_id: str) -> MessageTree | None:
- """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) -> MessageNode | None:
- """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 add_tree(self, root_id: str, tree: MessageTree) -> None:
- """Add a new tree to the repository."""
- self._trees[root_id] = tree
- self._node_to_tree[root_id] = root_id
- logger.debug("TREE_REPO: add_tree root_id={}", root_id)
-
- def register_node(self, node_id: str, root_id: str) -> None:
- """Register a node ID to a tree."""
- self._node_to_tree[node_id] = root_id
- logger.debug("TREE_REPO: register_node node_id={} root_id={}", node_id, root_id)
-
- def has_node(self, node_id: str) -> bool:
- """Check if a node is registered in any tree."""
- return node_id in self._node_to_tree
-
- def tree_count(self) -> int:
- """Get the number of trees in the repository."""
- return len(self._trees)
-
- 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
-
- 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 resolve_parent_node_id(self, msg_id: str) -> str | None:
- """
- 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
-
- if tree.has_node(msg_id):
- return msg_id
-
- node = tree.find_node_by_status_message(msg_id)
- if node:
- return node.node_id
-
- return None
-
- def get_pending_children(self, node_id: str) -> list[MessageNode]:
- """
- Get all pending child nodes (recursively) of a given node.
-
- Used for error propagation - when a node fails, its pending
- children should also be marked as failed.
- """
- tree = self.get_tree_for_node(node_id)
- if not tree:
- return []
-
- pending: list[MessageNode] = []
- stack = [node_id]
-
- while stack:
- current_id = stack.pop()
- node = tree.get_node(current_id)
- if not node:
- continue
- for child_id in node.children_ids:
- child = tree.get_node(child_id)
- if child and child.state == MessageState.PENDING:
- pending.append(child)
- stack.append(child_id)
-
- return pending
-
- def all_trees(self) -> list[MessageTree]:
- """Get all trees in the repository."""
- return list(self._trees.values())
-
- def tree_ids(self) -> list[str]:
- """Get all tree root IDs."""
- return list(self._trees.keys())
-
- def unregister_nodes(self, node_ids: list[str]) -> None:
- """Remove node IDs from the node-to-tree mapping."""
- for nid in node_ids:
- self._node_to_tree.pop(nid, None)
-
- def remove_tree(self, root_id: str) -> MessageTree | None:
- """
- Remove a tree and all its node mappings from the repository.
-
- Returns:
- The removed tree, or None if not found.
- """
- tree = self._trees.pop(root_id, None)
- if not tree:
- return None
- for node in tree.all_nodes():
- self._node_to_tree.pop(node.node_id, None)
- logger.debug("TREE_REPO: remove_tree root_id={}", root_id)
- return tree
-
- def get_message_ids_for_chat(self, platform: str, chat_id: str) -> set[str]:
- """Get all message IDs (incoming + status) for a given platform/chat."""
- msg_ids: set[str] = set()
- for tree in self._trees.values():
- for node in tree.all_nodes():
- if str(node.incoming.platform) == str(platform) and str(
- node.incoming.chat_id
- ) == str(chat_id):
- if node.incoming.message_id is not None:
- msg_ids.add(str(node.incoming.message_id))
- if node.status_message_id:
- msg_ids.add(str(node.status_message_id))
- return msg_ids
-
- 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) -> TreeRepository:
- """Deserialize from dictionary."""
- repo = cls()
- for root_id, tree_data in data.get("trees", {}).items():
- repo._trees[root_id] = MessageTree.from_dict(tree_data)
- repo._node_to_tree = data.get("node_to_tree", {})
- return repo
-
-
-class TreeQueueProcessor:
- """
- Per-tree async queue processing (one manager owns one processor instance).
- """
-
- def __init__(
- self,
- queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None = None,
- node_started_callback: Callable[[MessageTree, str], Awaitable[None]]
- | None = None,
- ) -> None:
- self._queue_update_callback = queue_update_callback
- self._node_started_callback = node_started_callback
-
- def set_queue_update_callback(
- self,
- queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None,
- ) -> None:
- """Update the callback used to refresh queue positions."""
- self._queue_update_callback = queue_update_callback
-
- def set_node_started_callback(
- self,
- node_started_callback: Callable[[MessageTree, str], Awaitable[None]] | None,
- ) -> None:
- """Update the callback used when a queued node starts processing."""
- self._node_started_callback = node_started_callback
-
- async def _notify_queue_updated(self, tree: MessageTree) -> None:
- """Invoke queue update callback if set."""
- if not self._queue_update_callback:
- return
- try:
- await self._queue_update_callback(tree)
- except Exception as e:
- d = get_settings().log_messaging_error_details
- logger.warning(
- "Queue update callback failed: {}",
- format_exception_for_log(e, log_full_message=d),
- )
-
- async def _notify_node_started(self, tree: MessageTree, node_id: str) -> None:
- """Invoke node started callback if set."""
- if not self._node_started_callback:
- return
- try:
- await self._node_started_callback(tree, node_id)
- except Exception as e:
- d = get_settings().log_messaging_error_details
- logger.warning(
- "Node started callback failed: {}",
- format_exception_for_log(e, log_full_message=d),
- )
-
- 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."""
- if node.state == MessageState.ERROR:
- logger.info(
- f"Skipping node {node.node_id} as it is already in state {node.state}"
- )
- await self._process_next(tree, processor)
- return
-
- 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:
- d = get_settings().log_messaging_error_details
- logger.error(
- "Error processing node {}: {}",
- node.node_id,
- format_exception_for_log(e, log_full_message=d),
- )
- await tree.update_state(
- node.node_id,
- MessageState.ERROR,
- error_message=get_user_facing_error_message(e),
- )
- finally:
- async with tree.with_lock():
- tree.clear_current_node()
- 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."""
- next_node_id = None
- async with tree.with_lock():
- next_node_id = await tree.dequeue()
-
- if not next_node_id:
- tree.set_processing_state(None, False)
- logger.debug(f"Tree {tree.root_id} queue empty, marking as free")
- return
-
- tree.set_processing_state(next_node_id, True)
- logger.info(f"Processing next queued node {next_node_id}")
-
- node = tree.get_node(next_node_id)
- if node:
- tree.set_current_task(
- asyncio.create_task(self.process_node(tree, node, processor))
- )
-
- if next_node_id:
- await self._notify_node_started(tree, next_node_id)
- await self._notify_queue_updated(tree)
-
- async def enqueue_and_start(
- self,
- tree: MessageTree,
- node_id: str,
- processor: Callable[[str, MessageNode], Awaitable[None]],
- ) -> bool:
- """
- Enqueue a node or start processing immediately.
-
- Returns:
- True if queued, False if processing immediately
- """
- async with tree.with_lock():
- if tree.is_processing:
- tree.put_queue_unlocked(node_id)
- queue_size = tree.get_queue_size()
- logger.info(f"Queued node {node_id}, position {queue_size}")
- return True
- else:
- tree.set_processing_state(node_id, True)
-
- node = tree.get_node(node_id)
- if node:
- tree.set_current_task(
- asyncio.create_task(self.process_node(tree, node, processor))
- )
- return False
-
- def cancel_current(self, tree: MessageTree) -> bool:
- """Cancel the currently running task in a tree."""
- return tree.cancel_current_task()
+from .processor import TreeQueueProcessor
+from .repository import TreeRepository
class TreeQueueManager:
@@ -598,8 +275,9 @@ class TreeQueueManager:
if tree.is_current_node(node_id):
self._processor.cancel_current(tree)
+ removed_from_queue = False
try:
- tree.remove_from_queue(node_id)
+ removed_from_queue = tree.remove_from_queue(node_id)
except Exception:
logger.debug(
"Failed to remove node from queue; will rely on state=ERROR"
@@ -607,7 +285,10 @@ class TreeQueueManager:
tree.set_node_error_sync(node, "Cancelled by user")
- return [node]
+ if removed_from_queue:
+ await self._processor.notify_queue_updated(tree)
+
+ return [node]
async def cancel_all(self) -> list[MessageNode]:
"""Cancel all messages in all trees."""
@@ -665,6 +346,7 @@ class TreeQueueManager:
branch_ids = set(tree.get_descendants(branch_root_id))
cancelled: list[MessageNode] = []
+ removed_from_queue = False
async with tree.with_lock():
for nid in branch_ids:
@@ -680,12 +362,16 @@ class TreeQueueManager:
tree.set_node_error_sync(node, "Cancelled by user")
cancelled.append(node)
else:
- tree.remove_from_queue(nid)
+ removed_from_queue = (
+ tree.remove_from_queue(nid) or removed_from_queue
+ )
tree.set_node_error_sync(node, "Cancelled by user")
cancelled.append(node)
if cancelled:
logger.info(f"Cancelled {len(cancelled)} nodes in branch {branch_root_id}")
+ if removed_from_queue:
+ await self._processor.notify_queue_updated(tree)
return cancelled
async def remove_branch(
@@ -715,7 +401,7 @@ class TreeQueueManager:
async with tree.with_lock():
removed = tree.remove_branch(branch_root_id)
- self._repository.unregister_nodes([n.node_id for n in removed])
+ self._repository.unregister_node_lookups(removed)
return (removed, root_id, False)
def get_message_ids_for_chat(self, platform: str, chat_id: str) -> set[str]:
@@ -744,6 +430,4 @@ class TreeQueueManager:
__all__ = [
"TreeQueueManager",
- "TreeQueueProcessor",
- "TreeRepository",
]
diff --git a/messaging/trees/processor.py b/messaging/trees/processor.py
new file mode 100644
index 00000000..b6315957
--- /dev/null
+++ b/messaging/trees/processor.py
@@ -0,0 +1,179 @@
+"""Async processing loop for a single messaging tree queue."""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+
+from loguru import logger
+
+from config.settings import get_settings
+from core.anthropic import get_user_facing_error_message
+
+from ..safe_diagnostics import format_exception_for_log
+from .data import MessageNode, MessageState, MessageTree
+
+
+class TreeQueueProcessor:
+ """Per-tree async queue processing owned by TreeQueueManager."""
+
+ def __init__(
+ self,
+ queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None = None,
+ node_started_callback: Callable[[MessageTree, str], Awaitable[None]]
+ | None = None,
+ ) -> None:
+ self._queue_update_callback = queue_update_callback
+ self._node_started_callback = node_started_callback
+
+ def set_queue_update_callback(
+ self,
+ queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None,
+ ) -> None:
+ """Update the callback used to refresh queue positions."""
+ self._queue_update_callback = queue_update_callback
+
+ def set_node_started_callback(
+ self,
+ node_started_callback: Callable[[MessageTree, str], Awaitable[None]] | None,
+ ) -> None:
+ """Update the callback used when a queued node starts processing."""
+ self._node_started_callback = node_started_callback
+
+ async def _notify_queue_updated(self, tree: MessageTree) -> None:
+ """Invoke queue update callback if set."""
+ if not self._queue_update_callback:
+ return
+ try:
+ await self._queue_update_callback(tree)
+ except Exception as e:
+ d = get_settings().log_messaging_error_details
+ logger.warning(
+ "Queue update callback failed: {}",
+ format_exception_for_log(e, log_full_message=d),
+ )
+
+ async def notify_queue_updated(self, tree: MessageTree) -> None:
+ """Invoke the queue update callback after external queue mutations."""
+ await self._notify_queue_updated(tree)
+
+ async def _notify_node_started(self, tree: MessageTree, node_id: str) -> None:
+ """Invoke node started callback if set."""
+ if not self._node_started_callback:
+ return
+ try:
+ await self._node_started_callback(tree, node_id)
+ except Exception as e:
+ d = get_settings().log_messaging_error_details
+ logger.warning(
+ "Node started callback failed: {}",
+ format_exception_for_log(e, log_full_message=d),
+ )
+
+ 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."""
+ if node.state == MessageState.ERROR:
+ logger.info(
+ f"Skipping node {node.node_id} as it is already in state {node.state}"
+ )
+ await self._process_next(tree, processor)
+ return
+
+ 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:
+ d = get_settings().log_messaging_error_details
+ logger.error(
+ "Error processing node {}: {}",
+ node.node_id,
+ format_exception_for_log(e, log_full_message=d),
+ )
+ await tree.update_state(
+ node.node_id,
+ MessageState.ERROR,
+ error_message=get_user_facing_error_message(e),
+ )
+ finally:
+ async with tree.with_lock():
+ tree.clear_current_node()
+ 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."""
+ next_node_id = None
+ node: MessageNode | None = None
+ discarded_stale_ids = False
+ async with tree.with_lock():
+ while True:
+ next_node_id = await tree.dequeue()
+
+ if not next_node_id:
+ tree.set_processing_state(None, False)
+ logger.debug(f"Tree {tree.root_id} queue empty, marking as free")
+ break
+
+ node = tree.get_node(next_node_id)
+ if node:
+ tree.set_processing_state(next_node_id, True)
+ logger.info(f"Processing next queued node {next_node_id}")
+ tree.set_current_task(
+ asyncio.create_task(self.process_node(tree, node, processor))
+ )
+ break
+
+ discarded_stale_ids = True
+ logger.debug(
+ "Skipping stale queued node {} in tree {}",
+ next_node_id,
+ tree.root_id,
+ )
+
+ if next_node_id and node:
+ await self._notify_node_started(tree, next_node_id)
+ await self._notify_queue_updated(tree)
+ elif discarded_stale_ids:
+ await self._notify_queue_updated(tree)
+
+ async def enqueue_and_start(
+ self,
+ tree: MessageTree,
+ node_id: str,
+ processor: Callable[[str, MessageNode], Awaitable[None]],
+ ) -> bool:
+ """
+ Enqueue a node or start processing immediately.
+
+ Returns True if queued, False if processing immediately.
+ """
+ async with tree.with_lock():
+ if tree.is_processing:
+ tree.put_queue_unlocked(node_id)
+ queue_size = tree.get_queue_size()
+ logger.info(f"Queued node {node_id}, position {queue_size}")
+ return True
+
+ tree.set_processing_state(node_id, True)
+
+ node = tree.get_node(node_id)
+ if node:
+ tree.set_current_task(
+ asyncio.create_task(self.process_node(tree, node, processor))
+ )
+ return False
+
+ def cancel_current(self, tree: MessageTree) -> bool:
+ """Cancel the currently running task in a tree."""
+ return tree.cancel_current_task()
+
+
+__all__ = ["TreeQueueProcessor"]
diff --git a/messaging/trees/repository.py b/messaging/trees/repository.py
new file mode 100644
index 00000000..b4267c78
--- /dev/null
+++ b/messaging/trees/repository.py
@@ -0,0 +1,177 @@
+"""In-memory repository for messaging trees and node indexes."""
+
+from loguru import logger
+
+from .data import MessageNode, MessageState, MessageTree
+
+
+class TreeRepository:
+ """
+ In-memory index of trees and node-to-root mappings.
+
+ Used only by TreeQueueManager; kept as a named type for focused tests.
+ """
+
+ def __init__(self) -> None:
+ self._trees: dict[str, MessageTree] = {}
+ self._node_to_tree: dict[str, str] = {}
+
+ def get_tree(self, root_id: str) -> MessageTree | None:
+ """Get a tree by its root ID."""
+ return self._trees.get(root_id)
+
+ def get_tree_for_node(self, node_id: str) -> MessageTree | None:
+ """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) -> MessageNode | None:
+ """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 add_tree(self, root_id: str, tree: MessageTree) -> None:
+ """Add a new tree to the repository."""
+ self._trees[root_id] = tree
+ self._node_to_tree[root_id] = root_id
+ logger.debug("TREE_REPO: add_tree root_id={}", root_id)
+
+ def register_node(self, node_id: str, root_id: str) -> None:
+ """Register a node ID to a tree."""
+ self._node_to_tree[node_id] = root_id
+ logger.debug("TREE_REPO: register_node node_id={} root_id={}", node_id, root_id)
+
+ def has_node(self, node_id: str) -> bool:
+ """Check if a node is registered in any tree."""
+ return node_id in self._node_to_tree
+
+ def tree_count(self) -> int:
+ """Get the number of trees in the repository."""
+ return len(self._trees)
+
+ 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
+
+ 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 resolve_parent_node_id(self, msg_id: str) -> str | None:
+ """
+ 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).
+ """
+ tree = self.get_tree_for_node(msg_id)
+ if not tree:
+ return None
+
+ if tree.has_node(msg_id):
+ return msg_id
+
+ node = tree.find_node_by_status_message(msg_id)
+ if node:
+ return node.node_id
+
+ return None
+
+ def get_pending_children(self, node_id: str) -> list[MessageNode]:
+ """Get all pending child nodes recursively for error propagation."""
+ tree = self.get_tree_for_node(node_id)
+ if not tree:
+ return []
+
+ pending: list[MessageNode] = []
+ stack = [node_id]
+
+ while stack:
+ current_id = stack.pop()
+ node = tree.get_node(current_id)
+ if not node:
+ continue
+ for child_id in node.children_ids:
+ child = tree.get_node(child_id)
+ if child and child.state == MessageState.PENDING:
+ pending.append(child)
+ stack.append(child_id)
+
+ return pending
+
+ def all_trees(self) -> list[MessageTree]:
+ """Get all trees in the repository."""
+ return list(self._trees.values())
+
+ def tree_ids(self) -> list[str]:
+ """Get all tree root IDs."""
+ return list(self._trees.keys())
+
+ def unregister_nodes(self, node_ids: list[str]) -> None:
+ """Remove lookup IDs from the node-to-tree mapping."""
+ for nid in node_ids:
+ self._node_to_tree.pop(nid, None)
+
+ def unregister_node_lookups(self, nodes: list[MessageNode]) -> None:
+ """Remove node and status-message lookup IDs for removed nodes."""
+ lookup_ids: list[str] = []
+ for node in nodes:
+ lookup_ids.append(node.node_id)
+ if node.status_message_id:
+ lookup_ids.append(node.status_message_id)
+ self.unregister_nodes(lookup_ids)
+
+ def remove_tree(self, root_id: str) -> MessageTree | None:
+ """
+ Remove a tree and all its node mappings from the repository.
+
+ Returns the removed tree, or None if not found.
+ """
+ tree = self._trees.pop(root_id, None)
+ if not tree:
+ return None
+ self.unregister_node_lookups(tree.all_nodes())
+ logger.debug("TREE_REPO: remove_tree root_id={}", root_id)
+ return tree
+
+ def get_message_ids_for_chat(self, platform: str, chat_id: str) -> set[str]:
+ """Get all message IDs (incoming + status) for a platform/chat."""
+ msg_ids: set[str] = set()
+ for tree in self._trees.values():
+ for node in tree.all_nodes():
+ if str(node.incoming.platform) == str(platform) and str(
+ node.incoming.chat_id
+ ) == str(chat_id):
+ if node.incoming.message_id is not None:
+ msg_ids.add(str(node.incoming.message_id))
+ if node.status_message_id:
+ msg_ids.add(str(node.status_message_id))
+ return msg_ids
+
+ 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) -> TreeRepository:
+ """Deserialize from dictionary."""
+ repo = cls()
+ for root_id, tree_data in data.get("trees", {}).items():
+ repo._trees[root_id] = MessageTree.from_dict(tree_data)
+ repo._node_to_tree = data.get("node_to_tree", {})
+ return repo
+
+
+__all__ = ["TreeRepository"]
diff --git a/messaging/turn_intake.py b/messaging/turn_intake.py
new file mode 100644
index 00000000..fc079b88
--- /dev/null
+++ b/messaging/turn_intake.py
@@ -0,0 +1,235 @@
+"""Inbound messaging turn intake and queue admission."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from loguru import logger
+
+from core.trace import trace_event
+
+from .cli_event_constants import STATUS_MESSAGE_PREFIXES
+from .command_context import MessagingCommandContext
+from .command_dispatcher import (
+ dispatch_command,
+ message_kind_for_command,
+ parse_command_base,
+)
+from .models import IncomingMessage
+from .platforms.base import MessagingPlatform
+from .safe_diagnostics import format_exception_for_log
+from .session import SessionStore
+from .trees import MessageNode, MessageState, MessageTree, TreeQueueManager
+
+
+class MessagingTurnIntake:
+ """Owns inbound turn classification and queue admission."""
+
+ def __init__(
+ self,
+ *,
+ platform: MessagingPlatform,
+ session_store: SessionStore,
+ command_context: MessagingCommandContext,
+ get_tree_queue: Callable[[], TreeQueueManager],
+ process_node: Callable[[str, MessageNode], Awaitable[None]],
+ format_status: Callable[[str, str, str | None], str],
+ get_parse_mode: Callable[[], str | None],
+ record_outgoing_message: Callable[[str, str, str | None, str], None],
+ log_messaging_error_details: bool = False,
+ ) -> None:
+ self.platform = platform
+ self.session_store = session_store
+ self._command_context = command_context
+ self._get_tree_queue = get_tree_queue
+ self._process_node = process_node
+ self._format_status = format_status
+ self._get_parse_mode = get_parse_mode
+ self._record_outgoing_message = record_outgoing_message
+ self._log_messaging_error_details = log_messaging_error_details
+
+ async def handle_message(self, incoming: IncomingMessage) -> None:
+ """
+ Handle an inbound platform message and queue it if it is a user prompt.
+ """
+ cmd_base = parse_command_base(incoming.text)
+
+ try:
+ if incoming.message_id is not None:
+ self.session_store.record_message_id(
+ incoming.platform,
+ incoming.chat_id,
+ str(incoming.message_id),
+ direction="in",
+ kind=message_kind_for_command(cmd_base),
+ )
+ except Exception as e:
+ logger.debug(
+ "Failed to record incoming message_id: {}",
+ format_exception_for_log(
+ e, log_full_message=self._log_messaging_error_details
+ ),
+ )
+
+ if await dispatch_command(self._command_context, incoming, cmd_base):
+ return
+
+ text = incoming.text or ""
+ if any(text.startswith(p) for p in STATUS_MESSAGE_PREFIXES):
+ return
+
+ parent_node_id = None
+ tree = None
+ tree_queue = self._get_tree_queue()
+
+ if incoming.is_reply() and incoming.reply_to_message_id:
+ reply_id = incoming.reply_to_message_id
+ tree = tree_queue.get_tree_for_node(reply_id)
+ if tree:
+ parent_node_id = tree_queue.resolve_parent_node_id(reply_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
+
+ node_id = incoming.message_id
+ status_text = self._get_initial_status(tree, parent_node_id)
+ if incoming.status_message_id:
+ status_msg_id = incoming.status_message_id
+ await self.platform.queue_edit_message(
+ incoming.chat_id,
+ status_msg_id,
+ status_text,
+ parse_mode=self._get_parse_mode(),
+ fire_and_forget=False,
+ )
+ else:
+ status_msg_id = await self.platform.queue_send_message(
+ incoming.chat_id,
+ status_text,
+ reply_to=incoming.message_id,
+ fire_and_forget=False,
+ message_thread_id=incoming.message_thread_id,
+ )
+ self._record_outgoing_message(
+ incoming.platform, incoming.chat_id, status_msg_id, "status"
+ )
+
+ tree_queue = self._get_tree_queue()
+ if parent_node_id and tree and status_msg_id:
+ tree, _node = await tree_queue.add_to_tree(
+ parent_node_id=parent_node_id,
+ node_id=node_id,
+ incoming=incoming,
+ status_message_id=status_msg_id,
+ )
+ 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)
+ elif status_msg_id:
+ tree = await tree_queue.create_tree(
+ node_id=node_id,
+ incoming=incoming,
+ status_message_id=status_msg_id,
+ )
+ 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)
+
+ if tree:
+ self.session_store.save_tree(tree.root_id, tree.to_dict())
+
+ was_queued = await tree_queue.enqueue(
+ node_id=node_id,
+ processor=self._process_node,
+ )
+
+ if was_queued and status_msg_id:
+ queue_size = tree_queue.get_queue_size(node_id)
+ trace_event(
+ stage="routing",
+ event="turn.queued",
+ source=getattr(self.platform, "name", "messaging"),
+ chat_id=incoming.chat_id,
+ platform_message_id=node_id,
+ status_message_id=status_msg_id,
+ queue_size=queue_size,
+ )
+ await self.platform.queue_edit_message(
+ incoming.chat_id,
+ status_msg_id,
+ self._format_status(
+ "📋", "Queued", f"(position {queue_size}) - waiting..."
+ ),
+ parse_mode=self._get_parse_mode(),
+ )
+
+ async def update_queue_positions(self, tree: MessageTree) -> None:
+ """Refresh queued status messages after a dequeue."""
+ try:
+ queued_ids = await tree.get_queue_snapshot()
+ except Exception as e:
+ logger.warning(
+ "Failed to read queue snapshot: {}",
+ format_exception_for_log(
+ e, log_full_message=self._log_messaging_error_details
+ ),
+ )
+ return
+
+ if not queued_ids:
+ return
+
+ position = 0
+ for node_id in queued_ids:
+ node = tree.get_node(node_id)
+ if not node or node.state != MessageState.PENDING:
+ continue
+ position += 1
+ self.platform.fire_and_forget(
+ self.platform.queue_edit_message(
+ node.incoming.chat_id,
+ node.status_message_id,
+ self._format_status(
+ "📋", "Queued", f"(position {position}) - waiting..."
+ ),
+ parse_mode=self._get_parse_mode(),
+ )
+ )
+
+ async def mark_node_processing(self, tree: MessageTree, node_id: str) -> None:
+ """Update the dequeued node's status to processing immediately."""
+ node = tree.get_node(node_id)
+ if not node or node.state == MessageState.ERROR:
+ return
+ self.platform.fire_and_forget(
+ self.platform.queue_edit_message(
+ node.incoming.chat_id,
+ node.status_message_id,
+ self._format_status("🔄", "Processing...", None),
+ parse_mode=self._get_parse_mode(),
+ )
+ )
+
+ def _get_initial_status(
+ self,
+ tree: object | None,
+ parent_node_id: str | None,
+ ) -> str:
+ """Get initial status message text."""
+ tree_queue = self._get_tree_queue()
+ if tree and parent_node_id:
+ if tree_queue.is_node_tree_busy(parent_node_id):
+ queue_size = tree_queue.get_queue_size(parent_node_id) + 1
+ return self._format_status(
+ "📋", "Queued", f"(position {queue_size}) - waiting..."
+ )
+ return self._format_status("🔄", "Continuing conversation...", None)
+
+ return self._format_status("⏳", "Launching new Claude CLI instance...", None)
+
+
+__all__ = ["MessagingTurnIntake"]
diff --git a/messaging/workflow.py b/messaging/workflow.py
new file mode 100644
index 00000000..beec6f8d
--- /dev/null
+++ b/messaging/workflow.py
@@ -0,0 +1,200 @@
+"""Messaging workflow coordinator for Discord and Telegram prompts."""
+
+from __future__ import annotations
+
+from loguru import logger
+
+from core.trace import trace_event
+
+from .models import IncomingMessage
+from .node_runner import MessagingNodeRunner
+from .platforms.base import MessagingPlatform, SessionManagerInterface
+from .rendering.profiles import build_rendering_profile
+from .safe_diagnostics import format_exception_for_log
+from .session import SessionStore
+from .transcript import RenderCtx
+from .trees import MessageNode, MessageState, MessageTree, TreeQueueManager
+from .turn_intake import MessagingTurnIntake
+
+
+class MessagingWorkflow:
+ """
+ Platform-agnostic messaging workflow.
+
+ It coordinates dependencies and owns stop/clear side effects. Inbound turn
+ intake and queued node execution live in dedicated collaborators.
+ """
+
+ def __init__(
+ self,
+ platform: MessagingPlatform,
+ cli_manager: SessionManagerInterface,
+ session_store: SessionStore,
+ *,
+ debug_platform_edits: bool = False,
+ debug_subagent_stack: bool = False,
+ log_raw_messaging_content: bool = False,
+ log_raw_cli_diagnostics: bool = False,
+ log_messaging_error_details: bool = False,
+ ):
+ self.platform = platform
+ self.cli_manager = cli_manager
+ self.session_store = session_store
+ self._log_messaging_error_details = log_messaging_error_details
+ self._tree_queue = TreeQueueManager()
+ self._rendering_profile = build_rendering_profile(platform.name)
+
+ self.node_runner = MessagingNodeRunner(
+ platform=platform,
+ cli_manager=cli_manager,
+ session_store=session_store,
+ get_tree_queue=lambda: self._tree_queue,
+ format_status=self.format_status,
+ get_parse_mode=self._parse_mode,
+ get_render_ctx=self.get_render_ctx,
+ get_limit_chars=self._get_limit_chars,
+ debug_platform_edits=debug_platform_edits,
+ debug_subagent_stack=debug_subagent_stack,
+ log_raw_cli_diagnostics=log_raw_cli_diagnostics,
+ log_messaging_error_details=log_messaging_error_details,
+ )
+ self.turn_intake = MessagingTurnIntake(
+ platform=platform,
+ session_store=session_store,
+ command_context=self,
+ get_tree_queue=lambda: self._tree_queue,
+ process_node=self.node_runner.process_node,
+ format_status=self.format_status,
+ get_parse_mode=self._parse_mode,
+ record_outgoing_message=self.record_outgoing_message,
+ log_messaging_error_details=log_messaging_error_details,
+ )
+ self._wire_tree_callbacks()
+
+ def _wire_tree_callbacks(self) -> None:
+ self._tree_queue.set_queue_update_callback(
+ self.turn_intake.update_queue_positions
+ )
+ self._tree_queue.set_node_started_callback(
+ self.turn_intake.mark_node_processing
+ )
+
+ def format_status(self, emoji: str, label: str, suffix: str | None = None) -> str:
+ return self._rendering_profile.format_status(emoji, label, suffix)
+
+ def _parse_mode(self) -> str | None:
+ return self._rendering_profile.parse_mode
+
+ def get_render_ctx(self) -> RenderCtx:
+ return self._rendering_profile.render_ctx
+
+ def _get_limit_chars(self) -> int:
+ return self._rendering_profile.limit_chars
+
+ @property
+ def tree_queue(self) -> TreeQueueManager:
+ """Accessor for the current tree queue manager."""
+ return self._tree_queue
+
+ def replace_tree_queue(self, tree_queue: TreeQueueManager) -> None:
+ """Replace tree queue manager via explicit API."""
+ self._tree_queue = tree_queue
+ self._wire_tree_callbacks()
+
+ async def handle_message(self, incoming: IncomingMessage) -> None:
+ """
+ Main entry point for handling an incoming platform message.
+ """
+ platform_name = getattr(self.platform, "name", "messaging")
+ trace_event(
+ stage="ingress",
+ event="turn.received",
+ source=platform_name,
+ chat_id=incoming.chat_id,
+ platform_message_id=incoming.message_id,
+ reply_to_message_id=incoming.reply_to_message_id,
+ thread_id=getattr(incoming, "message_thread_id", None),
+ message_text=incoming.text or "",
+ )
+
+ with logger.contextualize(
+ chat_id=incoming.chat_id, node_id=incoming.message_id
+ ):
+ await self.turn_intake.handle_message(incoming)
+
+ async def update_queue_positions(self, tree: MessageTree) -> None:
+ """Refresh queued status messages after a dequeue."""
+ await self.turn_intake.update_queue_positions(tree)
+
+ async def mark_node_processing(self, tree: MessageTree, node_id: str) -> None:
+ """Update the dequeued node's status to processing immediately."""
+ await self.turn_intake.mark_node_processing(tree, node_id)
+
+ async def stop_all_tasks(self) -> int:
+ """
+ Stop all pending and in-progress messaging tasks.
+ """
+ logger.info("Cancelling tree queue tasks...")
+ cancelled_nodes = await self.tree_queue.cancel_all()
+ logger.info(f"Cancelled {len(cancelled_nodes)} nodes")
+
+ logger.info("Stopping all CLI sessions...")
+ await self.cli_manager.stop_all()
+
+ self.update_cancelled_nodes_ui(cancelled_nodes)
+ return len(cancelled_nodes)
+
+ async def stop_task(self, node_id: str) -> int:
+ """Stop a single queued or in-progress task node."""
+ tree = self.tree_queue.get_tree_for_node(node_id)
+ if tree:
+ node = tree.get_node(node_id)
+ if node and node.state not in (MessageState.COMPLETED, MessageState.ERROR):
+ node.set_context({"cancel_reason": "stop"})
+
+ cancelled_nodes = await self.tree_queue.cancel_node(node_id)
+ self.update_cancelled_nodes_ui(cancelled_nodes)
+ return len(cancelled_nodes)
+
+ def record_outgoing_message(
+ self,
+ platform: str,
+ chat_id: str,
+ msg_id: str | None,
+ kind: str,
+ ) -> None:
+ """Record outgoing message ID for /clear. Best-effort, never raises."""
+ if not msg_id:
+ return
+ try:
+ self.session_store.record_message_id(
+ platform, chat_id, str(msg_id), direction="out", kind=kind
+ )
+ except Exception as e:
+ logger.debug(
+ "Failed to record message_id: {}",
+ format_exception_for_log(
+ e, log_full_message=self._log_messaging_error_details
+ ),
+ )
+
+ def update_cancelled_nodes_ui(self, nodes: list[MessageNode]) -> None:
+ """Update status messages and persist tree state for cancelled nodes."""
+ trees_to_save: dict[str, MessageTree] = {}
+ for node in nodes:
+ self.platform.fire_and_forget(
+ self.platform.queue_edit_message(
+ node.incoming.chat_id,
+ node.status_message_id,
+ self.format_status("⏹", "Stopped."),
+ parse_mode=self._parse_mode(),
+ )
+ )
+ tree = self.tree_queue.get_tree_for_node(node.node_id)
+ if tree:
+ trees_to_save[tree.root_id] = tree
+ for root_id, tree in trees_to_save.items():
+ self.session_store.save_tree(root_id, tree.to_dict())
+
+
+__all__ = ["MessagingWorkflow"]
diff --git a/pyproject.toml b/pyproject.toml
index cf1c4258..3dd2783f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "2.3.6"
+version = "2.3.7"
description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/smoke/capabilities.py b/smoke/capabilities.py
index 2557eda6..e13a6eea 100644
--- a/smoke/capabilities.py
+++ b/smoke/capabilities.py
@@ -336,7 +336,7 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
"messaging",
"discord_telegram_platforms",
"discord_telegram_bot",
- "messaging.handler.ClaudeMessageHandler",
+ "messaging.workflow.MessagingWorkflow",
"Discord/Telegram incoming messages and API callbacks",
"live progress edits and final transcript",
"platform retry/fallback or user-facing error",
diff --git a/smoke/lib/e2e.py b/smoke/lib/e2e.py
index 3aaabf27..38eaac07 100644
--- a/smoke/lib/e2e.py
+++ b/smoke/lib/e2e.py
@@ -27,10 +27,10 @@ from core.anthropic.stream_contracts import (
parse_sse_lines,
text_content,
)
-from messaging.handler import ClaudeMessageHandler
from messaging.models import IncomingMessage
from messaging.platforms.base import MessagingPlatform
from messaging.session import SessionStore
+from messaging.workflow import MessagingWorkflow
from smoke.lib.config import ProviderModel, SmokeConfig, auth_headers
from smoke.lib.server import RunningServer, start_server
from smoke.lib.skips import fail_missing_env
@@ -506,7 +506,7 @@ class FakePlatformDriver:
platform: FakePlatform = field(init=False)
cli_manager: FakeCLIManager = field(init=False)
session_store: SessionStore = field(init=False)
- handler: ClaudeMessageHandler = field(init=False)
+ workflow: MessagingWorkflow = field(init=False)
def __post_init__(self) -> None:
self.platform = FakePlatform(self.platform_name)
@@ -514,10 +514,10 @@ class FakePlatformDriver:
self.session_store = SessionStore(
storage_path=str(self.tmp_path / f"{self.platform_name}-sessions.json")
)
- self.handler = ClaudeMessageHandler(
+ self.workflow = MessagingWorkflow(
self.platform, self.cli_manager, self.session_store
)
- self.platform.on_message(self.handler.handle_message)
+ self.platform.on_message(self.workflow.handle_message)
async def send(
self,
@@ -549,7 +549,7 @@ class FakePlatformDriver:
raise AssertionError("fake platform did not become idle")
def _all_tree_nodes_terminal(self) -> bool:
- data = self.handler.tree_queue.to_dict()
+ data = self.workflow.tree_queue.to_dict()
for tree in data.get("trees", {}).values():
nodes = tree.get("nodes", {}) if isinstance(tree, dict) else {}
for node in nodes.values():
diff --git a/smoke/product/test_messaging_product_live.py b/smoke/product/test_messaging_product_live.py
index 202bd971..b14cc6bf 100644
--- a/smoke/product/test_messaging_product_live.py
+++ b/smoke/product/test_messaging_product_live.py
@@ -4,7 +4,7 @@ import json
import pytest
-from messaging.trees.queue_manager import MessageState
+from messaging.trees import MessageState
from smoke.lib.e2e import FakePlatformDriver, default_cli_events
pytestmark = [pytest.mark.live, pytest.mark.smoke_target("messaging")]
@@ -17,7 +17,7 @@ async def test_messaging_fake_full_flow_e2e(platform_name: str, tmp_path) -> Non
incoming = await driver.send("Please inspect README.", message_id="root_1")
- tree = driver.handler.tree_queue.get_tree_for_node(incoming.message_id)
+ tree = driver.workflow.tree_queue.get_tree_for_node(incoming.message_id)
assert tree is not None
node = tree.get_node(incoming.message_id)
assert node is not None
@@ -91,7 +91,7 @@ async def test_tree_threading_e2e(platform_name: str, tmp_path) -> None:
"branch prompt", message_id="branch_1", reply_to=root.message_id
)
- tree = driver.handler.tree_queue.get_tree_for_node(root.message_id)
+ tree = driver.workflow.tree_queue.get_tree_for_node(root.message_id)
assert tree is not None
branch_node = tree.get_node(branch.message_id)
assert branch_node is not None
diff --git a/tests/api/test_api.py b/tests/api/test_api.py
index cc48c812..36778346 100644
--- a/tests/api/test_api.py
+++ b/tests/api/test_api.py
@@ -260,11 +260,11 @@ def test_count_tokens_endpoint(client: TestClient):
assert "input_tokens" in response.json()
-def test_stop_endpoint_no_handler_no_cli_503(client: TestClient):
- """POST /stop without handler or cli_manager returns 503."""
- # Ensure no handler or cli_manager on app state
- if hasattr(app.state, "message_handler"):
- delattr(app.state, "message_handler")
+def test_stop_endpoint_no_workflow_no_cli_503(client: TestClient):
+ """POST /stop without messaging workflow or cli_manager returns 503."""
+ # Ensure no messaging workflow or cli_manager on app state
+ if hasattr(app.state, "messaging_workflow"):
+ delattr(app.state, "messaging_workflow")
if hasattr(app.state, "cli_manager"):
delattr(app.state, "cli_manager")
response = client.post("/stop")
diff --git a/tests/api/test_app_lifespan_and_errors.py b/tests/api/test_app_lifespan_and_errors.py
index 9ac31262..c88a79fd 100644
--- a/tests/api/test_app_lifespan_and_errors.py
+++ b/tests/api/test_app_lifespan_and_errors.py
@@ -315,7 +315,7 @@ def test_app_lifespan_sets_state_and_cleans_up(tmp_path, messaging_enabled):
patch("messaging.session.SessionStore", return_value=session_store),
patch("cli.manager.CLISessionManager", return_value=cli_manager),
patch(
- "messaging.trees.queue_manager.TreeQueueManager.from_dict",
+ "messaging.trees.TreeQueueManager.from_dict",
return_value=fake_queue,
),
TestClient(app),
@@ -328,7 +328,7 @@ def test_app_lifespan_sets_state_and_cleans_up(tmp_path, messaging_enabled):
fake_platform.start.assert_awaited_once()
fake_platform.stop.assert_awaited_once()
cli_manager.stop_all.assert_awaited_once()
- assert getattr(app.state, "message_handler", None) is not None
+ assert getattr(app.state, "messaging_workflow", None) is not None
session_store.sync_from_tree_data.assert_called_once_with(
[{"t": 1}],
{"n": "t"},
diff --git a/tests/api/test_routes_optimizations.py b/tests/api/test_routes_optimizations.py
index eb8d2ddf..540fff67 100644
--- a/tests/api/test_routes_optimizations.py
+++ b/tests/api/test_routes_optimizations.py
@@ -143,28 +143,28 @@ def test_count_tokens_error_returns_500(client):
assert "token error" in response.json()["detail"]
-def test_stop_cli_with_handler(client):
- mock_handler = MagicMock()
+def test_stop_cli_with_messaging_workflow(client):
+ mock_workflow = MagicMock()
# Mock the async method to return a completed future or just mock it since TestClient
# will run the app in a way that respects it?
# Actually, we need to mock it as an async function.
- mock_handler.stop_all_tasks = AsyncMock(return_value=3)
- app.state.message_handler = mock_handler
+ mock_workflow.stop_all_tasks = AsyncMock(return_value=3)
+ app.state.messaging_workflow = mock_workflow
response = client.post("/stop")
assert response.status_code == 200
assert response.json()["cancelled_count"] == 3
- mock_handler.stop_all_tasks.assert_called_once()
+ mock_workflow.stop_all_tasks.assert_called_once()
# Cleanup state
- if hasattr(app.state, "message_handler"):
- del app.state.message_handler
+ if hasattr(app.state, "messaging_workflow"):
+ del app.state.messaging_workflow
def test_stop_cli_fallback_to_manager(client):
- if hasattr(app.state, "message_handler"):
- del app.state.message_handler
+ if hasattr(app.state, "messaging_workflow"):
+ del app.state.messaging_workflow
mock_manager = MagicMock()
mock_manager.stop_all = AsyncMock()
diff --git a/tests/contracts/test_import_boundaries.py b/tests/contracts/test_import_boundaries.py
index d21dfebe..7cf6aa24 100644
--- a/tests/contracts/test_import_boundaries.py
+++ b/tests/contracts/test_import_boundaries.py
@@ -211,6 +211,35 @@ def test_openai_responses_uses_adapter_boundary() -> None:
assert deleted_api not in adapter_text
+def test_messaging_workflow_uses_split_runtime_owners() -> None:
+ repo_root = Path(__file__).resolve().parents[2]
+ messaging_root = repo_root / "messaging"
+ trees_root = messaging_root / "trees"
+
+ assert not (messaging_root / "handler.py").exists()
+ assert not (trees_root / "queue_manager.py").exists()
+
+ for path in {
+ messaging_root / "workflow.py",
+ messaging_root / "turn_intake.py",
+ messaging_root / "node_runner.py",
+ messaging_root / "command_context.py",
+ trees_root / "manager.py",
+ trees_root / "processor.py",
+ trees_root / "repository.py",
+ }:
+ assert path.exists()
+
+ offenders = _imports_matching(
+ [messaging_root, repo_root / "api", repo_root / "smoke", repo_root / "tests"],
+ forbidden_prefixes=(
+ "messaging.handler",
+ "messaging.trees.queue_manager",
+ ),
+ )
+ assert offenders == []
+
+
def _imports_matching(
roots: list[Path], *, forbidden_prefixes: tuple[str, ...]
) -> list[str]:
diff --git a/tests/messaging/test_handler.py b/tests/messaging/test_handler.py
index 6ea7380d..76a60e19 100644
--- a/tests/messaging/test_handler.py
+++ b/tests/messaging/test_handler.py
@@ -2,15 +2,15 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-from messaging.handler import ClaudeMessageHandler
from messaging.models import IncomingMessage
+from messaging.trees import MessageState
from messaging.trees.data import MessageNode, MessageTree
-from messaging.trees.queue_manager import MessageState
+from messaging.workflow import MessagingWorkflow
@pytest.fixture
def handler(mock_platform, mock_cli_manager, mock_session_store):
- return ClaudeMessageHandler(mock_platform, mock_cli_manager, mock_session_store)
+ return MessagingWorkflow(mock_platform, mock_cli_manager, mock_session_store)
@pytest.mark.asyncio
@@ -19,7 +19,7 @@ async def test_handle_message_turn_trace_includes_full_message_text(
):
"""turn.received always records the verbatim user message (local debugging)."""
secret = "user-message-content-visible-in-trace"
- handler = ClaudeMessageHandler(
+ handler = MessagingWorkflow(
mock_platform,
mock_cli_manager,
mock_session_store,
@@ -27,8 +27,8 @@ async def test_handle_message_turn_trace_includes_full_message_text(
)
incoming = incoming_message_factory(text=secret)
with (
- patch.object(handler, "_handle_message_impl", new_callable=AsyncMock),
- patch("messaging.handler.trace_event") as trace_mock,
+ patch.object(handler.turn_intake, "handle_message", new_callable=AsyncMock),
+ patch("messaging.workflow.trace_event") as trace_mock,
):
await handler.handle_message(incoming)
kwargs = trace_mock.call_args.kwargs
@@ -42,7 +42,7 @@ async def test_handle_message_log_raw_messaging_does_not_change_turn_received_sh
):
"""LOG_RAW_MESSAGING_CONTENT is adapter-only; ingress TRACE always includes text."""
text = "visible-either-way"
- handler = ClaudeMessageHandler(
+ handler = MessagingWorkflow(
mock_platform,
mock_cli_manager,
mock_session_store,
@@ -50,8 +50,8 @@ async def test_handle_message_log_raw_messaging_does_not_change_turn_received_sh
)
incoming = incoming_message_factory(text=text)
with (
- patch.object(handler, "_handle_message_impl", new_callable=AsyncMock),
- patch("messaging.handler.trace_event") as trace_mock,
+ patch.object(handler.turn_intake, "handle_message", new_callable=AsyncMock),
+ patch("messaging.workflow.trace_event") as trace_mock,
):
await handler.handle_message(incoming)
assert trace_mock.call_args.kwargs["message_text"] == text
@@ -59,7 +59,7 @@ async def test_handle_message_log_raw_messaging_does_not_change_turn_received_sh
def test_get_initial_status_new_conversation(handler):
"""New conversation always returns launching message."""
- result = handler._get_initial_status(None, None)
+ result = handler.turn_intake._get_initial_status(None, None)
assert "Launching" in result
@@ -69,7 +69,7 @@ def test_get_initial_status_reply_tree_busy_queued(handler):
mock_queue.is_node_tree_busy.return_value = True
mock_queue.get_queue_size.return_value = 2
handler.replace_tree_queue(mock_queue)
- result = handler._get_initial_status(MagicMock(), "parent_1")
+ result = handler.turn_intake._get_initial_status(MagicMock(), "parent_1")
assert "Queued" in result
assert "position 3" in result
@@ -79,7 +79,7 @@ def test_get_initial_status_reply_tree_not_busy_continuing(handler):
mock_queue = MagicMock()
mock_queue.is_node_tree_busy.return_value = False
handler.replace_tree_queue(mock_queue)
- result = handler._get_initial_status(MagicMock(), "parent_1")
+ result = handler.turn_intake._get_initial_status(MagicMock(), "parent_1")
assert "Continuing" in result
@@ -367,7 +367,9 @@ async def mock_async_gen(events):
@pytest.mark.asyncio
-async def test_process_node_success_flow(handler, mock_cli_manager, mock_platform):
+async def test_node_runner_process_node_success_flow(
+ handler, mock_cli_manager, mock_platform
+):
# Setup
node_id = "node_1"
mock_node = MagicMock()
@@ -405,7 +407,7 @@ async def test_process_node_success_flow(handler, mock_cli_manager, mock_platfor
with patch.object(
handler.tree_queue, "get_tree_for_node", MagicMock(return_value=mock_tree)
):
- await handler._process_node(node_id, mock_node)
+ await handler.node_runner.process_node(node_id, mock_node)
# Verify state updates
mock_tree.update_state.assert_any_call(node_id, MessageState.IN_PROGRESS)
@@ -428,7 +430,7 @@ async def test_process_node_success_flow(handler, mock_cli_manager, mock_platfor
@pytest.mark.asyncio
-async def test_process_node_reply_uses_parent_session_for_manager_and_fork(
+async def test_node_runner_process_node_reply_uses_parent_session_for_manager_and_fork(
handler, mock_cli_manager, mock_platform
):
"""Telegram follow-ups must reuse parent Claude session (issue #233)."""
@@ -457,7 +459,7 @@ async def test_process_node_reply_uses_parent_session_for_manager_and_fork(
with patch.object(
handler.tree_queue, "get_tree_for_node", MagicMock(return_value=mock_tree)
):
- await handler._process_node(node_id, mock_node)
+ await handler.node_runner.process_node(node_id, mock_node)
mock_tree.get_parent_session_id.assert_called_once_with(node_id)
mock_cli_manager.get_or_create_session.assert_awaited_once_with(
@@ -470,7 +472,9 @@ async def test_process_node_reply_uses_parent_session_for_manager_and_fork(
@pytest.mark.asyncio
-async def test_process_node_error_flow(handler, mock_cli_manager, mock_platform):
+async def test_node_runner_process_node_error_flow(
+ handler, mock_cli_manager, mock_platform
+):
node_id = "node_1"
mock_node = MagicMock()
mock_node.incoming.chat_id = "chat_1"
@@ -487,6 +491,8 @@ async def test_process_node_error_flow(handler, mock_cli_manager, mock_platform)
)
mock_tree = MagicMock()
+ mock_tree.root_id = "root_1"
+ mock_tree.to_dict.return_value = {"data": "tree"}
mock_tree.update_state = AsyncMock()
with (
@@ -497,11 +503,14 @@ async def test_process_node_error_flow(handler, mock_cli_manager, mock_platform)
handler.tree_queue, "mark_node_error", AsyncMock(return_value=[mock_node])
),
):
- await handler._process_node(node_id, mock_node)
+ await handler.node_runner.process_node(node_id, mock_node)
handler.tree_queue.mark_node_error.assert_called_once_with(
node_id, "CLI crashed", propagate_to_children=True
)
+ handler.session_store.save_tree.assert_called_once_with(
+ "root_1", {"data": "tree"}
+ )
last_call = mock_platform.queue_edit_message.call_args_list[-1]
assert "❌ *Error*" in last_call[0][2]
diff --git a/tests/messaging/test_handler_context_isolation.py b/tests/messaging/test_handler_context_isolation.py
index fc180906..4bf31f5f 100644
--- a/tests/messaging/test_handler_context_isolation.py
+++ b/tests/messaging/test_handler_context_isolation.py
@@ -2,8 +2,8 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
-from messaging.handler import ClaudeMessageHandler
from messaging.trees.data import MessageState
+from messaging.workflow import MessagingWorkflow
async def _gen_session(events):
@@ -13,7 +13,7 @@ async def _gen_session(events):
@pytest.fixture
def handler(mock_platform, mock_cli_manager, mock_session_store):
- return ClaudeMessageHandler(mock_platform, mock_cli_manager, mock_session_store)
+ return MessagingWorkflow(mock_platform, mock_cli_manager, mock_session_store)
@pytest.mark.asyncio
@@ -65,8 +65,8 @@ async def test_sibling_replies_fork_from_parent_session_id(
side_effect=_get_or_create_session
)
- await handler._process_node("R1", r1_node)
- await handler._process_node("R2", r2_node)
+ await handler.node_runner.process_node("R1", r1_node)
+ await handler.node_runner.process_node("R2", r2_node)
# Both siblings must resume from the same parent session and fork.
assert calls[0][0] == "R1"
@@ -119,7 +119,7 @@ async def test_grandchild_reply_forks_from_branch_session(
side_effect=_get_or_create_session
)
- await handler._process_node("R1", r1_node)
+ await handler.node_runner.process_node("R1", r1_node)
assert r1_node.session_id == "sess_R1"
# Grandchild C1 replies to R1 and must fork from sess_R1, not sess_A.
@@ -150,7 +150,7 @@ async def test_grandchild_reply_forks_from_branch_session(
side_effect=_get_or_create_session_c1
)
- await handler._process_node("C1", c1_node)
+ await handler.node_runner.process_node("C1", c1_node)
# The last call should be for C1 and must resume from sess_R1.
assert calls[-1][0] == "C1"
diff --git a/tests/messaging/test_handler_integration.py b/tests/messaging/test_handler_integration.py
index 0b016a91..1727b462 100644
--- a/tests/messaging/test_handler_integration.py
+++ b/tests/messaging/test_handler_integration.py
@@ -3,14 +3,14 @@ from unittest.mock import MagicMock
import pytest
-from messaging.handler import ClaudeMessageHandler
from messaging.trees.data import MessageState
+from messaging.workflow import MessagingWorkflow
@pytest.fixture
def handler_integration(mock_platform, mock_cli_manager, mock_session_store):
# Use real TreeQueueManager
- handler = ClaudeMessageHandler(mock_platform, mock_cli_manager, mock_session_store)
+ handler = MessagingWorkflow(mock_platform, mock_cli_manager, mock_session_store)
return handler
diff --git a/tests/messaging/test_handler_markdown_and_status_edges.py b/tests/messaging/test_handler_markdown_and_status_edges.py
index 662c6ffc..6594ef11 100644
--- a/tests/messaging/test_handler_markdown_and_status_edges.py
+++ b/tests/messaging/test_handler_markdown_and_status_edges.py
@@ -1,12 +1,13 @@
+import asyncio
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-from messaging.handler import ClaudeMessageHandler
from messaging.models import IncomingMessage
from messaging.node_event_pipeline import process_parsed_cli_event
from messaging.rendering.telegram_markdown import render_markdown_to_mdv2
from messaging.trees.data import MessageNode, MessageState
+from messaging.workflow import MessagingWorkflow
def test_render_markdown_to_mdv2_empty_returns_empty():
@@ -79,7 +80,7 @@ def test_get_initial_status_branches():
platform = MagicMock()
cli_manager = MagicMock()
session_store = MagicMock()
- handler = ClaudeMessageHandler(platform, cli_manager, session_store)
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
with (
patch.object(
@@ -87,17 +88,17 @@ def test_get_initial_status_branches():
),
patch.object(handler.tree_queue, "get_queue_size", MagicMock(return_value=2)),
):
- s1 = handler._get_initial_status(tree=object(), parent_node_id="p")
+ s1 = handler.turn_intake._get_initial_status(tree=object(), parent_node_id="p")
assert "Queued" in s1
assert "position 3" in s1 or "position 3" in s1.replace("\\", "")
with patch.object(
handler.tree_queue, "is_node_tree_busy", MagicMock(return_value=False)
):
- s2 = handler._get_initial_status(tree=object(), parent_node_id="p")
+ s2 = handler.turn_intake._get_initial_status(tree=object(), parent_node_id="p")
assert "Continuing" in s2
- s3 = handler._get_initial_status(tree=None, parent_node_id=None)
+ s3 = handler.turn_intake._get_initial_status(tree=None, parent_node_id=None)
assert "Launching" in s3
@@ -111,7 +112,7 @@ async def test_update_queue_positions_handles_snapshot_error_and_skips_non_pendi
cli_manager = MagicMock()
session_store = MagicMock()
- handler = ClaudeMessageHandler(platform, cli_manager, session_store)
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
# Snapshot error is swallowed.
tree = MagicMock()
@@ -136,7 +137,7 @@ async def test_update_queue_positions_handles_snapshot_error_and_skips_non_pendi
@pytest.mark.asyncio
-async def test_process_node_session_limit_marks_error_and_updates_ui():
+async def test_node_runner_process_node_session_limit_marks_error_and_updates_ui():
platform = MagicMock()
platform.queue_edit_message = AsyncMock()
platform.fire_and_forget = MagicMock(
@@ -148,9 +149,11 @@ async def test_process_node_session_limit_marks_error_and_updates_ui():
cli_manager.get_stats.return_value = {"active_sessions": 0}
session_store = MagicMock()
- handler = ClaudeMessageHandler(platform, cli_manager, session_store)
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
fake_tree = MagicMock()
+ fake_tree.root_id = "root"
+ fake_tree.to_dict = MagicMock(return_value={"root": "error"})
fake_tree.update_state = AsyncMock()
with patch.object(
handler.tree_queue, "get_tree_for_node", MagicMock(return_value=fake_tree)
@@ -164,9 +167,58 @@ async def test_process_node_session_limit_marks_error_and_updates_ui():
)
node = MessageNode(node_id="n1", incoming=incoming, status_message_id="s1")
- await handler._process_node("n1", node)
+ await handler.node_runner.process_node("n1", node)
assert platform.queue_edit_message.await_count >= 1
fake_tree.update_state.assert_awaited()
+ session_store.save_tree.assert_called_once_with("root", {"root": "error"})
+
+
+async def test_node_runner_cancellation_marks_error_and_saves_tree():
+ platform = MagicMock()
+ platform.queue_edit_message = AsyncMock()
+ platform.fire_and_forget = MagicMock(
+ side_effect=lambda c: getattr(c, "close", lambda: None)()
+ )
+
+ async def _cancelled_start_task(*args, **kwargs):
+ raise asyncio.CancelledError
+ yield
+
+ mock_session = MagicMock()
+ mock_session.start_task = _cancelled_start_task
+ cli_manager = MagicMock()
+ cli_manager.get_or_create_session = AsyncMock(
+ return_value=(mock_session, "s1", False)
+ )
+ cli_manager.remove_session = AsyncMock()
+ cli_manager.get_stats.return_value = {"active_sessions": 0}
+
+ session_store = MagicMock()
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
+
+ fake_tree = MagicMock()
+ fake_tree.root_id = "root"
+ fake_tree.to_dict = MagicMock(return_value={"root": "cancelled"})
+ fake_tree.update_state = AsyncMock()
+ with patch.object(
+ handler.tree_queue, "get_tree_for_node", MagicMock(return_value=fake_tree)
+ ):
+ incoming = IncomingMessage(
+ text="hi",
+ chat_id="c",
+ user_id="u",
+ message_id="n1",
+ platform="telegram",
+ )
+ node = MessageNode(node_id="n1", incoming=incoming, status_message_id="s1")
+
+ await handler.node_runner.process_node("n1", node)
+
+ fake_tree.update_state.assert_any_await(
+ "n1", MessageState.ERROR, error_message="Cancelled by user"
+ )
+ session_store.save_tree.assert_called_once_with("root", {"root": "cancelled"})
@pytest.mark.asyncio
@@ -182,7 +234,7 @@ async def test_stop_all_tasks_saves_tree_for_cancelled_nodes():
cli_manager.get_stats.return_value = {"active_sessions": 0}
session_store = MagicMock()
- handler = ClaudeMessageHandler(platform, cli_manager, session_store)
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
incoming = IncomingMessage(
text="hi",
@@ -218,7 +270,7 @@ async def test_handle_message_reply_with_tree_but_no_parent_treated_as_new():
cli_manager.get_stats.return_value = {"active_sessions": 0}
session_store = MagicMock()
- handler = ClaudeMessageHandler(platform, cli_manager, session_store)
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
# Force "tree exists but parent can't be resolved" branch.
mock_queue = MagicMock()
@@ -272,7 +324,7 @@ async def test_update_ui_handles_transcript_render_exception():
cli_manager.remove_session = AsyncMock()
cli_manager.get_stats.return_value = {"active_sessions": 0}
- handler = ClaudeMessageHandler(platform, cli_manager, session_store)
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
mock_queue = MagicMock()
mock_queue.get_tree_for_node.return_value = None
handler.replace_tree_queue(mock_queue)
@@ -286,13 +338,15 @@ async def test_update_ui_handles_transcript_render_exception():
)
node = MessageNode(node_id="n1", incoming=incoming, status_message_id="s1")
- with patch.object(handler, "_create_transcript_and_render_ctx") as mock_create:
+ with patch.object(
+ handler.node_runner, "_create_transcript_and_render_ctx"
+ ) as mock_create:
transcript = MagicMock()
transcript.render = MagicMock(side_effect=ValueError("render failed"))
render_ctx = MagicMock()
mock_create.return_value = (transcript, render_ctx)
- await handler._process_node("n1", node)
+ await handler.node_runner.process_node("n1", node)
assert transcript.render.call_count >= 1
@@ -308,7 +362,7 @@ async def test_handle_message_incoming_text_none_safe():
cli_manager.get_stats.return_value = {"active_sessions": 0}
session_store = MagicMock()
- handler = ClaudeMessageHandler(platform, cli_manager, session_store)
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
mock_queue = MagicMock()
mock_queue.get_tree_for_node.return_value = None
mock_queue.resolve_parent_node_id.return_value = None
@@ -340,7 +394,7 @@ async def test_process_parsed_event_malformed_content_continues():
cli_manager = MagicMock()
session_store = MagicMock()
- handler = ClaudeMessageHandler(platform, cli_manager, session_store)
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
transcript = MagicMock()
update_ui = AsyncMock()
@@ -364,7 +418,7 @@ async def test_process_parsed_event_malformed_content_continues():
@pytest.mark.asyncio
async def test_handler_update_ui_edit_failure_does_not_crash():
- """When queue_edit_message raises during streaming, _process_node continues and completes."""
+ """When queue_edit_message raises during streaming, node_runner.process_node continues and completes."""
platform = MagicMock()
platform.queue_edit_message = AsyncMock(
side_effect=RuntimeError("Telegram API error")
@@ -396,7 +450,7 @@ async def test_handler_update_ui_edit_failure_does_not_crash():
cli_manager.get_stats.return_value = {"active_sessions": 0}
session_store = MagicMock()
- handler = ClaudeMessageHandler(platform, cli_manager, session_store)
+ handler = MessagingWorkflow(platform, cli_manager, session_store)
mock_queue = MagicMock()
mock_queue.get_tree_for_node.return_value = None
handler.replace_tree_queue(mock_queue)
@@ -410,6 +464,6 @@ async def test_handler_update_ui_edit_failure_does_not_crash():
)
node = MessageNode(node_id="n1", incoming=incoming, status_message_id="s1")
- await handler._process_node("n1", node)
+ await handler.node_runner.process_node("n1", node)
cli_manager.remove_session.assert_awaited_once()
diff --git a/tests/messaging/test_messaging.py b/tests/messaging/test_messaging.py
index 6e019047..3867dc47 100644
--- a/tests/messaging/test_messaging.py
+++ b/tests/messaging/test_messaging.py
@@ -146,21 +146,21 @@ class TestTreeQueueManager:
def test_tree_queue_manager_init(self):
"""Test TreeQueueManager initialization."""
- from messaging.trees.queue_manager import TreeQueueManager
+ from messaging.trees import TreeQueueManager
mgr = TreeQueueManager()
assert mgr.get_tree_count() == 0
def test_tree_not_busy_initially(self):
"""Test tree is not busy when no messages."""
- from messaging.trees.queue_manager import TreeQueueManager
+ from messaging.trees import TreeQueueManager
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 node."""
- from messaging.trees.queue_manager import TreeQueueManager
+ from messaging.trees import TreeQueueManager
mgr = TreeQueueManager()
assert mgr.get_queue_size("nonexistent") == 0
@@ -169,7 +169,7 @@ class TestTreeQueueManager:
async def test_create_tree_and_enqueue(self):
"""Test creating a tree and enqueueing."""
from messaging.models import IncomingMessage
- from messaging.trees.queue_manager import TreeQueueManager
+ from messaging.trees import TreeQueueManager
mgr = TreeQueueManager()
processed = []
@@ -190,7 +190,7 @@ class TestTreeQueueManager:
@pytest.mark.asyncio
async def test_cancel_tree_empty(self):
"""Test cancelling non-existent tree."""
- from messaging.trees.queue_manager import TreeQueueManager
+ from messaging.trees import TreeQueueManager
mgr = TreeQueueManager()
cancelled = await mgr.cancel_tree("nonexistent")
diff --git a/tests/messaging/test_restart_reply_restore.py b/tests/messaging/test_restart_reply_restore.py
index cef1c6f2..82342783 100644
--- a/tests/messaging/test_restart_reply_restore.py
+++ b/tests/messaging/test_restart_reply_restore.py
@@ -2,10 +2,10 @@ from unittest.mock import AsyncMock, patch
import pytest
-from messaging.handler import ClaudeMessageHandler
from messaging.models import IncomingMessage
from messaging.session import SessionStore
-from messaging.trees.queue_manager import TreeQueueManager
+from messaging.trees import TreeQueueManager
+from messaging.workflow import MessagingWorkflow
@pytest.mark.asyncio
@@ -16,7 +16,7 @@ async def test_reply_to_old_status_message_after_restore_routes_to_parent(
store_path = tmp_path / "sessions.json"
store = SessionStore(storage_path=str(store_path))
- handler1 = ClaudeMessageHandler(mock_platform, mock_cli_manager, store)
+ handler1 = MessagingWorkflow(mock_platform, mock_cli_manager, store)
a_incoming = IncomingMessage(
text="A",
chat_id="chat_1",
@@ -34,7 +34,7 @@ async def test_reply_to_old_status_message_after_restore_routes_to_parent(
# "Restart": new store instance loads from disk, and we restore TreeQueueManager.
store2 = SessionStore(storage_path=str(store_path))
- handler2 = ClaudeMessageHandler(mock_platform, mock_cli_manager, store2)
+ handler2 = MessagingWorkflow(mock_platform, mock_cli_manager, store2)
handler2.replace_tree_queue(
TreeQueueManager.from_dict(
{
@@ -69,13 +69,13 @@ async def test_reply_to_old_status_message_after_restore_routes_to_parent(
@pytest.mark.asyncio
-async def test_reply_to_old_status_message_without_mapping_creates_new_conversation(
+async def test_save_tree_persists_status_message_mapping_without_manual_register(
tmp_path, mock_platform, mock_cli_manager
):
store_path = tmp_path / "sessions.json"
store = SessionStore(storage_path=str(store_path))
- handler1 = ClaudeMessageHandler(mock_platform, mock_cli_manager, store)
+ handler1 = MessagingWorkflow(mock_platform, mock_cli_manager, store)
a_incoming = IncomingMessage(
text="A",
chat_id="chat_1",
@@ -86,12 +86,11 @@ async def test_reply_to_old_status_message_without_mapping_creates_new_conversat
tree = await handler1.tree_queue.create_tree(
"A", a_incoming, status_message_id="status_A"
)
- # Intentionally do NOT register "status_A" mapping.
store.save_tree(tree.root_id, tree.to_dict())
store.flush_pending_save()
store2 = SessionStore(storage_path=str(store_path))
- handler2 = ClaudeMessageHandler(mock_platform, mock_cli_manager, store2)
+ handler2 = MessagingWorkflow(mock_platform, mock_cli_manager, store2)
handler2.replace_tree_queue(
TreeQueueManager.from_dict(
{
@@ -116,7 +115,68 @@ async def test_reply_to_old_status_message_without_mapping_creates_new_conversat
with patch.object(handler2.tree_queue, "enqueue", AsyncMock(return_value=False)):
await handler2.handle_message(reply)
- # Since the mapping is missing, this should be treated as a new conversation.
- new_tree = handler2.tree_queue.get_tree_for_node("R1")
- assert new_tree is not None
- assert new_tree.root_id == "R1"
+ restored_tree = handler2.tree_queue.get_tree_for_node("A")
+ assert restored_tree is not None
+ node_r1 = restored_tree.get_node("R1")
+ assert node_r1 is not None
+ assert node_r1.parent_id == "A"
+
+
+async def test_reply_clear_purges_removed_status_mapping_from_persisted_store(
+ tmp_path, mock_platform, mock_cli_manager
+):
+ store_path = tmp_path / "sessions.json"
+ store = SessionStore(storage_path=str(store_path))
+ handler = MessagingWorkflow(mock_platform, mock_cli_manager, store)
+
+ root_incoming = IncomingMessage(
+ text="root",
+ chat_id="chat_1",
+ user_id="user_1",
+ message_id="root",
+ platform="telegram",
+ )
+ tree = await handler.tree_queue.create_tree(
+ "root", root_incoming, status_message_id="root_status"
+ )
+ handler.tree_queue.register_node("root_status", tree.root_id)
+
+ child_incoming = IncomingMessage(
+ text="child",
+ chat_id="chat_1",
+ user_id="user_1",
+ message_id="child",
+ platform="telegram",
+ reply_to_message_id="root",
+ )
+ await handler.tree_queue.add_to_tree(
+ "root", "child", child_incoming, status_message_id="child_status"
+ )
+ handler.tree_queue.register_node("child_status", tree.root_id)
+ store.save_tree(tree.root_id, tree.to_dict())
+
+ clear_reply = IncomingMessage(
+ text="/clear",
+ chat_id="chat_1",
+ user_id="user_1",
+ message_id="clear_command",
+ platform="telegram",
+ reply_to_message_id="child",
+ )
+
+ await handler.handle_message(clear_reply)
+ store.flush_pending_save()
+
+ restored_store = SessionStore(storage_path=str(store_path))
+ restored_tree_queue = TreeQueueManager.from_dict(
+ {
+ "trees": restored_store.get_all_trees(),
+ "node_to_tree": restored_store.get_node_mapping(),
+ }
+ )
+
+ assert restored_tree_queue.get_tree_for_node("root") is not None
+ assert restored_tree_queue.get_tree_for_node("root_status") is not None
+ assert restored_tree_queue.get_tree_for_node("child") is None
+ assert restored_tree_queue.get_tree_for_node("child_status") is None
diff --git a/tests/messaging/test_session_store_edge_cases.py b/tests/messaging/test_session_store_edge_cases.py
index 8656c366..ca3d8b83 100644
--- a/tests/messaging/test_session_store_edge_cases.py
+++ b/tests/messaging/test_session_store_edge_cases.py
@@ -15,6 +15,13 @@ def tmp_store(tmp_path):
return SessionStore(storage_path=path)
+def _tree_node(node_id: str, status_message_id: str) -> dict:
+ return {
+ "node_id": node_id,
+ "status_message_id": status_message_id,
+ }
+
+
class TestSessionStoreLoadEdgeCases:
"""Tests for loading corrupted/malformed data."""
@@ -90,6 +97,73 @@ class TestSessionStoreSaveEdgeCases:
tmp_store._write_data(tmp_store._snapshot())
+class TestSessionStoreTreeMappings:
+ def test_save_tree_rebuilds_lookup_ids_for_that_root(self, tmp_path):
+ path = str(tmp_path / "sessions.json")
+ store = SessionStore(storage_path=path)
+ store.register_node("unrelated_status", "other_root")
+
+ store.save_tree(
+ "root",
+ {
+ "root_id": "root",
+ "nodes": {
+ "root": _tree_node("root", "root_status"),
+ "child": _tree_node("child", "child_status"),
+ },
+ },
+ )
+
+ mapping = store.get_node_mapping()
+ assert mapping["root"] == "root"
+ assert mapping["root_status"] == "root"
+ assert mapping["child"] == "root"
+ assert mapping["child_status"] == "root"
+
+ store.save_tree(
+ "root",
+ {
+ "root_id": "root",
+ "nodes": {
+ "root": _tree_node("root", "root_status"),
+ },
+ },
+ )
+
+ mapping = store.get_node_mapping()
+ assert mapping["root"] == "root"
+ assert mapping["root_status"] == "root"
+ assert "child" not in mapping
+ assert "child_status" not in mapping
+ assert mapping["unrelated_status"] == "other_root"
+
+ def test_remove_tree_removes_all_lookup_ids_for_that_root(self, tmp_path):
+ path = str(tmp_path / "sessions.json")
+ store = SessionStore(storage_path=path)
+ store.register_node("old_status", "root")
+ store.register_node("unrelated_status", "other_root")
+ store.save_tree(
+ "root",
+ {
+ "root_id": "root",
+ "nodes": {
+ "root": _tree_node("root", "root_status"),
+ "child": _tree_node("child", "child_status"),
+ },
+ },
+ )
+
+ store.remove_tree("root")
+
+ mapping = store.get_node_mapping()
+ assert "root" not in mapping
+ assert "root_status" not in mapping
+ assert "child" not in mapping
+ assert "child_status" not in mapping
+ assert "old_status" not in mapping
+ assert mapping["unrelated_status"] == "other_root"
+
+
class TestSessionStoreAtomicWrites:
"""Atomic persistence: failed replace must not truncate the prior file."""
diff --git a/tests/messaging/test_tree_concurrency.py b/tests/messaging/test_tree_concurrency.py
index 9b54a156..281843cc 100644
--- a/tests/messaging/test_tree_concurrency.py
+++ b/tests/messaging/test_tree_concurrency.py
@@ -5,8 +5,8 @@ import asyncio
import pytest
from messaging.models import IncomingMessage
+from messaging.trees import TreeQueueManager
from messaging.trees.data import MessageNode, MessageState, MessageTree
-from messaging.trees.queue_manager import TreeQueueManager
def _make_incoming(text: str = "hello", msg_id: str = "m1") -> IncomingMessage:
diff --git a/tests/messaging/test_tree_processor.py b/tests/messaging/test_tree_processor.py
index 664748d8..b3a00128 100644
--- a/tests/messaging/test_tree_processor.py
+++ b/tests/messaging/test_tree_processor.py
@@ -6,7 +6,7 @@ import pytest
from messaging.models import IncomingMessage
from messaging.trees.data import MessageNode, MessageState, MessageTree
-from messaging.trees.queue_manager import TreeQueueProcessor
+from messaging.trees.processor import TreeQueueProcessor
@pytest.fixture
@@ -158,6 +158,69 @@ async def test_process_next_with_item(tree_processor, sample_tree):
await sample_tree._current_task
+async def test_process_next_skips_stale_id_and_runs_next_valid_node(sample_tree):
+ queue_updated = AsyncMock()
+ node_started = AsyncMock()
+ processor = TreeQueueProcessor(
+ queue_update_callback=queue_updated,
+ node_started_callback=node_started,
+ )
+ release = asyncio.Event()
+
+ valid_incoming = IncomingMessage(
+ text="valid",
+ chat_id="chat123",
+ user_id="user456",
+ message_id="valid_node",
+ platform="telegram",
+ reply_to_message_id=sample_tree.root_id,
+ )
+ await sample_tree.add_node(
+ "valid_node",
+ valid_incoming,
+ "valid_status",
+ sample_tree.root_id,
+ )
+ await sample_tree._queue.put("missing_node")
+ await sample_tree._queue.put("valid_node")
+
+ async def node_processor(node_id, node):
+ await release.wait()
+
+ await processor._process_next(sample_tree, node_processor)
+
+ assert sample_tree._is_processing is True
+ assert sample_tree._current_node_id == "valid_node"
+ node_started.assert_awaited_once_with(sample_tree, "valid_node")
+ queue_updated.assert_awaited_once_with(sample_tree)
+
+ release.set()
+ if sample_tree._current_task:
+ await sample_tree._current_task
+
+
+async def test_process_next_drains_all_stale_ids_without_wedging(sample_tree):
+ queue_updated = AsyncMock()
+ node_started = AsyncMock()
+ processor = TreeQueueProcessor(
+ queue_update_callback=queue_updated,
+ node_started_callback=node_started,
+ )
+ sample_tree._is_processing = True
+ await sample_tree._queue.put("missing_one")
+ await sample_tree._queue.put("missing_two")
+
+ await processor._process_next(sample_tree, AsyncMock())
+
+ assert sample_tree._is_processing is False
+ assert sample_tree._current_node_id is None
+ assert sample_tree._queue.qsize() == 0
+ node_started.assert_not_awaited()
+ queue_updated.assert_awaited_once_with(sample_tree)
+
+
@pytest.mark.asyncio
async def test_process_next_triggers_queue_update(sample_tree):
callback = AsyncMock()
@@ -176,9 +239,24 @@ async def test_process_next_triggers_node_started(sample_tree):
node_started = AsyncMock()
processor = TreeQueueProcessor(node_started_callback=node_started)
+ incoming = IncomingMessage(
+ text="next",
+ chat_id="chat123",
+ user_id="user456",
+ message_id="next_node",
+ platform="telegram",
+ reply_to_message_id=sample_tree.root_id,
+ )
+ await sample_tree.add_node(
+ "next_node", incoming, "next_status", sample_tree.root_id
+ )
await sample_tree._queue.put("next_node")
- sample_tree.get_node = MagicMock(return_value=None)
await processor._process_next(sample_tree, AsyncMock())
node_started.assert_awaited_once_with(sample_tree, "next_node")
+
+ if sample_tree._current_task:
+ sample_tree._current_task.cancel()
+ with contextlib.suppress(asyncio.CancelledError):
+ await sample_tree._current_task
diff --git a/tests/messaging/test_tree_queue.py b/tests/messaging/test_tree_queue.py
index ed0c3d6b..cbece5d6 100644
--- a/tests/messaging/test_tree_queue.py
+++ b/tests/messaging/test_tree_queue.py
@@ -1,11 +1,12 @@
"""Tests for tree-based message queue system."""
import asyncio
+from unittest.mock import AsyncMock
import pytest
from messaging.models import IncomingMessage
-from messaging.trees.queue_manager import (
+from messaging.trees import (
MessageNode,
MessageState,
MessageTree,
@@ -561,6 +562,90 @@ class TestTreeQueueManager:
assert sibling_node is not None
assert sibling_node.state == MessageState.PENDING
+ @pytest.mark.asyncio
+ async def test_cancel_node_refreshes_queue_positions_for_remaining_nodes(self):
+ """Reply-scoped stop refreshes queued siblings after removing one queued node."""
+ queue_updated = AsyncMock()
+ manager = TreeQueueManager(queue_update_callback=queue_updated)
+
+ root_incoming = IncomingMessage(
+ text="Root", chat_id="1", user_id="1", message_id="root", platform="test"
+ )
+ tree = await manager.create_tree("root", root_incoming, "s1")
+
+ first_incoming = IncomingMessage(
+ text="First",
+ chat_id="1",
+ user_id="1",
+ message_id="queued_first",
+ platform="test",
+ reply_to_message_id="root",
+ )
+ await manager.add_to_tree("root", "queued_first", first_incoming, "s2")
+
+ second_incoming = IncomingMessage(
+ text="Second",
+ chat_id="1",
+ user_id="1",
+ message_id="queued_second",
+ platform="test",
+ reply_to_message_id="root",
+ )
+ await manager.add_to_tree("root", "queued_second", second_incoming, "s3")
+
+ async with tree.with_lock():
+ tree.set_processing_state("root", True)
+ tree.put_queue_unlocked("queued_first")
+ tree.put_queue_unlocked("queued_second")
+
+ cancelled = await manager.cancel_node("queued_first")
+
+ assert [node.node_id for node in cancelled] == ["queued_first"]
+ assert await tree.get_queue_snapshot() == ["queued_second"]
+ queue_updated.assert_awaited_once_with(tree)
+
+ @pytest.mark.asyncio
+ async def test_cancel_branch_refreshes_queue_positions_for_remaining_nodes(self):
+ """Reply-scoped clear refreshes queued siblings after removing a queued branch."""
+ queue_updated = AsyncMock()
+ manager = TreeQueueManager(queue_update_callback=queue_updated)
+
+ root_incoming = IncomingMessage(
+ text="Root", chat_id="1", user_id="1", message_id="root", platform="test"
+ )
+ tree = await manager.create_tree("root", root_incoming, "s1")
+
+ child_incoming = IncomingMessage(
+ text="Child",
+ chat_id="1",
+ user_id="1",
+ message_id="queued_first",
+ platform="test",
+ reply_to_message_id="root",
+ )
+ await manager.add_to_tree("root", "queued_first", child_incoming, "s2")
+
+ sibling_incoming = IncomingMessage(
+ text="Sibling",
+ chat_id="1",
+ user_id="1",
+ message_id="queued_second",
+ platform="test",
+ reply_to_message_id="root",
+ )
+ await manager.add_to_tree("root", "queued_second", sibling_incoming, "s3")
+
+ async with tree.with_lock():
+ tree.set_processing_state("root", True)
+ tree.put_queue_unlocked("queued_first")
+ tree.put_queue_unlocked("queued_second")
+
+ cancelled = await manager.cancel_branch("queued_first")
+
+ assert [node.node_id for node in cancelled] == ["queued_first"]
+ assert await tree.get_queue_snapshot() == ["queued_second"]
+ queue_updated.assert_awaited_once_with(tree)
+
@pytest.mark.asyncio
async def test_remove_branch_non_root(self):
"""Test remove_branch removes only the subtree when branch is not root."""
@@ -592,6 +677,48 @@ class TestTreeQueueManager:
assert tree.get_node("child") is None
assert "child" not in tree.get_root().children_ids
+ @pytest.mark.asyncio
+ async def test_remove_branch_unregisters_status_message_mappings(self):
+ """Removing a branch removes node and status lookup keys."""
+ manager = TreeQueueManager()
+
+ root_incoming = IncomingMessage(
+ text="Root", chat_id="1", user_id="1", message_id="root", platform="test"
+ )
+ await manager.create_tree("root", root_incoming, "s1")
+
+ 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")
+ manager.register_node("s2", "root")
+
+ grandchild_incoming = IncomingMessage(
+ text="Grandchild",
+ chat_id="1",
+ user_id="1",
+ message_id="grandchild",
+ platform="test",
+ reply_to_message_id="child",
+ )
+ await manager.add_to_tree("child", "grandchild", grandchild_incoming, "s3")
+ manager.register_node("s3", "root")
+
+ removed, root_id, removed_entire = await manager.remove_branch("child")
+
+ assert {node.node_id for node in removed} == {"child", "grandchild"}
+ assert root_id == "root"
+ assert removed_entire is False
+ assert manager.get_tree_for_node("child") is None
+ assert manager.get_tree_for_node("grandchild") is None
+ assert manager.get_tree_for_node("s2") is None
+ assert manager.get_tree_for_node("s3") is None
+
@pytest.mark.asyncio
async def test_remove_branch_root_removes_tree(self):
"""Test remove_branch when branch is root removes entire tree."""
@@ -610,6 +737,25 @@ class TestTreeQueueManager:
assert manager.get_tree("root") is None
assert manager.get_tree_for_node("root") is None
+ @pytest.mark.asyncio
+ async def test_remove_branch_root_unregisters_status_message_mapping(self):
+ """Removing an entire tree removes root status lookup keys too."""
+ manager = TreeQueueManager()
+
+ root_incoming = IncomingMessage(
+ text="Root", chat_id="1", user_id="1", message_id="root", platform="test"
+ )
+ await manager.create_tree("root", root_incoming, "s1")
+ manager.register_node("s1", "root")
+
+ removed, root_id, removed_entire = await manager.remove_branch("root")
+
+ assert [node.node_id for node in removed] == ["root"]
+ assert root_id == "root"
+ assert removed_entire is True
+ assert manager.get_tree_for_node("root") is None
+ assert manager.get_tree_for_node("s1") is None
+
class TestSessionStoreTrees:
"""Test SessionStore tree methods."""
diff --git a/tests/messaging/test_tree_repository.py b/tests/messaging/test_tree_repository.py
index e5bf4efd..2860ae6e 100644
--- a/tests/messaging/test_tree_repository.py
+++ b/tests/messaging/test_tree_repository.py
@@ -4,7 +4,7 @@ import pytest
from messaging.models import IncomingMessage
from messaging.trees.data import MessageNode, MessageState, MessageTree
-from messaging.trees.queue_manager import TreeRepository
+from messaging.trees.repository import TreeRepository
@pytest.fixture
diff --git a/uv.lock b/uv.lock
index 843eebb1..16668a6f 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "2.3.6"
+version = "2.3.7"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },